@qjp88995/agent-runtime 0.0.0-stage → 0.1.0

package/src/testing/index.ts

@@ -0,0 +1,14 @@
+/**
+ * 测试辅助（`@qjp88995/agent-runtime/testing`）：端口契约用例。需要 vitest（可选 peer）。
+ */
+export {
+  describeQuestionStoreContract,
+  describeRunStoreContract,
+  describeSessionLockContract,
+  describeSessionStoreContract,
+  describeStreamBusContract,
+  describeSubagentAwaitLeaseContract,
+  describeTreeBudgetContract,
+  describeVendorFileCacheContract,
+  describeWakeChannelContract,
+} from './contracts.js';

package/src/testing/stub.ts

@@ -0,0 +1,28 @@
+/**
+ * 部分实现的测试替身。
+ *
+ * 两条都要满足，所以拆成「`satisfies` 校验 + `asStub` 注入」两步：
+ *
+ * - **键名必须钉在 T 上**：`{ ... } satisfies Stub<T>` 对对象字面量会做多余属性
+ *   检查，把方法名打错（或 mock 一个已经改了名的方法）编译期就红。裸
+ *   `as unknown as T` 完全不校验——那种 mock 永远不会被调用，测试照样绿。
+ * - **属性类型必须保持 `Mock`**：所以是 `satisfies` 而不是标注返回类型。标注成 T
+ *   会让每个属性解析回接口的 method signature，断言得套一层 `vi.mocked()`，读
+ *   引用还要挨 `@typescript-eslint/unbound-method`。
+ *
+ * ```ts
+ * function makeService() {
+ *   return { list: vi.fn(), findById: vi.fn() } satisfies Stub<FooService>;
+ * }
+ * const svc = makeService();
+ * const ctrl = new FooController(asStub<FooService>(svc));
+ * expect(svc.list).toHaveBeenCalled();   // svc.list 是 Mock，不用 vi.mocked
+ * ```
+ *
+ * 替身实现了接口全部成员时直接 `satisfies FooService` 更强（连签名一起校验），
+ * `Stub` 是给「只实现被测路径用得到的那几个」准备的。
+ */
+export type Stub<T> = Partial<Record<keyof T, unknown>>;
+
+/** 把替身喂给期望真实类型的位置 —— 断言只发生在这一处。 */
+export const asStub = <T>(stub: Stub<T>): T => stub as unknown as T;

package/src/tools/agent-tool.base.ts

