@migor/agentia 0.0.1

package/dist/engine/context.js

@@ -0,0 +1,146 @@
+/**
+ * Agentia —— 长上下文策略的纯函数层（spec §5/§6：compaction / context editing 分清）。
+ *
+ * 三策略不混：
+ * - **context editing**（`trimToolPairs`）：清旧 tool_use→tool_result 对，不掉内容、不额外调模型；
+ * - **compaction**（`compactMessages`）：把旧消息前缀做**服务端摘要**（摘要器由上层注入，可走模型），
+ *   只保留最近 N 条 + 一段摘要 —— 新的消息数组仍保证角色交替合法；
+ * - **客户端剪裁** = Turn 3 子 agent（另件）。
+ *
+ * 不在此自研 token 计数黑名单：`estimateMessages` 只是预算策略的默认启发式
+ * （CJK 感知估算，明确标注为估算），上层可注入真实 count_tokens 结果。
+ */
+/**
+ * 默认估算（仅预算决策用，非精确记账）：CJK 字符按 ~1.5 字/token，
+ * 其余（ASCII/拉丁）按 ~4 字符/token。纯字符/4 对中文系统性高估，
+ * 会让预算护栏过早触发压缩。
+ */
+export function defaultEstimateTokens(text) {
+    let cjk = 0;
+    for (const ch of text) {
+        const cp = ch.codePointAt(0);
+        if ((cp >= 0x3400 && cp <= 0x9fff) || // CJK 统一表意文字（扩展A + 基本区）
+            (cp >= 0xf900 && cp <= 0xfaff) || // 兼容表意文字
+            (cp >= 0x20000 && cp <= 0x2a6df) || // 扩展B
+            (cp >= 0x3000 && cp <= 0x30ff) || // 日文假名 + CJK 标点
+            (cp >= 0xff00 && cp <= 0xffef) // 全角字符
+        ) {
+            cjk++;
+        }
+    }
+    const other = text.length - cjk; // 非 BMP 字符按 UTF-16 长度计，属可接受偏差
+    return Math.max(1, Math.ceil(cjk / 1.5 + other / 4));
+}
+export function isToolResultMessage(msg) {
+    if (msg.role !== 'user')
+        return false;
+    if (typeof msg.content === 'string')
+        return false;
+    return msg.content.length > 0 && msg.content.every((b) => b.type === 'tool_result');
+}
+function hasToolUse(msg) {
+    if (msg.role !== 'assistant')
+        return false;
+    if (typeof msg.content === 'string')
+        return false;
+    return msg.content.some((b) => b.type === 'tool_use');
+}
+function contentToText(content) {
+    if (typeof content === 'string')
+        return content;
+    return content
+        .map((b) => {
+        switch (b.type) {
+            case 'text':
+                return b.text;
+            case 'tool_use':
+                return `${b.name}(${JSON.stringify(b.input)})`;
+            case 'tool_result':
+                return JSON.stringify(b.content);
+            default:
+                return JSON.stringify(b);
+        }
+    })
+        .join('\n');
+}
+function contentTokens(content, estimate) {
+    if (typeof content === 'string')
+        return estimate(content);
+    let n = 0;
+    for (const b of content) {
+        n += 1; // block 自身开销
+        n += estimate(contentToText([b]));
+    }
+    return n;
+}
+/** 整组消息的估算 token（含每条 role 开销）。 */
+export function estimateMessages(messages, estimate = defaultEstimateTokens) {
+    let n = 0;
+    for (const m of messages) {
+        n += estimate(m.role);
+        n += contentTokens(m.content, estimate);
+    }
+    return n;
+}
+/** 把消息渲染成可喂给摘要器的纯文本（role: content）。 */
+export function renderMessages(messages) {
+    return messages.map((m) => `${m.role}: ${contentToText(m.content)}`).join('\n\n');
+}
+/**
+ * context editing：丢弃旧的 tool_use→tool_result 对（超出 keepRecent 的），
+ * 保留最近 N 对以及所有非工具消息。逐对整体移除，保角色交替合法。
+ * 返回原数组引用（若无需裁剪）或新数组。
+ */
+export function trimToolPairs(messages, opts = {}) {
+    const keep = Math.max(0, opts.keepRecent ?? 1);
+    const pairs = [];
+    for (let i = 0; i + 1 < messages.length; i++) {
+        if (hasToolUse(messages[i]) && isToolResultMessage(messages[i + 1])) {
+            pairs.push([i, i + 1]);
+            i += 1;
+        }
+    }
+    if (pairs.length <= keep)
+        return messages; // 无需裁剪（或本就留得下）
+    // 丢掉最旧的 (pairs.length - keep) 对，最近的 keep 对与所有非工具消息保留
+    const drop = new Set();
+    for (let k = 0; k < pairs.length - keep; k++) {
+        drop.add(pairs[k][0]);
+        drop.add(pairs[k][1]);
+    }
+    const out = messages.filter((_, i) => !drop.has(i));
+    return out.length === messages.length ? messages : out;
+}
+/**
+ * compaction：把 messages 里“除最近 keepRecent 条”的旧前缀做摘要，替换成一段
+ * 摘要消息，尾部保留。产出保证：
+ * - 不拆散 (assistant tool_use → user tool_result) 对 —— cut 落到对中间时整体后移；
+ * - 角色交替合法 —— 尾段首条是普通 user 时摘要并入之；否则摘要以 user 角色放最前。
+ */
+export async function compactMessages(messages, opts) {
+    const keepRecent = Math.max(1, opts.keepRecent ?? 20);
+    if (messages.length <= keepRecent)
+        return messages;
+    let cut = messages.length - keepRecent;
+    // cut 若落在一对 tool_result 的开头（前一条是带 tool_use 的 assistant），整对后移进保留段
+    while (cut > 1 && cut < messages.length && isToolResultMessage(messages[cut])) {
+        cut -= 1;
+    }
+    const prefix = messages.slice(0, cut);
+    const tail = messages.slice(cut);
+    const summary = await opts.summarize(renderMessages(prefix));
+    const label = `[此前对话摘要]\n${summary}`;
+    if (tail.length === 0)
+        return [{ role: 'user', content: label }];
+    const [first, ...rest] = tail;
+    if (first.role === 'user' && !isToolResultMessage(first)) {
+        // 并入首条普通 user 消息，保持 user→assistant 交替
+        const merged = typeof first.content === 'string'
+            ? { ...first, content: `${label}\n\n${first.content}` }
+            : { ...first, content: [{ type: 'text', text: label }, ...first.content] };
+        return [merged, ...rest];
+    }
+    // 尾段以 assistant 开头：摘要作首条 user（user→assistant 交替合法）
+    return [{ role: 'user', content: label }, ...tail];
+}
+//# sourceMappingURL=context.js.map

