@qjp88995/agent-runtime 0.0.0-stage → 0.1.1

package/dist/schema/agent-run.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+/** 跑次（一次 agent 执行，根或子）的状态。 */
+export declare const AGENT_RUN_STATUSES: readonly ["running", "completed", "aborted", "rejected", "failed"];
+export type AgentRunStatus = (typeof AGENT_RUN_STATUSES)[number];
+/** 一轮为什么停下。 */
+export declare const STOP_REASONS: readonly ["stop", "max-steps", "timeout", "aborted", "api-error", "rejected-by-hook", "blocked-by-hook", "error"];
+export type StopReason = (typeof STOP_REASONS)[number];
+/** 步级明细（随跑次一起存，不另开子表）。 */
+export declare const AgentRunStepEntrySchema: z.ZodObject<{
+    index: z.ZodNumber;
+    text: z.ZodOptional<z.ZodString>;
+    toolCalls: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        toolCallId: z.ZodString;
+        toolName: z.ZodString;
+        input: z.ZodUnknown;
+        output: z.ZodOptional<z.ZodUnknown>;
+        ok: z.ZodOptional<z.ZodBoolean>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    usage: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+}, z.core.$strip>;
+export type AgentRunStepEntry = z.infer<typeof AgentRunStepEntrySchema>;
+//# sourceMappingURL=agent-run.d.ts.map

package/dist/schema/agent-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-run.d.ts","sourceRoot":"","sources":["../../src/schema/agent-run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,8BAA8B;AAC9B,eAAO,MAAM,kBAAkB,oEAMrB,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE,eAAe;AACf,eAAO,MAAM,YAAY,mHASf,CAAC;AACX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,0BAA0B;AAC1B,eAAO,MAAM,uBAAuB;;;;;;;;;;;;iBAgBlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}

package/dist/schema/agent-run.js

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+/** 跑次（一次 agent 执行，根或子）的状态。 */
+export const AGENT_RUN_STATUSES = [
+    'running',
+    'completed',
+    'aborted',
+    'rejected',
+    'failed',
+];
+/** 一轮为什么停下。 */
+export const STOP_REASONS = [
+    'stop',
+    'max-steps',
+    'timeout',
+    'aborted',
+    'api-error',
+    'rejected-by-hook',
+    'blocked-by-hook',
+    'error',
+];
+/** 步级明细（随跑次一起存，不另开子表）。 */
+export const AgentRunStepEntrySchema = z.object({
+    index: z.number().int(),
+    text: z.string().optional(),
+    toolCalls: z
+        .array(z.object({
+        toolCallId: z.string(),
+        toolName: z.string(),
+        input: z.unknown(),
+        output: z.unknown().optional(),
+        ok: z.boolean().optional(),
+        durationMs: z.number().optional(),
+    }))
+        .default([]),
+    usage: z.record(z.string(), z.number()).optional(),
+});
+//# sourceMappingURL=agent-run.js.map

package/dist/schema/agent-run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-run.js","sourceRoot":"","sources":["../../src/schema/agent-run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,8BAA8B;AAC9B,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,SAAS;IACT,WAAW;IACX,SAAS;IACT,UAAU;IACV,QAAQ;CACA,CAAC;AAGX,eAAe;AACf,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,MAAM;IACN,WAAW;IACX,SAAS;IACT,SAAS;IACT,WAAW;IACX,kBAAkB;IAClB,iBAAiB;IACjB,OAAO;CACC,CAAC;AAGX,0BAA0B;AAC1B,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACvB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,SAAS,EAAE,CAAC;SACT,KAAK,CACJ,CAAC,CAAC,MAAM,CAAC;QACP,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;QACtB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;QACpB,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE;QAClB,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;QAC9B,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;QAC1B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAClC,CAAC,CACH;SACA,OAAO,CAAC,EAAE,CAAC;IACd,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;CACnD,CAAC,CAAC"}

package/dist/schema/index.d.ts

