@migor/agentia 0.2.0 → 0.2.2

package/dist/container/container.d.ts

@@ -5,7 +5,7 @@
  * Provider 三态：useValue / useClass / useFactory(+deps)。
  * 依赖以字符串 token 显式声明，靠工厂解析期惰性求值；无构造器参数反射。
  * 容器按 app 粒度单例缓存；run 作用域的黑板/上下文不经过 DI，而由
- * RunContext(AsyncLocalStorage) 在 executeRun 内注入（见 run/context.ts）。
+ * RunContext(AsyncLocalStorage) 在 executeRun 内注入（见 runtime/context.ts）。
  */
 export type Token = string;
 export interface ValueProvider<T = unknown> {
@@ -20,7 +20,13 @@ export interface ClassProvider<T = unknown> {
 }
 export interface FactoryProvider<T = unknown> {
     provide: Token;
-    useFactory: (...deps: unknown[]) => T;
+    /**
+     * 工厂函数。形参用 `never[]` 而非 `unknown[]` —— 函数参数是**逆变**的，
+     * 写 `(...deps: unknown[]) => T` 会拒掉一切带类型形参的正常工厂
+     * （`(cfg: Config) => T` 不可赋值）。`never` 是最小类型，任何形参列表都能赋值，
+     * 与 `ClassProvider.useClass` 的 `new (...args: never[])` 保持一致。
+     */
+    useFactory: (...deps: never[]) => T;
     /** 与 useFactory 形参一一对应的依赖 token */
     deps?: Token[];
 }
@@ -33,6 +39,8 @@ export declare class Container {
     private resolving;
     /** 覆盖式注册（后注册覆盖先注册；同一 app 内同 token 重复注册视为升级） */
     register(...providers: Provider[]): this;
+    /** token 的全部传递下游（直接或间接依赖它的 token），用于注册时传递失效缓存 */
+    private dependentsOf;
     has(token: Token): boolean;
     resolve<T = unknown>(token: Token): T;
     /** 调试辅助 */

package/dist/container/container.js

@@ -2,9 +2,7 @@ export function isProvider(p) {
     return (typeof p === 'object' &&
         p !== null &&
         typeof p.provide === 'string' &&
-        ('useValue' in p ||
-            'useClass' in p ||
-            'useFactory' in p));
+        ('useValue' in p || 'useClass' in p || 'useFactory' in p));
 }
 export class Container {
     bindings = new Map();
@@ -18,9 +16,34 @@ export class Container {
                 throw new Error(`非法 provider: ${JSON.stringify(p)}`);
             }
             this.bindings.set(p.provide, p);
+            // 已解析过的缓存必须一起失效：否则「后注册覆盖先注册」只在首次 resolve 前成立
+            // （重复 module 装配是常见场景，升级了 provider 却仍拿到旧实例）。
+            // 传递失效：依赖它的下游若已解析并缓存，也必须一起失效 —— 否则拿到的是
+            // 「旧依赖构造出来的」旧实例，升级对下游完全不可见。
+            this.cache.delete(p.provide);
+            for (const dep of this.dependentsOf(p.provide))
+                this.cache.delete(dep);
         }
         return this;
     }
+    /** token 的全部传递下游（直接或间接依赖它的 token），用于注册时传递失效缓存 */
+    dependentsOf(root) {
+        const out = new Set();
+        const queue = [root];
+        while (queue.length > 0) {
+            const cur = queue.shift();
+            for (const [token, binding] of this.bindings) {
+                if (token === root || out.has(token))
+                    continue;
+                const deps = binding.deps;
+                if (deps?.includes(cur)) {
+                    out.add(token);
+                    queue.push(token);
+                }
+            }
+        }
+        return out;
+    }
     has(token) {
         return this.bindings.has(token);
     }
@@ -49,6 +72,7 @@ export class Container {
             }
             else {
                 const deps = (binding.deps ?? []).map((d) => this.resolve(d));
+                // 工厂形参声明为 never[]（见 FactoryProvider 注释）：调用点按实际 deps 断言
                 value = binding.useFactory(...deps);
             }
         }

