dsh-plugin-dev-kb 1.0.8 → 1.1.0

package/kb/extra/cookbook/adding-a-remote-api.zh.md

@@ -0,0 +1,197 @@
+# 实操手册：新增一个 Remote API
+
+[English](adding-a-remote-api.md) | 中文
+
+新增或改动一个 `ctx.remote` 端点按本页五步走：声明方法、声明失败、在包上注册、在 Client 消费、写测试。decorator 语义、lookup 解析、生成管线与 `/api` 路由属于机制，由 [API Gateway 参考](../api-gateway.zh.md)负责；本页给的是每一步的动作与必须遵守的约定。为什么是这套编程面，见 [Typert Remote 方法调用 Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md)；为什么失败面是单个 `RemoteError` 加一张码表，见[失败词汇 Agent Note](../../.agents/notes/implemented/architecture/2026-08-28-ctx-remote-failure-vocabulary.zh.md)。
+
+## 1. 声明 API
+
+owner 是一个 Host 侧 Cordis 服务：继承 `TypertRemoteService` 把 service 键与 wire namespace 一起绑定，再用 `@Remote` 标注对外暴露的方法。业务方法的签名若已符合 wire 约定就直接标注它本身；只有形态需要调整（补 `signal`、换参数顺序、换导出名）才写一个 `remoteExport*` adapter，由它调用不改名的业务方法。lookup 对象（`Agent`、`Session`）只能占顶层参数位，支持协作式取消的方法把 `signal: AbortSignal` 放在最后一位。
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
+
+/** One stored note as a Client reads it. */
+export interface NoteRow {
+  readonly noteId: string
+  readonly title: string
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    notesController: NotesController
+  }
+}
+
+export class NotesController extends TypertRemoteService {
+  constructor(ctx: Context) {
+    super(ctx, 'notesController', { namespace: 'notes' })
+  }
+
+  /**
+   * @param agent - lookup parameter the Gateway resolves from its wire identity.
+   * @param signal - carrier cancellation, always the final parameter.
+   * @returns the notes this Agent's session owns.
+   */
+  @Remote('list')
+  async remoteExportList(agent: Agent, signal: AbortSignal): Promise<NoteRow[]> {
+    return await this.list(agent, signal)
+  }
+
+  /** The in-process API the adapter above delegates to, unchanged by it. */
+  async list(agent: Agent, signal: AbortSignal): Promise<NoteRow[]> {
+    signal.throwIfAborted()
+    return await Promise.resolve([{ noteId: `${agent.id}-1`, title: 'draft' }])
+  }
+}
+```
+
+## 2. 声明失败
+
+Remote 失败只有一个类 `RemoteError`：域码经 declaration merging 进 `RemoteErrorDetailsMap`，失败点直接 `throw new RemoteError(code, message, details)`。不要建域异常类家族，也不要写出口映射函数；与本端点无关的异常不预先归类，Gateway 会兜底折成 `gateway/internal`。只有"把任意 provider 异常归为一个域码"这一种场景才写 `catch`，并把原始异常挂在 `cause` 上。
+
+码名是 `<域>/<理由>`，声明落点四条：
+
+- 只有一个生产者：声明落生产者包，紧挨抛出点。
+- 多个包共同生产：落双方共同依赖的最低层域包（`session/not-found` 在 `core/session`，`workspace/not-found` 在 `dsh-workspace`）。
+- 载体码 `gateway/bad-request`、`gateway/cancelled`、`gateway/internal` 已在 protocol 声明，Gateway 基础设施码已在 gateway 声明——直接用，不要复制。
+- 不上 wire 的本地失败不进码表，用调用方自己的类型表达。
+
+```ts
+import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
+
+declare module '@deepseek-ai/dsh-typert-protocol' {
+  interface RemoteErrorDetailsMap {
+    /** No stored note carries that id. */
+    'note/not-found': { readonly noteId: string }
+    /** The store refused an otherwise valid write. */
+    'note/rejected': { readonly noteId: string }
+  }
+}
+
+declare const stored: ReadonlyMap<string, string>
+declare function persist(noteId: string, title: string): Promise<void>
+
+export async function rename(noteId: string, title: string): Promise<void> {
+  if (!stored.has(noteId)) {
+    throw new RemoteError('note/not-found', `no note "${noteId}"`, { noteId })
+  }
+  try {
+    await persist(noteId, title)
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new RemoteError('note/rejected', message, { noteId }, { cause: error })
+  }
+}
+```
+
+## 3. 在包上注册
+
+`@Remote` 必须落在一个 Loader entry 插件包里；owner 是抽象 seam 时把控制器放进 `packages/api/` 下的对应包。包清单要补两个生成入口与 protocol 的 peer 依赖，Client 侧则由 `@deepseek-ai/dsh-api-remotes` 的 assembly 挂载该贡献并按需转口类型词汇。两个入口分别指向哪个生成产物、生成管线如何排序，见 [API Gateway 参考](../api-gateway.zh.md)。
+
+```json
+{
+  "exports": {
+    "./typert": { "types": "./lib/typert.host.d.ts", "default": "./lib/typert.host.js" },
+    "./remote": { "types": "./lib/typert.remote-client.d.ts", "default": "./lib/typert.remote-client.js" }
+  },
+  "peerDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:^" },
+  "devDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:^" }
+}
+```
+
+改动了签名、码表、namespace 或导出名之后重跑 `pnpm run build:lib`，Client 才拿得到新的声明与 codec；只改实现体不需要重新生成。
+
+## 4. 在 Client 消费
+
+调用插件在 `inject` 里同时声明 `remote` 与 `remote.<namespace>`，调用点直写 `ctx.remote.<namespace>.<method>(...)`：不要用 `Pick<ClientRemote, …>` 窄化、不要手写方法签名、不要造 wire 中转对象。结果是 `RemoteResult<T>`，就地 `if (!result.ok)` 分支，判 `code` 而不是 `instanceof`——code 分支会自动窄化 `details`。异常流的站点写 `throw result.error`（它是真 Error）；接住它的上层用 `isRemoteFailure` 区分 Remote 失败与本地缺陷，本地缺陷继续往上抛。不要写防御性 catch：Remote 调用不 reject，装配错误就该炸。
+
+Host 的固定事实读 `ctx.remote.$host`：`home` 与 `isLoopback` 是普通值读取，没有订阅也没有 generation 计数器，`home` 在第一帧 ready 之前是 `undefined`；重连后的刷新走 `ctx.on('connection/reset')` 或各域自己的 remote 事件。调用方 abort 掉一次一元调用时，结果落在错误分支上的 `gateway/cancelled`，而不是抛出。
+
+```ts ignore-check
+import type { Context } from '@deepseek-ai/cordis'
+import { isRemoteFailure } from '@deepseek-ai/dsh-api-gateway/client'
+import type {} from '@deepseek-ai/dsh-api-remotes/client'
+
+export const inject = ['remote', 'remote.notes']
+
+declare const ctx: Context
+
+/** Store-side read: the error branch is handled where the code is meaningful. */
+export async function noteTitles(): Promise<readonly string[]> {
+  const result = await ctx.remote.notes.list()
+  if (!result.ok) {
+    if (result.error.code === 'note/not-found') return []
+    throw result.error
+  }
+  return result.value.map(row => row.title)
+}
+
+/** Action-side: a Remote failure becomes copy; a local fault keeps crashing. */
+export async function renderTitles(): Promise<string> {
+  try {
+    return (await noteTitles()).join(', ')
+  } catch (error: unknown) {
+    if (!isRemoteFailure(error)) throw error
+    return `unavailable (${error.code})`
+  }
+}
+
+/** Fixed Host facts as plain reads. */
+export function hostLabel(): string {
+  const { home, isLoopback } = ctx.remote.$host
+  return home ?? (isLoopback ? 'local host' : 'remote host')
+}
+```
+
+## 5. 测试
+
+owner 侧断言抛出的码：捕获后用 `remoteErrorOf` 取出失败，再用 `toMatchObject` 比对 `code` 与需要的 `details` 字段——不要用 `toEqual` 深比对错误对象，也不要断言 `instanceof`。
+
+```ts
+import { remoteErrorOf } from '@deepseek-ai/dsh-typert-protocol'
+import { expect, it } from 'vitest'
+
+declare function rename(noteId: string, title: string): Promise<void>
+
+it('refuses an unknown note before writing', async () => {
+  const failure = await rename('n-404', 'fresh title').catch((error: unknown) => error)
+
+  expect(remoteErrorOf(failure)).toMatchObject({
+    code: 'note/not-found',
+    details: { noteId: 'n-404' },
+  })
+})
+```
+
+Client 侧的替身返回真实例：`RemoteError` 与 `TestRemote` 的值 import 一律取自 `@deepseek-ai/dsh-client-test-runtime`，因为从 `api-remotes` facade 值 import 会拉起尚未构建的装配链。`TestRemote.$host` 是普通字段，spec 直接赋值即可。
+
+```ts ignore-check
+import { Context } from '@deepseek-ai/cordis'
+import { RemoteError, TestRemote } from '@deepseek-ai/dsh-client-test-runtime'
+import { expect, it } from 'vitest'
+
+it('renders the failure code the Host reported', async () => {
+  const ctx = new Context()
+  const remote = new TestRemote(ctx, {
+    notes: {
+      list: () => Promise.resolve({
+        ok: false as const,
+        error: new RemoteError('note/not-found', 'no note "n-404"', { noteId: 'n-404' }),
+      }),
+    },
+  })
+  remote.$host = { home: '/home/fixture', isLoopback: true }
+
+  await expect(ctx.remote.notes.list()).resolves.toMatchObject({ error: { code: 'note/not-found' } })
+})
+```
+
+## 验证
+
+1. `pnpm run build:lib`：签名、码表、namespace 或导出名变过就必须重跑，Client 声明与 codec 由它产出。
+2. `pnpm run typecheck`：Host 与 Client 两个 program 都过一遍，码表的 merge 落点错了会在这里红。
+3. 点名跑两侧 spec：`npx vitest run <owner spec> <client spec>`。
+4. 端点属于产品可见面时补一条录制会话快照，规则见[测试策略](../testing.zh.md)。

package/kb/extra/cookbook/adding-a-vendored-package.md

@@ -8,7 +8,7 @@ When the harness needs another upstream Cordis package (e.g. `@cordisjs/plugin-h
 
 ```
 vendor/<dir>/
-  package.json     # from upstream; set "private": true, rescope the name, keep exports/type
+  package.json     # from upstream; rescope the name, keep exports/type (publishable release member, no private flag)
   tsconfig.json    # extends ../../tsconfig.base.json (see configuration below)
   src/             # the upstream src/ verbatim
   README.md LICENSE # if upstream ships them
@@ -29,7 +29,7 @@ vendor/<dir>/
 }
 ```
 
