feat(taskservice): REST API, liveness protocol, artifact store, MCP contract

Slice 1, PR 3 of 4 — the task service API contract.

- panopticon.taskservice.service.TaskService: deterministic orchestration over the
  repository — tasks, transition enforcement (via the engine), slug, artifacts, and
  ephemeral liveness registrations. Injectable clock + id factory for test determinism.
- panopticon.taskservice.api: FastAPI app factory exposing repos, tasks, transitions
  (with per-responsibility settlement on the wire), slug, artifacts, liveness, and
  discovery, with domain exceptions mapped to HTTP status codes.
- panopticon.core.artifacts + taskservice.artifacts_fs: the artifact-store interface, the
  filesystem adapter, and the shared id->path->MCP-URI resolver (ADR 0003).
- panopticon.taskservice.mcp: the MCP surface contract (resource URI scheme + tool
  specs), defined now; the server is wired when real containers connect (Slice 2).

Adds fastapi + uvicorn (runtime) and httpx (dev, for TestClient).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: tildesrc

pyproject.toml

@@ -3,12 +3,16 @@ name = "panopticon"
 version = "0.0.1"
 description = "Orchestrate multiple coding agents across isolated tasks and configurable workflows."
 requires-python = ">=3.11"
-dependencies = []
+dependencies = [
+    "fastapi>=0.110",
+    "uvicorn>=0.29",
+]
 
 [dependency-groups]
 dev = [
     "pytest>=8",
     "mypy>=1.11",
+    "httpx>=0.27",
 ]
 
 [build-system]

src/panopticon/core/artifacts.py

@@ -0,0 +1,55 @@
+"""The artifact-store interface + the shared id→path→URI resolver (ADR 0003).
+
+Freeform per-task files (plan, notes) are file-backed, not in the DB. The same bytes are
+reachable via the filesystem, the dashboard, and MCP; this module owns the single resolver
+that maps ``(task_id, name)`` to a path and an MCP URI so every surface agrees.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+MCP_URI_SCHEME = "panopticon"
+
+
+class ArtifactError(Exception):
+    """Base class for artifact-store failures."""
+
+
+class InvalidArtifactName(ArtifactError):
+    """Raised for an artifact name (or task id) that could escape its directory."""
+
+
+def validate_segment(segment: str) -> None:
+    """Reject names/ids that contain path separators, dot-segments, or are empty."""
+    if (
+        not segment
+        or "/" in segment
+        or "\\" in segment
+        or segment in (".", "..")
+        or segment.startswith(".")
+    ):
+        raise InvalidArtifactName(f"invalid artifact segment: {segment!r}")
+
+
+def mcp_uri(task_id: str, name: str) -> str:
+    """The canonical MCP resource URI for an artifact (the shared resolver)."""
+    validate_segment(task_id)
+    validate_segment(name)
+    return f"{MCP_URI_SCHEME}://tasks/{task_id}/artifacts/{name}"
+
+
+class ArtifactStore(ABC):
+    """Read/write per-task artifact files."""
+
+    @abstractmethod
+    def put(self, task_id: str, name: str, content: bytes) -> None:
+        """Create or overwrite an artifact."""
+
+    @abstractmethod
+    def get(self, task_id: str, name: str) -> bytes | None:
+        """Return artifact bytes, or ``None`` if it does not exist."""
+
+    @abstractmethod
+    def list(self, task_id: str) -> list[str]:
+        """Return the names of a task's artifacts (empty if none)."""

src/panopticon/taskservice/__init__.py

@@ -1,5 +1,5 @@
 """The task service: the deterministic control plane.
 
 Owns the repository (the sole DB authority, ADR 0006), hosts the workflow registry, and
-drives task lifecycle. This package must remain LLM-free (enforced by a determinism test).
+drives task lifecycle. This package must remain LLM-free (the determinism invariant).
 """

src/panopticon/taskservice/api.py

