Merge branch 'codex/tool-json-schema-dsl' into codex/canonical-tool-output

packages/host/apiproxy/README.md

@@ -0,0 +1,27 @@
+# @deepseek-ai/dsh-host-apiproxy
+
+The ApiProxy front layer every client shape shares: the TS contract (`src/api/`, zero Node dependencies, importable from the browser) and the fetch carrier pair (`src/fetch/`: `toFetchHandler` on the host side, `AbstractApiClient` plus platform subclasses on the client side). Host assembly lives in `dsh-host-runtime`.
+
+## Contract layer (`/api`)
+
+Wire messages form a four-quadrant discriminated union — who initiates × request/response — decoupled from the physical channel: `ClientRequest` (POST `/api/<method>` body), `ServerResponse` (that POST's response body), `ServerRequest` (SSE frame), `ClientResponse` (POST `/api/respond` body). Responses always echo the matching request's `rpcId` and never mint a new one. Method parameter/return structures live only in the domain interface signatures (`SessionsApi`, `HostApi`, `EventsApi`); `RpcMethodMap` registers the methods and every other position derives via `RequestPayload<K>`/`ResponseValue<K>`. Zod schemas anchor `satisfies z.ZodType<Wire<T>>` and parse at two levels: envelope first, business payload second, dispatched per method. Business errors ride `RpcResult`'s error branch (`RpcErrorDetailsMap` closes the code set); HTTP status expresses only the carrier.
+
+The layering/protocol decisions are recorded in the [GUI layering and RPC protocol RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md); the browser-side consumption architecture in the [web client architecture RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md).
+
+## Carrier layer (`/client` + root)
+
+`AbstractApiClient` holds every protocol invariant — rpcId minting, envelope wrap/unwrap, zod parsing, SSE frame decoding, unary timeout, microtask-batched envelope observation (`subscribeEnvelopes`) — while platform subclasses supply only the `doFetch` transport aspect. `InProcessApiClient` over `toFetchHandler(api)` is the isomorphic point: the full wire serialization/validation path with no network, used by `dsh -p` headless.
+
+## Model Experience
+
+None, as the package defines the client↔host wire contract and carriers; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **`respond` routing is shipped, but pending-interaction state is host-side work** — the wire shape (POST `/api/respond`, `RpcReceipt`) is final; the pending table that makes late/duplicate answers meaningful lives in `dsh-host-runtime` and is still a stub there.
+- **Reserved seams stay out of `RpcMethodMap`** — `session.fork`, `prompt.mode: 'inject'`, `task.list`, `host.listModels`, and a describe `hostInstanceId` are documented reservations; an unknown method fails loud at envelope parse rather than getting a not-implemented code.
+- **No protocol version field** — client and host ship together; `host.describe` gains a version negotiation field only when an independently released client exists.

packages/host/apiproxy/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@deepseek-ai/dsh-host-apiproxy",
+  "description": "ApiProxy front layer: the TS contract (api/) and the fetch carrier pair (fetch/); host assembly lives in dsh-host-runtime",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json",
+    "./api": {
+      "types": "./lib/types/api/index.d.ts",
+      "default": "./lib/types/api/index.js"
+    },
+    "./api/*": {
+      "types": "./lib/types/api/*.d.ts",
+      "default": "./lib/types/api/*.js"
+    },
+    "./client": {
+      "types": "./lib/types/fetch/client.d.ts",
+      "default": "./lib/types/fetch/client.js"
+    }
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-user-approval": "workspace:^",
+    "@deepseek-ai/dsh-user-interaction": "workspace:^",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "cordis": "^4.0.0-rc.7",
+    "@deepseek-ai/dsh-invariants": "^0.0.1"
+  },
+  "devDependencies": {
+    "cordis": "^4.0.0-rc.7",
+    "@deepseek-ai/dsh-invariants": "workspace:^"
+  }
+}

packages/host/apiproxy/src/api/approvals.schema.ts

@@ -0,0 +1,21 @@
+/**
+ * approvals domain zod schemas (respond is a client-response; the payload schema serves
+ * the /api/respond endpoint's second parse after routing via the pending table).
+ * ApprovalRequestId brand cast point: one.
+ */
+
+import { z } from 'zod'
+import type { ApprovalRequestId } from '@deepseek-ai/dsh-user-approval/types'
+import type { ApprovalResponsePayload } from './approvals.ts'
+import type { Wire } from './rpc.schema.ts'
+import { sessionIdSchema } from './sessions.schema.ts'
+
+/** ApprovalRequestId: one brand cast after shape validation (the only cast point in this domain). */
+export const approvalRequestIdSchema = z.string().min(1) as unknown as z.ZodType<ApprovalRequestId>
+
+/** Approval answer payload (the result.value slot of a client-response). */
+export const approvalResponsePayloadSchema = z.object({
+  sessionId: sessionIdSchema,
+  approvalId: approvalRequestIdSchema,
+  outcome: z.union([z.literal('allowed-once'), z.literal('rejected')]),
+}) satisfies z.ZodType<Wire<ApprovalResponsePayload>>

packages/host/apiproxy/src/api/approvals.ts

@@ -0,0 +1,21 @@
+/**
+ * approvals domain contract. The approval requested frame is a
+ * server-request (stable rpcId); the answer is a client-response echoing that rpcId (not a
+ * unary method, not in RpcMethodMap, mints no new id), carried on POST /api/respond with an
+ * RpcReceipt carrier receipt as the HTTP response body; the final outcome arrives in the resolved frame.
+ */
+
+import type { ApprovalRequestId } from '@deepseek-ai/dsh-user-approval/types'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+
+/**
+ * Approval answer payload (the result.value slot of a client-response). outcome accepts only
+ * the two values a client can give (cancelled/unavailable are host-side outcomes). approvalId
+ * is the core audit correlation (used by the impl to reconcile `approval/asked`/`decided`;
+ * passes through core's existing brand); wire correlation is governed by the echoed rpcId.
+ */
+export interface ApprovalResponsePayload {
+  sessionId: SessionId
+  approvalId: ApprovalRequestId
+  outcome: 'allowed-once' | 'rejected'
+}

packages/host/apiproxy/src/api/events.schema.ts

@@ -0,0 +1,42 @@
+/**
+ * events domain zod schemas: MuxFrame / HostFrame unions (discriminatedUnion('type')).
+ * A frame is the payload slot of the ServerRequest full form; the SessionEvent inside
+ * a session/event frame reuses sessions.schema's strict-envelope + wide-data passthrough branch.
+ */
+
+import { z } from 'zod'
+import type { AskUserQuestionItem } from '@deepseek-ai/dsh-user-interaction/types'
+import type { HostFrame, MuxFrame } from './events.ts'
+import type { Wire } from './rpc.schema.ts'
+import { rpcErrorSchema, rpcIdSchema } from './rpc.schema.ts'
+import { approvalRequestIdSchema } from './approvals.schema.ts'
+import { sessionEventSchema, sessionIdSchema, toolEventViewSchema } from './sessions.schema.ts'
+
+/** Question shape validated strictly against core dsh-user-interaction. */
+export const askUserQuestionItemSchema = z.object({
+  id: z.string(),
+  question: z.string(),
+  header: z.string().optional(),
+  options: z.array(z.object({ label: z.string(), description: z.string().optional() })).optional(),
+  multiSelect: z.boolean().optional(),
+}) satisfies z.ZodType<Wire<AskUserQuestionItem>>
+
+/** MuxFrame union (payload slot of a mux-stream ServerRequest). */
+export const muxFrameSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('session/event'), sessionId: sessionIdSchema, event: sessionEventSchema, view: toolEventViewSchema.optional() }),
+  z.object({ type: z.literal('session/subscribed'), sessionId: sessionIdSchema, lastSeq: z.number().int() }),
+  z.object({ type: z.literal('approval/requested'), sessionId: sessionIdSchema, approvalId: approvalRequestIdSchema, toolName: z.string(), callId: z.string().optional(), reason: z.string().optional() }),
+  z.object({ type: z.literal('approval/resolved'), sessionId: sessionIdSchema, approvalId: approvalRequestIdSchema, outcome: z.union([z.literal('allowed-once'), z.literal('rejected'), z.literal('cancelled'), z.literal('unavailable')]) }),
+  z.object({ type: z.literal('question/requested'), sessionId: sessionIdSchema, questions: z.array(askUserQuestionItemSchema) }),
+  z.object({ type: z.literal('question/resolved'), sessionId: sessionIdSchema, questionRpcId: rpcIdSchema, outcome: z.union([z.literal('answered'), z.literal('cancelled')]) }),
+  z.object({ type: z.literal('stream/error'), error: rpcErrorSchema }),
+]) as unknown as z.ZodType<MuxFrame>
+
+/** HostFrame union (payload slot of a host-stream ServerRequest). */
+export const hostFrameSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('host/session-added'), sessionId: sessionIdSchema, parentSessionId: sessionIdSchema.optional() }),
+  z.object({ type: z.literal('host/session-removed'), sessionId: sessionIdSchema }),
+  z.object({ type: z.literal('host/session-status'), sessionId: sessionIdSchema, running: z.boolean() }),
+  z.object({ type: z.literal('host/agent-error'), sessionId: sessionIdSchema, message: z.string() }),
+  z.object({ type: z.literal('stream/error'), error: rpcErrorSchema }),
+]) as unknown as z.ZodType<HostFrame>

packages/host/apiproxy/src/api/events.ts

@@ -0,0 +1,69 @@
+/**
+ * events domain contract: signatures and frame unions for the two SSE
+ * streams. Four-quadrant: streams yield the narrow form `RpcRequest<Frame>` (server-request
+ * view) — rpcId must be exposed to the business layer, because responses to answerable frames
+ * (approval/question requested) echo it; for pure pushes it identifies that one push.
+ * signal is a local stream-control parameter, independent of the request (never on the wire).
+ */
+
+import type { AskUserQuestionItem } from '@deepseek-ai/dsh-user-interaction/types'
+import type { ApprovalOutcome, ApprovalRequestId } from '@deepseek-ai/dsh-user-approval/types'
+import type { CallId } from '@deepseek-ai/dsh-llm/brand'
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
+import type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools/presentation'
+import type { RpcError, RpcId, RpcRequest } from './rpc.ts'
+
+// Client-side consumers take the render-intent vocabulary from the contract;
+// dsh-tools remains its owner.
+export type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools/presentation'
+
+/**
+ * Host-computed render intent accompanying a `tool/call` or `tool/result`
+ * event. A pure derivation of args/result through the presenter registered at
+ * emission time — never persisted (the session log carries only the event), so
+ * the same event may carry a different view (or none) on a later delivery.
+ * `for` names which vocabulary applies without re-inspecting the event type.
+ * An absent view means the client's documented default (generic JSON card).
+ */
+export type ToolEventView =
+  | { for: 'call'; view: ToolCallView }
+  | { for: 'result'; view: ToolResultView }
+
+/** Streaming face of the contract: the two SSE stream openers (mux + host). */
+export interface EventsApi {
+  /**
+   * All-session aggregated mux stream. On open, emits a subscribed control frame for every
+   * attached session and replays each session's still-pending approval/question requested
+   * frames (rpcId reused verbatim — the refresh-recovery baseline).
+   * since: resume seam, unimplemented in v1 (ignored if passed); reconnection = reopen the
+   * stream + refetch history.
+   */
+  mux(request: RpcRequest<{ since?: Record<SessionId, number> }>, signal: AbortSignal): AsyncIterable<RpcRequest<MuxFrame>>
+
+  /**
+   * Host-level info stream: session create/destroy, running-status flips, and
+   * agent failures with no turn position. Empty payload uses `{}`.
+   */
+  host(request: RpcRequest<{}>, signal: AbortSignal): AsyncIterable<RpcRequest<HostFrame>>
+}
+
+/**
+ * Mux stream frames: raw session-event passthrough + control frames +
+ * approval/question frames (requested = answerable server-request, the rest are pure pushes).
+ */
+export type MuxFrame =
+  | { type: 'session/event'; sessionId: SessionId; event: SessionEvent; view?: ToolEventView }
+  | { type: 'session/subscribed'; sessionId: SessionId; lastSeq: number }
+  | { type: 'approval/requested'; sessionId: SessionId; approvalId: ApprovalRequestId; toolName: string; callId?: CallId; reason?: string }
+  | { type: 'approval/resolved'; sessionId: SessionId; approvalId: ApprovalRequestId; outcome: ApprovalOutcome }
+  | { type: 'question/requested'; sessionId: SessionId; questions: AskUserQuestionItem[] }
+  | { type: 'question/resolved'; sessionId: SessionId; questionRpcId: RpcId; outcome: 'answered' | 'cancelled' }
+  | { type: 'stream/error'; error: RpcError }
+
+/** Host stream frames. session-added carries the lineage anchor; agent-error is the only outlet for live failures with no turn position. */
+export type HostFrame =
+  | { type: 'host/session-added'; sessionId: SessionId; parentSessionId?: SessionId }
+  | { type: 'host/session-removed'; sessionId: SessionId }
+  | { type: 'host/session-status'; sessionId: SessionId; running: boolean }
+  | { type: 'host/agent-error'; sessionId: SessionId; message: string }
+  | { type: 'stream/error'; error: RpcError }

packages/host/apiproxy/src/api/host.schema.ts

@@ -0,0 +1,19 @@
+/**
+ * host domain zod schemas (names derived from map keys).
+ */
+
+import { z } from 'zod'
+import type { RequestPayload, ResponseValue } from './rpc-map.ts'
+import type { Wire } from './rpc.schema.ts'
+
+/** host.describe request payload (empty object literal). */
+export const hostDescribeRequestSchema = z.object({}) satisfies z.ZodType<Wire<RequestPayload<'host.describe'>>>
+
+/** host.describe response value. */
+export const hostDescribeValueSchema = z.object({
+  version: z.string(),
+  cwd: z.string(),
+  provider: z.string().optional(),
+  model: z.string().optional(),
+  attachedSessions: z.number().int().nonnegative(),
+}) satisfies z.ZodType<Wire<ResponseValue<'host.describe'>>>

packages/host/apiproxy/src/api/host.ts

@@ -0,0 +1,25 @@
+/**
+ * host domain contract. No protocol version: client and host ship
+ * together; introduce protocolVersion only when an independently released client appears.
+ */
+
+import type { RpcRequest, RpcResponse } from './rpc.ts'
+
+/** Host-level unary methods. */
+export interface HostApi {
+  /**
+   * One-shot host snapshot. Empty payload uses the literal `{}` (extend in place when fields arrive).
+   * version = the host app's (apps/cli) package.json version; cwd = the host process working
+   * directory (root for session persistence and tool execution); provider/model = the defaults
+   * applied when a new agent doesn't specify them explicitly, absent when the host configures
+   * no explicit default (the adapter falls back internally);
+   * attachedSessions = count of currently attached sessions (those with a live agent).
+   */
+  describe(request: RpcRequest<{}>): Promise<RpcResponse<{
+    version: string
+    cwd: string
+    provider?: string
+    model?: string
+    attachedSessions: number
+  }>>
+}

packages/host/apiproxy/src/api/index.ts

@@ -0,0 +1,46 @@
+/**
+ * apiproxy contract-layer barrel. api/ has zero Node dependencies and is
+ * importable from the browser; the TS interfaces are the authoritative contract, HTTP/SSE are
+ * merely physical channels (four-quadrant message model).
+ */
+
+import type { SessionsApi } from './sessions.ts'
+import type { HostApi } from './host.ts'
+import type { EventsApi } from './events.ts'
+import type { ClientResponse, RpcReceipt } from './rpc.ts'
+
+/** Root interface of the unified API surface. New client-request domain = one new file pair + one field here + one map row. */
+export interface ApiProxy {
+  sessions: SessionsApi
+  host: HostApi
+  events: EventsApi
+  /** Response entry for server-requests (client-response, echoing their rpcId); not a domain method (four-quadrant model). */
+  respond(message: ClientResponse): Promise<RpcReceipt>
+}
+
+// ---- Domain interfaces and payload entities ----
+export type { HistoryEntry, SessionsApi, SessionSummary } from './sessions.ts'
+export type { HostApi } from './host.ts'
+export type { EventsApi, MuxFrame, HostFrame, ToolCallView, ToolEventView, ToolResultView } from './events.ts'
+export type { ApprovalResponsePayload } from './approvals.ts'
+export type { QuestionResponsePayload } from './questions.ts'
+
+// ---- Message layer: narrow forms (domain-signature view) ----
+export type { RpcRequest, RpcResponse } from './rpc.ts'
+
+// ---- Message layer: the four wire full forms + carrier receipt ----
+export type {
+  ClientRequest,
+  ClientResponse,
+  RpcMessage,
+  RpcReceipt,
+  ServerRequest,
+  ServerResponse,
+} from './rpc.ts'
+
+// ---- Errors and ids ----
+export { RpcId } from './rpc.ts'
+export type { RpcError, RpcErrorCode, RpcErrorDetailsMap, RpcResult } from './rpc.ts'
+
+// ---- Method registry and derived generics ----
+export type { RequestPayload, ResponseValue, RpcMethodMap } from './rpc-map.ts'

packages/host/apiproxy/src/api/questions.schema.ts

@@ -0,0 +1,26 @@
+/**
+ * questions domain zod schemas (respond is a client-response; the payload schema serves
+ * the /api/respond endpoint's second parse after routing via the pending table). The question
+ * identifier is the echoed rpcId; the payload carries no resource id.
+ */
+
+import { z } from 'zod'
+import type { AskUserQuestionAnswer } from '@deepseek-ai/dsh-user-interaction/types'
+import type { QuestionResponsePayload } from './questions.ts'
+import type { Wire } from './rpc.schema.ts'
+import { sessionIdSchema } from './sessions.schema.ts'
+
+/** AskUserQuestionAnswer validated strictly against core dsh-user-interaction. */
+export const askUserQuestionAnswerSchema = z.object({
+  answers: z.array(z.object({
+    id: z.string(),
+    selected: z.array(z.string()),
+    custom: z.string().optional(),
+  })),
+}) satisfies z.ZodType<Wire<AskUserQuestionAnswer>>
+
+/** Question answer payload (the result.value slot of a client-response). */
+export const questionResponsePayloadSchema = z.object({
+  sessionId: sessionIdSchema,
+  answer: askUserQuestionAnswerSchema,
+}) satisfies z.ZodType<Wire<QuestionResponsePayload>>

packages/host/apiproxy/src/api/questions.ts

@@ -0,0 +1,19 @@
+/**
+ * questions domain contract. The question requested frame is a
+ * server-request whose rpcId is the question's stable logical id (minted when the host accepts
+ * ask(); core user-interaction has no request-level id); the answer is a client-response
+ * echoing that rpcId, with no resource id in the payload (rpcId suffices).
+ */
+
+import type { AskUserQuestionAnswer } from '@deepseek-ai/dsh-user-interaction/types'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+
+/**
+ * Question answer payload (the result.value slot of a client-response):
+ * answers one ask() as a whole batch (core: one ask, many questions, one
+ * answer — never split per question).
+ */
+export interface QuestionResponsePayload {
+  sessionId: SessionId
+  answer: AskUserQuestionAnswer
+}

packages/host/apiproxy/src/api/rpc-map.ts

@@ -0,0 +1,26 @@
+/**
+ * RPC method registry and signature-derived generics. The map
+ * registers only client-request methods (respond is a client-response, so it is absent);
+ * map keys are the wire path segments (POST /api/session.list).
+ */
+
+import type { SessionsApi } from './sessions.ts'
+import type { HostApi } from './host.ts'
+import type { RpcResponse } from './rpc.ts'
+
+/** Method name → method signature. Signatures are the single source of truth; payload/value types are always derived from here. */
+export interface RpcMethodMap {
+  'session.list': SessionsApi['list']
+  'session.create': SessionsApi['create']
+  'session.history': SessionsApi['history']
+  'session.prompt': SessionsApi['prompt']
+  'session.cancel': SessionsApi['cancel']
+  'host.describe': HostApi['describe']
+}
+
+/** Business request payload of method K (reaches through the RpcRequest narrow form to payload). */
+export type RequestPayload<K extends keyof RpcMethodMap> = Parameters<RpcMethodMap[K]>[0]['payload']
+
+/** Business return value of method K (reaches through the RpcResponse narrow form to infer the ok value of result). */
+export type ResponseValue<K extends keyof RpcMethodMap> =
+  Awaited<ReturnType<RpcMethodMap[K]>> extends RpcResponse<infer T> ? T : never

packages/host/apiproxy/src/api/rpc.schema.ts

@@ -0,0 +1,97 @@
+/**
+ * Message-layer zod schemas: the four wire full forms + error body +
+ * carrier receipt. The payload slot is unknown in the full-form schemas — business payloads
+ * get a second parse dispatched by method (two-level parse discipline).
+ * Brand cast point: rpcIdSchema, and only there.
+ */
+
+import { z } from 'zod'
+import type { z as zCore } from 'zod'
+type ZodIssue = zCore.core.$ZodIssue
+import type { ClientRequest, ClientResponse, RpcError, RpcId, RpcReceipt, ServerRequest, ServerResponse } from './rpc.ts'
+
+/**
+ * Wire widening of a contract type: widens every property (deeply) to `original | undefined`.
+ * The repo enables exactOptionalPropertyTypes while zod `.optional()` outputs `T | undefined`,
+ * so `satisfies z.ZodType<ContractType>` is unusable across the board; anchoring is always
+ * written `satisfies z.ZodType<Wire<ContractType>>` — the widening only adds undefined, so
+ * missing fields / wrong types still fail to compile. On the JSON wire, "absent" and
+ * "value undefined" serialize identically, so the widening loses no validation semantics.
+ */
+export type Wire<T> = T extends readonly (infer E)[] ? Wire<E>[]
+  : T extends object ? { [K in keyof T]: Wire<T[K]> | undefined }
+    : T
+
+/**
+ * RpcId: one brand cast after shape validation (the only cast point in this
+ * file). No min-length: the id is an opaque echo token, and rejecting shapes
+ * here would only turn a correlatable error report into a client-side parse
+ * failure (the handler substitutes a sentinel when a request's id is unreadable).
+ */
+export const rpcIdSchema = z.string() as unknown as z.ZodType<RpcId>
+
+/** Error body: discriminated by code, per-branch details aligned to RpcErrorDetailsMap; details is required. */
+export const rpcErrorSchema: z.ZodType<RpcError> = z.discriminatedUnion('code', [
+  z.object({ code: z.literal('bad-request'), message: z.string(), details: z.object({ issues: z.array(z.custom<ZodIssue>()) }) }),
+  z.object({ code: z.literal('session-not-found'), message: z.string(), details: z.object({ sessionId: z.string() }) }),
+  z.object({ code: z.literal('agent-busy'), message: z.string(), details: z.object({ reason: z.string() }) }),
+  z.object({ code: z.literal('internal'), message: z.string(), details: z.object({}) }),
+]) as unknown as z.ZodType<RpcError>
+
+/**
+ * Business success/failure result schema (generic, reusable).
+ * @param value - Schema for the business value.
+ * @returns Schema for RpcResult<T>.
+ */
+export function rpcResultSchema<T>(value: z.ZodType<T>): z.ZodUnion<readonly [z.ZodType, z.ZodType]> {
+  return z.union([
+    z.object({ ok: z.literal(true), value }),
+    z.object({ ok: z.literal(false), error: rpcErrorSchema }),
+  ])
+}
+
+// ---- The four wire full-form schemas (payload/result.value slots stay wide — business layer does the second parse) ----
+
+/** ClientRequest full form (payload stays wide — the business layer runs the second parse). */
+export const clientRequestSchema = z.object({
+  type: z.literal('client-request'),
+  rpcId: rpcIdSchema,
+  method: z.string(),
+  payload: z.unknown(),
+}) as unknown as z.ZodType<ClientRequest>
+
+/** ServerResponse full form (result.value stays wide). */
+export const serverResponseSchema = z.object({
+  type: z.literal('server-response'),
+  rpcId: rpcIdSchema,
+  result: rpcResultSchema(z.unknown()),
+}) as unknown as z.ZodType<ServerResponse>
+
+/** ServerRequest full form (payload stays wide). */
+export const serverRequestSchema = z.object({
+  type: z.literal('server-request'),
+  rpcId: rpcIdSchema,
+  method: z.string(),
+  payload: z.unknown(),
+}) as unknown as z.ZodType<ServerRequest>
+
+/** ClientResponse full form (result.value stays wide). */
+export const clientResponseSchema = z.object({
+  type: z.literal('client-response'),
+  rpcId: rpcIdSchema,
+  result: rpcResultSchema(z.unknown()),
+}) as unknown as z.ZodType<ClientResponse>
+
+/** Wire full-form union (discriminated by type). */
+export const rpcMessageSchema = z.discriminatedUnion('type', [
+  clientRequestSchema as unknown as z.ZodObject<z.ZodRawShape>,
+  serverResponseSchema as unknown as z.ZodObject<z.ZodRawShape>,
+  serverRequestSchema as unknown as z.ZodObject<z.ZodRawShape>,
+  clientResponseSchema as unknown as z.ZodObject<z.ZodRawShape>,
+])
+
+/** Carrier receipt schema. */
+export const rpcReceiptSchema = z.union([
+  z.object({ accepted: z.literal(true) }),
+  z.object({ accepted: z.literal(false), reason: z.union([z.literal('not-pending'), z.literal('bad-response')]) }),
+]) satisfies z.ZodType<Wire<RpcReceipt>>

packages/host/apiproxy/src/api/rpc.ts

@@ -0,0 +1,113 @@
+/**
+ * Four-quadrant RPC message model. Channels and messages are
+ * decoupled: HTTP is the client→server physical channel, SSE the server→client one; logical
+ * messages are channel-independent, and the wire full form is a four-member discriminated union.
+ * api/ contract layer: zero Node dependencies, importable from the browser.
+ */
+
+import type { z as zCore } from 'zod'
+type ZodIssue = zCore.core.$ZodIssue
+import type { Branded } from '@deepseek-ai/dsh-brand'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+
+/**
+ * Message correlation id: the initiator mints it on a request; a response
+ * echoes the matching request's rpcId and never mints a new one.
+ */
+export type RpcId = Branded<'rpc-id'>
+
+/**
+ * Brands a string as RpcId (same precedent as core `SessionId()`). Minted by the initiator:
+ * client-request → client mints; server-request → host mints (answerable frames get a stable
+ * logical id, pure pushes mint a fresh one each time).
+ * @param id - Raw id string (implementations mint UUIDs; tests may pass fixtures).
+ * @returns The same string, branded (compile-time cast, zero runtime cost).
+ */
+export function RpcId(id: string): RpcId {
+  return id as RpcId
+}
+
+/** Error code → details type map (a second table isomorphic to RpcMethodMap). New code = one row here + one branch in the error schema. */
+export interface RpcErrorDetailsMap {
+  'bad-request': { issues: ZodIssue[] }
+  'session-not-found': { sessionId: SessionId }
+  'agent-busy': { reason: string }
+  'internal': {}
+}
+
+/** Closed error-code union (the keys of RpcErrorDetailsMap). */
+export type RpcErrorCode = keyof RpcErrorDetailsMap
+
+/**
+ * Distributive union expanded from the map: code is the discriminant, so
+ * `switch (error.code)` narrows details. details is required (internal uses an explicit {}).
+ */
+export type RpcError = {
+  [C in RpcErrorCode]: { code: C; message: string; details: RpcErrorDetailsMap[C] }
+}[RpcErrorCode]
+
+/** Business success/failure result: the result slot of a unary response; methods never throw business errors. */
+export type RpcResult<T> = { ok: true; value: T } | { ok: false; error: RpcError }
+
+/**
+ * Signature-layer narrow form, request side (domain-interface view, shared by
+ * both directions): rpcId is explicit in the signature, never mixed into the
+ * business payload; the type tag and method are filled in by the carrier layer.
+ */
+export interface RpcRequest<P> {
+  rpcId: RpcId
+  payload: P
+}
+
+/** Signature-layer narrow form, response side: rpcId always echoes the matching request. */
+export interface RpcResponse<T> {
+  rpcId: RpcId
+  result: RpcResult<T>
+}
+
+// ---- Wire full forms: four named members of a discriminated union (discriminant = the four `type` literals) ----
+
+/** Call initiated by the client (wire carrier: POST /api/<method> body). */
+export interface ClientRequest {
+  type: 'client-request'
+  rpcId: RpcId
+  method: string
+  payload: unknown
+}
+
+/** Response to a ClientRequest (wire carrier: the HTTP response body of that POST); rpcId echoed. */
+export interface ServerResponse {
+  type: 'server-response'
+  rpcId: RpcId
+  result: RpcResult<unknown>
+}
+
+/**
+ * Message initiated by the server (wire carrier: SSE frame). Answerable interactions
+ * (approval/question requested — stable rpcId, reused on replay) and pure pushes
+ * (session/event etc. — rpcId identifies that one push) share this shape; whether a
+ * response is expected is determined statically by method (a strict dichotomy, no third kind).
+ */
+export interface ServerRequest {
+  type: 'server-request'
+  rpcId: RpcId
+  method: string
+  payload: unknown
+}
+
+/** Response to a ServerRequest (wire carrier: POST /api/respond body); rpcId echoed, never minted anew. */
+export interface ClientResponse {
+  type: 'client-response'
+  rpcId: RpcId
+  result: RpcResult<unknown>
+}
+
+/** Authoritative wire full-form union; narrow via `switch (message.type)`. */
+export type RpcMessage = ClientRequest | ServerResponse | ServerRequest | ClientResponse
+
+/**
+ * Carrier receipt (not an RpcMessage — it belongs to the carrier layer, same
+ * discipline as "HTTP status describes only the carrier"): the HTTP response
+ * body of the POST carrying a client-response. Late/duplicate responses yield not-pending.
+ */
+export type RpcReceipt = { accepted: true } | { accepted: false; reason: 'not-pending' | 'bad-response' }