package/dist/engine/context.js.map

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

package/dist/engine/errors.d.ts

@@ -0,0 +1,3 @@
+import type { SpanError } from '../core/trace.js';
+/** 把任意异常分类成 trace 可用的 SpanError（可重试 vs 不可重试）。 */
+export declare function classifyError(e: unknown): SpanError;

package/dist/engine/errors.js

@@ -0,0 +1,22 @@
+import Anthropic from '@anthropic-ai/sdk';
+/** 把任意异常分类成 trace 可用的 SpanError（可重试 vs 不可重试）。 */
+export function classifyError(e) {
+    if (e instanceof Anthropic.RateLimitError) {
+        return { type: 'rate_limit', message: e.message, retryable: true };
+    }
+    if (e instanceof Anthropic.APIConnectionError) {
+        return { type: 'connection', message: e.message, retryable: true };
+    }
+    if (e instanceof Anthropic.InternalServerError) {
+        return { type: 'server', message: e.message, retryable: true };
+    }
+    if (e instanceof Anthropic.APIError) {
+        const status = e.status ?? 0;
+        return { type: 'api', message: e.message, retryable: status >= 500 || status === 429 };
+    }
+    if (e instanceof Error) {
+        return { type: 'unknown', message: e.message, retryable: false };
+    }
+    return { type: 'unknown', message: String(e), retryable: false };
+}
+//# sourceMappingURL=errors.js.map

package/dist/engine/errors.js.map

@@ -0,0 +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"}

package/dist/engine/loop.d.ts

