agentdeck-sdk 3.1.0__py3-none-any.whl

agentdeck/serve.py

@@ -0,0 +1,330 @@
+"""Minimal HTTP surface: serve a project over FastAPI.
+
+    agentdeck-serve                  # console script; HOST / PORT env override
+
+Every endpoint below runs on the v2 ``Runtime`` a ``Deck`` composes: the handler builds a
+``RunContext``, calls ``Runtime.run`` / ``Runtime.resume`` / ``Runtime.pending``, and hands the
+canonical events to ``surfaces/serve/compat.py``, which renders v1's frames. So a turn — chat
+or workflow — leaves one canonical event log behind. The wire below is unchanged by that; that
+is the point, and ``tests/golden/`` is what proves it.
+
+``create_app()`` is ``Deck.from_project().asgi()`` — kept as a module-level function because the
+console script and every existing test import it by name; ``build_asgi_app(deck)`` is what
+:meth:`agentdeck.deck.Deck.asgi` actually calls, for a ``Deck`` built any other way.
+
+Endpoints:
+    GET  /health                     -> {"status": "ok", agents, workflows, skills}
+                                        503 {"status": "starting"} before the lifespan runs
+    POST /agents/{name}/chat         -> {"session_id", "message"} -> {"output"}
+    POST /agents/{name}/chat?stream=true
+                                      -> text/event-stream: "delta" events, then one
+                                         "done" event carrying {"output", "usage"};
+                                         an "error" event replaces "done" if the turn fails
+    POST /workflows/{name}           -> JSON state in, final state out — or
+                                        {"type": "interrupt", "payload", "thread_id"} when the
+                                        run pauses on a human decision;
+                                        409 while that thread's previous turn is unfinished,
+                                        an unanswered approval included
+    POST /workflows/{name}?stream=true
+                                      -> text/event-stream: "node_update"/"custom" events per
+                                         the LangGraph node updates/custom stream, then one
+                                         "done" event carrying the final state — or one
+                                         "interrupt" event in its place when the run pauses;
+                                         an "error" event replaces either if the run fails
+    GET  /workflows/{name}/pending   -> [{"type": "interrupt", "payload", "thread_id"}, ...]
+    POST /workflows/{name}/{thread_id}/resume
+                                      -> {"value": ...} -> final state, or the next interrupt;
+                                         404 when the thread has no paused run to answer
+    POST /runs/{run_id}/pause        -> {"reason": ...}? -> {"run_id", "verb", "recorded": true}
+    POST /runs/{run_id}/cancel       -> {"reason": ...}? -> {"run_id", "verb", "recorded": true}
+                                        Recorded, not applied: the run stops at its next safe
+                                        point, and its own run.paused / run.cancelled event is
+                                        what says it did
+    POST /runs/{run_id}/resume       -> {"reason": ...}? -> {"run_id", "status", "events"} for
+                                        the continuation this call played — 409 if the run is
+                                        not paused
+
+The workflow inbox above reads the event log, while ``Deck.due_resumes()`` still reads
+the graph's checkpointer — so the two disagree once approvals are driven through both doors
+(see the CHANGELOG for the plan to join them).
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+from contextlib import aclosing, asynccontextmanager
+from typing import TYPE_CHECKING, Any
+
+from agentdeck.core.content import coerce_input
+from agentdeck.core.status import status_of
+from agentdeck.errors import AgentdeckError, NotFoundError, SessionBusyError
+from agentdeck.surfaces.serve.compat import (
+    chat_frames,
+    chat_result,
+    interrupt_inbox,
+    workflow_frames,
+    workflow_result,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator, AsyncIterator, Awaitable, Callable
+
+    from fastapi import FastAPI
+
+    from agentdeck.core.events import Event
+    from agentdeck.deck import Deck
+
+logger = logging.getLogger(__name__)
+
+
+def create_app() -> Any:
+    from agentdeck.deck import Deck
+
+    return Deck.from_project().asgi()
+
+
+def _require_agent(deck: Deck, name: str) -> None:
+    """v1's 404 wording, owned here now that ``Deck`` exposes only the public ``agents``
+    mapping — a route that needs "unknown agent" as a client-facing miss checks membership
+    itself rather than reaching for a private lookup."""
+    if name not in deck.agents:
+        raise NotFoundError(f"No agent named {name!r}. Available: {sorted(deck.agents)}.")
+
+
+def _require_workflow(deck: Deck, name: str) -> None:
+    if name not in deck.workflows:
+        raise NotFoundError(f"No workflow named {name!r}. Available: {sorted(deck.workflows)}.")
+
+
+def build_asgi_app(deck: Deck) -> Any:
+    """The FastAPI app whose lifespan opens and closes ``deck`` — what
+    :meth:`agentdeck.deck.Deck.asgi` calls. Kept here, not in ``deck.py``: this is the one
+    module allowed to import FastAPI and the v1 wire-rendering helpers, the same rule every
+    other adapter directory follows for its own external system.
+    """
+    from fastapi import FastAPI, HTTPException, Request
+    from fastapi.responses import JSONResponse, StreamingResponse
+
+    @asynccontextmanager
+    async def lifespan(api: FastAPI) -> AsyncIterator[None]:
+        # `async with deck` closes the Redis session client + MCP servers on shutdown
+        # (including SIGTERM from `compose stop`), so no connection is leaked. Opening it is
+        # also where `resolve_event_store`/`resolve_control_port` run, which is where a
+        # `memory://` backend now logs its own "won't survive a restart" warning — composition
+        # time, not a server-specific check here.
+        async with deck:
+            api.state.deck = deck
+            yield
+            api.state.deck = None
+
+    api = FastAPI(title="agentdeck", lifespan=lifespan)
+    api.state.deck = None  # set by the lifespan; None means "not started yet"
+
+    def _deck() -> Deck:
+        if api.state.deck is None:
+            raise HTTPException(status_code=503, detail="agentdeck is not started")
+        return api.state.deck
+
+    # Starlette resolves a handler by walking the exception's MRO, so the
+    # AgentdeckError entry below would already catch NotFoundError. It gets its
+    # own entry because it is the one AgentdeckError caused by client input, and
+    # so the only one whose message is safe to echo back.
+    @api.exception_handler(NotFoundError)
+    async def not_found(_request: Request, exc: NotFoundError) -> JSONResponse:
+        return JSONResponse(status_code=404, content={"detail": str(exc)})
+
+    # The one refusal that is neither the client's malformed input nor a server fault: the log
+    # answered, and the answer was "this session already has a turn in flight". Its message
+    # names the holding run, which is what a caller retries behind.
+    @api.exception_handler(SessionBusyError)
+    async def session_busy(_request: Request, exc: SessionBusyError) -> JSONResponse:
+        return JSONResponse(status_code=409, content={"detail": str(exc)})
+
+    @api.exception_handler(AgentdeckError)
+    async def internal_error(request: Request, exc: AgentdeckError) -> JSONResponse:
+        # Every other AgentdeckError is a server-side fault, and its message can
+        # carry secrets (skill stderr, config values) — log it, never ship it.
+        logger.exception("%s serving %s", type(exc).__name__, request.url.path, exc_info=exc)
+        return JSONResponse(status_code=500, content={"detail": "internal error"})
+
+    @api.get("/health")
+    async def health() -> Any:
+        if api.state.deck is None:
+            return JSONResponse({"status": "starting"}, status_code=503)
+        return {"status": "ok", **_inventory(api.state.deck)}
+
+    @api.post("/agents/{name}/chat")
+    async def chat(name: str, body: dict[str, Any], stream: bool = False) -> Any:
+        # Read and validate the body up front: inside the generator either failure would
+        # surface as a 200 that just stops, since the response headers are already on the wire.
+        try:
+            session_id, message = body["session_id"], body["message"]
+        except KeyError as exc:
+            raise HTTPException(status_code=422, detail=f"missing field: {exc.args[0]}") from exc
+        # A body shape this endpoint cannot run is the client's mistake, not a server fault: 4xx
+        # like every other bad body here, never a 500 in somebody's alerting. Both fields are
+        # checked, because both reach a model that only accepts a string.
+        if not isinstance(session_id, str):
+            raise HTTPException(status_code=422, detail=f"session_id must be a string, got {type(session_id).__name__}")
+        try:
+            content = coerce_input(message)
+        except TypeError as exc:
+            raise HTTPException(
+                status_code=422, detail=f"message must be a string, got {type(message).__name__}"
+            ) from exc
+        deck = _deck()  # resolve before streaming so a pre-startup 503 keeps its status code
+        # Resolved against the agent catalog, not the Runtime's invocables: this route is
+        # agents-only (a workflow name must still 404 here), and the message matches v1's own.
+        _require_agent(deck, name)
+        run = deck.stream(name, content, session_id=session_id)
+        if stream:
+            return StreamingResponse(
+                chat_frames(await _opened(run)),
+                media_type="text/event-stream",
+                # Proxies buffer streamed responses by default; nginx needs X-Accel-Buffering.
+                headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+            )
+        return await chat_result(run)
+
+    @api.post("/workflows/{name}")
+    async def run_workflow(name: str, state: dict[str, Any], stream: bool = False, thread_id: str | None = None) -> Any:
+        deck = _deck()  # resolve before streaming so a pre-startup 503 keeps its status code
+        # Workflows-only, resolved against the workflow catalog rather than the Runtime's
+        # invocables: an agent name must still 404 here, with v1's message.
+        _require_workflow(deck, name)
+        # The posted state *is* the graph's input, and the thread the caller named is the
+        # session it runs under: one turn per thread at a time, and a resume can find it later.
+        run = deck.stream(name, state, session_id=thread_id)
+        if stream:
+            return StreamingResponse(
+                workflow_frames(await _opened(run)),
+                media_type="text/event-stream",
+                headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+            )
+        return await workflow_result(run)
+
+    @api.post("/runs/{run_id}/pause")
+    async def pause_run(run_id: str, body: dict[str, Any] | None = None) -> Any:
+        return await _control(_deck().pause, run_id, body, "pause")
+
+    @api.post("/runs/{run_id}/cancel")
+    async def cancel_run(run_id: str, body: dict[str, Any] | None = None) -> Any:
+        return await _control(_deck().cancel, run_id, body, "cancel")
+
+    @api.post("/runs/{run_id}/resume")
+    async def resume_run(run_id: str, body: dict[str, Any] | None = None) -> Any:
+        events = await _deck().resume(run_id, _reason(body))
+        if not events:
+            # 409, not 404: the run may well exist and simply not be paused — running,
+            # finished, cancelled, or already picked up by another worker. All of those are the
+            # same answer to this request, and none of them is an error the caller should retry.
+            raise HTTPException(status_code=409, detail=f"run {run_id!r} is not paused")
+        return {"run_id": run_id, "status": status_of(events).value, "events": len(events)}
+
+    def _reason(body: dict[str, Any] | None) -> str | None:
+        """The optional ``reason`` a control request carries, validated at the trust boundary:
+        it is recorded in the log and read by whoever asks why a run stopped."""
+        reason = (body or {}).get("reason")
+        if reason is not None and not isinstance(reason, str):
+            raise HTTPException(status_code=422, detail=f"reason must be a string, got {type(reason).__name__}")
+        return reason
+
+    async def _control(
+        operation: Callable[[str, str | None], Awaitable[bool]], run_id: str, body: dict[str, Any] | None, verb: str
+    ) -> Any:
+        """Pause and cancel are the same request: record intent for a ``run_id``, answer at once.
+
+        ``recorded`` says the request is written down, never that the run has stopped — a run
+        inside a tool call stops at its next safe point, and the run's own ``run.paused`` /
+        ``run.cancelled`` event is what reports that. Runs that already ended are accepted and
+        do nothing, which is what makes a double-clicked cancel harmless.
+        """
+        if not await operation(run_id, _reason(body)):
+            raise HTTPException(status_code=503, detail="run control is unavailable: no control backend is configured")
+        return {"run_id": run_id, "verb": verb, "recorded": True}
+
+    @api.get("/workflows/{name}/pending")
+    async def pending_interrupts(name: str) -> Any:
+        deck = _deck()
+        _require_workflow(deck, name)
+        return interrupt_inbox(await deck.pending(), name)
+
+    @api.post("/workflows/{name}/{thread_id}/resume")
+    async def resume_workflow(name: str, thread_id: str, body: dict[str, Any]) -> Any:
+        if "value" not in body:
+            raise HTTPException(status_code=422, detail="missing field: value")
+        deck = _deck()
+        _require_workflow(deck, name)
+        # v1's own 404 names the thread, not a run_id the caller never posted — so the lookup
+        # stays here rather than moving into Deck.answer, whose own miss talks about run_id.
+        paused = next(
+            (run for run in await deck.pending() if run.invocable == name and run.thread_id == thread_id),
+            None,
+        )
+        if paused is None:
+            raise NotFoundError(f"No paused run of {name!r} on thread {thread_id!r}.")
+        return await deck.answer(paused.run_id, body["value"])
+
+    return api
+
+
+def _inventory(deck: Deck) -> dict[str, list[str]]:
+    """v1's ``{"agents": [...], "workflows": [...], "skills": [...]}`` — built from ``Deck``'s
+    own properties rather than a separate cache, since they are already read-only mappings.
+
+    ``skills.list()``, not ``.build()``: ``build()`` re-scans disk and overwrites the registry
+    every call, which would make a hot probe endpoint re-read every ``SKILL.md`` on each request
+    and let one edited after startup change what ``load_skill`` returns mid-run — the catalog is
+    supposed to be immutable once ``BUILT``. ``Deck.build()`` already populated the cache
+    ``list()`` reads.
+    """
+    return {
+        "agents": sorted(deck.agents),
+        "workflows": sorted(deck.workflows),
+        "skills": sorted(deck.skills.list()) if deck.skills is not None else [],
+    }
+
+
+async def _opened(run: AsyncGenerator[Event, None]) -> AsyncGenerator[Event, None]:
+    """``run`` with its opening event already pulled, so a refusal is still an answer.
+
+    A run is claimed on its first event, so a generator handed straight to
+    ``StreamingResponse`` has committed ``200`` and ``text/event-stream`` before the claim is
+    even attempted — and a ``SessionBusyError`` then reaches the client in-band as a body that
+    stops, indistinguishable from a run that produced nothing. Pulling the opening event here
+    lets the refusal reach the exception handler that answers it **409**. The wire is unchanged:
+    ``run.started`` renders to no v1 frame, streamed or not.
+    """
+    opening = await anext(run)
+
+    async def replayed() -> AsyncGenerator[Event, None]:
+        # Closing this generator does not close the one it delegates to — a consumer that walks
+        # away must still land as a ``GeneratorExit`` inside the run, which is what closes it in
+        # the log.
+        async with aclosing(run):
+            yield opening
+            async for event in run:
+                yield event
+
+    return replayed()
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="agentdeck-serve",
+        description="Serves the deck discovered in ./.agentdeck over the v1 HTTP/SSE surface.",
+        epilog="Run it from the directory that holds .agentdeck — there is no --project-dir flag.",
+    )
+    parser.add_argument("--host", default=os.getenv("HOST", "0.0.0.0"), help="interface to bind (env: HOST)")
+    parser.add_argument("--port", type=int, default=int(os.getenv("PORT", "8000")), help="port to bind (env: PORT)")
+    args = parser.parse_args(argv)
+
+    import uvicorn
+
+    uvicorn.run(create_app(), host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+    main()

agentdeck/skills/__init__.py

@@ -0,0 +1,114 @@
+"""``Skills`` — the capability object a ``Deck`` composes for skill disclosure.
+
+A skill is progressive knowledge disclosure inside an agent's own execution, not a program to
+run (``docs/delivery/plan-skills.md``). ``Skills`` owns one or more root directories, scans each
+one's direct children for ``<root>/<name>/SKILL.md`` — never recursively — and merges the result
+into one name-keyed registry at :meth:`Skills.build`. Constructing it reads nothing from disk;
+``build()`` is the one place a bad skill directory is reported.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from agentdeck.errors import ConfigError, NotFoundError
+from agentdeck.skills.bundle import SKILL_MD_FILENAME, SkillBundle
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+class Skills:
+    """One or more skill roots, merged into one registry at :meth:`build`.
+
+    ``validate=True`` (the default) enforces what the Agent Skills contract requires and a
+    permissive scan would not catch: a ``SKILL.md``'s frontmatter ``name`` must match its
+    directory name, and it must declare a non-empty ``description`` — the text a model reads to
+    decide whether to use the skill at all. Both fail ``build()`` loudly instead of registering
+    a skill nothing can address or nothing can choose.
+    """
+
+    def __init__(self, *roots: str | Path, validate: bool = True) -> None:
+        if not roots:
+            raise ConfigError("Skills() needs at least one root directory.")
+        self._roots = tuple(Path(r).expanduser() for r in roots)
+        self._validate = validate
+        self._bundles: dict[str, SkillBundle] | None = None
+
+    @property
+    def roots(self) -> tuple[Path, ...]:
+        return self._roots
+
+    def build(self) -> dict[str, SkillBundle]:
+        """Scan every root (direct children only) and merge into one registry.
+
+        A root that does not exist on disk contributes no skills rather than failing — a
+        project need not have created its skills directory yet. Re-scans on every call; nothing
+        here holds a resource worth caching across calls.
+        """
+        merged: dict[str, SkillBundle] = {}
+        found_under: dict[str, Path] = {}
+        for root in self._roots:
+            resolved = root.resolve()
+            if not resolved.is_dir():
+                continue
+            for child in sorted(resolved.iterdir()):
+                if not child.is_dir() or child.name.startswith((".", "_")):
+                    continue
+                if not (child / SKILL_MD_FILENAME).is_file():
+                    continue
+                bundle = SkillBundle.from_path(child)
+                if self._validate:
+                    _validate_bundle(bundle, child)
+                if bundle.name in merged:
+                    raise ConfigError(
+                        f"skill {bundle.name!r} found under both {found_under[bundle.name]} and "
+                        f"{child} — a skill name must be unique across roots."
+                    )
+                merged[bundle.name] = bundle
+                found_under[bundle.name] = child
+        self._bundles = merged
+        return dict(merged)
+
+    def list(self, *, refresh: bool = False) -> dict[str, SkillBundle]:
+        if refresh or self._bundles is None:
+            self.build()
+        assert self._bundles is not None  # populated by build() on the line above
+        return dict(self._bundles)
+
+    def get(self, name: str) -> SkillBundle:
+        bundles = self.list()
+        try:
+            return bundles[name]
+        except KeyError:
+            raise NotFoundError(
+                f"No skill named {name!r} under {[str(r) for r in self._roots]}. Available: {sorted(bundles)}."
+            ) from None
+
+    def disclosure_text(self, names: Sequence[str]) -> str:
+        """The instructions-block for an agent's own ``skills=[...]``: each name and
+        description, never the full body — a model still decides whether to use one instead of
+        finding it pre-loaded into its context."""
+        if not names:
+            return ""
+        lines = [
+            "\n\n### Skills available",
+            "Each entry below is a name and a description. Call `load_skill(name)` to read the "
+            "full instructions before following one.",
+        ]
+        lines.extend(f"- {name}: {self.get(name).description}" for name in names)
+        return "\n".join(lines)
+
+
+def _validate_bundle(bundle: SkillBundle, path: Path) -> None:
+    if bundle.name != path.name:
+        raise ConfigError(
+            f"{path / SKILL_MD_FILENAME}: frontmatter declares name {bundle.name!r}, which must "
+            f"match its directory name {path.name!r}."
+        )
+    if not bundle.description:
+        raise ConfigError(f"{path / SKILL_MD_FILENAME}: missing a 'description' in its frontmatter.")
+
+
+__all__ = ["Skills", "SkillBundle"]

