dsh-plugin-guide 0.3.41 → 0.4.0

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

@@ -1,321 +0,0 @@
-# 子进程
-
-[English](subprocess.md) | 中文
-
-子进程 seam 分为 Service Definition（[dsh-subprocess](../../packages/subprocess/subprocess)，`ctx.subprocess`）与 Service Provider（[dsh-subprocess-local](../../packages/subprocess/subprocess-local)）；它的 Consumer 是其他能力 seam 与进程外后端：[bash 执行器家族](shell.zh.md)使用收集模式的批量输出，LSP 使用原始协议管道，PTY 后端使用终端原语，ACP（Agent Client Protocol）subagent 后端则使用通过管道传输的 ndjson，并让 stderr 采用 inherit。该 seam 拥有受管的 `DSH_*` 环境命名空间、共享的凭据清除（`scrubbedParentEnv`）与 `CollectedOutput` 形状；[dsh-shell](../../packages/shell/shell) 重导出这套词汇，使 bash 消费方保持单一导入入口。
-
-源码：[`packages/subprocess/subprocess/src/types.ts`](../../packages/subprocess/subprocess/src/types.ts) 与 [`packages/subprocess/subprocess/src/index.ts`](../../packages/subprocess/subprocess/src/index.ts)
-
-## 可执行文件查找
-
-一个提供方的 spawn 工作目录、可执行文件路径、普通进程与终端会话，和挂载的文件系统提供方处于同一路径与进程命名空间。`resolveExecutable(command, env?, signal?)` 验证绝对可执行文件路径，或通过提供方清理后的 `PATH` 加有意覆盖来解析裸名称。
-
-## 受管环境命名空间与捕获的输出
-
-`DSH_*` 变量是归 Harness 所有的子进程事实；实现会在合并调用方显式 `env` 之前丢弃环境中已有的 `DSH_*` 名称，因此当前事实只会以有意提供的字符串条目形式到达，而显式的 `undefined` tombstone 会删除普通环境中已有的值。每条被收集的流都通过 `CollectedOutput` 报告自身的截断与 spill 恢复状态。
-
-```ts type-equiv
-/** One environment key inside the managed {@link DSH_ENV_PREFIX} namespace. */
-type DshEnvironmentKey = `${typeof DSH_ENV_PREFIX}${string}`
-```
-
-```ts type-equiv
-/** Trusted DeepSeek Harness variables for one child-process execution. */
-type DshEnvironment = Readonly<Record<DshEnvironmentKey, string>>
-```
-
-```ts type-equiv
-/** One captured stream: the (possibly truncated) text plus recovery info. */
-interface CollectedOutput {
-  /** Collected text — the TAIL of the stream when truncated. */
-  text: string
-  /** True when bytes were dropped from `text`. */
-  truncated: boolean
-  /** Path to a file holding the COMPLETE stream, when truncated and available. */
-  spillPath?: string
-}
-```
-
-## Node 风格的 stdio 处置方式（disposition）
-
-每条流的处置方式都显式给出，由各消费方自行选择：原始管道用于协议分帧（LSP JSON-RPC、ACP ndjson），inherit 用于直通的诊断输出，收集模式用于有界的批量输出；其中 spill 文件是可选的，因此诊断尾部（语言服务器的 stderr）可以只在内存中缓冲，不留下任何文件。
-
-```ts type-equiv
-/**
- * stdin disposition. `'ignore'` leaves fd 0 on `/dev/null`; `'pipe'` exposes
- * {@link SubprocessHandle.stdin} for the caller's ongoing protocol writes;
- * `{ data }` writes the bytes and closes (the batch shape).
- */
-type SubprocessStdinMode = 'ignore' | 'pipe' | { readonly data: string }
-```
-
-```ts type-equiv
-/**
- * Bounded in-memory collection for one output stream, with an optional
- * full-stream spill file. Omitting `spill` keeps only the in-memory tail —
- * the diagnostic-tail shape (a language server's stderr); including it makes
- * the complete stream recoverable up to its cap (the bash tool shape).
- */
-interface SubprocessCollect {
-  /** In-memory cap in bytes; overflow keeps the TAIL. */
-  maxBytes: number
-  /** Full-stream spill file; absent disables spilling entirely. */
-  spill?: {
-    /** Whole-stream byte cap; a larger stream discards its now-incomplete spill. */
-    maxBytes: number
-  }
-}
-```
-
-```ts type-equiv
-/**
- * stdout/stderr disposition. `'pipe'` exposes the raw `Readable` for the
- * caller's protocol decoding; `'inherit'` passes the parent's descriptor
- * through (child diagnostics land on the harness's own stream); a
- * {@link SubprocessCollect} object buffers boundedly with offset-based reads.
- */
-type SubprocessOutputMode = 'pipe' | 'inherit' | SubprocessCollect
-```
-
-```ts type-equiv
-/** Per-stream stdio dispositions, all explicit — this seam applies no defaults. */
-interface SubprocessStdio {
-  stdin: SubprocessStdinMode
-  stdout: SubprocessOutputMode
-  stderr: SubprocessOutputMode
-  /** Request a separate byte-mode duplex channel; omission creates none. */
-  control?: 'pipe'
-}
-```
-
-## 完全显式的 spawn spec
-
-该 seam 不应用任何默认值：每项处置方式、限制与目录都在 spec 上显式给出，因此由调用方自己的配置决定它们，而不是由某个隐藏的子进程服务默认值决定。`argv` 绝不经过 shell 解释。
-
-```ts type-equiv
-/**
- * A fully-specified spawn request. This seam applies no defaults: every
- * disposition, limit, and directory is explicit, so the caller's own config —
- * not a hidden subprocess-service default — decides them (the `dsh-shell`
- * request/spec split is the owning template).
- */
-interface SubprocessSpawnSpec {
-  /** Executable and arguments; `argv[0]` is the program. Never shell-interpreted here. */
-  argv: readonly string[]
-  /** Working directory for the child. */
-  cwd: string
-  /** Per-stream stdio dispositions. */
-  stdio: SubprocessStdio
-  /**
-   * Positive finite grace period in milliseconds, no greater than
-   * `MAX_TIMER_DELAY_MS`, available to the provider's termination procedure
-   * and used for draining still-open collected pipes after the process exits
-   * (an inherited descriptor held by a survivor cannot hold the outcome open
-   * indefinitely). Providers document whether range termination is staged or
-   * immediate.
-   */
-  graceMs: number
-  /**
-   * Abort signal — starts the terminate escalation on the managed range when
-   * it fires. The caller owns deadlines and cause classification; this seam
-   * only reacts to the abort.
-   */
-  signal?: AbortSignal | undefined
-  /**
-   * Explicit environment entries merged onto the implementation's scrubbed
-   * parent base (see `scrubbedParentEnv`), with no namespace validation. A
-   * string is a deliberate caller opt-in, so a forwarded credential-shaped
-   * entry or current `DSH_*` fact survives the scrub; `undefined` is a
-   * tombstone that removes an ordinary ambient entry from the child.
-   */
-  env?: NodeJS.ProcessEnv | undefined
-}
-```
-
-## 句柄：流、读取器与 managed-range 终止
-
-spawn 会同步返回活动句柄，目标与受管范围标识则保留在 provider 内部。收集模式的读取器接受全流字节偏移量且从不消费，因此独立读取器不会抢走彼此的增量；管道化的流归调用方所有。`terminate()` 启动 provider 记录的终止过程，`waitForExit()` 观察同一个 provider-managed range；分阶段 provider 可以使用 `graceMs`，立即终止的 provider 不会等待。消费方可以在这两项操作上构建自己的分级清理流程；ACP 后端先关闭 stdin 的 `disposeAcpChild` 是参考实现。
-
-```ts type-equiv
-/**
- * A live subprocess and its provider-managed process range. Collected output
- * remains readable after exit; piped streams belong to the caller.
- *
- * Termination and {@link SubprocessHandle.waitForExit} use the same managed
- * range. Each provider documents the range it can observe and its signalling
- * and observation limits.
- */
-interface SubprocessHandle {
-  /** The child's stdin, present iff spawned with `stdin: 'pipe'`. */
-  readonly stdin: Writable | undefined
-  /** The child's raw stdout, present iff spawned with `stdout: 'pipe'`. */
-  readonly stdout: Readable | undefined
-  /** The child's raw stderr, present iff spawned with `stderr: 'pipe'`. */
-  readonly stderr: Readable | undefined
-  /** Separate caller-owned byte channel when requested; native startup failure may leave it absent. */
-  readonly control: Duplex | undefined
-  /** Offset-based readers for collect-mode streams (also readable after exit). */
-  readonly collected: SubprocessCollectedOutputs
-  /** Resolves with spawned-command exit facts; rejects for spawn or provider failures. */
-  readonly done: Promise<SubprocessOutcome>
-  /**
-   * Begin the provider's documented termination procedure on the managed range
-   * — the seam's only termination verb. Idempotent, a no-op once that range is
-   * gone, and also triggered by the spec's abort signal.
-   */
-  terminate(): void
-  /**
-   * Wait until the same managed range is empty — not just until the spawned
-   * command reports its outcome, so surviving work remains observable.
-   * @param signal - optional bound for the wait.
-   * @returns `true` when the managed range is empty, `false` when the signal aborted first.
-   * @throws when the selected provider can no longer observe its managed range.
-   */
-  waitForExit(signal?: AbortSignal): Promise<boolean>
-}
-```
-
-```ts type-equiv
-/**
- * Cursor-free incremental access to one collected output stream. Offsets are
- * whole-stream byte coordinates owned by the caller, so independent readers
- * cannot consume one another's output; `readFrom(0)` after settlement is the
- * batch result (`lossy` then means the in-memory tail lost its head — the
- * {@link CollectedOutput.truncated} fact).
- */
-interface SubprocessOutputReader {
-  /**
-   * Read everything captured since `fromByte`. When that offset has slid out
-   * of the in-memory tail window the read is `lossy` — it returns the whole
-   * retained tail and the gap is only recoverable from the spill file.
-   * @param fromByte - whole-stream offset to resume from (a prior read's `nextOffset`; 0 for the first read).
-   * @returns the delta text, the next offset, the `lossy` flag, and the spill path when one exists.
-   */
-  readFrom(fromByte: number): SubprocessOutputRead
-}
-```
-
-```ts type-equiv
-/** One incremental {@link SubprocessOutputReader.readFrom} read. */
-interface SubprocessOutputRead {
-  /** Stream text from the requested offset (the whole retained tail when lossy). */
-  text: string
-  /** Whole-stream offset to resume from on the next read. */
-  nextOffset: number
-  /** True when the requested offset slid out of the in-memory tail window. */
-  lossy: boolean
-  /** Path to the full-stream spill file, when one was created and remains intact. */
-  spillPath?: string
-}
-```
-
-```ts type-equiv
-/** Offset-based readers for the streams spawned in collect mode. */
-interface SubprocessCollectedOutputs {
-  /** Present iff stdout is a {@link SubprocessCollect}. */
-  readonly stdout?: SubprocessOutputReader
-  /** Present iff stderr is a {@link SubprocessCollect}. */
-  readonly stderr?: SubprocessOutputReader
-}
-```
-
-
-## 结果只承载退出事实
-
-`done` 报告 Node close 事件的词汇，不携带原因分类：服务会在中止时终止进程，但绝不判定原因（调用方读取归自己所有的 deadline 信号，例如 bash 执行器的 `timedOut`/`aborted` 拆分）。收集到的输出在结算后仍可经 `handle.collected` 读取，因此批量与流式调用方共用一条访问路径。
-
-```ts type-equiv
-/**
- * Exit facts of one closed process — Node's `close`-event vocabulary.
- * Deliberately carries NO timeout or cancellation classification (the caller
- * reads the signal it owns to classify causes) and NO output: collected
- * streams stay readable through {@link SubprocessHandle.collected} after
- * settlement, so batch and streaming callers share one access path.
- */
-interface SubprocessOutcome {
-  /** Exit code; null when the process died from a signal. */
-  exitCode: number | null
-  /** Terminating signal (e.g. 'SIGTERM'); null on normal exit. */
-  signal: NodeJS.Signals | null
-}
-```
-
-## 终端进程原语
-
-`spawnTerminal(spec)` 是非管道进程原语。提供方分配控制终端，并负责 UTF-8 文本传输、前台进程组检查与信号发送，以及一项须等待的 TERM→KILL 操作；该操作会使提供方仍可观察到的每个会话成员完全停稳，提供方则会记录执行基底特有的可观察性限制。PTY 后端仍负责提示符检测、就绪推断、scrollback、沙箱策略和持久会话所有权；普通 `spawn()` 无法重建控制终端语义。
-
-终端 spec 完全指定 argv、cwd、环境覆盖、终端类型、尺寸、清理宽限期与可选的分配取消和 shell 活动观察。其句柄公开 `pid`、有序输出、`done`、`write`、`resize`、`inspectForeground`、`inspectActivity`、`signalForeground` 和须等待的 `terminate`；[`SubprocessTerminalSpawnSpec` 与 `SubprocessTerminalHandle`](../../packages/subprocess/subprocess/src/types.ts) 定义这些字段和操作。`resize(cols, rows)` 更新正在运行的 PTY 尺寸，进程退出后拒绝调用。
-
-`inspectActivity()` 返回 `SubprocessTerminalActivity`：`state` 为 `idle`、`busy` 或 `unknown`，`revision` 随 provider 观察到的活动或输入变化。终端请求通过 `shellActivity` 启用受支持的 shell 生命周期观察；各 provider 的支持范围和保守返回 unknown 的情况见 [subprocess-local](../../packages/subprocess/subprocess-local/README.zh.md#running-terminal-sessions)。
-
-`terminalEnvironment(signal?)` 返回 `SubprocessTerminalEnvironment`：执行环境平台（`posix` 或 `windows`）与可选的 `defaultShell`。这些事实来自提供方，而非 Web 服务器或浏览器。`resolveExecutable` 验证候选 shell；`SubprocessExecutableNotFoundError` 表示可执行文件不存在，提供方与传输故障仍作为错误报告。
-
-## 服务行为
-
-抽象的 [`SubprocessRuntime`](../../packages/subprocess/subprocess/src/index.ts) Service Definition 规定执行世界坐标、可执行文件查找、普通 `spawn` 与 `spawnTerminal`。[`LocalSubprocessRuntime`](../../packages/subprocess/subprocess-local/src/index.ts) 以平台选择的 managed range、按处置方式接线、凭据清除、`node-pty`、平台进程检查，以及先终止再等待退出的资源释放提供这些能力。Service Definition 约定见 [`dsh-subprocess`](../../packages/subprocess/subprocess/README.zh.md)，本地机制见 [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.zh.md)。
-
-<!-- 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="ctxsubprocess--subprocessruntime-abstract-seam"></a>
-
-### `ctx.subprocess` — `SubprocessRuntime` (abstract seam)
-
-Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as `ctx.subprocess` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
-
-Implementations must honor these semantics:
-
-- Executable paths belong to one execution world shared with the mounted filesystem provider.
-- spawn returns a live handle synchronously. Target identity remains provider-private; `done` resolves with the spawned command's exit facts and may reject for spawn or provider failures.
-- Collect-mode readers are offset-based and non-consuming, so independent readers never consume one another's output; lossy reads report truncation and the spill file holding the complete stream when one exists. Piped streams are handed to the caller raw and never buffered here.
-- SubprocessHandle.terminate (and the spec's abort signal) starts the provider's documented procedure against its managed range. SubprocessHandle.waitForExit observes that same range so a consumer-owned teardown ladder can hold each tier on real quiescence; each provider documents its signalling and observability limits.
-- Disposal of the service terminates all still-running managed processes and awaits their exit.
-- spawnTerminal owns terminal allocation, text transport, foreground groups, signalling, and whole-session quiescence behind one awaited termination method; readiness and persistent-shell policy stay in the PTY consumer. Its output stream ends after queued terminal output when the top-level process exits.
-
-```ts cordis-catalog
-/**
- * Resolve one configured executable in this provider's execution world.
- * Absolute paths are verified; bare names use the provider's scrubbed PATH
- * plus explicit environment overrides. Relative paths containing separators
- * are rejected: the resolution base is undefined, so providers fail loud
- * instead of guessing.
- * @param command - absolute executable path or bare PATH name.
- * @param env - explicit environment entries used for lookup.
- * @param signal - aborts remote or local lookup.
- * @returns a canonical executable path.
- */
-abstract resolveExecutable( command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal, ): Promise<string>
-
-/**
- * Inspect shell-selection facts in the provider's execution environment.
- * @param signal - cancellation of remote environment inspection.
- * @returns platform and preferred shell; executable lookup and allocation remain separate operations.
- */
-abstract terminalEnvironment(signal?: AbortSignal): Promise<SubprocessTerminalEnvironment>
-
-/**
- * Start one managed child process from a fully-specified spec; this seam
- * applies no defaults.
- * @param spec - argv, directory, stdio dispositions, grace, cancellation, and environment.
- * @returns the live process handle (streams/readers, signalling, outcome promise).
- * @throws synchronously when pre-aborted or when argv, cwd, environment, or grace is invalid before handle creation.
- */
-abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle
-
-/**
- * Allocate a real terminal and start one owned process session. This is the
- * only non-pipe process primitive: implementations own terminal byte I/O,
- * foreground groups, signals, and whole-session quiescence.
- * @param spec - fully specified argv, cwd, environment, dimensions, grace, and allocation cancellation.
- * @returns the live terminal handle after allocation succeeds.
- */
-abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>
-```
-
-Source: [`packages/subprocess/subprocess/src/index.ts`](../../packages/subprocess/subprocess/src/index.ts)
-<!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/system-prompt.i18n.yaml

@@ -1,19 +0,0 @@
-# Bilingual-pair consistency record for system-prompt.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/system-prompt.md
-/system-prompt-assembly:
-  en: 7ad02b2146520e7b
-  zh: 93cb93c7aa12ceb4
-/system-prompt-assembly/assembly-context:
-  en: 371539c21c1ffc45
-  zh: ea429ea5a0c19215
-/system-prompt-assembly/tool-provider-result:
-  en: 89cb015bf2e3e7a5
-  zh: b4340e853b34c777
-/system-prompt-assembly/prompt-sections:
-  en: e31de7452a4f1186
-  zh: db697d4db7f88642
-/system-prompt-assembly/dynamic-prompt-context:
-  en: 2abb13dec8e6d041
-  zh: 8cf434f360d8a519

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

@@ -1,254 +0,0 @@
-# System Prompt Assembly
-
-English | [中文](system-prompt.zh.md)
-
-The [system-prompt package](../../packages/core/system-prompt) owns the data exchanged between prompt contributors and one assembly call. The package [README](../../packages/core/system-prompt/README.md) documents registration, ordering, scoping, and rendering behavior; this page records the exact cross-package types that plugins implement or pass.
-
-Source: [`packages/core/system-prompt/src/index.ts`](../../packages/core/system-prompt/src/index.ts).
-
-## Assembly context
-
-`AssembleContext` identifies the scope layer one assembly resolves and may carry the explicit control signal for that request. It is merge-extensible: `dsh-agent` adds the optional live `agent` field, and `assembleContextFor(agent, signal)` sets the explicit fields together. A bare assembly has neither scope nor 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
-}
-```
-
-## Tool-provider result
-
-`ToolProviderResult.schemas` is the model-visible set for the current assembly. `knownNames` is the provider's pre-restriction name universe used to distinguish a configured-name typo from a known tool that is deliberately hidden in this scope.
-
-```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[]
-}
-```
-
-## Prompt sections
-
-The exported `PERSONA_PREFIX_SECTION` (`deployment:persona-prefix`) and `PERSONA_SUFFIX_SECTION` (`deployment:persona-suffix`) name the slots shared by global configuration and scoped contributions. Their `PromptSectionOrderName` entries are `DEPLOYMENT_PERSONA_PREFIX` and `DEPLOYMENT_PERSONA_SUFFIX`; the [package README](../../packages/core/system-prompt/README.md#configure-the-prompt) owns their placement and template configuration.
-
-`PromptSection` is a readonly same-process registration contract. Its text may be static or resolved from the current assembly context. Sections sort by ascending order and then code-unit name; repository contributors resolve the service-owned named allocation through `getSectionOrder()`. Runtime-context contributors resolve their independent allocation through `getContextOrder()`. One effective `complete` section becomes the sole prompt section after cooperative assembly. agent-loop renders the assembled sections with `renderPrompt` and commits the text as a `system/message` surface node — appended as surface node 0 on the first step, then replaced in place when the rendered text changes or, when the prepared call declares `systemPromptUpdate: 'in-history'`, appended after the cached history for non-empty updates in a continuing series — so the prompt reaches the model as a message of derived history rather than as a request field ([decision](../../.agents/notes/implemented/architecture/2026-09-02-system-prompt-as-surface-node.md); [decision rule](../../packages/core/agent-loop/README.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
-}
-```
-
-## Dynamic prompt context
-
-`PromptContext` is the cache-safe counterpart to `PromptSection`. The assembly resolves and orders these contributions, while agent-loop logs their complete current snapshot after retained model history only when it changed or compaction removed it.
-
-```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` keeps an operational contribution when optional runtime context is suppressed. `interpolate: false` preserves literal text, including variable-like directory names. `AssembledContext` carries the resolved text and that interpolation choice into rendering.
-
-```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.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.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 -->