-`package.json` invariants: `"private": true` (vendored packages are never published), rescope the `name` ([mapping](../rescope.md)) while keeping upstream's `version`/`exports`/`type`, point declaration metadata at `lib/types`, publish `.d.ts` and `.d.ts.map` declaration outputs, and list its cordis deps in `peerDependencies` (matching the upstream manifest). Transitive upstream deps must themselves be vendored or already present — vendoring one package often means vendoring its dependency tree (e.g. `@cordisjs/plugin-http` pulls `@cordisjs/fetch-file`).
+`package.json` invariants: rescope the `name` ([mapping](../rescope.md)) while keeping upstream's `exports`/`type`, point declaration metadata at `lib/types`, publish `.d.ts` and `.d.ts.map` declaration outputs, and list its cordis deps in `peerDependencies` (matching the upstream manifest). Vendored packages are publishable release members, so they must NOT set `private: true` and must set `publishConfig.access: public`; the `version` field follows the harness release sequence (see [vendor/README.md](../../vendor/README.md)). Transitive upstream deps must themselves be vendored or already present — vendoring one package often means vendoring its dependency tree (e.g. `@cordisjs/plugin-http` pulls `@cordisjs/fetch-file`).
 
 Local relative imports/exports in vendored TypeScript source use explicit `.ts` specifiers after copying. This is a repo-local build difference from upstream: `rewriteRelativeImportExtensions` emits `.js` runtime imports while declarations keep explicit `.ts` specifiers that NodeNext/Node16 TypeScript consumers can resolve.
 

