dsh-plugin-guide 0.3.42 → 0.4.0

package/references/official-docs/docs/subsystems/slots.zh.md

@@ -1,204 +0,0 @@
-# Web Client Slots
-
-[English](slots.md) | 中文
-
-Slots 是 Web Client 的类型化 React 组合系统。[`dsh-client-ui-slots`](../../packages/client/ui-slots/README.zh.md)定义不依赖 React 的注册表与类型代数；[`dsh-client-ui-renderer`](../../packages/client/ui-renderer/README.zh.md)把可观测源绑定成钩子、渲染整棵树，并在内部拥有 React context。功能插件通过 `ctx.slots.register()` 贡献 UI，绝不导入其他功能插件的组件。
-
-本文记录 slot 的所有权、组件输入、扩展 API 与当前层级。外围的启动、Remote、Client model 与 Conversation 数据通路见 [Web Client 架构](web-client.zh.md)。
-
-`plugins.bundle.config` 以 npm 包名为 key，提供 Bundle 详情配置。`plugins.bundle.activation` 在用户显式启用后渲染可选引导，由拥有者提供关闭引导和打开该 Bundle 详情的回调。`conversation.input.activity` 提供模型选择器与发送按钮之间的单个活动控件，可展开工具栏并在卸载时释放展开状态。
-
-插件目录声明 `plugins.add.actions`，它是 root 作用域的 list，在添加插件菜单的安装项之后提供 `MenuItemButton` 行。owner 提供 `onDismiss()`，用于开始动作前关闭菜单。该 slot 遵循所属插件页面声明的生命周期。
-
-## 声明与生命周期
-
-`SlotMap` 是编译期注册表。包通过声明合并写入 key、cardinality（基数）、scope、owner props、keyed props 与可选的 slot 级 inject face。运行时声明则是拥有该渲染位置的组件在 `children` 中给出的对应条目。
-
-声明一个 child 会同时产生三种效果：令该 child key 生效、授权 parent entry 调用 `renderSlot` 或 `renderSlotChain`，以及记录运行时 dispatch 规格。每个声明只能有一个存活 owner。向未声明 slot 注册，或重复声明其他 entry 已拥有的 child，都会在插件激活时失败。
-
-`root` 是唯一内建声明，也是唯一由 Cordis service 自身渲染的 key。`ui-renderer` 调用 `ctx.slots.renderSlot('root', {})`；其余每个后代都通过声明它的 entry 所收到的 `renderSlot` 或 `renderSlotChain` prop 渲染。
-
-注册和声明遵循 Cordis effect 生命周期。销毁一个 entry 会移除其贡献，并递归折叠它声明的 child slots。因此，向其他包的 slot 贡献功能时使用 `ctx.slots.inject(key, callback)`：callback 会在每段声明生命周期内运行，owner 折叠时其 effect 随之移除，owner 再次挂载时则重新运行。
-
-```tsx ignore-check
-import type { Context } from '@deepseek-ai/cordis'
-import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
-import type {} from '@deepseek-ai/dsh-client-ui-session/client'
-import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
-
-type HeaderActionProps = PropsRuntime<'conversation.session.header.actions'>
-
-function HeaderAction({ useSession }: HeaderActionProps) {
-  const running = useSession(snapshot => snapshot.running)
-  return <button disabled={running}>Review</button>
-}
-
-export const inject = ['slots']
-
-export function apply(ctx: Context): void {
-  ctx.slots.inject('conversation.session.header.actions', () =>
-    ctx.slots.register({
-      name: 'conversation.session.header.actions',
-      id: 'review',
-      order: 100,
-    }, HeaderAction))
-}
-```
-
-## Cardinality 与 scope
-
-Slot 声明固定两个相互独立的维度。
-
-| 维度 | 值 | 含义 |
-|---|---|---|
-| cardinality | `single` | 单个 cell，渲染当前 priority 胜者；需要并列内容时应声明 child slot，而不是把它当作列表。 |
-| cardinality | `list` | cell 由必填 `id` 定址，先按 `order`、再按注册顺序排列。 |
-| cardinality | `keyed` | owner 传入 `entryKey`；匹配 cell 以该 key 对应的 props 渲染。 |
-| cardinality | `chain` | 每个 entry 提供纯 `select(owner)` 函数；按 priority 顺序遇到的第一个非 null 结果获选，并以 `matched` 传给组件；全部拒绝时渲染 owner fallback。 |
-| scope | `root` | 一个 root 作用域组件和 store 实例。 |
-| scope | `session-maybe` | 继承外围 Provider binding，但没有 binding 时仍可渲染；Session 值是可选的。 |
-| scope | `session` | 要求可解析的外围 Provider binding，并收到确定存在的 Session 值。 |
-
-对于 `single`、`list` 和 `keyed` cell，`priority` 是遮蔽优先级；对于 `chain`，它是选举顺序。数值越小越先运行或渲染。普通增量贡献应选用新的 list `id` 或 keyed `key`；复用已有 cell 表示有意替换其展示。
-
-<a id="component-inputs"></a>
-
-## 组件输入
-
-注册组件会在 binding 位置收到组装后的输入。组件应从这些类型推导 props，不要重新抄写成员。
-
-| 输入 | 声明者 | 组件类型 |
-|---|---|---|
-| owner 值与标准 scope 值 | `SlotMap` 条目与已安装的 scope adapter | `PropsRuntime<K>` |
-| 获授权的 child renderer | 注册项的 `children` keys | `PropsRenderSlots<S>` |
-| 共享视图状态的 selector hook 与 mutation callback | 注册项的 `store` | `PropsStore<H>` |
-| 私有数据、callback 与 observable hook | 注册项的 `inject` factory | `InjectFace<I>` |
-| 本地化 `t` 函数 | 注册项的 `locale` namespace | `PropsLocale<N>` |
-| chain 选中的值 | 注册项的 `select` 结果 | 通过 `ComposedProps` 提供的 `matched` |
-
-当 entry 声明 `session` 或 `session-maybe` child 时，`PropsRenderSlots` 还会提供 `SessionProvider`。不传 `session` prop 时，它继承外围 binding；显式传入 `SessionReference` 或 `undefined` 时，只覆盖该子树。Provider 不为整个 body 设置 key。严格 `session` entry 在 binding generation 改变时重新挂载。空白 `session-maybe` entry 接受首个 binding 时不重新挂载，后续 generation 变化或回到缺失状态时才重新挂载。
-
-组件绝不会收到 `ctx`。父组件在某次渲染时已经知道的值通过 `renderSlot` 的 owner 参数进入；共享视图状态使用声明的 store；service 与 model object 留在 `apply` closure 中，只向组件投影 callback 或 observable source。
-
-## 框架提供的 hooks
-
-当前组合中的 adapter 会添加以下标准 props。它们按目标 slot 的 scope 提供，与注册组件来自哪个包无关。
-
-| 可用范围 | Props | Owner |
-|---|---|---|
-| 所有 scope | `useSessions`、`useSessionStatus`、`useSessionRetainInfo`、`useSessionAccess` | `ui-session` |
-| 所有 scope | `useWorkspaces`、`useWorkspaceAccess` | `ui-workspace` |
-| 所有 scope | `useRemoteAccess`（`global` 资源） | `api-remote-access` |
-| 所有作用域 | `usePanelInfo` | `ui-layout` |
-| `session` | `sessionId`、`useSession`、`useProjection`、`useAccess`（所绑定 Session 的答案） | `ui-session` |
-| `session-maybe` | 结果可选的 `sessionId`、`useSession`、`useProjection`、`useAccess` | `ui-session` |
-| `session` | `useConversation`、`useInput`、`inputActions` | `ui-conversation` |
-| `session-maybe` | 结果可选的 `useConversation`、`useInput`、`inputActions` | `ui-conversation` |
-| `session` | `useChat` | `ui-chat` |
-| `session` | `useTrajectory` | `ui-trajectory` |
-
-Renderer 还会根据声明的 store 创建 `useStore`，并根据声明的 locale namespace 创建 `t`。这些是由注册项推导的 props，不属于全局标准 props。
-
-框架与领域 adapter owner 可以通过 `ctx.slots.provideRoot()` 或 `ctx.uiSession.provide()` 扩展标准集合，同时提供对应的 `GlobalStandardProps`、`SessionStandardProps` 或 `SessionMaybeStandardProps` 声明合并。普通功能组件不应自行创建 React hook prop，也不应为 entry 私有数据添加全局标准 prop。
-
-## 开发者提供的 injection
-
-注册项的 `inject` 选项是通常使用的功能私有注入点。它的 factory 在插件的 `apply` 世界中运行，可以闭包捕获已经注入的 Cordis service，并且只返回组件所需的数据与 callback。对于 `session` slot，它会收到 `sessionId`；对于 `session-maybe`，它收到 `sessionId | undefined`；声明 store 后，它还会收到该 store 绑定后的 actions。
-
-返回值中保留的 `hooks` 对象接收裸 `getSnapshot`／`subscribe` source。Renderer 把 `hooks: { status }` 转换为组件 prop `useStatus(selector)`，并按 source identity 缓存绑定。组件不会收到 source 本身，也不直接调用 `useSyncExternalStore`。
-
-当每个 occupant 都需要同一种能力时，slot owner 可以在 child 声明里放置 `inject` face。普通成员会原样交给所有 occupant；其 `hooks` 对象中的函数成员是 hook factory，它会收到 slot 的标准 props 与可选的逐次渲染 `hookContext`，再返回提供给 occupant 的受限 hook。`conversation.chat.node` 正是通过这种机制，为当前渲染的 node 提供 `useTurnData(key)`。
-
-一次渲染时 owner 已知的值走 owner props；单个 entry 的 callback 与私有 observable 走注册项 `inject`；由 slot owner 控制、所有 occupant 共享的能力走 slot 级 `inject`；需要跨 entry 共享或跨重新挂载保留的可变视图状态走声明的 store。React node 通过 child slot 组合，不通过注入值传递。
-
-<a id="current-hierarchy"></a>
-
-## Conversation 层级
-
-下面的 Conversation 路径区分声明所有者与可复用 Factory 根，省略无关的外壳位置。条目拥有其声明的子 Slot；Factory 在其定义注册期间拥有子 Slot 声明。方括号标出默认 React 组件，普通 React 后代组件可以渲染其所有者的 Slot。Factory 调用指向独立的可复用定义，不是新的 Slot 声明。
-
-```text
-root [AppFrame]
-└─ main[key=conversation] [ConversationPanel]
-   └─ main.conversation [ConversationRoot / ConversationMainPanel]
-      ├─ conversation.header [ConversationHeader]
-      │  ├─ conversation.header.leading
-      │  └─ conversation.session.header [ConversationSessionHeader]
-      │     ├─ conversation.session.header.lineage
-      │     ├─ conversation.session.header.actions
-      │     ├─ conversation.session.header.utilities
-      │     └─ conversation.session.header.corner
-      └─ calls Factory: conversation.content
-
-Factory: conversation.content [ConversationContent]
-├─ conversation.session [ConversationSession / DefaultConversationViews]
-│  └─ conversation.view
-│     ├─ id=chat [ChatView]
-│     │  └─ conversation.chat.flow [ChatFlow]
-│     │     └─ conversation.chat.node [ChatNodeSeat dispatch]
-│     │        ├─ key=user,steering [UserMessageNodeView]
-│     │        │  └─ calls Factory: conversation.chat.user.content
-│     │        ├─ key=assistant-step [AssistantNodeView / AssistantMarkdown]
-│     │        │  ├─ conversation.chat.message.images [MessageImages]
-│     │        │  └─ conversation.chat.reasoning.body [DefaultReasoningBody]
-│     │        │     └─ calls Factory: conversation.chat.reasoning.content
-│     │        ├─ key=tool-call [ToolCallTree]
-│     │        │  └─ tool.call.toolview
-│     │        │     └─ key=read_image [ReadImageRow / ToolRow]
-│     │        │        └─ tool.call.images [MessageImages]
-│     │        ├─ key=command-input [GoalCommandInputView]
-│     │        │  └─ calls Factory: conversation.user.text
-│     │        ├─ key=command [CommandNodeView]
-│     │        │  └─ conversation.chat.commandview
-│     │        └─ key=turn-tail [TurnTailNodeView]
-│     │           ├─ conversation.chat.turnTail
-│     │           └─ conversation.chat.assistant-actions
-│     └─ id=trajectory [TrajectoryView / TrajectoryTable]
-│        └─ conversation.trajectory.images [MessageImages]
-├─ conversation.composer
-│  ├─ conversation.approval.detail
-│  └─ conversation.plan-review.actions
-├─ conversation.composer.bar [InputBar]
-│  ├─ conversation.input.attachments
-│  ├─ conversation.input.permission
-│  ├─ conversation.input.plan
-│  ├─ conversation.input.model
-│  │  └─ conversation.input.model.label
-│  ├─ conversation.input.overlay
-│  ├─ conversation.composer.dock
-│  ├─ conversation.input.left
-│  └─ conversation.input.right
-├─ conversation.input.dock
-│  └─ id=queue [QueueDock]
-│     └─ calls Factory: conversation.user.text
-├─ conversation.hero.brand.mark
-├─ conversation.hero.workspace
-│  └─ conversation.hero.workspace.directoryFlow
-├─ conversation.hero.agentPreset
-└─ conversation.hero.options
-
-Factory: conversation.chat.user.content [UserContent]
-├─ conversation.chat.user.images [MessageImages]
-└─ calls Factory: conversation.user.text
-
-Factory: conversation.user.text [UserText]
-└─ conversation.user.text.node [keyed, inline]
-
-Factory: conversation.images.content [MessageImagesContent / ImageGallery]
-Factory: conversation.chat.reasoning.content [ReasoningContent / MarkdownText]
-```
-
-四个图片 Slot 默认均填入 `MessageImages`，由它携带调用者的图片引用和授权 loader 调用 `conversation.images.content`。用户与输出图片的替换互不影响。`conversation.user.text` Factory 由用户内容、Queue 和 Goal 共用；其 `inline: true` keyed Slot 使用 span 锚点及行内错误占位，而不是块级包装。
-
-生成的 [Client inspect catalog](../../packages/extensions/cordis-client-runner/src/client/slot-catalog.ts) 是包含所有外壳分支及每个 key 的完整参考，包含 cardinality、scope、owner props、标准 props、当前 occupant、声明 owner 与替换风险。运行中的动态包可以用 `cordis_inspect what:"client"` 查询实时树与某个精确 key；源码 catalog 由 `pnpm run gen-client-catalog` 根据 `SlotMap` 声明和 `slots.register()` 调用点生成。
-
-<a id="extension-rules"></a>
-
-## 扩展规则
-
-- 另一个功能包只能通过 `import type` 引入声明；绝不导入或转发它的运行时值。
-- 只在拥有并渲染某个位置的组件中声明新的 child slot。其他包通过 `ctx.slots.inject()` 等待，再通过 `ctx.slots.register()` 贡献内容。
-- 业务与传输状态留在所属 Cordis service 或 Client model 中。Slot store 只承载共享的视图与交互状态。
-- 可观测 source 及其 snapshot identity 在值变化前保持稳定；值变化时通过同一个 source 发布。
-- UI domain 之间只传 JSON 兼容数据和 callback。`hooks` compartment 是裸 observable 的唯一例外；React 内容通过 slot 传递。
-- 将 `single` 和已有 occupant 的 keyed cell 视为替换点。增量扩展使用 list id 或尚未占用的 key。

