@migor/agentia 0.2.1 → 0.3.0

package/dist/engine/concurrency.js

@@ -0,0 +1,95 @@
+/**
+ * Agentia —— 有界并发与超时（C2）。零依赖，供「同一回合的并行工具调用」用。
+ */
+/**
+ * 有界并发 map：最多 `limit` 个 `fn` 同时在飞，**结果顺序与输入一致**
+ * （调用方按序拼 tool_result，模型靠 tool_use_id 配对，顺序改动会打乱可读性）。
+ *
+ * `limit` 非正数或非有限值一律视为**不限**（= 旧行为 `Promise.all`）。
+ */
+export async function mapWithConcurrency(items, limit, fn) {
+    const results = new Array(items.length);
+    if (items.length === 0)
+        return results;
+    const width = Number.isFinite(limit) && limit > 0 ? Math.min(Math.floor(limit), items.length) : items.length;
+    // 取号自增在同步段完成（`next++` 在读 item 之前），所以 worker 之间不会重号。
+    let next = 0;
+    const worker = async () => {
+        for (;;) {
+            const i = next++;
+            if (i >= items.length)
+                return;
+            results[i] = await fn(items[i], i);
+        }
+    };
+    await Promise.all(Array.from({ length: width }, worker));
+    return results;
+}
+/** 超时哨兵：区分「超时」与「工具恰好返回了 undefined」 */
+export const TIMED_OUT = Symbol('agentia.timed-out');
+/**
+ * 给一个 promise 套超时；超时返回 `TIMED_OUT`。
+ *
+ * ⚠️ **不取消底层** —— `AgentTool.run` 拿不到 signal（那会破坏现有签名），所以
+ * 「超时」的语义是**放弃等待**：副作用可能已经发生，只是我们不等了。
+ * 想真停下来的工具请自行读 `ToolRunContext.signal`（框架传了，但**不强制**工具中断
+ * —— 见 core/tool.ts 的说明：工具副作用无法回滚）。
+ *
+ * **超时是硬的**（2026-09-14 收紧，见 `docs/spec.md` §10）：判定不看竞速结果，而看**实测耗时**。
+ * 原因：`Promise.race` 不是硬保证 —— 两个计时器在同一毫秒内建、又因事件循环被饿住而同批到期时，
+ * 列表顺序决定谁先 resolve，**超预算的工具能赢过截止计时器**（实测 `60ms 工具 vs 20ms 预算`
+ * 在 8 倍 CPU 超订下 1200 次翻转 1 次，记成 `ok: true`，护栏静默失效）。
+ * 代价是语义收紧：`21ms 完成 / 20ms 预算` 由「成功」变「超时」—— 这正确，
+ * 「预算」本来就是对**实际耗时**的承诺，不是对调度运气的承诺。
+ *
+ * `timeoutMs` 非正数 = 不设超时（直接返回原 promise）。
+ *
+ * ⚠️ **截止计时器绝不可 `unref()`**（2026-09-14 修正，见 `docs/spec.md` §10 ④）：
+ * 这个计时器的**触发本身就是「被 await 的 promise 得以 settle」的条件**。一旦 unref，
+ * 当它是事件循环里唯一的把手时，进程会在它触发前直接退出 —— `await` **永不 settle**。
+ * 实测（空事件循环、挂死的 promise，Node 22 与 26 一个样）：
+ *
+ * | 计时器 | 结果 |
+ * |---|---|
+ * | `unref()` | 进程退出（顶层 await 未 settle），**什么都没返回** |
+ * | 不 unref | `settled: TIMED_OUT`，exit 0 |
+ *
+ * 「兜底计时器不该让宿主为它续命」这条理由对**没人 await 的兜底 tick**（scheduler 的下一拍、
+ * SSE 心跳、metrics 刷盘）成立，对**「等待的终点」**不成立：那正是调用方在等的东西。
+ */
+export async function withTimeout(p, timeoutMs) {
+    if (!(timeoutMs > 0))
+        return p;
+    const startedAt = Date.now();
+    // 在**工具 settle 的那个微任务里**记时间，而不是 `await` 恢复之后再记：
+    // 微任务紧跟在 resolve 它的那次回调之后跑，所以这个时刻最贴近「工具真正完成」。
+    // 若改成 await 恢复后再测，宿主在「工具完成 → 恢复」之间被饿住会把按时完成的工具误判成超时。
+    let settledAt = 0;
+    const tracked = p.then((v) => {
+        settledAt = Date.now();
+        return v;
+    }, (e) => {
+        settledAt = Date.now();
+        throw e;
+    });
+    let timer;
+    try {
+        const out = await Promise.race([
+            tracked,
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(TIMED_OUT), timeoutMs);
+                // ⚠️ 不 unref：它的触发是「这个 await 得以结束」的条件（详见函数头注释的实测表）。
+                // unref 过它 ⇒ 空事件循环下进程先退出，await 永不 settle。
+            }),
+        ]);
+        // 竞速只当快路径；最终以实测耗时兜底判定（见上面注释里的翻转样本）。
+        if (out === TIMED_OUT)
+            return TIMED_OUT;
+        return settledAt - startedAt >= timeoutMs ? TIMED_OUT : out;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=concurrency.js.map