package/kb/extra/cookbook/adding-a-vendored-package.zh.md

@@ -8,7 +8,7 @@
 
 ```
 vendor/<dir>/
-  package.json     # from upstream; set "private": true, rescope the name, keep exports/type
+  package.json     # from upstream; rescope the name, keep exports/type (publishable release member, no private flag)
   tsconfig.json    # extends ../../tsconfig.base.json (see configuration below)
   src/             # the upstream src/ verbatim
   README.md LICENSE # if upstream ships them
@@ -29,7 +29,7 @@ vendor/<dir>/
 }
 ```
 
-`package.json` 的不变式：`"private": true`（vendored 包永不发布）；改写 `name` 的 scope（[映射](../rescope.zh.md)），保留上游的 `version`/`exports`/`type`；声明元数据指向 `lib/types`；发布 `.d.ts` 与 `.d.ts.map` 声明输出；在 `peerDependencies` 中列出其 Cordis 依赖（与上游 manifest（元数据清单）一致）。传递性上游依赖本身也必须被 vendor 或已存在于仓库中——vendor 一个包往往意味着 vendor 其整条依赖树（如 `@cordisjs/plugin-http` 会拉入 `@cordisjs/fetch-file`）。
+`package.json` 的不变式：改写 `name` 的 scope（[映射](../rescope.zh.md)），保留上游的 `exports`/`type`；声明元数据指向 `lib/types`；发布 `.d.ts` 与 `.d.ts.map` 声明输出；在 `peerDependencies` 中列出其 Cordis 依赖（与上游 manifest（元数据清单）一致）。vendored 包是可发布的 release member，因此不得设置 `private: true`，且必须设置 `publishConfig.access: public`；`version` 字段跟随 harness 发布序列（见 [vendor/README.md](../../vendor/README.md)）。传递性上游依赖本身也必须被 vendor 或已存在于仓库中——vendor 一个包往往意味着 vendor 其整条依赖树（如 `@cordisjs/plugin-http` 会拉入 `@cordisjs/fetch-file`）。
 
 vendored TypeScript 源码中的本地相对导入/导出在复制后使用显式 `.ts` 后缀。这是仓库本地构建与上游的差异：`rewriteRelativeImportExtensions` 输出 `.js` 运行时导入，而声明文件保留显式 `.ts` 后缀，使 NodeNext/Node16 的 TypeScript 消费方能够解析。
 

package/kb/extra/deepseek-llm-api-wire-extensions.md

