Merge origin/master into goal-ui: adopt the rewritten client core and apiproxy carrier

Conflict rulings follow the projection-reattach plan:
- host/runtime package (deleted on master): take master; the PR's boot
  composition moves to the cordis.yml roster and its goals handlers will be
  re-landed in dsh-host-apiproxy; the session.prompt slash interception and
  its spec are dropped entirely (superseded by command.execute + command/run
  logging).
- client core (rewritten on master): take master; the PR's Session goal
  fields/methods, ConversationSnapshot.goal, goalActions injection, and the
  hard-mounted GoalBar are all superseded by the 'goal' session projection
  (useProjection) and will return as the ui-goal plugin.
- wire contract: union of master's workspace/command/skill domains and the
  PR's goal domain, minus goal.get (the read side is the projection block +
  session/projection frames; six mutation RPCs stay).
- GoalBar component and spec leave ui-conversation (they re-land in the new
  ui-goal package); IconSparkle16 stays in ui-conversation chat.
- The web-slash-command-dispatch note documents the dropped interception and
  is removed; the goal-bar note will be rewritten for the projection model.
- pnpm-lock.yaml taken from master (reinstall recomputes).

packages/host/apiproxy/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/host/apiproxy/README.md
+README.md: c20887b73b9b9deb278db30d34d84df07257d664
+README.zh.md: 18a2f97477e5f57127371429b0dd59ba01f04341

packages/host/apiproxy/README.md

@@ -1,6 +1,8 @@
 # @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`.
+English | [中文](README.zh.md)
+
+The API gateway every client shape shares: the TS contract (`src/api/`, zero Node dependencies, importable from the browser), the fetch carrier pair (`src/fetch/`: `toFetchHandler` on the host side, `AbstractApiClient` plus platform subclasses on the client side), and the host-side implementation (`src/api-proxy.ts`: `createApiProxy` plus the default-exported `ApiProxyService` gateway plugin — config `{provider, model, workspaceRoot?}`, provides `ctx.apiProxy`). Transport-agnostic by design: this package registers no routes; carriers (HTTP today, IPC later) wrap `ctx.apiProxy` themselves. The shipped core composition lives in [`apps/cli/cordis.yml`](../../../apps/cli/cordis.yml).
 
 ## Contract layer (`/api`)
 
@@ -8,6 +10,20 @@ Wire messages form a four-quadrant discriminated union — who initiates × requ
 
 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).
 
