@qjp88995/agent-runtime 0.0.0-stage → 0.1.1

package/src/schema/message-part.ts

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+
+/**
+ * 落库消息的数据模型。搬自 agent-base `@ab/shared` 的 `schemas/agent.ts`（2026-11-11），
+ * 判据注释保留要点；改动：`ToolResultImage.src` 从 uuid 放宽为不透明字符串
+ * （字节存哪由宿主的 `ImageSource` 端口决定，runtime 不认识存储中心）。
+ *
+ * 刻意与 AI SDK 的 UIMessage.parts 不同：tool-call 与 tool-result 拆成两个 part
+ * （SDK 是合并态的 `tool-${name}`）。拆分格式厂商无关、不受 SDK 版本内部形状变化影响。
+ */
+
+/**
+ * 一张交给模型看的图（tool-result part 的 `images[]` 元素）。
+ *
+ * 库里只有 `src`，没有字节：投影层按它发一个引用，字节在请求前由图片递送解析
+ * （Files API / 公网 URL / base64 三档）。「模型看得见的一切都必须能从库里重建」，
+ * 所以 `src` 指向的内容必须不可变（换内容就是新的 `src`）。
+ */
+export const ToolResultImageSchema = z.object({
+  /** 字节的不可变身份（内容寻址的对象 id 等），由宿主的 `ImageSource` 解析。 */
+  src: z.string().min(1),
+  /** **完整子类型**（`image/jpeg`），不是顶层段 `image`。 */
+  mediaType: z.string(),
+  /** 进入对话那一刻在工作区的路径（之后可能被移走，只作提示）。 */
+  path: z.string().optional(),
+  /** 归一化后的字节数。 */
+  bytes: z.number().int().nonnegative().optional(),
+  /** 归一化后的像素尺寸。 */
+  width: z.number().int().positive().optional(),
+  height: z.number().int().positive().optional(),
+  /** 原始像素尺寸 `"3000x2000"`，**只在真的缩过时写**（模型据此换算坐标）。 */
+  origin: z.string().optional(),
+});
+export type ToolResultImage = z.infer<typeof ToolResultImageSchema>;
+
+/** 落库 part 上的厂商 metadata：与 providerOptions 同形（命名空间 → JSON 对象）。 */
+export const PartProviderMetadataSchema = z.record(
+  z.string(),
+  z.record(z.string(), z.json())
+);
+export type PartProviderMetadata = z.infer<typeof PartProviderMetadataSchema>;
+
+export const MessagePartSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('text'), text: z.string() }),
+  z.object({
+    type: z.literal('reasoning'),
+    text: z.string(),
+    /**
+     * 这一段思考产出了多久（毫秒）：第一个 `reasoning-delta` 到最后一个。
+     * 不取「请求发出」为起点（那段里有网络与排队）。可空：拿不到时间的路径没有它。
+     */
+    durationMs: z.number().int().nonnegative().optional(),
+  }),
+  z.object({
+    type: z.literal('tool-call'),
+    toolCallId: z.string(),
+    toolName: z.string(),
+    input: z.unknown(),
+    /**
+     * 厂商要求原样回传的不透明数据（Gemini 的思考签名），重放时作为这条 tool-call 的
+     * `providerOptions` 发回。**只存模型句柄 `replayedMetadataKeys` 声明的命名空间**：
+     * 别家的 metadata 原样回放会改变它们的请求形状。
+     */
+    providerMetadata: PartProviderMetadataSchema.optional(),
+  }),
+  z.object({
+    type: z.literal('tool-result'),
+    toolCallId: z.string(),
+    toolName: z.string(),
+    /** **渲染后的文本**（给人看，也是给模型看的那份），不存结构化结果。 */
+    output: z.unknown(),
+    isError: z.boolean().optional(),
+    /**
+     * 平台针对这一次调用追加的系统提示（如重复调用提醒）。与 `output` 分开存，
+     * 拼接只在投影期发生；不影响 `isError`。
+     */
+    systemNote: z.string().optional(),
+    /** 给程序认领实体用的最小结构化引用（如子 Agent 的会话 handle），由工具提供。 */
+    ref: z.record(z.string(), z.unknown()).optional(),
+    /** 这次调用交给模型看的图片（只有 `src`，见 `ToolResultImageSchema`）。 */
+    images: z.array(ToolResultImageSchema).optional(),
+    /**
+     * 上下文裁剪**不许**把这条结果的正文换成存根（如用户对提问的回答：短、且丢了
+     * 无从重得）。由工具声明，随结果落库。整行压缩不受它约束。
+     */
+    pinned: z.boolean().optional(),
+  }),
+]);
+export type MessagePart = z.infer<typeof MessagePartSchema>;
+
+/**
+ * 宿主往会话里塞的几种 user 行的标记（写在消息行 metadata 的 `kind` 上）。
+ * 落库存纯正文，围栏只在投影期拼；前端按它渲成系统标记而不是用户气泡。
+ */
+/** 上下文压缩产生的 checkpoint 行。 */
+export const COMPACTION_CHECKPOINT_KIND = 'compaction-checkpoint';
+/** 旧式重复调用提醒行（新的挂在 tool-result 的 `systemNote` 上；历史行仍要认得）。 */
+export const LOOP_REMINDER_KIND = 'loop-reminder';
+/** 待办结账提醒行。 */
+export const TODO_REMINDER_KIND = 'todo-reminder';

