Merge branch 'stack/agent-profiles-3-wire' into stack/agent-profiles-5-web-ui

The Client API carrier's `agentPresets` member was the one member of its class
without an `IApiClient[...]` annotation. Inferring it inlined `AgentPresetEntry`
into the emitted declaration by the specifier TS picks — the host `index.ts` —
dragging the whole gateway, and with it the host `Context` merges, into every
Client program importing the carrier. Annotated like its siblings.

`ApiRemoteAgentOptions.setup` now takes the inspected session rather than its
header alone: this layer resolves a resumed session's preset from the LOG,
because a session that switched while blank ran its turns under the newer
composition and the header is written once at creation.

Conflicts:
	apps/web/tests/snapshots/*/*.expected.md
	packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
	packages/host/apiproxy/src/api-proxy.ts
	scripts/doc-budgets.manifest.json

packages/AGENTS.md

@@ -19,7 +19,7 @@ These package-specific rules supplement the repo-wide [conventions](../AGENTS.md
 
 Naming notes:
 
-- **Package tsconfig shape:** extends `tsconfig.base.json` (client: `tsconfig.base.client.json`), `rootDir: src`, `outDir: lib/types`, a `references` entry per workspace dependency plus `support/invariants`; registered in exactly one aggregate — host packages in `tsconfig.host.json`, client in `tsconfig.client.json` ([layout](../docs/development.md#typescript-project-layout)).
+- **Package tsconfig:** extends `tsconfig.base.json` (Client: `tsconfig.base.client.json`), uses `rootDir: src`, `outDir: lib/types`, and references each workspace dependency plus `support/invariants`; registers in exactly one aggregate. Only `api/remotes` splits for generated contracts; ordinary two-entry Client plugins do not ([layout](../docs/development.md#typescript-project-layout)).
 - `src/types.ts` contains only types — no runtime code.
 - Tests live at package level under `tests/`, not `src/__tests__/`.
 - A package's README and JSDoc are part of the change: altered behavior (config keys, defaults, error codes, wire fields) updates them in the same commit. `doc-sync` gates what it can; apply [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for complete, concise prose and verify accuracy against code.

packages/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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/README.md
-README.md: baf1680dda6f379f61f91afe327034e2aa82e202
-README.zh.md: bb5c9cd610c4051e586d9ad323c36305613d6c20
+README.md: fcbe4859954efa20f41a5a7e26bc0f1406cbe7f8
+README.zh.md: 304b95c4fa47ced455411b03529b77956cfb2953

packages/README.md

@@ -11,6 +11,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | Group | Role | Release expectation |
 |---|---|---|
 | [`core/`](core/README.md) | Product API spine: sessions, prompts, tools, agent services, and the concrete loop | Product — stable surface |
+| [`api/`](api/README.md) | Remote BFF assembly and TypeRT RPC gateway | Product — stable surface |
 | [`typert/`](typert/README.md) | Type graph generation, artifact loading, and runtime registry | Product — stable surface |
 | [`goal/`](goal/README.md) | Same-session goal persistence and lifecycle | Product — stable surface |
 | [`feedback/`](feedback/README.md) | Human feedback | Product — stable surface |

packages/README.zh.md

@@ -11,6 +11,7 @@
 | 组 | 职责 | 发布预期 |
 |---|---|---|
 | [`core/`](core/README.md) | 产品 API 主干：会话、提示词、工具、agent（智能体）服务与具体循环 | 产品：稳定表面 |
+| [`api/`](api/README.md) | Remote BFF 装配与 TypeRT RPC Gateway | 产品：稳定表面 |
 | [`typert/`](typert/README.md) | 类型图生成、产物加载与运行时注册表 | 产品：稳定表面 |
 | [`goal/`](goal/README.md) | 同会话 goal 的持久化与生命周期 | 产品：稳定表面 |
 | [`feedback/`](feedback/README.md) | 人类反馈 | 产品：稳定表面 |

packages/api/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/api/README.md
+README.md: 7c75e8012459266e0ce09c97416d140e5ac777e1
+README.zh.md: 87bd15fc4e5ad23ef785f7c9ee805a4aa1a35e46

packages/api/README.md

@@ -0,0 +1,17 @@
+# api/ — Remote API layers
+
+English | [中文](README.zh.md)
+
+The application-facing Remote stack. `remotes` owns BFF policy and the selected business API, while `gateway` implements the TypeRT unary RPC endpoints shared by Host and Client environments.
+
+| Package | Role | ctx key |
+|---|---|---|
+| [`remotes/`](remotes/README.md) | Host Agent/Session lookup policy and Client Remote contribution assembly | no service; configures `ctx.typert` and consumes `ctx.remote` |
+| [`gateway/`](gateway/README.md) | Host TypeRT dispatcher and Client Remote endpoint | `ctx.typertGateway` / `ctx.remote` |
+
+The runtime dependency direction is `remotes → gateway → connection → webserver`: the BFF consumes the shared `TypeRTClientRemote` contract, Gateway delegates transport to Connection, and Connection mounts on the HTTP server. Cordis service injection and Client module metadata preserve this order without importing the concrete Gateway from the Remotes Client entry.
+
+## Known Limitations and Deferred Work
+
+- Connection and WebServer remain at [`client/connection`](../client/connection/README.md) and [`host/webserver`](../host/webserver/README.md); a later package-only move can place them under `api/connection` and `api/webserver` without changing their service contracts.
+- The legacy API Proxy remains at [`host/apiproxy`](../host/apiproxy/README.md) as the fallback for methods not yet migrated to Remote. It consumes the Host resolver owned by `api-remotes` so migrated and legacy methods retain one Agent/Session identity policy.

packages/api/README.zh.md

@@ -0,0 +1,17 @@
+# api/：Remote API 层
+
+[English](README.md) | 中文
+
+面向应用的 Remote 技术栈。`remotes` 负责 BFF 策略和选定的业务 API，`gateway` 则实现 Host 与 Client 环境共用的 TypeRT 一元 RPC endpoint。
+
+| 包 | 职责 | ctx key |
+|---|---|---|
+| [`remotes/`](remotes/README.md) | Host Agent/Session lookup 策略与 Client Remote contribution 装配 | 无服务；配置 `ctx.typert` 并消费 `ctx.remote` |
+| [`gateway/`](gateway/README.md) | Host TypeRT 分发器与 Client Remote endpoint | `ctx.typertGateway` / `ctx.remote` |
+
+运行时依赖方向为 `remotes → gateway → connection → webserver`：BFF 消费共享的 `TypeRTClientRemote` 契约，Gateway 把传输交给 Connection，Connection 再挂载到 HTTP server。Cordis 服务注入与 Client 模块元数据在不让 Remotes Client 入口导入具体 Gateway 实现的前提下维持该顺序。
+
+## 已知限制与延期工作
+
+- Connection 与 WebServer 仍位于 [`client/connection`](../client/connection/README.md) 和 [`host/webserver`](../host/webserver/README.md)；后续可以只移动包，将它们放到 `api/connection` 和 `api/webserver` 下，而无需改变服务契约。
+- 旧 API Proxy 仍位于 [`host/apiproxy`](../host/apiproxy/README.md)，作为尚未迁移到 Remote 的方法的回退路径。它使用由 `api-remotes` 持有的 Host resolver，使已迁移与旧方法共用同一套 Agent/Session 身份策略。

packages/api/gateway/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/api/gateway/README.md
+README.md: 0e1a03d2016b8cfbe165dbf1b0a9802290b29502
+README.zh.md: 6b5ccff2340405cc0045147239c5bd4f3eead7da

packages/api/gateway/README.md

@@ -0,0 +1,39 @@
+# @deepseek-ai/dsh-api-gateway
+
+English | [中文](README.zh.md)
+
+Two-sided TypeRT RPC endpoint for Host and Client Cordis environments. The Host entry provides `ctx.typertGateway`, while `@deepseek-ai/dsh-api-gateway/client` provides `ctx.remote`; both consume the same generated `InvocationDescriptor` contract and leave business selection to API Remotes and transport, request correlation, trust, and response envelopes to Connection.
+
+## Host service: `TypertGatewayService` (ctx key: `typertGateway`)
+
+`ctx.typertGateway.invoke()` resolves the current descriptor and Cordis Service for each call, validates exact named arguments, resolves registered object or Context identities, invokes the public business method, and validates its result. Business Services extend `GatewayService` and mark methods with `@Remote` or `@RemoteScope` from [`dsh-type-meta`](../../typert/type-meta/README.md); `bindTypeRTGateway()` remains available when another base class owns inheritance.
+
+Strict mode reads generated invocation descriptors from `ctx.typert.local`. Lookup parameters use the currently active resolver in `ctx.typert.lookups`: the business package registers the stable declaration and default policy, while Host composition can override resolution behavior with effect-scoped `configure()`; `@RemoteScope` resolves its receiver through a registered Host Context provider. SRC mode is a development fallback for endpoints that have never had a strict definition; it parses simple parameter names and accepts only JSON-safe values for non-lookup parameters. Withdrawing an observed strict definition fails instead of weakening validation.
+
+The Host entry registers a trusted-host interceptor on Connection's shared `/api` FetchHandler. Connection passes this composite handler through its HTTP bridge; the handler dispatches claimed endpoints to Gateway and unclaimed endpoints to API Proxy. Direct `invoke()` calls preserve business errors; `TypertGatewayError` distinguishes failures owned by dispatch, binding, providers, lookup, Context, arguments, and codecs. A resolver may use `TypeRTLookupFailure` to carry an existing RPC error, preserving its original error code for policy rejections such as cold-resume failures or ownership fences.
+
+A cancellation-aware Remote method declares `signal: AbortSignal` as its final Host parameter. The signal is descriptor metadata rather than a wire argument: Connection supplies it to the Gateway, and the Gateway injects it after decoded business parameters. SRC recognizes the reserved final name, while strict generation additionally requires the global `AbortSignal` type.
+
+## Client service: `ClientRemote` (ctx key: `remote`)
+
+`ctx.remote.$mount()` validates and registers a generated Host-for-Client contribution, then installs concrete direct and scoped methods for the calling Cordis fiber. Each namespace is a traced `remote.<namespace>` child Service and unloads after its last method is withdrawn. Duplicate endpoints, namespace collisions, and descriptors without strict generated codecs fail before methods become callable.
+
+Each call validates positional inputs, constructs the descriptor's exact named `args`, and sends it through `ctx.connection.rpc.call('/api', endpoint, ...)`. Generated cancellation-aware methods accept a final optional `AbortSignal`; the Client combines it with the contribution mount lifetime before calling Connection. The returned value is validated before reaching application code. Withdrawing a contribution removes its descriptors and methods together, aborts in-flight calls, and makes retained method handles reject.
+
+Generated declaration merges provide the TypeScript API through the shared `TypeRTClientRemote` contract. The Client entry contains no Host Service or Host Cordis interface merge, and method lookup and invocation use ordinary objects and functions rather than a JavaScript Proxy.
+
+## Model Experience
+
+None, as the package dispatches application calls and registers no prompt, tool, or session event.
+
+#### KV Cache effect
+
+No direct effect; invoked business Services own any model-visible result.
+
+## Known Limitations and Deferred Work
+
+- The Connection adapter maps ordinary dispatch failures and business exceptions to the RPC `internal` code with empty details; lookup-policy errors carried by `TypeRTLookupFailure` are returned unchanged. Structured `TypertGatewayError` categories remain available only to same-process callers.
+- SRC mode supports unique identifier parameters without destructuring, defaults, or rest parameters. It validates JSON safety rather than generated business types and never infers optional fields.
+- Only strict generated contributions can mount on the Client face. SRC markers have no Client codec or type projection.
+- The package dispatches unary methods only. Incremental Session data uses a separate named-stream protocol over the same Connection.
+- Lookup resolvers are configured per key; an individual Remote parameter or endpoint cannot currently select a live-only policy under the same `agent`/`session` key.

packages/api/gateway/README.zh.md

@@ -0,0 +1,39 @@
+# @deepseek-ai/dsh-api-gateway
+
+[English](README.md) | 中文
+
+为 Host 与 Client 两侧的 Cordis 环境提供 TypeRT RPC endpoint。Host 入口提供 `ctx.typertGateway`，`@deepseek-ai/dsh-api-gateway/client` 则提供 `ctx.remote`；两者使用同一份生成的 `InvocationDescriptor` 契约，并将业务选择交给 API Remotes，将传输、请求关联、信任和响应封装交给 Connection。
+
+## Host 服务：`TypertGatewayService`（ctx key：`typertGateway`）
+
+每次调用时，`ctx.typertGateway.invoke()` 都会解析当前的描述符和 Cordis 服务，校验具名参数是否完全匹配，解析已注册的对象或 Context 身份标识，调用公开的业务方法，并校验其结果。业务服务继承 [`dsh-type-meta`](../../typert/type-meta/README.md) 的 `GatewayService`，并用 `@Remote` 或 `@RemoteScope` 标记方法；已有其他基类时仍可改用 `bindTypeRTGateway()`。
+
+严格模式从 `ctx.typert.local` 读取生成的调用描述符。查找参数使用 `ctx.typert.lookups` 中当前有效的 resolver：业务包注册稳定声明与默认策略，Host 组合可用 effect-scoped `configure()` 覆盖解析行为；`@RemoteScope` 则通过已注册的 Host Context 提供方解析其接收者。SRC 模式是开发阶段的回退路径，适用于从未具备严格定义的端点；它解析简单参数名，并且只允许非查找参数使用可安全表示为 JSON 的值。已观测到的严格定义一旦撤回，系统会直接报错，而不会降低校验强度。
+
+Connection 可用时，Host 入口会在 Connection 共享的 `/api` FetchHandler 上注册 trusted-host interceptor。Connection 把这个复合 handler 交给 HTTP bridge；handler 将已认领 endpoint 分发给 Gateway，未认领 endpoint 则交给 API Proxy。直接调用 `invoke()` 会保留业务错误；`TypertGatewayError` 可区分分发、绑定、提供方、查找、Context、参数和编解码器各自负责的故障。resolver 可以用 `TypeRTLookupFailure` 携带既有 RPC error，使冷恢复失败或 ownership fence 等策略拒绝保持原错误码。
+
+支持取消的 Remote 方法会把 `signal: AbortSignal` 声明为最后一个 Host 参数。signal 是 descriptor 元数据，而不是 wire 参数：Connection 将它提供给 Gateway，Gateway 则在已解码的业务参数之后注入它。SRC 识别这个保留的末位参数名，严格生成还要求它具有全局 `AbortSignal` 类型。
+
+## Client 服务：`ClientRemote`（ctx key：`remote`）
+
+`ctx.remote.$mount()` 会校验并注册生成的 Host-for-Client 贡献项，然后为发起调用的 Cordis fiber 安装具体的直接方法和作用域方法。每个 namespace 都是可追踪的 `remote.<namespace>` 子 Service，并在最后一个方法撤回后卸载。重复端点、命名空间冲突，以及缺少生成的严格编解码器的描述符，都会在方法可调用前报错。
+
+每次调用都会校验位置参数，构造与描述符完全匹配的具名 `args`，再通过 `ctx.connection.rpc.call('/api', endpoint, ...)` 发送。生成的支持取消的方法接受最后一个可选 `AbortSignal`；Client 会在调用 Connection 前将它与贡献项的挂载生命周期合并。返回值经过校验后才会交给应用代码。撤回贡献项会同时移除其描述符和方法、中止正在进行的调用，并使外部仍持有的方法句柄在调用时返回拒绝。
+
+生成的声明合并通过共享的 `TypeRTClientRemote` 契约提供 TypeScript API。Client 入口不包含 Host 服务或 Host Cordis 接口合并；方法查找和调用使用普通对象与函数，而不使用 JavaScript Proxy。
+
+## 模型体验
+
+无，因为该包分发应用调用，不注册任何提示词、工具或会话事件。
+
+#### KV Cache 影响
+
+无直接影响；被调用的业务服务负责产生任何模型可见结果。
+
+## 已知限制与延期工作
+
+- Connection 适配器将普通分发故障和业务异常映射为 RPC 的 `internal` 代码，且不附带详细信息；`TypeRTLookupFailure` 携带的 lookup 策略错误会原样返回。结构化的 `TypertGatewayError` 类别仅供同进程调用方使用。
+- SRC 模式仅支持名称唯一的标识符参数，不支持解构、默认值或剩余参数。它只校验值能否安全表示为 JSON，不校验生成的业务类型，也绝不会推断可选字段。
+- Client 侧只能挂载严格模式生成的贡献项。SRC 标记不具备 Client 编解码器或类型投影。
+- 该包只分发一元方法。增量会话数据通过同一个 Connection 上独立的具名流协议传输。
+- lookup resolver 按 key 配置；当前无法让单个 Remote 参数或 endpoint 在同一 `agent`/`session` key 下选择 live-only 策略。

packages/api/gateway/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@deepseek-ai/dsh-api-gateway",
+  "description": "TypeRT Remote Host dispatcher and Client API endpoint",
+  "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"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-typert-registry",
+      "@deepseek-ai/dsh-client-connection"
+    ],
+    "platform": "web",
+    "immediately": true
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-type-meta": "workspace:^"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-connection": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-typert-registry": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-host-webserver": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-typert-registry": "workspace:^",
+    "cordis": "^4.0.0-rc.7",
+    "zod": "^4.4.3"
+  }
+}

packages/api/gateway/src/client/index.ts

@@ -0,0 +1,498 @@
+/**
+ * Client projection of generated TypeRT Remote descriptors. Contributions
+ * install traced `remote.<namespace>` services; no JavaScript Proxy
+ * participates in method lookup, invocation, or type exposure.
+ */
+
+import { Service } from 'cordis'
+import type { Context } from 'cordis'
+import type { ConnectionHandle, RpcError } from '@deepseek-ai/dsh-client-connection/client'
+import type {
+  InvocationDescriptor,
+  TypeRTClientRemote,
+  TypeRTCodec,
+  TypeRTDisposer,
+  TypeRTRemoteContribution,
+} from '@deepseek-ai/dsh-type-meta'
+
+interface MountToken {
+  active: boolean
+  readonly abort: AbortController
+}
+
+interface ScopedProjection {
+  readonly context: string
+  readonly wire: string
+  readonly codec: TypeRTCodec
+  readonly parameterIndex?: number
+}
+
+interface DirectMethod {
+  readonly descriptor: InvocationDescriptor
+  readonly token: MountToken
+}
+
+interface ScopedMethod extends DirectMethod {
+  readonly projection: ScopedProjection
+}
+
+interface RemoteMethodRecord {
+  direct?: DirectMethod
+  scoped?: ScopedMethod
+}
+
+interface BoundContextIdentity {
+  readonly value: unknown
+}
+
+interface RemoteNamespaceHandle {
+  readonly service: RemoteNamespaceService
+  readonly dispose: TypeRTDisposer
+}
+
+/** Typed Remote service augmented by generated direct namespaces. */
+export type ClientRemote = TypeRTClientRemote
+
+declare module 'cordis' {
+  interface Context {
+    /** Generated Remote namespaces selected by the Client assembly. */
+    remote: ClientRemote
+  }
+}
+
+/** Required Client services: the TypeRT registry and the existing Connection carrier. */
+export const inject = ['typert', 'connection']
+
+/**
+ * Install the typed Client Remote service.
+ * @param ctx - Client Cordis root.
+ */
+export function apply(ctx: Context): void {
+  new ClientRemoteService(ctx)
+}
+
+class ClientRemoteService extends Service implements TypeRTClientRemote {
+  private readonly ownerCtx: Context
+  private readonly namespaces = new Map<string, RemoteNamespaceHandle>()
+  private mutations = Promise.resolve()
+
+  constructor(ctx: Context) {
+    super(ctx, 'remote')
+    this.ownerCtx = ctx
+  }
+
+  async $mount(contribution: TypeRTRemoteContribution): ReturnType<TypeRTClientRemote['$mount']> {
+    const callerCtx = this.ctx
+    const owned = callerCtx.effect(async () => {
+      const dispose = await this.enqueue(() => this.mountContribution(callerCtx, contribution))
+      return () => this.enqueue(dispose)
+    }, `api-gateway.client.$mount(${JSON.stringify(contribution.package)})`)
+    await owned
+    return async () => { await owned() }
+  }
+
+  private enqueue<T>(operation: () => T | Promise<T>): Promise<T> {
+    const result = this.mutations.then(operation, operation)
+    this.mutations = result.then(() => undefined, () => undefined)
+    return result
+  }
+
+  private async mountContribution(
+    callerCtx: Context,
+    contribution: TypeRTRemoteContribution,
+  ): Promise<TypeRTDisposer> {
+    this.validateContribution(contribution)
+    const disposeRemote = callerCtx.typert.remotes.register(contribution)
+    const installed: TypeRTDisposer[] = []
+    try {
+      for (const descriptor of contribution.descriptors) installed.push(await this.install(descriptor))
+    } catch (error) {
+      for (const dispose of installed.reverse()) await dispose()
+      await disposeRemote()
+      throw error
+    }
+    return async () => {
+      for (const dispose of installed.reverse()) await dispose()
+      await disposeRemote()
+    }
+  }
+
+  private validateContribution(contribution: TypeRTRemoteContribution): void {
+    const direct = new Map<string, Set<string>>()
+    const scoped = new Map<string, Set<string>>()
+    const add = (
+      table: Map<string, Set<string>>,
+      descriptor: InvocationDescriptor,
+      kind: 'direct' | 'scoped',
+    ): void => {
+      const methods = table.get(descriptor.namespace) ?? new Set<string>()
+      if (methods.has(descriptor.method)) {
+        throw new Error(`client api: contribution repeats ${kind} method ${endpointOf(descriptor)}`)
+      }
+      methods.add(descriptor.method)
+      table.set(descriptor.namespace, methods)
+      const namespace = this.namespaces.get(descriptor.namespace)?.service
+      if (namespace?.has(kind, descriptor.method) === true) {
+        throw new Error(`client api: ${kind} method ${endpointOf(descriptor)} is already mounted`)
+      }
+    }
+    for (const descriptor of contribution.descriptors) {
+      requireStrictDescriptor(descriptor)
+      if (descriptor.invocation.kind === 'direct') add(direct, descriptor, 'direct')
+      if (scopedProjection(descriptor) !== undefined) add(scoped, descriptor, 'scoped')
+    }
+    const namespaces = new Set([...direct.keys(), ...scoped.keys()])
+    for (const namespace of namespaces) {
+      const service = this.namespaces.get(namespace)?.service
+      if (service === undefined) {
+        if (namespace in this) {
+          throw new Error(`client api: namespace ${JSON.stringify(namespace)} conflicts with the Remote service`)
+        }
+        const serviceKey = remoteServiceKey(namespace)
+        const property = this.ownerCtx.reflect.props[serviceKey]
+        if (property?.type === 'accessor' || this.ownerCtx.get(serviceKey) !== undefined) {
+          throw new Error(`client api: namespace ${JSON.stringify(namespace)} conflicts with an existing Remote namespace`)
+        }
+      }
+      for (const method of new Set([...(direct.get(namespace) ?? []), ...(scoped.get(namespace) ?? [])])) {
+        if (service === undefined) RemoteNamespaceService.assertMethodAvailable(namespace, method)
+        else service.assertMethodAvailable(method)
+      }
+    }
+  }
+
+  private async install(descriptor: InvocationDescriptor): Promise<TypeRTDisposer> {
+    const token: MountToken = { active: true, abort: new AbortController() }
+    const installed: TypeRTDisposer[] = []
+    try {
+      if (descriptor.invocation.kind === 'direct') {
+        installed.push(await this.installDirect(descriptor, token))
+      }
+      const projection = scopedProjection(descriptor)
+      if (projection !== undefined) installed.push(await this.installScoped(descriptor, projection, token))
+    } catch (error) {
+      token.active = false
+      token.abort.abort()
+      for (const dispose of installed.reverse()) await dispose()
+      throw error
+    }
+    return async () => {
+      /* v8 ignore next -- Cordis effect disposers are idempotent and invoke this cleanup at most once. */
+      if (!token.active) return
+      token.active = false
+      token.abort.abort()
+      for (const dispose of installed.reverse()) await dispose()
+    }
+  }
+
+  private async installDirect(descriptor: InvocationDescriptor, token: MountToken): Promise<TypeRTDisposer> {
+    const namespace = await this.namespace(descriptor.namespace)
+    try {
+      namespace.service.installDirect(descriptor, token)
+    } catch (error) {
+      await this.disposeNamespace(descriptor.namespace, namespace)
+      throw error
+    }
+    return async () => {
+      namespace.service.remove('direct', descriptor.method, token)
+      await this.disposeNamespace(descriptor.namespace, namespace)
+    }
+  }
+
+  private async installScoped(
+    descriptor: InvocationDescriptor,
+    projection: ScopedProjection,
+    token: MountToken,
+  ): Promise<TypeRTDisposer> {
+    const namespace = await this.namespace(descriptor.namespace)
+    try {
+      namespace.service.installScoped(descriptor, projection, token)
+    } catch (error) {
+      await this.disposeNamespace(descriptor.namespace, namespace)
+      throw error
+    }
+    return async () => {
+      namespace.service.remove('scoped', descriptor.method, token)
+      await this.disposeNamespace(descriptor.namespace, namespace)
+    }
+  }
+
+  private async namespace(name: string): Promise<RemoteNamespaceHandle> {
+    let namespace = this.namespaces.get(name)
+    if (namespace !== undefined) return namespace
+    let service: RemoteNamespaceService | undefined
+    const fiber = this.ownerCtx.plugin({
+      name: remoteServiceKey(name),
+      apply: (ctx: Context) => {
+        service = new RemoteNamespaceService(
+          ctx,
+          name,
+          (direct, scoped, caller, args) => this.invokeMethod(direct, scoped, caller, args),
+        )
+      },
+    })
+    try {
+      await fiber
+    } catch (error) {
+      await fiber.dispose()
+      throw error
+    }
+    /* v8 ignore next -- a settled namespace fiber synchronously constructs its Service. */
+    if (service === undefined) throw new Error(`client api: namespace ${JSON.stringify(name)} did not start`)
+    namespace = { service, dispose: fiber.dispose }
+    this.namespaces.set(name, namespace)
+    return namespace
+  }
+
+  private async disposeNamespace(name: string, namespace: RemoteNamespaceHandle): Promise<void> {
+    if (!namespace.service.empty || this.namespaces.get(name) !== namespace) return
+    this.namespaces.delete(name)
+    await namespace.dispose()
+  }
+
+  private invokeMethod(
+    direct: DirectMethod | undefined,
+    scoped: ScopedMethod | undefined,
+    callerCtx: Context,
+    values: readonly unknown[],
+  ): Promise<unknown> {
+    if (scoped !== undefined) {
+      const binder = this.ownerCtx.typert.contexts.getClient(scoped.projection.context)
+      const identity = binder?.identity(callerCtx)
+      if (identity !== undefined) {
+        return this.invoke(
+          scoped.descriptor,
+          scoped.projection,
+          scoped.token,
+          callerCtx,
+          values,
+          { value: identity },
+        )
+      }
+    }
+    if (direct !== undefined) {
+      return this.invoke(direct.descriptor, undefined, direct.token, callerCtx, values)
+    }
+    if (scoped !== undefined) {
+      return this.invoke(scoped.descriptor, scoped.projection, scoped.token, callerCtx, values)
+    }
+    throw new Error('client api: Remote method is no longer mounted')
+  }
+
+  private async invoke(
+    descriptor: InvocationDescriptor,
+    projection: ScopedProjection | undefined,
+    token: MountToken,
+    callerCtx: Context,
+    values: readonly unknown[],
+    boundIdentity?: BoundContextIdentity,
+  ): Promise<unknown> {
+    const endpoint = endpointOf(descriptor)
+    if (!token.active) throw new Error(`client api: Remote method ${endpoint} is no longer mounted`)
+    const expected = descriptor.parameters.length - (projection?.parameterIndex === undefined ? 0 : 1)
+    const hasCallerSignal = descriptor.cancellation !== undefined && values.length === expected + 1
+    if (values.length !== expected && !hasCallerSignal) {
+      const contract = descriptor.cancellation === undefined
+        ? `${String(expected)} argument(s)`
+        : `${String(expected)} business argument(s) plus an optional AbortSignal`
+      throw new Error(
+        `client api: ${endpoint} expected ${contract}, got ${String(values.length)}`,
+      )
+    }
+    const args = Object.create(null) as Record<string, unknown>
+    if (projection !== undefined) {
+      const binder = boundIdentity === undefined
+        ? this.ownerCtx.typert.contexts.getClient(projection.context)
+        : undefined
+      if (boundIdentity === undefined && binder === undefined) {
+        throw new Error(`client api: ${endpoint} has no Client Context binder for ${JSON.stringify(projection.context)}`)
+      }
+      const identity = boundIdentity === undefined
+        ? binder?.identity(callerCtx)
+        : boundIdentity.value
+      if (identity === undefined) {
+        throw new Error(`client api: ${endpoint} requires a ${JSON.stringify(projection.context)} Context`)
+      }
+      args[projection.wire] = parse(projection.codec, identity, endpoint, projection.wire)
+    }
+    let valueIndex = 0
+    descriptor.parameters.forEach((parameter, parameterIndex) => {
+      if (parameterIndex === projection?.parameterIndex) return
+      args[parameter.wire] = parse(parameter.codec, values[valueIndex], endpoint, parameter.wire)
+      valueIndex += 1
+    })
+    const connection = this.ownerCtx.get('connection') as ConnectionHandle | undefined
+    if (connection === undefined) throw new Error(`client api: ${endpoint} has no active Connection`)
+    const callerSignal = hasCallerSignal ? values[expected] as AbortSignal | undefined : undefined
+    const signal = callerSignal === undefined
+      ? token.abort.signal
+      : AbortSignal.any([token.abort.signal, callerSignal])
+    const result = await connection.rpc.call('/api', endpoint, { args }, signal)
+    if (!mountActive(token)) throw new Error(`client api: Remote method ${endpoint} was withdrawn during invocation`)
+    if (!result.ok) throw remoteFailure(endpoint, result.error)
+    return parse(descriptor.result, result.value, endpoint, 'result')
+  }
+}
+
+type InvokeRemote = (
+  direct: DirectMethod | undefined,
+  scoped: ScopedMethod | undefined,
+  callerCtx: Context,
+  args: readonly unknown[],
+) => Promise<unknown>
+
+class RemoteNamespaceService extends Service {
+  private readonly methods = new Map<string, RemoteMethodRecord>()
+  private readonly namespace: string
+
+  static assertMethodAvailable(namespace: string, method: string): void {
+    if (REMOTE_NAMESPACE_FIELDS.has(method) || method in RemoteNamespaceService.prototype) {
+      throw new Error(`client api: method ${JSON.stringify(`${namespace}/${method}`)} conflicts with its namespace service`)
+    }
+  }
+
+  constructor(
+    ctx: Context,
+    name: string,
+    private readonly invokeRemote: InvokeRemote,
+  ) {
+    super(ctx, remoteServiceKey(name))
+    this.namespace = name
+  }
+
+  assertMethodAvailable(method: string): void {
+    RemoteNamespaceService.assertMethodAvailable(this.namespace, method)
+    if (method in this && !this.methods.has(method)) {
+      throw new Error(`client api: method ${JSON.stringify(`${this.namespace}/${method}`)} conflicts with its namespace service`)
+    }
+  }
+
+  get empty(): boolean {
+    return this.methods.size === 0
+  }
+
+  has(kind: 'direct' | 'scoped', method: string): boolean {
+    return this.methods.get(method)?.[kind] !== undefined
+  }
+
+  installDirect(descriptor: InvocationDescriptor, token: MountToken): void {
+    this.install(descriptor.method, 'direct', { descriptor, token })
+  }
+
+  installScoped(descriptor: InvocationDescriptor, projection: ScopedProjection, token: MountToken): void {
+    this.install(descriptor.method, 'scoped', { descriptor, projection, token })
+  }
+
+  private install(method: string, kind: 'direct', value: DirectMethod): void
+  private install(method: string, kind: 'scoped', value: ScopedMethod): void
+  private install(method: string, kind: 'direct' | 'scoped', value: DirectMethod | ScopedMethod): void {
+    this.assertMethodAvailable(method)
+    let record = this.methods.get(method)
+    const fresh = record === undefined
+    record ??= {}
+    if (fresh) {
+      Object.defineProperty(this, method, {
+        configurable: true,
+        enumerable: true,
+        get: function (this: RemoteNamespaceService): (...args: unknown[]) => Promise<unknown> {
+          const callerCtx = this.ctx
+          const current = this.methods.get(method)
+          const direct = current?.direct
+          const scoped = current?.scoped
+          return (...args: unknown[]) => {
+            return this.invokeRemote(direct, scoped, callerCtx, args)
+          }
+        },
+      })
+      this.methods.set(method, record)
+    }
+    if (kind === 'direct') record.direct = value
+    else record.scoped = value as ScopedMethod
+  }
+
+  remove(kind: 'direct' | 'scoped', method: string, token: MountToken): void {
+    const record = this.methods.get(method)
+    const current = record?.[kind]
+    /* v8 ignore next -- duplicate live variants are rejected before installation, so no newer token can replace this one. */
+    if (record === undefined || current?.token !== token) return
+    if (kind === 'direct') delete record.direct
+    else delete record.scoped
+    if (record.direct !== undefined || record.scoped !== undefined) return
+    this.methods.delete(method)
+    Reflect.deleteProperty(this, method)
+  }
+}
+
+const REMOTE_NAMESPACE_FIELDS = new Set(['ctx', 'empty', 'invokeRemote', 'methods', 'name', 'namespace'])
+
+function remoteServiceKey(namespace: string): string {
+  return `remote.${namespace}`
+}
+
+function endpointOf(descriptor: Pick<InvocationDescriptor, 'namespace' | 'method'>): string {
+  return `${descriptor.namespace}/${descriptor.method}`
+}
+
+function mountActive(token: MountToken): boolean {
+  return token.active
+}
+
+function scopedProjection(descriptor: InvocationDescriptor): ScopedProjection | undefined {
+  if (descriptor.invocation.kind === 'context') {
+    return {
+      context: descriptor.invocation.context,
+      wire: descriptor.invocation.wire,
+      codec: descriptor.invocation.codec,
+    }
+  }
+  if (descriptor.scope === undefined) return undefined
+  const lookupParameters = descriptor.parameters
+    .map((parameter, index) => ({ parameter, index }))
+    .filter(candidate => candidate.parameter.source === 'lookup')
+  const selected = lookupParameters.length === 1 ? lookupParameters[0] : undefined
+  if (selected === undefined
+    || selected.parameter.wire !== descriptor.scope.wire
+    || selected.parameter.lookup !== descriptor.scope.context) {
+    throw new Error(
+      `client api: generated Remote ${endpointOf(descriptor)} scope must select its only lookup parameter`,
+    )
+  }
+  return {
+    context: descriptor.scope.context,
+    wire: descriptor.scope.wire,
+    codec: selected.parameter.codec,
+    parameterIndex: selected.index,
+  }
+}
+
+function requireStrictDescriptor(descriptor: InvocationDescriptor): void {
+  const endpoint = endpointOf(descriptor)
+  requireStrictCodec(descriptor.result, endpoint, 'result')
+  for (const parameter of descriptor.parameters) {
+    requireStrictCodec(parameter.codec, endpoint, parameter.wire)
+  }
+  if (descriptor.invocation.kind === 'context') {
+    requireStrictCodec(descriptor.invocation.codec, endpoint, descriptor.invocation.wire)
+  }
+}
+
+function requireStrictCodec(codec: TypeRTCodec, endpoint: string, field: string): void {
+  if (codec.mode !== 'strict') {
+    throw new Error(`client api: generated Remote ${endpoint} field ${JSON.stringify(field)} has no strict codec`)
+  }
+}
+
+function parse(codec: TypeRTCodec, value: unknown, endpoint: string, field: string): unknown {
+  if (codec.mode !== 'strict') {
+    throw new Error(`client api: generated Remote ${endpoint} field ${JSON.stringify(field)} has no strict codec`)
+  }
+  try {
+    return codec.schema.parse(value)
+  } catch (cause) {
+    throw new Error(`client api: ${endpoint} rejected ${JSON.stringify(field)}`, { cause })
+  }
+}
+
+function remoteFailure(endpoint: string, error: RpcError): Error {
+  return new Error(`client api: ${endpoint} failed: ${error.code}: ${error.message}`, { cause: error })
+}

packages/api/gateway/src/index.ts

