@nifrajs/agent 3.1.0 → 3.2.0

package/src/index.ts

@@ -3,7 +3,10 @@
  *
  * One turn makes one model decision and may execute one {@link ToolContract}. The multi-turn runner
  * is intentionally bounded. The state adapter stores token-only evidence and cursor metadata; model
- * input, tool input, and tool output remain transient caller data.
+ * input, tool input, and tool output remain transient caller data. A model port may additionally
+ * stream progressive output (text, reasoning, tool-call arguments) through the request's optional
+ * `onDelta` callback when the caller wires an {@link AgentDeltaSink} into the ports - deltas are
+ * transient observer data for live UIs, never evidence, and are never persisted by the runtime.
  */
 
 import { canAttempt, type RequestBudget } from "@nifrajs/core/budget"
@@ -21,6 +24,40 @@ import {
   type ToolIdempotencyStore,
 } from "@nifrajs/core/tool-contract"
 
+export {
+  AgentDeployment,
+  type AgentDeploymentAdapter,
+  type AgentDeploymentPlan,
+  assertDeploymentAuthorityMonotonic,
+  createDeploymentAuthority,
+  type DeploymentActivationOptions,
+  type DeploymentAuthority,
+  type DeploymentCancellation,
+  type DeploymentCancelRequest,
+  type DeploymentCancelResult,
+  type DeploymentCapabilities,
+  type DeploymentCapabilityReport,
+  type DeploymentDisposeRequest,
+  type DeploymentDisposeResult,
+  DeploymentError,
+  type DeploymentErrorCode,
+  type DeploymentEvidence,
+  type DeploymentFilesystem,
+  type DeploymentInspection,
+  type DeploymentInspectRequest,
+  type DeploymentNetwork,
+  type DeploymentPrepareRequest,
+  type DeploymentPrepareResult,
+  type DeploymentProcess,
+  type DeploymentRuntime,
+  type DeploymentSecrets,
+  type DeploymentStartRequest,
+  type DeploymentStartResult,
+  type DeploymentState,
+  type HostileCodeIsolation,
+  parseDeploymentCapabilityReport,
+  parseDeploymentPlan,
+} from "./deployment.ts"
 export {
   createLocalProcessAdapter,
   type ExecutionPolicy,
@@ -32,6 +69,39 @@ export {
   type LocalProcessRequest,
   type LocalProcessResult,
 } from "./execution-policy.ts"
+export {
+  createStructuredOutputParser,
+  FakeModelGateway,
+  type FakeModelGatewayOptions,
+  isModelGatewayErrorCode,
+  MODEL_GATEWAY_ERROR_CODES,
+  type ModelGateway,
+  type ModelGatewayAttemptRequest,
+  type ModelGatewayBudget,
+  type ModelGatewayEnvelope,
+  type ModelGatewayError,
+  type ModelGatewayErrorCode,
+  type ModelGatewayEvidence,
+  type ModelGatewayExecutionResult,
+  type ModelGatewayFailure,
+  ModelGatewayFailureError,
+  type ModelGatewayRawResult,
+  type ModelGatewayRequest,
+  type ModelGatewayResult,
+  type ModelGatewaySuccess,
+  type ModelGatewayTerminalFailure,
+  type ModelGatewayUsage,
+  type ModelRoute,
+  type ModelRoutePolicy,
+  type ModelRouteRef,
+  parseModelGatewayError,
+  parseModelGatewayResult,
+  ReplayModelGateway,
+  type ReplayModelGatewayOptions,
+  runModelGateway,
+  type StructuredOutputParser,
+  structuredOutputParser,
+} from "./gateway.ts"
 
 export type AgentStatus = "continue" | "completed" | "suspended"
 export type AgentPendingKind = "approval" | "budget" | "model" | "cancelled"
@@ -91,6 +161,14 @@ export interface AgentModelRequest {
   readonly signal: AbortSignal
   /** Wall-clock budget shared with the parent request. Use withDeadlineHeader for outbound requests. */
   readonly deadline?: RequestBudget
+  /**
+   * Present when an observer asked for progressive output (see {@link AgentPorts.deltas}). A
+   * streaming port calls it per chunk while producing the decision; emitting is optional and
+   * best-effort - a port that returns only complete responses ignores it, and callback failures
+   * never reach the port. Deltas are transient observer data, not evidence: they are not
+   * validated, not persisted, and not replayed.
+   */
+  readonly onDelta?: (delta: AgentModelDelta) => void
 }
 
 export type AgentModelResponse =
@@ -102,6 +180,57 @@ export interface AgentModelPort {
   complete(request: AgentModelRequest): unknown | PromiseLike<unknown>
 }
 
+/**
+ * One progressive chunk of a model decision in flight: user-visible text, reasoning text, or the
+ * raw argument text of the tool call being formed (`name` on the first chunk when the provider
+ * announces it). A `usage` delta reports the decision's token counts once the provider settles
+ * them, optionally attributed to a provider and model - observers sum across decisions. Chunks
+ * are provider output surface, not evidence - the runtime never stores them.
+ */
+export type AgentModelDelta =
+  | { readonly kind: "text"; readonly text: string }
+  | { readonly kind: "reasoning"; readonly text: string }
+  | { readonly kind: "tool-args"; readonly name?: string; readonly argsText: string }
+  | {
+      readonly kind: "usage"
+      readonly provider?: string
+      readonly model?: string
+      readonly inputTokens?: number
+      readonly outputTokens?: number
+      readonly totalTokens?: number
+      readonly reasoningTokens?: number
+      readonly cachedInputTokens?: number
+    }
+
+/** A transient observer of model deltas - an SSE bridge, a live console, a progress meter. */
+export interface AgentDeltaSink {
+  delta(delta: AgentModelDelta): void
+}
+
+/**
+ * Fan model deltas out to several sinks - a protocol bridge and a logger can watch the same run.
+ * `undefined` entries are skipped, and the combined sink is `undefined` when none remain. Each
+ * sink is isolated: one sink throwing never starves the others.
+ */
+export function combineAgentDeltaSinks(
+  ...sinks: readonly (AgentDeltaSink | undefined)[]
+): AgentDeltaSink | undefined {
+  const live = sinks.filter((sink): sink is AgentDeltaSink => sink !== undefined)
+  if (live.length === 0) return undefined
+  if (live.length === 1) return live[0]
+  return {
+    delta(delta) {
+      for (const sink of live) {
+        try {
+          sink.delta(delta)
+        } catch {
+          // Deltas are best-effort observability; a failing sink must not affect its peers.
+        }
+      }
+    },
+  }
+}
+
 export interface AgentToolResult {
   readonly name: string
   readonly ok: boolean
@@ -156,6 +285,152 @@ export interface AgentTelemetryPort {
   step(evidence: AgentStepEvidence): void | PromiseLike<void>
 }
 
+/**
+ * Fan one run's step evidence out to several telemetry ports - an SSE evidence stream and an
+ * exporter can observe the same turn. Ports are awaited in argument order; `undefined` entries are
+ * skipped, and the combined port is `undefined` when none remain.
+ */
+export function combineAgentTelemetry(
+  ...ports: readonly (AgentTelemetryPort | undefined)[]
+): AgentTelemetryPort | undefined {
+  const live = ports.filter((port): port is AgentTelemetryPort => port !== undefined)
+  if (live.length === 0) return undefined
+  if (live.length === 1) return live[0]
+  return {
+    async step(evidence) {
+      for (const port of live) await port.step(evidence)
+    },
+  }
+}
+
+/** One RFC 6902 operation from the applied subset: `add`, `replace`, `remove`. */
+export type AgentStatePatchOp =
+  | { readonly op: "add" | "replace"; readonly path: string; readonly value: unknown }
+  | { readonly op: "remove"; readonly path: string }
+
+/**
+ * A shared, observable state document for one run - the state a live UI mirrors while the agent
+ * works. App code (a model port, a tool executor) calls `patch` with RFC 6902 operations; every
+ * subscriber sees the applied ops, and protocol bridges project them onto their wire (AG-UI
+ * `STATE_SNAPSHOT`/`STATE_DELTA`). The document is transient per-run observer data - it is not
+ * turn state, not evidence, and never persisted by the runtime.
+ */
+export interface AgentSharedState<State = unknown> {
+  /** A defensive deep copy of the current document. */
+  snapshot(): State
+  /** Apply ops atomically - on an invalid op the whole batch is rejected with a TypeError. */
+  patch(ops: readonly AgentStatePatchOp[]): void
+  /** Observe applied patches. Returns the unsubscribe function. Listener failures are isolated. */
+  subscribe(listener: (ops: readonly AgentStatePatchOp[]) => void): () => void
+}
+
+export function createAgentSharedState<State>(initial: State): AgentSharedState<State> {
+  let document: unknown = structuredClone(initial)
+  const listeners = new Set<(ops: readonly AgentStatePatchOp[]) => void>()
+  return {
+    snapshot() {
+      return structuredClone(document) as State
+    },
+    patch(ops) {
+      // Validate-then-apply on a copy so a mid-batch failure never leaves a half-patched document.
+      let next = structuredClone(document)
+      for (const op of ops) next = applyStatePatchOp(next, op)
+      document = next
+      const applied = Object.freeze([...ops])
+      for (const listener of listeners) {
+        try {
+          listener(applied)
+        } catch {
+          // Observer failures must not affect the document or the other observers.
+        }
+      }
+    },
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+  }
+}
+
+/** JSON Pointer segments that would graft onto the prototype chain are rejected outright. */
+const FORBIDDEN_STATE_KEYS = new Set(["__proto__", "constructor", "prototype"])
+
+function applyStatePatchOp(document: unknown, op: AgentStatePatchOp): unknown {
+  if (op === null || typeof op !== "object" || typeof op.path !== "string")
+    throw new TypeError("agent: invalid patch op")
+  if (op.op !== "add" && op.op !== "replace" && op.op !== "remove")
+    throw new TypeError("agent: unsupported patch op")
+  if (op.path === "") {
+    if (op.op === "remove") throw new TypeError("agent: cannot remove the document root")
+    return op.value
+  }
+  if (!op.path.startsWith("/")) throw new TypeError("agent: patch path must be a JSON Pointer")
+  const segments = op.path
+    .slice(1)
+    .split("/")
+    .map((segment) => segment.replaceAll("~1", "/").replaceAll("~0", "~"))
+  let parent: unknown = document
+  for (let index = 0; index < segments.length - 1; index += 1)
+    parent = stateChild(parent, segments[index] as string)
+  const key = segments[segments.length - 1] as string
+  if (Array.isArray(parent)) {
+    if (op.op === "add" && key === "-") {
+      parent.push(op.value)
+      return document
+    }
+    const index = asStateIndex(key, parent.length + (op.op === "add" ? 1 : 0))
+    if (op.op === "add") parent.splice(index, 0, op.value)
+    else if (op.op === "replace") parent[index] = op.value
+    else parent.splice(index, 1)
+    return document
+  }
+  const record = asStateRecord(parent)
+  if (FORBIDDEN_STATE_KEYS.has(key)) throw new TypeError("agent: forbidden patch path segment")
+  if (op.op === "remove") {
+    if (!Object.hasOwn(record, key)) throw new TypeError("agent: patch path does not exist")
+    delete record[key]
+    return document
+  }
+  if (op.op === "replace" && !Object.hasOwn(record, key))
+    throw new TypeError("agent: patch path does not exist")
+  record[key] = op.value
+  return document
+}
+
+function stateChild(parent: unknown, segment: string): unknown {
+  if (Array.isArray(parent)) return parent[asStateIndex(segment, parent.length)]
+  const record = asStateRecord(parent)
+  if (FORBIDDEN_STATE_KEYS.has(segment) || !Object.hasOwn(record, segment))
+    throw new TypeError("agent: patch path does not exist")
+  return record[segment]
+}
+
+function asStateIndex(segment: string, bound: number): number {
+  if (!/^(0|[1-9]\d{0,9})$/.test(segment)) throw new TypeError("agent: invalid array index")
+  const index = Number(segment)
+  if (index >= bound) throw new TypeError("agent: array index out of bounds")
+  return index
+}
+
+function asStateRecord(value: unknown): Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value))
+    throw new TypeError("agent: patch path does not exist")
+  return value as Record<string, unknown>
+}
+
+/** A sink failure must surface as neither a model failure nor a dropped run. */
+function guardedDelta(sink: AgentDeltaSink): (delta: AgentModelDelta) => void {
+  return (delta) => {
+    try {
+      sink.delta(delta)
+    } catch {
+      // Deltas are best-effort observability.
+    }
+  }
+}
+
 export interface AgentPorts {
   readonly model: AgentModelPort
   readonly capabilities: readonly string[]
@@ -166,6 +441,8 @@ export interface AgentPorts {
   readonly state?: AgentStateStore
   readonly approval?: AgentApprovalPort
   readonly telemetry?: AgentTelemetryPort
+  /** Receives model deltas when the model port streams. Transient - nothing here is persisted. */
+  readonly deltas?: AgentDeltaSink
   readonly clock?: () => number
   /** Adapter used to satisfy execution policies declared by tool contracts. */
   readonly executionPolicy?: ExecutionPolicyAdapter
@@ -382,6 +659,7 @@ export async function turn<
       ...(ports.deadline === undefined
         ? {}
         : { deadline: ports.deadline.child(AGENT_SETTLE_RESERVE_MS) }),
+      ...(ports.deltas === undefined ? {} : { onDelta: guardedDelta(ports.deltas) }),
     })
     response = parseModelResponse(rawResponse)
   } catch {
@@ -801,3 +1079,27 @@ function freezeState(state: AgentTurnState): AgentTurnState {
     ...(state.pending === undefined ? {} : { pending: Object.freeze({ ...state.pending }) }),
   })
 }