package/dist/container/container.js.map

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

package/dist/core/abort.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Agentia —— 中断信号合成（零依赖）。
+ *
+ * 一条 run 的中断可能来自多个源头：调用方显式传入、HTTP 客户端断开、
+ * AsyncRunner 的 runTimeoutMs 超时、宿主停机。任一触发都应中止本次 run。
+ *
+ * Node 18 没有 `AbortSignal.any`，这里手写兜底（Node 20.3+ 才有）。
+ */
+/** 合成多个中断源：任一已中止 / 后中止即中止；忽略 undefined；全空返回**永不中止**的 signal。 */
+export declare function combineSignals(...signals: Array<AbortSignal | undefined>): AbortSignal;

package/dist/core/abort.js

@@ -0,0 +1,28 @@
+/**
+ * Agentia —— 中断信号合成（零依赖）。
+ *
+ * 一条 run 的中断可能来自多个源头：调用方显式传入、HTTP 客户端断开、
+ * AsyncRunner 的 runTimeoutMs 超时、宿主停机。任一触发都应中止本次 run。
+ *
+ * Node 18 没有 `AbortSignal.any`，这里手写兜底（Node 20.3+ 才有）。
+ */
+/** 合成多个中断源：任一已中止 / 后中止即中止；忽略 undefined；全空返回**永不中止**的 signal。 */
+export function combineSignals(...signals) {
+    const real = signals.filter((s) => s !== undefined);
+    // 单源直接复用，避免多包一层 listener
+    if (real.length === 1)
+        return real[0];
+    const ac = new AbortController();
+    for (const s of real) {
+        if (s.aborted) {
+            ac.abort(s.reason);
+            break;
+        }
+    }
+    if (!ac.signal.aborted) {
+        for (const s of real)
+            s.addEventListener('abort', () => ac.abort(s.reason), { once: true });
+    }
+    return ac.signal;
+}
+//# sourceMappingURL=abort.js.map

package/dist/core/abort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.js","sourceRoot":"","sources":["../../src/core/abort.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,gEAAgE;AAChE,MAAM,UAAU,cAAc,CAAC,GAAG,OAAuC;IACvE,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAoB,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;IACtE,yBAAyB;IACzB,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC;IAEtC,MAAM,EAAE,GAAG,IAAI,eAAe,EAAE,CAAC;IACjC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;YACd,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YACnB,MAAM;QACR,CAAC;IACH,CAAC;IACD,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,IAAI,IAAI;YAAE,CAAC,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9F,CAAC;IACD,OAAO,EAAE,CAAC,MAAM,CAAC;AACnB,CAAC"}

package/dist/core/blackboard.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Agentia —— 类型化黑板（**可选**，靠 TS 声明合并扩展）。core 层：纯类型、零依赖。
+ *
+ * 不扩展时（默认空前接口）：键回落 `string`、值回落 `unknown`、种子回落
+ * `Record<string, unknown>` —— 与旧版逐字一致，既有代码零改动。
+ *
+ * 扩展后，`RunContext.get/set/has/delete/keys` 与 `run({ blackboard })` 种子
+ * 都会得到**键补全 + 拼写检查 + 值类型**：
+ *
+ * ```ts
+ * // 在你自己项目的任意 .ts / .d.ts 里写一次（全局生效）
+ * declare module '@migor/agentia' {
+ *   interface Blackboard {
+ *     profile: { name: string; vip: boolean };
+ *     turnCount: number;
+ *   }
+ * }
+ * // 之后：
+ * ctx.get('profile')   // { name: string; vip: boolean } | undefined
+ * ctx.set('turnCount', 1);   // ✓ 值类型不对会报错
+ * ctx.get('profil')    // ✗ 编译期报错（键不存在）
+ * ```
+ *
+ * 动态键（键是运行时算出来的 `string`）拿不到字面量联合，需自行断言：
+ * `ctx.get(key as BlackboardKey)`。
+ *
+ * 说明：类型定义在 core（纯数据），而读写它的 `RunContext`（含 ALS 传播）
+ * 留在 runtime —— 契约下沉、机制留层，避免 runtime 的类型被 store 反向依赖。
+ */
+export interface Blackboard {
+}
+/** 黑板键：扩展过 `Blackboard` → 其键联合；未扩展 → `string`（向后兼容） */
+export type BlackboardKey = [keyof Blackboard] extends [never] ? string : keyof Blackboard;
+/** 键对应的值类型：未扩展 / 未知键 → `unknown` */
+export type BlackboardValue<K> = K extends keyof Blackboard ? Blackboard[K] : unknown;
+/** blackboard 种子：扩展过 `Blackboard` → `Partial<Blackboard>`（键有补全）；未扩展 → `Record<string, unknown>` */
+export type BlackboardSeed = [keyof Blackboard] extends [never] ? Record<string, unknown> : Partial<Blackboard>;