@@ -0,0 +1,291 @@
+"""The task service REST API (FastAPI).
+
+The dashboard, the runner, and in-container skills are clients of this API. (Agents also
+reach artifacts/tools over MCP — see :mod:`panopticon.taskservice.mcp` — but the walking
+skeleton uses REST.) ``create_app`` builds an app around an injected
+:class:`~panopticon.taskservice.service.TaskService`, so tests can wire a deterministic one.
+"""
+
+from __future__ import annotations
+
+from fastapi import FastAPI, HTTPException, Request, Response
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+
+from panopticon.core.artifacts import ArtifactError
+from panopticon.core.models import Repo, Responsibility, Status, Task
+from panopticon.core.repository import AlreadyExists, NotFound, RepositoryError
+from panopticon.core.workflow import IllegalTransition, InvalidWorkflow, ResponsibilitiesNotMet
+from panopticon.taskservice.service import Registration, TaskService, UnknownWorkflow
+
+# -- wire schemas -------------------------------------------------------------------
+
+
+class ResponsibilityOut(BaseModel):
+    key: str
+    description: str
+    status: str
+    comment: str | None = None
+
+
+class HistoryOut(BaseModel):
+    at: str
+    from_state: str | None
+    to_state: str
+    trigger: str | None = None
+    note: str | None = None
+    responsibilities: list[ResponsibilityOut] = []
+
+
+class TaskOut(BaseModel):
+    id: str
+    repo_id: str
+    workflow: str
+    state: str
+    turn: str
+    slug: str | None
+    history: list[HistoryOut]
+
+    @classmethod
+    def of(cls, task: Task) -> "TaskOut":
+        return cls(
+            id=task.id,
+            repo_id=task.repo_id,
+            workflow=task.workflow,
+            state=task.state,
+            turn=task.turn.value,
+            slug=task.slug,
+            history=[
+                HistoryOut(
+                    at=h.at,
+                    from_state=h.from_state,
+                    to_state=h.to_state,
+                    trigger=h.trigger,
+                    note=h.note,
+                    responsibilities=[
+                        ResponsibilityOut(
+                            key=r.key,
+                            description=r.description,
+                            status=r.status.value,
+                            comment=r.comment,
+                        )
+                        for r in h.responsibilities
+                    ],
+                )
+                for h in task.history
+            ],
+        )
+
+
+class RepoIn(BaseModel):
+    id: str
+    name: str
+    git_url: str
+    default_base: str = "main"
+
+
+class RepoOut(BaseModel):
+    id: str
+    name: str
+    git_url: str
+    default_base: str
+
+    @classmethod
+    def of(cls, repo: Repo) -> "RepoOut":
+        return cls(
+            id=repo.id, name=repo.name, git_url=repo.git_url, default_base=repo.default_base
+        )
+
+
+class CreateTaskIn(BaseModel):
+    repo_id: str
+    workflow: str
+
+
+class ResponsibilityIn(BaseModel):
+    key: str
+    status: Status
+    comment: str | None = None
+
+
+class TransitionIn(BaseModel):
+    to_state: str
+    trigger: str | None = None
+    note: str | None = None
+    responsibilities: list[ResponsibilityIn] | None = None
+
+
+class SlugIn(BaseModel):
+    slug: str
+
+
+class RegisterIn(BaseModel):
+    container_id: str
+    runner_id: str | None = None
+
+
+class RegistrationOut(BaseModel):
+    id: str
+    task_id: str
+    container_id: str
+    runner_id: str | None
+    registered_at: str
+    last_seen: str
+
+    @classmethod
+    def of(cls, reg: Registration) -> "RegistrationOut":
+        return cls(
+            id=reg.id,
+            task_id=reg.task_id,
+            container_id=reg.container_id,
+            runner_id=reg.runner_id,
+            registered_at=reg.registered_at,
+            last_seen=reg.last_seen,
+        )
+
+
+def create_app(service: TaskService) -> FastAPI:
+    app = FastAPI(title="panopticon task service", version="0.0.1")
+
+    # -- error mapping: domain exceptions -> HTTP status --------------------------
+
+    @app.exception_handler(NotFound)
+    async def _not_found(_: Request, exc: NotFound) -> JSONResponse:
+        return JSONResponse(status_code=404, content={"detail": str(exc)})
+
+    @app.exception_handler(AlreadyExists)
+    async def _conflict(_: Request, exc: AlreadyExists) -> JSONResponse:
+        return JSONResponse(status_code=409, content={"detail": str(exc)})
+
+    @app.exception_handler(IllegalTransition)
+    async def _illegal(_: Request, exc: IllegalTransition) -> JSONResponse:
+        return JSONResponse(status_code=409, content={"detail": str(exc)})
+
+    @app.exception_handler(ResponsibilitiesNotMet)
+    async def _responsibilities(_: Request, exc: ResponsibilitiesNotMet) -> JSONResponse:
+        return JSONResponse(status_code=409, content={"detail": str(exc)})
+
+    @app.exception_handler(UnknownWorkflow)
+    async def _unknown_wf(_: Request, exc: UnknownWorkflow) -> JSONResponse:
+        return JSONResponse(status_code=400, content={"detail": str(exc)})
+
+    @app.exception_handler(InvalidWorkflow)
+    async def _invalid_wf(_: Request, exc: InvalidWorkflow) -> JSONResponse:
+        return JSONResponse(status_code=400, content={"detail": str(exc)})
+
+    @app.exception_handler(ArtifactError)
+    async def _artifact(_: Request, exc: ArtifactError) -> JSONResponse:
+        return JSONResponse(status_code=400, content={"detail": str(exc)})
+
+    @app.exception_handler(RepositoryError)
+    async def _repo_error(_: Request, exc: RepositoryError) -> JSONResponse:
+        return JSONResponse(status_code=409, content={"detail": str(exc)})
+
+    # -- health & discovery -------------------------------------------------------
+
+    @app.get("/healthz")
+    async def healthz() -> dict[str, str]:
+        return {"status": "ok"}
+
+    @app.get("/workflows")
+    async def list_workflows() -> list[str]:
+        return service.workflow_names()
+
+    # -- repos --------------------------------------------------------------------
+
+    @app.post("/repos", status_code=201)
+    async def create_repo(body: RepoIn) -> RepoOut:
+        repo = service.create_repo(
+            Repo(
+                id=body.id, name=body.name, git_url=body.git_url, default_base=body.default_base
+            )
+        )
+        return RepoOut.of(repo)
+
+    @app.get("/repos")
+    async def list_repos() -> list[RepoOut]:
+        return [RepoOut.of(r) for r in service.list_repos()]
+
+    @app.get("/repos/{repo_id}")
+    async def get_repo(repo_id: str) -> RepoOut:
+        return RepoOut.of(service.get_repo(repo_id))
+
+    # -- tasks --------------------------------------------------------------------
+
+    @app.post("/tasks", status_code=201)
+    async def create_task(body: CreateTaskIn) -> TaskOut:
+        return TaskOut.of(service.create_task(body.repo_id, body.workflow))
+
+    @app.get("/tasks")
+    async def list_tasks() -> list[TaskOut]:
+        return [TaskOut.of(t) for t in service.list_tasks()]
+
+    @app.get("/tasks/{task_id}")
+    async def get_task(task_id: str) -> TaskOut:
+        return TaskOut.of(service.get_task(task_id))
+
+    @app.post("/tasks/{task_id}/transition")
+    async def transition(task_id: str, body: TransitionIn) -> TaskOut:
+        responsibilities = (
+            [
+                Responsibility(key=r.key, description="", status=r.status, comment=r.comment)
+                for r in body.responsibilities
+            ]
+            if body.responsibilities is not None
+            else None
+        )
+        return TaskOut.of(
+            service.request_transition(
+                task_id,
+                body.to_state,
+                trigger=body.trigger,
+                note=body.note,
+                responsibilities=responsibilities,
+            )
+        )
+
+    @app.put("/tasks/{task_id}/slug")
+    async def set_slug(task_id: str, body: SlugIn) -> TaskOut:
+        return TaskOut.of(service.set_slug(task_id, body.slug))
+
+    # -- artifacts ----------------------------------------------------------------
+
+    @app.put("/tasks/{task_id}/artifacts/{name}", status_code=204)
+    async def put_artifact(task_id: str, name: str, request: Request) -> Response:
+        service.put_artifact(task_id, name, await request.body())
+        return Response(status_code=204)
+
+    @app.get("/tasks/{task_id}/artifacts")
+    async def list_artifacts(task_id: str) -> list[str]:
+        return service.list_artifacts(task_id)
+
+    @app.get("/tasks/{task_id}/artifacts/{name}")
+    async def get_artifact(task_id: str, name: str) -> Response:
+        content = service.get_artifact(task_id, name)
+        if content is None:
+            raise HTTPException(status_code=404, detail=f"artifact {name!r} not found")
+        return Response(content=content, media_type="application/octet-stream")
+
+    # -- liveness -----------------------------------------------------------------
+
+    @app.post("/tasks/{task_id}/registrations", status_code=201)
+    async def register(task_id: str, body: RegisterIn) -> RegistrationOut:
+        return RegistrationOut.of(
+            service.register(task_id, body.container_id, body.runner_id)
+        )
+
+    @app.get("/tasks/{task_id}/registrations")
+    async def list_registrations(task_id: str) -> list[RegistrationOut]:
+        service.get_task(task_id)  # 404 if the task is unknown
+        return [RegistrationOut.of(r) for r in service.registrations(task_id)]
+
+    @app.post("/registrations/{registration_id}/heartbeat")
+    async def heartbeat(registration_id: str) -> RegistrationOut:
+        return RegistrationOut.of(service.heartbeat(registration_id))
+
+    @app.delete("/registrations/{registration_id}", status_code=204)
+    async def deregister(registration_id: str) -> Response:
+        service.deregister(registration_id)
+        return Response(status_code=204)
+
+    return app