package/src/subagent/delegate.tool.ts

@@ -0,0 +1,476 @@
+import { z } from 'zod';
+
+import {
+  AWAIT_RENEW_INTERVAL_MS,
+  type SubagentAwaitLease,
+} from '../ports/coordination.js';
+import {
+  type Logger,
+  type LoggerFactory,
+  silentLogger,
+} from '../ports/logger.js';
+import {
+  AgentTool,
+  type ToolAccepted,
+  toolAccepted,
+} from '../tools/agent-tool.base.js';
+import type { ToolContext } from '../tools/agent-tool.interface.js';
+import {
+  DELEGATE_FORMER_NAMES,
+  DELEGATE_TOOL_NAME,
+} from '../tools/builtin-names.js';
+import type { ToolMeta } from '../tools/tool-meta.js';
+import type { ToolRegistry } from '../tools/tool-registry.js';
+import { toolError, type ToolOut } from '../tools/tool-result.js';
+import { wrapSubagentResult } from './milestone-body.js';
+import {
+  canSpawnDeeper,
+  DEPTH_EXHAUSTED_HINT,
+  MAX_SUBAGENT_DEPTH,
+  treeFullHint,
+} from './spawn-guards.js';
+import type { SubagentSessions } from './subagent-sessions.js';
+
+/**
+ * 同步等待缺省上限。**到点不算失败**：父放弃等待、拿到 handle，子照常跑完并把结论回投
+ * inbox。选小了的代价是「同步退化成异步」，不是丢结果——它只在子真的卡死时把父放出来
+ * （兜底扫描只在启动时跑，不设上限的话父就陪着泄漏的子一起挂到重启）。
+ */
+export const DELEGATE_SYNC_WAIT_MS = 30 * 60_000;
+
+/** 轮询间隔。判据是子会话行上的游标，一次读而已。 */
+export const DELEGATE_POLL_INTERVAL_MS = 1_500;
+
+const InputSchema = z.object({
+  agentType: z
+    .string()
+    .optional()
+    .describe(
+      '**派生新的**子 Agent 时填：子 Agent 名称，取自 system prompt 里' +
+        '【可派生的子 Agent】列表。与 handle 二选一，不要同时给。'
+    ),
+  handle: z
+    .string()
+    .optional()
+    .describe(
+      '给**已经派生过的**子 Agent 追加任务时填：本工具当初返回给你的那个 handle。' +
+        '它会带着你们之前的全部往来继续做事，适合修改/补充/换个角度重做。' +
+        '与 agentType 二选一，不要同时给；只能是你自己派生过的子 Agent。'
+    ),
+  title: z
+    .string()
+    .min(1)
+    .max(80)
+    .describe(
+      '一句话任务标题（≤80 字），概括这次要它做什么，用于界面展示。' +
+        '例如「调研 Claude Code 的读前写机制」「把第三段压到 200 字」。'
+    ),
+  prompt: z
+    .string()
+    .min(1)
+    .describe(
+      '这次交给它的任务。**派生新的**子 Agent 时它看不到你的对话历史，所有必要' +
+        '背景都要写进来；**追加任务**时它记得你们之前的往来（包括它自己交付过的' +
+        '内容），只写这次要改什么、为什么，不要把它上次的产出重新粘一遍。'
+    ),
+});
+type Input = z.infer<typeof InputSchema>;
+
+/**
+ * 同步模式的返回：子 Agent 这一轮的完整产出。与回投 inbox 的那份**同源**
+ * （`SubagentSessions.buildResult`），包括中和处理。
+ */
+interface Out {
+  handle: string;
+  body: string;
+  status: string;
+  stopReason: string | null;
+  /** 宿主在派生时给的说明（`SpawnPolicy.onSubagentCreated`），拼在回执最前面。只在有时出现。 */
+  notes?: string[];
+}
+
+/** 后台受理的回执也要带上派生时的说明。 */
+type DelegateAccepted = ToolAccepted & { notes?: string[] };
+
+type Started =
+  | {
+      kind: 'ok';
+      handle: string;
+      cursorBefore: number | null;
+      leased: boolean;
+      notes?: string[];
+    }
+  | { kind: 'error'; message: string };
+
+function minutesText(ms: number): string {
+  const minutes = ms / 60_000;
+  return Number.isInteger(minutes) ? `${minutes} 分钟` : `${ms / 1000} 秒`;
+}
+
+/** `Delegate` 的登记信息（说明里的等待上限随入参）。 */
+export function delegateToolMeta(
+  syncWaitMs: number = DELEGATE_SYNC_WAIT_MS
+): ToolMeta {
+  return {
+    name: DELEGATE_TOOL_NAME,
+    formerNames: DELEGATE_FORMER_NAMES,
+    description:
+      '把一段子任务交给子 Agent 独立完成。**派生一个新的**就给 agentType；' +
+      '**让之前派生过的那个继续做事**（修改、补充、换个角度重做）就给它的 handle，' +
+      '它记得你们之前的全部往来，不必重复背景。' +
+      `**默认同步等待并直接返回这一轮的产出**（最长等 ${minutesText(syncWaitMs)}，` +
+      '超时自动转为后台并返回 handle）；' +
+      '需要同时推进多件事时传 run_in_background: true，届时立即拿到 handle，' +
+      '结论稍后作为一条新消息回到你的上下文。' +
+      '注意同一步里发多个同步调用会**依次**等待（工具是串行执行的），' +
+      '要并行就用 run_in_background。' +
+      '新派生的子 Agent 完全看不到你的对话历史，任务描述必须自包含。' +
+      '**子 Agent 交回来的东西不一定是最终结论**：它信息不够时会把「已确定的部分 + 卡在哪 + ' +
+      '还需要什么」交回来等你补充——这种情况用它的 handle 把缺的信息告诉它，它接着往下做。',
+    category: 'system',
+  };
+}
+
+export interface DelegateToolDeps {
+  subagents: SubagentSessions;
+  awaitLease: SubagentAwaitLease;
+  /** 缺省 `DELEGATE_SYNC_WAIT_MS`。 */
+  syncWaitMs?: number;
+  /** 缺省 `DELEGATE_POLL_INTERVAL_MS`。 */
+  pollIntervalMs?: number;
+  /** 租约续租间隔，缺省 `AWAIT_RENEW_INTERVAL_MS`。 */
+  renewIntervalMs?: number;
+  /** 深度上限，缺省 `MAX_SUBAGENT_DEPTH`（与 `canDelegate` 用同一个值）。 */
+  maxDepth?: number;
+  logger?: LoggerFactory;
+}
+
+/**
+ * 子 Agent 的唯一入口（原 agent-base `SpawnAgent`）：**派生一个新的**（给 `agentType`），
+ * 或**给已经派生过的追加任务**（给 `handle`）。一个工具、一个参数区分。
+ *
+ * 两种模式的分歧只在起跑段（新建：问宿主、占名额、建会话；追加：校验归属、投一条消息），
+ * 之后完全一样——等子跑到 idle 终态、取这一轮的产出、包围栏、等不到就降级转后台。
+ *
+ * 追加任务不是「重新派生一个」：子会话的完整历史都在，重新派生等于让一个全新的子从零读
+ * 一遍需求、父还得把初稿全文复述给它。
+ *
+ * 同步与异步是同一条实现：子会话都是独立持久跑的（会话行 + inbox + loop + 兜底扫描），
+ * 区别只在父等不等。所以这里覆盖 `runInBackground`，不用基类那个进程内 fire-and-forget
+ * （重启即丢）。
+ */
+export class DelegateTool extends AgentTool<Input, Out> {
+  readonly inputSchema = InputSchema;
+
+  protected override readonly supportsBackground = true;
+
+  /**
+   * 比同步等待上限大一档：等待器到点会走**优雅降级**（返回 handle，告诉模型转后台了），
+   * 基类那道 race 只会给一句没信息量的超时，还把子的结果变成孤儿。这一层赢了说明等待器
+   * 自己有 bug。
+   */
+  protected override readonly timeoutMs: number;
+
+  private readonly logger: Logger;
+  private readonly syncWaitMs: number;
+  private readonly pollIntervalMs: number;
+  private readonly renewIntervalMs: number;
+  private readonly maxDepth: number;
+
+  constructor(private readonly deps: DelegateToolDeps) {
+    super();
+    this.syncWaitMs = deps.syncWaitMs ?? DELEGATE_SYNC_WAIT_MS;
+    this.pollIntervalMs = deps.pollIntervalMs ?? DELEGATE_POLL_INTERVAL_MS;
+    this.renewIntervalMs = deps.renewIntervalMs ?? AWAIT_RENEW_INTERVAL_MS;
+    this.maxDepth = deps.maxDepth ?? MAX_SUBAGENT_DEPTH;
+    this.timeoutMs = this.syncWaitMs + 60_000;
+    this.logger = (deps.logger ?? silentLogger)('DelegateTool');
+  }
+
+  /** 同步：让子跑起来 → 等它到达 idle 终态 → 返回这一轮的产出。 */
+  protected async run(
+    input: Input,
+    ctx: ToolContext
+  ): Promise<ToolOut<Out> | ToolAccepted> {
+    const started = await this.start(input, ctx, { lease: true });
+    if (started.kind !== 'ok') return started;
+    const { handle, cursorBefore, notes } = started;
+
+    // 拿不到租约就退回异步：没有租约就没有互斥，硬等下去会和收尾各投一次。
+    // **追加任务时租约必须先于投递**，`start()` 已在投递前拿过；这里只为新派生补上
+    // （它的 handle 要等会话建出来才存在）。
+    if (!started.leased && !(await this.deps.awaitLease.begin(handle))) {
+      return withNotes(toolAccepted(handle, '无法登记同步等待'), notes);
+    }
+
+    if (await this.waitForChild(handle, cursorBefore, ctx)) {
+      return this.collect(handle, cursorBefore, notes);
+    }
+
+    // 等不到了（超时 / 用户中止）。抢投递权：抢到 = 成功放弃，之后由收尾回投；没抢到 =
+    // 收尾刚刚接管，说明子其实已经跑完了，直接取产物。
+    if (await this.deps.awaitLease.claim(handle, 'parent')) {
+      const why = ctx.abortSignal.aborted ? '已中止等待' : '等待超时';
+      this.logger.warn(
+        `Delegate(${handle}) 同步等待未完成，已转后台（${why}）`
+      );
+      return withNotes(toolAccepted(handle, why), notes);
+    }
+    return this.collect(handle, cursorBefore, notes);
+  }
+
+  /** 异步：让子跑起来即返 handle，回投交给收尾。 */
+  protected override async runInBackground(
+    input: Input,
+    ctx: ToolContext
+  ): Promise<ToolOut<Out> | ToolAccepted> {
+    const started = await this.start(input, ctx, { lease: false });
+    if (started.kind !== 'ok') return started;
+    return withNotes(toolAccepted(started.handle), started.notes);
+  }
+
+  /**
+   * 两种模式共用的起跑段：返回 handle 与**这一轮开始前**的游标（null = 子从未 settle 过）。
+   * 它同时是同步等待的判据起点与取产出的起点，故父拿到的恒是「这一轮新说的话」。
+   */
+  private async start(
+    input: Input,
+    ctx: ToolContext,
+    opts: { lease: boolean }
+  ): Promise<Started> {
+    const mode = resolveMode(input);
+    if (mode.kind === 'error') return mode;
+    return mode.mode === 'follow-up'
+      ? this.startFollowUp(input, ctx, mode.handle, opts)
+      : this.startSpawn(input, ctx, mode.agentType);
+  }
+
+  /**
+   * 新建。深度守卫：触顶时本工具已从工具集摘掉（`canDelegate`），这里再挡一次。**只挡
+   * 新建**——触顶的那一层从来没派生过任何子，不可能持有 handle。
+   */
+  private async startSpawn(
+    input: Input,
+    ctx: ToolContext,
+    agentType: string
+  ): Promise<Started> {
+    if (!canSpawnDeeper(ctx.depth, this.maxDepth)) {
+      return toolError(DEPTH_EXHAUSTED_HINT);
+    }
+    const out = await this.deps.subagents.spawn({
+      agentName: agentType,
+      title: input.title,
+      prompt: input.prompt,
+      parentSessionId: ctx.sessionId,
+      rootSessionId: ctx.rootSessionId,
+      parentRunId: ctx.runId,
+      depth: ctx.depth,
+      userId: ctx.userId,
+      agent: ctx.agent,
+      sessionMetadata: ctx.sessionMetadata,
+      initiatorPermissions: ctx.initiatorPermissions ?? new Set(),
+    });
+    if (!out.ok) {
+      switch (out.reason) {
+        case 'refused':
+          return toolError(out.message);
+        case 'tree_full':
+          return toolError(treeFullHint(this.deps.subagents.maxLivePerTree));
+        default:
+          return toolError(
+            '该子 Agent 不存在或未在当前 Agent 中定义，无法派生。可选项见 system prompt 里的【可派生的子 Agent】列表。'
+          );
+      }
+    }
+    return {
+      kind: 'ok',
+      handle: out.childSessionId,
+      cursorBefore: null,
+      leased: false,
+      ...(out.notes ? { notes: out.notes } : {}),
+    };
+  }
+
+  /**
+   * 追加任务：校验归属 → （同步模式）拿租约 → 投递。三步的顺序都是必须的：
+   *
+   * - **校验先于租约**：给一个不属于本父的会话种下租约，会让真正在等它的父被收尾跳过
+   *   投递——一次静默丢失的回执。
+   * - **租约先于投递**：反过来的话子可能在父开始等之前就跑完，收尾拿不到租约便回投
+   *   inbox，父随后又同步取一份——双份回执。
+   * - **游标读在投递之前**：投递后再读可能读到子已经推进过的新值，父会拿着上一轮的结果
+   *   立刻返回。
+   */
+  private async startFollowUp(
+    input: Input,
+    ctx: ToolContext,
+    handle: string,
+    opts: { lease: boolean }
+  ): Promise<Started> {
+    const target = await this.deps.subagents.resolveFollowUpTarget({
+      childSessionId: handle,
+      parentSessionId: ctx.sessionId,
+    });
+    if (!target.ok) {
+      // 两种拒绝给不同的话：「没这个子」要它核对 handle，「不是你的子」要它明白这条路
+      // 根本不通——合成一句「无法追加」的话，模型只会换个 id 再试。
+      return toolError(
+        target.reason === 'not_found'
+          ? `找不到 handle 为 ${handle} 的子 Agent。请核对本工具当初返回给你的 id；` +
+              '如果这是一个全新的任务，改用 agentType 派生一个新的。'
+          : `handle 为 ${handle} 的子 Agent 不是你派生的，你不能给它派任务。` +
+              '只有你自己派生出来的子 Agent 才能追加任务；' +
+              '你派生的子 Agent 自己再往下派生的那一层，要由它去指挥。'
+      );
+    }
+    // 拿不到租约不阻断投递——任务不该因为「没法同步等」而丢掉，调用方据 leased 退回异步。
+    const leased = opts.lease
+      ? await this.deps.awaitLease.begin(handle)
+      : false;
+    await this.deps.subagents.deliverFollowUp({
+      childSessionId: handle,
+      prompt: input.prompt,
+      userId: ctx.userId,
+    });
+    return { kind: 'ok', handle, cursorBefore: target.cursorBefore, leased };
+  }
+
+  /**
+   * 轮询到子的游标越过 `cursorBefore`。false = 没等到（超时或中止）。判据取游标而非「子有没有
+   * 新消息」：游标是收尾的 CAS 写的，它一推进就意味着收尾已经走过 claim——父此刻去取产物，
+   * 绝不会与「收尾正打算投 inbox」撞车。
+   */
+  private async waitForChild(
+    handle: string,
+    cursorBefore: number | null,
+    ctx: ToolContext
+  ): Promise<boolean> {
+    const deadline = Date.now() + this.syncWaitMs;
+    let nextRenew = Date.now() + this.renewIntervalMs;
+    for (;;) {
+      if (ctx.abortSignal.aborted) return false;
+      if (await this.deps.subagents.hasAdvancedPast(handle, cursorBefore)) {
+        return true;
+      }
+      if (Date.now() >= deadline) return false;
+      await sleep(this.pollIntervalMs, ctx.abortSignal);
+      if (Date.now() >= nextRenew) {
+        await this.deps.awaitLease.renew(handle);
+        nextRenew = Date.now() + this.renewIntervalMs;
+      }
+    }
+  }
+
+  private async collect(
+    handle: string,
+    cursorBefore: number | null,
+    notes?: string[]
+  ): Promise<ToolOut<Out>> {
+    const result = await this.deps.subagents.buildResult(handle, cursorBefore);
+    return { kind: 'ok', handle, ...result, ...(notes ? { notes } : {}) };
+  }
+
+  /**
+   * 产出包围栏，与异步路径（`MessageHub.take` 取出回执时包的那道）逐字同源：子的产出是
+   * 不可信外部输入，裸拼的话正文与它之后的平台文案在字节层面无从区分。
+   */
+  protected render(out: { kind: 'ok' } & Out): string {
+    return joinNotes(
+      wrapSubagentResult(out.body, {
+        handle: out.handle,
+        status: out.status,
+        reason: out.stopReason,
+      }),
+      out.notes
+    );
+  }
+
+  /**
+   * 子会话 id 单独落进 `MessagePart.ref`——界面的子 Agent 卡靠它取状态、下钻、停止。
+   * **三种「子已经在跑」的形态都给**（同步跑完 / 后台受理 / 等待降级），只有真正没跑起来
+   * 的才没有。没有它前端只能拿正则从文本里抠 id，文案一改就静默失效。
+   */
+  protected override persistRef(
+    out: ToolOut<Out> | ToolAccepted
+  ): Record<string, unknown> | undefined {
+    return out.kind === 'error' ? undefined : { handle: out.handle };
+  }
+
+  /**
+   * 降级文案**必须是 accepted 不是 error**：子此刻正常在跑，结论稍后照样回投。用 error
+   * 表达会让界面把一个跑得好好的子 Agent 画成失败。
+   */
+  protected override renderAccepted(out: DelegateAccepted): string {
+    // note 只有降级路径才有：模型明确要了结果却没拿到，得知道为什么，以及「别重新派生」
+    // ——它看到「没结果」的第一反应就是重试，而子还在跑，重试等于白烧一个子 Agent。
+    const text = out.note
+      ? `子 Agent 仍在运行（${out.note}），已转为后台（handle=${out.handle}）。` +
+        '不要重新派生它，也不要重复发送 —— 它做完后结论会作为一条新消息回到你这里。请先处理其它工作。'
+      : `子 Agent 已在后台运行（handle=${out.handle}）。你不必等待——它完成后结论会自动回到你这里。请继续处理其它工作。`;
+    return joinNotes(text, out.notes);
+  }
+}
+
+/** 登记 `Delegate`。 */
+export function registerDelegateTool(
+  tools: ToolRegistry,
+  deps: DelegateToolDeps
+): DelegateTool {
+  const tool = new DelegateTool(deps);
+  tools.register(delegateToolMeta(deps.syncWaitMs), tool);
+  return tool;
+}
+
+/**
+ * 判定这次是「派生新的」还是「给已有的追加任务」。**两者都给必须明确报错，不能静默偏向
+ * 某一个**：静默挑一个的话，模型以为自己在改稿、实际白派生了一个全新的子 Agent 从零重写，
+ * 而拿到的产出看起来完全正常。schema 表达不了「恰填其一」（注册表要往 `ZodObject` 上注入
+ * `run_in_background`），所以这道判断落在运行时。
+ */
+function resolveMode(
+  input: Input
+):
+  | { kind: 'ok'; mode: 'spawn'; agentType: string }
+  | { kind: 'ok'; mode: 'follow-up'; handle: string }
+  | { kind: 'error'; message: string } {
+  const agentType = input.agentType?.trim() || undefined;
+  const handle = input.handle?.trim() || undefined;
+  if (agentType && handle) {
+    return toolError(
+      'agentType 与 handle 只能给一个：要派生一个新的子 Agent 就只给 agentType，' +
+        '要让已经派生过的那个继续做事就只给 handle（它会带着之前的往来接着做）。'
+    );
+  }
+  if (handle) return { kind: 'ok', mode: 'follow-up', handle };
+  if (agentType) return { kind: 'ok', mode: 'spawn', agentType };
+  return toolError(
+    '缺少 agentType 或 handle：要派生一个新的子 Agent 就给 agentType' +
+      '（可选项见 system prompt 里的【可派生的子 Agent】列表）；' +
+      '要让已经派生过的那个继续做事就给它的 handle。'
+  );
+}
+
+function withNotes(
+  accepted: ToolAccepted,
+  notes: string[] | undefined
+): DelegateAccepted {
+  return notes ? { ...accepted, notes } : accepted;
+}
+
+/** 说明各占一行，接一个空行再是正文；没有说明原样返回。 */
+function joinNotes(text: string, notes: readonly string[] | undefined): string {
+  return notes && notes.length > 0 ? `${notes.join('\n')}\n\n${text}` : text;
+}
+
+/** 可中止的 sleep：信号一来立刻醒。 */
+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/subagent/index.ts