+`session.history`'s tail page (`beforeSeq` absent) additionally carries an optional `projections` block — the watermark snapshot of every unit registered on `ctx.sessionProjections` (`@deepseek-ai/dsh-session-projection`), with `asOfSeq` = the last event seq the values reflect (`-1` on an empty log). The gateway also subscribes to the registry's change feed and mints a `session/projection` mux frame per changed unit (`{sessionId, key, value, seq}` — live push state, never logged; clients hold one generic per-session value store under higher-seq-wins). The carrier holds zero domain knowledge (each value passed its unit's own schema inside the registry; the wire schemas keep `values`/`value` wide); loadOlder pages never carry the block, and a composition without the registry serves histories without either surface.
+
+Session titles ride the generic projection pair like every other domain — the history-tail `projections` block plus `session/projection` frames under the `title` key (the bespoke `session/title` frame is retired). Titles do not join `session.list`; cold sessions remain metadata-only there until opening or resuming attaches their logs.
+
+Session model routing is a session-domain contract. `session.models` returns the selected provider/model/reasoning target with provider-grouped advisory models, exact-route reasoning metadata, and provider-local lookup failures. `session.selectModel` validates the optional adapter-owned reasoning effort and replaces the complete target selected for the next prompt-assembly boundary. Catalog membership is not validation: an adapter may resolve an unlisted model, while an unavailable route or unsupported effort returns `model-unavailable`.
+
+Workspace and Session lists are separate reconnect baselines. `workspace.create` creates a unique name or adopts an existing directory, `workspace.delete` removes only the Workspace registration, `session.create` accepts an optional preallocated Session id, and `host/workspace-changed`, `host/workspace-removed`, plus `host/session-added` carry committed increments in either arrival order. Registration deletion preserves the directory and session logs; its Sessions remain in `session.list` and become Ungrouped. `SessionSummary.blank` and the `host/session-added` frame carry the derived zero-events bit: clients hide blank sessions and reuse them per workspace, flip blank on the first `host/session-status(running:true)`, and treat `session.list` as the reconnect authority; cold summaries are never blank because lazy persistence keeps never-appended sessions out of `list()`.
+
+`host.pickDirectory` opens one native directory picker and returns its selected path, or `null` when the user cancels. Its host implementation invokes platform tools without a shell: `osascript` on macOS, an STA PowerShell `FolderBrowserDialog` on Windows, and Zenity with a KDialog fallback on Linux. The picker function is injectable for tests. This user-paced method is the sole unary call exempt from the default 30-second timeout; caller and connection aborts still propagate to the native process. The browser carrier separately restricts this privileged method to loopback, same-origin requests.
+
+`host.openPath` opens a filesystem path with the operating system's default application (`open` on macOS, `Invoke-Item` on Windows, `xdg-open` on Linux). The opener is injectable for tests. The browser carrier applies the same loopback, same-origin restriction as `host.pickDirectory`.
+
+The `command.*` and `skill.*` domains expose the host command registry and skill catalog to clients. Every method addresses one session's agent by `sessionId` (a served session always has an Agent; `command.*` resumes cold sessions through the same path as `session.*`, while `skill.list` resolves the project root from the session header without touching the Agent registry). `command.execute` runs a slash-command line host-side with pure admission semantics: the response reports whether the line resolved to a handler plus the minted lifecycle `commandId` when it did (correlating the acknowledgment with the flow node), while the outcome rides the durably logged `command/run`/`command/done` lifecycle pair broadcast on the mux stream; the carrier's request signal cancels the running handler. `host/commands-changed` is the catalog invalidation frame: clients refetch `command.list` instead of diffing.
+
 ## 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.
@@ -22,6 +38,7 @@ 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.
+- **`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 `src/api-proxy.ts` and is still minimal (questions only, no approvals).
 - **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.
+- **Linux native picker requires desktop tooling** — `host.pickDirectory` reports an actionable error when neither Zenity nor KDialog is installed; it does not fall back to a custom or typed-path browser.

packages/host/apiproxy/README.zh.md

@@ -0,0 +1,44 @@
+# @deepseek-ai/dsh-host-apiproxy
+
+[English](README.md) | 中文
+
+所有客户端形态共用的 API 网关：TS 契约（`src/api/`，不依赖 Node，可从浏览器导入）、fetch 载体对（`src/fetch/`：宿主侧的 `toFetchHandler`，以及客户端侧的 `AbstractApiClient` 与平台子类）和宿主侧实现（`src/api-proxy.ts`：`createApiProxy` 加上默认导出的 `ApiProxyService` 网关插件，其配置为 `{provider, model, workspaceRoot?}`，提供 `ctx.apiProxy`）。该包（package）在设计上与传输方式无关，不注册任何路由；载体（目前为 HTTP，未来可以是 IPC）自行包装 `ctx.apiProxy`。已发布的核心组合位于 [`apps/cli/cordis.yml`](../../../apps/cli/cordis.yml)。
+
+## 契约层（`/api`）
+
+协议消息组成一个四象限可辨识联合：发起方 × 请求／响应，与物理通道解耦。四种消息分别是 `ClientRequest`（POST `/api/<method>` 的请求体）、`ServerResponse`（该 POST 的响应体）、`ServerRequest`（SSE 帧）和 `ClientResponse`（POST `/api/respond` 的请求体）。响应始终回显对应请求的 `rpcId`，绝不签发新值。方法的参数与返回值结构只存在于领域接口签名（`SessionsApi`、`HostApi`、`EventsApi`）中；`RpcMethodMap` 注册方法，其他所有位置均通过 `RequestPayload<K>`／`ResponseValue<K>` 派生。Zod schema 以 `satisfies z.ZodType<Wire<T>>` 锚定类型，并分两层解析：先解析信封，再解析业务载荷，随后按方法分发。业务错误由 `RpcResult` 的错误分支承载（`RpcErrorDetailsMap` 封闭错误码集合）；HTTP 状态只表达载体层结果。
+
+分层与协议决策记录在 [GUI 分层与 RPC 协议 RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)中；浏览器侧消费架构记录在 [Web 客户端架构 RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)中。
+
+`session.history` 的尾页（不带 `beforeSeq`）额外携带一个可选的 `projections` 块——`ctx.sessionProjections`（`@deepseek-ai/dsh-session-projection`）上每个已注册单元的水位线快照，`asOfSeq` = 这些值共同反映到的最后一个事件 seq（空日志为 `-1`）。网关还订阅注册表的变更流，为每个状态发生变化的单元铸造一个 `session/projection` mux 帧（`{sessionId, key, value, seq}`——实时推送状态，绝不入日志；客户端按 seq 高者胜维护一个按会话的通用值仓）。载体不持有任何领域知识（每个值在注册表内部已过其单元自己的 schema；协议 schema 对 `values`/`value` 保持宽松）；loadOlder 页永不携带该块，未装注册表的组合则两个面都不提供。
+
+会话标题与其他所有领域一样搭乘这对通用投影机制——历史尾页的 `projections` 块外加 `title` 键下的 `session/projection` 帧（专设的 `session/title` 帧已下线）。标题不会加入 `session.list`；冷会话在其中仍只有元数据，直到打开或恢复操作附加其日志。
+
+会话模型路由属于会话领域契约。`session.models` 返回选中的提供方／模型／推理（reasoning）目标，以及按提供方分组的建议性模型、精确路由推理元数据和逐提供方查询失败记录。`session.selectModel` 校验由适配器持有的可选推理强度，并替换将在下一提示词组装边界使用的完整目标。目录成员关系不构成校验：适配器可以解析未列出的模型，而不可用路由或不受支持的推理强度会返回 `model-unavailable`。
+
+Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.create` 会创建唯一名称或接纳现有目录，`workspace.delete` 只移除 Workspace 注册记录，`session.create` 接受可选的预分配 Session id，`host/workspace-changed`、`host/workspace-removed` 与 `host/session-added` 则以任意到达顺序携带已提交的增量。删除注册记录会保留目录和会话日志；相关 Session 仍留在 `session.list` 中，并进入 Ungrouped。`SessionSummary.blank` 与 `host/session-added` 帧携带派生的零事件位：客户端隐藏空白会话并按 workspace 复用它们，在首个 `host/session-status(running:true)` 时翻转 blank，并以 `session.list` 作为重连权威；冷会话摘要永远不是空白：惰性持久化让从未追加过事件的会话根本不出现在 `list()` 中。
+
+`host.pickDirectory` 会打开一个原生目录选择器并返回选中的路径；用户取消时返回 `null`。宿主实现不经 shell 调用平台工具：macOS 使用 `osascript`，Windows 使用以 STA 模式运行的 PowerShell `FolderBrowserDialog`，Linux 使用 Zenity，并以 KDialog 作为回退。选择器函数可在测试中注入。该方法需等待用户完成操作，是唯一不受默认 30 秒超时限制的一元调用；调用方发出的中止信号和连接中止仍会传播至原生进程。浏览器载体另行将这一特权方法限制为仅接受来自回环地址的同源请求。
+
+`host.openPath` 会用操作系统的默认应用打开一个文件系统路径（macOS 为 `open`，Windows 为 `Invoke-Item`，Linux 为 `xdg-open`）。打开器可在测试中注入。浏览器载体对其施加与 `host.pickDirectory` 相同的回环、同源限制。
+
+`command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和技能目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent（被服务的会话必有 Agent；`command.*` 经由与 `session.*` 相同的路径恢复冷会话，而 `skill.list` 从会话头解析项目根目录，不触碰 Agent 注册表）。`command.execute` 在宿主侧运行一条斜杠命令行，语义为纯准入：响应报告该行是否解析到处理器，并在解析到时回带铸造的生命周期 `commandId`（将本次确认与流节点关联）；结局经由持久落账并在 mux 流广播的 `command/run`/`command/done` 生命周期事件对承载；载体的请求信号可取消正在运行的处理器。`host/commands-changed` 是目录失效帧：客户端重新拉取 `command.list` 而不是做差分。
+
+## 载体层（`/client` + 根路径）
+
+`AbstractApiClient` 持有全部协议不变量：签发 rpcId、包装／解包信封、Zod 解析、SSE 帧解码、一元请求超时，以及按微任务批处理的信封观测（`subscribeEnvelopes`）；平台子类只提供 `doFetch` 传输环节。`InProcessApiClient` 以 `toFetchHandler(api)` 为基础，是同构接点：它运行完整的协议序列化与校验路径而不经过网络，供 `dsh -p` headless 模式使用。
+
+## 模型体验
+
+无。该包定义客户端与宿主间的协议契约和载体，其中没有任何内容会进入模型请求。
+
+#### KV 缓存影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与延期工作
+
+- **`respond` 路由已经发布，但待处理交互状态仍属宿主侧工作**：协议形状（POST `/api/respond`、`RpcReceipt`）已经定型；使延迟或重复回答具有明确语义的待处理表位于 `src/api-proxy.ts`，目前仍很精简（只支持问题，不支持审批）。
+- **预留 seam 不进入 `RpcMethodMap`**：`session.fork`、`prompt.mode: 'inject'`、`task.list`、`host.listModels` 和描述字段 `hostInstanceId` 都是已记录的预留项；未知方法会在信封解析时直接失败，而不会返回「尚未实现」错误码。
+- **没有协议版本字段**：客户端与宿主一同发布；只有出现独立发布的客户端后，`host.describe` 才会增加版本协商字段。
+- **Linux 原生选择器依赖桌面工具**：Zenity 和 KDialog 均未安装时，`host.pickDirectory` 会给出包含解决建议的错误提示；它不会回退到自定义目录浏览器，也不会要求用户手动输入路径。

packages/host/apiproxy/package.json

@@ -1,6 +1,6 @@
 {
   "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",
+  "description": "API gateway: the ApiProxy contract (api/), the fetch carrier pair (fetch/), and the host-side gateway plugin providing ctx.apiProxy",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -40,12 +40,19 @@
   ],
   "license": "BSD-3-Clause",
   "dependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence": "workspace:^",
+    "@deepseek-ai/dsh-session-projection": "workspace:^",
+    "@deepseek-ai/dsh-skill": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/dsh-user-approval": "workspace:^",
     "@deepseek-ai/dsh-user-interaction": "workspace:^",
+    "@deepseek-ai/dsh-workspace": "workspace:^",
+    "schemastery": "^3.18.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
@@ -53,6 +60,8 @@
     "@deepseek-ai/dsh-invariants": "^0.0.1"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-storage": "workspace:^",
+    "@deepseek-ai/dsh-storage-domain": "workspace:^",
     "cordis": "^4.0.0-rc.7",
     "@deepseek-ai/dsh-invariants": "workspace:^"
   }

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

@@ -0,0 +1,44 @@
+/**
+ * commands domain zod schemas (names derived from map keys: commandListRequestSchema /
+ * commandListValueSchema / commandExecuteRequestSchema / commandExecuteValueSchema).
+ */
+
+import { z } from 'zod'
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
+import type { RequestPayload, ResponseValue } from './rpc-map.ts'
+import type { Wire } from './rpc.schema.ts'
+import { sessionIdSchema } from './sessions.schema.ts'
+import type { CommandDescriptor } from './commands.ts'
+
+/** CommandDescriptor row of command.list. */
+export const commandDescriptorSchema = z.object({
+  name: z.string().min(1),
+  description: z.string(),
+  input: z.object({ hint: z.string() }).optional(),
+}) satisfies z.ZodType<Wire<CommandDescriptor>>
+
+/** command.list request payload. */
+export const commandListRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+}) satisfies z.ZodType<Wire<RequestPayload<'command.list'>>>
+
+/** command.list response value. */
+export const commandListValueSchema = z.object({
+  commands: z.array(commandDescriptorSchema),
+}) satisfies z.ZodType<Wire<ResponseValue<'command.list'>>>
+
+/** command.execute request payload. */
+export const commandExecuteRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+  line: z.string(),
+}) satisfies z.ZodType<Wire<RequestPayload<'command.execute'>>>
+
+/** CommandId: one brand cast after shape validation (the only cast point in this domain). */
+export const commandIdSchema = z.string().min(1) as unknown as z.ZodType<CommandId>
+
+/** command.execute response value: pure admission — outcomes ride the logged
+ * lifecycle events; commandId (present exactly when matched) correlates with them. */
+export const commandExecuteValueSchema = z.object({
+  matched: z.boolean(),
+  commandId: commandIdSchema.optional(),
+}) satisfies z.ZodType<Wire<ResponseValue<'command.execute'>>>

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

@@ -0,0 +1,48 @@
+/**
+ * commands domain contract: the web catalog/dispatch face of the host command
+ * registry (`ctx.commands`). Both methods address one session's agent via
+ * `sessionId` — every served session has an Agent (Session+Agent are born
+ * together), so there is no agent-less surface on this wire.
+ */
+
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { RpcRequest, RpcResponse } from './rpc.ts'
+
+/**
+ * Handler-free command view served to clients. Wire mirror of the host
+ * registry descriptor (which stays host-side with its cordis dependencies);
+ * no source field — the host descriptor has none.
+ */
+export interface CommandDescriptor {
+  /** Lowercase command name without the leading slash. */
+  readonly name: string
+  /** Human-readable summary used in discovery UI. */
+  readonly description: string
+  /** Optional free-form input hint advertised to capable clients. */
+  readonly input?: { readonly hint: string }
+}
+
+/** Command-domain unary methods (the map keys command.* of RpcMethodMap). */
+export interface CommandsApi {
+  /**
+   * Lists the addressed agent's effective command catalog (name-sorted,
+   * globals plus its scoped shadows).
+   */
+  list(request: RpcRequest<{ sessionId: SessionId }>): Promise<RpcResponse<{ commands: readonly CommandDescriptor[] }>>
+
+  /**
+   * Parses and executes one slash-command line against the addressed agent
+   * without sending it to the model — pure admission semantics. matched=false
+   * when syntax or name does not resolve (the client falls back to its
+   * default sink). The handler's outcome does NOT ride the response: the host
+   * executor durably logs the lifecycle (`command/run`/`command/done`), which
+   * broadcasts on the mux stream and renders as a persistent flow node.
+   * `commandId` is present exactly when matched — the minted lifecycle
+   * pairing id, letting the issuing client correlate this acknowledgment
+   * with that flow node. The signal rides beside the request, never on the
+   * wire: the fetch carrier's request signal cancels the running handler.
+   */
+  execute(request: RpcRequest<{ sessionId: SessionId; line: string }>, signal: AbortSignal):
+  Promise<RpcResponse<{ matched: boolean; commandId?: CommandId }>>
+}

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

@@ -10,33 +10,53 @@ 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'
+import { contentBlockSchema, sessionEventSchema, sessionIdSchema, toolEventViewSchema } from './sessions.schema.ts'
+import { workspaceIdSchema, workspaceViewSchema } from './workspace.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(),
+  detail: 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>>
 
+/** Unified message envelope carried by transient queue frames. */
+const messageSchema = z.object({
+  id: z.string().min(1),
+  role: z.union([z.literal('system'), z.literal('user'), z.literal('assistant')]),
+  content: z.array(contentBlockSchema),
+  source: z.looseObject({ kind: z.string() }),
+})
+
 /** 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) }),
+  // Non-empty by wire contract: the user-interaction service rejects empty
+  // batches at ask() (EMPTY_QUESTIONS), so an empty frame is host breakage
+  // and must fail loud here, not reach the composer.
+  z.object({ type: z.literal('question/requested'), sessionId: sessionIdSchema, questions: z.array(askUserQuestionItemSchema).min(1) }),
   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('session/queued'), sessionId: sessionIdSchema, message: messageSchema, steering: z.boolean() }),
+  // value stays wide: it already passed its unit's own schema on the host,
+  // and deep-validating here would import every domain's schema into the carrier.
+  z.object({ type: z.literal('session/projection'), sessionId: sessionIdSchema, key: z.string().min(1), value: z.unknown(), seq: z.number().int().nonnegative() }),
   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-added'), sessionId: sessionIdSchema, blank: z.boolean(), parentSessionId: sessionIdSchema.optional(), cwd: z.string().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('host/workspace-changed'), workspace: workspaceViewSchema }),
+  z.object({ type: z.literal('host/workspace-removed'), workspaceId: workspaceIdSchema }),
+  z.object({ type: z.literal('host/commands-changed') }),
   z.object({ type: z.literal('stream/error'), error: rpcErrorSchema }),
 ]) as unknown as z.ZodType<HostFrame>

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

@@ -8,10 +8,12 @@
 
 import type { AskUserQuestionItem } from '@deepseek-ai/dsh-user-interaction/types'
 import type { ApprovalOutcome, ApprovalRequestId } from '@deepseek-ai/dsh-user-approval/types'
+import type { Message } from '@deepseek-ai/dsh-llm/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'
+import type { WorkspaceView } from './workspace.ts'
 
 // Client-side consumers take the render-intent vocabulary from the contract;
 // dsh-tools remains its owner.
@@ -33,8 +35,9 @@ export type ToolEventView =
 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).
+   * attached session, then replays each session's still-pending approval/question requested
+   * frames (rpcId reused verbatim — the refresh-recovery baseline). Session titles ride the
+   * generic projection pair (history-tail projections block + session/projection frames).
    * since: resume seam, unimplemented in v1 (ignored if passed); reconnection = reopen the
    * stream + refetch history.
    */
@@ -58,12 +61,55 @@ export type MuxFrame =
   | { 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' }
+  /**
+   * A message entered the addressed agent's inbox. A queued message is not
+   * model-visible, so there is no session event to carry it; this transient
+   * frame is the only wire signal. On stream open the
+   * host replays the current queue snapshot for every attached session (same
+   * refresh-recovery baseline as pending questions); queue clearing on cancel
+   * has no dedicated frame — clients fold it from the status flip.
+   * `steering` is the host's acceptance-time queue classification and remains
+   * authoritative in reconnect snapshots. `message.source` carries the prompt's rpcId
+   * when the message came over this wire (the client's provisional-echo
+   * reconciliation key).
+   */
+  | { type: 'session/queued'; sessionId: SessionId; message: Message; steering: boolean }
+  /**
+   * One projection unit's finished value changed (session-projection RFC).
+   * Live push state, never logged — replay recomputes on the host (the
+   * tool-view posture). `value` is the unit's schema-validated view output;
+   * `seq` is the unit's watermark at emission. Clients keep one generic
+   * per-session value store under higher-seq-wins, seeded by the history
+   * tail page's projections block.
+   */
+  | { type: 'session/projection'; sessionId: SessionId; key: string; value: unknown; seq: number }
   | { 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. */
+/**
+ * Host stream frames. session-added carries the lineage anchor, the project
+ * cwd, and the blank bit (the list-summary fields a client cannot wait for a
+ * refresh to learn); the frame fires at session/created, so blank is
+ * constantly true — clients flip it on the session's first
+ * `host/session-status(running:true)` (a blank session never runs), and a
+ * reconnecting client takes `session.list`'s summary.blank as authoritative.
+ * agent-error is the only outlet for live failures with no turn position;
+ * workspace-changed pushes the full new snapshot after every durable
+ * workspace mutation (create/attach/order change — the client upserts, while
+ * `workspace.list` provides the reconnect baseline); workspace-removed is the
+ * committed registration-deletion increment and never implies directory or
+ * session-log deletion.
+ */
 export type HostFrame =
-  | { type: 'host/session-added'; sessionId: SessionId; parentSessionId?: SessionId }
+  | { type: 'host/session-added'; sessionId: SessionId; blank: boolean; parentSessionId?: SessionId; cwd?: string }
   | { type: 'host/session-removed'; sessionId: SessionId }
   | { type: 'host/session-status'; sessionId: SessionId; running: boolean }
   | { type: 'host/agent-error'; sessionId: SessionId; message: string }
+  | { type: 'host/workspace-changed'; workspace: WorkspaceView }
+  | { type: 'host/workspace-removed'; workspaceId: WorkspaceView['workspaceId'] }
+  /**
+   * The command registry changed (`commands/change` passthrough). Pure
+   * invalidation signal, no payload: clients refetch `command.list` in the
+   * background rather than diffing.
+   */
+  | { type: 'host/commands-changed' }
   | { type: 'stream/error'; error: RpcError }

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

@@ -32,16 +32,6 @@ export const goalViewSchema = z.object({
   activation: z.union([z.literal('armed'), z.literal('disarmed')]),
 }) as unknown as z.ZodType<Wire<GoalView>>
 
-/** goal.get request payload. */
-export const goalGetRequestSchema = z.object({
-  sessionId: z.string(),
-}) as unknown as z.ZodType<Wire<RequestPayload<'goal.get'>>>
-
-/** goal.get response value. */
-export const goalGetValueSchema = z.object({
-  goal: goalViewSchema.nullable(),
-}) as unknown as z.ZodType<Wire<ResponseValue<'goal.get'>>>
-
 /** goal.create request payload. */
 export const goalCreateRequestSchema = z.object({
   sessionId: z.string(),

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

@@ -58,11 +58,8 @@ export interface EditGoalRequest {
   readonly maxGoalRounds?: number
 }
 
-/** Goal-domain unary methods. */
+/** Goal-domain unary methods (mutations only: the read side is the 'goal' session projection). */
 export interface GoalsApi {
-  /** Read the current goal for one session. Returns null when no goal is current. */
-  get(request: RpcRequest<{ sessionId: SessionId }>): Promise<RpcResponse<{ goal: GoalView | null }>>
-
   /** Create and arm a goal. */
   create(request: RpcRequest<{ sessionId: SessionId; objective: string; maxGoalRounds?: number }>):
   Promise<RpcResponse<{ goal: GoalView }>>

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

@@ -17,3 +17,21 @@ export const hostDescribeValueSchema = z.object({
   model: z.string().optional(),
   attachedSessions: z.number().int().nonnegative(),
 }) satisfies z.ZodType<Wire<ResponseValue<'host.describe'>>>
+
+/** host.pickDirectory request payload (empty object literal). */
+export const hostPickDirectoryRequestSchema = z.object({}) satisfies z.ZodType<Wire<RequestPayload<'host.pickDirectory'>>>
+
+/** host.pickDirectory response value; null means the user cancelled. */
+export const hostPickDirectoryValueSchema = z.object({
+  path: z.string().nullable(),
+}) satisfies z.ZodType<Wire<ResponseValue<'host.pickDirectory'>>>
+
+/** host.openPath request payload. */
+export const hostOpenPathRequestSchema = z.object({
+  path: z.string().min(1),
+}) satisfies z.ZodType<Wire<RequestPayload<'host.openPath'>>>
+
+/** host.openPath response value. */
+export const hostOpenPathValueSchema = z.object({
+  opened: z.literal(true),
+}) satisfies z.ZodType<Wire<ResponseValue<'host.openPath'>>>

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

@@ -22,4 +22,20 @@ export interface HostApi {
     model?: string
     attachedSessions: number
   }>>
+
+  /** Open the operating system's single-directory picker; cancellation returns null. */
+  pickDirectory(
+    request: RpcRequest<{}>,
+    signal: AbortSignal,
+  ): Promise<RpcResponse<{ path: string | null }>>
+
+  /**
+   * Open a filesystem path with the operating system's default application
+   * (Finder / Explorer / xdg-open hand-off). The browser carrier restricts this
+   * privileged method to loopback, same-origin requests.
+   */
+  openPath(
+    request: RpcRequest<{ path: string }>,
+    signal: AbortSignal,
+  ): Promise<RpcResponse<{ opened: true }>>
 }

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

@@ -6,6 +6,9 @@
 
 import type { SessionsApi } from './sessions.ts'
 import type { HostApi } from './host.ts'
+import type { WorkspaceApi } from './workspace.ts'
+import type { CommandsApi } from './commands.ts'
+import type { SkillsApi } from './skills.ts'
 import type { EventsApi } from './events.ts'
 import type { GoalsApi } from './goals.ts'
 import type { ClientResponse, RpcReceipt } from './rpc.ts'
@@ -14,6 +17,9 @@ import type { ClientResponse, RpcReceipt } from './rpc.ts'
 export interface ApiProxy {
   sessions: SessionsApi
   host: HostApi
+  workspace: WorkspaceApi
+  commands: CommandsApi
+  skills: SkillsApi
   events: EventsApi
   goals: GoalsApi
   /** Response entry for server-requests (client-response, echoing their rpcId); not a domain method (four-quadrant model). */
@@ -21,8 +27,14 @@ export interface ApiProxy {
 }
 
 // ---- Domain interfaces and payload entities ----
-export type { HistoryEntry, SessionsApi, SessionSummary } from './sessions.ts'
+export type {
+  HistoryEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
+  ModelReasoningEffort, ModelTarget, SessionModels, SessionProjectionsBlock, SessionsApi, SessionSummary,
+} from './sessions.ts'
 export type { HostApi } from './host.ts'
+export type { WorkspaceApi, WorkspaceId, WorkspaceView } from './workspace.ts'
+export type { CommandsApi, CommandDescriptor } from './commands.ts'
+export type { SkillsApi, SkillEntry } from './skills.ts'
 export type { EventsApi, MuxFrame, HostFrame, ToolCallView, ToolEventView, ToolResultView } from './events.ts'
 export type { GoalsApi, GoalView, GoalRef, GoalPhase, GoalBlockReason, CreateGoalRequest, EditGoalRequest } from './goals.ts'
 export type { ApprovalResponsePayload } from './approvals.ts'
@@ -42,7 +54,7 @@ export type {
 } from './rpc.ts'
 
 // ---- Errors and ids ----
-export { RpcId } from './rpc.ts'
+export { RpcId, transportError } from './rpc.ts'
 export type { RpcError, RpcErrorCode, RpcErrorDetailsMap, RpcResult } from './rpc.ts'
 
 // ---- Method registry and derived generics ----

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

@@ -6,18 +6,36 @@
 
 import type { SessionsApi } from './sessions.ts'
 import type { HostApi } from './host.ts'
+import type { WorkspaceApi } from './workspace.ts'
+import type { CommandsApi } from './commands.ts'
+import type { SkillsApi } from './skills.ts'
 import type { GoalsApi } from './goals.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. */
+/**
+ * Method name → method signature. Signatures are the single source of truth; payload/value
+ * types are always derived from here. A method may declare a trailing AbortSignal after the
+ * request (command.execute): the carrier passes its request signal, never a wire field.
+ */
 export interface RpcMethodMap {
   'session.list': SessionsApi['list']
   'session.create': SessionsApi['create']
   'session.history': SessionsApi['history']
+  'session.models': SessionsApi['models']
+  'session.selectModel': SessionsApi['selectModel']
   'session.prompt': SessionsApi['prompt']
   'session.cancel': SessionsApi['cancel']
   'host.describe': HostApi['describe']
-  'goal.get': GoalsApi['get']
+  'host.pickDirectory': HostApi['pickDirectory']
+  'host.openPath': HostApi['openPath']
+  'workspace.list': WorkspaceApi['list']
+  'workspace.create': WorkspaceApi['create']
+  'workspace.rename': WorkspaceApi['rename']
+  'workspace.delete': WorkspaceApi['delete']
+  'workspace.insertSessionBefore': WorkspaceApi['insertSessionBefore']
+  'command.list': CommandsApi['list']
+  'command.execute': CommandsApi['execute']
+  'skill.list': SkillsApi['list']
   'goal.create': GoalsApi['create']
   'goal.edit': GoalsApi['edit']
   'goal.pause': GoalsApi['pause']

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

@@ -33,7 +33,15 @@ 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('cancelled'), message: z.string(), details: z.object({}) }),
   z.object({ code: z.literal('session-not-found'), message: z.string(), details: z.object({ sessionId: z.string() }) }),
+  z.object({ code: z.literal('model-unavailable'), message: z.string(), details: z.object({ provider: z.string(), model: z.string() }) }),
+  z.object({ code: z.literal('session-conflict'), message: z.string(), details: z.object({ sessionId: z.string(), requestedCwd: z.string(), existingCwd: z.string().optional() }) }),
+  z.object({ code: z.literal('workspace-attach-failed'), message: z.string(), details: z.object({ sessionId: z.string(), workspaceId: z.string() }) }),
+  z.object({ code: z.literal('workspace-not-found'), message: z.string(), details: z.object({ workspaceId: z.string() }) }),
+  z.object({ code: z.literal('workspace-invalid-path'), message: z.string(), details: z.object({ path: z.string() }) }),
+  z.object({ code: z.literal('workspace-name-conflict'), message: z.string(), details: z.object({ name: z.string() }) }),
+  z.object({ code: z.literal('workspace-move-invalid'), message: z.string(), details: z.object({ workspaceId: z.string(), sessionId: z.string(), beforeSessionId: z.string().optional() }) }),
   z.object({ code: z.literal('agent-busy'), message: z.string(), details: z.object({ reason: z.string() }) }),
   z.object({ code: z.literal('command-error'), message: z.string(), details: z.object({}) }),
   z.object({ code: z.literal('unknown-command'), message: z.string(), details: z.object({}) }),

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

@@ -30,7 +30,15 @@ export function RpcId(id: string): 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[] }
+  'cancelled': {}
   'session-not-found': { sessionId: SessionId }
+  'model-unavailable': { provider: string; model: string }
+  'session-conflict': { sessionId: SessionId; requestedCwd: string; existingCwd?: string }
+  'workspace-attach-failed': { sessionId: SessionId; workspaceId: string }
+  'workspace-not-found': { workspaceId: string }
+  'workspace-invalid-path': { path: string }
+  'workspace-name-conflict': { name: string }
+  'workspace-move-invalid': { workspaceId: string; sessionId: SessionId; beforeSessionId?: SessionId }
   'agent-busy': { reason: string }
   /** A known slash command reported a usage/state error; the message is the command's own text. */
   'command-error': {}
@@ -53,6 +61,20 @@ export type RpcError = {
 /** 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 }
 
+/**
+ * Fold a transport exception into the RpcResult error branch (unified error
+ * surface; 'internal' as the catch-all code). Lives with RpcResult so every
+ * carrier consumer folds the same way.
+ * @param error - the thrown value from the carrier.
+ * @returns the error branch of an RpcResult.
+ */
+export function transportError<T>(error: unknown): RpcResult<T> {
+  return {
+    ok: false,
+    error: { code: 'internal', message: error instanceof Error ? error.message : String(error), details: {} },
+  }
+}
+
 /**
  * Signature-layer narrow form, request side (domain-interface view, shared by
  * both directions): rpcId is explicit in the signature, never mixed into the

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

@@ -9,12 +9,24 @@ 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 {
+  HistoryEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
+  ModelReasoningEffort, ModelTarget, SessionProjectionsBlock, SessionSummary,
+} from './sessions.ts'
 import type { ToolEventView } from './events.ts'
+import type { WorkspaceId } from './workspace.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>
 
+/**
+ * WorkspaceId: the workspace domain's one brand cast. Hosted here rather
+ * than in workspace.schema because session.create references it while
+ * workspace.schema references sessionIdSchema — schema modules must stay a
+ * DAG (both casts used at module top level; a cycle is a load-time TDZ).
+ */
+export const workspaceIdSchema = z.string().min(1) as unknown as z.ZodType<WorkspaceId>
+
 /** SessionEvent passthrough: strict envelope, wide data (the client fold handles unknown types via its documented default). */
 export const sessionEventSchema = z.object({
   type: z.string(),
@@ -30,6 +42,7 @@ export const sessionSummarySchema = z.object({
   sessionId: sessionIdSchema,
   updatedAt: z.number(),
   running: z.boolean(),
+  blank: z.boolean(),
   parentSessionId: sessionIdSchema.optional(),
   cwd: z.string().optional(),
 }) satisfies z.ZodType<Wire<SessionSummary>>
@@ -44,10 +57,15 @@ export const sessionListValueSchema = z.object({
   items: z.array(sessionSummarySchema),
 }) satisfies z.ZodType<Wire<ResponseValue<'session.list'>>>
 
-/** session.create request payload. */
+/** session.create request payload (at most one of workspaceId / cwd). */
 export const sessionCreateRequestSchema = z.object({
+  workspaceId: workspaceIdSchema.optional(),
   cwd: z.string().optional(),
-}) satisfies z.ZodType<Wire<RequestPayload<'session.create'>>>
+  sessionId: sessionIdSchema.optional(),
+}).refine(
+  payload => payload.workspaceId === undefined || payload.cwd === undefined,
+  { message: 'session.create accepts workspaceId or cwd, not both' },
+) satisfies z.ZodType<Wire<RequestPayload<'session.create'>>>
 
 /** session.create response value. */
 export const sessionCreateValueSchema = z.object({
@@ -61,6 +79,49 @@ export const sessionHistoryRequestSchema = z.object({
   maxMessages: z.number().int().positive().optional(),
 }) satisfies z.ZodType<Wire<RequestPayload<'session.history'>>>
 
+/** Complete provider/model target. */
+export const modelTargetSchema = z.object({
+  provider: z.string().min(1),
+  model: z.string().min(1),
+  reasoningEffort: z.string().min(1).optional(),
+}) satisfies z.ZodType<Wire<ModelTarget>>
+
+/** One adapter-owned reasoning effort. */
+export const modelReasoningEffortSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  description: z.string().optional(),
+}) satisfies z.ZodType<Wire<ModelReasoningEffort>>
+
+/** Exact-model reasoning metadata. */
+export const modelReasoningSchema = z.object({
+  efforts: z.array(modelReasoningEffortSchema).min(1),
+  defaultEffort: z.string().min(1).optional(),
+}) satisfies z.ZodType<Wire<ModelReasoning>>
+
+/** One advisory model entry inside a provider group. */
+export const modelCatalogModelSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  description: z.string().optional(),
+  unlisted: z.literal(true).optional(),
+  reasoning: modelReasoningSchema.optional(),
+}) satisfies z.ZodType<Wire<ModelCatalogModel>>
+
+/** One successfully loaded provider group. */
+export const modelProviderGroupSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  models: z.array(modelCatalogModelSchema),
+}) satisfies z.ZodType<Wire<ModelProviderGroup>>
+
+/** One provider-local catalog failure. */
+export const modelCatalogFailureSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  message: z.string(),
+}) satisfies z.ZodType<Wire<ModelCatalogFailure>>
+
 /**
  * ToolEventView passthrough: lock only the `for` discriminant and the presence
  * of a card-tagged `view` object. The view interior is a host-computed product
@@ -78,12 +139,49 @@ export const historyEntrySchema = z.object({
   view: toolEventViewSchema.optional(),
 }) satisfies z.ZodType<Wire<HistoryEntry>>
 
-/** session.history response value. */
+/**
+ * Projection baseline passthrough: `values` stays a wide record — each value
+ * was already parsed by its provider's own schema on the host side, and
+ * deep-validating here would import every domain's schema into the carrier.
+ */
+export const sessionProjectionsBlockSchema = z.object({
+  // -1 = empty log (the lastSeq convention of session/subscribed).
+  asOfSeq: z.number().int().min(-1),
+  values: z.record(z.string(), z.unknown()),
+}) as unknown as z.ZodType<SessionProjectionsBlock>
+
+/** session.history response value (projections rides the tail page only). */
 export const sessionHistoryValueSchema = z.object({
   events: z.array(historyEntrySchema),
   hasMore: z.boolean(),
+  projections: sessionProjectionsBlockSchema.optional(),
 }) satisfies z.ZodType<Wire<ResponseValue<'session.history'>>>
 
+/** session.models request payload. */
+export const sessionModelsRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+}) satisfies z.ZodType<Wire<RequestPayload<'session.models'>>>
+
+/** session.models response value. */
+export const sessionModelsValueSchema = z.object({
+  current: modelTargetSchema,
+  groups: z.array(modelProviderGroupSchema),
+  failures: z.array(modelCatalogFailureSchema),
+}) satisfies z.ZodType<Wire<ResponseValue<'session.models'>>>
+
+/** session.selectModel request payload. */
+export const sessionSelectModelRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+  provider: z.string().min(1),
+  model: z.string().min(1),
+  reasoningEffort: z.string().min(1).optional(),
+}) satisfies z.ZodType<Wire<RequestPayload<'session.selectModel'>>>
+
+/** session.selectModel response value. */
+export const sessionSelectModelValueSchema = z.object({
+  selected: modelTargetSchema,
+}) satisfies z.ZodType<Wire<ResponseValue<'session.selectModel'>>>
+
 /** ContentBlock passthrough: core is merge-extensible — the type discriminant envelope is strict, the rest stays wide. */
 export const contentBlockSchema = z.looseObject({ type: z.string() })
 

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

@@ -6,8 +6,12 @@
 
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
+// The pure-type outlet: api/ is browser-importable, and the package root's
+// cordis Context merge (via dsh-agent) must not enter client aggregates.
+import type { SessionProjectionMap } from '@deepseek-ai/dsh-session-projection/types'
 import type { RpcId, RpcRequest, RpcResponse } from './rpc.ts'
 import type { ToolEventView } from './events.ts'
+import type { WorkspaceId } from './workspace.ts'
 
 declare module '@deepseek-ai/dsh-llm' {
   interface MessageSourceMap {
@@ -31,6 +35,95 @@ export interface HistoryEntry {
   view?: ToolEventView
 }
 
+/**
+ * The projection baseline riding the history tail page: one synchronous cut
+ * over every registered projection unit, read from the registry's watermark
+ * cache. `asOfSeq` is the seq of the last committed event every value
+ * reflects — the window tail event seq (`-1` for an empty log, mirroring
+ * `session/subscribed.lastSeq`), directly comparable with
+ * `session/projection` frame seqs under the client's higher-seq-wins rule. A
+ * key absent from `values` means the capability is absent (its domain plugin
+ * is unmounted).
+ */
+export interface SessionProjectionsBlock {
+  /** Seq of the last event the values reflect; -1 for an empty log. */
+  asOfSeq: number
+  /** Whole current value per registered projection key. */
+  values: Partial<SessionProjectionMap>
+}
+
+/** Complete model target selected for one session. */
+export interface ModelTarget {
+  /** Registered provider route. */
+  provider: string
+  /** Provider-owned model id. */
+  model: string
+  /** Adapter-owned reasoning effort; absence preserves adapter/provider default behavior. */
+  reasoningEffort?: string
+}
+
+/** One adapter-owned reasoning effort displayed for an exact model route. */
+export interface ModelReasoningEffort {
+  /** Opaque value submitted back to the owning adapter. */
+  id: string
+  /** Adapter-supplied display name. */
+  name: string
+  /** Optional adapter-supplied description. */
+  description?: string
+}
+
+/** Selectable reasoning metadata for one exact model route. */
+export interface ModelReasoning {
+  /** Efforts in adapter-preferred display order. */
+  efforts: ModelReasoningEffort[]
+  /** Adapter-configured default; absence preserves the provider default. */
+  defaultEffort?: string
+}
+
+/** One model displayed inside its provider group. */
+export interface ModelCatalogModel {
+  /** Provider-owned model id. */
+  id: string
+  /** Provider-supplied display name. */
+  name: string
+  /** Optional provider-supplied description. */
+  description?: string
+  /** The current model was inserted because the advisory catalog omitted it. */
+  unlisted?: true
+  /** Exact-route reasoning metadata when the adapter exposes it. */
+  reasoning?: ModelReasoning
+}
+
+/** One provider and the models it advertised successfully. */
+export interface ModelProviderGroup {
+  /** Provider route id used for requests. */
+  id: string
+  /** Provider display name. */
+  name: string
+  /** Models in provider-preferred order. */
+  models: ModelCatalogModel[]
+}
+
+/** A provider whose asynchronous catalog lookup failed. */
+export interface ModelCatalogFailure {
+  /** Provider route id. */
+  id: string
+  /** Provider display name. */
+  name: string
+  /** Lookup failure diagnostic. */
+  message: string
+}
+
+/** Detached model-directory snapshot for one session. */
+export interface SessionModels {
+  /** Target selected for the session's next assembled step. */
+  current: ModelTarget
+  /** Successfully loaded provider groups. */
+  groups: ModelProviderGroup[]
+  /** Provider-local failures; successful groups remain usable. */
+  failures: ModelCatalogFailure[]
+}
+
 /** Session list entry (v1 builds no index: list does readdir+stat). */
 export interface SessionSummary {
   sessionId: SessionId
@@ -38,6 +131,14 @@ export interface SessionSummary {
   updatedAt: number
   /** Status of the attached agent; always false for cold (unattached) sessions. */
   running: boolean
+  /**
+   * Derived emptiness bit: true while the session log holds zero events (no
+   * user message yet). Clients hide blank sessions from lists and reuse them
+   * for New Session on the same workspace. Always false for cold sessions —
+   * lazy persistence keeps a never-appended session out of the store, so a
+   * listed cold session necessarily has events.
+   */
+  blank: boolean
   /** fork/spawn lineage (session.header.parentSession passthrough); absent for root sessions. */
   parentSessionId?: SessionId
   /** Session working directory (header.cwd passthrough); absent when unrecorded. */
@@ -49,8 +150,16 @@ 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 }>>
+  /**
+   * Creates a real session and its idle agent. At most one of `workspaceId` /
+   * `cwd` is accepted; an omitted project uses the Host cwd. A caller may
+   * preallocate `sessionId`: retries with the same id and cwd return the same
+   * session, while a different cwd fails with `session-conflict`. Workspace
+   * creation attaches the session after publication; an attach failure
+   * returns `workspace-attach-failed` with the published session id.
+   */
+  create(request: RpcRequest<{ workspaceId?: WorkspaceId; cwd?: string; sessionId?: SessionId }>):
+  Promise<RpcResponse<{ sessionId: SessionId }>>
 
   /**
    * Reads a window of history events; page boundaries align to message boundaries: one page =
@@ -60,9 +169,30 @@ export interface SessionsApi {
    * 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.
+   * The tail page — and only the tail page — additionally carries `projections`
+   * when the deployment mounts the session-projection registry: every moment
+   * the client needs a fresh baseline already pulls the tail page, and
+   * loadOlder (the only beforeSeq path) is the only path that never needs one.
+   * A deployment without the registry serves histories without the block.
    */
   history(request: RpcRequest<{ sessionId: SessionId; beforeSeq?: number; maxMessages?: number }>):
-  Promise<RpcResponse<{ events: HistoryEntry[]; hasMore: boolean }>>
+  Promise<RpcResponse<{ events: HistoryEntry[]; hasMore: boolean; projections?: SessionProjectionsBlock }>>
+
+  /** Reads a fresh advisory model directory for this session. Provider lookups run independently. */
+  models(request: RpcRequest<{ sessionId: SessionId }>): Promise<RpcResponse<SessionModels>>
+
+  /**
+   * Selects the complete target for this session. Exact model metadata
+   * validates an optional reasoning effort, while catalog membership remains
+   * advisory.
+   */
+  selectModel(request: RpcRequest<{
+    sessionId: SessionId
+    provider: string
+    model: string
+    reasoningEffort?: string
+  }>):
+  Promise<RpcResponse<{ selected: ModelTarget }>>
 
   /**
    * Sends a message. content is core's ContentBlock[] verbatim; mode maps 1:1 — queue→send, steer→steer.

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

@@ -0,0 +1,27 @@
+/**
+ * skills domain zod schemas (names derived from map keys: skillListRequestSchema /
+ * skillListValueSchema).
+ */
+
+import { z } from 'zod'
+import type { RequestPayload, ResponseValue } from './rpc-map.ts'
+import type { Wire } from './rpc.schema.ts'
+import { sessionIdSchema } from './sessions.schema.ts'
+import type { SkillEntry } from './skills.ts'
+
+/** SkillEntry row of skill.list. */
+export const skillEntrySchema = z.object({
+  name: z.string().min(1),
+  description: z.string(),
+  whenToUse: z.string().optional(),
+}) satisfies z.ZodType<Wire<SkillEntry>>
+
+/** skill.list request payload. */
+export const skillListRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+}) satisfies z.ZodType<Wire<RequestPayload<'skill.list'>>>
+
+/** skill.list response value. */
+export const skillListValueSchema = z.object({
+  skills: z.array(skillEntrySchema),
+}) satisfies z.ZodType<Wire<ResponseValue<'skill.list'>>>

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

@@ -0,0 +1,25 @@
+/**
+ * skills domain contract: read-only skill catalog lookup addressed by session.
+ * The session's header cwd resolves to the canonical project root host-side —
+ * the client never submits a raw path, and skill lookup never creates or
+ * resumes an Agent.
+ */
+
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { RpcRequest, RpcResponse } from './rpc.ts'
+
+/** Skill catalog row (wire projection of the host SkillSummary; provider/source vocabulary stays host-side). */
+export interface SkillEntry {
+  /** Kebab-case identifier referenced as `<skill>name</skill>` in prompts. */
+  readonly name: string
+  /** Short routing description. */
+  readonly description: string
+  /** Optional extra routing guidance. */
+  readonly whenToUse?: string
+}
+
+/** Skill-domain unary methods (the map key skill.* of RpcMethodMap). */
+export interface SkillsApi {
+  /** Lists model-invocable skills for the addressed session's project root. */
+  list(request: RpcRequest<{ sessionId: SessionId }>): Promise<RpcResponse<{ skills: readonly SkillEntry[] }>>
+}

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

@@ -0,0 +1,82 @@
+/**
+ * workspace domain zod schemas (names derived from map keys). The
+ * WorkspaceId brand cast lives in sessions.schema (see the note there) and
+ * is re-exported here as the domain-local name.
+ */
+
+import { z } from 'zod'
+import type { RequestPayload, ResponseValue } from './rpc-map.ts'
+import type { Wire } from './rpc.schema.ts'
+import type { WorkspaceView } from './workspace.ts'
+import { sessionIdSchema, workspaceIdSchema } from './sessions.schema.ts'
+
+export { workspaceIdSchema } from './sessions.schema.ts'
+
+/** WorkspaceView row of every workspace.* response. */
+export const workspaceViewSchema = z.object({
+  workspaceId: workspaceIdSchema,
+  path: z.string(),
+  title: z.string(),
+  sessionIds: z.array(sessionIdSchema),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+}) satisfies z.ZodType<Wire<WorkspaceView>>
+
+/** workspace.list request payload (empty object literal). */
+export const workspaceListRequestSchema = z.object({}) satisfies z.ZodType<Wire<RequestPayload<'workspace.list'>>>
+
+/** workspace.list response value. */
+export const workspaceListValueSchema = z.object({
+  items: z.array(workspaceViewSchema),
+}) satisfies z.ZodType<Wire<ResponseValue<'workspace.list'>>>
+
+/** workspace.create request payload: exactly one of path/name (the contract's create spellings). */
+export const workspaceCreateRequestSchema = z.object({
+  path: z.string().optional(),
+  name: z.string().optional(),
+}).refine(
+  payload => (payload.path === undefined) !== (payload.name === undefined),
+  { message: 'workspace.create requires exactly one of path / name' },
+) satisfies z.ZodType<Wire<RequestPayload<'workspace.create'>>>
+
+/** workspace.create response value. */
+export const workspaceCreateValueSchema = z.object({
+  workspace: workspaceViewSchema,
+  created: z.boolean(),
+}) satisfies z.ZodType<Wire<ResponseValue<'workspace.create'>>>
+
+/** workspace.rename request payload: the new title must be non-blank. */
+export const workspaceRenameRequestSchema = z.object({
+  workspaceId: workspaceIdSchema,
+  title: z.string(),
+}).refine(
+  payload => payload.title.trim() !== '',
+  { message: 'workspace.rename requires a non-blank title' },
+) satisfies z.ZodType<Wire<RequestPayload<'workspace.rename'>>>
+
+/** workspace.rename response value. */
+export const workspaceRenameValueSchema = z.object({
+  workspace: workspaceViewSchema,
+}) satisfies z.ZodType<Wire<ResponseValue<'workspace.rename'>>>
+
+/** workspace.delete request payload. */
+export const workspaceDeleteRequestSchema = z.object({
+  workspaceId: workspaceIdSchema,
+}) satisfies z.ZodType<Wire<RequestPayload<'workspace.delete'>>>
+
+/** workspace.delete response value. */
+export const workspaceDeleteValueSchema = z.object({
+  deleted: z.literal(true),
+}) satisfies z.ZodType<Wire<ResponseValue<'workspace.delete'>>>
+
+/** workspace.insertSessionBefore request payload (anchor omitted = append to end). */
+export const workspaceInsertSessionBeforeRequestSchema = z.object({
+  workspaceId: workspaceIdSchema,
+  sessionId: sessionIdSchema,
+  beforeSessionId: sessionIdSchema.optional(),
+}) satisfies z.ZodType<Wire<RequestPayload<'workspace.insertSessionBefore'>>>
+
+/** workspace.insertSessionBefore response value. */
+export const workspaceInsertSessionBeforeValueSchema = z.object({
+  workspace: workspaceViewSchema,
+}) satisfies z.ZodType<Wire<ResponseValue<'workspace.insertSessionBefore'>>>

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

@@ -0,0 +1,89 @@
+/**
+ * workspace domain contract. Wire projection of the host-side workspace
+ * entity (@deepseek-ai/dsh-workspace): a stable id over a directory path,
+ * a display title, and the ordered session account. Method signatures are the
+ * source of truth, same as the sessions domain.
+ */
+
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { Branded } from '@deepseek-ai/dsh-brand'
+import type { RpcRequest, RpcResponse } from './rpc.ts'
+
+/**
+ * Wire-side workspace id brand. Deliberately re-declared here rather than
+ * imported from dsh-workspace: api/ must stay browser-importable with zero
+ * host-package dependencies, and the brand string matches, so both sides
+ * agree structurally.
+ */
+export type WorkspaceId = Branded<'WorkspaceId'>
+
+/** One workspace row: the record projection every workspace.* value carries. */
+export interface WorkspaceView {
+  workspaceId: WorkspaceId
+  /** Canonical directory path (host-side realpath canon). */
+  path: string
+  /** Unique display title (defaults to the path basename at create). */
+  title: string
+  /**
+   * Sessions accounted under this workspace, in manually owned order
+   * (attach prepends, insertSessionBefore reorders; activity never does).
+   */
+  sessionIds: SessionId[]
+  /** ISO-8601 creation instant. */
+  createdAt: string
+  /** ISO-8601 last-mutation instant. */
+  updatedAt: string
+}
+
+/** Workspace-domain unary methods (the map keys workspace.* of RpcMethodMap). */
+export interface WorkspaceApi {
+  /** Lists all workspaces in the registry's durable display order. */
+  list(request: RpcRequest<{}>): Promise<RpcResponse<{ items: WorkspaceView[] }>>
+
+  /**
+   * Creates (or idempotently resolves) a workspace. Exactly one of `path` /
+   * `name` (schema-enforced): `path` registers an EXISTING directory (no
+   * mkdir — a missing or non-directory path fails with `workspace-invalid-path`);
+   * `name` is a single path segment the host mkdirs under its default project
+   * root before registering. Either spelling resolving to a directory already
+   * owned by a workspace returns that workspace (`created: false`) for the
+   * existing-folder spelling. Create-by-name rejects an existing title with
+   * `workspace-name-conflict`; a new path whose basename duplicates another
+   * Workspace title is rejected by the registry with the same code.
+   * A new name-created workspace uses `name` as both directory name and title;
+   * a path-created workspace uses the registry's basename title default.
+   */
+  create(request: RpcRequest<{ path?: string; name?: string }>):
+  Promise<RpcResponse<{ workspace: WorkspaceView; created: boolean }>>
+
+  /**
+   * Renames a workspace. `title` is trimmed and must be non-empty
+   * (schema-enforced). An unknown id fails with `workspace-not-found`; a
+   * title equal to another workspace's fails with `workspace-name-conflict`.
+   * Renaming to the current title is a no-op success (no durable write).
+   */
+  rename(request: RpcRequest<{ workspaceId: WorkspaceId; title: string }>):
+  Promise<RpcResponse<{ workspace: WorkspaceView }>>
+
+  /**
+   * Removes one Workspace registration. The directory, every user file, and
+   * every session log remain untouched; those Sessions consequently become
+   * ungrouped. An unknown id fails with `workspace-not-found`.
+   */
+  delete(request: RpcRequest<{ workspaceId: WorkspaceId }>):
+  Promise<RpcResponse<{ deleted: true }>>
+
+  /**
+   * Moves an accounted session within its workspace's manual order,
+   * DOM-insertBefore-like: with `beforeSessionId` the session is inserted
+   * before that anchor; omitted appends to the end. An unknown workspace
+   * fails with `workspace-not-found`; a session or anchor not accounted by
+   * the workspace fails with `workspace-move-invalid`. A move to the current
+   * position is a no-op success.
+   */
+  insertSessionBefore(request: RpcRequest<{
+    workspaceId: WorkspaceId
+    sessionId: SessionId
+    beforeSessionId?: SessionId
+  }>): Promise<RpcResponse<{ workspace: WorkspaceView }>>
+}

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

@@ -13,16 +13,28 @@ 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 {
+  hostDescribeValueSchema, hostOpenPathValueSchema, hostPickDirectoryValueSchema,
+} from '../api/host.schema.ts'
 import {
   sessionCancelValueSchema,
   sessionCreateValueSchema,
   sessionHistoryValueSchema,
   sessionListValueSchema,
+  sessionModelsValueSchema,
   sessionPromptValueSchema,
+  sessionSelectModelValueSchema,
 } from '../api/sessions.schema.ts'
 import {
-  goalGetValueSchema,
+  workspaceCreateValueSchema,
+  workspaceDeleteValueSchema,
+  workspaceInsertSessionBeforeValueSchema,
+  workspaceListValueSchema,
+  workspaceRenameValueSchema,
+} from '../api/workspace.schema.ts'
+import { commandExecuteValueSchema, commandListValueSchema } from '../api/commands.schema.ts'
+import { skillListValueSchema } from '../api/skills.schema.ts'
+import {
   goalCreateValueSchema,
   goalEditValueSchema,
   goalPauseValueSchema,
@@ -51,11 +63,29 @@ export interface IApiClient {
     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'>>>
+    models(payload: RequestPayload<'session.models'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.models'>>>
+    selectModel(payload: RequestPayload<'session.selectModel'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.selectModel'>>>
     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'>>>
+    pickDirectory(payload: RequestPayload<'host.pickDirectory'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.pickDirectory'>>>
+    openPath(payload: RequestPayload<'host.openPath'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'host.openPath'>>>
+  }
+  workspace: {
+    list(payload: RequestPayload<'workspace.list'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'workspace.list'>>>
+    create(payload: RequestPayload<'workspace.create'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'workspace.create'>>>
+    rename(payload: RequestPayload<'workspace.rename'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'workspace.rename'>>>
+    delete(payload: RequestPayload<'workspace.delete'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'workspace.delete'>>>
+    insertSessionBefore(payload: RequestPayload<'workspace.insertSessionBefore'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'workspace.insertSessionBefore'>>>
+  }
+  commands: {
+    list(payload: RequestPayload<'command.list'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'command.list'>>>
+    execute(payload: RequestPayload<'command.execute'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'command.execute'>>>
+  }
+  skills: {
+    list(payload: RequestPayload<'skill.list'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'skill.list'>>>
   }
   events: {
     mux(payload: Parameters<ApiProxy['events']['mux']>[0]['payload'], signal: AbortSignal, onOpen?: () => void): AsyncIterable<RpcRequest<MuxFrame>>
@@ -82,10 +112,21 @@ const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType<Wire<ResponseV
   'session.list': sessionListValueSchema,
   'session.create': sessionCreateValueSchema,
   'session.history': sessionHistoryValueSchema,
+  'session.models': sessionModelsValueSchema,
+  'session.selectModel': sessionSelectModelValueSchema,
   'session.prompt': sessionPromptValueSchema,
   'session.cancel': sessionCancelValueSchema,
   'host.describe': hostDescribeValueSchema,
-  'goal.get': goalGetValueSchema,
+  'host.pickDirectory': hostPickDirectoryValueSchema,
+  'host.openPath': hostOpenPathValueSchema,
+  'workspace.list': workspaceListValueSchema,
+  'workspace.create': workspaceCreateValueSchema,
+  'workspace.rename': workspaceRenameValueSchema,
+  'workspace.delete': workspaceDeleteValueSchema,
+  'workspace.insertSessionBefore': workspaceInsertSessionBeforeValueSchema,
+  'command.list': commandListValueSchema,
+  'command.execute': commandExecuteValueSchema,
+  'skill.list': skillListValueSchema,
   'goal.create': goalCreateValueSchema,
   'goal.edit': goalEditValueSchema,
   'goal.pause': goalPauseValueSchema,
@@ -171,13 +212,22 @@ export abstract class AbstractApiClient implements IApiClient {
    * 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)
+  private async postJson(
+    path: string,
+    body: ClientRequest | ClientResponse,
+    signal: AbortSignal | undefined,
+    useDefaultTimeout = true,
+  ): Promise<Response> {
+    const requestSignal = useDefaultTimeout
+      ? signal === undefined
+        ? AbortSignal.timeout(this.timeoutMs)
+        : AbortSignal.any([AbortSignal.timeout(this.timeoutMs), signal])
+      : signal
     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]),
+      ...requestSignal === undefined ? {} : { signal: requestSignal },
     })
     if (!response.ok) throw new Error(`transport failure for ${path}: HTTP ${response.status}`)
     return response
@@ -192,10 +242,11 @@ export abstract class AbstractApiClient implements IApiClient {
     method: K,
     payload: RequestPayload<K>,
     signal?: AbortSignal,
+    useDefaultTimeout = true,
   ): 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 response = await this.postJson(`/api/${method}`, message, signal, useDefaultTimeout)
     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}`)