@@ -0,0 +1,638 @@
+/**
+ * Live TypeRT Remote dispatch over Cordis Services and registered providers.
+ * Transport, request correlation, and response envelopes belong to Connection.
+ * @module @deepseek-ai/dsh-api-gateway
+ */
+
+import { Context, Service, symbols } from 'cordis'
+import type { ConnectionRpcHandler } from '@deepseek-ai/dsh-client-connection'
+import {
+  remoteMethods,
+  TypeRTLookupFailure,
+  type InvocationDescriptor,
+  type InvocationParameterDescriptor,
+  type TypeRTCodec,
+  type TypeRTGatewayBinding,
+} from '@deepseek-ai/dsh-type-meta'
+import type {
+  InvokeRemoteRequest,
+  TypertGateway,
+  TypertGatewayErrorCode,
+} from './types.ts'
+
+export type {
+  InvokeRemoteRequest,
+  TypertGateway,
+  TypertGatewayErrorCode,
+} from './types.ts'
+
+interface GatewayErrorOptions {
+  readonly cause?: unknown
+  readonly field?: string
+}
+
+interface ResolvedBinding {
+  readonly binding: TypeRTGatewayBinding
+  readonly original: object
+}
+
+type ConnectionRpcResult = Awaited<ReturnType<ConnectionRpcHandler>>
+type ConnectionRpcError = Extract<ConnectionRpcResult, { readonly ok: false }>['error']
+const NEVER_ABORTED_SIGNAL = new AbortController().signal
+
+/** Dispatch failure produced outside the invoked business method. */
+export class TypertGatewayError extends Error {
+  /** Machine-readable failure category. */
+  readonly code: TypertGatewayErrorCode
+  /** Canonical `<namespace>/<method>` endpoint. */
+  readonly endpoint: string
+  /** Affected wire field when the failure is field-specific. */
+  readonly field: string | undefined
+
+  /**
+   * Construct a Gateway failure without embedding boundary values in its message.
+   * @param code - stable failure category.
+   * @param endpoint - canonical Remote endpoint.
+   * @param message - correction-oriented diagnostic without sensitive values.
+   * @param options - optional field and contained cause.
+   */
+  constructor(
+    code: TypertGatewayErrorCode,
+    endpoint: string,
+    message: string,
+    options: GatewayErrorOptions = {},
+  ) {
+    super(`typert gateway: ${endpoint}: ${message}`, options.cause === undefined ? undefined : { cause: options.cause })
+    this.name = 'TypertGatewayError'
+    this.code = code
+    this.endpoint = endpoint
+    this.field = options.field
+  }
+}
+
+/**
+ * Resolve strict generated definitions or conservative SRC markers against
+ * current Cordis Services and TypeRT providers.
+ * @typert service typertGateway
+ */
+export class TypertGatewayService extends Service implements TypertGateway {
+  static inject = ['typert']
+
+  private srcClaims: ReadonlySet<string> | undefined
+
+  /**
+   * Register the Gateway against the active TypeRT registry.
+   * @param ctx - owning Host Context with TypeRT registry access.
+   */
+  constructor(ctx: Context) {
+    super(ctx, 'typertGateway')
+    ctx.on('internal/service', () => {
+      this.srcClaims = undefined
+    })
+    ctx.inject(['connection'], (connectionCtx) => {
+      connectionCtx.connection.rpc.intercept(
+        '/api',
+        endpoint => this.claimsEndpoint(endpoint),
+        (endpoint, payload, signal) => this.dispatchRpc(endpoint, payload, signal),
+        { authority: 'trusted-host' },
+      )
+    })
+  }
+
+  private claimsEndpoint(endpoint: string): boolean {
+    const segments = endpoint.split('/')
+    if (segments.length !== 2 || segments[0] === '' || segments[1] === '') return false
+    if (this.ctx.typert.local.get(endpoint) !== undefined || this.ctx.typert.local.hasSeen(endpoint)) return true
+    this.srcClaims ??= this.collectSrcClaims()
+    return this.srcClaims.has(endpoint)
+  }
+
+  private collectSrcClaims(): ReadonlySet<string> {
+    const claims = new Set<string>()
+    for (const [serviceKey, definition] of Object.entries(this.ctx.reflect.props)) {
+      if (definition.type !== 'service') continue
+      const receiver = this.ctx.get(serviceKey) as unknown
+      if (!isObject(receiver)) continue
+      const original = originalOf(receiver)
+      const binding = Reflect.get(original, 'typertGateway') as unknown
+      if (!isObject(binding) || typeof Reflect.get(binding, 'namespace') !== 'string') continue
+      const namespace = Reflect.get(binding, 'namespace') as string
+      for (const candidate of remoteMethods(original)) {
+        claims.add(endpointOf(namespace, candidate.exportName ?? candidate.method))
+      }
+    }
+    return claims
+  }
+
+  /**
+   * Invoke one live Remote method through strict generated reflection or SRC markers.
+   * @param request - decoded endpoint and exact named wire arguments.
+   * @returns the validated business result.
+   * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; lookup-policy and business errors retain identity.
+   */
+  async invoke(request: InvokeRemoteRequest): Promise<unknown> {
+    const endpoint = endpointOf(request.namespace, request.method)
+    const descriptor = this.resolveDescriptor(request.namespace, request.method, endpoint)
+    assertExactArguments(request.args, descriptor, endpoint)
+    const receiverContext = await this.resolveReceiverContext(descriptor, request.args, endpoint)
+    const receiver = receiverContext.get(descriptor.service) as unknown
+    if (!isObject(receiver)) {
+      throw new TypertGatewayError(
+        'service-unavailable',
+        endpoint,
+        `active Service ${JSON.stringify(descriptor.service)} is unavailable`,
+      )
+    }
+    validateBinding(receiver, descriptor.service, descriptor.namespace, endpoint)
+    const args = await Promise.all(descriptor.parameters.map(parameter =>
+      this.resolveParameter(parameter, request.args, endpoint)))
+    if (descriptor.cancellation !== undefined) args.push(request.signal ?? NEVER_ABORTED_SIGNAL)
+    const implementation = descriptor.implementation ?? descriptor.method
+    const method = Reflect.get(receiver, implementation) as unknown
+    if (typeof method !== 'function') {
+      throw new TypertGatewayError(
+        'method-unavailable',
+        endpoint,
+        `active Service ${JSON.stringify(descriptor.service)} has no callable method ${JSON.stringify(implementation)}`,
+      )
+    }
+
+    const result = await Reflect.apply(method, receiver, args) as unknown
+    return decode(descriptor.result, result, 'result-invalid', endpoint, 'result')
+  }
+
+  private async dispatchRpc(
+    endpoint: string,
+    payload: unknown,
+    signal: AbortSignal,
+  ): Promise<ConnectionRpcResult> {
+    return this.invokeRpc(endpoint, payload, signal)
+  }
+
+  private async invokeRpc(endpoint: string, payload: unknown, signal: AbortSignal): Promise<ConnectionRpcResult> {
+    try {
+      const segments = endpoint.split('/')
+      if (segments.length !== 2 || segments[0] === '' || segments[1] === '') {
+        throw new Error(`invalid Remote endpoint ${JSON.stringify(endpoint)}`)
+      }
+      const [namespace, method] = segments as [string, string]
+      if (!isObject(payload)
+        || !isPlainObject(payload)
+        || Reflect.ownKeys(payload).length !== 1
+        || !Object.hasOwn(payload, 'args')
+        || !isObject(payload.args)
+        || !isPlainObject(payload.args)) {
+        throw new Error('Remote payload must contain exactly one plain-object args field')
+      }
+      const value = await this.invoke({
+        namespace,
+        method,
+        args: payload.args,
+        signal,
+      })
+      return { ok: true, value }
+    } catch (error) {
+      return rpcFailure(error)
+    }
+  }
+
+  private resolveDescriptor(namespace: string, method: string, endpoint: string): InvocationDescriptor {
+    const strict = this.ctx.typert.local.get(endpoint)
+    if (strict !== undefined) return strict
+    if (this.ctx.typert.local.hasSeen(endpoint)) {
+      throw new TypertGatewayError(
+        'definition-unavailable',
+        endpoint,
+        'its strict definition was withdrawn and SRC fallback is forbidden',
+      )
+    }
+    return this.resolveSrcDescriptor(namespace, method, endpoint)
+  }
+
+  private resolveSrcDescriptor(namespace: string, method: string, endpoint: string): InvocationDescriptor {
+    const candidates: InvocationDescriptor[] = []
+    for (const [serviceKey, definition] of Object.entries(this.ctx.reflect.props)) {
+      if (definition.type !== 'service') continue
+      const receiver = this.ctx.get(serviceKey) as unknown
+      if (!isObject(receiver)) continue
+      const original = originalOf(receiver)
+      const value = Reflect.get(original, 'typertGateway') as unknown
+      if (value === undefined) continue
+      const binding = readBinding(value, original, serviceKey, endpoint)
+      if (binding.namespace !== namespace) continue
+      const marker = remoteMethods(original).find(candidate => (candidate.exportName ?? candidate.method) === method)
+      if (marker === undefined) continue
+      candidates.push(this.srcDescriptor(binding, marker, method, endpoint))
+    }
+    if (candidates.length === 0) {
+      throw new TypertGatewayError('invocation-unavailable', endpoint, 'no active Remote method exports this endpoint')
+    }
+    if (candidates.length > 1) {
+      throw new TypertGatewayError(
+        'ambiguous-endpoint',
+        endpoint,
+        `multiple active Services export this endpoint: ${candidates.map(candidate => candidate.service).sort().join(', ')}`,
+      )
+    }
+    return candidates[0] as InvocationDescriptor
+  }
+
+  private srcDescriptor(
+    binding: TypeRTGatewayBinding,
+    marker: ReturnType<typeof remoteMethods>[number],
+    method: string,
+    endpoint: string,
+  ): InvocationDescriptor {
+    const names = methodParameterNames(binding.service, marker.method, endpoint)
+    const signalIndex = names.indexOf('signal')
+    if (signalIndex >= 0 && signalIndex !== names.length - 1) {
+      throw new TypertGatewayError(
+        'signature-invalid',
+        endpoint,
+        'SRC cancellation parameter signal must be the final parameter',
+        { field: 'signal' },
+      )
+    }
+    const cancellation = signalIndex >= 0
+      ? { parameter: 'signal' as const }
+      : undefined
+    const businessNames = cancellation === undefined ? names : names.slice(0, -1)
+    const parameters: InvocationParameterDescriptor[] = []
+    const wires = new Set<string>()
+    for (const name of businessNames) {
+      const matches = this.ctx.typert.lookups.definitions()
+        .filter(definition => definition.parameter === name)
+      if (matches.length > 1) {
+        throw new TypertGatewayError(
+          'signature-invalid',
+          endpoint,
+          `parameter ${JSON.stringify(name)} matches multiple lookup providers`,
+          { field: name },
+        )
+      }
+      const match = matches[0]
+      const parameter: InvocationParameterDescriptor = match === undefined
+        ? { name, wire: name, source: 'json', codec: { mode: 'src-json' } }
+        : {
+          name,
+          wire: match.wire,
+          source: 'lookup',
+          lookup: match.key,
+          codec: { mode: 'src-json' },
+        }
+      if (wires.has(parameter.wire)) {
+        throw new TypertGatewayError(
+          'signature-invalid',
+          endpoint,
+          `multiple parameters use wire field ${JSON.stringify(parameter.wire)}`,
+          { field: parameter.wire },
+        )
+      }
+      wires.add(parameter.wire)
+      parameters.push(parameter)
+    }
+
+    let receiver: InvocationDescriptor['invocation'] = { kind: 'direct' }
+    if (marker.invocation.kind === 'context') {
+      const provider = this.ctx.typert.contexts.getHost(marker.invocation.context)
+      if (provider === undefined) {
+        throw new TypertGatewayError(
+          'context-unavailable',
+          endpoint,
+          `Context provider ${JSON.stringify(marker.invocation.context)} is unavailable`,
+        )
+      }
+      if (wires.has(provider.wire)) {
+        throw new TypertGatewayError(
+          'signature-invalid',
+          endpoint,
+          `Context identity conflicts with wire field ${JSON.stringify(provider.wire)}`,
+          { field: provider.wire },
+        )
+      }
+      receiver = {
+        kind: 'context',
+        context: marker.invocation.context,
+        wire: provider.wire,
+        codec: { mode: 'src-json' },
+      }
+    }
+
+    return {
+      id: `src:${binding.serviceKey}#${endpoint}`,
+      service: binding.serviceKey,
+      namespace: binding.namespace,
+      method,
+      ...(marker.method === method ? {} : { implementation: marker.method }),
+      invocation: receiver,
+      parameters,
+      ...(cancellation === undefined ? {} : { cancellation }),
+      result: { mode: 'src-json' },
+    }
+  }
+
+  private async resolveReceiverContext(
+    descriptor: InvocationDescriptor,
+    args: Readonly<Record<string, unknown>>,
+    endpoint: string,
+  ): Promise<Context> {
+    if (descriptor.invocation.kind === 'direct') return this.ctx
+    const invocation = descriptor.invocation
+    const provider = this.ctx.typert.contexts.getHost(invocation.context)
+    if (provider === undefined) {
+      throw new TypertGatewayError(
+        'context-unavailable',
+        endpoint,
+        `Context provider ${JSON.stringify(invocation.context)} is unavailable`,
+      )
+    }
+    if (provider.wire !== invocation.wire
+      || (invocation.codec.mode === 'strict' && provider.wireTypeSymbol !== invocation.codec.typeSymbol)) {
+      throw new TypertGatewayError(
+        'provider-mismatch',
+        endpoint,
+        `Context provider ${JSON.stringify(invocation.context)} does not match its strict definition`,
+        { field: invocation.wire },
+      )
+    }
+    const identity = decode(invocation.codec, args[invocation.wire], 'input-invalid', endpoint, invocation.wire)
+    let context: Context | undefined
+    try {
+      context = await provider.resolve(identity)
+    } catch (cause) {
+      if (cause instanceof TypeRTLookupFailure) throw cause
+      throw new TypertGatewayError(
+        'context-failed',
+        endpoint,
+        `Context provider ${JSON.stringify(invocation.context)} failed`,
+        { cause, field: invocation.wire },
+      )
+    }
+    if (context === undefined) {
+      throw new TypertGatewayError(
+        'context-not-found',
+        endpoint,
+        `Context provider ${JSON.stringify(invocation.context)} did not resolve the requested identity`,
+        { field: invocation.wire },
+      )
+    }
+    return context
+  }
+
+  private async resolveParameter(
+    parameter: InvocationParameterDescriptor,
+    args: Readonly<Record<string, unknown>>,
+    endpoint: string,
+  ): Promise<unknown> {
+    const value = decode(parameter.codec, args[parameter.wire], 'input-invalid', endpoint, parameter.wire)
+    if (parameter.source === 'json') return value
+    const key = parameter.lookup
+    /* v8 ignore next -- registry validation rejects strict descriptors without a key, and SRC derivation always supplies one. */
+    if (key === undefined) {
+      throw new TypertGatewayError(
+        'lookup-unavailable',
+        endpoint,
+        `lookup parameter ${JSON.stringify(parameter.name)} has no provider key`,
+        { field: parameter.wire },
+      )
+    }
+    const provider = this.ctx.typert.lookups.get(key)
+    if (provider === undefined) {
+      throw new TypertGatewayError(
+        'lookup-unavailable',
+        endpoint,
+        `lookup provider ${JSON.stringify(key)} is unavailable`,
+        { field: parameter.wire },
+      )
+    }
+    if (provider.wire !== parameter.wire
+      || (parameter.codec.mode === 'strict' && provider.wireTypeSymbol !== parameter.codec.typeSymbol)) {
+      throw new TypertGatewayError(
+        'provider-mismatch',
+        endpoint,
+        `lookup provider ${JSON.stringify(key)} does not match its strict definition`,
+        { field: parameter.wire },
+      )
+    }
+    let resolved: unknown
+    try {
+      resolved = await provider.resolve(value)
+    } catch (cause) {
+      if (cause instanceof TypeRTLookupFailure) throw cause
+      throw new TypertGatewayError(
+        'lookup-failed',
+        endpoint,
+        `lookup provider ${JSON.stringify(key)} failed`,
+        { cause, field: parameter.wire },
+      )
+    }
+    if (resolved === undefined) {
+      throw new TypertGatewayError(
+        'lookup-not-found',
+        endpoint,
+        `lookup provider ${JSON.stringify(key)} did not resolve the requested identity`,
+        { field: parameter.wire },
+      )
+    }
+    return resolved
+  }
+}
+
+function rpcFailure(error: unknown): ConnectionRpcResult {
+  if (error instanceof TypeRTLookupFailure) {
+    return { ok: false, error: error.failure as ConnectionRpcError }
+  }
+  return {
+    ok: false,
+    error: {
+      code: 'internal',
+      message: error instanceof Error ? error.message : String(error),
+      details: {},
+    },
+  }
+}
+
+function endpointOf(namespace: string, method: string): string {
+  return `${namespace}/${method}`
+}
+
+function validateBinding(
+  receiver: object,
+  serviceKey: string,
+  namespace: string,
+  endpoint: string,
+): ResolvedBinding {
+  const original = originalOf(receiver)
+  const value = Reflect.get(original, 'typertGateway') as unknown
+  if (value === undefined) {
+    throw new TypertGatewayError(
+      'binding-invalid',
+      endpoint,
+      `Service ${JSON.stringify(serviceKey)} has no visible typertGateway binding`,
+    )
+  }
+  return {
+    binding: readBinding(value, original, serviceKey, endpoint, namespace),
+    original,
+  }
+}
+
+function readBinding(
+  value: unknown,
+  original: object,
+  serviceKey: string,
+  endpoint: string,
+  namespace?: string,
+): TypeRTGatewayBinding {
+  if (!isObject(value)
+    || Reflect.get(value, 'service') !== original
+    || Reflect.get(value, 'serviceKey') !== serviceKey
+    || typeof Reflect.get(value, 'namespace') !== 'string'
+    || (namespace !== undefined && Reflect.get(value, 'namespace') !== namespace)) {
+    throw new TypertGatewayError(
+      'binding-invalid',
+      endpoint,
+      `Service ${JSON.stringify(serviceKey)} has an inconsistent typertGateway binding`,
+    )
+  }
+  return value as unknown as TypeRTGatewayBinding
+}
+
+function originalOf(receiver: object): object {
+  const original = Reflect.get(receiver, symbols.original) as unknown
+  return isObject(original) ? original : receiver
+}
+
+function methodParameterNames(service: object, method: string, endpoint: string): readonly string[] {
+  let prototype: object | null = Object.getPrototypeOf(service) as object | null
+  let implementation: ((this: object, ...args: never[]) => unknown) | undefined
+  while (prototype !== null) {
+    const descriptor = Object.getOwnPropertyDescriptor(prototype, method)
+    if (descriptor !== undefined) {
+      if ('value' in descriptor && typeof descriptor.value === 'function') {
+        implementation = descriptor.value as (this: object, ...args: never[]) => unknown
+      }
+      break
+    }
+    prototype = Object.getPrototypeOf(prototype) as object | null
+  }
+  if (implementation === undefined) {
+    throw new TypertGatewayError(
+      'method-unavailable',
+      endpoint,
+      `Remote marker has no prototype method ${JSON.stringify(method)}`,
+    )
+  }
+  const source = Function.prototype.toString.call(implementation)
+  const open = source.indexOf('(')
+  const close = source.indexOf(')', open + 1)
+  /* v8 ignore next -- standard public class-method syntax always contains a parenthesized parameter list. */
+  if (open < 0 || close < 0) return invalidSignature(endpoint, method)
+  const body = source.slice(open + 1, close).trim()
+  if (body.length === 0) return []
+  const parts = body.split(',').map(part => part.trim())
+  const names = new Set<string>()
+  for (const part of parts) {
+    if (!/^[$A-Z_a-z][$\w]*$/u.test(part) || names.has(part)) return invalidSignature(endpoint, method)
+    names.add(part)
+  }
+  return [...names]
+}
+
+function invalidSignature(endpoint: string, method: string): never {
+  throw new TypertGatewayError(
+    'signature-invalid',
+    endpoint,
+    `SRC method ${JSON.stringify(method)} must use unique identifier parameters without destructuring, defaults, or rest`,
+  )
+}
+
+function assertExactArguments(
+  args: Readonly<Record<string, unknown>>,
+  descriptor: InvocationDescriptor,
+  endpoint: string,
+): void {
+  if (!isPlainObject(args)) {
+    throw new TypertGatewayError('arguments-invalid', endpoint, 'args must be a plain object')
+  }
+  const expected = new Set(descriptor.parameters.map(parameter => parameter.wire))
+  if (descriptor.invocation.kind === 'context') expected.add(descriptor.invocation.wire)
+  const actual = Reflect.ownKeys(args)
+  const extra = actual.filter(key => typeof key !== 'string' || !expected.has(key))
+  const missing = [...expected].filter(key => !Object.hasOwn(args, key))
+  if (extra.length === 0 && missing.length === 0) return
+  const clauses: string[] = []
+  if (missing.length > 0) clauses.push(`missing ${missing.map(key => JSON.stringify(key)).join(', ')}`)
+  if (extra.length > 0) clauses.push(`unexpected ${extra.map(key => JSON.stringify(String(key))).join(', ')}`)
+  throw new TypertGatewayError('arguments-invalid', endpoint, `args fields do not match the descriptor: ${clauses.join('; ')}`)
+}
+
+function decode(
+  codec: TypeRTCodec,
+  value: unknown,
+  code: 'input-invalid' | 'result-invalid',
+  endpoint: string,
+  field: string,
+): unknown {
+  try {
+    if (codec.mode === 'strict') value = codec.schema.parse(value)
+    assertJsonValue(value, new Set())
+    return value
+  } catch (cause) {
+    throw new TypertGatewayError(
+      code,
+      endpoint,
+      code === 'input-invalid'
+        ? `wire field ${JSON.stringify(field)} failed boundary validation`
+        : 'business result failed boundary validation',
+      { cause, field },
+    )
+  }
+}
+
+function assertJsonValue(value: unknown, ancestors: Set<object>): void {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return
+  if (typeof value === 'number') {
+    if (Number.isFinite(value)) return
+    throw new TypeError('non-finite number is not JSON-safe')
+  }
+  if (!isObject(value)) throw new TypeError(`${typeof value} is not JSON-safe`)
+  if (ancestors.has(value)) throw new TypeError('cyclic value is not JSON-safe')
+  ancestors.add(value)
+  try {
+    if (Array.isArray(value)) {
+      if (Object.getOwnPropertySymbols(value).length > 0 || Object.keys(value).length !== value.length) {
+        throw new TypeError('sparse or decorated array is not JSON-safe')
+      }
+      for (let index = 0; index < value.length; index += 1) {
+        if (!Object.hasOwn(value, index)) throw new TypeError('sparse array is not JSON-safe')
+        assertJsonValue(value[index], ancestors)
+      }
+      return
+    }
+    if (!isPlainObject(value)) throw new TypeError('non-plain object is not JSON-safe')
+    if (Object.getOwnPropertySymbols(value).length > 0) throw new TypeError('symbol property is not JSON-safe')
+    for (const key of Reflect.ownKeys(value)) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key)
+      /* v8 ignore next -- ownKeys() just returned this key; only a hostile same-process Proxy can delete it between operations. */
+      if (descriptor === undefined || !descriptor.enumerable || !('value' in descriptor)) {
+        throw new TypeError('non-data property is not JSON-safe')
+      }
+      assertJsonValue(descriptor.value, ancestors)
+    }
+  } finally {
+    ancestors.delete(value)
+  }
+}
+
+function isPlainObject(value: object): value is Record<string, unknown> {
+  if (Array.isArray(value)) return false
+  const prototype = Object.getPrototypeOf(value) as object | null
+  return prototype === null || prototype === Object.prototype
+}
+
+function isObject(value: unknown): value is object {
+  return (typeof value === 'object' && value !== null) || typeof value === 'function'
+}
+
+export default TypertGatewayService