@@ -0,0 +1,33 @@
+import Anthropic from '@anthropic-ai/sdk';
+import type { AgentTool, RecorderBackend } from '../core/tool.js';
+import type { SpanError, SpanId } from '../core/trace.js';
+import type { AgentRunResult, AgentStopReason, ContextPolicy, RunAgentOptions, SystemParam } from './types.js';
+/**
+ * 缺省模型解析：显式传入 > AGENTIA_MODEL env > 'claude-opus-5'。
+ * 不把端点私有模型写死在代码里 —— 走 Anthropic 兼容网关（如 DeepSeek 端点）时
+ * export AGENTIA_MODEL=deepseek-… 即可全局覆盖，无需逐处传 model。
+ */
+export declare function resolveDefaultModel(over?: string): string;
+export interface AgentLoopResult {
+    stopReason: AgentStopReason;
+    finalText: string;
+    error?: SpanError;
+    /** 本轮循环自己发起的模型往返次数 */
+    iterations: number;
+}
+/** 主入口：开 run 根 span，循环跑在其下。返回完整 trace（traceId 即 runId）。 */
+export declare function runAgent(options: RunAgentOptions): Promise<AgentRunResult>;
+/** 嵌套单元（子 agent）入口：不自开 run 根，llm.turn 挂在给定 parentSpanId 下的同一条 trace。 */
+export declare function runAgentScoped(opts: {
+    client?: Anthropic;
+    system?: SystemParam;
+    messages: Anthropic.MessageParam[];
+    tools?: AgentTool[];
+    model?: string;
+    maxTokens?: number;
+    maxIterations?: number;
+    recorder: RecorderBackend;
+    parentSpanId: SpanId;
+    onText?: (delta: string) => void;
+    contextPolicy?: ContextPolicy;
+}): Promise<AgentLoopResult>;

package/dist/engine/loop.js