packages/host/apiproxy/src/api/sessions.schema.ts

@@ -0,0 +1,110 @@
+/**
+ * sessions domain zod schemas (names derived from map keys: sessionListRequestSchema /
+ * sessionListValueSchema). SessionEvent passthrough = strict envelope (type/seq/time) + wide
+ * data: the merge-extensible event surface keeps an unknown-type branch at the union level,
+ * with no field-level passthrough. SessionId brand cast point: sessionIdSchema, and only there.
+ */
+
+import { z } from 'zod'
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
+import type { RequestPayload, ResponseValue } from './rpc-map.ts'
+import type { Wire } from './rpc.schema.ts'
+import type { HistoryEntry, SessionSummary } from './sessions.ts'
+import type { ToolEventView } from './events.ts'
+
+/** SessionId: one brand cast after shape validation (the only cast point in this domain). */
+export const sessionIdSchema = z.string().min(1) as unknown as z.ZodType<SessionId>
+
+/** SessionEvent passthrough: strict envelope, wide data (the client fold handles unknown types via its documented default). */
+export const sessionEventSchema = z.object({
+  type: z.string(),
+  seq: z.number().int().nonnegative(),
+  time: z.number(),
+  data: z.unknown(),
+  sourceEventSeqs: z.array(z.number()).optional(),
+  surfaceOp: z.unknown().optional(),
+}) as unknown as z.ZodType<SessionEvent>
+
+/** SessionSummary row of session.list. */
+export const sessionSummarySchema = z.object({
+  sessionId: sessionIdSchema,
+  updatedAt: z.number(),
+  running: z.boolean(),
+  parentSessionId: sessionIdSchema.optional(),
+  cwd: z.string().optional(),
+}) satisfies z.ZodType<Wire<SessionSummary>>
+
+/** session.list request payload (cursor is a reserved seat, unimplemented in v1). */
+export const sessionListRequestSchema = z.object({
+  cursor: z.string().optional(),
+}) satisfies z.ZodType<Wire<RequestPayload<'session.list'>>>
+
+/** session.list response value. */
+export const sessionListValueSchema = z.object({
+  items: z.array(sessionSummarySchema),
+}) satisfies z.ZodType<Wire<ResponseValue<'session.list'>>>
+
+/** session.create request payload. */
+export const sessionCreateRequestSchema = z.object({
+  cwd: z.string().optional(),
+}) satisfies z.ZodType<Wire<RequestPayload<'session.create'>>>
+
+/** session.create response value. */
+export const sessionCreateValueSchema = z.object({
+  sessionId: sessionIdSchema,
+}) satisfies z.ZodType<Wire<ResponseValue<'session.create'>>>
+
+/** session.history request payload (beforeSeq/maxMessages page backwards from the window tail). */
+export const sessionHistoryRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+  beforeSeq: z.number().int().nonnegative().optional(),
+  maxMessages: z.number().int().positive().optional(),
+}) satisfies z.ZodType<Wire<RequestPayload<'session.history'>>>
+
+/**
+ * ToolEventView passthrough: lock only the `for` discriminant and the presence
+ * of a card-tagged `view` object. The view interior is a host-computed product
+ * the client reads without echoing back; deep-validating it would hand-copy
+ * the dsh-tools vocabulary into this schema and drift with it.
+ */
+export const toolEventViewSchema = z.discriminatedUnion('for', [
+  z.object({ for: z.literal('call'), view: z.looseObject({ card: z.string() }) }),
+  z.object({ for: z.literal('result'), view: z.looseObject({ card: z.string() }) }),
+]) as unknown as z.ZodType<ToolEventView>
+
+/** One session.history item: the session event plus its optional host-computed tool view. */
+export const historyEntrySchema = z.object({
+  event: sessionEventSchema,
+  view: toolEventViewSchema.optional(),
+}) satisfies z.ZodType<Wire<HistoryEntry>>
+
+/** session.history response value. */
+export const sessionHistoryValueSchema = z.object({
+  events: z.array(historyEntrySchema),
+  hasMore: z.boolean(),
+}) satisfies z.ZodType<Wire<ResponseValue<'session.history'>>>
+
+/** ContentBlock passthrough: core is merge-extensible — the type discriminant envelope is strict, the rest stays wide. */
+export const contentBlockSchema = z.looseObject({ type: z.string() })
+
+/** session.prompt request payload. */
+export const sessionPromptRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+  mode: z.union([z.literal('queue'), z.literal('steer')]),
+  content: z.array(contentBlockSchema),
+}) as unknown as z.ZodType<RequestPayload<'session.prompt'>>
+
+/** session.prompt response value. */
+export const sessionPromptValueSchema = z.object({
+  accepted: z.literal(true),
+}) satisfies z.ZodType<Wire<ResponseValue<'session.prompt'>>>
+
+/** session.cancel request payload. */
+export const sessionCancelRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+}) satisfies z.ZodType<Wire<RequestPayload<'session.cancel'>>>
+
+/** session.cancel response value. */
+export const sessionCancelValueSchema = z.object({
+  accepted: z.literal(true),
+}) satisfies z.ZodType<Wire<ResponseValue<'session.cancel'>>>

packages/host/apiproxy/src/api/sessions.ts

@@ -0,0 +1,73 @@
+/**
+ * sessions domain contract. Method signatures are the source of truth:
+ * unary methods take the RpcRequest<P> narrow form and the impl echoes rpcId; everything
+ * else references RequestPayload<'session.*'> / ResponseValue<'session.*'>.
+ */
+
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
+import type { RpcId, RpcRequest, RpcResponse } from './rpc.ts'
+import type { ToolEventView } from './events.ts'
+
+declare module '@deepseek-ai/dsh-llm' {
+  interface MessageSourceMap {
+    /**
+     * The prompt's rpcId is passed through MessageSource into the `user/message` event
+     * (the client uses it to reconcile the optimistically
+     * echoed provisional message with the event stream). kind stays `'user'` — the model face
+     * carries no transport vocabulary; rpcId is an extra durable-JSON field passed back to the client with the event.
+     */
+    'user-rpc': { kind: 'user'; rpcId: RpcId }
+  }
+}
+
+/**
+ * One history page entry: the raw event plus the optional host-computed render
+ * intent (same semantics as the mux frame's `view` slot — a pagination-time
+ * derivation, never persisted).
+ */
+export interface HistoryEntry {
+  event: SessionEvent
+  view?: ToolEventView
+}
+
+/** Session list entry (v1 builds no index: list does readdir+stat). */
+export interface SessionSummary {
+  sessionId: SessionId
+  /** Persisted file mtime. */
+  updatedAt: number
+  /** Status of the attached agent; always false for cold (unattached) sessions. */
+  running: boolean
+  /** fork/spawn lineage (session.header.parentSession passthrough); absent for root sessions. */
+  parentSessionId?: SessionId
+  /** Session working directory (header.cwd passthrough); absent when unrecorded. */
+  cwd?: string
+}
+
+/** Session-domain unary methods (the map keys session.* of RpcMethodMap). */
+export interface SessionsApi {
+  /** Lists persisted sessions (updatedAt descending). v1 returns everything; cursor is a reserved seat, unimplemented. */
+  list(request: RpcRequest<{ cursor?: string }>): Promise<RpcResponse<{ items: SessionSummary[] }>>
+
+  /** Creates a new session (and its agent, idle and standing by). */
+  create(request: RpcRequest<{ cwd?: string }>): Promise<RpcResponse<{ sessionId: SessionId }>>
+
+  /**
+   * Reads a window of history events; page boundaries align to message boundaries: one page =
+   * all raw events owned by a whole number of messages (including their chunk / tool events),
+   * never cut mid-message. The tail page (beforeSeq absent) additionally carries the in-flight
+   * partial — chunk events already emitted for the last unfinalized message.
+   * Each entry pairs the raw SessionEvent with the host-computed view (tool events whose
+   * presenter produced one, evaluated against the registry at pagination time); the client
+   * rebuilds the surface from the events with the shared fold.
+   */
+  history(request: RpcRequest<{ sessionId: SessionId; beforeSeq?: number; maxMessages?: number }>):
+  Promise<RpcResponse<{ events: HistoryEntry[]; hasMore: boolean }>>
+
+  /** Sends a message. content is core's ContentBlock[] verbatim; mode maps 1:1 — queue→send, steer→steer. */
+  prompt(request: RpcRequest<{ sessionId: SessionId; mode: 'queue' | 'steer'; content: ContentBlock[] }>):
+  Promise<RpcResponse<{ accepted: true }>>
+
+  /** Stops: clears both FIFOs + aborts the current step (1:1 with agent.cancel). */
+  cancel(request: RpcRequest<{ sessionId: SessionId }>): Promise<RpcResponse<{ accepted: true }>>
+}

packages/host/apiproxy/src/fetch/client.ts

@@ -0,0 +1,302 @@
+/**
+ * Client side of the fetch carrier. AbstractApiClient holds every protocol invariant: rpcId minting,
+ * four-quadrant envelope wrap/unwrap, zod parsing, SSE frame decoding, and the payload-direct
+ * IApiClient domain methods (business code never mints). Platform differences ride two aspects:
+ * abstract doFetch (transport) + overridable onEnvelope (tap). ApiProxy (the impl face) is untouched.
+ */
+
+import type { z } from 'zod'
+import type { ApiProxy, HostFrame, MuxFrame } from '../api/index.ts'
+import type { RequestPayload, ResponseValue, RpcMethodMap } from '../api/rpc-map.ts'
+import type { ClientRequest, ClientResponse, RpcMessage, RpcReceipt, RpcRequest, RpcResponse, ServerRequest } from '../api/rpc.ts'
+import { RpcId } from '../api/rpc.ts'
+import type { Wire } from '../api/rpc.schema.ts'
+import { rpcReceiptSchema, serverRequestSchema, serverResponseSchema } from '../api/rpc.schema.ts'
+import { hostFrameSchema, muxFrameSchema } from '../api/events.schema.ts'
+import { hostDescribeValueSchema } from '../api/host.schema.ts'
+import {
+  sessionCancelValueSchema,
+  sessionCreateValueSchema,
+  sessionHistoryValueSchema,
+  sessionListValueSchema,
+  sessionPromptValueSchema,
+} from '../api/sessions.schema.ts'
+
+/**
+ * Client consumption face of the contract (shape a): same domain tree as ApiProxy, but unary
+ * methods take the business payload directly — the carrier mints the rpcId and wraps the
+ * envelope. Business code needing the call's rpcId reads it from the RpcResponse echo.
+ * Unary methods and respond accept an optional external AbortSignal as the last parameter
+ * (merged with the instance timeout via AbortSignal.any; same "signal rides beside the
+ * request, never on the wire" discipline as the stream signatures).
+ * Stream methods accept an optional onOpen callback: it fires once the SSE transport is
+ * readable (response headers received, before any frame) — the "stream established" signal
+ * connection controllers need for the readiness handshake. Generators are lazy, so the
+ * underlying fetch (and therefore onOpen) only happens once iteration starts.
+ * Relationship: ApiProxy is the narrow-form signature contract the impl side implements;
+ * IApiClient is the payload-direct view clients consume; AbstractApiClient bridges the two.
+ * Derived per method key from RpcMethodMap so a map row addition updates this mechanically.
+ */
+export interface IApiClient {
+  sessions: {
+    list(payload: RequestPayload<'session.list'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.list'>>>
+    create(payload: RequestPayload<'session.create'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.create'>>>
+    history(payload: RequestPayload<'session.history'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.history'>>>
+    prompt(payload: RequestPayload<'session.prompt'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.prompt'>>>
+    cancel(payload: RequestPayload<'session.cancel'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.cancel'>>>
+  }
+  host: {
+    describe(payload: RequestPayload<'host.describe'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.describe'>>>
+  }
+  events: {
+    mux(payload: Parameters<ApiProxy['events']['mux']>[0]['payload'], signal: AbortSignal, onOpen?: () => void): AsyncIterable<RpcRequest<MuxFrame>>
+    host(payload: Parameters<ApiProxy['events']['host']>[0]['payload'], signal: AbortSignal, onOpen?: () => void): AsyncIterable<RpcRequest<HostFrame>>
+  }
+  /** client-response passthrough (rpcId is a backfill of the server-request's id — never minted here). */
+  respond(message: ClientResponse, signal?: AbortSignal): Promise<RpcReceipt>
+}
+
+/**
+ * S→C second-level parse table: value schema by method (the response-path
+ * mirror of the handler's request table; key coverage compiler-enforced against RpcMethodMap).
+ */
+const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType<Wire<ResponseValue<K>>> } = {
+  'session.list': sessionListValueSchema,
+  'session.create': sessionCreateValueSchema,
+  'session.history': sessionHistoryValueSchema,
+  'session.prompt': sessionPromptValueSchema,
+  'session.cancel': sessionCancelValueSchema,
+  'host.describe': hostDescribeValueSchema,
+}
+
+/** Default unary timeout (rpc-compare 2026-07-19: a hung host must not leave callers pending forever). */
+const DEFAULT_TIMEOUT_MS = 30_000
+
+/** URL base for in-process handler injection (fake authority, opencode precedent). */
+const INTERNAL_BASE = 'http://dsh.internal'
+
+/**
+ * Abstract fetch-carrier client. Subclasses supply the transport (doFetch) and may refine the
+ * per-message tap (onEnvelope) — platform aspects stay in subclasses, protocol invariants stay
+ * here. Envelope observation is a first-class aspect of this data middle layer: the instance
+ * owns a microtask-batched buffer (frame storms must not cost one consumer update per frame),
+ * and observers subscribe via subscribeEnvelopes. The isomorphic point survives: an in-process
+ * subclass whose doFetch is toFetchHandler(api).fetch never touches the network.
+ */
+export abstract class AbstractApiClient implements IApiClient {
+  /** Instance-owned observation buffer (module-level state would leak across instances/tests). */
+  private envelopeBatch: RpcMessage[] = []
+  private flushScheduled = false
+  private readonly envelopeListeners = new Set<(batch: readonly RpcMessage[]) => void>()
+
+  /** @param timeoutMs - unary timeout; streams never time out (long-lived by nature). */
+  constructor(protected readonly timeoutMs: number = DEFAULT_TIMEOUT_MS) {}
+
+  /** Transport aspect: browser fetch, injected handler.fetch, IPC bridge, ... */
+  protected abstract doFetch(input: URL, init?: RequestInit): Promise<Response>
+
+  /**
+   * Subscribe to batched envelope observation (diagnostics/logging consumers).
+   * Batches follow microtask boundaries; a listener throw is isolated (observation
+   * must never break the carrier).
+   * @param listener - receives each flushed batch in arrival order.
+   * @returns unsubscribe function.
+   */
+  subscribeEnvelopes(listener: (batch: readonly RpcMessage[]) => void): () => void {
+    this.envelopeListeners.add(listener)
+    return () => {
+      this.envelopeListeners.delete(listener)
+    }
+  }
+
+  /** Per-message tap: feeds the instance buffer. Subclasses may override to observe unbatched (call super to keep batching). */
+  protected onEnvelope(message: RpcMessage): void {
+    if (this.envelopeListeners.size === 0) return
+    this.envelopeBatch.push(message)
+    if (this.flushScheduled) return
+    this.flushScheduled = true
+    queueMicrotask(() => {
+      this.flushScheduled = false
+      // Never empty here: a flush is only ever scheduled by the push above,
+      // and this callback is the sole drain point.
+      const batch = this.envelopeBatch
+      this.envelopeBatch = []
+      for (const notify of this.envelopeListeners) {
+        try {
+          notify(batch)
+        } catch (error) {
+          console.error('[apiproxy] envelope listener threw:', error)
+        }
+      }
+    })
+  }
+
+  /** Browser = same-origin (a fake authority would fail DNS on real requests); no-location env (Node) = fake authority. */
+  protected resolveBase(): string {
+    const loc = (globalThis as { location?: { origin?: string } }).location
+    return loc?.origin !== undefined && loc.origin !== 'null' ? loc.origin : INTERNAL_BASE
+  }
+
+  protected mintRpcId(): RpcId {
+    // crypto.randomUUID is a Web API (browser + Node ≥19): keeps this base platform-neutral.
+    return RpcId(crypto.randomUUID())
+  }
+
+  /**
+   * Shared POST leg of both C→S carriers (callUnary/respond): JSON body,
+   * timeout merged with the caller's optional external signal, non-2xx → transport throw.
+   */
+  private async postJson(path: string, body: ClientRequest | ClientResponse, signal: AbortSignal | undefined): Promise<Response> {
+    const timeout = AbortSignal.timeout(this.timeoutMs)
+    const response = await this.doFetch(new URL(path, this.resolveBase()), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: signal === undefined ? timeout : AbortSignal.any([timeout, signal]),
+    })
+    if (!response.ok) throw new Error(`transport failure for ${path}: HTTP ${response.status}`)
+    return response
+  }
+
+  /**
+   * Unary protocol path: mint → tap → POST full form → envelope parse → verify
+   * echo → value parse → tap → narrow. Virtual so a fake carrier (fixture) can
+   * override transport at this layer.
+   */
+  protected async callUnary<K extends keyof RpcMethodMap>(
+    method: K,
+    payload: RequestPayload<K>,
+    signal?: AbortSignal,
+  ): Promise<RpcResponse<ResponseValue<K>>> {
+    const message: ClientRequest = { type: 'client-request', rpcId: this.mintRpcId(), method, payload }
+    this.onEnvelope(message)
+    const response = await this.postJson(`/api/${method}`, message, signal)
+    const full = serverResponseSchema.parse(await response.json())
+    this.onEnvelope(full)
+    if (full.rpcId !== message.rpcId) throw new Error(`rpcId mismatch for ${method}: sent ${message.rpcId}, got ${full.rpcId}`)
+    if (!full.result.ok) return { rpcId: full.rpcId, result: full.result }
+    // Second-level S→C parse: the ok value must match the method's Value schema (mirror of the
+    // handler's request-payload parse). The cast collapses the Wire<> widening, same as the handler side.
+    const value = UNARY_VALUE_SCHEMAS[method].parse(full.result.value) as ResponseValue<K>
+    return { rpcId: full.rpcId, result: { ok: true, value } }
+  }
+
+  /** Mux stream opener; virtual for the same override reason as callUnary. */
+  protected openMux(_payload: Parameters<ApiProxy['events']['mux']>[0]['payload'], signal: AbortSignal, onOpen?: () => void): AsyncIterable<RpcRequest<MuxFrame>> {
+    return this.readSse('/api/events.mux', signal, muxFrameSchema, onOpen)
+  }
+
+  /** Host stream opener; virtual. */
+  protected openHost(_payload: Parameters<ApiProxy['events']['host']>[0]['payload'], signal: AbortSignal, onOpen?: () => void): AsyncIterable<RpcRequest<HostFrame>> {
+    return this.readSse('/api/events.host', signal, hostFrameSchema, onOpen)
+  }
+
+  /**
+   * SSE protocol path: streaming fetch (not EventSource), '\n\n' framing, ServerRequest envelope +
+   * frame-schema parse, tap, narrow yield. onOpen fires once the response headers are in and the
+   * body is readable — the stream-established signal, before any frame arrives. A frame that fails
+   * either parse level is reported and skipped (one corrupt frame must not kill the stream; the
+   * client's gap detection covers whatever the frame carried).
+   */
+  protected async *readSse<F extends MuxFrame | HostFrame>(
+    path: string,
+    signal: AbortSignal,
+    frameSchema: z.ZodType<F>,
+    onOpen?: () => void,
+  ): AsyncGenerator<RpcRequest<F>> {
+    const response = await this.doFetch(new URL(path, this.resolveBase()), { signal })
+    if (!response.ok || response.body === null) throw new Error(`transport failure for ${path}: HTTP ${response.status}`)
+    onOpen?.()
+    const reader = response.body.getReader()
+    const decoder = new TextDecoder()
+    let buffer = ''
+    try {
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) return
+        buffer += decoder.decode(value, { stream: true })
+        let boundary: number
+        while ((boundary = buffer.indexOf('\n\n')) !== -1) {
+          const chunk = buffer.slice(0, boundary)
+          buffer = buffer.slice(boundary + 2)
+          const data = chunk.split('\n').filter(line => line.startsWith('data: ')).map(line => line.slice(6)).join('')
+          if (data === '') continue
+          let full: ServerRequest
+          let frame: F
+          try {
+            full = serverRequestSchema.parse(JSON.parse(data))
+            frame = frameSchema.parse(full.payload)
+          } catch (error) {
+            console.error(`[apiproxy] dropping malformed SSE frame on ${path}:`, error)
+            continue
+          }
+          this.onEnvelope(full)
+          yield { rpcId: full.rpcId, payload: frame }
+        }
+      }
+    } finally {
+      await reader.cancel().catch(() => undefined)
+    }
+  }
+
+  // ---- IApiClient surface (arrow properties so destructured/passed references stay bound) ----
+
+  readonly sessions: IApiClient['sessions'] = {
+    list: (payload, signal) => this.callUnary('session.list', payload, signal),
+    create: (payload, signal) => this.callUnary('session.create', payload, signal),
+    history: (payload, signal) => this.callUnary('session.history', payload, signal),
+    prompt: (payload, signal) => this.callUnary('session.prompt', payload, signal),
+    cancel: (payload, signal) => this.callUnary('session.cancel', payload, signal),
+  }
+
+  readonly host: IApiClient['host'] = {
+    describe: (payload, signal) => this.callUnary('host.describe', payload, signal),
+  }
+
+  readonly events: IApiClient['events'] = {
+    mux: (payload, signal, onOpen) => this.openMux(payload, signal, onOpen),
+    host: (payload, signal, onOpen) => this.openHost(payload, signal, onOpen),
+  }
+
+  async respond(message: ClientResponse, signal?: AbortSignal): Promise<RpcReceipt> {
+    this.onEnvelope(message)
+    const response = await this.postJson('/api/respond', message, signal)
+    return rpcReceiptSchema.parse(await response.json())
+  }
+}
+
+/**
+ * In-process client over an injected fetch-shaped handler (the isomorphic point:
+ * `new InProcessApiClient(toFetchHandler(api))` never touches the network). Lives here because
+ * in-process injection is this package's own capability (handler and client are both local).
+ */
+export class InProcessApiClient extends AbstractApiClient {
+  constructor(private readonly handler: { fetch: typeof fetch }, timeoutMs?: number) {
+    super(timeoutMs)
+  }
+
+  /**
+   * Faithful to real fetch: reject on signal abort even when the in-process
+   * handler ignores the signal (a hung impl must not defeat timeout/cancel).
+   */
+  protected doFetch(input: URL, init?: RequestInit): Promise<Response> {
+    const signal = init?.signal ?? undefined
+    if (signal === undefined) return this.handler.fetch(input, init)
+    if (signal.aborted) return Promise.reject(abortError(signal))
+    return new Promise((resolve, reject) => {
+      const onAbort = (): void => { reject(abortError(signal)) }
+      signal.addEventListener('abort', onAbort, { once: true })
+      this.handler.fetch(input, init)
+        .then(resolve, reject)
+        .finally(() => { signal.removeEventListener('abort', onAbort) })
+    })
+  }
+}
+
+/** Mirror fetch's abort rejection: the signal's reason when present, else a DOMException-style AbortError. */
+function abortError(signal: AbortSignal): Error {
+  const reason: unknown = signal.reason
+  if (reason instanceof Error) return reason
+  if (typeof reason === 'string') return new Error(reason)
+  return new Error('This operation was aborted')
+}

packages/host/apiproxy/src/fetch/handler.ts

@@ -0,0 +1,197 @@
+/**
+ * Server side of the fetch carrier: maps an ApiProxy onto a pure
+ * WHATWG Request->Response function. Two-level parse: full form (type/rpcId/method +
+ * path==method) -> payload dispatched per method. HTTP status expresses only the carrier
+ * (404 unknown path / 400 non-JSON body / 500 handler crash); business errors are always
+ * 200 + ServerResponse.
+ */
+
+import { randomUUID } from 'node:crypto'
+import type { z } from 'zod'
+import type { ApiProxy, MuxFrame, HostFrame } from '../api/index.ts'
+import type { RequestPayload, ResponseValue, RpcMethodMap } from '../api/rpc-map.ts'
+import type { ClientRequest, RpcError, RpcRequest, RpcResponse, ServerRequest, ServerResponse } from '../api/rpc.ts'
+import { RpcId } from '../api/rpc.ts'
+import type { Wire } from '../api/rpc.schema.ts'
+import { clientRequestSchema, clientResponseSchema } from '../api/rpc.schema.ts'
+import {
+  sessionCancelRequestSchema,
+  sessionCreateRequestSchema,
+  sessionHistoryRequestSchema,
+  sessionListRequestSchema,
+  sessionPromptRequestSchema,
+} from '../api/sessions.schema.ts'
+import { hostDescribeRequestSchema } from '../api/host.schema.ts'
+
+/**
+ * Unary dispatch table, keyed by (and compiler-locked to) RpcMethodMap: a map row without a
+ * route row fails to compile, and each row's schema/invoke pair is checked against that row's
+ * payload type — a schema pasted onto the wrong row is a type error, not a runtime surprise.
+ * Schemas anchor to the Wire<> widening (the repo-wide exactOptionalPropertyTypes accommodation
+ * documented on Wire); the dispatch point carries the one Wire→exact cast.
+ */
+type UnaryRoutes = {
+  [K in keyof RpcMethodMap]: {
+    schema: z.ZodType<Wire<RequestPayload<K>>>
+    invoke(api: ApiProxy, request: RpcRequest<RequestPayload<K>>): Promise<RpcResponse<ResponseValue<K>>>
+  }
+}
+
+const UNARY_ROUTES: UnaryRoutes = {
+  'session.list': { schema: sessionListRequestSchema, invoke: (api, r) => api.sessions.list(r) },
+  'session.create': { schema: sessionCreateRequestSchema, invoke: (api, r) => api.sessions.create(r) },
+  'session.history': { schema: sessionHistoryRequestSchema, invoke: (api, r) => api.sessions.history(r) },
+  'session.prompt': { schema: sessionPromptRequestSchema, invoke: (api, r) => api.sessions.prompt(r) },
+  'session.cancel': { schema: sessionCancelRequestSchema, invoke: (api, r) => api.sessions.cancel(r) },
+  'host.describe': { schema: hostDescribeRequestSchema, invoke: (api, r) => api.host.describe(r) },
+}
+
+/** Route lookup that narrows an arbitrary path segment to a map key (single cast point for the string→key refinement). */
+function methodFor(path: string): keyof RpcMethodMap | undefined {
+  return Object.hasOwn(UNARY_ROUTES, path) ? path as keyof RpcMethodMap : undefined
+}
+
+/**
+ * Sentinel rpcId for error responses to envelopes whose own rpcId is unreadable: the response
+ * must still be a valid ServerResponse (a self-violating shape would turn the server's explicit
+ * bad-request report into a client-side parse failure). Fixed value, documented here as wire contract.
+ */
+const INVALID_REQUEST_RPC_ID = RpcId('invalid-request')
+
+/** Wrap a business error as a ServerResponse full form (rpcId backfilled; an unreadable rpcId uses the invalid-request sentinel). */
+function errorResponse(rpcId: RpcId, error: RpcError): Response {
+  const body: ServerResponse = { type: 'server-response', rpcId, result: { ok: false, error } }
+  return Response.json(body)
+}
+
+/** Complete the impl's narrow form into a ServerResponse full form. */
+function fullResponse(narrow: RpcResponse<unknown>): Response {
+  const body: ServerResponse = { type: 'server-response', rpcId: narrow.rpcId, result: narrow.result }
+  return Response.json(body)
+}
+
+/**
+ * Parse the payload and invoke one unary route. Generic over the map key so
+ * the row's schema/invoke pairing typechecks; the only cast collapses the
+ * Wire<> widening back to the exact payload (undefined-valued properties and
+ * absent ones are indistinguishable after JSON transport).
+ */
+// K appears once in the signature but ties the UNARY_ROUTES[K] row lookup to its own
+// schema/invoke pairing; a union parameter degrades the row to an uninvokable intersection.
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
+async function handleUnary<K extends keyof RpcMethodMap>(api: ApiProxy, method: K, message: ClientRequest): Promise<Response> {
+  const route = UNARY_ROUTES[method]
+  const payload = route.schema.safeParse(message.payload)
+  if (!payload.success) {
+    return errorResponse(message.rpcId, { code: 'bad-request', message: `invalid payload for ${method}`, details: { issues: payload.error.issues } })
+  }
+  try {
+    return fullResponse(await route.invoke(api, { rpcId: message.rpcId, payload: payload.data }))
+  } catch (error: unknown) {
+    // The impl never throws business errors; reaching here means the implementation itself crashed — 500, carrier layer.
+    return new Response(`handler failure: ${String(error)}`, { status: 500 })
+  }
+}
+
+/** SSE frame: complete the narrow RpcRequest<frame> into a ServerRequest full form (method = frame type). */
+function fullFrame(narrow: RpcRequest<MuxFrame | HostFrame>): ServerRequest {
+  return { type: 'server-request', rpcId: narrow.rpcId, method: narrow.payload.type, payload: narrow.payload }
+}
+
+/**
+ * Wrap a frame stream as an SSE Response; stops when req.signal aborts. An
+ * impl throw mid-stream emits one stream/error frame and then closes.
+ */
+function sseResponse(frames: AsyncIterable<RpcRequest<MuxFrame | HostFrame>>): Response {
+  const encoder = new TextEncoder()
+  const stream = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      try {
+        // Send an SSE comment line on open so clients/proxies see a live channel (the host
+        // stream has no baseline frames and would otherwise emit zero bytes while idle;
+        // a comment line is not a frame, so client frame parsing skips it naturally).
+        controller.enqueue(encoder.encode(': connected\n\n'))
+        for await (const narrow of frames) {
+          controller.enqueue(encoder.encode(`data: ${JSON.stringify(fullFrame(narrow))}\n\n`))
+        }
+      } catch (error: unknown) {
+        // Mid-stream impl failure → one stream/error frame, then close: the client must see
+        // the failure instead of a silent end (which reads as a normal disconnect). A fresh
+        // rpcId is minted — this is a server-initiated push like any other frame.
+        const failure: MuxFrame | HostFrame = { type: 'stream/error', error: { code: 'internal', message: String(error), details: {} } }
+        try {
+          controller.enqueue(encoder.encode(`data: ${JSON.stringify(fullFrame({ rpcId: RpcId(randomUUID()), payload: failure }))}\n\n`))
+        } catch {
+          // Consumer already cancelled the stream: enqueue-after-cancel is the
+          // only reachable error, and there is no one left to tell.
+        }
+      } finally {
+        try {
+          controller.close()
+        } catch { /* already cancelled by the consumer: a double close is the only reachable error */ }
+      }
+    },
+  })
+  return new Response(stream, {
+    headers: { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' },
+  })
+}
+
+/**
+ * Wraps an ApiProxy into a pure fetch function (isomorphic point: feed the returned fetch straight to InProcessApiClient).
+ * @param api - the host-side ApiProxy implementation.
+ * @returns an object holding `fetch(Request)`; paths outside /api/ return 404.
+ */
+export function toFetchHandler(api: ApiProxy): { fetch: typeof fetch } {
+  return {
+    // Signature matches global fetch: the isomorphic point hands this function to InProcessApiClient as its transport aspect,
+    // Clients call in (url, init) form — normalize to Request before handling.
+    async fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
+      const req = input instanceof Request ? input : new Request(input, init)
+      const url = new URL(req.url)
+      const path = url.pathname
+
+      if (path === '/api/events.mux' && req.method === 'GET') {
+        return sseResponse(api.events.mux({ rpcId: RpcId(randomUUID()), payload: {} }, req.signal))
+      }
+      if (path === '/api/events.host' && req.method === 'GET') {
+        return sseResponse(api.events.host({ rpcId: RpcId(randomUUID()), payload: {} }, req.signal))
+      }
+
+      if (req.method !== 'POST' || !path.startsWith('/api/')) {
+        return new Response('not found', { status: 404 })
+      }
+
+      let body: unknown
+      try {
+        body = await req.json()
+      } catch {
+        // 400 = carrier layer (body is not even JSON); valid JSON with a bad shape goes 200 + bad-request.
+        return new Response('body is not JSON', { status: 400 })
+      }
+
+      if (path === '/api/respond') {
+        const parsed = clientResponseSchema.safeParse(body)
+        if (!parsed.success) return Response.json({ accepted: false, reason: 'bad-response' })
+        return Response.json(await api.respond(parsed.data))
+      }
+
+      const method = methodFor(path.slice('/api/'.length))
+      if (method === undefined) return new Response('not found', { status: 404 })
+
+      const envelope = clientRequestSchema.safeParse(body)
+      if (!envelope.success) {
+        // Best effort at correlation: salvage a string rpcId from the raw body;
+        // otherwise the fixed sentinel keeps the response a valid ServerResponse.
+        const rawId = (body as { rpcId?: unknown } | null)?.rpcId
+        const rpcId = typeof rawId === 'string' ? RpcId(rawId) : INVALID_REQUEST_RPC_ID
+        return errorResponse(rpcId, { code: 'bad-request', message: 'invalid client-request message', details: { issues: envelope.error.issues } })
+      }
+      const message: ClientRequest = envelope.data
+      if (message.method !== method) {
+        return errorResponse(message.rpcId, { code: 'bad-request', message: `method "${message.method}" does not match path "${method}"`, details: { issues: [] } })
+      }
+      return handleUnary(api, method, message)
+    },
+  }
+}