@@ -0,0 +1,63 @@
+export {
+  DELEGATE_POLL_INTERVAL_MS,
+  DELEGATE_SYNC_WAIT_MS,
+  DelegateTool,
+  type DelegateToolDeps,
+  delegateToolMeta,
+  registerDelegateTool,
+} from './delegate.tool.js';
+export {
+  buildMilestoneBody,
+  escapeSubagentFence,
+  isFailedTerminal,
+  type MilestoneTerminal,
+  normalizeMilestoneStatus,
+  type SubagentResultFence,
+  wrapSubagentResult,
+} from './milestone-body.js';
+export { type ScanResult, scanSubagentOutput } from './output-scan.js';
+export {
+  registrySpawnPolicy,
+  type RegistrySpawnPolicyOptions,
+} from './registry-spawn-policy.js';
+export {
+  buildSubagentIndexBlock,
+  DESC_LIMIT,
+  OWN_GROUP_HEADING,
+  type SubagentIndexEntry,
+} from './roster-block.js';
+export {
+  buildSubagentSituationBlock,
+  DEFAULT_AGENT_PROMPT_BLOCK,
+  type SubagentSituationOptions,
+} from './situation-block.js';
+export {
+  canDelegate,
+  canSpawnDeeper,
+  DEPTH_EXHAUSTED_HINT,
+  MAX_LIVE_SUBS_PER_TREE,
+  MAX_SUBAGENT_DEPTH,
+  TREE_FULL_HINT,
+  treeFullHint,
+} from './spawn-guards.js';
+export {
+  GENERAL_PURPOSE_PROMPT,
+  GENERAL_PURPOSE_SUBAGENT,
+  type SubagentAccess,
+  type SubagentMeta,
+  type SubagentProvider,
+  SubagentRegistry,
+  type SubagentRegistryOptions,
+} from './subagent-registry.js';
+export {
+  type FollowUpTarget,
+  type SpawnCheck,
+  type SpawnOutcome,
+  type SpawnPolicy,
+  type SpawnRequest,
+  SUBAGENT_SWEEP_IDLE_MS,
+  type SubagentResult,
+  SubagentSessions,
+  type SubagentSessionsDeps,
+  type SubagentTickInfo,
+} from './subagent-sessions.js';