@@ -0,0 +1,227 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { validateJsonSchema } from '../core/schema.js';
+import { classifyError } from './errors.js';
+import { TraceRecorder } from './tracer.js';
+import { costEstimate, usageFromAnthropic } from './usage.js';
+/**
+ * 缺省模型解析：显式传入 > AGENTIA_MODEL env > 'claude-opus-5'。
+ * 不把端点私有模型写死在代码里 —— 走 Anthropic 兼容网关（如 DeepSeek 端点）时
+ * export AGENTIA_MODEL=deepseek-… 即可全局覆盖，无需逐处传 model。
+ */
+export function resolveDefaultModel(over) {
+    if (over)
+        return over;
+    return process.env.AGENTIA_MODEL?.trim() || 'claude-opus-5';
+}
+/** 循环体核心：带父 span 跑一轮 manual loop。请求失败按 error 收掉 turn 后抛出，由外层收尾。 */
+async function agentLoop(args) {
+    const { client, model, recorder, parentSpanId } = args;
+    const messages = [...args.messages];
+    const apiTools = args.tools.map(toApiTool);
+    let stopReason = 'end_turn';
+    let error;
+    let finalText = '';
+    let finished = false;
+    let iterations = 0;
+    for (let iteration = 0; iteration < args.maxIterations; iteration++) {
+        // 发送前给上下文策略一个机会（编辑/压缩预算超限的历史）
+        if (args.contextPolicy) {
+            const next = await args.contextPolicy.beforeTurn(messages, { iteration, model });
+            if (next && next !== messages) {
+                if (parentSpanId) {
+                    recorder.event(parentSpanId, 'context.budget', {
+                        from: messages.length,
+                        to: next.length,
+                        model,
+                    });
+                }
+                messages.splice(0, messages.length, ...next);
+            }
+        }
+        const turnId = recorder.begin('llm.turn', model, parentSpanId);
+        let message;
+        try {
+            const stream = client.messages.stream({
+                model,
+                max_tokens: args.maxTokens,
+                ...(args.system ? { system: args.system } : {}),
+                ...(apiTools.length ? { tools: apiTools } : {}),
+                messages,
+            });
+            stream.on('text', (delta) => args.onText?.(delta));
+            message = await stream.finalMessage();
+        }
+        catch (e) {
+            recorder.end(turnId, { status: 'error', error: classifyError(e) });
+            throw e; // 冒泡：runAgent 或子 agent 运行器负责标记根/unit 与收尾
+        }
+        iterations++;
+        const usage = message.usage ? usageFromAnthropic(message.usage) : undefined;
+        if (usage)
+            usage.costEstimate = costEstimate(model, usage);
+        recorder.end(turnId, { usage });
+        recorder.setAttribute(turnId, 'input_tokens', usage?.inputTokens ?? 0);
+        recorder.setAttribute(turnId, 'output_tokens', usage?.outputTokens ?? 0);
+        recorder.setAttribute(turnId, 'cache_read_tokens', usage?.cacheReadTokens ?? 0);
+        messages.push({ role: 'assistant', content: message.content });
+        // —— 终止/边界分支（每个都置 finished，退出循环不再兜底改判）——
+        if (message.stop_reason === 'end_turn') {
+            stopReason = 'end_turn';
+            finalText = textOf(message);
+            finished = true;
+            break;
+        }
+        if (message.stop_reason === 'refusal') {
+            stopReason = 'refusal';
+            finalText = textOf(message);
+            error = { type: 'refusal', message: 'model refused the request', retryable: false };
+            finished = true;
+            break;
+        }
+        if (message.stop_reason === 'max_tokens') {
+            stopReason = 'max_tokens';
+            finalText = textOf(message);
+            finished = true;
+            break;
+        }
+        if (message.stop_reason === 'pause_turn') {
+            // Turn 0 无 server tools，正常不会到；避免无限循环直接停
+            stopReason = 'pause_turn';
+            finished = true;
+            break;
+        }
+        const toolUses = message.content.filter((b) => b.type === 'tool_use');
+        if (toolUses.length === 0) {
+            // 到这里的剩余 stop_reason 不会产生可执行块，防死循环直接停
+            stopReason = 'tool_use_no_blocks';
+            finished = true;
+            break;
+        }
+        // —— 执行工具：并行；单条 user 消息回全部 tool_result（抑制并行是反模式）——
+        const toolResults = await Promise.all(toolUses.map(async (use) => {
+            const tool = args.tools.find((t) => t.name === use.name);
+            recorder.event(turnId, 'tool.input', { tool: use.name, input: limit(use.input, 2000) });
+            const ctx = { client, recorder, parentSpanId: turnId };
+            let ok = true;
+            let content = '';
+            if (!tool) {
+                ok = false;
+                content = `unknown tool: ${use.name}`;
+            }
+            else {
+                // 模型给的 input 先过 schema 校验：不合法直接回 is_error（含路径，
+                // 模型可自我修正），不进方法体 —— schema 是方法与模型间的运行时契约。
+                const invalid = validateJsonSchema(tool.inputSchema, use.input);
+                if (invalid) {
+                    ok = false;
+                    content = `invalid input: ${invalid}`;
+                }
+                else {
+                    try {
+                        content = await tool.run(use.input, ctx);
+                    }
+                    catch (e) {
+                        ok = false;
+                        const err = classifyError(e);
+                        content = `error(${err.type}): ${err.message}`;
+                    }
+                }
+            }
+            recorder.event(turnId, 'tool.output', { tool: use.name, ok, content: ok ? limit(content, 2000) : limit(content, 1000) });
+            return {
+                type: 'tool_result',
+                tool_use_id: use.id,
+                content: stringifySafe(content),
+                is_error: !ok,
+            };
+        }));
+        messages.push({ role: 'user', content: toolResults });
+    }
+    if (!finished && stopReason === 'end_turn') {
+        // 循环因 maxIterations 上限退出而非正常终止
+        stopReason = 'max_iterations';
+    }
+    return { stopReason, finalText, error, iterations };
+}
+/** 主入口：开 run 根 span，循环跑在其下。返回完整 trace（traceId 即 runId）。 */
+export async function runAgent(options) {
+    const recorder = options.recorder ?? new TraceRecorder();
+    const rootId = recorder.begin('run', options.runName ?? 'agent.run', null);
+    recorder.setAttribute(rootId, 'model', resolveDefaultModel(options.model));
+    let result;
+    try {
+        result = await agentLoop({
+            client: options.client ?? new Anthropic(),
+            model: resolveDefaultModel(options.model),
+            maxTokens: options.maxTokens ?? 64_000,
+            maxIterations: options.maxIterations ?? 40,
+            system: options.system,
+            messages: options.messages,
+            tools: options.tools ?? [],
+            recorder,
+            parentSpanId: rootId,
+            onText: options.onText,
+            contextPolicy: options.contextPolicy,
+        });
+    }
+    catch (e) {
+        result = { stopReason: 'error', finalText: '', error: classifyError(e), iterations: 0 };
+    }
+    const runStatus = result.stopReason === 'end_turn' ? 'ok' : 'error';
+    recorder.setAttribute(rootId, 'stop_reason', result.stopReason);
+    recorder.end(rootId, { status: runStatus, ...(result.error ? { error: result.error } : {}) });
+    const trace = recorder.snapshot(runStatus);
+    return {
+        trace,
+        stopReason: result.stopReason,
+        finalText: result.finalText,
+        iterations: result.iterations,
+        error: result.error,
+    };
+}
+/** 嵌套单元（子 agent）入口：不自开 run 根，llm.turn 挂在给定 parentSpanId 下的同一条 trace。 */
+export async function runAgentScoped(opts) {
+    return agentLoop({
+        client: opts.client ?? new Anthropic(),
+        model: resolveDefaultModel(opts.model),
+        maxTokens: opts.maxTokens ?? 64_000,
+        maxIterations: opts.maxIterations ?? 40,
+        system: opts.system,
+        messages: opts.messages,
+        tools: opts.tools ?? [],
+        recorder: opts.recorder,
+        parentSpanId: opts.parentSpanId,
+        onText: opts.onText,
+        contextPolicy: opts.contextPolicy,
+    });
+}
+function toApiTool(t) {
+    return {
+        name: t.name,
+        description: t.description,
+        input_schema: t.inputSchema,
+        ...(t.strict ? { strict: true } : {}),
+    };
+}
+function textOf(message) {
+    return message.content
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text)
+        .join('\n');
+}
+function stringifySafe(x) {
+    if (typeof x === 'string')
+        return x;
+    try {
+        return JSON.stringify(x) ?? String(x);
+    }
+    catch {
+        return String(x);
+    }
+}
+/** 截断到上限字符，超长加省略标记 */
+function limit(x, n) {
+    const s = stringifySafe(x);
+    return s.length > n ? `${s.slice(0, n)}…(+${s.length - n})` : s;
+}
+//# sourceMappingURL=loop.js.map