packages/host/apiproxy/src/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @deepseek-ai/dsh-host-apiproxy — the front layer every client shape shares:
+ * the ApiProxy contract (api/: types + zod schemas, browser-safe) and the
+ * fetch carrier pair (fetch/: toFetchHandler on the host side, AbstractApiClient +
+ * platform subclasses on the client side). Host assembly (bootHost/createApiProxy/startHost)
+ * lives in @deepseek-ai/dsh-host-runtime.
+ */
+
+export type * from './api/index.ts'
+export { RpcId } from './api/rpc.ts'
+export { toFetchHandler } from './fetch/handler.ts'
+export { AbstractApiClient, InProcessApiClient } from './fetch/client.ts'
+export type { IApiClient } from './fetch/client.ts'

packages/host/apiproxy/src/invariant.ts

@@ -0,0 +1,33 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-host-apiproxy`.
+ * @module @deepseek-ai/dsh-host-apiproxy/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-host-apiproxy'
+
+/** Cordis companion plugin name. */
+export const name = 'host-apiproxy-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package is the wire contract layer (types,
+ * schemas, fetch carrier glue) — it emits no cordis events and owns no
+ * mutable cross-plugin relation. rpcId round-trip and schema acceptance are
+ * enforced at the carrier boundary and exercised by the protocol-isomorphism
+ * suite; the live implementation relations belong to dsh-host-runtime.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/host/apiproxy/tests/client-handler.spec.ts

@@ -0,0 +1,407 @@
+/**
+ * Wire-protocol coverage over the isomorphic point: InProcessApiClient →
+ * toFetchHandler(scripted impl) runs the real envelope wrap/unwrap, zod
+ * two-level parse, rpcId discipline, and SSE framing with no network and no
+ * browser. Each case scripts its own minimal ApiProxy.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+import type { ApiProxy, HostFrame, MuxFrame, RpcMessage, RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy'
+import { InProcessApiClient, RpcId, toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
+
+const sid = (id: string): SessionId => id as SessionId
+
+function ok<T>(request: RpcRequest<unknown>, value: T): Promise<RpcResponse<T>> {
+  return Promise.resolve({ rpcId: request.rpcId, result: { ok: true, value } })
+}
+
+/** Scripted impl: every method resolves an empty-ish OK unless a case overrides it. */
+function scriptedApi(overrides: {
+  sessions?: Partial<ApiProxy['sessions']>
+  host?: Partial<ApiProxy['host']>
+  events?: Partial<ApiProxy['events']>
+  respond?: ApiProxy['respond']
+} = {}): ApiProxy {
+  async function *empty<F>(): AsyncGenerator<RpcRequest<F>> { /* no frames */ }
+  return {
+    sessions: {
+      list: r => ok(r, { items: [] }),
+      create: r => ok(r, { sessionId: sid('s-new') }),
+      history: r => ok(r, { events: [], hasMore: false }),
+      prompt: r => ok(r, { accepted: true as const }),
+      cancel: r => ok(r, { accepted: true as const }),
+      ...overrides.sessions,
+    },
+    host: { describe: r => ok(r, { version: '0-test', cwd: '/t', attachedSessions: 0 }), ...overrides.host },
+    events: { mux: () => empty<MuxFrame>(), host: () => empty<HostFrame>(), ...overrides.events },
+    respond: overrides.respond ?? (() => Promise.resolve({ accepted: false as const, reason: 'not-pending' as const })),
+  }
+}
+
+function client(api: ApiProxy, timeoutMs?: number): InProcessApiClient {
+  return new InProcessApiClient(toFetchHandler(api), timeoutMs)
+}
+
+describe('unary round trip', () => {
+  it('carries payload out and value back through the full wire form', async () => {
+    let seen: RpcRequest<{ cursor?: string }> | undefined
+    const api = scriptedApi({
+      sessions: {
+        list: (r) => {
+          seen = r
+          return ok(r, { items: [{ sessionId: sid('s1'), updatedAt: 7, running: false }] })
+        },
+      },
+    })
+    const response = await client(api).sessions.list({ cursor: 'c1' })
+    // Impl received the narrow form with a minted id; client returned the same id and value.
+    expect(seen?.payload).toEqual({ cursor: 'c1' })
+    expect(seen?.rpcId).toBeTruthy()
+    expect(response.rpcId).toBe(seen?.rpcId)
+    expect(response.result).toEqual({ ok: true, value: { items: [{ sessionId: 's1', updatedAt: 7, running: false }] } })
+  })
+
+  it('passes business errors through as 200 + err result, not a throw', async () => {
+    const api = scriptedApi({
+      sessions: {
+        cancel: r => Promise.resolve({ rpcId: r.rpcId, result: { ok: false, error: { code: 'session-not-found', message: 'nope', details: { sessionId: sid('sx') } } } }),
+      },
+    })
+    const response = await client(api).sessions.cancel({ sessionId: sid('sx') })
+    expect(response.result).toEqual({ ok: false, error: { code: 'session-not-found', message: 'nope', details: { sessionId: 'sx' } } })
+  })
+
+  it('throws on rpcId echo mismatch', async () => {
+    const api = scriptedApi({
+      sessions: { list: () => Promise.resolve({ rpcId: RpcId('forged'), result: { ok: true, value: { items: [] } } }) },
+    })
+    await expect(client(api).sessions.list({})).rejects.toThrow(/rpcId mismatch/)
+  })
+
+  it('rejects an invalid payload at the handler as 200 + bad-request with issues', async () => {
+    const api = scriptedApi()
+    const response = await client(api).sessions.history({ sessionId: 123 as unknown as SessionId })
+    expect(response.result.ok).toBe(false)
+    if (!response.result.ok) {
+      expect(response.result.error.code).toBe('bad-request')
+      expect((response.result.error.details as { issues: unknown[] }).issues.length).toBeGreaterThan(0)
+    }
+  })
+
+  it('rejects a method/path mismatch as bad-request', async () => {
+    const handler = toFetchHandler(scriptedApi())
+    const body = { type: 'client-request', rpcId: 'r1', method: 'session.create', payload: {} }
+    const response = await handler.fetch('http://dsh.internal/api/session.list', { method: 'POST', body: JSON.stringify(body) })
+    expect(response.status).toBe(200)
+    const parsed = await response.json() as { result: { ok: boolean; error?: { code: string; message: string } } }
+    expect(parsed.result.ok).toBe(false)
+    expect(parsed.result.error?.code).toBe('bad-request')
+    expect(parsed.result.error?.message).toMatch(/does not match path/)
+  })
+
+  it('rejects a malformed envelope as bad-request, salvaging the rpcId or falling back to the sentinel', async () => {
+    const handler = toFetchHandler(scriptedApi())
+    // No salvageable rpcId → the fixed invalid-request sentinel keeps the response a valid ServerResponse.
+    const noId = await handler.fetch('http://dsh.internal/api/session.list', { method: 'POST', body: JSON.stringify({ nonsense: true }) })
+    expect(noId.status).toBe(200)
+    const noIdParsed = await noId.json() as { rpcId: string; result: { ok: boolean } }
+    expect(noIdParsed.result.ok).toBe(false)
+    expect(noIdParsed.rpcId).toBe('invalid-request')
+    // A string rpcId in the otherwise-bad body is salvaged for correlation.
+    const withId = await handler.fetch('http://dsh.internal/api/session.list', { method: 'POST', body: JSON.stringify({ rpcId: 'salvage-me', nonsense: true }) })
+    const withIdParsed = await withId.json() as { rpcId: string; result: { ok: boolean } }
+    expect(withIdParsed.result.ok).toBe(false)
+    expect(withIdParsed.rpcId).toBe('salvage-me')
+  })
+
+  it('maps carrier failures to HTTP statuses and the client throws transport failure', async () => {
+    const handler = toFetchHandler(scriptedApi())
+    // Unknown method → 404.
+    const notFound = await handler.fetch('http://dsh.internal/api/no.such', { method: 'POST', body: '{}' })
+    expect(notFound.status).toBe(404)
+    // Non-JSON body → 400.
+    const badBody = await handler.fetch('http://dsh.internal/api/session.list', { method: 'POST', body: '{oops' })
+    expect(badBody.status).toBe(400)
+    // Impl crash → 500, and through the client that is a throw, not an err result.
+    const crashing = scriptedApi({ sessions: { list: () => { throw new Error('impl exploded') } } })
+    await expect(client(crashing).sessions.list({})).rejects.toThrow(/transport failure .*500/)
+  })
+
+  it('rejects when the transport never resolves within timeoutMs', async () => {
+    // AbortSignal.timeout is immune to fake timers; a short real timeout keeps this fast.
+    const never = new InProcessApiClient({
+      fetch: (_i: RequestInfo | URL, init?: RequestInit) => new Promise<Response>((_resolve, reject) => {
+        init?.signal?.addEventListener('abort', () => { reject(new Error('aborted by timeout')) })
+      }),
+    }, 25)
+    await expect(never.sessions.list({})).rejects.toThrow()
+  })
+
+  it('aborts a unary call through the caller-supplied external signal', async () => {
+    // Real-fetch semantics: on abort the rejection is the signal's reason, and the abort
+    // works even when the transport ignores the signal entirely (hung impl).
+    const gate = new AbortController()
+    const hung = new InProcessApiClient({ fetch: () => new Promise<Response>(() => {}) }, 60_000)
+    const call = hung.sessions.list({}, gate.signal)
+    gate.abort(new Error('externally aborted'))
+    await expect(call).rejects.toThrow(/externally aborted/)
+  })
+
+  it('rejects an already-aborted signal before touching the transport, mapping a string reason to an Error', async () => {
+    let touched = false
+    const c = new InProcessApiClient({
+      fetch: () => {
+        touched = true
+        return Promise.resolve(new Response('{}'))
+      },
+    }, 60_000)
+    const gate = new AbortController()
+    gate.abort('gone before start')
+    await expect(c.sessions.list({}, gate.signal)).rejects.toThrow('gone before start')
+    expect(touched).toBe(false)
+  })
+
+  it('maps a non-Error, non-string abort reason to the default AbortError message', async () => {
+    const gate = new AbortController()
+    const hung = new InProcessApiClient({ fetch: () => new Promise<Response>(() => {}) }, 60_000)
+    const call = hung.sessions.list({}, gate.signal)
+    gate.abort(42)
+    await expect(call).rejects.toThrow('This operation was aborted')
+  })
+
+  it('passes a signal-less doFetch straight through to the handler', async () => {
+    class Probe extends InProcessApiClient {
+      direct(url: URL): Promise<Response> {
+        return this.doFetch(url)
+      }
+    }
+    const probe = new Probe({ fetch: () => Promise.resolve(new Response('raw')) })
+    const response = await probe.direct(new URL('http://dsh.internal/probe'))
+    expect(await response.text()).toBe('raw')
+  })
+
+  it('throws on an S→C ok value that fails the method value schema (second-level parse)', async () => {
+    // Impl echoes rpcId but returns a wrong-shaped value: envelope parse passes, value parse must reject.
+    const api = scriptedApi({
+      sessions: { list: r => Promise.resolve({ rpcId: r.rpcId, result: { ok: true, value: { items: 'not-an-array' } } }) as never },
+    })
+    await expect(client(api).sessions.list({})).rejects.toThrow()
+  })
+})
+
+describe('SSE stream path', () => {
+  it('yields frames in order and skips the comment preamble', async () => {
+    const frames: MuxFrame[] = [
+      { type: 'session/subscribed', sessionId: sid('s1'), lastSeq: 3 },
+      { type: 'stream/error', error: { code: 'internal', message: 'x', details: {} } },
+    ]
+    const api = scriptedApi({
+      events: {
+        async *mux(request) {
+          let n = 0
+          for (const frame of frames) yield { rpcId: RpcId(`push-${n++}-${request.rpcId}`), payload: frame }
+        },
+      },
+    })
+    const seen: MuxFrame[] = []
+    for await (const envelope of client(api).events.mux({}, new AbortController().signal)) {
+      seen.push(envelope.payload)
+    }
+    expect(seen).toEqual(frames)
+  })
+
+  it('reassembles frames across arbitrary chunk boundaries', async () => {
+    // Two SSE frames split so one frame spans chunks and one chunk carries parts of both.
+    const f1 = { type: 'server-request', rpcId: 'a', method: 'session/subscribed', payload: { type: 'session/subscribed', sessionId: 's1', lastSeq: 1 } }
+    const f2 = { type: 'server-request', rpcId: 'b', method: 'session/subscribed', payload: { type: 'session/subscribed', sessionId: 's2', lastSeq: 2 } }
+    const wire = `: connected\n\ndata: ${JSON.stringify(f1)}\n\ndata: ${JSON.stringify(f2)}\n\n`
+    const cuts = [5, 40, wire.indexOf('data: ', 40) + 3]
+    const encoder = new TextEncoder()
+    const doFetch = (): Promise<Response> => Promise.resolve(new Response(new ReadableStream<Uint8Array>({
+      start(controller) {
+        let prev = 0
+        for (const cut of [...cuts, wire.length]) {
+          controller.enqueue(encoder.encode(wire.slice(prev, cut)))
+          prev = cut
+        }
+        controller.close()
+      },
+    }), { status: 200 }))
+    const chopped = new InProcessApiClient({ fetch: doFetch })
+    const seen: string[] = []
+    for await (const envelope of chopped.events.mux({}, new AbortController().signal)) {
+      seen.push((envelope.payload as { sessionId: string }).sessionId)
+      expect(envelope.rpcId).toBe(seen.length === 1 ? 'a' : 'b')
+    }
+    expect(seen).toEqual(['s1', 's2'])
+  })
+
+  it('emits a stream/error frame then closes when the impl throws mid-stream', async () => {
+    const api = scriptedApi({
+      events: {
+        async *host(request): AsyncGenerator<RpcRequest<HostFrame>> {
+          yield { rpcId: RpcId(`p-${request.rpcId}`), payload: { type: 'host/session-added', sessionId: sid('s1') } }
+          throw new Error('impl died mid-stream')
+        },
+      },
+    })
+    const seen: HostFrame[] = []
+    for await (const envelope of client(api).events.host({}, new AbortController().signal)) {
+      seen.push(envelope.payload)
+    }
+    expect(seen.map(f => f.type)).toEqual(['host/session-added', 'stream/error'])
+    const last = seen.at(-1)
+    if (last?.type === 'stream/error') expect(last.error.message).toMatch(/impl died mid-stream/)
+  })
+
+  it('drops a malformed SSE frame and keeps the stream alive (S→C two-level parse)', async () => {
+    const good = { type: 'server-request', rpcId: 'g1', method: 'session/subscribed', payload: { type: 'session/subscribed', sessionId: 's1', lastSeq: 1 } }
+    const badEnvelope = { type: 'server-response', rpcId: 'x' } // wrong quadrant for a stream
+    const badFrame = { type: 'server-request', rpcId: 'b1', method: 'nope', payload: { type: 'no/such-frame' } }
+    const wire = [
+      'data: {oops', // not JSON
+      `data: ${JSON.stringify(badEnvelope)}`,
+      `data: ${JSON.stringify(badFrame)}`,
+      `data: ${JSON.stringify(good)}`,
+    ].map(l => `${l}\n\n`).join('')
+    const doFetch = (): Promise<Response> => Promise.resolve(new Response(new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode(wire))
+        controller.close()
+      },
+    }), { status: 200 }))
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    try {
+      const seen: MuxFrame[] = []
+      for await (const envelope of new InProcessApiClient({ fetch: doFetch }).events.mux({}, new AbortController().signal)) {
+        seen.push(envelope.payload)
+      }
+      // The three corrupt frames are reported and skipped; the good one still arrives.
+      expect(seen).toEqual([{ type: 'session/subscribed', sessionId: 's1', lastSeq: 1 }])
+      expect(errorSpy.mock.calls.length).toBe(3)
+    } finally {
+      errorSpy.mockRestore()
+    }
+  })
+
+  it('fires onOpen once headers are in, before the first frame, and not on transport failure', async () => {
+    const api = scriptedApi({
+      events: {
+        async *mux(request): AsyncGenerator<RpcRequest<MuxFrame>> {
+          yield { rpcId: RpcId(`p-${request.rpcId}`), payload: { type: 'session/subscribed', sessionId: sid('s1'), lastSeq: 0 } }
+        },
+      },
+    })
+    const order: string[] = []
+    const iterator = client(api).events.mux({}, new AbortController().signal, () => order.push('open'))
+    expect(order).toEqual([]) // lazy generator: no fetch (and no onOpen) before iteration
+    for await (const _ of iterator) order.push('frame')
+    expect(order).toEqual(['open', 'frame'])
+
+    // Transport failure path: onOpen must not fire.
+    const failing = new InProcessApiClient({ fetch: () => Promise.resolve(new Response('down', { status: 503 })) })
+    const failOrder: string[] = []
+    await expect((async () => {
+      for await (const _ of failing.events.mux({}, new AbortController().signal, () => failOrder.push('open'))) { /* unreachable */ }
+    })()).rejects.toThrow(/transport failure/)
+    expect(failOrder).toEqual([])
+  })
+
+  it('stops consuming when the caller aborts', async () => {
+    let implSawAbort = false
+    const api = scriptedApi({
+      events: {
+        async *mux(_request, signal): AsyncGenerator<RpcRequest<MuxFrame>> {
+          try {
+            let n = 0
+            while (true) {
+              yield { rpcId: RpcId(`p${n}`), payload: { type: 'session/subscribed', sessionId: sid('s1'), lastSeq: n++ } }
+              await new Promise(resolve => setTimeout(resolve, 5))
+              if (signal.aborted) return
+            }
+          } finally {
+            implSawAbort = true
+          }
+        },
+      },
+    })
+    const abort = new AbortController()
+    let count = 0
+    // In-process abort ends the stream (impl returns on signal.aborted); over a real
+    // network fetch the same abort surfaces as a rejection — both stop the loop.
+    await (async () => {
+      for await (const _ of client(api).events.mux({}, abort.signal)) {
+        if (++count === 2) abort.abort()
+      }
+    })().catch(() => undefined)
+    expect(count).toBe(2)
+    // Generator teardown may lag the abort by a microtask; poll briefly.
+    await vi.waitFor(() => { expect(implSawAbort).toBe(true) })
+  })
+})
+
+describe('respond path', () => {
+  it('round-trips a client-response to a receipt', async () => {
+    const seen: unknown[] = []
+    const api = scriptedApi({
+      respond: (message) => {
+        seen.push(message)
+        return Promise.resolve({ accepted: true as const })
+      },
+    })
+    const receipt = await client(api).respond({ type: 'client-response', rpcId: RpcId('req-1'), result: { ok: true, value: { behavior: 'allow' } } })
+    expect(receipt).toEqual({ accepted: true })
+    expect(seen).toEqual([{ type: 'client-response', rpcId: 'req-1', result: { ok: true, value: { behavior: 'allow' } } }])
+  })
+
+  it('returns bad-response for a malformed client-response without reaching the impl', async () => {
+    const respond = vi.fn()
+    const handler = toFetchHandler(scriptedApi({ respond }))
+    const response = await handler.fetch('http://dsh.internal/api/respond', { method: 'POST', body: JSON.stringify({ type: 'client-response' }) })
+    expect(await response.json()).toEqual({ accepted: false, reason: 'bad-response' })
+    expect(respond).not.toHaveBeenCalled()
+  })
+})
+
+describe('envelope tap', () => {
+  it('delivers one microtask batch of full forms per unary call', async () => {
+    const api = scriptedApi()
+    const tapped = client(api)
+    const batches: (readonly RpcMessage[])[] = []
+    tapped.subscribeEnvelopes(batch => batches.push(batch))
+    await tapped.sessions.list({})
+    await vi.waitFor(() => { expect(batches.length).toBeGreaterThan(0) })
+    const all = batches.flat()
+    expect(all.map(m => m.type)).toEqual(['client-request', 'server-response'])
+    expect(all[0]?.rpcId).toBe(all[1]?.rpcId)
+  })
+
+  it('isolates a throwing listener and keeps serving the call', async () => {
+    const api = scriptedApi()
+    const tapped = client(api)
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    try {
+      const good: string[] = []
+      tapped.subscribeEnvelopes(() => { throw new Error('listener bug') })
+      tapped.subscribeEnvelopes(batch => good.push(...batch.map(m => m.type)))
+      const response = await tapped.sessions.list({})
+      expect(response.result.ok).toBe(true)
+      await vi.waitFor(() => { expect(good).toContain('server-response') })
+    } finally {
+      errorSpy.mockRestore()
+    }
+  })
+
+  it('buffers nothing with zero subscribers and unsubscribes cleanly', async () => {
+    const api = scriptedApi()
+    const tapped = client(api)
+    await tapped.sessions.list({}) // no subscribers: must not accumulate
+    const batches: (readonly RpcMessage[])[] = []
+    const unsubscribe = tapped.subscribeEnvelopes(batch => batches.push(batch))
+    unsubscribe()
+    await tapped.sessions.list({})
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(batches).toEqual([])
+  })
+})

packages/host/apiproxy/tests/fetch-carrier.spec.ts

@@ -0,0 +1,305 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { ApiProxy, HostFrame, MuxFrame } from '../src/api/index.ts'
+import type { ClientResponse, RpcMessage, RpcReceipt, RpcRequest } from '../src/api/rpc.ts'
+import { RpcId } from '../src/api/rpc.ts'
+import { toFetchHandler } from '../src/fetch/handler.ts'
+import { AbstractApiClient, InProcessApiClient } from '../src/fetch/client.ts'
+
+/** Minimal in-memory ApiProxy: echoes rpcIds, scripts one frame per stream. */
+function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFrame[]; crashOn: string }> = {}): ApiProxy {
+  const muxFrames = overrides.muxFrames ?? [{ type: 'session/subscribed', sessionId: 's1' as never, lastSeq: -1 }]
+  const hostFrames = overrides.hostFrames ?? [{ type: 'host/session-removed', sessionId: 's1' as never }]
+  async function * stream<F>(frames: F[], signal: AbortSignal): AsyncGenerator<RpcRequest<F>> {
+    for (const payload of frames) {
+      if (signal.aborted) return
+      yield { rpcId: RpcId(`frame-${String(frames.indexOf(payload))}`), payload }
+    }
+  }
+  return {
+    sessions: {
+      async list(request) {
+        if (overrides.crashOn === 'session.list') throw new Error('impl crashed')
+        return { rpcId: request.rpcId, result: { ok: true, value: { items: [] } } }
+      },
+      async create(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { sessionId: 's-new' as never } } }
+      },
+      async history(request) {
+        return {
+          rpcId: request.rpcId,
+          result: { ok: false, error: { code: 'session-not-found', message: 'nope', details: { sessionId: request.payload.sessionId } } },
+        }
+      },
+      async prompt(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { accepted: true as const } } }
+      },
+      async cancel(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { accepted: true as const } } }
+      },
+    },
+    host: {
+      async describe(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { version: 'v', cwd: '/w', attachedSessions: 0 } } }
+      },
+    },
+    events: {
+      mux: (_request, signal) => stream(muxFrames, signal),
+      host: (_request, signal) => stream(hostFrames, signal),
+    },
+    async respond(message: ClientResponse): Promise<RpcReceipt> {
+      return message.rpcId === 'known' ? { accepted: true } : { accepted: false, reason: 'not-pending' }
+    },
+  }
+}
+
+function client(api: ApiProxy = fakeApi()): InProcessApiClient {
+  return new InProcessApiClient(toFetchHandler(api))
+}
+
+async function collect<F>(stream: AsyncIterable<RpcRequest<F>>): Promise<RpcRequest<F>[]> {
+  const out: RpcRequest<F>[] = []
+  for await (const envelope of stream) out.push(envelope)
+  return out
+}
+
+describe('unary round trip (handler ⇄ client, no network)', () => {
+  it('carries a success result and echoes the minted rpcId', async () => {
+    const response = await client().sessions.list({})
+    expect(response.result).toEqual({ ok: true, value: { items: [] } })
+    expect(response.rpcId).toMatch(/[0-9a-f-]{36}/)
+  })
+
+  it('carries a business error as 200 + error result', async () => {
+    const response = await client().sessions.history({ sessionId: 'missing' as never })
+    expect(response.result.ok).toBe(false)
+    if (!response.result.ok) expect(response.result.error.code).toBe('session-not-found')
+  })
+
+  it('covers create/prompt/cancel/describe passthrough', async () => {
+    const c = client()
+    expect((await c.sessions.create({})).result.ok).toBe(true)
+    expect((await c.sessions.prompt({ sessionId: 's' as never, mode: 'queue', content: [{ type: 'text', text: 'x' }] })).result.ok).toBe(true)
+    expect((await c.sessions.cancel({ sessionId: 's' as never })).result.ok).toBe(true)
+    expect((await c.host.describe({})).result.ok).toBe(true)
+  })
+})
+
+describe('handler carrier-layer statuses', () => {
+  const handler = toFetchHandler(fakeApi())
+
+  it('404s unknown paths and non-POST non-stream methods', async () => {
+    expect((await handler.fetch(new Request('http://x/other', { method: 'POST', body: '{}' }))).status).toBe(404)
+    expect((await handler.fetch(new Request('http://x/api/session.list', { method: 'GET' }))).status).toBe(404)
+    expect((await handler.fetch(new Request('http://x/api/no.such', { method: 'POST', body: JSON.stringify({ type: 'client-request', rpcId: 'r', method: 'no.such', payload: {} }) }))).status).toBe(404)
+  })
+
+  it('400s a non-JSON body', async () => {
+    const response = await handler.fetch(new Request('http://x/api/session.list', { method: 'POST', body: 'not json' }))
+    expect(response.status).toBe(400)
+  })
+
+  it('rejects a malformed envelope with bad-request and the invalid-request sentinel rpcId', async () => {
+    const response = await handler.fetch(new Request('http://x/api/session.list', { method: 'POST', body: JSON.stringify({ nope: true }) }))
+    expect(response.status).toBe(200)
+    const body = await response.json() as { rpcId: string; result: { ok: boolean; error?: { code: string } } }
+    expect(body.rpcId).toBe('invalid-request')
+    expect(body.result.error?.code).toBe('bad-request')
+  })
+
+  it('rejects a method/path mismatch echoing the envelope rpcId', async () => {
+    const body = JSON.stringify({ type: 'client-request', rpcId: 'r-9', method: 'session.cancel', payload: {} })
+    const response = await handler.fetch(new Request('http://x/api/session.list', { method: 'POST', body }))
+    const parsed = await response.json() as { rpcId: string; result: { error?: { message: string } } }
+    expect(parsed.rpcId).toBe('r-9')
+    expect(parsed.result.error?.message).toContain('does not match path')
+  })
+
+  it('rejects an invalid payload with the zod issues attached', async () => {
+    const body = JSON.stringify({ type: 'client-request', rpcId: 'r-10', method: 'session.cancel', payload: {} })
+    const response = await handler.fetch(new Request('http://x/api/session.cancel', { method: 'POST', body }))
+    const parsed = await response.json() as { result: { error?: { code: string; details: { issues: unknown[] } } } }
+    expect(parsed.result.error?.code).toBe('bad-request')
+    expect(parsed.result.error?.details.issues.length).toBeGreaterThan(0)
+  })
+
+  it('500s when the impl itself throws', async () => {
+    const crashing = toFetchHandler(fakeApi({ crashOn: 'session.list' }))
+    const body = JSON.stringify({ type: 'client-request', rpcId: 'r-11', method: 'session.list', payload: {} })
+    const response = await crashing.fetch(new Request('http://x/api/session.list', { method: 'POST', body }))
+    expect(response.status).toBe(500)
+    expect(await response.text()).toContain('impl crashed')
+  })
+
+  it('routes /api/respond, rejecting malformed client-responses as a receipt', async () => {
+    const good = JSON.stringify({ type: 'client-response', rpcId: 'known', result: { ok: true, value: null } })
+    const goodReceipt: unknown = await (await handler.fetch(new Request('http://x/api/respond', { method: 'POST', body: good }))).json()
+    expect(goodReceipt).toEqual({ accepted: true })
+    const bad = JSON.stringify({ type: 'client-request', rpcId: 'r', method: 'x', payload: {} })
+    const badReceipt: unknown = await (await handler.fetch(new Request('http://x/api/respond', { method: 'POST', body: bad }))).json()
+    expect(badReceipt).toEqual({ accepted: false, reason: 'bad-response' })
+  })
+
+  it('accepts (url, init) form fetch invocation', async () => {
+    const body = JSON.stringify({ type: 'client-request', rpcId: 'r-12', method: 'session.list', payload: {} })
+    const response = await handler.fetch('http://x/api/session.list', { method: 'POST', body })
+    expect(response.status).toBe(200)
+  })
+})
+
+describe('SSE streams through the carrier', () => {
+  it('yields mux frames as ServerRequest narrow forms and completes', async () => {
+    const ac = new AbortController()
+    const frames = await collect(client().events.mux({}, ac.signal))
+    expect(frames).toHaveLength(1)
+    expect(frames[0]?.payload).toMatchObject({ type: 'session/subscribed' })
+    expect(frames[0]?.rpcId).toBe('frame-0')
+  })
+
+  it('yields host frames', async () => {
+    const ac = new AbortController()
+    const frames = await collect(client().events.host({}, ac.signal))
+    expect(frames[0]?.payload).toMatchObject({ type: 'host/session-removed' })
+  })
+
+  it('drops frames after the consumer aborts mid-stream', async () => {
+    const many = Array.from({ length: 50 }, (_, i): MuxFrame => ({ type: 'session/subscribed', sessionId: `s${String(i)}` as never, lastSeq: i }))
+    const ac = new AbortController()
+    const received: RpcRequest<MuxFrame>[] = []
+    for await (const envelope of client(fakeApi({ muxFrames: many })).events.mux({}, ac.signal)) {
+      received.push(envelope)
+      if (received.length === 2) break // generator return → reader.cancel path
+    }
+    expect(received).toHaveLength(2)
+  })
+
+  it('swallows a reader.cancel rejection on early exit', async () => {
+    const encoder = new TextEncoder()
+    const body = new ReadableStream<Uint8Array>({
+      start(controller) {
+        const frame = { type: 'server-request', rpcId: 'f0', method: 'session/subscribed', payload: { type: 'session/subscribed', sessionId: 's', lastSeq: -1 } }
+        controller.enqueue(encoder.encode(`data: ${JSON.stringify(frame)}\n\n`))
+        // stream intentionally left open: the consumer breaks first
+      },
+      cancel() {
+        throw new Error('cancel refused')
+      },
+    })
+    const c = new InProcessApiClient({ fetch: async () => new Response(body, { headers: { 'content-type': 'text/event-stream' } }) })
+    const received: RpcRequest<MuxFrame>[] = []
+    for await (const envelope of c.events.mux({}, new AbortController().signal)) {
+      received.push(envelope)
+      break
+    }
+    expect(received).toHaveLength(1)
+  })
+
+  it('surfaces a mid-stream impl failure as one stream/error frame, then the stream ends', async () => {
+    const api = fakeApi()
+    api.events.mux = (_request, _signal) => (async function * (): AsyncGenerator<RpcRequest<MuxFrame>> {
+      yield { rpcId: RpcId('f0'), payload: { type: 'session/subscribed', sessionId: 's' as never, lastSeq: -1 } }
+      throw new Error('stream source died')
+    })()
+    const frames = await collect(client(api).events.mux({}, new AbortController().signal))
+    expect(frames).toHaveLength(2)
+    expect(frames[1]?.payload).toMatchObject({ type: 'stream/error', error: { code: 'internal' } })
+  })
+})
+
+describe('client respond and transport failures', () => {
+  it('passes a client-response through and parses the receipt', async () => {
+    const receipt = await client().respond({ type: 'client-response', rpcId: RpcId('known'), result: { ok: true, value: null } })
+    expect(receipt).toEqual({ accepted: true })
+    const late = await client().respond({ type: 'client-response', rpcId: RpcId('late'), result: { ok: true, value: null } })
+    expect(late).toEqual({ accepted: false, reason: 'not-pending' })
+  })
+
+  it('throws on non-OK unary and respond and stream transport', async () => {
+    const broken = new InProcessApiClient({ fetch: async () => new Response('down', { status: 503 }) })
+    await expect(broken.sessions.list({})).rejects.toThrow('transport failure for /api/session.list: HTTP 503')
+    await expect(broken.respond({ type: 'client-response', rpcId: RpcId('r'), result: { ok: true, value: null } }))
+      .rejects.toThrow('transport failure for /api/respond')
+    await expect(collect(broken.events.mux({}, new AbortController().signal))).rejects.toThrow('transport failure for /api/events.mux')
+  })
+
+  it('throws on an rpcId echo mismatch', async () => {
+    const lying = new InProcessApiClient({
+      fetch: async () => Response.json({ type: 'server-response', rpcId: 'someone-else', result: { ok: true, value: { items: [] } } }),
+    })
+    await expect(lying.sessions.list({})).rejects.toThrow('rpcId mismatch')
+  })
+})
+
+describe('envelope observation', () => {
+  it('batches envelopes per microtask and isolates a throwing listener', async () => {
+    const c = client()
+    const batches: (readonly RpcMessage[])[] = []
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+    const unsubscribeThrowing = c.subscribeEnvelopes(() => { throw new Error('observer bug') })
+    const unsubscribe = c.subscribeEnvelopes((batch) => { batches.push(batch) })
+    await c.sessions.list({})
+    await new Promise((resolve) => { setTimeout(resolve, 0) })
+    // request and response tap in separate microtask windows (the await between
+    // them yields), so both arrive but batch count is timing-defined
+    expect(batches.flatMap(batch => batch.map(message => message.type))).toEqual(['client-request', 'server-response'])
+    expect(errorSpy).toHaveBeenCalled()
+    unsubscribe()
+    unsubscribeThrowing()
+    errorSpy.mockRestore()
+  })
+
+  it('skips buffering entirely with no listeners and after unsubscribe', async () => {
+    const c = client()
+    const seen: RpcMessage[] = []
+    const unsubscribe = c.subscribeEnvelopes((batch) => { seen.push(...batch) })
+    unsubscribe()
+    await c.sessions.list({})
+    await new Promise((resolve) => { setTimeout(resolve, 0) })
+    expect(seen).toHaveLength(0)
+  })
+
+  it('coalesces multiple calls in one microtask window into one flush', async () => {
+    const c = client()
+    const batches: (readonly RpcMessage[])[] = []
+    c.subscribeEnvelopes((batch) => { batches.push(batch) })
+    await Promise.all([c.sessions.list({}), c.host.describe({})])
+    await new Promise((resolve) => { setTimeout(resolve, 0) })
+    const total = batches.reduce((n, batch) => n + batch.length, 0)
+    expect(total).toBe(4)
+  })
+})
+
+describe('resolveBase', () => {
+  it('prefers a real location.origin and falls back to the internal authority', async () => {
+    class Probe extends AbstractApiClient {
+      urls: string[] = []
+      protected async doFetch(input: URL): Promise<Response> {
+        this.urls.push(input.href)
+        return Response.json({ type: 'server-response', rpcId: this.lastMinted, result: { ok: true, value: { items: [] } } })
+      }
+
+      lastMinted = ''
+      protected override mintRpcId(): ReturnType<AbstractApiClient['mintRpcId']> {
+        const id = super.mintRpcId()
+        this.lastMinted = id
+        return id
+      }
+    }
+    const probe = new Probe()
+    await probe.sessions.list({})
+    expect(probe.urls[0]).toMatch(/^http:\/\/dsh\.internal\//)
+
+    const globalWithLocation = globalThis as { location?: { origin?: string } }
+    globalWithLocation.location = { origin: 'http://host.example' }
+    try {
+      const probe2 = new Probe()
+      await probe2.sessions.list({})
+      expect(probe2.urls[0]).toMatch(/^http:\/\/host\.example\//)
+      globalWithLocation.location = { origin: 'null' } // sandboxed iframe shape
+      const probe3 = new Probe()
+      await probe3.sessions.list({})
+      expect(probe3.urls[0]).toMatch(/^http:\/\/dsh\.internal\//)
+    } finally {
+      delete globalWithLocation.location
+    }
+  })
+})

packages/host/apiproxy/tests/rpc-schemas.spec.ts

@@ -0,0 +1,161 @@
+import { describe, expect, it } from 'vitest'
+import { RpcId } from '../src/api/rpc.ts'
+import {
+  clientRequestSchema, clientResponseSchema, rpcErrorSchema, rpcIdSchema, rpcMessageSchema,
+  rpcReceiptSchema, rpcResultSchema, serverRequestSchema, serverResponseSchema,
+} from '../src/api/rpc.schema.ts'
+import { z } from 'zod'
+import {
+  contentBlockSchema, sessionCancelRequestSchema, sessionCancelValueSchema, sessionCreateRequestSchema,
+  sessionCreateValueSchema, sessionEventSchema, sessionHistoryRequestSchema, sessionHistoryValueSchema,
+  sessionIdSchema, sessionListRequestSchema, sessionListValueSchema, sessionPromptRequestSchema,
+  sessionPromptValueSchema, sessionSummarySchema,
+} from '../src/api/sessions.schema.ts'
+import { hostDescribeRequestSchema, hostDescribeValueSchema } from '../src/api/host.schema.ts'
+import { hostFrameSchema, muxFrameSchema, askUserQuestionItemSchema } from '../src/api/events.schema.ts'
+import { approvalRequestIdSchema, approvalResponsePayloadSchema } from '../src/api/approvals.schema.ts'
+import { askUserQuestionAnswerSchema, questionResponsePayloadSchema } from '../src/api/questions.schema.ts'
+
+describe('RpcId', () => {
+  it('brands a raw string at zero runtime cost', () => {
+    expect(RpcId('abc')).toBe('abc')
+    expect(rpcIdSchema.parse('abc')).toBe('abc')
+    // No min-length: the id is an opaque echo token (see rpcIdSchema's contract).
+    expect(rpcIdSchema.parse('')).toBe('')
+    expect(() => rpcIdSchema.parse(42)).toThrow()
+  })
+})
+
+describe('rpcErrorSchema', () => {
+  it('accepts every code branch with its required details', () => {
+    expect(rpcErrorSchema.parse({ code: 'bad-request', message: 'm', details: { issues: [] } }).code).toBe('bad-request')
+    expect(rpcErrorSchema.parse({ code: 'session-not-found', message: 'm', details: { sessionId: 's' } }).code).toBe('session-not-found')
+    expect(rpcErrorSchema.parse({ code: 'agent-busy', message: 'm', details: { reason: 'r' } }).code).toBe('agent-busy')
+    expect(rpcErrorSchema.parse({ code: 'internal', message: 'm', details: {} }).code).toBe('internal')
+  })
+
+  it('rejects a known code with missing details', () => {
+    expect(() => rpcErrorSchema.parse({ code: 'agent-busy', message: 'm', details: {} })).toThrow()
+    expect(() => rpcErrorSchema.parse({ code: 'nope', message: 'm', details: {} })).toThrow()
+  })
+})
+
+describe('rpcResultSchema', () => {
+  it('accepts both result branches and rejects hybrids', () => {
+    const schema = rpcResultSchema(z.object({ n: z.number() }))
+    expect(schema.parse({ ok: true, value: { n: 1 } })).toEqual({ ok: true, value: { n: 1 } })
+    const err = schema.parse({ ok: false, error: { code: 'internal', message: 'x', details: {} } })
+    expect(err).toMatchObject({ ok: false })
+    expect(() => schema.parse({ ok: true, error: {} })).toThrow()
+  })
+})
+
+describe('wire full-form schemas', () => {
+  it('parses the four quadrants and the union discriminates on type', () => {
+    const cq = { type: 'client-request', rpcId: 'r1', method: 'session.list', payload: {} }
+    const sr = { type: 'server-response', rpcId: 'r1', result: { ok: true, value: 1 } }
+    const rq = { type: 'server-request', rpcId: 'r2', method: 'session/event', payload: { a: 1 } }
+    const cr = { type: 'client-response', rpcId: 'r2', result: { ok: true, value: null } }
+    expect(clientRequestSchema.parse(cq).method).toBe('session.list')
+    expect(serverResponseSchema.parse(sr).rpcId).toBe('r1')
+    expect(serverRequestSchema.parse(rq).method).toBe('session/event')
+    expect(clientResponseSchema.parse(cr).rpcId).toBe('r2')
+    for (const message of [cq, sr, rq, cr]) expect(rpcMessageSchema.parse(message)).toBeTruthy()
+    expect(() => rpcMessageSchema.parse({ type: 'other', rpcId: 'x' })).toThrow()
+  })
+
+  it('rejects a quadrant missing its members', () => {
+    expect(() => clientRequestSchema.parse({ type: 'client-request', rpcId: 'r1' })).toThrow()
+    expect(() => serverResponseSchema.parse({ type: 'server-response', rpcId: 'r1', result: { ok: true } })).toThrow()
+  })
+})
+
+describe('rpcReceiptSchema', () => {
+  it('accepts both receipt branches with the closed reason set', () => {
+    expect(rpcReceiptSchema.parse({ accepted: true })).toEqual({ accepted: true })
+    expect(rpcReceiptSchema.parse({ accepted: false, reason: 'not-pending' })).toEqual({ accepted: false, reason: 'not-pending' })
+    expect(rpcReceiptSchema.parse({ accepted: false, reason: 'bad-response' })).toEqual({ accepted: false, reason: 'bad-response' })
+    expect(() => rpcReceiptSchema.parse({ accepted: false, reason: 'other' })).toThrow()
+  })
+})
+
+describe('sessions domain schemas', () => {
+  it('validates ids, summaries, and the event passthrough envelope', () => {
+    expect(sessionIdSchema.parse('s1')).toBe('s1')
+    expect(() => sessionIdSchema.parse('')).toThrow()
+    expect(sessionSummarySchema.parse({ sessionId: 's1', updatedAt: 1, running: false })).toMatchObject({ sessionId: 's1' })
+    expect(sessionSummarySchema.parse({ sessionId: 's1', updatedAt: 1, running: true, parentSessionId: 'p', cwd: '/x' }).cwd).toBe('/x')
+    const event = sessionEventSchema.parse({ type: 'user/message', seq: 0, time: 1, data: { any: true } })
+    expect(event).toMatchObject({ type: 'user/message' })
+    expect(() => sessionEventSchema.parse({ type: 'user/message', seq: -1, time: 1, data: {} })).toThrow()
+  })
+
+  it('validates the per-method request/value pairs', () => {
+    expect(sessionListRequestSchema.parse({})).toEqual({})
+    expect(sessionListRequestSchema.parse({ cursor: 'c' }).cursor).toBe('c')
+    expect(sessionListValueSchema.parse({ items: [] }).items).toEqual([])
+    expect(sessionCreateRequestSchema.parse({ cwd: '/w' }).cwd).toBe('/w')
+    expect(sessionCreateValueSchema.parse({ sessionId: 's1' }).sessionId).toBe('s1')
+    expect(sessionHistoryRequestSchema.parse({ sessionId: 's1', beforeSeq: 3, maxMessages: 5 }).beforeSeq).toBe(3)
+    expect(() => sessionHistoryRequestSchema.parse({ sessionId: 's1', maxMessages: 0 })).toThrow()
+    expect(sessionHistoryValueSchema.parse({ events: [], hasMore: false }).hasMore).toBe(false)
+    const prompt = sessionPromptRequestSchema.parse({ sessionId: 's1', mode: 'queue', content: [{ type: 'text', text: 'hi' }] })
+    expect(prompt.mode).toBe('queue')
+    expect(() => sessionPromptRequestSchema.parse({ sessionId: 's1', mode: 'inject', content: [] })).toThrow()
+    expect(sessionPromptValueSchema.parse({ accepted: true }).accepted).toBe(true)
+    expect(sessionCancelRequestSchema.parse({ sessionId: 's1' }).sessionId).toBe('s1')
+    expect(sessionCancelValueSchema.parse({ accepted: true }).accepted).toBe(true)
+    expect(contentBlockSchema.parse({ type: 'text', text: 'x', extra: 1 })).toMatchObject({ extra: 1 })
+  })
+})
+
+describe('host domain schemas', () => {
+  it('validates describe request/value', () => {
+    expect(hostDescribeRequestSchema.parse({})).toEqual({})
+    const value = hostDescribeValueSchema.parse({ version: '1', cwd: '/x', provider: 'p', model: 'm', attachedSessions: 2 })
+    expect(value.attachedSessions).toBe(2)
+    expect(hostDescribeValueSchema.parse({ version: '1', cwd: '/x', attachedSessions: 0 }).provider).toBeUndefined()
+  })
+})
+
+describe('events frame schemas', () => {
+  it('accepts every mux frame branch', () => {
+    const frames = [
+      { type: 'session/event', sessionId: 's', event: { type: 't', seq: 0, time: 1, data: null } },
+      { type: 'session/subscribed', sessionId: 's', lastSeq: -1 },
+      { type: 'approval/requested', sessionId: 's', approvalId: 'a', toolName: 'bash', callId: 'c', reason: 'r' },
+      { type: 'approval/resolved', sessionId: 's', approvalId: 'a', outcome: 'allowed-once' },
+      { type: 'question/requested', sessionId: 's', questions: [{ id: 'q', question: 'Q?', options: [{ label: 'L' }], multiSelect: true }] },
+      { type: 'question/resolved', sessionId: 's', questionRpcId: 'r', outcome: 'answered' },
+      { type: 'stream/error', error: { code: 'internal', message: 'm', details: {} } },
+    ]
+    for (const frame of frames) expect(muxFrameSchema.parse(frame)).toMatchObject({ type: frame.type })
+    expect(() => muxFrameSchema.parse({ type: 'unknown/frame' })).toThrow()
+    expect(askUserQuestionItemSchema.parse({ id: 'q', question: 'Q?' }).id).toBe('q')
+  })
+
+  it('accepts every host frame branch', () => {
+    const frames = [
+      { type: 'host/session-added', sessionId: 's', parentSessionId: 'p' },
+      { type: 'host/session-added', sessionId: 's' },
+      { type: 'host/session-removed', sessionId: 's' },
+      { type: 'host/session-status', sessionId: 's', running: true },
+      { type: 'host/agent-error', sessionId: 's', message: 'boom' },
+      { type: 'stream/error', error: { code: 'internal', message: 'm', details: {} } },
+    ]
+    for (const frame of frames) expect(hostFrameSchema.parse(frame)).toMatchObject({ type: frame.type })
+  })
+})
+
+describe('respond payload schemas', () => {
+  it('validates approval and question answer payloads', () => {
+    expect(approvalRequestIdSchema.parse('a1')).toBe('a1')
+    const approval = approvalResponsePayloadSchema.parse({ sessionId: 's', approvalId: 'a', outcome: 'rejected' })
+    expect(approval.outcome).toBe('rejected')
+    expect(() => approvalResponsePayloadSchema.parse({ sessionId: 's', approvalId: 'a', outcome: 'cancelled' })).toThrow()
+    const answer = askUserQuestionAnswerSchema.parse({ answers: [{ id: 'q', selected: ['x'], custom: 'c' }] })
+    expect(answer.answers[0]?.selected).toEqual(['x'])
+    const payload = questionResponsePayloadSchema.parse({ sessionId: 's', answer: { answers: [] } })
+    expect(payload.sessionId).toBe('s')
+  })
+})

packages/host/apiproxy/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../util/brand"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../core/tools"
+    },
+    {
+      "path": "../../ui/user-approval"
+    },
+    {
+      "path": "../../ui/user-interaction"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/host/runtime/README.md

@@ -0,0 +1,31 @@
+# @deepseek-ai/dsh-host-runtime
+
+Host runtime assembly for `dsc`: `bootHost` composes the core plugin spine (LLM service + DeepSeek adapter, sessions with JSONL persistence, system prompt, tools, agents, agent loop, local bash), `createApiProxy` implements the [`dsh-host-apiproxy`](../apiproxy/README.md) contract over that composition, and `startHost` is the one-step shell seam returning `{ api, handler, defaults, ctx, dispose }`.
+
+Which plugins mount and with what defaults is decided only here — shells must not `ctx.plugin` to alter the assembly. `RunningHost.ctx` is a formal seam with exactly two sanctioned uses: mounting protocol front-door plugins (e.g. a future `dsh acp`) and headless session-event subscription; consuming clients must not bypass `api` through it.
+
+## Configuration
+
+| Key | Default | Contract |
+|---|---:|---|
+| `persistenceRoot` | (required) | Root directory for JSONL session persistence. |
+| `provider` | `'deepseek'` | Default provider route injected as agentOptions on create/resume and reported by `host.describe`. |
+| `model` | `'deepseek-v4-flash'` | Default model id, same single source as `provider`. |
+
+## ApiProxy implementation notes
+
+Unary methods take the narrow `RpcRequest<P>` and echo `request.rpcId`; a prompt's rpcId rides `MessageSource` into the `user/message` event so clients can promote optimistic echoes. `history`/`prompt` on a cold session implicitly resume it, deduplicating concurrent calls through an in-flight table; `history` paginates backwards on message boundaries (never mid-message). The mux stream replays a `session/subscribed` baseline per attached session on open; the host stream carries session lifecycle, running flips, and `agent/error` as the only outlet for live failures with no turn position.
+
+## Model Experience
+
+Indirectly, through the model-facing plugins bootHost mounts and the provider/model defaults injected into created and resumed agents.
+
+#### KV Cache effect
+
+No direct invalidation; the mounted model-facing plugins own their request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **`respond` is a stub** — it always returns `not-pending`; the approval/question pending registry (stable-rpcId mint on accept, baseline replay on stream reopen, wire answerer) is the next host-side step.
+- **`session.list` covers live sessions only** — cold sessions in the persistence directory are not yet merged into the listing; `host.describe.version` is a placeholder rather than the `apps/cli` package version.
+- **The assembly is fixed** — per-deployment plugin selection (user profile, log sinks, alternative persistence) has a documented home here but no configuration surface yet.

packages/host/runtime/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@deepseek-ai/dsh-host-runtime",
+  "description": "Host runtime assembly for dsh: bootHost composes the core spine, createApiProxy implements the contract, startHost is the one-step shell seam",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@cordisjs/plugin-loader": "workspace:^",
+    "@cordisjs/plugin-timer": "workspace:^",
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-bash-local": "workspace:^",
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-client-i18n": "workspace:^",
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-sidebar": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-theme": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-trajectory": "workspace:^",
+    "@deepseek-ai/dsh-compact-basic": "workspace:^",
+    "@deepseek-ai/dsh-fs-local": "workspace:^",
+    "@deepseek-ai/dsh-fs-policy": "workspace:^",
+    "@deepseek-ai/dsh-host-apiproxy": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-llm-deepseek": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
+    "@deepseek-ai/dsh-skill": "workspace:^",
+    "@deepseek-ai/dsh-skill-local": "workspace:^",
+    "@deepseek-ai/dsh-spill-local": "workspace:^",
+    "@deepseek-ai/dsh-spill-policy": "workspace:^",
+    "@deepseek-ai/dsh-subagent": "workspace:^",
+    "@deepseek-ai/dsh-subagent-fork": "workspace:^",
+    "@deepseek-ai/dsh-subagent-spawn": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tasks": "workspace:^",
+    "@deepseek-ai/dsh-timeout-policy": "workspace:^",
+    "@deepseek-ai/dsh-token-meter": "workspace:^",
+    "@deepseek-ai/dsh-tool-bash": "workspace:^",
+    "@deepseek-ai/dsh-tool-fs": "workspace:^",
+    "@deepseek-ai/dsh-tool-fs-search": "workspace:^",
+    "@deepseek-ai/dsh-tool-skill": "workspace:^",
+    "@deepseek-ai/dsh-tool-subagent": "workspace:^",
+    "@deepseek-ai/dsh-tool-tasks": "workspace:^",
+    "@deepseek-ai/dsh-tool-todo": "workspace:^",
+    "@deepseek-ai/dsh-tool-workflow": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-workflow-workerthread": "workspace:^"
+  },
+  "peerDependencies": {
+    "cordis": "^4.0.0-rc.7",
+    "@deepseek-ai/dsh-invariants": "^0.0.1"
+  },
+  "devDependencies": {
+    "cordis": "^4.0.0-rc.7",
+    "@deepseek-ai/dsh-invariants": "workspace:^"
+  }
+}

packages/host/runtime/src/api-proxy.ts

@@ -0,0 +1,429 @@
+/**
+ * Host-side ApiProxy implementation (minimal-first —
+ * describe/list/create/history/prompt/cancel and both streams are real,
+ * respond is a stub). Signature discipline: unary takes the narrow
+ * RpcRequest<P> and echoes request.rpcId on the RpcResponse<T>.
+ */
+
+import { randomUUID } from 'node:crypto'
+import { stat } from 'node:fs/promises'
+import type { Context } from 'cordis'
+import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
+import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
+import type { JsonValue, Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
+import type { ApiProxy, HistoryEntry, HostFrame, MuxFrame, SessionSummary, ToolEventView } from '@deepseek-ai/dsh-host-apiproxy/api'
+import type { ClientResponse, RpcError, RpcReceipt, RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+
+/** Page size when history is called without maxMessages. */
+const DEFAULT_MAX_MESSAGES = 50
+
+/** Surface message event types (the pagination counting unit). */
+const MESSAGE_TYPES = new Set(['user/message', 'assistant/message', 'steering/message'])
+
+/**
+ * Message-boundary pagination: count maxMessages surface messages backwards from
+ * the window tail; the cut is the starting seq of the oldest message group
+ * (chunks group via sourceEventSeqs — never cut mid-message). The tail page
+ * naturally includes the in-progress partial.
+ */
+function paginate(
+  events: readonly SessionEvent[],
+  beforeSeq: number | undefined,
+  maxMessages: number,
+): { events: SessionEvent[]; hasMore: boolean } {
+  const window = beforeSeq === undefined ? [...events] : events.filter(event => event.seq < beforeSeq)
+  let count = 0
+  let cut = 0
+  for (let i = window.length - 1; i >= 0; i--) {
+    const event = window[i] as SessionEvent
+    if (!MESSAGE_TYPES.has(event.type)) continue
+    count++
+    const sources = (event as { sourceEventSeqs?: number[] }).sourceEventSeqs
+    const groupStart = sources !== undefined && sources.length > 0 ? Math.min(event.seq, ...sources) : event.seq
+    if (count >= maxMessages) {
+      cut = groupStart
+      break
+    }
+  }
+  const page = window.filter(event => event.seq >= cut)
+  return { events: page, hasMore: cut > 0 }
+}
+
+/** Wrap an ok result echoing the request's rpcId. */
+function ok<T>(request: RpcRequest<unknown>, value: T): RpcResponse<T> {
+  return { rpcId: request.rpcId, result: { ok: true, value } }
+}
+
+/** Wrap an error result echoing the request's rpcId. */
+function err<T>(request: RpcRequest<unknown>, error: RpcError): RpcResponse<T> {
+  return { rpcId: request.rpcId, result: { ok: false, error } }
+}
+
+/** Simple async queue: core callbacks push, the AsyncIterable pulls; abort/return cleans up. */
+class FrameQueue<F> {
+  private buffer: F[] = []
+  private waiter: (() => void) | undefined
+  private done = false
+
+  push(item: F): void {
+    if (this.done) return
+    this.buffer.push(item)
+    this.waiter?.()
+  }
+
+  end(): void {
+    this.done = true
+    this.waiter?.()
+  }
+
+  async *iterate(signal: AbortSignal, cleanup: () => void): AsyncGenerator<F> {
+    const onAbort = (): void => { this.end() }
+    signal.addEventListener('abort', onAbort, { once: true })
+    try {
+      while (true) {
+        while (this.buffer.length > 0) yield this.buffer.shift() as F
+        if (this.done || signal.aborted) return
+        await new Promise<void>((resolve) => { this.waiter = resolve })
+        this.waiter = undefined
+      }
+    } finally {
+      signal.removeEventListener('abort', onAbort)
+      cleanup()
+    }
+  }
+}
+
+/**
+ * Server-side frame mint: pure pushes get a fresh rpcId per frame (stable ids
+ * for answerable frames belong to the approval/question registry, absent in
+ * this minimal version).
+ */
+function frame<F>(payload: F): RpcRequest<F> {
+  return { rpcId: RpcId(randomUUID()), payload }
+}
+
+/** SessionSummary projection for attached (in-memory) sessions. */
+function summarize(session: Session, running: boolean): SessionSummary {
+  return {
+    sessionId: session.id,
+    updatedAt: session.events.at(-1)?.time ?? session.header.createdAt,
+    running,
+    ...session.header.parentSession === undefined ? {} : { parentSessionId: session.header.parentSession },
+    ...session.header.cwd === undefined ? {} : { cwd: session.header.cwd },
+  }
+}
+
+/**
+ * SessionSummary projection for cold (persisted, unattached) sessions.
+ * updatedAt is the log file's mtime; backends without a per-session file
+ * (locate() undefined) fall back to the header's createdAt.
+ */
+async function summarizeCold(persistence: SessionPersistence, meta: SessionHeader): Promise<SessionSummary> {
+  let updatedAt = meta.createdAt
+  const location = persistence.locate(meta)
+  if (location !== undefined) {
+    try {
+      updatedAt = (await stat(location.path)).mtimeMs
+    } catch {
+      // The log vanished between list() and stat() (concurrent cleanup); createdAt stands in.
+    }
+  }
+  return {
+    sessionId: meta.id,
+    updatedAt,
+    running: false,
+    ...meta.parentSession === undefined ? {} : { parentSessionId: meta.parentSession },
+    /* v8 ignore next -- the empty arm needs a cwd-less meta, but list()
+    filters those out (legacy logs are not served); the conditional mirrors
+    summarize() shape. */
+    ...meta.cwd === undefined ? {} : { cwd: meta.cwd },
+  }
+}
+
+/** Host-level default agent routing (same shape as bootHost's HostDefaults; avoids an impl→index reverse import). */
+export interface ApiProxyDefaults {
+  provider: string
+  model: string
+  /** Default project directory for new sessions whose create request carries no cwd. */
+  cwd: string
+}
+
+/** The tool/call payload fields the presenter path reads. */
+interface ToolCallData { callId: string; name: string; arguments: string }
+/** The tool/result payload fields the presenter path reads. */
+interface ToolResultData { callId: string; content: ContentBlock[]; isError: boolean; meta?: JsonValue }
+
+/**
+ * Compute the render intent for a tool/call or tool/result event through the
+ * presenters registered at this moment; every other event type gets none. A
+ * result's presenter needs its call's parsed args — `argsFor` supplies them
+ * (live: the per-session call table; history: an in-page backscan), returning
+ * undefined when the pairing is unavailable (e.g. the call fell off the page),
+ * which soft-falls to no view. Presenter or JSON.parse throws also soft-fall:
+ * the client's documented default (generic JSON card) covers every miss.
+ */
+function viewFor(ctx: Context, event: SessionEvent, argsFor: (callId: string) => unknown): ToolEventView | undefined {
+  try {
+    if (event.type === 'tool/call') {
+      const { name, arguments: raw } = event.data as ToolCallData
+      const view = ctx.tools.get(name)?.presentCall?.(JSON.parse(raw))
+      return view === undefined ? undefined : { for: 'call', view }
+    }
+    if (event.type === 'tool/result') {
+      const { callId, content, isError, meta } = event.data as ToolResultData
+      const call = argsFor(callId) as { name: string; args: unknown } | undefined
+      if (call === undefined) return undefined
+      const view = ctx.tools.get(call.name)?.presentResult?.(call.args, { content, isError, ...meta === undefined ? {} : { meta } })
+      return view === undefined ? undefined : { for: 'result', view }
+    }
+  } catch (error: unknown) {
+    // A throwing presenter (or unparseable arguments) must not break delivery;
+    // the event still ships, just without a view.
+    console.error(`api-proxy: presenter failed for ${event.type}, falling back to generic: ${String(error)}`)
+  }
+  return undefined
+}
+
+/**
+ * Resolve a tool/result's call pairing by scanning a window of events backwards
+ * for the matching tool/call. Used by the history path (the page is the
+ * window — a cross-page pairing soft-falls to no view) and by live-path table
+ * misses after a reconnect-eviction.
+ */
+function backscanArgs(events: readonly SessionEvent[], callId: string): { name: string; args: unknown } | undefined {
+  for (let i = events.length - 1; i >= 0; i--) {
+    const event = events[i] as SessionEvent
+    if (event.type !== 'tool/call') continue
+    const data = event.data as ToolCallData
+    if (data.callId !== callId) continue
+    try {
+      return { name: data.name, args: JSON.parse(data.arguments) }
+    } catch {
+      // Unparseable stored arguments: same soft-fall as a live parse failure.
+      return undefined
+    }
+  }
+  return undefined
+}
+
+/**
+ * Thrown by the cold-resume path when the id names no servable session
+ * (absent from the store, or a pre-project legacy log without a cwd).
+ */
+class SessionNotFound extends Error {}
+
+/**
+ * Implement ApiProxy over the ctx composed by bootHost.
+ * @param ctx - the root context returned by bootHost (sessions/agents services mounted).
+ * @param defaults - host-level default provider/model: injected as
+ * agentOptions on create/resume, reported by describe from the same source.
+ * @returns the ApiProxy implementation (minimal-first; stubs noted per method).
+ */
+export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiProxy {
+  const agentOptions = { provider: defaults.provider, model: defaults.model }
+  /** Implicit resume of cold sessions, deduplicating concurrent calls (follows the jsonrpc sessionCreations precedent). */
+  const resumes = new Map<SessionId, Promise<Agent>>()
+
+  /**
+   * Gate the cold path on the store: an id absent from it, or naming a legacy
+   * log without a cwd (pre-release stance: not served, no compatibility), is
+   * not-found before any resume is attempted. With the gate passed, a later
+   * resume failure is genuinely internal. No persistence configured skips the
+   * gate — resume itself then fails loud with its own diagnostic.
+   */
+  async function assertServable(sessionId: SessionId): Promise<void> {
+    const persistence = ctx.get('sessionPersistence')
+    if (persistence === undefined) return
+    const meta = (await persistence.list()).find(m => m.id === sessionId)
+    if (meta === undefined || meta.cwd === undefined) throw new SessionNotFound(`session "${sessionId}" not found`)
+  }
+
+  async function agentFor(sessionId: SessionId): Promise<{ agent: Agent } | { error: RpcError }> {
+    const live = ctx.agents.get(sessionId)
+    if (live !== undefined) return { agent: live }
+    let resume = resumes.get(sessionId)
+    if (resume === undefined) {
+      resume = (async () => {
+        try {
+          await assertServable(sessionId)
+          const handle = await ctx.agents.resume({ resumeSessionId: sessionId, agentOptions })
+          return handle.agent
+        } finally {
+          resumes.delete(sessionId)
+        }
+      })()
+      resumes.set(sessionId, resume)
+    }
+    try {
+      return { agent: await resume }
+    } catch (error: unknown) {
+      if (error instanceof SessionNotFound) {
+        return { error: { code: 'session-not-found', message: error.message, details: { sessionId } } }
+      }
+      // The internal details slot is contractually {}; the reason rides the message.
+      return { error: { code: 'internal', message: `resume failed for session "${sessionId}": ${String(error)}`, details: {} } }
+    }
+  }
+
+  return {
+    sessions: {
+      // Attached sessions summarize from memory; persisted-but-unattached (cold)
+      // sessions merge in from the persistence store so history survives restarts.
+      // Legacy logs without a cwd (pre-project stance) are not served — every
+      // session now records its project at create time.
+      async list(request) {
+        const items = ctx.sessions.list().map((session) => {
+          const agent = ctx.agents.get(session.id)
+          return summarize(session, agent?.status === 'running')
+        })
+        const attached = new Set(items.map(item => item.sessionId))
+        const persistence = ctx.get('sessionPersistence')
+        if (persistence !== undefined) {
+          const cold = (await persistence.list()).filter(meta => !attached.has(meta.id) && meta.cwd !== undefined)
+          items.push(...await Promise.all(cold.map(meta => summarizeCold(persistence, meta))))
+        }
+        items.sort((a, b) => b.updatedAt - a.updatedAt)
+        return ok(request, { items })
+      },
+
+      async create(request) {
+        const sessionId = `session-${randomUUID()}` as SessionId
+        // A session's cwd is its project path. When the creator does not choose
+        // one, the default project is the host-level default (the host process
+        // working directory unless boot overrides it).
+        const cwd = request.payload.cwd ?? defaults.cwd
+        const handle = await ctx.agents.create({ sessionId, agentOptions, meta: { cwd } })
+        return ok(request, { sessionId: handle.agent.id })
+      },
+
+      async history(request) {
+        const { sessionId, beforeSeq, maxMessages } = request.payload
+        const found = await agentFor(sessionId)
+        if ('error' in found) return err(request, found.error)
+        const page = paginate(found.agent.session.events, beforeSeq, maxMessages ?? DEFAULT_MAX_MESSAGES)
+        // Views are computed against the registry at pagination time; result
+        // pairing scans within the page only (message-boundary pagination keeps
+        // a call and its result on one page — a cross-page miss soft-falls).
+        const entries: HistoryEntry[] = page.events.map((event) => {
+          const view = viewFor(ctx, event, callId => backscanArgs(page.events, callId))
+          return { event, ...view === undefined ? {} : { view } }
+        })
+        return ok(request, { events: entries, hasMore: page.hasMore })
+      },
+
+      async prompt(request) {
+        const { sessionId, mode, content } = request.payload
+        const found = await agentFor(sessionId)
+        if ('error' in found) return err(request, found.error)
+        const agent = found.agent
+        // The rpcId rides MessageSource into user/message (merge declaration in api/sessions.ts; provisional correlation).
+        const source: MessageSource = { kind: 'user', rpcId: request.rpcId }
+        try {
+          if (mode === 'steer') agent.steer(content, { source })
+          else agent.send(content, { source })
+        } catch (error: unknown) {
+          // A synchronous throw from send/steer means disposed or invalid input; surface as agent-busy with the reason attached.
+          return err(request, { code: 'agent-busy', message: 'prompt rejected', details: { reason: String(error) } })
+        }
+        return ok(request, { accepted: true as const })
+      },
+
+      cancel(request) {
+        const { sessionId } = request.payload
+        const agent = ctx.agents.get(sessionId)
+        if (agent === undefined) {
+          return Promise.resolve(err(request, {
+            code: 'session-not-found',
+            message: `session "${sessionId}" not found (not attached)`,
+            details: { sessionId },
+          }))
+        }
+        agent.cancel()
+        return Promise.resolve(ok(request, { accepted: true as const }))
+      },
+    },
+
+    host: {
+      describe(request) {
+        // TODO(step2): version should read apps/cli's package.json; placeholder for now.
+        return Promise.resolve(ok(request, {
+          version: '0.0.1',
+          cwd: process.cwd(),
+          provider: defaults.provider,
+          model: defaults.model,
+          attachedSessions: ctx.agents.list().length,
+        }))
+      },
+    },
+
+    events: {
+      mux(_request, signal) {
+        const queue = new FrameQueue<RpcRequest<MuxFrame>>()
+        for (const session of ctx.sessions.list()) {
+          queue.push(frame({ type: 'session/subscribed', sessionId: session.id, lastSeq: session.seq - 1 }))
+        }
+        // Per-session open-call table for result-view pairing. Bounded by the
+        // per-turn call count: entries clear on turn/end; a table miss (stream
+        // opened mid-turn) backscans the session's in-memory events instead.
+        const openCalls = new Map<SessionId, Map<string, { name: string; args: unknown }>>()
+        const disposers = [
+          ctx.on('session/event', (session: Session, event: SessionEvent) => {
+            if (event.type === 'tool/call') {
+              const data = event.data as ToolCallData
+              try {
+                let table = openCalls.get(session.id)
+                if (table === undefined) openCalls.set(session.id, table = new Map<string, { name: string; args: unknown }>())
+                table.set(data.callId, { name: data.name, args: JSON.parse(data.arguments) })
+              } catch {
+                // Unparseable model arguments: leave the table unset; the result view soft-falls.
+              }
+            } else if (event.type === 'turn/end') {
+              openCalls.delete(session.id)
+            }
+            const view = viewFor(ctx, event, callId =>
+              openCalls.get(session.id)?.get(callId) ?? backscanArgs(session.events, callId))
+            queue.push(frame({ type: 'session/event', sessionId: session.id, event, ...view === undefined ? {} : { view } }))
+          }),
+          ctx.on('session/created', (session: Session) => {
+            queue.push(frame({ type: 'session/subscribed', sessionId: session.id, lastSeq: session.seq - 1 }))
+          }),
+          ctx.on('session/disposed', (session: Session) => {
+            openCalls.delete(session.id)
+          }),
+        ]
+        return queue.iterate(signal, () => { for (const dispose of disposers) dispose() })
+      },
+
+      host(_request, signal) {
+        const queue = new FrameQueue<RpcRequest<HostFrame>>()
+        const disposers = [
+          ctx.on('session/created', (session: Session) => {
+            queue.push(frame({
+              type: 'host/session-added',
+              sessionId: session.id,
+              ...session.header.parentSession === undefined ? {} : { parentSessionId: session.header.parentSession },
+            }))
+          }),
+          ctx.on('session/disposed', (session: Session) => {
+            queue.push(frame({ type: 'host/session-removed', sessionId: session.id }))
+          }),
+          ctx.on('agent/status', (agent: Agent, status: AgentStatus) => {
+            if (status === 'disposed') return
+            queue.push(frame({ type: 'host/session-status', sessionId: agent.id, running: status === 'running' }))
+          }),
+          ctx.on('agent/error', (agent: Agent, _turn: number, _step: number, error: Error) => {
+            queue.push(frame({ type: 'host/agent-error', sessionId: agent.id, message: String(error) }))
+          }),
+        ]
+        return queue.iterate(signal, () => { for (const dispose of disposers) dispose() })
+      },
+    },
+
+    // TODO(step2): approval/question pending registry (wire answerer + proxy provider).
+    respond(_message: ClientResponse): Promise<RpcReceipt> {
+      return Promise.resolve({ accepted: false, reason: 'not-pending' })
+    },
+  }
+}

packages/host/runtime/src/boot.ts

@@ -0,0 +1,133 @@
+/**
+ * Core spine composition for the dsh host: mounts the harness core plugins
+ * one by one (each awaited so a load failure surfaces deterministically at
+ * boot, unlike bundle plugins whose children mount unawaited).
+ */
+
+import { Context } from 'cordis'
+import Timer from '@cordisjs/plugin-timer'
+import LlmService from '@deepseek-ai/dsh-llm'
+import SessionStore from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import TaskService from '@deepseek-ai/dsh-tasks'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
+import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
+import LocalBashExecutor from '@deepseek-ai/dsh-bash-local'
+import * as toolBash from '@deepseek-ai/dsh-tool-bash'
+import * as toolTodo from '@deepseek-ai/dsh-tool-todo'
+import * as toolTasks from '@deepseek-ai/dsh-tool-tasks'
+import FsLocal from '@deepseek-ai/dsh-fs-local'
+import * as fsPolicy from '@deepseek-ai/dsh-fs-policy'
+import * as toolFs from '@deepseek-ai/dsh-tool-fs'
+import * as toolFsSearch from '@deepseek-ai/dsh-tool-fs-search'
+import SkillService from '@deepseek-ai/dsh-skill'
+import * as SkillLocal from '@deepseek-ai/dsh-skill-local'
+import * as toolSkill from '@deepseek-ai/dsh-tool-skill'
+import TokenMeter from '@deepseek-ai/dsh-token-meter'
+import CompactBasic from '@deepseek-ai/dsh-compact-basic'
+import SubagentService from '@deepseek-ai/dsh-subagent'
+import * as SubagentSpawn from '@deepseek-ai/dsh-subagent-spawn'
+import * as SubagentFork from '@deepseek-ai/dsh-subagent-fork'
+import * as toolSubagent from '@deepseek-ai/dsh-tool-subagent'
+import WorkflowWorkerthread from '@deepseek-ai/dsh-workflow-workerthread'
+import * as toolWorkflow from '@deepseek-ai/dsh-tool-workflow'
+import * as timeoutPolicy from '@deepseek-ai/dsh-timeout-policy'
+import SpillLocal from '@deepseek-ai/dsh-spill-local'
+import * as spillPolicy from '@deepseek-ai/dsh-spill-policy'
+
+/** Options for bootHost — the assembly-layer composition knobs. */
+export interface BootHostOptions {
+  /** Root directory for JSONL session persistence. */
+  persistenceRoot: string
+  /** Default provider route for created/resumed agents (defaults to 'deepseek', the only adapter bootHost registers). */
+  provider?: string
+  /** Default model id (defaults to 'deepseek-v4-flash', matching the demos). */
+  model?: string
+  /**
+   * Default project directory for sessions created without an explicit cwd
+   * (defaults to the host process working directory). A session's cwd is its
+   * project path — a per-session choice, not a host property; this option only
+   * supplies the value used when the creator does not choose one.
+   */
+  cwd?: string
+}
+
+/** Host-level default agent routing: the single source injected on create and reported by host.describe. */
+export interface HostDefaults {
+  provider: string
+  model: string
+  /** Default project directory for new sessions whose create request carries no cwd. */
+  cwd: string
+}
+
+/** Booted host handle: composed root context + resolved defaults + disposer. */
+export interface HostHandle {
+  /** Root context with the full plugin assembly mounted. */
+  ctx: Context
+  /** Resolved default agent routing (options ?? built-in fallbacks). */
+  defaults: HostDefaults
+  /** Tear down the whole plugin tree. */
+  dispose(): Promise<void>
+}
+
+/**
+ * Compose the harness host plugin assembly (the one place deciding which plugins mount and
+ * with what defaults — shells must not alter the assembly).
+ * @param options - persistence root and optional default provider/model.
+ * @returns the booted handle (ctx + defaults + dispose).
+ */
+export async function bootHost(options: BootHostOptions): Promise<HostHandle> {
+  const defaults: HostDefaults = {
+    provider: options.provider ?? 'deepseek',
+    model: options.model ?? 'deepseek-v4-flash',
+    cwd: options.cwd ?? process.cwd(),
+  }
+  const ctx = new Context()
+  await ctx.plugin(Timer)
+  await ctx.plugin(LlmService)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt, { persona: '' })
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(TaskService)
+  await ctx.plugin(AgentLoop, { agents: [] })
+  await ctx.plugin(LlmDeepSeek, {})
+  await ctx.plugin(SessionPersistenceJsonl, { root: options.persistenceRoot, compression: 'none' })
+  await ctx.plugin(LocalBashExecutor, {})
+  // Tool suite mirroring the demo:repl composition (repl-agent/cordis.yml +
+  // the agent-spine bundle) so web sessions get the same coding-agent tool
+  // face; deviations are noted inline.
+  await ctx.plugin(toolBash, {})
+  await ctx.plugin(toolTodo)
+  await ctx.plugin(toolTasks, {})
+  // fs paths resolve against the host default project rather than the raw
+  // process cwd — the same source create() injects into session.cwd.
+  await ctx.plugin(FsLocal, { cwd: defaults.cwd })
+  await ctx.plugin(fsPolicy)
+  await ctx.plugin(toolFs, {})
+  await ctx.plugin(toolFsSearch, {})
+  // Skill stack with the demo default dshHome (~/.dsh via resolveDshHome).
+  await ctx.plugin(SkillService, {})
+  await ctx.plugin(SkillLocal, {})
+  await ctx.plugin(toolSkill, {})
+  // Request pressure + compaction (service-wide defaults, as in repl-agent).
+  await ctx.plugin(TokenMeter)
+  await ctx.plugin(CompactBasic)
+  // Subagent spawn/fork backends and their two model-facing tool instances.
+  await ctx.plugin(SubagentService)
+  await ctx.plugin(SubagentSpawn, { providerName: 'spawn' })
+  await ctx.plugin(SubagentFork, { providerName: 'fork' })
+  await ctx.plugin(toolSubagent, { provider: 'spawn', toolName: 'subagent' })
+  await ctx.plugin(toolSubagent, { provider: 'fork', toolName: 'subagent_fork' })
+  await ctx.plugin(WorkflowWorkerthread, { provider: 'spawn' })
+  await ctx.plugin(toolWorkflow, {})
+  // Declared per-tool timeouts become enforced deadlines.
+  await ctx.plugin(timeoutPolicy)
+  // Oversized tool output spills to session-scoped files (repl-agent budget).
+  await ctx.plugin(SpillLocal, {})
+  await ctx.plugin(spillPolicy, { maxInlineBytes: 50000 })
+  return { ctx, defaults, dispose: () => ctx.fiber.dispose() }
+}

packages/host/runtime/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @deepseek-ai/dsh-host-runtime — host runtime assembly layer: the core spine
+ * composition (bootHost), the ApiProxy implementation (createApiProxy), and
+ * the one-step shell seam (startHost). Host-level configuration (defaults,
+ * persistenceRoot, future user profile) lives here.
+ */
+
+export { bootHost } from './boot.ts'
+export type { BootHostOptions, HostDefaults, HostHandle } from './boot.ts'
+export { createApiProxy } from './api-proxy.ts'
+export type { ApiProxyDefaults } from './api-proxy.ts'
+export { startHost } from './start.ts'
+export type { StartHostOptions, RunningHost } from './start.ts'
+export { mountWebPlugins, WEB_UI_PLUGINS } from './web-plugins.ts'

packages/host/runtime/src/invariant.ts

@@ -0,0 +1,31 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-host-runtime`.
+ * @module @deepseek-ai/dsh-host-runtime/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-host-runtime'
+
+/** Cordis companion plugin name. */
+export const name = 'host-runtime-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this assembly layer only composes plugins owned
+ * elsewhere; the event/data relations it touches (session events, agent
+ * lifecycle, wire frames) are asserted by their owning packages' companions.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/host/runtime/src/start.ts