package/dist/core/blackboard.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=blackboard.js.map

package/dist/core/blackboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blackboard.js","sourceRoot":"","sources":["../../src/core/blackboard.ts"],"names":[],"mappings":""}

package/dist/core/json.d.ts

@@ -1,2 +1,4 @@
 /** 任意值 → 字符串：string 原样，其余 JSON.stringify，循环引用等异常回落 String()。 */
 export declare function stringifySafe(x: unknown): string;
+/** 截断到上限字符、超长加省略标记 `…(+N)`。trace 展示（engine/loop）与 replay 共用同一格式。 */
+export declare function truncateWithMark(s: string, n: number): string;

package/dist/core/json.js

@@ -9,4 +9,8 @@ export function stringifySafe(x) {
         return String(x);
     }
 }
+/** 截断到上限字符、超长加省略标记 `…(+N)`。trace 展示（engine/loop）与 replay 共用同一格式。 */
+export function truncateWithMark(s, n) {
+    return s.length > n ? `${s.slice(0, n)}…(+${s.length - n})` : s;
+}
 //# sourceMappingURL=json.js.map

package/dist/core/json.js.map

@@ -1 +1 @@
-{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/core/json.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,MAAM,UAAU,aAAa,CAAC,CAAU;IACtC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC;IACpC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IACnB,CAAC;AACH,CAAC"}
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/core/json.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,MAAM,UAAU,aAAa,CAAC,CAAU;IACtC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC;IACpC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IACnB,CAAC;AACH,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,gBAAgB,CAAC,CAAS,EAAE,CAAS;IACnD,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC"}

package/dist/core/run.d.ts

@@ -0,0 +1,18 @@
+import type { SpanError } from './trace.js';
+/**
+ * Agentia —— run 生命周期数据模型（spec §6.1）。
+ *
+ * 放在 core 的理由：`RunStatus` / `RunMeta` 是纯数据，只依赖 `core/trace`。
+ * store / transport / runtime 都要读它，下沉 core 后三者都不必再向上引 runtime
+ * （此前 `store → runtime` 是未声明的兄弟层依赖，见 AGENTS.md 分层约定）。
+ */
+export type RunStatus = 'queued' | 'running' | 'succeeded' | 'failed';
+export interface RunMeta {
+    runId: string;
+    status: RunStatus;
+    idempotencyKey?: string;
+    createdAt: number;
+    startedAt?: number;
+    finishedAt?: number;
+    error?: SpanError;
+}

package/dist/core/run.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=run.js.map

package/dist/core/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/core/run.ts"],"names":[],"mappings":""}

package/dist/core/schema.js

@@ -14,12 +14,12 @@ import { stringifySafe } from './json.js';
  */
 export function validateJsonSchema(schema, input) {
     // zod 可选接入（toolkit/zod.ts 的 fromZod 挂的隐藏字段）：存在则先走 zod 校验，
-    // 失败即回「$.: <首条错误>」（含 zod 路径）；通过后再叠加 JSON Schema 子集校验。
+    // 失败即回「$: <首条错误>」（含 zod 路径，前缀与原生分支的 `$` 路径一致）；通过后再叠加 JSON Schema 子集校验。
     const zv = schema.__zodValidate;
     if (typeof zv === 'function') {
         const err = zv(input);
         if (err)
-            return `$.: ${err}`;
+            return `$: ${err}`;
     }
     return check(schema, input, '$');
 }

package/dist/core/schema.js.map

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

package/dist/core/tool.d.ts

@@ -3,8 +3,8 @@ import type { SpanError, SpanId, SpanKind, SpanStatus, Trace, Usage } from './tr
 /**
  * Agentia —— 工具定义。
  * v1 用裸 JSON Schema，不引 zod。
- * run 执行体可接收第二参 ctx（ToolRunContext），供子 agent/嵌套单元把
- * 自己的 llm.turn 递归挂进当前 trace（unit span 的父由 engine 给定）。
+ * run 执行体可接收第二参 ctx（ToolRunContext），供子 agent/嵌套能力把
+ * 自己的 llm.turn 递归挂进当前 trace（capability span 的父由 engine 给定）。
  */
 /** JSON Schema 对象子集，供工具的 input_schema */
 export interface JsonSchema {
@@ -16,8 +16,31 @@ export interface JsonSchema {
     [key: string]: unknown;
 }
 /**
- * engine 的 TraceRecorder 面向子单元的最小结构面（core 不依赖 engine）。
- * 需要开嵌套 span 的单元（如 @SubAgent）通过 ctx.recorder 记账，
+ * 泛型 schema：在普通 JSON Schema 上挂一个**纯类型**的幻影字段，把「校验通过后的
+ * 结果类型」带进类型系统 —— 框架据此推导 `AgentRunResult.typed` 与 `@Tool` 方法的
+ * 入参类型。运行时**不存在**该字段（见 toolkit/zod.ts 的 fromZod）。
+ *
+ * 不是必须的：直接给裸 JsonSchema（旧写法）时回落 unknown/any，行为与之前逐字一致。
+ */
+export interface TypedSchema<T> extends JsonSchema {
+    /** 幻影字段（永不在运行时出现）：仅用于类型推导，勿读取 */
+    readonly __typed?: T;
+}
+/**
+ * 从 schema 提取「结果类型」：`TypedSchema<T>` → `T`；普通 `JsonSchema` → `unknown`
+ * （与 typed 字段旧语义一致）。用于 `runAgent` / `executeRun` / `app.run` 的返回值。
+ */
+export type SchemaType<S> = S extends TypedSchema<infer T> ? T : unknown;
+/**
+ * 装饰器方法入参类型：与 SchemaType 同源，但**未给出具体类型时回落 any** ——
+ * 这样「裸 JsonSchema」与「fromZod(...) 没写 <T>」两种既有写法都不被破坏
+ * （不校验方法签名），只有 `fromZod<T>()` 明确了 T 后才开始校验
+ * 「方法签名 vs schema」的一致性。
+ */
+export type SchemaInput<S> = S extends TypedSchema<infer T> ? (unknown extends T ? any : T) : any;
+/**
+ * engine 的 TraceRecorder 面向子能力的最小结构面（core 不依赖 engine）。
+ * 需要开嵌套 span 的能力（如 @SubAgent）通过 ctx.recorder 记账，
  * 其余工具可完全忽略它。
  */
 export interface RecorderBackend {
@@ -44,23 +67,55 @@ export interface ModelClient {
             system?: string | Anthropic.TextBlockParam[];
             tools?: Anthropic.Tool[];
             messages: Anthropic.MessageParam[];
+            /**
+             * 中断信号（可选）：实现须转发给底层请求，否则调用方无法中止在飞 run。
+             *
+             * ⚠️ **自定义 client 的常见坑**：`signal` 在**本契约里是 params 的一个字段**，但多数厂商
+             * SDK 把「传输层的 signal」放在**请求选项**里（如 `@anthropic-ai/sdk` 的
+             * `stream(body, options?)` —— `signal` 只在 `RequestOptions` 里认）。若把本 params 原样
+             * 交给 SDK，signal 会被**静默丢弃**，中止失效且**没有任何报错**。
+             * 参考实现：`integrations/anthropic.ts` 的 `splitSignal()`（把 signal 摘出来搬到 options），
+             * 以及 `integrations/openai.ts`（手写 fetch，直接透传）。
+             * 门禁：`tests/integrations/anthropic.test.ts`（零 key 本地假端点，abort 后必须断开）。
+             */
+            signal?: AbortSignal;
         }): {
             on(event: 'text', cb: (delta: string) => void): void;
             finalMessage(): Promise<Anthropic.Message>;
         };
     };
 }