package/dist/engine/loop.js.map

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

package/dist/engine/policy.d.ts

@@ -0,0 +1,30 @@
+import type { ContextPolicy } from './types.js';
+/**
+ * Agentia —— 预算驱动的上下文策略（spec §5 compaction / §6 budget）。
+ *
+ * 规则（带滞回，避免每回合反复压缩）：
+ * 1. 估算整组消息 token；≤ budgetTokens → 原样放行（快路径）。
+ * 2. 超预算：先 **context editing**（trimToolPairs 丢旧工具对，不额外调模型）；
+ *    若裁剪后回到预算内即止。
+ * 3. 仍超预算且有 summarize（compaction 摘要器）→ 压缩：旧前缀做成摘要，只留最近 keepRecent 条。
+ *    距上次压缩 < compactEvery 个回合则跳过（滞回，防抖）。
+ * 4. 无 summarize 时 compaction 不可用，编辑已是上限（返回裁剪后消息）。
+ *
+ * summarize 未提供时 policy 不会自己调模型 —— 框架不替你造 token（spec：不主动黑名单，
+ * 预算只是护栏；真机可注入按 /count_tokens 的 estimate 与走模型的 summarize）。
+ */
+export interface BudgetPolicyOptions {
+    /** 预算（估算 input tokens）；缺省 60_000 */
+    budgetTokens?: number;
+    /** compaction 保留的最近消息条数；缺省 20 */
+    keepRecent?: number;
+    /** token 估算函数（预算决策用，非精确记账）；缺省 CJK 感知启发式 */
+    estimateTokens?: (text: string) => number;
+    /** 是否先编辑再压缩；缺省 true */
+    editBeforeCompact?: boolean;
+    /** 提供则允许 compaction（旧前缀→摘要）。框架不自动造摘要器 */
+    summarize?: (historyText: string) => string | Promise<string>;
+    /** 距上次压缩至少隔几个回合才再次压缩（滞回）；缺省 1 */
+    compactEvery?: number;
+}
+export declare function createBudgetPolicy(opts?: BudgetPolicyOptions): ContextPolicy;

