dsh-plugin-dev-kb 1.6.0 → 1.8.0

package/skills/dsh-plugin-starter.md

@@ -0,0 +1,65 @@
+---
+name: dsh-plugin-starter
+description: dsh 插件脚手架助手：从零新建一个合规的 dsh 插件骨架（package.json 含 dsh.bundle.patch 与 peer 显式预发布范围、cordis.patch.yml、双语 README、selfcheck、CHANGELOG、GitHub topics），逐项满足 dsh 官方发布要求与 dsh-market / awesome-dsh-plugin 收录门槛。用户说「新建 dsh 插件 / 做一个插件 / 插件脚手架 / starter」时加载本技能。注意：写 NoneBot 插件时请用 nonebot-plugin-dev-kb，勿用本技能。
+whenToUse: 用户要从零开始新建一个 dsh 插件，或问「插件骨架怎么搭 / 发布要准备什么文件」时
+---
+# dsh 插件脚手架（dsh-plugin-starter）
+
+帮用户从零搭一个**能通过官方校验、能进 market / awesome 收录**的 dsh 插件骨架。
+原则：每生成一个文件都对照下方清单自检；知识库文档只读不猜，拿不准就先检索确认。
+
+## 0. 知识库位置
+
+- **知识库根**：`{{KB_ROOT}}`
+- 先读两篇再动手：`{{KB_ROOT}}/site/develop/basic/index.md`（插件 = 导出 `apply(ctx)` 的模块，
+  `ctx.effect()` 自动清理）与 `{{KB_ROOT}}/site/develop/basic/publish.md`（打包发布）。
+- 配置 / 工具 / 事件写法按需检索：`dsh_kb_search`，如 query=`ctx.tools.register 工具定义`。
+
+## 1. 骨架清单（缺一 = 发布/收录会卡）
+
+在用户指定的目录 `<plugin-name>/` 下生成（命名规范：`dsh-plugin-<topic>` 或 `dsh-<topic>`）：
+
+| 文件 | 要点 |
+|---|---|
+| `package.json` | `"main": "./lib/index.js"`；`files` 数组**必须含 main 入口所在目录**；`license: "MIT"`；`homepage` 指 GitHub 仓库 `#readme`；`repository.url`；`keywords ≥3`（含 `dsh` / `dsh-plugin` / `deepseek-harness`）；**`dsh: { bundle: { patch: "./cordis.patch.yml" } }`**（只声明 `dsh.client` 会被 awesome CI 拒）；`engines.node >=18`；`peerDependencies` 若引 `@deepseek-ai/*`，**范围必须显式覆盖预发布分支**（如 `"^4.0.1"` 对 cordis 可行，对 dsh 主包要写 `">=0.2.0-rc.1 <0.3.0-0"` 形态，否则预发布构建被静默排除）；`scripts.selfcheck` 指向最小自检 |
+| `cordis.patch.yml` | 插件自注册声明（`dsh.profile.bundles` 挂载用）；含 Config 时在此声明配置 schema |
+| `lib/index.js` | `export function apply(ctx, config)`；零 `@deepseek-ai/*` 运行时 import（插件以 link:/file: 装入 profile，外部依赖按 realpath 解析不到——用原始 definition 形状注册工具，参照 dsh-plugin-windows-guard 先例）；每个注册动作包 `ctx.effect(() => ..., '说明')` |
+| `README.md` | ① 顶部标题 + 一句话描述；② `## 安装` 段**必须含标准安装命令**（`git clone` / `npm install` 等——market ease 项）；③ `## 功能` + `## 配置`/`## 示例` 双标题；④ ≥2 个代码块；⑤ `## 相关插件` 互相引用段（列同系列全部**已发布**插件：npm 链 + GitHub 链 + 一句话）；⑥ 长度 >2000 字更佳；⑦ 需要 `AI 生成声明` 段 |
+| `README.en.md` | 结构与中文一致（i18n 规范见 `{{KB_ROOT}}/extra/i18n/`） |
+| `CHANGELOG.md` | `## x.y.z - 日期` 逐版条目：修了什么/为什么/怎么验证 |
+| `LICENSE` | MIT |
+| `scripts/selfcheck.mjs` | 最小结构自检（文件存在性 + package.json 关键字段），发布前必跑 |
+| `.github/workflows/`（可选） | CI / 自动化（如每周内容同步） |
+
+## 2. 命名与元数据红线
+
+- 目录名 = npm 包名（例外如 `dsh-notify` 是历史遗留，新插件不要再造）
+- **README 里写「无需配置」时必须带否定词**（"无需 / 不需要 / zero-config"）——market 的
+  needsConfig 反向检测按裸关键词（`API_KEY` 等）扫描，否定语境会被先摘除；确需配置的插件
+  写配置项时避免裸写这些 KEY 名
+- 描述不得夸大：awesome 评审会对着源码逐条核对数字 / 命令 / API 名
+
+## 3. GitHub 侧（骨架生成后提醒用户补）
+
+```powershell
+gh api -X PATCH repos/<owner>/<repo> -f description="…（一句话中文简介，勿夸大）" -f homepage="https://github.com/<owner>/<repo>#readme"
+# topics 至少含 dsh / dsh-plugin / deepseek-harness + 主题词——缺 topics 是 market 收录失败最常见原因
+gh api -X PUT repos/<owner>/<repo>/topics --input topics.json
+```
+
+## 4. 验证闭环
+
+1. `node scripts/selfcheck.mjs` → 全部通过
+2. 用 dsh-dev-sandbox 技能建独立沙箱 profile 挂载冒烟（不污染主力 dsh）：
+   启动日志**不得**出现 `skipping profile bundle "<你的插件>"`（出现 = peer 闸门没过 = 静默失效）
+3. `npm pack --dry-run` 核对发布内容（files 不夹带内部文档）
+4. 发布流程与版本纪律见 `{{KB_ROOT}}/site/develop/basic/publish.md`
+
+## 5. 红线
+
+- **不要双挂载**：插件经 `dsh.profile.bundles` 进场后，profile 层不得再 insert 同 id
+  （`duplicate loader entry id` 启动即崩）
+- **不要在插件运行时 import `@deepseek-ai/*`**（见 lib/index.js 要点）
+- **不要把凭据写进入库文件**；用户凭据走 credentials ref / 环境变量
+- 知识库快照可能领先宿主 dsh 版本：API 行为不符时以宿主实际安装包为准，
+  版本差异读 `{{KB_ROOT}}/extra/upgrade-guide/`