+/**
+ * 模型单价（美元 / 1M tokens）。内置表见 `engine/usage.ts`；宿主可用
+ * `priceOverrides` 覆盖或追加（非 Anthropic 端点也能算成成本）。
+ * 定义在 core 是为了让 `ToolRunContext` 能带上它 —— core 不能依赖 engine。
+ */
+export interface ModelPricing {
+    in: number;
+    out: number;
+}
 /**
  * engine 在调用每个工具时注入的执行上下文（spec §9.2：当前 span 句柄随调用传播，
  * 不用全局单例，保证并行工具调用父子关系准确）。
- * - recorder：整条 run 共享的 recorder（新子单元/子 agent 的 span 写它下面）；
- * - parentSpanId：发起本次调用的上层 span —— 子单元 span 应挂它下面；
+ * - recorder：整条 run 共享的 recorder（新子能力/子 agent 的 span 写它下面）；
+ * - parentSpanId：发起本次调用的上层 span —— 子能力 span 应挂它下面；
  * - client：与主循环同一注入（子 agent 独立循环复用它）。
  */
 export interface ToolRunContext {
     client: ModelClient;
     recorder: RecorderBackend;
     parentSpanId: SpanId;
+    /**
+     * 本次 run 的中断信号。工具**自行决定**是否尊重（如传给 fetch）；框架不会
+     * 强制中断工具 —— 工具副作用无法回滚，强行中止只会留下不一致的中间态。
+     */
+    signal?: AbortSignal;
+    /**
+     * 宿主的价格覆盖表（见 `engine/usage.ts` 的 `buildPricing`）。嵌套能力
+     * （@SubAgent / @Skill）拉起自己的 llm 循环时必须原样传下去，否则自定义定价的
+     * 模型在子循环里会退化成"未定价"（成本恒 0，`maxCostUsd` 静默失效）。
+     */
+    priceOverrides?: Record<string, ModelPricing>;
 }
 export interface AgentTool<I = unknown, O = unknown> {
     /** 模型可见的唯一名（建议 snake_case） */
@@ -71,7 +126,7 @@ export interface AgentTool<I = unknown, O = unknown> {
     strict?: boolean;
     /**
      * 执行体。入参 = 模型按 schema 解析的结构化 input；
-     * ctx 由 engine 注入（含 recorder/父 span），需要开嵌套 span 的单元（子 agent）用，
+     * ctx 由 engine 注入（含 recorder/父 span），需要开嵌套 span 的能力（子 agent）用，
      * 普通工具可忽略。抛错会被包成 is_error 的 tool_result 回给模型，不中断 run。
      */
     run: (input: I, ctx?: ToolRunContext) => Promise<O> | O;

package/dist/core/trace.d.ts

@@ -4,9 +4,12 @@
  */
 export type TraceId = string;
 export type SpanId = string;
-/** span 层级：run=整次运行；unit=对单个单元(tool/skill/prompt/subagent)的调用；llm.turn=unit 内每次模型往返 */
-export type SpanKind = 'run' | 'unit' | 'llm.turn' | 'internal';
-export type UnitType = 'tool' | 'skill' | 'prompt' | 'subagent';
+/** span 层级：run=整次运行；capability=对能力的调用；llm.turn=每次模型往返。
+ *  注意 capability span 只由 skill / subagent 创建（toolkit/skill.ts、toolkit/subagent.ts 里的
+ *  recorder.begin('capability', …)）；普通工具与 @Prompt 资产【不建 span】，只记 turn 上的
+ *  tool.input / tool.output 事件（engine/loop.ts）。 */
+export type SpanKind = 'run' | 'capability' | 'llm.turn';
+export type CapabilityType = 'tool' | 'skill' | 'prompt' | 'subagent';
 export interface Usage {
     inputTokens: number;
     outputTokens: number;
@@ -38,7 +41,12 @@ export interface Span {
     endedAt?: number;
     status: SpanStatus;
     error?: SpanError;
-    /** unit / llm.turn 的聚合用量 */
+    /**
+     * usage —— 语义按 kind 区分：
+     * - `llm.turn`：该次模型往返的**自身计量**，是 Trace.totalUsage 的唯一来源；
+     * - `capability`（skill / subagent）：其**子孙 llm.turn 的聚合**，仅供展示（看某个能力花了多少），
+     *   **不**计入 totalUsage（否则与子孙重复计数）。
+     */
     usage?: Usage;
     attributes: Record<string, string | number | boolean>;
     events: SpanEvent[];
@@ -50,3 +58,11 @@ export interface Trace {
     status: SpanStatus;
     totalUsage: Usage;
 }
+/**
+ * trace 出口：run 收尾（成功或失败）后，框架把【完整 Trace】交给每个 sink。
+ * sink 抛错由框架吞掉，绝不影响 run 结果（与 memory 回写同款防护）。
+ * 形状与 OtlpExporter 一致 —— createOtlpExporter() 的返回值天然满足本接口。
+ */
+export interface TraceSink {
+    export(trace: Trace): void | Promise<void>;
+}

package/dist/engine/budget.d.ts

@@ -0,0 +1,49 @@
+import type { Trace } from '../core/trace.js';
+/**
+ * Agentia —— 成本硬管控（C1，补 spec §6.4 的欠账）。
+ *
+ * ⚠️ **与 `createBudgetPolicy` 的分工（文档必须并列讲清，别混）**：
+ * - `createBudgetPolicy`（engine/policy.ts）= **发送前**的上下文裁剪：防止历史过长把请求撞成
+ *   400、或过早触发压缩。它改的是 messages；
+ * - `createBudgetGuard`（本文件）= **记账后**的硬停止：每回合 `llm.turn` 的 usage 落账后累计判断，
+ *   超限即把 run 停掉。它不改 messages，目的是**控制花钱**。
+ *
+ * 两者互补，可以同时用。
+ */
+/** 超限快照：记进 run 根的 `budget.exceeded` 事件，也回调给 `onExceed` */
+export interface BudgetSnapshot {
+    /** 先触发的那条护栏（**先算 tokens 再算 cost**） */
+    kind: 'tokens' | 'cost';
+    /** 该护栏的上限 */
+    limit: number;
+    /** 触发时的实际值（必然 > limit） */
+    actual: number;
+    /** 累计 token = input + output + cacheRead + cacheCreation */
+    totalTokens: number;
+    /** 累计成本估算（美元）；模型不在价格表内时恒为 0（见 maxCostUsd 说明） */
+    costUsd: number;
+}
+export interface BudgetGuardOptions {
+    /** 整条 run（含子 agent）的累计 token 上限 */
+    maxTotalTokens?: number;
+    /**
+     * 累计成本上限（美元）。**依赖 span 级 usage 的 `costEstimate`** ——
+     * 模型不在 `engine/usage.ts` 的价格表里时成本恒为 0，这条护栏**永远不触发**；
+     * 要无条件兜底请用 `maxTotalTokens`。同理，缓存 token 的单价是近似值（见 usage.ts）。
+     */
+    maxCostUsd?: number;
+    /**
+     * 超限时的回调（在 `check` 返回前调用）。**抛错会冒泡进引擎** ——
+     * 想记日志/告警请自行保证不抛（引擎侧装配的那条已经做了 try 包裹）。
+     */
+    onExceed?: (snapshot: BudgetSnapshot) => void;
+}
+export interface BudgetGuard {
+    /** 每回合记账完成后调用；超限返回 `'tokens' | 'cost'`，否则 `null` */
+    check(trace: Trace): 'tokens' | 'cost' | null;
+}
+/**
+ * 建一个预算护栏。`check` 只看 **trace.totalUsage**（已由 recorder 按 llm.turn 求和，
+ * 子 agent 的往返也在内 —— 所以这是**整条 run** 的口径，不只是主循环）。
+ */
+export declare function createBudgetGuard(opts?: BudgetGuardOptions): BudgetGuard;

package/dist/engine/budget.js

@@ -0,0 +1,30 @@
+/**
+ * 建一个预算护栏。`check` 只看 **trace.totalUsage**（已由 recorder 按 llm.turn 求和，
+ * 子 agent 的往返也在内 —— 所以这是**整条 run** 的口径，不只是主循环）。
+ */
+export function createBudgetGuard(opts = {}) {
+    const { maxTotalTokens, maxCostUsd, onExceed } = opts;
+    return {
+        check(trace) {
+            const u = trace.totalUsage;
+            const totalTokens = u.inputTokens + u.outputTokens + u.cacheReadTokens + u.cacheCreationTokens;
+            const costUsd = u.costEstimate ?? 0;
+            if (maxTotalTokens != null && totalTokens > maxTotalTokens) {
+                onExceed?.({
+                    kind: 'tokens',
+                    limit: maxTotalTokens,
+                    actual: totalTokens,
+                    totalTokens,
+                    costUsd,
+                });
+                return 'tokens';
+            }
+            if (maxCostUsd != null && costUsd > maxCostUsd) {
+                onExceed?.({ kind: 'cost', limit: maxCostUsd, actual: costUsd, totalTokens, costUsd });
+                return 'cost';
+            }
+            return null;
+        },
+    };
+}
+//# sourceMappingURL=budget.js.map

package/dist/engine/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../src/engine/budget.ts"],"names":[],"mappings":"AAiDA;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAI,GAAuB,EAAE;IAC7D,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IACtD,OAAO;QACL,KAAK,CAAC,KAAY;YAChB,MAAM,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC;YAC3B,MAAM,WAAW,GACf,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,eAAe,GAAG,CAAC,CAAC,mBAAmB,CAAC;YAC7E,MAAM,OAAO,GAAG,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC;YACpC,IAAI,cAAc,IAAI,IAAI,IAAI,WAAW,GAAG,cAAc,EAAE,CAAC;gBAC3D,QAAQ,EAAE,CAAC;oBACT,IAAI,EAAE,QAAQ;oBACd,KAAK,EAAE,cAAc;oBACrB,MAAM,EAAE,WAAW;oBACnB,WAAW;oBACX,OAAO;iBACR,CAAC,CAAC;gBACH,OAAO,QAAQ,CAAC;YAClB,CAAC;YACD,IAAI,UAAU,IAAI,IAAI,IAAI,OAAO,GAAG,UAAU,EAAE,CAAC;gBAC/C,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,CAAC;gBACvF,OAAO,MAAM,CAAC;YAChB,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/engine/concurrency.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Agentia —— 有界并发与超时（C2）。零依赖，供「同一回合的并行工具调用」用。
+ */
+/**
+ * 有界并发 map：最多 `limit` 个 `fn` 同时在飞，**结果顺序与输入一致**
+ * （调用方按序拼 tool_result，模型靠 tool_use_id 配对，顺序改动会打乱可读性）。
+ *
+ * `limit` 非正数或非有限值一律视为**不限**（= 旧行为 `Promise.all`）。
+ */
+export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+/** 超时哨兵：区分「超时」与「工具恰好返回了 undefined」 */
+export declare const TIMED_OUT: unique symbol;
+/**
+ * 给一个 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 declare function withTimeout<T>(p: Promise<T>, timeoutMs: number): Promise<T | typeof TIMED_OUT>;