+
+// Unified capability descriptor registry. Re-exported at the root and via the `./registry` subpath so
+// the MCP and coding-agent adapters can consume the descriptor contracts through the one declared edge.
+export type {
+  ApprovalClass,
+  CapabilityDescriptor,
+  CapabilityKind,
+  DescriptorInput,
+  IdempotencyClass,
+  IsolationClass,
+  RegistryErrorCode,
+  RegistrySnapshot,
+  RetryClass,
+  ToolDescriptorOptions,
+} from "./registry.ts"
+export {
+  CAPABILITY_DESCRIPTOR_VERSION,
+  composeDescriptor,
+  composeRegistrySnapshot,
+  descriptorFromTool,
+  parseCapabilityDescriptor,
+  REGISTRY_SNAPSHOT_VERSION,
+  RegistryError,
+} from "./registry.ts"

package/src/mount.ts

@@ -0,0 +1,344 @@
+/**
+ * `mountAgent` - the one-call HTTP + SSE seam for a {@link AgentDefinition}.
+ *
+ * It translates HTTP to the bounded runner and back, nothing more. The request body is read through
+ * core's single bounded, proto-guarded framing lane (`@nifrajs/core/edge-kit`); the run itself is
+ * driven by {@link runAgent}/{@link resumeAgent}. The caller supplies the ports through a per-request
+ * factory, so the model, durable state store, and approval transport - the operated, credentialed, or
+ * tenant-scoped pieces - are injected here and never live in this package.
+ *
+ * Wire contract (default path `/agent`):
+ * - `POST {path}` body `{ input, turnId?, resume? }`:
+ *   - `Accept: text/event-stream` -> SSE: one `event: step` per {@link AgentStepEvidence}, then a final
+ *     `event: result` carrying the projected run result, then the stream closes.
+ *   - otherwise -> a single JSON body: the projected run result.
+ * - `resume` is `{ continuation, approval? }` (see {@link AgentTurnInput}); the runtime keeps state
+ *   token-only, so a suspended tool's input must be replayed by the caller in `continuation.input`.
+ * - With an `evidenceLog` configured, `step` frames carry `id: <seq>` and a dropped SSE connection
+ *   is resumable: re-POST the same `turnId` with a `Last-Event-ID` header to replay the missed
+ *   evidence and rejoin the still-running turn (or receive the stored terminal frame) - the run is
+ *   never re-executed. Without the log the header is ignored and every POST starts a run.
+ * - The seam performs no authentication or authorization. Wrap it with the app's own route guards, and
+ *   scope the store/model returned by `ports` to the caller (RLS born in at the data layer).
+ */
+
+import {
+  EMPTY_RESPONSE_CONTROLS,
+  type ProtoPoisoning,
+  plainError,
+  type ResponseResult,
+  readBodyFramed,
+  toResponse,
+} from "@nifrajs/core/edge-kit"
+import type { StandardSchemaV1 } from "@nifrajs/core/schema"
+import {
+  type AgentEvidenceLog,
+  type AgentEvidenceReplay,
+  createAgentEvidenceStream,
+} from "./events.ts"
+import {
+  type AgentDefinition,
+  type AgentPendingKind,
+  type AgentPorts,
+  type AgentRunResult,
+  type AgentTurnInput,
+  combineAgentTelemetry,
+  createAgentState,
+  resumeAgent,
+  runAgent,
+} from "./index.ts"
+
+const DEFAULT_PATH = "/agent"
+const DEFAULT_MAX_BODY_BYTES = 1_000_000
+const PENDING_KINDS: readonly AgentPendingKind[] = ["approval", "budget", "model", "cancelled"]
+const LAST_EVENT_ID_PATTERN = /^\d{1,15}$/
+
+/** The structural slice of a route context the seam needs. Kept loose so core stays a peer dependency. */
+export interface AgentRouteContext {
+  readonly req: Request
+}
+
+/** The structural slice of a nifra server `mountAgent` needs. */
+export interface AgentMountableApp {
+  post(path: string, handler: (c: AgentRouteContext) => Response | Promise<Response>): unknown
+}
+
+export interface MountAgentOptions<
+  InputSchema extends StandardSchemaV1,
+  OutputSchema extends StandardSchemaV1,
+> {
+  readonly agent: AgentDefinition<InputSchema, OutputSchema>
+  /** Endpoint path. Default `/agent`. */
+  readonly path?: string
+  /** Bounded run length passed to {@link runAgent}. */
+  readonly maxTurns?: number
+  /** Maximum request body size in bytes. Default 1_000_000. */
+  readonly maxBodyBytes?: number
+  /** Prototype-poisoning policy for the framing lane. Default `"reject"`. */
+  readonly protoPoisoning?: ProtoPoisoning
+  /**
+   * Build the ports for one request - the model, durable state store, approval transport, capabilities,
+   * and budgets. Receives the route context so the caller can scope every port to the request subject.
+   */
+  readonly ports: (c: AgentRouteContext) => AgentPorts | Promise<AgentPorts>
+  /**
+   * Evidence log making the SSE stream resumable via `Last-Event-ID`. The in-memory reference
+   * (`createMemoryAgentEvidenceLog`) is single-process; a durable log is an adapter concern.
+   */
+  readonly evidenceLog?: AgentEvidenceLog
+}
+
+/** Mount a single agent as `POST {path}`, negotiating an SSE evidence stream on `Accept`. */
+export function mountAgent<
+  InputSchema extends StandardSchemaV1,
+  OutputSchema extends StandardSchemaV1,
+>(app: AgentMountableApp, options: MountAgentOptions<InputSchema, OutputSchema>): void {
+  const path = options.path ?? DEFAULT_PATH
+  const maxBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES
+  const proto = options.protoPoisoning ?? "reject"
+  const runOptions = options.maxTurns === undefined ? {} : { maxTurns: options.maxTurns }
+
+  app.post(path, (c) =>
+    readBodyFramed<Response>(
+      c.req,
+      maxBytes,
+      proto,
+      (parsed) => execute(c, parsed, options, runOptions),
+      (rejection) => render(rejection),
+      () => render(plainError(400, "bad_request")),
+    ).catch(() => render(plainError(400, "bad_request"))),
+  )
+}
+
+async function execute<InputSchema extends StandardSchemaV1, OutputSchema extends StandardSchemaV1>(
+  c: AgentRouteContext,
+  parsed: unknown,
+  options: MountAgentOptions<InputSchema, OutputSchema>,
+  runOptions: { readonly maxTurns?: number },
+): Promise<Response> {
+  const body = asRecord(parsed)
+  if (body === undefined) return jsonResponse(400, { error: "body_must_be_object" })
+
+  const turnIdRaw = typeof body.turnId === "string" ? body.turnId : undefined
+  const turnId = turnIdRaw ?? crypto.randomUUID()
+
+  const resume = parseResume(body.resume)
+  const log = options.evidenceLog
+  const wantsSse = (c.req.headers.get("accept") ?? "").includes("text/event-stream")
+
+  // A reconnect replays recorded evidence and rejoins the turn; it never starts a second run.
+  const lastEventId = c.req.headers.get("last-event-id")
+  if (wantsSse && log !== undefined && lastEventId !== null) {
+    if (!LAST_EVENT_ID_PATTERN.test(lastEventId))
+      return jsonResponse(400, { error: "invalid_last_event_id" })
+    const replay = await log.replay(turnId, Number(lastEventId))
+    if (replay === undefined) return jsonResponse(409, { error: "replay_unavailable" })
+    return sseReplayResponse(turnId, replay)
+  }
+
+  const basePorts = await options.ports(c)
+
+  const start = (
+    telemetry?: AgentPorts["telemetry"],
+  ): Promise<AgentRunResult<NonNullable<OutputSchema["~standard"]["types"]>["output"]>> => {
+    // Compose rather than replace: an SSE evidence stream must not displace a telemetry port the
+    // caller injected through `ports` (an exporter, a durable evidence log).
+    const combined = combineAgentTelemetry(basePorts.telemetry, log?.open(turnId), telemetry)
+    const ports = combined === undefined ? basePorts : { ...basePorts, telemetry: combined }
+    if (resume !== undefined) {
+      return resumeAgent(options.agent, turnId, { value: body.input, resume }, ports, runOptions)
+    }
+    let state: ReturnType<typeof createAgentState>
+    try {
+      state = createAgentState(turnId)
+    } catch {
+      return Promise.reject(new BadTurnId())
+    }
+    return runAgent(options.agent, { value: body.input }, ports, { ...runOptions, state })
+  }
+
+  if (!wantsSse) {
+    try {
+      const result = await start()
+      const projected = projectResult(turnId, result)
+      await finishQuietly(log, turnId, { event: "result", data: projected })
+      return jsonResponse(200, projected)
+    } catch (err) {
+      await finishQuietly(log, turnId, { event: "error", data: { turnId, error: "run_failed" } })
+      if (err instanceof BadTurnId) return jsonResponse(400, { error: "invalid_turn_id" })
+      return jsonResponse(409, { error: "resume_unavailable" })
+    }
+  }
+  return sseResponse(turnId, start, log)
+}
+
+function sseResponse<Output>(
+  turnId: string,
+  start: (telemetry: AgentPorts["telemetry"]) => Promise<AgentRunResult<Output>>,
+  log: AgentEvidenceLog | undefined,
+): Response {
+  const stream = createAgentEvidenceStream()
+  // `id:` frames are only meaningful when a log can serve the reconnect they invite.
+  const withIds = log !== undefined
+  const body = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const send = sseSender(controller)
+      const run = start(stream)
+      // The evidence stream must terminate whether the run resolves or throws, or the `for await`
+      // below would hang; the run result (or the error) is still reported in-band after it drains.
+      run
+        .then(
+          () => {},
+          () => {},
+        )
+        .finally(() => stream.complete())
+      try {
+        for await (const evidence of stream)
+          send("step", evidence, withIds ? evidence.seq : undefined)
+        const frame = { event: "result", data: projectResult(turnId, await run) }
+        // Store the terminal frame before delivering it, so a client that misses it can replay.
+        await finishQuietly(log, turnId, frame)
+        send(frame.event, frame.data)
+      } catch {
+        const frame = { event: "error", data: { turnId, error: "run_failed" } }
+        await finishQuietly(log, turnId, frame)
+        send(frame.event, frame.data)
+      } finally {
+        controller.close()
+      }
+    },
+  })
+  return sseHeaders(body)
+}
+
+function sseReplayResponse(turnId: string, replay: AgentEvidenceReplay): Response {
+  const body = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const send = sseSender(controller)
+      try {
+        for (const evidence of replay.evidence) send("step", evidence, evidence.seq)
+        if (replay.live !== undefined)
+          for await (const evidence of replay.live) send("step", evidence, evidence.seq)
+        const frame = asTerminalFrame(await replay.result)
+        if (frame === undefined) send("error", { turnId, error: "run_failed" })
+        else send(frame.event, frame.data)
+      } catch {
+        send("error", { turnId, error: "run_failed" })
+      } finally {
+        controller.close()
+      }
+    },
+  })
+  return sseHeaders(body)
+}
+
+function sseSender(
+  controller: ReadableStreamDefaultController<Uint8Array>,
+): (event: string, data: unknown, id?: number) => void {
+  const encoder = new TextEncoder()
+  return (event, data, id) => {
+    const head = id === undefined ? "" : `id: ${id}\n`
+    controller.enqueue(encoder.encode(`${head}event: ${event}\ndata: ${JSON.stringify(data)}\n\n`))
+  }
+}
+
+function sseHeaders(body: ReadableStream<Uint8Array>): Response {
+  return new Response(body, {
+    status: 200,
+    headers: {
+      "content-type": "text/event-stream; charset=utf-8",
+      "cache-control": "no-cache, no-transform",
+      connection: "keep-alive",
+    },
+  })
+}
+
+interface TerminalFrame {
+  readonly event: string
+  readonly data: unknown
+}
+
+/** Parse the stored terminal value - a durable log adapter may hand back anything. */
+function asTerminalFrame(value: unknown): TerminalFrame | undefined {
+  const record = asRecord(value)
+  if (record === undefined || typeof record.event !== "string") return undefined
+  return { event: record.event, data: record.data }
+}
+
+/** Telemetry-grade storage: a failing log must not fail the turn or mask its result. */
+async function finishQuietly(
+  log: AgentEvidenceLog | undefined,
+  turnId: string,
+  frame: TerminalFrame,
+): Promise<void> {
+  if (log === undefined) return
+  try {
+    await log.finish(turnId, frame)
+  } catch {
+    // Replay degrades to unavailable; the in-band response is unaffected.
+  }
+}
+
+/** Project a run result onto the wire. State evidence is token-only by design, so it passes through. */
+function projectResult<Output>(
+  turnId: string,
+  result: AgentRunResult<Output>,
+): Record<string, unknown> {
+  const base = { turnId, status: result.status, evidence: result.evidence }
+  if (result.status === "completed") {
+    return result.error !== undefined
+      ? { ...base, ok: false, error: result.error }
+      : { ...base, ok: true, output: result.output }
+  }
+  if (result.status === "suspended") {
+    return { ...base, reason: result.reason, pending: result.pending }
+  }
+  return base
+}
+
+function parseResume(raw: unknown): AgentTurnInput["resume"] | undefined {
+  const record = asRecord(raw)
+  if (record === undefined) return undefined
+  const continuation = asRecord(record.continuation)
+  if (continuation === undefined) return undefined
+  const kind = continuation.kind
+  if (typeof kind !== "string" || !PENDING_KINDS.includes(kind as AgentPendingKind))
+    return undefined
+  if (typeof continuation.effectId !== "string") return undefined
+  if (continuation.tool !== undefined && typeof continuation.tool !== "string") return undefined
+  const approval = asRecord(record.approval)
+  return {
+    continuation: {
+      kind: kind as AgentPendingKind,
+      ...(continuation.tool === undefined ? {} : { tool: continuation.tool as string }),
+      ...(Object.hasOwn(continuation, "input") ? { input: continuation.input } : {}),
+      effectId: continuation.effectId,
+    },
+    ...(approval !== undefined && typeof approval.granted === "boolean"
+      ? {
+          approval: {
+            granted: approval.granted,
+            ...(typeof approval.reason === "string" ? { reason: approval.reason } : {}),
+          },
+        }
+      : {}),
+  }
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined
+  return value as Record<string, unknown>
+}
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json; charset=utf-8" },
+  })
+}
+
+function render(response: Response | ResponseResult): Response {
+  return response instanceof Response ? response : toResponse(response, EMPTY_RESPONSE_CONTROLS)
+}
+
+class BadTurnId extends Error {}