package/skills/dsh-upgrade-assistant.md

@@ -0,0 +1,62 @@
+---
+name: dsh-upgrade-assistant
+description: DeepSeek Harness (dsh) 升级助手：用户升级 dsh 版本时，用知识库里的官方升级指南（upgrade-guide/）与持久化变更记录（persistence-changes/）生成迁移检查清单、预判破坏性变更、给出回滚方案。用户提到「升级 dsh / 更新 Harness / 换版本 / upgrade」或升级 dsh 后报错时加载本技能。注意：写 NoneBot 时请用 nonebot-plugin-dev-kb，勿用本技能。
+whenToUse: 用户要升级 dsh / DeepSeek Harness 版本，或升级后插件不工作、会话打不开等需要排查迁移问题时
+---
+# dsh 升级助手（dsh-upgrade-assistant）
+
+帮用户安全升级 DeepSeek Harness：先搞清「从哪版 → 到哪版」，再用知识库把两版之间的全部变更读出来，
+生成检查清单，升级后逐条验证。
+
+## 0. 知识库位置
+
+- **知识库根**：`{{KB_ROOT}}`（插件挂载时自动替换为实际绝对路径，可直接 read/glob/grep）
+- 升级相关内容在：`{{KB_ROOT}}/extra/upgrade-guide/`（逐版本升级指南）与
+  `{{KB_ROOT}}/extra/persistence-changes/`（持久化格式变更，按日期命名）
+
+## 1. 标准流程
+
+### 第一步：确定版本区间
+
+1. **当前版本**：读用户 profile 的安装信息（如 `%LOCALAPPDATA%` / profile 目录下的
+   `package.json` 中 `@deepseek-ai/dsh` 的版本，或让用户看 Desktop 关于页）。
+2. **目标版本**：`npm view @deepseek-ai/dsh version`（latest）或用户指定版本。
+3. 列出区间内的版本号，形如 `v0.2.0-rc.2 → v0.2.1-rc.4`。
+
+### 第二步：读变更（知识库检索）
+
+1. 对区间内**每个版本**读一份指南：
+   `{{KB_ROOT}}/extra/upgrade-guide/<版本>/`（目录按 `v0.1.7-rc.2` … `v0.2.2-alpha.3` 组织，
+   每个子目录是一篇 guide.md / guide.zh.md，读中文版）。
+2. 持久化/会话格式变更：列出 `{{KB_ROOT}}/extra/persistence-changes/` 中日期晚于当前版本
+   发布日的条目（文件名即日期），只读标题相关条目判断「历史会话会不会丢/迁移」。
+3. 快速定位也可用 `dsh_kb_search` 工具，如 query=`升级 upgrade-guide v0.2.1`。
+4. 优先关注三类破坏点：**删除/改名的 API**（插件会静默失效）、**会话格式升级**
+   （旧会话打不开或需要迁移）、**配置字段变更**（profile 的 cordis.patch.yml / package.json）。
+
+### 第三步：给出升级检查清单（输出给用户）
+
+清单必须包含：
+
+- **备份**：升级前备份 profile 的 `package.json` 与 `pnpm-lock.yaml`
+- **变更摘要**：区间内每个版本的破坏性变更，逐条说明「影响你吗」
+- **插件兼容**：dsh 有插件兼容闸门——`peerDependencies` 不覆盖目标版本的插件会被
+  **整体拒绝安装**或**启动时跳过（静默失效）**；把用户已装插件与目标版本对照，
+  预先列出需要升级/移除/豁免（allow-version）的插件
+- **回滚方案**：保留旧版本安装包/备份路径，回滚 = 恢复备份 + 重装旧版
+
+### 第四步：升级后验证
+
+- 启动时逐条看 stderr 的 `dsh: skipping profile bundle "X"` 警告——被跳过 = 该插件静默失效
+- 用一个旧会话验证历史消息正常加载（会话格式变更最常坏这里）
+- 逐个核心功能冒烟：新建会话、工具调用、技能加载、设置页
+- 若用户安装了 `dsh-plugin-dev-kb`，知识库可能比目标版本新（快照领先），
+  文档与实际行为不符时以实际安装包为准
+
+## 2. 红线
+
+- **不要在未备份的情况下动 profile**；备份是第一步，不是可选项
+- **不要用 allow-version 豁免兼容闸门来「绕过」不兼容插件**——除非用户明确要求并理解风险
+  （静默失效比拒绝安装更难排查）
+- 知识库是快照，若 upgrade-guide 目录里没有目标版本的目录（比如目标版本比知识库同步点新），
+  明确告知用户「该版本的官方指南未收录」，让用户看官方 release notes，不要编造变更内容