@@ -0,0 +1,4 @@
+export { AGENT_EVENT_TYPES, type AgentEvent, type AgentEventType, createSeqCounter, } from './agent-event.js';
+export { AGENT_RUN_STATUSES, type AgentRunStatus, type AgentRunStepEntry, AgentRunStepEntrySchema, STOP_REASONS, type StopReason, } from './agent-run.js';
+export { COMPACTION_CHECKPOINT_KIND, LOOP_REMINDER_KIND, type MessagePart, MessagePartSchema, type PartProviderMetadata, PartProviderMetadataSchema, TODO_REMINDER_KIND, type ToolResultImage, ToolResultImageSchema, } from './message-part.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/schema/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schema/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,kBAAkB,EAClB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,uBAAuB,EACvB,YAAY,EACZ,KAAK,UAAU,GAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,0BAA0B,EAC1B,kBAAkB,EAClB,KAAK,WAAW,EAChB,iBAAiB,EACjB,KAAK,oBAAoB,EACzB,0BAA0B,EAC1B,kBAAkB,EAClB,KAAK,eAAe,EACpB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC"}

package/dist/schema/index.js

@@ -0,0 +1,4 @@
+export { AGENT_EVENT_TYPES, createSeqCounter, } from './agent-event.js';
+export { AGENT_RUN_STATUSES, AgentRunStepEntrySchema, STOP_REASONS, } from './agent-run.js';
+export { COMPACTION_CHECKPOINT_KIND, LOOP_REMINDER_KIND, MessagePartSchema, PartProviderMetadataSchema, TODO_REMINDER_KIND, ToolResultImageSchema, } from './message-part.js';
+//# sourceMappingURL=index.js.map

package/dist/schema/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/schema/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EAGjB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,kBAAkB,EAGlB,uBAAuB,EACvB,YAAY,GAEb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,0BAA0B,EAC1B,kBAAkB,EAElB,iBAAiB,EAEjB,0BAA0B,EAC1B,kBAAkB,EAElB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC"}

package/dist/schema/message-part.d.ts

@@ -0,0 +1,73 @@
+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 declare const ToolResultImageSchema: z.ZodObject<{
+    src: z.ZodString;
+    mediaType: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    bytes: z.ZodOptional<z.ZodNumber>;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+    origin: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ToolResultImage = z.infer<typeof ToolResultImageSchema>;
+/** 落库 part 上的厂商 metadata：与 providerOptions 同形（命名空间 → JSON 对象）。 */
+export declare const PartProviderMetadataSchema: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+export type PartProviderMetadata = z.infer<typeof PartProviderMetadataSchema>;
+export declare const MessagePartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"reasoning">;
+    text: z.ZodString;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"tool-call">;
+    toolCallId: z.ZodString;
+    toolName: z.ZodString;
+    input: z.ZodUnknown;
+    providerMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodJSONSchema>>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"tool-result">;
+    toolCallId: z.ZodString;
+    toolName: z.ZodString;
+    output: z.ZodUnknown;
+    isError: z.ZodOptional<z.ZodBoolean>;
+    systemNote: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    images: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        src: z.ZodString;
+        mediaType: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        bytes: z.ZodOptional<z.ZodNumber>;
+        width: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+        origin: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    pinned: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>], "type">;
+export type MessagePart = z.infer<typeof MessagePartSchema>;
+/**
+ * 宿主往会话里塞的几种 user 行的标记（写在消息行 metadata 的 `kind` 上）。
+ * 落库存纯正文，围栏只在投影期拼；前端按它渲成系统标记而不是用户气泡。
+ */
+/** 上下文压缩产生的 checkpoint 行。 */
+export declare const COMPACTION_CHECKPOINT_KIND = "compaction-checkpoint";
+/** 旧式重复调用提醒行（新的挂在 tool-result 的 `systemNote` 上；历史行仍要认得）。 */
+export declare const LOOP_REMINDER_KIND = "loop-reminder";
+/** 待办结账提醒行。 */
+export declare const TODO_REMINDER_KIND = "todo-reminder";
+//# sourceMappingURL=message-part.d.ts.map

package/dist/schema/message-part.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-part.d.ts","sourceRoot":"","sources":["../../src/schema/message-part.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;iBAchC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,kEAAkE;AAClE,eAAO,MAAM,0BAA0B,qEAGtC,CAAC;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BA6C5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;GAGG;AACH,6BAA6B;AAC7B,eAAO,MAAM,0BAA0B,0BAA0B,CAAC;AAClE,4DAA4D;AAC5D,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAClD,eAAe;AACf,eAAO,MAAM,kBAAkB,kBAAkB,CAAC"}

package/dist/schema/message-part.js