@@ -0,0 +1,58 @@
+/**
+ * One-step host startup seam: boot core → assemble ApiProxy → assemble the
+ * fetch handler. The returned RunningHost is shell-agnostic — node:http
+ * (dsh web), in-process injection (dsh -p, tests), an IPC bridge (future
+ * Electron sidecar), and front-door plugin mounting (future dsh acp) all
+ * consume the same shape.
+ */
+
+import type { Context } from 'cordis'
+import type { ApiProxy } from '@deepseek-ai/dsh-host-apiproxy/api'
+import { toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
+import { bootHost } from './boot.ts'
+import type { BootHostOptions, HostDefaults } from './boot.ts'
+import { createApiProxy } from './api-proxy.ts'
+
+/** Options for startHost. */
+export interface StartHostOptions {
+  /**
+   * Passed through to bootHost verbatim (persistenceRoot required +
+   * provider?/model?). Future host-level knobs (profile, log sink — any
+   * output added to the assembly MUST be switchable off here) land as
+   * additive fields.
+   */
+  boot: BootHostOptions
+}
+
+/** Running host handle: the contract impl plus its fetch carrier and root ctx. */
+export interface RunningHost {
+  /** Contract implementation (direct calls for in-process consumers; the input of an IPC adapter). */
+  api: ApiProxy
+  /** WHATWG-fetch-shaped carrier (web shell bridges it to node:http; host-side endpoint of an IPC bridge). */
+  handler: { fetch: typeof fetch }
+  /** Host-level default routing (describe and every shell share this single source). */
+  defaults: HostDefaults
+  /**
+   * Root context — a formal seam, not an escape hatch: (1) the mount point for
+   * protocol front-door plugins (`dsh acp` = startHost() → ctx.plugin(uiAcp, config));
+   * (2) headless session-event subscription. Discipline: consuming clients must
+   * not bypass `api` through ctx; shells must not ctx.plugin to alter the
+   * assembly (mounting a front door is the shell's own shape, not an assembly change).
+   */
+  ctx: Context
+  /** Single shutdown exit (ctx.fiber.dispose()). Idempotent: a second call returns the same promise. */
+  dispose(): Promise<void>
+}
+
+/**
+ * Boot the host and assemble its consumption surfaces in one step.
+ * @param options - boot passthrough (see StartHostOptions).
+ * @returns the running host handle shared by every shell shape.
+ */
+export async function startHost(options: StartHostOptions): Promise<RunningHost> {
+  const host = await bootHost(options.boot)
+  const api = createApiProxy(host.ctx, host.defaults)
+  const handler = toFetchHandler(api)
+  let disposing: Promise<void> | undefined
+  return { api, handler, defaults: host.defaults, ctx: host.ctx, dispose: () => (disposing ??= host.dispose()) }
+}

packages/host/runtime/src/web-plugins.ts

@@ -0,0 +1,63 @@
+/**
+ * Web UI plugin assembly: mounts @cordisjs/plugin-loader with an in-memory
+ * entry tree listing the eight UI plugin packages (the P-I config-source bar —
+ * a cordis.yml file form comes later; install/remove currently means editing
+ * this list and restarting). The web plugin registry discovers the entries by
+ * their package.json dshClient declarations; node halves are empty applies,
+ * so mounting them here costs nothing beyond Loader governance.
+ */
+import { createRequire } from 'node:module'
+import type { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+
+/** The eight UI plugin packages served to the browser (order = manifest order). */
+export const WEB_UI_PLUGINS = [
+  '@deepseek-ai/dsh-client-connection',
+  '@deepseek-ai/dsh-client-runtime',
+  '@deepseek-ai/dsh-client-ui-theme',
+  '@deepseek-ai/dsh-client-i18n',
+  '@deepseek-ai/dsh-client-ui-layout',
+  '@deepseek-ai/dsh-client-ui-sidebar',
+  '@deepseek-ai/dsh-client-ui-conversation',
+  '@deepseek-ai/dsh-client-ui-trajectory',
+] as const
+
+/** What the shell hands the web plugin registry (loader view + module resolution seam). */
+export interface MountedWebPlugins {
+  /** Entry enumeration surface of the mounted Loader (registry scan source). */
+  loader: { entries(): Iterable<{ options: { name: string }; fiber?: unknown; disabled: boolean }> }
+  /** Resolve a plugin package's package.json absolute path. */
+  resolvePkgJson: (name: string) => string
+}
+
+/**
+ * Mount the Loader (when absent) and create one in-memory entry per UI
+ * plugin, then wait for the tree to settle. A plugin whose import fails
+ * leaves its entry fiber-less — surfaced here as a loud throw listing the
+ * failures (misconfiguration must not silently drop a UI plugin).
+ * @param ctx - host root context (bootHost product).
+ * @returns the loader view and package.json resolver the registry consumes.
+ */
+export async function mountWebPlugins(ctx: Context): Promise<MountedWebPlugins> {
+  // The Loader resolves bare specifiers against ctx.baseUrl; without one the
+  // import silently fails and every entry stays fiber-less. This package
+  // depends on all eight UI plugins, so its own URL is the right anchor.
+  ctx.baseUrl ??= import.meta.url
+  if (ctx.get('loader') === undefined) await ctx.plugin(Loader)
+  const existing = new Set([...ctx.loader.entries()].map(entry => entry.options.name))
+  for (const name of WEB_UI_PLUGINS) {
+    if (!existing.has(name)) await ctx.loader.create({ name })
+  }
+  await ctx.loader.await()
+  const dead = [...ctx.loader.entries()]
+    .filter(entry => (WEB_UI_PLUGINS as readonly string[]).includes(entry.options.name))
+    .filter(entry => entry.fiber === undefined && !entry.disabled)
+  if (dead.length > 0) {
+    throw new Error(`web-plugins: UI plugin(s) failed to load: ${dead.map(e => e.options.name).join(', ')}`)
+  }
+  const require = createRequire(import.meta.url)
+  return {
+    loader: ctx.loader,
+    resolvePkgJson: name => require.resolve(`${name}/package.json`),
+  }
+}

packages/host/runtime/tests/api-proxy-cold.spec.ts

@@ -0,0 +1,94 @@
+/**
+ * Cold-session and degenerate-composition paths of the host ApiProxy:
+ * sessions.list merging persisted-but-unattached summaries (mtime source,
+ * createdAt fallbacks, lineage projection) and the resume error split when
+ * the composition has no persistence gate and no agent factory.
+ */
+
+import { mkdtempSync, writeFileSync, utimesSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SessionStore from '@deepseek-ai/dsh-session'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import type { RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { createApiProxy } from '../src/api-proxy.ts'
+
+const sid = (id: string): SessionId => id as SessionId
+
+let nextRpc = 1
+function request<P>(payload: P): RpcRequest<P> {
+  return { rpcId: RpcId(`cold-${String(nextRpc++)}`), payload }
+}
+
+function header(id: string, createdAt: number, extra: Partial<SessionHeader> = {}): SessionHeader {
+  return { version: 0, id: sid(id), createdAt, cwd: '/proj', ...extra }
+}
+
+describe('sessions.list cold merge', () => {
+  it('summarizes unattached sessions: log mtime, locate-less and vanished-log createdAt fallbacks, lineage', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const root = mkdtempSync(join(tmpdir(), 'dsh-cold-'))
+    const logPath = join(root, 'a.log')
+    writeFileSync(logPath, 'log-bytes')
+    utimesSync(logPath, 5000, 5000) // mtime 5_000_000 ms — newer than every createdAt below
+    const metas = [
+      header('session-a', 1000),
+      header('session-b', 2000, { parentSession: sid('session-parent') }),
+      header('session-c', 1500),
+    ]
+    // Structural fake of the persistence face list() consumes: list + locate.
+    // locate: a real per-session file (mtime wins), a backend without one
+    // (SQLite shape → createdAt), and a path whose file vanished (stat ENOENT
+    // → createdAt).
+    ctx.provide('sessionPersistence', {
+      list: () => Promise.resolve(metas),
+      locate: (meta: SessionHeader) => {
+        if (meta.id === sid('session-a')) return { kind: 'jsonl', path: logPath }
+        if (meta.id === sid('session-c')) return { kind: 'jsonl', path: join(root, 'vanished.log') }
+        return undefined
+      },
+    })
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
+
+    const response = await api.sessions.list(request({}))
+    expect(response.result.ok).toBe(true)
+    if (!response.result.ok) throw new Error('unreachable')
+    const items = response.result.value.items
+    expect(items.map(item => item.sessionId)).toEqual(['session-a', 'session-b', 'session-c'])
+    const [a, b, c] = items
+    expect(a?.updatedAt).toBeCloseTo(5_000_000, -3)
+    expect(a?.running).toBe(false)
+    expect(a?.cwd).toBe('/proj')
+    expect(a?.parentSessionId).toBeUndefined()
+    expect(b?.updatedAt).toBe(2000)
+    expect(b?.parentSessionId).toBe('session-parent')
+    expect(c?.updatedAt).toBe(1500)
+  })
+})
+
+describe('degenerate composition (no persistence, no factory)', () => {
+  it('list skips the cold merge and resume maps a non-not-found failure to internal', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
+
+    const listed = await api.sessions.list(request({}))
+    expect(listed.result.ok).toBe(true)
+    if (listed.result.ok) expect(listed.result.value.items).toEqual([])
+
+    // No persistence → the servable gate passes silently; the factory-less
+    // registry then rejects resume, which is NOT a SessionNotFound.
+    const response = await api.sessions.history(request({ sessionId: sid('session-ghost') }))
+    expect(response.result.ok).toBe(false)
+    if (!response.result.ok) {
+      expect(response.result.error.code).toBe('internal')
+      expect(response.result.error.message).toMatch(/resume failed for session "session-ghost"/)
+    }
+  })
+})

packages/host/runtime/tests/api-proxy-view.spec.ts

@@ -0,0 +1,179 @@
+/**
+ * Tool-card view computation over the mux live path: three standard card types
+ * arrive on the frame, a presenterless tool ships no view field, and a throwing
+ * presenter soft-falls to no view (the event still ships). Result pairing works
+ * both through the live open-call table and the backscan fallback after
+ * turn/end cleared it.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import SessionStore from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import type { Session, SessionId } from '@deepseek-ai/dsh-session'
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
+import type { MuxFrame, RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api'
+import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { createApiProxy } from '../src/api-proxy.ts'
+
+const reply = (text: string): Promise<ContentBlock[]> => Promise.resolve([{ type: 'text', text }])
+
+function tool(name: string, presenters: Pick<ToolDefinition, 'presentCall' | 'presentResult'>): ToolDefinition {
+  return defineContentToolFixture({
+    name,
+    description: `tool ${name}`,
+    parameters: {},
+    execute: () => reply(`ran:${name}`),
+    ...presenters,
+  })
+}
+
+async function harness(): Promise<{ ctx: Context }> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt, { persona: '' })
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
+  ctx.tools.register(tool('gen', {
+    presentCall: () => ({ card: 'generic', title: 'gen call' }),
+    presentResult: (_args, result) => ({ card: 'generic', title: result.isError ? 'gen failed' : 'gen done' }),
+  }))
+  ctx.tools.register(tool('term', {
+    presentCall: args => ({ card: 'terminal', title: (args as { cmd?: string }).cmd ?? '' }),
+    presentResult: () => ({ card: 'terminal', output: 'done' }),
+  }))
+  ctx.tools.register(tool('diffy', {
+    presentCall: () => ({ card: 'diff', title: 'Write f.txt', diffs: [{ path: 'f.txt', oldText: null, newText: 'x' }] }),
+  }))
+  ctx.tools.register(tool('plain', {}))
+  ctx.tools.register(tool('boom', {
+    presentCall: () => { throw new Error('presenter exploded') },
+  }))
+  return { ctx }
+}
+
+/** Drain frames from an open mux stream until `count` session/event frames arrived. */
+async function collect(iterable: AsyncIterable<RpcRequest<MuxFrame>>, count: number, abort: AbortController): Promise<MuxFrame[]> {
+  const frames: MuxFrame[] = []
+  for await (const frame of iterable) {
+    frames.push(frame.payload)
+    if (frames.filter(f => f.type === 'session/event').length >= count) abort.abort()
+  }
+  return frames
+}
+
+describe('mux live view computation', () => {
+  it('attaches the three standard card views, omits view without a presenter, soft-falls on throw', async () => {
+    const { ctx } = await harness()
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
+    const abort = new AbortController()
+    const stream = api.events.mux({ rpcId: RpcId('t-mux'), payload: {} }, abort.signal)
+    const collected = collect(stream, 7, abort)
+
+    const session = ctx.sessions.create()
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-gen'), name: 'gen', arguments: '{}' })
+    session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-term'), name: 'term', arguments: '{"cmd":"echo hi"}' })
+    session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-diff'), name: 'diffy', arguments: '{}' })
+    session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-plain'), name: 'plain', arguments: '{}' })
+    session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-boom'), name: 'boom', arguments: '{}' })
+    session.append('tool/result', { turn: 1, step: 1, callId: CallId('c-gen'), content: [{ type: 'text', text: 'ok' }], isError: false }, { surfaceOp: 'append' })
+
+    const frames = await collected
+    const events = frames.filter(f => f.type === 'session/event')
+    const byCall = new Map(events
+      .filter(f => f.event.type === 'tool/call' || f.event.type === 'tool/result')
+      .map(f => [`${f.event.type}:${(f.event.data as { callId: string }).callId}`, f]))
+
+    expect(byCall.get('tool/call:c-gen')?.view).toEqual({ for: 'call', view: { card: 'generic', title: 'gen call' } })
+    expect(byCall.get('tool/call:c-term')?.view).toEqual({ for: 'call', view: { card: 'terminal', title: 'echo hi' } })
+    expect(byCall.get('tool/call:c-diff')?.view?.view.card).toBe('diff')
+    // No presenter → the frame carries no view property at all.
+    expect('view' in (byCall.get('tool/call:c-plain') ?? {})).toBe(false)
+    // Throwing presenter → soft-fall: event ships, no view.
+    expect(byCall.get('tool/call:c-boom')).toBeDefined()
+    expect('view' in (byCall.get('tool/call:c-boom') ?? {})).toBe(false)
+    // Result pairing through the live table: presentResult saw the call's args.
+    expect(byCall.get('tool/result:c-gen')?.view).toEqual({ for: 'result', view: { card: 'generic', title: 'gen done' } })
+  })
+
+  it('serves history entries with call/result views, backscan pairing, and soft-falls', async () => {
+    const { ctx } = await harness()
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
+    const session = ctx.sessions.create()
+    // history resolves the agent first; a live structural stub is enough (only
+    // .session is read on this path).
+    ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('tool/call', { turn: 1, step: 1, callId: CallId('h-term'), name: 'term', arguments: '{"cmd":"ls"}' })
+    // meta rides through to presentResult's ToolResult (the spread arm).
+    session.append('tool/result', { turn: 1, step: 1, callId: CallId('h-term'), content: [{ type: 'text', text: 'ok' }], isError: false, meta: { n: 1 } }, { surfaceOp: 'append' })
+    // Unpaired result: no tool/call with this id anywhere in the page.
+    session.append('tool/result', { turn: 1, step: 1, callId: CallId('h-orphan'), content: [{ type: 'text', text: 'x' }], isError: false }, { surfaceOp: 'append' })
+    // Paired, but the call's stored arguments do not parse: backscan soft-falls.
+    session.append('tool/call', { turn: 1, step: 1, callId: CallId('h-bad'), name: 'term', arguments: '{broken' })
+    session.append('tool/result', { turn: 1, step: 1, callId: CallId('h-bad'), content: [{ type: 'text', text: 'y' }], isError: false }, { surfaceOp: 'append' })
+    // Presenterless tool: pairing succeeds but presentResult is absent.
+    session.append('tool/call', { turn: 1, step: 1, callId: CallId('h-plain'), name: 'plain', arguments: '{}' })
+    session.append('tool/result', { turn: 1, step: 1, callId: CallId('h-plain'), content: [{ type: 'text', text: 'z' }], isError: false }, { surfaceOp: 'append' })
+
+    const response = await api.sessions.history({ rpcId: RpcId('t-hist'), payload: { sessionId: session.id } })
+    expect(response.result.ok).toBe(true)
+    if (!response.result.ok) throw new Error('unreachable')
+    const entries = response.result.value.events
+    const byKey = new Map(entries
+      .filter(entry => entry.event.type === 'tool/call' || entry.event.type === 'tool/result')
+      .map(entry => [`${entry.event.type}:${(entry.event.data as { callId: string }).callId}`, entry]))
+    expect(byKey.get('tool/call:h-term')?.view).toEqual({ for: 'call', view: { card: 'terminal', title: 'ls' } })
+    expect(byKey.get('tool/result:h-term')?.view).toEqual({ for: 'result', view: { card: 'terminal', output: 'done' } })
+    expect('view' in (byKey.get('tool/result:h-orphan') ?? {})).toBe(false)
+    expect('view' in (byKey.get('tool/result:h-bad') ?? {})).toBe(false)
+    expect('view' in (byKey.get('tool/result:h-plain') ?? {})).toBe(false)
+  })
+
+  it('drops a disposed session from the live open-call table (result after dispose gets no view)', async () => {
+    const { ctx } = await harness()
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
+    const abort = new AbortController()
+    const stream = api.events.mux({ rpcId: RpcId('t-mux3'), payload: {} }, abort.signal)
+
+    let session: Session | undefined
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      session = inner.sessions.create('session-doomed' as SessionId)
+    }, { inject: ['sessions'] }))
+    session?.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session?.append('tool/call', { turn: 1, step: 1, callId: CallId('c-doomed'), name: 'term', arguments: '{"cmd":"x"}' })
+    // Disposing the owning fiber detaches the session mid-stream; the
+    // session/disposed listener must clear its open-call table entry.
+    await fiber.dispose()
+
+    const frames = await collect(stream, 2, abort)
+    const call = frames.find(f => f.type === 'session/event' && f.event.type === 'tool/call')
+    expect(call?.type === 'session/event' && call.view?.for).toBe('call')
+  })
+
+  it('pairs a result after turn/end via the in-memory backscan fallback', async () => {
+    const { ctx } = await harness()
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
+    const abort = new AbortController()
+    const stream = api.events.mux({ rpcId: RpcId('t-mux2'), payload: {} }, abort.signal)
+    const collected = collect(stream, 4, abort)
+
+    const session = ctx.sessions.create()
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('tool/call', { turn: 1, step: 1, callId: CallId('c-late'), name: 'term', arguments: '{"cmd":"tail"}' })
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    // The turn/end above cleared the live table; pairing must fall back to
+    // scanning the session's in-memory events.
+    session.append('tool/result', { turn: 1, step: 1, callId: CallId('c-late'), content: [{ type: 'text', text: 'ok' }], isError: false }, { surfaceOp: 'append' })
+
+    const frames = await collected
+    const result = frames.find(f => f.type === 'session/event' && f.event.type === 'tool/result')
+    expect(result?.type === 'session/event' && result.view).toEqual({ for: 'result', view: { card: 'terminal', output: 'done' } })
+  })
+})

