@xrkseek/harness 0.6.23 → 0.7.0-rc.1

package/node_modules/@xrkseek/claude-code-mods/README.md

@@ -0,0 +1,152 @@
+# @xrkseek/claude-code-mods
+
+Run **Claude Code plugins (mods)** inside this harness: read
+`.claude-plugin/plugin.json` + `hooks/hooks.json`, import the hook modules with
+the native ESM loader, run their `register(on)` handlers as one middleware
+chain, and serve the `$` API from our own tool pipeline and services.
+
+A plugin author changes nothing — you ship the same directory that
+`claude --plugin-dir` accepts.
+
+```
+my-plugin/
+  .claude-plugin/plugin.json     { "name": "my-plugin", "version": "0.1.0" }
+  hooks/hooks.json               { "modules": ["./my-plugin.mjs"] }
+  hooks/my-plugin.mjs            export function register(on) { … }
+```
+
+## Use
+
+The shipped runtime (`core-agent` / `core-tools`, no Cordis container in the
+request path) uses `createModsRuntime`:
+
+```ts
+import { createModsRuntime } from "@xrkseek/claude-code-mods";
+
+const mods = await createModsRuntime({
+  services: { fs, subprocess, commands, tools, workingDirectory, storageDomain },
+  pipeline, // the composition's ToolPipeline
+  agentOf: ({ call }) => agentForSession(call),
+  dirs: ["~/.xrk/plugins/claude-code/my-plugin"],
+});
+
+await mods.dispatch("prompt.submit", { text }, () => ({ text }), { agent, signal });
+await mods.dispose();
+```
+
+A Cordis composition (tests, or a host that already runs one) uses
+`attachClaudeCodeMods`:
+
+```ts
+import { attachClaudeCodeMods } from "@xrkseek/claude-code-mods";
+
+const mods = await attachClaudeCodeMods({
+  ctx,
+  pipeline, // the composition's ToolPipeline
+  dirs: ["~/.xrk/plugins/claude-code/my-plugin"],
+  agentOf: ({ call }) => agentForSession(call),
+});
+
+// live now: a plugin observes, refuses, or rewrites every tool call
+// other events are raised by the host on its own seam:
+await mods.dispatch("prompt.submit", { text, messages }, () => ({ text }), {
+  agent,
+  signal,
+});
+```
+
+`definePluginDir(dir)` is usable on its own: it turns a plugin directory into an
+ordinary Cordis plugin (`ctx.plugin(...)`) for hosts that do not want the tool
+interceptor installed.
+
+## Product wiring
+
+`presets/harness/mods.ts` is the only place that knows the tool pipeline, the
+filesystem seam, and the session identity at once. `createHarnessComposition()`
+uses it to:
+
+1. `await mods.attach(handle)` in `createAgent()` — raises `session.start`, then
+   hands back `mods.wrap(handle)`;
+2. wrap `continueTurn` / `run` — `prompt.submit` (a plugin may rewrite or drop
+   the turn), then `turn.start`, then `turn.complete` on both the answer and the
+   error path;
+3. `await mods.dispose()` first in `dispose()` — `session.end` runs while
+   `$.state` is still readable, and only then do the seams come down.
+
+Plugins live at `~/.xrk/plugins/claude-code/<name>/.claude-plugin/plugin.json`
+by default; `createHarnessComposition({ claudeCodePluginsRoot })` points
+somewhere else. A missing directory means "no plugins installed" and costs the
+composition nothing.
+
+Inside a composition `$.fs`, `$.process`, `$.store` and `$.session` are the
+product's own services (workspace-confined fs, the shell's own subprocess, a
+`.state/` directory beside the plugins, the session cwd). Everything else fails
+with the service name:
+
+| Call                                  | Result in the product                                                                  |
+| ------------------------------------- | -------------------------------------------------------------------------------------- |
+| `$.tool.list`                         | the product registry's `name` / `description` (never `execute`)                        |
+| `$.tool.register`                     | lands in the product registry as `mcp__<plugin>__<tool>`, dropped with the session     |
+| `$.tool.call`                         | runs the product `ToolPipeline` (policy, sandbox, other plugins' hooks), returns text  |
+| `$.command.register` / `run` / `list` | the composition's own table: listed in Face's `/` panel, a typed `/name` dispatches it |
+| `$.ui.ask`                            | throws (no question surface yet)                                                       |
+
+Plugin tools are named `mcp__<plugin>__<tool>` (Claude Code's namespace rule) and are
+registered `direct`, so the model sees them immediately. Their `execute` is still a
+placeholder that rejects: the result has to come from
+`on('tool.call', { tool: 'mcp__<plugin>__<tool>' }, …)`. With no hook answering, the
+model reads "no tool.call hook answered it" — a diagnosable failure, not an empty result.
+
+The per-method wiring matrix (9 events × 36 `$` methods, including _why_ each gap is a
+gap) lives in [`docs/claude-code-mods-wiring.md`](../../docs/claude-code-mods-wiring.md).
+Change either side, update that table.
+
+## Events
+
+| Event                          | Raised here by                                                         | A hook may                                                                                            |
+| ------------------------------ | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `tool.call`                    | **wired**: `ToolPipeline.onPre` / `onExecute` / `onPost`               | observe, `{ deny }`, answer before dispatch with `{ result }` (body skipped), or replace after `next` |
+| `session.start`                | **wired**: harness composition, before `createAgent()` returns         | observe; register commands and tools                                                                  |
+| `prompt.submit`                | **wired**: harness composition, before `continueTurn`                  | rewrite `text`, `{ drop }`; `context` has no seam here and is reported then dropped                   |
+| `turn.start` / `turn.complete` | **wired**: harness composition, around `continueTurn`                  | observe; `{ text }` for the host log                                                                  |
+| `command.run`                  | **wired**: `$.command.run`, and harness composition on a typed `/name` | answer `{ text }` or `{}`                                                                             |
+| `ui.render`                    | ✅ AbovePrompt band (`session/band` + `ModBandDock`)                   | return a `Box`/`Text`/`Button` tree, or `next`                                                        |
+| `session.end`                  | **wired**: harness composition, first thing in `dispose()`             | observe; `$.state` still readable                                                                     |
+
+Unwired events are not silently broken: they can be registered, never fire, and
+are named in a load-time warning — the same deal Claude Code gives an event it
+never raises.
+
+Tool names translate both ways (`Bash` ↔ `bash`), for `e.tool` and for matchers.
+
+## `$` surface
+
+`plugin`, `ui`, `command`, `tool`, `prompt`, `session`, `state`, `store`,
+`clock`, `fs`, `process`, `http`, `env` — all implemented **by the bridge**. A
+service the deployment did not compose fails the call with the package name;
+anything outside the table rejects with `no implementation for <namespace>.<method>`.
+Which method actually runs inside this product's composition is the matrix in
+[`docs/claude-code-mods-wiring.md`](../../docs/claude-code-mods-wiring.md).
+See `README.zh.md` for the per-method table and the security boundary
+(plugins run with the host process's full privileges).
+
+## Differences from the upstream bridge
+
+Ported from `@deepseek-ai/dsh-experimental-claude-code-mods` (v0.2.1-rc.3).
+Chain, engine and `$` semantics match; the differences are the host seams and
+four self-supplied dependencies (`storage-domain`, `working-directory`,
+`deepFreeze`/`JsonValue`, `randomUUID`). `README.zh.md` carries the full table.
+
+## Tests
+
+```
+npx vitest run packages/claude-code-mods/tests
+```
+
+63 tests, including real plugin directories driven through a real
+`ToolPipeline`: refuse → tool error, pass → body runs, rewrite after `next`,
+pipeline restored after `dispose`.
+
+## License
+
+MIT

package/node_modules/@xrkseek/claude-code-mods/README.zh.md

@@ -0,0 +1,172 @@
+# @xrkseek/claude-code-mods
+
+把 **Claude Code 插件（mods）** 装进本仓：读 `.claude-plugin/plugin.json`、`hooks/hooks.json`，
+用原生 ESM 加载钩子模块，把 `register(on)` 收集到的钩子跑成一条中间件链，并按本仓的
+工具管线提供 `$`（`$.fs`、`$.store`、`$.session`、`$.tool`…）。
+
+插件作者不需要为本仓改一行代码——写的就是上架 Claude Code 的那份目录。
+
+```
+my-plugin/
+  .claude-plugin/plugin.json     { "name": "my-plugin", "version": "0.1.0" }
+  hooks/hooks.json               { "modules": ["./my-plugin.mjs"] }
+  hooks/my-plugin.mjs            export function register(on) { … }
+```
+
+## 用法
+
+产品运行时（`core-agent` / `core-tools`，没有 Cordis 容器）用 `createModsRuntime`：
+
+```ts
+import { createModsRuntime } from "@xrkseek/claude-code-mods";
+
+const mods = await createModsRuntime({
+  services: { fs, subprocess, commands, tools, workingDirectory, storageDomain },
+  pipeline, // 本组合现有的 ToolPipeline
+  agentOf: ({ call }) => agentForSession(call),
+  dirs: ["~/.xrk/plugins/claude-code/my-plugin"],
+});
+
+// 工具调用已被拦截（观察 / 拒绝 / 改写）
+// 其余事件由宿主在它自己的接缝上派发：
+await mods.dispatch("prompt.submit", { text }, () => ({ text }), { agent, signal });
+
+await mods.dispose();
+```
+
+Cordis 组合（测试、或已有 Cordis 容器的宿主）用 `attachClaudeCodeMods`：
+
+```ts
+import { attachClaudeCodeMods } from "@xrkseek/claude-code-mods";
+
+// pipeline 是本组合现有的 ToolPipeline（presets/harness 里 createToolPipeline 的结果）
+const mods = await attachClaudeCodeMods({
+  ctx,
+  pipeline,
+  dirs: ["~/.xrk/plugins/claude-code/my-plugin"],
+  agentOf: ({ call }) => agentForSession(call),
+});
+
+// 已经生效：插件可以观察、拒绝、改写每一次工具调用
+// 其余事件由宿主在它自己的接缝上派发：
+await mods.dispatch("prompt.submit", { text, messages }, () => ({ text }), {
+  agent,
+  signal,
+});
+```
+
+`definePluginDir(dir)` 单独可用：它把一个插件目录包装成普通的 Cordis 插件（`ctx.plugin(...)`），
+用于不想接管工具管线的场合（例如校验、测试、自带管线的宿主）。
+
+## 在产品里的装配
+
+`presets/harness/mods.ts` 是唯一同时知道「工具管线 + 文件系统 + 会话身份」的地方，`createHarnessComposition()`
+在它上面做三件事：
+
+1. `createAgent()` 里 `await mods.attach(handle)`——派发 `session.start`，再把包装过的句柄交出去；
+2. 包装过的 `continueTurn` / `run`——先 `prompt.submit`（可改写或丢弃这一轮），再 `turn.start`，跑完或抛错都派发 `turn.complete`；
+3. `dispose()` 最先 `await mods.dispose()`——`session.end` 读完 `$.state` 之后才拆管线。
+
+插件目录默认 `~/.xrk/plugins/claude-code/<插件名>/.claude-plugin/plugin.json`；
+`createHarnessComposition({ claudeCodePluginsRoot })` 可指到别处。目录不存在等同于「没装插件」，组合不付出代价。
+
+组合里的 `$.fs` / `$.process` / `$.store` / `$.session` 用**产品自己的服务**：workspace 根限定的 `fs`、
+与 shell 共用的同一个 `subprocess`、插件目录内的 `.state/`、会话 `cwd`。其余服务没组合就按包名拒绝：
+
+| 调用                                  | 产品里的结果                                                                   |
+| ------------------------------------- | ------------------------------------------------------------------------------ |
+| `$.tool.list`                         | 返回产品注册表的 `name` / `description`（不暴露 `execute`）                    |
+| `$.tool.register`                     | 真进产品注册表，名字为 `mcp__<插件>__<工具>`；会话结束撤销                     |
+| `$.tool.call`                         | 走产品 `ToolPipeline`（policy / sandbox / 其它插件的 hook 都看得到），只回文本 |
+| `$.command.register` / `run` / `list` | 组合自带一张表：进 Face 的 `/` 面板，输入框打 `/name` 也能派发                 |
+| `$.ui.ask`                            | 抛（还没有作答面）                                                             |
+
+插件注册的工具名是 `mcp__<插件>__<工具>`（Claude Code 的命名空间约定），产品侧按 `direct` 暴露，
+所以模型能直接看到并调用。但它的 `execute` 是占位体（一定 reject）：真正的结果必须由
+`on('tool.call', { tool: 'mcp__<插件>__<工具>' }, …)` 那个 hook 回答；链上没人回答时，模型读到的
+就是那句「no tool.call hook answered it」——这是可诊断的失败，不是空结果。
+
+**逐条的接入矩阵**（9 个事件 × 36 个 `$` 方法，含「为什么没接」）见
+[`docs/claude-code-mods-wiring.md`](../../docs/claude-code-mods-wiring.md)。改任何一方都要同步那张表。
+
+## 事件
+
+| 事件                           | 本仓由谁触发                                                            | 钩子能做                                                                                             |
+| ------------------------------ | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `tool.call`                    | **已接**：`ToolPipeline.onPre` / `onExecute` / `onPost`                 | 观察、`{ deny }` 拒绝、派发前 `{ result }` 直接作答（工具体不跑）、`next` 之后 `{ result }` 改写结果 |
+| `session.start`                | **已接**：harness 组合，`createAgent()` 返回前                          | 观察；注册命令与工具                                                                                 |
+| `prompt.submit`                | **已接**：harness 组合，`continueTurn` 之前                             | 改写 `text`、追加 `context`、`{ drop }` 丢弃该轮                                                     |
+| `turn.start` / `turn.complete` | **已接**：harness 组合，`continueTurn` 前后                             | 观察；`{ text }` 在宿主日志里写一行                                                                  |
+| `command.run`                  | **已接**：`$.command.run` 解析名字时；harness 组合在输入框打 `/name` 时 | 以 `{ text }` 或 `{}` 作答                                                                           |
+| `ui.render`                    | ✅ AbovePrompt 横幅（`session/band` + `ModBandDock`）                     | 返回 `Box`/`Text`/`Button` 树，或 `next` 让出                                                        |
+| `session.end`                  | **已接**：harness 组合，`dispose()` 最先                                | 观察；结束前 `$.state` 仍可读                                                                        |
+
+未接线的事件不是「静默失败」：它们可以被注册，链里永远不触发，加载时会以警告点名——
+这和 Claude Code 对未知事件的处理一致。
+
+工具名双向翻译：插件写 `Bash`/`Read`/`Edit`，本仓登记的是 `bash`/`read`/`edit`；
+`e.tool` 与 `{ tool: 'Bash' }` 匹配器都走这张表（`tool-names.ts`）。
+
+## `$` 能力面
+
+| 命名空间    | 状态                                                                                                           | 依托                                                    |
+| ----------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| `$.plugin`  | ✅ `name` / `root`                                                                                             | 插件清单                                                |
+| `$.ui`      | ✅ `log` / `toast` / `status` / `invalidate` / `open` / `close` / `panes` / `ask`                              | 宿主日志；`ask` 还需 `userQuestions`                    |
+| `$.command` | ✅ `register` / `run` / `list`（**需 `commands` 服务**；harness 组合自带一张，并把它挂到 handle 上给 Face 用） | `ctx.get('commands')`                                   |
+| `$.tool`    | ✅ `register` / `call` / `list`                                                                                | `ctx.get('tools')`（产品：真实注册表 + `ToolPipeline`） |
+| `$.prompt`  | ✅ `submit`                                                                                                    | `agent.followup()`                                      |
+| `$.session` | ✅ `id` / `cwd` / `root` / `model` / `turns` / `messages` / `usage` / `version`                                | `deriveMessages(events)` + `workingDirectory`           |
+| `$.state`   | ✅ `get` / `set`                                                                                               | 按会话内存                                              |
+| `$.store`   | ✅ `get` / `set` / `delete` / `keys`                                                                           | `storageDomain`（本包自带 `createJsonStorageDomain`）   |
+| `$.clock`   | ✅ `now` / `sleep` / `after` / `every`                                                                         | —                                                       |
+| `$.fs`      | ✅ `read` / `write` / `list` / `exists` / `stat`                                                               | `@xrkseek/exec-fs`（已限定在 workspace 根内）           |
+| `$.process` | ✅ `run`                                                                                                       | `@xrkseek/exec-subprocess`（argv，无 shell）            |
+| `$.http`    | ✅ `fetch`                                                                                                     | 进程 `fetch`，正文上限 4 MiB                            |
+| `$.env`     | ✅ `get` / `set`                                                                                               | 进程环境变量                                            |
+
+这张表说的是**桥实现了什么**，不是产品组合里每一格都真的能跑——哪些能跑、哪些按服务名拒绝，
+见矩阵文档。服务未组合时按包名拒绝；表外的命名空间/方法一律
+`no implementation for <namespace>.<method>`——宁可调用点炸，也不让插件读到 `undefined` 后算出错误结论。
+
+**安全边界**：插件以本进程全部权限运行。`$.env` 读写宿主环境变量，`$.http.fetch` 可访问任意 URL，
+`$.fs` 与 `$.tool.call` 以会话身份行动。只挂载你愿意当代码运行的插件。
+
+## 与上游桥的差异
+
+本包移植自 DSH 的 `@deepseek-ai/dsh-experimental-claude-code-mods`（v0.2.1-rc.3），
+链/引擎/`$` 语义保持一致，差异只在**宿主接缝**和**三处自建依赖**：
+
+| 处                            | 上游                                                           | 本仓                                                                           | 原因                                                                            |
+| ----------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
+| 事件来源                      | Cordis 事件 `agent/created`、`agent/pre-step`、`tools/execute` | `ToolPipeline.onPre/onPost` + 宿主显式 `dispatch`                              | 本仓运行时走 `core-agent` / `core-tools`，不发那三个 Cordis 事件                |
+| `$.session.turns`             | `ctx.agents.turnBoundaryOf()`                                  | 派生会话面上 assistant 消息数                                                  | 本仓无 `agents` 服务；`deriveMessages` 是同一份数据                             |
+| `$.session.usage` 的 `window` | `tokenMeter.contextPressure()`                                 | `tokenMeter.measure().window`（harness 组合读 `request/header`，其余宿主留空） | DSH 从压力回调里拿；本仓把窗口写在 `request/header`，读得到的就报，读不到才留 0 |
+| `$.fs`                        | `dsh-fs` 的 `resolve/readText/listDir`                         | `exec-fs` 的 `resolvePath/read/list`                                           | 本仓 fs 已按 workspace 根限定，路径只解析一次                                   |
+| storage domain                | `dsh-storage-domain` 服务                                      | 本包 `storage-domain.ts` + JSON 后端                                           | 本仓尚无该服务；契约保持一致（同步读、异步写）                                  |
+| working directory             | `dsh-working-directory`                                        | 本包 `working-directory.ts`（读 `session.header.cwd`）                         | 本仓会话已把它作为绝对路径校验并持久化                                          |
+| `ui.render` 横幅              | Remote 流 + 客户端渲染器                                       | `SurfaceTable` + Face `session/band` + 壳 `ModBandDock`                        | Pane 仍诚实降级到横幅                                                           |
+| `@Remote({ mode: 'stream' })` | 上游 typert 支持流                                             | `@Remote('watchBand')`                                                         | 本仓 typert 的 `Remote` 只接受名字                                              |
+
+## 测试
+
+63 条，全部跑在自己的 Vento 测试进程里，包括**真实插件目录 + 真实 ToolPipeline**：
+
+```
+npx vitest run packages/claude-code-mods/tests
+```
+
+- `plugin-dir.test.ts` — 清单解析、路径逃逸拒绝、模块顺序、缺 `register` 拒绝
+- `attach.test.ts` — 拒绝 → 工具错误、放行 → 工具体执行、`next` 后改写结果、卸载后管线复原
+- `chain.test.ts` / `module.test.ts` / `matcher.test.ts` — 链语义、`next` 单次、超时、错误隔离、`on` 的重复规则
+- `define-mod.test.ts` / `testing.test.ts` — 插件包装、测试工具包
+- `elements.test.ts` — 横幅元素构造器与序列化
+
+## 环境
+
+- Node ≥ 22（`Promise.withResolvers`、`AbortSignal.any`）
+- 本包 tsconfig 的 `lib` 为 `ES2024`，`target` 仍随仓库基线
+
+## 许可
+
+MIT

package/node_modules/@xrkseek/claude-code-mods/dist/api.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The `$` a hook receives. Each method shapes its arguments into the mods API
+ * event of the same name and hands it to the binding's `invoke`, which runs
+ * the mods loaded before this one and then the engine's implementation. The
+ * hook's running-time clock pauses while a call is awaited, except for
+ * `$.clock.sleep`, which Claude Code counts as the hook's own time.
+ * @module
+ */
+import type { BudgetClock, LoadedMod } from "./chain.js";
+import type { ModsApi, ModTimer } from "./types.js";
+/** Timers the engine owns on a mod's behalf, so disposal and reload can cancel them. */
+export interface TimerHost {
+    after(ms: number, fn: () => unknown): ModTimer;
+    every(ms: number, fn: () => unknown): ModTimer;
+}
+/** What one `$` instance is bound to. */
+export interface ApiBinding {
+    readonly mod: LoadedMod;
+    /** The running hook's clock, paused while mods API calls are awaited; absent outside a hook. */
+    readonly clock: BudgetClock | undefined;
+    /**
+     * Raise one mods API call as its event and resolve to the value the chain
+     * answered with; a `{ deny }` answer rejects with the reason.
+     */
+    readonly invoke: (op: string, input: unknown) => Promise<unknown>;
+    readonly timers: TimerHost;
+    /** Receives a rejected fire-and-forget call's reason. */
+    readonly report: (line: string) => void;
+}
+/**
+ * Build the `$` for one hook invocation.
+ * @param binding - the mod, clock, and engine entry points this instance uses.
+ * @returns the mods API.
+ */
+export declare function createModsApi(binding: ApiBinding): ModsApi;
+//# sourceMappingURL=api.d.ts.map

package/node_modules/@xrkseek/claude-code-mods/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEzD,OAAO,KAAK,EASV,OAAO,EAUP,QAAQ,EAMT,MAAM,YAAY,CAAC;AAEpB,wFAAwF;AACxF,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,GAAG,QAAQ,CAAC;IAC/C,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,GAAG,QAAQ,CAAC;CAChD;AAED,yCAAyC;AACzC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,gGAAgG;IAChG,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,CAAC;IACxC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAClE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAkJ1D"}

package/node_modules/@xrkseek/claude-code-mods/dist/api.js

@@ -0,0 +1,215 @@
+/**
+ * The `$` a hook receives. Each method shapes its arguments into the mods API
+ * event of the same name and hands it to the binding's `invoke`, which runs
+ * the mods loaded before this one and then the engine's implementation. The
+ * hook's running-time clock pauses while a call is awaited, except for
+ * `$.clock.sleep`, which Claude Code counts as the hook's own time.
+ * @module
+ */
+import { uiElements } from "./elements.js";
+import { messageOf } from "./values.js";
+/**
+ * Build the `$` for one hook invocation.
+ * @param binding - the mod, clock, and engine entry points this instance uses.
+ * @returns the mods API.
+ */
+export function createModsApi(binding) {
+    const { mod, clock, timers } = binding;
+    async function call(op, input) {
+        clock?.pause();
+        try {
+            return (await binding.invoke(op, input));
+        }
+        finally {
+            clock?.resume();
+        }
+    }
+    function fire(op, input) {
+        call(op, input).catch((error) => {
+            binding.report(`${mod.name}: $.${op} failed: ${messageOf(error)}`);
+        });
+    }
+    // Not frozen: the proxy below returns a wrapped namespace, which a frozen target's invariant would forbid.
+    const served = {
+        plugin: Object.freeze({ name: mod.name, root: mod.root }),
+        ui: Object.freeze({
+            log(text, options) {
+                fire("ui.log", { text, to: options?.to ?? "transcript" });
+            },
+            toast(text, options) {
+                fire("ui.toast", {
+                    text,
+                    ...(options?.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+                });
+            },
+            status(text) {
+                fire("ui.status", { text });
+            },
+            invalidate(event) {
+                fire("ui.invalidate", { event });
+            },
+            open(pane) {
+                return call("ui.open", pane);
+            },
+            close(pane) {
+                return call("ui.close", { id: pane.id, origin: "plugin" });
+            },
+            panes() {
+                return call("ui.panes", {});
+            },
+            ask(question, options) {
+                const normalized = Array.isArray(options)
+                    ? { options }
+                    : (options ?? {});
+                return call("ui.ask", { question, ...normalized });
+            },
+            resolve: () => uiElements(),
+        }),
+        command: Object.freeze({
+            register(command) {
+                return call("command.register", command);
+            },
+            run(input) {
+                return call("command.run", { command: input.command, args: input.args ?? "" });
+            },
+            list() {
+                return call("command.list", {});
+            },
+        }),
+        tool: Object.freeze({
+            register(tool) {
+                return call("tool.register", tool);
+            },
+            call(input) {
+                return call("tool.call", input);
+            },
+            list() {
+                return call("tool.list", {});
+            },
+        }),
+        prompt: Object.freeze({
+            submit(input) {
+                return call("prompt.submit", {
+                    text: input.text,
+                    asUser: input.asUser === true,
+                });
+            },
+        }),
+        session: Object.freeze({
+            id: () => call("session.id", {}),
+            cwd: () => call("session.cwd", {}),
+            root: () => call("session.root", {}),
+            model: () => call("session.model", {}),
+            turns: () => call("session.turns", {}),
+            messages: () => call("session.messages", {}),
+            usage: () => call("session.usage", {}),
+            version: () => call("session.version", {}),
+        }),
+        state: Object.freeze({
+            get(ref) {
+                return call("state.get", { plugin: ref.plugin, key: ref.key });
+            },
+            set(ref, value) {
+                return call("state.set", { plugin: ref.plugin, key: ref.key, value });
+            },
+        }),
+        store: Object.freeze({
+            get: (key) => call("store.get", { key }),
+            set: (key, value) => call("store.set", { key, value }),
+            delete: (key) => call("store.delete", { key }),
+            keys: () => call("store.keys", {}),
+        }),
+        clock: Object.freeze({
+            now: () => call("clock.now", {}),
+            // Counted as the hook's own time, so the clock is not paused.
+            sleep: (ms) => binding.invoke("clock.sleep", { ms }),
+            after: (ms, fn) => timers.after(ms, fn),
+            every: (ms, fn) => timers.every(ms, fn),
+        }),
+        fs: Object.freeze({
+            read: (path) => call("fs.read", { path, as: "text" }),
+            write: (path, text) => call("fs.write", { path, text }),
+            list: (path) => call("fs.list", { path: path ?? "." }),
+            exists: (path) => call("fs.exists", { path }),
+            stat: (path) => call("fs.stat", { path, resolve: true }),
+        }),
+        process: Object.freeze({
+            run(argv, init) {
+                return call("process.run", { argv, ...(init === undefined ? {} : { init }) });
+            },
+        }),
+        http: Object.freeze({
+            fetch(url, init) {
+                return call("http.fetch", { url, ...(init === undefined ? {} : { init }) });
+            },
+        }),
+        env: Object.freeze({
+            get: (name) => call("env.get", { name }),
+            set: (name, value) => call("env.set", { name, ...(value === undefined ? {} : { value }) }),
+        }),
+    };
+    return withUnservedMembers(served, mod.name);
+}
+/** The method namespaces Claude Code's `$` has; `plugin` holds facts, not methods, and stays as served. */
+const METHOD_NAMESPACES = new Set([
+    "ui",
+    "command",
+    "tool",
+    "prompt",
+    "session",
+    "state",
+    "store",
+    "clock",
+    "fs",
+    "process",
+    "http",
+    "env",
+    "model",
+    "agent",
+    "config",
+    "settings",
+    "mcp",
+    "audio",
+    "telemetry",
+    "turn",
+]);
+/**
+ * Give `$` Claude Code's full namespace set: a served member is itself; any
+ * other member of a method namespace is a function whose call rejects with
+ * `no implementation for <namespace>.<member>`, so a mod that reaches past
+ * this host fails with the gap named, not with a TypeError.
+ * @param served - the frozen object of served namespaces.
+ * @param modName - the mod the `$` belongs to, for the rejection text.
+ * @returns the `$` a hook receives.
+ */
+function withUnservedMembers(served, modName) {
+    const namespaces = new Map();
+    const namespaceOf = (name, base) => {
+        let wrapped = namespaces.get(name);
+        if (wrapped === undefined) {
+            wrapped = new Proxy(base, {
+                get(target, member, receiver) {
+                    const own = Reflect.get(target, member, receiver);
+                    if (own !== undefined || typeof member !== "string" || member === "then")
+                        return own;
+                    return () => Promise.reject(new Error(`${modName}: no implementation for ${name}.${member}`));
+                },
+            });
+            namespaces.set(name, wrapped);
+        }
+        return wrapped;
+    };
+    return new Proxy(served, {
+        get(target, namespace, receiver) {
+            const own = Reflect.get(target, namespace, receiver);
+            if (typeof namespace !== "string" || !METHOD_NAMESPACES.has(namespace))
+                return own;
+            return namespaceOf(namespace, typeof own === "object" && own !== null ? own : Object.freeze({}));
+        },
+        // `$` is read-only, as the frozen object was.
+        set: () => false,
+        defineProperty: () => false,
+        deleteProperty: () => false,
+    });
+}
+//# sourceMappingURL=api.js.map

package/node_modules/@xrkseek/claude-code-mods/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}