@@ -0,0 +1,90 @@
+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(),
+});
+/** 落库 part 上的厂商 metadata：与 providerOptions 同形（命名空间 → JSON 对象）。 */
+export const PartProviderMetadataSchema = z.record(z.string(), z.record(z.string(), z.json()));
+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(),
+    }),
+]);
+/**
+ * 宿主往会话里塞的几种 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';
+//# sourceMappingURL=message-part.js.map

package/dist/schema/message-part.js.map

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

package/dist/subagent/delegate.tool.d.ts

@@ -0,0 +1,145 @@
+import { z } from 'zod';
+import { type SubagentAwaitLease } from '../ports/coordination.js';
+import { type LoggerFactory } from '../ports/logger.js';
+import { AgentTool, type ToolAccepted } from '../tools/agent-tool.base.js';
+import type { ToolContext } from '../tools/agent-tool.interface.js';
+import type { ToolMeta } from '../tools/tool-meta.js';
+import type { ToolRegistry } from '../tools/tool-registry.js';
+import { type ToolOut } from '../tools/tool-result.js';
+import type { SubagentSessions } from './subagent-sessions.js';
+/**
+ * 同步等待缺省上限。**到点不算失败**：父放弃等待、拿到 handle，子照常跑完并把结论回投
+ * inbox。选小了的代价是「同步退化成异步」，不是丢结果——它只在子真的卡死时把父放出来
+ * （兜底扫描只在启动时跑，不设上限的话父就陪着泄漏的子一起挂到重启）。
+ */
+export declare const DELEGATE_SYNC_WAIT_MS: number;
+/** 轮询间隔。判据是子会话行上的游标，一次读而已。 */
+export declare const DELEGATE_POLL_INTERVAL_MS = 1500;
+declare const InputSchema: z.ZodObject<{
+    agentType: z.ZodOptional<z.ZodString>;
+    handle: z.ZodOptional<z.ZodString>;
+    title: z.ZodString;
+    prompt: z.ZodString;
+}, z.core.$strip>;
+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[];
+};
+/** `Delegate` 的登记信息（说明里的等待上限随入参）。 */
+export declare function delegateToolMeta(syncWaitMs?: number): ToolMeta;
+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 declare class DelegateTool extends AgentTool<Input, Out> {
+    private readonly deps;
+    readonly inputSchema: z.ZodObject<{
+        agentType: z.ZodOptional<z.ZodString>;
+        handle: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        prompt: z.ZodString;
+    }, z.core.$strip>;
+    protected readonly supportsBackground = true;
+    /**
+     * 比同步等待上限大一档：等待器到点会走**优雅降级**（返回 handle，告诉模型转后台了），
+     * 基类那道 race 只会给一句没信息量的超时，还把子的结果变成孤儿。这一层赢了说明等待器
+     * 自己有 bug。
+     */
+    protected readonly timeoutMs: number;
+    private readonly logger;
+    private readonly syncWaitMs;
+    private readonly pollIntervalMs;
+    private readonly renewIntervalMs;
+    private readonly maxDepth;
+    constructor(deps: DelegateToolDeps);
+    /** 同步：让子跑起来 → 等它到达 idle 终态 → 返回这一轮的产出。 */
+    protected run(input: Input, ctx: ToolContext): Promise<ToolOut<Out> | ToolAccepted>;
+    /** 异步：让子跑起来即返 handle，回投交给收尾。 */
+    protected runInBackground(input: Input, ctx: ToolContext): Promise<ToolOut<Out> | ToolAccepted>;
+    /**
+     * 两种模式共用的起跑段：返回 handle 与**这一轮开始前**的游标（null = 子从未 settle 过）。
+     * 它同时是同步等待的判据起点与取产出的起点，故父拿到的恒是「这一轮新说的话」。
+     */
+    private start;
+    /**
+     * 新建。深度守卫：触顶时本工具已从工具集摘掉（`canDelegate`），这里再挡一次。**只挡
+     * 新建**——触顶的那一层从来没派生过任何子，不可能持有 handle。
+     */
+    private startSpawn;
+    /**
+     * 追加任务：校验归属 → （同步模式）拿租约 → 投递。三步的顺序都是必须的：
+     *
+     * - **校验先于租约**：给一个不属于本父的会话种下租约，会让真正在等它的父被收尾跳过
+     *   投递——一次静默丢失的回执。
+     * - **租约先于投递**：反过来的话子可能在父开始等之前就跑完，收尾拿不到租约便回投
+     *   inbox，父随后又同步取一份——双份回执。
+     * - **游标读在投递之前**：投递后再读可能读到子已经推进过的新值，父会拿着上一轮的结果
+     *   立刻返回。
+     */
+    private startFollowUp;
+    /**
+     * 轮询到子的游标越过 `cursorBefore`。false = 没等到（超时或中止）。判据取游标而非「子有没有
+     * 新消息」：游标是收尾的 CAS 写的，它一推进就意味着收尾已经走过 claim——父此刻去取产物，
+     * 绝不会与「收尾正打算投 inbox」撞车。
+     */
+    private waitForChild;
+    private collect;
+    /**
+     * 产出包围栏，与异步路径（`MessageHub.take` 取出回执时包的那道）逐字同源：子的产出是
+     * 不可信外部输入，裸拼的话正文与它之后的平台文案在字节层面无从区分。
+     */
+    protected render(out: {
+        kind: 'ok';
+    } & Out): string;
+    /**
+     * 子会话 id 单独落进 `MessagePart.ref`——界面的子 Agent 卡靠它取状态、下钻、停止。
+     * **三种「子已经在跑」的形态都给**（同步跑完 / 后台受理 / 等待降级），只有真正没跑起来
+     * 的才没有。没有它前端只能拿正则从文本里抠 id，文案一改就静默失效。
+     */
+    protected persistRef(out: ToolOut<Out> | ToolAccepted): Record<string, unknown> | undefined;
+    /**
+     * 降级文案**必须是 accepted 不是 error**：子此刻正常在跑，结论稍后照样回投。用 error
+     * 表达会让界面把一个跑得好好的子 Agent 画成失败。
+     */
+    protected renderAccepted(out: DelegateAccepted): string;
+}
+/** 登记 `Delegate`。 */
+export declare function registerDelegateTool(tools: ToolRegistry, deps: DelegateToolDeps): DelegateTool;
+export {};
+//# sourceMappingURL=delegate.tool.d.ts.map