@@ -0,0 +1,361 @@
+import type { z } from 'zod';
+
+import type { ToolResultImage } from '../schema/index.js';
+import type { AgentToolProvider, ToolContext } from './agent-tool.interface.js';
+import { toolError, type ToolOut } from './tool-result.js';
+
+/**
+ * 后台受理结果 —— `run_in_background: true` 时 `execute` 的返回形状。
+ *
+ * 与 `ToolOut` 共用判别键 `kind`（三态 `ok`/`error`/`accepted` 互斥），
+ * 故调用方一次 switch 就能穷尽，不必先判「这是不是后台调用」。
+ */
+export interface ToolAccepted {
+  kind: 'accepted';
+  /** 供模型后续引用这次后台任务（Delegate 用子会话 id）。 */
+  handle: string;
+  /**
+   * 为什么是后台受理而不是直接给结果。缺省（＝调用方本来就要后台）不必填；
+   * 「本来要同步等、但等不到了」这类降级填一句，好让模型知道自己没拿到结果
+   * 不是因为它请求错了。
+   */
+  note?: string;
+}
+
+export function toolAccepted(handle: string, note?: string): ToolAccepted {
+  return note
+    ? { kind: 'accepted', handle, note }
+    : { kind: 'accepted', handle };
+}
+
+/** 重试策略。**默认不重试** —— 不声明就是不重试，见 `AgentTool.retry`。 */
+export interface RetryPolicy {
+  /** 总尝试次数，含首次。2 = 首次 + 1 次重试。 */
+  maxAttempts: number;
+  /**
+   * 只有返回 true 的异常才重试。**没有缺省实现是有意的**：能不能重试取决于
+   * 这个工具在做什么（网络抖动可以，「找不到」重试一万次还是同一个答案），
+   * 基类无从判断，猜错的方向是把一次确定的失败变成 N 倍延迟。
+   */
+  isRetryable(err: unknown): boolean;
+  /** 首次退避毫秒，此后指数翻倍。缺省 200ms。 */
+  backoffMs?: number;
+}
+
+/** 供 `ToolRegistry` 读取的横切能力（protected 字段它够不着）。 */
+export interface ToolCapabilities {
+  timeoutMs: number;
+  supportsBackground: boolean;
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_BACKOFF_MS = 200;
+
+/**
+ * 全部 agent 工具的基类。**新工具一律继承它，不要直接 implements
+ * `AgentToolProvider`** —— 那个接口现在只是基类对注册表的对外契约。
+ *
+ * ## 它替你做掉的四件事
+ *
+ * 1. **错误只有一个出口**。子类可以返回 `toolError(...)`，也可以直接抛（域错误、
+ *    库错误、意外异常都算），基类统一收编成 `{kind:'error'}`，再经同一条
+ *    `toModelOutput` 渲染。改造前抛出的那条路径是**绕过 `toModelOutput`** 的
+ *    ——注册表直接把 `err.message` 喂给模型，而域错误的 message 是写给 HTTP
+ *    调用方看的。同一个工具里两条错误路径给出两种质量的文案，正是当时
+ *    `GetTwinEntry`/`SaveTwinPersona` 那批工具的形态。
+ * 2. **`render` 是抽象方法**。漏写是编译错误，不再静默退化成
+ *    `JSON.stringify` ——那会把 markdown 正文的换行全转义成 `\n` 字面量。
+ * 3. **返回类型被钉死**。`execute` 由基类实现且返回 `ToolOut`，注册表内部信封
+ *    `ok()/fail()` 的误用在类型层面不再可能（`LoadSkill` 曾为此坏过整整一轮：
+ *    `fail()` 的外层 `ok:true` 让注册表以为调用成功，失败路径根本走不到）。
+ * 4. **超时 / 重试 / 后台运行**三个横切机制，子类只声明不实现。
+ *
+ * ## 三层的嵌套顺序
+ *
+ * ```
+ * 后台  ⊃  重试  ⊃  超时  ⊃  run()
+ * ```
+ *
+ * 即：每一次尝试各自计时，**超时本身可以被重试**（瞬态卡顿正是最值得重试的
+ * 一类）；后台模式下这两层照常在后台生效。反过来把重试放进超时里，会让
+ * 「总时长」等于一个尝试的预算，第二次尝试注定跑不完。
+ */
+export abstract class AgentTool<TInput, TData> implements AgentToolProvider<
+  TInput,
+  ToolOut<TData> | ToolAccepted
+> {
+  abstract readonly inputSchema: z.ZodType<TInput>;
+
+  /**
+   * 工具正文。**子类实现这个，不是 `execute`**。
+   *
+   * 失败两种写法都行：返回 `toolError('...')`（措辞可控，首选），或直接抛
+   * （基类兜成 `toolError(this.describeError(err))`）。**只有抛出的那条会被
+   * 重试**——返回 `toolError` 是工具自己判定的确定性失败，重试没有意义。
+   *
+   * **也可以返回 `toolAccepted(handle)`**：一次同步调用完全可能中途决定「这个
+   * 等不下去了，转后台」（`Delegate` 的等待降级）。那不是失败 —— 用 error 表达
+   * 会让下游把一个正常在跑的任务显示成失败。
+   *
+   * `ctx.abortSignal` 已被基类替换成「用户中止 ∪ 本次超时」的合成信号：
+   * 长任务应当监听它并尽早返回，否则超时只能做到「不再等它」，工具本身会
+   * 变成没人要结果的幽灵任务继续跑。
+   */
+  protected abstract run(
+    input: TInput,
+    ctx: ToolContext
+  ): Promise<ToolOut<TData> | ToolAccepted>;
+
+  /**
+   * 成功结果 → 喂给模型的文本。**必须实现**。
+   *
+   * 长正文（markdown 规则、脚本样本、文件内容）一律**裸出**，不要包 JSON；
+   * 元数据用自然语言带一行。另外几条反复踩过的「沉默即误导」：抽样要报总数
+   * 与范围、多关键词查询要点名哪几个没匹配上、「零结果」与「搜不到」要分开、
+   * 写操作要说清副作用范围。
+   */
+  protected abstract render(out: { kind: 'ok' } & TData): string;
+
+  /** 单次尝试的超时。子类覆盖为字面量常量即可。 */
+  protected readonly timeoutMs: number = DEFAULT_TIMEOUT_MS;
+
+  /**
+   * 重试策略，**默认关闭**。
+   *
+   * 开之前先回答一个问题：这个工具重跑两次，效果和跑一次一样吗？`Write`/
+   * `Edit`/`CreateUser` 的答案都是否 —— 重试一次就是写两遍、
+   * 建两个账号，而调用方看到的仍然只是一次失败。
+   */
+  protected readonly retry: RetryPolicy | undefined = undefined;
+
+  /**
+   * 声明本工具接受 `run_in_background` 参数（由注册表注入 schema，子类的
+   * `inputSchema` 不要自己写它 —— 一个参数只能有一个定义处）。
+   *
+   * 默认 false：绝大多数工具跑几十毫秒，给它一个「要不要后台」的选项是纯
+   * 噪音，模型还得为此付 token 并可能选错。
+   */
+  protected readonly supportsBackground: boolean = false;
+
+  /**
+   * 后台运行的实现。`supportsBackground` 为 true 且调用方传了
+   * `run_in_background: true` 时走这里。
+   *
+   * **缺省是抛**，不是 fire-and-forget：一个「跑在进程内、没人追踪、重启即丢」
+   * 的后台任务是隐性的数据丢失，不该由基类默默提供给每一个后来者。今天唯一
+   * 支持后台的 `Delegate` 覆盖了它（子会话本就是持久化的，回投由 finalizer
+   * 负责）。将来第二个工具要用时，再据它的真实需求决定是进程内还是落队列。
+   */
+  protected runInBackground(
+    _input: TInput,
+    _ctx: ToolContext
+  ): Promise<ToolOut<TData> | ToolAccepted> {
+    return Promise.reject(
+      new Error('该工具声明了 supportsBackground 但未实现 runInBackground()')
+    );
+  }
+
+  /** 异常 → 给模型看的一句话。子类可覆盖以翻译自己的域错误。 */
+  protected describeError(err: unknown): string {
+    return err instanceof Error ? err.message : String(err);
+  }
+
+  /**
+   * 落库时随 tool-result part 一起存的**结构化引用**（`MessagePart.ref`）。
+   *
+   * 默认没有。只有当界面需要从一次工具调用里认出一个实体时才实现它，且**只放
+   * 认领所必需的最小信息** —— `output` 已经存了给人看的文本，这里再存一份结果
+   * 副本就是同一行里两份长正文。
+   */
+  protected persistRef(
+    _out: ToolOut<TData> | ToolAccepted
+  ): Record<string, unknown> | undefined {
+    return undefined;
+  }
+
+  /** 供注册表调用（`persistRef` 是 protected，它够不着）。 */
+  refFor(out: unknown): Record<string, unknown> | undefined {
+    return this.persistRef(out as ToolOut<TData> | ToolAccepted);
+  }
+
+  /**
+   * 落库时随 tool-result part 一起存、并交给**模型看**的图片
+   * （`MessagePart.images`）。默认没有。
+   *
+   * 形状照抄 `persistRef`/`refFor` 那一对，理由也一样：注册表在基类外面，
+   * protected 够不着。**不要把图塞进 `persistRef` 复用那条路**——`ref` 的约定是
+   * 「只放认领实体所必需的最小信息」，塞进去之后那句注释就不再成立。
+   *
+   * 实现者要保证 `src` 是存储中心对象 id（字节已固化）、`mediaType` 是完整
+   * 子类型——判据见 `ToolResultImageSchema` 各字段注释。
+   */
+  protected persistImages(
+    _out: ToolOut<TData> | ToolAccepted
+  ): ToolResultImage[] | undefined {
+    return undefined;
+  }
+
+  /** 供注册表调用（`persistImages` 是 protected，它够不着）。 */
+  imagesFor(out: unknown): ToolResultImage[] | undefined {
+    return this.persistImages(out as ToolOut<TData> | ToolAccepted);
+  }
+
+  /**
+   * 这次结果**不许被上下文裁剪换成存根**（落库进 `MessagePart.pinned`）。默认 false。
+   *
+   * 裁剪的前提是「正文是体积、丢了可以重跑」。只有两条都不满足的结果才该钉住——
+   * 当前唯一的用例是 `Ask`：一两句话，且是**用户做的决定**，裁掉之后
+   * 模型无从重新得知。**别把它当通用的「重要结果」开关**：`Read` 的结果再重要也能
+   * 重读。形状照抄 `persistRef`/`refFor`（注册表在基类外面，protected 够不着）。
+   */
+  protected persistPinned(_out: ToolOut<TData> | ToolAccepted): boolean {
+    return false;
+  }
+
+  /** 供注册表调用（`persistPinned` 是 protected，它够不着）。 */
+  pinnedFor(out: unknown): boolean {
+    return this.persistPinned(out as ToolOut<TData> | ToolAccepted);
+  }
+
+  /** 后台受理 → 给模型看的一句话。子类可覆盖。 */
+  protected renderAccepted(out: ToolAccepted): string {
+    return `任务已在后台启动（handle=${out.handle}）。你不必等待，完成后结果会回到你这里。`;
+  }
+
+  /** 注册表读取横切能力用（`protected` 字段它够不着）。 */
+  get capabilities(): ToolCapabilities {
+    return {
+      timeoutMs: this.timeoutMs,
+      supportsBackground: this.supportsBackground,
+    };
+  }
+
+  /**
+   * 三层组装。**子类不要覆盖** —— 覆盖它就绕开了上面全部四件事。
+   *
+   * `run_in_background` 由注册表注入 schema，故它会混在 `input` 里到达这里；
+   * 取出后**从传给 `run()` 的对象里剥掉**，让子类的 `TInput` 保持干净（它没有
+   * 声明过这个字段，留着会让「这个参数归谁管」变得含糊）。
+   */
+  async execute(
+    input: TInput,
+    ctx: ToolContext
+  ): Promise<ToolOut<TData> | ToolAccepted> {
+    const { background, rest } = splitBackgroundFlag(input);
+    try {
+      if (background && this.supportsBackground) {
+        return await this.runInBackground(rest, ctx);
+      }
+      return await this.withRetry(rest, ctx);
+    } catch (err) {
+      return toolError(this.describeError(err));
+    }
+  }
+
+  /** 三态一次穷尽。基类实现，子类只写 `render`/`renderAccepted`。 */
+  toModelOutput(out: ToolOut<TData> | ToolAccepted): string {
+    switch (out.kind) {
+      case 'ok':
+        return this.render(out);
+      case 'accepted':
+        return this.renderAccepted(out);
+      case 'error':
+        return out.message;
+    }
+  }
+
+  private async withRetry(
+    input: TInput,
+    ctx: ToolContext
+  ): Promise<ToolOut<TData> | ToolAccepted> {
+    const policy = this.retry;
+    const maxAttempts = Math.max(1, policy?.maxAttempts ?? 1);
+    let lastErr: unknown;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return await this.withTimeout(input, ctx);
+      } catch (err) {
+        lastErr = err;
+        const canRetry =
+          policy !== undefined &&
+          attempt < maxAttempts &&
+          policy.isRetryable(err);
+        if (!canRetry) throw err;
+        // 用户中止时不再重试——那不是瞬态故障，是有人明确要求停下。
+        if (ctx.abortSignal.aborted) throw err;
+        const backoff =
+          (policy.backoffMs ?? DEFAULT_BACKOFF_MS) * 2 ** (attempt - 1);
+        await sleep(backoff, ctx.abortSignal);
+      }
+    }
+    throw lastErr;
+  }
+
+  /**
+   * 单次尝试的超时。**两道并用，不是重复**：合成 `AbortSignal` 让配合的工具
+   * 真正停下（这是改造前缺的那半），`Promise.race` 保证不配合的工具也拖不死
+   * 这一轮。
+   */
+  private async withTimeout(
+    input: TInput,
+    ctx: ToolContext
+  ): Promise<ToolOut<TData> | ToolAccepted> {
+    const timeoutMs = this.timeoutMs;
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    try {
+      const signal = AbortSignal.any([ctx.abortSignal, ac.signal]);
+      // 先把 run() 的两种结局都收敛成 resolve —— 否则 race 里 timeout 赢时
+      // run() 迟到的 rejection 无人接管，会冒成 unhandledRejection 打崩进程。
+      const work = this.run(input, { ...ctx, abortSignal: signal }).then(
+        out => ({ ok: true as const, out }),
+        (err: unknown) => ({ ok: false as const, err })
+      );
+      const timeout = new Promise<'timeout'>(resolve => {
+        ac.signal.addEventListener('abort', () => resolve('timeout'), {
+          once: true,
+        });
+      });
+      const raced = await Promise.race([work, timeout]);
+      if (raced === 'timeout') {
+        return toolError(`工具执行超过 ${timeoutMs}ms 未返回`);
+      }
+      if (!raced.ok) throw raced.err;
+      return raced.out;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+/**
+ * 剥出注册表注入的 `run_in_background`。
+ *
+ * 键名是 snake_case、与本仓其余 camelCase 参数不一致，那是**有意**对齐
+ * Claude Code 的同名参数——理由与工具名用 PascalCase 是同一条：模型在训练
+ * 语料里见过海量样本，工具调用准确率是实打实的收益。因为它只在这里和注册表
+ * 注入处出现两次，不会扩散成两套命名风格。
+ */
+function splitBackgroundFlag<TInput>(input: TInput): {
+  background: boolean;
+  rest: TInput;
+} {
+  if (input === null || typeof input !== 'object') {
+    return { background: false, rest: input };
+  }
+  const { run_in_background: flag, ...rest } = input as Record<string, unknown>;
+  return { background: flag === true, rest: rest as TInput };
+}
+
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise(resolve => {
+    const timer = setTimeout(done, ms);
+    signal.addEventListener('abort', done, { once: true });
+    function done(): void {
+      clearTimeout(timer);
+      signal.removeEventListener('abort', done);
+      resolve();
+    }
+  });
+}

package/src/tools/agent-tool.interface.ts

@@ -0,0 +1,101 @@
+import type { z } from 'zod';
+
+import type { AgentExtensions } from '../agent-extensions.js';
+import type { MessagePart } from '../schema/index.js';
+
+/** 工具执行上下文。刻意不含任何渠道概念（本项目单渠道）。 */
+export interface ToolContext {
+  /** 当前 agent_run 的 id。 */
+  runId: string;
+  /** 根 turn 的 id，跨父子共享。 */
+  streamId: string;
+  /** 根会话 id —— agent 产物库的树级作用域键（pre-1b：= sessionId）。 */
+  rootSessionId: string;
+  /** 当前 loop 的会话 id —— 产物 writer 审计。 */
+  sessionId: string;
+  /** 发起者，可空（系统触发时）。 */
+  userId: string | null;
+  /**
+   * 跑的是哪个 agent：`id` 与模型能力之外，全是宿主经 `AgentExtensions` 加的字段
+   * （随本轮所跑的那一版配置下来，工具不必再查库）。
+   */
+  agent: ToolAgentContext;
+  /**
+   * 会话上的不透明附加信息（宿主写、宿主的工具读，内核不解释；派子 Agent 时子会话继承）。
+   * 缺省空对象。
+   */
+  sessionMetadata: Readonly<Record<string, unknown>>;
+  /** subagent 深度，根为 0。 */
+  depth: number;
+  /**
+   * 本轮发起人此刻的权限点（`Initiator.permissions`）。**可选、缺省按空**：只给「派不派得出
+   * 要权限点的内置子 Agent」这类判据用——**不是工具权限的门**，要权限的工具各自现查。
+   */
+  initiatorPermissions?: ReadonlySet<string>;
+  /** 同一轮内可变：前一个工具的修改对后续工具可见。 */
+  metadata: Record<string, unknown>;
+  abortSignal: AbortSignal;
+  toolCallId: string;
+  /**
+   * 异步工具的回投通道：绑定到**当前会话**（`sessionId`），由宿主实现
+   * （投进 inbox + 唤醒会话）。
+   * 供 async 工具的后台段（execute 返回受理占位后 fire-and-forget 的部分）
+   * 把真结果投回 inbox，由下一轮 drain 拾取。
+   */
+  postToInbox?: (input: {
+    kind: 'user_message' | 'tool_result';
+    source?: Record<string, unknown>;
+    parts: MessagePart[];
+  }) => Promise<void>;
+}
+
+/** `ToolContext.agent`：agent id、本轮模型能力，加上宿主的扩展字段。 */
+export type ToolAgentContext = {
+  /** agent 的 id（宿主定义；内置形式可以是名字）。 */
+  id: string;
+  /**
+   * 本轮模型标了哪些能力（模型目录里的能力名）。`Delegate` 据此拒绝派一个替「自己已有的
+   * 能力」顶替的子 Agent。缺省空数组。
+   */
+  modelCapabilities: readonly string[];
+} & AgentExtensions;
+
+/** `AgentToolProvider.isAvailable` / `describe` 看得到的那份 agent 配置（宿主的扩展字段）。 */
+export type ToolAvailabilityView = AgentExtensions;
+
+/**
+ * 工具实现契约。Provider 永不 import 'ai' —— 由 ToolRegistry
+ * 负责包成 AI SDK 的 tool()。这个解耦让工具层不受 SDK 版本影响。
+ */
+export interface AgentToolProvider<TInput = unknown, TOutput = unknown> {
+  readonly inputSchema: z.ZodType<TInput>;
+  execute(input: TInput, ctx: ToolContext): Promise<TOutput>;
+  /**
+   * 结构化结果 → 喂模型的文本。缺省直接序列化整个结果。
+   * 双轨的落点：结构化那份落库/发 SSE，只有这里返回的进模型上下文。
+   */
+  toModelOutput?(output: TOutput): string;
+  /**
+   * 这一轮能不能用（缺省 = 能）。不能用就从本轮工具集摘掉（`unavailableToolNames`
+   * → loop 的摘除清单），而不是端上桌让模型调一次、收回一句「未配置」，还在自述
+   * 能力时承诺做不到的事。判据写在工具自己身上：部署级开关（取数账号配没配）、
+   * agent 级配置（联网服务选没选）都由工具回答，loop 一个具体工具名都不必认识。
+   *
+   * **这不是门**：工具里的判空 / 拒绝照留，这里只决定端不端上桌。每轮现问，不在
+   * 启动时快照——开关由别的 provider 的 `onModuleInit` 决定。可以是异步的（WebFetch
+   * 要查一次联网服务是哪家：有的家没有读网页接口），但答案必须在相邻两轮之间稳定——
+   * 工具表一变，前缀缓存整段 miss。
+   */
+  isAvailable?(agent: ToolAvailabilityView): boolean | Promise<boolean>;
+  /**
+   * 这份 agent 配置下的工具说明（缺省或返回 `null` = 装饰器里的 `description`）。给「说明要跟着
+   * 配置走」的工具用：WebSearch / WebFetch 的说明由所选联网服务的适配器追加或替换。每轮现问，
+   * 与 `isAvailable` 同时机；loop 与「下一轮预览」用同一份（`ToolRegistry.descriptionsFor`）。
+   *
+   * 答案进工具表：**只许随配置变**（管理员改了配置，相邻两轮才可以不同），别掺按「现在」算的东西——
+   * 工具表一变，前缀缓存整段 miss。
+   */
+  describe?(
+    agent: ToolAvailabilityView
+  ): string | null | Promise<string | null>;
+}

package/src/tools/builtin-names.ts

@@ -0,0 +1,26 @@
+/**
+ * runtime 自带的三个通用工具的名字。**前后端、宿主都从这里取，别各写各的字面量**——
+ * 名字对不上时不报错也不告警，只是界面上某块静默空着（待办面板、提问卡片、子 Agent 卡）。
+ *
+ * 2026-11-11 改成单个动词（原名是 agent-base 的 `SpawnAgent` / `TodoWrite` /
+ * `AskUserQuestion`）。旧名登记为 `formerNames`：库里的旧历史照常以现名投影给模型
+ * （`ToolRegistry.toolNameAliases`），宿主前端从历史里认这几个工具时也要认旧名
+ * （`isToolNamed`）。
+ */
+export const DELEGATE_TOOL_NAME = 'Delegate';
+export const DELEGATE_FORMER_NAMES = ['SpawnAgent'] as const;
+
+export const TODO_TOOL_NAME = 'Todo';
+export const TODO_FORMER_NAMES = ['TodoWrite'] as const;
+
+export const ASK_TOOL_NAME = 'Ask';
+export const ASK_FORMER_NAMES = ['AskUserQuestion'] as const;
+
+/** `name` 是不是这个工具（现名或任一旧名）。前端从历史里认工具用。 */
+export function isToolNamed(
+  name: string,
+  current: string,
+  former: readonly string[]
+): boolean {
+  return name === current || former.includes(name);
+}

package/src/tools/index.ts

@@ -0,0 +1,39 @@
+export {
+  AgentTool,
+  type RetryPolicy,
+  type ToolAccepted,
+  toolAccepted,
+  type ToolCapabilities,
+} from './agent-tool.base.js';
+export type {
+  AgentToolProvider,
+  ToolAgentContext,
+  ToolAvailabilityView,
+  ToolContext,
+} from './agent-tool.interface.js';
+export {
+  ASK_FORMER_NAMES,
+  ASK_TOOL_NAME,
+  DELEGATE_FORMER_NAMES,
+  DELEGATE_TOOL_NAME,
+  isToolNamed,
+  TODO_FORMER_NAMES,
+  TODO_TOOL_NAME,
+} from './builtin-names.js';
+export { digestInputSchema, type SchemaDigest } from './tool-definition.js';
+export type { ToolMeta } from './tool-meta.js';
+export {
+  type ToolAgentView,
+  ToolRegistry,
+  type ToolRegistryOptions,
+  type ToolSetOptions,
+} from './tool-registry.js';
+export {
+  fail,
+  ok,
+  safe,
+  toolError,
+  type ToolOut,
+  type ToolResult,
+} from './tool-result.js';
+export type { ToolDefinitionWire, ToolParamWire } from './tool-wire.js';

package/src/tools/tool-definition.ts

@@ -0,0 +1,93 @@
+import { z } from 'zod';
+
+import type { ToolParamWire } from './tool-wire.js';
+
+/** `digestInputSchema` 的产物：参数表 + 摊不平时的说明。 */
+export interface SchemaDigest {
+  params: ToolParamWire[];
+  schemaNote: string | null;
+}
+
+/**
+ * 把工具的 zod inputSchema 摊平成后台「工具列表」页的参数表。
+ *
+ * 走 `z.toJSONSchema`（`unrepresentable: 'any'`——遇到表示不了的类型退化成
+ * any，不抛）再取顶层 properties。工具入参在本仓约定就是 `z.object`，非对象
+ * 结构（如测试 stub 的 `z.unknown()`）不硬摊，如实给一句说明。
+ *
+ * **绝不抛**：这是展示路径，一个工具的 schema 转不动不该拖垮整张列表。
+ */
+export function digestInputSchema(schema: z.ZodType): SchemaDigest {
+  let json: Record<string, unknown>;
+  try {
+    json = z.toJSONSchema(schema, {
+      unrepresentable: 'any',
+      io: 'input',
+    });
+  } catch (err) {
+    return {
+      params: [],
+      schemaNote: `schema 转换失败：${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  const properties = json.properties;
+  if (
+    json.type !== 'object' ||
+    typeof properties !== 'object' ||
+    properties === null
+  ) {
+    return {
+      params: [],
+      schemaNote: `入参不是对象结构：${JSON.stringify(json)}`,
+    };
+  }
+
+  const required = new Set(
+    Array.isArray(json.required) ? (json.required as string[]) : []
+  );
+  const params = Object.entries(properties as Record<string, unknown>).map(
+    ([key, prop]) => ({
+      key,
+      type: typeLabel(prop),
+      required: required.has(key),
+      description: descriptionOf(prop),
+    })
+  );
+  return { params, schemaNote: null };
+}
+
+function descriptionOf(prop: unknown): string | null {
+  if (typeof prop !== 'object' || prop === null) return null;
+  const d = (prop as { description?: unknown }).description;
+  return typeof d === 'string' ? d : null;
+}
+
+/**
+ * JSON schema 片段 → 人读的类型标签。尽力而为：认不出的形状退化成 JSON 原文
+ * ——比一个笼统的 any 有信息量（那正是要审阅的东西）。
+ */
+function typeLabel(prop: unknown): string {
+  if (typeof prop !== 'object' || prop === null) return 'any';
+  const p = prop as Record<string, unknown>;
+
+  if (Array.isArray(p.enum)) {
+    return p.enum.map(v => JSON.stringify(v)).join(' | ');
+  }
+  if (Array.isArray(p.anyOf)) {
+    return (p.anyOf as unknown[]).map(typeLabel).join(' | ');
+  }
+  if (p.type === 'array') {
+    return `${typeLabel(p.items)}[]`;
+  }
+  if (Array.isArray(p.type)) {
+    return (p.type as unknown[]).join(' | ');
+  }
+  if (typeof p.type === 'string') {
+    return p.format === 'uuid' ? `${p.type}（uuid）` : p.type;
+  }
+  // 空对象 = 任意值（z.unknown / unrepresentable 退化）；其余原样亮出来。
+  return Object.keys(p).filter(k => k !== 'description').length === 0
+    ? 'any'
+    : JSON.stringify(p);
+}