@@ -270,12 +321,35 @@ export abstract class AbstractApiClient implements IApiClient {
     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),
+    models: (payload, signal) => this.callUnary('session.models', payload, signal),
+    selectModel: (payload, signal) => this.callUnary('session.selectModel', 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),
+    // A native system dialog is user-paced and may legitimately stay open
+    // longer than the normal unary deadline. Caller/connection aborts remain.
+    pickDirectory: (payload, signal) => this.callUnary('host.pickDirectory', payload, signal, false),
+    openPath: (payload, signal) => this.callUnary('host.openPath', payload, signal),
+  }
+
+  readonly workspace: IApiClient['workspace'] = {
+    list: (payload, signal) => this.callUnary('workspace.list', payload, signal),
+    create: (payload, signal) => this.callUnary('workspace.create', payload, signal),
+    rename: (payload, signal) => this.callUnary('workspace.rename', payload, signal),
+    delete: (payload, signal) => this.callUnary('workspace.delete', payload, signal),
+    insertSessionBefore: (payload, signal) => this.callUnary('workspace.insertSessionBefore', payload, signal),
+  }
+
+  readonly commands: IApiClient['commands'] = {
+    list: (payload, signal) => this.callUnary('command.list', payload, signal),
+    execute: (payload, signal) => this.callUnary('command.execute', payload, signal),
+  }
+
+  readonly skills: IApiClient['skills'] = {
+    list: (payload, signal) => this.callUnary('skill.list', payload, signal),
   }
 
   readonly goals: IApiClient['goals'] = {

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

@@ -19,11 +19,23 @@ import {
   sessionCreateRequestSchema,
   sessionHistoryRequestSchema,
   sessionListRequestSchema,
+  sessionModelsRequestSchema,
   sessionPromptRequestSchema,
+  sessionSelectModelRequestSchema,
 } from '../api/sessions.schema.ts'
-import { hostDescribeRequestSchema } from '../api/host.schema.ts'
 import {
-  goalGetRequestSchema,
+  hostDescribeRequestSchema, hostOpenPathRequestSchema, hostPickDirectoryRequestSchema,
+} from '../api/host.schema.ts'
+import {
+  workspaceCreateRequestSchema,
+  workspaceDeleteRequestSchema,
+  workspaceInsertSessionBeforeRequestSchema,
+  workspaceListRequestSchema,
+  workspaceRenameRequestSchema,
+} from '../api/workspace.schema.ts'
+import { commandExecuteRequestSchema, commandListRequestSchema } from '../api/commands.schema.ts'
+import { skillListRequestSchema } from '../api/skills.schema.ts'
+import {
   goalCreateRequestSchema,
   goalEditRequestSchema,
   goalPauseRequestSchema,
@@ -38,11 +50,13 @@ import {
  * 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.
+ * Every invoke receives the carrier Request's signal; methods whose contract
+ * declares a signal parameter (command.execute) forward it, the rest ignore it.
  */
 type UnaryRoutes = {
   [K in keyof RpcMethodMap]: {
     schema: z.ZodType<Wire<RequestPayload<K>>>
-    invoke(api: ApiProxy, request: RpcRequest<RequestPayload<K>>): Promise<RpcResponse<ResponseValue<K>>>
+    invoke(api: ApiProxy, request: RpcRequest<RequestPayload<K>>, signal: AbortSignal): Promise<RpcResponse<ResponseValue<K>>>
   }
 }
 
@@ -50,10 +64,21 @@ 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.models': { schema: sessionModelsRequestSchema, invoke: (api, r) => api.sessions.models(r) },
+  'session.selectModel': { schema: sessionSelectModelRequestSchema, invoke: (api, r) => api.sessions.selectModel(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) },
-  'goal.get': { schema: goalGetRequestSchema, invoke: (api, r) => api.goals.get(r) },
+  'host.pickDirectory': { schema: hostPickDirectoryRequestSchema, invoke: (api, r, signal) => api.host.pickDirectory(r, signal) },
+  'host.openPath': { schema: hostOpenPathRequestSchema, invoke: (api, r, signal) => api.host.openPath(r, signal) },
+  'workspace.list': { schema: workspaceListRequestSchema, invoke: (api, r) => api.workspace.list(r) },
+  'workspace.create': { schema: workspaceCreateRequestSchema, invoke: (api, r) => api.workspace.create(r) },
+  'workspace.rename': { schema: workspaceRenameRequestSchema, invoke: (api, r) => api.workspace.rename(r) },
+  'workspace.delete': { schema: workspaceDeleteRequestSchema, invoke: (api, r) => api.workspace.delete(r) },
+  'workspace.insertSessionBefore': { schema: workspaceInsertSessionBeforeRequestSchema, invoke: (api, r) => api.workspace.insertSessionBefore(r) },
+  'command.list': { schema: commandListRequestSchema, invoke: (api, r) => api.commands.list(r) },
+  'command.execute': { schema: commandExecuteRequestSchema, invoke: (api, r, signal) => api.commands.execute(r, signal) },
+  'skill.list': { schema: skillListRequestSchema, invoke: (api, r) => api.skills.list(r) },
   'goal.create': { schema: goalCreateRequestSchema, invoke: (api, r) => api.goals.create(r) },
   'goal.edit': { schema: goalEditRequestSchema, invoke: (api, r) => api.goals.edit(r) },
   'goal.pause': { schema: goalPauseRequestSchema, invoke: (api, r) => api.goals.pause(r) },
@@ -95,14 +120,16 @@ function fullResponse(narrow: RpcResponse<unknown>): Response {
 // 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> {
+async function handleUnary<K extends keyof RpcMethodMap>(
+  api: ApiProxy, method: K, message: ClientRequest, signal: AbortSignal,
+): 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 }))
+    return fullResponse(await route.invoke(api, { rpcId: message.rpcId, payload: payload.data }, signal))
   } 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 })
@@ -207,7 +234,7 @@ export function toFetchHandler(api: ApiProxy): { fetch: typeof fetch } {
       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)
+      return handleUnary(api, method, message, req.signal)
     },
   }
 }

packages/host/apiproxy/src/index.ts

@@ -1,13 +1,85 @@
 /**
- * @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.
+ * @deepseek-ai/dsh-host-apiproxy — the API gateway every client shape shares:
+ * the ApiProxy contract (api/: types + zod schemas, browser-safe), the fetch
+ * carrier pair (fetch/: toFetchHandler on the host side, AbstractApiClient +
+ * platform subclasses on the client side), and the host-side implementation
+ * (api-proxy.ts: createApiProxy + the ApiProxyService gateway plugin providing
+ * `ctx.apiProxy`). Transport-agnostic by design: this package registers no
+ * routes — carriers (HTTP today, IPC later) wrap `ctx.apiProxy` themselves.
  */
 
+import { resolve } from 'node:path'
+import { Context, Service } from 'cordis'
+import z from 'schemastery'
+import type { ApiProxy } from './api/index.ts'
+import { createApiProxy } from './api-proxy.ts'
+
 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'
+export { createApiProxy } from './api-proxy.ts'
+export type { ApiProxyDefaults } from './api-proxy.ts'
+
+declare module 'cordis' {
+  interface Context {
+    /** The host-side ApiProxy implementation (the transport-agnostic gateway face). */
+    apiProxy: ApiProxy
+  }
+}
+
+/** Gateway plugin config: host-level agent routing and Workspace creation root. */
+export interface Config {
+  /** Default provider route for created/resumed agents. */
+  provider: string
+  /** Default model id. */
+  model: string
+  /** Parent directory for name-created Workspaces; defaults to the Host cwd. */
+  workspaceRoot?: string
+}
+
+/**
+ * The API gateway service: implements the ApiProxy contract over the composed
+ * host context and provides it as `ctx.apiProxy`. The Host cwd is the default
+ * project directory and the fallback parent for name-created Workspaces.
+ */
+export class ApiProxyService extends Service implements ApiProxy {
+  static inject = ['agents', 'llm', 'sessions', 'tools', 'userInteraction', 'workspace']
+
+  static Config: z<Config> = z.object({
+    provider: z.string().required(),
+    model: z.string().required(),
+    workspaceRoot: z.string(),
+  })
+
+  readonly sessions: ApiProxy['sessions']
+  readonly workspace: ApiProxy['workspace']
+  readonly host: ApiProxy['host']
+  readonly commands: ApiProxy['commands']
+  readonly skills: ApiProxy['skills']
+  readonly events: ApiProxy['events']
+  readonly respond: ApiProxy['respond']
+
+  constructor(ctx: Context, config: Config) {
+    super(ctx, 'apiProxy')
+    const cwd = process.cwd()
+    const api = createApiProxy(ctx, {
+      provider: config.provider,
+      model: config.model,
+      cwd,
+      workspaceRoot: resolve(config.workspaceRoot ?? cwd),
+    })
+    this.sessions = api.sessions
+    this.workspace = api.workspace
+    this.host = api.host
+    this.commands = api.commands
+    this.skills = api.skills
+    this.events = api.events
+    // createApiProxy returns closures (no `this` capture); bind only satisfies
+    // the unbound-method lint without changing behavior.
+    this.respond = api.respond.bind(api)
+  }
+}
+
+export default ApiProxyService

packages/host/apiproxy/src/invariant.ts

@@ -15,11 +15,12 @@ export const name = 'host-apiproxy-invariant'
 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.
+ * No runtime invariant: this package is the wire contract layer plus the
+ * host-side gateway over services owned elsewhere — it emits no cordis events
+ * of its own; the session/agent event streams it projects are asserted by
+ * their owning packages' companions. rpcId round-trip and schema acceptance
+ * are enforced at the carrier boundary and exercised by the
+ * protocol-isomorphism suite.
  */
 const install: InvariantInstaller = () => {}
 

packages/host/apiproxy/src/native-command.ts

@@ -0,0 +1,38 @@
+/** Shared no-shell `execFile` runner for native host dialogs and openers. */
+
+import { execFile } from 'node:child_process'
+
+/** Testable command boundary; native implementations never invoke a shell. */
+export type NativeCommandRunner = (
+  command: string,
+  args: readonly string[],
+  signal: AbortSignal,
+) => Promise<{ stdout: string; stderr: string }>
+
+/**
+ * Run a host command with utf8 stdio, abort propagation, and Windows hide.
+ * @param command - executable path or PATH name.
+ * @param args - argv (never a shell string).
+ * @param signal - caller/connection lifetime; abort terminates the child.
+ * @returns captured stdout/stderr on exit 0.
+ */
+export const runNativeCommand: NativeCommandRunner = (command, args, signal) =>
+  new Promise((resolve, reject) => {
+    execFile(
+      command,
+      [...args],
+      { encoding: 'utf8', signal, windowsHide: true },
+      (error, stdout, stderr) => {
+        if (error !== null) {
+          const failure = Object.assign(new Error(error.message, { cause: error }), {
+            code: error.code,
+            stdout,
+            stderr,
+          })
+          reject(failure)
+          return
+        }
+        resolve({ stdout, stderr })
+      },
+    )
+  })

packages/host/apiproxy/src/native-directory-picker.ts

@@ -0,0 +1,111 @@
+/** Cross-platform native single-directory picker used by the local GUI carrier. */
+
+import { runNativeCommand, type NativeCommandRunner } from './native-command.ts'
+
+/** Testable command boundary; native implementations never invoke a shell. */
+export type DirectoryPickerRunner = NativeCommandRunner
+
+/** Injectable platform facts for deterministic adapter tests. */
+export interface DirectoryPickerInternals {
+  platform?: NodeJS.Platform
+  run?: DirectoryPickerRunner
+}
+
+function outputPath(stdout: string): string | null {
+  const path = stdout.replace(/[\r\n]+$/, '')
+  return path === '' ? null : path
+}
+
+function errorCode(error: unknown): string | number | undefined {
+  if (typeof error !== 'object' || error === null || !('code' in error)) return undefined
+  const code = (error as { code?: unknown }).code
+  return typeof code === 'string' || typeof code === 'number' ? code : undefined
+}
+
+function errorStderr(error: unknown): string {
+  if (typeof error !== 'object' || error === null || !('stderr' in error)) return ''
+  const stderr = (error as { stderr?: unknown }).stderr
+  return typeof stderr === 'string' ? stderr : ''
+}
+
+function isMissingCommand(error: unknown): boolean {
+  return errorCode(error) === 'ENOENT'
+}
+
+function rethrowIfAborted(signal: AbortSignal, error: unknown): void {
+  if (signal.aborted) throw error
+}
+
+/**
+ * Open the platform directory picker.
+ * @param signal - caller/connection lifetime; abort terminates the native command.
+ * @param internals - platform and runner seam for deterministic tests.
+ * @returns the selected path, or null when the user cancels.
+ */
+export async function pickNativeDirectory(
+  signal: AbortSignal,
+  internals: DirectoryPickerInternals = {},
+): Promise<string | null> {
+  const platform = internals.platform ?? process.platform
+  const run = internals.run ?? runNativeCommand
+
+  if (platform === 'darwin') {
+    try {
+      const result = await run('osascript', [
+        '-e', 'set selectedFolder to choose folder with prompt "Select Workspace Directory"',
+        '-e', 'POSIX path of selectedFolder',
+      ], signal)
+      return outputPath(result.stdout)
+    } catch (error: unknown) {
+      if (!signal.aborted && errorCode(error) === 1
+        && /(?:User canceled|-128)/i.test(errorStderr(error))) return null
+      throw error
+    }
+  }
+
+  if (platform === 'win32') {
+    const script = [
+      "$ErrorActionPreference = 'Stop'",
+      'Add-Type -AssemblyName System.Windows.Forms',
+      '$dialog = New-Object System.Windows.Forms.FolderBrowserDialog',
+      "$dialog.Description = 'Select Workspace Directory'",
+      '$dialog.ShowNewFolderButton = $true',
+      '$result = $dialog.ShowDialog()',
+      'if ($result -eq [System.Windows.Forms.DialogResult]::OK) {',
+      '  [Console]::OutputEncoding = [System.Text.Encoding]::UTF8',
+      '  [Console]::WriteLine($dialog.SelectedPath)',
+      '}',
+    ].join('; ')
+    const result = await run('powershell.exe', ['-NoProfile', '-STA', '-Command', script], signal)
+    return outputPath(result.stdout)
+  }
+
+  if (platform === 'linux') {
+    try {
+      const result = await run('zenity', [
+        '--file-selection', '--directory', '--title=Select Workspace Directory',
+      ], signal)
+      return outputPath(result.stdout)
+    } catch (error: unknown) {
+      rethrowIfAborted(signal, error)
+      if (errorCode(error) === 1) return null
+      if (!isMissingCommand(error)) throw error
+    }
+
+    try {
+      const result = await run('kdialog', [
+        '--getexistingdirectory', '.', '--title', 'Select Workspace Directory',
+      ], signal)
+      return outputPath(result.stdout)
+    } catch (error: unknown) {
+      rethrowIfAborted(signal, error)
+      if (errorCode(error) === 1) return null
+      if (isMissingCommand(error)) {
+        throw new Error('no supported native directory picker found (install zenity or kdialog)')
+      }
+      throw error
+    }
+  }
+
+  throw new Error(`native directory picker is unsupported on ${platform}`)
+}

packages/host/apiproxy/src/native-path-opener.ts

@@ -0,0 +1,53 @@
+/** Cross-platform open-with-default-application used by the local GUI carrier. */
+
+import { runNativeCommand, type NativeCommandRunner } from './native-command.ts'
+
+/** Testable command boundary; native implementations never invoke a shell. */
+export type PathOpenerRunner = NativeCommandRunner
+
+/** Injectable platform facts for deterministic adapter tests. */
+export interface PathOpenerInternals {
+  platform?: NodeJS.Platform
+  run?: PathOpenerRunner
+}
+
+/** PowerShell single-quoted literal (doubles embedded quotes). */
+function powershellLiteral(path: string): string {
+  return `'${path.replace(/'/g, "''")}'`
+}
+
+/**
+ * Open a filesystem path with the operating system's default application.
+ * @param path - absolute or host-resolvable path (caller owns resolution).
+ * @param signal - caller/connection lifetime; abort terminates the native command.
+ * @param internals - platform and runner seam for deterministic tests.
+ */
+export async function openNativePath(
+  path: string,
+  signal: AbortSignal,
+  internals: PathOpenerInternals = {},
+): Promise<void> {
+  const platform = internals.platform ?? process.platform
+  const run = internals.run ?? runNativeCommand
+
+  if (platform === 'darwin') {
+    await run('open', [path], signal)
+    return
+  }
+
+  if (platform === 'win32') {
+    await run('powershell.exe', [
+      '-NoProfile',
+      '-Command',
+      `Invoke-Item -LiteralPath ${powershellLiteral(path)}`,
+    ], signal)
+    return
+  }
+
+  if (platform === 'linux') {
+    await run('xdg-open', [path], signal)
+    return
+  }
+
+  throw new Error(`native path opener is unsupported on ${platform}`)
+}

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

@@ -1,8 +1,9 @@
 /**
  * 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.
+ * createdAt fallbacks, lineage projection), the resume error split when
+ * the composition has no persistence gate and no agent factory, and the
+ * agent-busy mapping of a synchronous prompt rejection.
  */
 
 import { mkdtempSync, writeFileSync, utimesSync } from 'node:fs'
@@ -12,10 +13,12 @@ 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 { Agent } from '@deepseek-ai/dsh-agent'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 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'
+import { createApiProxy } from '@deepseek-ai/dsh-host-apiproxy'
 
 const sid = (id: string): SessionId => id as SessionId
 
@@ -32,6 +35,7 @@ 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)
+    await ctx.plugin(UserInteractionService)
     const root = mkdtempSync(join(tmpdir(), 'dsh-cold-'))
     const logPath = join(root, 'a.log')
     writeFileSync(logPath, 'log-bytes')
@@ -53,7 +57,7 @@ describe('sessions.list cold merge', () => {
         return undefined
       },
     })
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const response = await api.sessions.list(request({}))
     expect(response.result.ok).toBe(true)
@@ -63,6 +67,9 @@ describe('sessions.list cold merge', () => {
     const [a, b, c] = items
     expect(a?.updatedAt).toBeCloseTo(5_000_000, -3)
     expect(a?.running).toBe(false)
+    // Cold summaries are never blank: lazy persistence keeps never-appended
+    // sessions out of list(), so a listed session necessarily has events.
+    expect(items.every(item => !item.blank)).toBe(true)
     expect(a?.cwd).toBe('/proj')
     expect(a?.parentSessionId).toBeUndefined()
     expect(b?.updatedAt).toBe(2000)
@@ -76,7 +83,8 @@ describe('degenerate composition (no persistence, no factory)', () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     await ctx.plugin(AgentRegistry)
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
+    await ctx.plugin(UserInteractionService)
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
 
     const listed = await api.sessions.list(request({}))
     expect(listed.result.ok).toBe(true)
@@ -92,3 +100,38 @@ describe('degenerate composition (no persistence, no factory)', () => {
     }
   })
 })
+
+describe('sessions.prompt synchronous rejection', () => {
+  it('maps a synchronous send throw (disposed/invalid input) to agent-busy with the reason attached', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(UserInteractionService)
+    const session = ctx.sessions.create(sid('session-throwing'))
+    // A live structural stub whose delivery verbs throw synchronously, the
+    // shape a disposed loop presents at this seam.
+    ctx.agents.register({
+      id: session.id,
+      session,
+      status: 'idle',
+      ctx,
+      followup: () => { throw new Error('agent "session-throwing" lifecycle disposed') },
+      steer: () => { throw new Error('agent "session-throwing" lifecycle disposed') },
+    } as unknown as Agent)
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+
+    for (const mode of ['queue', 'steer'] as const) {
+      const response = await api.sessions.prompt(request({
+        sessionId: session.id, mode, content: [{ type: 'text' as const, text: 'x' }],
+      }))
+      expect(response.result.ok).toBe(false)
+      if (!response.result.ok) {
+        expect(response.result.error.code).toBe('agent-busy')
+        expect(response.result.error.message).toBe('prompt rejected')
+        expect(response.result.error.details).toEqual({
+          reason: 'Error: agent "session-throwing" lifecycle disposed',
+        })
+      }
+    }
+  })
+})

packages/host/apiproxy/tests/api-proxy-commands.spec.ts