@@ -0,0 +1,163 @@
+# Official DeepSeek LLM API wire extensions
+
+English | [中文](deepseek-llm-api-wire-extensions.zh.md)
+
+This reference defines every DeepSeek Harness-specific HTTP header and additive JSON field sent by [`@deepseek-ai/dsh-llm-deepseek`](../packages/llm/llm-deepseek/README.md) on `deepseek-official` chat-completion requests. It does not redefine fields owned by the upstream DeepSeek API. The provider-neutral LLM interface and `llm-pi-ai` do not implement these additions.
+
+The adapter sends the additions to its resolved `baseURL`, including a configured gateway. They remain outside `messages`, system prompts, and tool schemas, so they do not add model-input tokens or alter the model-visible prefix.
+
+## Wire namespaces and versioning
+
+| Location | Naming | Examples |
+|---|---|---|
+| HTTP field names | Lowercase kebab-case; HTTP matching remains case-insensitive | `user-agent`, `x-deepseek-harness-session-id` |
+| DeepSeek request-body extension fields | Snake case with the reserved `dsh_` prefix | `dsh_plugin_packages`, `dsh_session_log` |
+| DSH-owned nested JSON members | Camel case | `afterSeq`, `throughSeq`, `sessionId` |
+| Tagged values | Kebab-case strings; durable events use `domain/action` | `session-log-deepseek/delivery-accepted` |
+
+Each body extension owns its `version` independently. A version applies only to the object that contains it; no compatibility or ordering relationship exists between versions of different fields. JSON member order is not part of the protocol.
+
+The [`DeepSeekLlmApiExtensionRegistry`](../packages/llm/deepseek-llm-api-extensions/README.md) reserves one provider per top-level extension name. Empty or whitespace-padded names, duplicate registrations, and collisions with the base DeepSeek request fail before HTTP dispatch.
+
+## Request headers
+
+| Header | Presence | Value |
+|---|---|---|
+| `user-agent` | Every provider HTTP request, including Files API operations | Application identity in `product/version (+url)` form; the default product is `deepseek-harness` |
+| `x-deepseek-harness-user-id` | Every authorized chat-completion request | The stable anonymous UUID for the resolved Harness home |
+| `x-deepseek-harness-session-id` | Chat-completion requests carrying a Session id | The exact request `sessionId` string |
+| `x-deepseek-harness-compact` | Chat-completion requests whose purpose is `compaction` | The literal string `1` |
+
+Credential failure happens before anonymous-user-id resolution, so an unauthorized request neither sends these headers nor creates the identity file. A direct request without a Session omits `x-deepseek-harness-session-id`. Session-title requests have no additional purpose header; the ordinary Session-id rule still applies when one carries a `sessionId`.
+
+## Body-extension transaction
+
+The adapter serializes the complete base body, including the exact `messages`, before it asks registered providers to prepare fields. A provider receives that immutable body, the request cancellation signal, and optional `sessionId` and auxiliary-call `purpose`. Returning `undefined` omits that provider's field for the request.
+
+Prepared JSON values are detached from provider-owned state, merged as top-level siblings of the base fields, and serialized in the same HTTP body. Preparation or collision failure prevents the request. A composition without the registry sends the unextended base body.
+
+After the configured endpoint returns HTTP 2xx, the adapter runs the prepared `accept()` transaction before reading the SSE response body. Transport failures and non-2xx responses do not accept any contribution. An acceptance failure fails the model request even though the endpoint returned 2xx. Acceptance records endpoint-level HTTP success; it does not assert that an SSE stream completed or that the endpoint persisted an extension.
+
+## `dsh_plugin_packages`
+
+[`@deepseek-ai/dsh-plugin-package-inventory-deepseek`](../packages/llm/plugin-package-inventory-deepseek/README.md) contributes the complete active Loader-backed plugin package inventory. The field is enabled by default.
+
+```json
+{
+  "dsh_plugin_packages": {
+    "version": 1,
+    "packages": [
+      {
+        "name": "@deepseek-ai/dsh-example",
+        "version": "0.1.1-rc.2"
+      }
+    ]
+  }
+}
+```
+
+| Member | Type | Meaning |
+|---|---|---|
+| `version` | `1` | Schema version for `dsh_plugin_packages` |
+| `packages` | array | Complete active set for this request |
+| `packages[].name` | string | Exact non-empty npm package name from the owning manifest |
+| `packages[].version` | string | Exact non-empty package version from the same manifest |
+
+Every request re-reads active non-group Loader entries from the host tree and, when available for the request Session, its standing agent-preset tree. Relative and absolute modules use their nearest owning manifest; bare package entries follow the Loader resolution base that activated them. A named manifest without a non-empty version fails request preparation.
+
+The sender deduplicates exact `(name, version)` pairs and sorts first by `name`, then by `version`, with a locale-independent text comparison. Simultaneously active versions of one package remain separate entries. Receivers must not collapse the array by package name or infer package activation from array order.
+
+Disabled, pending, failed, unloading, disposed, and structural Loader entries are absent. Ordinary dependencies, loose modules without a named owning package, programmatically mounted child fibers, and in-memory dynamic plugins are also absent because they have no authoritative Loader package provenance.
+
+An enabled inventory with no qualifying entries sends `packages: []`; disabling the contributor omits the entire `dsh_plugin_packages` field. Package identities are provider metadata and never enter model input.
+
+## `dsh_session_log`
+
+[`@deepseek-ai/dsh-session-log-deepseek`](../packages/session/session-log-deepseek/README.md) contributes one contiguous suffix of the canonical Session log. The field is disabled by default. When enabled, it applies to a request with a live Session and at least one event; a direct request, a stale Session id, or an empty log omits the field.
+
+```json
+{
+  "dsh_session_log": {
+    "version": 2,
+    "sessionFormatVersion": 2,
+    "session": {
+      "version": 2,
+      "id": "session-id",
+      "createdAt": 1780000000000,
+      "isSeeded": false
+    },
+    "afterSeq": -1,
+    "throughSeq": 0,
+    "events": [
+      {
+        "type": "turn/start",
+        "seq": 0,
+        "time": 1780000000001,
+        "data": {
+          "turn": 1
+        }
+      }
+    ]
+  }
+}
+```
+
+| Member | Type | Meaning |
+|---|---|---|
+| `version` | `2` | Schema version for `dsh_session_log` |
+| `sessionFormatVersion` | non-negative integer | Session format generation represented by this suffix |
+| `session` | object | Immutable wire projection of the current Session header |
+| `afterSeq` | integer | Greatest sequence recorded as accepted before this request, or `-1` |
+| `throughSeq` | non-negative integer | Greatest sequence represented by this request |
+| `events` | array | Contiguous events from `afterSeq + 1` through `throughSeq` |
+
+The first upload uses `afterSeq: -1` and carries the complete current log. Each later upload starts after the greatest accepted watermark for the same Session id. The sender snapshots the event array once per request; appends after that snapshot belong to a later request.
+
+### Wire Session header
+
+The `session` member projects `Session.header`, not a complete runtime Session or the header object itself. It copies the current header facts, including the required `isSeeded` lineage bit; the exact `Session.inheritedEventCount` is not part of this request field. The outer `dsh_session_log.version` selects this extension schema, while `session.version` selects the logical Session format. Changing the Session header projection requires an extension-schema bump even when the embedded logical format also changes.
+
+| Member | Presence | Meaning |
+|---|---|---|
+| `version` | required | Logical Session format version; currently `2` |
+| `id` | required | Exact Session id |
+| `createdAt` | required | Non-negative safe-integer Unix epoch milliseconds |
+| `cwd` | optional | Absolute working directory recorded at Session creation |
+| `parentSession` | optional | Parent Session id for a fork |
+| `isSeeded` | required | Whether the Session contains a fork-inherited event prefix |
+| `origin` | optional | Literal `subagent` for a subagent child |
+| `delegationDepth` | optional | Non-negative persisted subagent delegation depth |
+| `agentPreset` | optional | Agent preset id used to compose this Session |
+
+### Canonical event envelopes
+
+Each `events` item is a complete canonical `SessionEvent`, independent of every other request field. An event always carries `type`, `seq`, `time`, and `data`; it may carry `ignorable: true`, and surface events may additionally carry `sourceEventSeqs` and `surfaceOp`. The sender copies every present member without projection, redaction, or reconstruction.
+
+### Acceptance watermark and at-least-once delivery
+
+After the endpoint returns HTTP 2xx, the contribution appends this canonical event to the same Session:
+
+```json
+{
+  "type": "session-log-deepseek/delivery-accepted",
+  "seq": 8,
+  "time": 1780000000002,
+  "data": {
+    "sessionId": "session-id",
+    "sessionFormatVersion": 2,
+    "throughSeq": 7
+  }
+}
+```
+
+`delivery-accepted` means that the configured endpoint returned HTTP 2xx for the containing LLM request. It does not assert SSE completion or remote persistence. The event's `throughSeq` must identify an earlier event, its `sessionId` identifies the Session whose suffix was sent, and `sessionFormatVersion` binds the watermark to that exact logical generation. Absence means historical format v0.
+
+The sender folds the greatest matching `throughSeq` for the current Session id and format generation, so concurrent accepted requests cannot move the cursor backward and a watermark from another generation cannot authorize the current suffix. A resumed process rebuilds the cursor from the durable log. A fork ignores inherited watermarks that name another Session, and therefore sends its own complete inherited prefix before advancing under the child id. The watermark event itself belongs to the next unsent suffix.
+
+Transport and non-2xx failures append no watermark. A crash after endpoint acceptance but before local persistence may resend an already accepted range; uncertainty produces duplicates, never a sequence gap. There is no independent upload store, size cap, or truncation path.
+
+## Exposure and receiver requirements
+
+The request headers expose the Harness application version, one anonymous Harness-home identity, and an optional Session identity. `dsh_plugin_packages` exposes active npm package names and versions. When enabled, `dsh_session_log` may expose the Session working directory, system-prompt snapshots, user and Assistant content, embedded Assistant streams, failed-attempt output, tool arguments and results, compaction summaries, feedback, and plugin-owned events. Adapter API keys are not Session events and therefore do not enter the field. A gateway selected through `baseURL` receives the same values as the official endpoint.
+
+Receivers address extension fields by name, dispatch each field by its own `version`, preserve distinct package versions, and ignore JSON member ordering. A session-log receiver validates the contiguous sequence range before interpreting event types. An unrecognized canonical event without `ignorable: true` prevents lossless reconstruction. The base request remains usable without either the registry or a particular contribution; field absence means that contribution did not apply to that request.