packages/host/runtime/tests/host-runtime.spec.ts

@@ -0,0 +1,367 @@
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { Context } from 'cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { agentEvents } from '@deepseek-ai/dsh-agent'
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import { LlmAdapter } from '@deepseek-ai/dsh-llm'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+import type { HostFrame, MuxFrame } from '@deepseek-ai/dsh-host-apiproxy/api'
+import type { RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { bootHost, startHost, type HostHandle, type RunningHost } from '../src/index.ts'
+
+/** Scripted adapter: each model call consumes the next chunk list; 'hang' streams then waits for abort. */
+class ScriptedAdapter extends LlmAdapter {
+  constructor(private script: (StreamChunk[] | 'hang')[]) {
+    super()
+  }
+
+  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    const entry = this.script.shift()
+    if (!entry) throw new Error('ScriptedAdapter: script exhausted')
+    if (entry === 'hang') {
+      yield { type: 'block-start', index: 0, blockType: 'text' }
+      await new Promise<void>((_resolve, reject) => {
+        options.signal?.addEventListener('abort', () => { reject(new Error('aborted')) }, { once: true })
+      })
+      return
+    }
+    yield * entry
+  }
+}
+
+function textResponse(text: string): StreamChunk[] {
+  return [
+    { type: 'block-start', index: 0, blockType: 'text' },
+    { type: 'text-delta', index: 0, text },
+    { type: 'block-end', index: 0, block: { type: 'text', text } },
+    { type: 'usage', usage: { inputTokens: 10, outputTokens: text.length } },
+    { type: 'finish', reason: { kind: 'stop' } },
+  ]
+}
+
+function request<P>(payload: P): RpcRequest<P> {
+  return { rpcId: RpcId(`req-${String(nextRpc++)}`), payload }
+}
+let nextRpc = 1
+
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
+  return new Promise((resolve) => {
+    const dispose = ctx.on('agent/status', (subject: Agent, status: string) => {
+      if (subject === agent && status === 'idle') {
+        dispose()
+        resolve()
+      }
+    })
+  })
+}
+
+function expectOk<T>(response: RpcResponse<T>): T {
+  expect(response.result.ok).toBe(true)
+  if (!response.result.ok) throw new Error('unreachable')
+  return response.result.value
+}
+
+let host: RunningHost | undefined
+
+beforeEach(() => {
+  vi.stubEnv('DEEPSEEK_API_KEY', 'spec-placeholder-key')
+})
+
+afterEach(async () => {
+  await host?.dispose()
+  host = undefined
+  vi.unstubAllEnvs()
+})
+
+async function boot(script: (StreamChunk[] | 'hang')[] = []): Promise<RunningHost> {
+  host = await startHost({
+    boot: { persistenceRoot: mkdtempSync(join(tmpdir(), 'dsh-host-runtime-')), provider: 'scripted', model: 'test-model' },
+  })
+  host.ctx.llm.registerAdapter(['scripted'], new ScriptedAdapter(script))
+  return host
+}
+
+describe('bootHost / startHost', () => {
+  it('falls back to the deepseek defaults and disposes idempotently', async () => {
+    const handle: HostHandle = await bootHost({ persistenceRoot: mkdtempSync(join(tmpdir(), 'dsh-boot-')) })
+    expect(handle.defaults).toMatchObject({ provider: 'deepseek', model: 'deepseek-v4-flash' })
+    expect(typeof handle.defaults.cwd).toBe('string')
+    await handle.dispose()
+  })
+
+  it('startHost assembles api + handler over the same defaults and dedupes dispose', async () => {
+    const running = await boot()
+    expect(running.defaults).toMatchObject({ provider: 'scripted', model: 'test-model' })
+    const body = JSON.stringify({ type: 'client-request', rpcId: 'r-h', method: 'host.describe', payload: {} })
+    const response = await running.handler.fetch(new Request('http://x/api/host.describe', { method: 'POST', body }))
+    const parsed = await response.json() as { result: { ok: boolean; value: { provider: string } } }
+    expect(parsed.result.value.provider).toBe('scripted')
+    const first = running.dispose()
+    expect(running.dispose()).toBe(first)
+    await first
+    host = undefined
+  })
+})
+
+describe('host.describe', () => {
+  it('reports version, cwd, defaults, and the attached count', async () => {
+    const { api } = await boot()
+    const value = expectOk(await api.host.describe(request({})))
+    expect(value).toMatchObject({ version: '0.0.1', cwd: process.cwd(), provider: 'scripted', model: 'test-model', attachedSessions: 0 })
+  })
+})
+
+describe('sessions.create / list', () => {
+  it('creates a session (echoing the request rpcId) and lists it newest-first', async () => {
+    const { api } = await boot()
+    const created = await api.sessions.create(request({ cwd: '/tmp' }))
+    const { sessionId } = expectOk(created)
+    expect(created.rpcId).toMatch(/^req-/)
+    const second = expectOk(await api.sessions.create(request({}))).sessionId
+
+    const { items } = expectOk(await api.sessions.list(request({})))
+    expect(items.map(item => item.sessionId)).toContain(sessionId)
+    expect(items.map(item => item.sessionId)).toContain(second)
+    const first = items.find(item => item.sessionId === sessionId)
+    expect(first?.cwd).toBe('/tmp')
+    expect(first?.running).toBe(false)
+    expect(first?.parentSessionId).toBeUndefined()
+  })
+})
+
+describe('sessions.prompt / cancel', () => {
+  it('queues a prompt whose rpcId rides into user/message, then the reply lands', async () => {
+    const running = await boot([textResponse('pong')])
+    const { api, ctx } = running
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const agent = ctx.agents.get(sessionId)
+    expect(agent).toBeDefined()
+    const idle = waitForIdle(ctx, agent as Agent)
+    const promptRequest = request({ sessionId, mode: 'queue' as const, content: [{ type: 'text' as const, text: 'ping' }] })
+    expectOk(await api.sessions.prompt(promptRequest))
+    await idle
+
+    const value = expectOk(await api.sessions.history(request({ sessionId })))
+    const events = value.events.map(entry => entry.event)
+    const userEvent = events.find(event => event.type === 'user/message') as
+      | { data: { source?: { rpcId?: string } } } | undefined
+    expect(userEvent?.data.source?.rpcId).toBe(promptRequest.rpcId)
+    const reply = events.find(event => event.type === 'assistant/message')
+    expect(reply).toBeDefined()
+  })
+
+  it('steer on an idle agent falls through to send', async () => {
+    const running = await boot([textResponse('steered')])
+    const { api, ctx } = running
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const idle = waitForIdle(ctx, ctx.agents.get(sessionId) as Agent)
+    expectOk(await api.sessions.prompt(request({ sessionId, mode: 'steer' as const, content: [{ type: 'text' as const, text: 'now' }] })))
+    await idle
+  })
+
+  it('errors session-not-found on a ghost session', async () => {
+    const { api } = await boot()
+    const response = await api.sessions.prompt(request({ sessionId: 'session-void' as SessionId, mode: 'queue' as const, content: [{ type: 'text' as const, text: 'x' }] }))
+    expect(response.result.ok).toBe(false)
+    if (!response.result.ok) expect(response.result.error.code).toBe('session-not-found')
+  })
+
+  it('maps a synchronous send throw to agent-busy', async () => {
+    const { api } = await boot()
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const poisoned = [{ type: 'text', text: 'x', bad: () => 1 }] as never
+    const response = await api.sessions.prompt(request({ sessionId, mode: 'queue' as const, content: poisoned }))
+    expect(response.result.ok).toBe(false)
+    if (!response.result.ok) expect(response.result.error.code).toBe('agent-busy')
+  })
+
+  it('cancels an attached agent and rejects an unattached one', async () => {
+    const running = await boot(['hang'])
+    const { api, ctx } = running
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const agent = ctx.agents.get(sessionId) as Agent
+    agent.send([{ type: 'text', text: 'run forever' }])
+    expectOk(await api.sessions.cancel(request({ sessionId })))
+
+    const missing = await api.sessions.cancel(request({ sessionId: 'session-none' as SessionId }))
+    expect(missing.result.ok).toBe(false)
+    if (!missing.result.ok) expect(missing.result.error.code).toBe('session-not-found')
+  })
+})
+
+describe('sessions.history', () => {
+  it('implicitly resumes a cold session, deduplicating concurrent calls to one attach', async () => {
+    const persistenceRoot = mkdtempSync(join(tmpdir(), 'dsh-host-resume-'))
+    const first = await startHost({ boot: { persistenceRoot, provider: 'scripted', model: 'test-model' } })
+    first.ctx.llm.registerAdapter(['scripted'], new ScriptedAdapter([textResponse('persisted')]))
+    const { sessionId } = expectOk(await first.api.sessions.create(request({})))
+    const agent = first.ctx.agents.get(sessionId) as Agent
+    const idle = waitForIdle(first.ctx, agent)
+    agent.send([{ type: 'text', text: 'save me' }])
+    await idle
+    await first.dispose()
+
+    host = await startHost({ boot: { persistenceRoot, provider: 'scripted', model: 'test-model' } })
+    host.ctx.llm.registerAdapter(['scripted'], new ScriptedAdapter([]))
+    expect(host.ctx.agents.get(sessionId)).toBeUndefined()
+    const [a, b] = await Promise.all([
+      host.api.sessions.history(request({ sessionId })),
+      host.api.sessions.history(request({ sessionId })),
+    ])
+    for (const response of [a, b]) {
+      const value = expectOk(response)
+      expect(value.events.some(entry => entry.event.type === 'assistant/message')).toBe(true)
+    }
+    expect(host.ctx.agents.get(sessionId)).toBeDefined()
+    expect(host.ctx.agents.list()).toHaveLength(1)
+  })
+
+  it('errors session-not-found when resume fails, deduplicating concurrent resumes', async () => {
+    const { api } = await boot()
+    const ghost = 'session-ghost' as SessionId
+    const [first, second] = await Promise.all([
+      api.sessions.history(request({ sessionId: ghost })),
+      api.sessions.history(request({ sessionId: ghost })),
+    ])
+    for (const response of [first, second]) {
+      expect(response.result.ok).toBe(false)
+      if (!response.result.ok) expect(response.result.error.code).toBe('session-not-found')
+    }
+  })
+
+  it('paginates backwards on message boundaries with hasMore', async () => {
+    const running = await boot([textResponse('a1'), textResponse('a2'), textResponse('a3')])
+    const { api, ctx } = running
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const agent = ctx.agents.get(sessionId) as Agent
+    for (const text of ['q1', 'q2', 'q3']) {
+      const idle = waitForIdle(ctx, agent)
+      agent.send([{ type: 'text', text }])
+      await idle
+    }
+
+    const all = expectOk(await api.sessions.history(request({ sessionId })))
+    expect(all.hasMore).toBe(false)
+    const messageCount = all.events.filter(entry => entry.event.type === 'user/message' || entry.event.type === 'assistant/message').length
+    expect(messageCount).toBe(6)
+
+    const lastPage = expectOk(await api.sessions.history(request({ sessionId, maxMessages: 1 })))
+    expect(lastPage.hasMore).toBe(true)
+    expect(lastPage.events.filter(entry => entry.event.type === 'assistant/message')).toHaveLength(1)
+    expect(lastPage.events.filter(entry => entry.event.type === 'user/message')).toHaveLength(0)
+
+    const firstSeq = lastPage.events[0]?.event.seq as number
+    const olderPage = expectOk(await api.sessions.history(request({ sessionId, beforeSeq: firstSeq, maxMessages: 2 })))
+    expect(olderPage.events.at(-1)?.event.seq).toBeLessThan(firstSeq)
+    expect(olderPage.hasMore).toBe(true)
+    expect(olderPage.events.filter(entry => entry.event.type === 'user/message' || entry.event.type === 'assistant/message').length).toBe(2)
+  })
+})
+
+describe('events streams', () => {
+  it('mux: a pending pull wakes when a frame arrives (waiter path)', async () => {
+    const running = await boot()
+    const { api } = running
+    const ac = new AbortController()
+    const stream = api.events.mux(request({}), ac.signal)[Symbol.asyncIterator]()
+    // no sessions yet: next() must pend on the queue's waiter, not the buffer
+    const pending = stream.next()
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const frame = (await pending).value as RpcRequest<MuxFrame>
+    expect(frame.payload).toMatchObject({ type: 'session/subscribed', sessionId })
+    ac.abort()
+    expect((await stream.next()).done).toBe(true)
+  })
+
+  it('lists fork lineage and announces it on the host stream', async () => {
+    const running = await boot()
+    const { api, ctx } = running
+    const { sessionId: parent } = expectOk(await api.sessions.create(request({})))
+    const ac = new AbortController()
+    const stream = api.events.host(request({}), ac.signal)[Symbol.asyncIterator]()
+    const child = `session-child-${String(Date.now())}` as SessionId
+    const handle = await ctx.agents.create({ sessionId: child, meta: { parentSession: parent }, agentOptions: { provider: 'scripted', model: 'test-model' } })
+    expect(handle.agent.id).toBe(child)
+    const added = (await stream.next()).value as RpcRequest<HostFrame>
+    expect(added.payload).toMatchObject({ type: 'host/session-added', sessionId: child, parentSessionId: parent })
+    const { items } = expectOk(await api.sessions.list(request({})))
+    expect(items.find(item => item.sessionId === child)?.parentSessionId).toBe(parent)
+
+    await handle.dispose()
+    let frame: RpcRequest<HostFrame>
+    do frame = (await stream.next()).value as RpcRequest<HostFrame>
+    while (frame.payload.type !== 'host/session-removed')
+    expect(frame.payload).toMatchObject({ type: 'host/session-removed', sessionId: child })
+    ac.abort()
+  })
+
+  it('mux: emits subscribed baselines, live session events, and new-session subscriptions until abort', async () => {
+    const running = await boot([textResponse('live')])
+    const { api, ctx } = running
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+
+    const ac = new AbortController()
+    const stream = api.events.mux(request({}), ac.signal)[Symbol.asyncIterator]()
+    const baseline = await stream.next()
+    expect((baseline.value as RpcRequest<MuxFrame>).payload).toMatchObject({ type: 'session/subscribed', sessionId })
+
+    const agent = ctx.agents.get(sessionId) as Agent
+    const idle = waitForIdle(ctx, agent)
+    agent.send([{ type: 'text', text: 'go' }])
+    await idle
+    const live = await stream.next()
+    expect((live.value as RpcRequest<MuxFrame>).payload.type).toBe('session/event')
+
+    const other = expectOk(await api.sessions.create(request({}))).sessionId
+    let frame: RpcRequest<MuxFrame>
+    do frame = (await stream.next()).value as RpcRequest<MuxFrame>
+    while (!(frame.payload.type === 'session/subscribed' && frame.payload.sessionId === other))
+
+    ac.abort()
+    expect((await stream.next()).done).toBe(true)
+  })
+
+  it('host: session lifecycle, status flips (disposed suppressed), and agent errors', async () => {
+    const running = await boot([textResponse('x')])
+    const { api, ctx } = running
+    const ac = new AbortController()
+    const stream = api.events.host(request({}), ac.signal)[Symbol.asyncIterator]()
+
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const added = await stream.next()
+    expect((added.value as RpcRequest<HostFrame>).payload).toMatchObject({ type: 'host/session-added', sessionId })
+
+    const agent = ctx.agents.get(sessionId) as Agent
+    const idle = waitForIdle(ctx, agent)
+    agent.send([{ type: 'text', text: 'run' }])
+    await idle
+    const runningFrame = await stream.next()
+    expect((runningFrame.value as RpcRequest<HostFrame>).payload).toMatchObject({ type: 'host/session-status', running: true })
+    const idleFrame = await stream.next()
+    expect((idleFrame.value as RpcRequest<HostFrame>).payload).toMatchObject({ type: 'host/session-status', running: false })
+
+    // Raw ctx.emit lacks the scope carrier the mounted invariants plugin now
+    // enforces; dispatch the way the loop does.
+    agentEvents(ctx, agent).emit('agent/error', 1, 1, new Error('boom'))
+    const errorFrame = await stream.next()
+    expect((errorFrame.value as RpcRequest<HostFrame>).payload).toMatchObject({ type: 'host/agent-error', message: 'Error: boom' })
+
+    ac.abort()
+    // Push-after-done: an event landing between abort and generator wind-down
+    // must be dropped silently, not crash the queue.
+    agentEvents(ctx, agent).emit('agent/error', 1, 1, new Error('late'))
+    expect((await stream.next()).done).toBe(true)
+  })
+})
+
+describe('respond stub', () => {
+  it('always reports not-pending (step2 registry pending)', async () => {
+    const { api } = await boot()
+    const receipt = await api.respond({ type: 'client-response', rpcId: RpcId('r'), result: { ok: true, value: null } })
+    expect(receipt).toEqual({ accepted: false, reason: 'not-pending' })
+  })
+})

