dsh-plugin-guide 0.3.42 → 0.4.1

package/references/official-docs/docs/subsystems/system-prompt.zh.md

@@ -1,254 +0,0 @@
-# 系统提示词组装
-
-[English](system-prompt.md) | 中文
-
-[system-prompt 包](../../packages/core/system-prompt)负责管理提示词贡献者与一次组装调用之间交换的数据。该包的 [README](../../packages/core/system-prompt/README.zh.md) 记录注册、排序、作用域与渲染行为；本页记录各插件实现或传递的确切跨包类型。
-
-源码：[`packages/core/system-prompt/src/index.ts`](../../packages/core/system-prompt/src/index.ts)。
-
-## 组装上下文
-
-`AssembleContext` 标识一次组装所解析的作用域层，并可携带该请求的显式控制信号。它可合并扩展：`dsh-agent` 添加可选字段 `agent`，用于携带当前的 agent（智能体）实例；`assembleContextFor(agent, signal)` 则一起设置这些显式字段。裸组装既没有作用域，也没有信号。
-
-```ts type-equiv
-/** Merge-extensible context for one prompt assembly. */
-interface AssembleContext {
-  /**
-   * Scope whose providers and waterfall listeners participate. When absent,
-   * only global providers and subject-less listeners participate.
-   */
-  scope?: ScopeKey
-  /** Explicit control signal for the turn that requested this assembly, when any. */
-  signal?: AbortSignal
-}
-```
-
-## 工具提供方结果
-
-`ToolProviderResult.schemas` 是当前组装中对模型可见的工具 schema 集合。`knownNames` 是提供方在限制前的名称全集，用于区分「配置名拼写错误」与「已知工具在此作用域中被有意隐藏」。
-
-```ts type-equiv
-/** Tool schemas visible in one assembly and their pre-restriction name set. */
-interface ToolProviderResult {
-  /** The schemas this provider contributes to THIS assembly. */
-  readonly schemas: readonly ToolSchema[]
-  /** The pre-restriction name universe for config validation (defaults to `schemas`' names). */
-  readonly knownNames?: readonly string[]
-}
-```
-
-## 提示词段落
-
-导出的 `PERSONA_PREFIX_SECTION`（`deployment:persona-prefix`）与 `PERSONA_SUFFIX_SECTION`（`deployment:persona-suffix`）为全局配置和带作用域贡献所共享的段落命名。它们对应的 `PromptSectionOrderName` 项为 `DEPLOYMENT_PERSONA_PREFIX` 与 `DEPLOYMENT_PERSONA_SUFFIX`；[包 README](../../packages/core/system-prompt/README.zh.md#configure-the-prompt)规定其位置与模板配置。
-
-`PromptSection` 是一份只读的同进程注册约定。其文本可以是静态的，也可以从当前组装上下文动态解析。各段先按 order 升序排列，再按名称的代码单元顺序排列；仓库贡献方通过 `getSectionOrder()` 解析服务持有的具名分配。Runtime-context 贡献方通过 `getContextOrder()` 解析独立分配。协作式组装完成后，一个有效的 `complete` 段会成为唯一的提示词段落。agent loop（智能体循环）用 `renderPrompt` 渲染组装后的各段，并把文本作为 `system/message` surface 节点提交——首个步骤作为 surface 第 0 号节点追加，之后在渲染文本变化时原地替换，或者当已准备调用声明 `systemPromptUpdate: 'in-history'` 时，在序列延续期间把非空更新追加到已缓存历史之后——因此提示词作为派生历史中的消息而不是请求字段到达模型（[决策](../../.agents/notes/implemented/architecture/2026-09-02-system-prompt-as-surface-node.zh.md)；[决策规则](../../packages/core/agent-loop/README.zh.md#understand-the-implementation)）。
-
-```ts type-equiv
-/** One contributed section of the system prompt (registry input). */
-interface PromptSection {
-  /** Unique name — a duplicate registration throws (see {@link SystemPrompt.section}). */
-  readonly name: string
-  /**
-   * Sections are concatenated in ascending order. Equal orders use code-unit
-   * name order.
-   */
-  readonly order: number
-  /**
-   * Static text or a provider evaluated at each assembly with that assembly's
-   * {@link AssembleContext}. The text may reference `{{variable}}`s — they are
-   * interpolated later, by {@link renderPrompt}, unless `interpolate` is false.
-   */
-  readonly text: string | ((context: AssembleContext) => string)
-  /** Whether to interpolate prompt variables. Defaults to true; false preserves literal text. */
-  readonly interpolate?: boolean
-  /**
-   * Treat this contribution as the complete system prompt. Assembly still
-   * runs the cooperative waterfall so tools, contexts, and variables can be
-   * resolved, then restores this exact section as the sole prompt section.
-   * More than one effective complete section makes assembly fail.
-   */
-  readonly complete?: boolean
-}
-```
-
-## 动态提示词上下文
-
-`PromptContext` 是与 `PromptSection` 对应的缓存安全结构。组装会解析这些贡献并排序；agent loop（智能体循环）仅在完整当前快照发生变化或被压缩（compaction）移除时，才会将其记录在保留的模型历史之后。
-
-```ts type-equiv
-/** Dynamic model context materialized as a durable user-role snapshot. */
-interface PromptContext {
-  /** Unique name — a duplicate registration throws (see {@link SystemPrompt.context}). */
-  readonly name: string
-  /** Contexts are joined in ascending order. */
-  readonly order: number
-  /** Static text or a provider evaluated at assembly and admission refresh. Empty text contributes nothing. */
-  readonly text: string | ((context: AssembleContext) => string)
-  /** Whether to interpolate prompt variables. Defaults to true; false preserves literal text. */
-  readonly interpolate?: boolean
-  /** Keep this operational context when optional runtime context is disabled. */
-  readonly required?: boolean
-}
-```
-
-`required: true` 在可选运行时上下文被抑制时保留操作所需的贡献。`interpolate: false` 原样保留文本，包括看起来像变量的目录名。`AssembledContext` 将已求值文本及其插值选择传给渲染过程。
-
-```ts type-equiv
-/** One resolved dynamic context contribution. */
-interface AssembledContext {
-  /** The contributing context's unique name. */
-  name: string
-  /** The resolved text before variable interpolation. */
-  text: string
-  /** Whether to interpolate prompt variables. Defaults to true; false preserves literal text. */
-  interpolate?: boolean
-}
-```
-
-<!-- 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="ctxsystemprompt--systemprompt"></a>
-
-### `ctx.systemPrompt` — `SystemPrompt`
-
-Registry service for the prompt inputs assembled before each model step.
-
-```ts cordis-catalog
-/**
- * Register an ordered prompt section in the calling context's scope. A scoped
- * section shadows a global section with the same name; duplicates within one
- * layer and non-finite orders throw. Registration and disposal emit
- * `system-prompt/change`.
- * @param section - the section to register.
- * @returns the exact Cordis effect disposer.
- */
-section(section: PromptSection): () => void
-
-/**
- * Resolve the centrally owned placement of a repository prompt section.
- * @param name - stable section placement name.
- * @returns the section's numeric sort order.
- */
-getSectionOrder(name: PromptSectionOrderName): number
-
-/**
- * Resolve the centrally owned placement of a repository runtime context.
- * @param name - stable context placement name.
- * @returns the context's numeric sort order.
- */
-getContextOrder(name: PromptContextOrderName): number
-
-/**
- * Register ordered dynamic context in the calling context's scope. Scoped
- * entries shadow global entries with the same name.
- * @param context - the context contribution to register.
- * @returns the exact Cordis effect disposer.
- */
-context(context: PromptContext): () => void
-
-/**
- * Suppress optional dynamic runtime-context contributions in the calling
- * context's scope without changing the services that own or enforce those
- * facts. Multiple suppressors remain independently disposable.
- * @returns the exact Cordis effect disposer.
- */
-suppressRuntimeContext(): () => void
-
-/**
- * Register a tool-schema provider in the calling context's scope. Global and
- * matching scoped providers both contribute; returning the reserved
- * {@link TOOL_ORDER_REST} name makes assembly fail.
- * @param provider - evaluated for each assembly with its context.
- * @returns the exact Cordis effect disposer.
- */
-tools(provider: (context: AssembleContext) => ToolProviderResult): () => void
-
-/**
- * Register a prompt variable in the calling context's scope. Scoped values
- * shadow globals; invalid or duplicate names throw. A provider may return
- * `undefined`, but rendering a section that references that value then fails.
- * @param name - the `[a-z][a-z0-9_]*` reference name.
- * @param provider - evaluated for each assembly.
- * @returns the exact Cordis effect disposer.
- */
-variable(name: string, provider: (context: AssembleContext) => string | undefined): () => void
-
-/**
- * Refresh accepted registered runtime facts for request admission. Contexts
- * added only by the assembly waterfall retain their accepted values. Current
- * suppression removes optional contexts, and missing required registrations
- * are restored in registry order. Sections, tools, and interpolation variables
- * retain the accepted assembly; their providers and waterfall do not rerun.
- * @param assembly - accepted assembly for this scope and step.
- * @param context - the same scope and current plugin-defined assembly fields.
- * @returns the accepted assembly with current runtime-context provider text.
- */
-refreshContext(assembly: PromptAssembly, context: AssembleContext = {}): PromptAssembly
-
-/**
- * Assemble global and scoped providers, detach tool parameters, apply
- * canonical ordering, then run the assembly waterfall. Scoped sections and
- * variables shadow globals. The returned waterfall value is authoritative
- * except that an effective complete section is restored afterwards as the
- * sole prompt section.
- * @param context - the optional scope and plugin-defined assembly fields.
- * @returns the post-waterfall assembly with any complete prompt enforced.
- */
-async assemble(context: AssembleContext = {}): Promise<PromptAssembly>
-```
-
-Source: [`packages/core/system-prompt/src/index.ts`](../../packages/core/system-prompt/src/index.ts)
-
-<a id="system-prompt-events"></a>
-
-### `system-prompt/*` events
-
-<a id="system-promptassemble--waterfall"></a>
-
-#### `system-prompt/assemble` — waterfall
-
-Expert waterfall over the assembled sections, contexts, tools, and variables. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners receive only that scope's assemblies. The returned value is authoritative. A supplied signal controls only this explicit assembly request and must not be retained to control later turns. A registered complete section is restored after this waterfall, so listeners cannot add to or replace that scope's system prompt.
-
-```ts cordis-catalog
-/**
- * Expert waterfall over the assembled sections, contexts, tools, and variables.
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners
- * receive only that scope's assemblies. The returned value is authoritative.
- * A supplied signal controls only this explicit assembly request and must not
- * be retained to control later turns. A registered complete section is
- * restored after this waterfall, so listeners cannot add to or replace
- * that scope's system prompt.
- * @param assembly - the mutable assembly built from registered providers.
- * @param context - the caller's per-assembly context.
- * @mode waterfall
- */
-'system-prompt/assemble'(this: Scoped<SystemPrompt>, assembly: PromptAssembly, context: AssembleContext, next: () => Promise<PromptAssembly>): Promise<PromptAssembly>
-```
-
-Types: [Scoped](scope.zh.md)
-
-Source: [`packages/core/system-prompt/src/index.ts`](../../packages/core/system-prompt/src/index.ts)
-
-<a id="system-promptchange--emit"></a>
-
-#### `system-prompt/change` — emit
-
-Emitted when any prompt provider changes. This registry notification is unfiltered because a global change affects every scope.
-
-```ts cordis-catalog
-/**
- * Emitted when any prompt provider changes. This registry notification is
- * unfiltered because a global change affects every scope.
- * @mode emit
- */
-'system-prompt/change'(): void
-```
-
-Source: [`packages/core/system-prompt/src/index.ts`](../../packages/core/system-prompt/src/index.ts)
-<!-- END GENERATED cordis-surface -->

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

@@ -1,19 +0,0 @@
-# Bilingual-pair consistency record for terminal.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/terminal.md
-/persistent-pty-sessions:
-  en: 5debd6ec3dc43d0b
-  zh: 716307c837310aaa
-/persistent-pty-sessions/identity-and-readiness:
-  en: d2b0f4a2ea428e95
-  zh: 732e30b50b24a1cd
-/persistent-pty-sessions/backend-and-live-session:
-  en: 327d7a0e306ceb35
-  zh: 3ad5ef2c23413cdd
-/persistent-pty-sessions/send-and-retained-output:
-  en: c895ec190cf3e5d8
-  zh: 6fc443e08946e17d
-/persistent-pty-sessions/ownership-and-durability:
-  en: 5604e1d1c450882a
-  zh: b97d925978aad7e2

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

@@ -1,184 +0,0 @@
-# Persistent PTY Sessions
-
-English | [中文](terminal.zh.md)
-
-Types shared by PTY backends, `ctx.terminals`, and the model-facing consumer. The [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) owns the rationale; this page records the cross-package vocabulary from [`packages/terminal/terminal/src/types.ts`](../../packages/terminal/terminal/src/types.ts).
-
-## Identity and readiness
-
-`TerminalSessionId` is a service-minted branded id. Optional names are owner-local display metadata; authorization compares the exact owning `Agent`, not a name or guessed id.
-
-`TerminalWaitReason` says why one send returned. It is independent from `TerminalSessionStatus`: silence or timeout may return while the top-level shell remains alive, while `session_exit` means that shell exited rather than an arbitrary foreground child.
-
-```ts type-equiv
-/** Why one interactive send returned control to its caller. */
-type TerminalWaitReason = 'stdin_read' | 'inferred_idle' | 'timeout' | 'session_exit'
-```
-
-```ts type-equiv
-/** Top-level PTY process status, independent of a send's wait reason. */
-type TerminalSessionStatus =
-  | { kind: 'running' }
-  | { kind: 'exited'; exitCode: number | null; signal: NodeJS.Signals | null }
-```
-
-## Backend and live session
-
-A backend owns how one registered type starts and detects readiness. `TerminalSessionService` publishes the returned session only after setup succeeds, then owns id authorization and cleanup. A backend that cannot clean partial startup resources rejects with `TerminalBackendCleanupError`, allowing disposal to retain the cleanup failure without replacing the caller's cancellation reason. A backend session owns terminal state and captured-resource quiescence.
-
-```ts type-equiv
-/** Replaceable provider for one PTY session type. */
-interface TerminalBackend {
-  /** Stable type selected by {@link TerminalSpawnRequest.type}. */
-  readonly type: string
-  /** Create an unpublished session or reject after cleaning partial resources; cleanup failure uses {@link TerminalBackendCleanupError}. */
-  spawn(spec: TerminalBackendSpawnSpec): Promise<TerminalBackendSession>
-}
-```
-
-```ts type-equiv
-/** Backend-owned live session retained by {@link TerminalSessionService}. */
-interface TerminalBackendSession {
-  /** Initial bounded terminal output returned from `terminal_open`. */
-  readonly motd: string
-  /** Top-level process id when one exists. */
-  readonly pid?: number
-  /** Start one exclusive send operation. */
-  startSend(request: TerminalSendRequest): TerminalSendOperation
-  /** Read one bounded page from retained scrollback. */
-  read(request: TerminalReadRequest): TerminalReadResult
-  /** Signal the verified foreground process group. */
-  signal(signal: TerminalSignal): Promise<TerminalSignalResult>
-  /** Observe top-level process status. */
-  status(): TerminalSessionStatus
-  /** Idempotently close the captured owned process tree and await quiescence. */
-  close(reason: string): Promise<void>
-}
-```
-
-## Send and retained output
-
-One live session accepts one active send. Its operation exposes a consuming output cursor for generic background jobs and one terminal result for a foreground caller. `TerminalReadResult` separately pages the bounded session scrollback.
-
-```ts type-equiv
-/** Live backend-owned send; exactly one may be active per PTY session. */
-interface TerminalSendOperation {
-  /** Resolves after readiness, timeout, cancellation, or top-level process exit. */
-  done: Promise<TerminalSendResult>
-  /** Consume output produced since the prior call. */
-  readOutput(): TerminalSendRead
-  /** Request `SIGINT`; returns false after the operation settled. */
-  cancel(): boolean
-}
-```
-
-```ts type-equiv
-/** Settled result for one foreground or background send. */
-interface TerminalSendResult {
-  /** Bounded rendered terminal delta remaining at settlement. */
-  viewport: string
-  /** Why the wait returned; this does not imply arbitrary child-process exit. */
-  waitReason: TerminalWaitReason
-  /** Top-level session status observed at settlement. */
-  sessionStatus: TerminalSessionStatus
-  /** Whether output was dropped from the operation or retained scrollback. */
-  truncated: boolean
-}
-```
-
-## Ownership and durability
-
-`TerminalSessionService` attaches one awaited cleanup to the exact owner scope, rejects foreign operations, and keeps sessions alive across backend or tool-plugin reload. PTY state and raw bytes remain process-local. Model input and bounded returned output are durable through the existing `tool/call`, `tool/result`, and task-result paths rather than duplicate PTY session events.
-
-<!-- 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="ctxterminals--terminalsessionservice"></a>
-
-### `ctx.terminals` — `TerminalSessionService`
-
-In-process registry for replaceable PTY backends and exact-Agent sessions.
-
-```ts cordis-catalog
-/**
- * Register one backend type for this effect scope.
- * @param backend - provider with a non-empty unique type.
- * @returns disposer that removes exactly this contribution.
- */
-registerBackend(backend: TerminalBackend): () => void
-
-/**
- * List registered backend types in registration order.
- * @returns fresh backend type names.
- */
-listBackends(): string[]
-
-/**
- * Create and publish one owner-scoped session after backend setup succeeds.
- * @param owner - exact registered Agent that owns access and cleanup.
- * @param request - backend type plus optional owner-local name and cwd.
- * @param signal - cancellation of unpublished setup.
- * @returns published identity, metadata, status, and MOTD.
- */
-async spawn(owner: Agent, request: TerminalSpawnRequest, signal?: AbortSignal): Promise<TerminalSpawnResult>
-
-/**
- * Test whether an exact owner has a published session or unpublished spawn.
- * @param owner - exact live owner to inspect.
- * @returns true across the entire spawn-to-close interval, with no publication gap.
- */
-hasOwnerActivity(owner: Agent): boolean
-
-/**
- * Start one exclusive interactive send.
- * @param owner - exact session owner.
- * @param id - target PTY identity.
- * @param request - explicit text, submit behavior, and cancellation.
- * @returns live operation handle for foreground await or task registration.
- */
-startSend(owner: Agent, id: TerminalSessionId, request: TerminalSendRequest): TerminalSendOperation
-
-/**
- * Read one bounded scrollback page from an owned session.
- * @param owner - exact session owner.
- * @param id - target PTY identity.
- * @param request - optional newest-relative offset and line count.
- * @returns bounded retained text and pagination metadata.
- */
-read(owner: Agent, id: TerminalSessionId, request: TerminalReadRequest = {}): TerminalReadResult
-
-/**
- * Deliver an allowed signal through an owned backend session.
- * @param owner - exact session owner.
- * @param id - target PTY identity.
- * @param signal - allowed POSIX signal name.
- * @returns delivered foreground process-group identity.
- */
-signal(owner: Agent, id: TerminalSessionId, signal: TerminalSignal): Promise<TerminalSignalResult>
-
-/**
- * Close one owned session and remove it only after quiescent backend cleanup.
- * @param owner - exact session owner.
- * @param id - target PTY identity.
- * @param reason - diagnostic cleanup reason.
- * @returns true for a newly closed session, false when the same close is already in flight.
- */
-async kill(owner: Agent, id: TerminalSessionId, reason: string = 'model request'): Promise<boolean>
-
-/**
- * List fresh snapshots for exactly one owner.
- * @param owner - exact owner whose sessions are visible.
- * @returns owner-visible snapshots in publication order.
- */
-list(owner: Agent): TerminalSessionSnapshot[]
-```
-
-Types: [Agent](core.md)
-
-Source: [`packages/terminal/terminal/src/index.ts`](../../packages/terminal/terminal/src/index.ts)
-<!-- END GENERATED cordis-surface -->

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

@@ -1,184 +0,0 @@
-# 持久 PTY 会话
-
-[English](terminal.md) | 中文
-
-PTY 后端、`ctx.terminals` 与面向模型的消费方共享的类型。[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.zh.md) 负责记录决策依据；本页记录来自 [`packages/terminal/terminal/src/types.ts`](../../packages/terminal/terminal/src/types.ts) 的跨包词汇。
-
-## 标识与就绪
-
-`TerminalSessionId` 是由服务铸造的branded id。可选名称是拥有者本地的显示元数据；授权比较的是拥有该会话的确切 `Agent`，而不是名称或猜测的 id。
-
-`TerminalWaitReason` 说明一次发送为何返回。它与 `TerminalSessionStatus` 无关：一次发送可能因静默或超时而返回，但顶层 shell 仍然存活；`session_exit` 表示该 shell 已退出，而不是某个任意的前台子进程已退出。
-
-```ts type-equiv
-/** Why one interactive send returned control to its caller. */
-type TerminalWaitReason = 'stdin_read' | 'inferred_idle' | 'timeout' | 'session_exit'
-```
-
-```ts type-equiv
-/** Top-level PTY process status, independent of a send's wait reason. */
-type TerminalSessionStatus =
-  | { kind: 'running' }
-  | { kind: 'exited'; exitCode: number | null; signal: NodeJS.Signals | null }
-```
-
-## 后端与活跃会话
-
-后端负责启动某种已注册类型的会话并检测其就绪状态。`TerminalSessionService` 只在初始化成功后才发布返回的会话，随后负责 id 授权与清理。无法清理部分启动资源时，后端会以 `TerminalBackendCleanupError` 拒绝启动；这样，资源释放流程既能保留清理失败，也不会用它替换调用方的取消原因。后端会话拥有终端状态，并负责让已捕获的资源完全停稳。
-
-```ts type-equiv
-/** Replaceable provider for one PTY session type. */
-interface TerminalBackend {
-  /** Stable type selected by {@link TerminalSpawnRequest.type}. */
-  readonly type: string
-  /** Create an unpublished session or reject after cleaning partial resources; cleanup failure uses {@link TerminalBackendCleanupError}. */
-  spawn(spec: TerminalBackendSpawnSpec): Promise<TerminalBackendSession>
-}
-```
-
-```ts type-equiv
-/** Backend-owned live session retained by {@link TerminalSessionService}. */
-interface TerminalBackendSession {
-  /** Initial bounded terminal output returned from `terminal_open`. */
-  readonly motd: string
-  /** Top-level process id when one exists. */
-  readonly pid?: number
-  /** Start one exclusive send operation. */
-  startSend(request: TerminalSendRequest): TerminalSendOperation
-  /** Read one bounded page from retained scrollback. */
-  read(request: TerminalReadRequest): TerminalReadResult
-  /** Signal the verified foreground process group. */
-  signal(signal: TerminalSignal): Promise<TerminalSignalResult>
-  /** Observe top-level process status. */
-  status(): TerminalSessionStatus
-  /** Idempotently close the captured owned process tree and await quiescence. */
-  close(reason: string): Promise<void>
-}
-```
-
-## 发送与保留输出
-
-一个活跃会话同时只接受一个活动发送。该操作向通用后台任务提供读取后即推进的输出游标，并向前台调用方提供最终结果。`TerminalReadResult` 则为有界的会话 scrollback 单独分页。
-
-```ts type-equiv
-/** Live backend-owned send; exactly one may be active per PTY session. */
-interface TerminalSendOperation {
-  /** Resolves after readiness, timeout, cancellation, or top-level process exit. */
-  done: Promise<TerminalSendResult>
-  /** Consume output produced since the prior call. */
-  readOutput(): TerminalSendRead
-  /** Request `SIGINT`; returns false after the operation settled. */
-  cancel(): boolean
-}
-```
-
-```ts type-equiv
-/** Settled result for one foreground or background send. */
-interface TerminalSendResult {
-  /** Bounded rendered terminal delta remaining at settlement. */
-  viewport: string
-  /** Why the wait returned; this does not imply arbitrary child-process exit. */
-  waitReason: TerminalWaitReason
-  /** Top-level session status observed at settlement. */
-  sessionStatus: TerminalSessionStatus
-  /** Whether output was dropped from the operation or retained scrollback. */
-  truncated: boolean
-}
-```
-
-## 归属与持久性
-
-`TerminalSessionService` 会将一项等待完成的清理附加到确切的拥有者作用域，拒绝其他拥有者的操作，并让会话在后端或工具插件重载期间保持存活。PTY 状态与原始字节仍局限在进程内。模型输入与有界返回输出通过现有 `tool/call`、`tool/result` 和任务结果路径持久保存，而不是重复记录 PTY 会话事件。
-
-<!-- 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="ctxterminals--terminalsessionservice"></a>
-
-### `ctx.terminals` — `TerminalSessionService`
-
-In-process registry for replaceable PTY backends and exact-Agent sessions.
-
-```ts cordis-catalog
-/**
- * Register one backend type for this effect scope.
- * @param backend - provider with a non-empty unique type.
- * @returns disposer that removes exactly this contribution.
- */
-registerBackend(backend: TerminalBackend): () => void
-
-/**
- * List registered backend types in registration order.
- * @returns fresh backend type names.
- */
-listBackends(): string[]
-
-/**
- * Create and publish one owner-scoped session after backend setup succeeds.
- * @param owner - exact registered Agent that owns access and cleanup.
- * @param request - backend type plus optional owner-local name and cwd.
- * @param signal - cancellation of unpublished setup.
- * @returns published identity, metadata, status, and MOTD.
- */
-async spawn(owner: Agent, request: TerminalSpawnRequest, signal?: AbortSignal): Promise<TerminalSpawnResult>
-
-/**
- * Test whether an exact owner has a published session or unpublished spawn.
- * @param owner - exact live owner to inspect.
- * @returns true across the entire spawn-to-close interval, with no publication gap.
- */
-hasOwnerActivity(owner: Agent): boolean
-
-/**
- * Start one exclusive interactive send.
- * @param owner - exact session owner.
- * @param id - target PTY identity.
- * @param request - explicit text, submit behavior, and cancellation.
- * @returns live operation handle for foreground await or task registration.
- */
-startSend(owner: Agent, id: TerminalSessionId, request: TerminalSendRequest): TerminalSendOperation
-
-/**
- * Read one bounded scrollback page from an owned session.
- * @param owner - exact session owner.
- * @param id - target PTY identity.
- * @param request - optional newest-relative offset and line count.
- * @returns bounded retained text and pagination metadata.
- */
-read(owner: Agent, id: TerminalSessionId, request: TerminalReadRequest = {}): TerminalReadResult
-
-/**
- * Deliver an allowed signal through an owned backend session.
- * @param owner - exact session owner.
- * @param id - target PTY identity.
- * @param signal - allowed POSIX signal name.
- * @returns delivered foreground process-group identity.
- */
-signal(owner: Agent, id: TerminalSessionId, signal: TerminalSignal): Promise<TerminalSignalResult>
-
-/**
- * Close one owned session and remove it only after quiescent backend cleanup.
- * @param owner - exact session owner.
- * @param id - target PTY identity.
- * @param reason - diagnostic cleanup reason.
- * @returns true for a newly closed session, false when the same close is already in flight.
- */
-async kill(owner: Agent, id: TerminalSessionId, reason: string = 'model request'): Promise<boolean>
-
-/**
- * List fresh snapshots for exactly one owner.
- * @param owner - exact owner whose sessions are visible.
- * @returns owner-visible snapshots in publication order.
- */
-list(owner: Agent): TerminalSessionSnapshot[]
-```
-
-Types: [Agent](core.zh.md)
-
-Source: [`packages/terminal/terminal/src/index.ts`](../../packages/terminal/terminal/src/index.ts)
-<!-- END GENERATED cordis-surface -->

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

@@ -1,13 +0,0 @@
-# Bilingual-pair consistency record for todo.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/todo.md
-/todo:
-  en: 92e62f0694b67bea
-  zh: 1759d71cfa980af9
-/todo/todoitem-one-list-entry:
-  en: 3580467f183af02a
-  zh: e3fc7208b0c2ee59
-/todo/durable-event:
-  en: 5e00744b8bf1d72f
-  zh: c85327d075675630