package/dist/engine/policy.js

@@ -0,0 +1,35 @@
+import { compactMessages, defaultEstimateTokens, estimateMessages, trimToolPairs, } from './context.js';
+export function createBudgetPolicy(opts = {}) {
+    const budgetTokens = opts.budgetTokens ?? 60_000;
+    const keepRecent = Math.max(1, opts.keepRecent ?? 20);
+    const estimate = opts.estimateTokens ?? defaultEstimateTokens;
+    const editBeforeCompact = opts.editBeforeCompact ?? true;
+    const summarize = opts.summarize;
+    const compactEvery = Math.max(1, opts.compactEvery ?? 1);
+    let lastCompactAt = Number.NEGATIVE_INFINITY;
+    return {
+        budgetTokens,
+        async beforeTurn(messages, info) {
+            if (estimateMessages(messages, estimate) <= budgetTokens)
+                return messages;
+            // 1) context editing：先丢旧工具对
+            let current = messages;
+            if (editBeforeCompact) {
+                const trimmed = trimToolPairs(current, { keepRecent });
+                if (trimmed.length < current.length) {
+                    current = trimmed;
+                    if (estimateMessages(current, estimate) <= budgetTokens)
+                        return current;
+                }
+            }
+            // 2) compaction：仍超预算且有摘要器
+            if (!summarize)
+                return current;
+            if (info.iteration - lastCompactAt < compactEvery)
+                return current;
+            lastCompactAt = info.iteration;
+            return compactMessages(current, { keepRecent, summarize });
+        },
+    };
+}
+//# sourceMappingURL=policy.js.map

package/dist/engine/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/engine/policy.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,gBAAgB,EAChB,aAAa,GACd,MAAM,cAAc,CAAC;AA+BtB,MAAM,UAAU,kBAAkB,CAAC,IAAI,GAAwB,EAAE;IAC/D,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,MAAM,CAAC;IACjD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;IACtD,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,IAAI,qBAAqB,CAAC;IAC9D,MAAM,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,IAAI,IAAI,CAAC;IACzD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IACjC,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC,CAAC;IACzD,IAAI,aAAa,GAAG,MAAM,CAAC,iBAAiB,CAAC;IAE7C,OAAO;QACL,YAAY;QACZ,KAAK,CAAC,UAAU,CAAC,QAAQ,EAAE,IAAI;YAC7B,IAAI,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,YAAY;gBAAE,OAAO,QAAQ,CAAC;YAE1E,4BAA4B;YAC5B,IAAI,OAAO,GAAG,QAAQ,CAAC;YACvB,IAAI,iBAAiB,EAAE,CAAC;gBACtB,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC;gBACvD,IAAI,OAAO,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;oBACpC,OAAO,GAAG,OAAO,CAAC;oBAClB,IAAI,gBAAgB,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,YAAY;wBAAE,OAAO,OAAO,CAAC;gBAC1E,CAAC;YACH,CAAC;YAED,0BAA0B;YAC1B,IAAI,CAAC,SAAS;gBAAE,OAAO,OAAO,CAAC;YAC/B,IAAI,IAAI,CAAC,SAAS,GAAG,aAAa,GAAG,YAAY;gBAAE,OAAO,OAAO,CAAC;YAClE,aAAa,GAAG,IAAI,CAAC,SAAS,CAAC;YAC/B,OAAO,eAAe,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC;QAC7D,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/engine/tracer.d.ts

