@demlik/tea 0.1.1 → 0.2.0

package/dist/do/index.d.ts

@@ -1,15 +1,15 @@
 import { Store, Runtime, BootingRuntime } from '../index.js';
-import { P as PendingEffectsRecorder, b as EffectOwed, a as EffectConfirmed } from '../durable-effects-2MDxDs45.js';
-export { D as DeliveryId, E as EffectLedgerEvent, O as OwedEffect, d as PendingEffectsLedger, c as applyEffectEvent, e as emptyLedger, f as foldLedger, i as isOwed, p as pendingEffectsLedger, s as survivingEffects } from '../durable-effects-2MDxDs45.js';
+import { P as PendingEffectsRecorder, b as EffectOwed, a as EffectConfirmed } from '../durable-effects-9LxFpmh3.js';
+export { D as DeliveryId, E as EffectLedgerEvent, O as OwedEffect, d as PendingEffectsLedger, c as applyEffectEvent, e as emptyLedger, f as foldLedger, i as isOwed, p as pendingEffectsLedger, s as survivingEffects } from '../durable-effects-9LxFpmh3.js';
 import { RetryPolicy, Rng } from '../retry-backoff/index.js';
-import { C as Cmd, S as Sub, M as Machine } from '../core-CymXZCeY.js';
-import { AgentTurn, AgentState, AgentMachineMsg, AgentEvent, AgentStatus } from '../agent/index.js';
+import { C as Cmd, S as Sub, M as Machine } from '../core-BmlJOvxM.js';
+import { AgentEvent, AgentTurn, AgentState, AgentMachineMsg, AgentStatus } from '../agent/index.js';
 import '../fan-out/index.js';
 import '../work-queue/index.js';
 import '../llm-call/index.js';
 import '../resilient-call/index.js';
 import '../cache/index.js';
-import '../types-N9LZbdnr.js';
+import '../types-BoUWgwSm.js';
 import '../circuit-breaker/index.js';
 import '../deadline/index.js';
 import '../protocol-B5YmJr0d.js';