package/kb/extra/deepseek-llm-api-wire-extensions.zh.md

@@ -0,0 +1,163 @@
+# DeepSeek 官方 LLM API 协议扩展
+
+[English](deepseek-llm-api-wire-extensions.md) | 中文
+
+本参考文档定义 [`@deepseek-ai/dsh-llm-deepseek`](../packages/llm/llm-deepseek/README.zh.md) 在 `deepseek-official` 聊天补全请求中发送的全部 DeepSeek Harness 特有 HTTP 标头和附加 JSON 字段。本文不重复定义 DeepSeek 上游 API 持有的字段。提供方无关的 LLM（大语言模型）接口与 `llm-pi-ai` 均不实现这些扩展。
+
+适配器将这些扩展发送至已解析的 `baseURL`，包括已配置的网关。扩展位于 `messages`、系统提示词和工具 schema 之外，因此不会增加模型输入 token，也不会改变模型可见前缀。
+
+## 协议命名空间与版本
+
+| 位置 | 命名方式 | 示例 |
+|---|---|---|
+| HTTP 字段名 | 小写 kebab-case；HTTP 匹配仍不区分大小写 | `user-agent`, `x-deepseek-harness-session-id` |
+| DeepSeek 请求正文扩展字段 | 使用保留 `dsh_` 前缀的 snake case | `dsh_plugin_packages`, `dsh_session_log` |
+| DSH 持有的嵌套 JSON 成员 | Camel case | `afterSeq`, `throughSeq`, `sessionId` |
+| 带标签的值 | 使用 kebab-case 字符串；持久事件采用 `domain/action` | `session-log-deepseek/delivery-accepted` |
+
+每个正文扩展独立持有自身的 `version`。版本仅适用于包含该字段的对象；不同字段的版本之间不存在兼容或排序关系。JSON 成员顺序不属于协议。
+
+[`DeepSeekLlmApiExtensionRegistry`](../packages/llm/deepseek-llm-api-extensions/README.zh.md) 为每个顶层扩展名保留一个提供方。空名称、两端带空白的名称、重复注册以及与 DeepSeek 基础请求冲突的名称都会在 HTTP 分派前失败。
+
+## 请求标头
+
+| 标头 | 出现条件 | 值 |
+|---|---|---|
+| `user-agent` | 每个提供方 HTTP 请求，包括 Files API 操作 | 采用 `product/version (+url)` 形式的应用身份；默认产品为 `deepseek-harness` |
+| `x-deepseek-harness-user-id` | 每个已授权的聊天补全请求 | 已解析 Harness home 的稳定匿名 UUID |
+| `x-deepseek-harness-session-id` | 携带会话 id 的聊天补全请求 | 确切的请求 `sessionId` 字符串 |
+| `x-deepseek-harness-compact` | 用途为 `compaction` 的聊天补全请求 | 字面字符串 `1` |
+
+凭据失败发生在解析匿名用户 id 之前，因此未授权请求既不会发送这些标头，也不会创建身份文件。没有会话的直接请求会省略 `x-deepseek-harness-session-id`。会话标题请求没有额外的用途标头；请求携带 `sessionId` 时，仍然适用普通的会话 id 规则。
+
+## 正文扩展事务
+
+适配器先序列化包括确切 `messages` 在内的完整基础正文，再让已注册提供方准备字段。提供方会收到该不可变正文、请求取消信号，以及可选的 `sessionId` 和辅助调用 `purpose`。提供方返回 `undefined` 时，本次请求会省略其字段。
+
+系统将已准备的 JSON 值与提供方持有的状态分离，再将其作为基础字段的顶层同级成员合并，并序列化到同一个 HTTP 正文中。准备失败或冲突会阻止请求。组合未挂载注册表时，适配器发送未经扩展的基础正文。
+
+已配置端点返回 HTTP 2xx 后，适配器会在读取 SSE 正文之前运行已准备的 `accept()` 事务。传输失败和非 2xx 响应不会接受任何贡献。即使端点返回 2xx，接受失败仍会使模型请求失败。接受仅记录端点级 HTTP 成功，不表示 SSE 流已完整结束，也不表示端点已持久化扩展。
+
+## `dsh_plugin_packages`
+
+[`@deepseek-ai/dsh-plugin-package-inventory-deepseek`](../packages/llm/plugin-package-inventory-deepseek/README.zh.md) 贡献完整存活的 Loader-backed 插件包清单。该字段默认启用。
+
+```json
+{
+  "dsh_plugin_packages": {
+    "version": 1,
+    "packages": [
+      {
+        "name": "@deepseek-ai/dsh-example",
+        "version": "0.1.1-rc.2"
+      }
+    ]
+  }
+}
+```
+
+| 成员 | 类型 | 含义 |
+|---|---|---|
+| `version` | `1` | `dsh_plugin_packages` 的 schema 版本 |
+| `packages` | 数组 | 本次请求的完整存活集合 |
+| `packages[].name` | 字符串 | 来自所属 manifest（元数据清单）的确切非空 npm 包名 |
+| `packages[].version` | 字符串 | 来自同一 manifest 的确切非空包版本 |
+
+每个请求都会重新读取宿主树中的存活非分组 Loader 配置项；请求会话存在 standing agent-preset 树时，也会读取该树。相对与绝对模块使用距离自身最近的所属 manifest；裸包配置项使用激活自身的 Loader 解析基准。具名 manifest 未提供非空版本时，请求准备会失败。
+
+发送方会对确切 `(name, version)` 组合去重，并使用与 locale 无关的文本比较，先按 `name`、再按 `version` 排序。同一包的多个同时存活版本会保留为独立配置项。接收方不得按包名折叠该数组，也不得根据数组顺序推断包的激活关系。
+
+该清单不包含已禁用、pending、failed、unloading、disposed 和结构性 Loader 配置项。普通依赖、没有具名所属包的松散模块、以编程方式挂载的子 fiber，以及内存动态插件也不在其中，因为它们没有权威的 Loader 包来源信息。
+
+清单已启用但没有符合条件的配置项时，系统发送 `packages: []`；禁用贡献插件时，系统省略整个 `dsh_plugin_packages` 字段。包身份属于提供方元数据，绝不进入模型输入。
+
+## `dsh_session_log`
+
+[`@deepseek-ai/dsh-session-log-deepseek`](../packages/session/session-log-deepseek/README.zh.md) 贡献权威会话日志的一段连续后缀。该字段默认禁用。启用后，它适用于携带存活会话且至少存在一个事件的请求；直接请求、陈旧会话 id 或空日志会省略该字段。
+
+```json
+{
+  "dsh_session_log": {
+    "version": 2,
+    "sessionFormatVersion": 2,
+    "session": {
+      "version": 2,
+      "id": "session-id",
+      "createdAt": 1780000000000,
+      "isSeeded": false
+    },
+    "afterSeq": -1,
+    "throughSeq": 0,
+    "events": [
+      {
+        "type": "turn/start",
+        "seq": 0,
+        "time": 1780000000001,
+        "data": {
+          "turn": 1
+        }
+      }
+    ]
+  }
+}
+```
+
+| 成员 | 类型 | 含义 |
+|---|---|---|
+| `version` | `2` | `dsh_session_log` 的 schema 版本 |
+| `sessionFormatVersion` | 非负整数 | 该后缀所表示的 Session 格式 generation |
+| `session` | 对象 | 当前 Session header 的不可变协议投影 |
+| `afterSeq` | 整数 | 本次请求前记录为已接受的最大序号，或 `-1` |
+| `throughSeq` | 非负整数 | 本次请求所表示的最大序号 |
+| `events` | 数组 | 从 `afterSeq + 1` 到 `throughSeq` 的连续事件 |
+
+首次上传使用 `afterSeq: -1`，并携带当前的完整日志。此后每次上传都从同一会话 id 的最大已接受水位（watermark）之后开始。发送方为每次请求仅快照一次事件数组；快照后的追加内容属于后续请求。
+
+### Session 协议 header
+
+`session` 成员投影 `Session.header`，既不是完整的运行时 Session，也不是 header 对象本身。它复制当前 header 事实，包括必需的 `isSeeded` 谱系位；精确的 `Session.inheritedEventCount` 不属于该请求字段。外层 `dsh_session_log.version` 选择本扩展 schema，`session.version` 则选择逻辑 Session 格式。即使嵌入的逻辑格式同时变化，只要 Session header 投影变化，扩展 schema 也必须升版。
+
+| 成员 | 出现条件 | 含义 |
+|---|---|---|
+| `version` | 必需 | 逻辑 Session 格式版本；当前为 `2` |
+| `id` | 必需 | 确切的会话 id |
+| `createdAt` | 必需 | 非负安全整数 Unix epoch 毫秒数 |
+| `cwd` | 可选 | 创建会话时记录的绝对工作目录 |
+| `parentSession` | 可选 | fork 的父会话 id |
+| `isSeeded` | 必需 | Session 是否包含 fork 继承的事件前缀 |
+| `origin` | 可选 | subagent 子项使用的字面值 `subagent` |
+| `delegationDepth` | 可选 | 持久化的非负 subagent 委派深度 |
+| `agentPreset` | 可选 | 用于组合该会话的 agent preset id |
+
+### 权威事件信封
+
+每个 `events` 元素都是完整的权威 `SessionEvent`，不依赖任何其他请求字段。事件始终携带 `type`、`seq`、`time` 与 `data`；它可以携带 `ignorable: true`，展示事件还可携带 `sourceEventSeqs` 与 `surfaceOp`。发送方会复制每个已有成员，不执行投影、脱敏或重建。
+
+### 接受水位与至少一次交付
+
+端点返回 HTTP 2xx 后，该贡献会向同一会话追加以下权威事件：
+
+```json
+{
+  "type": "session-log-deepseek/delivery-accepted",
+  "seq": 8,
+  "time": 1780000000002,
+  "data": {
+    "sessionId": "session-id",
+    "sessionFormatVersion": 2,
+    "throughSeq": 7
+  }
+}
+```
+
+`delivery-accepted` 表示已配置端点为包含该字段的 LLM 请求返回 HTTP 2xx。它不表示 SSE 已完整结束，也不表示远端已经持久化。该事件的 `throughSeq` 必须标识一项更早的事件，`sessionId` 标识已发送后缀所属的 Session，`sessionFormatVersion` 则把水位绑定到该逻辑 generation。缺少该字段表示历史格式 v0。
+
+发送方只会为当前 Session id 与格式 generation 折叠最大的匹配 `throughSeq`，因此并发已接受请求无法使游标倒退，其他 generation 的水位也不能授权当前后缀。恢复后的进程会从持久日志重建游标。fork 会忽略命名其他 Session 的继承水位，因此先发送自身完整的继承前缀，再以子会话 id 推进。水位事件自身属于下一段未发送后缀。
+
+传输失败和非 2xx 响应不会追加水位。端点接受后、本地持久化前发生崩溃时，系统可能重新发送已接受范围；不确定性只会产生重复，绝不会产生序号缺口。系统没有独立上传存储、大小上限或截断路径。
+
+## 暴露内容与接收方要求
+
+请求标头会暴露 Harness 应用版本、一个匿名 Harness-home 身份和可选的会话身份。`dsh_plugin_packages` 会暴露存活 npm 包的名称与版本。启用后，`dsh_session_log` 可能暴露会话工作目录、系统提示词快照、用户与 Assistant 内容、嵌入式 Assistant stream、失败 attempt 输出、工具参数与结果、压缩摘要、反馈和插件持有的事件。适配器 API key 不是会话事件，因此不会进入该字段。通过 `baseURL` 选择的网关会收到与官方端点相同的值。
+
+接收方按名称定位扩展字段，按各字段自己的 `version` 分派，保留不同的包版本，并忽略 JSON 成员顺序。会话日志接收方必须先校验连续序号范围，再解释事件类型。遇到不带 `ignorable: true` 的未知权威事件时，接收方无法进行无损重建。即使缺少注册表或某项贡献，基础请求仍然可用；字段缺失表示该项贡献不适用于本次请求。