package/references/official-docs/docs/subsystems/spill.i18n.yaml

@@ -1,16 +0,0 @@
-# Bilingual-pair consistency record for spill.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/subsystems/spill.md
-/spill-storage:
-  en: 5bbcc1a88d71014d
-  zh: cfd2caf22147ad04
-/spill-storage/the-save-request:
-  en: 05dd1d013c45ee55
-  zh: e2ba974827f47a54
-/spill-storage/the-result:
-  en: e806be024ff6281a
-  zh: d8b452b379d98d95
-/spill-storage/the-service:
-  en: d75a7c8d2c508cf4
-  zh: 3e60cb048a22a288

package/references/official-docs/docs/subsystems/spill.md

@@ -1,124 +0,0 @@
-# Spill Storage
-
-English | [中文](spill.zh.md)
-
-The spill storage [capability seam](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md) persists caller-provided text and returns a model-facing locator with retrieval guidance. Its Service Definition is [dsh-spill](../../packages/spill/spill) (`ctx.spillStore`), and its local Service Provider is [dsh-spill-local](../../packages/spill/spill-local). Consumers include the [tool-result policy](../../packages/spill/spill-policy) and [session references](../../packages/context/session-reference/README.md). Spill is optional, not part of the [agent-loop spine](core.md); consumers own preview and spill decisions, while storage saves the supplied text verbatim.
-
-Source: [`packages/spill/spill/src/types.ts`](../../packages/spill/spill/src/types.ts)
-
-## The save request
-
-`saveText` is the sole service operation: persist `content` verbatim, return an opaque locator, a backend-supplied retrieval hint, and the exact byte count. The request carries the save-time storage namespace (`owner`), descriptive producer details (`source`, never access control), and a `suggestedName` the backend may use as a naming hint, not a path. A tool source identifies the actual tool call; a session-reference source identifies the captured source session, while its owner is the target session receiving the context.
-
-```ts type-equiv
-/** One request to persist text to a spill artifact. */
-interface SaveTextSpill {
-  owner: SpillOwner
-  source: SpillSource
-  /**
-   * A caller-suggested base name (e.g. `web_fetch.txt`). The backend sanitizes
-   * it to a single safe path segment before use — it is a hint, never a path.
-   */
-  suggestedName: string
-  /** The full text to persist (UTF-8). */
-  content: string
-}
-```
-
-```ts type-equiv
-/**
- * Save-time storage namespace for a spilled artifact. The session id lets a
- * backend group storage under the producing session, but the returned
- * {@link SpillLocator} is the model-facing handle. Forked sessions inherit
- * locators already present in the seeded log; those artifacts are not copied or
- * re-owned, and spills produced after the fork use the child session id.
- */
-interface SpillOwner {
-  sessionId: SessionId
-}
-```
-
-A retention-period cleanup may expire old locators with other old session artifacts; the spill seam does not define a per-session cleanup policy.
-
-```ts type-equiv
-/**
- * Producer of a spilled artifact. Tool results carry their model-issued call id;
- * session references identify the captured source session instead. Descriptive
- * source description only, never access control.
- */
-type SpillSource = {
-  kind: 'tool'
-  /** The tool whose result was spilled (e.g. `web_fetch`). */
-  toolName: string
-  /** The model-issued call id the result belongs to. */
-  callId: ToolCallId
-  /** A short human label for the artifact (e.g. `result`). */
-  label: string
-} | {
-  kind: 'session-reference'
-  /** Session whose projected conversation was captured. */
-  sessionId: SessionId
-  /** Host-provided label for the referenced session. */
-  label: string
-}
-```
-
-## The result
-
-```ts type-equiv
-/** A saved spill artifact: its locator, byte length, and backend-specific retrieval guidance. */
-interface SpillRef {
-  locator: SpillLocator
-  bytes: number
-  retrievalHint: string
-}
-```
-
-`SpillLocator` is a [branded](core.md#branded-ids) model-facing handle returned by the backend. The local backend renders it as a filesystem path; a remote or database backend can render a URI, key, or command token. Consumers treat it as opaque and render it with `retrievalHint` instead of assuming `read` is always the right retrieval mechanism.
-
-```ts type-equiv
-/**
- * Opaque model-facing handle for one spilled artifact. A local backend may use a
- * filesystem path; a remote or database backend may use a URI or key. Consumers
- * render it with {@link SpillRef.retrievalHint}, but do not parse it.
- */
-type SpillLocator = Branded<'SpillLocator'>
-```
-
-## The service
-
-`SpillStore` (`ctx.spillStore`, defined in [`packages/spill/spill/src/index.ts`](../../packages/spill/spill/src/index.ts)) is a one-method abstract service: `saveText(input) → Promise<SpillRef>`. It persists the FULL `content` and REJECTS on a real storage failure (permissions, ENOSPC, backend unavailable). The seam owns storage only: no retention policy, no tool-result replacement, no retrieval/search API.
-
-The local backend ([dsh-spill-local](../../packages/spill/spill-local)) writes under `<root>/session-<hash>/<random>-<safeName>` — a configured or lazily-created private (0700) root, a `sha256(sessionId)` session subdir, and an exclusive owner-only (`open(path, 'wx', 0o600)`) write so a planted symlink cannot redirect it. Its `locator` is the local path and its `retrievalHint` tells the model to use `read` or `grep` on that path. The policy consumer ([dsh-spill-policy](../../packages/spill/spill-policy)) replaces an over-`maxInlineTokens` text/image result with ordered head/tail content and a spill address, best-effort: a save failure keeps the original inline result rather than turning a successful call into an `isError`.
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxspillstore--spillstore-abstract-seam"></a>
-
-### `ctx.spillStore` — `SpillStore` (abstract seam)
-
-Abstract spill storage service. Subclass, implement saveText, and load the subclass as a plugin — it registers as `ctx.spillStore` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
-
-Semantics every implementation must honor:
-
-- saveText persists the FULL `content` verbatim and returns an opaque locator, exact byte length, and model-facing retrieval guidance.
-- Storage is scoped by the request's SaveTextSpill.owner session; the backend chooses a private (not world-readable) location and a collision-free name derived from — never equal to — the caller's `suggestedName`.
-- `saveText` REJECTS on a real storage failure (permissions, ENOSPC, backend unavailable); the caller decides how to degrade (the spill policy treats a rejection as best-effort and keeps the inline result).
-
-```ts cordis-catalog
-/**
- * Persist `input.content` to a session-scoped spill artifact.
- * @param input - the owner, caller-supplied source fields, suggested name, and full text to save.
- * @returns the saved artifact's {@link SpillRef}; rejects on a storage failure.
- */
-abstract saveText(input: SaveTextSpill): Promise<SpillRef>
-```
-
-Source: [`packages/spill/spill/src/index.ts`](../../packages/spill/spill/src/index.ts)
-<!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/spill.zh.md

@@ -1,124 +0,0 @@
-# spill 存储
-
-[English](spill.md) | 中文
-
-spill 存储[能力 seam](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md)持久保存调用方提供的文本，并返回面向模型的定位符与检索指引。其 Service Definition 是 [dsh-spill](../../packages/spill/spill)（`ctx.spillStore`），本地 Service Provider 是 [dsh-spill-local](../../packages/spill/spill-local)。消费方包括[工具结果策略](../../packages/spill/spill-policy)与[会话引用](../../packages/context/session-reference/README.zh.md)。spill 是可选能力，不属于[智能体循环主干](core.zh.md)；预览与 spill 决策由消费方负责，存储则原样保存所提供的文本。
-
-源码：[`packages/spill/spill/src/types.ts`](../../packages/spill/spill/src/types.ts)
-
-## 保存请求
-
-`saveText` 是唯一的服务操作：原样持久保存 `content`，并返回不透明的定位符、后端提供的检索提示和精确字节数。请求携带保存时的存储命名空间（`owner`）、描述性的生产者来源信息（`source`，绝非访问控制）以及后端可用作命名提示而非路径的 `suggestedName`。工具来源标识实际工具调用；会话引用来源标识被捕获的源会话，而其归属是接收上下文的目标会话。
-
-```ts type-equiv
-/** One request to persist text to a spill artifact. */
-interface SaveTextSpill {
-  owner: SpillOwner
-  source: SpillSource
-  /**
-   * A caller-suggested base name (e.g. `web_fetch.txt`). The backend sanitizes
-   * it to a single safe path segment before use — it is a hint, never a path.
-   */
-  suggestedName: string
-  /** The full text to persist (UTF-8). */
-  content: string
-}
-```
-
-```ts type-equiv
-/**
- * Save-time storage namespace for a spilled artifact. The session id lets a
- * backend group storage under the producing session, but the returned
- * {@link SpillLocator} is the model-facing handle. Forked sessions inherit
- * locators already present in the seeded log; those artifacts are not copied or
- * re-owned, and spills produced after the fork use the child session id.
- */
-interface SpillOwner {
-  sessionId: SessionId
-}
-```
-
-保留期清理可以连同其他旧会话产物一起使旧定位符失效；spill seam 不定义逐会话的清理策略。
-
-```ts type-equiv
-/**
- * Producer of a spilled artifact. Tool results carry their model-issued call id;
- * session references identify the captured source session instead. Descriptive
- * source description only, never access control.
- */
-type SpillSource = {
-  kind: 'tool'
-  /** The tool whose result was spilled (e.g. `web_fetch`). */
-  toolName: string
-  /** The model-issued call id the result belongs to. */
-  callId: ToolCallId
-  /** A short human label for the artifact (e.g. `result`). */
-  label: string
-} | {
-  kind: 'session-reference'
-  /** Session whose projected conversation was captured. */
-  sessionId: SessionId
-  /** Host-provided label for the referenced session. */
-  label: string
-}
-```
-
-## 结果
-
-```ts type-equiv
-/** A saved spill artifact: its locator, byte length, and backend-specific retrieval guidance. */
-interface SpillRef {
-  locator: SpillLocator
-  bytes: number
-  retrievalHint: string
-}
-```
-
-`SpillLocator` 是后端返回的[品牌化](core.zh.md#branded-ids)面向模型句柄。本地后端将它渲染为文件系统路径；远程或数据库后端可以渲染 URI、键或命令 token。消费方将它视为不透明值，并使用 `retrievalHint` 渲染，而不是假定 `read` 始终是正确的检索机制。
-
-```ts type-equiv
-/**
- * Opaque model-facing handle for one spilled artifact. A local backend may use a
- * filesystem path; a remote or database backend may use a URI or key. Consumers
- * render it with {@link SpillRef.retrievalHint}, but do not parse it.
- */
-type SpillLocator = Branded<'SpillLocator'>
-```
-
-## 服务
-
-`SpillStore`（`ctx.spillStore`，定义于 [`packages/spill/spill/src/index.ts`](../../packages/spill/spill/src/index.ts)）是只有一个方法的抽象服务：`saveText(input) → Promise<SpillRef>`。它持久保存完整的 `content`，并在实际存储失败（权限、ENOSPC、后端不可用）时拒绝。该 seam 只负责存储：不负责保留策略、工具结果替换或检索／搜索 API。
-
-本地后端（[dsh-spill-local](../../packages/spill/spill-local)）写入 `<root>/session-<hash>/<random>-<safeName>`：根目录是已配置或延迟创建的私有（0700）目录，会话子目录采用 `sha256(sessionId)`，并通过排他且仅所有者可访问的写入（`open(path, 'wx', 0o600)`）防止预先植入的符号链接重定向写入。其 `locator` 是本地路径，`retrievalHint` 则告知模型在该路径上使用 `read` 或 `grep`。策略消费方（[dsh-spill-policy](../../packages/spill/spill-policy)）会把超过 `maxInlineTokens` 的图文结果替换为按原顺序保留的首尾内容和 spill 地址；该过程尽力而为：保存失败时保留原始内联结果，而不会把成功的调用变成 `isError`。
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxspillstore--spillstore-abstract-seam"></a>
-
-### `ctx.spillStore` — `SpillStore` (abstract seam)
-
-Abstract spill storage service. Subclass, implement saveText, and load the subclass as a plugin — it registers as `ctx.spillStore` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
-
-Semantics every implementation must honor:
-
-- saveText persists the FULL `content` verbatim and returns an opaque locator, exact byte length, and model-facing retrieval guidance.
-- Storage is scoped by the request's SaveTextSpill.owner session; the backend chooses a private (not world-readable) location and a collision-free name derived from — never equal to — the caller's `suggestedName`.
-- `saveText` REJECTS on a real storage failure (permissions, ENOSPC, backend unavailable); the caller decides how to degrade (the spill policy treats a rejection as best-effort and keeps the inline result).
-
-```ts cordis-catalog
-/**
- * Persist `input.content` to a session-scoped spill artifact.
- * @param input - the owner, caller-supplied source fields, suggested name, and full text to save.
- * @returns the saved artifact's {@link SpillRef}; rejects on a storage failure.
- */
-abstract saveText(input: SaveTextSpill): Promise<SpillRef>
-```
-
-Source: [`packages/spill/spill/src/index.ts`](../../packages/spill/spill/src/index.ts)
-<!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/ssh.i18n.yaml

@@ -1,22 +0,0 @@
-# Bilingual-pair consistency record for ssh.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/subsystems/ssh.md
-/ssh:
-  en: 847a37e7a77c8a3f
-  zh: 33f4de7837ec2faa
-/ssh/execution-coordinates:
-  en: 6dca62a58ecbc1ff
-  zh: 1ebb7dbe79927701
-/ssh/transport-and-trust:
-  en: e807ecd0222acb80
-  zh: b2077393b549a7fe
-/ssh/process-lifetime-and-cancellation:
-  en: 3e29eb0f47ca4d21
-  zh: 9d880e082d39577e
-/ssh/composition-scope:
-  en: 13a012fde5c31dae
-  zh: 52ee73d3be07cec8
-/ssh/connection-api:
-  en: eae91ed9211f563b
-  zh: 78bebc76c4a82306

package/references/official-docs/docs/subsystems/ssh.md

@@ -1,146 +0,0 @@
-# SSH
-
-English | [中文](ssh.zh.md)
-
-The [SSH provider family](../../packages/ssh/README.md) supplies one remote filesystem/process world through a deployment-owned OpenSSH connection. The Harness, model transport and Session storage remain on the host. The family implements the existing filesystem, subprocess and sandbox APIs; it introduces no SSH-specific model tools.
-
-## Execution coordinates
-
-Filesystem identities, executable lookup, process cwd, sandbox workspace roots and language-server file URLs refer to the SSH host. Providers canonicalize paths where the files exist, preserving filesystem interpretation of `symlink/..`. The policy resolver carries absolute execution-world spelling without trying to resolve remote paths on the Harness host.
-
-`processPath()` supplies a path usable by the paired subprocess provider. `processPathFromHostPath()` remains unavailable for SSH; installing a remote artifact does not make an arbitrary host path portable. [`NodePtcRuntime`](../../packages/ptc-runtime/ptc-runtime-node/README.md) therefore takes the verified remote launch configuration: an installed script bootstrap or the [helper executable’s embedded worker](../../packages/ssh/ssh-helper-runtime/README.md).
-
-## Transport and trust
-
-Administrative RPC uses the helper’s SSH exec streams. Ordinary stdin, stdout, stderr, terminal output and optional fd 7 control traffic use separately authenticated forwarded Unix sockets. Each forwarded stream has its own SSH channel window; paused program output does not share the control or administrative window. All channels still share connection bandwidth and transport failure.
-
-Deployment authentication, installed artifact verification and per-stream TLS authentication belong to [`dsh-ssh`](../../packages/ssh/ssh/README.md). The helper executes filesystem and process requests with trusted local providers on the remote machine. SSH is a transport; the selected remote sandbox provider enforces file effects.
-
-## Process lifetime and cancellation
-
-A process is reserved before its streams are connected, and launch is accepted at most once. `done` reports the direct result; `waitForExit` observes the remote managed range. Terminal operations retain the asynchronous shared API. Preparation cancellation, launched-process termination and provider disposal release their owned resources through the helper.
-
-Administrative deadlines bound individual RPC observations; they do not replace the execution deadline chosen by a Bash or ptc-runtime consumer. Remote waits can remain pending while other requests progress. SSH loss invalidates pending operations; helper EOF, signals and lease expiry start remote cleanup. The client reports unconfirmed outcomes honestly and never reconnects to replay a possibly executed action.
-
-## Composition scope
-
-Headless records and checks Session cwd through the mounted filesystem provider. Remote FS, Bash, terminal, LSP and PTC consumers can therefore share those coordinates. Web workspace views that assume host filesystem access need separate integration; replacing providers alone does not make those views remote-aware.
-
-See the [decision record](../../.agents/notes/implemented/architecture/2026-09-11-posix-ssh-runtime.md) for the alternatives and verification obligations.
-
-## Connection API
-
-```ts type-equiv
-/** Installed helper invocation; script deployments may also install a PTC bootstrap. */
-type HelperLaunch = {
-  /** Run the installed script with a separately installed Node executable. */
-  kind: 'node-script'
-  /** Absolute remote Node executable. */
-  node: string
-  /** Absolute remote PTC bootstrap; requires bootstrapHash. */
-  bootstrapPath?: string
-  /** Lowercase SHA-256 of bootstrapPath; requires that path. */
-  bootstrapHash?: string
-} | {
-  /** Run the helper executable with its embedded Node and PTC worker. */
-  kind: 'executable'
-}
-```
-
-```ts type-equiv
-/** Deployment-owned SSH identity and installed helper; no model argument selects these values. */
-interface Config {
-  /** OpenSSH host alias, including its existing user, key and known-host configuration. */
-  host: string
-  /** Explicit script or self-contained executable invocation. */
-  launch: HelperLaunch
-  /** Absolute path to the installed, bundled helper entry. */
-  helper: string
-  /** SHA-256 of that bundled helper; mismatches refuse the connection. */
-  helperHash: string
-  /** Absolute remote default workspace. */
-  workspace: string
-  /** Connection and administrative-request deadline, at most 2,147,483,647 milliseconds. */
-  requestTimeoutMs?: number
-  /** Maximum JSON payload bytes per helper request or response. */
-  maxFrameBytes?: number
-  /** Maximum ordinary requests; heartbeat and bounded resource cleanup have reserved capacity. */
-  maxPending?: number
-  /** Remote helper lease; loss of heartbeats starts remote managed cleanup. */
-  leaseMs?: number
-}
-```
-
-```ts public-api
-/** One non-reconnecting SSH session; loss invalidates all active operations. */
-declare class SshConnection extends Service {
-  static Config: schema<Config>;
-  /** Verified remote helper coordinates; callers must await this before launch. */
-  readonly ready: Promise<Hello>;
-  constructor(ctx: Context, config: Config);
-  /** Hold plugin readiness until the remote identity and helper digest are verified. */
-  async [Service.init](): Promise<void>;
-  /** Verified remote PTC launch configuration; script deployments require a verified bootstrap. */
-  get ptcLaunch(): { kind: 'embedded'; executable: string } | { kind: 'node-script'; executable: string; bootstrapPath: string };
-  /**
-     * Send a helper operation; cancellation never replays an ambiguous mutation.
-     * @param method - the private helper operation.
-     * @param params - JSON request fields validated by the helper.
-     * @param result - response validation before returning provider-visible data.
-     * @param signal - cancellation, which does not undo completed remote effects.
-     * @param wait - allow a process observation to outlast the administrative deadline.
-     * @returns the validated remote result.
-     */
-  async request<T>(method: string, params: unknown, result: z.ZodType<T>, signal?: AbortSignal, wait: boolean = false): Promise<T>;
-  /**
-     * Forward one authenticated stream through an independent SSH channel.
-     * @param endpoint - private coordinates issued by this connection's helper.
-     * @param signal - cancellation of allocation and the resulting socket.
-     * @returns a paused socket; attach a consumer before resuming it.
-     */
-  async connectStream(endpoint: SshStreamEndpoint, signal?: AbortSignal): Promise<Socket>;
-  /** Tear down the helper's remote managed ranges before releasing the SSH master when reachable. */
-  dispose(): Promise<void>;
-}
-```
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxssh--sshconnection"></a>
-
-### `ctx.ssh` — `SshConnection`
-
-One non-reconnecting SSH session; loss invalidates all active operations.
-
-```ts cordis-catalog
-/**
- * Send a helper operation; cancellation never replays an ambiguous mutation.
- * @param method - the private helper operation.
- * @param params - JSON request fields validated by the helper.
- * @param result - response validation before returning provider-visible data.
- * @param signal - cancellation, which does not undo completed remote effects.
- * @param wait - allow a process observation to outlast the administrative deadline.
- * @returns the validated remote result.
- */
-async request<T>(method: string, params: unknown, result: z.ZodType<T>, signal?: AbortSignal, wait: boolean = false): Promise<T>
-
-/**
- * Forward one authenticated stream through an independent SSH channel.
- * @param endpoint - private coordinates issued by this connection's helper.
- * @param signal - cancellation of allocation and the resulting socket.
- * @returns a paused socket; attach a consumer before resuming it.
- */
-async connectStream(endpoint: SshStreamEndpoint, signal?: AbortSignal): Promise<Socket>
-
-/** Tear down the helper's remote managed ranges before releasing the SSH master when reachable. */
-dispose(): Promise<void>
-```
-
-Source: [`packages/ssh/ssh/src/index.ts`](../../packages/ssh/ssh/src/index.ts)
-<!-- END GENERATED cordis-surface -->