@@ -0,0 +1,27 @@
+import type { SpanError, SpanId, SpanKind, SpanStatus, Trace, TraceId, Usage } from '../core/trace.js';
+/**
+ * 内存 TraceRecorder —— v1 实现（spec §9.3）。
+ * 显式传 parentSpanId 而非内部栈，保证并行工具调用时父子关系准确。
+ * 一次 run 一个 recorder；run 与 trace 1:1。
+ */
+export declare class TraceRecorder {
+    readonly traceId: TraceId;
+    private readonly spans;
+    private readonly index;
+    private rootSpanId;
+    begin(kind: SpanKind, name: string, parentSpanId: SpanId | null): SpanId;
+    get rootStarted(): boolean;
+    /**
+     * 结束 span。容错策略：未知 span id 抛错（程序员错误要响亮）；
+     * 对已结束的 span 幂等忽略（重复 end 视为无害）。event/setAttribute 对未知
+     * span 静默忽略 —— 观测不应中断业务，与 end 的严格性刻意区分。
+     */
+    end(id: SpanId, patch?: {
+        status?: SpanStatus;
+        error?: SpanError;
+        usage?: Usage;
+    }): void;
+    event(id: SpanId, name: string, body: unknown): void;
+    setAttribute(id: SpanId, key: string, value: string | number | boolean): void;
+    snapshot(status: SpanStatus): Trace;
+}

package/dist/engine/tracer.js

@@ -0,0 +1,93 @@
+import { randomUUID } from 'node:crypto';
+/**
+ * 内存 TraceRecorder —— v1 实现（spec §9.3）。
+ * 显式传 parentSpanId 而非内部栈，保证并行工具调用时父子关系准确。
+ * 一次 run 一个 recorder；run 与 trace 1:1。
+ */
+export class TraceRecorder {
+    traceId = randomUUID();
+    spans = [];
+    index = new Map();
+    rootSpanId = null;
+    begin(kind, name, parentSpanId) {
+        if (kind === 'run') {
+            if (this.rootSpanId)
+                throw new Error('run root already started');
+            this.rootSpanId = randomUUID();
+        }
+        const id = kind === 'run' ? this.rootSpanId : randomUUID();
+        const span = {
+            spanId: id,
+            traceId: this.traceId,
+            parentSpanId,
+            kind,
+            name,
+            status: 'ok',
+            startedAt: Date.now(),
+            attributes: {},
+            events: [],
+        };
+        this.spans.push(span);
+        this.index.set(id, span);
+        return id;
+    }
+    get rootStarted() {
+        return this.rootSpanId !== null;
+    }
+    /**
+     * 结束 span。容错策略：未知 span id 抛错（程序员错误要响亮）；
+     * 对已结束的 span 幂等忽略（重复 end 视为无害）。event/setAttribute 对未知
+     * span 静默忽略 —— 观测不应中断业务，与 end 的严格性刻意区分。
+     */
+    end(id, patch = {}) {
+        const span = this.index.get(id);
+        if (!span)
+            throw new Error(`span not found: ${id}`);
+        if (span.endedAt !== undefined)
+            return; // 幂等：重复 end 忽略
+        span.endedAt = Date.now();
+        if (patch.status)
+            span.status = patch.status;
+        if (patch.error)
+            span.error = patch.error;
+        if (patch.usage)
+            span.usage = patch.usage;
+    }
+    event(id, name, body) {
+        this.index.get(id)?.events.push({ time: Date.now(), name, body });
+    }
+    setAttribute(id, key, value) {
+        const span = this.index.get(id);
+        if (span)
+            span.attributes[key] = value;
+    }
+    snapshot(status) {
+        if (!this.rootSpanId)
+            throw new Error('run root not started');
+        const totalUsage = {
+            inputTokens: 0,
+            outputTokens: 0,
+            cacheReadTokens: 0,
+            cacheCreationTokens: 0,
+        };
+        for (const s of this.spans) {
+            if (!s.usage)
+                continue;
+            totalUsage.inputTokens += s.usage.inputTokens;
+            totalUsage.outputTokens += s.usage.outputTokens;
+            totalUsage.cacheReadTokens += s.usage.cacheReadTokens;
+            totalUsage.cacheCreationTokens += s.usage.cacheCreationTokens;
+            if (s.usage.costEstimate != null) {
+                totalUsage.costEstimate = (totalUsage.costEstimate ?? 0) + s.usage.costEstimate;
+            }
+        }
+        return {
+            traceId: this.traceId,
+            rootSpanId: this.rootSpanId,
+            spans: [...this.spans],
+            status,
+            totalUsage,
+        };
+    }
+}
+//# sourceMappingURL=tracer.js.map