package/kb/extra/development.md

@@ -43,11 +43,11 @@ Setup is complete when `pnpm run typecheck` exits successfully.
 
 ### TypeScript project layout
 
-The repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.
+The repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`; three packages (`host/webserver`, `compaction/compaction`, `typert/registry`) are referenced by both aggregates as shared leaves so each side type-checks the same source.
 
 | File | Role | Forms a program? |
 |---|---|---|
-| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |
+| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `scripts/`. | No |
 | `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |
 | `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |
 | `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |
@@ -57,9 +57,9 @@ Host and Client stay two aggregate programs because both sides declaration-merge
 
 - `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.
 - A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.
-- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.
+- A new package is registered in exactly one aggregate; only the split packages above carry both leaf configs, and the shared leaves are registered in both aggregates because each side must type-check the same source. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.
 
-`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host Typert graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf; it discovers split packages from the presence of both leaf configs, so a new split joins the gate automatically. Do not copy this structure to other packages; the [`api-remotes` README](../packages/api/remotes/README.md) explains the Host/Client split and build order.
+Six packages split Host and Client tsconfigs: `api/remotes`, `api/gateway`, `api/session-controller`, `api/workspace-controller`, `client/connection`, and `session-query/session-log-export`. `api/remotes`' Host entry participates in the Host Typert graph while its Client entry imports generated `/remote` declarations; `session-log-export` keeps Node archive production out of its browser controller. Each split package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf; it discovers split packages from the presence of both leaf configs, so a new split joins the gate automatically. The [`api-remotes` README](../packages/api/remotes/README.md) and [`session-log-export` README](../packages/session-query/session-log-export/README.md) explain their splits.
 
 The root build follows the generated dependency order:
 