agentdeck/skills/bundle.py

@@ -0,0 +1,65 @@
+"""Parse one ``SKILL.md`` bundle directory."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from agentdeck.errors import ConfigError
+
+SKILL_MD_FILENAME = "SKILL.md"
+
+_FRONTMATTER_RE = re.compile(r"\A---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+
+
+@dataclass(slots=True)
+class SkillBundle:
+    """A parsed skill bundle on disk. Construct via :meth:`from_path`."""
+
+    name: str
+    path: Path
+    description: str = ""
+    frontmatter: dict[str, Any] = field(default_factory=dict)
+    body: str = ""
+
+    @classmethod
+    def from_path(cls, path: str | Path, *, name: str | None = None) -> SkillBundle:
+        bundle_path = Path(path).expanduser().resolve()
+        if not bundle_path.is_dir():
+            raise FileNotFoundError(f"skill bundle not found: {bundle_path}")
+        skill_md = bundle_path / SKILL_MD_FILENAME
+        if not skill_md.is_file():
+            raise FileNotFoundError(f"missing {SKILL_MD_FILENAME} under {bundle_path}")
+        frontmatter, body = _split_frontmatter(skill_md.read_text(encoding="utf-8"))
+        return cls(
+            name=name or _str_field(frontmatter, "name") or bundle_path.name,
+            path=bundle_path,
+            description=_str_field(frontmatter, "description").strip(),
+            frontmatter=frontmatter,
+            body=body,
+        )
+
+
+def _str_field(frontmatter: dict[str, Any], key: str) -> str:
+    value = frontmatter.get(key)
+    return value if isinstance(value, str) else ""
+
+
+def _split_frontmatter(text: str) -> tuple[dict[str, Any], str]:
+    match = _FRONTMATTER_RE.match(text)
+    if not match:
+        return {}, text
+    try:
+        data = yaml.safe_load(match.group(1)) or {}
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"invalid YAML frontmatter: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ConfigError(f"frontmatter must be a YAML mapping, got {type(data).__name__}")
+    return data, text[match.end() :]
+
+
+__all__ = ["SKILL_MD_FILENAME", "SkillBundle"]

agentdeck/surfaces/__init__.py

@@ -0,0 +1,4 @@
+"""Ring 3: thin readers of a ``Runtime`` handed to them by the composition root.
+Never import an adapter directly — wiring is the composition root's job, and the
+import linter enforces it.
+"""

agentdeck/surfaces/cli/__init__.py

@@ -0,0 +1,7 @@
+"""The ~50-line CLI chat renderer — the switch-loop reference consumer."""
+
+from __future__ import annotations
+
+from agentdeck.surfaces.cli.chat import render, stream_chat
+
+__all__ = ["render", "stream_chat"]

agentdeck/surfaces/cli/chat.py

@@ -0,0 +1,88 @@
+"""~50-line CLI chat renderer — the reference consumer for the event stream.
+
+Distinguishes bubbles using **only** ``event.origin`` and ``payload.message_id`` — the
+label is ``origin``, the bubble boundary is ``message_id``; grep this file for any other
+mechanism and you won't find one. The transcript is rebuilt from
+``message.completed`` alone: ``text.delta`` is read for nothing, so there is no delta
+assembly to get wrong.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from agentdeck.core.content import TextBlock
+from agentdeck.core.events import (
+    ControlObserved,
+    ControlRequested,
+    Event,
+    MessageCompleted,
+    ProgressReported,
+    RunCancelled,
+    RunCompleted,
+    RunFailed,
+    RunStarted,
+    StatusReported,
+    ToolCallCompleted,
+    ToolCallStarted,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+    import httpx
+
+
+async def render(lines: AsyncIterator[str]) -> None:
+    """Print one line per bubble: a user turn, a tool notice, a completed message, a control
+    notice, or the run's close. Everything else (deltas, ``custom``, ``node.updated``, ...)
+    is skipped by design, per this module's docstring — the ``case _`` default below."""
+    async for line in lines:
+        if not line.startswith("data: "):
+            continue  # blank keep-alives and any `event: ...` framing line
+        event = Event.model_validate(json.loads(line.removeprefix("data: ")))
+        match event.payload:
+            case RunStarted(input=blocks):
+                text = " ".join(block.text for block in blocks if isinstance(block, TextBlock))
+                print(f"You: {text}")
+            case ToolCallStarted(tool=tool):
+                print(f"[tool] {tool} called")
+            case ToolCallCompleted(tool=tool, result_preview=preview):
+                print(f"[tool] {tool} -> {preview}")
+            case StatusReported(message=message):
+                print(f"[status] {message}")
+            case ProgressReported(step=step, current=current, total=total):
+                print(f"[progress] {step}{_counted(current, total)}")
+            case MessageCompleted(message_id=message_id, text=text):
+                print(f"{event.origin} [{message_id}]: {text}")
+            case ControlRequested(verb=verb, reason=reason):
+                # Between a request and the run acting on it there can be a whole tool call,
+                # so a reader watching a stream that has gone quiet is told which it is.
+                print(f"[control] {verb} requested" + (f": {reason}" if reason else ""))
+            case ControlObserved(verb=verb, safe_point=safe_point):
+                print(f"[control] {verb} observed at {safe_point}")
+            case RunCompleted() | RunFailed() | RunCancelled():
+                print(f"-- {event.kind} --")
+            case _:
+                pass
+
+
+def _counted(current: int | None, total: int | None) -> str:
+    """``" (2/4)"`` when counted, ``""`` when the stage has no numbers — and never a
+    percentage, which a missing ``total`` would make up."""
+    if current is None and total is None:
+        return ""
+    return f" ({'?' if current is None else current}/{'?' if total is None else total})"
+
+
+async def stream_chat(client: httpx.AsyncClient, name: str, session_id: str, message: str) -> None:
+    """Post one chat turn to the crude SSE route (``surfaces/serve/app.py``) and render it
+    live — the thing this whole module exists to prove works end to end."""
+    async with client.stream(
+        "POST", f"/v2/invocables/{name}/chat", json={"session_id": session_id, "message": message}
+    ) as response:
+        await render(response.aiter_lines())
+
+
+__all__ = ["render", "stream_chat"]

agentdeck/surfaces/serve/__init__.py

@@ -0,0 +1,7 @@
+"""The crude v2 SSE surface — a skeleton component, hardened or discarded at the M0 review."""
+
+from __future__ import annotations
+
+from agentdeck.surfaces.serve.app import build_app
+
+__all__ = ["build_app"]