packages/api/gateway/src/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-api-gateway`.
+ * @module @deepseek-ai/dsh-api-gateway/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-api-gateway'
+
+/** Cordis companion plugin name. */
+export const name = 'api-gateway-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: Host calls re-read authoritative Cordis and TypeRT
+ * state, while Client methods and descriptors mutate in one owned effect.
+ */
+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/api/gateway/src/types.ts

@@ -0,0 +1,54 @@
+/**
+ * Carrier-independent TypeRT Gateway request, service, and error contracts.
+ * @module @deepseek-ai/dsh-api-gateway/types
+ */
+
+/** One Remote method request after a carrier has decoded its envelope. */
+export interface InvokeRemoteRequest {
+  /** Remote namespace selected by the generated descriptor. */
+  readonly namespace: string
+  /** Exported Service method name. */
+  readonly method: string
+  /** Named wire values; fields must exactly match the descriptor. */
+  readonly args: Readonly<Record<string, unknown>>
+  /** Carrier or direct-caller cancellation injected only into cancellation-aware methods. */
+  readonly signal?: AbortSignal
+}
+
+/** Stable infrastructure and boundary failures emitted before or after business execution. */
+export type TypertGatewayErrorCode =
+  | 'ambiguous-endpoint'
+  | 'arguments-invalid'
+  | 'binding-invalid'
+  | 'context-failed'
+  | 'context-not-found'
+  | 'context-unavailable'
+  | 'definition-unavailable'
+  | 'input-invalid'
+  | 'invocation-unavailable'
+  | 'lookup-failed'
+  | 'lookup-not-found'
+  | 'lookup-unavailable'
+  | 'method-unavailable'
+  | 'provider-mismatch'
+  | 'result-invalid'
+  | 'service-unavailable'
+  | 'signature-invalid'
+
+/** Host dispatcher consumed by Connection adapters. */
+export interface TypertGateway {
+  /**
+   * Invoke one live Remote method without assuming a carrier or response envelope.
+   * @param request - decoded endpoint and named wire arguments.
+   * @returns the validated business result.
+   * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; lookup-policy and business errors retain identity.
+   */
+  invoke(request: InvokeRemoteRequest): Promise<unknown>
+}
+
+declare module 'cordis' {
+  interface Context {
+    /** Host dispatcher for TypeRT Remote calls. */
+    typertGateway: TypertGateway
+  }
+}

packages/api/gateway/tests/client.spec.ts

@@ -0,0 +1,573 @@
+import { Context, Service } from 'cordis'
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
+import type {
+  InvocationDescriptor,
+  TypeRTClientRemote,
+  TypeRTContext,
+  TypeRTRemoteScopeApi,
+  TypeRTRemoteNamespace,
+} from '@deepseek-ai/dsh-type-meta'
+import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
+import { apply, inject } from '../src/client/index.ts'
+
+declare module '@deepseek-ai/dsh-type-meta' {
+  interface TypeRTContextMap {
+    fixture: TypeRTContext<string>
+  }
+
+  interface TypeRTRemoteMap {
+    'goals/create': (
+      agentId: string,
+      request: { readonly objective: string },
+      signal?: AbortSignal,
+    ) => Promise<{ readonly ref: string }>
+  }
+
+  interface TypeRTRemoteScopeMap {
+    'fixture:goals/create': (
+      request: { readonly objective: string },
+      signal?: AbortSignal,
+    ) => Promise<{ readonly ref: string }>
+    'fixture:goals/rename': (request: { readonly objective: string }) => Promise<{ readonly renamed: boolean }>
+  }
+
+  interface TypeRTRemoteNamespaceMap {
+    goals: TypeRTRemoteNamespace<'goals'>
+  }
+
+}
+
+type FixtureContext = Omit<Context, 'remote'> & {
+  readonly remote: TypeRTClientRemote & TypeRTRemoteScopeApi<'fixture'>
+}
+
+const idSchema = z.string().min(1)
+const requestSchema = z.object({ objective: z.string().min(1) })
+const createResultSchema = z.object({ ref: z.string().min(1) })
+const renameResultSchema = z.object({ renamed: z.boolean() })
+
+function directDescriptor(): InvocationDescriptor {
+  return {
+    id: '@fixture/goals#goals/create',
+    service: 'goals',
+    namespace: 'goals',
+    method: 'create',
+    invocation: { kind: 'direct' },
+    scope: { context: 'fixture', wire: 'agentId' },
+    parameters: [{
+      name: 'agent',
+      wire: 'agentId',
+      source: 'lookup',
+      lookup: 'fixture',
+      codec: { mode: 'strict', typeSymbol: '@fixture#AgentId', schema: idSchema },
+    }, {
+      name: 'request',
+      wire: 'request',
+      source: 'json',
+      codec: { mode: 'strict', typeSymbol: '@fixture#CreateRequest', schema: requestSchema },
+    }],
+    cancellation: { parameter: 'signal' },
+    result: { mode: 'strict', typeSymbol: '@fixture#CreateResult', schema: createResultSchema },
+  }
+}
+
+function contextDescriptor(): InvocationDescriptor {
+  return {
+    id: '@fixture/goals#goals/rename',
+    service: 'goals',
+    namespace: 'goals',
+    method: 'rename',
+    invocation: {
+      kind: 'context',
+      context: 'fixture',
+      wire: 'agentId',
+      codec: { mode: 'strict', typeSymbol: '@fixture#AgentId', schema: idSchema },
+    },
+    parameters: [{
+      name: 'request',
+      wire: 'request',
+      source: 'json',
+      codec: { mode: 'strict', typeSymbol: '@fixture#RenameRequest', schema: requestSchema },
+    }],
+    result: { mode: 'strict', typeSymbol: '@fixture#RenameResult', schema: renameResultSchema },
+  }
+}
+
+async function bench(call: ConnectionHandle['rpc']['call']): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(TypertRegistry)
+  ctx.provide('connection', { rpc: { call } } as unknown as ConnectionHandle)
+  await ctx.plugin({ inject, apply })
+  return ctx
+}
+
+describe('Client TypeRT API', () => {
+  it('mounts concrete direct methods, validates both boundaries, and withdraws retained handles', async () => {
+    const call = vi.fn<ConnectionHandle['rpc']['call']>()
+      .mockResolvedValue({ ok: true, value: { ref: 'goal-1' } })
+    const ctx = await bench(call)
+    const businessGoals = { owner: 'host business service' }
+    const disposeBusinessGoals = ctx.provide('goals', businessGoals)
+    const assembly = ctx.plugin(Object.assign(
+      (scope: Context) => scope.remote.$mount({ package: '@fixture/goals', descriptors: [directDescriptor()] }),
+      { inject: ['remote'] },
+    ))
+    await assembly
+    const retained = ctx.remote.goals.create
+
+    await expect(ctx.remote.goals.create('agent-1', { objective: 'ship' })).resolves.toEqual({ ref: 'goal-1' })
+    expect(call).toHaveBeenCalledWith(
+      '/api',
+      'goals/create',
+      { args: { agentId: 'agent-1', request: { objective: 'ship' } } },
+      expect.any(AbortSignal),
+    )
+    const callerAbort = new AbortController()
+    await expect(ctx.remote.goals.create(
+      'agent-1',
+      { objective: 'cancel me' },
+      callerAbort.signal,
+    )).resolves.toEqual({ ref: 'goal-1' })
+    const combinedSignal = call.mock.calls.at(-1)?.[3]
+    expect(combinedSignal).toBeInstanceOf(AbortSignal)
+    expect(combinedSignal).not.toBe(callerAbort.signal)
+    const cancellation = new Error('caller cancelled')
+    callerAbort.abort(cancellation)
+    expect(combinedSignal?.aborted).toBe(true)
+    expect(combinedSignal?.reason).toBe(cancellation)
+    await expect(ctx.remote.goals.create('', { objective: 'ship' })).rejects.toThrow('rejected "agentId"')
+
+    call.mockResolvedValueOnce({ ok: true, value: { ref: 1 } })
+    await expect(ctx.remote.goals.create('agent-1', { objective: 'ship' })).rejects.toThrow('rejected "result"')
+
+    await assembly.dispose()
+    expect((ctx.remote as unknown as Record<string, unknown>).goals).toBeUndefined()
+    expect(ctx.get('remote.goals')).toBeUndefined()
+    expect(ctx.get('goals')).toBe(businessGoals)
+    expect(ctx.typert.remotes.list()).toEqual([])
+    await expect(retained?.('agent-1', { objective: 'ship' })).rejects.toThrow('no longer mounted')
+    disposeBusinessGoals()
+  })
+
+  it('projects one direct lookup descriptor onto an Agent-scoped alias', async () => {
+    const call = vi.fn<ConnectionHandle['rpc']['call']>()
+      .mockResolvedValue({ ok: true, value: { ref: 'goal-2' } })
+    const ctx = await bench(call)
+    const agentCtx = ctx.extend({ fixtureId: 'agent-2' }) as FixtureContext
+    ctx.typert.contexts.registerClient('fixture', {
+      identity: candidate => (candidate as Context & { fixtureId?: string }).fixtureId,
+    })
+    const assembly = ctx.plugin(Object.assign(
+      (scope: Context) => scope.remote.$mount({ package: '@fixture/goals', descriptors: [directDescriptor()] }),
+      { inject: ['remote'] },
+    ))
+    await assembly
+
+    await expect(agentCtx.remote.goals.create({ objective: 'ship scoped' })).resolves.toEqual({ ref: 'goal-2' })
+    expect(call).toHaveBeenCalledWith(
+      '/api',
+      'goals/create',
+      { args: { agentId: 'agent-2', request: { objective: 'ship scoped' } } },
+      expect.any(AbortSignal),
+    )
+    await expect((ctx as FixtureContext).remote.goals.create({ objective: 'wrong scope' }))
+      .rejects.toThrow('expected 2 business argument(s)')
+
+    await assembly.dispose()
+    expect((ctx.remote as unknown as Record<string, unknown>).goals).toBeUndefined()
+    expect(ctx.get('remote.goals')).toBeUndefined()
+  })
+
+  it('uses the caller Context identity for scoped namespace methods', async () => {
+    const call = vi.fn<ConnectionHandle['rpc']['call']>()
+      .mockResolvedValue({ ok: true, value: { renamed: true } })
+    const ctx = await bench(call)
+    const agentCtx = ctx.extend({ fixtureId: 'agent-2' }) as FixtureContext
+    ctx.typert.contexts.registerClient('fixture', {
+      identity: candidate => (candidate as Context & { fixtureId?: string }).fixtureId,
+    })
+    const assembly = ctx.plugin(Object.assign(
+      (scope: Context) => scope.remote.$mount({ package: '@fixture/goals', descriptors: [contextDescriptor()] }),
+      { inject: ['remote'] },
+    ))
+    await assembly
+
+    await expect(agentCtx.remote.goals.rename({ objective: 'land' })).resolves.toEqual({ renamed: true })
+    expect(call).toHaveBeenCalledWith(
+      '/api',
+      'goals/rename',
+      { args: { agentId: 'agent-2', request: { objective: 'land' } } },
+      expect.any(AbortSignal),
+    )
+    await expect((ctx as FixtureContext).remote.goals.rename({ objective: 'land' }))
+      .rejects.toThrow('requires a "fixture" Context')
+
+    await assembly.dispose()
+    expect(ctx.get('remote.goals')).toBeUndefined()
+  })
+
+  it('rejects weak descriptors and namespace collisions before registration', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const weak: InvocationDescriptor = {
+      ...directDescriptor(),
+      result: { mode: 'src-json' },
+    }
+
+    await expect(ctx.remote.$mount({ package: '@fixture/weak', descriptors: [weak] }))
+      .rejects.toThrow('has no strict codec')
+    await expect(ctx.remote.$mount({
+      package: '@fixture/conflict',
+      descriptors: [{ ...directDescriptor(), namespace: '$mount' }],
+    })).rejects.toThrow('conflicts with the Remote service')
+    expect(ctx.typert.remotes.list()).toEqual([])
+  })
+
+  it('rejects duplicate, live, scoped-service, and Context namespace collisions', async () => {
+    const call = vi.fn<ConnectionHandle['rpc']['call']>()
+      .mockResolvedValue({ ok: true, value: { renamed: true } })
+    const ctx = await bench(call)
+    const agentCtx = ctx.extend({ fixtureId: 'agent-remounted' }) as FixtureContext
+    ctx.typert.contexts.registerClient('fixture', {
+      identity: candidate => (candidate as Context & { fixtureId?: string }).fixtureId,
+    })
+    const direct = directDescriptor()
+    const context = contextDescriptor()
+
+    await expect(ctx.remote.$mount({
+      package: '@fixture/direct-duplicates',
+      descriptors: [direct, { ...direct, id: '@fixture/goals#goals/create-again' }],
+    })).rejects.toThrow('repeats direct method')
+    await expect(ctx.remote.$mount({
+      package: '@fixture/scoped-duplicates',
+      descriptors: [context, { ...context, id: '@fixture/goals#goals/rename-again' }],
+    })).rejects.toThrow('repeats scoped method')
+
+    const disposeDirect = await ctx.remote.$mount({ package: '@fixture/direct-live', descriptors: [direct] })
+    await expect(ctx.remote.$mount({
+      package: '@fixture/direct-conflict', descriptors: [{ ...direct, id: '@fixture/other#goals/create' }],
+    })).rejects.toThrow('direct method goals/create is already mounted')
+    await disposeDirect()
+
+    const disposeScoped = await ctx.remote.$mount({ package: '@fixture/scoped-live', descriptors: [context] })
+    await expect(ctx.remote.$mount({
+      package: '@fixture/scoped-conflict', descriptors: [{ ...context, id: '@fixture/other#goals/rename' }],
+    })).rejects.toThrow('scoped method goals/rename is already mounted')
+    await expect(ctx.remote.$mount({
+      package: '@fixture/service-method-conflict',
+      descriptors: [{ ...context, id: '@fixture/goals#goals/remove', method: 'remove' }],
+    })).rejects.toThrow('conflicts with its namespace service')
+    const scopedService = ctx.get('remote.goals') as unknown as object
+    Object.defineProperty(scopedService, 'custom', { configurable: true, value: () => undefined })
+    await expect(ctx.remote.$mount({
+      package: '@fixture/service-own-property-conflict',
+      descriptors: [{ ...direct, id: '@fixture/goals#goals/custom', method: 'custom' }],
+    })).rejects.toThrow('conflicts with its namespace service')
+    Reflect.deleteProperty(scopedService, 'custom')
+    await disposeScoped()
+
+    const disposeRemoteTypert = ctx.reflect.provide('remote.typert', { owner: 'fixture' })
+    await expect(ctx.remote.$mount({
+      package: '@fixture/context-property-conflict',
+      descriptors: [{ ...context, namespace: 'typert' }],
+    })).rejects.toThrow('conflicts with an existing Remote namespace')
+    await disposeRemoteTypert()
+
+    const disposeMultipleScoped = await ctx.remote.$mount({
+      package: '@fixture/multiple-scoped',
+      descriptors: [directDescriptor(), contextDescriptor()],
+    })
+    await expect(agentCtx.remote.goals.rename({ objective: 'remounted' })).resolves.toEqual({ renamed: true })
+    expect(call).toHaveBeenLastCalledWith(
+      '/api',
+      'goals/rename',
+      { args: { agentId: 'agent-remounted', request: { objective: 'remounted' } } },
+      expect.any(AbortSignal),
+    )
+    await disposeMultipleScoped()
+  })
+
+  it('rolls back earlier descriptors when a later descriptor fails to install', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const { scope: _scope, ...first } = directDescriptor()
+    const second: InvocationDescriptor = {
+      ...first,
+      id: '@fixture/goals#goals/archive',
+      method: 'archive',
+    }
+    const defineProperty = Object.defineProperty
+    const spy = vi.spyOn(Object, 'defineProperty').mockImplementation((target, key, attributes) => {
+      if (key === 'archive') throw new Error('fixture later-descriptor failure')
+      return defineProperty(target, key, attributes)
+    })
+    try {
+      await expect(ctx.remote.$mount({ package: '@fixture/failing-batch', descriptors: [first, second] }))
+        .rejects.toThrow('fixture later-descriptor failure')
+    } finally {
+      spy.mockRestore()
+    }
+
+    expect((ctx.remote as unknown as Record<string, unknown>).goals).toBeUndefined()
+    await vi.waitFor(() => { expect(ctx.typert.remotes.list()).toEqual([]) })
+    const retry = await ctx.remote.$mount({ package: '@fixture/retry-batch', descriptors: [first, second] })
+    expect(ctx.remote.goals.create).toBeTypeOf('function')
+    expect((ctx.remote.goals as unknown as Record<string, unknown>).archive).toBeTypeOf('function')
+    await retry()
+  })
+
+  it('rolls back a direct projection when its scoped projection fails to install', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const disposeContext = await ctx.remote.$mount({
+      package: '@fixture/context-anchor',
+      descriptors: [contextDescriptor()],
+    })
+    const namespace = ctx.get('remote.goals') as unknown as {
+      installScoped: (...args: unknown[]) => void
+      readonly create?: unknown
+    }
+    const installScoped = vi.spyOn(namespace, 'installScoped').mockImplementation(() => {
+      throw new Error('fixture scoped projection failure')
+    })
+    try {
+      await expect(ctx.remote.$mount({
+        package: '@fixture/direct-projection-failure',
+        descriptors: [directDescriptor()],
+      })).rejects.toThrow('fixture scoped projection failure')
+    } finally {
+      installScoped.mockRestore()
+    }
+
+    expect(namespace.create).toBeUndefined()
+    await disposeContext()
+  })
+
+  it('rejects weak parameter and Context codecs plus malformed scope projections', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const direct = directDescriptor()
+    const context = contextDescriptor()
+    await expect(ctx.remote.$mount({
+      package: '@fixture/weak-parameter',
+      descriptors: [{
+        ...direct,
+        parameters: direct.parameters.map((parameter, index) => index === 0
+          ? { ...parameter, codec: { mode: 'src-json' } }
+          : parameter),
+      }],
+    })).rejects.toThrow('has no strict codec')
+    await expect(ctx.remote.$mount({
+      package: '@fixture/weak-context',
+      descriptors: [{
+        ...context,
+        invocation: { ...context.invocation, codec: { mode: 'src-json' } },
+      } as InvocationDescriptor],
+    })).rejects.toThrow('has no strict codec')
+    await expect(ctx.remote.$mount({
+      package: '@fixture/malformed-scope',
+      descriptors: [{ ...direct, scope: { context: 'fixture', wire: 'missingId' } }],
+    })).rejects.toThrow('scope must select its only lookup parameter')
+    await expect(ctx.remote.$mount({
+      package: '@fixture/ambiguous-scope',
+      descriptors: [{
+        ...direct,
+        parameters: [...direct.parameters, {
+          name: 'other', wire: 'otherId', source: 'lookup', lookup: 'fixture',
+          codec: { mode: 'strict', typeSymbol: '@fixture#AgentId', schema: idSchema },
+        }],
+      }],
+    })).rejects.toThrow('scope must select its only lookup parameter')
+  })
+
+  it('validates invocation arity, required binders, live Connection, and mutable descriptor codecs', async () => {
+    const call = vi.fn<ConnectionHandle['rpc']['call']>()
+      .mockResolvedValue({ ok: true, value: { ref: 'goal-1' } })
+    const ctx = await bench(call)
+    const descriptor = directDescriptor()
+    const dispose = await ctx.remote.$mount({
+      package: '@fixture/goals',
+      descriptors: [descriptor, contextDescriptor()],
+    })
+    const create = ctx.remote.goals.create as unknown as (...args: unknown[]) => Promise<unknown>
+    const goals = (ctx as FixtureContext).remote.goals
+    const rename = goals.rename as unknown as (...args: unknown[]) => Promise<unknown>
+
+    await expect(create('agent-1')).rejects.toThrow('expected 2 business argument(s) plus an optional AbortSignal, got 1')
+    await expect(create('agent-1', { objective: 'ship' }, undefined, 'extra'))
+      .rejects.toThrow('got 4')
+    await expect(rename.call(goals)).rejects.toThrow('expected 1 argument(s), got 0')
+    await expect((ctx as FixtureContext).remote.goals.create({ objective: 'ship' }))
+      .rejects.toThrow('expected 2 business argument(s)')
+    await expect((ctx as FixtureContext).remote.goals.rename({ objective: 'ship' }))
+      .rejects.toThrow('no Client Context binder')
+
+    ;(descriptor.parameters[0] as { codec: { mode: string } }).codec.mode = 'src-json'
+    await expect(ctx.remote.goals.create('agent-1', { objective: 'ship' })).rejects.toThrow('has no strict codec')
+    ;(descriptor.parameters[0] as { codec: { mode: string } }).codec.mode = 'strict'
+
+    ctx.set('connection', undefined)
+    await expect(ctx.remote.goals.create('agent-1', { objective: 'ship' })).rejects.toThrow('no active Connection')
+    await dispose()
+  })
+
+  it('withdraws a pending invocation and preserves a direct namespace until its last method leaves', async () => {
+    let resolveCall!: (result: Awaited<ReturnType<ConnectionHandle['rpc']['call']>>) => void
+    const pending = new Promise<Awaited<ReturnType<ConnectionHandle['rpc']['call']>>>((resolve) => {
+      resolveCall = resolve
+    })
+    const call = vi.fn<ConnectionHandle['rpc']['call']>().mockReturnValue(pending)
+    const ctx = await bench(call)
+    const { scope: _scope, ...first } = directDescriptor()
+    const second: InvocationDescriptor = {
+      ...first,
+      id: '@fixture/goals#goals/archive',
+      method: 'archive',
+    }
+    const dispose = await ctx.remote.$mount({ package: '@fixture/goals', descriptors: [first, second] })
+    const invocation = ctx.remote.goals.create('agent-1', { objective: 'ship' })
+    await vi.waitFor(() => { expect(call).toHaveBeenCalledTimes(1) })
+    await dispose()
+    resolveCall({ ok: true, value: { ref: 'goal-1' } })
+
+    await expect(invocation).rejects.toThrow('withdrawn during invocation')
+    expect((ctx.remote as unknown as Record<string, unknown>).goals).toBeUndefined()
+  })
+
+  it('fails a method obtained from a withdrawn namespace getter', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const dispose = await ctx.remote.$mount({ package: '@fixture/goals', descriptors: [directDescriptor()] })
+    const namespace = ctx.get('remote.goals') as unknown as object
+    const getWithdrawn = Object.getOwnPropertyDescriptor(namespace, 'create')?.get?.bind(namespace)
+
+    await dispose()
+
+    expect(getWithdrawn).toBeTypeOf('function')
+    const withdrawn = getWithdrawn?.() as (...args: unknown[]) => Promise<unknown>
+    expect(() => withdrawn('agent-1', { objective: 'ship' }))
+      .toThrow('Remote method is no longer mounted')
+  })
+
+  it('preserves a __proto__ wire parameter as an own named argument', async () => {
+    const call = vi.fn<ConnectionHandle['rpc']['call']>()
+      .mockResolvedValue({ ok: true, value: { ref: 'goal-1' } })
+    const ctx = await bench(call)
+    const { scope: _scope, ...base } = directDescriptor()
+    const descriptor: InvocationDescriptor = {
+      ...base,
+      id: '@fixture/goals#goals/prototype',
+      method: 'prototype',
+      parameters: [{
+        name: 'value',
+        wire: '__proto__',
+        source: 'json',
+        codec: { mode: 'strict', typeSymbol: '@fixture#PrototypeValue', schema: z.string() },
+      }],
+    }
+    const dispose = await ctx.remote.$mount({ package: '@fixture/prototype', descriptors: [descriptor] })
+
+    const method = (ctx.remote.goals as unknown as Record<string, (...args: unknown[]) => Promise<unknown>>).prototype
+    await expect(method?.('wire-value')).resolves.toEqual({ ref: 'goal-1' })
+    const payload = call.mock.calls[0]?.[2] as { readonly args: Record<string, unknown> }
+    expect(Object.getPrototypeOf(payload.args)).toBeNull()
+    expect(Object.hasOwn(payload.args, '__proto__')).toBe(true)
+    expect(payload.args.__proto__).toBe('wire-value')
+    await dispose()
+  })
+
+  it('rolls back Remote registration when namespace Service startup fails', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const defineProperty = Object.defineProperty
+    const spy = vi.spyOn(Object, 'defineProperty').mockImplementation((target, key, attributes) => {
+      if (key === Service.tracker) throw new Error('fixture namespace startup failure')
+      return defineProperty(target, key, attributes)
+    })
+    try {
+      await expect(ctx.remote.$mount({ package: '@fixture/goals', descriptors: [directDescriptor()] }))
+        .rejects.toThrow('fixture namespace startup failure')
+      await vi.waitFor(() => { expect(ctx.typert.remotes.list()).toEqual([]) })
+    } finally {
+      spy.mockRestore()
+    }
+
+    const retry = await ctx.remote.$mount({ package: '@fixture/goals-retry', descriptors: [directDescriptor()] })
+    expect(ctx.remote.goals.create).toBeTypeOf('function')
+    await retry()
+  })
+
+  it('withdraws a fresh direct namespace when its first method fails to install', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const defineProperty = Object.defineProperty
+    const spy = vi.spyOn(Object, 'defineProperty').mockImplementation((target, key, attributes) => {
+      if (key === 'create') throw new Error('fixture direct method installation failure')
+      return defineProperty(target, key, attributes)
+    })
+    try {
+      await expect(ctx.remote.$mount({
+        package: '@fixture/direct-method-failure',
+        descriptors: [directDescriptor()],
+      })).rejects.toThrow('fixture direct method installation failure')
+    } finally {
+      spy.mockRestore()
+    }
+
+    expect((ctx.remote as unknown as Record<string, unknown>).goals).toBeUndefined()
+    await vi.waitFor(() => { expect(ctx.typert.remotes.list()).toEqual([]) })
+    const retry = await ctx.remote.$mount({
+      package: '@fixture/direct-method-retry',
+      descriptors: [directDescriptor()],
+    })
+    expect(ctx.remote.goals.create).toBeTypeOf('function')
+    await retry()
+  })
+
+  it('withdraws a fresh scoped Service when its first method fails to install', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const defineProperty = Object.defineProperty
+    const spy = vi.spyOn(Object, 'defineProperty').mockImplementation((target, key, attributes) => {
+      if (key === 'rename') throw new Error('fixture scoped installation failure')
+      return defineProperty(target, key, attributes)
+    })
+    try {
+      await expect(ctx.remote.$mount({ package: '@fixture/scoped-failure', descriptors: [contextDescriptor()] }))
+        .rejects.toThrow('fixture scoped installation failure')
+    } finally {
+      spy.mockRestore()
+    }
+
+    expect(ctx.get('remote.goals')).toBeUndefined()
+    await vi.waitFor(() => { expect(ctx.typert.remotes.list()).toEqual([]) })
+    const retry = await ctx.remote.$mount({ package: '@fixture/scoped-retry', descriptors: [contextDescriptor()] })
+    expect((ctx.get('remote.goals') as unknown as Record<string, unknown>).rename).toBeTypeOf('function')
+    await retry()
+  })
+
+  it('unregisters an empty scoped namespace so another provider can claim its name', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const dispose = await ctx.remote.$mount({ package: '@fixture/scoped', descriptors: [contextDescriptor()] })
+    expect(ctx.get('remote.goals')).toBeDefined()
+
+    await dispose()
+
+    expect(ctx.get('remote.goals')).toBeUndefined()
+    const replacement = { owner: 'replacement' }
+    const disposeReplacement = ctx.reflect.provide('remote.goals', replacement)
+    expect(ctx.get('remote.goals')).toBe(replacement)
+    await disposeReplacement()
+  })
+
+  it('throws RPC failures with the structured error as its cause', async () => {
+    const rpcError = { code: 'internal' as const, message: 'host failed', details: {} }
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>().mockResolvedValue({ ok: false, error: rpcError }))
+    await ctx.remote.$mount({ package: '@fixture/goals', descriptors: [directDescriptor()] })
+
+    let failure: unknown
+    try {
+      await ctx.remote.goals.create('agent-1', { objective: 'ship' })
+    } catch (error) {
+      failure = error
+    }
+    expect(failure).toBeInstanceOf(Error)
+    if (!(failure instanceof Error)) throw new Error('expected Client API invocation to fail')
+    expect(failure.message).toContain('internal: host failed')
+    expect(failure.cause).toBe(rpcError)
+  })
+})

packages/api/gateway/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../support/invariants"
+    },
+    {
+      "path": "../../client/connection"
+    },
+    {
+      "path": "../../typert/type-meta"
+    }
+  ]
+}

packages/api/gateway/tsdown.config.ts

@@ -0,0 +1,3 @@
+import { clientBundle } from '../../client/tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-api-gateway', ['lib/types/index.js', 'lib/types/invariant.js'])

packages/api/remotes/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/api/remotes/README.md
+README.md: 3d9de0955faefe37c95ff8bb792d57c4fa1f1a3a
+README.zh.md: 7490d68781d3a7b0002b73fe06056ec86c144575

packages/api/remotes/README.md

@@ -0,0 +1,33 @@
+# @deepseek-ai/dsh-api-remotes
+
+English | [中文](README.zh.md)
+
+Two-sided BFF for Host Remote capabilities selected by this application. The Host entry owns Agent/Session identity policy; the Client entry imports generated `/remote` artifacts as runtime values, mounts each contribution through `ctx.remote.$mount()`, and re-exports their declaration merges. Client business packages depend on this facade rather than the Gateway implementation or individual Remote runtime entries.
+
+`createApiRemoteAgentResolver()` reuses live Agents, resumes ordinary cold sessions, deduplicates concurrent resumes, preserves the subagent ownership fence, and configures the same resolver for TypeRT `agent` and `session` lookups. The standard Web API Proxy supplies its Agent defaults and scope setup, then uses the returned resolver for legacy methods, so migrated and unmigrated methods share one policy implementation.
+
+The current Client assembly mounts only the Goal Remote contribution. Cordis effect ownership withdraws every contribution when this assembly unloads, while `@deepseek-ai/dsh-api-gateway/client` owns descriptor validation, traced namespace Services, direct and scoped methods, invocation, and cancellation. The Client entry consumes the shared `TypeRTClientRemote` interface through Cordis and does not import the concrete Gateway.
+
+This package contains no transport or Host service discovery logic. Its Client face can be reused by Web or a future TUI that provides the same React-free `ctx.remote` contract.
+
+## Build boundary
+
+An ordinary repository package belongs to one TypeScript face: Host packages are registered in the root `tsconfig.host.json`, and Client packages in the root `tsconfig.client.json`. `api-remotes` is the only deliberate exception because its Host entry must participate in the Host TypeRT graph, while `src/client/index.ts` cannot compile until Host tsdown has generated the business packages' `/remote` declarations.
+
+This package's root `tsconfig.json` is only a solution that references `tsconfig.host.json` and `tsconfig.client.json`. The Host aggregate and direct Host consumers reference the former, while the Client aggregate and direct Client consumers reference the latter; the package-root solution must not enter either aggregate's dependency graph. The two projects own disjoint source files and `.tsbuildinfo` files but share the `lib/types` output directory.
+
+The package-local `clientBundle(..., { hostPhase: true })` makes Host tsdown bundle the Host entry and the later Client tsdown bundle only the browser entry. Ordinary Client plugins remain single Client projects and produce both their Node loader entry and browser bundle during Client tsdown; do not copy this package's split merely because a package has both `src/index.ts` and `src/client/index.ts`.
+
+## Model Experience
+
+None, as this BFF selects Remote application methods and identity policy but registers no model surface.
+
+#### KV Cache effect
+
+No direct effect; mounted Host capabilities own any model-visible behavior they trigger.
+
+## Known Limitations and Deferred Work
+
+- The capability set is fixed by explicit build-time value imports; the Client does not discover the Host's active Services or Remote definitions at runtime.
+- Additional capabilities require an explicit `/remote` value import and mount in this assembly.
+- The standard Web Host supplies resume defaults and Agent-scope setup from the legacy API Proxy until that remaining BFF configuration moves into `api-remotes`.

packages/api/remotes/README.zh.md

@@ -0,0 +1,33 @@
+# @deepseek-ai/dsh-api-remotes
+
+[English](README.md) | 中文
+
+为本应用选定的 Host Remote 能力提供双侧 BFF。Host 入口负责 Agent/Session 身份策略；Client 入口以运行时值形式导入生成的 `/remote` 产物，通过 `ctx.remote.$mount()` 挂载每项贡献，并重新导出对应的声明合并。Client 业务包依赖该外观，而不依赖 Gateway 实现或单独的 Remote 运行时入口。
+
+`createApiRemoteAgentResolver()` 会复用 live Agent、恢复普通冷会话、对并发恢复去重、保留 subagent ownership fence，并为 TypeRT `agent` 和 `session` lookup 配置同一个 resolver。标准 Web API Proxy 提供 Agent 默认值和 scope 设置，再将返回的 resolver 用于旧方法，使已迁移与未迁移方法共用同一份策略实现。
+
+当前 Client 组合仅挂载 Goal Remote 贡献。该组合卸载时，Cordis effect 的所有权机制会撤回所有贡献；`@deepseek-ai/dsh-api-gateway/client` 负责描述符校验、可追踪 namespace Service、直接与作用域方法、调用与取消。Client 入口通过 Cordis 消费共享的 `TypeRTClientRemote` 接口，不导入具体 Gateway。
+
+本包不包含传输逻辑或 Host 服务发现逻辑。Web 或未来的 TUI 只要提供同一份不依赖 React 的 `ctx.remote` 契约，均可复用其 Client face。
+
+## 构建边界
+
+仓库中的普通包只属于一个 TypeScript face：Host 包登记在根 `tsconfig.host.json`，Client 包登记在根 `tsconfig.client.json`。`api-remotes` 是唯一刻意拆分的特例，因为它的 Host 入口要参与 Host TypeRT 图，而 `src/client/index.ts` 必须等 Host tsdown 生成业务包的 `/remote` 声明后才能编译。
+
+本包根 `tsconfig.json` 只是引用 `tsconfig.host.json` 与 `tsconfig.client.json` 的 solution。Host aggregate 和 Host 直接消费方引用前者，Client aggregate 和 Client 直接消费方引用后者；禁止把包根 solution 放进任一 aggregate 的依赖图。两个 project 拥有互不重叠的源码和 `.tsbuildinfo`，但共享 `lib/types` 输出目录。
+
+包内 `clientBundle(..., { hostPhase: true })` 让 Host tsdown 打包 Host 入口，让后续 Client tsdown 只打包 browser 入口。普通 Client 插件仍使用单一 Client project，并在 Client tsdown 阶段一起生成 Node loader 入口和 browser bundle；不得因一个包同时存在 `src/index.ts` 与 `src/client/index.ts` 就复制本包的拆分。
+
+## 模型体验
+
+无，因为该 BFF 只选择 Remote 应用方法和身份策略，不注册任何模型接口。
+
+#### KV Cache 影响
+
+无直接影响；其触发的任何模型可见行为均由已挂载的 Host 能力负责。
+
+## 已知限制与暂缓事项
+
+- 能力集合由构建时显式导入的值固定确定；Client 不会在运行时发现 Host 中已启用的服务或 Remote 定义。
+- 若要增加能力，必须显式导入相应的 `/remote` 值并在此组合中挂载。
+- 在剩余 BFF 配置迁移到 `api-remotes` 之前，标准 Web Host 仍从旧 API Proxy 提供恢复默认值与 Agent scope 设置。

packages/api/remotes/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@deepseek-ai/dsh-api-remotes",
+  "description": "Remote BFF assembly and Host Agent/Session lookup policy",
+  "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"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-api-gateway"
+    ],
+    "platform": "web",
+    "immediately": true
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "BSD-3-Clause",
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "dependencies": {
+    "@deepseek-ai/dsh-type-meta": "workspace:^"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-goal": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.0.1",
+    "@deepseek-ai/dsh-typert-registry": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-goal": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence": "workspace:^",
+    "@deepseek-ai/dsh-typert-registry": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/api/remotes/src/agent-lookup.ts

@@ -0,0 +1,211 @@
+/** Host BFF policy for resolving Remote Agent and Session identities. */
+
+import type { Context } from 'cordis'
+import type { Agent, AgentOptions, AgentSetup } from '@deepseek-ai/dsh-agent'
+import type { Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-session-persistence'
+import { TypeRTLookupFailure } from '@deepseek-ai/dsh-type-meta'
+import type {} from '@deepseek-ai/dsh-typert-registry'
+
+/** Caller-facing failures preserved by the Gateway's RPC adapter. */
+export type ApiRemoteLookupError =
+  | { readonly code: 'agent-busy'; readonly message: string; readonly details: { readonly reason: string } }
+  | { readonly code: 'session-not-found'; readonly message: string; readonly details: { readonly sessionId: SessionId } }
+  | { readonly code: 'internal'; readonly message: string; readonly details: Record<never, never> }
+
+/** Result of resolving one session identity to its live Agent. */
+export type ApiRemoteAgentResult =
+  | { readonly agent: Agent }
+  | { readonly error: ApiRemoteLookupError }
+
+/** Resume configuration supplied by the owning Host composition. */
+export interface ApiRemoteAgentOptions {
+  /** Read the per-Agent defaults when a cold identity must resume. */
+  readonly agentOptions?: () => AgentOptions
+  /**
+   * Build the Host-specific Agent-scope composition completed before
+   * publication. Keyed by the resumed session itself because what a Host
+   * installs may depend on what that session recorded: an agent preset fixes
+   * the tools its history was produced under, so rebuilding it under another
+   * composition would replay tool calls the agent can no longer make. The
+   * events come along because a session's own record of such a choice may be
+   * an event rather than a header field.
+   * @param session - the resumed session's persisted header and event log.
+   * @returns the Agent-scope setup to run before publication.
+   */
+  readonly setup?: (
+    session: { meta: SessionHeader; events: readonly SessionEvent[] },
+  ) => AgentSetup | Promise<AgentSetup>
+}
+
+/** Cold identity absent from the durable session store. */
+export class ApiRemoteSessionNotFound extends Error {}
+
+/** Session identity whose lifecycle belongs to subagent routing. */
+export class ApiRemoteSubagentSessionOwnership extends Error {
+  /**
+   * Construct the ownership fence.
+   * @param sessionId - identity reserved to subagent routing.
+   */
+  constructor(readonly sessionId: SessionId) {
+    super(`session "${sessionId}" is a subagent session; use subagent delivery`)
+  }
+}
+
+/**
+ * Test whether generic Host routing must leave an identity to subagent routing.
+ * @param ctx - Host Context carrying the live Agent registry.
+ * @param session - attached or live Session metadata.
+ * @param agent - live Agent when one is registered.
+ * @returns whether generic Remote and legacy API calls must reject the identity.
+ */
+export function hasApiRemoteSubagentOwner(
+  ctx: Context,
+  session: Pick<Session, 'header'>,
+  agent: Agent | undefined,
+): boolean {
+  if (session.header.origin === 'subagent') return true
+  const parentId = session.header.parentSession
+  if (parentId === undefined || agent === undefined) return false
+  const parent = ctx.agents.get(parentId)
+  return parent !== undefined && ctx.agents.isOwnedBy(agent.id, parent)
+}
+
+/**
+ * Build the stable caller-facing ownership rejection.
+ * @param sessionId - identity reserved to subagent routing.
+ * @returns the existing `agent-busy` RPC shape.
+ */
+export function apiRemoteSubagentOwnershipError(sessionId: SessionId): ApiRemoteLookupError {
+  return {
+    code: 'agent-busy',
+    message: `session "${sessionId}" is owned by subagent routing`,
+    details: { reason: 'use subagent delivery for this child session' },
+  }
+}
+
+/**
+ * Inspect one cold served session without repairing, resuming, or publishing it.
+ * @param ctx - Host Context carrying the optional persistence provider.
+ * @param sessionId - durable identity to inspect.
+ * @returns detached metadata and events for a servable session.
+ * @throws {@link ApiRemoteSessionNotFound} when the identity has no project-backed session.
+ */
+export async function inspectApiRemoteSession(
+  ctx: Context,
+  sessionId: SessionId,
+): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+  const persistence = ctx.get('sessionPersistence')
+  if (persistence === undefined) {
+    throw new Error('session persistence is not configured (load a dsh-session-persistence backend)')
+  }
+  const meta = (await persistence.list()).find(candidate => candidate.id === sessionId)
+  if (meta === undefined || meta.cwd === undefined) {
+    throw new ApiRemoteSessionNotFound(`session "${sessionId}" not found`)
+  }
+  const inspected = await persistence.inspect(sessionId)
+  if (inspected.meta.cwd === undefined) {
+    throw new ApiRemoteSessionNotFound(`session "${sessionId}" not found`)
+  }
+  return { meta: inspected.meta, events: [...inspected.events] }
+}
+
+/**
+ * Create the Host's shared Agent resolver and configure Agent/Session TypeRT lookups.
+ * Live Agents are reused, ordinary cold sessions resume once per identity, and
+ * subagent-owned identities retain the legacy `agent-busy` fence.
+ * @param ctx - owning Host Context.
+ * @param options - defaults and Agent-scope setup used only for cold resume.
+ * @returns resolver shared by legacy API Proxy methods and TypeRT lookups.
+ */
+export function createApiRemoteAgentResolver(
+  ctx: Context,
+  options: ApiRemoteAgentOptions,
+): (sessionId: SessionId) => Promise<ApiRemoteAgentResult> {
+  const resumes = new Map<SessionId, Promise<Agent>>()
+
+  const fencedLiveAgent = (sessionId: SessionId): ApiRemoteAgentResult | undefined => {
+    const live = ctx.agents.get(sessionId)
+    if (live === undefined) return undefined
+    if (hasApiRemoteSubagentOwner(ctx, live.session, live)) {
+      return { error: apiRemoteSubagentOwnershipError(sessionId) }
+    }
+    return { agent: live }
+  }
+
+  const agentFor = async (sessionId: SessionId): Promise<ApiRemoteAgentResult> => {
+    const fenced = fencedLiveAgent(sessionId)
+    if (fenced !== undefined) return fenced
+    const attached = ctx.sessions.get(sessionId)
+    if (attached !== undefined && hasApiRemoteSubagentOwner(ctx, attached, undefined)) {
+      return { error: apiRemoteSubagentOwnershipError(sessionId) }
+    }
+    let resume = resumes.get(sessionId)
+    if (resume === undefined) {
+      resume = (async () => {
+        try {
+          const inspected = await inspectApiRemoteSession(ctx, sessionId)
+          if (hasApiRemoteSubagentOwner(ctx, { header: inspected.meta }, undefined)) {
+            throw new ApiRemoteSubagentSessionOwnership(sessionId)
+          }
+          // Built from the inspected session before the published re-checks
+          // below, so those stay adjacent to `resume` and a Host setup that
+          // awaits (composing a preset, say) does not widen the collision
+          // window.
+          const setup = options.setup === undefined ? undefined : await options.setup(inspected)
+          const publishedSession = ctx.sessions.get(sessionId)
+          const publishedAgent = ctx.agents.get(sessionId)
+          if (publishedSession !== undefined
+            && hasApiRemoteSubagentOwner(ctx, publishedSession, publishedAgent)) {
+            throw new ApiRemoteSubagentSessionOwnership(sessionId)
+          }
+          const handle = await ctx.agents.resume({
+            resumeSessionId: sessionId,
+            ...options.agentOptions === undefined ? {} : { agentOptions: options.agentOptions() },
+            ...setup === undefined ? {} : { setup },
+          })
+          return handle.agent
+        } finally {
+          resumes.delete(sessionId)
+        }
+      })()
+      resumes.set(sessionId, resume)
+    }
+    try {
+      return { agent: await resume }
+    } catch (error: unknown) {
+      if (error instanceof ApiRemoteSessionNotFound) {
+        return { error: { code: 'session-not-found', message: error.message, details: { sessionId } } }
+      }
+      if (error instanceof ApiRemoteSubagentSessionOwnership) {
+        return { error: apiRemoteSubagentOwnershipError(error.sessionId) }
+      }
+      const fenced = fencedLiveAgent(sessionId)
+      if (fenced !== undefined) return fenced
+      const attached = ctx.sessions.get(sessionId)
+      if (attached !== undefined && hasApiRemoteSubagentOwner(ctx, attached, undefined)) {
+        return { error: apiRemoteSubagentOwnershipError(sessionId) }
+      }
+      return {
+        error: {
+          code: 'internal',
+          message: `resume failed for session "${sessionId}": ${String(error)}`,
+          details: {},
+        },
+      }
+    }
+  }
+
+  ctx.inject(['typert'], (typeCtx) => {
+    const resolveAgent = async (sessionId: SessionId): Promise<Agent> => {
+      const found = await agentFor(sessionId)
+      if ('error' in found) throw new TypeRTLookupFailure(found.error)
+      return found.agent
+    }
+    typeCtx.typert.lookups.configure('agent', resolveAgent)
+    typeCtx.typert.lookups.configure('session', async sessionId => (await resolveAgent(sessionId)).session)
+    typeCtx.typert.contexts.configureHost('agent', async sessionId => (await resolveAgent(sessionId)).ctx)
+  })
+
+  return agentFor
+}

packages/api/remotes/src/client/index.ts

@@ -0,0 +1,27 @@
+/** Platform-neutral assembly of generated Host Remote contributions. */
+
+import type { Context } from 'cordis'
+import goalsRemote from '@deepseek-ai/dsh-goal/remote'
+import type { TypeRTClientRemote } from '@deepseek-ai/dsh-type-meta'
+
+export type { TypeRTClientRemote as ClientRemote } from '@deepseek-ai/dsh-type-meta'
+export type {} from '@deepseek-ai/dsh-goal/remote'
+
+declare module 'cordis' {
+  interface Context {
+    /** Generated Remote namespaces selected by this Client assembly. */
+    remote: TypeRTClientRemote
+  }
+}
+
+/** Required service: the typed Client Remote contribution mount. */
+export const inject = ['remote']
+
+/**
+ * Mount the Host capabilities explicitly selected for this Client assembly.
+ * @param ctx - Client Cordis root carrying the typed API service.
+ * @returns disposer after every selected Remote namespace is ready.
+ */
+export async function apply(ctx: Context): Promise<() => Promise<void>> {
+  return await ctx.remote.$mount(goalsRemote)
+}

packages/api/remotes/src/index.ts

@@ -0,0 +1,18 @@
+/** Host BFF entry and Loader shell for the Remote contribution assembly. */
+
+export {
+  ApiRemoteSessionNotFound,
+  ApiRemoteSubagentSessionOwnership,
+  apiRemoteSubagentOwnershipError,
+  createApiRemoteAgentResolver,
+  hasApiRemoteSubagentOwner,
+  inspectApiRemoteSession,
+} from './agent-lookup.ts'
+export type {
+  ApiRemoteAgentOptions,
+  ApiRemoteAgentResult,
+  ApiRemoteLookupError,
+} from './agent-lookup.ts'
+
+/** Host plugin body; the selected contributions mount only in Client environments. */
+export function apply(): void {}

packages/api/remotes/src/invariant.ts

@@ -0,0 +1,24 @@
+/** Package-owned invariant companion for `@deepseek-ai/dsh-api-remotes`. */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-api-remotes'
+
+/** Cordis companion plugin name. */
+export const name = 'api-remotes-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** No runtime invariant: TypeRT and the Agent/Session registries own the observed relationships. */
+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/api/remotes/tests/agent-lookup.spec.ts

@@ -0,0 +1,154 @@
+import { describe, expect, it, vi } 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 { Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import { createApiRemoteAgentResolver } from '@deepseek-ai/dsh-api-remotes'
+import { TypeRTLookupFailure } from '@deepseek-ai/dsh-type-meta'
+import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
+
+const sid = (value: string): SessionId => value as SessionId
+
+function header(id: SessionId): SessionHeader {
+  return { version: 0, id, createdAt: 1, cwd: '/proj' }
+}
+
+async function createContext(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(TypertRegistry)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(AgentRegistry)
+  return ctx
+}
+
+function provideSession(
+  ctx: Context,
+  meta: SessionHeader,
+  inspect: () => Promise<{ meta: SessionHeader; events: SessionEvent[] }>,
+): void {
+  ctx.provide('sessionPersistence', {
+    list: () => Promise.resolve([meta]),
+    inspect,
+    locate: () => undefined,
+  } as never)
+}
+
+function stubAgent(ctx: Context, session: Session): Agent {
+  return { id: session.id, session, status: 'idle', ctx } as Agent
+}
+
+describe('API Remote Agent resolver races', () => {
+  it('maps an inspected session without a cwd to session-not-found', async () => {
+    const ctx = await createContext()
+    const sessionId = sid('missing-after-inspect')
+    const meta = header(sessionId)
+    provideSession(ctx, meta, () => Promise.resolve({
+      meta: { ...meta, cwd: undefined } as unknown as SessionHeader,
+      events: [],
+    }))
+
+    const result = await createApiRemoteAgentResolver(ctx, {})(sessionId)
+
+    expect(result).toMatchObject({ error: { code: 'session-not-found', details: { sessionId } } })
+    await ctx.fiber.dispose()
+  })
+
+  it('resumes through a concurrently attached ordinary Session without optional defaults', async () => {
+    const ctx = await createContext()
+    const sessionId = sid('ordinary-attach-race')
+    const meta = header(sessionId)
+    let published: Session | undefined
+    provideSession(ctx, meta, () => {
+      published = ctx.sessions.create(sessionId, { meta: { cwd: '/proj' } })
+      return Promise.resolve({ meta, events: [] })
+    })
+    const resume = vi.spyOn(ctx.agents, 'resume').mockImplementation(async () => {
+      if (published === undefined) throw new Error('Session was not published')
+      return { agent: stubAgent(ctx, published), dispose: () => Promise.resolve() }
+    })
+
+    const result = await createApiRemoteAgentResolver(ctx, {})(sessionId)
+
+    expect(result).toMatchObject({ agent: { id: sessionId } })
+    expect(resume).toHaveBeenCalledWith({ resumeSessionId: sessionId })
+    await ctx.fiber.dispose()
+  })
+
+  it('rejects a subagent Session published after durable inspection', async () => {
+    const ctx = await createContext()
+    const sessionId = sid('owned-attach-race')
+    const meta = header(sessionId)
+    provideSession(ctx, meta, () => {
+      ctx.sessions.create(sessionId, { meta: { cwd: '/proj', origin: 'subagent' } })
+      return Promise.resolve({ meta, events: [] })
+    })
+    const resume = vi.spyOn(ctx.agents, 'resume')
+
+    const result = await createApiRemoteAgentResolver(ctx, {})(sessionId)
+
+    expect(result).toMatchObject({ error: { code: 'agent-busy' } })
+    expect(resume).not.toHaveBeenCalled()
+    await ctx.fiber.dispose()
+  })
+
+  it('reclassifies failed resumes after a live or attached subagent wins publication', async () => {
+    for (const winner of ['agent', 'session'] as const) {
+      const ctx = await createContext()
+      const sessionId = sid(`owned-${winner}-resume-race`)
+      const meta = header(sessionId)
+      provideSession(ctx, meta, () => Promise.resolve({ meta, events: [] }))
+      vi.spyOn(ctx.agents, 'resume').mockImplementationOnce(async () => {
+        const session = ctx.sessions.create(sessionId, { meta: { cwd: '/proj', origin: 'subagent' } })
+        if (winner === 'agent') ctx.agents.register(stubAgent(ctx, session))
+        throw new Error('session id already published')
+      })
+
+      const result = await createApiRemoteAgentResolver(ctx, {})(sessionId)
+
+      expect(result).toMatchObject({ error: { code: 'agent-busy' } })
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('uses the shared cold-resume policy for the Agent Host Context', async () => {
+    const ctx = await createContext()
+    const sessionId = sid('context-cold-resume')
+    const meta = header(sessionId)
+    let published: Session | undefined
+    provideSession(ctx, meta, () => {
+      published = ctx.sessions.create(sessionId, { meta: { cwd: '/proj' } })
+      return Promise.resolve({ meta, events: [] })
+    })
+    const agentCtx = ctx.extend()
+    vi.spyOn(ctx.agents, 'resume').mockImplementation(async () => {
+      if (published === undefined) throw new Error('Session was not published')
+      return { agent: stubAgent(agentCtx, published), dispose: () => Promise.resolve() }
+    })
+    const defaultProvider = ctx.typert.contexts.getHost('agent')
+    createApiRemoteAgentResolver(ctx, {})
+    await vi.waitFor(() => { expect(ctx.typert.contexts.getHost('agent')).not.toBe(defaultProvider) })
+    const provider = ctx.typert.contexts.getHost('agent')
+    if (provider === undefined) throw new Error('Agent Host Context provider was not mounted')
+
+    await expect(provider.resolve(sessionId)).resolves.toBe(agentCtx)
+    await ctx.fiber.dispose()
+  })
+
+  it('applies the subagent ownership fence to the Agent Host Context', async () => {
+    const ctx = await createContext()
+    const sessionId = sid('context-owned-subagent')
+    const session = ctx.sessions.create(sessionId, { meta: { cwd: '/proj', origin: 'subagent' } })
+    ctx.agents.register(stubAgent(ctx.extend(), session))
+    const defaultProvider = ctx.typert.contexts.getHost('agent')
+    createApiRemoteAgentResolver(ctx, {})
+    await vi.waitFor(() => { expect(ctx.typert.contexts.getHost('agent')).not.toBe(defaultProvider) })
+    const provider = ctx.typert.contexts.getHost('agent')
+    if (provider === undefined) throw new Error('Agent Host Context provider was not mounted')
+
+    const resolution = provider.resolve(sessionId)
+    await expect(resolution).rejects.toBeInstanceOf(TypeRTLookupFailure)
+    await expect(resolution).rejects.toMatchObject({ failure: { code: 'agent-busy' } })
+    await ctx.fiber.dispose()
+  })
+})

packages/api/remotes/tests/built-lib.e2e.ts

@@ -0,0 +1,224 @@
+import { execFile } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * Built-artifact smoke for the first generated Remote: plain Node boots the
+ * Host and Browser bundle handoffs, then crosses the shared `/api` HTTP route.
+ */
+
+const packageDir = fileURLToPath(new URL('..', import.meta.url))
+const root = resolve(packageDir, '../../..')
+const artifact = (path: string): string => join(root, path)
+const artifactUrl = (path: string): string => pathToFileURL(artifact(path)).href
+
+const requiredArtifacts = [
+  'packages/client/connection/lib/client.js',
+  'packages/client/connection/lib/index.js',
+  'packages/api/remotes/lib/client.js',
+  'packages/core/agent/lib/index.js',
+  'packages/core/session/lib/index.js',
+  'packages/goal/goal/lib/index.js',
+  'packages/goal/goal/lib/typert.host.js',
+  'packages/api/gateway/lib/client.js',
+  'packages/api/gateway/lib/index.js',
+  'packages/typert/registry/lib/client.js',
+  'packages/typert/registry/lib/index.js',
+].every(path => existsSync(artifact(path)))
+
+describe.skipIf(!requiredArtifacts)('Goal Remote built LIB chain', () => {
+  it('runs root and Agent-scoped calls through generated bundles and real HTTP', async () => {
+    const urls = Object.fromEntries(Object.entries({
+      agent: 'packages/core/agent/lib/index.js',
+      apiGatewayClient: 'packages/api/gateway/lib/client.js',
+      apiGatewayHost: 'packages/api/gateway/lib/index.js',
+      connectionClient: 'packages/client/connection/lib/client.js',
+      connectionHost: 'packages/client/connection/lib/index.js',
+      goal: 'packages/goal/goal/lib/index.js',
+      goalTypert: 'packages/goal/goal/lib/typert.host.js',
+      registryClient: 'packages/typert/registry/lib/client.js',
+      registryHost: 'packages/typert/registry/lib/index.js',
+      remotesClient: 'packages/api/remotes/lib/client.js',
+      session: 'packages/core/session/lib/index.js',
+    }).map(([key, path]) => [key, artifactUrl(path)]))
+    const script = `
+      import { createServer } from 'node:http'
+      import * as cordis from 'cordis'
+
+      const urls = ${JSON.stringify(urls)}
+      const { Context } = cordis
+      const { default: AgentRegistry } = await import(urls.agent)
+      const connectionHost = await import(urls.connectionHost)
+      const { default: TypertGatewayService } = await import(urls.apiGatewayHost)
+      const { default: GoalService } = await import(urls.goal)
+      const { TYPERT } = await import(urls.goalTypert)
+      const { default: TypertRegistry } = await import(urls.registryHost)
+      const { Session, SessionId } = await import(urls.session)
+
+      const routes = []
+      const host = new Context()
+      host.provide('httpServer', {
+        register(route) {
+          routes.push(route)
+          return () => { routes.splice(routes.indexOf(route), 1) }
+        },
+        tapIndex() { return () => {} },
+        port: 0,
+      })
+      await host.plugin({ inject: connectionHost.inject, apply: connectionHost.apply })
+      await host.plugin(TypertRegistry)
+      await host.plugin(AgentRegistry)
+      await host.plugin(TypertGatewayService)
+      await host.plugin(GoalService)
+      host.typert.register(TYPERT)
+
+      const makeAgent = rawId => {
+        const session = new Session(SessionId(rawId))
+        return {
+          id: session.id,
+          options: {},
+          session,
+          ctx: host.extend(),
+          status: 'idle',
+          acceptsNextStep: false,
+          send() {},
+          updateInbox() { return 'not-found' },
+          followup() {},
+          steer() { return { outcome: Promise.resolve({ status: 'rejected' }) } },
+          inject(input) { session.append('user/message', input, { surfaceOp: 'append' }) },
+          reserveTurnAdmission() {},
+          cancel() {},
+          whenIdle() { return Promise.resolve() },
+        }
+      }
+      const rootAgent = makeAgent('built-root-agent')
+      const scopedAgent = makeAgent('built-scoped-agent')
+      host.agents.register(rootAgent)
+      host.agents.register(scopedAgent)
+
+      if (routes.length !== 1 || routes[0].path !== '/api') {
+        throw new Error('Connection did not register exactly one /api route')
+      }
+      const server = createServer((request, response) => { void routes[0].handler(request, response) })
+      await new Promise(resolveListen => server.listen(0, '127.0.0.1', resolveListen))
+      const address = server.address()
+      if (address === null || typeof address === 'string') throw new Error('HTTP server has no TCP address')
+      const origin = 'http://127.0.0.1:' + String(address.port)
+
+      const handoffs = new Map()
+      globalThis.window = {
+        __ModuleLoader__: {
+          load(handoff) { handoffs.set(handoff.id, handoff) },
+        },
+      }
+      globalThis.location = { hostname: '127.0.0.1', origin, search: '' }
+      await import(urls.registryClient)
+      await import(urls.connectionClient)
+      await import(urls.apiGatewayClient)
+      await import(urls.remotesClient)
+
+      const instantiate = id => {
+        const handoff = handoffs.get(id)
+        if (handoff === undefined) throw new Error('missing Client bundle handoff ' + id)
+        return handoff.factory(specifier => {
+          if (specifier === 'cordis') return cordis
+          throw new Error('unexpected Client external ' + specifier)
+        })
+      }
+      const client = new Context()
+      for (const id of [
+        '@deepseek-ai/dsh-typert-registry',
+        '@deepseek-ai/dsh-client-connection',
+        '@deepseek-ai/dsh-api-gateway',
+        '@deepseek-ai/dsh-api-remotes',
+      ]) {
+        const plugin = instantiate(id)
+        await client.plugin({ inject: plugin.inject, apply: plugin.apply })
+      }
+      client.typert.contexts.registerClient('agent', {
+        identity: candidate => candidate.builtAgentId,
+      })
+
+      let invalidRejected = false
+      try {
+        await client.remote.goals.create(rootAgent.id, { objective: 1 })
+      } catch {
+        invalidRejected = true
+      }
+      const rootResult = await client.remote.goals.create(rootAgent.id, { objective: 'root goal' })
+      const rootEdit = await client.remote.goals.edit(
+        rootAgent.id,
+        rootResult.ref,
+        { objective: 'edited root goal' },
+      )
+      const agentContext = client.extend({ builtAgentId: scopedAgent.id })
+      const scopedResult = await agentContext.remote.goals.create({ objective: 'scoped goal', maxGoalRounds: 3 })
+      const result = {
+        invalidRejected,
+        rootResult,
+        rootEdit,
+        scopedResult,
+        rootGoal: host.goals.get(rootAgent)?.objective,
+        scopedGoal: host.goals.get(scopedAgent)?.objective,
+        rootEvents: rootAgent.session.events.length,
+        scopedEvents: scopedAgent.session.events.length,
+      }
+
+      await client.fiber.dispose()
+      await new Promise((resolveClose, rejectClose) => server.close(error => {
+        if (error === undefined) resolveClose()
+        else rejectClose(error)
+      }))
+      await host.fiber.dispose()
+      console.log(JSON.stringify(result))
+    `
+
+    const result = await runPlainNode(script)
+    expect(result.exitCode, `stderr:\n${result.stderr}`).toBe(0)
+    const output = JSON.parse(result.stdout.trim().split('\n').at(-1) ?? '{}') as {
+      invalidRejected: boolean
+      rootResult: { ref: { id: string; revision: number } }
+      rootEdit: { objective: string; revision: number }
+      scopedResult: { ref: { id: string; revision: number } }
+      rootGoal: string
+      scopedGoal: string
+      rootEvents: number
+      scopedEvents: number
+    }
+    expect(output).toMatchObject({
+      invalidRejected: true,
+      rootResult: { ref: { revision: 1 } },
+      rootEdit: { objective: 'edited root goal', revision: 2 },
+      scopedResult: { ref: { revision: 1 } },
+      rootGoal: 'edited root goal',
+      scopedGoal: 'scoped goal',
+      rootEvents: 2,
+      scopedEvents: 1,
+    })
+    expect(output.rootResult.ref.id).toMatch(/^goal-/)
+    expect(output.scopedResult.ref.id).toMatch(/^goal-/)
+  }, 60_000)
+})
+
+/** Execute one ESM script without tsx or a TypeScript loader. */
+function runPlainNode(script: string): Promise<{
+  readonly exitCode: number | null
+  readonly stdout: string
+  readonly stderr: string
+}> {
+  return new Promise((resolveRun) => {
+    execFile(process.execPath, ['--input-type=module', '-e', script], {
+      cwd: packageDir,
+      encoding: 'utf8',
+      timeout: 55_000,
+    }, (error, stdout, stderr) => {
+      resolveRun({
+        exitCode: error === null ? 0 : typeof error.code === 'number' ? error.code : null,
+        stdout,
+        stderr,
+      })
+    })
+  })
+}

packages/api/remotes/tsconfig.client.json

@@ -0,0 +1,22 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "tsBuildInfoFile": "lib/tsconfig.client.tsbuildinfo"
+  },
+  "files": [
+    "src/client/index.ts"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../goal/goal"
+    },
+    {
+      "path": "../../typert/type-meta"
+    }
+  ]
+}

packages/api/remotes/tsconfig.host.json

@@ -0,0 +1,36 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "tsBuildInfoFile": "lib/tsconfig.host.tsbuildinfo"
+  },
+  "files": [
+    "src/agent-lookup.ts",
+    "src/index.ts",
+    "src/invariant.ts"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../session-persistence/session-persistence"
+    },
+    {
+      "path": "../../support/invariants"
+    },
+    {
+      "path": "../../typert/registry"
+    },
+    {
+      "path": "../../typert/type-meta"
+    }
+  ]
+}

packages/api/remotes/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "files": [],
+  "references": [
+    {
+      "path": "./tsconfig.host.json"
+    },
+    {
+      "path": "./tsconfig.client.json"
+    }
+  ]
+}

packages/api/remotes/tsdown.config.ts

@@ -0,0 +1,7 @@
+import { clientBundle } from '../../client/tsdown.client.ts'
+
+export default clientBundle(
+  '@deepseek-ai/dsh-api-remotes',
+  ['lib/types/index.js', 'lib/types/invariant.js'],
+  { hostPhase: true },
+)

packages/bundle/base/cordis.patch.yml

@@ -34,6 +34,15 @@
     - id: session
       name: '@deepseek-ai/dsh-session'
 
+    - id: typert
+      name: '@deepseek-ai/dsh-typert-registry'
+
+    - id: typert-loader
+      name: '@deepseek-ai/dsh-typert-loader'
+
+    - id: typert-gateway
+      name: '@deepseek-ai/dsh-api-gateway'
+
     - id: session-title
       name: '@deepseek-ai/dsh-session-title'
       config:
@@ -68,12 +77,10 @@
     - id: settings
       name: '@deepseek-ai/dsh-settings-local'
 
-    # Credential store: the live process environment over `$DSH_HOME/.env`
-    # (owner-only file, hot-reloaded). Adapters resolve their key references
-    # through it at each request, so no key is inlined in this file. The web
-    # Models page's key inputs write it through `credentials.set`; nothing hoists
-    # the document into the process environment, which would make every stored key
-    # read as an unrotatable ambient override.
+    # Credential sources: inherited environment over the managed
+    # `$DSH_HOME/.credentials.yaml`, with project and user `.env` fallbacks.
+    # Adapters resolve references per request; the Models page writes only the
+    # managed document, which is never materialized into the process environment.
     - id: credentials
       name: '@deepseek-ai/dsh-credentials-local'
 
@@ -373,7 +380,6 @@
       name: '@deepseek-ai/dsh-web-search-deepseek'
       config:
         apiKeyEnv: DEEPSEEK_API_KEY
-        baseURL: !!js process.env.DEEPSEEK_SEARCH_BASE_URL
 
     - id: tool-web
       name: '@deepseek-ai/dsh-tool-web'

packages/bundle/base/package.json

@@ -49,6 +49,7 @@
     "@deepseek-ai/dsh-fs-sandbox": "workspace:^",
     "@deepseek-ai/dsh-goal": "workspace:^",
     "@deepseek-ai/dsh-goal-session": "workspace:^",
+    "@deepseek-ai/dsh-api-gateway": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-llm-deepseek": "workspace:^",
     "@deepseek-ai/dsh-llm-pi-ai": "workspace:^",
@@ -95,6 +96,8 @@
     "@deepseek-ai/dsh-tool-web": "workspace:^",
     "@deepseek-ai/dsh-tool-workflow": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-typert-loader": "workspace:^",
+    "@deepseek-ai/dsh-typert-registry": "workspace:^",
     "@deepseek-ai/dsh-user-approval": "workspace:^",
     "@deepseek-ai/dsh-user-interaction": "workspace:^",
     "@deepseek-ai/dsh-web": "workspace:^",

packages/bundle/web-app/cordis.patch.yml

@@ -35,11 +35,6 @@
     # once the web UI owns the choice per session.
     mode: !!js process.env.DSH_TOOLS_MODE
 
-- id: llm-deepseek
-  config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
-    baseURL: !!js process.env.DEEPSEEK_BASE_URL
-
 # ── web-only host rows, the transport layer, and the browser roster ─────────
 
 # `dshClient` rows are the browser roster the modules node half scans into
@@ -124,6 +119,9 @@
     - id: connection
       name: '@deepseek-ai/dsh-client-connection'
 
+    - id: api-remotes
+      name: '@deepseek-ai/dsh-api-remotes'
+
     - id: client-runtime
       name: '@deepseek-ai/dsh-client-runtime'
 
@@ -151,6 +149,11 @@
     - id: ui-conversation
       name: '@deepseek-ai/dsh-client-ui-conversation'
 
+    # Turn tail: the produced-files row under each closing assistant message.
+    # Remove this entry to turn the surface off; the tail hole renders empty.
+    - id: ui-deliverables
+      name: '@deepseek-ai/dsh-client-ui-deliverables'
+
 
     - id: ui-workspace
       name: '@deepseek-ai/dsh-client-ui-workspace'

packages/bundle/web-app/package.json

@@ -38,9 +38,11 @@
     "@deepseek-ai/dsh-client-hmr": "workspace:^",
     "@deepseek-ai/dsh-client-locale": "workspace:^",
     "@deepseek-ai/dsh-client-modules": "workspace:^",
+    "@deepseek-ai/dsh-api-remotes": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-ui-command": "workspace:^",
     "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-deliverables": "workspace:^",
     "@deepseek-ai/dsh-client-ui-goal": "workspace:^",
     "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
     "@deepseek-ai/dsh-client-ui-model": "workspace:^",

packages/client/connection/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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/client/connection/README.md
-README.md: 1393e79aacecbbf7b186f19e4c42269595854b0e
-README.zh.md: 70380ceba1b16b2970e947fb6cd9b2af9085ae51
+README.md: 161e34c4b6018625fb690e178eb9a9f8ac0ef21b
+README.zh.md: d17012cc89c02a1b11f16d126b7c0cafe67fb2a0

packages/client/connection/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Wire consumer layer: the client plugin's apply mounts `ctx.connection` (shared api client + current-page loopback state + single-consumer stream-loop starter); the export face carries the wire contract types, the `AbstractApiClient` seam, and the loop's sink/config types. The browser carrier uses HTTP POST for unary and respond operations and opens one downlink-only WebSocket each for `events.mux` and `events.host`; the in-process carrier satisfies the same two-stream abstraction. Loopback hostname classification stays package-internal: the `/api` Host fence and WebSocket upgrades use it directly, while other client plugins consume the derived `ctx.connection.isLoopback` state. The node half's `/api` route pins the privileged method set (`host.pickDirectory`, `host.openPath`, and the whole configuration plane — `settings.describe`/`openDocument`/`update`/`replace`/`mutate` and `credentials.describe`/`set`/`unset`; reads and native actions included, since describing returns the exposed configuration, opening acts on the Host desktop, and probing an arbitrary reference reports where a credential comes from) to loopback by passing the trust fence with an empty trust list — a declared `trustedHosts` authority reaches every other method, while these stay loopback-local until a real authentication layer exists. The platform carriers and ConnectionController loop are package-internal; apply selects and drives them. The downlink boundary is documented in the [WebSocket downlink carrier Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md); the protocol contract is api-contracts v3 §3.
+Wire consumer layer: the client plugin's apply mounts `ctx.connection` (shared api client + current-page loopback state + single-consumer stream-loop starter); the export face carries the wire contract types, the `AbstractApiClient` seam, and the loop's sink/config types. The browser carrier uses HTTP POST for unary and respond operations and opens one downlink-only WebSocket each for `events.mux` and `events.host`; the in-process carrier satisfies the same two-stream abstraction. The Host half owns the single `/api` route and its Fetch bridge; a registered TypeRT interceptor claims its Remote endpoints before the API Proxy fallback. Loopback hostname classification stays package-internal: the `/api` Host fence and WebSocket upgrades use it directly, while other client plugins consume the derived `ctx.connection.isLoopback` state. The node half's `/api` route pins the privileged method set (`host.pickDirectory`, `host.openPath`, and the whole configuration plane — `settings.describe`/`openDocument`/`update`/`replace`/`mutate` and `credentials.describe`/`set`/`unset`; reads and native actions included, since describing returns the exposed configuration, opening acts on the Host desktop, and probing an arbitrary reference reports where a credential comes from) to loopback by passing the trust fence with an empty trust list — a declared `trustedHosts` authority reaches every other method, while these stay loopback-local until a real authentication layer exists. The platform carriers and ConnectionController loop are package-internal; apply selects and drives them. The downlink boundary is documented in the [WebSocket downlink carrier Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md); the protocol contract is api-contracts v3 §3.
 
 ## /api browser-trust fence
 

packages/client/connection/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 单消费方流循环启动器）；导出表层携带协议契约类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；进程内载体满足同一双流抽象。Loopback hostname 判定逻辑留在包内部：`/api` Host fence 与 WebSocket upgrade 会直接使用它，其他客户端插件则消费派生的 `ctx.connection.isLoopback` 状态。node 半侧的 `/api` 路由让特权方法集（`host.pickDirectory`、`host.openPath`，以及整个配置面——`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`；读取与原生操作也在内，因为 describe 会返回已暴露的配置、打开操作会作用于 Host 桌面，而探测任意引用会报出某条凭据来自何处）以空信任表过信任 fence，从而钉在回环——已声明的 `trustedHosts` 授权可达其余全部方法，而这些方法在真正的认证层出现之前仍只限回环本机。平台载体与 ConnectionController 循环属于包内部；apply 负责选择并驱动它们。下行边界见 [WebSocket 下行载体 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md)；协议契约见 api-contracts v3 §3。
+协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 单消费方流循环启动器）；导出表层携带协议契约类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；进程内载体满足同一双流抽象。Host half 持有唯一 `/api` route 及其 Fetch bridge；已注册的 TypeRT interceptor 会先认领自己的 Remote endpoint，未认领请求再回退 API Proxy。Loopback hostname 判定逻辑留在包内部：`/api` Host fence 与 WebSocket upgrade 会直接使用它，其他客户端插件则消费派生的 `ctx.connection.isLoopback` 状态。node 半侧的 `/api` 路由让特权方法集（`host.pickDirectory`、`host.openPath`，以及整个配置面——`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`；读取与原生操作也在内，因为 describe 会返回已暴露的配置、打开操作会作用于 Host 桌面，而探测任意引用会报出某条凭据来自何处）以空信任表过信任 fence，从而钉在回环——已声明的 `trustedHosts` 授权可达其余全部方法，而这些方法在真正的认证层出现之前仍只限回环本机。平台载体与 ConnectionController 循环属于包内部；apply 负责选择并驱动它们。下行边界见 [WebSocket 下行载体 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md)；协议契约见 api-contracts v3 §3。
 
 ## /api 浏览器信任栅栏
 

packages/client/connection/src/api-request-trust.ts

@@ -16,12 +16,13 @@
 import type { IncomingHttpHeaders } from 'node:http'
 import { isLoopbackHostname } from './loopback-hostname.ts'
 
-/** The request facts the fence reads (structural subset of IncomingMessage). */
+/** The request facts the fence reads from either HTTP representation. */
 interface ApiTrustRequest {
-  headers: IncomingHttpHeaders
+  headers: IncomingHttpHeaders | Headers
 }
 
-function header(headers: IncomingHttpHeaders, name: string): string | undefined {
+function header(headers: IncomingHttpHeaders | Headers, name: string): string | undefined {
+  if (headers instanceof Headers) return headers.get(name) ?? undefined
   const value = headers[name]
   return typeof value === 'string' ? value : undefined
 }
@@ -88,7 +89,7 @@ function isTrustedAuthority(hostUrl: URL, trustedHosts: readonly string[]): bool
 
 /**
  * Decide whether one /api request may reach the RPC bridge.
- * @param request - node HTTP request facts (headers).
+ * @param request - Node HTTP or Fetch request facts (headers).
  * @param trustedHosts - non-loopback authorities this deployment serves: exact `host:port`, or port-less `host` matching any port.
  * @returns true when the Host is ours (loopback or trusted) and any attached browser markers are same-origin.
  */

packages/client/connection/src/client/fixture.ts

@@ -35,10 +35,12 @@ import type {
 } from './api.ts'
 import type { RequestPayload, ResponseValue, RpcMethodMap } from '@deepseek-ai/dsh-host-apiproxy/api'
 import { AbstractApiClient, RpcId, SESSION_SEARCH_RESULT_LIMIT } from './api.ts'
+import { randomUuid } from './random-uuid.ts'
+import type { ClientConnectionRpc } from '../rpc.ts'
 
 /** The fake carrier mints like a real one (business code never mints). */
 function rpcRequest<P>(payload: P): RpcRequest<P> {
-  return { rpcId: RpcId(crypto.randomUUID()), payload }
+  return { rpcId: RpcId(randomUuid()), payload }
 }
 
 function text(t: string): ContentBlock[] {
@@ -1328,6 +1330,16 @@ class FxInbox<F> implements StreamConn<F> {
  * @returns an ApiProxy backed entirely by in-memory state — no host process, no network.
  */
 export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
+  return createFixtureWorld(options).api
+}
+
+interface FixtureWorld {
+  readonly api: ApiProxy
+  readonly rpc: ClientConnectionRpc
+}
+
+/** Build the fixture's legacy API and Remote RPC faces over one state graph. */
+function createFixtureWorld(options: FixtureOptions): FixtureWorld {
   // The resident fixture sessions all carry history, so none of them is blank.
   const sessions: SessionSummary[] = options.empty ? [] : [
     { sessionId: sid('fx-alpha'), updatedAt: Date.now(), running: true, blank: false, cwd: '/tmp/fixture' },
@@ -1506,31 +1518,141 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
     return backscanGoal(log) as FxGoalProjection
   }
 
-  /** Shared CAS mutation path of the goal verbs (undefined next = invalid transition). */
-  const fxMutateGoal = (
-    request: RpcRequest<{ sessionId: SessionId; ref: { id: string; revision: number } }>,
-    ref: { id: string; revision: number },
-    next: (current: FxGoalProjection) => FxGoalProjection['goal'] | undefined,
-  ): Promise<RpcResponse<{ ref: { id: never; revision: number } }>> => {
-    const missing = requireSession(request)
+  type FxGoalRef = { id: string; revision: number }
+  type FxGoalView = FxGoalProjection['goal'] & {
+    roundsStarted: number
+    createdAt: number
+    updatedAt: number
+    activation: 'armed' | 'disarmed'
+  }
+
+  const goalFailure = <T>(message: string): RpcResult<T> => ({
+    ok: false,
+    error: { code: 'internal', message, details: {} },
+  })
+
+  const requireGoalSession = (id: SessionId): RpcResult<never> | undefined => (
+    summaryOf(id) === undefined
+      ? { ok: false, error: { code: 'session-not-found', message: `no session ${id}`, details: { sessionId: id } } }
+      : undefined
+  )
+
+  const goalView = (projection: FxGoalProjection): FxGoalView => ({
+    ...projection.goal,
+    roundsStarted: projection.roundsStarted,
+    createdAt: projection.createdAt,
+    updatedAt: projection.updatedAt,
+    activation: projection.goal.phase === 'active' ? 'armed' : 'disarmed',
+  })
+
+  /** Canonical fixture implementation of the generated Goal Remote contract. */
+  const goalRemotes = {
+    create(id: SessionId, request: { objective: string; maxGoalRounds?: number }): RpcResult<{ ref: FxGoalRef }> {
+      const missing = requireGoalSession(id)
+      if (missing !== undefined) return missing
+      const current = backscanGoal(logOf(id))
+      if (current !== null && current.goal.phase !== 'complete') {
+        return goalFailure(`goal "${current.goal.id}" already exists`)
+      }
+      const now = Date.now()
+      const projection = appendGoalChange(id, {
+        kind: 'goal/change', version: 1, operation: 'create',
+        goal: {
+          id: `fx-goal-${logOf(id).length}`,
+          revision: 1,
+          objective: request.objective,
+          phase: 'active',
+          maxGoalRounds: request.maxGoalRounds ?? 256,
+        },
+        roundsStarted: 0, createdAt: now, updatedAt: now,
+      })
+      return { ok: true, value: { ref: { id: projection.goal.id, revision: projection.goal.revision } } }
+    },
+    edit(id: SessionId, ref: FxGoalRef, request: { objective?: string; maxGoalRounds?: number }): RpcResult<FxGoalView> {
+      return mutateGoal(id, ref, current => ({
+        ...current.goal,
+        revision: current.goal.revision + 1,
+        ...request.objective === undefined ? {} : { objective: request.objective },
+        ...request.maxGoalRounds === undefined ? {} : { maxGoalRounds: request.maxGoalRounds },
+      }))
+    },
+    pause(id: SessionId, ref: FxGoalRef): RpcResult<FxGoalView> {
+      return mutateGoal(id, ref, current => (
+        current.goal.phase === 'active'
+          ? { ...current.goal, revision: current.goal.revision + 1, phase: 'paused' }
+          : undefined
+      ))
+    },
+    resume(id: SessionId, ref: FxGoalRef): RpcResult<FxGoalView> {
+      return mutateGoal(id, ref, current => (
+        current.goal.phase === 'paused' || current.goal.phase === 'blocked' || current.goal.phase === 'active'
+          ? { ...current.goal, revision: current.goal.revision + 1, phase: 'active' }
+          : undefined
+      ))
+    },
+    complete(id: SessionId, ref: FxGoalRef): RpcResult<FxGoalView> {
+      return mutateGoal(id, ref, current => (
+        current.goal.phase === 'complete'
+          ? undefined
+          : { ...current.goal, revision: current.goal.revision + 1, phase: 'complete' }
+      ))
+    },
+    clear(id: SessionId, ref: FxGoalRef): RpcResult<FxGoalRef> {
+      const resolved = resolveGoal(id, ref)
+      if (!resolved.ok) return resolved
+      const current = resolved.value
+      const tombstone = { id: current.goal.id, revision: current.goal.revision + 1 }
+      appendGoalChange(id, {
+        kind: 'goal/change', version: 1, operation: 'clear', cleared: tombstone, clearedAt: Date.now(),
+      })
+      return { ok: true, value: tombstone }
+    },
+  }
+
+  /** Resolve one current goal revision for a canonical Remote mutation. */
+  function resolveGoal(id: SessionId, ref: FxGoalRef): RpcResult<FxGoalProjection> {
+    const missing = requireGoalSession(id)
     if (missing !== undefined) return missing
-    const id = request.payload.sessionId
     const current = backscanGoal(logOf(id))
     if (current === null || current.goal.id !== ref.id || current.goal.revision !== ref.revision) {
-      return err(request, { code: 'internal', message: 'stale or missing goal revision', details: { goalCode: 'GOAL_STALE_REVISION' } })
+      return goalFailure('stale or missing goal revision')
     }
+    return { ok: true, value: current }
+  }
+
+  /** Shared CAS mutation path behind the canonical Remote verbs. */
+  function mutateGoal(
+    id: SessionId,
+    ref: FxGoalRef,
+    next: (current: FxGoalProjection) => FxGoalProjection['goal'] | undefined,
+  ): RpcResult<FxGoalView> {
+    const resolved = resolveGoal(id, ref)
+    if (!resolved.ok) return resolved
+    const current = resolved.value
     const goal = next(current)
     if (goal === undefined) {
-      return err(request, { code: 'internal', message: `invalid goal transition from "${current.goal.phase}"`, details: { goalCode: 'GOAL_INVALID_TRANSITION' } })
+      return goalFailure(`invalid goal transition from "${current.goal.phase}"`)
     }
     const projection = appendGoalChange(id, {
       kind: 'goal/change', version: 1,
       operation: goal.phase === current.goal.phase ? 'edit' : goal.phase === 'paused' ? 'pause' : goal.phase === 'active' ? 'resume' : 'complete',
       goal, roundsStarted: current.roundsStarted, createdAt: current.createdAt, updatedAt: Date.now(),
     })
-    return ok(request, { ref: { id: projection.goal.id as never, revision: projection.goal.revision } })
+    return { ok: true, value: goalView(projection) }
   }
 
+  const mapGoalResult = <T, U>(result: RpcResult<T>, map: (value: T) => U): RpcResult<U> => (
+    result.ok ? { ok: true, value: map(result.value) } : result
+  )
+
+  const goalRefResult = (result: RpcResult<FxGoalView>): RpcResult<{ ref: { id: never; revision: number } }> => (
+    mapGoalResult(result, view => ({ ref: { id: view.id as never, revision: view.revision } }))
+  )
+
+  const legacyGoalResponse = <P, T>(request: RpcRequest<P>, result: RpcResult<T>): Promise<RpcResponse<T>> => (
+    Promise.resolve({ rpcId: request.rpcId, result })
+  )
+
   /** At most one in-flight replay per session; cancel clears it. */
   const replays = new Map<SessionId, { timer: ReturnType<typeof setTimeout>; finish(aborted: boolean): void }>()
 
@@ -1776,7 +1898,7 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
     replays.set(id, { timer: setTimeout(tick, 80), finish })
   }
 
-  return {
+  const api: ApiProxy = {
     sessions: {
       list: request => ok(request, { items: [...sessions].sort((a, b) => b.updatedAt - a.updatedAt) }),
       search: (request, signal) => {
@@ -1978,6 +2100,9 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
       models: request => ok(request, {
         current: modelTargets.get(request.payload.sessionId)
           ?? { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+        // The fixture's routes all serve; a surface exercising the blocked
+        // posture drives it through its own stub.
+        routable: true,
         groups: fixtureModelGroups(),
         failures: [],
       }),
@@ -2342,60 +2467,44 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
       },
     },
     goals: {
-      // Mutation-only mirror of the host handlers: each verb CAS-checks the
-      // projected current goal, appends the whole-value change (the mux
-      // stream and projection frame ride the shared append path), and
-      // acknowledges with the new ref only.
-      create: (request) => {
-        const missing = requireSession(request)
-        if (missing !== undefined) return missing
-        const id = request.payload.sessionId
-        const current = backscanGoal(logOf(id))
-        if (current !== null && current.goal.phase !== 'complete') {
-          return err(request, { code: 'internal', message: `goal "${current.goal.id}" already exists`, details: { goalCode: 'GOAL_ALREADY_EXISTS' } })
-        }
-        const projection = appendGoalChange(id, {
-          kind: 'goal/change', version: 1, operation: 'create',
-          goal: { id: `fx-goal-${logOf(id).length}`, revision: 1, objective: request.payload.objective, phase: 'active', maxGoalRounds: request.payload.maxGoalRounds ?? 256 },
-          roundsStarted: 0, createdAt: Date.now(), updatedAt: Date.now(),
-        })
-        return ok(request, { ref: { id: projection.goal.id as never, revision: projection.goal.revision } })
-      },
-      edit: request => fxMutateGoal(request, request.payload.ref, current => ({
-        ...current.goal,
-        revision: current.goal.revision + 1,
-        ...request.payload.objective === undefined ? {} : { objective: request.payload.objective },
-        ...request.payload.maxGoalRounds === undefined ? {} : { maxGoalRounds: request.payload.maxGoalRounds },
-      })),
-      pause: request => fxMutateGoal(request, request.payload.ref, current => (
-        current.goal.phase === 'active'
-          ? { ...current.goal, revision: current.goal.revision + 1, phase: 'paused' }
-          : undefined
-      )),
-      resume: request => fxMutateGoal(request, request.payload.ref, current => (
-        current.goal.phase === 'paused' || current.goal.phase === 'blocked' || current.goal.phase === 'active'
-          ? { ...current.goal, revision: current.goal.revision + 1, phase: 'active' }
-          : undefined
-      )),
-      complete: request => fxMutateGoal(request, request.payload.ref, current => (
-        current.goal.phase === 'complete'
-          ? undefined
-          : { ...current.goal, revision: current.goal.revision + 1, phase: 'complete' }
-      )),
-      clear: (request) => {
-        const missing = requireSession(request)
-        if (missing !== undefined) return missing
-        const id = request.payload.sessionId
-        const current = backscanGoal(logOf(id))
-        if (current === null || current.goal.id !== request.payload.ref.id || current.goal.revision !== request.payload.ref.revision) {
-          return err(request, { code: 'internal', message: 'stale or missing goal revision', details: { goalCode: 'GOAL_STALE_REVISION' } })
-        }
-        appendGoalChange(id, {
-          kind: 'goal/change', version: 1, operation: 'clear',
-          cleared: { id: current.goal.id, revision: current.goal.revision + 1 }, clearedAt: Date.now(),
-        })
-        return ok(request, { cleared: true as const })
-      },
+      // Compatibility face only: old API Proxy payloads and acknowledgements
+      // adapt to the canonical fixture Remote implementation above.
+      create: request => legacyGoalResponse(
+        request,
+        mapGoalResult(
+          goalRemotes.create(request.payload.sessionId, {
+            objective: request.payload.objective,
+            ...request.payload.maxGoalRounds === undefined ? {} : { maxGoalRounds: request.payload.maxGoalRounds },
+          }),
+          value => ({ ref: { id: value.ref.id as never, revision: value.ref.revision } }),
+        ),
+      ),
+      edit: request => legacyGoalResponse(
+        request,
+        goalRefResult(goalRemotes.edit(request.payload.sessionId, request.payload.ref, {
+          ...request.payload.objective === undefined ? {} : { objective: request.payload.objective },
+          ...request.payload.maxGoalRounds === undefined ? {} : { maxGoalRounds: request.payload.maxGoalRounds },
+        })),
+      ),
+      pause: request => legacyGoalResponse(
+        request,
+        goalRefResult(goalRemotes.pause(request.payload.sessionId, request.payload.ref)),
+      ),
+      resume: request => legacyGoalResponse(
+        request,
+        goalRefResult(goalRemotes.resume(request.payload.sessionId, request.payload.ref)),
+      ),
+      complete: request => legacyGoalResponse(
+        request,
+        goalRefResult(goalRemotes.complete(request.payload.sessionId, request.payload.ref)),
+      ),
+      clear: request => legacyGoalResponse(
+        request,
+        mapGoalResult(
+          goalRemotes.clear(request.payload.sessionId, request.payload.ref),
+          () => ({ cleared: true as const }),
+        ),
+      ),
     },
     events: {
       async *mux(_request, signal) {
@@ -2515,8 +2624,11 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
       providers: request => ok(request, {
         providers: [
           { provider: 'deepseek-official', displayName: 'DeepSeek', settingsNs: 'llm-deepseek', settingsPath: [], active: true },
-          { provider: 'openai', displayName: 'openai', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'openai'], active: true },
-          { provider: 'anthropic', displayName: 'anthropic', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'anthropic'], active: false },
+          { provider: 'openai', displayName: 'openai', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'openai'], active: true, declared: false },
+          { provider: 'anthropic', displayName: 'anthropic', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'anthropic'], active: false, declared: false },
+          // One hand-declared route, so a surface reading this fixture meets
+          // the tagged shape rather than only the shipped one.
+          { provider: 'acme-gateway', displayName: 'Acme Gateway', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'acme-gateway'], active: true, declared: true },
         ],
       }),
       models: request => ok(request, { groups: fixtureModelGroups(), failures: [] }),
@@ -2553,6 +2665,36 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
       return Promise.resolve({ accepted: true })
     },
   }
+
+  const rpc: ClientConnectionRpc = {
+    call(channel, endpoint, payload) {
+      if (channel !== '/api') {
+        return Promise.reject(new Error(`fixture connection RPC channel ${JSON.stringify(channel)} is unavailable`))
+      }
+      const args = (payload as {
+        args: {
+          agentId: SessionId
+          ref?: { id: string; revision: number }
+          request?: { objective?: string; maxGoalRounds?: number }
+        }
+      }).args
+      const sessionId = args.agentId
+      switch (endpoint) {
+        case 'goals/create': return Promise.resolve(goalRemotes.create(sessionId, {
+          objective: args.request?.objective as string,
+          ...args.request?.maxGoalRounds === undefined ? {} : { maxGoalRounds: args.request.maxGoalRounds },
+        }))
+        case 'goals/edit': return Promise.resolve(goalRemotes.edit(sessionId, args.ref as FxGoalRef, args.request ?? {}))
+        case 'goals/pause': return Promise.resolve(goalRemotes.pause(sessionId, args.ref as FxGoalRef))
+        case 'goals/resume': return Promise.resolve(goalRemotes.resume(sessionId, args.ref as FxGoalRef))
+        case 'goals/complete': return Promise.resolve(goalRemotes.complete(sessionId, args.ref as FxGoalRef))
+        case 'goals/clear': return Promise.resolve(goalRemotes.clear(sessionId, args.ref as FxGoalRef))
+        default:
+          return Promise.reject(new Error(`fixture connection RPC endpoint ${JSON.stringify(endpoint)} is unavailable`))
+      }
+    },
+  }
+  return { api, rpc }
 }
 
 /**
@@ -2564,10 +2706,14 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
  */
 export class FixtureApiClient extends AbstractApiClient {
   private readonly api: ApiProxy
+  /** Generic Remote caller backed by the same in-memory state as the legacy fixture API. */
+  readonly rpc: ClientConnectionRpc
 
   constructor() {
     super()
-    this.api = createFixtureApi(fixtureOptionsFromLocation())
+    const world = createFixtureWorld(fixtureOptionsFromLocation())
+    this.api = world.api
+    this.rpc = world.rpc
   }
 
   protected doFetch(): Promise<Response> {

packages/client/connection/src/client/index.ts

@@ -8,7 +8,9 @@ import type { IApiClient } from './api.ts'
 import { ConnectionController, type ConnectionConfig, type ConnectionSinks, type ConnectionState } from './connection.ts'
 import { FixtureApiClient } from './fixture.ts'
 import { WebApiClient } from './web-api-client.ts'
+import { createWebConnectionRpc } from './rpc.ts'
 import { isLoopbackHostname } from '../loopback-hostname.ts'
+import type { ClientConnectionRpc } from '../rpc.ts'
 
 // ---- Contract re-exports (browser-safe apiproxy channels + core types) ----
 export type {
@@ -36,6 +38,7 @@ export {
 // Connection loop types are public through ConnectionHandle.start; the
 // controller remains package-internal.
 export type { ConnectionConfig, ConnectionSinks, ConnectionState }
+export type { ClientConnectionRpc } from '../rpc.ts'
 
 
 /** Required services (none — this is the wire root). */
@@ -51,6 +54,8 @@ export interface ConnectionHandle {
   readonly api: IApiClient
   /** Whether the current page authority is loopback; non-browser contexts default to true. */
   readonly isLoopback: boolean
+  /** Generic logical RPC channels over the same Connection transport. */
+  readonly rpc: ClientConnectionRpc
   /**
    * Start the connect/pump/reconnect loop with the consumer's frame sinks.
    * One consumer owns the streams (the runtime object layer); a second call
@@ -69,11 +74,14 @@ export interface ConnectionHandle {
 export function apply(ctx: Context): void {
   const pageLocation = typeof location === 'undefined' ? undefined : location
   const fixture = pageLocation !== undefined && new URLSearchParams(pageLocation.search).has('fixture')
-  const api: IApiClient = fixture ? new FixtureApiClient() : new WebApiClient()
+  const fixtureClient = fixture ? new FixtureApiClient() : undefined
+  const api: IApiClient = fixtureClient ?? new WebApiClient()
+  const rpc = fixtureClient?.rpc ?? createWebConnectionRpc()
   let started = false
   const handle: ConnectionHandle = {
     api,
     isLoopback: pageLocation === undefined || isLoopbackHostname(pageLocation.hostname),
+    rpc,
     start(sinks, config) {
       if (started) throw new Error('connection: the stream loop is already owned by another consumer')
       started = true

packages/client/connection/src/client/random-uuid.ts

@@ -0,0 +1,14 @@
+/** Browser-safe UUID generation for client-side wire correlation. */
+
+/**
+ * Generate an RFC 4122 version 4 UUID without requiring a secure context.
+ * @returns a UUID backed by `crypto.getRandomValues()`, which browsers expose on insecure origins.
+ */
+export function randomUuid(): string {
+  const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16))
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  view.setUint8(6, (view.getUint8(6) & 0x0f) | 0x40)
+  view.setUint8(8, (view.getUint8(8) & 0x3f) | 0x80)
+  const hex = Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+}

packages/client/connection/src/client/rpc.ts

@@ -0,0 +1,63 @@
+/** Browser caller for generic Connection unary RPC channels. */
+
+import {
+  RpcId,
+  serverResponseSchema,
+  type ClientRequest,
+} from '@deepseek-ai/dsh-host-apiproxy/api'
+import type { ClientConnectionRpc } from '../rpc.ts'
+import { randomUuid } from './random-uuid.ts'
+
+const INTERNAL_BASE = 'http://dsh.internal'
+const CHANNEL_PATTERN = /^\/[A-Za-z0-9._~-]+$/
+const ENDPOINT_SEGMENT_PATTERN = /^[A-Za-z0-9_$.-]+$/
+
+/**
+ * Create the browser-backed generic RPC caller.
+ * @returns caller that owns request correlation and response-envelope validation.
+ */
+export function createWebConnectionRpc(): ClientConnectionRpc {
+  return {
+    async call(channel, endpoint, payload, signal) {
+      assertTarget(channel, endpoint)
+      const rpcId = RpcId(randomUuid())
+      const message: ClientRequest = {
+        type: 'client-request',
+        rpcId,
+        method: endpoint,
+        payload,
+      }
+      const response = await globalThis.fetch(
+        new URL(`${channel}/${endpoint}`, resolveBase()),
+        {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify(message),
+          ...signal === undefined ? {} : { signal },
+        },
+      )
+      if (!response.ok) {
+        throw new Error(`transport failure for ${channel}/${endpoint}: HTTP ${response.status}`)
+      }
+      const full = serverResponseSchema.parse(await response.json())
+      if (full.rpcId !== rpcId) {
+        throw new Error(`rpcId mismatch for ${endpoint}: sent ${rpcId}, got ${full.rpcId}`)
+      }
+      return full.result
+    },
+  }
+}
+
+function resolveBase(): string {
+  const location = (globalThis as { location?: { origin?: string } }).location
+  return location?.origin !== undefined && location.origin !== 'null' ? location.origin : INTERNAL_BASE
+}
+
+function assertTarget(channel: string, endpoint: string): void {
+  const segments = endpoint.split('/')
+  if (!CHANNEL_PATTERN.test(channel)
+    || segments.some(segment =>
+      segment === '' || segment === '.' || segment === '..' || !ENDPOINT_SEGMENT_PATTERN.test(segment))) {
+    throw new Error(`connection: invalid RPC target ${JSON.stringify(`${channel}/${endpoint}`)}`)
+  }
+}

packages/client/connection/src/http-bridge.ts

@@ -5,6 +5,16 @@
 
 import type { IncomingMessage, ServerResponse } from 'node:http'
 
+/** Transport-independent request handler consumed by the Host HTTP bridge. */
+export interface FetchHandler {
+  /**
+   * Handle one standard Fetch request.
+   * @param request - request produced by the active transport bridge.
+   * @returns complete or streaming Fetch response.
+   */
+  fetch(request: Request): Promise<Response>
+}
+
 /**
  * Bridge one node:http request to the fetch-shaped handler (client close
  * aborts; SSE bodies stream out chunk by chunk).
@@ -12,7 +22,7 @@ import type { IncomingMessage, ServerResponse } from 'node:http'
  * @param res - node:http response the bridge writes and owns to completion.
  * @param apiHandler - fetch-shaped API carrier the request is dispatched to.
  */
-export async function bridge(req: IncomingMessage, res: ServerResponse, apiHandler: { fetch: typeof fetch }): Promise<void> {
+export async function bridge(req: IncomingMessage, res: ServerResponse, apiHandler: FetchHandler): 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

packages/client/connection/src/index.ts

@@ -7,15 +7,26 @@ import { toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
 import { API_PATH, HOST_EVENTS_PATH, MUX_EVENTS_PATH } from './api-path.ts'
 import { bridge } from './http-bridge.ts'
 import { assertTrustedAuthority, isTrustedApiRequest } from './api-request-trust.ts'
+import { HostConnectionService } from './rpc-host.ts'
 import { rejectWebSocketUpgrade, WebSocketDownlinks } from './websocket-downlink.ts'
 
+export type {
+  ConnectionRpcAuthority,
+  ConnectionRpcEndpointMatcher,
+  ConnectionRpcHandler,
+  ConnectionRpcHandlerOptions,
+  HostConnectionHandle,
+  HostConnectionRpc,
+} from './rpc.ts'
+export { HostConnectionService } from './rpc-host.ts'
+
 export { API_PATH, HOST_EVENTS_PATH, MUX_EVENTS_PATH } from './api-path.ts'
 
 /** Stable Cordis plugin name. */
 export const name = 'client-connection'
 
-/** Services required before mounting the route. */
-export const inject = ['httpServer', 'apiProxy']
+/** Services required before providing Connection; API Proxy is an optional `/api` fallback. */
+export const inject = ['httpServer']
 
 /** Plugin config: the deployment's non-loopback serving authorities. */
 export interface ConnectionConfig {
@@ -83,49 +94,61 @@ export function apply(ctx: Context, config?: ConnectionConfig): void {
   // Config boundary: a malformed entry fails the load loudly here rather than
   // silently authorizing its hostname prefix at request time.
   for (const entry of trustedHosts) assertTrustedAuthority(entry)
-  const apiHandler = toFetchHandler(ctx.apiProxy)
-  const downlinks = new WebSocketDownlinks(ctx.apiProxy)
+  const connection = new HostConnectionService(ctx, trustedHosts)
+  const fetchHandler = connection.createSharedFetchHandler(API_PATH, {
+    async fetch(request) {
+      const pathname = new URL(request.url).pathname
+      const method = pathname.startsWith(`${API_PATH}/`)
+        ? pathname.slice(API_PATH.length + 1)
+        : undefined
+      if (method !== undefined
+        && PRIVILEGED_METHODS.has(method)
+        && !isTrustedApiRequest(request, [])) {
+        return new Response('forbidden', { status: 403 })
+      }
+      if (request.method === 'GET' && (pathname === MUX_EVENTS_PATH || pathname === HOST_EVENTS_PATH)) {
+        return new Response('upgrade required', {
+          status: 426,
+          headers: { connection: 'Upgrade', upgrade: 'websocket' },
+        })
+      }
+      const apiProxy = ctx.get('apiProxy')
+      if (apiProxy === undefined) return new Response('not found', { status: 404 })
+      return toFetchHandler(apiProxy).fetch(request)
+    },
+  })
   const route: WebRoute = {
     kind: 'prefix',
     path: API_PATH,
     handler: async (req, res) => {
-      const pathname = new URL(req.url ?? '/', 'http://dsh.internal').pathname
-      const method = pathname.startsWith(`${API_PATH}/`)
-        ? pathname.slice(API_PATH.length + 1)
-        : undefined
-      const allowed = method !== undefined && PRIVILEGED_METHODS.has(method)
-        ? isTrustedApiRequest(req, [])
-        : isTrustedApiRequest(req, trustedHosts)
-      if (!allowed) {
+      if (!isTrustedApiRequest(req, trustedHosts)) {
         res.writeHead(403)
         res.end('forbidden')
         return
       }
-      if (req.method === 'GET' && (pathname === MUX_EVENTS_PATH || pathname === HOST_EVENTS_PATH)) {
-        res.writeHead(426, { connection: 'Upgrade', upgrade: 'websocket' })
-        res.end('upgrade required')
-        return
-      }
-      await bridge(req, res, apiHandler)
+      await bridge(req, res, fetchHandler)
     },
   }
   ctx.effect(() => ctx.httpServer.register(route), 'client-connection: /api route')
-  const registerDownlink = (
-    path: string,
-    handle: WebUpgradeRoute['handler'],
-  ): void => {
-    ctx.effect(() => ctx.httpServer.registerUpgrade({
-      path,
-      handler: (req, socket, head) => {
-        if (!isTrustedApiRequest(req, trustedHosts)) {
-          rejectWebSocketUpgrade(socket)
-          return
-        }
-        return handle(req, socket, head)
-      },
-    }), `client-connection: ${path} WebSocket`)
-  }
-  ctx.effect(() => () => downlinks.close(), 'client-connection: WebSocket downlinks')
-  registerDownlink(MUX_EVENTS_PATH, (req, socket, head) => { downlinks.handleMux(req, socket, head) })
-  registerDownlink(HOST_EVENTS_PATH, (req, socket, head) => { downlinks.handleHost(req, socket, head) })
+  ctx.inject(['apiProxy'], (apiCtx) => {
+    const downlinks = new WebSocketDownlinks(apiCtx.apiProxy)
+    const registerDownlink = (
+      path: string,
+      handle: WebUpgradeRoute['handler'],
+    ): void => {
+      apiCtx.effect(() => apiCtx.httpServer.registerUpgrade({
+        path,
+        handler: (req, socket, head) => {
+          if (!isTrustedApiRequest(req, trustedHosts)) {
+            rejectWebSocketUpgrade(socket)
+            return
+          }
+          return handle(req, socket, head)
+        },
+      }), `client-connection: ${path} WebSocket`)
+    }
+    apiCtx.effect(() => () => downlinks.close(), 'client-connection: WebSocket downlinks')
+    registerDownlink(MUX_EVENTS_PATH, (req, socket, head) => { downlinks.handleMux(req, socket, head) })
+    registerDownlink(HOST_EVENTS_PATH, (req, socket, head) => { downlinks.handleHost(req, socket, head) })
+  })
 }

packages/client/connection/src/rpc-host.ts

@@ -0,0 +1,224 @@
+/** Host registry and HTTP adapter for generic Connection RPC channels. */
+
+import { Context, Service } from 'cordis'
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
+import {
+  clientRequestSchema,
+  RpcId,
+  type ClientRequest,
+  type RpcError,
+  type RpcErrorDetailsMap,
+  type RpcId as RpcIdType,
+  type ServerResponse as RpcServerResponse,
+} from '@deepseek-ai/dsh-host-apiproxy/api'
+import { bridge, type FetchHandler } from './http-bridge.ts'
+import { isTrustedApiRequest } from './api-request-trust.ts'
+import { API_PATH } from './api-path.ts'
+import type {
+  ConnectionRpcEndpointMatcher,
+  ConnectionRpcHandler,
+  ConnectionRpcHandlerOptions,
+  HostConnectionHandle,
+  HostConnectionRpc,
+} from './rpc.ts'
+
+const INVALID_REQUEST_RPC_ID = RpcId('invalid-request')
+const CHANNEL_PATTERN = /^\/[A-Za-z0-9._~-]+$/
+const ENDPOINT_SEGMENT_PATTERN = /^[A-Za-z0-9_$.-]+$/
+
+interface ConnectionRpcInterceptor {
+  readonly matches: ConnectionRpcEndpointMatcher
+  readonly fetchHandler: FetchHandler
+  readonly options: ConnectionRpcHandlerOptions
+}
+
+declare module 'cordis' {
+  interface Context {
+    /** Host Connection transport and RPC registrations. */
+    connection: HostConnectionHandle
+  }
+}
+
+/** Host Connection service whose channel registrations belong to the caller fiber. */
+export class HostConnectionService extends Service implements HostConnectionHandle {
+  private readonly interceptors = new Map<string, ConnectionRpcInterceptor>()
+
+  /**
+   * Provide the Host half over the active HTTP server.
+   * @param ctx - owning Connection plugin context.
+   * @param trustedHosts - deployment authorities accepted by trusted-host channels.
+   */
+  constructor(ctx: Context, private readonly trustedHosts: readonly string[]) {
+    super(ctx, 'connection')
+  }
+
+  /** Generic channel registry scoped to the Context reading this service. */
+  get rpc(): HostConnectionRpc {
+    const owner = this.ctx
+    return {
+      handle: (channel, handler, options) => this.register(owner, channel, handler, options),
+      intercept: (channel, matches, handler, options) =>
+        this.registerInterceptor(owner, channel, matches, handler, options),
+    }
+  }
+
+  /**
+   * Compose one shared-channel Fetch handler from its interceptor and fallback.
+   * @param channel - shared channel mounted by Connection.
+   * @param fallback - handler for endpoints not claimed by the interceptor.
+   * @returns Fetch handler that selects exactly one target for each request.
+   */
+  createSharedFetchHandler(
+    channel: '/api',
+    fallback: FetchHandler,
+  ): FetchHandler {
+    return {
+      fetch: (request) => {
+        const endpoint = endpointFromPath(channel, new URL(request.url).pathname)
+        const interceptor = this.interceptors.get(channel)
+        if (endpoint === undefined || interceptor === undefined || !interceptor.matches(endpoint)) {
+          return fallback.fetch(request)
+        }
+        if (interceptor.options.authority === 'loopback' && !isTrustedApiRequest(request, [])) {
+          return Promise.resolve(new Response('forbidden', { status: 403 }))
+        }
+        return interceptor.fetchHandler.fetch(request)
+      },
+    }
+  }
+
+  private register(
+    owner: Context,
+    channel: string,
+    handler: ConnectionRpcHandler,
+    options: ConnectionRpcHandlerOptions,
+  ): () => Promise<void> {
+    assertChannel(channel)
+    const trustedHosts = options.authority === 'loopback' ? [] : this.trustedHosts
+    const fetchHandler = rpcFetchHandler(channel, handler)
+    const route: WebRoute = {
+      kind: 'prefix',
+      path: channel,
+      handler: async (req, res) => {
+        if (!isTrustedApiRequest(req, trustedHosts)) {
+          res.writeHead(403)
+          res.end('forbidden')
+          return
+        }
+        await bridge(req, res, fetchHandler)
+      },
+    }
+    return owner.effect(
+      () => owner.httpServer.register(route),
+      `client-connection: ${channel} rpc channel`,
+    )
+  }
+
+  private registerInterceptor(
+    owner: Context,
+    channel: string,
+    matches: ConnectionRpcEndpointMatcher,
+    handler: ConnectionRpcHandler,
+    options: ConnectionRpcHandlerOptions,
+  ): () => Promise<void> {
+    if (channel !== API_PATH) {
+      throw new Error(`connection: invalid shared RPC channel ${JSON.stringify(channel)}`)
+    }
+    const interceptor: ConnectionRpcInterceptor = {
+      matches,
+      fetchHandler: rpcFetchHandler(channel, handler),
+      options,
+    }
+    return owner.effect(() => {
+      if (this.interceptors.has(channel)) {
+        throw new Error(`connection: shared RPC channel ${JSON.stringify(channel)} already has an interceptor`)
+      }
+      this.interceptors.set(channel, interceptor)
+      return () => {
+        this.interceptors.delete(channel)
+      }
+    }, `client-connection: ${channel} rpc interceptor`)
+  }
+}
+
+function rpcFetchHandler(
+  channel: string,
+  handler: ConnectionRpcHandler,
+): FetchHandler {
+  return {
+    async fetch(request: Request): Promise<Response> {
+      const endpoint = endpointFromPath(channel, new URL(request.url).pathname)
+      if (request.method !== 'POST' || endpoint === undefined) {
+        return new Response('not found', { status: 404 })
+      }
+
+      const mediaType = request.headers.get('content-type')?.split(';', 1)[0]?.trim().toLowerCase()
+      if (mediaType !== 'application/json') {
+        return new Response('content type must be application/json', { status: 415 })
+      }
+
+      let body: unknown
+      try {
+        body = await request.json()
+      } catch {
+        return new Response('body is not JSON', { status: 400 })
+      }
+
+      const envelope = clientRequestSchema.safeParse(body)
+      if (!envelope.success) {
+        return invalidEnvelopeResponse(body, envelope.error.issues)
+      }
+      const message: ClientRequest = envelope.data
+      if (message.method !== endpoint) {
+        return errorResponse(message.rpcId, {
+          code: 'bad-request',
+          message: `method ${JSON.stringify(message.method)} does not match endpoint ${JSON.stringify(endpoint)}`,
+          details: { issues: [] },
+        })
+      }
+
+      try {
+        const result = await handler(endpoint, message.payload, request.signal)
+        return fullResponse(message.rpcId, result)
+      } catch (error) {
+        return new Response(`handler failure: ${String(error)}`, { status: 500 })
+      }
+    },
+  }
+}
+
+function invalidEnvelopeResponse(body: unknown, issues: RpcErrorDetailsMap['bad-request']['issues']): Response {
+  const rawId = (body as { rpcId?: unknown } | null)?.rpcId
+  const rpcId = typeof rawId === 'string' ? RpcId(rawId) : INVALID_REQUEST_RPC_ID
+  return errorResponse(rpcId, {
+    code: 'bad-request',
+    message: 'invalid client-request message',
+    details: { issues },
+  })
+}
+
+function endpointFromPath(channel: string, pathname: string): string | undefined {
+  if (!pathname.startsWith(`${channel}/`)) return undefined
+  const endpoint = pathname.slice(channel.length + 1)
+  const segments = endpoint.split('/')
+  if (segments.some(segment =>
+    segment === '' || segment === '.' || segment === '..' || !ENDPOINT_SEGMENT_PATTERN.test(segment))) {
+    return undefined
+  }
+  return endpoint
+}
+
+function errorResponse(rpcId: RpcIdType, error: RpcError): Response {
+  return fullResponse(rpcId, { ok: false, error })
+}
+
+function fullResponse(rpcId: RpcIdType, result: RpcServerResponse['result']): Response {
+  const body: RpcServerResponse = { type: 'server-response', rpcId, result }
+  return Response.json(body)
+}
+
+function assertChannel(channel: string): void {
+  if (!CHANNEL_PATTERN.test(channel) || channel === '/api') {
+    throw new Error(`connection: invalid or reserved RPC channel ${JSON.stringify(channel)}`)
+  }
+}

packages/client/connection/src/rpc.ts

@@ -0,0 +1,77 @@
+/** Generic unary RPC contracts shared by the Host and Client Connection halves. */
+
+import type { RpcResult } from '@deepseek-ai/dsh-host-apiproxy/api'
+
+/** Trust fence applied before a Host RPC channel reaches its handler. */
+export type ConnectionRpcAuthority = 'trusted-host' | 'loopback'
+
+/** Registration policy for one logical RPC channel. */
+export interface ConnectionRpcHandlerOptions {
+  /** Browser authority accepted by every endpoint in this channel. */
+  readonly authority: ConnectionRpcAuthority
+}
+
+/** Handler invoked after Connection has decoded the transport envelope. */
+export type ConnectionRpcHandler = (
+  endpoint: string,
+  payload: unknown,
+  signal: AbortSignal,
+) => Promise<RpcResult<unknown>>
+
+/** Synchronous ownership test for one endpoint on a shared RPC channel. */
+export type ConnectionRpcEndpointMatcher = (endpoint: string) => boolean
+
+/** Host registry for logical RPC channels carried by the current transport. */
+export interface HostConnectionRpc {
+  /**
+   * Register one absolute channel prefix and its trust policy.
+   * @param channel - absolute logical channel such as `/rpc`.
+   * @param handler - decoded endpoint handler returning the existing RPC result shape.
+   * @param options - channel trust policy.
+   * @returns asynchronous disposer removing the channel and its physical route.
+   */
+  handle(
+    channel: string,
+    handler: ConnectionRpcHandler,
+    options: ConnectionRpcHandlerOptions,
+  ): () => Promise<void>
+
+  /**
+   * Intercept owned endpoints on the shared `/api` channel before its fallback.
+   * @param channel - reserved shared channel; currently `/api`.
+   * @param matches - synchronous endpoint ownership test.
+   * @param handler - decoded endpoint handler returning the existing RPC result shape.
+   * @param options - trust policy for every endpoint claimed by this interceptor.
+   * @returns asynchronous disposer removing the interceptor.
+   */
+  intercept(
+    channel: '/api',
+    matches: ConnectionRpcEndpointMatcher,
+    handler: ConnectionRpcHandler,
+    options: ConnectionRpcHandlerOptions,
+  ): () => Promise<void>
+}
+
+/** Host `ctx.connection` shape consumed by transport-independent adapters. */
+export interface HostConnectionHandle {
+  /** Generic RPC channel registry. */
+  readonly rpc: HostConnectionRpc
+}
+
+/** Client caller for logical RPC channels carried by the current transport. */
+export interface ClientConnectionRpc {
+  /**
+   * Call one endpoint through an already registered logical channel.
+   * @param channel - absolute logical channel such as `/api`.
+   * @param endpoint - channel-relative endpoint such as `goals/create`.
+   * @param payload - channel-owned request payload.
+   * @param signal - optional caller cancellation.
+   * @returns the existing RPC success/error result; correlation stays inside Connection.
+   */
+  call(
+    channel: string,
+    endpoint: string,
+    payload: unknown,
+    signal?: AbortSignal,
+  ): Promise<RpcResult<unknown>>
+}

packages/client/connection/tests/client-apply.spec.ts

@@ -203,4 +203,119 @@ describe('connection client apply', () => {
     expect(sockets).toHaveLength(1)
     expect(sockets[0]?.readyState).toBe(FakeWebSocket.CLOSED)
   })
+
+  it('carries RPC calls without requiring secure-context randomUUID', async () => {
+    ;(globalThis as Win).location = { hostname: 'localhost', search: '' }
+    vi.stubGlobal('crypto', {
+      getRandomValues(bytes: Uint8Array) {
+        return bytes.fill(0)
+      },
+    })
+    const handle = await mount()
+    const original = globalThis.fetch
+    const seen: { url: string; body: unknown }[] = []
+    globalThis.fetch = async (input: URL | RequestInfo, init?: RequestInit) => {
+      const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
+      if (typeof init?.body !== 'string') throw new TypeError('expected a JSON string request body')
+      const body = JSON.parse(init.body) as { rpcId: string }
+      seen.push({ url, body })
+      return Response.json({
+        type: 'server-response',
+        rpcId: body.rpcId,
+        result: { ok: true, value: { ref: 'goal-1' } },
+      })
+    }
+    try {
+      await expect(handle.rpc.call('/api', 'goals/create', { args: { agentId: 'agent-1' } }))
+        .resolves.toEqual({ ok: true, value: { ref: 'goal-1' } })
+    } finally {
+      globalThis.fetch = original
+      vi.unstubAllGlobals()
+    }
+    expect(seen).toHaveLength(1)
+    expect(seen[0]?.url).toBe('http://dsh.internal/api/goals/create')
+    expect(seen[0]?.body).toMatchObject({
+      type: 'client-request',
+      rpcId: '00000000-0000-4000-8000-000000000000',
+      method: 'goals/create',
+      payload: { args: { agentId: 'agent-1' } },
+    })
+  })
+
+  it('validates generic RPC transport failures, correlation, and targets', async () => {
+    ;(globalThis as Win).location = {
+      hostname: 'harness.example', search: '', origin: 'https://harness.example',
+    }
+    const handle = await mount()
+    const original = globalThis.fetch
+    const abort = new AbortController()
+    globalThis.fetch = vi.fn().mockResolvedValue(new Response('unavailable', { status: 503 }))
+    try {
+      await expect(handle.rpc.call('/api', 'goals/create', {}, abort.signal))
+        .rejects.toThrow('HTTP 503')
+      expect(globalThis.fetch).toHaveBeenCalledWith(
+        new URL('https://harness.example/api/goals/create'),
+        expect.objectContaining({ signal: abort.signal }),
+      )
+
+      ;(globalThis as Win).location = { hostname: 'localhost', search: '', origin: 'null' }
+      globalThis.fetch = vi.fn().mockResolvedValue(Response.json({
+        type: 'server-response',
+        rpcId: 'different-rpc',
+        result: { ok: true, value: null },
+      }))
+      await expect(handle.rpc.call('/api', 'goals/create', {})).rejects.toThrow('rpcId mismatch')
+      const fetch = vi.mocked(globalThis.fetch)
+      expect(fetch.mock.calls[0]?.[0]).toEqual(new URL('http://dsh.internal/api/goals/create'))
+      expect(fetch.mock.calls[0]?.[1]).not.toHaveProperty('signal')
+    } finally {
+      globalThis.fetch = original
+    }
+
+    for (const [channel, endpoint] of [
+      ['api2', 'goals/create'],
+      ['/api/path', 'goals/create'],
+      ['/api', ''],
+      ['/api', '.'],
+      ['/api', '..'],
+      ['/api', 'goals//create'],
+      ['/api', 'goals/create?unsafe'],
+    ] as const) {
+      await expect(handle.rpc.call(channel, endpoint, {})).rejects.toThrow('invalid RPC target')
+    }
+  })
+
+  it('carries Goal Remotes over the same state as the client-only fixture API', async () => {
+    ;(globalThis as Win).location = { hostname: 'localhost', search: '?fixture' }
+    const handle = await mount()
+    const created = await handle.rpc.call('/api', 'goals/create', {
+      args: { agentId: 'fx-alpha', request: { objective: 'fixture remote' } },
+    })
+    expect(created).toMatchObject({ ok: true, value: { ref: { revision: 1 } } })
+    if (!created.ok) throw new Error('fixture Goal create failed')
+    const ref = (created.value as { ref: { id: string; revision: number } }).ref
+    const edited = await handle.rpc.call('/api', 'goals/edit', {
+      args: { agentId: 'fx-alpha', ref, request: { objective: 'edited fixture remote' } },
+    })
+    expect(edited).toMatchObject({ ok: true, value: { objective: 'edited fixture remote', revision: 2 } })
+    const editedRef = { id: ref.id, revision: 2 }
+    const paused = await handle.rpc.call('/api', 'goals/pause', {
+      args: { agentId: 'fx-alpha', ref: editedRef },
+    })
+    expect(paused).toMatchObject({ ok: true, value: { phase: 'paused', activation: 'disarmed', revision: 3 } })
+    const resumed = await handle.rpc.call('/api', 'goals/resume', {
+      args: { agentId: 'fx-alpha', ref: { id: ref.id, revision: 3 } },
+    })
+    expect(resumed).toMatchObject({ ok: true, value: { phase: 'active', activation: 'armed', revision: 4 } })
+    const completed = await handle.rpc.call('/api', 'goals/complete', {
+      args: { agentId: 'fx-alpha', ref: { id: ref.id, revision: 4 } },
+    })
+    expect(completed).toMatchObject({ ok: true, value: { phase: 'complete', activation: 'disarmed', revision: 5 } })
+    await expect(handle.rpc.call('/api', 'goals/clear', {
+      args: { agentId: 'fx-alpha', ref: { id: ref.id, revision: 5 } },
+    })).resolves.toEqual({ ok: true, value: { id: ref.id, revision: 6 } })
+    await expect(handle.rpc.call('/other', 'goals/create', {})).rejects.toThrow(/channel.*unavailable/)
+    await expect(handle.rpc.call('/api', 'unknown/read', { args: { agentId: 'fx-alpha' } }))
+      .rejects.toThrow(/endpoint.*unavailable/)
+  })
 })

packages/client/connection/tests/fake-api.ts

@@ -59,6 +59,7 @@ export class FakeApiClient implements IApiClient {
 
   onModels: (payload: unknown) => Promise<RpcResponse<SessionModels>> = () => Promise.resolve(ok({
     current: { provider: 'deepseek-official', model: 'deepseek-chat' },
+    routable: true,
     groups: [],
     failures: [],
   }))

packages/client/connection/tests/http-bridge.spec.ts

@@ -28,7 +28,7 @@ describe('HTTP bridge abort', () => {
     let carrierSignal: AbortSignal | undefined
     const pending = bridge(request, response, {
       fetch: async (input) => {
-        const fetchRequest = input as Request
+        const fetchRequest = input
         carrierSignal = fetchRequest.signal
         resolveStarted()
         if (!fetchRequest.signal.aborted) {

packages/client/connection/tests/node-half.spec.ts

@@ -7,8 +7,9 @@ import { describe, expect, it } from 'vitest'
 import type { AddressInfo } from 'node:net'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { ApiProxy } from '@deepseek-ai/dsh-host-apiproxy/api'
+import { RpcId, type ClientRequest } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { HttpServerService, WebRoute, WebUpgradeRoute } from '@deepseek-ai/dsh-host-webserver'
-import { API_PATH, apply, HOST_EVENTS_PATH, inject, MUX_EVENTS_PATH } from '../src/index.ts'
+import { API_PATH, apply, HOST_EVENTS_PATH, inject, MUX_EVENTS_PATH, type HostConnectionHandle } from '../src/index.ts'
 
 /** Structural httpServer fake recording both route registries. */
 function fakeHttpServer(
@@ -17,6 +18,9 @@ function fakeHttpServer(
 ): Pick<HttpServerService, 'register' | 'registerUpgrade' | 'tapIndex' | 'port'> {
   return {
     register(route) {
+      if (routes.some(candidate => candidate.kind === route.kind && candidate.path === route.path)) {
+        throw new Error(`duplicate route ${route.path}`)
+      }
       routes.push(route)
       return () => { routes.splice(routes.indexOf(route), 1) }
     },
@@ -36,15 +40,32 @@ function fakeRequest(headers: Record<string, string>, url = `${API_PATH}/session
   return request
 }
 
