outfitter-dispatch 0.1.0__py3-none-any.whl

outfitter/dispatch/__init__.py

@@ -0,0 +1,6 @@
+"""outfitter.dispatch — local control plane for orchestrating Codex agent lanes.
+
+PEP 420 namespace package: there is intentionally no ``__init__.py`` at the
+``src/outfitter/`` level. The importable package starts here, at
+``outfitter.dispatch``.
+"""

outfitter/dispatch/cli.py

@@ -0,0 +1,16 @@
+"""dispatch CLI entrypoint (console script ``dispatch``).
+
+The app is *derived* from the op registry — there are no hand-written per-op
+commands here (see ``surfaces/cli.py`` and ``contracts/derive_cli.py``). Adding
+an op makes it appear on the CLI automatically.
+"""
+
+from __future__ import annotations
+
+from outfitter.dispatch.surfaces.cli import build_cli
+
+app = build_cli()
+
+
+if __name__ == "__main__":
+    app()

outfitter/dispatch/client/AGENTS.md

@@ -0,0 +1,29 @@
+# client/ — the App Server client
+
+Path: `src/outfitter/dispatch/client/`. The ONLY place that spawns or speaks to `codex app-server`. Importable standalone (no daemon dependency).
+
+## Transport
+
+- Spawn `codex app-server --listen stdio://` via `asyncio.create_subprocess_exec`. **stdio JSONL is the only bare-JSON transport** — one newline-delimited JSON message per line. (unix/ws are WebSocket-framed; the managed daemon control socket is auth-gated. Do not use them.)
+- One app-server process hosts many lanes. A single connection multiplexes them.
+- Detect crash via stdout EOF; surface it so the daemon can restart + re-resume.
+
+## Message router
+
+Demux the single stream: responses by request `id`, notifications by `threadId`, into per-lane async queues + a global stream. Expose `events(thread_id | all)`. This is the verified pattern (mirrors the Python SDK's internal router).
+
+## Primitives (typed; Pydantic wire models)
+
+`initialize` → `thread_start/resume/list/read/archive` → `turn_start/steer/interrupt` → `inject_items` → approval responder. Verified gotchas to encode:
+
+- `thread/start.sandbox` is a **string** enum (`read-only`/`workspace-write`/`danger-full-access`); `turn/start.sandboxPolicy` is an **object** (`{type:"readOnly", ...}`). Different encodings — model both.
+- `turn/steer` requires `expectedTurnId` (from `turn/started`).
+- `thread/list` results are under `result.data` (not `result.threads`); `useStateDbOnly:true` reads the persisted store.
+- `thread/resume` of a *persisted* thread yields live event fan-out; pre-persistence it errors `no rollout found`.
+- Approvals are server→client requests: lane emits `thread/status/changed` `activeFlags:["waitingOnApproval"]`; reply `{id, result:{decision}}` (`accept`/`acceptForSession`/`decline`/`cancel`); server emits `serverRequest/resolved`. File-change approvals carry **no diff** — correlate by `itemId` to the `fileChange` item.
+- Threads persist by default (`ephemeral:false`). Pass `ephemeral:true` for throwaway/test lanes.
+
+## Discipline
+
+- Pin the binary; regenerate wire models from `codex app-server generate-json-schema` for that version. Do NOT depend on the `openai-codex` Python SDK (it pins an older CLI).
+- No business logic here — this layer is transport + typed primitives only. Orchestration lives in `core/`.

outfitter/dispatch/client/__init__.py

@@ -0,0 +1,47 @@
+"""Typed async App Server client (importable standalone, no daemon dependency).
+
+The only layer that spawns or speaks to ``codex app-server``. Exposes the typed
+primitives, the normalized ``LaneEvent`` vocabulary, and the client exceptions.
+"""
+
+from __future__ import annotations
+
+from .client import AppServerClient
+from .errors import AppServerError, ClientError, ProtocolError, TransportError
+from .events import (
+    ApprovalRequested,
+    DiffUpdated,
+    ItemCompleted,
+    LaneEvent,
+    LaneIdle,
+    StatusChanged,
+    TokenUsageUpdated,
+    TurnCompleted,
+    TurnFailed,
+    TurnStarted,
+)
+from .models import InitializeResult, SandboxPolicy, ThreadInfo
+from .transport import StdioTransport, Transport
+
+__all__ = [
+    "AppServerClient",
+    "AppServerError",
+    "ApprovalRequested",
+    "ClientError",
+    "DiffUpdated",
+    "InitializeResult",
+    "ItemCompleted",
+    "LaneEvent",
+    "LaneIdle",
+    "ProtocolError",
+    "SandboxPolicy",
+    "StatusChanged",
+    "StdioTransport",
+    "ThreadInfo",
+    "TokenUsageUpdated",
+    "Transport",
+    "TransportError",
+    "TurnCompleted",
+    "TurnFailed",
+    "TurnStarted",
+]

outfitter/dispatch/client/client.py

@@ -0,0 +1,360 @@
+"""The App Server client facade.
+
+Transport + router + typed primitives. The ONLY place that speaks the App Server
+protocol (``.claude/rules/client.md``). Importable standalone (no daemon). No
+business logic here — orchestration lives in ``core/``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from collections.abc import AsyncIterator
+from types import TracebackType
+from typing import Self
+
+from pydantic import BaseModel
+
+from .errors import ProtocolError, TransportError
+from .events import LaneEvent
+from .models import (
+    ApprovalPolicy,
+    ApprovalsReviewer,
+    ClientInfo,
+    Decision,
+    Effort,
+    InitializeParams,
+    InitializeResult,
+    InjectItemsParams,
+    Personality,
+    ReasoningSummary,
+    SandboxPolicy,
+    TextInput,
+    ThreadArchiveParams,
+    ThreadCompactStartParams,
+    ThreadForkParams,
+    ThreadGoal,
+    ThreadGoalClearParams,
+    ThreadGoalGetParams,
+    ThreadGoalGetResult,
+    ThreadGoalResult,
+    ThreadGoalSetParams,
+    ThreadGoalStatus,
+    ThreadInfo,
+    ThreadListParams,
+    ThreadListResult,
+    ThreadReadParams,
+    ThreadResult,
+    ThreadResumeParams,
+    ThreadRollbackParams,
+    ThreadSandbox,
+    ThreadSetNameParams,
+    ThreadStartParams,
+    TurnInterruptParams,
+    TurnStartParams,
+    TurnSteerParams,
+)
+from .router import Router
+from .transport import Transport
+
+_DEFAULT_CLIENT_INFO = ClientInfo(name="dispatch", version="0")
+
+
+def _dump(model: BaseModel) -> dict[str, object]:
+    # All params are WireModel/BaseModel; serialize with aliases, drop None.
+    return model.model_dump(by_alias=True, exclude_none=True)
+
+
+class AppServerClient:
+    """Typed async client over one app-server connection."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+        self._router = Router()
+        self._id = 0
+        self._read_task: asyncio.Task[None] | None = None
+        self._closed = False
+        self._closed_event = asyncio.Event()  # set when the read loop ends (EOF or close)
+
+    async def start(self) -> None:
+        """Begin consuming the transport. Idempotent."""
+        if self._read_task is None:
+            self._read_task = asyncio.create_task(self._read_loop())
+
+    async def __aenter__(self) -> Self:
+        await self.start()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    async def _read_loop(self) -> None:
+        try:
+            try:
+                while True:
+                    message = await self._transport.receive()
+                    if message is None:
+                        break
+                    self._router.handle(message)
+            except (TransportError, ProtocolError) as exc:
+                self._router.fail_all(exc)
+                return
+            self._router.fail_all(TransportError("app-server stream closed (stdout EOF)"))
+        finally:
+            self._closed_event.set()  # wake supervisors waiting on wait_closed()
+
+    async def wait_closed(self) -> None:
+        """Block until the read loop ends — EOF (app-server crash) or ``close()``."""
+        await self._closed_event.wait()
+
+    def _next_id(self) -> int:
+        self._id += 1
+        return self._id
+
+    async def _request(
+        self, method: str, params: dict[str, object] | None = None
+    ) -> dict[str, object]:
+        request_id = self._next_id()
+        fut = self._router.new_request(request_id)
+        message: dict[str, object] = {"id": request_id, "method": method}
+        if params is not None:
+            message["params"] = params
+        await self._transport.send(message)
+        try:
+            return await fut
+        except asyncio.CancelledError:
+            # A bounded caller (e.g. attach's wait_for) timed out: drop the pending
+            # request so abandoned ids don't accumulate in the router.
+            self._router.discard_request(request_id)
+            raise
+
+    async def _notify(self, method: str, params: dict[str, object] | None = None) -> None:
+        message: dict[str, object] = {"method": method}
+        if params is not None:
+            message["params"] = params
+        await self._transport.send(message)
+
+    # --- lifecycle ------------------------------------------------------------
+
+    async def initialize(
+        self,
+        client_info: ClientInfo = _DEFAULT_CLIENT_INFO,
+        capabilities: dict[str, bool] | None = None,
+    ) -> InitializeResult:
+        params = InitializeParams(
+            client_info=client_info,
+            capabilities=capabilities if capabilities is not None else {"experimentalApi": False},
+        )
+        result = await self._request("initialize", _dump(params))
+        await self._notify("initialized", {})
+        return InitializeResult.model_validate(result)
+
+    # --- threads --------------------------------------------------------------
+
+    async def thread_start(
+        self,
+        cwd: str | None,
+        sandbox: ThreadSandbox = "read-only",
+        approval_policy: ApprovalPolicy = "never",
+        approvals_reviewer: ApprovalsReviewer | None = None,
+        base_instructions: str | None = None,
+        developer_instructions: str | None = None,
+        personality: Personality | None = None,
+        service_tier: str | None = None,
+        model: str | None = None,
+        model_provider: str | None = None,
+        ephemeral: bool = False,
+    ) -> ThreadInfo:
+        params = ThreadStartParams(
+            cwd=cwd,
+            sandbox=sandbox,
+            approval_policy=approval_policy,
+            approvals_reviewer=approvals_reviewer,
+            base_instructions=base_instructions,
+            developer_instructions=developer_instructions,
+            personality=personality,
+            service_tier=service_tier,
+            model=model,
+            model_provider=model_provider,
+            ephemeral=ephemeral,
+        )
+        result = await self._request("thread/start", _dump(params))
+        return ThreadResult.model_validate(result).thread
+
+    async def thread_resume(self, thread_id: str) -> ThreadInfo:
+        result = await self._request(
+            "thread/resume", _dump(ThreadResumeParams(thread_id=thread_id))
+        )
+        return ThreadResult.model_validate(result).thread
+
+    async def thread_fork(
+        self,
+        thread_id: str,
+        *,
+        cwd: str | None = None,
+        sandbox: ThreadSandbox | None = None,
+        approval_policy: ApprovalPolicy | None = None,
+        approvals_reviewer: ApprovalsReviewer | None = None,
+        base_instructions: str | None = None,
+        developer_instructions: str | None = None,
+        service_tier: str | None = None,
+        model: str | None = None,
+        model_provider: str | None = None,
+        ephemeral: bool = False,
+    ) -> ThreadInfo:
+        params = ThreadForkParams(
+            thread_id=thread_id,
+            cwd=cwd,
+            sandbox=sandbox,
+            approval_policy=approval_policy,
+            approvals_reviewer=approvals_reviewer,
+            base_instructions=base_instructions,
+            developer_instructions=developer_instructions,
+            service_tier=service_tier,
+            model=model,
+            model_provider=model_provider,
+            ephemeral=ephemeral,
+        )
+        result = await self._request("thread/fork", _dump(params))
+        return ThreadResult.model_validate(result).thread
+
+    async def thread_list(
+        self, limit: int = 50, cursor: str | None = None, use_state_db_only: bool | None = None
+    ) -> list[ThreadInfo]:
+        params = ThreadListParams(limit=limit, cursor=cursor, use_state_db_only=use_state_db_only)
+        result = await self._request("thread/list", _dump(params))
+        return ThreadListResult.model_validate(result).data
+
+    async def thread_read(self, thread_id: str, include_turns: bool = False) -> dict[str, object]:
+        return await self._request(
+            "thread/read", _dump(ThreadReadParams(thread_id=thread_id, include_turns=include_turns))
+        )
+
+    async def thread_archive(self, thread_id: str) -> None:
+        await self._request("thread/archive", _dump(ThreadArchiveParams(thread_id=thread_id)))
+
+    async def thread_set_name(self, thread_id: str, name: str) -> None:
+        await self._request(
+            "thread/name/set", _dump(ThreadSetNameParams(thread_id=thread_id, name=name))
+        )
+
+    async def thread_rollback(self, thread_id: str, num_turns: int) -> ThreadInfo:
+        result = await self._request(
+            "thread/rollback", _dump(ThreadRollbackParams(thread_id=thread_id, num_turns=num_turns))
+        )
+        return ThreadResult.model_validate(result).thread
+
+    async def thread_compact_start(self, thread_id: str) -> None:
+        await self._request(
+            "thread/compact/start", _dump(ThreadCompactStartParams(thread_id=thread_id))
+        )
+
+    async def thread_goal_get(self, thread_id: str) -> ThreadGoal | None:
+        result = await self._request(
+            "thread/goal/get", _dump(ThreadGoalGetParams(thread_id=thread_id))
+        )
+        return ThreadGoalGetResult.model_validate(result).goal
+
+    async def thread_goal_set(
+        self,
+        thread_id: str,
+        *,
+        objective: str | None = None,
+        status: ThreadGoalStatus | None = None,
+        token_budget: int | None = None,
+    ) -> ThreadGoal:
+        params = ThreadGoalSetParams(
+            thread_id=thread_id,
+            objective=objective,
+            status=status,
+            token_budget=token_budget,
+        )
+        result = await self._request("thread/goal/set", _dump(params))
+        return ThreadGoalResult.model_validate(result).goal
+
+    async def thread_goal_clear(self, thread_id: str) -> None:
+        await self._request("thread/goal/clear", _dump(ThreadGoalClearParams(thread_id=thread_id)))
+
+    # --- turns + injection ----------------------------------------------------
+
+    async def turn_start(
+        self,
+        thread_id: str,
+        text: str,
+        cwd: str,
+        approval_policy: ApprovalPolicy = "never",
+        approvals_reviewer: ApprovalsReviewer | None = None,
+        sandbox_policy: SandboxPolicy | None = None,
+        effort: Effort | None = None,
+        summary: ReasoningSummary | None = None,
+        model: str | None = None,
+        output_schema: dict[str, object] | None = None,
+        personality: Personality | None = None,
+    ) -> dict[str, object]:
+        params = TurnStartParams(
+            thread_id=thread_id,
+            input=[TextInput(text=text)],
+            cwd=cwd,
+            approval_policy=approval_policy,
+            approvals_reviewer=approvals_reviewer,
+            sandbox_policy=sandbox_policy if sandbox_policy is not None else SandboxPolicy(),
+            effort=effort,
+            summary=summary,
+            model=model,
+            output_schema=output_schema,
+            personality=personality,
+        )
+        return await self._request("turn/start", _dump(params))
+
+    async def turn_steer(
+        self, thread_id: str, expected_turn_id: str, text: str
+    ) -> dict[str, object]:
+        params = TurnSteerParams(
+            thread_id=thread_id, expected_turn_id=expected_turn_id, input=[TextInput(text=text)]
+        )
+        return await self._request("turn/steer", _dump(params))
+
+    async def turn_interrupt(self, thread_id: str, turn_id: str) -> None:
+        await self._request(
+            "turn/interrupt", _dump(TurnInterruptParams(thread_id=thread_id, turn_id=turn_id))
+        )
+
+    async def inject_items(self, thread_id: str, items: list[dict[str, object]]) -> None:
+        await self._request(
+            "thread/inject_items", _dump(InjectItemsParams(thread_id=thread_id, items=items))
+        )
+
+    # --- approvals ------------------------------------------------------------
+
+    async def respond_approval(self, request_id: int, decision: Decision) -> None:
+        """Reply to a server->client approval request on the same stream."""
+        await self._transport.send({"id": request_id, "result": {"decision": decision}})
+
+    # --- event streams --------------------------------------------------------
+
+    def events(self, lane: str | None = None) -> AsyncIterator[LaneEvent]:
+        """Normalized LaneEvents for one lane, or all lanes when ``lane`` is None."""
+        return self._router.events.subscribe(lane)
+
+    def raw_events(self, lane: str | None = None) -> AsyncIterator[dict[str, object]]:
+        """Raw notifications/server-requests for one lane (content for ``show``)."""
+        return self._router.raw.subscribe(lane)
+
+    async def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        # Fail any in-flight requests and close the event/raw streams up front, so
+        # callers never deadlock if close() wins the race against stdout EOF.
+        self._router.fail_all(TransportError("client closed"))
+        if self._read_task is not None:
+            self._read_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._read_task
+        await self._transport.close()
+        self._closed_event.set()

outfitter/dispatch/client/errors.py

@@ -0,0 +1,33 @@
+"""Client-layer exceptions.
+
+The ``client/`` package is importable standalone (no daemon/contracts
+dependency, per ``.claude/rules/client.md``), so it defines its own minimal
+exception family. Phase 2's ``contracts/errors.py`` (the ``DispatchError``
+taxonomy, ADR-0001) maps these into surface-projected errors at the handler
+boundary; nothing here imports from ``contracts``.
+"""
+
+from __future__ import annotations
+
+
+class ClientError(Exception):
+    """Base class for all App Server client errors."""
+
+
+class TransportError(ClientError):
+    """The app-server subprocess/stream failed (spawn failure, stdout EOF, write
+    to a dead process)."""
+
+
+class ProtocolError(ClientError):
+    """A wire message was malformed or violated the expected JSON-RPC-lite shape."""
+
+
+class AppServerError(ClientError):
+    """The app-server returned a JSON-RPC error response to one of our requests."""
+
+    def __init__(self, code: int, message: str, data: object | None = None) -> None:
+        super().__init__(f"app-server error {code}: {message}")
+        self.code = code
+        self.message = message
+        self.data = data

outfitter/dispatch/client/events.py

@@ -0,0 +1,163 @@
+"""Normalized internal LaneEvent vocabulary + projection (ADR-0007).
+
+The client layer is the single point that turns raw App Server notifications and
+server-requests into typed ``LaneEvent``s. The reactor, triggers, and the
+conditional-guard seam operate ONLY on these — never on raw protocol dicts — so
+they stay stable across binary/protocol drift.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+ApprovalKind = Literal["command", "file_change"]
+
+
+@dataclass(frozen=True)
+class LaneEvent:
+    """Base for all normalized lane events. ``lane_id`` is the App Server threadId."""
+
+    lane_id: str
+
+
+@dataclass(frozen=True)
+class TurnStarted(LaneEvent):
+    turn_id: str | None = None
+
+
+@dataclass(frozen=True)
+class TurnCompleted(LaneEvent):
+    turn_id: str | None = None
+
+
+@dataclass(frozen=True)
+class TurnFailed(LaneEvent):
+    turn_id: str | None = None
+    message: str | None = None
+
+
+@dataclass(frozen=True)
+class LaneIdle(LaneEvent):
+    """Derived: the lane has no active flags (computed here, not per-consumer)."""
+
+
+@dataclass(frozen=True)
+class ApprovalRequested(LaneEvent):
+    """A server->client approval request. ``request_id`` is the JSON-RPC id to
+    reply on; file-change requests carry no diff (correlate by ``item_id``)."""
+
+    request_id: int
+    kind: ApprovalKind
+    item_id: str | None = None
+    turn_id: str | None = None
+
+
+@dataclass(frozen=True)
+class ItemCompleted(LaneEvent):
+    item_id: str | None = None
+
+
+@dataclass(frozen=True)
+class DiffUpdated(LaneEvent):
+    turn_id: str | None = None
+
+
+@dataclass(frozen=True)
+class StatusChanged(LaneEvent):
+    active_flags: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class TokenUsageUpdated(LaneEvent):
+    pass
+
+
+@dataclass(frozen=True)
+class GoalUpdated(LaneEvent):
+    pass
+
+
+@dataclass(frozen=True)
+class GoalCleared(LaneEvent):
+    pass
+
+
+@dataclass(frozen=True)
+class ThreadCompacted(LaneEvent):
+    pass
+
+
+def _thread_id(params: dict[str, object]) -> str | None:
+    tid = params.get("threadId")
+    return tid if isinstance(tid, str) else None
+
+
+def _str(params: dict[str, object], key: str) -> str | None:
+    val = params.get(key)
+    return val if isinstance(val, str) else None
+
+
+def project_notification(method: str, params: dict[str, object]) -> list[LaneEvent]:
+    """Project a server->client notification into zero or more LaneEvents.
+
+    Unknown methods project to ``[]`` (ignored), keeping triggers decoupled from
+    the long tail of protocol notifications.
+    """
+    lane = _thread_id(params)
+    if lane is None:
+        return []
+    turn = _str(params, "turnId")
+    match method:
+        case "turn/started":
+            return [TurnStarted(lane, turn)]
+        case "turn/completed":
+            return [TurnCompleted(lane, turn)]
+        case "turn/failed":
+            return [TurnFailed(lane, turn, _str(params, "message"))]
+        case "turn/diff/updated":
+            return [DiffUpdated(lane, turn)]
+        case "item/completed":
+            return [ItemCompleted(lane, _str(params, "itemId"))]
+        case "thread/tokenUsage/updated":
+            return [TokenUsageUpdated(lane)]
+        case "thread/goal/updated":
+            return [GoalUpdated(lane)]
+        case "thread/goal/cleared":
+            return [GoalCleared(lane)]
+        case "thread/compacted":
+            return [ThreadCompacted(lane)]
+        case "thread/status/changed":
+            flags = _active_flags(params)
+            events: list[LaneEvent] = [StatusChanged(lane, flags)]
+            if not flags:
+                events.append(LaneIdle(lane))
+            return events
+        case _:
+            return []
+
+
+def project_server_request(
+    request_id: int, method: str, params: dict[str, object]
+) -> LaneEvent | None:
+    """Project a server->client request (approvals) into a LaneEvent, or None."""
+    lane = _thread_id(params)
+    if lane is None:
+        return None
+    item = _str(params, "itemId")
+    turn = _str(params, "turnId")
+    match method:
+        case "item/commandExecution/requestApproval":
+            return ApprovalRequested(lane, request_id, "command", item, turn)
+        case "item/fileChange/requestApproval":
+            return ApprovalRequested(lane, request_id, "file_change", item, turn)
+        case _:
+            return None
+
+
+def _active_flags(params: dict[str, object]) -> tuple[str, ...]:
+    status = params.get("status")
+    flags = status.get("activeFlags") if isinstance(status, dict) else params.get("activeFlags")
+    if isinstance(flags, list):
+        return tuple(f for f in flags if isinstance(f, str))
+    return ()