package/kb/extra/agent-lifecycle.md

@@ -1,91 +0,0 @@
-<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
-     Run `pnpm run gen-doc-graphs` to regenerate. -->
-
-# Agent Turn And Step Lifecycle
-
-This sequence is the visual companion to [architecture.md](architecture.md#turn-flow). It keeps durable replay facts on `session/event` and live control/status on `agent/*`.
-
-```mermaid
-sequenceDiagram
-  participant User
-  participant Agent
-  participant Driver
-  participant Hooks as hook listeners
-  participant Prompt as ctx.systemPrompt
-  participant LLM as ctx.llm
-  participant Tools as ctx.tools
-  participant Session
-  participant SDK as UI or SDK listener
-  User->>Agent: followup(content)
-  Agent-->>SDK: <code>agent/inbox/spliced</code>
-  Agent-->>SDK: <code>agent/inbox/inserted</code> { message }
-  Agent->>Driver: queued work wakes driver
-  Driver-->>SDK: <code>agent/status</code> running
-  Driver->>Session: <code>turn/start</code>
-  Note over Agent,Driver: claim pending next-step input plus one queued prompt
-  Driver-->>SDK: <code>agent/inbox/spliced</code> pure deletion
-  Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
-  Driver->>Prompt: <code>system-prompt/assemble</code> waterfall
-  Driver->>Hooks: <code>agent/pre-step</code> waterfall
-  Hooks-->>Driver: authoritative reject or enter(messages)
-  alt proposed step rejected, first batch empty, or pre-step failed
-    Driver-->>Driver: claimed batch stays removed, the open turn spends no step
-  else enter proposed step
-  Driver->>Session: <code>step/start</code>
-  Driver->>Hooks: <code>agent/request</code> waterfall
-  Driver->>LLM: prepareCall(config, signal)
-  Note over Driver,LLM: cancellation during either async phase commits neither system nor users
-  Note over Driver,Session: synchronous admission using the prepared call capability
-  Driver->>Session: <code>system/message</code> ordered per-node reconciliation
-  Driver->>Session: <code>user/message</code> per entered message
-  Driver->>Session: <code>request/header</code> and <code>request/context</code> as needed
-  Driver->>Driver: derive and freeze request from the log
-  Driver->>LLM: bound prepared call through <code>llm/stream</code> waterfall
-  LLM-->>Driver: StreamChunk*
-  Driver-->>SDK: <code>agent/assistant-stream</code> chunk*
-  alt final adapter or terminal in-band request failure
-    Driver->>Session: <code>assistant/attempt</code>
-    Driver-->>SDK: <code>agent/assistant-stream</code> committed end
-    Driver->>Hooks: <code>agent/request-error</code> waterfall
-    Hooks-->>Driver: return retry action or preserve the original error
-    Note over Driver,LLM: retry in the open step: prepare and reconcile the same rendered assembly without repeating pre-step or users
-  else model request succeeded
-  Driver->>Session: <code>assistant/message</code>
-  Driver-->>SDK: <code>agent/assistant-stream</code> committed end
-  Driver->>Tools: classify pending call by executionMode
-  loop barriers and bounded rolling pool, reclassify before start
-    opt call starts
-      Driver->>Session: <code>tool/call</code>
-      Driver->>Tools: ordered pre, concurrent execute
-      Tools-->>Session: tool-owned events when applicable
-    end
-    opt next model-order result ready
-      Driver->>Tools: ordered post
-      Driver->>Session: <code>tool/result</code>
-    end
-  end
-  Driver->>Session: <code>step/end</code>
-  opt natural stop and next-step inbox empty
-    Driver->>Hooks: <code>agent/turn-stopping</code> serial terminal checkpoint
-  end
-  opt next-step input is pending
-    Driver-->>Driver: claim pending next-step input
-    Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
-    Driver->>Hooks: <code>agent/pre-step</code> waterfall
-    Hooks-->>Driver: authoritative reject or enter(messages)
-  end
-  end
-  end
-  Driver->>Session: <code>turn/end</code>
-  Driver-->>SDK: <code>agent/status</code> idle
-```
-
-The `assistant/message` event records every successful provider call, including content-less and `max-tokens` finishes, and embeds the exact compact timed stream. Empty content stays out of derived history. A failed, retried, cancelled, or stream-error attempt that reaches settlement without a surface message records its stream as `assistant/attempt`. Live `agent/assistant-stream` chunk frames are transient; replay reads either durable settlement, and a hard process loss before settlement leaves no durable attempt stream.
-
-`dsh-compaction-basic` uses `agent/pre-step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery runs within the open step and retries only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative. Each retry prepares its call and reconciles the retained rendered assembly before request derivation, without repeating assembly, pre-step, or user admission.
-
-The returned `agent/pre-step` decision is authoritative; listeners wrapping `next()` preserve downstream messages and `startsRequestSeries` unless replacement is intentional. Steering and injected context pass through the same waterfall after a later claim operation takes their next-step batch.
-
-SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination API for queue/status, prompt interception, request construction, steering, continuation, and errors.
-
-Maintenance mode: curated Mermaid sequence; exact event signatures live in the generated Cordis catalog.

package/kb/extra/agent-lifecycle.zh.md

@@ -1,93 +0,0 @@
-<!-- 英文源文件由 scripts/gen-doc-graphs.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
-     更新时先运行 `pnpm run gen-doc-graphs` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/agent-lifecycle.md` 重新记录配对。 -->
-
-# Agent 轮次与步骤生命周期
-
-[English](agent-lifecycle.md) | 中文
-
-此时序图是 [architecture.md](architecture.zh.md#turn-flow) 的配套图示。持久的回放事实保存在 `session/event` 中，实时控制与状态则保存在 `agent/*` 中。
-
-```mermaid
-sequenceDiagram
-  participant User
-  participant Agent
-  participant Driver
-  participant Hooks as hook listeners
-  participant Prompt as ctx.systemPrompt
-  participant LLM as ctx.llm
-  participant Tools as ctx.tools
-  participant Session
-  participant SDK as UI or SDK listener
-  User->>Agent: followup(content)
-  Agent-->>SDK: <code>agent/inbox/spliced</code>
-  Agent-->>SDK: <code>agent/inbox/inserted</code> { message }
-  Agent->>Driver: queued work wakes driver
-  Driver-->>SDK: <code>agent/status</code> running
-  Driver->>Session: <code>turn/start</code>
-  Note over Agent,Driver: claim pending next-step input plus one queued prompt
-  Driver-->>SDK: <code>agent/inbox/spliced</code> pure deletion
-  Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
-  Driver->>Prompt: <code>system-prompt/assemble</code> waterfall
-  Driver->>Hooks: <code>agent/pre-step</code> waterfall
-  Hooks-->>Driver: authoritative reject or enter(messages)
-  alt proposed step rejected, first batch empty, or pre-step failed
-    Driver-->>Driver: claimed batch stays removed, the open turn spends no step
-  else enter proposed step
-  Driver->>Session: <code>step/start</code>
-  Driver->>Hooks: <code>agent/request</code> waterfall
-  Driver->>LLM: prepareCall(config, signal)
-  Note over Driver,LLM: cancellation during either async phase commits neither system nor users
-  Note over Driver,Session: synchronous admission using the prepared call capability
-  Driver->>Session: <code>system/message</code> ordered per-node reconciliation
-  Driver->>Session: <code>user/message</code> per entered message
-  Driver->>Session: <code>request/header</code> and <code>request/context</code> as needed
-  Driver->>Driver: derive and freeze request from the log
-  Driver->>LLM: bound prepared call through <code>llm/stream</code> waterfall
-  LLM-->>Driver: StreamChunk*
-  Driver-->>SDK: <code>agent/assistant-stream</code> chunk*
-  alt final adapter or terminal in-band request failure
-    Driver->>Session: <code>assistant/attempt</code>
-    Driver-->>SDK: <code>agent/assistant-stream</code> committed end
-    Driver->>Hooks: <code>agent/request-error</code> waterfall
-    Hooks-->>Driver: return retry action or preserve the original error
-    Note over Driver,LLM: retry in the open step: prepare and reconcile the same rendered assembly without repeating pre-step or users
-  else model request succeeded
-  Driver->>Session: <code>assistant/message</code>
-  Driver-->>SDK: <code>agent/assistant-stream</code> committed end
-  Driver->>Tools: classify pending call by executionMode
-  loop barriers and bounded rolling pool, reclassify before start
-    opt call starts
-      Driver->>Session: <code>tool/call</code>
-      Driver->>Tools: ordered pre, concurrent execute
-      Tools-->>Session: tool-owned events when applicable
-    end
-    opt next model-order result ready
-      Driver->>Tools: ordered post
-      Driver->>Session: <code>tool/result</code>
-    end
-  end
-  Driver->>Session: <code>step/end</code>
-  opt natural stop and next-step inbox empty
-    Driver->>Hooks: <code>agent/turn-stopping</code> serial terminal checkpoint
-  end
-  opt next-step input is pending
-    Driver-->>Driver: claim pending next-step input
-    Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
-    Driver->>Hooks: <code>agent/pre-step</code> waterfall
-    Hooks-->>Driver: authoritative reject or enter(messages)
-  end
-  end
-  end
-  Driver->>Session: <code>turn/end</code>
-  Driver-->>SDK: <code>agent/status</code> idle
-```
-
-`assistant/message` 事件会记录每次成功的提供方调用，包括返回空内容或以 `max-tokens` 结束的调用，并嵌入精确的紧凑带时间 stream。空内容不会进入派生历史。失败、重试、取消或 stream error attempt 到达 settlement 时，如果没有 surface message，就会把 stream 记录为 `assistant/attempt`。实时 `agent/assistant-stream` chunk frame 是瞬态数据；回放读取任一种持久 settlement，如果进程在 settlement 前硬中断，则不会留下持久 attempt stream。
-
-`dsh-compaction-basic` 在派生请求之前通过 `agent/pre-step` 处理压力，而 `agent/request-error` 仅用于规范的上下文溢出。任一触发条件满足后，系统都会先执行可选的工具结果剪枝，再选择摘要。恢复发生在仍打开的步骤内，只有剪枝或摘要生成推进 surface replacement generation 时才重试，否则仍以原始请求错误为准。每次重试都会准备调用，并在派生请求之前协调保留的已渲染组装结果，不重复组装、pre-step 或用户消息准入。
-
-以返回的 `agent/pre-step` 决策为准；通过包装 `next()` 的监听器会保留下游消息与 `startsRequestSeries`，除非有意替换。steering（中途引导）和注入的上下文在后续的认领操作取得其下一步骤批次后，会经过同一 waterfall（瀑布式事件）。
-
-需要可回放 transcript（文本记录）数据的 SDK 用户应当消费 `session/event`；`agent/*` 是用于队列与状态、提示词拦截、请求构造、steering、继续执行和错误处理的实时协调接口。
-
-维护模式：英文源文件包含人工维护的 Mermaid 时序图，并由生成器写出；本中文文件作为经评审对侧通过双语配对维护。确切的事件签名位于生成的 Cordis 目录中。

package/kb/extra/api-gateway.md

@@ -1,172 +0,0 @@
-# API Gateway
-
-English | [中文](api-gateway.zh.md)
-
-This is the current-state reference for the Typert API Gateway. It describes how business services declare unary and stream Remote methods, how the build generates Host and Client contracts, and how calls reuse the Connection RPC and `/api` route. Session events, incremental data, and other streaming protocols are outside this document's scope; they may use the same Connection but do not use Remote method descriptors.
-
-## Programming model
-
-Business services use `@Remote` or `@RemoteScope` to select the methods exposed to the Client. Unmarked methods do not enter the generated Client types or runtime contributions and cannot be called through `ctx.remote`.
-
-`@Remote` denotes calling a Cordis service registered on the root Host Context. Complex Host objects cannot cross the wire directly; the business package must declare their association with a wire identity through `TypertLookupMap` and register a default resolution provider with `ctx.typert.lookups` at runtime. For example, an `Agent` parameter named `agent` in the Host signature produces an `agentId` wire field, and the Gateway resolves that id to a Host object before invoking the business method. Host composition can use `ctx.typert.lookups.configure()` to override the resolution policy for a lookup key without changing the parameter name, wire field, or canonical type symbol owned by the business package.
-
-`@RemoteScope(key)` first resolves an identity to a scoped Context through `ctx.typert.contexts`, then obtains the service from that Context and invokes the method. It applies when the method itself depends on scoped composition and does not need to receive objects such as `Agent` explicitly.
-
-`@Remote` accepts an export name or `{ name?, mode?, resources? }`, and `@RemoteScope(key, option?)` accepts an export name, as in `@RemoteScope('agent', 'current')` below, or `{ name?, resources? }` as its second argument. `resources` holds per-kind readers that return the identities of the resources one call touches for access control; each reader receives the method's wire arguments as its own parameters, with types inferred from the decorated method. Most methods declare no readers, because the Gateway also reads identities from lookup parameters and scoped Contexts that declare a `resource`, and from the default fields in `typert.resources`; the [Typert subsystem](subsystems/typert.md) owns that order.
-
-Services normally extend `TypertRemoteService` so the constructor explicitly binds the Cordis service key and default Remote namespace. A service that already has another base class can instead declare `readonly typertRemote = bindTypertRemote(this, serviceKey)`; both forms leave an inspectable public binding and do not depend on the compiler injecting a symbol into the constructor.
-
-```ts
-import type { Agent } from '@deepseek-ai/dsh-agent'
-import { TypertRemoteService, Remote, RemoteScope } from '@deepseek-ai/dsh-typert-protocol'
-import type { Context } from '@deepseek-ai/cordis'
-
-export interface CreateGoalRequest {
-  objective: string
-}
-
-export interface CreateGoalResult {
-  accepted: boolean
-}
-
-export class GoalService extends TypertRemoteService {
-  constructor(ctx: Context) {
-    super(ctx, 'goals')
-  }
-
-  @Remote('create')
-  createForClient(
-    agent: Agent,
-    request: CreateGoalRequest,
-    signal: AbortSignal,
-  ): CreateGoalResult {
-    signal.throwIfAborted()
-    return this.create(agent, request)
-  }
-
-  @RemoteScope('agent', 'current')
-  currentForClient(): CreateGoalResult {
-    return { accepted: true }
-  }
-
-  private create(_agent: Agent, request: CreateGoalRequest): CreateGoalResult {
-    return { accepted: request.objective.length > 0 }
-  }
-}
-```
-
-Remote methods may return a value synchronously or return a Promise. For cooperative cancellation, the final parameter in the Host signature must be `signal: AbortSignal` using the global type; it is recorded in the descriptor instead of entering `args`, while the generated Client method accepts an optional final `AbortSignal`.
-
-`@Remote({ mode: 'stream' })` marks a method that returns `Iterable`, `AsyncIterable`, or `RemoteStream<Out, In>`: the Gateway delivers each yielded item, a value the Host method produced, over its multiplexed `/api/remote.mux` WebSocket or an in-process carrier, and the generated Client method returns a `RemoteStreamHandle<Out, In>` that iterates the items and exposes `send`, `end`, and `dispose` for the Client-to-Host uplink of the same logical stream. The second type argument of `RemoteStream<Out, In>` declares the uplink item type; the Gateway validates each item the Client sends, because it arrives from the browser, with the generated `In` codec before the Host method reads it through `this.ctx.invocation.uplink<In>()`. The uplink enters neither `args` nor the parameter list; the [Gateway README](../packages/api/gateway/README.md) owns the frame, half-close, cancellation, and inbox-bound contracts.
-
-The Client uses concrete functions on ordinary objects, not a JavaScript Proxy. Direct and scoped calls appear under `ctx.remote.<namespace>` and `agentCtx.remote.<namespace>`. Each namespace is a traced Cordis child Service registered as `remote.<namespace>`; the Client assembly mounts contributions through `ctx.remote.$mount()`, and the namespace unloads after its last method is withdrawn. Dependency declarations belong to the actual caller: only a business package that reads `ctx.remote.<namespace>` or `agentCtx.remote.<namespace>` declares both `remote` and `remote.<namespace>` in its own `inject`; assemblies that only mount contributions and higher-level runtimes that do not call that namespace do not declare the namespace dependency on the business package's behalf. When an `@Remote` method has exactly one lookup parameter and a same-named `TypertContextMap` uses the same wire identity, the generated scoped signature omits that identity parameter. `@RemoteScope` generates only the scoped invocation interface.
-
-```ts ignore-check
-import type { SessionId } from '@deepseek-ai/dsh-session/types'
-import type { AgentContext } from '@deepseek-ai/dsh-api-session-controller/client'
-import type { Context } from '@deepseek-ai/cordis'
-import type {} from '@deepseek-ai/dsh-api-remotes/client'
-
-export const inject = ['remote', 'remote.goals']
-
-declare const ctx: Context
-declare const agentCtx: AgentContext
-declare const agentId: SessionId
-
-await ctx.remote.goals.create(agentId, { objective: 'ship it' })
-await agentCtx.remote.goals.create({ objective: 'ship it' })
-```
-
-Client applications assemble only `@deepseek-ai/dsh-api-remotes`. That package imports the `/remote` subpaths of selected business packages as runtime values, mounts their contributions through `ctx.remote.$mount()`, and re-exports the declaration merges from the same files. Adding a Host Remote package is an explicit choice by the Client composition owner; business components do not need to load the Typert Gateway or the business package's Remote JS separately.
-
-The `api-remotes` assembly and the `ctx.remote` contract are React-independent; the Host methods visible to any Client assembly are limited to the Remote methods selected at generation time.
-
-## Component responsibilities
-
-| Location | Package or entry | Responsibility |
-|---|---|---|
-| Shared | `@deepseek-ai/dsh-typert-protocol` | Declares decorators, Gateway bindings, merge-extensible protocol maps, invocation descriptors, and provider types; starts no TypeScript analysis and registers no Cordis services |
-| Build | `@deepseek-ai/dsh-typert-generator` | Strictly analyzes Remote signatures, the type graph, lookups, Contexts, and source locations from the Host `ts.Program`, then generates Host and Host-for-Client artifacts |
-| Host | `@deepseek-ai/dsh-typert-registry` and Loader | Places generated Host descriptors, schemas, and business-package registrations in `ctx.typert`, and holds lookup and Context providers |
-| Host | `@deepseek-ai/dsh-api-session-controller` | Owns the application Agent/Session identity policy and configures the corresponding Typert lookups |
-| Host | `@deepseek-ai/dsh-api-gateway` | Provides `ctx.typertGateway`, claims Remote endpoints, validates request values, resolves objects or Contexts, and invokes live Cordis services |
-| Host | `@deepseek-ai/dsh-api-remote-access` | Decides which Remote methods a non-owner Peer may call through business-registered role-based policies, filters list results, and streams each Peer's access snapshot; the Gateway requires it |
-| Client | `@deepseek-ai/dsh-api-gateway/client` | Provides `ctx.remote` and `remote.<namespace>` child Services, mounts generated descriptors as concrete methods, and initiates and cancels calls through the Connection |
-| Client | `@deepseek-ai/dsh-api-remotes/client` | Explicitly selects and mounts the `/remote` contributions allowed by the application and brings the corresponding declaration merges into business code |
-| Both | `@deepseek-ai/dsh-client-connection` | Provides the RPC carrier, request correlation, trust boundary, cancellation, response envelope, and the `/api` HTTP bridge |
-
-The API Gateway package owns the Host dispatcher and Client Remote endpoint as peer entries, but the two builds never enter the same `ts.Program`. The Host entry does not import the Client Cordis `Context` merge, and the Client entry does not import the Host Gateway service.
-
-## Strict generation pipeline
-
-The root build compiles and bundles the Host face, then the Client face, then builds the Web shell ([step order](development.md#typescript-project-layout)). The Host phase first compiles the Host package references, then runs `tsdown --env.DSH_BUILD_FACE host`; the normal Host Project Reference graph compiles the Typert generator, which runs during this tsdown pass with the Host aggregate as its only `ts.Program` seed. The Client phase then compiles the Client package references and runs `tsdown --env.DSH_BUILD_FACE client`, consuming the newly generated Remote Client declarations and runtime contributions without starting Typert again.
-
-Both tsdown passes match `vendor/*`, `packages/*/*`, and `apps/cli`, the Host pass also `apps/desktop-host` ([build order](development.md#typescript-project-layout)), and both bundle only JavaScript emitted to `lib/types` by the corresponding tsc phase. The root config does not scan Client artifacts, classify package names, or pass a maintained filter to tsdown; package-local configs return entries for the current phase based on `DSH_BUILD_FACE`. An ordinary Client plugin produces both its Node loader entry and browser bundle during the Client phase.
-
-`api/remotes`, `api/gateway`, `api/session-controller`, and `api/workspace-controller` (plus `client/connection`) split TypeScript faces. `api/remotes`' Client project depends on `/remote` declarations generated for business packages during Host tsdown; root aggregates and direct consumers must reference each split package's `tsconfig.host.json` or `tsconfig.client.json` respectively. `api-remotes`' `clientBundle(..., { hostPhase: true })` produces its Host entry during Host tsdown and leaves only the browser entry for Client tsdown. The Agent/Session lookup policy lives in `@deepseek-ai/dsh-api-session-controller`, not in `api-remotes`.
-
-Each contributing business package writes generated files to its own `lib/` directory, not to its source directory:
-
-| File | Consumer | Contents |
-|---|---|---|
-| `typert.host.js` | Host Loader | Runtime reflection for the Host face, strict invocation descriptors, and schema registration values |
-| `typert.host.d.ts` | Host type system | Generated declarations for the Host face |
-| `typert.remote-client.js` | `api-remotes` | A mountable `TypertRemoteContribution` containing strict descriptors and runtime codecs |
-| `typert.remote-client.d.ts` | Client type system | Declaration merges for `TypertRemoteNamespaceMap` and `TypertRemoteScopeMap`, plus Client-safe type references |
-| `typert.remote-client.d.ts.map` | Editor | Maps generated method properties back to Remote method declarations in the Host package |
-
-Business packages expose the Host Loader entry through `./typert` and the Host-for-Client entry through `./remote`. The generator also validates these package exports and published-file lists; it generates artifacts only for explicit contribution packages that provide the corresponding entry.
-
-Parameter names in Remote Client declarations come from wire fields, while parameter and return types reference Client-safe types exported by the original business package. The declaration map resolves the generated property behind `ctx.remote.goals.create` back to the Host source method marked with `@Remote`, so editors that support declaration maps can navigate from a Client call to the real implementation instead of stopping at the generated `.d.ts`.
-
-Strict analysis requires a Remote to be a public, non-static instance method with a concrete implementation. The method cannot be generic; parameters must be required, named simple identifiers and cannot use destructuring, default values, rest parameters, or optional parameters. Typert generates strict schemas for ordinary JSON-representable types; complex objects such as workspace classes must have a unique `TypertLookupMap` declaration. Lookup and Context packages are responsible for both static declaration merges and runtime provider registration; if either side is missing, the build fails or the first call that needs the provider fails.
-
-## Runtime invocation
-
-Remote calls use the Connection's `/api` route. The Client Remote calls `connection.rpc.call('/api', '<namespace>/<method>', { args }, signal)`; the HTTP carrier maps this to `POST /api/<namespace>/<method>`, with a payload containing only a named `args` object.
-
-The Connection performs the unified trust check for `/api` before the HTTP bridge, then dispatches inside the shared FetchHandler. The Typert Gateway claims only two-segment endpoints that have a strict descriptor or active SRC marker; it projects binary Remote fields into JSON-compatible metadata and result-relative byte attachments, which Connection frames as multipart responses. Feature-owned exact Fetch routes handle responses outside the RPC envelope, and other requests return 404. Connection owns transport, RPC ids, response envelopes, and request cancellation, while Gateway owns the Remote data protocol and business dispatch. Replacing the Connection carrier does not require changes to Remote descriptors or the Client programming interface.
-
-For every call, the Gateway resolves the descriptor and live service from the current registries instead of caching business objects. Every call names the Peer it speaks for, and a disposed Peer is refused with `gateway/peer-disposed`. The Gateway requires the fields in `args` to match the descriptor exactly; for a call whose Peer principal is not the owner it then resolves the resources the call touches and asks `ctx.remoteAccess.decide()`, so a refused call resolves no lookup and activates no Agent. It validates wire values with codecs, resolves objects or receivers through registered lookup or Context providers, and invokes the service method targeted by the binding. The Client Gateway validates decoded binary results with the generated result codec; ordinary JSON results retain their existing handling. A missing provider, unknown identity, binding mismatch, missing or extra argument, schema failure, or missing method fails before entering or after leaving business code.
-
-The lookup provider's `register()` supplies both the stable declaration and the default resolver; `configure()` supplies a resolver owned by Host composition that may execute asynchronously and is scoped to an effect lifetime. Configuration may precede provider mounting; without a provider, invocation still fails with `gateway/lookup-unavailable`, and unloading the configuration restores the provider's default policy. The Session Controller owns the standard resolver semantics for `agent` and `session`: it reuses a live Agent, automatically resumes ordinary cold sessions, deduplicates concurrent resumes, and rejects identities owned by subagent routing; the `session` lookup returns that Agent's Session. A resume failure and an ownership fence raise a `RemoteError` carrying their own code, `session/not-found` or `session/agent-busy`, which the Gateway encodes onto the wire unchanged; only an unclassified throw folds into `gateway/internal`.
-
-Unloading a Client contribution removes its descriptors and concrete methods together, aborts its in-flight calls, and makes stale method handles retained by external code reject further calls. A strict endpoint withdrawn on the Host also does not degrade to SRC inference, preventing a hot unload from silently weakening validation.
-
-## SRC development fallback
-
-When the Host starts from source through `node --import tsx/esm`, it does not execute the Typert compiler plugin. Standard decorator initializers still record the method name and invocation mode in a versioned descriptor on the Service prototype, while `TypertRemoteService` or `bindTypertRemote()` supplies the explicit service binding; the Gateway can therefore construct a weaker temporary descriptor without starting a `ts.Program`. The descriptor's stable string property name lets `remoteMethods()` read markers written by another installed copy of the protocol package.
-
-The SRC fallback parses simple parameter names from the live function. When a parameter name matches the `parameter` of a registered lookup, such as `agent` or `session`, it uses the lookup's `agentId` or `sessionId` wire field and resolves the object on the Host; other parameters are checked only for cycle-free, JSON-safe data with no special prototype. `@RemoteScope` directly uses the wire field of a registered Host Context provider. SRC does not read TypeScript types, generate Zod schemas, infer optional parameters, or support destructuring, default values, rest parameters, or duplicate parameter names.
-
-SRC solves only dispatch for a Host process running from source. The Client does not discover decorators from the running Host, and the Client Remote refuses to mount SRC descriptors that lack strict codecs; its types, codecs, and Remote registration values always come from the most recently generated `lib/typert.remote-client.*` artifacts.
-
-## Development mode
-
-Web development runs one command, which builds current Host, Client, and Web artifacts, starts the source Host, and keeps Client bundles rebuilt:
-
-```sh
-pnpm run dev:web
-```
-
-`dsh` starts the Host source through tsx, so the Host can use the SRC fallback; the `dev:web` watchers rebuild the client-face type emit, Client plugin and library bundles, and the Web shell on source edits. They do not analyze Host decorators or generate Remote Client DTS; only the complete build that `dev:web` runs first (or `pnpm run build`) does.
-
-Changing only a Remote method's implementation body without changing its contract does not require regenerating the Typert files. After adding or removing a decorator or changing an export name, namespace, parameter, return value, lookup, Context, or cancellation signature, rerun the ordered lib build so the Host generates the strict contract before the Client compiles and bundles the new contribution:
-
-```sh
-pnpm run build:lib
-```
-
-The running Client watcher consumes these generated files when it rebundles. If `pnpm run build:lib:host` has already refreshed the Host contract, `pnpm run build:lib:client` can complete the Client side; a clean worktree cannot skip the Host phase. Recompiling only the frontend source cannot infer new types from Host decorators. `pnpm run typecheck` generates the Host contract with the bundle-free Typert pass before Client tsc, and the CI build lanes and release builds generate it in the Host bundle phase before Client tsc.
-
-## Boundaries
-
-Remote handles unary method calls with one request and one result, and stream methods whose items flow Host → Client while the Client's items reach the running Host method through `this.ctx.invocation.uplink()`. Session event streams, pagination, incremental reduce, projection, and entity substreams still require a separate data protocol and registration model; even when they reuse the Connection, they must not masquerade as Remote methods or enter invocation descriptors.
-
-The API layers are organized as `remotes → gateway → connection → webserver`. The BFF and Typert RPC layers live under `packages/api`; Connection and WebServer live at `packages/client/connection` and `packages/host/webserver`. Unary results containing `Uint8Array`, including nested fields and array entries, use [binary Remote transfer](../.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.md). A feature that needs a response outside the RPC envelope registers an exact Connection Fetch route.
-
-Lookup policy is configured per key, so all `agent` or `session` parameters share the cold-resume behavior. Accepting live objects only would require an explicit per-parameter or per-endpoint policy, which does not exist; the business method must not guess whether the object came from restoration.
-
-### Business ownership
-
-`packages/api` owns transport, call shape, and session lifecycle; a business rule belongs to an independent business package and reaches this layer through a registration surface or projected data. The requirements a change here must satisfy — the four `@Remote` disciplines, the additive-names rule, and the boundary this layer keeps — are owned by [Remote and API rules](defensive-patterns/remote-and-api.md), which is where a review checks them.