+/** JSON POST carrying a complete client-request envelope. */
+function fakePost(headers: Record<string, string>, url: string, body: unknown): IncomingMessage {
+  const request = Readable.from([Buffer.from(JSON.stringify(body))]) as unknown as IncomingMessage
+  Object.assign(request, { url, method: 'POST', headers: { 'content-type': 'application/json', ...headers } })
+  return request
+}
+
+/** Raw POST for malformed-body and media-type boundary cases. */
+function fakeRawPost(headers: Record<string, string>, url: string, body: string): IncomingMessage {
+  const request = Readable.from([Buffer.from(body)]) as unknown as IncomingMessage
+  Object.assign(request, { url, method: 'POST', headers })
+  return request
+}
+
 /** Response recorder compatible with both the fence's short-circuit and the bridge. */
 function fakeResponse(): { response: ServerResponse; state: { status?: number; body?: unknown } } {
   const state: { status?: number; body?: unknown } = {}
+  const chunks: Buffer[] = []
   const response = Object.assign(new EventEmitter(), {
     writableEnded: false,
     writeHead(value: number) { state.status = value; return this },
-    write() { return true },
+    write(value: string | Uint8Array) { chunks.push(Buffer.from(value)); return true },
     end(this: { writableEnded: boolean }, value?: unknown) {
-      if (value !== undefined) state.body = value
+      if (typeof value === 'string' || value instanceof Uint8Array) chunks.push(Buffer.from(value))
+      else if (value !== undefined) throw new TypeError('fake response only accepts string or Uint8Array bodies')
+      if (chunks.length > 0) state.body = Buffer.concat(chunks).toString()
       this.writableEnded = true
       return this
     },
@@ -173,6 +194,211 @@ describe('connection node half', () => {
     expect(declared.state.status).toBe(404)
     await dispose()
   })
+
+  it('provides a disposable dedicated RPC channel without requiring apiProxy', async () => {
+    const ctx = new Context()
+    const routes: WebRoute[] = []
+    ctx.provide('httpServer', fakeHttpServer(routes, []) as HttpServerService)
+    const fiber = ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    expect(routes).toHaveLength(1)
+    expect(routes[0]).toMatchObject({ kind: 'prefix', path: API_PATH })
+
+    const connection = ctx.get('connection') as HostConnectionHandle
+    const calls: unknown[] = []
+    const remove = connection.rpc.handle('/rpc', async (endpoint, payload) => {
+      calls.push({ endpoint, payload })
+      return { ok: true, value: { accepted: true } }
+    }, { authority: 'trusted-host' })
+    const route = routes.find(candidate => candidate.path === '/rpc')
+    expect(route).toBeDefined()
+
+    const request: ClientRequest = {
+      type: 'client-request',
+      rpcId: RpcId('rpc-dedicated'),
+      method: 'goals/create',
+      payload: { args: { agentId: 'agent-1' } },
+    }
+    const result = fakeResponse()
+    await route!.handler(fakePost({ host: '127.0.0.1:3080' }, '/rpc/goals/create', request), result.response)
+    expect(result.state.status).toBe(200)
+    expect(JSON.parse(String(result.state.body))).toEqual({
+      type: 'server-response',
+      rpcId: 'rpc-dedicated',
+      result: { ok: true, value: { accepted: true } },
+    })
+    expect(calls).toEqual([{
+      endpoint: 'goals/create',
+      payload: { args: { agentId: 'agent-1' } },
+    }])
+
+    expect(() => connection.rpc.handle('/rpc', async () => ({ ok: true, value: null }), {
+      authority: 'trusted-host',
+    })).toThrow(/duplicate route/)
+    await remove()
+    expect(routes.map(candidate => candidate.path)).toEqual([API_PATH])
+    await fiber.dispose()
+    expect(routes).toHaveLength(0)
+  })
+
+  it('dispatches claimed /api endpoints before the API Proxy fallback and withdraws the claim', async () => {
+    const ctx = new Context()
+    const routes: WebRoute[] = []
+    ctx.provide('httpServer', fakeHttpServer(routes, []) as HttpServerService)
+    ctx.provide('apiProxy', {} as unknown as ApiProxy)
+    const fiber = ctx.plugin({ inject: [...inject], apply }, { trustedHosts: ['harness.example'] })
+    await fiber.await()
+    const connection = ctx.get('connection') as HostConnectionHandle
+    const calls: unknown[] = []
+    const remove = connection.rpc.intercept(
+      '/api',
+      endpoint => endpoint === 'goals/create',
+      async (endpoint, payload) => {
+        calls.push({ endpoint, payload })
+        return { ok: true, value: { accepted: true } }
+      },
+      { authority: 'trusted-host' },
+    )
+    expect(() => connection.rpc.intercept(
+      '/api',
+      () => true,
+      async () => ({ ok: true, value: null }),
+      { authority: 'trusted-host' },
+    )).toThrow('already has an interceptor')
+    expect(() => connection.rpc.intercept(
+      '/rpc' as '/api',
+      () => true,
+      async () => ({ ok: true, value: null }),
+      { authority: 'trusted-host' },
+    )).toThrow('invalid shared RPC channel')
+    const route = routes.find(candidate => candidate.path === API_PATH)!
+    const request: ClientRequest = {
+      type: 'client-request',
+      rpcId: RpcId('rpc-shared'),
+      method: 'goals/create',
+      payload: { args: { agentId: 'agent-1' } },
+    }
+
+    const claimed = fakeResponse()
+    await route.handler(fakePost({ host: '127.0.0.1:3080' }, '/api/goals/create', request), claimed.response)
+    expect(JSON.parse(String(claimed.state.body))).toEqual({
+      type: 'server-response',
+      rpcId: 'rpc-shared',
+      result: { ok: true, value: { accepted: true } },
+    })
+    expect(calls).toEqual([{
+      endpoint: 'goals/create',
+      payload: { args: { agentId: 'agent-1' } },
+    }])
+
+    const denied = fakeResponse()
+    await route.handler(fakePost({ host: 'other.example' }, '/api/goals/create', request), denied.response)
+    expect(denied.state).toMatchObject({ status: 403, body: 'forbidden' })
+    expect(calls).toHaveLength(1)
+
+    const unclaimed = fakeResponse()
+    await route.handler(fakeRequest({ host: '127.0.0.1:3080' }, '/api/session.list'), unclaimed.response)
+    expect(unclaimed.state.status).toBe(404)
+
+    await remove()
+    const withdrawn = fakeResponse()
+    await route.handler(fakePost({ host: '127.0.0.1:3080' }, '/api/goals/create', request), withdrawn.response)
+    expect(withdrawn.state.status).toBe(404)
+    expect(calls).toHaveLength(1)
+
+    const removeLoopback = connection.rpc.intercept(
+      '/api',
+      endpoint => endpoint === 'goals/create',
+      async () => ({ ok: true, value: null }),
+      { authority: 'loopback' },
+    )
+    const loopbackOnly = fakeResponse()
+    await route.handler(fakePost({ host: 'harness.example' }, '/api/goals/create', request), loopbackOnly.response)
+    expect(loopbackOnly.state.status).toBe(403)
+    await removeLoopback()
+    await fiber.dispose()
+  })
+
+  it('applies the configured trust fence and JSON envelope checks to generic channels', async () => {
+    const ctx = new Context()
+    const routes: WebRoute[] = []
+    ctx.provide('httpServer', fakeHttpServer(routes, []) as HttpServerService)
+    const fiber = ctx.plugin({ inject: [...inject], apply }, { trustedHosts: ['harness.example'] })
+    await fiber.await()
+    const connection = ctx.get('connection') as HostConnectionHandle
+    const remove = connection.rpc.handle('/rpc', async (endpoint) => {
+      if (endpoint === 'fail') throw new Error('handler broke')
+      return { ok: true, value: null }
+    }, {
+      authority: 'trusted-host',
+    })
+    const route = routes.find(candidate => candidate.path === '/rpc')!
+
+    const denied = fakeResponse()
+    await route.handler(fakePost({ host: 'other.example' }, '/rpc/goals/create', {}), denied.response)
+    expect(denied.state).toMatchObject({ status: 403, body: 'forbidden' })
+
+    const methodMismatch = fakeResponse()
+    await route.handler(fakePost({ host: 'harness.example' }, '/rpc/goals/create', {
+      type: 'client-request', rpcId: 'rpc-bad', method: 'other', payload: {},
+    }), methodMismatch.response)
+    expect(JSON.parse(String(methodMismatch.state.body))).toMatchObject({
+      rpcId: 'rpc-bad',
+      result: { ok: false, error: { code: 'bad-request' } },
+    })
+
+    for (const [request, status] of [
+      [fakeRequest({ host: 'harness.example' }, '/rpc/goals/create'), 404],
+      [fakePost({ host: 'harness.example' }, '/outside/goals/create', {}), 404],
+      [fakePost({ host: 'harness.example' }, '/rpc/goals//create', {}), 404],
+      [fakeRawPost({ host: 'harness.example' }, '/rpc/goals/create', '{}'), 415],
+      [fakeRawPost({ host: 'harness.example', 'content-type': 'text/plain' }, '/rpc/goals/create', '{}'), 415],
+      [fakeRawPost({ host: 'harness.example', 'content-type': 'application/json; charset=utf-8' }, '/rpc/goals/create', '{'), 400],
+    ] as const) {
+      const response = fakeResponse()
+      await route.handler(request, response.response)
+      expect(response.state.status).toBe(status)
+    }
+
+    for (const [body, rpcId] of [
+      [{ rpcId: 'retained-id' }, 'retained-id'],
+      [{ rpcId: 42 }, 'invalid-request'],
+      [null, 'invalid-request'],
+    ] as const) {
+      const response = fakeResponse()
+      await route.handler(fakePost({ host: 'harness.example' }, '/rpc/goals/create', body), response.response)
+      expect(JSON.parse(String(response.state.body))).toMatchObject({
+        rpcId,
+        result: { ok: false, error: { code: 'bad-request' } },
+      })
+    }
+
+    const failed = fakeResponse()
+    await route.handler(fakePost({ host: 'harness.example' }, '/rpc/fail', {
+      type: 'client-request', rpcId: 'rpc-fail', method: 'fail', payload: {},
+    }), failed.response)
+    expect(failed.state).toMatchObject({ status: 500, body: 'handler failure: Error: handler broke' })
+
+    expect(() => connection.rpc.handle('/api', async () => ({ ok: true, value: null }), {
+      authority: 'loopback',
+    })).toThrow('invalid or reserved RPC channel')
+    expect(() => connection.rpc.handle('api3', async () => ({ ok: true, value: null }), {
+      authority: 'loopback',
+    })).toThrow('invalid or reserved RPC channel')
+
+    const removeLoopback = connection.rpc.handle('/loopback', async () => ({ ok: true, value: null }), {
+      authority: 'loopback',
+    })
+    const loopbackRoute = routes.find(candidate => candidate.path === '/loopback')!
+    const publicResponse = fakeResponse()
+    await loopbackRoute.handler(fakePost({ host: 'harness.example' }, '/loopback/read', {
+      type: 'client-request', rpcId: 'rpc-public', method: 'read', payload: {},
+    }), publicResponse.response)
+    expect(publicResponse.state.status).toBe(403)
+    await removeLoopback()
+    await remove()
+    await fiber.dispose()
+  })
 })
 
 describe('connection node half over a real HTTP server', () => {

packages/client/runtime/package.json

@@ -24,7 +24,8 @@
   },
   "dshClient": {
     "inject": [
-      "@deepseek-ai/dsh-client-connection"
+      "@deepseek-ai/dsh-client-connection",
+      "@deepseek-ai/dsh-typert-registry"
     ],
     "platform": "web",
     "immediately": true
@@ -47,11 +48,15 @@
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-type-meta": "^0.0.1",
+    "@deepseek-ai/dsh-typert-registry": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-timeout": "workspace:^",
+    "@deepseek-ai/dsh-type-meta": "workspace:^",
+    "@deepseek-ai/dsh-typert-registry": "workspace:^",
     "@types/react": "~18.3.1",
     "cordis": "^4.0.0-rc.7"
   },

packages/client/runtime/src/client/agents/scope.ts

@@ -18,6 +18,12 @@
 import { Context as CordisContext } from 'cordis'
 import type { Context, Fiber } from 'cordis'
 import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import type { TypeRTClientRemote, TypeRTRemoteScopeApi } from '@deepseek-ai/dsh-type-meta'
+
+/** Client Cordis Context carrying one Agent identity and its scoped Remote namespaces. */
+export type AgentContext = Omit<Context, 'remote'> & {
+  readonly remote: TypeRTClientRemote & TypeRTRemoteScopeApi<'agent'>
+}
 
 /** Context tag written by {@link createScope}. */
 const kScope = Symbol('dsh.client.scope')
@@ -29,7 +35,7 @@ export interface AgentScopeHandle {
    * through it (passing it as the dispatch subject routes to this agent's
    * tagged listeners plus every untagged one).
    */
-  ctx: Context
+  ctx: AgentContext
   /** Backing fiber (dispose tears down every scope-owned registration). */
   fiber: Fiber
 }
@@ -48,15 +54,16 @@ function agentScope(): void {}
  */
 export function createScope(ctx: Context, key: SessionId): AgentScopeHandle {
   const fiber = ctx.plugin(agentScope)
+  const scoped = fiber.ctx.extend({
+    [kScope]: key,
+    [CordisContext.filter](listenerCtx: Context): boolean {
+      const tag = scopeOf(listenerCtx)
+      return tag === undefined || tag === key
+    },
+  }) as AgentContext
   return {
     fiber,
-    ctx: fiber.ctx.extend({
-      [kScope]: key,
-      [CordisContext.filter](listenerCtx: Context): boolean {
-        const tag = scopeOf(listenerCtx)
-        return tag === undefined || tag === key
-      },
-    }),
+    ctx: scoped,
   }
 }
 

packages/client/runtime/src/client/contract/sessions.ts

@@ -12,6 +12,7 @@ import type {
   RpcResult, SessionId, SubagentAddress,
 } from '@deepseek-ai/dsh-client-connection/client'
 import type { HostObservable, SessionMaybeProvideInfo } from '@deepseek-ai/dsh-client-ui-slots'
+import type { AgentContext } from '../agents/scope.ts'
 import type { SessionSearchResultItem } from '../sessions/manager.ts'
 import type {
   SessionBinding, SessionListState, SessionProvideDescriptor,
@@ -19,6 +20,8 @@ import type {
 import type { SessionFace } from './session.ts'
 import type { ObservableSnapshot } from './store.ts'
 
+export type { AgentContext } from '../agents/scope.ts'
+
 /** The sessions-service face injected as `ctx.sessions`. */
 export interface ISessions {
   /** The useSessions standard feed (list rows + current selection; read face — writes stay inside the domain). */
@@ -95,7 +98,7 @@ export interface ISessions {
    * @param id - session id.
    * @returns scoped ctx, or undefined for a session neither listed nor already scoped.
    */
-  scope(id: SessionId): Context | undefined
+  scope(id: SessionId): AgentContext | undefined
   /**
    * Read the Agent scope tag off a context (service-method seam: fetch
    * bundles must reach scope resolution through ctx.sessions).

packages/client/runtime/src/client/index.ts

@@ -1,6 +1,7 @@
 /** Browser runtime services for slots, sessions, workspaces, and connection-stream delivery. */
 import type { Context } from 'cordis'
 import type { ConnectionHandle, SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import type { TypeRTContext } from '@deepseek-ai/dsh-type-meta'
 import type { MaybeSnapshotSelectorHook, SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotsService } from './slots.ts'
 import { SessionsService } from './sessions/service.ts'
@@ -26,7 +27,7 @@ export type { ISession, ProjectionsFace, SessionFace } from './contract/session.
 export type {
   ISessionHistory, SessionHistoryFace, SessionHistorySnapshot,
 } from './contract/session-history.ts'
-export type { ISessions } from './contract/sessions.ts'
+export type { AgentContext, ISessions } from './contract/sessions.ts'
 export type { IWorkspaces } from './contract/workspaces.ts'
 export type {
   SessionBinding, SessionListState, SessionProvideContribution, SessionProvideDescriptor, SessionSummary,
@@ -75,6 +76,13 @@ export type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
 /** Client-side Cordis context after declaration merging. */
 export type ClientContext = Context
 
+declare module '@deepseek-ai/dsh-type-meta' {
+  interface TypeRTContextMap {
+    /** Client Agent scope identity; the agent and session share one wire id. */
+    agent: TypeRTContext<SessionId>
+  }
+}
+
 /** The conversation-snapshot selector hook (ConvViewProps/ToolRowProps take this). */
 export type UseConversationSession = SnapshotSelectorHook<ConversationSnapshot>
 
@@ -170,8 +178,8 @@ declare module 'cordis' {
   }
 }
 
-/** Required services: the wire handle mounted by the connection plugin. */
-export const inject = ['connection']
+/** Required services: the wire handle and Client TypeRT registry. */
+export const inject = ['connection', 'typert']
 
 /** Mounts the browser runtime services and connection stream.
  * @param ctx - Client Cordis context.
@@ -180,6 +188,9 @@ export function apply(ctx: Context): void {
   ctx.plugin(SlotsService)
   const connection = ctx.get('connection') as ConnectionHandle
   const sessions = new SessionsService(ctx, connection.api)
+  ctx.typert.contexts.registerClient('agent', {
+    identity: candidate => sessions.scopeOf(candidate),
+  })
   const sessionHistory = new SessionHistoryService(ctx, connection.api)
   const workspaces = new WorkspacesService(ctx, connection.api, sessions)
   ctx.effect(

packages/client/runtime/src/client/sessions/service.ts

@@ -29,7 +29,7 @@ import type { SessionProjectionMap } from '@deepseek-ai/dsh-session-projection/t
 import type { SnapshotStore } from '../contract/store.ts'
 import { createSnapshotStore } from '../contract/store.ts'
 import type { SessionFace } from '../contract/session.ts'
-import type { ISessions } from '../contract/sessions.ts'
+import type { AgentContext, ISessions } from '../contract/sessions.ts'
 import { createScope, scopeOf as scopeTagOf } from '../agents/scope.ts'
 import { SessionManager } from './manager.ts'
 import type { SessionListPhase, SessionSearchResultItem, SubagentCatalogSnapshot } from './manager.ts'
@@ -133,7 +133,7 @@ export interface SessionBinding {
   readonly sessionId: SessionId
   /** The outward session face only — feature code never sees the concrete class. */
   readonly session: SessionFace
-  readonly ctx: Context
+  readonly ctx: AgentContext
 }
 
 // Scope primitives live in ../agents/scope.ts (the client mirror of host
@@ -188,7 +188,7 @@ function increasedForkTitle(title: string): string {
 
 interface ScopeRecord {
   fiber: Fiber
-  ctx: Context
+  ctx: AgentContext
   binding: SessionBinding
   /** The concrete Session for runtime-internal entry points (staging open()); the binding carries only the outward face. */
   session: Session
@@ -489,7 +489,7 @@ export class SessionsService implements ISessions {
    * @param id - session id (the agent identity — 1:1 same axis).
    * @returns scoped ctx, or undefined for a session neither listed nor already scoped.
    */
-  scope(id: SessionId): Context | undefined {
+  scope(id: SessionId): AgentContext | undefined {
     return this.resolve(id)?.ctx
   }
 

packages/client/runtime/tests/client-apply.spec.ts

@@ -8,6 +8,7 @@ import { describe, expect, it } from 'vitest'
 import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
 import type { ConnectionSinks } from '@deepseek-ai/dsh-client-connection/client'
 import { SESSION_SEARCH_RESULT_LIMIT } from '@deepseek-ai/dsh-host-apiproxy/api'
+import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
 import * as RuntimeClient from '../src/client/index.ts'
 import type { SessionsService } from '../src/client/sessions/service.ts'
 import type { WorkspacesService } from '../src/client/workspaces/service.ts'
@@ -22,17 +23,22 @@ interface Bench {
 
 async function mount(): Promise<Bench> {
   const ctx = new Context()
+  await ctx.plugin(TypertRegistry)
   const api = new FakeApiClient()
   const bench: Bench = { ctx, api, sinks: undefined, stopped: 0 }
   const handle: ConnectionHandle = {
     api,
     isLoopback: true,
+    rpc: {
+      call: () => Promise.reject(new Error('unexpected generic RPC call')),
+    },
     start: (sinks) => {
       bench.sinks = sinks
       return { stop: () => { bench.stopped += 1 } }
     },
   }
   ctx.reflect.provide('connection', handle)
+  ctx.reflect.provide('remote', {})
   await ctx.plugin(RuntimeClient).await()
   return bench
 }

packages/client/runtime/tests/fake-api.ts

@@ -73,6 +73,7 @@ export class FakeApiClient implements IApiClient {
 
   onModels: (payload: unknown) => Promise<RpcResponse<SessionModels>> = () => Promise.resolve(ok({
     current: this.defaultModel,
+    routable: true,
     groups: [{
       id: 'deepseek-official',
       name: 'DeepSeek',

packages/client/runtime/tests/wire-events.spec.ts

@@ -6,6 +6,7 @@
 import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
 import type { ConnectionHandle, ConnectionSinks } from '@deepseek-ai/dsh-client-connection/client'
+import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
 import * as RuntimeClient from '../src/client/index.ts'
 import { FakeApiClient } from './fake-api.ts'
 
@@ -16,17 +17,22 @@ interface Bench {
 
 async function mount(): Promise<Bench> {
   const ctx = new Context()
+  await ctx.plugin(TypertRegistry)
   const api = new FakeApiClient()
   const bench: Bench = { ctx, sinks: undefined }
   const handle: ConnectionHandle = {
     api,
     isLoopback: true,
+    rpc: {
+      call: () => Promise.reject(new Error('unexpected generic RPC call')),
+    },
     start: (sinks) => {
       bench.sinks = sinks
       return { stop: () => {} }
     },
   }
   ctx.reflect.provide('connection', handle)
+  ctx.reflect.provide('remote', {})
   await ctx.plugin(RuntimeClient).await()
   return bench
 }

packages/client/runtime/tsconfig.json

@@ -43,6 +43,12 @@
     },
     {
       "path": "../../support/invariants"
+    },
+    {
+      "path": "../../typert/type-meta"
+    },
+    {
+      "path": "../../typert/registry"
     }
   ],
   "exclude": [

packages/client/schema-form/tsdown.config.ts

@@ -0,0 +1,6 @@
+import { clientLibrary } from '../tsdown.client.ts'
+
+export default clientLibrary(
+  '@deepseek-ai/dsh-client-schema-form',
+  ['lib/types/index.js', 'lib/types/invariant.js'],
+)

packages/client/test-runtime/src/sessions.ts

@@ -3,7 +3,7 @@ import type { Context } from 'cordis'
 import { createScope, scopeOf, SessionProvideChannel } from '@deepseek-ai/dsh-client-runtime/client'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import type {
-  ConversationSnapshot, ISessions, ObservableSnapshot, ProjectionsFace, SessionFace, SessionId,
+  AgentContext, ConversationSnapshot, ISessions, ObservableSnapshot, ProjectionsFace, SessionFace, SessionId,
   SessionListState, SessionProvideDescriptor, SessionSearchResultItem, SessionSummary, SnapshotStore,
   SubagentAddress,
 } from '@deepseek-ai/dsh-client-runtime/client'
@@ -134,7 +134,7 @@ interface SessionRecord {
   summary: SessionSummary
   snapshot: SnapshotStore<ConversationSnapshot>
   session: FixtureSession
-  scope: Context | undefined
+  scope: AgentContext | undefined
   scopeFiber: { dispose(): Promise<void> } | undefined
   /** Materialized standard-props bundle (identity-stable per session; invalidated on roster change). */
   provideInfo: SessionProvideInfo | undefined
@@ -144,7 +144,7 @@ interface SessionRecord {
 export interface TestSessionBinding {
   readonly sessionId: SessionId
   readonly session: FixtureSession
-  readonly ctx: Context
+  readonly ctx: AgentContext
 }
 
 /**
@@ -345,7 +345,7 @@ export class TestSessions implements ISessions {
    * @param id - session id.
    * @returns the scoped context, or undefined for unknown sessions.
    */
-  scope(id: string): Context | undefined {
+  scope(id: string): AgentContext | undefined {
     const record = this.records.get(id as SessionId)
     if (record === undefined) return undefined
     if (record.scope === undefined) {

packages/client/test-runtime/tsdown.config.ts

@@ -0,0 +1,6 @@
+import { clientLibrary } from '../tsdown.client.ts'
+
+export default clientLibrary(
+  '@deepseek-ai/dsh-client-test-runtime',
+  ['lib/types/index.js', 'lib/types/invariant.js'],
+)

packages/client/tsdown.client.ts

@@ -9,6 +9,7 @@
  * The virtual loader registers each real stylesheet as a watch dependency.
  */
 import { readFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
 import { basename, dirname, relative, resolve as resolvePath, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import type { UserConfig } from 'tsdown'
@@ -31,6 +32,15 @@ const CSS_VIRTUAL_SUFFIX = '.mjs'
  */
 export const INLINE_SAFE = /^@deepseek-ai\/dsh-(host-apiproxy|session|llm|tools|brand)(\/|$)/
 
+/** Generated descriptor/codec contribution with no shared runtime identity. */
+const GENERATED_REMOTE = /^@deepseek-ai\/dsh-[a-z0-9]+(?:-[a-z0-9]+)*\/remote$/
+
+/**
+ * Workspace mode replaces an empty config array with the root defaults. A
+ * falsey entry instead removes this package before entry resolution.
+ */
+const SKIP_WORKSPACE_BUILD: UserConfig = { entry: '' }
+
 /**
  * Documented TEMPORARY exemption, not a platform module (hence not in
  * platform.ts): the snapshot-store engine (createSnapshotStore/defineStore/
@@ -58,19 +68,85 @@ function browserSourcePath(source: string, sourcemapPath: string): string {
 
 /**
  * Build the tsdown config for one UI plugin package: the node-half lib build
- * plus the browser client bundle. A package-level tsdown.config.ts REPLACES
- * the root workspace shape, so the lib half must be restated here — dropping
- * it leaves the package without lib/index.js and the host Loader cannot
- * import its node half.
+ * plus the browser client bundle. Client packages emit both halves during the
+ * Client pass by default; packages needed for Host reflection may opt into the
+ * earlier Host pass. A package-level tsdown.config.ts REPLACES the root
+ * workspace shape, so the lib half must be restated here — dropping it leaves
+ * the package without lib/index.js and the host Loader cannot import its node
+ * half.
  * @param id - plugin id (package name), stamped into the __ModuleLoader__.load
  * handoff and onto the injected style tags.
  * @param libEntry - node-half entries, spelled at the call site so the
  * package-invariants gate can see `lib/types/invariant.js` in each package's
  * own tsdown.config.ts (a preset-side glob hides it from the mechanical check).
- * @returns tsdown user configs emitting lib/*.js and lib/client.js.
+ * @param options - phase placement, lib overrides, and companion Node configs.
+ * @returns ENV-selected tsdown config for the current build face.
  */
-export function clientBundle(id: string, libEntry: readonly string[]): [UserConfig, UserConfig] {
-  return [{
+export function clientBundle(
+  id: string,
+  libEntry: readonly string[],
+  options: ClientBundleOptions = {},
+): BuildFaceConfig {
+  const lib = clientLibraryConfig(id, libEntry, options.lib)
+  return ({ env }) => {
+    const face = buildFace(env?.DSH_BUILD_FACE)
+    const client = clientConfig(id, face === undefined
+      ? 'src/client/index.ts'
+      : 'lib/types/client/index.js')
+    const node = [lib, ...(options.companions ?? [])]
+    if (face === 'host') return options.hostPhase === true ? node : [SKIP_WORKSPACE_BUILD]
+    if (face === 'client') return options.hostPhase === true ? [client] : [...node, client]
+    return [...node, client]
+  }
+}
+
+/**
+ * Build a Client-only Node library during the Client pass.
+ * @param id - Package name used in tsdown diagnostics.
+ * @param libEntry - Emitted JavaScript entries consumed from `lib/types`.
+ * @returns ENV-selected tsdown config for the Client build face.
+ */
+export function clientLibrary(id: string, libEntry: readonly string[]): BuildFaceConfig {
+  const lib = clientLibraryConfig(id, libEntry)
+  return clientOnly([lib])
+}
+
+/**
+ * Select arbitrary package-local configs only during the Client pass.
+ * @param configs - Node-side configs emitted after Client tsc.
+ * @returns ENV-selected tsdown config for the Client build face.
+ */
+export function clientOnly(configs: readonly UserConfig[]): BuildFaceConfig {
+  return ({ env }) => buildFace(env?.DSH_BUILD_FACE) === 'host'
+    ? [SKIP_WORKSPACE_BUILD]
+    : [...configs]
+}
+
+interface ClientBundleOptions {
+  /** Emit the Node-side artifacts during the Host pass instead of the Client pass. */
+  readonly hostPhase?: boolean
+  /** Additional Node-side configs emitted alongside the package library. */
+  readonly companions?: readonly UserConfig[]
+  /** Overrides for the package's primary Node-side library config. */
+  readonly lib?: UserConfig
+}
+
+type BuildFace = 'host' | 'client' | undefined
+
+type BuildFaceConfig = (inlineConfig: Pick<UserConfig, 'env'>) => UserConfig[]
+
+function buildFace(value: unknown): BuildFace {
+  if (value === undefined || value === 'host' || value === 'client') return value
+  throw new Error(`tsdown: --env.DSH_BUILD_FACE must be host or client, received ${String(value)}`)
+}
+
+function clientLibraryConfig(
+  id: string,
+  libEntry: readonly string[],
+  overrides: UserConfig = {},
+): UserConfig {
+  return {
+    name: id,
     entry: [...libEntry],
     outDir: 'lib',
     format: ['esm'],
@@ -79,8 +155,14 @@ export function clientBundle(id: string, libEntry: readonly string[]): [UserConf
     fixedExtension: false,
     dts: false,
     clean: false,
-  }, {
-    entry: { client: 'src/client/index.ts' },
+    ...overrides,
+  }
+}
+
+function clientConfig(id: string, entry: string): UserConfig {
+  return {
+    name: `${id}/client`,
+    entry: { client: entry },
     // Browser bundle lands next to the node half (single lib/ artifact dir;
     // the entryFileNames pin keeps it exactly lib/client.js). clean must stay
     // off — a default clean would wipe the node-half output emitted above.
@@ -126,9 +208,9 @@ export function clientBundle(id: string, libEntry: readonly string[]): [UserConf
       resolveId(source: string) {
         if (!source.startsWith('@deepseek-ai/')) return null
         if (CLIENT_EXTERNALS.includes(source)) return null // platform module: external wins
-        if (INLINE_SAFE.test(source)) return null // wire/type layer: inline is the point
+        if (INLINE_SAFE.test(source) || GENERATED_REMOTE.test(source)) return null // wire contribution: inline is the point
         throw new Error(
-          `client bundle purity: "${source}" is not a platform module (CLIENT_EXTERNALS) and not an inline-safe wire layer — `
+          `client bundle purity: "${source}" is not a platform module (CLIENT_EXTERNALS), an inline-safe wire layer, or a generated /remote contribution — `
           + 'cross-plugin value imports are forbidden; collaborate through cordis services (type-only imports are erased and never reach this gate)',
         )
       },
@@ -136,7 +218,7 @@ export function clientBundle(id: string, libEntry: readonly string[]): [UserConf
       name: 'dsh-css-modules-inline',
       resolveId(source: string, importer: string | undefined) {
         if (!source.endsWith('.module.css')) return null
-        const abs = importer !== undefined ? resolvePath(dirname(importer), source) : source
+        const abs = importer !== undefined ? sourceAssetPath(source, importer) : source
         return CSS_VIRTUAL_PREFIX + abs + CSS_VIRTUAL_SUFFIX
       },
       async load(virtualId: string) {
@@ -179,5 +261,15 @@ export function clientBundle(id: string, libEntry: readonly string[]): [UserConf
       footer: `return module.exports; } });`,
       intro: 'var module = { exports: {} }; var exports = module.exports;',
     },
-  }]
+  }
+}
+
+/** Resolve an emitted JS asset import against its source-tree counterpart. */
+function sourceAssetPath(source: string, importer: string): string {
+  const emitted = resolvePath(dirname(importer), source)
+  if (existsSync(emitted)) return emitted
+  const marker = `${sep}lib${sep}types${sep}`
+  const boundary = emitted.indexOf(marker)
+  if (boundary < 0) return emitted
+  return resolvePath(emitted.slice(0, boundary), 'src', emitted.slice(boundary + marker.length))
 }

packages/client/ui-conversation/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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/client/ui-conversation/README.md
-README.md: a75f25d8669cd688795842a655106e0e27bb7173
-README.zh.md: f0d744c31020730857d210d75749b907dbffca08
+README.md: 0cf50146cc44ef0d6cc060a4c97b3d1ff454f013
+README.zh.md: 8bfb96bb9326d8fcadc3c357b6abaad88c92bd17

packages/client/ui-conversation/README.md

@@ -8,17 +8,19 @@ Compaction renders as one collapsed row at the checkpoint's flow position withou
 
 The resident conversation shell survives no-session and session transitions. Without a current session it renders a disabled input bar; its root-scoped `conversation.hero.workspace` slot hosts the Workspace picker. Selecting a Workspace connects or reuses its Host-owned blank session and opens that session without replacing the shell. The root always owns the same scrollport and Hero/composer subtree; separate strict-session header and body outlets fill their regions when the first Session arrives, so the Workspace picker, scroll body, composer seat, and textarea retain their React and DOM identity. Blank sessions render the same composer body as active sessions, while the InputHub carries drafts across Workspace switches and mirrors them into the session store. In the active phase the session header shows only the current session title and view tabs as ordinary column chrome; fork lineage remains session data and is not projected into the header. Beneath it the scrollport (`data-conversation-scroll`) holds the flowing views and the sticky composer stack (stats dock + input docks + bar). That scrollport reserves its scrollbar gutter unconditionally, and a view opting into a composer overlay leaves it a scroll container, so the input card keeps one horizontal position whether or not the transcript scrolls and whichever view tab is shown ([decision](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)). Wheel over the textarea chains: the capped draft scrolls locally until its edge, then forwards to that host.
 
+Another plugin can make one session's composer inert through `ctx.conversation.blocks`: it sets a block carrying its own localized reason, and the bar renders the same disabled textarea with that reason as the placeholder — the no-workspace posture, reused. The push direction is the constraint, not a preference: the plugins that know a session cannot send (ui-model, when no adapter serves its route) already depend on this package, so this package cannot read them. The model seat is the one control a block leaves live — every block this contract has is cleared by choosing a model, so locking it too would leave the composer asking for the only thing it prevents. A block is an affordance only; the Host refuses a prompt it cannot route regardless of what any client disables. The no-workspace state wins when both hold, because picking a workspace is the earlier prerequisite.
+
 The view ring is a slot: the strict session-body registration declares the session-scoped `'conversation.view'` list in its `children` table, that body renders the active entry through its renderSlot share (`only: <active id>`), and view tabs project from registration options (`id`/`order`/`label`). The chat view is this package's own entry; plugins such as ui-trajectory contribute tabs through `ctx.slots.register`, and each view owns its chrome.
 
 Approvals take over the composer through the chain this package declares: `ApprovalPanel` registers as a selector-routed `'conversation.composer'` entry (the ui-question pattern) and occupies the composer in place of the InputBar while an approval wait is pending (amber strip, justification headline, paired command line from the running call's args, one-shot refuse/allow). The `PendingApproval` domain face in `contract/slots.ts` owns the wire encoding — the `ApprovalResponsePayload` value with the audit correlation — over the runtime's `PendingWait` carrier; the broadcast `approval/resolved` frame settles the wait and restores the composer. The runtime manager projects every approval or question wait through `SessionSummary.pendingInteraction`, including sessions never instantiated; `ui-workspace` owns its sidebar presentation. Pending waits leave the message flow entirely: questions (ui-question) and approvals (ApprovalPanel) both answer through the composer takeover, so no display-only placeholder card remains. The composer's bottom-row Access seat mounts `PermissionSelect`, fed by the host-computed `permissions` projection through the standard-kit `useProjection` (key absence hides the chip); the chip opens a Menu-primitive dropdown whose kebab-case preset names render as title-case labels. Safe preset picks submit `/permission <preset>` immediately through the bar's injected `command` callback, while `danger-full-access` is presented as `Full access` and first opens an in-page Modal risk confirmation. The enabling action stays disabled until the user checks the acknowledgement; cancel, Escape, close, and mask click submit nothing.
 
 The session header declares and renders the session-scoped `'conversation.session.header.actions'` list beside the title, allowing feature plugins to contribute controls without entering the skeleton. The composer chain currency includes the current conversation `session`; ui-subagent selects one-shot or parent-unavailable addressed sessions for reason-specific read-only copy, while the ordinary InputBar keeps every addressed child Send-only because the continuation service exposes no public per-Activation cancellation operation and `session.cancel` would bypass its ownership.
 
-Logged non-user messages render as a default-collapsed disclosure whose header names the role the runtime projected for the message — `上下文注入` for an injection, `跨会话召回` for a recalled session — followed by the producer name that projection read out of the durable source, so a reader distinguishes a skill catalog from a workspace instruction file or a recalled session without expanding. A source that names no producer shows the role alone. The header shares the Tool calls geometry and interaction with `ToolRow` through the package-internal `DisclosureRow`, while retaining context semantics: the expanded body follows its content height up to a 141px scrolling cap and synthesizes no tool state, summary, or keyed toolview dispatch ([disclosure decision](../../../.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.md), [provenance decision](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)). That body follows the form the producer declared on its durable source: `instructions` names the reconciled files above their text, `catalog` lists the entries the source recorded instead of the model-facing prose, and every other value — absent, unknown to this version, or carrying no usable fields — renders the opaque body, which shows the model-facing text with its real line breaks and the remaining provenance as fields. The opaque body is the documented default, not a leftover: a resumed, forked, or foreign log must render whether or not its producer is mounted here. A durable or pending steering bubble carries an `插话` / `Interjection` caption above it, the only thing distinguishing a mid-turn interjection from the turn-opening prompt that shares its bubble.
+Logged non-user messages render as a default-collapsed disclosure whose header names the role the runtime projected for the message — `上下文注入` for an injection, `跨会话召回` for a recalled session — followed by the producer name that projection read out of the durable source, so a reader distinguishes a skill catalog from a workspace instruction file or a recalled session without expanding. A source that names no producer shows the role alone. The header shares the Tool calls geometry and interaction with `ToolRow` through the package-internal `DisclosureRow`, while retaining context semantics: the expanded body follows its content height up to a 141px scrolling cap and synthesizes no tool state, summary, or keyed toolview dispatch ([historical disclosure decision](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md), [provenance decision](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)). That body follows the form the producer declared on its durable source: `instructions` names the reconciled files above their text, `catalog` lists the entries the source recorded instead of the model-facing prose, and every other value — absent, unknown to this version, or carrying no usable fields — renders the opaque body, which shows the model-facing text with its real line breaks and the remaining provenance as fields. The opaque body is the documented default, not a leftover: a resumed, forked, or foreign log must render whether or not its producer is mounted here. A durable or pending steering bubble carries an `插话` / `Interjection` caption above it, the only thing distinguishing a mid-turn interjection from the turn-opening prompt that shares its bubble.
 
 A Think row stays collapsed by default and exposes live reasoning throughput without expanding the chain of thought: while its reasoning block is the streaming tail, the summary switches from the settled first line to the latest non-blank line and its one-line scrollport follows each delta to the inline end. Expanding the row removes the moving summary and leaves the full reasoning in ordinary page flow, so page reading never fights an internal follower; settlement restores the stable first-line summary at the left edge ([decision](../../../.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md)).
 
-Generic tool rows classify the built-in bash, read, search, write, edit, and run_code names into dedicated visual variants. The filesystem variants render the edit icon and a path summary; that path is a hover-underline link that opens the file with the host OS default application (`host.openPath`, relative paths resolve against the session cwd). Tool rows are not whole-row click targets and do not open the details panel. The code variant summarizes with the model-authored `description` and expands to the program itself; its logged sub-dispatches render as always-visible nested rows through the SAME keyed toolview hole (custom registrations and the GenericToolCard fallback apply to sub-rows unchanged). Cordis lifecycle tools reuse those generic variants while presenting `Inspect`, `Mount temporary Plugin`, and `Unmount temporary Plugin` with a shared Cordis accent; mount keeps the code variant's expandable source rendering.
+Generic tool rows classify the built-in bash, read, search, write, edit, and run_code names into dedicated visual variants. The filesystem variants render the edit icon and a path summary; that path is an underlined link — it reads as one at rest, not only on hover, because a path styled like the surrounding prose is an affordance nobody finds — and it opens the file through the Host (`host.openPath`, relative paths resolve against the session cwd). A document a browser renders prefers the default browser where the Host platform can name one; Windows and WSL use the Windows registered association. The Host opens it on the Host's own machine: a client reached over a network sees nothing, which is the deliberate scope of this surface. Tool rows are not whole-row click targets and do not open the details panel. The code variant summarizes with the model-authored `description` and expands to the program itself; its logged sub-dispatches render as always-visible nested rows through the SAME keyed toolview hole (custom registrations and the GenericToolCard fallback apply to sub-rows unchanged). Cordis lifecycle tools reuse those generic variants while presenting `Inspect`, `Mount temporary Plugin`, and `Unmount temporary Plugin` with a shared Cordis accent; mount keeps the code variant's expandable source rendering.
 
 A tool call declaring the `terminal` render intent renders its command output inline, at both conversation render sites, through ui-primitives' `TerminalBlock`. `contract/terminal-card-model.ts` is the single derivation from the snapshot's `callView`/`resultView` pair, so the sites cannot disagree about a command, its cwd, or its exit status; it yields null — the generic path — for any other card tag, including one this client version does not know. Both sites therefore also show the card's run-state dot, which is the same `StateDot` semantic a tool row's leading icon carries, so a row and its own card always agree about one command's state. A multi-line command gets one prompt row per line, with the dot marking the call once on the first row — the exit status is the whole call's, so a dot per line would claim a per-line outcome bash does not report. The keyed `BashRow` carries the card below its summary row; tool rows are summary surfaces, so the card's copy and expand controls are the row's only interactions. The render-site fallback row keeps the card behind its existing expand control. Rows cap at `CHAT_TERMINAL_MAX_LINES` (8) against the panel's 16, which keeps the summary bounded; the panel stays the single-call reading surface. Inline output is licensed per render intent — the terminal and web cards, each with its own bound. A Bash execution failure that settles on the generic path instead exposes its original arguments and full error through the same bounded IN/OUT disclosure, while successful generic results such as a background-start acknowledgement remain summary-only ([decision](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)).
 
@@ -50,6 +52,8 @@ The chat stats line takes its token accounting from the generic token-meter `tok
 
 `src/client/` is organized by domain. `contract/` is the sole inter-domain shared face (`slots.ts` slot declarations and composed props, `views.ts` shared primitives, `tool-call-model.ts`); the `skeleton/`, `chat/`, and `toolviews/` directories import contract files and never each other. `apply.ts` is the only assembly point allowed to import all three domains. The `/client` export surface is the contract only — `apply`/`inject`, the two service classes, and the `contract/` type families; implementation components and the store factory stay internal and reach the page through apply's slot registrations.
 
+A finished turn ends with a turn-tail hole: the chat view renders the `conversation.chat.turnTail` list slot between the closing assistant's body and its IconActions, once per turn at the seq `assistantActionsSeqs` elects, dispatching `TurnTailOwnerProps` (the snapshot nodes, the closing seq, and the tool rows' `openFile`). This package owns only the hole; the produced-files row that fills it — derivation from the mutation tools' `locations`, the chip cap, the copy — lives in `@deepseek-ai/dsh-client-ui-deliverables`, so composing that plugin out of cordis.yml turns the surface off while the hole renders empty at zero cost.
+
 ## Model Experience
 
 None, as the conversation UI renders session history and streams in the browser; nothing here reaches a model request.

packages/client/ui-conversation/README.zh.md

@@ -8,15 +8,17 @@
 
 常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会渲染禁用输入栏；其根作用域的 `conversation.hero.workspace` slot 承载 Workspace 选择器。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。根组件始终拥有同一个滚动容器与 Hero／编辑器子树；首个会话到达时，彼此独立的严格会话页头和主体 outlet 只填入各自区域，因此 Workspace 选择器、滚动主体、编辑器 seat 与 textarea 都保留原有 React 和 DOM identity。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。活跃阶段，会话标题栏作为普通列 chrome，仅显示当前会话标题和视图标签；fork 谱系仍保留为会话数据，不投影到标题栏。其下滚动容器（`data-conversation-scroll`）承载流动排版的各视图与 sticky 编辑器栈（统计 dock＋输入区 dock＋输入栏）。该滚动容器无条件预留自己的滚动条槽，选用编辑器 overlay 的视图也仍把它保留为滚动容器，因此无论对话记录是否滚动、无论展示哪个视图标签，输入卡片都保持同一个横向位置（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)）。textarea 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。
 
+别的插件可以经 `ctx.conversation.blocks` 让某个会话的编辑器变为惰性：它设置一个携带自己本地化理由的 block，输入栏就渲染同一个禁用的 textarea，并把该理由作为 placeholder——复用无 Workspace 时的那套姿态。推送方向是约束而非偏好：知道某会话发不出消息的插件（ui-model，在没有适配器服务其路由时）本就依赖本包，因此本包读不到它们。模型 seat 是 block 唯一保留可用的控件——这份契约里的每个 block 都靠选模型来解除，把它一起锁上会让编辑器索要它自己拦下的那件事。block 只是提示性设计；无论客户端禁用了什么，宿主都会拒绝一个它路由不了的 prompt。两者同时成立时以无 Workspace 姿态为准，因为选 Workspace 是更靠前的前提。
+
 视图环是一个 slot：严格会话主体注册在 `children` 表中声明 Session scope 的 `'conversation.view'` 列表，并通过自身的 renderSlot share 渲染活跃配置项（`only: <active id>`）；视图标签页则从注册选项（`id`／`order`／`label`）投影而来。聊天视图是该包自身的配置项；ui-trajectory 等插件通过 `ctx.slots.register` 贡献标签页，每个视图负责自己的 chrome。
 
 会话页头会在标题旁声明并渲染 Session scope 的 `'conversation.session.header.actions'` 列表，使功能插件无需进入骨架即可贡献控件。编辑器链的 currency 包含当前对话 `session`；ui-subagent 会选取 one-shot 或 parent 不可用的已寻址会话，并按原因显示只读文案，而普通 InputBar 会让所有已寻址 child 仅保留 Send，因为继续执行服务不公开逐 Activation 取消操作，`session.cancel` 也会绕过其所有权。
 
-已记录的非用户消息渲染为默认折叠的展开项，标题栏先给出运行时为该消息投影出的角色——注入为 `上下文注入`，召回为 `跨会话召回`——其后是该投影从持久来源读出的生产者名称，因此读者无需展开即可区分 skill（技能）目录、工作区指令文件与被召回的会话。来源未提供生产者名称时只显示角色。标题栏通过包内部的 `DisclosureRow` 与 `ToolRow` 共享 Tool calls 的几何与交互，同时保留上下文语义：展开内容区的高度会随内容自适应，最大为 141px，超出后滚动，且不会合成工具状态、摘要或键控 toolview 分发（[展开项决策](../../../.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.md)、[来源决策](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)）。该内容区按生产方在持久来源上声明的形态渲染：`instructions` 在正文之上列出它对账过的文件，`catalog` 列出来源记录的条目而非面向模型的散文，其余取值——未声明、本版本不认识、或字段不可用——一律渲染 opaque 内容区，即按真实换行展示面向模型的文本，并把剩余来源信息列成字段。opaque 不是兜底剩余物而是有文档的默认：恢复的、fork 的、外部写入的日志，无论其生产方是否挂载在此处，都必须渲染得出来。持久或待处理的 steering（中途引导）气泡上方带有 `插话` / `Interjection` 标注，这是把中途插话与共用同一气泡的开轮提示区分开的唯一标识。
+已记录的非用户消息渲染为默认折叠的展开项，标题栏先给出运行时为该消息投影出的角色——注入为 `上下文注入`，召回为 `跨会话召回`——其后是该投影从持久来源读出的生产者名称，因此读者无需展开即可区分 skill（技能）目录、工作区指令文件与被召回的会话。来源未提供生产者名称时只显示角色。标题栏通过包内部的 `DisclosureRow` 与 `ToolRow` 共享 Tool calls 的几何与交互，同时保留上下文语义：展开内容区的高度会随内容自适应，最大为 141px，超出后滚动，且不会合成工具状态、摘要或键控 toolview 分发（[历史展开项决策](../../../.agents/notes/archived/feature/2026-07-30-web-context-injection-disclosure.md)、[来源决策](../../../.agents/notes/implemented/feature/2026-08-04-web-context-source-and-steer-marks.md)）。该内容区按生产方在持久来源上声明的形态渲染：`instructions` 在正文之上列出它对账过的文件，`catalog` 列出来源记录的条目而非面向模型的散文，其余取值——未声明、本版本不认识、或字段不可用——一律渲染 opaque 内容区，即按真实换行展示面向模型的文本，并把剩余来源信息列成字段。opaque 不是兜底剩余物而是有文档的默认：恢复的、fork 的、外部写入的日志，无论其生产方是否挂载在此处，都必须渲染得出来。持久或待处理的 steering（中途引导）气泡上方带有 `插话` / `Interjection` 标注，这是把中途插话与共用同一气泡的开轮提示区分开的唯一标识。
 
 Think 行默认保持折叠，并在不展开思维链的情况下暴露实时推理（reasoning）吞吐：当推理块是流式输出尾部时，摘要从结算后的首行切换到最新的非空行，其单行滚动区会随每个 delta 追到行内末端。展开该行会移除移动摘要，让完整推理进入普通页面流，因此页面阅读不会与内部跟随器争夺滚动；结算后恢复左对齐的稳定首行摘要（[决策](../../../.agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.md)）。
 
-通用工具行把内置的 bash、read、search、write、edit 和 run_code 名称归入专用视觉变体。文件系统变体会渲染 edit 图标和路径摘要；该路径是悬停下划线链接，点击后通过宿主操作系统的默认应用打开文件（`host.openPath`，相对路径相对会话 cwd 解析）。工具行不再是整行点击目标，也不会打开 details 面板。code 变体以模型撰写的 `description` 作摘要，展开后显示程序本身；其已记录的子调用经由同一个键控 toolview 空位渲染为始终可见的嵌套行（自定义注册和 GenericToolCard fallback 原样适用于子行）。Cordis 生命周期工具复用这些通用变体，同时以统一的 Cordis 强调色呈现 `Inspect`、`Mount temporary Plugin` 和 `Unmount temporary Plugin`；mount 行保留 code 变体的可展开源码渲染。
+通用工具行把内置的 bash、read、search、write、edit 和 run_code 名称归入专用视觉变体。文件系统变体会渲染 edit 图标和路径摘要；该路径是带下划线的链接——静止状态下就读得出是链接，而不只在悬停时，因为一条与周围正文同样样式的路径是没人会发现的交互——点击即经由 Host 打开文件（`host.openPath`，相对路径相对会话 cwd 解析）。浏览器能渲染的文档会在 Host 平台能够确定默认浏览器时优先使用它；Windows 与 WSL 则使用 Windows 注册的文件关联。Host 在它自己的机器上打开：经网络访问的客户端看不到任何东西，这是本交互面刻意划定的范围。工具行不再是整行点击目标，也不会打开 details 面板。code 变体以模型撰写的 `description` 作摘要，展开后显示程序本身；其已记录的子调用经由同一个键控 toolview 空位渲染为始终可见的嵌套行（自定义注册和 GenericToolCard fallback 原样适用于子行）。Cordis 生命周期工具复用这些通用变体，同时以统一的 Cordis 强调色呈现 `Inspect`、`Mount temporary Plugin` 和 `Unmount temporary Plugin`；mount 行保留 code 变体的可展开源码渲染。
 
 声明 `terminal` 渲染意图的工具调用，会在两个对话渲染点上都通过 ui-primitives 的 `TerminalBlock` 内联渲染其命令输出。`contract/terminal-card-model.ts` 是从快照的 `callView`／`resultView` 对推导的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧；对任何其他 card 标签——包括当前客户端版本不认识的标签——它返回 null，落回通用路径。因此两个渲染点也都显示卡片的运行状态点，它与工具行行首图标承载同一套 `StateDot` 语义，所以一行与其自身的卡片对同一条命令的状态总是一致。多行命令的每一行各占一个提示行，状态点只在第一行为整次调用标记一次——退出状态属于整次调用，因此每行一枚就会声称一个 bash 并不报告的逐行结果。键控的 `BashRow` 把卡片放在摘要行下方；工具行是摘要 surface，因此卡片的复制与展开控件是该行唯一的交互。渲染点兜底行则保持其既有的展开控件。行的上限是 `CHAT_TERMINAL_MAX_LINES`（8），面板为 16，因此摘要保持有界；面板仍是单次调用的阅读 surface。内联输出按渲染意图开放——终端卡片与 web 卡片各有自己的上限。若 Bash 执行失败时落在通用路径，则改用同样有界的 IN/OUT 展开区暴露原始参数和完整错误；后台启动确认等成功的通用结果仍只显示摘要（[决策](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)）。
 
@@ -50,6 +52,8 @@ Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。Qu
 
 `src/client/` 按领域组织。`contract/` 是唯一的跨领域共享表层（`slots.ts` slot 声明与组合后的 props、`views.ts` 共享原语、`tool-call-model.ts`）；`skeleton/`、`chat/` 和 `toolviews/` 目录只导入 contract 文件，彼此之间从不互相导入。`apply.ts` 是唯一允许导入全部三个领域的组装点。`/client` 导出表层只包含契约：`apply`／`inject`、两个服务类和 `contract/` 类型家族；实现组件与 store factory 保持内部，经 apply 的 slot 注册抵达页面。
 
+完成的一轮以一个 turn-tail 空位收尾：chat 视图在收尾 assistant 正文与其 IconActions 之间渲染 `conversation.chat.turnTail` list slot，每轮一次、位于 `assistantActionsSeqs` 选出的 seq，派发 `TurnTailOwnerProps`（快照节点、收尾 seq，以及工具行的 `openFile`）。本包只拥有空位；填充它的产物行——从改写工具 `locations` 的派生、chip 上限、文案——都在 `@deepseek-ai/dsh-client-ui-deliverables` 里，因此把那个插件从 cordis.yml 中组合掉即可关闭该交互面，空位以零成本渲染为空。
+
 ## 模型体验
 
 无。会话 UI 在浏览器中渲染会话历史与流；这里没有任何内容进入模型请求。

packages/client/ui-conversation/src/client/apply.ts

@@ -15,6 +15,8 @@ import { resolveToolPath } from './contract/tool-call-model.ts'
 import { createChatStore } from './stores.ts'
 import { ConversationService } from './service.ts'
 import type { IConversation } from './service.ts'
+import { ComposerBlockRegistry } from './input/blocks.ts'
+import type { ComposerBlock } from './input/blocks.ts'
 import { InputHub } from './input/hub.ts'
 import { ComposerSubmissionPolicy } from './input/submission-policy.ts'
 import { InputBar } from './skeleton/InputBar.tsx'
@@ -54,6 +56,11 @@ const ABSENT_NOTICES = {
   getSnapshot: (): InputNotice | null => null,
   subscribe: () => () => {},
 }
+/** No session, therefore nothing to block; same one-identity rule as above. */
+const ABSENT_BLOCK = {
+  getSnapshot: (): ComposerBlock | undefined => undefined,
+  subscribe: () => () => {},
+}
 const EMPTY_LEXICON: ReadonlyMap<'/' | '@', readonly string[]> = new Map()
 const ABSENT_LEXICON = {
   getSnapshot: () => EMPTY_LEXICON,
@@ -133,6 +140,12 @@ export function apply(ctx: Context): void {
   // ctx.conversation.input by the service below sharing this one instance).
   const inputHub = new InputHub(ctx)
 
+  // The composer-block registry: a plugin that knows a session cannot send —
+  // ui-model, when no adapter serves the session's route — raises a block
+  // here, and the bar reads its own session's store. It cannot flow the other
+  // way: this package must not import the plugins that would know.
+  const composerBlocks = new ComposerBlockRegistry()
+
   // Decision 19/20: the input machine feeds every session-scope slot
   // component through the standard provide channel — the 'input' hook plus
   // the two public actions. Materialization is the shell creation trigger
@@ -167,6 +180,7 @@ export function apply(ctx: Context): void {
       'conversation.hero.workspace': { kind: 'single', scope: 'root' },
     },
     inject: (sessionId: SessionId | undefined): ConversationInjected => ({
+      hooks: { composerBlock: sessionId === undefined ? ABSENT_BLOCK : composerBlocks.storeFor(sessionId) },
       selectWorkspace: async (workspaceId) => {
         const nextId = await workspaces.connectWorkspace(workspaceId)
         if (sessionId !== undefined && nextId !== sessionId) {
@@ -304,6 +318,7 @@ export function apply(ctx: Context): void {
     children: {
       'conversation.chat.toolview': { kind: 'keyed', scope: 'session' },
       'conversation.chat.commandview': { kind: 'keyed', scope: 'session' },
+      'conversation.chat.turnTail': { kind: 'chain', scope: 'session' },
     },
     store: chatStore,
     inject: (sessionId: SessionId, actions: BoundActions<typeof chatStore>): ChatViewInjected => {
@@ -352,7 +367,7 @@ export function apply(ctx: Context): void {
   // registers itself as `conversation` and lives on its own child fiber.
   // Presentation registrants depend directly on their slot declarations;
   // this service remains only where conversation actions are required.
-  ctx.plugin(ConversationService, { input: inputHub })
+  ctx.plugin(ConversationService, { input: inputHub, blocks: composerBlocks })
 
   // The bash sample rides the same declaration seam, in third-party posture
   // (ToolRow-matching Bash · {description} chrome).

packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx

@@ -11,10 +11,11 @@
 
 import { memo, useMemo } from 'react'
 import type { AssistantBlock } from '@deepseek-ai/dsh-client-runtime/client'
+import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
 import {
   IconThinkOutline14, JsonBlock, MarkdownText,
 } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { ChatViewSlotProps } from '../contract/slots.ts'
+import type { ChatViewSlotProps, TurnTailOwnerProps } from '../contract/slots.ts'
 import { hasContentText } from './chat-flow.ts'
 import { MessageIconActions } from './MessageIconActions.tsx'
 import { ToolRow } from './ToolRow.tsx'
@@ -40,6 +41,8 @@ export interface AssistantMarkdownProps {
   seq?: number | undefined
   /** Fork the session through this finalized message's completed turn when eligible. */
   onFork?: ((seq: number) => void) | undefined
+  /** Turn-tail slot dispatch share and owner currency; omitted for a mid-turn assistant. */
+  turnTail?: (Pick<PropsRenderSlots<'conversation.chat.turnTail'>, 'renderSlotChain'> & { owner: TurnTailOwnerProps }) | undefined
   /** The message is not the transcript tail of a completed turn. */
   forkUnavailable?: boolean | undefined
   /** The owning view's locale seat, passed down as a plain prop. */
@@ -83,7 +86,7 @@ function ThinkRow({ text, running, t }: { text: string; running: boolean; t: Ass
 }
 
 export const AssistantMarkdown = memo(function AssistantMarkdown({
-  blocks, streaming, interrupted, time, runMs, ttftMs, tokensPerSecond, seq, onFork, forkUnavailable, t,
+  blocks, streaming, interrupted, time, runMs, ttftMs, tokensPerSecond, seq, onFork, forkUnavailable, turnTail, t,
 }: AssistantMarkdownProps) {
   // Stable per locale revision (t identity changes on switch): a fresh object
   // per render would rebuild MarkdownText's component table every chunk.
@@ -121,6 +124,7 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({
         })}
         {interrupted && <span className={css.stopped}>{t('message.stopped')}</span>}
       </div>
+      {showActions && turnTail?.renderSlotChain('conversation.chat.turnTail', turnTail.owner)}
       {showActions && (
         <MessageIconActions
           text={copyText(blocks)}

packages/client/ui-conversation/src/client/chat/ChatView.tsx

@@ -335,7 +335,7 @@ function StreamingTail({ useSession, t }: {
  * render through the declared keyed hole's renderSlot share).
  */
 export function ChatView({
-  useSession, useSessions, useStore, renderSlot, sessionId, openFile, loadOlder, inspectCall, chatScroll, forkAt, t,
+  useSession, useSessions, useStore, renderSlot, renderSlotChain, sessionId, openFile, loadOlder, inspectCall, chatScroll, forkAt, t,
 }: ChatViewSlotProps) {
   const nodes = useSession(s => s.nodes)
   const turnTimings = useSession(s => s.turnTimings)
@@ -600,6 +600,9 @@ export function ChatView({
           seq={node.seq}
           onFork={forkAt}
           forkUnavailable={!branchSeqs.has(node.seq)}
+          turnTail={actionSeqs.has(node.seq)
+            ? { renderSlotChain, owner: { nodes, seq: node.seq, openFile } }
+            : undefined}
           t={t}
         />
       )

packages/client/ui-conversation/src/client/chat/ToolRow.module.css

@@ -103,7 +103,7 @@
   color: var(--dsw-alias-label-tertiary);
 }
 
-/* File-tool path: same geometry as .summary; hover underline + pointer. */
+/* File-tool path: same geometry as .summary, with a persistent link affordance. */
 .fileLink {
   flex: 1 1 auto;
   min-width: 0;
@@ -118,12 +118,16 @@
   text-align: left;
   font-size: 14px;
   line-height: 24px;
-  color: var(--dsw-alias-label-tertiary);
+  color: var(--dsw-alias-label-secondary);
+  text-decoration: underline;
+  text-decoration-color: var(--dsw-alias-label-quaternary);
+  text-underline-offset: 3px;
   cursor: pointer;
 }
 
 .fileLink:hover {
-  text-decoration: underline;
+  color: var(--dsw-alias-label-primary);
+  text-decoration-color: currentColor;
 }
 
 /* Error row's collapsed summary: the failure's first line in the error color. */

packages/client/ui-conversation/src/client/contract/slots.ts

@@ -3,8 +3,9 @@ import type { ReactNode, RefObject } from 'react'
 import type {
   InjectFace, MaybeSnapshotSelectorHook, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore, SnapshotSelectorHook,
 } from '@deepseek-ai/dsh-client-ui-slots'
-import type { CommandNode, ConversationSnapshot, ObservableSnapshot, PendingInteraction, PendingWait, SessionId, ToolCallBlock, WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { CommandNode, ConversationNode, ConversationSnapshot, ObservableSnapshot, PendingInteraction, PendingWait, SessionId, ToolCallBlock, WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client'
 import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
+import type { ComposerBlock } from '../input/blocks.ts'
 import type { ComposerKeyboard, EditSelection, InputActions, InputNotice, InputState } from '../input/contract.ts'
 import type { createChatStore } from '../stores.ts'
 import type { ComposerSubmitGesture, InputSubmitMode } from './composer-submission.ts'
@@ -46,6 +47,14 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
      * registration, and a domain upgrades by registering one row component.
      */
     'conversation.chat.commandview': { kind: 'keyed'; scope: 'session'; owner: CommandRowOwnerProps }
+    /**
+     * The chat view's turn-tail chain: rendered between a closing assistant
+     * message's body and its IconActions footer, once per turn (the render
+     * site elects the closing seq). Entries derive a match from the owner
+     * currency before mounting, so presentation components never mount only
+     * to return null; an all-declined chain renders nothing.
+     */
+    'conversation.chat.turnTail': { kind: 'chain'; scope: 'session'; owner: TurnTailOwnerProps }
     /**
      * The composer takeover chain: entries are selector-routed replacements
      * of the default InputBar. Declared by this package's 'conversation'
@@ -156,6 +165,24 @@ export interface ConvViewOwnerProps {
   onInspectDone?: () => void
 }
 
+/**
+ * Owner currency of the chat view's turn-tail hole: the finalized snapshot
+ * and the closing assistant's anchor. Registrants derive their own facts
+ * from the nodes (the owner never pre-chews a feature's vocabulary), and
+ * open files through the same opener the tool rows use.
+ */
+export interface TurnTailOwnerProps {
+  /** Finalized snapshot nodes in surface order. */
+  nodes: readonly ConversationNode[]
+  /** The closing assistant's seq — the anchor the tail renders under. */
+  seq: number
+  /**
+   * Open a filesystem path through the Host (tool-row semantics; the chat
+   * view resolves relative paths against the session cwd).
+   */
+  openFile: (path: string) => void
+}
+
 /**
  * Owner share of a per-view toolview slot: the call material the rendering
  * view supplies per row. Uniform across views — the trajectory/waterfall
@@ -229,6 +256,12 @@ export interface ConversationInjected {
    * When a blank session is already current, carry its draft to the target.
    */
   selectWorkspace: (workspaceId: WorkspaceId) => Promise<void>
+  /**
+   * Framework-bound sources. `composerBlock` is this session's block when a
+   * plugin raised one; the reason is the blocker's own localized copy, which
+   * the root renders as the inert composer's placeholder.
+   */
+  hooks: { composerBlock: ObservableSnapshot<ComposerBlock | undefined> }
 }
 
 /** Business callbacks injected into the strict Session body seat. */
@@ -264,6 +297,14 @@ export interface ConversationSessionHeaderInjected {
 export interface ComposerBarOwnerProps {
   /** Hero = empty-state centered card; composer = resident bottom bar. */
   variant: 'hero' | 'composer'
+  /**
+   * A block another plugin raised for this session: the bar refuses input and
+   * shows the blocker's reason as the placeholder, but — unlike `disabled` —
+   * keeps the model seat live. Every block this contract has is one the user
+   * clears by choosing a model, so locking that seat too would leave the
+   * composer telling them to do the one thing it prevents.
+   */
+  blocked?: { readonly reason: string }
   /**
    * Inert no-workspace state: the bar renders its normal DOM fully disabled
    * (textarea, add, send) so the workspace pick transitions in place instead
@@ -362,7 +403,7 @@ export type ConversationSlotProps =
     | 'conversation.input.left' | 'conversation.input.right'
     | 'conversation.hero.workspace'
   >
-  & ConversationInjected
+  & InjectFace<ConversationInjected>
   & PropsLocale<'conversation'>
 
 /** Full strict-session body props: per-session store, view ring, and draft mirror. */
@@ -486,7 +527,7 @@ export interface ChatViewInjected {
 
 /** Full chat-view component props: runtime & the declared toolview/commandview holes' render share & store & injected & locale seat. */
 export type ChatViewSlotProps =
-  PropsRuntime<'conversation.view'> & PropsRenderSlots<'conversation.chat.toolview' | 'conversation.chat.commandview'>
+  PropsRuntime<'conversation.view'> & PropsRenderSlots<'conversation.chat.toolview' | 'conversation.chat.commandview' | 'conversation.chat.turnTail'>
   & PropsStore<ChatStore> & ChatViewInjected & PropsLocale<'conversation'>
 
 /**

packages/client/ui-conversation/src/client/index.ts

@@ -17,7 +17,7 @@ export type {
   ComposerChainProps, ConversationInjected,
   ConversationSessionHeaderInjected, ConversationSessionInjected, ConversationSlotProps,
   ConvViewOwnerProps, ConvViewProps, DetailsInjected, DetailsSlotProps,
-  EmptyWorkspaceOwnerProps, ToolRowOwnerProps, ToolRowProps,
+  EmptyWorkspaceOwnerProps, ToolRowOwnerProps, ToolRowProps, TurnTailOwnerProps,
 } from './contract/slots.ts'
 // Export discipline: packages/client/AGENTS.md.
 

packages/client/ui-conversation/src/client/input/blocks.ts

@@ -0,0 +1,77 @@
+/**
+ * Composer blocks: the one way another plugin stops a session's input.
+ *
+ * The composer cannot read the plugins that would know — the dependency runs
+ * ui-model → ui-conversation, never back — so a blocker pushes here and the
+ * bar reads its own session's store. A block carries the localized reason it
+ * exists, because the plugin that raised it owns that copy; the composer only
+ * knows how to render an inert textarea with a placeholder, exactly as it
+ * already does for a session with no workspace.
+ *
+ * This is an affordance, not enforcement: the Host refuses a prompt it cannot
+ * route regardless of what any client disables.
+ */
+
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SessionId, SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+
+/** Why one session's composer is inert. */
+export interface ComposerBlock {
+  /**
+   * Localized placeholder replacing the composer's own, owned by the plugin
+   * that raised the block.
+   */
+  readonly reason: string
+}
+
+/** The registry face other plugins reach through `ctx.conversation.blocks`. */
+export interface ComposerBlocks {
+  /**
+   * Raise or clear this session's block. Idempotent: setting a block equal to
+   * the current one, or clearing an absent one, notifies nobody.
+   * @param sessionId - the session whose composer is affected.
+   * @param block - the block to raise, or undefined to clear it.
+   */
+  set(sessionId: SessionId, block: ComposerBlock | undefined): void
+  /**
+   * The store the composer subscribes to for one session. Created on first
+   * read from either side, so a blocker may raise a block before the session's
+   * composer mounts and the composer still sees it.
+   * @param sessionId - the session to observe.
+   * @returns that session's block store (undefined value = not blocked).
+   */
+  storeFor(sessionId: SessionId): SnapshotStore<ComposerBlock | undefined>
+  /**
+   * Drop one session's store. The session scope's disposer calls this; a
+   * blocker never needs to.
+   * @param sessionId - the session being torn down.
+   */
+  forget(sessionId: SessionId): void
+}
+
+/** The per-session composer-block registry (one instance per plugin fiber). */
+export class ComposerBlockRegistry implements ComposerBlocks {
+  private readonly stores = new Map<SessionId, SnapshotStore<ComposerBlock | undefined>>()
+
+  /** @inheritdoc */
+  set(sessionId: SessionId, block: ComposerBlock | undefined): void {
+    const store = this.storeFor(sessionId)
+    const current = store.getSnapshot()
+    if (current?.reason === block?.reason) return
+    store.set(block)
+  }
+
+  /** @inheritdoc */
+  storeFor(sessionId: SessionId): SnapshotStore<ComposerBlock | undefined> {
+    const existing = this.stores.get(sessionId)
+    if (existing !== undefined) return existing
+    const created = createSnapshotStore<ComposerBlock | undefined>(undefined)
+    this.stores.set(sessionId, created)
+    return created
+  }
+
+  /** @inheritdoc */
+  forget(sessionId: SessionId): void {
+    this.stores.delete(sessionId)
+  }
+}

packages/client/ui-conversation/src/client/locales.ts

@@ -44,7 +44,7 @@ export const zh = {
   'access.confirm.acknowledge': '我已了解风险，并愿意继续',
   'access.confirm.cancel': '取消',
   'access.confirm.enable': '启用 Full access',
-  'hero.headline': '开始构建吧',
+  'hero.headline': '探索未知之境',
   'hero.preview': '预览版',
   'hero.chooseWorkspace': '选择工作区',
   'session.hierarchy': '会话层级',
@@ -184,7 +184,7 @@ export const en = {
   'access.confirm.acknowledge': 'I understand the risks and want to continue',
   'access.confirm.cancel': 'Cancel',
   'access.confirm.enable': 'Enable Full access',
-  'hero.headline': 'Let\'s start building',
+  'hero.headline': 'Into the Unknown',
   'hero.preview': 'Preview',
   'hero.chooseWorkspace': 'Choose workspace',
   'session.hierarchy': 'Session hierarchy',

packages/client/ui-conversation/src/client/service.ts

@@ -14,6 +14,7 @@ import type { Context } from 'cordis'
 // method) instead of the standalone helper.
 import type { ISessions, SessionFace, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import type { QueueAction, QueueItemId } from './contract/queue.ts'
+import type { ComposerBlocks } from './input/blocks.ts'
 import type { InputService } from './input/contract.ts'
 
 /**
@@ -24,6 +25,11 @@ import type { InputService } from './input/contract.ts'
 export interface IConversation {
   /** The per-session input machine registry (InputService face). */
   readonly input: InputService
+  /**
+   * The per-session composer-block registry: how a plugin the composer
+   * cannot import makes a session's input inert with its own reason.
+   */
+  readonly blocks: ComposerBlocks
   /**
    * Send a prompt into the caller scope's session (queued turn).
    * @param text - prompt text, sent verbatim as one text block.
@@ -53,16 +59,20 @@ export interface IConversation {
 export class ConversationService extends Service implements IConversation {
   /** The per-session input machine registry (InputService face, design §5.2). */
   readonly input: InputService
+  /** The per-session composer-block registry. */
+  readonly blocks: ComposerBlocks
 
   /**
    * @param ctx - owning root context (the plugin apply context; the service
    * registers itself and follows that fiber's lifetime).
-   * @param config - carries the InputService instance constructed by the
-   * plugin apply (the same InputHub the slot inject factories close over).
+   * @param config - carries the InputService and composer-block registry
+   * constructed by the plugin apply (the same instances the slot inject
+   * factories close over).
    */
-  constructor(ctx: Context, config: { input: InputService }) {
+  constructor(ctx: Context, config: { input: InputService; blocks: ComposerBlocks }) {
     super(ctx, 'conversation')
     this.input = config.input
+    this.blocks = config.blocks
   }
 
   /**

packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx

@@ -13,7 +13,7 @@ import css from './ConversationRoot.module.css'
 export type ConversationRootProps = ConversationSlotProps
 
 export function ConversationRoot({
-  sessionId, useSession, useSessions, useWorkspaces, useInput,
+  sessionId, useSession, useSessions, useWorkspaces, useInput, useComposerBlock,
   renderSlot, renderSlotChain, selectWorkspace, t,
 }: ConversationRootProps) {
   const openState = useSession(s => s.openState)
@@ -24,6 +24,9 @@ export function ConversationRoot({
   const cwd = useSessions(s => sessionId === undefined ? undefined : s.byId[sessionId]?.cwd)
   const summaryBlank = useSessions(s => sessionId === undefined ? undefined : s.byId[sessionId]?.blank)
   const workspaces = useWorkspaces(s => s)
+  // A plugin this package cannot import (ui-model) says this session cannot
+  // send; its reason is already localized by whoever raised it.
+  const composerBlock = useComposerBlock(block => block)
 
   const [pickerOpen, setPickerOpen] = useState(false)
   const [pendingWorkspaceId, setPendingWorkspaceId] = useState<WorkspaceId | undefined>()
@@ -126,11 +129,20 @@ export function ConversationRoot({
   // bar is ONE session-maybe slot rendered unconditionally — inert is a prop,
   // not a different tree, so the textarea DOM survives the transition.
   const inert = sessionId === undefined || (hero && chipTitle === undefined)
+  // A raised block is the same inert posture with the blocker's own reason:
+  // one disabled textarea, never a second tree. The no-workspace state wins
+  // when both hold — picking a workspace is the earlier prerequisite.
+  const blocked = !inert && composerBlock !== undefined
   const inputBar = renderSlot('conversation.composer.bar', {
     variant: hero ? 'hero' : 'composer',
     ...(inert
       ? { disabled: true, placeholder: t('placeholder.workspace') }
-      : hero ? { placeholder: t('placeholder.hero') } : {}),
+      : blocked
+        // `blocked`, not `disabled`: the bar refuses input either way, but a
+        // block keeps the model seat live because choosing a model is how the
+        // user clears it.
+        ? { blocked: composerBlock, placeholder: composerBlock.reason }
+        : hero ? { placeholder: t('placeholder.hero') } : {}),
     overlay: renderSlot('conversation.input.overlay', {}),
     leftItems: zone === undefined ? null : renderSlot('conversation.input.left', zone),
     rightItems: zone === undefined ? null : renderSlot('conversation.input.right', zone),

packages/client/ui-conversation/src/client/skeleton/HeroShell.module.css

@@ -24,12 +24,12 @@
 }
 
 /* figma 34:10411: fish + title, gap 10, centered; 26/32 wt500. The preview
-   badge is a product addition outside that source and aligns to the title. */
+   badge is a product addition outside that source: a mono superscript pill
+   riding the title's top-right. */
 .headline {
   display: grid;
-  grid-template-columns: 34px auto;
+  grid-template-columns: 34px auto auto;
   column-gap: 10px;
-  row-gap: 4px;
   align-items: center;
   justify-content: center;
   font-size: 26px;
@@ -44,13 +44,17 @@
 }
 
 .previewBadge {
-  grid-row: 2;
-  grid-column: 2;
-  justify-self: start;
-  padding: 0 4px;
-  border-radius: 4px;
+  grid-row: 1;
+  grid-column: 3;
+  align-self: start;
+  margin-top: 2px;
+  margin-left: -3px;
+  padding: 1px 7px 0;
+  border: 1px solid var(--dsw-alias-interactive-bg-hover);
+  border-radius: 24px;
   background: var(--dsw-alias-state-business-tertiary);
-  color: var(--dsw-alias-label-primary);
+  color: var(--dsw-alias-label-primary-bluish);
+  font-family: var(--ds-font-family-code);
   font-size: 12px;
   line-height: 18px;
   font-weight: 500;

packages/client/ui-conversation/src/client/skeleton/InputBar.tsx

@@ -37,7 +37,8 @@ export type InputBarProps = ComposerBarProps
 export function InputBar({
   useSession, useInput, inputActions, keyboard, resolveSubmitMode, toggleCommandMenu, stop, command, t,
   renderSlot, useNotices, useLexicon, useMenuLauncher,
-  useProjection, sessionId, variant, disabled: inert = false, placeholder, accessory, overlay, leftItems, rightItems, footer,
+  useProjection, sessionId, variant, disabled: inert = false, blocked, placeholder,
+  accessory, overlay, leftItems, rightItems, footer,
 }: InputBarProps) {
   const input = useInput(s => s)
   const notice = useNotices(s => s)
@@ -86,8 +87,13 @@ export function InputBar({
   // inert no-workspace state, or the machine faces absent (no session). The
   // transient machine locks (adjudicating pending / submitting) render
   // read-only — the draft stays visible and focused, keystrokes drop.
-  const disabled = removed || inert || !live
+  const disabled = removed || inert || !live || blocked !== undefined
   const locked = disabled
+  // The model seat is the ONE control a block leaves live: every block this
+  // contract has is cleared by choosing a model, so locking it too would leave
+  // the composer asking for the only thing it prevents. The other reasons to
+  // be disabled do lock it — there is no session to choose a model for.
+  const modelSeatLocked = removed || inert || !live
   const machineBusy = input?.phase === 'adjudicating' || input?.phase === 'submitting'
 
   // Scroll the draft scrollport the minimum that brings `caret` into view — the
@@ -513,7 +519,7 @@ export function InputBar({
           <div className={css.trailing}>
             {rightItems}
             {renderSlot('conversation.input.agentPreset', { locked })}
-            {renderSlot('conversation.input.model', { locked })}
+            {renderSlot('conversation.input.model', { locked: modelSeatLocked })}
             <ContextMeter useProjection={useProjection} t={t} />
             {/* {machineBusy && <span className={css.pending} data-input-pending aria-label="处理中" />} */}
             <Tooltip label={primaryLabel} side="top" delayMs={500}>

packages/client/ui-conversation/tests/chat-view.spec.tsx

@@ -130,6 +130,8 @@ function makeHarness(init?: Partial<ConversationSnapshot>) {
   const chat = createChatStore().create()
   const renderSlot = ((_key: string, _owner: object, opts?: { fallback?: React.ReactNode }) =>
     opts?.fallback ?? null) as unknown as ChatViewSlotProps['renderSlot']
+  const renderSlotChain = ((_key: string, _owner: object, opts?: { fallback?: React.ReactNode }) =>
+    opts?.fallback ?? null) as unknown as ChatViewSlotProps['renderSlotChain']
   // SessionProvider seat arrives with the session-scope child declaration;
   // ChatView never invokes it (render-prop pass-through stub).
   const SessionProviderStub: ChatViewSlotProps['SessionProvider'] = ({ children }) => <>{children(SID)}</>
@@ -144,6 +146,7 @@ function makeHarness(init?: Partial<ConversationSnapshot>) {
     useStore: bindSnapshotSelector(chat),
     actions: chat.actions,
     renderSlot,
+    renderSlotChain,
     SessionProvider: SessionProviderStub,
     openDetails,
     openFile,
@@ -732,7 +735,8 @@ describe('ChatView', () => {
     // Count renderSlot invocations: the memo boundary holds when CallRow does
     // not re-render, so the row's renderSlot call count freezes during chunks.
     let rowRenders = 0
-    h.props.renderSlot = ((_key: string, _owner: object) => {
+    h.props.renderSlot = ((key: string, _owner: object) => {
+      if (key !== 'conversation.chat.toolview') return null
       rowRenders += 1
       return <div data-testid="counting-row" />
     })

packages/client/ui-conversation/tests/service-orchestration.spec.ts

@@ -7,6 +7,7 @@ import { Context } from 'cordis'
 import { describe, expect, it, vi } from 'vitest'
 import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
 import { ConversationService } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { ComposerBlockRegistry } from '../src/client/input/blocks.ts'
 import { InputHub } from '../src/client/input/hub.ts'
 
 async function bench() {
@@ -23,6 +24,7 @@ async function bench() {
   // factories); the bench passes its own instance explicitly.
   const fiber = runtime.ctx.plugin(ConversationService, {
     input: new InputHub(runtime.ctx),
+    blocks: new ComposerBlockRegistry(),
   })
   await fiber.await()
   const root = runtime.ctx.get('conversation') as ConversationService
@@ -86,6 +88,7 @@ describe('ConversationService', () => {
     const bare = new Context()
     await bare.plugin(ConversationService, {
       input: new InputHub(bare),
+      blocks: new ComposerBlockRegistry(),
     }).await()
     const orphan = bare.get('conversation') as ConversationService
     await expect(orphan.send('x')).rejects.toThrow(/sessions service unavailable/)

packages/client/ui-conversation/tests/skeleton.spec.tsx

@@ -91,6 +91,8 @@ function mount(
     omitSummaryRow?: boolean
     /** Classify the selected child as a subagent instead of an ordinary fork. */
     summaryOrigin?: 'subagent'
+    /** A composer block another plugin raised for this session. */
+    composerBlock?: { reason: string }
   } = {},
 ) {
   const root = sid('root')
@@ -118,9 +120,14 @@ function mount(
   const stop = vi.fn()
   const open = vi.fn()
   const slotCalls: string[] = []
+  /** Owner share handed to the two composer tool-row seats, per render. */
+  const seatOwners: { key: string; owner: unknown }[] = []
   let pickerOwner: unknown
   const renderSlot = ((key: string, owner: object, opts?: { only?: string }) => {
     slotCalls.push(key)
+    if (key === 'conversation.input.model' || key === 'conversation.input.plan') {
+      seatOwners.push({ key, owner })
+    }
     if (key === 'conversation.hero.workspace') { pickerOwner = owner; return null }
     if (key === 'conversation.session.header') {
       return (
@@ -198,7 +205,12 @@ function mount(
           stop={stop}
           command={() => Promise.resolve(true)}
           t={t}
-          renderSlot={(() => null) as InputBarProps['renderSlot']}
+          renderSlot={((key: string, seatOwner: object) => {
+            // The bar's own seats: recorded so a case can assert what share
+            // each tool-row control received.
+            seatOwners.push({ key, owner: seatOwner })
+            return null
+          }) as InputBarProps['renderSlot']}
           {...bar}
         />
       )
@@ -224,6 +236,7 @@ function mount(
     useSessions: bindSnapshotSelector(sessions),
     useWorkspaces: bindSnapshotSelector(workspaces),
     useProjection: (() => undefined),
+    useComposerBlock: select => select(options.composerBlock),
     useInput,
     inputActions,
     renderSlot,
@@ -233,7 +246,7 @@ function mount(
   }
   const view = render(<ConversationRoot {...props} />)
   return {
-    view, chat, sink, retargetWorkspace, session, slotCalls, open,
+    view, chat, sink, retargetWorkspace, session, slotCalls, seatOwners, open,
     pickerOwner: () => pickerOwner,
     rerender: () => { view.rerender(<ConversationRoot {...props} />) },
   }
@@ -242,12 +255,44 @@ function mount(
 describe('Hero chrome', () => {
   it('renders the English preview badge through the hero locale seat', () => {
     const view = render(<HeroShell t={makeTranslate(en, commonEn)} />)
-    expect(view.getByText('Let\'s start building')).toBeTruthy()
+    expect(view.getByText('Into the Unknown')).toBeTruthy()
     expect(view.getByText('Preview')).toBeTruthy()
   })
 })
 
 describe('ConversationRoot resident composer', () => {
+  it('renders the composer inert with the blocker\u2019s own reason', () => {
+    const b = mount(conversationSnapshot(), undefined, undefined, {
+      composerBlock: { reason: 'select a model first' },
+    })
+    const box = b.view.getByRole('textbox') as HTMLTextAreaElement
+    // One disabled textarea with the blocker's placeholder, never a second
+    // tree: the DOM survives the block being raised and cleared.
+    expect(box.disabled).toBe(true)
+    expect(box.placeholder).toBe('select a model first')
+    fireEvent.keyDown(box, { key: 'Enter' })
+    expect(b.sink).not.toHaveBeenCalled()
+
+    // The model seat stays live. Locking it too would leave the composer
+    // asking for the one thing it prevents — every block this contract has is
+    // cleared by choosing a model.
+    const seat = (key: string) => b.seatOwners.filter(call => call.key === key).at(-1)?.owner
+    expect(seat('conversation.input.model')).toEqual({ locked: false })
+    expect(seat('conversation.input.plan')).toEqual({ locked: true })
+  })
+
+  it('lets the no-workspace posture win over a block', () => {
+    // Picking a workspace is the earlier prerequisite; naming a model first
+    // would send the user somewhere they cannot act yet.
+    const b = mount(conversationSnapshot({ composerPhase: 'blank' }), [], undefined, {
+      summaryBlank: true,
+      composerBlock: { reason: 'select a model first' },
+    })
+    const box = b.view.getByRole('textbox') as HTMLTextAreaElement
+    expect(box.disabled).toBe(true)
+    expect(box.placeholder).not.toBe('select a model first')
+  })
+
   it('keeps composer text in the machine, mirrors to the chat store, and submits through the sink', () => {
     const b = mount(conversationSnapshot())
     const box = b.view.getByRole('textbox')
@@ -306,7 +351,7 @@ describe('ConversationRoot resident composer', () => {
     const header = b.view.container.querySelector('header')
     expect(host).not.toBeNull()
     expect(header?.getAttribute('aria-hidden')).toBe('true')
-    expect(b.view.getByText('开始构建吧')).toBeTruthy()
+    expect(b.view.getByText('探索未知之境')).toBeTruthy()
     expect(b.view.getByText('预览版')).toBeTruthy()
     expect(b.view.queryByTestId('view-chat')).toBeNull()
     // The same machine-backed textarea is live in the hero, and the
@@ -330,7 +375,7 @@ describe('ConversationRoot resident composer', () => {
     const b = mount(conversationSnapshot({ composerPhase: 'blank', blank: true, openState: 'loading' }))
     const root = b.view.container.querySelector('[data-phase]')
     expect(root?.getAttribute('data-phase')).toBe('settling')
-    expect(b.view.queryByText('开始构建吧')).toBeNull()
+    expect(b.view.queryByText('探索未知之境')).toBeNull()
   })
 
   it('settling phase: a session the list has no row for settles conservatively', () => {
@@ -355,7 +400,7 @@ describe('ConversationRoot resident composer', () => {
     // blank the column for the history round-trip.
     const root = b.view.container.querySelector('[data-phase]')
     expect(root?.getAttribute('data-phase')).toBe('hero')
-    expect(b.view.getByText('开始构建吧')).toBeTruthy()
+    expect(b.view.getByText('探索未知之境')).toBeTruthy()
     expect(b.view.getByRole('textbox')).toBeTruthy()
   })
 
@@ -373,7 +418,7 @@ describe('ConversationRoot resident composer', () => {
     expect(after.value).toBe('kept across flip')
     expect(b.chat.store.getSnapshot().draft).toBe('kept across flip')
     expect(b.view.container.querySelector('[data-conversation-scroll]')?.contains(after)).toBe(true)
-    expect(b.view.queryByText('开始构建吧')).toBeNull()
+    expect(b.view.queryByText('探索未知之境')).toBeNull()
     expect(b.view.getByTestId('view-chat')).toBeTruthy()
   })
 

packages/client/ui-deliverables/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/client/ui-deliverables/README.md
+README.md: b8b0ea2ef1cbc9b18b905fc08b41278f403ef043
+README.zh.md: a16535b8a8d3625ca1cf90e88c6d9dca742d916b

packages/client/ui-deliverables/README.md

@@ -0,0 +1,21 @@
+# @deepseek-ai/dsh-client-ui-deliverables
+
+English | [中文](README.zh.md)
+
+Produced-files feature owner: registers the deliverables row a finished turn ends with into the chat view's `conversation.chat.turnTail` hole. All policy lives here; removing this plugin's line from cordis.yml removes the surface entirely, and the owning view renders an empty hole at zero cost.
+
+`producedForClosing` derives one turn's produced files from the tail hole's owner currency — the finalized snapshot nodes and the closing assistant's seq. The vocabulary is the mutation tools' own follow-along `locations`, never the closing prose: a produced file is listed whether or not the model remembered to name it. A mutation is recognized by render intent, not tool name — a diff card, or a generic card whose `kind` is `edit` (the shape `str_replace_editor`'s insert presents) — so a new mutation tool joins by declaring what it does. Reads, deletes, and failed calls contribute nothing; a path appears once per turn in first-seen order; accumulation resets on the turn boundary, so a turn that mutates and then ends without content text cannot spill into the next turn's row.
+
+`ProducedFiles` renders the row between the closing message's body and its IconActions footer: a quiet label, up to six chips (basename text, full path as the `title`), and an explicit remainder count past the cap. Each chip opens through the owner-supplied `openFile` — the same Host opener the tool rows use, with the chat view resolving relative paths against the session cwd. Design rationale: the [workspace file links Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md).
+
+## Model Experience
+
+None, as the row is a pure client derivation over already-logged tool metadata and nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends provider requests.
+
+## Known Limitations and Deferred Work
+
+- **Prose mentions stay inert.** An inline-code file name in the closing message does not open the file yet; linking it to the same `locations` vocabulary is the stacked follow-up.

packages/client/ui-deliverables/README.zh.md

@@ -0,0 +1,21 @@
+# @deepseek-ai/dsh-client-ui-deliverables
+
+[English](README.md) | 中文
+
+产物文件的功能属主：把"完成的一轮以其产出文件收尾"的产物行注册进 chat 视图的 `conversation.chat.turnTail` 空位。全部策略都在本包内；从 cordis.yml 中删去本插件那一行即可整体移除该交互面，属主视图以零成本渲染一个空的空位。
+
+`producedForClosing` 从 tail 空位的 owner 通货——定稿的快照节点与收尾 assistant 的 seq——推导一轮产出的文件。词表是改写工具自身的跟随 `locations`，绝不是收尾正文：无论模型是否记得点名，产出文件都会被列出。改写按渲染意图识别而非工具名——diff 卡片，或 `kind` 为 `edit` 的 generic 卡片（即 `str_replace_editor` 的 insert 所呈现的形状）——因此新的改写工具靠声明自己做了什么加入。read、删除与失败的调用不贡献任何条目；同一路径在一轮内按首见顺序只出现一次；累积在 turn 边界重置，因此一轮若先改写文件、随后没有正文内容就结束，不会溢进下一轮的行里。
+
+`ProducedFiles` 在收尾消息正文与其 IconActions 之间渲染该行：一个安静的标签、至多六枚 chip（文本为文件名，完整路径作为 `title`），超出上限则显示一个明确的剩余计数。每枚 chip 经由 owner 提供的 `openFile` 打开——与工具行相同的 Host 打开器，chat 视图会把相对路径按会话 cwd 解析。设计原理：[workspace 文件链接 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md)。
+
+## 模型体验
+
+无。该行是对已记录工具元数据的纯客户端派生，这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **正文提及仍是死文本。**收尾消息里以行内代码写出的文件名尚不能点击打开；把它接到同一份 `locations` 词表是 stacked 的后续工作。

packages/client/ui-deliverables/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-deliverables",
+  "description": "Produced-files turn tail: the deliverables row a finished turn ends with",
+  "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"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-client-locale",
+      "@deepseek-ai/dsh-client-runtime",
+      "@deepseek-ai/dsh-client-ui-conversation"
+    ],
+    "platform": "web"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "react": "^18.2.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-locale": "^0.0.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-locale": "workspace:^",
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@types/react": "~18.3.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ]
+}

packages/client/ui-deliverables/src/client/ProducedFiles.module.css

@@ -0,0 +1,44 @@
+/* Turn-tail produced-files row: a quiet label followed by wrapping file chips.
+   Sits between the assistant body and its IconActions footer, so it reads as
+   part of the answer rather than as another tool row. */
+
+.root {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  margin-top: 16px;
+  font-size: 13px;
+  line-height: 22px;
+}
+
+.label {
+  color: var(--dsw-alias-label-tertiary);
+}
+
+/* One produced file. A link by behavior (it opens the file), a chip by shape:
+   full paths are long and several may wrap onto one row. */
+.file {
+  max-width: 320px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  margin: 0;
+  padding: 0 8px;
+  border: none;
+  border-radius: 6px;
+  background: var(--dsw-alias-interactive-bg-hover);
+  color: var(--dsw-alias-label-secondary);
+  font: inherit;
+  cursor: pointer;
+}
+
+.file:hover {
+  color: var(--dsw-alias-label-primary);
+  text-decoration: underline;
+}
+
+/* Overflow count: the row never silently drops files it did not show. */
+.more {
+  color: var(--dsw-alias-label-tertiary);
+}

packages/client/ui-deliverables/src/client/ProducedFiles.tsx

@@ -0,0 +1,54 @@
+// ProducedFiles: the produced-file row a finished turn ends with. The paths
+// come pre-matched by the turn-tail chain from the mutation tools'
+// follow-along locations, never from the closing prose. Clicking one goes
+// through the same openFile the tool rows use — the Host's own opener, on the
+// Host machine.
+
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
+import type { TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { NS } from './locales.ts'
+import css from './ProducedFiles.module.css'
+
+/** Files past this stay counted but unlisted: a refactor turn must not bury the answer. */
+const SHOWN = 6
+
+/** Trailing path segment, the part that identifies the file at a glance. */
+function basename(path: string): string {
+  const at = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'))
+  return at === -1 ? path : path.slice(at + 1)
+}
+
+/** Matched paths plus the opener and locale seats needed to present them. */
+export type ProducedFilesProps = Pick<TurnTailOwnerProps, 'openFile'> & {
+  matched: readonly string[]
+} & PropsLocale<typeof NS>
+
+/**
+ * Render one turn's produced files as openable chips.
+ * @param props - selector-matched paths, the chat view's file opener, and the locale seat.
+ * @returns The produced-files row.
+ */
+export function ProducedFiles({ matched: paths, openFile, t }: ProducedFilesProps) {
+  const shown = paths.slice(0, SHOWN)
+  const hidden = paths.length - shown.length
+  return (
+    <div className={css.root}>
+      <span className={css.label}>{t('produced.label')}</span>
+      {shown.map(path => (
+        <button
+          key={path}
+          type="button"
+          className={css.file}
+          // The full path is the disambiguator when two turns produce files
+          // that share a basename; the chip itself stays short.
+          title={path}
+          aria-label={t('produced.open', { name: path })}
+          onClick={() => { openFile(path) }}
+        >
+          {basename(path)}
+        </button>
+      ))}
+      {hidden > 0 && <span className={css.more}>{t('produced.more', { count: String(hidden) })}</span>}
+    </div>
+  )
+}

packages/client/ui-deliverables/src/client/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Deliverables plugin, browser half: registers the produced-files row into
+ * the chat view's turn-tail hole. All policy lives here — the derivation
+ * from the mutation tools' `locations`, the chip cap, and the copy — so
+ * composing this plugin out of cordis.yml removes the surface entirely; the
+ * owning view renders an empty hole at zero cost.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type {} from '@deepseek-ai/dsh-client-locale/client'
+import { ProducedFiles } from './ProducedFiles.tsx'
+import { en, NS, zh, type DeliverablesKey } from './locales.ts'
+import { selectProducedFiles } from './turn-deliverables.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface LocaleNamespaceMap {
+    /** Produced-files row copy. */
+    'deliverables': DeliverablesKey
+  }
+}
+
+export { ProducedFiles, type ProducedFilesProps } from './ProducedFiles.tsx'
+export { producedForClosing } from './turn-deliverables.ts'
+
+/** Required services for the tail-slot registration and its dictionaries. */
+export const inject = ['slots', 'locale']
+
+/**
+ * Client plugin body: register the dictionaries and the turn-tail entry.
+ * @param ctx - client root context.
+ */
+export function apply(ctx: ClientContext): void {
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-deliverables: dictionaries')
+  ctx.slots.inject(
+    'conversation.chat.turnTail',
+    () => ctx.slots.register({
+      name: 'conversation.chat.turnTail',
+      select: selectProducedFiles,
+      locale: NS,
+    }, ProducedFiles),
+  )
+}

packages/client/ui-deliverables/src/client/locales.ts

@@ -0,0 +1,21 @@
+/** `deliverables` namespace dictionaries. */
+
+/** Dictionary namespace owned by this plugin. */
+export const NS = 'deliverables'
+
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export const zh = {
+  'produced.label': '产物',
+  'produced.more': '还有 {count} 个',
+  'produced.open': '打开 {name}',
+}
+
+/** English dictionary (same key set). */
+export const en: Record<DeliverablesKey, string> = {
+  'produced.label': 'Produced',
+  'produced.more': '{count} more',
+  'produced.open': 'Open {name}',
+}
+
+/** Union of this namespace's dictionary keys. */
+export type DeliverablesKey = keyof typeof zh

packages/client/ui-deliverables/src/client/turn-deliverables.ts

@@ -0,0 +1,90 @@
+/**
+ * Pure derivation of one turn's produced files from finalized snapshot
+ * nodes. Client-only and model-free: the vocabulary is the mutation tools'
+ * own follow-along `locations`, never the closing prose.
+ */
+import type { ConversationNode, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
+import type { TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+
+/**
+ * Paths a call view reports having created or changed, by render intent rather
+ * than tool name: a diff card, or a generic card whose kind is `edit` (the
+ * shape `str_replace_editor`'s insert presents). Every other card produces
+ * nothing to open — a read looked, a delete removed, a terminal ran.
+ */
+function producedPaths(view: ToolResultNode['callView']): readonly string[] {
+  if (view === null) return []
+  if (view.card === 'diff') return (view.locations ?? []).map(location => location.path)
+  if (view.card === 'generic' && view.kind === 'edit') {
+    return (view.locations ?? []).map(location => location.path)
+  }
+  return []
+}
+
+/**
+ * Files produced by the turn the assistant at `seq` closes — the anchor the
+ * render site elects, so the row lands under the message that reports the
+ * work rather than after some mid-turn narration.
+ *
+ * The source is the mutation tools' own follow-along `locations`, not the
+ * closing prose: a produced file must be listed whether or not the model
+ * remembered to name it. A mutation is recognized by render intent, not by
+ * tool name — a diff card, or a generic card whose `kind` is `edit` (the shape
+ * `str_replace_editor`'s insert presents) — so a new mutation tool joins by
+ * declaring what it does. Reads contribute nothing (looking at a file does not
+ * produce it), and neither do deletes (there is nothing left to open) or
+ * failed calls. Paths keep first-seen order and appear once, so a file written
+ * and then edited in the same turn is one entry.
+ *
+ * Accumulation resets on the turn boundary — a user message, or a node
+ * reporting a different turn number — so a turn that mutates files and then
+ * ends without content text cannot spill its paths into the next turn's row,
+ * nor leave the dedup set suppressing a file the next turn legitimately
+ * rewrites. Tool results carry no turn of their own; the boundary is read off
+ * the nodes that do, and a user message resets the tracked turn to undefined
+ * because the next node to report one is stating the current turn, not
+ * entering a new one.
+ * @param nodes - snapshot nodes (surface order).
+ * @param seq - the closing assistant's seq (the render site's anchor).
+ * @returns Produced paths in first-seen order; empty when the turn wrote nothing.
+ */
+export function producedForClosing(nodes: readonly ConversationNode[], seq: number): readonly string[] {
+  let pending: string[] = []
+  let seen = new Set<string>()
+  let turn: number | undefined
+  for (const node of nodes) {
+    if (node.kind === 'tool-result') {
+      if (node.isError) continue
+      for (const path of producedPaths(node.callView)) {
+        if (seen.has(path)) continue
+        seen.add(path)
+        pending.push(path)
+      }
+      continue
+    }
+    if (node.kind === 'user') {
+      turn = undefined
+      pending = []
+      seen = new Set()
+    } else if ('turn' in node) {
+      if (turn !== undefined && node.turn !== turn) {
+        pending = []
+        seen = new Set()
+      }
+      turn = node.turn
+    }
+    if (node.kind === 'assistant' && node.seq === seq) return pending
+  }
+  return []
+}
+
+/**
+ * Claim the turn-tail chain only when its closing turn produced files.
+ * @param owner - Turn-tail owner currency for the closing assistant.
+ * @returns Produced paths as the component's match, or null to decline before mount.
+ */
+export function selectProducedFiles(owner: TurnTailOwnerProps): readonly string[] | null {
+  const { nodes, seq } = owner
+  const paths = producedForClosing(nodes, seq)
+  return paths.length === 0 ? null : paths
+}

packages/client/ui-deliverables/src/css-modules.d.ts

@@ -0,0 +1,6 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}
+
+declare module '*.css'

packages/client/ui-deliverables/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Deliverables plugin, node half. Pure UI plugin: the empty apply exists so
+ * the plugin appears in the host cordis.yml / Loader; the browser half ships
+ * via exports["./client"], discovered through the package.json dshClient
+ * declaration.
+ */
+
+/** Host plugin body — no host-side behavior for this surface plugin. */
+export function apply(): void {}

packages/client/ui-deliverables/src/invariant.ts

@@ -0,0 +1,32 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-deliverables`.
+ * @module @deepseek-ai/dsh-client-ui-deliverables/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-ui-deliverables'
+
+/** Cordis companion plugin name. */
+export const name = 'client-ui-deliverables-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: one slot registration and one dictionary
+ * registration, both effect-owned with disposal proven by the HMR-safety
+ * spec — the plugin emits no cordis events and owns no cross-plugin mutable
+ * state.
+ */
+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/client/ui-deliverables/tests/produced-files.spec.tsx

@@ -0,0 +1,178 @@
+// @vitest-environment jsdom
+/**
+ * ui-deliverables browser half: the derivation contract of
+ * `producedForClosing` over finalized snapshot nodes, the row's rendering
+ * and opener wiring, and the plugin registrations' fiber-teardown removal
+ * (HMR safety) against the real SlotsService.
+ */
+import { Context } from 'cordis'
+import { cleanup, fireEvent, render } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  AssistantMessageNode, ConversationNode, ToolResultNode, UserMessageNode,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { apply as applyLocale } from '@deepseek-ai/dsh-client-locale/client'
+import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
+import { ProducedFiles } from '../src/client/ProducedFiles.tsx'
+import { producedForClosing, selectProducedFiles } from '../src/client/turn-deliverables.ts'
+import { apply, inject } from '../src/client/index.ts'
+import { apply as applyNode } from '../src/index.ts'
+import { apply as applyInvariant } from '../src/invariant.ts'
+import { zh } from '../src/client/locales.ts'
+
+afterEach(cleanup)
+
+const user = (seq: number, text: string): UserMessageNode => ({
+  kind: 'user',
+  seq,
+  time: seq * 1000,
+  content: [{ type: 'text', text }] as never,
+  source: null,
+})
+const assistant = (seq: number, text: string, turn = 1): AssistantMessageNode => ({
+  kind: 'assistant', seq, time: seq * 1_000, turn, step: 1, blocks: [{ kind: 'text', text }],
+})
+const toolResult = (seq: number, callId: string, name = 'bash'): ToolResultNode => ({
+  kind: 'tool-result', seq, time: seq * 1_000, callId,
+  call: { name, argsRaw: `{"command":"cmd-${callId}","description":"run ${callId}"}` },
+  callTime: seq * 1_000 - 500,
+  content: [], isError: false, callView: null, resultView: null,
+})
+const wrote = (seq: number, callId: string, ...paths: string[]): ToolResultNode => ({
+  ...toolResult(seq, callId, 'write'),
+  callView: {
+    card: 'diff', title: `Write ${paths[0] ?? ''}`,
+    diffs: paths.map(path => ({ path, oldText: null, newText: 'x' })),
+    locations: paths.map(path => ({ path })),
+  },
+})
+
+describe('producedForClosing derivation', () => {
+  it('attributes each turn’s written files to the assistant that closes it', () => {
+    const nodes: ConversationNode[] = [
+      user(1, 'build it'),
+      assistant(2, 'writing', 1),
+      wrote(3, 'a', 'out/index.html'),
+      // Same file touched twice in one turn is one deliverable, in first-seen order.
+      wrote(4, 'b', 'out/app.css', 'out/index.html'),
+      // A read is not a deliverable; a failed write has no file to open.
+      { ...toolResult(5, 'c', 'read'), callView: { card: 'generic', title: 'Read x', locations: [{ path: 'x.ts' }] } },
+      { ...wrote(6, 'd', 'out/broken.html'), isError: true },
+      assistant(7, 'done', 1),
+      user(8, 'again'),
+      assistant(9, 'second turn', 2),
+    ]
+    expect(producedForClosing(nodes, 7)).toEqual(['out/index.html', 'out/app.css'])
+    expect(selectProducedFiles({ nodes, seq: 7, openFile: () => {} })).toEqual(['out/index.html', 'out/app.css'])
+    expect(selectProducedFiles({ nodes, seq: 9, openFile: () => {} })).toBeNull()
+    // A turn that produced nothing yields the empty list, and so does an
+    // anchor the window does not contain.
+    expect(producedForClosing(nodes, 9)).toEqual([])
+    expect(producedForClosing([user(1, 'hi'), assistant(2, 'hello', 1)], 2)).toEqual([])
+    expect(producedForClosing(nodes, 999)).toEqual([])
+  })
+
+  it('counts a generic edit and never spills across the turn boundary', () => {
+    const inserted = (seq: number, callId: string, path: string): ToolResultNode => ({
+      ...toolResult(seq, callId, 'str_replace_editor'),
+      // str_replace_editor's insert mutates behind a generic card, so the
+      // discriminant is the render intent, not the card shape alone.
+      callView: { card: 'generic', title: `insert ${path}`, kind: 'edit', locations: [{ path }] },
+    })
+    const nodes: ConversationNode[] = [
+      user(1, 'insert a line'),
+      inserted(2, 'i', 'notes.md'),
+      assistant(3, 'inserted', 1),
+      // Turn 2 mutates and then ends with no content text (interrupted, or its
+      // last text preceded the tool): its paths must not ride into turn 3.
+      user(4, 'now rewrite it'),
+      wrote(5, 'w', 'leaked.txt'),
+      user(6, 'and again'),
+      wrote(7, 'w2', 'notes.md'),
+      assistant(8, 'done', 3),
+    ]
+    expect(producedForClosing(nodes, 3)).toEqual(['notes.md'])
+    // Turn 3 lists only its own file — and the dedup set did not suppress the
+    // rewrite of a path an earlier turn already touched.
+    expect(producedForClosing(nodes, 8)).toEqual(['notes.md'])
+    expect(producedForClosing(nodes, 8)).not.toContain('leaked.txt')
+  })
+
+  it('resets on a turn-number change and skips turnless, viewless, and locationless nodes', () => {
+    const nodes: ConversationNode[] = [
+      user(1, 'go'),
+      // A turnless surface node neither tracks nor resets the boundary.
+      { kind: 'unknown', seq: 1.5, time: 1_500, type: 'x', data: null },
+      wrote(2, 'w', 'turn-one.txt'),
+      // A view-less result (window truncation) and cards without locations
+      // contribute nothing rather than crashing the walk.
+      toolResult(3, 'plain'),
+      { ...toolResult(4, 'nl', 'write'), callView: { card: 'diff', title: 'Write', diffs: [] } },
+      { ...toolResult(5, 'ge', 'str_replace_editor'), callView: { card: 'generic', title: 'insert', kind: 'edit' } },
+      assistant(6, 'mid narration', 1),
+      // Turn number advances with no user message in the window (truncated
+      // history): the accumulator must reset all the same.
+      assistant(7, 'closing', 2),
+    ]
+    expect(producedForClosing(nodes, 6)).toEqual(['turn-one.txt'])
+    expect(producedForClosing(nodes, 7)).toEqual([])
+  })
+})
+
+describe('ProducedFiles row', () => {
+  const t = makeTranslate(zh)
+
+  it('renders capped chips with the full path reachable and opens one on click', () => {
+    // Seven files: six chips plus an explicit remainder — the row bounds what
+    // it shows and says so rather than dropping the rest silently.
+    const paths = ['deep/a.html', 'b.css', 'c.ts', 'd.ts', 'e.ts', 'f.ts', 'g.ts']
+    const openFile = vi.fn<(path: string) => void>()
+    const view = render(<ProducedFiles matched={paths} openFile={openFile} t={t} />)
+    expect(view.getByText('产物')).toBeTruthy()
+    // Chips carry the basename; the full path stays reachable as the title.
+    const chip = view.getByRole('button', { name: '打开 deep/a.html' })
+    expect(chip.textContent).toBe('a.html')
+    expect(chip.getAttribute('title')).toBe('deep/a.html')
+    expect(view.queryByRole('button', { name: '打开 g.ts' })).toBeNull()
+    expect(view.getByText('还有 1 个')).toBeTruthy()
+    fireEvent.click(chip)
+    expect(openFile).toHaveBeenCalledWith('deep/a.html')
+  })
+})
+
+describe('package shells', () => {
+  it('the node half mounts inert and the invariant companion registers ownership', async () => {
+    // The node half is deliberately inert; mounting it must simply not throw.
+    applyNode()
+    const registered: string[] = []
+    const ctx = new Context()
+    ctx.provide('invariants')
+    ctx.set('invariants', {
+      register: (pkg: string) => { registered.push(pkg); return () => {} },
+    } as never)
+    const dispose = await applyInvariant(ctx)
+    expect(registered).toEqual(['@deepseek-ai/dsh-client-ui-deliverables'])
+    expect(dispose).toBeTypeOf('function')
+  })
+})
+
+describe('plugin registration', () => {
+  it('registers the tail entry and fiber disposal removes it', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SlotsService).await()
+    // The owning view's child declaration, stood up by a bench root entry.
+    ctx.slots.register({
+      name: 'root',
+      children: { 'conversation.chat.turnTail': { kind: 'chain', scope: 'session' } },
+    } as never, () => null)
+    await ctx.plugin({ inject: ['slots'], apply: applyLocale }).await()
+
+    const fiber = ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    expect(ctx.slots.entries('conversation.chat.turnTail')).toHaveLength(1)
+
+    await fiber.dispose()
+    expect(ctx.slots.entries('conversation.chat.turnTail')).toHaveLength(0)
+  })
+})

packages/client/ui-deliverables/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../locale"
+    },
+    {
+      "path": "../runtime"
+    },
+    {
+      "path": "../ui-conversation"
+    },
+    {
+      "path": "../ui-slots"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/client/ui-deliverables/tsdown.config.ts

@@ -0,0 +1,3 @@
+import { clientBundle } from '../tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-client-ui-deliverables', ['lib/types/index.js', 'lib/types/invariant.js'])

packages/client/ui-goal/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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/client/ui-goal/README.md
-README.md: 0ea00b8bf9b07f02b5df0f7b3e7d3d9c6f109fde
-README.zh.md: 70bf443118e5d2b1ce46e7bc1479bf932507b3f9
+README.md: a53fb3a89eaee364cb025ca728ca42ce934887b0
+README.zh.md: 1ad9f50aee5b103f6455e4d4b7d29fa9eb29a108