@@ -0,0 +1,339 @@
+import { MessageId, freezeMessage } from '@deepseek-ai/dsh-llm'
+/**
+ * Command/skill RPC handlers and the two new frames over createApiProxy:
+ * command.list serves the addressed agent's effective catalog (missing
+ * registry = loud internal error), command.execute dispatches through the
+ * registry with the carrier signal, skill.list resolves cwd from the session
+ * header (never via the Agent registry), the host stream broadcasts
+ * commands-changed, and the mux stream carries live queued frames plus the
+ * open-time queue snapshot.
+ */
+
+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 type { SessionId, UserMessage } from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import CommandService from '@deepseek-ai/dsh-commands'
+import SkillService from '@deepseek-ai/dsh-skill'
+import type { HostFrame, MuxFrame } from '../src/api/index.ts'
+import type { RpcRequest, RpcResponse } from '../src/api/rpc.ts'
+import { RpcId } from '../src/api/rpc.ts'
+import { createApiProxy } from '../src/api-proxy.ts'
+
+const DEFAULTS = { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' }
+
+function request<P>(payload: P): RpcRequest<P> {
+  return { rpcId: RpcId(`req-${String(nextRpc++)}`), payload }
+}
+let nextRpc = 1
+
+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
+}
+
+function expectErr<T>(response: RpcResponse<T>): { code: string; message: string } {
+  expect(response.result.ok).toBe(false)
+  if (response.result.ok) throw new Error('unreachable')
+  return response.result.error
+}
+
+/** Composition floor for the command/skill paths (no LLM, no persistence). */
+async function harness(options: { commands?: boolean; skills?: boolean } = {}): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt, { persona: '' })
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(UserInteractionService)
+  await ctx.plugin(AgentRegistry)
+  if (options.skills !== false) await ctx.plugin(SkillService, {})
+  if (options.commands !== false) await ctx.plugin(CommandService)
+  // Host-stream opener reads the committed-workspace baseline; the stub
+  // suffices here — the real workspace composition is api-proxy-workspace.spec's.
+  ctx.provide('workspace', { list: () => [] } as never)
+  return ctx
+}
+
+/** Register a live structural agent stub (api-proxy-view precedent: only id/session/status/ctx are read). */
+function stubAgent(ctx: Context, sessionId?: SessionId): Agent {
+  const session = ctx.sessions.create(sessionId)
+  const agent = { id: session.id, session, status: 'idle', ctx } as Agent
+  ctx.agents.register(agent)
+  return agent
+}
+
+/** Drain `count` frames from a stream, then abort it. */
+async function collect<F>(iterable: AsyncIterable<RpcRequest<F>>, count: number, abort: AbortController): Promise<F[]> {
+  const frames: F[] = []
+  for await (const frame of iterable) {
+    frames.push(frame.payload)
+    if (frames.length >= count) abort.abort()
+  }
+  return frames
+}
+
+describe('command.list', () => {
+  it('serves the addressed agent\'s name-sorted catalog', async () => {
+    const ctx = await harness()
+    ctx.commands.register({ name: 'zeta', description: 'z', handler: () => ({ kind: 'success' }) })
+    ctx.commands.register({ name: 'alpha', description: 'a', input: { hint: '<x>' }, handler: () => ({ kind: 'success' }) })
+    const api = createApiProxy(ctx, DEFAULTS)
+    const agent = stubAgent(ctx)
+    const value = expectOk(await api.commands.list(request({ sessionId: agent.id })))
+    expect(value.commands).toEqual([
+      { name: 'alpha', description: 'a', input: { hint: '<x>' } },
+      { name: 'zeta', description: 'z' },
+    ])
+  })
+
+  it('fails loud with internal when the command registry is not mounted', async () => {
+    const ctx = await harness({ commands: false })
+    const api = createApiProxy(ctx, DEFAULTS)
+    const error = expectErr(await api.commands.list(request({ sessionId: 's' as SessionId })))
+    expect(error.code).toBe('internal')
+    expect(error.message).toContain('command registry')
+  })
+})
+
+describe('command.execute', () => {
+  it('executes a known command against the addressed agent and detaches the result', async () => {
+    const ctx = await harness()
+    let received: string | undefined
+    ctx.commands.register({
+      name: 'goal',
+      description: 'set goal',
+      handler: (invocation) => {
+        received = invocation.rawInput
+        return { kind: 'success', text: `goal:${invocation.agent.id}` }
+      },
+    })
+    const api = createApiProxy(ctx, DEFAULTS)
+    const agent = stubAgent(ctx)
+    const value = expectOk(await api.commands.execute(request({ sessionId: agent.id, line: '/goal ship it' }), new AbortController().signal))
+    expect(value).toMatchObject({ matched: true })
+    expect(value.commandId).toBeTruthy()
+    expect(received).toBe(' ship it')
+    // Pure admission on the wire: the outcome rides the durably logged
+    // lifecycle pair instead of the response.
+    const lifecycle = agent.session.events.filter(e => e.type === 'command/run' || e.type === 'command/done')
+    expect(lifecycle).toMatchObject([
+      { type: 'command/run', data: { commandId: value.commandId, name: 'goal', args: ' ship it' } },
+      { type: 'command/done', data: { commandId: value.commandId, kind: 'success', text: `goal:${agent.id}` } },
+    ])
+  })
+
+  it('returns matched:false when syntax or name does not resolve', async () => {
+    const ctx = await harness()
+    const api = createApiProxy(ctx, DEFAULTS)
+    const agent = stubAgent(ctx)
+    const signal = new AbortController().signal
+    expect(expectOk(await api.commands.execute(request({ sessionId: agent.id, line: '/unknown' }), signal))).toEqual({ matched: false })
+    expect(expectOk(await api.commands.execute(request({ sessionId: agent.id, line: 'not a command' }), signal))).toEqual({ matched: false })
+  })
+
+  it('maps a session miss to session-not-found and a registry gap to internal', async () => {
+    const ctx = await harness()
+    const api = createApiProxy(ctx, DEFAULTS)
+    const missing = expectErr(await api.commands.execute(
+      request({ sessionId: 'session-nope' as SessionId, line: '/x' }), new AbortController().signal))
+    expect(missing.code).toBe('internal') // no persistence configured: resume fails loud past the gate
+
+    const bare = await harness({ commands: false })
+    const bareApi = createApiProxy(bare, DEFAULTS)
+    expect(expectErr(await bareApi.commands.execute(
+      request({ sessionId: 's' as SessionId, line: '/x' }), new AbortController().signal)).code).toBe('internal')
+  })
+
+  it('reports an aborted handler as cancelled and a throwing handler as internal', async () => {
+    const ctx = await harness()
+    ctx.commands.register({
+      name: 'hang',
+      description: 'never settles on its own',
+      handler: () => new Promise(() => { /* settled only by abort */ }),
+    })
+    ctx.commands.register({
+      name: 'boom',
+      description: 'throws',
+      handler: () => { throw new Error('kaboom') },
+    })
+    const api = createApiProxy(ctx, DEFAULTS)
+    const agent = stubAgent(ctx)
+
+    const controller = new AbortController()
+    const pending = api.commands.execute(request({ sessionId: agent.id, line: '/hang' }), controller.signal)
+    controller.abort()
+    expect(expectErr(await pending).code).toBe('cancelled')
+
+    const thrown = expectErr(await api.commands.execute(request({ sessionId: agent.id, line: '/boom' }), new AbortController().signal))
+    expect(thrown.code).toBe('internal')
+    expect(thrown.message).toContain('kaboom')
+  })
+})
+
+describe('skill.list', () => {
+  it('lists skills for the session cwd taken from the header', async () => {
+    const ctx = await harness()
+    const seenCwds: (string | undefined)[] = []
+    ctx.skills.registerProvider({
+      name: 'probe',
+      list: (options) => {
+        seenCwds.push(options.cwd)
+        return Promise.resolve([{
+          name: 'commit-helper', description: 'Git commits', whenToUse: 'when committing',
+          source: 'custom', provider: 'probe', rank: 0, locator: null,
+        }])
+      },
+      get: () => Promise.resolve(undefined),
+    })
+    const api = createApiProxy(ctx, DEFAULTS)
+    // No agent is registered for this session: header resolution must not
+    // touch (or resume through) the Agent registry.
+    const session = ctx.sessions.create(undefined, { meta: { cwd: '/proj' } })
+    const value = expectOk(await api.skills.list(request({ sessionId: session.id })))
+    expect(value.skills).toEqual([{ name: 'commit-helper', description: 'Git commits', whenToUse: 'when committing' }])
+    expect(seenCwds).toEqual(['/proj'])
+    expect(ctx.agents.get(session.id)).toBeUndefined()
+  })
+
+  it('fails loud on an unattached session id (business error, no resume attempt)', async () => {
+    const ctx = await harness()
+    const api = createApiProxy(ctx, DEFAULTS)
+    const error = expectErr(await api.skills.list(request({ sessionId: 'session-cold' as SessionId })))
+    expect(error.code).toBe('session-not-found')
+  })
+
+  it('fails loud with internal when the skill registry is not mounted', async () => {
+    const ctx = await harness({ skills: false })
+    const api = createApiProxy(ctx, DEFAULTS)
+    const session = ctx.sessions.create(undefined, { meta: { cwd: '/proj' } })
+    const error = expectErr(await api.skills.list(request({ sessionId: session.id })))
+    expect(error.code).toBe('internal')
+    expect(error.message).toContain('skill registry is absent')
+  })
+
+  it('folds a provider failure into internal', async () => {
+    const ctx = await harness()
+    ctx.skills.registerProvider({
+      name: 'broken',
+      list: () => Promise.reject(new Error('directory exploded')),
+      get: () => Promise.resolve(undefined),
+    })
+    const api = createApiProxy(ctx, DEFAULTS)
+    const session = ctx.sessions.create(undefined, { meta: { cwd: '/proj' } })
+    const response = await api.skills.list(request({ sessionId: session.id }))
+    // dsh-skill contains one provider's failure (logs and serves the rest), so
+    // this surfaces as an empty ok catalog rather than an error.
+    const value = expectOk(response)
+    expect(value.skills).toEqual([])
+  })
+})
+
+describe('host/commands-changed frame', () => {
+  it('broadcasts on registry change', async () => {
+    const ctx = await harness()
+    const api = createApiProxy(ctx, DEFAULTS)
+    const abort = new AbortController()
+    const stream = api.events.host({ rpcId: RpcId('t-host'), payload: {} }, abort.signal)
+    const collected = collect<HostFrame>(stream, 1, abort)
+    ctx.commands.register({ name: 'late', description: 'l', handler: () => ({ kind: 'success' }) })
+    expect(await collected).toEqual([{ type: 'host/commands-changed' }])
+  })
+})
+
+/** Build one frozen inbox message for the live `agent/inbox/*` events. */
+function inboxMessage(id: string, text: string, rpcId?: string): UserMessage {
+  return freezeMessage({
+    id: MessageId(id),
+    role: 'user',
+    content: [{ type: 'text' as const, text }],
+    source: rpcId === undefined ? { kind: 'user' as const } : { kind: 'user' as const, rpcId: RpcId(rpcId) },
+  })
+}
+
+describe('session/queued frames', () => {
+  it('forwards live enqueue events and replays the snapshot on a later mux open', async () => {
+    const ctx = await harness()
+    const api = createApiProxy(ctx, DEFAULTS)
+    const agent = stubAgent(ctx)
+    const live = new AbortController()
+    const liveStream = api.events.mux({ rpcId: RpcId('t-mux-live'), payload: {} }, live.signal)
+    // subscribed baseline + 2 queued frames
+    const liveCollected = collect<MuxFrame>(liveStream, 3, live)
+
+    const queued = inboxMessage('m-1', 'queued prompt')
+    const steering = inboxMessage('m-2', 'queued prompt')
+    ctx.emit('agent/inbox/enqueue', agent, queued, 'queued')
+    ctx.emit('agent/inbox/enqueue', agent, steering, 'steering')
+
+    const liveFrames = (await liveCollected).filter(f => f.type === 'session/queued')
+    expect(liveFrames).toEqual([
+      { type: 'session/queued', sessionId: agent.id, message: queued, steering: false },
+      { type: 'session/queued', sessionId: agent.id, message: steering, steering: true },
+    ])
+
+    // A fresh mux connection replays the still-pending entries as its baseline.
+    const replay = new AbortController()
+    const replayFrames = await collect<MuxFrame>(
+      api.events.mux({ rpcId: RpcId('t-mux-replay'), payload: {} }, replay.signal), 3, replay)
+    expect(replayFrames.filter(f => f.type === 'session/queued')).toEqual(liveFrames)
+  })
+
+  it('retires mirror entries on their terminal dequeue', async () => {
+    const ctx = await harness()
+    const api = createApiProxy(ctx, DEFAULTS)
+    const agent = stubAgent(ctx)
+    const queued = inboxMessage('m-3', 'x')
+    const steering = inboxMessage('m-4', 'x', 'r-1')
+    ctx.emit('agent/inbox/enqueue', agent, queued, 'queued')
+    ctx.emit('agent/inbox/enqueue', agent, steering, 'steering')
+    ctx.emit('agent/inbox/dequeue', agent, queued, 'queued')
+    ctx.emit('agent/inbox/dequeue', agent, steering, 'steering')
+
+    const abort = new AbortController()
+    const frames = await collect<MuxFrame>(
+      api.events.mux({ rpcId: RpcId('t-mux-after'), payload: {} }, abort.signal), 1, abort)
+    expect(frames.filter(f => f.type === 'session/queued')).toHaveLength(0)
+  })
+
+  it('retires the matching placement when one message identity is queued and steering', async () => {
+    const ctx = await harness()
+    const api = createApiProxy(ctx, DEFAULTS)
+    const agent = stubAgent(ctx)
+    const repeated = inboxMessage('m-repeat', 'same prompt')
+    ctx.emit('agent/inbox/enqueue', agent, repeated, 'queued')
+    ctx.emit('agent/inbox/enqueue', agent, repeated, 'steering')
+    ctx.emit('agent/inbox/dequeue', agent, inboxMessage('unknown', 'not queued'), 'queued')
+    ctx.emit('agent/inbox/dequeue', agent, repeated, 'steering')
+
+    const abort = new AbortController()
+    const frames = await collect<MuxFrame>(
+      api.events.mux({ rpcId: RpcId('t-mux-repeat'), payload: {} }, abort.signal), 2, abort)
+    expect(frames.filter(f => f.type === 'session/queued')).toEqual([
+      { type: 'session/queued', sessionId: agent.id, message: repeated, steering: false },
+    ])
+  })
+
+  it('retires mirror entries on a batch discard (cancel path)', async () => {
+    const ctx = await harness()
+    const api = createApiProxy(ctx, DEFAULTS)
+    const agent = stubAgent(ctx)
+    const doomed = inboxMessage('m-5', 'doomed')
+    const survivor = inboxMessage('m-6', 'survivor')
+    ctx.emit('agent/inbox/enqueue', agent, doomed, 'queued')
+    ctx.emit('agent/inbox/enqueue', agent, survivor, 'queued')
+    ctx.emit('agent/inbox/discard', agent, [doomed])
+
+    const abort = new AbortController()
+    const frames = await collect<MuxFrame>(
+      api.events.mux({ rpcId: RpcId('t-mux-swept'), payload: {} }, abort.signal), 2, abort)
+    const remaining = frames.filter(f => f.type === 'session/queued')
+    expect(remaining).toHaveLength(1)
+    expect(remaining[0]).toMatchObject({ message: survivor })
+  })
+})

packages/host/apiproxy/tests/api-proxy-models.spec.ts

@@ -0,0 +1,233 @@
+/**
+ * Web session model-directory and selection behavior: dynamic provider grouping,
+ * provider-local catalog failures, logged-target restoration, advisory unlisted
+ * models, and the prompt-assembly boundary for a running selection change.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import AgentRegistry, { agentEvents } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import LlmService, { LlmAdapter, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
+import type {
+  GenerateOptions, LlmCallConfig, LlmModelInfo, LlmModelReasoningInfo, LlmProviderInfo,
+  LlmResolvedModelInfo, StreamChunk,
+} from '@deepseek-ai/dsh-llm'
+import SessionStore from '@deepseek-ai/dsh-session'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+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'
+
+let nextRpc = 1
+function request<P>(payload: P): RpcRequest<P> {
+  return { rpcId: RpcId(`models-${String(nextRpc++)}`), payload }
+}
+
+class CatalogAdapter extends LlmAdapter {
+  constructor(
+    private readonly name: string,
+    private readonly models: readonly LlmModelInfo[] | Error,
+    private readonly reasoning?: LlmModelReasoningInfo,
+    private readonly exactError?: Error,
+  ) {
+    super()
+  }
+
+  override providerInfo(provider: string): LlmProviderInfo {
+    return { id: provider, name: this.name }
+  }
+
+  override listModels(): Promise<readonly LlmModelInfo[]> {
+    return this.models instanceof Error
+      ? Promise.reject(this.models)
+      : Promise.resolve(this.models)
+  }
+
+  override resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo> {
+    if (this.exactError !== undefined) return Promise.reject(this.exactError)
+    return Promise.resolve({
+      provider,
+      id: model,
+      name: model,
+      ...this.reasoning === undefined ? {} : { reasoning: this.reasoning },
+    })
+  }
+
+  override async *stream(_options: GenerateOptions): AsyncIterable<StreamChunk> {
+    // Catalog tests never enter provider streaming.
+  }
+}
+
+const REASONING: LlmModelReasoningInfo = {
+  efforts: [
+    { id: ReasoningEffortId('off'), name: 'Off' },
+    { id: ReasoningEffortId('high'), name: 'High' },
+    { id: ReasoningEffortId('max'), name: 'Max' },
+  ],
+  defaultEffort: ReasoningEffortId('high'),
+}
+
+async function harness(logged?: {
+  provider: string
+  model: string
+  reasoningEffort?: ReasoningEffortId
+}): Promise<{
+  ctx: Context
+  agent: Agent
+  sessionId: SessionId
+}> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt, { persona: '' })
+  await ctx.plugin(LlmService)
+  await ctx.plugin(UserInteractionService)
+  await ctx.plugin(AgentRegistry)
+  ctx.llm.registerAdapter(['deepseek'], new CatalogAdapter('DeepSeek', [
+    { provider: 'deepseek', id: 'deepseek-chat', name: 'DeepSeek Chat' },
+    { provider: 'deepseek', id: 'deepseek-reasoner', name: 'DeepSeek Reasoner', description: 'Reasoning model' },
+  ], REASONING))
+  ctx.llm.registerAdapter(['broken'], new CatalogAdapter('Broken Provider', new Error('catalog offline')))
+  ctx.llm.registerAdapter(['metadata-broken'], new CatalogAdapter('Metadata Broken', [
+    { provider: 'metadata-broken', id: 'listed', name: 'Listed' },
+  ], undefined, new Error('reasoning metadata offline')))
+  ctx.llm.registerAdapter(['empty'], new CatalogAdapter('Empty Provider', []))
+  ctx.llm.registerAdapter(['duplicate'], new CatalogAdapter('Duplicate Provider', [
+    { provider: 'duplicate', id: 'same', name: 'Same' },
+    { provider: 'duplicate', id: 'same', name: 'Same Again' },
+  ]))
+  const session = ctx.sessions.create()
+  if (logged !== undefined) {
+    session.append('request/header', { header: { config: logged }, reason: 'initial' })
+  }
+  const agent = {
+    id: session.id,
+    session,
+    status: 'running',
+    ctx,
+  } as Agent
+  ctx.agents.register(agent)
+  return { ctx, agent, sessionId: session.id }
+}
+
+function expectValue<T>(response: { result: { ok: true; value: T } | { ok: false } }): T {
+  if (!response.result.ok) throw new Error('expected successful response')
+  return response.result.value
+}
+
+describe('Web session model selection', () => {
+  it('groups successful providers, isolates failures, and preserves an unlisted current model', async () => {
+    const { ctx, sessionId } = await harness({
+      provider: 'deepseek',
+      model: 'private-preview',
+      reasoningEffort: ReasoningEffortId('max'),
+    })
+    const api = createApiProxy(ctx, { provider: 'deepseek', model: 'deepseek-chat', cwd: '/tmp', workspaceRoot: '/tmp' })
+
+    const catalog = expectValue(await api.sessions.models(request({ sessionId })))
+    expect(catalog.current).toEqual({
+      provider: 'deepseek',
+      model: 'private-preview',
+      reasoningEffort: 'max',
+    })
+    expect(catalog.groups).toEqual([{
+      id: 'deepseek',
+      name: 'DeepSeek',
+      models: [
+        { id: 'deepseek-chat', name: 'DeepSeek Chat', reasoning: REASONING },
+        {
+          id: 'deepseek-reasoner',
+          name: 'DeepSeek Reasoner',
+          description: 'Reasoning model',
+          reasoning: REASONING,
+        },
+        {
+          id: 'private-preview',
+          name: 'private-preview',
+          unlisted: true,
+          reasoning: REASONING,
+        },
+      ],
+    }])
+    expect(catalog.failures).toEqual([
+      { id: 'broken', name: 'Broken Provider', message: 'catalog offline' },
+      { id: 'metadata-broken', name: 'Metadata Broken', message: 'reasoning metadata offline' },
+      {
+        id: 'duplicate',
+        name: 'Duplicate Provider',
+        message: 'adapter returned invalid or duplicate model metadata for provider "duplicate"',
+      },
+    ])
+    await ctx.fiber.dispose()
+  })
+
+  it('accepts an advisory-unlisted model, rejects an unavailable provider, and switches only after the next assembly', async () => {
+    const { ctx, agent, sessionId } = await harness()
+    const api = createApiProxy(ctx, { provider: 'deepseek', model: 'deepseek-chat', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const seed: LlmCallConfig = { provider: 'seed', model: 'seed', temperature: 0.2 }
+    const signal = new AbortController().signal
+
+    expect(expectValue(await api.sessions.models(request({ sessionId }))).current)
+      .toEqual({ provider: 'deepseek', model: 'deepseek-chat' })
+    expect((await ctx.systemPrompt.assemble()).variables)
+      .toMatchObject({ provider: 'deepseek', model: 'deepseek-chat' })
+
+    const selected = expectValue(await api.sessions.selectModel(request({
+      sessionId,
+      provider: 'deepseek',
+      model: 'private-preview',
+      reasoningEffort: 'max',
+    })))
+    expect(selected.selected).toEqual({
+      provider: 'deepseek',
+      model: 'private-preview',
+      reasoningEffort: 'max',
+    })
+    await expect(agentEvents(ctx, agent).waterfall(
+      'agent/request', 1, 0, signal, () => Promise.resolve(seed),
+    )).resolves.toMatchObject({ provider: 'deepseek', model: 'deepseek-chat' })
+
+    expect((await ctx.systemPrompt.assemble()).variables)
+      .toMatchObject({ provider: 'deepseek', model: 'private-preview' })
+    await expect(agentEvents(ctx, agent).waterfall(
+      'agent/request', 1, 1, signal, () => Promise.resolve(seed),
+    )).resolves.toMatchObject({
+      provider: 'deepseek',
+      model: 'private-preview',
+      reasoningEffort: 'max',
+    })
+
+    const unsupported = await api.sessions.selectModel(request({
+      sessionId,
+      provider: 'deepseek',
+      model: 'private-preview',
+      reasoningEffort: 'medium',
+    }))
+    expect(unsupported.result).toMatchObject({
+      ok: false,
+      error: {
+        code: 'model-unavailable',
+        message: 'provider "deepseek" model "private-preview" does not support reasoning effort "medium"',
+      },
+    })
+
+    const rejected = await api.sessions.selectModel(request({
+      sessionId,
+      provider: 'missing',
+      model: 'model',
+    }))
+    expect(rejected.result).toEqual({
+      ok: false,
+      error: {
+        code: 'model-unavailable',
+        message: 'no adapter registered for provider "missing"',
+        details: { provider: 'missing', model: 'model' },
+      },
+    })
+    expect(expectValue(await api.sessions.models(request({ sessionId }))).current)
+      .toEqual({ provider: 'deepseek', model: 'private-preview', reasoningEffort: 'max' })
+    await ctx.fiber.dispose()
+  })
+})

packages/host/apiproxy/tests/api-proxy-projections.spec.ts

@@ -0,0 +1,185 @@
+/**
+ * Projection carrier paths of the host ApiProxy: the history tail page's
+ * projections block reads the registry's watermark snapshot (asOfSeq = last
+ * event seq, one consistent cut); loadOlder pages never carry the block; a
+ * composition without the registry serves histories without it; a disposed
+ * registration's key leaves subsequent responses; and every unit change is
+ * pushed to mux consumers as a session/projection frame minted here.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { z } from 'zod'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import SessionStore from '@deepseek-ai/dsh-session'
+import type { Session } from '@deepseek-ai/dsh-session'
+import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
+import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import type { MuxFrame, RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api'
+import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import { createApiProxy } from '@deepseek-ai/dsh-host-apiproxy'
+
+declare module '@deepseek-ai/dsh-session-projection/types' {
+  interface SessionProjectionMap {
+    'test/last-user': { text: string } | null
+  }
+}
+
+let nextRpc = 1
+function request<P>(payload: P): RpcRequest<P> {
+  return { rpcId: RpcId(`proj-${String(nextRpc++)}`), payload }
+}
+
+/** Whole-value unit folding the latest user/message text; null before the first. */
+type LastUserState = { text: string } | null
+const lastUserUnit = (): ProjectionDefinition<'test/last-user', LastUserState> => ({
+  key: 'test/last-user',
+  schema: z.union([z.object({ text: z.string() }), z.null()]),
+  init: () => null,
+  apply: (state, event) => (event.type === 'user/message'
+    ? { text: (event.data.content[0] as { text?: string }).text ?? '' }
+    : state),
+  view: state => state,
+  stateVersion: 1,
+})
+
+async function harness(withRegistry: boolean): Promise<{ ctx: Context; session: Session }> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(UserInteractionService)
+  await ctx.plugin(AgentRegistry)
+  if (withRegistry) await ctx.plugin(SessionProjectionRegistry)
+  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)
+  return { ctx, session }
+}
+
+/** Append `count` user messages so the log has paginable message boundaries. */
+function seedMessages(session: Session, count: number): void {
+  for (let i = 0; i < count; i++) {
+    session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: `m${i}` }],
+      source: { kind: 'user' },
+    }), { surfaceOp: 'append' })
+  }
+}
+
+const api = (ctx: Context) => createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+
+describe('session.history projections block', () => {
+  it('serves the unit value on the tail page with asOfSeq = last event seq', async () => {
+    const { ctx, session } = await harness(true)
+    ctx.sessionProjections.register(lastUserUnit())
+    seedMessages(session, 3)
+    const response = await api(ctx).sessions.history(request({ sessionId: session.id }))
+    expect(response.result.ok).toBe(true)
+    if (!response.result.ok) throw new Error('unreachable')
+    const { events, projections } = response.result.value
+    expect(projections).toBeDefined()
+    expect(projections?.asOfSeq).toBe(session.seq - 1)
+    expect(projections?.values['test/last-user']).toEqual({ text: 'm2' })
+    // asOfSeq IS the window tail: the last served event carries it.
+    expect(events.at(-1)?.event.seq).toBe(projections?.asOfSeq)
+  })
+
+  it('never carries the block on loadOlder pages (beforeSeq present)', async () => {
+    const { ctx, session } = await harness(true)
+    ctx.sessionProjections.register(lastUserUnit())
+    seedMessages(session, 5)
+    const older = await api(ctx).sessions.history(request({ sessionId: session.id, beforeSeq: 3, maxMessages: 2 }))
+    expect(older.result.ok).toBe(true)
+    if (!older.result.ok) throw new Error('unreachable')
+    expect('projections' in older.result.value).toBe(false)
+  })
+
+  it('serves no block when the composition has no projection registry', async () => {
+    const { ctx, session } = await harness(false)
+    seedMessages(session, 2)
+    const response = await api(ctx).sessions.history(request({ sessionId: session.id }))
+    expect(response.result.ok).toBe(true)
+    if (!response.result.ok) throw new Error('unreachable')
+    expect('projections' in response.result.value).toBe(false)
+  })
+
+  it('drops a disposed registration from subsequent tail pages (empty block, key absent)', async () => {
+    const { ctx, session } = await harness(true)
+    const dispose = ctx.sessionProjections.register(lastUserUnit())
+    seedMessages(session, 1)
+    const proxy = api(ctx)
+    const before = await proxy.sessions.history(request({ sessionId: session.id }))
+    if (!before.result.ok) throw new Error('unreachable')
+    expect(before.result.value.projections?.values['test/last-user']).toEqual({ text: 'm0' })
+
+    dispose()
+    const after = await proxy.sessions.history(request({ sessionId: session.id }))
+    if (!after.result.ok) throw new Error('unreachable')
+    // The registry is still mounted, so the block itself stays (asOfSeq cut
+    // with zero keys); the disposed key reads as capability absence.
+    expect(after.result.value.projections?.asOfSeq).toBe(session.seq - 1)
+    expect(after.result.value.projections?.values).toEqual({})
+  })
+})
+
+describe('session/projection push frame', () => {
+  /** Drain frames until `count` session/projection frames arrived. */
+  async function collect(iterable: AsyncIterable<RpcRequest<MuxFrame>>, count: number, abort: AbortController): Promise<MuxFrame[]> {
+    const frames: MuxFrame[] = []
+    for await (const envelope of iterable) {
+      frames.push(envelope.payload)
+      if (frames.filter(f => f.type === 'session/projection').length >= count) abort.abort()
+    }
+    return frames
+  }
+
+  it('broadcasts a frame per changed unit with the causing seq, and none for same-reference applies', async () => {
+    const { ctx, session } = await harness(true)
+    ctx.sessionProjections.register(lastUserUnit())
+    const proxy = api(ctx)
+    // The gateway's onChanged subscription lives in an inject child whose
+    // fiber activates asynchronously; yield until it lands before appending.
+    await new Promise(resolve => setTimeout(resolve, 0))
+    const abort = new AbortController()
+    const stream = proxy.events.mux({ rpcId: RpcId('t-proj-mux'), payload: {} }, abort.signal)
+    const collected = collect(stream, 2, abort)
+
+    seedMessages(session, 1)
+    // Same-reference apply: turn/start does not concern the unit — no frame.
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    seedMessages(session, 1)
+
+    const frames = await collected
+    const pushes = frames.filter(
+      (f): f is Extract<MuxFrame, { type: 'session/projection' }> => f.type === 'session/projection',
+    )
+    expect(pushes).toEqual([
+      { type: 'session/projection', sessionId: session.id, key: 'test/last-user', value: { text: 'm0' }, seq: 0 },
+      { type: 'session/projection', sessionId: session.id, key: 'test/last-user', value: { text: 'm0' }, seq: 2 },
+    ])
+    // Frame seq aligns with the tail block's asOfSeq vocabulary (higher-seq-wins compatible).
+    const tail = await proxy.sessions.history(request({ sessionId: session.id }))
+    if (!tail.result.ok) throw new Error('unreachable')
+    expect(tail.result.value.projections?.asOfSeq).toBe(pushes.at(-1)?.seq)
+  })
+
+  it('emits no projection frames when the composition has no registry', async () => {
+    const { ctx, session } = await harness(false)
+    const proxy = api(ctx)
+    const abort = new AbortController()
+    const stream = proxy.events.mux({ rpcId: RpcId('t-noproj-mux'), payload: {} }, abort.signal)
+    const frames: MuxFrame[] = []
+    const drained = (async () => {
+      for await (const envelope of stream) {
+        frames.push(envelope.payload)
+        if (frames.filter(f => f.type === 'session/event').length >= 2) abort.abort()
+      }
+    })()
+    seedMessages(session, 2)
+    await drained
+    expect(frames.some(f => f.type === 'session/projection')).toBe(false)
+  })
+})

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