packages/host/runtime/tests/web-plugins.e2e.ts

@@ -0,0 +1,71 @@
+/**
+ * Web UI plugin assembly: the in-memory Loader tree mounts all eight UI
+ * packages (node halves), and the webserver registry built over it yields the
+ * full __DSH_BOOT__ manifest — the P-I config-source bar end to end.
+ *
+ * The Loader imports plugin packages through their exports maps (lib/), so
+ * this is a built-artifact e2e: it skips until the workspace build has run
+ * (`pnpm run build`), like the other built-* e2e suites.
+ */
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { Context } from 'cordis'
+import { afterEach, describe, expect, it } from 'vitest'
+import { createHostWebPluginRegistry } from '@deepseek-ai/dsh-host-webserver'
+import { WEB_UI_PLUGINS, mountWebPlugins } from '../src/web-plugins.ts'
+
+const nodeRequire = createRequire(import.meta.url)
+const built = WEB_UI_PLUGINS.every((name) => {
+  try {
+    return existsSync(nodeRequire.resolve(name))
+  } catch {
+    return false
+  }
+})
+
+let root: Context | undefined
+
+afterEach(async () => {
+  await root?.fiber.dispose()
+  root = undefined
+})
+
+describe.skipIf(!built)('mountWebPlugins + registry', () => {
+  it('mounts the eight-package in-memory Loader tree and projects the boot manifest', async () => {
+    root = new Context()
+    const mounted = await mountWebPlugins(root)
+    const registry = createHostWebPluginRegistry({
+      ctx: root,
+      loader: mounted.loader,
+      resolvePkgJson: mounted.resolvePkgJson,
+      onError: (err) => { throw err },
+    })
+    const rows = registry.snapshot()
+    expect(rows.map(r => r.id)).toEqual([...WEB_UI_PLUGINS])
+    // The infra four are the early-load group; the UI four are not.
+    const immediate = rows.filter(r => r.immediately === true).map(r => r.id)
+    expect(immediate).toEqual([
+      '@deepseek-ai/dsh-client-connection',
+      '@deepseek-ai/dsh-client-runtime',
+      '@deepseek-ai/dsh-client-ui-theme',
+      '@deepseek-ai/dsh-client-i18n',
+    ])
+    // Every row resolves a client path under its own package dist/.
+    for (const row of rows) {
+      expect(registry.clientPath(row.id)).toMatch(/dist[/\\]client\.js$/)
+      expect(row.url).toBe(`/plugins/${row.id}/client.js`)
+    }
+    registry.dispose()
+  })
+
+  it('is idempotent: a second mount reuses the loader and creates no duplicate entries', async () => {
+    root = new Context()
+    await mountWebPlugins(root)
+    const second = await mountWebPlugins(root)
+    // ctx.loader hands out a fresh traced proxy per access, so loader identity
+    // is not assertable; the observable contract is a single entry per package.
+    const names = [...second.loader.entries()].map(e => e.options.name)
+      .filter(n => (WEB_UI_PLUGINS as readonly string[]).includes(n))
+    expect(names.length).toBe(WEB_UI_PLUGINS.length)
+  })
+})

