dsh-plugin-guide 0.3.42 → 0.4.1

package/references/official-docs/docs/subsystems/claude-code-mods.md

@@ -1,146 +0,0 @@
-# Claude Code mods: compatibility
-
-English | [中文](claude-code-mods.zh.md)
-
-Every way a mod behaves differently through this bridge than under Claude Code, as of Claude Code 2.1.287 ([mods reference](https://code.claude.com/docs/en/plugins/mods/reference), its `claude-code.d.ts`) and the [Getting started with Claude Code mods](https://claude.dev/blog/getting-started-with-claude-code-mods/) post of 2026-10-01. A row names the Claude Code behavior, what this bridge does, and the reason or the follow-up. Anything not listed here behaves as the reference describes; a hook on an event this host never raises is named in a warning when the mod loads, and a `$` call outside the served table rejects with `no implementation for <namespace>.<method>`.
-
-## Packaging and loading
-
-| Claude Code | This bridge | Reason or follow-up |
-|---|---|---|
-| A plugin directory with `.claude-plugin/plugin.json` and `hooks/hooks.json` naming one hooks module; `claude --plugin-dir`, marketplaces, `/plugin install` | A mod is a plugin: `defineMod({ name, version, root, userConfig, register })` wraps the hooks module and mounts through cordis.yml after the bridge; `plugin.json` and `hooks.json` are not read | Mods join the one composition mechanism every DSH plugin uses; the example directories keep their manifests so they also run under `claude --plugin-dir` |
-| `userConfig` schema in `plugin.json` with typed defaults; options validated at load | `userConfig` is the defaults object of the `defineMod` spec; the plugin's cordis.yml `config` overlays it and is validated as a record of strings, numbers, booleans, and string lists | No manifest is read |
-| Tiers (`user`, `project`, `managed`) and `next.to(e, tier)` | Every mod loads as `user`; `tier()` in a test is accepted and ignored; `next.to` rejects | Managed settings are not a DSH concept |
-| Hot reload of the hooks module on edit; `claude plugin validate`, `claude plugin test`, types generation from `types/index.d.ts` | None of these commands; a remount re-runs `register` on the same evaluated module, so module-level variables keep their values | Follow-up only on demand; the test kit's `createModTestKit` replaces `claude plugin test` inside Vitest |
-| A hooks module may be TypeScript | A `.ts` hooks module loads only where the launcher transpiles (the source launch does; a built install does not) | DSH ships plain Node |
-| Mods run in-process with `$` as their only access to the host | The hooks module runs in-process with Node's globals, no access rule, and the process's full authority: `$.env` reads and writes the harness environment, `$.http.fetch` reaches any URL, `$.fs` and `$.tool.call` act as the session | No sandbox is applied to mods; mount only mods you would run as a plugin |
-| `import type { … } from 'claude-code'`, `declare module 'claude-code' { interface PluginState }` | The `claude-code` module name resolves only inside this repository's test setup, to the bridge's types; a mod outside it imports `@deepseek-ai/dsh-experimental-claude-code-mods` | The type names are the bridge's own |
-| `settings hooks` in `hooks.json` run beside mod hooks | Not run; mount `@deepseek-ai/dsh-hooks-claude-code` for them | Different bridge |
-
-## Events
-
-| Event | Claude Code | This bridge |
-|---|---|---|
-| `session.start` | Raised once per session, before the first prompt | Raised for a root agent from `agent/created`, awaited before its first turn; not raised for subagents |
-| `session.end` | Raised once per session | Raised for a root agent from `agent/disposed`; `$.state` is readable until the hooks settle |
-| `prompt.submit` | `e.text` is the typed prompt; `context` entries become one block each after the prompt as typed; a prompt a plugin submitted carries `origin: { kind: 'plugin', name }` | Same; `e.text` joins the text blocks of the human's own (`user`-sourced) messages in the claimed batch, a batch of injected context alone raises nothing, and a prompt `$.prompt.submit` queued carries the submitting mod as its origin |
-| `turn.start`, `turn.complete` | Per turn; subagent turns carry `agentId` | Same; `turn.complete`'s `{ text }` reaches the host log, not a line under the answer; `durationMs` counts from `turn/start` |
-| `tool.call` | Runs before Claude Code's permission check; `next({ ...e, command })` rewrites the arguments the tool runs with, and `next({ ...e, tool })` reroutes the call | Runs around `tools/execute`, after the harness permission decision; a hook (or `.catch` handler) that rewrites arguments or names another tool is skipped with a report — the argument case names the [pre-tool input rewrite proposal](../../.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md) — because the logged call runs as logged. `{ deny }`, `{ result }`, observing, and rewriting the result or `isError` after `next` work as described |
-| `command.run` | Runs for a command the mod registered | Same |
-| `ui.render` | Raised for every render site (`AbovePrompt`, `Pane`, `ToolUse`, `AssistantMessage`, `Spinner`, …) | Raised for `AbovePrompt` only, once per redraw of a session's band; `Pane` hooks run only through the test kit's `$.ui.mount({ component: 'Pane' })` |
-| `tool.check`, `tool.describe`, `tool.list`, `tool.register` | Shape the tool list and permissions | Not raised; `$.tool.register` and `$.tool.list` are served as `$` calls |
-| `turn.step` | Per model step | Not raised |
-| Every other reference event: the other `prompt.*` events, `skill.prompt`, `attribution.text`, `command.describe`, `config.*`, the other `session.*` events, `agent.*`, `plugin.register`, `engine.create`, `telemetry.*`, `ui.resolve`, `ui.press`, `ui.input`, `ui.select`, `ui.focus`, `ui.scroll`, `ui.close`, `ui.message` | Raised by the engine | Registered, never raised, named in a warning at load |
-| `classic.*` | Classic settings hooks as events | Refused at `register`, like any unknown event name |
-| `<namespace>.<method>` op events (`fs.read`, `store.set`, …) | A later-loaded mod's `$` call reaches the mods loaded before it | Same; `tool.call` arrives through the tool pipeline instead |
-
-## The chain
-
-| Claude Code | This bridge | Reason |
-|---|---|---|
-| A hook may call `next` more than once; each call runs the chain beneath again | `next` runs once: a second call returns the first run's result | One tool execution per logged call |
-| A hook that answers while its `next` is still running | The run beneath is awaited before the hook's answer settles; a failure beneath after the answer is reported | The event settles only when nothing it started is running |
-| 10 s own-time budget, 1 s for `.catch`, time inside `next` and `$` calls excluded except `$.clock.sleep` | Same, configurable (`hookTimeoutMs`, `catchTimeoutMs`) | — |
-| Not returning a result object is a failure | Same; `null` is accepted as an answer (a surface drawn empty) | `ui.render` with nothing to draw |
-| A result's unknown fields are dropped and wrong types fail the hook | A `prompt.submit` result with wrong types keeps the original text and only the string context lines | Lenient on the one event where partial results are common |
-
-## `$` members
-
-| Namespace | Claude Code | This bridge |
-|---|---|---|
-| `$.plugin` | `name`, `root`, `tier` | `name`, `root` from the `defineMod` spec |
-| `$.ui` | `resolve`, `invalidate`, `open`, `close`, `panes`, `focus`, `log`, `toast`, `status`, `notice`, `ask`, `blit`, `copy`, `press`, `input`, `select` | `resolve`, `invalidate`, `open`, `close`, `panes`, `log`, `toast`, `status`, `ask`; `open` answers `{ isPlaced: false }` with a reason and redraws the band; `log`, `toast`, `status` reach the host log; the rest reject |
-| `$.command` | `register`, `run`, `list` | Same; `run` of a command nobody answers rejects with the registering mod named |
-| `$.tool` | `register`, `call`, `list` | Same; a registered tool is `mcp__<plugin>__<tool>`; `call` runs the harness pipeline and injects a tool's deferred contexts into the session |
-| `$.prompt` | `submit`, `compose` | `submit`; the message is `user`-sourced, framed `Message from the "<plugin>" mod:` unless `asUser`, and the `prompt.submit` it raises names the mod as origin |
-| `$.session` | `id`, `cwd`, `root`, `repo`, `model`, `turns`, `messages`, `usage`, `version`, `send`, `append`, `authorize`, `compact`, `surfaces` | `id`, `cwd`, `root`, `model`, `turns`, `messages`, `usage`, `version`; `cwd` reports the committed current directory; `root` retains the original project; `usage.context.window` is `0` and `percent` absent until the token meter knows the route's window; `rateLimits` is empty; `version` names this bridge |
-| `$.state` | Per session, survives hot reload | Per session, in memory; a read during `ui.render` subscribes the band to the slot |
-| `$.store` | Per plugin, durable | Same, in the `claude_code_mods` storage domain, 4 MiB per plugin |
-| `$.clock` | `now`, `sleep`, `after`, `every`; timers die with the plugin | Same; a timer also dies with the session whose event scheduled it, and `sleep` rejects when the event is cancelled |
-| `$.fs` | `read`, `write`, `list`, `exists`, `stat`, `ancestors` | All but `ancestors`; 4 MiB per file; `stat.mtimeMs` is `0` |
-| `$.process` | `run`, `spawn` | `run` only, argv without a shell, `processTimeoutMs` default |
-| `$.http` | `fetch` | Same, bodies up to 4 MiB |
-| `$.env` | `get`, `set` | Same; the process environment is shared by every session and plugin |
-| `$.model`, `$.agent`, `$.config`, `$.settings`, `$.mcp`, `$.audio`, `$.telemetry`, `$.turn` | Served | Reject with `no implementation`; `$.model.complete` waits on a logged side-request event |
-
-## Drawing
-
-| Claude Code | This bridge |
-|---|---|
-| `Box`, `Text`, `Button`, `Input`, `Spacer`, and the host's own element kinds | `Box`, `Text`, `Button` from `$.ui.resolve(e)`; the tree is validated, and a `Button`'s `onPress` stays in the host behind a per-drawing action id |
-| `Box` props: `flexDirection`, `padding*`, `gap`, `border*`, `width`, `height`, `overflow`, `scroll` | `flexDirection`, `padding`, `paddingX`, `paddingY`, `gap`, `border`, `borderColor`; the others serialize and the Web band ignores them |
-| `Text` props: `color`, `bold`, `dimColor`, `italic`, `underline`, `wrap`, `truncate` | `color` (the terminal palette names), `bold`, `dimColor`, `italic`, `underline`; the Web band wraps |
-| `Button` props: `label`, `hotkey`, `disabled`, `onPress`; a bare digit arms the hotkey | `label`, `hotkey` (shown as a hint), `disabled`, `onPress` (a click) |
-| The band is one instance; `hasSurvey`, `isWorking`, `maxRows`, `bodyColumns` reflect the terminal | One instance per session, consulted in mod load order; `bodyColumns` and `viewport.columns` are the bridge's `bandColumns` (default `120`), `maxRows` its `bandRows` (default `10`), `hasSurvey` and `isWorking` are `false`; the Web band wraps instead of scrolling |
-| The band redraws on the host's frame and when a `$.state` value a render read changes | Redraws after `session.start`, when a `$.state` value the last drawing read is written, after `$.ui.open`, `$.ui.close`, `$.ui.invalidate`, after each `tool.call` chain and `turn.complete` settle, and after a press; a mod that changes module-level state at other times draws it at the next trigger. A press runs `onPress` without a time limit |
-| `Pane` with `focus`, `scroll`, docked beside the transcript | No pane: `$.ui.open` answers `{ isPlaced: false }` so a mod falls back to the band; the test kit mounts `Pane` hooks directly |
-| Hotkeys, `TextInput`, focus, scrolling, `ui.press`, `ui.input`, `ui.select` | Not served; follow-up |
-
-## Testing
-
-| `claude-code/testing` | This bridge |
-|---|---|
-| `describe`, `test(name, ($, on) => …)`, `expect`, `mock`, `tier` | Inside this repository the same module name provides them over Vitest; `test` infers the mod from the test file's location (`<mod>/tests/*.test.ts` → `<mod>/index.ts`) and `defineModTests` overrides it. Outside, `createModTestKit` and `mock` come from `@deepseek-ai/dsh-experimental-claude-code-mods/testing` |
-| `on` stubs the engine's answers; the kit answers `ui.*` itself | Same; `ui.open` answers `{ isPlaced: false }`, `ui.invalidate` and `ui.close` succeed; `session.cwd`, `process.run`, `fs.*`, `store.*`, `env.*` need a stub (`mock.store`, `mock.env`, `mock.clock` answer whole namespaces) |
-| `$.ui.mount({ plugin, surface, component, props })` → `find`, `findAll`, `press`, `unmount` | Same, plus `tree()` and `text()`; every read renders afresh through every loaded mod's hooks; `plugin` and `surface` are accepted for source compatibility |
-| 5 s hook budget in tests | Same (`budgetMs`) |
-
-## The example mods
-
-| Mod | Source | Through this bridge |
-|---|---|---|
-| Token Weather | The post's module, type contract, and test, unchanged | Runs as published; the test's three `as any` casts are dropped because the kit is typed. Draws in the band from `$.session.usage` through the token meter |
-| Blast Radius | The post's `tool.call` hook unchanged; `classify`, `measure`, and the trees completed to the post's description | Holds the command with real `sleep` polls, draws the report in the band (`isPlaced: false`), and Proceed or Cancel decides; load it before Token Weather |
-| Replay Theater | The post's five hooks unchanged; `stepsFor`, the diff, `openReplay`, the pane and the hint completed | Records Edit and Write calls, hints in the band after the turn, and steps through the diffs in the band because no pane is placed |
-| `diff` ([anthropics/claude-code](https://github.com/anthropics/claude-code/tree/main/mods/diff), read at `52c7644`) | TypeScript, ~570 files, hooks `command.run`, `prompt.submit`, `session.start`, `tool.call`, `ui.close`, `ui.focus`, `ui.render`, `ui.scroll` | Not runnable: needs `$.settings.read`, `$.telemetry.*`, `$.session.messages` over a pane, `ui.focus` and `ui.scroll` events, and a placed `Pane`. Assessed by reading; the repository's terms do not allow a fixture copy |
-| `agents-md` (same repository) | Hooks `agent.spawn`, `prompt.context`, `session.start`, `tool.call` | Not runnable: `prompt.context` and `agent.spawn` are not raised and `$.fs.ancestors`, `$.telemetry.*` are not served |
-| `sec-default` (same repository) | Hooks `tool.check`, `prompt.compose`, `settings.read`, `classic.*`, `plugin.register`, … | Not runnable: managed-tier policy over events this host does not raise |
-| `telemetry` (same repository) | Hooks `engine.create`, `telemetry.*`, `session.start`, `session.end`; calls `$.session.repo`, `$.settings.read` | Not runnable: `telemetry.*` and `engine.create` are not raised and the two `$` members are not served |
-
-<!-- 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="ctxclaudecodemods--claudecodemods"></a>
-
-### `ctx.claudeCodeMods` — `ClaudeCodeMods`
-
-The bridge service: loaded mods, their hooks, and the harness listeners that raise their events. Mods join through ClaudeCodeMods.add, which defineMod calls when a mod plugin mounts. The Remote methods let a Client draw each session's band above the prompt and press its buttons.
-
-```ts cordis-catalog
-/**
- * Watch the band above the prompt of one session: the current drawing, then
- * every redraw, until the Client stops watching.
- * @param agent - the session's agent, resolved by the Gateway.
- * @param signal - carrier cancellation.
- * @returns the band's snapshots.
- */
-@Remote({ mode: 'stream' }) watchBand(agent: Agent, signal: AbortSignal): AsyncIterable<SurfaceSnapshot>
-
-/**
- * Press a button of the band's current drawing: runs the mod's `onPress` and redraws.
- * @param agent - the session's agent, resolved by the Gateway.
- * @param generation - the drawing the Client saw.
- * @param actionId - the button's action id in that drawing.
- * @returns the snapshot after the press.
- */
-@Remote pressBand(agent: Agent, generation: number, actionId: string): Promise<SurfaceSnapshot>
-
-/**
- * Load one mod beneath every mod loaded before it: run its `register`,
- * keep its hooks, and report which of its events this host never raises.
- * @param definition - the mod as its plugin defined it.
- * @returns the disposer that removes the mod's hooks, closes its timers, and releases its registrations.
- * @throws Error when the name is invalid or taken, or when `register` throws (Claude Code's `hooks module did not load` wording).
- */
-async add(definition: ModDefinition): Promise<() => Promise<void>>
-```
-
-Types: [Agent](core.md)
-
-Source: [`packages/experimental/claude-code-mods/src/index.ts`](../../packages/experimental/claude-code-mods/src/index.ts)
-<!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/claude-code-mods.zh.md

@@ -1,146 +0,0 @@
-# Claude Code 模组：兼容性
-
-[English](claude-code-mods.md) | 中文
-
-模组经本桥接运行时与在 Claude Code 下行为不同的每一处，基准为 Claude Code 2.1.287（[模组参考](https://code.claude.com/docs/en/plugins/mods/reference)及其 `claude-code.d.ts`）与 2026-10-01 的 [Getting started with Claude Code mods](https://claude.dev/blog/getting-started-with-claude-code-mods/) 一文。每行给出 Claude Code 的行为、本桥接的做法，以及原因或后续工作。未列出的一切均按参考文档描述的方式运行；对本宿主永不触发的事件注册钩子会在模组加载时以警告点名，服务表之外的 `$` 调用以 `no implementation for <namespace>.<method>` 拒绝。
-
-## 打包与加载
-
-| Claude Code | 本桥接 | 原因或后续 |
-|---|---|---|
-| 一个插件目录，含 `.claude-plugin/plugin.json` 与指定一个钩子模块的 `hooks/hooks.json`；`claude --plugin-dir`、市场、`/plugin install` | 模组就是插件：`defineMod({ name, version, root, userConfig, register })` 包装钩子模块，并在桥接之后经 cordis.yml 挂载；不读取 `plugin.json` 与 `hooks.json` | 模组加入每个 DSH 插件都使用的同一组合机制；示例目录保留其清单，因此也能在 `claude --plugin-dir` 下运行 |
-| `plugin.json` 中带类型默认值的 `userConfig` schema；选项在加载时校验 | `userConfig` 是 `defineMod` 规格的默认值对象；插件的 cordis.yml `config` 覆盖其上，并按字符串、数字、布尔与字符串列表的记录校验 | 不读取清单 |
-| 层级（`user`、`project`、`managed`）与 `next.to(e, tier)` | 每个模组都以 `user` 加载；测试中的 `tier()` 被接受并忽略；`next.to` 拒绝 | 托管设置不是 DSH 的概念 |
-| 编辑时热重载钩子模块；`claude plugin validate`、`claude plugin test`、由 `types/index.d.ts` 生成类型 | 这些命令都没有；重新挂载会在同一已求值模块上重新运行 `register`，模块级变量保留其值 | 仅按需跟进；测试工具包的 `createModTestKit` 在 Vitest 中替代 `claude plugin test` |
-| 钩子模块可以是 TypeScript | `.ts` 钩子模块只在启动器转译时可加载（源码启动可以；构建后的安装不行） | DSH 交付的是纯 Node |
-| 模组在进程内运行，`$` 是其访问宿主的唯一途径 | 钩子模块以 Node 全局对象在进程内运行，没有访问规则，并拥有进程的全部权限：`$.env` 读写 harness 环境变量，`$.http.fetch` 可访问任意 URL，`$.fs` 与 `$.tool.call` 以会话的身份行动 | 不对模组施加沙箱；只挂载你愿意作为插件运行的模组 |
-| `import type { … } from 'claude-code'`、`declare module 'claude-code' { interface PluginState }` | `claude-code` 模块名只在本仓库的测试设置中解析到桥接的类型；仓库外的模组导入 `@deepseek-ai/dsh-experimental-claude-code-mods` | 类型名是桥接自己的 |
-| `hooks.json` 中的设置钩子与模组钩子并行运行 | 不运行；为它们挂载 `@deepseek-ai/dsh-hooks-claude-code` | 不同的桥接 |
-
-## 事件
-
-| 事件 | Claude Code | 本桥接 |
-|---|---|---|
-| `session.start` | 每会话触发一次，在首个提示词之前 | 由根智能体的 `agent/created` 触发，在其首轮之前等待完成；不为子智能体触发 |
-| `session.end` | 每会话触发一次 | 由根智能体的 `agent/disposed` 触发；钩子结束前 `$.state` 可读 |
-| `prompt.submit` | `e.text` 是输入的提示词；`context` 条目各成一块跟在输入的提示词之后；插件提交的提示词带 `origin: { kind: 'plugin', name }` | 相同；`e.text` 拼接已认领批次中人类自己（`user` 来源）消息的文本块，仅含注入上下文的批次不触发，`$.prompt.submit` 排入的提示词以提交的模组为来源 |
-| `turn.start`、`turn.complete` | 每轮触发；子智能体的轮带 `agentId` | 相同；`turn.complete` 的 `{ text }` 到达宿主日志，而非答案下方的一行；`durationMs` 从 `turn/start` 起算 |
-| `tool.call` | 在 Claude Code 的权限检查之前运行；`next({ ...e, command })` 改写工具实际运行的参数，`next({ ...e, tool })` 把调用改派给另一工具 | 包裹 `tools/execute` 运行，在 harness 权限决定之后；改写参数或改名工具的钩子（或 `.catch` 处理器）会被跳过并报告——参数情形指向[工具前输入改写提案](../../.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.zh.md)——因为已写入日志的调用按原样运行。`{ deny }`、`{ result }`、观察以及在 `next` 之后改写结果或 `isError` 均按描述工作 |
-| `command.run` | 为模组注册的命令运行 | 相同 |
-| `ui.render` | 为每个渲染位点触发（`AbovePrompt`、`Pane`、`ToolUse`、`AssistantMessage`、`Spinner`……） | 只为 `AbovePrompt` 触发，每次会话横幅重绘一次；`Pane` 钩子只经测试工具包的 `$.ui.mount({ component: 'Pane' })` 运行 |
-| `tool.check`、`tool.describe`、`tool.list`、`tool.register` | 塑造工具列表与权限 | 不触发；`$.tool.register` 与 `$.tool.list` 作为 `$` 调用服务 |
-| `turn.step` | 每个模型步骤 | 不触发 |
-| 参考中的其他所有事件：其他 `prompt.*` 事件、`skill.prompt`、`attribution.text`、`command.describe`、`config.*`、其他 `session.*` 事件、`agent.*`、`plugin.register`、`engine.create`、`telemetry.*`、`ui.resolve`、`ui.press`、`ui.input`、`ui.select`、`ui.focus`、`ui.scroll`、`ui.close`、`ui.message` | 由引擎触发 | 可注册，永不触发，在加载时以警告点名 |
-| `classic.*` | 经典设置钩子作为事件 | 在 `register` 时拒绝，与任何未知事件名相同 |
-| `<namespace>.<method>` 操作事件（`fs.read`、`store.set`……） | 更晚加载的模组的 `$` 调用到达在它之前加载的模组 | 相同；`tool.call` 则经由工具流水线到达 |
-
-## 链
-
-| Claude Code | 本桥接 | 原因 |
-|---|---|---|
-| 钩子可多次调用 `next`；每次调用都再次运行下层链 | `next` 只运行一次：第二次调用返回第一次运行的结果 | 每条写入日志的调用只执行一次工具 |
-| 钩子在其 `next` 仍在运行时作答 | 下层运行会在钩子答案落定前被等待；答案之后的下层失败会被报告 | 事件只在其启动的一切都结束后落定 |
-| 自身时间预算 10 秒，`.catch` 为 1 秒，`next` 与 `$` 调用内的时间不计，`$.clock.sleep` 除外 | 相同，可配置（`hookTimeoutMs`、`catchTimeoutMs`） | — |
-| 不返回结果对象视为失败 | 相同；`null` 被接受为答案（绘制为空的表面） | 无可绘制内容的 `ui.render` |
-| 结果中的未知字段被丢弃，类型错误使钩子失败 | 类型错误的 `prompt.submit` 结果保留原文本，并只取字符串形式的 context 行 | 对这一常见部分结果的事件从宽处理 |
-
-## `$` 成员
-
-| 命名空间 | Claude Code | 本桥接 |
-|---|---|---|
-| `$.plugin` | `name`、`root`、`tier` | 来自 `defineMod` 规格的 `name`、`root` |
-| `$.ui` | `resolve`、`invalidate`、`open`、`close`、`panes`、`focus`、`log`、`toast`、`status`、`notice`、`ask`、`blit`、`copy`、`press`、`input`、`select` | `resolve`、`invalidate`、`open`、`close`、`panes`、`log`、`toast`、`status`、`ask`；`open` 带原因回答 `{ isPlaced: false }` 并重绘横幅；`log`、`toast`、`status` 到达宿主日志；其余拒绝 |
-| `$.command` | `register`、`run`、`list` | 相同；`run` 一个无人回答的命令时拒绝，并点名注册它的模组 |
-| `$.tool` | `register`、`call`、`list` | 相同；注册的工具为 `mcp__<plugin>__<tool>`；`call` 运行 harness 流水线，并把工具推迟的上下文注入会话 |
-| `$.prompt` | `submit`、`compose` | `submit`；消息为 `user` 来源，除非 `asUser` 否则套上 `Message from the "<plugin>" mod:` 框架，它触发的 `prompt.submit` 以该模组为来源 |
-| `$.session` | `id`、`cwd`、`root`、`repo`、`model`、`turns`、`messages`、`usage`、`version`、`send`、`append`、`authorize`、`compact`、`surfaces` | `id`、`cwd`、`root`、`model`、`turns`、`messages`、`usage`、`version`；`cwd` 报告已提交的当前目录；`root` 保留原始项目；在 token 计量器得知路由窗口前 `usage.context.window` 为 `0` 且无 `percent`；`rateLimits` 为空；`version` 指明本桥接 |
-| `$.state` | 按会话，热重载后保留 | 按会话，内存中；`ui.render` 期间的读取让横幅订阅该槽位 |
-| `$.store` | 按插件，持久 | 相同，在 `claude_code_mods` 存储域中，每插件 4 MiB |
-| `$.clock` | `now`、`sleep`、`after`、`every`；定时器随插件消亡 | 相同；定时器还随安排它的事件所属会话消亡，事件取消时 `sleep` 拒绝 |
-| `$.fs` | `read`、`write`、`list`、`exists`、`stat`、`ancestors` | 除 `ancestors` 外全部；每文件 4 MiB；`stat.mtimeMs` 为 `0` |
-| `$.process` | `run`、`spawn` | 仅 `run`，不经 shell 的 argv，默认 `processTimeoutMs` |
-| `$.http` | `fetch` | 相同，正文最多 4 MiB |
-| `$.env` | `get`、`set` | 相同；进程环境由所有会话与插件共享 |
-| `$.model`、`$.agent`、`$.config`、`$.settings`、`$.mcp`、`$.audio`、`$.telemetry`、`$.turn` | 已服务 | 以 `no implementation` 拒绝；`$.model.complete` 等待一个写入日志的副请求事件 |
-
-## 绘制
-
-| Claude Code | 本桥接 |
-|---|---|
-| `Box`、`Text`、`Button`、`Input`、`Spacer` 以及宿主自己的元素种类 | 来自 `$.ui.resolve(e)` 的 `Box`、`Text`、`Button`；树经校验，`Button` 的 `onPress` 留在宿主中，位于按绘制分配的动作 id 之后 |
-| `Box` 属性：`flexDirection`、`padding*`、`gap`、`border*`、`width`、`height`、`overflow`、`scroll` | `flexDirection`、`padding`、`paddingX`、`paddingY`、`gap`、`border`、`borderColor`；其余会序列化，Web 横幅忽略 |
-| `Text` 属性：`color`、`bold`、`dimColor`、`italic`、`underline`、`wrap`、`truncate` | `color`（终端调色板名）、`bold`、`dimColor`、`italic`、`underline`；Web 横幅会换行 |
-| `Button` 属性：`label`、`hotkey`、`disabled`、`onPress`；单个数字键触发热键 | `label`、`hotkey`（显示为提示）、`disabled`、`onPress`（点击） |
-| 横幅是一个实例；`hasSurvey`、`isWorking`、`maxRows`、`bodyColumns` 反映终端 | 每会话一个实例，按模组加载顺序咨询；`bodyColumns` 与 `viewport.columns` 取桥接的 `bandColumns`（默认 `120`），`maxRows` 取 `bandRows`（默认 `10`），`hasSurvey` 与 `isWorking` 为 `false`；Web 横幅换行而非滚动 |
-| 横幅随宿主帧重绘，并在渲染读取过的 `$.state` 值变化时重绘 | 在 `session.start` 之后、上次绘制读取过的 `$.state` 值被写入时、在 `$.ui.open`、`$.ui.close`、`$.ui.invalidate` 之后、在每条 `tool.call` 链与 `turn.complete` 结束后以及按下之后重绘；在其他时刻改变模块级状态的模组在下一次触发时绘出。按下运行 `onPress` 时没有时间限制 |
-| 带 `focus`、`scroll`、停靠在对话旁的 `Pane` | 没有面板：`$.ui.open` 回答 `{ isPlaced: false }`，模组回退到横幅；测试工具包直接挂载 `Pane` 钩子 |
-| 热键、`TextInput`、焦点、滚动、`ui.press`、`ui.input`、`ui.select` | 不服务；后续工作 |
-
-## 测试
-
-| `claude-code/testing` | 本桥接 |
-|---|---|
-| `describe`、`test(name, ($, on) => …)`、`expect`、`mock`、`tier` | 在本仓库内同一模块名基于 Vitest 提供它们；`test` 从测试文件位置推断模组（`<mod>/tests/*.test.ts` → `<mod>/index.ts`），`defineModTests` 可覆盖。仓库外则从 `@deepseek-ai/dsh-experimental-claude-code-mods/testing` 获取 `createModTestKit` 与 `mock` |
-| `on` 为引擎的答案打桩；工具包自行回答 `ui.*` | 相同；`ui.open` 回答 `{ isPlaced: false }`，`ui.invalidate` 与 `ui.close` 成功；`session.cwd`、`process.run`、`fs.*`、`store.*`、`env.*` 需要桩（`mock.store`、`mock.env`、`mock.clock` 回答整个命名空间） |
-| `$.ui.mount({ plugin, surface, component, props })` → `find`、`findAll`、`press`、`unmount` | 相同，另有 `tree()` 与 `text()`；每次读取都经所有已加载模组的钩子重新渲染；`plugin` 与 `surface` 为源码兼容而接受 |
-| 测试中钩子预算 5 秒 | 相同（`budgetMs`） |
-
-## 示例模组
-
-| 模组 | 来源 | 经本桥接 |
-|---|---|---|
-| Token Weather | 文中的模块、类型契约与测试，原样 | 按发布原样运行；测试中的三处 `as any` 转换因工具包带类型而去掉。通过 token 计量器从 `$.session.usage` 在横幅中绘制 |
-| Blast Radius | 文中的 `tool.call` 钩子原样；`classify`、`measure` 与树按文中描述补全 | 以真实的 `sleep` 轮询持有命令，在横幅中绘制报告（`isPlaced: false`），由 Proceed 或 Cancel 决定；请加载在 Token Weather 之前 |
-| Replay Theater | 文中的五个钩子原样；`stepsFor`、差异、`openReplay`、面板与提示补全 | 记录 Edit 与 Write 调用，轮结束后在横幅中提示，并因无面板放置而在横幅中逐步浏览差异 |
-| `diff`（[anthropics/claude-code](https://github.com/anthropics/claude-code/tree/main/mods/diff)，于 `52c7644` 阅读） | TypeScript，约 570 个文件，钩住 `command.run`、`prompt.submit`、`session.start`、`tool.call`、`ui.close`、`ui.focus`、`ui.render`、`ui.scroll` | 不可运行：需要 `$.settings.read`、`$.telemetry.*`、面板上的 `$.session.messages`、`ui.focus` 与 `ui.scroll` 事件以及已放置的 `Pane`。以阅读方式评估；该仓库的条款不允许复制夹具 |
-| `agents-md`（同一仓库） | 钩住 `agent.spawn`、`prompt.context`、`session.start`、`tool.call` | 不可运行：`prompt.context` 与 `agent.spawn` 不触发，`$.fs.ancestors`、`$.telemetry.*` 不服务 |
-| `sec-default`（同一仓库） | 钩住 `tool.check`、`prompt.compose`、`settings.read`、`classic.*`、`plugin.register`…… | 不可运行：基于本宿主不触发的事件的托管层策略 |
-| `telemetry`（同一仓库） | 钩住 `engine.create`、`telemetry.*`、`session.start`、`session.end`；调用 `$.session.repo`、`$.settings.read` | 不可运行：`telemetry.*` 与 `engine.create` 不触发，两个 `$` 成员不服务 |
-
-<!-- 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="ctxclaudecodemods--claudecodemods"></a>
-
-### `ctx.claudeCodeMods` — `ClaudeCodeMods`
-
-The bridge service: loaded mods, their hooks, and the harness listeners that raise their events. Mods join through ClaudeCodeMods.add, which defineMod calls when a mod plugin mounts. The Remote methods let a Client draw each session's band above the prompt and press its buttons.
-
-```ts cordis-catalog
-/**
- * Watch the band above the prompt of one session: the current drawing, then
- * every redraw, until the Client stops watching.
- * @param agent - the session's agent, resolved by the Gateway.
- * @param signal - carrier cancellation.
- * @returns the band's snapshots.
- */
-@Remote({ mode: 'stream' }) watchBand(agent: Agent, signal: AbortSignal): AsyncIterable<SurfaceSnapshot>
-
-/**
- * Press a button of the band's current drawing: runs the mod's `onPress` and redraws.
- * @param agent - the session's agent, resolved by the Gateway.
- * @param generation - the drawing the Client saw.
- * @param actionId - the button's action id in that drawing.
- * @returns the snapshot after the press.
- */
-@Remote pressBand(agent: Agent, generation: number, actionId: string): Promise<SurfaceSnapshot>
-
-/**
- * Load one mod beneath every mod loaded before it: run its `register`,
- * keep its hooks, and report which of its events this host never raises.
- * @param definition - the mod as its plugin defined it.
- * @returns the disposer that removes the mod's hooks, closes its timers, and releases its registrations.
- * @throws Error when the name is invalid or taken, or when `register` throws (Claude Code's `hooks module did not load` wording).
- */
-async add(definition: ModDefinition): Promise<() => Promise<void>>
-```
-
-Types: [Agent](core.zh.md)
-
-Source: [`packages/experimental/claude-code-mods/src/index.ts`](../../packages/experimental/claude-code-mods/src/index.ts)
-<!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/client-modules.i18n.yaml

@@ -1,19 +0,0 @@
-# Bilingual-pair consistency record for client-modules.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/client-modules.md
-/client-modules:
-  en: e256a29cc5bc2726
-  zh: e181d6b1a6e5c647
-/client-modules/the-wire:
-  en: 96b95cdb015c1af6
-  zh: 01e4144d91551c13
-/client-modules/the-scan:
-  en: 91ce66fab388a8a2
-  zh: 77428943582ae3f6
-/client-modules/the-bundle-route-and-index-injection:
-  en: d653be500d3a0d67
-  zh: fffb1901ce8ba7d9
-/client-modules/the-service:
-  en: 000882ed7f09ad3f
-  zh: c17c05f087d9574d

package/references/official-docs/docs/subsystems/client-modules.md

@@ -1,198 +0,0 @@
-# Client Modules
-
-English | [中文](client-modules.zh.md)
-
-The web plugin table: the Node half of the client module system in [dsh-client-modules](../../packages/client/modules), provided as `ctx.clientModules` (`ClientModuleRegistry`). It scans the host Loader's entries for packages declaring `dsh.client`, composes the `window.__DSH_BOOT__` entry graph, serves versioned one-or-more-resource combo scripts under `/plugins`, and answers every index-injection collection with the boot protocol rows — the four faces of one service. It is an optional capability of the web GUI stack, not part of the agent-loop spine, and it is a consumer of [dsh-host-webserver](../../packages/host/webserver): the carrier described in [web-server.md](web-server.md) supplies the prefix route and the `webserver/index-inject` event this service answers. The same package's browser half (`ctx.modules`, the lazy-CJS module table that fetches and materializes these bundles) is kernel machinery documented in the [package README](../../packages/client/modules/README.md), not here.
-
-Source: [`packages/client/modules/src/client/manifest.ts`](../../packages/client/modules/src/client/manifest.ts)
-
-## The wire
-
-The graph is the wire single source between the Node and browser halves. The host composes `WebBootEntry` rows and `WebBootBatch` descriptors from scanned packages, then contributes the registration facade, application preloads, bootstrap scripts, and graph global to the structured index-injection table before the Vite entry. The `global` row renders as `globalThis["__DSH_BOOT__"]` with `<` escaped so plugin-controlled strings cannot break out of the script element. A page without a valid manifest cannot boot: the browser parser rejects malformed rows or batches, unknown members, and entries without exactly one initial combo descriptor.
-
-```ts type-equiv
-/**
- * One composed client entry pushed by the host (a graph row). Wire
- * single source: the host node half (package root) produces this same shape.
- * `immediately` marks stage-one prefetch. `inject` names package rows whose
- * factories must arrive before this row materializes, while Cordis separately
- * uses the same package edges to compose entries. `external` carries exact
- * non-inject module requests (see {@link WebBootGraph.entries}).
- */
-interface WebBootEntry {
-  /** Entry name == package name. */
-  id: string
-  /**
-   * Revisioned single-resource combo reference used by HMR. It is relative to
-   * the document, so the browser resolves it under whatever mount served the page.
-   */
-  url: string
-  /** Opaque plugin-artifact revision used for HMR cache busting. */
-  rev: string
-  /** Package-name dependency edges used for factory arrival and plugin composition. */
-  inject?: string[]
-  /** Stage-one prefetch mark: load the script for factory registration during module-face boot. */
-  immediately?: boolean
-  /** Non-baseline module specifiers this row requests; omitted when it requests none. */
-  external?: string[]
-}
-```
-
-```ts type-equiv
-/** Initial scheduling phase for one revisioned combo script. */
-type WebBootBatchPhase = 'bootstrap' | 'application'
-```
-
-```ts type-equiv
-/** One initial combo script; a scheduling phase may span several descriptors. */
-interface WebBootBatch {
-  /** Parser-blocking bootstrap or preloaded application scheduling. */
-  phase: WebBootBatchPhase
-  /** Content-addressed combo script reference, document-relative like {@link WebBootEntry.url}. */
-  url: string
-  /** Revision derived from the ordered entry revisions. */
-  rev: string
-  /** Graph entry ids whose factories the script registers, in execution order. */
-  entries: string[]
-}
-```
-
-```ts type-equiv
-/** Host release identity; two releases are the same when both fields are equal. */
-interface WebBootRelease {
-  /** Release version label. */
-  version: string
-  /** Source commit fixed in when the Host was built; absent when the build recorded none. */
-  commit?: string
-}
-```
-
-```ts type-equiv
-/** The composed client entry graph the host injects as `window.__DSH_BOOT__`. */
-interface WebBootGraph {
-  /** Consistency anchor over the current entry and batch descriptors. */
-  rev: string
-  /** Host release identity; absent from a Host that publishes none. */
-  release?: WebBootRelease
-  /**
-   * Composed entries in module-graph order — a dynamic package row precedes
-   * rows whose `external` requests that package. Cordis activation order is
-   * unrelated and remains owned by fiber service waiting.
-   */
-  entries: WebBootEntry[]
-  /** Initial combo descriptors; every entry belongs to exactly one descriptor. */
-  batches: WebBootBatch[]
-}
-```
-
-Initial publication and HMR derive each row's `rev` from the entry's mtime, ctime, and size, without hashing executable bytes. The same artifacts retain their revisions across Host restarts. The initial descriptors partition rows into bootstrap and application scheduling phases, and either phase may contain several descriptors. Their URLs contain only the ordered package-resource list and a revision derived from those row revisions; phase names do not enter the route. Graph composition preserves row order while greedily splitting before the map-form URL exceeds 3 KiB, without concatenating scripts or reading maps. The graph revision hashes the entry and batch descriptors. `immediately` marks the stage-one registration barrier; rows within one combo share its script transport, while separate combos load independently.
-
-`release` pairs this package's version with the source commit the client build fixes into the built Host artifact, and stays outside the graph revision. A page applies graphs and rebuilt frames only while the Host serves the page's boot release; another release waits for a page reload ([Host release changes](../../packages/client/modules/README.md#host-release-changes)).
-
-## The scan
-
-A package joins the table by declaring `dsh.client` (`platform: 'web'`, optional `inject` edges, optional `immediately`) in its package.json and exporting its built bundle at `exports["./client"]`. Each live row resolves from its own Loader specifier and owning-tree `baseUrl`, through the same `loader.internal.resolveSync` implementation that imports its Host face when available. The nearest owning package manifest supplies the browser module id, so relative source and built overlays retain the package identity. Distinct active Loader sources resolving to one package name fail composition; after one source unloads, the surviving source supplies the row without a fiber restart.
-
-Scanning is incremental per package; there is no full-rescan code path. Every cordis `internal/plugin` emission (fiber construction or disposal) marks the fiber's entry name dirty, and a microtask flush reconciles each dirty name against the live loader entries. The activation pass seeds the same dirty set with all current entries and flushes synchronously, so first scan and steady state share one implementation — with opposite failure postures. At activation, a malformed declaration or missing bundle among the already-loaded entries aggregates into one loud `AggregateError` listing every broken package: the fiber FAILS and the boot's fail-loud sweep reports it. In steady state, a broken package logs a warning and must not poison the others.
-
-Package metadata — including the negative "not a client package" verdict — is cached per Loader specifier and owning-tree base URL until restart. A fiber restart from the same source reuses its row and rev untouched; bundle content changes reach the graph only through `rebuilt()`.
-
-## The bundle route and index injection
-
-`GET`/`HEAD /plugins/??<package-a>/client.js,<package-b>/client.js&rev=<rev>` addresses one generated combo script; a one-resource request uses the same form and is the HMR path. The script is concatenated once on its first `GET` and ends with a `sourceMappingURL` that carries the combo query alone — `??<package-a>/client.js.map,<package-b>/client.js.map&rev=<rev>`, resolved against the script's own directory rather than the document. The map files are not read by startup, index rendering, script `GET`, or `HEAD`; the first map `GET` reads and validates them, composes one Indexed Source Map v3, and caches that body. An authored component map supplies its section; a component without one receives an identity section whose `sourcesContent` is the captured bundle and whose source name is its packaged `sourceURL` or plugin route. Every startup request URL is at most 3 KiB measured as UTF-8 bytes; partitioning uses the longer map form. All application URLs are preloaded, and all bootstrap URLs execute before the graph global and Vite entry. Materialized responses use long-lived immutable caching. Unknown or altered resource lists, missing revisions, and stale revisions answer 404 rather than serving different bytes or letting the SPA fallback return HTML as JavaScript; other methods are 405. The injection rows carry the current graph on every index render, so a reload always boots against the live composition.
-
-## The service
-
-```ts type-equiv
-/** Filesystem baseline captured before a client artifact snapshot is read. */
-interface ClientArtifactBaseline {
-  /** Absolute path of the client bundle. */
-  readonly path: string
-  /** Bundle modification time in milliseconds. */
-  readonly mtimeMs: number
-  /** Bundle status-change time in milliseconds, including writes that preserve mtime. */
-  readonly ctimeMs: number
-  /** Bundle size in bytes. */
-  readonly size: number
-}
-```
-
-`ClientModuleRegistry` (`ctx.clientModules`, defined in [`packages/client/modules/src/index.ts`](../../packages/client/modules/src/index.ts)) exposes reads and the rebuild face; signatures are in the generated [service catalog](#ctxclientmodules--clientmoduleregistry). `graph()` returns the current composed graph (a stable object between changes), `clientPath(id)` returns the bundle's absolute path, and `artifactBaseline(id)` returns the bundle stat values captured before the current snapshot was read. `fetchBundle()` resolves the same lazy response used by the HTTP route. `rebuilt(id)` is the only entry point through which changed bundle content reaches the graph: it derives the revision from filesystem metadata, and only a revision change reads the new bytes, recomposes the graph, and notifies. `onRebuilt` fires per changed bundle with the new revision; `onGraphChanged` fires after any flush that recomposed the graph (row added or removed, or a rebuilt revision change) and is pull-model — listeners re-read `graph()`. Both notification paths contain listener exceptions so one throwing subscriber cannot skip later subscribers or kill whatever triggered the flush.
-
-[`dsh-client-hmr`](../../packages/client/hmr/README.md) delivers live graph snapshots in the shipped Web composition. The Host forwards existing graph-change notifications immediately, and reconnect sends the current full graph. A graph describes desired browser entries without asserting that Host cleanup has completed. Its artifact poll separately reports rebuilt revisions. Source-map changes alone do not trigger a reload; a new combo-map URL appears only after a bundle revision changes, and each map body is fixed by its first `GET`. Client Modules validates snapshots and serializes reconciliation with those rebuilds; it owns the boot-created entry map, single-resource arrivals, asynchronous removal, unused-module/style cleanup and page-local retry status. Static platform modules and the bootstrap retain their page lifetime; Electron installation is a separate flow.
-
-<!-- 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="ctxclientmodules--clientmoduleregistry"></a>
-
-### `ctx.clientModules` — `ClientModuleRegistry`
-
-The web plugin table service: incremental `dsh.client` scan + wire composition + bundle route + index injection rows. Construction runs the activation scan synchronously — a malformed declaration or missing bundle among the already-loaded entries aggregates into one loud throw (FAILED fiber; the boot activation audit reports it).
-
-```ts cordis-catalog
-/**
- * Current composed entry graph (stable object between changes).
- * @returns the graph served as `window.__DSH_BOOT__`.
- */
-graph(): WebBootGraph
-
-/**
- * Absolute path of an entry's client bundle.
- * @param id - entry id (package name).
- * @returns the path, or undefined for an unknown id.
- */
-clientPath(id: string): string | undefined
-
-/**
- * Serve an advertised revisioned bundle or source map without a Web server.
- * Unknown URLs return 404, unsupported methods return 405, and `HEAD`
- * returns the same immutable headers without materializing a body. Each body
- * is built once on its first `GET`; script construction never reads maps.
- * @param request - shell-carrier request for a `/plugins` resource.
- * @returns the exact response also exposed by the optional Web route.
- */
-async fetchBundle(request: Request): Promise<Response>
-
-/**
- * Filesystem baseline captured before an entry's current bytes were read.
- * HMR compares it with the live files when installing a watch, so a write
- * between startup composition and watch installation cannot disappear into
- * the watcher's initial state.
- * @param id - entry id (package name).
- * @returns the path and baseline, or undefined for an unknown id.
- */
-artifactBaseline(id: string): ClientArtifactBaseline | undefined
-
-/**
- * Publish one completed bundle generation (the HMR watch's registration
- * hook — the only entry point through which build changes reach the graph).
- * Unchanged mtime, ctime and size preserve the graph without reading the bundle.
- * @param id - entry id (package name).
- * @returns the current artifact rev, or undefined for an unknown id.
- */
-rebuilt(id: string): string | undefined
-
-/**
- * Subscribe to bundle rebuilds; fires only when artifact metadata changes the rev.
- * @param listener - receives the entry id and its new bundle rev.
- * @returns the unsubscriber.
- */
-onRebuilt(listener: (id: string, rev: string) => void): () => void
-
-/**
- * Fires after any flush that recomposed the graph (row added/removed, or a
- * rebuilt rev change). Pull model: listeners re-read {@link graph}.
- * @param listener - notified with no payload.
- * @returns the unsubscriber.
- */
-onGraphChanged(listener: () => void): () => void
-```
-
-Source: [`packages/client/modules/src/index.ts`](../../packages/client/modules/src/index.ts)
-<!-- END GENERATED cordis-surface -->