@@ -1,8 +1,9 @@
 /**
  * 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
+ * arrive on the frame, a presenterless tool ships no view field, a call-only
+ * presenter keeps raw result content out of the view payload, 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.
  */
 
@@ -12,25 +13,26 @@ 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 from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
+import { CallId, createToolResultMessage } from '@deepseek-ai/dsh-llm'
 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 { Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
 import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 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'
+import { createApiProxy } from '@deepseek-ai/dsh-host-apiproxy'
 
 const reply = (text: string): Promise<ContentBlock[]> => Promise.resolve([{ type: 'text', text }])
 
 function tool(name: string, presenters: Pick<ToolDefinition, 'presentCall' | 'presentResult'>): ToolDefinition {
-  return {
+  return defineContentToolFixture({
     name,
     description: `tool ${name}`,
-    parameters: { type: 'object', properties: {} },
+    parameters: {},
     execute: () => reply(`ran:${name}`),
     ...presenters,
-  }
+  })
 }
 
 async function harness(): Promise<{ ctx: Context }> {
@@ -38,6 +40,7 @@ async function harness(): Promise<{ ctx: Context }> {
   await ctx.plugin(SessionStore)
   await ctx.plugin(SystemPrompt, { persona: '' })
   await ctx.plugin(ToolRegistry)
+  await ctx.plugin(UserInteractionService)
   await ctx.plugin(AgentRegistry)
   ctx.tools.register(tool('gen', {
     presentCall: () => ({ card: 'generic', title: 'gen call' }),
@@ -50,6 +53,9 @@ async function harness(): Promise<{ ctx: Context }> {
   ctx.tools.register(tool('diffy', {
     presentCall: () => ({ card: 'diff', title: 'Write f.txt', diffs: [{ path: 'f.txt', oldText: null, newText: 'x' }] }),
   }))
+  ctx.tools.register(tool('call-only', {
+    presentCall: () => ({ card: 'generic', title: 'program', kind: 'execute', rawInput: 'return value' }),
+  }))
   ctx.tools.register(tool('plain', {}))
   ctx.tools.register(tool('boom', {
     presentCall: () => { throw new Error('presenter exploded') },
@@ -70,29 +76,60 @@ async function collect(iterable: AsyncIterable<RpcRequest<MuxFrame>>, count: num
 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 api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
     const abort = new AbortController()
     const stream = api.events.mux({ rpcId: RpcId('t-mux'), payload: {} }, abort.signal)
-    const collected = collect(stream, 7, abort)
+    const collected = collect(stream, 9, abort)
+    const rawResult = `RAW_RESULT:${'x'.repeat(64 * 1024)}`
 
     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-call-only'), name: 'call-only', arguments: '{}' })
+    session.append('tool/result', {
+      turn: 1, step: 1,
+      message: createToolResultMessage({
+        callId: CallId('c-call-only'),
+        content: [{ type: 'text', text: rawResult }],
+        isError: false,
+      }),
+    }, { surfaceOp: 'append' })
     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' })
+    session.append('tool/result', {
+      turn: 1, step: 1,
+      message: createToolResultMessage({
+        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]))
+      .map(f => [
+        `${f.event.type}:${f.event.type === 'tool/call'
+          ? f.event.data.callId
+          : (f.event.data as SessionEvent<'tool/result'>['data']).message.source.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')
+    expect(byCall.get('tool/call:c-call-only')?.view).toEqual({
+      for: 'call',
+      view: { card: 'generic', title: 'program', kind: 'execute', rawInput: 'return value' },
+    })
+    const callOnlyResult = byCall.get('tool/result:c-call-only')
+    expect('view' in (callOnlyResult ?? {})).toBe(false)
+    const serializedResult = JSON.stringify(callOnlyResult)
+    expect(serializedResult.indexOf(rawResult)).toBeGreaterThanOrEqual(0)
+    expect(serializedResult.indexOf(rawResult)).toBe(serializedResult.lastIndexOf(rawResult))
     // 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.
@@ -104,7 +141,7 @@ describe('mux live view computation', () => {
 
   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 api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
     const session = ctx.sessions.create()
     // history resolves the agent first; a live structural stub is enough (only
     // .session is read on this path).
@@ -112,15 +149,44 @@ describe('mux live view computation', () => {
     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' })
+    session.append('tool/result', {
+      turn: 1, step: 1,
+      message: createToolResultMessage({
+        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' })
+    session.append('tool/result', {
+      turn: 1, step: 1,
+      message: createToolResultMessage({
+        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' })
+    session.append('tool/result', {
+      turn: 1, step: 1,
+      message: createToolResultMessage({
+        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' })
+    session.append('tool/result', {
+      turn: 1, step: 1,
+      message: createToolResultMessage({
+        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)
@@ -128,7 +194,12 @@ describe('mux live view computation', () => {
     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]))
+      .map(entry => [
+        `${entry.event.type}:${entry.event.type === 'tool/call'
+          ? entry.event.data.callId
+          : (entry.event.data as SessionEvent<'tool/result'>['data']).message.source.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)
@@ -138,7 +209,7 @@ describe('mux live view computation', () => {
 
   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 api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
     const abort = new AbortController()
     const stream = api.events.mux({ rpcId: RpcId('t-mux3'), payload: {} }, abort.signal)
 
@@ -159,7 +230,7 @@ describe('mux live view computation', () => {
 
   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 api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
     const abort = new AbortController()
     const stream = api.events.mux({ rpcId: RpcId('t-mux2'), payload: {} }, abort.signal)
     const collected = collect(stream, 4, abort)
@@ -170,7 +241,14 @@ describe('mux live view computation', () => {
     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' })
+    session.append('tool/result', {
+      turn: 1, step: 1,
+      message: createToolResultMessage({
+        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')

packages/host/apiproxy/tests/api-proxy-workspace.spec.ts

@@ -0,0 +1,355 @@
+import { existsSync, mkdirSync, mkdtempSync, realpathSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import AgentRegistry, {} from '@deepseek-ai/dsh-agent'
+import type { Agent, AgentFactory } from '@deepseek-ai/dsh-agent'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import type { Session } from '@deepseek-ai/dsh-session'
+import Storage from '@deepseek-ai/dsh-storage'
+import { DomainFacility } from '@deepseek-ai/dsh-storage-domain'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import WorkspaceRegistry from '@deepseek-ai/dsh-workspace'
+import type { HostFrame, WorkspaceId } 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 { createApiProxy } from '@deepseek-ai/dsh-host-apiproxy'
+import { MemoryStorageBackend } from '../../../storage/storage-domain/tests/helpers/memory-backend.ts'
+
+let nextRpc = 1
+
+function request<P>(payload: P): RpcRequest<P> {
+  return { rpcId: RpcId(`workspace-${String(nextRpc++)}`), payload }
+}
+
+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
+}
+
+async function nextHostFrame(
+  stream: AsyncIterator<RpcRequest<HostFrame>>,
+): Promise<RpcRequest<HostFrame>> {
+  const next = await stream.next()
+  if (next.done === true) throw new Error('Host stream ended before the expected increment')
+  return next.value
+}
+
+function stubAgent(session: Session): Agent {
+  return {
+    id: session.id,
+    options: {},
+    session,
+    status: 'idle',
+    acceptsNextStep: false,
+    ctx: new Context(),
+    followup: () => {},
+    steer: () => {},
+    inject: () => {},
+    send: () => {},
+    cancel() {},
+    whenIdle: () => Promise.resolve(),
+  }
+}
+
+/** Compose the API over real Session, Agent, Storage, Domain, and Workspace services. */
+async function harness(
+  workspaceRoot = realpathSync(mkdtempSync(join(tmpdir(), 'dsh-apiproxy-workspace-'))),
+  extras: {
+    pickDirectory?: (signal: AbortSignal) => Promise<string | null>
+    openPath?: (path: string, signal: AbortSignal) => Promise<void>
+  } = {},
+) {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(UserInteractionService)
+  await ctx.plugin(Storage)
+  ctx.storage.backend.register('memory', new MemoryStorageBackend())
+  const storageDomain = new DomainFacility(ctx, { backend: 'memory', routes: {} })
+  ctx.storage.mount('domain', storageDomain)
+  ctx.provide('storageDomain', storageDomain)
+  ctx.provide('sessionPersistence', { list: () => Promise.resolve([]) } as never)
+  await ctx.plugin(WorkspaceRegistry)
+
+  const factory: AgentFactory = {
+    async createAgent(_ownerCtx, options) {
+      const session = ctx.sessions.create(
+        options.sessionId,
+        options.meta === undefined ? {} : { meta: options.meta },
+      )
+      const agent = stubAgent(session)
+      const unregister = ctx.agents.register(agent)
+      return {
+        agent,
+        dispose: () => {
+          unregister()
+          return Promise.resolve()
+        },
+      }
+    },
+    async resume() {
+      throw new Error('test harness has no persisted sessions')
+    },
+  }
+  ctx.agents.setFactory(factory)
+  const api = createApiProxy(ctx, {
+    provider: 'test',
+    model: 'test-model',
+    cwd: workspaceRoot,
+    workspaceRoot,
+    ...extras.pickDirectory === undefined ? {} : { pickDirectory: extras.pickDirectory },
+    ...extras.openPath === undefined ? {} : { openPath: extras.openPath },
+  })
+  return { api, ctx, storageDomain, workspaceRoot }
+}
+
+describe('host.pickDirectory', () => {
+  it('returns a selected path or explicit cancellation from the injected native boundary', async () => {
+    const selected = await harness(undefined, { pickDirectory: async () => '/tmp/project' })
+    expect((await selected.api.host.pickDirectory(request({}), new AbortController().signal)).result)
+      .toEqual({ ok: true, value: { path: '/tmp/project' } })
+
+    const cancelled = await harness(undefined, { pickDirectory: async () => null })
+    expect((await cancelled.api.host.pickDirectory(request({}), new AbortController().signal)).result)
+      .toEqual({ ok: true, value: { path: null } })
+  })
+
+  it('propagates abort into the native boundary as a cancelled RPC error', async () => {
+    const { api } = await harness(undefined, {
+      pickDirectory: signal => new Promise((_resolve, reject) => {
+        signal.addEventListener('abort', () => { reject(new Error('aborted')) }, { once: true })
+      }),
+    })
+    const abort = new AbortController()
+    const pending = api.host.pickDirectory(request({}), abort.signal)
+    abort.abort()
+    expect((await pending).result).toMatchObject({ ok: false, error: { code: 'cancelled' } })
+  })
+})
+
+describe('host.openPath', () => {
+  it('opens through the injected native boundary', async () => {
+    const opened: string[] = []
+    const { api } = await harness(undefined, {
+      openPath: async (path) => { opened.push(path) },
+    })
+    expect((await api.host.openPath(request({ path: '/tmp/a.txt' }), new AbortController().signal)).result)
+      .toEqual({ ok: true, value: { opened: true } })
+    expect(opened).toEqual(['/tmp/a.txt'])
+  })
+
+  it('propagates abort into the native boundary as a cancelled RPC error', async () => {
+    const { api } = await harness(undefined, {
+      openPath: (_path, signal) => new Promise((_resolve, reject) => {
+        signal.addEventListener('abort', () => { reject(new Error('aborted')) }, { once: true })
+      }),
+    })
+    const abort = new AbortController()
+    const pending = api.host.openPath(request({ path: '/tmp/a.txt' }), abort.signal)
+    abort.abort()
+    expect((await pending).result).toMatchObject({ ok: false, error: { code: 'cancelled' } })
+  })
+})
+
+describe('workspace.create', () => {
+  it('serializes concurrent names and rejects the duplicate', async () => {
+    const { api, workspaceRoot } = await harness()
+    const responses = await Promise.all([
+      api.workspace.create(request({ name: 'alpha' })),
+      api.workspace.create(request({ name: 'alpha' })),
+    ])
+    const created = responses.find(response => response.result.ok)
+    const duplicate = responses.find(response => !response.result.ok)
+
+    expect(created).toBeDefined()
+    expect(expectOk(created!)).toMatchObject({
+      created: true,
+      workspace: { path: join(workspaceRoot, 'alpha'), title: 'alpha' },
+    })
+    expect(duplicate?.result).toMatchObject({
+      ok: false,
+      error: { code: 'workspace-name-conflict', details: { name: 'alpha' } },
+    })
+    expect(existsSync(join(workspaceRoot, 'alpha'))).toBe(true)
+  })
+
+  it('adopts only existing directories and rejects unsafe names', async () => {
+    const { api, workspaceRoot } = await harness()
+    const existing = join(workspaceRoot, 'existing')
+    mkdirSync(existing)
+    const first = expectOk(await api.workspace.create(request({ path: existing })))
+    const repeated = expectOk(await api.workspace.create(request({ path: existing })))
+    expect(first).toMatchObject({ created: true, workspace: { path: existing, title: 'existing' } })
+    expect(repeated).toMatchObject({ created: false, workspace: { workspaceId: first.workspace.workspaceId } })
+
+    expectOk(await api.workspace.rename(request({
+      workspaceId: first.workspace.workspaceId,
+      title: 'renamed-existing',
+    })))
+    const reopened = expectOk(await api.workspace.create(request({ path: existing })))
+    expect(reopened.workspace.title).toBe('renamed-existing')
+
+    const missing = join(workspaceRoot, 'missing')
+    const missingResult = await api.workspace.create(request({ path: missing }))
+    expect(missingResult.result).toMatchObject({ ok: false, error: { code: 'workspace-invalid-path' } })
+    expect(existsSync(missing)).toBe(false)
+
+    for (const name of ['', '.', '..', 'a/b', 'a\\b']) {
+      const invalid = await api.workspace.create(request({ name }))
+      expect(invalid.result).toMatchObject({ ok: false, error: { code: 'workspace-invalid-path' } })
+    }
+  })
+
+  it('rejects different paths that derive the same Workspace title', async () => {
+    const { api, workspaceRoot } = await harness()
+    const first = join(workspaceRoot, 'one', 'project')
+    const second = join(workspaceRoot, 'two', 'project')
+    mkdirSync(first, { recursive: true })
+    mkdirSync(second, { recursive: true })
+    expectOk(await api.workspace.create(request({ path: first })))
+    const conflict = await api.workspace.create(request({ path: second }))
+    expect(conflict.result).toMatchObject({
+      ok: false,
+      error: { code: 'workspace-name-conflict', details: { name: 'project' } },
+    })
+  })
+})
+
+describe('session creation and Workspace membership', () => {
+  it('attaches a preallocated idempotent session while cwd-only sessions stay ungrouped', async () => {
+    const { api, ctx } = await harness()
+    const workspace = expectOk(await api.workspace.create(request({ name: 'project' }))).workspace
+    const sessionId = SessionId('session-workspace-preallocated')
+
+    expectOk(await api.sessions.create(request({ workspaceId: workspace.workspaceId, sessionId })))
+    expectOk(await api.sessions.create(request({ workspaceId: workspace.workspaceId, sessionId })))
+    expect(expectOk(await api.workspace.list(request({}))).items[0]?.sessionIds).toEqual([sessionId])
+    expect(ctx.agents.list().filter(agent => agent.id === sessionId)).toHaveLength(1)
+
+    const ungrouped = SessionId('session-cwd-only')
+    expectOk(await api.sessions.create(request({ cwd: workspace.path, sessionId: ungrouped })))
+    expect(expectOk(await api.workspace.list(request({}))).items[0]?.sessionIds).toEqual([sessionId])
+    expect(expectOk(await api.sessions.list(request({}))).items.map(item => item.sessionId)).toContain(ungrouped)
+
+    const conflict = await api.sessions.create(request({ cwd: join(workspace.path, 'other'), sessionId }))
+    expect(conflict.result).toMatchObject({
+      ok: false,
+      error: { code: 'session-conflict', details: { sessionId, existingCwd: workspace.path } },
+    })
+    const missing = await api.sessions.create(request({
+      workspaceId: 'missing-workspace' as WorkspaceId,
+      sessionId: SessionId('session-missing-workspace'),
+    }))
+    expect(missing.result).toMatchObject({ ok: false, error: { code: 'workspace-not-found' } })
+  })
+
+  it('retains a published session when attachment fails and repairs it on retry', async () => {
+    const { api, ctx } = await harness()
+    const created = expectOk(await api.workspace.create(request({ name: 'project' }))).workspace
+    const workspace = ctx.workspace.list()[0]
+    if (workspace === undefined) throw new Error('workspace missing from registry')
+    vi.spyOn(workspace, 'attachSession').mockRejectedValueOnce(new Error('simulated write failure'))
+    const sessionId = SessionId('session-attach-retry')
+
+    const failed = await api.sessions.create(request({ workspaceId: created.workspaceId, sessionId }))
+    expect(failed.result).toMatchObject({
+      ok: false,
+      error: { code: 'workspace-attach-failed', details: { sessionId, workspaceId: created.workspaceId } },
+    })
+    expect(ctx.agents.get(sessionId)).toBeDefined()
+
+    expectOk(await api.sessions.create(request({ workspaceId: created.workspaceId, sessionId })))
+    expect(expectOk(await api.workspace.list(request({}))).items[0]?.sessionIds).toEqual([sessionId])
+  })
+})
+
+describe('Host Workspace increments', () => {
+  it('streams committed Workspace and Session increments after empty baselines', async () => {
+    const { api } = await harness()
+    expect(expectOk(await api.workspace.list(request({}))).items).toEqual([])
+    expect(expectOk(await api.sessions.list(request({}))).items).toEqual([])
+
+    const abort = new AbortController()
+    const stream: AsyncIterator<RpcRequest<HostFrame>> =
+      api.events.host(request({}), abort.signal)[Symbol.asyncIterator]()
+    const workspaceIncrement = nextHostFrame(stream)
+    const workspace = expectOk(await api.workspace.create(request({ name: 'project' }))).workspace
+    expect(await workspaceIncrement).toMatchObject({
+      payload: { type: 'host/workspace-changed', workspace: { workspaceId: workspace.workspaceId } },
+    })
+
+    const sessionId = SessionId('session-streamed-workspace')
+    const pending = nextHostFrame(stream)
+    expectOk(await api.sessions.create(request({ workspaceId: workspace.workspaceId, sessionId })))
+    const increments: HostFrame[] = []
+    increments.push((await pending).payload)
+    while (increments.length < 2) {
+      const next = await stream.next()
+      if (next.done === true) throw new Error('Host stream ended before both increments')
+      increments.push(next.value.payload)
+    }
+    expect(increments.find(increment => increment.type === 'host/session-added')).toMatchObject({
+      // A just-created session has no events: the frame constantly carries blank:true.
+      type: 'host/session-added', sessionId, blank: true, cwd: workspace.path,
+    })
+    const workspaceChanged = increments.find(
+      (increment): increment is Extract<HostFrame, { type: 'host/workspace-changed' }> =>
+        increment.type === 'host/workspace-changed',
+    )
+    expect(workspaceChanged?.workspace.sessionIds).toEqual([sessionId])
+    abort.abort()
+  })
+
+  it('does not publish a Workspace whose registry-order commit fails', async () => {
+    const { api, storageDomain } = await harness()
+    const domain = storageDomain.get('workspace')
+    if (domain === undefined) throw new Error('workspace domain is not open')
+    vi.spyOn(domain.global, 'set').mockRejectedValueOnce(new Error('simulated registry order failure'))
+    const abort = new AbortController()
+    const stream: AsyncIterator<RpcRequest<HostFrame>> =
+      api.events.host(request({}), abort.signal)[Symbol.asyncIterator]()
+    const next = stream.next()
+
+    const failed = await api.workspace.create(request({ name: 'ghost' }))
+    expect(failed.result.ok).toBe(false)
+    expect(expectOk(await api.workspace.list(request({}))).items).toEqual([])
+    abort.abort()
+    expect(await next).toMatchObject({ done: true })
+  })
+
+  it('deletes the registration, keeps its session and folder, and streams one removal', async () => {
+    const { api, ctx } = await harness()
+    const workspace = expectOk(await api.workspace.create(request({ name: 'delete-me' }))).workspace
+    const sessionId = SessionId('session-kept-after-workspace-delete')
+    expectOk(await api.sessions.create(request({ workspaceId: workspace.workspaceId, sessionId })))
+
+    const abort = new AbortController()
+    const stream: AsyncIterator<RpcRequest<HostFrame>> =
+      api.events.host(request({}), abort.signal)[Symbol.asyncIterator]()
+    const removed = nextHostFrame(stream)
+    expectOk(await api.workspace.delete(request({ workspaceId: workspace.workspaceId })))
+    expect(await removed).toMatchObject({
+      payload: { type: 'host/workspace-removed', workspaceId: workspace.workspaceId },
+    })
+    expect(expectOk(await api.workspace.list(request({}))).items).toEqual([])
+    expect(expectOk(await api.sessions.list(request({}))).items.map(item => item.sessionId)).toContain(sessionId)
+    expect(ctx.agents.get(sessionId)).toBeDefined()
+    expect(existsSync(workspace.path)).toBe(true)
+
+    const missing = await api.workspace.delete(request({ workspaceId: workspace.workspaceId }))
+    expect(missing.result).toMatchObject({
+      ok: false,
+      error: { code: 'workspace-not-found', details: { workspaceId: workspace.workspaceId } },
+    })
+
+    const reregistered = expectOk(await api.workspace.create(request({ path: workspace.path }))).workspace
+    expect(reregistered.workspaceId).not.toBe(workspace.workspaceId)
+    expect(reregistered.path).toBe(workspace.path)
+    expect(reregistered.sessionIds).toEqual([])
+    expect(expectOk(await api.sessions.list(request({}))).items.map(item => item.sessionId)).toContain(sessionId)
+    abort.abort()
+  })
+})

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

@@ -20,6 +20,8 @@ function ok<T>(request: RpcRequest<unknown>, value: T): Promise<RpcResponse<T>>
 function scriptedApi(overrides: {
   sessions?: Partial<ApiProxy['sessions']>
   host?: Partial<ApiProxy['host']>
+  commands?: Partial<ApiProxy['commands']>
+  skills?: Partial<ApiProxy['skills']>
   events?: Partial<ApiProxy['events']>
   goals?: Partial<ApiProxy['goals']>
   respond?: ApiProxy['respond']
@@ -31,14 +33,43 @@ function scriptedApi(overrides: {
     sessions: {
       list: r => ok(r, { items: [] }),
       create: r => ok(r, { sessionId: sid('s-new') }),
-      history: r => ok(r, { events: [], hasMore: false }),
+      history: r => ok(r, {
+        events: [],
+        hasMore: false,
+        modelTarget: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+      }),
+      models: r => ok(r, {
+        current: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+        groups: [],
+        failures: [],
+      }),
+      selectModel: r => ok(r, {
+        selected: { provider: r.payload.provider, model: r.payload.model },
+      }),
       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 },
+    host: {
+      describe: r => ok(r, { version: '0-test', cwd: '/t', attachedSessions: 0 }),
+      pickDirectory: r => ok(r, { path: null }),
+      openPath: r => ok(r, { opened: true as const }),
+      ...overrides.host,
+    },
+    workspace: {
+      list: r => ok(r, { items: [] }),
+      create: r => ok(r, { workspace: { workspaceId: 'w1' as never, path: '/t', title: 't', sessionIds: [], createdAt: '0', updatedAt: '0' }, created: true }),
+      rename: r => ok(r, { workspace: { workspaceId: 'w1' as never, path: '/t', title: 't', sessionIds: [], createdAt: '0', updatedAt: '0' } }),
+      delete: r => ok(r, { deleted: true as const }),
+      insertSessionBefore: r => ok(r, { workspace: { workspaceId: 'w1' as never, path: '/t', title: 't', sessionIds: [], createdAt: '0', updatedAt: '0' } }),
+    },
+    commands: {
+      list: r => ok(r, { commands: [] }),
+      execute: r => ok(r, { matched: false }),
+      ...overrides.commands,
+    },
+    skills: { list: r => ok(r, { skills: [] }), ...overrides.skills },
     goals: {
-      get: err,
       create: err,
       edit: err,
       pause: err,
@@ -63,7 +94,7 @@ describe('unary round trip', () => {
       sessions: {
         list: (r) => {
           seen = r
-          return ok(r, { items: [{ sessionId: sid('s1'), updatedAt: 7, running: false }] })
+          return ok(r, { items: [{ sessionId: sid('s1'), updatedAt: 7, running: false, blank: false }] })
         },
       },
     })
@@ -72,7 +103,22 @@ describe('unary round trip', () => {
     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 }] } })
+    expect(response.result).toEqual({ ok: true, value: { items: [{ sessionId: 's1', updatedAt: 7, running: false, blank: false }] } })
+  })
+
+  it('routes workspace rename, delete, and insertSessionBefore through the wire', async () => {
+    const api = scriptedApi()
+    const c = client(api)
+    const renamed = await c.workspace.rename({ workspaceId: 'w1' as never, title: 'next' })
+    expect(renamed.result.ok).toBe(true)
+    const blankTitle = await c.workspace.rename({ workspaceId: 'w1' as never, title: '   ' })
+    expect(blankTitle.result).toMatchObject({ ok: false, error: { code: 'bad-request' } })
+    const deleted = await c.workspace.delete({ workspaceId: 'w1' as never })
+    expect(deleted.result).toEqual({ ok: true, value: { deleted: true } })
+    const anchored = await c.workspace.insertSessionBefore({ workspaceId: 'w1' as never, sessionId: sid('s1'), beforeSessionId: sid('s2') })
+    expect(anchored.result.ok).toBe(true)
+    const appended = await c.workspace.insertSessionBefore({ workspaceId: 'w1' as never, sessionId: sid('s1') })
+    expect(appended.result.ok).toBe(true)
   })
 
   it('passes business errors through as 200 + err result, not a throw', async () => {
@@ -203,6 +249,23 @@ describe('unary round trip', () => {
   })
 })
 
+describe('workspace domain round trip', () => {
+  it('routes both workspace methods through their handler rows and value schemas', async () => {
+    const c = client(scriptedApi())
+    const list = await c.workspace.list({})
+    expect(list.result).toEqual({ ok: true, value: { items: [] } })
+    const created = await c.workspace.create({ path: '/t' })
+    expect(created.result.ok).toBe(true)
+    if (created.result.ok) expect(created.result.value.created).toBe(true)
+  })
+
+  it('rejects a create payload violating the exactly-one refine at the handler', async () => {
+    const response = await client(scriptedApi()).workspace.create({})
+    expect(response.result.ok).toBe(false)
+    if (!response.result.ok) expect(response.result.error.code).toBe('bad-request')
+  })
+})
+
 describe('SSE stream path', () => {
   it('yields frames in order and skips the comment preamble', async () => {
     const frames: MuxFrame[] = [
@@ -254,7 +317,7 @@ describe('SSE stream path', () => {
     const api = scriptedApi({
       events: {
         async *host(request): AsyncGenerator<RpcRequest<HostFrame>> {
-          yield { rpcId: RpcId(`p-${request.rpcId}`), payload: { type: 'host/session-added', sessionId: sid('s1') } }
+          yield { rpcId: RpcId(`p-${request.rpcId}`), payload: { type: 'host/session-added', sessionId: sid('s1'), blank: true } }
           throw new Error('impl died mid-stream')
         },
       },

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

@@ -1,3 +1,4 @@
+import { CommandId } from '@deepseek-ai/dsh-commands/brand'
 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'
@@ -25,11 +26,47 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
         return { rpcId: request.rpcId, result: { ok: true, value: { sessionId: 's-new' as never } } }
       },
       async history(request) {
+        if (request.payload.sessionId === ('with-projections' as never)) {
+          return {
+            rpcId: request.rpcId,
+            result: { ok: true, value: { events: [], hasMore: false, projections: { asOfSeq: 9, values: { todos: [{ content: 'current', status: 'in_progress' as const }] } } } },
+          }
+        }
         return {
           rpcId: request.rpcId,
           result: { ok: false, error: { code: 'session-not-found', message: 'nope', details: { sessionId: request.payload.sessionId } } },
         }
       },
+      async models(request) {
+        return {
+          rpcId: request.rpcId,
+          result: {
+            ok: true,
+            value: {
+              current: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+              groups: [],
+              failures: [],
+            },
+          },
+        }
+      },
+      async selectModel(request) {
+        return {
+          rpcId: request.rpcId,
+          result: {
+            ok: true,
+            value: {
+              selected: {
+                provider: request.payload.provider,
+                model: request.payload.model,
+                ...request.payload.reasoningEffort === undefined
+                  ? {}
+                  : { reasoningEffort: request.payload.reasoningEffort },
+              },
+            },
+          },
+        }
+      },
       async prompt(request) {
         return { rpcId: request.rpcId, result: { ok: true, value: { accepted: true as const } } }
       },
@@ -41,6 +78,62 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
       async describe(request) {
         return { rpcId: request.rpcId, result: { ok: true, value: { version: 'v', cwd: '/w', attachedSessions: 0 } } }
       },
+      async pickDirectory(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { path: null } } }
+      },
+      async openPath(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { opened: true as const } } }
+      },
+    },
+    workspace: {
+      async list(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { items: [] } } }
+      },
+      async create(request) {
+        return {
+          rpcId: request.rpcId,
+          result: { ok: true, value: { workspace: { workspaceId: 'w1' as never, path: '/w', title: 'w', sessionIds: [], createdAt: 't', updatedAt: 't' }, created: true } },
+        }
+      },
+      async rename(request) {
+        return {
+          rpcId: request.rpcId,
+          result: { ok: true, value: { workspace: { workspaceId: 'w1' as never, path: '/w', title: 'w', sessionIds: [], createdAt: 't', updatedAt: 't' } } },
+        }
+      },
+      async delete(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { deleted: true as const } } }
+      },
+      async insertSessionBefore(request) {
+        return {
+          rpcId: request.rpcId,
+          result: { ok: true, value: { workspace: { workspaceId: 'w1' as never, path: '/w', title: 'w', sessionIds: [], createdAt: 't', updatedAt: 't' } } },
+        }
+      },
+    },
+    commands: {
+      async list(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { commands: [{ name: 'plan', description: 'Toggle plan mode', input: { hint: 'on|off' } }] } } }
+      },
+      async execute(request, signal) {
+        if (request.payload.line === '/hang') {
+          // Cooperative hang: settles only through the carrier signal (sticky
+          // abort checked first — listeners never fire retroactively).
+          if (!signal.aborted) {
+            await new Promise<void>((resolve) => { signal.addEventListener('abort', () => { resolve() }, { once: true }) })
+          }
+          return { rpcId: request.rpcId, result: { ok: false, error: { code: 'cancelled', message: 'aborted', details: {} } } }
+        }
+        if (request.payload.line.startsWith('/plan')) {
+          return { rpcId: request.rpcId, result: { ok: true, value: { matched: true, commandId: CommandId('cmd-x') } } }
+        }
+        return { rpcId: request.rpcId, result: { ok: true, value: { matched: false } } }
+      },
+    },
+    skills: {
+      async list(request) {
+        return { rpcId: request.rpcId, result: { ok: true, value: { skills: [{ name: 'commit-helper', description: 'Git commits' }] } } }
+      },
     },
     goals: {
       async get(request) {
@@ -75,8 +168,8 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
   }
 }
 
-function client(api: ApiProxy = fakeApi()): InProcessApiClient {
-  return new InProcessApiClient(toFetchHandler(api))
+function client(api: ApiProxy = fakeApi(), timeoutMs?: number): InProcessApiClient {
+  return new InProcessApiClient(toFetchHandler(api), timeoutMs)
 }
 
 async function collect<F>(stream: AsyncIterable<RpcRequest<F>>): Promise<RpcRequest<F>[]> {
@@ -92,6 +185,16 @@ describe('unary round trip (handler ⇄ client, no network)', () => {
     expect(response.rpcId).toMatch(/[0-9a-f-]{36}/)
   })
 
+  it('carries the tail-page projections block through the wire schema (Zod must not strip it)', async () => {
+    const response = await client().sessions.history({ sessionId: 'with-projections' as never })
+    expect(response.result.ok).toBe(true)
+    if (response.result.ok) {
+      expect(response.result.value.projections).toEqual(
+        { asOfSeq: 9, values: { todos: [{ content: 'current', status: 'in_progress' }] } },
+      )
+    }
+  })
+
   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)
@@ -101,10 +204,99 @@ describe('unary round trip (handler ⇄ client, no network)', () => {
   it('covers create/prompt/cancel/describe passthrough', async () => {
     const c = client()
     expect((await c.sessions.create({})).result.ok).toBe(true)
+    expect((await c.sessions.models({ sessionId: 's' as never })).result.ok).toBe(true)
+    const selected = await c.sessions.selectModel({
+      sessionId: 's' as never,
+      provider: 'deepseek',
+      model: 'deepseek-v4-flash',
+      reasoningEffort: 'max',
+    })
+    expect(selected.result).toMatchObject({
+      ok: true,
+      value: {
+        selected: {
+          provider: 'deepseek',
+          model: 'deepseek-v4-flash',
+          reasoningEffort: 'max',
+        },
+      },
+    })
     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)
   })
+
+  it('round-trips the native picker without the default unary timeout', async () => {
+    const api = fakeApi()
+    api.host.pickDirectory = async (request) => {
+      await new Promise(resolve => setTimeout(resolve, 15))
+      return { rpcId: request.rpcId, result: { ok: true, value: { path: '/tmp/project' } } }
+    }
+    const response = await client(api, 1).host.pickDirectory({})
+    expect(response.result).toEqual({ ok: true, value: { path: '/tmp/project' } })
+  })
+
+  it('round-trips host.openPath through the wire form', async () => {
+    const api = fakeApi()
+    let opened: string | undefined
+    api.host.openPath = async (request) => {
+      opened = request.payload.path
+      return { rpcId: request.rpcId, result: { ok: true, value: { opened: true as const } } }
+    }
+    const response = await client(api).host.openPath({ path: '/tmp/a.txt' })
+    expect(opened).toBe('/tmp/a.txt')
+    expect(response.result).toEqual({ ok: true, value: { opened: true } })
+  })
+
+  it('round-trips command.list / command.execute / skill.list through the wire form', async () => {
+    const c = client()
+    const list = await c.commands.list({ sessionId: 's' as never })
+    expect(list.result).toEqual({ ok: true, value: { commands: [{ name: 'plan', description: 'Toggle plan mode', input: { hint: 'on|off' } }] } })
+    const hit = await c.commands.execute({ sessionId: 's' as never, line: '/plan off' })
+    expect(hit.result).toEqual({ ok: true, value: { matched: true, commandId: 'cmd-x' } })
+    const miss = await c.commands.execute({ sessionId: 's' as never, line: '/nope' })
+    expect(miss.result).toEqual({ ok: true, value: { matched: false } })
+    const skills = await c.skills.list({ sessionId: 's' as never })
+    expect(skills.result).toEqual({ ok: true, value: { skills: [{ name: 'commit-helper', description: 'Git commits' }] } })
+  })
+
+  it('propagates the carrier Request signal into command.execute', async () => {
+    const handler = toFetchHandler(fakeApi())
+    const controller = new AbortController()
+    const body = JSON.stringify({ type: 'client-request', rpcId: 'r-sig', method: 'command.execute', payload: { sessionId: 's', line: '/hang' } })
+    // The fake's /hang settles only when the invoke-level signal aborts: a
+    // completed response with the cancelled error proves req.signal reached it.
+    const pending = handler.fetch(new Request('http://x/api/command.execute', { method: 'POST', body, signal: controller.signal }))
+    controller.abort()
+    const response = await pending
+    const parsed = await response.json() as { rpcId: string; result: { ok: boolean; error?: { code: string } } }
+    expect(parsed.rpcId).toBe('r-sig')
+    expect(parsed.result.error?.code).toBe('cancelled')
+  })
+
+  it('propagates the carrier Request signal into host.pickDirectory', async () => {
+    const api = fakeApi()
+    api.host.pickDirectory = async (request, signal) => {
+      if (!signal.aborted) {
+        await new Promise<void>((resolve) => {
+          signal.addEventListener('abort', () => { resolve() }, { once: true })
+        })
+      }
+      return {
+        rpcId: request.rpcId,
+        result: { ok: false, error: { code: 'cancelled', message: 'aborted', details: {} } },
+      }
+    }
+    const handler = toFetchHandler(api)
+    const controller = new AbortController()
+    const body = JSON.stringify({ type: 'client-request', rpcId: 'r-picker', method: 'host.pickDirectory', payload: {} })
+    const pending = handler.fetch(new Request('http://x/api/host.pickDirectory', {
+      method: 'POST', body, signal: controller.signal,
+    }))
+    controller.abort()
+    const parsed = await (await pending).json() as { result: { error?: { code: string } } }
+    expect(parsed.result.error?.code).toBe('cancelled')
+  })
 })
 
 describe('handler carrier-layer statuses', () => {

packages/host/apiproxy/tests/native-directory-picker.spec.ts

@@ -0,0 +1,139 @@
+type ExecFileCallback = (
+  error: (Error & { code?: string | number }) | null,
+  stdout: string,
+  stderr: string,
+) => void
+type ExecFileMock = (
+  command: string,
+  args: readonly string[],
+  options: { encoding: string; signal: AbortSignal; windowsHide: boolean },
+  callback: ExecFileCallback,
+) => void
+
+const { execFileMock } = vi.hoisted(() => ({ execFileMock: vi.fn<ExecFileMock>() }))
+
+vi.mock('node:child_process', () => ({ execFile: execFileMock }))
+
+import { describe, expect, it, vi } from 'vitest'
+import { pickNativeDirectory, type DirectoryPickerRunner } from '../src/native-directory-picker.ts'
+
+function failure(code: string | number, stderr = ''): Error {
+  return Object.assign(new Error(`command failed: ${String(code)}`), { code, stderr })
+}
+
+const signal = () => new AbortController().signal
+
+describe('native directory picker', () => {
+  it('uses the macOS folder chooser and maps user cancellation to null', async () => {
+    const run = vi.fn<DirectoryPickerRunner>(async () => ({ stdout: '/Users/test/project/\n', stderr: '' }))
+    await expect(pickNativeDirectory(signal(), { platform: 'darwin', run })).resolves.toBe('/Users/test/project/')
+    expect(run).toHaveBeenCalledWith('osascript', expect.arrayContaining(['POSIX path of selectedFolder']), expect.any(AbortSignal))
+
+    run.mockRejectedValueOnce(failure(1, 'execution error: User canceled. (-128)'))
+    await expect(pickNativeDirectory(signal(), { platform: 'darwin', run })).resolves.toBeNull()
+
+    run.mockRejectedValueOnce(failure(2, 'permission denied'))
+    await expect(pickNativeDirectory(signal(), { platform: 'darwin', run })).rejects.toThrow('command failed')
+  })
+
+  it.each([
+    ['a primitive error', 'failed'],
+    ['an invalid code type', { code: true }],
+    ['a missing stderr property', { code: 1 }],
+    ['a non-string stderr property', { code: 1, stderr: 42 }],
+  ])('does not mistake %s for macOS cancellation', async (_label, reason) => {
+    const run = vi.fn<DirectoryPickerRunner>(async () => { throw reason })
+    await expect(pickNativeDirectory(signal(), { platform: 'darwin', run })).rejects.toBe(reason)
+  })
+
+  it('uses the Windows STA folder dialog and maps empty output to cancellation', async () => {
+    const run = vi.fn<DirectoryPickerRunner>(async () => ({ stdout: 'C:\\work\\project\r\n', stderr: '' }))
+    await expect(pickNativeDirectory(signal(), { platform: 'win32', run })).resolves.toBe('C:\\work\\project')
+    expect(run).toHaveBeenCalledWith(
+      'powershell.exe',
+      expect.arrayContaining(['-NoProfile', '-STA', '-Command']),
+      expect.any(AbortSignal),
+    )
+    expect(run.mock.calls[0]?.[1].at(-1)).toContain("$ErrorActionPreference = 'Stop'")
+    run.mockResolvedValueOnce({ stdout: '', stderr: '' })
+    await expect(pickNativeDirectory(signal(), { platform: 'win32', run })).resolves.toBeNull()
+    run.mockRejectedValueOnce(failure(1, 'Add-Type failed'))
+    await expect(pickNativeDirectory(signal(), { platform: 'win32', run })).rejects.toThrow('command failed')
+  })
+
+  it('runs the default command adapter without a shell and preserves command failures', async () => {
+    execFileMock.mockImplementationOnce((_command, _args, _options, callback) => {
+      callback(null, 'C:\\work\\default\r\n', '')
+    })
+    await expect(pickNativeDirectory(signal(), { platform: 'win32' })).resolves.toBe('C:\\work\\default')
+    const [command, args, options] = execFileMock.mock.calls[0]!
+    expect(command).toBe('powershell.exe')
+    expect(args).toEqual(expect.arrayContaining(['-NoProfile', '-STA', '-Command']))
+    expect(options.encoding).toBe('utf8')
+    expect(options.windowsHide).toBe(true)
+    expect(options.signal).toBeInstanceOf(AbortSignal)
+
+    const commandError = Object.assign(new Error('powershell failed'), { code: 7 })
+    execFileMock.mockImplementationOnce((_command, _args, _options, callback) => {
+      callback(commandError, 'partial output', 'failure details')
+    })
+    await expect(pickNativeDirectory(signal(), { platform: 'win32' })).rejects.toMatchObject({
+      message: 'powershell failed', cause: commandError, code: 7,
+      stdout: 'partial output', stderr: 'failure details',
+    })
+  })
+
+  it('uses the current process platform when no platform override is supplied', async () => {
+    const run = vi.fn<DirectoryPickerRunner>(async () => ({ stdout: '/default/platform\n', stderr: '' }))
+    await expect(pickNativeDirectory(signal(), { run })).resolves.toBe('/default/platform')
+  })
+
+  it('uses Zenity on Linux and falls back to KDialog only when Zenity is missing', async () => {
+    const run = vi.fn<DirectoryPickerRunner>()
+      .mockRejectedValueOnce(failure('ENOENT'))
+      .mockResolvedValueOnce({ stdout: '/home/test/project\n', stderr: '' })
+    await expect(pickNativeDirectory(signal(), { platform: 'linux', run })).resolves.toBe('/home/test/project')
+    expect(run.mock.calls.map(call => call[0])).toEqual(['zenity', 'kdialog'])
+
+    const zenity = vi.fn<DirectoryPickerRunner>(async () => ({ stdout: '/home/test/direct\n', stderr: '' }))
+    await expect(pickNativeDirectory(signal(), { platform: 'linux', run: zenity }))
+      .resolves.toBe('/home/test/direct')
+    expect(zenity).toHaveBeenCalledOnce()
+  })
+
+  it('maps Linux cancellation to null and reports a missing desktop picker', async () => {
+    const cancelled = vi.fn<DirectoryPickerRunner>(async () => { throw failure(1) })
+    await expect(pickNativeDirectory(signal(), { platform: 'linux', run: cancelled })).resolves.toBeNull()
+
+    const missing = vi.fn<DirectoryPickerRunner>(async () => { throw failure('ENOENT') })
+    await expect(pickNativeDirectory(signal(), { platform: 'linux', run: missing }))
+      .rejects.toThrow('install zenity or kdialog')
+
+    const kdialogCancelled = vi.fn<DirectoryPickerRunner>()
+      .mockRejectedValueOnce(failure('ENOENT'))
+      .mockRejectedValueOnce(failure(1))
+    await expect(pickNativeDirectory(signal(), { platform: 'linux', run: kdialogCancelled }))
+      .resolves.toBeNull()
+
+    const zenityFailed = vi.fn<DirectoryPickerRunner>(async () => { throw failure(2) })
+    await expect(pickNativeDirectory(signal(), { platform: 'linux', run: zenityFailed }))
+      .rejects.toThrow('command failed')
+
+    const kdialogFailed = vi.fn<DirectoryPickerRunner>()
+      .mockRejectedValueOnce(failure('ENOENT'))
+      .mockRejectedValueOnce(failure(2))
+    await expect(pickNativeDirectory(signal(), { platform: 'linux', run: kdialogFailed }))
+      .rejects.toThrow('command failed')
+  })
+
+  it('does not convert caller aborts into user cancellation', async () => {
+    const abort = new AbortController()
+    abort.abort(new Error('closed'))
+    const run = vi.fn<DirectoryPickerRunner>(async () => { throw failure('ABORT_ERR') })
+    await expect(pickNativeDirectory(abort.signal, { platform: 'linux', run })).rejects.toThrow('command failed')
+  })
+
+  it('reports unsupported platforms', async () => {
+    await expect(pickNativeDirectory(signal(), { platform: 'aix' })).rejects.toThrow('unsupported on aix')
+  })
+})

packages/host/apiproxy/tests/native-path-opener.spec.ts

@@ -0,0 +1,82 @@
+type ExecFileCallback = (
+  error: (Error & { code?: string | number }) | null,
+  stdout: string,
+  stderr: string,
+) => void
+type ExecFileMock = (
+  command: string,
+  args: readonly string[],
+  options: { encoding: string; signal: AbortSignal; windowsHide: boolean },
+  callback: ExecFileCallback,
+) => void
+
+const { execFileMock } = vi.hoisted(() => ({ execFileMock: vi.fn<ExecFileMock>() }))
+
+vi.mock('node:child_process', () => ({ execFile: execFileMock }))
+
+import { describe, expect, it, vi } from 'vitest'
+import { openNativePath, type PathOpenerRunner } from '../src/native-path-opener.ts'
+
+const signal = () => new AbortController().signal
+
+describe('native path opener', () => {
+  it('opens with macOS open(1)', async () => {
+    const run = vi.fn<PathOpenerRunner>(async () => ({ stdout: '', stderr: '' }))
+    await openNativePath('/Users/test/file.txt', signal(), { platform: 'darwin', run })
+    expect(run).toHaveBeenCalledWith('open', ['/Users/test/file.txt'], expect.any(AbortSignal))
+  })
+
+  it('opens with Windows Invoke-Item and escapes single quotes', async () => {
+    const run = vi.fn<PathOpenerRunner>(async () => ({ stdout: '', stderr: '' }))
+    await openNativePath("C:\\work\\o'reilly.txt", signal(), { platform: 'win32', run })
+    expect(run).toHaveBeenCalledWith(
+      'powershell.exe',
+      ['-NoProfile', '-Command', "Invoke-Item -LiteralPath 'C:\\work\\o''reilly.txt'"],
+      expect.any(AbortSignal),
+    )
+  })
+
+  it('opens with Linux xdg-open', async () => {
+    const run = vi.fn<PathOpenerRunner>(async () => ({ stdout: '', stderr: '' }))
+    await openNativePath('/tmp/a.txt', signal(), { platform: 'linux', run })
+    expect(run).toHaveBeenCalledWith('xdg-open', ['/tmp/a.txt'], expect.any(AbortSignal))
+  })
+
+  it('rejects unsupported platforms', async () => {
+    await expect(openNativePath('/x', signal(), { platform: 'freebsd' as NodeJS.Platform }))
+      .rejects.toThrow('unsupported on freebsd')
+  })
+
+  it('uses the current process platform when no platform override is supplied', async () => {
+    const run = vi.fn<PathOpenerRunner>(async () => ({ stdout: '', stderr: '' }))
+    await openNativePath('/tmp/platform-default.txt', signal(), { run })
+    const expected = process.platform === 'win32'
+      ? 'powershell.exe'
+      : process.platform === 'linux'
+        ? 'xdg-open'
+        : 'open'
+    expect(run.mock.calls[0]?.[0]).toBe(expected)
+  })
+
+  it('runs the default command adapter without a shell and preserves command failures', async () => {
+    execFileMock.mockImplementationOnce((_command, _args, _options, callback) => {
+      callback(null, '', '')
+    })
+    await openNativePath('/tmp/default.txt', signal(), { platform: 'darwin' })
+    const [command, args, options] = execFileMock.mock.calls[0]!
+    expect(command).toBe('open')
+    expect(args).toEqual(['/tmp/default.txt'])
+    expect(options.encoding).toBe('utf8')
+    expect(options.windowsHide).toBe(true)
+    expect(options.signal).toBeInstanceOf(AbortSignal)
+
+    const commandError = Object.assign(new Error('open failed'), { code: 1 })
+    execFileMock.mockImplementationOnce((_command, _args, _options, callback) => {
+      callback(commandError, 'partial output', 'failure details')
+    })
+    await expect(openNativePath('/tmp/missing.txt', signal(), { platform: 'darwin' })).rejects.toMatchObject({
+      message: 'open failed', cause: commandError, code: 1,
+      stdout: 'partial output', stderr: 'failure details',
+    })
+  })
+})

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { RpcId } from '../src/api/rpc.ts'
+import { RpcId, transportError } from '../src/api/rpc.ts'
 import {
   clientRequestSchema, clientResponseSchema, rpcErrorSchema, rpcIdSchema, rpcMessageSchema,
   rpcReceiptSchema, rpcResultSchema, serverRequestSchema, serverResponseSchema,
@@ -8,10 +8,23 @@ import { z } from 'zod'
 import {
   contentBlockSchema, sessionCancelRequestSchema, sessionCancelValueSchema, sessionCreateRequestSchema,
   sessionCreateValueSchema, sessionEventSchema, sessionHistoryRequestSchema, sessionHistoryValueSchema,
-  sessionIdSchema, sessionListRequestSchema, sessionListValueSchema, sessionPromptRequestSchema,
-  sessionPromptValueSchema, sessionSummarySchema,
+  sessionIdSchema, sessionListRequestSchema, sessionListValueSchema, sessionModelsRequestSchema,
+  sessionModelsValueSchema, sessionPromptRequestSchema, sessionPromptValueSchema,
+  sessionSelectModelRequestSchema, sessionSelectModelValueSchema, sessionSummarySchema,
 } from '../src/api/sessions.schema.ts'
 import { hostDescribeRequestSchema, hostDescribeValueSchema } from '../src/api/host.schema.ts'
+import {
+  workspaceCreateRequestSchema, workspaceCreateValueSchema, workspaceIdSchema,
+  workspaceDeleteRequestSchema, workspaceDeleteValueSchema,
+  workspaceInsertSessionBeforeRequestSchema, workspaceInsertSessionBeforeValueSchema,
+  workspaceListRequestSchema, workspaceListValueSchema,
+  workspaceRenameRequestSchema, workspaceRenameValueSchema, workspaceViewSchema,
+} from '../src/api/workspace.schema.ts'
+import {
+  commandDescriptorSchema, commandExecuteRequestSchema, commandExecuteValueSchema,
+  commandListRequestSchema, commandListValueSchema,
+} from '../src/api/commands.schema.ts'
+import { skillEntrySchema, skillListRequestSchema, skillListValueSchema } from '../src/api/skills.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'
@@ -27,10 +40,29 @@ describe('RpcId', () => {
   })
 })
 
+describe('transportError', () => {
+  it('folds Error and non-Error throws into the internal error branch', () => {
+    expect(transportError(new Error('wire down'))).toEqual({ ok: false, error: { code: 'internal', message: 'wire down', details: {} } })
+    expect(transportError('raw')).toMatchObject({ ok: false, error: { code: 'internal', message: 'raw' } })
+  })
+})
+
 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: 'cancelled', message: 'm', details: {} }).code).toBe('cancelled')
     expect(rpcErrorSchema.parse({ code: 'session-not-found', message: 'm', details: { sessionId: 's' } }).code).toBe('session-not-found')
+    expect(rpcErrorSchema.parse({ code: 'session-conflict', message: 'm', details: { sessionId: 's', requestedCwd: '/a', existingCwd: '/b' } }).code).toBe('session-conflict')
+    expect(rpcErrorSchema.parse({ code: 'workspace-attach-failed', message: 'm', details: { sessionId: 's', workspaceId: 'w' } }).code).toBe('workspace-attach-failed')
+    expect(rpcErrorSchema.parse({ code: 'workspace-not-found', message: 'm', details: { workspaceId: 'w' } }).code).toBe('workspace-not-found')
+    expect(rpcErrorSchema.parse({ code: 'workspace-invalid-path', message: 'm', details: { path: '/x' } }).code).toBe('workspace-invalid-path')
+    expect(rpcErrorSchema.parse({ code: 'workspace-name-conflict', message: 'm', details: { name: 'x' } }).code).toBe('workspace-name-conflict')
+    expect(rpcErrorSchema.parse({ code: 'workspace-move-invalid', message: 'm', details: { workspaceId: 'w', sessionId: 's' } }).code).toBe('workspace-move-invalid')
+    expect(rpcErrorSchema.parse({
+      code: 'model-unavailable',
+      message: 'm',
+      details: { provider: 'p', model: 'm' },
+    }).code).toBe('model-unavailable')
     expect(rpcErrorSchema.parse({ code: 'agent-busy', message: 'm', details: { reason: 'r' } }).code).toBe('agent-busy')
     expect(rpcErrorSchema.parse({ code: 'command-error', message: 'm', details: {} }).code).toBe('command-error')
     expect(rpcErrorSchema.parse({ code: 'unknown-command', message: 'm', details: {} }).code).toBe('unknown-command')
@@ -87,11 +119,23 @@ 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(sessionSummarySchema.parse({ sessionId: 's1', updatedAt: 1, running: false, blank: true })).toMatchObject({ sessionId: 's1', blank: true })
+    expect(sessionSummarySchema.parse({ sessionId: 's1', updatedAt: 1, running: true, blank: false, parentSessionId: 'p', cwd: '/x' }).cwd).toBe('/x')
+    // blank is mandatory: a summary without it fails the parse.
+    expect(() => sessionSummarySchema.parse({ sessionId: 's1', updatedAt: 1, running: false })).toThrow()
+    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()
+    expect(() => sessionEventSchema.parse({
+      type: 'user/message',
+      seq: -1,
+      time: 1,
+      data: {},
+    })).toThrow()
   })
 
   it('validates the per-method request/value pairs', () => {
@@ -99,10 +143,68 @@ describe('sessions domain schemas', () => {
     expect(sessionListRequestSchema.parse({ cursor: 'c' }).cursor).toBe('c')
     expect(sessionListValueSchema.parse({ items: [] }).items).toEqual([])
     expect(sessionCreateRequestSchema.parse({ cwd: '/w' }).cwd).toBe('/w')
+    // The refine's both-sides branch: workspaceId alone passes, workspaceId+cwd rejects.
+    expect(sessionCreateRequestSchema.parse({ workspaceId: 'w1', sessionId: 's1' }).sessionId).toBe('s1')
+    expect(() => sessionCreateRequestSchema.parse({ workspaceId: 'w1', cwd: '/w' })).toThrow(/not both/)
     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)
+    expect(sessionHistoryValueSchema.parse({
+      events: [],
+      hasMore: false,
+      modelTarget: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+    }).hasMore).toBe(false)
+    expect(sessionModelsRequestSchema.parse({ sessionId: 's1' }).sessionId).toBe('s1')
+    expect(sessionModelsValueSchema.parse({
+      current: { provider: 'deepseek', model: 'deepseek-v4-flash', reasoningEffort: 'max' },
+      groups: [{
+        id: 'deepseek',
+        name: 'DeepSeek',
+        models: [{
+          id: 'deepseek-v4-flash',
+          name: 'DeepSeek V4 Flash',
+          description: 'fast',
+          unlisted: true,
+          reasoning: {
+            efforts: [
+              { id: 'off', name: 'Off' },
+              { id: 'max', name: 'Max', description: 'Largest budget' },
+            ],
+            defaultEffort: 'off',
+          },
+        }],
+      }],
+      failures: [{ id: 'broken', name: 'Broken', message: 'offline' }],
+    }).groups[0]?.models[0]?.id).toBe('deepseek-v4-flash')
+    expect(sessionSelectModelRequestSchema.parse({
+      sessionId: 's1',
+      provider: 'deepseek',
+      model: 'deepseek-v4-pro',
+      reasoningEffort: 'max',
+    }).reasoningEffort).toBe('max')
+    expect(sessionSelectModelValueSchema.parse({
+      selected: { provider: 'deepseek', model: 'deepseek-v4-pro', reasoningEffort: 'max' },
+    }).selected.reasoningEffort).toBe('max')
+    expect(() => sessionSelectModelRequestSchema.parse({
+      sessionId: 's1',
+      provider: '',
+      model: 'm',
+    })).toThrow()
+    expect(() => sessionSelectModelRequestSchema.parse({
+      sessionId: 's1',
+      provider: 'deepseek',
+      model: 'm',
+      reasoningEffort: '',
+    })).toThrow()
+    expect(() => sessionModelsValueSchema.parse({
+      current: { provider: 'deepseek', model: 'm' },
+      groups: [{
+        id: 'deepseek',
+        name: 'DeepSeek',
+        models: [{ id: 'm', name: 'M', reasoning: { efforts: [] } }],
+      }],
+      failures: [],
+    })).toThrow()
     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()
@@ -127,6 +229,98 @@ describe('host domain schemas', () => {
   })
 })
 
+describe('workspace domain schemas', () => {
+  const view = {
+    workspaceId: 'w1', path: '/p', title: 'p', sessionIds: ['s1'],
+    createdAt: '2026-07-25T00:00:00.000Z', updatedAt: '2026-07-25T00:00:00.000Z',
+  }
+
+  it('validates ids, the view row, and list request/value', () => {
+    expect(workspaceIdSchema.parse('w1')).toBe('w1')
+    expect(() => workspaceIdSchema.parse('')).toThrow()
+    expect(workspaceViewSchema.parse(view).sessionIds).toEqual(['s1'])
+    expect(() => workspaceViewSchema.parse({ ...view, sessionIds: 's1' })).toThrow()
+    expect(workspaceListRequestSchema.parse({})).toEqual({})
+    expect(workspaceListValueSchema.parse({ items: [view] }).items).toHaveLength(1)
+  })
+
+  it('create requires exactly one of path/name (both refine arms)', () => {
+    expect(workspaceCreateRequestSchema.parse({ path: '/p' }).path).toBe('/p')
+    expect(workspaceCreateRequestSchema.parse({ name: 'n' }).name).toBe('n')
+    expect(() => workspaceCreateRequestSchema.parse({})).toThrow(/exactly one/)
+    expect(() => workspaceCreateRequestSchema.parse({ path: '/p', name: 'n' })).toThrow(/exactly one/)
+    expect(workspaceCreateValueSchema.parse({ workspace: view, created: false }).created).toBe(false)
+  })
+
+  it('rename requires a non-blank title (both refine arms)', () => {
+    expect(workspaceRenameRequestSchema.parse({ workspaceId: 'w1', title: 'new' }).title).toBe('new')
+    expect(() => workspaceRenameRequestSchema.parse({ workspaceId: 'w1', title: '  ' })).toThrow(/non-blank/)
+    expect(workspaceRenameValueSchema.parse({ workspace: view }).workspace.workspaceId).toBe('w1')
+  })
+
+  it('validates workspace deletion payload and receipt', () => {
+    expect(workspaceDeleteRequestSchema.parse({ workspaceId: 'w1' }).workspaceId).toBe('w1')
+    expect(() => workspaceDeleteRequestSchema.parse({})).toThrow()
+    expect(workspaceDeleteValueSchema.parse({ deleted: true })).toEqual({ deleted: true })
+    expect(() => workspaceDeleteValueSchema.parse({ deleted: false })).toThrow()
+  })
+
+  it('insertSessionBefore accepts an anchored and an anchorless move', () => {
+    expect(workspaceInsertSessionBeforeRequestSchema.parse({ workspaceId: 'w1', sessionId: 's1', beforeSessionId: 's2' }).beforeSessionId).toBe('s2')
+    expect(workspaceInsertSessionBeforeRequestSchema.parse({ workspaceId: 'w1', sessionId: 's1' }).beforeSessionId).toBeUndefined()
+    expect(() => workspaceInsertSessionBeforeRequestSchema.parse({ workspaceId: 'w1' })).toThrow()
+    expect(workspaceInsertSessionBeforeValueSchema.parse({ workspace: view }).workspace.workspaceId).toBe('w1')
+  })
+})
+
+describe('commands domain schemas', () => {
+  it('validates the catalog request/value pair', () => {
+    expect(commandListRequestSchema.parse({ sessionId: 's1' }).sessionId).toBe('s1')
+    // The wire is session-addressed only: a sessionId-less payload fails.
+    expect(() => commandListRequestSchema.parse({})).toThrow()
+    expect(commandListValueSchema.parse({ commands: [] }).commands).toEqual([])
+    const value = commandListValueSchema.parse({ commands: [
+      { name: 'plan', description: 'Toggle plan mode' },
+      { name: 'goal', description: 'Set the goal', input: { hint: '<goal>' } },
+    ] })
+    expect(value.commands[1]?.input?.hint).toBe('<goal>')
+    expect(commandDescriptorSchema.parse({ name: 'x', description: 'd' }).input).toBeUndefined()
+    expect(() => commandDescriptorSchema.parse({ name: '', description: 'd' })).toThrow()
+    expect(() => commandDescriptorSchema.parse({ name: 'x', description: 'd', input: {} })).toThrow()
+  })
+
+  it('validates the execute request/value pair with both matched branches', () => {
+    expect(commandExecuteRequestSchema.parse({ sessionId: 's1', line: '/plan off' }).line).toBe('/plan off')
+    // Both members are mandatory: dropping either fails the parse.
+    expect(() => commandExecuteRequestSchema.parse({ line: '/compact' })).toThrow()
+    expect(() => commandExecuteRequestSchema.parse({ sessionId: 's1' })).toThrow()
+    expect(commandExecuteValueSchema.parse({ matched: false })).toEqual({ matched: false })
+    // Pure admission: matched plus the optional lifecycle pairing id
+    // (outcomes ride the logged lifecycle events, never this response).
+    expect(commandExecuteValueSchema.parse({ matched: true, commandId: 'cmd-1' }))
+      .toEqual({ matched: true, commandId: 'cmd-1' })
+    expect(commandExecuteValueSchema.parse({ matched: true })).toEqual({ matched: true })
+    expect(() => commandExecuteValueSchema.parse({ matched: true, commandId: '' })).toThrow()
+    expect(() => commandExecuteValueSchema.parse({})).toThrow()
+  })
+})
+
+describe('skills domain schemas', () => {
+  it('validates the list request/value pair', () => {
+    expect(skillListRequestSchema.parse({ sessionId: 's1' })).toEqual({ sessionId: 's1' })
+    // The wire is session-addressed only: a sessionId-less payload fails.
+    expect(() => skillListRequestSchema.parse({})).toThrow()
+    expect(skillListValueSchema.parse({ skills: [] }).skills).toEqual([])
+    const value = skillListValueSchema.parse({ skills: [
+      { name: 'commit-helper', description: 'Git commits', whenToUse: 'when committing' },
+      { name: 'bare', description: 'No guidance' },
+    ] })
+    expect(value.skills[0]?.whenToUse).toBe('when committing')
+    expect(value.skills[1]?.whenToUse).toBeUndefined()
+    expect(() => skillEntrySchema.parse({ name: '', description: 'd' })).toThrow()
+  })
+})
+
 describe('goals domain schemas', () => {
   it('requires at least one replacement field for goal.edit', () => {
     const ref = { id: 'g1', revision: 1 }
@@ -145,20 +339,44 @@ describe('events frame schemas', () => {
       { 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: 'session/queued', sessionId: 's', message: { id: 'm1', role: 'user', content: [{ type: 'text', text: 'queued prompt' }], source: { kind: 'user', rpcId: 'r9' } }, steering: false },
+      { type: 'session/queued', sessionId: 's', message: { id: 'm2', role: 'user', content: [{ type: 'text', text: 'steer' }], source: { kind: 'user' } }, steering: true },
+      { type: 'session/projection', sessionId: 's', key: 'todos', value: [{ content: 'x', status: 'pending' }], seq: 7 },
       { 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()
+    for (const invalid of [
+      { type: 'session/projection', sessionId: 's', key: '', value: null, seq: 0 },
+      { type: 'session/projection', sessionId: 's', key: 'todos', value: null, seq: -1 },
+      { type: 'session/projection', sessionId: 's', key: 'todos', value: null, seq: 0.5 },
+    ]) expect(() => muxFrameSchema.parse(invalid)).toThrow()
     expect(askUserQuestionItemSchema.parse({ id: 'q', question: 'Q?' }).id).toBe('q')
   })
 
+  it('rejects an empty question batch (ask() guarantees at least one, so an empty frame is host breakage)', () => {
+    expect(() => muxFrameSchema.parse({ type: 'question/requested', sessionId: 's', questions: [] })).toThrow()
+  })
+
+  it('rejects a queued frame missing its members', () => {
+    expect(() => muxFrameSchema.parse({ type: 'session/queued', sessionId: 's', message: 'x', steering: false })).toThrow()
+    expect(() => muxFrameSchema.parse({ type: 'session/queued', sessionId: 's', message: { id: 'm', role: 'user', content: [], source: { kind: 'user' } } })).toThrow()
+    expect(() => muxFrameSchema.parse({ type: 'session/queued', sessionId: 's', message: { id: 'm', role: 'user', content: [], source: {} }, steering: false })).toThrow()
+  })
+
   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-added', sessionId: 's', blank: true, parentSessionId: 'p' },
+      { type: 'host/session-added', sessionId: 's', blank: true },
       { type: 'host/session-removed', sessionId: 's' },
       { type: 'host/session-status', sessionId: 's', running: true },
       { type: 'host/agent-error', sessionId: 's', message: 'boom' },
+      { type: 'host/workspace-changed', workspace: {
+        workspaceId: 'w', path: '/w', title: 'w', sessionIds: [],
+        createdAt: '0', updatedAt: '0',
+      } },
+      { type: 'host/workspace-removed', workspaceId: 'w' },
+      { type: 'host/commands-changed' },
       { type: 'stream/error', error: { code: 'internal', message: 'm', details: {} } },
     ]
     for (const frame of frames) expect(hostFrameSchema.parse(frame)).toMatchObject({ type: frame.type })

packages/host/apiproxy/tsconfig.json

@@ -8,24 +8,48 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
     {
       "path": "../../util/brand"
     },
     {
       "path": "../../llm/llm"
     },
+    {
+      "path": "../../core/agent"
+    },
     {
       "path": "../../core/session"
     },
     {
       "path": "../../core/tools"
     },
+    {
+      "path": "../../session-persistence/session-persistence"
+    },
+    {
+      "path": "../../session-projection/session-projection"
+    },
+    {
+      "path": "../../skill/skill"
+    },
+    {
+      "path": "../../ui/commands"
+    },
     {
       "path": "../../ui/user-approval"
     },
     {
       "path": "../../ui/user-interaction"
     },
+    {
+      "path": "../../workspace/workspace"
+    },
     {
       "path": "../../support/invariants"
     }

packages/host/runtime/README.md

@@ -1,31 +0,0 @@
-# @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

@@ -1,86 +0,0 @@
-{
-  "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-command-goal": "workspace:^",
-    "@deepseek-ai/dsh-commands": "workspace:^",
-    "@deepseek-ai/dsh-compact-basic": "workspace:^",
-    "@deepseek-ai/dsh-goal": "workspace:^",
-    "@deepseek-ai/dsh-goal-session": "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

@@ -1,547 +0,0 @@
-/**
- * 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 { Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
-import type {} from '@deepseek-ai/dsh-commands'
-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 { GoalView } from '@deepseek-ai/dsh-host-apiproxy/api'
-import type { GoalView as CoreGoalView } from '@deepseek-ai/dsh-goal'
-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 }
-}
-
-/**
- * Slash-command candidate: the web composer sends exactly one text block, so
- * only that exact shape dispatches; multi-block content is never flattened.
- */
-function commandCandidate(content: ContentBlock[]): string | undefined {
-  const [first, ...rest] = content
-  if (first === undefined || rest.length > 0) return undefined
-  if (first.type !== 'text' || !first.text.startsWith('/')) return undefined
-  return first.text
-}
-
-/** 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?: unknown }
-
-/**
- * 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
-}
-
-/** Project a server-side GoalView into the wire GoalView shape. */
-function goalView(g: CoreGoalView): GoalView {
-  return {
-    id: g.id,
-    revision: g.revision,
-    objective: g.objective,
-    phase: g.phase,
-    ...(g.blockedReason !== undefined ? { blockedReason: g.blockedReason } : {}),
-    maxGoalRounds: g.maxGoalRounds,
-    roundsStarted: g.roundsStarted,
-    createdAt: g.createdAt,
-    updatedAt: g.updatedAt,
-    activation: g.activation,
-  }
-}
-
-/**
- * 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: {} } }
-    }
-  }
-
-  /** Resolve a session, apply one goal mutation, and map domain failures to the wire result. */
-  async function mutateGoal(
-    request: RpcRequest<{ sessionId: SessionId }>,
-    mutation: (agent: Agent) => CoreGoalView,
-  ): Promise<RpcResponse<{ goal: GoalView }>> {
-    const found = await agentFor(request.payload.sessionId)
-    if ('error' in found) return err(request, found.error)
-    try {
-      return ok(request, { goal: goalView(mutation(found.agent)) })
-    } catch (error: unknown) {
-      return err(request, { code: 'internal', message: 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
-        // Host-side slash-command dispatch (symmetric with the ACP adapter): a
-        // leading-/ single-text-block prompt executes through the command
-        // registry instead of reaching the model. Commands are mode-agnostic,
-        // so queue and steer dispatch identically.
-        const commandLine = commandCandidate(content)
-        if (commandLine !== undefined) {
-          // Unary handlers carry no request signal; the dispatch owns a fresh
-          // one (commands here are synchronous mutations, so nothing aborts it).
-          const result = await ctx.commands.execute(agent, commandLine, new AbortController().signal)
-          if (result === undefined) {
-            const space = commandLine.search(/\s/u)
-            const token = space === -1 ? commandLine : commandLine.slice(0, space)
-            return err(request, { code: 'unknown-command', message: `unknown command: ${token}`, details: {} })
-          }
-          // Usage/state errors travel as RPC errors so the client restores the
-          // composer's draft and shows the message on its error strip.
-          if (result.kind === 'error') {
-            return err(request, { code: 'command-error', message: result.text, details: {} })
-          }
-          return ok(request, {
-            accepted: true as const,
-            command: { kind: 'success' as const, ...result.text === undefined ? {} : { text: result.text } },
-          })
-        }
-        // 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' })
-    },
-
-    goals: {
-      async get(request) {
-        const { sessionId } = request.payload
-        const found = await agentFor(sessionId)
-        if ('error' in found) return err(request, found.error)
-        const goal = ctx.goals.get(found.agent)
-        return ok(request, { goal: goal ? goalView(goal) : null })
-      },
-
-      async create(request) {
-        const { objective, maxGoalRounds } = request.payload
-        return mutateGoal(request, agent => ctx.goals.create(agent, {
-          objective,
-          ...(maxGoalRounds !== undefined ? { maxGoalRounds } : {}),
-        }))
-      },
-
-      async edit(request) {
-        const { ref, objective, maxGoalRounds } = request.payload
-        return mutateGoal(request, agent => ctx.goals.edit(agent, ref, {
-          ...(objective !== undefined ? { objective } : {}),
-          ...(maxGoalRounds !== undefined ? { maxGoalRounds } : {}),
-        }))
-      },
-
-      async pause(request) {
-        return mutateGoal(request, agent => ctx.goals.pause(agent, request.payload.ref))
-      },
-
-      async resume(request) {
-        return mutateGoal(request, agent => ctx.goals.resume(agent, request.payload.ref))
-      },
-
-      async complete(request) {
-        return mutateGoal(request, agent => ctx.goals.complete(agent, request.payload.ref))
-      },
-
-      async clear(request) {
-        const { sessionId, ref } = request.payload
-        const found = await agentFor(sessionId)
-        if ('error' in found) return err(request, found.error)
-        try {
-          ctx.goals.clear(found.agent, ref)
-          return ok(request, { cleared: true as const })
-        } catch (error: unknown) {
-          return err(request, { code: 'internal', message: String(error), details: {} })
-        }
-      },
-    },
-  }
-}

packages/host/runtime/src/boot.ts

@@ -1,144 +0,0 @@
-/**
- * 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'
-import GoalService from '@deepseek-ai/dsh-goal'
-import * as goalSession from '@deepseek-ai/dsh-goal-session'
-import CommandService from '@deepseek-ai/dsh-commands'
-import * as commandGoal from '@deepseek-ai/dsh-command-goal'
-
-/** 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 })
-  // Goal service and automatic same-session continuation.
-  await ctx.plugin(GoalService, {})
-  await ctx.plugin(goalSession)
-  // Human slash commands: the registry plus the /goal producer; the api-proxy
-  // prompt path dispatches leading-/ single-text-block prompts through them.
-  await ctx.plugin(CommandService)
-  await ctx.plugin(commandGoal)
-  return { ctx, defaults, dispose: () => ctx.fiber.dispose() }
-}

packages/host/runtime/src/index.ts

@@ -1,14 +0,0 @@
-/**
- * @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

@@ -1,31 +0,0 @@
-/**
- * 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

@@ -1,58 +0,0 @@
-/**
- * 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

@@ -1,63 +0,0 @@
-/**
- * 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-command.spec.ts

@@ -1,345 +0,0 @@
-/**
- * Host-side slash-command dispatch in sessions.prompt: a leading-/
- * single-text-block prompt executes through the command registry and never
- * reaches the model — symmetric with the ACP adapter. Successful commands
- * return ok with the command slot; usage errors and unknown names return RPC
- * errors so the client restores the composer's draft. Non-command prompts
- * still route to agent.send/steer.
- *
- * The second suite covers the goals RPC surface over the same live harness:
- * get/create/edit/pause/resume/complete/clear project the goal service onto
- * the wire, service rejections (stale ref, duplicate create) become internal
- * RPC errors, and an unservable session id is an RPC error on every method.
- */
-
-import { describe, expect, it } from 'vitest'
-import { Context } from 'cordis'
-import AgentRegistry from '@deepseek-ai/dsh-agent'
-import type { Agent, AgentStatus, InjectOptions } from '@deepseek-ai/dsh-agent'
-import CommandService from '@deepseek-ai/dsh-commands'
-import GoalService from '@deepseek-ai/dsh-goal'
-import * as commandGoal from '@deepseek-ai/dsh-command-goal'
-import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
-import { Session, SessionId } from '@deepseek-ai/dsh-session'
-import type { ApiProxy, GoalView } from '@deepseek-ai/dsh-host-apiproxy/api'
-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'
-
-interface Harness {
-  readonly ctx: Context
-  readonly agent: Agent
-  readonly session: Session
-  /** Content arguments of every agent.send/steer call, in order. */
-  readonly sent: ContentBlock[][]
-  readonly steered: ContentBlock[][]
-}
-
-/** Number the next balanced injection turn. */
-function nextTurn(session: Session): number {
-  return session.events.reduce(
-    (maximum, event) => event.type === 'turn/start' ? Math.max(maximum, event.data.turn) : maximum,
-    0,
-  ) + 1
-}
-
-/** Build a live idle agent whose send/steer calls are recorded. */
-function stubAgent(id: string): { agent: Agent; session: Session; sent: ContentBlock[][]; steered: ContentBlock[][] } {
-  const session = new Session(SessionId(id))
-  const sent: ContentBlock[][] = []
-  const steered: ContentBlock[][] = []
-  let status: AgentStatus = 'idle'
-  const agent: Agent = {
-    id: session.id,
-    options: {},
-    session,
-    ctx: new Context(),
-    get status() { return status },
-    send(content) { sent.push(content) },
-    steer(content) { steered.push(content) },
-    inject(content: ContentBlock[], options?: InjectOptions) {
-      const source: MessageSource = options?.source ?? { kind: 'user' }
-      const turn = nextTurn(session)
-      session.append('turn/start', { turn, trigger: { kind: 'injection', source } })
-      session.append('context/message', {
-        content,
-        source,
-        ...options?.meta === undefined ? {} : { meta: options.meta },
-      }, { surfaceOp: 'append' })
-      session.append('turn/end', { turn, reason: { kind: 'completed' } })
-    },
-    cancel() { status = 'idle' },
-    whenIdle() { return Promise.resolve() },
-  }
-  return { agent, session, sent, steered }
-}
-
-/** Mount the real command registry, goal domain, and /goal producer. */
-async function harness(): Promise<Harness> {
-  const ctx = new Context()
-  await ctx.plugin(CommandService)
-  await ctx.plugin(AgentRegistry)
-  await ctx.plugin(GoalService)
-  await ctx.plugin(commandGoal)
-  const { agent, session, sent, steered } = stubAgent(`api-proxy-command-${Math.random()}`)
-  ctx.agents.register(agent)
-  return { ctx, agent, session, sent, steered }
-}
-
-let nextRpc = 1
-function request<P>(payload: P): RpcRequest<P> {
-  return { rpcId: RpcId(`command-${String(nextRpc++)}`), payload }
-}
-
-function promptPayload(test: Harness, text: string, mode: 'queue' | 'steer' = 'queue') {
-  const content: ContentBlock[] = [{ type: 'text', text }]
-  return request({ sessionId: test.session.id, mode, content })
-}
-
-describe('sessions.prompt slash-command dispatch', () => {
-  it('executes /goal <objective>: goal created, command slot carried, no model turn', async () => {
-    const test = await harness()
-    const api = createApiProxy(test.ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
-
-    const response = await api.sessions.prompt(promptPayload(test, '/goal fix the flaky test'))
-    expect(response.result.ok).toBe(true)
-    if (!response.result.ok) throw new Error('unreachable')
-    expect(response.result.value.accepted).toBe(true)
-    expect(response.result.value.command?.kind).toBe('success')
-    expect(response.result.value.command?.text).toContain('Goal created')
-
-    const goal = test.ctx.goals.get(test.agent)
-    expect(goal?.objective).toBe('fix the flaky test')
-    // The prompt never reached the model: no send, no user/message event.
-    expect(test.sent).toEqual([])
-    expect(test.steered).toEqual([])
-    expect(test.session.events.filter(event => event.type === 'user/message')).toEqual([])
-  })
-
-  it('dispatches commands regardless of mode (steer prompt never steers)', async () => {
-    const test = await harness()
-    const api = createApiProxy(test.ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
-
-    const response = await api.sessions.prompt(promptPayload(test, '/goal', 'steer'))
-    expect(response.result.ok).toBe(true)
-    if (!response.result.ok) throw new Error('unreachable')
-    expect(response.result.value.command?.text).toContain('No goal is currently set')
-    expect(test.sent).toEqual([])
-    expect(test.steered).toEqual([])
-  })
-
-  it('returns unknown-command for an unregistered name', async () => {
-    const test = await harness()
-    const api = createApiProxy(test.ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
-
-    const response = await api.sessions.prompt(promptPayload(test, '/bogus do something'))
-    expect(response.result.ok).toBe(false)
-    if (response.result.ok) throw new Error('unreachable')
-    expect(response.result.error.code).toBe('unknown-command')
-    expect(response.result.error.message).toBe('unknown command: /bogus')
-    expect(test.sent).toEqual([])
-
-    const bare = await api.sessions.prompt(promptPayload(test, '/bogus'))
-    expect(bare.result.ok).toBe(false)
-    if (!bare.result.ok) expect(bare.result.error.message).toBe('unknown command: /bogus')
-  })
-
-  it('carries a success without text when the command produced none', async () => {
-    const test = await harness()
-    const api = createApiProxy(test.ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
-    test.ctx.commands.register({ name: 'ping', description: 'test no-text success', handler: () => ({ kind: 'success' }) })
-
-    const response = await api.sessions.prompt(promptPayload(test, '/ping'))
-    expect(response.result.ok).toBe(true)
-    if (!response.result.ok) throw new Error('unreachable')
-    expect(response.result.value.command).toEqual({ kind: 'success' })
-    expect(test.sent).toEqual([])
-  })
-
-  it('returns command-error for a usage error (bare /goal edit)', async () => {
-    const test = await harness()
-    const api = createApiProxy(test.ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
-
-    const response = await api.sessions.prompt(promptPayload(test, '/goal edit'))
-    expect(response.result.ok).toBe(false)
-    if (response.result.ok) throw new Error('unreachable')
-    expect(response.result.error.code).toBe('command-error')
-    expect(response.result.error.message).toContain('Goal editing requires a replacement objective')
-    expect(test.sent).toEqual([])
-  })
-
-  it('routes a non-command prompt to agent.send unchanged', async () => {
-    const test = await harness()
-    const api = createApiProxy(test.ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
-
-    const response = await api.sessions.prompt(promptPayload(test, 'hello there'))
-    expect(response.result.ok).toBe(true)
-    if (!response.result.ok) throw new Error('unreachable')
-    expect(response.result.value.accepted).toBe(true)
-    expect('command' in response.result.value).toBe(false)
-    expect(test.sent).toEqual([[{ type: 'text', text: 'hello there' }]])
-  })
-
-  it('routes multi-block content starting with / to the model (never flattened)', async () => {
-    const test = await harness()
-    const api = createApiProxy(test.ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
-
-    const content: ContentBlock[] = [{ type: 'text', text: '/goal not a command' }, { type: 'text', text: 'second' }]
-    const response = await api.sessions.prompt(request({ sessionId: test.session.id, mode: 'queue' as const, content }))
-    expect(response.result.ok).toBe(true)
-    expect(test.sent).toEqual([content])
-  })
-
-  it('routes degenerate content shapes to the model (empty array, single non-text block)', async () => {
-    const test = await harness()
-    const api = createApiProxy(test.ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
-
-    const empty: ContentBlock[] = []
-    await api.sessions.prompt(request({ sessionId: test.session.id, mode: 'queue' as const, content: empty }))
-    const nonText: ContentBlock[] = [{ type: 'reasoning', text: '/goal not a command' }]
-    await api.sessions.prompt(request({ sessionId: test.session.id, mode: 'queue' as const, content: nonText }))
-    expect(test.sent).toEqual([empty, nonText])
-  })
-})
-
-describe('goals RPC surface', () => {
-  /** Unwrap an ok goal value or fail the test. */
-  function goalOf(response: Awaited<ReturnType<ApiProxy['goals']['get']>>): GoalView {
-    if (!response.result.ok) throw new Error(`expected ok, got ${response.result.error.message}`)
-    if (response.result.value.goal === null) throw new Error('expected a current goal')
-    return response.result.value.goal
-  }
-
-  it('get returns null when no goal is set', async () => {
-    const test = await harness()
-    const api = createApiProxy(test.ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
-
-    const response = await api.goals.get(request({ sessionId: test.session.id }))
-    expect(response.result.ok).toBe(true)
-    if (!response.result.ok) throw new Error('unreachable')
-    expect(response.result.value.goal).toBeNull()
-  })
-
-  it('create arms a goal, defaulting and honoring the round cap; a duplicate create is an internal error', async () => {
-    const test = await harness()
-    const api = createApiProxy(test.ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
-
-    const created = goalOf(await api.goals.create(request({ sessionId: test.session.id, objective: 'first' })))
-    expect(created.phase).toBe('active')
-    expect(created.activation).toBe('armed')
-    expect(created.maxGoalRounds).toBe(256) // service default
-
-    const duplicate = await api.goals.create(request({ sessionId: test.session.id, objective: 'second' }))
-    expect(duplicate.result.ok).toBe(false)
-    if (duplicate.result.ok) throw new Error('unreachable')
-    expect(duplicate.result.error.code).toBe('internal')
-    expect(duplicate.result.error.message).toContain('already exists')
-
-    const cleared = await api.goals.clear(request({ sessionId: test.session.id, ref: created }))
-    expect(cleared.result.ok).toBe(true)
-
-    const capped = goalOf(await api.goals.create(request({ sessionId: test.session.id, objective: 'capped', maxGoalRounds: 4 })))
-    expect(capped.maxGoalRounds).toBe(4)
-  })
-
-  it('get projects the live goal, including the durable blocked reason', async () => {
-    const test = await harness()
-    const api = createApiProxy(test.ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
-    const created = goalOf(await api.goals.create(request({ sessionId: test.session.id, objective: 'block me' })))
-
-    const before = goalOf(await api.goals.get(request({ sessionId: test.session.id })))
-    expect(before.objective).toBe('block me')
-    expect('blockedReason' in before).toBe(false)
-
-    test.ctx.goals.block(test.agent, created, { code: 'stalled', message: 'no progress' })
-    const after = goalOf(await api.goals.get(request({ sessionId: test.session.id })))
-    expect(after.phase).toBe('blocked')
-    expect(after.blockedReason).toEqual({ code: 'stalled', message: 'no progress' })
-  })
-
-  it('edit replaces the objective and/or the round cap, one field at a time', async () => {
-    const test = await harness()
-    const api = createApiProxy(test.ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
-    const created = goalOf(await api.goals.create(request({ sessionId: test.session.id, objective: 'v1', maxGoalRounds: 4 })))
-
-    const renamed = goalOf(await api.goals.edit(request({ sessionId: test.session.id, ref: created, objective: 'v2' })))
-    expect(renamed.objective).toBe('v2')
-    expect(renamed.maxGoalRounds).toBe(4)
-    expect(renamed.revision).toBe(created.revision + 1)
-
-    const recapped = goalOf(await api.goals.edit(request({ sessionId: test.session.id, ref: renamed, maxGoalRounds: 8 })))
-    expect(recapped.objective).toBe('v2')
-    expect(recapped.maxGoalRounds).toBe(8)
-  })
-
-  it('pause, resume, complete, and clear drive the phase machine over the wire', async () => {
-    const test = await harness()
-    const api = createApiProxy(test.ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
-    const created = goalOf(await api.goals.create(request({ sessionId: test.session.id, objective: 'lifecycle' })))
-
-    const paused = goalOf(await api.goals.pause(request({ sessionId: test.session.id, ref: created })))
-    expect([paused.phase, paused.activation]).toEqual(['paused', 'disarmed'])
-
-    const resumed = goalOf(await api.goals.resume(request({ sessionId: test.session.id, ref: paused })))
-    expect([resumed.phase, resumed.activation]).toEqual(['active', 'armed'])
-
-    const completed = goalOf(await api.goals.complete(request({ sessionId: test.session.id, ref: resumed })))
-    expect([completed.phase, completed.activation]).toEqual(['complete', 'disarmed'])
-
-    const cleared = await api.goals.clear(request({ sessionId: test.session.id, ref: completed }))
-    expect(cleared.result.ok).toBe(true)
-    if (!cleared.result.ok) throw new Error('unreachable')
-    expect(cleared.result.value.cleared).toBe(true)
-    expect(goalOfNull(await api.goals.get(request({ sessionId: test.session.id })))).toBeNull()
-  })
-
-  /** Unwrap a get value (goal or null) or fail the test. */
-  function goalOfNull(response: Awaited<ReturnType<ApiProxy['goals']['get']>>): GoalView | null {
-    if (!response.result.ok) throw new Error('unreachable')
-    return response.result.value.goal
-  }
-
-  it('a stale ref surfaces as an internal RPC error on every mutating method', async () => {
-    const test = await harness()
-    const api = createApiProxy(test.ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
-    const created = goalOf(await api.goals.create(request({ sessionId: test.session.id, objective: 'cas' })))
-    const stale = { id: created.id, revision: created.revision + 99 }
-
-    const attempts = [
-      () => api.goals.edit(request({ sessionId: test.session.id, ref: stale, objective: 'nope' })),
-      () => api.goals.pause(request({ sessionId: test.session.id, ref: stale })),
-      () => api.goals.resume(request({ sessionId: test.session.id, ref: stale })),
-      () => api.goals.complete(request({ sessionId: test.session.id, ref: stale })),
-      () => api.goals.clear(request({ sessionId: test.session.id, ref: stale })),
-    ]
-    for (const attempt of attempts) {
-      const response = await attempt()
-      expect(response.result.ok).toBe(false)
-      if (!response.result.ok) expect(response.result.error.code).toBe('internal')
-    }
-    // None of the failed mutations touched the goal.
-    const current = goalOfNull(await api.goals.get(request({ sessionId: test.session.id })))
-    expect([current?.objective, current?.revision]).toEqual(['cas', created.revision])
-  })
-
-  it('an unservable session id is an RPC error on every goal method', async () => {
-    const test = await harness()
-    const api = createApiProxy(test.ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
-    const missing = SessionId('no-such-session')
-    const ref = { id: 'goal-x' as GoalView['id'], revision: 1 }
-
-    const attempts = [
-      () => api.goals.get(request({ sessionId: missing })),
-      () => api.goals.create(request({ sessionId: missing, objective: 'x' })),
-      () => api.goals.edit(request({ sessionId: missing, ref, objective: 'x' })),
-      () => api.goals.pause(request({ sessionId: missing, ref })),
-      () => api.goals.resume(request({ sessionId: missing, ref })),
-      () => api.goals.complete(request({ sessionId: missing, ref })),
-      () => api.goals.clear(request({ sessionId: missing, ref })),
-    ]
-    for (const attempt of attempts) {
-      const response = await attempt()
-      expect(response.result.ok).toBe(false)
-    }
-  })
-})

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

@@ -1,367 +0,0 @@
-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

@@ -1,71 +0,0 @@
-/**
- * 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 lib/.
-    for (const row of rows) {
-      expect(registry.clientPath(row.id)).toMatch(/lib[/\\]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

@@ -1,114 +0,0 @@
-/**
- * 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

@@ -1,156 +0,0 @@
-{
-  "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": "../../goal/goal"
-    },
-    {
-      "path": "../../goal/goal-session"
-    },
-    {
-      "path": "../../goal/command-goal"
-    },
-    {
-      "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": "../../ui/commands"
-    },
-    {
-      "path": "../../client/ui-trajectory"
-    }
-  ]
-}

packages/host/webserver/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: c589c32c4e641e188f19ac6c5ad2e88e3eb79be3
+README.zh.md: 767195086b90a76160d87865caebf514ca75b0e3

packages/host/webserver/README.md

@@ -1,16 +1,18 @@
 # @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.
+English | [中文](README.zh.md)
 
-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.
+Plain HTTP route-registration plugin (default-exported `WebServerService`, config `{host, port, distIndex}`): a `node:http` server that listens on activation and provides `ctx.webServer` — `register(route)` adds a named `exact`/`prefix` route (duplicate `(kind, path)` throws: route patterns are a composition-level contract, so a collision is a misconfiguration; the returned disposer removes the route), `tapIndex(transform)` adds an index.html transform applied in registration order, and `port` reads the listening port (the OS-assigned value when `port` is 0). The match order is fixed — exact over the whole table, then longest prefix, then the static dist fallback with the 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. Registration order carries no request-facing semantics.
 
-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.
+The package knows no harness concepts: the `/api` bridge is the connection plugin's route, plugin bundles and the HMR event stream are the modules/hmr plugins' routes. `host` accepts only `127.0.0.1` (default posture) and `0.0.0.0` (deliberate network exposure); `distIndex` is an assembly fact the composing app resolves and injects, never self-resolved (dist location is workspace knowledge of the app). 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.
 
-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.
+A listen failure (EADDRINUSE…) throws out of activation — a FAILED fiber the boot's fail-loud sweep reports. 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 logged as a warning; it never exits the process. Disposal pairs `close()` with `closeAllConnections()` because held-open responses (SSE) never end on their own.
+
+In development, the client-plugin registry synchronously captures each built bundle's stat baseline before it returns, then polls those baselines and re-hashes changed content. Each rescan stages its candidate table, graph, and watch map before publishing them, so a baseline failure preserves the prior graph. An immediate rebuild therefore cannot disappear into an asynchronously established watch baseline; a rename window marks the path dirty, retains the last successful baseline, and forces a re-hash when the bundle reappears even with identical metadata.
 
 ## 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.
+None, as the package is a pure HTTP carrier between the browser and the routes other plugins register; nothing here reaches a model request.
 
 #### KV Cache effect
 
@@ -18,6 +20,6 @@ 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.
+- **No TLS, auth, or origin policy** — binding a non-loopback address exposes the server to that 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.
+- **Socket options are fixed** — config selects the bind host and port, while backlog and other socket settings remain internal until a deployment needs them.

packages/host/webserver/README.zh.md

@@ -0,0 +1,25 @@
+# @deepseek-ai/dsh-host-webserver
+
+[English](README.md) | 中文
+
+朴素的 HTTP 路由注册插件（默认导出 `WebServerService`，配置为 `{host, port, distIndex}`）：一个在激活时开始监听的 `node:http` 服务器，提供 `ctx.webServer`。`register(route)` 添加具名的 `exact`／`prefix` 路由；重复的 `(kind, path)` 会抛错，因为路由模式是组合层契约，冲突即配置错误；返回的 disposer 会移除该路由。`tapIndex(transform)` 添加按注册顺序应用的 index.html 转换，`port` 读取正在监听的端口（当 `port` 为 0 时读取 OS 分配的值）。匹配顺序固定不变：先在整张表中匹配精确路由，再匹配最长前缀，最后回退到静态 dist，并遵循固定语义：越出 dist 根目录的遍历返回 403，任何未命中项都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 octet-stream 提供，GET／HEAD 之外的方法返回 405。注册顺序不承载任何面向请求的语义。
+
+该包不了解任何 harness 概念：`/api` 桥接是 connection 插件的路由，插件 bundle 与 HMR（热模块替换）事件流则是 modules／hmr 插件的路由。`host` 只接受 `127.0.0.1`（默认姿态）和 `0.0.0.0`（有意向网络开放）；`distIndex` 是由组合应用解析并注入的组装事实，绝不会自行解析，因为 dist 位置属于应用的工作区知识。该服务器只服务 Web（浏览器）形态；Electron 通过 `file://` 加载 dist，并经 IPC 桥接承载 fetch，而不使用本服务器。该包从不打印内容；URL 行属于 shell。
+
+监听失败（EADDRINUSE……）会从激活过程抛出，使 fiber 进入 FAILED 状态并由启动流程的快速失败扫描报告。处理请求时抛错（例如格式错误的百分号转义传入 `decodeURIComponent`，或客户端在请求体传输中途断开）时，服务器会响应 400；若响应头已经发出，则销毁 socket，并记录 warning，但绝不会退出进程。资源释放会把 `close()` 与 `closeAllConnections()` 配对，因为一直保持打开的响应（SSE）不会自行结束。
+
+在开发环境中，客户端插件注册表会在返回前同步捕获每个已构建 bundle 的 stat 基线，随后轮询这些基线，并在内容变化后重新计算哈希。每次重新扫描都会先暂存候选表、图和监听 map，再统一发布，因此基线失败会保留先前的图。这样，即时重建不会消失在异步建立的监听基线中；重命名窗口会把路径标记为脏，保留最近一次成功基线，并在 bundle 重新出现时强制重新计算哈希，即使其元数据完全相同也不例外。
+
+## 模型体验
+
+无。该包只是浏览器与其他插件所注册路由之间的纯 HTTP 载体，其中没有任何内容会进入模型请求。
+
+#### KV 缓存影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与延期工作
+
+- **不提供 TLS、认证或来源策略**：绑定非回环地址会向对应网络公开服务器；面向部署的加固措施（或在前方放置真正的反向代理）有意不纳入面向开发环境的 v1。
+- **初始 MIME 表很精简**：Vite 输出集合以外的扩展名会回退到 `application/octet-stream`；实际发布新的资产类别时再扩展该表。
+- **Socket 选项固定不变**：配置只选择绑定宿主与端口；在具体部署产生需求前，backlog 和其他 socket 设置仍保持内部实现。

packages/host/webserver/package.json

@@ -1,6 +1,6 @@
 {
   "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)",
+  "description": "Plain HTTP route-registration plugin: named-route registry (webServer service) + index transform taps + static dist fallback; knows no harness concepts",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -30,6 +30,9 @@
     "cordis": "^4.0.0-rc.7",
     "@deepseek-ai/dsh-invariants": "^0.0.1"
   },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
   "devDependencies": {
     "cordis": "^4.0.0-rc.7",
     "@deepseek-ai/dsh-invariants": "workspace:^"

packages/host/webserver/src/index.ts

@@ -1,208 +1,184 @@
 /**
- * @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.
+ * @deepseek-ai/dsh-host-webserver — plain HTTP route-registration plugin: a
+ * node:http server plus the `httpServer` service (named-route registry + index
+ * transform taps + static dist fallback). Knows no harness concepts — every
+ * feature surface (API bridge, plugin bundles, SSE) is a route some other
+ * plugin registers. 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 type { IncomingMessage, ServerResponse, Server } from 'node:http'
 import { readFile } from 'node:fs/promises'
+import type { AddressInfo } from 'node:net'
 import { dirname } from 'node:path'
+import { Context, Service } from 'cordis'
+import z from 'schemastery'
 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'>
+declare module 'cordis' {
+  interface Context {
+    httpServer: HttpServerService
+  }
 }
 
-/** Listening web server handle. */
-export interface RunningWebServer {
-  /** The listening port (for the shell's URL line; equals options.port). */
+/** Route match kind: 'exact' matches the pathname verbatim; 'prefix' p matches p and p/<anything>. */
+export type WebRouteKind = 'exact' | 'prefix'
+
+/** One named route registration. */
+export interface WebRoute {
+  kind: WebRouteKind
+  /** Absolute pathname, no trailing slash. */
+  path: string
+  /** Owns the full response lifecycle (may hold the response open, e.g. SSE). */
+  handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
+}
+
+/** Gateway config: listen address plus the static dist anchor (injected by the composing app, never self-resolved). */
+export interface Config {
+  /** Listen host; the two supported values are loopback and all-interfaces. */
+  host: '127.0.0.1' | '0.0.0.0'
+  /** Listen port; zero requests an OS-assigned port. */
   port: number
-  /**
-   * Shutdown: close + closeAllConnections (SSE connections never end on their
-   * own; without the force-close, close() would hang). Idempotent.
-   */
-  close(): Promise<void>
+  /** Absolute path of index.html inside the static root (dist location is workspace knowledge of the app). */
+  distIndex: string
 }
 
 /**
- * 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.
+ * The web-shape HTTP carrier service. Activation listens immediately (route
+ * registration order carries no request-facing semantics: named routes are
+ * composed to be disjoint, and the static dist fallback answers anything not
+ * yet claimed during the boot window). A listen failure throws out of init —
+ * a FAILED fiber the boot's fail-loud sweep reports.
  */
-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())
+export class HttpServerService extends Service {
+  static Config: z<Config> = z.object({
+    host: z.union([z.const('127.0.0.1'), z.const('0.0.0.0')]).required(),
+    port: z.natural().max(65535).required(),
+    distIndex: z.string().required(),
+  })
+
+  private readonly exact = new Map<string, WebRoute>()
+  private readonly prefixes = new Map<string, WebRoute>()
+  private readonly indexTaps: ((html: string) => string)[] = []
+  private readonly distRoot: string
+  private readonly distIndex: string
+  private server!: Server
+  private listenedPort!: number
+
+  constructor(ctx: Context, private config: Config) {
+    super(ctx, 'httpServer')
+    this.distIndex = config.distIndex
+    this.distRoot = dirname(config.distIndex)
   }
 
-  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)
+  /** The listening port (the OS-assigned value when config.port is 0). */
+  get port(): number {
+    return this.listenedPort
   }
-  // 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()
+
+  /**
+   * Register a named route. Duplicate (kind, path) throws — route patterns are
+   * a composition-level contract, so a collision is a misconfiguration.
+   * @param route - kind, path, and the owning handler.
+   * @returns the disposer removing the route.
+   */
+  register(route: WebRoute): () => void {
+    const table = route.kind === 'exact' ? this.exact : this.prefixes
+    if (table.has(route.path)) {
+      throw new Error(`webserver: duplicate ${route.kind} route "${route.path}"`)
+    }
+    table.set(route.path, route)
+    return () => { table.delete(route.path) }
+  }
+
+  /**
+   * Register an index.html transform, applied to every index response in
+   * registration order.
+   * @param transform - pure html-to-html function.
+   * @returns the disposer removing the transform.
+   */
+  tapIndex(transform: (html: string) => string): () => void {
+    this.indexTaps.push(transform)
+    return () => {
+      const at = this.indexTaps.indexOf(transform)
+      if (at !== -1) this.indexTaps.splice(at, 1)
+    }
+  }
+
+  /** Listen; resolves once the socket is bound (rejection = FAILED fiber). */
+  async [Service.init](): Promise<void> {
+    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
+      const route = this.match(rawPath)
+      if (route !== undefined) {
+        await route.handler(req, res)
         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)
-      })
+      // Static fallback keeps the pre-plugin semantics: non-GET/HEAD is 405,
+      // traversal 403, miss falls back to index.html 200 (SPA routing).
+      if (req.method !== 'GET' && req.method !== 'HEAD') {
+        res.writeHead(405)
+        res.end()
+        return
+      }
+      await serveStatic(decodeURIComponent(rawPath), res, this.distRoot, this.distIndex, () => this.renderIndex())
     }
+    // Last-resort guard: handle() rejecting would otherwise be an unhandled
+    // rejection killing the process on one malformed request (bad %-escape,
+    // client dropping mid-body). Per-request failures log and answer 400 —
+    // never a process exit.
+    this.server = createServer((req, res) => {
+      handle(req, res).catch((err: unknown) => {
+        this.ctx.logger.warn(err instanceof Error ? err : new Error(String(err)))
+        if (res.headersSent) {
+          res.destroy()
+          return
+        }
+        res.writeHead(400)
+        res.end()
+      })
+    })
+
+    await new Promise<void>((resolve, reject) => {
+      this.server.once('error', reject)
+      this.server.listen(this.config.port, this.config.host, () => {
+        this.server.off('error', reject)
+        this.server.on('error', (err) => { this.ctx.logger.error(err) })
+        this.listenedPort = (this.server.address() as AddressInfo).port
+        resolve()
+      })
+    })
+
+    // close + closeAllConnections: held-open responses (SSE) never end on
+    // their own; without the force-close, close() would hang teardown.
+    this.ctx.effect(() => () => new Promise<void>((resolve) => {
+      this.server.close(() => { resolve() })
+      this.server.closeAllConnections()
+    }), 'httpServer.listen')
+  }
+
+  /** Longest-prefix-wins over the prefix table after an exact-table miss. */
+  private match(pathname: string): WebRoute | undefined {
+    const exact = this.exact.get(pathname)
+    if (exact !== undefined) return exact
+    let best: WebRoute | undefined
+    for (const [prefix, route] of this.prefixes) {
+      if (pathname !== prefix && !pathname.startsWith(`${prefix}/`)) continue
+      if (best === undefined || prefix.length > best.path.length) best = route
+    }
+    return best
+  }
+
+  /** Index body: dist index.html through the registered taps in order. */
+  private async renderIndex(): Promise<string> {
+    let html = await readFile(this.distIndex, 'utf8')
+    for (const transform of this.indexTaps) html = transform(html)
+    return html
   }
-  res.end()
 }
+
+export default HttpServerService

packages/host/webserver/src/invariant.ts

@@ -15,26 +15,30 @@ export const name = 'host-webserver-invariant'
 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.
+ * Owned relation: route registrations and their disposers must stay
+ * symmetric — after the owning fiber of a registered route unloads, the
+ * route table must no longer answer for its path (a stale route would keep
+ * serving a disposed plugin's handler). Checked on every fiber teardown
+ * (cordis 'internal/plugin'): the service's own registry state is compared
+ * against the set of live fibers' registrations indirectly, by probing that
+ * dispose really removed the entry — the register() disposer contract.
  */
 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 }
+    const server = ctx.get('httpServer') as
+      | { register(route: { kind: 'exact'; path: string; handler: () => void }): () => void }
       | 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`)
-      }
+    if (server === undefined) return // no webserver row in this composition
+    // Register/dispose probe on a reserved path: if dispose leaves the route
+    // behind, a second register throws the duplicate error — the asymmetry.
+    // Each register(probe)() is one register+dispose cycle, so the probe never
+    // leaves residue; a leftover from the first cycle makes the second throw.
+    const probe = { kind: 'exact' as const, path: '/__dsh_invariant_probe__', handler: () => {} }
+    try {
+      server.register(probe)()
+      server.register(probe)()
+    } catch {
+      fail('httpServer.register() disposer left the route registered — route table and fiber lifecycles diverged')
     }
   }, { global: true })
 }

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

@@ -1,184 +0,0 @@
-/**
- * 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

@@ -1,50 +0,0 @@
-/**
- * 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

@@ -1,210 +0,0 @@
-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

@@ -1,337 +1,168 @@
-import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs'
-import { createServer as createNetServer, type AddressInfo } from 'node:net'
+/**
+ * REAL-composition coverage: a test-only cordis.yml booted through the
+ * vendored Loader mounts the webserver row, and every assertion observes the
+ * user-visible HTTP surface of the running server (routing precedence, index
+ * taps, static-fallback semantics, per-request error containment, teardown).
+ */
+
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { mkdir } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
 import { afterEach, describe, expect, it } from 'vitest'
-import { startWebServer, type RunningWebServer } from '../src/index.ts'
+import { Context, FiberState } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import Include from '@cordisjs/plugin-include'
+import HttpServer 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
+let root: string | undefined
+let context: Context | undefined
 
 afterEach(async () => {
-  await server?.close()
-  server = undefined
+  await context?.fiber.dispose()
+  context = undefined
+  if (root !== undefined) await rm(root, { recursive: true, force: true })
+  root = 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)}`
+/** Write a dist fixture and a cordis.yml with one webserver row, then boot it through the real Loader. */
+async function loadComposition(port = 0): Promise<Context> {
+  root = await mkdtemp(join(tmpdir(), 'dsh-webserver-loader-'))
+  const dist = join(root, 'dist')
+  await mkdir(dist)
+  const distIndex = join(dist, 'index.html')
+  await writeFile(distIndex, '<head></head><body>shell</body>')
+  await writeFile(join(dist, 'app.js'), 'export {}')
+  const configPath = join(root, 'cordis.yml')
+  await writeFile(configPath, [
+    "- name: '@deepseek-ai/dsh-host-webserver'",
+    '  config:',
+    "    host: '127.0.0.1'",
+    `    port: ${String(port)}`,
+    `    distIndex: '${distIndex}'`,
+    '',
+  ].join('\n'))
+
+  context = new Context()
+  context.baseUrl = pathToFileURL(root).href + '/'
+  await context.plugin(Loader)
+  context.loader.builtins.include = Include
+  const modules = new Map<string, unknown>([
+    ['@deepseek-ai/dsh-host-webserver', HttpServer],
+  ])
+  context.loader.internal = {
+    version: 'v2',
+    async import(specifier: string) {
+      if (!modules.has(specifier)) throw new Error(`unexpected Loader import: ${specifier}`)
+      return modules.get(specifier)
+    },
+  } as unknown as NonNullable<typeof context.loader.internal>
+  await context.loader.create({
+    name: 'cordis:include',
+    config: { path: pathToFileURL(configPath).href },
+  })
+  await context.loader.await()
+  return context
 }
 
-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
+/** GET (by default) one path against the running server; returns status plus a body prefix. */
+async function request(port: number, path: string, init?: RequestInit): Promise<{ status: number; body: string }> {
+  const response = await fetch(`http://127.0.0.1:${String(port)}${path}`, init)
+  return { status: response.status, body: (await response.text()).slice(0, 80) }
+}
+
+describe('real Loader composition', () => {
+  // Real-Loader composition resolves workspace packages through tsx at test
+  // time; first resolution after the host/client program split is slow enough
+  // to trip the default 5s budget on cold caches.
+  it('serves registered routes, index taps, and the static fallback semantics', { timeout: 60_000 }, async () => {
+    const loaded = await loadComposition()
+    const unloaded = [...loaded.loader.entries()]
+      .filter(entry => entry.fiber === undefined && !entry.disabled)
+      .map(entry => entry.options.name)
+    expect(unloaded).toEqual([])
+
+    const server = loaded.httpServer
+    expect(server).toBeInstanceOf(HttpServer)
+    const port = server.port
+    expect(port).toBeGreaterThan(0)
+
+    // Routing precedence: exact beats prefix, longest prefix wins, a prefix
+    // route answers its own path, and routes own their method handling
+    // (POST reaches a registered prefix; 405 is fallback-only semantics).
+    server.register({ kind: 'exact', path: '/probe', handler: (_req, res) => { res.writeHead(200); res.end('EXACT') } })
+    server.register({ kind: 'prefix', path: '/api', handler: (_req, res) => { res.writeHead(200); res.end('API') } })
+    server.register({ kind: 'prefix', path: '/api/deep', handler: (_req, res) => { res.writeHead(200); res.end('DEEP') } })
+    expect(await request(port, '/probe')).toMatchObject({ status: 200, body: 'EXACT' })
+    expect(await request(port, '/api/anything')).toMatchObject({ status: 200, body: 'API' })
+    expect(await request(port, '/api/deep/leaf')).toMatchObject({ status: 200, body: 'DEEP' })
+    expect(await request(port, '/api')).toMatchObject({ status: 200, body: 'API' })
+    expect(await request(port, '/api/anything', { method: 'POST' })).toMatchObject({ status: 200, body: 'API' })
+
+    // Index taps apply in registration order on `/` and on the SPA fallback;
+    // the disposer removes the transform.
+    const untap = server.tapIndex(html => html.replace('<head>', '<head><script>window.__T__=1</script>'))
+    expect((await request(port, '/')).body).toContain('__T__')
+    expect((await request(port, '/no/such/route')).body).toContain('__T__')
+    untap()
+    expect((await request(port, '/')).body).not.toContain('__T__')
+
+    // Static fallback semantics: real asset served, traversal 403, non-GET/
+    // HEAD without a matching route 405.
+    expect(await request(port, '/app.js')).toMatchObject({ status: 200, body: 'export {}' })
+    expect((await request(port, '/..%2f..%2fetc%2fpasswd')).status).toBe(403)
+    expect((await request(port, '/nowhere', { method: 'POST' })).status).toBe(405)
+
+    // Per-request error containment: a malformed %-escape answers 400 and the
+    // server keeps serving afterwards (no process-level failure path).
+    expect((await request(port, '/%zz')).status).toBe(400)
+    expect(await request(port, '/probe')).toMatchObject({ status: 200, body: 'EXACT' })
+
+    // Duplicate (kind, path) is a misconfiguration and throws; the disposer
+    // restores registrability (register/disposer symmetry).
+    expect(() => server.register({ kind: 'exact', path: '/probe', handler: () => {} }))
+      .toThrow(/duplicate exact route/)
+    const disposeOnce = server.register({ kind: 'exact', path: '/once', handler: (_req, res) => { res.writeHead(200); res.end('ONCE') } })
+    expect(await request(port, '/once')).toMatchObject({ status: 200, body: 'ONCE' })
+    disposeOnce()
+    expect((await request(port, '/once')).body).toContain('shell') // back to the SPA fallback
+    expect(() => server.register({ kind: 'exact', path: '/once', handler: () => {} })).not.toThrow()
+
+    // Teardown: fiber dispose closes the socket and severs held connections.
+    await loaded.fiber.dispose()
+    await expect(request(port, '/probe')).rejects.toThrow()
   })
 
-  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' })
-  })
-})
+  it('fails the fiber when the port is already taken (fail-loud at activation)', { timeout: 60_000 }, async () => {
+    const first = await loadComposition()
+    const takenPort = first.httpServer.port
+    const firstRoot = root
+    root = undefined // keep the first composition's files until the end
 
-describe.skipIf(process.platform === 'win32')('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.skipIf(process.platform === 'win32')('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,
+    // loader.await() never rejects (allSettled); the bind failure surfaces as
+    // a FAILED fiber whose error escapes as a late rejection — the shape the
+    // boot's installFailLoud is contracted to catch. Capture it here the same
+    // way, and assert it really is the bind error.
+    const rejections: unknown[] = []
+    const onUnhandled = (err: unknown): void => { rejections.push(err) }
+    process.on('unhandledRejection', onUnhandled)
+    let second: Context | undefined
+    try {
+      second = await loadComposition(takenPort)
+      const entry = [...second.loader.entries()].find(e => e.options.name === '@deepseek-ai/dsh-host-webserver')
+      expect(entry?.fiber?.state).toBe(FiberState.FAILED)
+      // The rejection escapes a tick after loader.await() settles; bounded poll.
+      for (let i = 0; i < 100 && rejections.length === 0; i++) {
+        await new Promise(resolve => setTimeout(resolve, 10))
+      }
+      expect(rejections.map(String).join('\n')).toContain('EADDRINUSE')
+    } finally {
+      process.off('unhandledRejection', onUnhandled)
+      await second?.fiber.dispose()
+      context = first
+      if (root !== undefined) await rm(root, { recursive: true, force: true })
+      root = firstRoot
     }
-    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

@@ -11,6 +11,9 @@
     {
       "path": "../../../vendor/cordis"
     },
+    {
+      "path": "../../../vendor/schemastery"
+    },
     {
       "path": "../../support/invariants"
     }