package/dist/engine/concurrency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.js","sourceRoot":"","sources":["../../src/engine/concurrency.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAmB,EACnB,KAAa,EACb,EAA0C;IAE1C,MAAM,OAAO,GAAG,IAAI,KAAK,CAAI,KAAK,CAAC,MAAM,CAAC,CAAC;IAC3C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IACvC,MAAM,KAAK,GACT,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC;IACjG,oDAAoD;IACpD,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,MAAM,MAAM,GAAG,KAAK,IAAmB,EAAE;QACvC,SAAS,CAAC;YACR,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC;YACjB,IAAI,CAAC,IAAI,KAAK,CAAC,MAAM;gBAAE,OAAO;YAC9B,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACrC,CAAC;IACH,CAAC,CAAC;IACF,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;IACzD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,sCAAsC;AACtC,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,CAAa,EACb,SAAiB;IAEjB,IAAI,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,gDAAgD;IAChD,8CAA8C;IAC9C,qDAAqD;IACrD,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,MAAM,OAAO,GAAG,CAAC,CAAC,IAAI,CACpB,CAAC,CAAC,EAAE,EAAE;QACJ,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,OAAO,CAAC,CAAC;IACX,CAAC,EACD,CAAC,CAAC,EAAE,EAAE;QACJ,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,CAAC,CAAC;IACV,CAAC,CACF,CAAC;IACF,IAAI,KAAiC,CAAC;IACtC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;YAC7B,OAAO;YACP,IAAI,OAAO,CAAmB,CAAC,OAAO,EAAE,EAAE;gBACxC,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC,CAAC;gBACxD,mDAAmD;gBACnD,0CAA0C;YAC5C,CAAC,CAAC;SACH,CAAC,CAAC;QACH,oCAAoC;QACpC,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACxC,OAAO,SAAS,GAAG,SAAS,IAAI,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC;IAC9D,CAAC;YAAS,CAAC;QACT,IAAI,KAAK;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;AACH,CAAC"}

package/dist/engine/errors.d.ts

@@ -1,3 +1,5 @@
 import type { SpanError } from '../core/trace.js';
+/** 是否中断异常（DOMException / 普通 Error 都可能是，靠 name 判定） */
+export declare function isAbortError(e: unknown): boolean;
 /** 把任意异常分类成 trace 可用的 SpanError（可重试 vs 不可重试）。 */
 export declare function classifyError(e: unknown): SpanError;

package/dist/engine/errors.js

@@ -1,6 +1,13 @@
 import Anthropic from '@anthropic-ai/sdk';