@@ -117,6 +117,13 @@ interface NextStep<I> {
  * A `/step` response — a discriminated union on `done`:
  *   - `{ done: false, step }` — execute `step`, POST its result, ask again.
  *   - `{ done: true, output }` — the run is terminal; `output` is its result.
+ *
+ * This is the ORIGINAL 2-arm INLINE contract, kept byte-identical: a host that
+ * resolves each step inside the held request returns exactly these two shapes.
+ * The not-ready arm ({@link StepWorking}) is a SEPARATE, opt-in type reachable
+ * only through the defer-resume hook — see {@link DeferredStepResponse}. Keeping
+ * `StepResponse` a strict subset is what makes inline adopters unaffected: their
+ * `if (r.done) … else r.step` narrowing never sees a third member.
  */
 type StepResponse<I, O> = {
     readonly done: false;
@@ -125,6 +132,37 @@ type StepResponse<I, O> = {
     readonly done: true;
     readonly output: O;
 };
+/**
+ * The NOT-READY arm — the run is computing OUT-OF-BAND under a defer-resume host
+ * (Binclusive ADR 0035 / prod incident #1873: a non-blocking pull carrier must
+ * answer a pull with an explicit "computing, poll again" instead of holding the
+ * request across a multi-second step). The held `/step` request returns this
+ * IMMEDIATELY instead of inline-awaiting `engine.resume`; the hands re-poll
+ * (optionally after `retryAfterMs`) until the deferred compute lands in the
+ * durable checkpoint and a real {@link StepResponse} step/done arm is returned.
+ *
+ * It is a first-class discriminated member (`working: true`), NOT a hollow
+ * `{ done: false }` with an absent/stale `step` — the not-ready state is made
+ * representable so it can never be confused with a real pending step.
+ */
+interface StepWorking {
+    readonly done: false;
+    readonly working: true;
+    /**
+     * Advisory earliest re-poll delay as a hint to the hands (ms to wait before
+     * the next pull). Purely advisory — a host may omit it and the hands fall back
+     * to their own backoff curve.
+     */
+    readonly retryAfterMs?: number;
+}
+/**
+ * The 3-arm response a DEFER-RESUME host returns — the inline {@link StepResponse}
+ * arms PLUS {@link StepWorking}. A superset of `StepResponse`, so a 2-arm value is
+ * assignable to it (the widening is safe for existing transports); discriminate
+ * with `if (r.done)` for terminal, then `"working" in r` for the not-ready arm,
+ * else the step arm.
+ */
+type DeferredStepResponse<I, O> = StepResponse<I, O> | StepWorking;
 /**
  * Mint a fresh per-run capability token: 32 random bytes, hex-encoded. Uses the
  * Web Crypto `crypto.getRandomValues` available in the Workers runtime (and in
@@ -173,7 +211,8 @@ interface StepEngine<R, I, O> {
     /**
      * Settle the posted tool result into the run, then RESUME from the durable
      * checkpoint: dispatch the settle and run to DISPATCH-QUIESCENCE (e.g.
-     * `dispatchToIdle(runtime, settleMsg)`). Called at most once per distinct
+     * `await runtime.dispatch(settleMsg)` — dispatch drains the follow-up chain
+     * by default, #50). Called at most once per distinct
      * `callId` — `stepHost` dedupes re-POSTs via `idempotent-intake` BEFORE
      * calling this, so the side effect runs exactly once. On the first request
      * (`posted === null`) `stepHost` skips settle and calls {@link nextStep}
@@ -201,6 +240,51 @@ interface StepHostConfig {
      */
     readonly giveUpAfterMs?: number;
 }
+/**
+ * The DEFER-RESUME hook — the opt-in seam that drives `engine.resume` OUT of the
+ * held `/step` request. A non-blocking host (Binclusive audit carrier, ADR 0035)
+ * cannot inline-await a multi-second step inside the held request, so instead of
+ * `stepHost` calling `engine.resume` inline it hands the posted result to this
+ * hook to SETTLE-AND-ENQUEUE (record it durably, schedule the compute in a
+ * returning activation) and returns the {@link StepWorking} arm PROMPTLY. A later
+ * pull re-reads the durable next-step once {@link DeferResumeHook.settled} reports
+ * the enqueued compute has landed.
+ *
+ * Providing this hook is what flips `stepHost` from the 2-arm inline contract to
+ * the 3-arm deferred contract — see the `stepHost` overloads. Omit it and the
+ * host stays byte-identical inline.
+ */
+interface DeferResumeHook<R> {
+    /**
+     * SETTLE-AND-ENQUEUE the posted result to resume OUT of the held request:
+     * durably record it and schedule the compute (e.g. `ctx.storage.setAlarm` or a
+     * queue) so a returning activation runs `engine.resume`. MUST return promptly —
+     * it never awaits the step compute. Called at most once per distinct `callId`
+     * (`stepHost` dedupes re-POSTs through `idempotent-intake` first), so a re-POST
+     * of the same step does not re-enqueue.
+     */
+    enqueue(runId: string, posted: StepResult<R>): void | Promise<void>;
+    /**
+     * Has the enqueued resume for `callId` COMPLETED and been written to the
+     * durable checkpoint? `false` ⇒ the held request returns {@link StepWorking}
+     * (poll again); `true` ⇒ `stepHost` reads the next step / terminal output off
+     * the now-advanced checkpoint, exactly as the inline path does.
+     */
+    settled(runId: string, callId: string): boolean | Promise<boolean>;
+    /**
+     * Optional advisory re-poll delay (ms) surfaced on the {@link StepWorking} arm
+     * so the hands can back off to the host's expected step latency.
+     */
+    retryAfterMs?: number;
+}
+/**
+ * `StepHostConfig` with the defer-resume hook engaged — the presence of
+ * `deferResume` is the type-level switch that selects the 3-arm response (see the
+ * `stepHost` overloads). Extends the inline config, so the alarm tuning is shared.
+ */
+interface DeferStepHostConfig<R> extends StepHostConfig {
+    readonly deferResume: DeferResumeHook<R>;
+}
 /**
  * A structured `/step` outcome `stepHost` returns — the response body plus the
  * HTTP status the consumer's route should send. Kept transport-agnostic (no
@@ -215,6 +299,21 @@ type StepOutcome<I, O> = {
         readonly error: string;
     };
 };
+/**
+ * The `/step` outcome a DEFER-RESUME host returns — like {@link StepOutcome} but
+ * its 200 body is the 3-arm {@link DeferredStepResponse} (it can carry the
+ * not-ready arm). Returned only from the `deferResume` overload of `stepHost`;
+ * the inline overload keeps the narrower {@link StepOutcome}.
+ */
+type DeferredStepOutcome<I, O> = {
+    readonly status: 200;
+    readonly body: DeferredStepResponse<I, O>;
+} | {
+    readonly status: 401 | 404;
+    readonly body: {
+        readonly error: string;
+    };
+};
 /**
  * Build the `/step` handler for a DO that drives one or more runs over the pull
  * carrier. Returns `handle(request, now)` — call it from the DO's `/step`
@@ -232,11 +331,20 @@ type StepOutcome<I, O> = {
  * @param engine the run-specific operations
  * @param config alarm tuning
  */
+declare function stepHost<R, I, O>(ctx: StepCtx, engine: StepEngine<R, I, O>, config: DeferStepHostConfig<R>): {
+    handle(request: StepRequest<R>, now: number): Promise<DeferredStepOutcome<I, O>>;
+};
 declare function stepHost<R, I, O>(ctx: StepCtx, engine: StepEngine<R, I, O>, config?: StepHostConfig): {
     handle(request: StepRequest<R>, now: number): Promise<StepOutcome<I, O>>;
 };
-/** The `/step` transport the hands POST through (injected; faked in tests). */
-type StepTransport<R, I, O> = (request: StepRequest<R>) => Promise<StepResponse<I, O>>;
+/**
+ * The `/step` transport the hands POST through (injected; faked in tests).
+ * Returns the 3-arm {@link DeferredStepResponse} — a defer-resume host may answer
+ * with the not-ready arm, which {@link runStepLoop} re-polls. An inline host's
+ * 2-arm transport (`=> Promise<StepResponse>`) is assignable here (the narrower
+ * return widens), so existing inline adopters are unaffected.
+ */
+type StepTransport<R, I, O> = (request: StepRequest<R>) => Promise<DeferredStepResponse<I, O>>;
 /** Execute one tool call and produce its result (the consumer's hands). */
 type ExecuteStep<I, R> = (step: NextStep<I>) => Promise<R> | R;
 /** Tuning for {@link runStepLoop}. */
@@ -283,6 +391,11 @@ type StepLoopOutcome<O> = {
  *     not re-executed; its prior result is re-POSTed. Closes the "the host
  *     re-handed the same step after a duplicate settle" path (the host side is
  *     idempotent; the hands match it).
+ *   - **not-ready re-poll** — a {@link StepWorking} arm (a defer-resume host
+ *     computing the step out-of-band) is not a step: the loop re-POSTs the SAME
+ *     `posted` after a backoff (honoring the host's advisory `retryAfterMs`),
+ *     until a real step / done arrives. Bounded only by the absolute deadline —
+ *     an inline host never returns this arm, so its drive is unchanged.
  */
 declare function runStepLoop<R, I, O>(token: string, runId: string, transport: StepTransport<R, I, O>, execute: ExecuteStep<I, R>, config: RunStepLoopConfig): Promise<StepLoopOutcome<O>>;
 
@@ -827,35 +940,253 @@ declare function rebuildProjection<Model, Msg extends {
 }[]): ProjectionRunner<Model, Msg, View>;
 
 /**
- * @demlik/tea/do — the minimum-viable Durable-Object HOST for a `@demlik/tea`
- * `createAgent` runtime.
+ * The runtime→SSE plumbing — the hub, its projection expression, and the
+ * semantic-event adapter. See `./host` for the transport-model rationale.
+ */
+
+/**
+ * A set of SSE sinks plus the plumbing to fan an event out to all of them and
+ * to open a `text/event-stream` Response wired to a fresh sink.
+ *
+ * The consumer:
+ *   1. holds one `SseHub<E>` per DO,
+ *   2. calls `hub.emit(event)` from its Msg→event mapping (driven off
+ *      `runtime.observe`), and
+ *   3. returns `hub.open()` from the `/sse` route.
+ *
+ * `register(sink)` exists for tests: subscribe a sink directly and observe the
+ * exact event sequence a live client would receive (a live `text/event-stream`
+ * fights vitest-pool-workers teardown). Deletes the consumer's `sseSinks` set,
+ * `openSse`, `emitSse`, and `onSseEvent`.
+ */
+interface SseHub<E> {
+    emit(event: E): void;
+    open(): Response;
+    register(sink: (event: E) => void): () => void;
+}
+/** Build an SSE hub for event type `E` (the consumer's domain event shape). */
+declare function sseHub<E>(): SseHub<E>;
+/**
+ * Express an {@link SseHub} as a {@link Projection}. The projection's view is
+ * the latest emitted SSE event (or `null` before the first); `apply` maps each
+ * write-model update to an event via `toEvent` and emits it through `hub.emit`,
+ * so the SSE stream is driven by the SAME hub `sseHub()` returns — no API
+ * change for the `/sse` route (`hub.open()`) or any existing caller.
+ *
+ *   - `toEvent(msg, model)` returns the SSE event for this update, or `null` to
+ *     skip it (the view stays, nothing is emitted).
+ *   - `name`/`key` default to `"sse"`/`"main"`; override for a second SSE view.
+ *
+ * @example
+ *   const hub = sseHub<MyEvent>();
+ *   const registry = projectionRegistry<MyState, MyMsg>();
+ *   registry.register(sseProjection(hub, (msg) =>
+ *     msg?.type === "turn_done" ? { kind: "turn", ... } : null,
+ *   ));
+ *   driveProjections(registry, runtime); // SSE is now one projection
+ *   // /sse route unchanged:
+ *   return hub.open();
+ */
+declare function sseProjection<Model, Msg extends {
+    type: string;
+}, E>(hub: SseHub<E>, toEvent: (msg: Msg | null, model: Model) => E | null, id?: {
+    name?: string;
+    key?: string;
+}): Projection<Model, Msg, E | null>;
+/**
+ * Wire an {@link SseHub} to a runtime's semantic {@link AgentEvent} stream (#47).
+ * For each event `type` the runtime can emit, subscribes via `runtime.on` and
+ * pushes `toFrame(event)` at the hub (returning `null` skips that event). The
+ * runtime MUST have been built with `run(machine, { events: agentEvents() })`,
+ * which is what makes `on` deliver the `AgentEvent`s. Returns a cleanup that
+ * detaches every subscription.
+ *
+ * This is the runtime→SSE adapter expressed over the typed event channel: no
+ * `observe` firehose, no private-Msg coupling. `hub.open()` and every existing
+ * `sseHub` caller are unchanged — only the SOURCE of `hub.emit` moves from a
+ * hand-rolled Msg switch to `on`.
  *
- * `doStore` (in `./index`) is the durability half. This file is the rest of the
- * boilerplate a DO consumer hand-rolls every time it drives a tea agent over a
- * remote transport: the deferred-tool gateway, auto-boot on rehydrate, the
- * command-runner WS accept, the runtime→SSE plumbing, and a clean read of a
- * run's terminal output. Each export below names exactly the hand-rolled piece
- * it deletes from the consumer.
+ * @example
+ *   const hub = sseHub<MyFrame>();
+ *   const runtime = await run(machine, { ctx, events: agentEvents() }).ready;
+ *   const off = sseFromAgentEvents(runtime, hub, (e) =>
+ *     e.type === "RunDone" ? { kind: "done", output: e.output } : null,
+ *   );
+ *   // /sse route unchanged:
+ *   return hub.open();
+ */
+declare function sseFromAgentEvents<R, Frame>(runtime: {
+    on<K extends AgentEvent<R>["type"]>(type: K, handler: (event: Extract<AgentEvent<R>, {
+        type: K;
+    }>) => void): () => void;
+}, hub: SseHub<Frame>, toFrame: (event: AgentEvent<R>) => Frame | null): () => void;
+
+/**
+ * `createAgentHost` — the runtime+events+autoBoot assembly + the test seam,
+ * ONCE (issue #53). The facade over the concern modules: the deferred gateway
+ * (`./deferred-gateway`), the WS carrier (`./command-socket`), the SSE plumbing
+ * (`./sse`), and the cold-wake resume (`./resume`). See `./host` for the
+ * transport-model rationale.
+ */
+
+/**
+ * What the consumer supplies to {@link createAgentHost} — the domain mappings,
+ * nothing of the wiring. `Stage`/`P`/`O`/`R` are the agent slice's type
+ * parameters (the consumer names them once); `Frame` is its SSE event shape.
+ * `C`/`U`/`Ctx` are the machine's own Cmd/Sub/Ctx — inferred from
+ * `buildMachine` at the `createAgentHost` call site (never name them by hand;
+ * an erased `any` here cost consumers all checking on this layer — #278).
+ */
+interface AgentHostConfig<Stage, P extends string, O extends Record<P, AgentTurn>, R, Frame, C extends Cmd = Cmd, U extends Sub = Sub, Ctx = unknown> {
+    /**
+     * Build the wired agent machine. Called once per host build (per activation),
+     * AFTER the previous runtime — if any — was torn down. The consumer wires its
+     * per-tool interpret here (`agent.toMachine({ toolInterpret })`).
+     */
+    readonly buildMachine: () => Machine<AgentState<Stage, P, O, R>, AgentMachineMsg<P, O, R>, C, U, Ctx>;
+    /** The durable `Store` for the agent slice (typically `doStore(storage, parse)`). */
+    readonly store: Store<AgentState<Stage, P, O, R>>;
+    /** The Ctx the machine threads to its interpret cells — checked against `buildMachine`'s. */
+    readonly ctx: Ctx;
+    /**
+     * The run-terminality predicate (#46) — what makes `result()` first-class.
+     * Defaults to the agent's own terminal phases (`done` / `failed`).
+     */
+    readonly terminal?: (state: AgentState<Stage, P, O, R>) => boolean;
+    /**
+     * Map one semantic {@link AgentEvent} to the consumer's SSE frame, or `null`
+     * to skip it. This is the ONLY place the consumer touches the SSE seam — the
+     * host owns the subscription wiring (`sseFromAgentEvents`) and the hub.
+     */
+    readonly toSseFrame: (event: AgentEvent<R>) => Frame | null;
+    /** Clock injected for `autoBoot` (the host's only boot clock read). */
+    readonly now?: () => number;
+}
+/**
+ * The assembled host: the runtime cell + the SSE hub + the framework test seam,
+ * owned ONCE. A DO holds one `AgentHost` and delegates to it; its own surface
+ * shrinks to the domain (the gateway, the WS bridge, the command-send mapping).
  *
- * ## The transport model: ONE Sub type, gateway-bridged I/O
+ * @typeParam Stage Pipeline stage type.
+ * @typeParam P     Brain-call purposes.
+ * @typeParam O     Per-purpose outputs (bound to {@link AgentTurn}).
+ * @typeParam R     Tool result type.
+ * @typeParam Frame The consumer's SSE event shape.
+ */
+interface AgentHost<Stage, P extends string, O extends Record<P, AgentTurn>, R, Frame> {
+    /**
+     * Get (or build) the booted runtime. Build-once-boot-once: the first call
+     * builds the machine, wires SSE off the semantic event stream, awaits the boot
+     * gate, runs the `autoBoot` re-fire for a rehydrated suspended run, and caches
+     * the booted `Runtime`; subsequent calls return the cached handle. The single
+     * assembly every consumer used to hand-roll in `getRuntime()`.
+     */
+    runtime(): Promise<Runtime<AgentState<Stage, P, O, R>, AgentMachineMsg<P, O, R>, AgentEvent<R>>>;
+    /**
+     * The agent's lifecycle status (#49) — the ONE typed channel a consumer reads
+     * instead of re-deriving `run.phase` / `awaiting` by hand. Ensures the runtime
+     * is built + boot-reconciled first. Replaces the per-consumer `isSuspended` /
+     * `runPhase` test methods (read `status().kind`).
+     */
+    status(): Promise<AgentStatus<Stage>>;
+    /**
+     * The run's terminal State (#46), or `undefined` while in flight. Read the
+     * run's product off it (e.g. `result()?.output`). Replaces the per-consumer
+     * `verdict` plumbing's source. Ensures the runtime is built first.
+     */
+    result(): Promise<AgentState<Stage, P, O, R> | undefined>;
+    /**
+     * The SSE hub — the route (`host.sse.open()`) AND the test seam
+     * (`host.sse.register(sink)`). The host drives `hub.emit` off the semantic
+     * event stream; the consumer never touches it except to open / register.
+     */
+    readonly sse: SseHub<Frame>;
+    /**
+     * Tear down the cached runtime (drain its tail via `stop()`, drop the handle)
+     * so the next `runtime()` rebuilds from storage. The framework `settle` test
+     * seam, owned once.
+     */
+    reset(): Promise<void>;
+}
+/**
+ * Build an {@link AgentHost} from the consumer's domain mappings. Owns the
+ * runtime+events+autoBoot assembly and the framework test seam — the wiring
+ * issue #53 had every consumer re-write.
  *
- * `createAgent().toMachine()` fixes the machine's Sub type to `DeadlineSub` —
- * the agent owns the retry + watchdog timers and nothing else. That is the
- * WHOLE Sub model for a DO-hosted agent, and it is coherent because the
- * transport deliberately does NOT live in the Sub system:
+ * @example
+ *   const host = createAgentHost<Stage, Purpose, Outputs, ClientResult, SseEvent>({
+ *     buildMachine: () => agent.toMachine<Ctx>({ toolInterpret }),
+ *     store: doStore(storage, parse),
+ *     ctx,
+ *     toSseFrame: (e) =>
+ *       e.type === "ToolSettled" ? { kind: "result", ...} :
+ *       e.type === "TurnSettled" && e.turn.toolCalls.length === 0
+ *         ? { kind: "verdict", verdict: e.turn.content } :
+ *       e.type === "RunDone" ? { kind: "phase", phase: "done" } : null,
+ *   });
+ *   // route:   return host.sse.open();
+ *   // start:   await (await host.runtime()).dispatch({ type: "agent_start", ... });
+ *   // test:    (await host.status()).kind === "suspended"
+ */
+declare function createAgentHost<Stage, P extends string, O extends Record<P, AgentTurn>, R, Frame, C extends Cmd = Cmd, U extends Sub = Sub, Ctx = unknown>(config: AgentHostConfig<Stage, P, O, R, Frame, C, U, Ctx>): AgentHost<Stage, P, O, R, Frame>;
+
+/**
+ * The command-runner WebSocket host + broadcast — the WS half of the
+ * `@demlik/tea/do` transport, in both the resident (`acceptCommandSocket`) and
+ * hibernation-aware (`acceptDurableCommandSocket`) forms. See `./host` for the
+ * transport-model rationale (ONE Sub type, gateway-bridged I/O).
+ */
+/**
+ * Accept a command-runner WebSocket on the DO's `fetch`. Adds the server end to
+ * `clients`, wires `message` → `onFrame(data)` (string frames only) and
+ * `close` → deregister, and returns the 101 upgrade Response.
  *
- *   - Inbound WebSocket frames are bridged straight into `gateway.settle(...)`
- *     from the DO's `webSocketMessage` lifecycle method — a direct dispatch,
- *     not a Sub.
- *   - The per-tool deadline is a `setTimeout` inside the gateway — a timer, not
- *     a DO alarm.
+ * The consumer's `onFrame` parses the frame and calls `gateway.settle(callId,
+ * result)` — the inbound bridge. Deletes the consumer's `acceptClient` method.
+ */
+declare function acceptCommandSocket(clients: Set<WebSocket>, onFrame: (data: string) => void): Response;
+/**
+ * Broadcast a JSON frame to every connected command-runner socket. A dead
+ * socket is skipped (dropped on its own `close` event). Lifts the consumer's
+ * fan-out loop in `sendCommand`.
+ */
+declare function broadcast(clients: Set<WebSocket>, frame: unknown): void;
+/**
+ * The slice of `DurableObjectState` the durable carrier needs: the Hibernation
+ * API accept + the registry of hibernatable sockets. A real `DurableObjectState`
+ * satisfies this structurally; a test supplies a fake (no live Workers runtime
+ * needed to exercise the accept/registry seam).
+ */
+interface HibernatableCtx {
+    acceptWebSocket(ws: WebSocket): void;
+    getWebSockets(): WebSocket[];
+}
+/**
+ * Accept a command-runner WebSocket using the Cloudflare **Hibernation API** so
+ * the socket survives DO eviction. Unlike {@link acceptCommandSocket}, this does
+ * NOT attach an isolate-resident `message` listener (that listener is what dies
+ * on eviction) — instead `ctx.acceptWebSocket(server)` hands the socket to the
+ * runtime, which re-creates the DO and calls its `webSocketMessage(ws, data)`
+ * lifecycle method on the next inbound frame. The consumer routes that method to
+ * its `onFrame` (which calls `carrier.settle(callId, result)`).
  *
- * The deferred-tool gateway owns each tool round-trip as a Promise the interpret
- * cell awaits; the transport bridges results into `dispatch` from outside the
- * Sub system. The agent's Sub type stays exactly `DeadlineSub` — there is no
- * competing DO-native Sub variant to union in, and the host needs none. This is
- * the single transport model for `@demlik/tea/do` (#52); see
- * `.patterns/tea/durable-actors.md` for the host-layer north star.
+ * Returns the 101 upgrade Response. There is no `clients` registry to keep — the
+ * live sockets are `ctx.getWebSockets()` (see {@link broadcastHibernatable}),
+ * which the runtime repopulates after a wake.
+ */
+declare function acceptDurableCommandSocket(ctx: HibernatableCtx): Response;
+/**
+ * Broadcast a JSON frame to every hibernatable command-runner socket. The live
+ * set is read from `ctx.getWebSockets()` (the runtime repopulates it after a
+ * wake), NOT a resident `Set<WebSocket>` — so it is correct immediately after an
+ * eviction, before any other lifecycle method has run. A dead socket is skipped.
+ */
+declare function broadcastHibernatable(ctx: HibernatableCtx, frame: unknown): void;
+
+/**
+ * The deferred-tool gateway + its durable wrappers — the Promise-owning half of
+ * the `@demlik/tea/do` transport. See `./host` for the transport-model
+ * rationale (ONE Sub type, gateway-bridged I/O).
  */
 
 /**
@@ -931,7 +1262,64 @@ declare function durableDeferredGateway<R>(inner: DeferredGateway<R>, recorder:
     recordConfirmed(callId: string, event: EffectConfirmed): void;
 }): DurableDeferredGateway<R>;
 /**
- * The typed cold-wake resume port `bootResume` fires through — the agent's
+ * The durable command carrier — a {@link DurableDeferredGateway} whose every
+ * tool round-trip is also a durable owed effect.
+ *
+ * A consumer's tool interpret cell still calls `carrier.await(callId, send,
+ * deadlineMs)` and awaits the Promise (mapping Ok/Err to `agent_tool_ok` /
+ * `agent_tool_err`) — the SAME fast path as the volatile gateway. The addition
+ * is durability: `await` hands the consumer an `effect_owed` event (via
+ * `recordOwed`) to PERSIST before the send, and `settle`/`fail` hand it an
+ * `effect_confirmed` (via `recordConfirmed`) to persist. On the next activation
+ * the consumer reads its persisted ledger events back and calls
+ * `reissueSurvivingEffects` (see `./resume`) to re-fire the survivors.
+ *
+ * It extends `DurableDeferredGateway` (so it is a drop-in for the gateway the
+ * interpret cell already awaits) and exposes the underlying `recorder` for a
+ * host that wants to read `surviving()` directly.
+ */
+interface DurableCommandCarrier<R> extends DeferredGateway<R> {
+    /** The ledger recorder backing this carrier (for `surviving()` introspection). */
+    readonly recorder: PendingEffectsRecorder<{
+        callId: string;
+    }>;
+}
+/**
+ * Build a durable command carrier over a (volatile) `DeferredGateway<R>` and a
+ * `PendingEffectsRecorder`. Thin assembly over {@link durableDeferredGateway}:
+ * it names the #91 piece — "the command carrier whose round-trips survive
+ * eviction" — and keeps the recorder reachable for the activation-time re-emit.
+ *
+ *   - `inner` — the volatile gateway whose in-isolate Promise the interpret cell
+ *     awaits (typically `deferredGateway<R>()`).
+ *   - `recorder` — the durable-effects recorder (typically
+ *     `pendingEffectsLedger({ events, lastId })` rehydrated from the persisted
+ *     log on a wake, or a fresh `pendingEffectsLedger()` on a cold boot).
+ *   - `hooks.recordOwed` / `hooks.recordConfirmed` — the persist callbacks the
+ *     consumer points at its event log (so the ledger survives eviction).
+ *
+ * The carrier never persists anything itself (it does not own the consumer's
+ * log) — it hands the consumer the events, faithful to "persist the intent
+ * before deliver".
+ */
+declare function durableCommandCarrier<R>(inner: DeferredGateway<R>, recorder: PendingEffectsRecorder<{
+    callId: string;
+}>, hooks: {
+    recordOwed(callId: string, event: EffectOwed<{
+        callId: string;
+    }>): void;
+    recordConfirmed(callId: string, event: EffectConfirmed): void;
+}): DurableCommandCarrier<R>;
+
+/**
+ * Cold-wake resume — the boot/hibernation re-fire path: the generalized
+ * `bootResume` port, its agent specialization `autoBoot`, and the wake-time
+ * re-emit of surviving tool round-trips. See `./host` for the transport-model
+ * rationale.
+ */
+
+/**
+ * The typed cold-wake resume port `bootResume` fires through — the agent's
  * `AgentBootPort` (issue #60) generalized to any DO-hosted machine (issue #231).
  *
  * - `isResumable(state)` — true iff the rehydrated State is mid-loop and needs a
@@ -987,101 +1375,6 @@ declare function agentIsResumable<Stage, P extends string, O extends Record<P, u
 declare function autoBoot<Stage, P extends string, O extends Record<P, unknown>, R, E extends {
     type: string;
 } = never>(booting: BootingRuntime<AgentState<Stage, P, O, R>, AgentMachineMsg<P, O, R>, E>, now?: () => number): Promise<void>;
-/**
- * Accept a command-runner WebSocket on the DO's `fetch`. Adds the server end to
- * `clients`, wires `message` → `onFrame(data)` (string frames only) and
- * `close` → deregister, and returns the 101 upgrade Response.
- *
- * The consumer's `onFrame` parses the frame and calls `gateway.settle(callId,
- * result)` — the inbound bridge. Deletes the consumer's `acceptClient` method.
- */
-declare function acceptCommandSocket(clients: Set<WebSocket>, onFrame: (data: string) => void): Response;
-/**
- * Broadcast a JSON frame to every connected command-runner socket. A dead
- * socket is skipped (dropped on its own `close` event). Lifts the consumer's
- * fan-out loop in `sendCommand`.
- */
-declare function broadcast(clients: Set<WebSocket>, frame: unknown): void;
-/**
- * The slice of `DurableObjectState` the durable carrier needs: the Hibernation
- * API accept + the registry of hibernatable sockets. A real `DurableObjectState`
- * satisfies this structurally; a test supplies a fake (no live Workers runtime
- * needed to exercise the accept/registry seam).
- */
-interface HibernatableCtx {
-    acceptWebSocket(ws: WebSocket): void;
-    getWebSockets(): WebSocket[];
-}
-/**
- * Accept a command-runner WebSocket using the Cloudflare **Hibernation API** so
- * the socket survives DO eviction. Unlike {@link acceptCommandSocket}, this does
- * NOT attach an isolate-resident `message` listener (that listener is what dies
- * on eviction) — instead `ctx.acceptWebSocket(server)` hands the socket to the
- * runtime, which re-creates the DO and calls its `webSocketMessage(ws, data)`
- * lifecycle method on the next inbound frame. The consumer routes that method to
- * its `onFrame` (which calls `carrier.settle(callId, result)`).
- *
- * Returns the 101 upgrade Response. There is no `clients` registry to keep — the
- * live sockets are `ctx.getWebSockets()` (see {@link broadcastHibernatable}),
- * which the runtime repopulates after a wake.
- */
-declare function acceptDurableCommandSocket(ctx: HibernatableCtx): Response;
-/**
- * Broadcast a JSON frame to every hibernatable command-runner socket. The live
- * set is read from `ctx.getWebSockets()` (the runtime repopulates it after a
- * wake), NOT a resident `Set<WebSocket>` — so it is correct immediately after an
- * eviction, before any other lifecycle method has run. A dead socket is skipped.
- */
-declare function broadcastHibernatable(ctx: HibernatableCtx, frame: unknown): void;
-/**
- * The durable command carrier — a {@link DurableDeferredGateway} whose every
- * tool round-trip is also a durable owed effect.
- *
- * A consumer's tool interpret cell still calls `carrier.await(callId, send,
- * deadlineMs)` and awaits the Promise (mapping Ok/Err to `agent_tool_ok` /
- * `agent_tool_err`) — the SAME fast path as the volatile gateway. The addition
- * is durability: `await` hands the consumer an `effect_owed` event (via
- * `recordOwed`) to PERSIST before the send, and `settle`/`fail` hand it an
- * `effect_confirmed` (via `recordConfirmed`) to persist. On the next activation
- * the consumer reads its persisted ledger events back and calls
- * {@link reissueSurvivingEffects} to re-fire the survivors.
- *
- * It extends `DurableDeferredGateway` (so it is a drop-in for the gateway the
- * interpret cell already awaits) and exposes the underlying `recorder` for a
- * host that wants to read `surviving()` directly.
- */
-interface DurableCommandCarrier<R> extends DeferredGateway<R> {
-    /** The ledger recorder backing this carrier (for `surviving()` introspection). */
-    readonly recorder: PendingEffectsRecorder<{
-        callId: string;
-    }>;
-}
-/**
- * Build a durable command carrier over a (volatile) `DeferredGateway<R>` and a
- * `PendingEffectsRecorder`. Thin assembly over {@link durableDeferredGateway}:
- * it names the #91 piece — "the command carrier whose round-trips survive
- * eviction" — and keeps the recorder reachable for the activation-time re-emit.
- *
- *   - `inner` — the volatile gateway whose in-isolate Promise the interpret cell
- *     awaits (typically `deferredGateway<R>()`).
- *   - `recorder` — the durable-effects recorder (typically
- *     `pendingEffectsLedger({ events, lastId })` rehydrated from the persisted
- *     log on a wake, or a fresh `pendingEffectsLedger()` on a cold boot).
- *   - `hooks.recordOwed` / `hooks.recordConfirmed` — the persist callbacks the
- *     consumer points at its event log (so the ledger survives eviction).
- *
- * The carrier never persists anything itself (it does not own the consumer's
- * log) — it hands the consumer the events, faithful to "persist the intent
- * before deliver".
- */
-declare function durableCommandCarrier<R>(inner: DeferredGateway<R>, recorder: PendingEffectsRecorder<{
-    callId: string;
-}>, hooks: {
-    recordOwed(callId: string, event: EffectOwed<{
-        callId: string;
-    }>): void;
-    recordConfirmed(callId: string, event: EffectConfirmed): void;
-}): DurableCommandCarrier<R>;
 /**
  * RE-EMIT ON ACTIVATION (the #91 wake path). Given a durable carrier whose
  * recorder was rehydrated from the persisted ledger events (e.g.
@@ -1111,192 +1404,6 @@ declare function durableCommandCarrier<R>(inner: DeferredGateway<R>, recorder: P
  * they restore a suspended run's full in-flight state after a wake.
  */
 declare function reissueSurvivingEffects<R>(carrier: DurableCommandCarrier<R>, reissue: (callId: string) => void): readonly string[];
-/**
- * A set of SSE sinks plus the plumbing to fan an event out to all of them and
- * to open a `text/event-stream` Response wired to a fresh sink.
- *
- * The consumer:
- *   1. holds one `SseHub<E>` per DO,
- *   2. calls `hub.emit(event)` from its Msg→event mapping (driven off
- *      `runtime.observe`), and
- *   3. returns `hub.open()` from the `/sse` route.
- *
- * `register(sink)` exists for tests: subscribe a sink directly and observe the
- * exact event sequence a live client would receive (a live `text/event-stream`
- * fights vitest-pool-workers teardown). Deletes the consumer's `sseSinks` set,
- * `openSse`, `emitSse`, and `onSseEvent`.
- */
-interface SseHub<E> {
-    emit(event: E): void;
-    open(): Response;
-    register(sink: (event: E) => void): () => void;
-}
-/** Build an SSE hub for event type `E` (the consumer's domain event shape). */
-declare function sseHub<E>(): SseHub<E>;
-/**
- * Express an {@link SseHub} as a {@link Projection}. The projection's view is
- * the latest emitted SSE event (or `null` before the first); `apply` maps each
- * write-model update to an event via `toEvent` and emits it through `hub.emit`,
- * so the SSE stream is driven by the SAME hub `sseHub()` returns — no API
- * change for the `/sse` route (`hub.open()`) or any existing caller.
- *
- *   - `toEvent(msg, model)` returns the SSE event for this update, or `null` to
- *     skip it (the view stays, nothing is emitted).
- *   - `name`/`key` default to `"sse"`/`"main"`; override for a second SSE view.
- *
- * @example
- *   const hub = sseHub<MyEvent>();
- *   const registry = projectionRegistry<MyState, MyMsg>();
- *   registry.register(sseProjection(hub, (msg) =>
- *     msg?.type === "turn_done" ? { kind: "turn", ... } : null,
- *   ));
- *   driveProjections(registry, runtime); // SSE is now one projection
- *   // /sse route unchanged:
- *   return hub.open();
- */
-declare function sseProjection<Model, Msg extends {
-    type: string;
-}, E>(hub: SseHub<E>, toEvent: (msg: Msg | null, model: Model) => E | null, id?: {
-    name?: string;
-    key?: string;
-}): Projection<Model, Msg, E | null>;
-/**
- * Wire an {@link SseHub} to a runtime's semantic {@link AgentEvent} stream (#47).
- * For each event `type` the runtime can emit, subscribes via `runtime.on` and
- * pushes `toFrame(event)` at the hub (returning `null` skips that event). The
- * runtime MUST have been built with `run(machine, { events: agentEvents() })`,
- * which is what makes `on` deliver the `AgentEvent`s. Returns a cleanup that
- * detaches every subscription.
- *
- * This is the runtime→SSE adapter expressed over the typed event channel: no
- * `observe` firehose, no private-Msg coupling. `hub.open()` and every existing
- * `sseHub` caller are unchanged — only the SOURCE of `hub.emit` moves from a
- * hand-rolled Msg switch to `on`.
- *
- * @example
- *   const hub = sseHub<MyFrame>();
- *   const runtime = await run(machine, { ctx, events: agentEvents() }).ready;
- *   const off = sseFromAgentEvents(runtime, hub, (e) =>
- *     e.type === "RunDone" ? { kind: "done", output: e.output } : null,
- *   );
- *   // /sse route unchanged:
- *   return hub.open();
- */
-declare function sseFromAgentEvents<R, Frame>(runtime: {
-    on<K extends AgentEvent<R>["type"]>(type: K, handler: (event: Extract<AgentEvent<R>, {
-        type: K;
-    }>) => void): () => void;
-}, hub: SseHub<Frame>, toFrame: (event: AgentEvent<R>) => Frame | null): () => void;
-/**
- * Dispatch `msg` and resolve only once the runtime has drained every follow-up
- * Msg the transition (transitively) enqueued — run-to-quiescence. Sugar over
- * `await runtime.dispatch(msg); await runtime.idle();`.
- *
- * Replaces the consumer's / test's `until(() => cond)` poll after a `dispatch`
- * for the common "dispatch, then let the loop settle" case. (A poll is still
- * the right tool when waiting on an EXTERNAL event — e.g. a WS reply — that the
- * runtime cannot enqueue itself.)
- */
-declare function dispatchToIdle<M extends {
-    type: string;
-}>(runtime: Runtime<unknown, M>, msg: M): Promise<void>;
-/**
- * What the consumer supplies to {@link createAgentHost} — the domain mappings,
- * nothing of the wiring. `Stage`/`P`/`O`/`R` are the agent slice's type
- * parameters (the consumer names them once); `Frame` is its SSE event shape.
- */
-interface AgentHostConfig<Stage, P extends string, O extends Record<P, AgentTurn>, R, Frame> {
-    /**
-     * Build the wired agent machine. Called once per host build (per activation),
-     * AFTER the previous runtime — if any — was torn down. The consumer wires its
-     * per-tool interpret here (`agent.toMachine({ toolInterpret })`).
-     */
-    readonly buildMachine: () => Machine<AgentState<Stage, P, O, R>, AgentMachineMsg<P, O, R>, any, any, any>;
-    /** The durable `Store` for the agent slice (typically `doStore(storage, parse)`). */
-    readonly store: Store<AgentState<Stage, P, O, R>>;
-    /** The Ctx the machine threads to its interpret cells. */
-    readonly ctx: unknown;
-    /**
-     * The run-terminality predicate (#46) — what makes `result()` first-class.
-     * Defaults to the agent's own terminal phases (`done` / `failed`).
-     */
-    readonly terminal?: (state: AgentState<Stage, P, O, R>) => boolean;
-    /**
-     * Map one semantic {@link AgentEvent} to the consumer's SSE frame, or `null`
-     * to skip it. This is the ONLY place the consumer touches the SSE seam — the
-     * host owns the subscription wiring (`sseFromAgentEvents`) and the hub.
-     */
-    readonly toSseFrame: (event: AgentEvent<R>) => Frame | null;
-    /** Clock injected for `autoBoot` (the host's only boot clock read). */
-    readonly now?: () => number;
-}
-/**
- * The assembled host: the runtime cell + the SSE hub + the framework test seam,
- * owned ONCE. A DO holds one `AgentHost` and delegates to it; its own surface
- * shrinks to the domain (the gateway, the WS bridge, the command-send mapping).
- *
- * @typeParam Stage Pipeline stage type.
- * @typeParam P     Brain-call purposes.
- * @typeParam O     Per-purpose outputs (bound to {@link AgentTurn}).
- * @typeParam R     Tool result type.
- * @typeParam Frame The consumer's SSE event shape.
- */
-interface AgentHost<Stage, P extends string, O extends Record<P, AgentTurn>, R, Frame> {
-    /**
-     * Get (or build) the booted runtime. Build-once-boot-once: the first call
-     * builds the machine, wires SSE off the semantic event stream, awaits the boot
-     * gate, runs the `autoBoot` re-fire for a rehydrated suspended run, and caches
-     * the booted `Runtime`; subsequent calls return the cached handle. The single
-     * assembly every consumer used to hand-roll in `getRuntime()`.
-     */
-    runtime(): Promise<Runtime<AgentState<Stage, P, O, R>, AgentMachineMsg<P, O, R>, AgentEvent<R>>>;
-    /**
-     * The agent's lifecycle status (#49) — the ONE typed channel a consumer reads
-     * instead of re-deriving `run.phase` / `awaiting` by hand. Ensures the runtime
-     * is built + boot-reconciled first. Replaces the per-consumer `isSuspended` /
-     * `runPhase` test methods (read `status().kind`).
-     */
-    status(): Promise<AgentStatus<Stage>>;
-    /**
-     * The run's terminal State (#46), or `undefined` while in flight. Read the
-     * run's product off it (e.g. `result()?.output`). Replaces the per-consumer
-     * `verdict` plumbing's source. Ensures the runtime is built first.
-     */
-    result(): Promise<AgentState<Stage, P, O, R> | undefined>;
-    /**
-     * The SSE hub — the route (`host.sse.open()`) AND the test seam
-     * (`host.sse.register(sink)`). The host drives `hub.emit` off the semantic
-     * event stream; the consumer never touches it except to open / register.
-     */
-    readonly sse: SseHub<Frame>;
-    /**
-     * Tear down the cached runtime (drain its tail via `stop()`, drop the handle)
-     * so the next `runtime()` rebuilds from storage. The framework `settle` test
-     * seam, owned once.
-     */
-    reset(): Promise<void>;
-}
-/**
- * Build an {@link AgentHost} from the consumer's domain mappings. Owns the
- * runtime+events+autoBoot assembly and the framework test seam — the wiring
- * issue #53 had every consumer re-write.
- *
- * @example
- *   const host = createAgentHost<Stage, Purpose, Outputs, ClientResult, SseEvent>({
- *     buildMachine: () => agent.toMachine<Ctx>({ toolInterpret }),
- *     store: doStore(storage, parse),
- *     ctx,
- *     toSseFrame: (e) =>
- *       e.type === "ToolSettled" ? { kind: "result", ...} :
- *       e.type === "TurnSettled" && e.turn.toolCalls.length === 0
- *         ? { kind: "verdict", verdict: e.turn.content } :
- *       e.type === "RunDone" ? { kind: "phase", phase: "done" } : null,
- *   });
- *   // route:   return host.sse.open();
- *   // start:   await (await host.runtime()).dispatch({ type: "agent_start", ... });
- *   // test:    (await host.status()).kind === "suspended"
- */
-declare function createAgentHost<Stage, P extends string, O extends Record<P, AgentTurn>, R, Frame>(config: AgentHostConfig<Stage, P, O, R, Frame>): AgentHost<Stage, P, O, R, Frame>;
 
 /**
  * @demlik/tea/do — the idempotent-effect brick (the receiver/effect-side dedup).
@@ -1772,4 +1879,4 @@ interface DoStoreOptions<S> {
  */
 declare function doStore<S>(storage: DurableObjectStorage, parse: (raw: unknown) => S | null, keyOrOptions?: string | DoStoreOptions<S>): Store<S>;
 
-export { type AgentHost, type AgentHostConfig, type AlarmStorage, type AppliedEffects, type AppliedEffectsEvent, type AppliedEffectsGuard, type AttachableSocket, type BroadcastOptions, type BroadcastReport, type DeferredGateway, type DoStoreOptions, type DurableCommandCarrier, type DurableTimer, type DurableTimerConfig, type EffectApplied, EffectConfirmed, type EffectForgotten, type EffectKey, EffectOwed, type EventLogRange, type EventSourcedOptions, type EventSourcedStore, type ExecuteStep, type HibernatableCtx, type IdempotentEffect, type IdempotentOutcome, type NextStep, PendingEffectsRecorder, type PersistedEvent, type PresenceCtx, type PresenceSocket, type PresenceUpgrade, type Projection, type ProjectionId, type ProjectionRegistry, type ProjectionRunner, type ProjectionUpdate, type RegisterOptions, type ResumePort, type RunStepLoopConfig, type SseHub, type StepCtx, type StepEngine, type StepHostConfig, type StepLoopOutcome, type StepOutcome, type StepRequest, type StepResponse, type StepResult, type StepTransport, WS_READY_STATE_OPEN, acceptCommandSocket, acceptDurableCommandSocket, acceptPresenceSocket, agentIsResumable, appliedEffects, applyAppliedEvent, autoBoot, bootResume, broadcast, broadcastFrame, broadcastHibernatable, constantTimeEqual, createAgentHost, deferredGateway, dispatchToIdle, doEventSourcedStore, doStore, driveProjections, durableCommandCarrier, durableDeferredGateway, durableTimer, emptyApplied, foldApplied, idempotentEffect, isApplied, mintRunToken, presenceCount, projectionIdString, projectionRegistry, rebuildProjection, registerHibernatableSocket, reissueSurvivingEffects, runProjection, runStepLoop, sseFromAgentEvents, sseHub, sseProjection, stepHost };
+export { type AgentHost, type AgentHostConfig, type AlarmStorage, type AppliedEffects, type AppliedEffectsEvent, type AppliedEffectsGuard, type AttachableSocket, type BroadcastOptions, type BroadcastReport, type DeferResumeHook, type DeferStepHostConfig, type DeferredGateway, type DeferredStepOutcome, type DeferredStepResponse, type DoStoreOptions, type DurableCommandCarrier, type DurableTimer, type DurableTimerConfig, type EffectApplied, EffectConfirmed, type EffectForgotten, type EffectKey, EffectOwed, type EventLogRange, type EventSourcedOptions, type EventSourcedStore, type ExecuteStep, type HibernatableCtx, type IdempotentEffect, type IdempotentOutcome, type NextStep, PendingEffectsRecorder, type PersistedEvent, type PresenceCtx, type PresenceSocket, type PresenceUpgrade, type Projection, type ProjectionId, type ProjectionRegistry, type ProjectionRunner, type ProjectionUpdate, type RegisterOptions, type ResumePort, type RunStepLoopConfig, type SseHub, type StepCtx, type StepEngine, type StepHostConfig, type StepLoopOutcome, type StepOutcome, type StepRequest, type StepResponse, type StepResult, type StepTransport, type StepWorking, WS_READY_STATE_OPEN, acceptCommandSocket, acceptDurableCommandSocket, acceptPresenceSocket, agentIsResumable, appliedEffects, applyAppliedEvent, autoBoot, bootResume, broadcast, broadcastFrame, broadcastHibernatable, constantTimeEqual, createAgentHost, deferredGateway, doEventSourcedStore, doStore, driveProjections, durableCommandCarrier, durableDeferredGateway, durableTimer, emptyApplied, foldApplied, idempotentEffect, isApplied, mintRunToken, presenceCount, projectionIdString, projectionRegistry, rebuildProjection, registerHibernatableSocket, reissueSurvivingEffects, runProjection, runStepLoop, sseFromAgentEvents, sseHub, sseProjection, stepHost };