package/dist/subagent/delegate.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate.tool.d.ts","sourceRoot":"","sources":["../../src/subagent/delegate.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAEL,KAAK,aAAa,EAEnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,SAAS,EACT,KAAK,YAAY,EAElB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAKpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAa,KAAK,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAQlE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,QAAc,CAAC;AAEjD,8BAA8B;AAC9B,eAAO,MAAM,yBAAyB,OAAQ,CAAC;AAE/C,QAAA,MAAM,WAAW;;;;;iBAgCf,CAAC;AACH,KAAK,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEzC;;;GAGG;AACH,UAAU,GAAG;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,yBAAyB;AACzB,KAAK,gBAAgB,GAAG,YAAY,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAiB5D,qCAAqC;AACrC,wBAAgB,gBAAgB,CAC9B,UAAU,GAAE,MAA8B,GACzC,QAAQ,CAmBV;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,UAAU,EAAE,kBAAkB,CAAC;IAC/B,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2CAA2C;IAC3C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,YAAa,SAAQ,SAAS,CAAC,KAAK,EAAE,GAAG,CAAC;IAkBzC,OAAO,CAAC,QAAQ,CAAC,IAAI;IAjBjC,QAAQ,CAAC,WAAW;;;;;sBAAe;IAEnC,mBAA4B,kBAAkB,QAAQ;IAEtD;;;;OAIG;IACH,mBAA4B,SAAS,EAAE,MAAM,CAAC;IAE9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEL,IAAI,EAAE,gBAAgB;IAUnD,0CAA0C;cAC1B,GAAG,CACjB,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC;IA4BvC,gCAAgC;cACP,eAAe,CACtC,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC;IAMvC;;;OAGG;YACW,KAAK;IAYnB;;;OAGG;YACW,UAAU;IA0CxB;;;;;;;;;OASG;YACW,aAAa;IAkC3B;;;;OAIG;YACW,YAAY;YAqBZ,OAAO;IASrB;;;OAGG;IACH,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE;QAAE,IAAI,EAAE,IAAI,CAAA;KAAE,GAAG,GAAG,GAAG,MAAM;IAWnD;;;;OAIG;cACgB,UAAU,CAC3B,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,YAAY,GAC/B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAItC;;;OAGG;cACgB,cAAc,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM;CASjE;AAED,qBAAqB;AACrB,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,gBAAgB,GACrB,YAAY,CAId"}