packages/host/runtime/tests/web-plugins.spec.ts

@@ -0,0 +1,114 @@
+/**
+ * mountWebPlugins unit coverage (keyless; the real eight-package walk is the
+ * built-artifact e2e). The Loader-facing behavior — baseUrl anchoring, entry
+ * creation with idempotent reuse, the fiber-less fail-loud sweep, and the
+ * resolver seam — is exercised against a stubbed loader service so it runs
+ * without built lib/ artifacts.
+ */
+import { Context } from 'cordis'
+import { afterEach, describe, expect, it } from 'vitest'
+import { WEB_UI_PLUGINS, mountWebPlugins } from '../src/web-plugins.ts'
+
+interface FakeEntry {
+  options: { name: string }
+  fiber?: unknown
+  disabled: boolean
+}
+
+/** Loader stub provided under the real service name (mountWebPlugins skips ctx.plugin(Loader) when present). */
+class FakeLoader {
+  readonly created: string[] = []
+  awaited = 0
+  constructor(private readonly entriesList: FakeEntry[], private readonly onCreate?: (name: string) => void) {}
+  entries(): Iterable<FakeEntry> {
+    return this.entriesList
+  }
+  async create(options: { name: string }): Promise<void> {
+    this.created.push(options.name)
+    this.onCreate?.(options.name)
+  }
+  async await(): Promise<void> {
+    this.awaited += 1
+  }
+}
+
+let root: Context | undefined
+
+afterEach(async () => {
+  await root?.fiber.dispose()
+  root = undefined
+})
+
+function withLoader(entriesList: FakeEntry[], onCreate?: (name: string) => void): { ctx: Context; loader: FakeLoader } {
+  root = new Context()
+  const loader = new FakeLoader(entriesList, onCreate)
+  root.reflect.provide('loader', loader)
+  return { ctx: root, loader }
+}
+
+describe('mountWebPlugins (stubbed loader)', () => {
+  it('creates one entry per UI plugin, awaits the tree, and returns the loader view + resolver', async () => {
+    const entriesList: FakeEntry[] = []
+    const { ctx, loader } = withLoader(entriesList, (name) => {
+      entriesList.push({ options: { name }, fiber: {}, disabled: false })
+    })
+    const mounted = await mountWebPlugins(ctx)
+    expect(loader.created).toEqual([...WEB_UI_PLUGINS])
+    expect(loader.awaited).toBe(1)
+    expect([...mounted.loader.entries()].map(e => e.options.name)).toEqual([...WEB_UI_PLUGINS])
+    // The resolver resolves this package's own manifest through real module resolution.
+    expect(mounted.resolvePkgJson('@deepseek-ai/dsh-host-runtime')).toMatch(/package\.json$/)
+    expect(ctx.baseUrl).toBeDefined()
+  })
+
+  it('reuses existing entries (idempotent mount creates no duplicates)', async () => {
+    const preexisting: FakeEntry[] = WEB_UI_PLUGINS.map(name => ({ options: { name }, fiber: {}, disabled: false }))
+    const { ctx, loader } = withLoader(preexisting)
+    await mountWebPlugins(ctx)
+    expect(loader.created).toEqual([])
+  })
+
+  it('throws listing every fiber-less entry (silent import failure must not drop a UI plugin)', async () => {
+    const entriesList: FakeEntry[] = []
+    const { ctx } = withLoader(entriesList, (name) => {
+      // First two load; the rest stay fiber-less (import failed silently).
+      entriesList.push({ options: { name }, fiber: entriesList.length < 2 ? {} : undefined, disabled: false })
+    })
+    await expect(mountWebPlugins(ctx)).rejects.toThrow(/UI plugin\(s\) failed to load: .*dsh-client-ui-theme/)
+  })
+
+  it('skips disabled entries in the fail-loud sweep (disabled is the one valid fiber-less state)', async () => {
+    const entriesList: FakeEntry[] = WEB_UI_PLUGINS.map(name => ({ options: { name }, fiber: undefined, disabled: true }))
+    const { ctx } = withLoader(entriesList)
+    await expect(mountWebPlugins(ctx)).resolves.toBeDefined()
+  })
+
+  it('mounts the real Loader when none is present (the ctx.plugin(Loader) branch)', async () => {
+    root = new Context()
+    // Environment-dependent outcome: with built lib/ the eight imports load
+    // and the mount resolves; without them every entry stays fiber-less and
+    // the sweep throws its loud list. Either way the branch under test is the
+    // Loader auto-mount. Manual try/catch keeps cordis-traced proxies out of
+    // expect()'s formatting path (pretty-format probes throw on them).
+    // Plain string: the success sentinel and error text share one channel.
+    let outcome: string
+    try {
+      await mountWebPlugins(root)
+      outcome = 'resolved'
+    } catch (error) {
+      outcome = error instanceof Error ? error.message : String(error)
+    }
+    expect(outcome === 'resolved' || /UI plugin\(s\) failed to load/.test(outcome)).toBe(true)
+    expect(root.get('loader') !== undefined).toBe(true)
+  }, 30_000) // built-env run imports eight real plugin packages through the Loader
+
+  it('keeps a caller-set baseUrl (anchors only when absent)', async () => {
+    const entriesList: FakeEntry[] = []
+    const { ctx } = withLoader(entriesList, (name) => {
+      entriesList.push({ options: { name }, fiber: {}, disabled: false })
+    })
+    ctx.baseUrl = 'file:///caller/anchor/'
+    await mountWebPlugins(ctx)
+    expect(ctx.baseUrl).toBe('file:///caller/anchor/')
+  })
+})

packages/host/runtime/tsconfig.json

@@ -0,0 +1,144 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/timer"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../llm/llm-deepseek"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../core/system-prompt"
+    },
+    {
+      "path": "../../core/tools"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../tasks/tasks"
+    },
+    {
+      "path": "../../core/agent-loop"
+    },
+    {
+      "path": "../../session-persistence/session-persistence-jsonl"
+    },
+    {
+      "path": "../../bash/bash-local"
+    },
+    {
+      "path": "../../bash/tool-bash"
+    },
+    {
+      "path": "../../compact/compact-basic"
+    },
+    {
+      "path": "../../fs/fs-local"
+    },
+    {
+      "path": "../../fs/fs-policy"
+    },
+    {
+      "path": "../../fs/tool-fs"
+    },
+    {
+      "path": "../../fs/tool-fs-search"
+    },
+    {
+      "path": "../../llm/token-meter"
+    },
+    {
+      "path": "../../skill/skill"
+    },
+    {
+      "path": "../../skill/skill-local"
+    },
+    {
+      "path": "../../skill/tool-skill"
+    },
+    {
+      "path": "../../spill/spill-local"
+    },
+    {
+      "path": "../../spill/spill-policy"
+    },
+    {
+      "path": "../../subagent/subagent"
+    },
+    {
+      "path": "../../subagent/subagent-fork"
+    },
+    {
+      "path": "../../subagent/subagent-spawn"
+    },
+    {
+      "path": "../../subagent/tool-subagent"
+    },
+    {
+      "path": "../../support/invariants"
+    },
+    {
+      "path": "../../tasks/tool-tasks"
+    },
+    {
+      "path": "../../timeout/timeout-policy"
+    },
+    {
+      "path": "../../todo/tool-todo"
+    },
+    {
+      "path": "../../workflow/tool-workflow"
+    },
+    {
+      "path": "../../workflow/workflow-workerthread"
+    },
+    {
+      "path": "../apiproxy"
+    },
+    {
+      "path": "../../../vendor/loader"
+    },
+    {
+      "path": "../../client/connection"
+    },
+    {
+      "path": "../../client/runtime"
+    },
+    {
+      "path": "../../client/ui-theme"
+    },
+    {
+      "path": "../../client/i18n"
+    },
+    {
+      "path": "../../client/ui-layout"
+    },
+    {
+      "path": "../../client/ui-sidebar"
+    },
+    {
+      "path": "../../client/ui-conversation"
+    },
+    {
+      "path": "../../client/ui-trajectory"
+    }
+  ]
+}

packages/host/webserver/README.md

@@ -0,0 +1,23 @@
+# @deepseek-ai/dsh-host-webserver
+
+Web-shape HTTP carrier: a `node:http` server routing `/api/*` to an injected fetch-shaped handler (node:http ↔ WHATWG bridge with SSE streamed out chunk by chunk) and everything else to static file serving with the step1-locked semantics — traversal outside the dist root is 403, any miss falls back to `index.html` with HTTP 200 (SPA routing), unknown extensions ship as octet-stream, non-GET/HEAD is 405.
+
+The package has zero workspace dependencies on purpose: the handler arrives by structural typing (`{ fetch: typeof fetch }`), so `webserver ← runtime` is a runtime injection relationship, never a package dependency. Web (browser) shape only — Electron loads dist over `file://` and carries fetch over an IPC bridge, not this server. This package never prints; the URL line belongs to the shell.
+
+Client-disconnect detection hangs off the **response** `close` event, not the request: since Node 16, `IncomingMessage` `close` fires as soon as the request body is consumed (immediately for a bodyless GET), which would abort every SSE stream right after open. `RunningWebServer.close()` pairs `close()` with `closeAllConnections()` because SSE connections never end on their own.
+
+A request whose handling throws (a malformed %-escape hitting `decodeURIComponent`, a client dropping mid-body) is answered 400 — or the socket destroyed when headers are already out — and reported to `onError`; it never becomes a process-killing unhandled rejection.
+
+## Model Experience
+
+None, as the package is a pure HTTP carrier between the browser and the injected API handler; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **No TLS, auth, or origin policy** — the server binds `0.0.0.0` and trusts its network; deployment hardening (or fronting it with a real reverse proxy) is deliberately out of scope for the dev-facing v1.
+- **The starter MIME table is minimal** — extensions beyond the vite-emitted set fall back to `application/octet-stream`; extend the table when an asset class actually ships.
+- **`port` is the only listen knob** — bind address and socket options are fixed until a deployment needs them.

packages/host/webserver/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@deepseek-ai/dsh-host-webserver",
+  "description": "Web-shape HTTP carrier: static file serving plus the /api/* bridge to an injected fetch-shaped handler (SSE streamed through)",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "cordis": "^4.0.0-rc.7",
+    "@deepseek-ai/dsh-invariants": "^0.0.1"
+  },
+  "devDependencies": {
+    "cordis": "^4.0.0-rc.7",
+    "@deepseek-ai/dsh-invariants": "workspace:^"
+  }
+}

packages/host/webserver/src/index.ts

@@ -0,0 +1,208 @@
+/**
+ * @deepseek-ai/dsh-host-webserver — the web-shape HTTP carrier: node:http server
+ * routing /api/* to an injected fetch-shaped handler (node:http ↔ WHATWG
+ * bridge with SSE streamed out chunk by chunk) and everything else to static
+ * file serving. Web (browser) shape only — Electron loads dist over file://
+ * and carries fetch over an IPC bridge, not this server. This package never
+ * prints: the URL line belongs to the shell.
+ */
+
+import { createServer } from 'node:http'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { readFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import { serveStatic } from './static.ts'
+import type { HostWebPluginRegistry } from './web-plugins.ts'
+
+export { createHostWebPluginRegistry } from './web-plugins.ts'
+export type {
+  HostWebPluginRegistry, LoaderEntryView, LoaderView, WebPluginBootEntry, WebPluginRegistryDeps,
+} from './web-plugins.ts'
+
+/** Options for startWebServer. */
+export interface WebServerOptions {
+  /** Port to listen on (0.0.0.0). */
+  port: number
+  /**
+   * Absolute path of index.html inside the static root — the caller resolves
+   * it (dist location is workspace knowledge of the shell, not this package's).
+   */
+  distIndex: string
+  /** Fetch-shaped API carrier; /api/*-prefixed requests are bridged to it. */
+  apiHandler: { fetch: typeof fetch }
+  /**
+   * Web plugin table. When present, every index.html response carries a
+   * `window.__DSH_BOOT__` manifest script and `/plugins/<id>/client.js` serves
+   * each plugin's client bundle. Absent = both surfaces off (carrier-only use).
+   */
+  webPlugins?: Pick<HostWebPluginRegistry, 'snapshot' | 'clientPath'>
+}
+
+/** Listening web server handle. */
+export interface RunningWebServer {
+  /** The listening port (for the shell's URL line; equals options.port). */
+  port: number
+  /**
+   * Shutdown: close + closeAllConnections (SSE connections never end on their
+   * own; without the force-close, close() would hang). Idempotent.
+   */
+  close(): Promise<void>
+}
+
+/**
+ * Start the web-shape HTTP server: listen(port, '0.0.0.0').
+ * Routing: /api/* → apiHandler bridge; non-GET/HEAD → 405; everything else →
+ * static with the step1-locked semantics (403 traversal, SPA fallback 200).
+ * A listen failure (EADDRINUSE…) rejects — the shell decides how to exit; a
+ * server error after listen goes to onError. A request whose handling throws
+ * (malformed %-escapes, a client dropping mid-body) is answered 400 — or the
+ * socket destroyed when headers are already out — and reported to onError;
+ * it never becomes an unhandled rejection.
+ * @param options - port, static root anchor, and the API carrier.
+ * @param onError - sink for post-listen server errors and per-request handling failures.
+ * @returns the running server handle once listening.
+ */
+export function startWebServer(options: WebServerOptions, onError: (err: Error) => void): Promise<RunningWebServer> {
+  const { port, distIndex, apiHandler, webPlugins } = options
+  const distRoot = dirname(distIndex)
+  const renderIndex = webPlugins === undefined ? undefined : async (): Promise<string> => {
+    const html = await readFile(distIndex, 'utf8')
+    return injectBootManifest(html, webPlugins.snapshot())
+  }
+
+  const handle = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    /* v8 ignore next -- `?? '/'` arm: node:http always sets url on server
+    requests; the field is only optional on the client-side IncomingMessage type */
+    const rawPath = new URL(req.url ?? '/', 'http://x').pathname
+    if (rawPath.startsWith('/api/')) {
+      await bridge(req, res, apiHandler)
+      return
+    }
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      res.writeHead(405)
+      res.end()
+      return
+    }
+    if (webPlugins !== undefined && rawPath.startsWith('/plugins/') && rawPath.endsWith('/client.js')) {
+      await servePluginBundle(decodeURIComponent(rawPath), res, webPlugins)
+      return
+    }
+    await serveStatic(decodeURIComponent(rawPath), res, distRoot, distIndex, renderIndex)
+  }
+  // Last-resort guard: handle() rejecting would otherwise be an unhandled
+  // rejection, and one malformed request (a bad %-escape hitting
+  // decodeURIComponent, a client dropping mid-body) would kill the whole
+  // process. Nothing after this catch can throw again on the same response.
+  const server = createServer((req, res) => {
+    handle(req, res).catch((err: unknown) => {
+      onError(err instanceof Error ? err : new Error(String(err)))
+      if (res.headersSent) {
+        res.destroy()
+        return
+      }
+      res.writeHead(400)
+      res.end()
+    })
+  })
+
+  let closing: Promise<void> | undefined
+  const close = (): Promise<void> => (closing ??= new Promise((resolveClose) => {
+    server.close(() => { resolveClose() })
+    server.closeAllConnections()
+  }))
+
+  return new Promise((resolveListen, rejectListen) => {
+    server.once('error', rejectListen)
+    server.listen(port, '0.0.0.0', () => {
+      server.off('error', rejectListen)
+      server.on('error', onError)
+      resolveListen({ port, close })
+    })
+  })
+}
+
+/**
+ * Inject the boot manifest into index.html: `window.__DSH_BOOT__` as the first
+ * script in <head> (before the shell bundle reads it). `<` is escaped in the
+ * JSON so plugin-controlled strings cannot break out of the script element.
+ * @param html - the index.html source.
+ * @param plugins - the manifest rows from the registry snapshot.
+ * @returns the html with the manifest script injected.
+ */
+export function injectBootManifest(html: string, plugins: readonly unknown[]): string {
+  const json = JSON.stringify({ plugins }).replaceAll('<', '\\u003c')
+  const script = `<script>window.__DSH_BOOT__ = ${json}</script>`
+  const head = html.indexOf('<head>')
+  if (head !== -1) return `${html.slice(0, head + 6)}${script}${html.slice(head + 6)}`
+  // Headless fixture pages may lack <head>; prepending keeps the read-before-shell ordering.
+  return `${script}${html}`
+}
+
+/** Serve one plugin client bundle from the registry table (unknown id = 404; the id may contain a scope slash). */
+async function servePluginBundle(
+  pathname: string, res: ServerResponse, webPlugins: Pick<HostWebPluginRegistry, 'clientPath'>,
+): Promise<void> {
+  const id = pathname.slice('/plugins/'.length, -'/client.js'.length)
+  const path = webPlugins.clientPath(id)
+  if (path === undefined) {
+    res.writeHead(404)
+    res.end()
+    return
+  }
+  try {
+    const body = await readFile(path)
+    res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8' })
+    res.end(body)
+  } catch {
+    // Registered but unreadable (bundle not built yet): loud 404 beats a silent SPA-fallback HTML page.
+    res.writeHead(404)
+    res.end()
+  }
+}
+
+/** Bridge one node:http request to the WHATWG fetch handler (client close aborts; SSE bodies stream out chunk by chunk). */
+async function bridge(req: IncomingMessage, res: ServerResponse, apiHandler: { fetch: typeof fetch }): Promise<void> {
+  const abort = new AbortController()
+  // Client-disconnect detection MUST hang off the response, not the request:
+  // since Node 16, IncomingMessage 'close' fires as soon as the request body is
+  // fully consumed (immediately for a bodyless GET), which would abort every SSE
+  // stream right after open. ServerResponse 'close' fires on connection teardown;
+  // writableEnded distinguishes a normal end() from the client going away.
+  res.on('close', () => {
+    if (!res.writableEnded) abort.abort()
+  })
+  const chunks: Buffer[] = []
+  for await (const chunk of req) chunks.push(chunk as Buffer)
+  /* v8 ignore next 3 -- `??` arms: node:http always sets url/method on server
+  requests; the fields are only optional on the client-side IncomingMessage type */
+  const request = new Request(new URL(req.url ?? '/', 'http://dsh.internal'), {
+    method: req.method ?? 'GET',
+    headers: Object.fromEntries(Object.entries(req.headers).filter(([, v]) => typeof v === 'string') as [string, string][]),
+    ...chunks.length > 0 ? { body: Buffer.concat(chunks) } : {},
+    signal: abort.signal,
+  })
+  const response = await apiHandler.fetch(request)
+  res.writeHead(response.status, Object.fromEntries(response.headers.entries()))
+  if (response.body === null) {
+    res.end()
+    return
+  }
+  for await (const chunk of response.body) {
+    // Backpressure: a false return means the socket buffer is full — wait for drain
+    // instead of buffering unboundedly (slow/suspended SSE consumers). 'close' also
+    // resolves so a mid-wait disconnect can't park this loop forever; the close
+    // handler above aborts the handler stream, which then ends the iteration.
+    if (!res.write(chunk)) {
+      await new Promise<void>((resolve) => {
+        const done = (): void => {
+          res.off('drain', done)
+          res.off('close', done)
+          resolve()
+        }
+        res.once('drain', done)
+        res.once('close', done)
+      })
+    }
+  }
+  res.end()
+}

packages/host/webserver/src/invariant.ts