@@ -75,7 +75,7 @@ Both tsdown passes use the same complete workspace match. They neither scan buil
 
 Typert runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start Typert. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.
 
-`pnpm run build` embeds the caller's exact `DSH_CLIENT_*` environment and uses no public client values when none are set. `pnpm run build:official` is the cross-platform local equivalent of the CI and release artifact build. Each successful complete build writes a gitignored record that binds those values to the Vite output and dynamic client bundles; release packing and built Web tests reject a missing record or artifacts changed by a later partial build.
+`pnpm run build` embeds the root package version, the seven-character source commit, and a dirty marker when Git reports local changes; it also inherits other caller-supplied `DSH_CLIENT_*` values. `pnpm run build:official` is the cross-platform local equivalent of the CI and release artifact build and omits the local dirty marker. Each successful complete build writes a gitignored record that binds the exact public values to the Vite output and dynamic client bundles; release packing and built Web tests reject a missing record or artifacts changed by a later partial build. `pnpm run dev:web` still requires the artifact tree from a prior complete build, but it samples the current version and Git state once at startup and shares that environment across every watcher stage for the session; it does not validate the complete-build record because the watcher stages rewrite its recorded artifacts.
 
 Static analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already depends on the Typert contract-generation pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate setup, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [Typert Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.
 
@@ -126,7 +126,7 @@ The keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates
 
 The root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.
 
-### Demos
+### Profile runs
 
 Run the repository build separately before using these source-checkout demos:
 
@@ -140,16 +140,10 @@ The one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment o
 pnpm dsh --profile headless "summarize this workspace"
 ```
 
-The self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):
+The PTC mode demo runs the same headless profile with code presentation enabled:
 
 ```sh
-pnpm run demo:cordis
-```
-
-The ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:
-
-```sh
-pnpm run demo:acp
+pnpm run demo:ptc -- "summarize this workspace"
 ```
 
 ### TODO markers