+/** 是否中断异常（DOMException / 普通 Error 都可能是，靠 name 判定） */
+export function isAbortError(e) {
+    return typeof e === 'object' && e !== null && e.name === 'AbortError';
+}
 /** 把任意异常分类成 trace 可用的 SpanError（可重试 vs 不可重试）。 */
 export function classifyError(e) {
+    if (isAbortError(e)) {
+        return { type: 'aborted', message: 'run 已被取消', retryable: false };
+    }
     if (e instanceof Anthropic.RateLimitError) {
         return { type: 'rate_limit', message: e.message, retryable: true };
     }

package/dist/engine/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/engine/errors.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAG1C,iDAAiD;AACjD,MAAM,UAAU,aAAa,CAAC,CAAU;IACtC,IAAI,CAAC,YAAY,SAAS,CAAC,cAAc,EAAE,CAAC;QAC1C,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACrE,CAAC;IACD,IAAI,CAAC,YAAY,SAAS,CAAC,kBAAkB,EAAE,CAAC;QAC9C,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACrE,CAAC;IACD,IAAI,CAAC,YAAY,SAAS,CAAC,mBAAmB,EAAE,CAAC;QAC/C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACjE,CAAC;IACD,IAAI,CAAC,YAAY,SAAS,CAAC,QAAQ,EAAE,CAAC;QACpC,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC;QAC7B,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,GAAG,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;IACzF,CAAC;IACD,IAAI,CAAC,YAAY,KAAK,EAAE,CAAC;QACvB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACnE,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;AACnE,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/engine/errors.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAG1C,qDAAqD;AACrD,MAAM,UAAU,YAAY,CAAC,CAAU;IACrC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAK,CAAwB,CAAC,IAAI,KAAK,YAAY,CAAC;AAChG,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,aAAa,CAAC,CAAU;IACtC,IAAI,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;QACpB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACpE,CAAC;IACD,IAAI,CAAC,YAAY,SAAS,CAAC,cAAc,EAAE,CAAC;QAC1C,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACrE,CAAC;IACD,IAAI,CAAC,YAAY,SAAS,CAAC,kBAAkB,EAAE,CAAC;QAC9C,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACrE,CAAC;IACD,IAAI,CAAC,YAAY,SAAS,CAAC,mBAAmB,EAAE,CAAC;QAC/C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACjE,CAAC;IACD,IAAI,CAAC,YAAY,SAAS,CAAC,QAAQ,EAAE,CAAC;QACpC,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC;QAC7B,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,GAAG,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;IACzF,CAAC;IACD,IAAI,CAAC,YAAY,KAAK,EAAE,CAAC;QACvB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACnE,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;AACnE,CAAC"}

package/dist/engine/loop.d.ts

@@ -1,6 +1,7 @@
-import Anthropic from '@anthropic-ai/sdk';
-import type { AgentTool, JsonSchema, ModelClient, RecorderBackend } from '../core/tool.js';
+import type Anthropic from '@anthropic-ai/sdk';
+import type { AgentTool, JsonSchema, ModelClient, ModelPricing, RecorderBackend, SchemaType } from '../core/tool.js';
 import type { SpanError, SpanId } from '../core/trace.js';
+import type { RetryOptions } from './retry.js';
 import type { AgentRunResult, AgentStopReason, ContextPolicy, RunAgentOptions, SystemParam } from './types.js';
 /**
  * 缺省模型解析：显式传入 > AGENTIA_MODEL env > 'claude-opus-5'。
@@ -8,23 +9,23 @@ import type { AgentRunResult, AgentStopReason, ContextPolicy, RunAgentOptions, S
  * export AGENTIA_MODEL=deepseek-… 即可全局覆盖，无需逐处传 model。
  */
 export declare function resolveDefaultModel(over?: string): string;
-export interface AgentLoopResult {
+export interface AgentLoopResult<T = unknown> {
     stopReason: AgentStopReason;
     finalText: string;
     error?: SpanError;
     /** 本轮循环自己发起的模型往返次数 */
     iterations: number;
-    /** submit_result 校验通过的结构化结果；未提交则为 undefined */
-    typed?: unknown;
+    /** submit_result 校验通过的结构化结果；未提交则为 undefined（类型由 resultSchema 推导） */
+    typed?: T;
 }
 /** 主入口：开 run 根 span，循环跑在其下。返回完整 trace（traceId 即 runId）。 */
-export declare function runAgent(options: RunAgentOptions): Promise<AgentRunResult>;
+export declare function runAgent<S extends JsonSchema = JsonSchema>(options: RunAgentOptions<S>): Promise<AgentRunResult<SchemaType<S>>>;
 /**
- * 嵌套单元（子 agent）入口：不自开 run 根，llm.turn 挂在给定 parentSpanId 下的同一条 trace。
+ * 嵌套能力（子 agent）入口：不自开 run 根，llm.turn 挂在给定 parentSpanId 下的同一条 trace。
  * resultSchema 语义与 runAgent 一致（隐藏 submit_result → AgentLoopResult.typed），
  * 供子 agent 产出结构化结果（见 toolkit/subagent.ts 的交回逻辑）。
  */
-export declare function runAgentScoped(opts: {
+export declare function runAgentScoped<S extends JsonSchema = JsonSchema>(opts: {
     client?: ModelClient;
     system?: SystemParam;
     messages: Anthropic.MessageParam[];
@@ -35,7 +36,31 @@ export declare function runAgentScoped(opts: {
     recorder: RecorderBackend;
     parentSpanId: SpanId;
     onText?: (delta: string) => void;
+    /** 中断信号（由发起它的能力从 ToolRunContext.signal 透传，取消能传播到子 agent） */
+    signal?: AbortSignal;
+    /** 模型请求重试策略（缺省开启） */
+    retry?: RetryOptions | false;
     contextPolicy?: ContextPolicy;
     /** 结构化结果 schema：存在时追加隐藏 submit_result 工具（同 RunAgentOptions.resultSchema） */
-    resultSchema?: JsonSchema;
-}): Promise<AgentLoopResult>;
+    resultSchema?: S;
+    /** 单个工具执行超时（毫秒）；同 RunAgentOptions.toolTimeoutMs */
+    toolTimeoutMs?: number;
+    /** 同回合并行工具上限；同 RunAgentOptions.maxToolConcurrency */
+    maxToolConcurrency?: number;
+    /** 价格表覆盖（F1）：由发起它的能力从 ToolRunContext.priceOverrides 透传 */
+    priceOverrides?: Record<string, ModelPricing>;
+    /** 未定价模型回调（F2）：由发起它的能力透传 */
+    onUnpricedModel?: (info: {
+        model: string;
+        spanId: string;
+    }) => void;
+}): Promise<AgentLoopResult<SchemaType<S>>>;
+/**
+ * 用 `next` 原地替换 `target` 的全部内容（保持数组引用不变 —— 循环各处持同一数组）。
+ *
+ * **不要**写回 `target.splice(0, target.length, ...next)`：展开传参受 V8 实参个数上限
+ * 约束，`next` 超过约 12 万项即抛 `RangeError: Maximum call stack size exceeded`
+ * （实测 12 万 ok、30 万抛）。`next` 来自调用方注入的 `contextPolicy`，长度不受框架
+ * 控制，所以用循环逐项写，彻底没有这个上限。
+ */
+export declare function replaceMessages(target: Anthropic.MessageParam[], next: readonly Anthropic.MessageParam[]): void;