@@ -0,0 +1,49 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-host-webserver`.
+ * @module @deepseek-ai/dsh-host-webserver/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-host-webserver'
+
+/** Cordis companion plugin name. */
+export const name = 'host-webserver-invariant'
+/** Service required before the companion can register. */
+export const inject = ['invariants']
+
+/**
+ * Owned relation: the web plugin registry's boot manifest must stay
+ * self-consistent — every snapshot() row must resolve a clientPath under the
+ * same id (the /plugins/<id>/client.js URL it advertises would otherwise 404
+ * on a browser that just received the manifest). Checked synchronously on
+ * every rescan trigger (cordis 'internal/plugin'): snapshot() and
+ * clientPath() read the same table object, so the relation is
+ * self-consistent at any instant — no need to wait out the registry's own
+ * debounced rescan. The registry arrives through the context key the
+ * assembly publishes it under.
+ */
+const install: InvariantInstaller = (ctx, fail) => {
+  ctx.on('internal/plugin', () => {
+    const registry = ctx.get('webPlugins') as
+      | { snapshot(): { id: string; url: string }[]; clientPath(id: string): string | undefined }
+      | undefined
+    if (registry === undefined) return // carrier-only deployments never publish the registry
+    for (const row of registry.snapshot()) {
+      if (registry.clientPath(row.id) === undefined) {
+        fail(`web plugin manifest row "${row.id}" advertises ${row.url} but resolves no client bundle path — the served __DSH_BOOT__ would 404 on fetch`)
+      }
+    }
+  }, { global: true })
+}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/host/webserver/src/static.ts

@@ -0,0 +1,58 @@
+/**
+ * Static file serving for the web shell: the starter MIME table and the
+ * request handler with the semantics locked by the step1 acceptance list —
+ * traversal outside the dist root is 403, any miss falls back to index.html
+ * with HTTP 200 (SPA routing), unknown extensions ship as octet-stream.
+ */
+
+import type { ServerResponse } from 'node:http'
+import { extname, join, normalize, resolve } from 'node:path'
+import { readFile } from 'node:fs/promises'
+
+const MIME: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.json': 'application/json',
+  '.map': 'application/json',
+}
+
+/**
+ * Serve one GET/HEAD static request from the dist root.
+ * @param pathname - decoded URL pathname of the request.
+ * @param res - the node:http response to write.
+ * @param distRoot - absolute dist root directory (resolved by the caller).
+ * @param distIndex - absolute path of index.html inside distRoot.
+ * @param renderIndex - when set, produces the index.html body (boot-manifest
+ * injection) for `/` and every SPA fallback; undefined serves the file verbatim.
+ */
+export async function serveStatic(
+  pathname: string, res: ServerResponse, distRoot: string, distIndex: string,
+  renderIndex?: () => Promise<string>,
+): Promise<void> {
+  const target = resolve(normalize(join(distRoot, pathname)))
+  // Traversal rejection: the target must be distRoot itself (`/`) or stay under it.
+  if (target !== distRoot && !target.startsWith(distRoot + '/')) {
+    res.writeHead(403)
+    res.end()
+    return
+  }
+  const serveIndex = async (): Promise<void> => {
+    const body = renderIndex === undefined ? await readFile(distIndex) : await renderIndex()
+    res.writeHead(200, { 'content-type': MIME['.html'] })
+    res.end(body)
+  }
+  if (target === distRoot || target === distIndex) {
+    await serveIndex()
+    return
+  }
+  try {
+    const body = await readFile(target)
+    res.writeHead(200, { 'content-type': MIME[extname(target)] ?? 'application/octet-stream' })
+    res.end(body)
+  } catch {
+    // Miss (ENOENT/EISDIR) falls back to index.html with 200 (SPA routing).
+    await serveIndex()
+  }
+}

packages/host/webserver/src/web-plugins.ts

@@ -0,0 +1,184 @@
+/**
+ * HostWebPluginRegistry: discovers web-client plugins among the host Loader's
+ * loaded entries by their package.json `dshClient` declaration and resolves
+ * each one's client bundle path from `exports["./client"]`. The webserver
+ * consumes the table to emit `window.__DSH_BOOT__` and to serve
+ * `GET /plugins/<id>/client.js`. Discovery is declaration-only: plugin authors
+ * write package.json; no serve() call surface exists.
+ *
+ * The vendored loader emits no "entry loaded" event (only `loader/entry-init`,
+ * which fires at Entry construction before import/apply), so the registry
+ * scans `loader.entries()` and rescans on cordis `internal/plugin` (fiber
+ * create/dispose), microtask-debounced. Plugin-set changes take effect on
+ * restart per the config-source ruling; the subscription only keeps the table
+ * fresh within a process lifetime.
+ */
+
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import type { Context } from 'cordis'
+
+/** One `window.__DSH_BOOT__.plugins` row (wire shape of api-contracts v3 §9.2). */
+export interface WebPluginBootEntry {
+  /** Plugin id = package name (may contain a scope slash). */
+  id: string
+  /** Bundle URL served by this webserver (`/plugins/<id>/client.js`). */
+  url: string
+  /** Client-half load dependencies (plugin ids), topologically ordered by the client loader. */
+  inject: string[]
+  /** Marks the early-load group: fetched in parallel and applied before all other plugins. */
+  immediately?: boolean
+}
+
+/** The web plugin table consumed by the boot injection and the bundle endpoint. */
+export interface HostWebPluginRegistry {
+  /** Current manifest rows (stable order: loader entry order). */
+  snapshot(): WebPluginBootEntry[]
+  /**
+   * Absolute path of a plugin's client bundle.
+   * @param id - plugin id (package name).
+   * @returns the path, or undefined for an unknown id.
+   */
+  clientPath(id: string): string | undefined
+  /** Remove the loader subscription. */
+  dispose(): void
+}
+
+/** Structural view of a loader entry (webserver keeps zero workspace dependencies; cordis stays a type-only peer). */
+export interface LoaderEntryView {
+  options: { name: string }
+  /** Present once the entry's plugin fiber exists (import succeeded and apply ran/started). */
+  fiber?: unknown
+  /** True when the entry or an owning group is disabled. */
+  disabled: boolean
+}
+
+/** Structural view of the host Loader (entry enumeration is all the registry needs). */
+export interface LoaderView {
+  entries(): Iterable<LoaderEntryView>
+}
+
+/** Dependencies injected by the assembly layer. */
+export interface WebPluginRegistryDeps {
+  /** Host root context; used only to subscribe `internal/plugin` for rescans. */
+  ctx: Context
+  /** The host Loader owning the plugin entries. */
+  loader: LoaderView
+  /**
+   * Resolve a package specifier to its package.json absolute path (assembly
+   * passes `createRequire(...).resolve(`${name}/package.json`)`); injected so
+   * the registry makes no module-resolution assumptions of its own.
+   */
+  resolvePkgJson: (name: string) => string
+  /** Sink for rescan failures (the initial scan throws instead — misconfiguration fails loud at load). */
+  onError: (err: Error) => void
+}
+
+/** package.json `dshClient` declaration shape (file boundary — validated field by field). */
+interface DshClientDeclaration {
+  inject?: string[]
+  platform: string
+  immediately?: boolean
+}
+
+interface WebPluginRecord {
+  entry: WebPluginBootEntry
+  clientPath: string
+}
+
+/** Narrow an unknown parsed JSON value to the dshClient declaration, throwing on malformed fields. */
+function parseDshClient(name: string, value: unknown): DshClientDeclaration | undefined {
+  if (value === undefined) return undefined
+  if (typeof value !== 'object' || value === null) {
+    throw new Error(`web-plugins: ${name} has a non-object dshClient declaration`)
+  }
+  const decl = value as Record<string, unknown>
+  if (typeof decl.platform !== 'string') {
+    throw new Error(`web-plugins: ${name} dshClient.platform must be a string`)
+  }
+  if (decl.inject !== undefined && (!Array.isArray(decl.inject) || decl.inject.some(i => typeof i !== 'string'))) {
+    throw new Error(`web-plugins: ${name} dshClient.inject must be a string array`)
+  }
+  if (decl.immediately !== undefined && typeof decl.immediately !== 'boolean') {
+    throw new Error(`web-plugins: ${name} dshClient.immediately must be a boolean`)
+  }
+  return {
+    platform: decl.platform,
+    ...(decl.inject !== undefined ? { inject: decl.inject as string[] } : {}),
+    ...(decl.immediately !== undefined ? { immediately: decl.immediately } : {}),
+  }
+}
+
+/** Resolve `exports["./client"]` to a relative path, accepting the string and one-level conditional forms. */
+function clientExportOf(name: string, exportsField: unknown): string | undefined {
+  if (typeof exportsField !== 'object' || exportsField === null) return undefined
+  const client = (exportsField as Record<string, unknown>)['./client']
+  if (client === undefined) return undefined
+  if (typeof client === 'string') return client
+  if (typeof client === 'object' && client !== null) {
+    const fallback = (client as Record<string, unknown>).default
+    if (typeof fallback === 'string') return fallback
+  }
+  throw new Error(`web-plugins: ${name} exports["./client"] has an unsupported shape`)
+}
+
+/**
+ * Build the web plugin registry: scan once synchronously (a malformed
+ * declaration throws here — load-time fail loud), then rescan on
+ * `internal/plugin`, microtask-debounced (failures go to `deps.onError`).
+ * @param deps - loader view, resolution hook, and error sink (see {@link WebPluginRegistryDeps}).
+ * @returns the registry handle.
+ */
+export function createHostWebPluginRegistry(deps: WebPluginRegistryDeps): HostWebPluginRegistry {
+  let table = scan(deps)
+
+  let pending = false
+  const unsubscribe = deps.ctx.on('internal/plugin', () => {
+    if (pending) return
+    pending = true
+    queueMicrotask(() => {
+      pending = false
+      try {
+        table = scan(deps)
+      } catch (error) {
+        // Keep serving the previous table: a mid-flight rescan failure must not
+        // take down the boot manifest for plugins that were fine.
+        deps.onError(error instanceof Error ? error : new Error(String(error)))
+      }
+    })
+  })
+
+  return {
+    snapshot: () => [...table.values()].map(record => record.entry),
+    clientPath: id => table.get(id)?.clientPath,
+    dispose: () => { unsubscribe() },
+  }
+}
+
+/** One full table build from the loader's current entries. */
+function scan(deps: WebPluginRegistryDeps): Map<string, WebPluginRecord> {
+  const table = new Map<string, WebPluginRecord>()
+  for (const entry of deps.loader.entries()) {
+    if (entry.fiber === undefined || entry.disabled) continue
+    const name = entry.options.name
+    if (table.has(name)) continue
+    const pkgPath = deps.resolvePkgJson(name)
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as Record<string, unknown>
+    const decl = parseDshClient(name, pkg.dshClient)
+    if (decl === undefined || decl.platform !== 'web') continue
+    const clientRel = clientExportOf(name, pkg.exports)
+    if (clientRel === undefined) {
+      throw new Error(`web-plugins: ${name} declares dshClient but exports no "./client" bundle`)
+    }
+    table.set(name, {
+      entry: {
+        id: name,
+        url: `/plugins/${name}/client.js`,
+        inject: decl.inject ?? [],
+        ...(decl.immediately === true ? { immediately: true } : {}),
+      },
+      clientPath: join(dirname(pkgPath), clientRel),
+    })
+  }
+  return table
+}

packages/host/webserver/tests/invariant.spec.ts

@@ -0,0 +1,50 @@
+/**
+ * Webserver invariant companion: the boot-manifest consistency audit — every
+ * registry snapshot row must resolve a clientPath, checked on fiber lifecycle
+ * events against the assembly-published 'webPlugins' context key.
+ */
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import * as WebserverInvariant from '../src/invariant.ts'
+
+interface RegistryStub {
+  snapshot(): { id: string; url: string }[]
+  clientPath(id: string): string | undefined
+}
+
+async function setup(registry?: RegistryStub): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(InvariantService, { enabled: true })
+  await ctx.plugin(WebserverInvariant).await()
+  if (registry !== undefined) ctx.reflect.provide('webPlugins', registry)
+  return ctx
+}
+
+/** Fire the audit trigger directly (same technique as the scope invariant
+ *  spec): a synchronous emit propagates the fail() throw to the caller. */
+function trigger(ctx: Context): void {
+  ;(ctx.emit as (event: string, ...args: unknown[]) => void)('internal/plugin', ctx.fiber)
+}
+
+describe('webserver manifest invariant', () => {
+  it('stays silent without a registry (carrier-only deployment) and with a consistent table', async () => {
+    const bare = await setup()
+    expect(() => { trigger(bare) }).not.toThrow() // no 'webPlugins' key published
+
+    const consistent = await setup({
+      snapshot: () => [{ id: 'p1', url: '/plugins/p1/client.js' }],
+      clientPath: () => '/tmp/p1/lib/client.js',
+    })
+    expect(() => { trigger(consistent) }).not.toThrow()
+  })
+
+  it('throws on a manifest row whose bundle path no longer resolves', async () => {
+    const ctx = await setup({
+      snapshot: () => [{ id: 'ghost', url: '/plugins/ghost/client.js' }],
+      clientPath: () => undefined,
+    })
+    expect(() => { trigger(ctx) })
+      .toThrow(/manifest row "ghost".*resolves no client bundle path/)
+  })
+})

packages/host/webserver/tests/web-plugins.spec.ts

@@ -0,0 +1,210 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import { createHostWebPluginRegistry, injectBootManifest } from '../src/index.ts'
+import type { LoaderEntryView, WebPluginRegistryDeps } from '../src/index.ts'
+
+/** Write a fake installed package (package.json + optional client bundle) and return its package.json path. */
+function makePkg(root: string, name: string, pkg: Record<string, unknown>, withBundle = true): string {
+  const dir = join(root, name.replaceAll('/', '__'))
+  mkdirSync(join(dir, 'lib'), { recursive: true })
+  writeFileSync(join(dir, 'package.json'), JSON.stringify({ name, ...pkg }))
+  if (withBundle) writeFileSync(join(dir, 'lib', 'client.js'), `// bundle of ${name}`)
+  return join(dir, 'package.json')
+}
+
+const webDecl = (extra: Record<string, unknown> = {}): Record<string, unknown> => ({
+  dshClient: { inject: [], platform: 'web', ...extra },
+  exports: { '.': './lib/index.js', './client': './lib/client.js' },
+})
+
+interface Fixture {
+  deps: WebPluginRegistryDeps
+  entries: LoaderEntryView[]
+  errors: Error[]
+  ctx: Context
+}
+
+function makeDeps(
+  specs: { name: string; pkg: Record<string, unknown>; loaded?: boolean; disabled?: boolean; withBundle?: boolean }[],
+): Fixture {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-webplugins-'))
+  const paths = new Map<string, string>()
+  const entries: LoaderEntryView[] = specs.map((spec) => {
+    paths.set(spec.name, makePkg(root, spec.name, spec.pkg, spec.withBundle ?? true))
+    return { options: { name: spec.name }, fiber: spec.loaded === false ? undefined : {}, disabled: spec.disabled ?? false }
+  })
+  const ctx = new Context()
+  const errors: Error[] = []
+  const deps: WebPluginRegistryDeps = {
+    ctx,
+    loader: { entries: () => entries },
+    resolvePkgJson: (name) => {
+      const path = paths.get(name)
+      if (path === undefined) throw new Error(`unresolvable ${name}`)
+      return path
+    },
+    onError: err => void errors.push(err),
+  }
+  return { deps, entries, errors, ctx }
+}
+
+describe('createHostWebPluginRegistry', () => {
+  it('collects loaded web-declared plugins with url/inject/immediately and client paths', () => {
+    const { deps } = makeDeps([
+      { name: '@deepseek-ai/dsh-client-connection', pkg: webDecl({ immediately: true }) },
+      { name: '@deepseek-ai/dsh-client-ui-layout', pkg: webDecl({ inject: ['@deepseek-ai/dsh-client-runtime'] }) },
+      { name: '@deepseek-ai/dsh-agent', pkg: { exports: { '.': './lib/index.js' } } }, // no dshClient: skipped
+    ])
+    const registry = createHostWebPluginRegistry(deps)
+    const rows = registry.snapshot()
+    expect(rows).toEqual([
+      {
+        id: '@deepseek-ai/dsh-client-connection',
+        url: '/plugins/@deepseek-ai/dsh-client-connection/client.js',
+        inject: [],
+        immediately: true,
+      },
+      {
+        id: '@deepseek-ai/dsh-client-ui-layout',
+        url: '/plugins/@deepseek-ai/dsh-client-ui-layout/client.js',
+        inject: ['@deepseek-ai/dsh-client-runtime'],
+      },
+    ])
+    expect(registry.clientPath('@deepseek-ai/dsh-client-connection')).toMatch(/lib[/\\]client\.js$/)
+    expect(registry.clientPath('@deepseek-ai/dsh-agent')).toBeUndefined()
+    registry.dispose()
+  })
+
+  it('skips entries that are unloaded, disabled, or declare another platform', () => {
+    const { deps } = makeDeps([
+      { name: 'not-loaded', pkg: webDecl(), loaded: false },
+      { name: 'disabled', pkg: webDecl(), disabled: true },
+      { name: 'electron-only', pkg: { dshClient: { platform: 'electron' }, exports: { './client': './lib/client.js' } } },
+    ])
+    const registry = createHostWebPluginRegistry(deps)
+    expect(registry.snapshot()).toEqual([])
+    registry.dispose()
+  })
+
+  it('fails loud at build time on a dshClient declaration without a "./client" export', () => {
+    const { deps } = makeDeps([
+      { name: 'broken', pkg: { dshClient: { platform: 'web' }, exports: { '.': './lib/index.js' } } },
+    ])
+    expect(() => createHostWebPluginRegistry(deps)).toThrow(/declares dshClient but exports no/)
+  })
+
+  it('fails loud on malformed declaration fields', () => {
+    for (const dshClient of [42, { platform: 7 }, { platform: 'web', inject: 'nope' }, { platform: 'web', immediately: 'yes' }]) {
+      const { deps } = makeDeps([{ name: 'bad', pkg: { dshClient, exports: { './client': './lib/client.js' } } }])
+      expect(() => createHostWebPluginRegistry(deps)).toThrow(/dshClient/)
+    }
+  })
+
+  it('rescans on internal/plugin (debounced) and keeps the old table when a rescan fails', async () => {
+    const { deps, entries, errors, ctx } = makeDeps([
+      { name: 'late-loader', pkg: webDecl(), loaded: false },
+    ])
+    const registry = createHostWebPluginRegistry(deps)
+    expect(registry.snapshot()).toEqual([])
+
+    // Entry finishes loading; a fiber lifecycle event triggers the debounced rescan.
+    ;(entries[0] as { fiber?: unknown }).fiber = {}
+    ctx.emit('internal/plugin', ctx.fiber)
+    ctx.emit('internal/plugin', ctx.fiber) // debounce: two emissions, one rescan
+    await Promise.resolve()
+    expect(registry.snapshot().map(row => row.id)).toEqual(['late-loader'])
+
+    // A failing rescan reports the error and keeps serving the previous table.
+    entries.push({ options: { name: 'ghost' }, fiber: {}, disabled: false })
+    ctx.emit('internal/plugin', ctx.fiber)
+    await Promise.resolve()
+    expect(errors).toHaveLength(1)
+    expect(registry.snapshot().map(row => row.id)).toEqual(['late-loader'])
+
+    // After dispose, further fiber events no longer rescan.
+    registry.dispose()
+    entries.pop()
+    ctx.emit('internal/plugin', ctx.fiber)
+    await Promise.resolve()
+    expect(errors).toHaveLength(1)
+  })
+})
+
+describe('injectBootManifest', () => {
+  it('injects the manifest as the first script inside <head> and escapes </script> breakouts', () => {
+    const html = '<html><head><script src="app.js"></script></head><body></body></html>'
+    const out = injectBootManifest(html, [{ id: 'x</script><script>alert(1)', url: '/plugins/x/client.js', inject: [] }])
+    expect(out.indexOf('window.__DSH_BOOT__')).toBeLessThan(out.indexOf('app.js'))
+    expect(out).not.toContain('</script><script>alert(1)')
+    expect(out).toContain('\\u003c/script')
+  })
+
+  it('prepends when the page has no <head>', () => {
+    const out = injectBootManifest('<body>x</body>', [])
+    expect(out.startsWith('<script>window.__DSH_BOOT__')).toBe(true)
+  })
+})
+
+describe('clientExportOf shapes (through the registry build)', () => {
+  it('accepts the conditional {types, default} export form', () => {
+    const { deps } = makeDeps([{
+      name: 'conditional',
+      pkg: {
+        dshClient: { platform: 'web' },
+        exports: { './client': { types: './lib/types/client/index.d.ts', default: './lib/client.js' } },
+      },
+    }])
+    const registry = createHostWebPluginRegistry(deps)
+    expect(registry.clientPath('conditional')).toMatch(/lib[/\\]client\.js$/)
+    registry.dispose()
+  })
+
+  it('rejects a conditional form without a string default, an array form, and a non-object exports field', () => {
+    for (const exportsField of [
+      { './client': { types: './x.d.ts' } },
+      { './client': ['./a.js'] },
+    ]) {
+      const { deps } = makeDeps([{ name: 'bad-shape', pkg: { dshClient: { platform: 'web' }, exports: exportsField } }])
+      expect(() => createHostWebPluginRegistry(deps)).toThrow(/unsupported shape/)
+    }
+    // Non-object exports: treated as "no ./client export" → the declares-but-no-bundle throw.
+    const { deps } = makeDeps([{ name: 'no-exports', pkg: { dshClient: { platform: 'web' }, exports: './single.js' } }])
+    expect(() => createHostWebPluginRegistry(deps)).toThrow(/declares dshClient but exports no/)
+  })
+
+  it('skips duplicate loader entries for the same package name (first wins)', () => {
+    const { deps, entries } = makeDeps([{ name: 'dup-entry', pkg: webDecl() }])
+    const first = entries[0] as LoaderEntryView
+    entries.push({ options: { name: 'dup-entry' }, fiber: {}, disabled: false })
+    void first
+    const registry = createHostWebPluginRegistry(deps)
+    expect(registry.snapshot().filter(r => r.id === 'dup-entry')).toHaveLength(1)
+    registry.dispose()
+  })
+
+  it('rejects a null conditional form and wraps a non-Error rescan throw', async () => {
+    // client: null → the object-form branch's null guard.
+    const nulled = makeDeps([{ name: 'null-client', pkg: { dshClient: { platform: 'web' }, exports: { './client': null } } }])
+    expect(() => createHostWebPluginRegistry(nulled.deps)).toThrow(/unsupported shape/)
+
+    // Non-Error rescan throw: resolvePkgJson throws a string; onError must get a wrapped Error.
+    const { deps, entries, errors, ctx } = makeDeps([{ name: 'ok-one', pkg: webDecl() }])
+    const registry = createHostWebPluginRegistry(deps)
+    entries.push({ options: { name: 'ghost-two' }, fiber: {}, disabled: false })
+    const original = deps.resolvePkgJson
+    deps.resolvePkgJson = (name) => {
+
+      if (name === 'ghost-two') throw 'string failure'
+      return original(name)
+    }
+    ctx.emit('internal/plugin', ctx.fiber)
+    await Promise.resolve()
+    expect(errors[0]).toBeInstanceOf(Error)
+    expect(String(errors[0])).toContain('string failure')
+    registry.dispose()
+  })
+
+})

packages/host/webserver/tests/webserver.spec.ts

@@ -0,0 +1,337 @@
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs'
+import { createServer as createNetServer, type AddressInfo } from 'node:net'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { startWebServer, type RunningWebServer } from '../src/index.ts'
+
+/** RunningWebServer.port echoes options.port, so tests must pick a concrete free port up front. */
+function freePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const probe = createNetServer()
+    probe.once('error', reject)
+    probe.listen(0, () => {
+      const port = (probe.address() as AddressInfo).port
+      probe.close(() => { resolve(port) })
+    })
+  })
+}
+
+/** dist fixture: index.html + one asset of each MIME class + a subdir. */
+function makeDist(): { distIndex: string; distRoot: string } {
+  const distRoot = mkdtempSync(join(tmpdir(), 'dsh-webserver-'))
+  writeFileSync(join(distRoot, 'index.html'), '<html>INDEX</html>')
+  writeFileSync(join(distRoot, 'app.js'), 'console.log(1)')
+  writeFileSync(join(distRoot, 'app.css'), 'body{}')
+  writeFileSync(join(distRoot, 'logo.svg'), '<svg/>')
+  writeFileSync(join(distRoot, 'data.json'), '{}')
+  writeFileSync(join(distRoot, 'app.js.map'), '{}')
+  writeFileSync(join(distRoot, 'blob.bin'), 'BIN')
+  mkdirSync(join(distRoot, 'sub'))
+  writeFileSync(join(distRoot, 'sub', 'page.html'), '<html>SUB</html>')
+  return { distIndex: join(distRoot, 'index.html'), distRoot }
+}
+
+const echoingApi = {
+  fetch: async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    const req = input instanceof Request ? input : new Request(input, init)
+    if (req.url.endsWith('/api/echo')) {
+      return Response.json({ method: req.method, body: await req.text(), header: req.headers.get('x-probe') })
+    }
+    if (req.url.endsWith('/api/empty')) return new Response(null, { status: 204 })
+    if (req.url.endsWith('/api/big')) {
+      // Chunks far above any socket highWaterMark force res.write to return false.
+      const big = new Uint8Array(4 * 1024 * 1024).fill(65)
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.enqueue(big)
+          controller.enqueue(big)
+          controller.close()
+        },
+      })
+      return new Response(stream, { headers: { 'content-type': 'application/octet-stream' } })
+    }
+    if (req.url.endsWith('/api/sse')) {
+      const encoder = new TextEncoder()
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.enqueue(encoder.encode('data: one\n\n'))
+          controller.enqueue(encoder.encode('data: two\n\n'))
+          controller.close()
+        },
+      })
+      return new Response(stream, { headers: { 'content-type': 'text/event-stream' } })
+    }
+    if (req.url.endsWith('/api/throw-string')) {
+      // Non-Error rejection: the guard must wrap it for onError.
+      throw 'string failure'
+    }
+    if (req.url.endsWith('/api/explode-mid-stream')) {
+      // Headers go out with the first chunk, then the source errors: the
+      // guard's headersSent leg must destroy the socket, not writeHead again.
+      // The error is deferred a tick so the 200 + first chunk actually flush
+      // to the client before the teardown.
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.enqueue(new TextEncoder().encode('data: first\n\n'))
+          setTimeout(() => { controller.error(new Error('stream exploded')) }, 20)
+        },
+      })
+      return new Response(stream, { headers: { 'content-type': 'text/event-stream' } })
+    }
+    if (req.url.endsWith('/api/abort-probe')) {
+      // Endless SSE that only ends when the request signal aborts.
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          req.signal.addEventListener('abort', () => {
+            try {
+              controller.close()
+            } catch { /* already closed by teardown: nothing else can reach this */ }
+          }, { once: true })
+          controller.enqueue(new TextEncoder().encode('data: open\n\n'))
+        },
+      })
+      return new Response(stream, { headers: { 'content-type': 'text/event-stream' } })
+    }
+    return new Response('nope', { status: 404 })
+  },
+}
+
+let server: RunningWebServer | undefined
+
+afterEach(async () => {
+  await server?.close()
+  server = undefined
+})
+
+async function boot(onError: (err: Error) => void = () => undefined): Promise<string> {
+  const { distIndex } = makeDist()
+  const port = await freePort()
+  server = await startWebServer({ port, distIndex, apiHandler: echoingApi }, onError)
+  return `http://127.0.0.1:${String(server.port)}`
+}
+
+describe('startWebServer', () => {
+  it('reports the listening port and closes idempotently', async () => {
+    const { distIndex } = makeDist()
+    const port = await freePort()
+    server = await startWebServer({ port, distIndex, apiHandler: echoingApi }, () => undefined)
+    expect(server.port).toBe(port)
+    const first = server.close()
+    const second = server.close()
+    expect(second).toBe(first)
+    await first
+    server = undefined
+  })
+
+  it('rejects when the port is already taken', async () => {
+    const { distIndex } = makeDist()
+    const port = await freePort()
+    server = await startWebServer({ port, distIndex, apiHandler: echoingApi }, () => undefined)
+    await expect(startWebServer({ port, distIndex, apiHandler: echoingApi }, () => undefined))
+      .rejects.toMatchObject({ code: 'EADDRINUSE' })
+  })
+})
+
+describe('static serving', () => {
+  it('serves index at /, subpaths by MIME, octet-stream for unknown, SPA fallback on miss', async () => {
+    const base = await boot()
+    const index = await fetch(`${base}/`)
+    expect(index.status).toBe(200)
+    expect(index.headers.get('content-type')).toBe('text/html; charset=utf-8')
+    expect(await index.text()).toBe('<html>INDEX</html>')
+
+    expect((await fetch(`${base}/app.js`)).headers.get('content-type')).toBe('text/javascript; charset=utf-8')
+    expect((await fetch(`${base}/app.css`)).headers.get('content-type')).toBe('text/css; charset=utf-8')
+    expect((await fetch(`${base}/logo.svg`)).headers.get('content-type')).toBe('image/svg+xml')
+    expect((await fetch(`${base}/data.json`)).headers.get('content-type')).toBe('application/json')
+    expect((await fetch(`${base}/app.js.map`)).headers.get('content-type')).toBe('application/json')
+    expect((await fetch(`${base}/blob.bin`)).headers.get('content-type')).toBe('application/octet-stream')
+    expect(await (await fetch(`${base}/sub/page.html`)).text()).toBe('<html>SUB</html>')
+
+    const miss = await fetch(`${base}/routes/deep/link`)
+    expect(miss.status).toBe(200)
+    expect(await miss.text()).toBe('<html>INDEX</html>')
+  })
+
+  it('403s traversal outside the dist root and 405s non-GET/HEAD', async () => {
+    const base = await boot()
+    // %2e%2e would be dot-collapsed by WHATWG URL parsing on both ends; an
+    // encoded slash keeps the segment intact until the server's decodeURIComponent.
+    const traversal = await fetch(`${base}/..%2f..%2fetc%2fpasswd`)
+    expect(traversal.status).toBe(403)
+    const put = await fetch(`${base}/index.html`, { method: 'PUT', body: 'x' })
+    expect(put.status).toBe(405)
+  })
+
+  it('answers HEAD like GET (no 405)', async () => {
+    const base = await boot()
+    const head = await fetch(`${base}/`, { method: 'HEAD' })
+    expect(head.status).toBe(200)
+  })
+})
+
+describe('web plugin surfaces (boot injection + bundle endpoint)', () => {
+  const rows = [
+    { id: '@deepseek-ai/dsh-client-connection', url: '/plugins/@deepseek-ai/dsh-client-connection/client.js', inject: [], immediately: true },
+    { id: '@deepseek-ai/dsh-client-ui-layout', url: '/plugins/@deepseek-ai/dsh-client-ui-layout/client.js', inject: ['@deepseek-ai/dsh-client-runtime'] },
+  ]
+
+  async function bootWithPlugins(): Promise<string> {
+    const { distIndex, distRoot } = makeDist()
+    writeFileSync(join(distRoot, 'bundle.js'), 'window.DSHClientProxy.loadPlugin({})')
+    const webPlugins = {
+      snapshot: () => rows,
+      clientPath: (id: string) => id === rows[0]?.id ? join(distRoot, 'bundle.js') : undefined,
+    }
+    const port = await freePort()
+    server = await startWebServer({ port, distIndex, apiHandler: echoingApi, webPlugins }, () => undefined)
+    return `http://127.0.0.1:${String(server.port)}`
+  }
+
+  it('injects window.__DSH_BOOT__ into / and SPA fallbacks; asset requests stay verbatim', async () => {
+    const base = await bootWithPlugins()
+    const index = await (await fetch(`${base}/`)).text()
+    expect(index).toContain('window.__DSH_BOOT__')
+    const manifest = /window\.__DSH_BOOT__ = (.*?)<\/script>/.exec(index)?.[1]
+    expect(JSON.parse(manifest ?? '')).toEqual({ plugins: rows })
+
+    const fallback = await (await fetch(`${base}/routes/deep/link`)).text()
+    expect(fallback).toContain('window.__DSH_BOOT__')
+    const direct = await (await fetch(`${base}/index.html`)).text()
+    expect(direct).toContain('window.__DSH_BOOT__')
+
+    expect(await (await fetch(`${base}/app.js`)).text()).toBe('console.log(1)')
+  })
+
+  it('serves registered client bundles and 404s unknown ids (no SPA fallback)', async () => {
+    const base = await bootWithPlugins()
+    const bundle = await fetch(`${base}/plugins/@deepseek-ai/dsh-client-connection/client.js`)
+    expect(bundle.status).toBe(200)
+    expect(bundle.headers.get('content-type')).toBe('text/javascript; charset=utf-8')
+    expect(await bundle.text()).toContain('DSHClientProxy')
+
+    expect((await fetch(`${base}/plugins/unknown/client.js`)).status).toBe(404)
+  })
+
+  it('404s a registered id whose bundle file is unreadable (unbuilt dist must fail loud, not fall back to HTML)', async () => {
+    const { distIndex } = makeDist()
+    const webPlugins = {
+      snapshot: () => rows,
+      clientPath: () => '/nonexistent/lib/client.js',
+    }
+    const port = await freePort()
+    server = await startWebServer({ port, distIndex, apiHandler: echoingApi, webPlugins }, () => undefined)
+    const res = await fetch(`http://127.0.0.1:${String(server.port)}/plugins/@deepseek-ai/dsh-client-connection/client.js`)
+    expect(res.status).toBe(404)
+  })
+
+  it('keeps both surfaces off without the webPlugins option', async () => {
+    const base = await boot()
+    expect(await (await fetch(`${base}/`)).text()).toBe('<html>INDEX</html>')
+    // No plugin route: falls through to static SPA fallback semantics.
+    const res = await fetch(`${base}/plugins/x/client.js`)
+    expect(res.status).toBe(200)
+    expect(await res.text()).toBe('<html>INDEX</html>')
+  })
+})
+
+describe('request-handling guard (one bad request must not kill the process)', () => {
+  it('400s malformed %-escapes, reports to onError, and stays alive', async () => {
+    const errors: Error[] = []
+    const base = await boot(err => errors.push(err))
+    for (const path of ['/%', '/%c0', '/%zz%']) {
+      expect((await fetch(`${base}${path}`)).status).toBe(400)
+    }
+    expect(errors.length).toBe(3)
+    expect(errors[0]?.name).toBe('URIError')
+    // The barrage left the server serving.
+    expect((await fetch(`${base}/`)).status).toBe(200)
+  })
+
+  it('wraps a non-Error throw for onError and still answers 400', async () => {
+    const errors: Error[] = []
+    const base = await boot(err => errors.push(err))
+    expect((await fetch(`${base}/api/throw-string`, { method: 'POST' })).status).toBe(400)
+    expect(errors[0]).toBeInstanceOf(Error)
+    expect(errors[0]?.message).toBe('string failure')
+  })
+
+  it('destroys the socket when the failure lands after headers went out', async () => {
+    const errors: Error[] = []
+    const base = await boot(err => errors.push(err))
+    const response = await fetch(`${base}/api/explode-mid-stream`)
+    expect(response.status).toBe(200) // headers made it out before the explosion
+    await expect(response.text()).rejects.toThrow() // then the socket is torn down
+    expect(errors.length).toBe(1)
+    expect((await fetch(`${base}/`)).status).toBe(200)
+  })
+})
+
+describe('/api bridge', () => {
+  it('forwards method, headers, and body; relays status and body back', async () => {
+    const base = await boot()
+    const response = await fetch(`${base}/api/echo`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-probe': 'p1' },
+      body: JSON.stringify({ n: 1 }),
+    })
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({ method: 'POST', body: '{"n":1}', header: 'p1' })
+  })
+
+  it('relays a bodyless response', async () => {
+    const base = await boot()
+    const response = await fetch(`${base}/api/empty`, { method: 'POST' })
+    expect(response.status).toBe(204)
+    expect(await response.text()).toBe('')
+  })
+
+  it('streams SSE frames through chunk by chunk', async () => {
+    const base = await boot()
+    const response = await fetch(`${base}/api/sse`)
+    expect(response.headers.get('content-type')).toBe('text/event-stream')
+    expect(await response.text()).toBe('data: one\n\ndata: two\n\n')
+  })
+
+  it('waits for drain when a streamed chunk overfills the socket buffer', async () => {
+    // 4 MiB chunks dwarf the socket highWaterMark, so res.write returns false
+    // and the bridge parks on 'drain'; reading the body to completion proves
+    // the loop resumed instead of dropping the remainder.
+    const base = await boot()
+    const response = await fetch(`${base}/api/big`)
+    const body = new Uint8Array(await response.arrayBuffer())
+    expect(body.length).toBe(8 * 1024 * 1024)
+    expect(body[0]).toBe(65)
+    expect(body[body.length - 1]).toBe(65)
+  })
+
+  it('releases a drain wait when the client disconnects mid-chunk', async () => {
+    // The 'close' leg of the drain race: abort while the socket buffer is
+    // still full so the parked write wakes via 'close', not 'drain'.
+    const base = await boot()
+    const ac = new AbortController()
+    const response = await fetch(`${base}/api/big`, { signal: ac.signal })
+    const reader = response.body?.getReader()
+    const first = await reader?.read()
+    expect(first?.value?.length).toBeGreaterThan(0)
+    ac.abort()
+    // afterEach close() completing is the leak assertion, same as abort-probe.
+    await new Promise((resolve) => { setTimeout(resolve, 50) })
+  })
+
+  it('aborts the bridged request when the client disconnects mid-SSE', async () => {
+    const base = await boot()
+    const ac = new AbortController()
+    const response = await fetch(`${base}/api/abort-probe`, { signal: ac.signal })
+    const reader = response.body?.getReader()
+    expect(reader).toBeDefined()
+    const first = await reader?.read()
+    expect(new TextDecoder().decode(first?.value)).toContain('open')
+    ac.abort()
+    // server-side abort propagation has no client-observable handshake beyond
+    // the closed connection; close() would hang on a leaked live SSE socket,
+    // so afterEach completing IS the assertion that the bridge released it.
+    await new Promise((resolve) => { setTimeout(resolve, 50) })
+  })
+})

packages/host/webserver/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}