@migor/agentia 0.2.0 → 0.2.2

package/dist/integrations/report.js

@@ -0,0 +1,257 @@
+/** 空 usage 副本（避免多处各写一遍字面量） */
+function emptyUsage() {
+    return { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 };
+}
+function usageTotal(u) {
+    return u.inputTokens + u.outputTokens + u.cacheReadTokens + u.cacheCreationTokens;
+}
+/** Prometheus 式「最近 rank」分位，与 metricsSink 同口径 */
+function percentile(sorted, q) {
+    if (sorted.length === 0)
+        return 0;
+    const rank = Math.ceil(q * sorted.length);
+    return sorted[Math.min(Math.max(rank, 1), sorted.length) - 1];
+}
+function durationReport(samples) {
+    if (samples.length === 0)
+        return { total: 0, max: 0, p50: 0, p95: 0 };
+    const sorted = [...samples].sort((a, b) => a - b);
+    return {
+        total: samples.reduce((a, b) => a + b, 0),
+        max: sorted[sorted.length - 1],
+        p50: percentile(sorted, 0.5),
+        p95: percentile(sorted, 0.95),
+    };
+}
+function addUsage(into, add) {
+    into.inputTokens += add.inputTokens;
+    into.outputTokens += add.outputTokens;
+    into.cacheReadTokens += add.cacheReadTokens;
+    into.cacheCreationTokens += add.cacheCreationTokens;
+    if (add.costEstimate != null)
+        into.costEstimate = (into.costEstimate ?? 0) + add.costEstimate;
+}
+function capabilityKindOf(span) {
+    if (span.attributes.skill !== undefined)
+        return 'skill';
+    if (span.attributes.subagent !== undefined)
+        return 'subagent';
+    return 'capability';
+}
+/** 从一条 Trace 生成报告（纯函数） */
+export function buildRunReport(trace) {
+    const capabilities = new Map();
+    const acc = (capability) => {
+        let a = capabilities.get(capability);
+        if (!a) {
+            a = { calls: 0, errors: 0, durations: [], tokens: null, costUsd: null };
+            capabilities.set(capability, a);
+        }
+        return a;
+    };
+    const models = new Map();
+    const unpriced = new Set();
+    for (const span of trace.spans) {
+        if (span.kind === 'capability') {
+            const a = acc(`${capabilityKindOf(span)}:${span.name}`);
+            a.calls++;
+            if (span.status === 'error')
+                a.errors++;
+            if (span.endedAt !== undefined)
+                a.durations.push(Math.max(0, span.endedAt - span.startedAt));
+            if (span.usage) {
+                a.tokens = a.tokens ? { ...a.tokens } : emptyUsage();
+                addUsage(a.tokens, span.usage);
+                if (span.usage.costEstimate != null)
+                    a.costUsd = (a.costUsd ?? 0) + span.usage.costEstimate;
+            }
+            continue;
+        }
+        if (span.kind !== 'llm.turn')
+            continue;
+        const model = span.name;
+        let m = models.get(model);
+        if (!m) {
+            m = {
+                model,
+                turns: 0,
+                tokens: emptyUsage(),
+                tokensTotal: 0,
+                costUsd: null,
+                unpricedTurns: 0,
+                durationMs: { total: 0, max: 0, p50: 0, p95: 0 },
+                durations: [],
+            };
+            models.set(model, m);
+        }
+        m.turns++;
+        if (span.usage) {
+            addUsage(m.tokens, span.usage);
+            if (span.usage.costEstimate != null)
+                m.costUsd = (m.costUsd ?? 0) + span.usage.costEstimate;
+            else {
+                m.unpricedTurns++;
+                unpriced.add(model);
+            }
+        }
+        if (span.endedAt !== undefined)
+            m.durations.push(Math.max(0, span.endedAt - span.startedAt));
+        // 普通工具的耗时/成败在 turn 的 tool.output 事件上（E1）
+        for (const e of span.events) {
+            if (e.name !== 'tool.output')
+                continue;
+            const body = e.body;
+            if (!body || typeof body !== 'object' || typeof body.tool !== 'string')
+                continue;
+            const a = acc(`tool:${body.tool}`);
+            a.calls++;
+            if (body.ok === false)
+                a.errors++;
+            const d = body.durationMs;
+            a.durations.push(typeof d === 'number' && Number.isFinite(d) ? Math.max(0, d) : 0);
+        }
+    }
+    const capabilityReports = [...capabilities.entries()].map(([capability, a]) => ({
+        capability,
+        calls: a.calls,
+        errors: a.errors,
+        durationMs: durationReport(a.durations),
+        tokens: a.tokens,
+        tokensTotal: a.tokens ? usageTotal(a.tokens) : null,
+        costUsd: a.costUsd,
+        durations: [...a.durations],
+    }));
+    // 按总耗时降序 —— 排在最前的是「最该看的那个」
+    capabilityReports.sort((x, y) => y.durationMs.total - x.durationMs.total || y.calls - x.calls);
+    const modelReports = [...models.values()].map((m) => ({
+        ...m,
+        tokensTotal: usageTotal(m.tokens),
+        durationMs: durationReport(m.durations),
+    }));
+    const root = trace.spans.find((s) => s.spanId === trace.rootSpanId);
+    return {
+        traceId: trace.traceId,
+        status: trace.status,
+        durationMs: root && root.endedAt !== undefined ? Math.max(0, root.endedAt - root.startedAt) : 0,
+        totalUsage: { ...trace.totalUsage },
+        models: modelReports,
+        capabilities: capabilityReports,
+        unpricedModels: [...unpriced].sort(),
+        runs: 1,
+    };
+}
+/** 汇总多条报告（跨 run 的能力排行才有统计意义）。空数组 → 空报告。 */
+export function mergeRunReports(reports) {
+    const total = {
+        traceId: `merged(${reports.length} runs)`,
+        status: reports.some((r) => r.status === 'error') ? 'error' : 'ok',
+        durationMs: 0,
+        totalUsage: emptyUsage(),
+        models: [],
+        capabilities: [],
+        unpricedModels: [],
+        runs: reports.length,
+    };
+    const capabilities = new Map();
+    const models = new Map();
+    const unpriced = new Set();
+    for (const r of reports) {
+        total.durationMs += r.durationMs;
+        addUsage(total.totalUsage, r.totalUsage);
+        for (const m of r.models) {
+            let acc = models.get(m.model);
+            if (!acc) {
+                acc = {
+                    model: m.model,
+                    turns: 0,
+                    tokens: emptyUsage(),
+                    tokensTotal: 0,
+                    costUsd: null,
+                    unpricedTurns: 0,
+                    durationMs: { total: 0, max: 0, p50: 0, p95: 0 },
+                    durations: [],
+                };
+                models.set(m.model, acc);
+            }
+            acc.turns += m.turns;
+            addUsage(acc.tokens, m.tokens);
+            if (m.costUsd != null)
+                acc.costUsd = (acc.costUsd ?? 0) + m.costUsd;
+            acc.unpricedTurns += m.unpricedTurns;
+            acc.durations.push(...m.durations);
+        }
+        for (const u of r.capabilities) {
+            let acc = capabilities.get(u.capability);
+            if (!acc) {
+                acc = { calls: 0, errors: 0, durations: [], tokens: null, costUsd: null };
+                capabilities.set(u.capability, acc);
+            }
+            acc.calls += u.calls;
+            acc.errors += u.errors;
+            acc.durations.push(...u.durations);
+            if (u.tokens) {
+                acc.tokens = acc.tokens ?? emptyUsage();
+                addUsage(acc.tokens, u.tokens);
+            }
+            if (u.costUsd != null)
+                acc.costUsd = (acc.costUsd ?? 0) + u.costUsd;
+        }
+        for (const m of r.unpricedModels)
+            unpriced.add(m);
+    }
+    total.capabilities = [...capabilities.entries()].map(([capability, a]) => ({
+        capability,
+        calls: a.calls,
+        errors: a.errors,
+        durationMs: durationReport(a.durations),
+        tokens: a.tokens,
+        tokensTotal: a.tokens ? usageTotal(a.tokens) : null,
+        costUsd: a.costUsd,
+        durations: [...a.durations],
+    }));
+    total.capabilities.sort((x, y) => y.durationMs.total - x.durationMs.total || y.calls - x.calls);
+    total.models = [...models.values()].map((m) => ({
+        ...m,
+        tokensTotal: usageTotal(m.tokens),
+        durationMs: durationReport(m.durations),
+    }));
+    total.unpricedModels = [...unpriced].sort();
+    return total;
+}
+/** 人类可读的纯文本报告（CLI `agentia report` 与日志用；零依赖手写） */
+export function renderRunReport(report) {
+    const lines = [];
+    const u = report.totalUsage;
+    lines.push(`run      ${report.traceId}  [${report.status}]`);
+    lines.push(`total    ${report.durationMs}ms  ·  tokens ${usageTotal(u)} (in ${u.inputTokens} / out ${u.outputTokens} / cacheR ${u.cacheReadTokens} / cacheW ${u.cacheCreationTokens})` +
+        (u.costEstimate != null ? `  ·  ~$${u.costEstimate}` : '  ·  成本：未定价'));
+    if (report.unpricedModels.length > 0) {
+        lines.push(`⚠️  未定价模型：${report.unpricedModels.join(', ')} —— 这些模型的成本按 0 计，maxCostUsd 对它们不生效`);
+    }
+    const pad = (s, n) => (s.length >= n ? s : s + ' '.repeat(n - s.length));
+    if (report.models.length > 0) {
+        lines.push('');
+        lines.push(`${pad('model', 24)} ${pad('turns', 6)} ${pad('tokens', 10)} ${pad('cost', 10)} ${pad('avg ms', 8)}`);
+        for (const m of report.models) {
+            const avg = m.turns > 0 ? Math.round(m.durationMs.total / m.turns) : 0;
+            lines.push(`${pad(m.model, 24)} ${pad(String(m.turns), 6)} ${pad(String(m.tokensTotal), 10)} ` +
+                `${pad(m.costUsd != null ? m.costUsd.toFixed(6) : '未定价', 10)} ${pad(String(avg), 8)}`);
+        }
+    }
+    if (report.capabilities.length > 0) {
+        lines.push('');
+        lines.push(`${pad('capability', 32)} ${pad('calls', 6)} ${pad('err', 5)} ${pad('total ms', 9)} ${pad('max ms', 8)} ${pad('tokens', 8)} ${pad('cost', 10)}`);
+        for (const x of report.capabilities) {
+            lines.push(`${pad(x.capability, 32)} ${pad(String(x.calls), 6)} ${pad(String(x.errors), 5)} ` +
+                `${pad(String(x.durationMs.total), 9)} ${pad(String(x.durationMs.max), 8)} ` +
+                `${pad(x.tokensTotal != null ? String(x.tokensTotal) : '-', 8)} ` +
+                `${pad(x.costUsd != null ? x.costUsd.toFixed(6) : '-', 10)}`);
+        }
+    }
+    if (report.capabilities.length === 0 && report.models.length === 0) {
+        lines.push('');
+        lines.push('（没有可归因的能力/模型：trace 里没有 capability span、llm.turn span 或 tool.output 事件）');
+    }
+    return lines.join('\n') + '\n';
+}
+//# sourceMappingURL=report.js.map

package/dist/integrations/report.js.map

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

package/dist/runtime/context.d.ts

@@ -0,0 +1,25 @@
+import type { Run } from './run.js';
+import type { BlackboardKey, BlackboardValue } from '../core/blackboard.js';
+/** 在指定 ctx 下执行（executeRun 内部使用）；当前上下文对外以 current() 读取。
+ *  返回类型随 fn 而定：async fn → Promise<T>，同步 fn → T（不再是恒 Promise 的假类型）。 */
+export declare function withRunContext<T>(ctx: RunContext, fn: () => Promise<T>): Promise<T>;
+export declare function withRunContext<T>(ctx: RunContext, fn: () => T): T;
+export declare class RunContext {
+    readonly run: Run;
+    private readonly blackboard;
+    constructor(run: Run);
+    /** 当前 run 的上下文。不在 run 内调用时返回 undefined。 */
+    static current(): RunContext | undefined;
+    get runId(): string;
+    /**
+     * 读黑板。键经 `Blackboard` 声明后：字面量键 → 对应值类型；未知键 → 编译期报错。
+     * 未声明 `Blackboard` 时键为 `string`、值为 `unknown`（旧行为）。
+     */
+    get<K extends BlackboardKey>(key: K): BlackboardValue<K> | undefined;
+    /** 写黑板。值类型与 `Blackboard` 声明的键对齐（未声明时不校验）。 */
+    set<K extends BlackboardKey>(key: K, value: BlackboardValue<K>): this;
+    has(key: BlackboardKey): boolean;
+    delete(key: BlackboardKey): boolean;
+    /** 当前黑板上的全部键（扩展过 `Blackboard` 时为键联合数组，字面量有补全） */
+    keys(): BlackboardKey[];
+}

package/dist/{run → runtime}/context.js

@@ -8,9 +8,10 @@ import { AsyncLocalStorage } from 'node:async_hooks';
  * `RunContext.current()` 拿到当前 run —— 无需把 ctx 作为参数层层下传。
  *
  * blackboard：单次 run 内累积的项目事实/产物，随 run 释放（spec §2）。
+ * 其**类型**（Blackboard/BlackboardKey/BlackboardSeed）定义在 `core/blackboard.js`
+ * —— core 是纯数据层，store 也要读这些类型；机制（ALS 传播 + 读写方法）留在这里。
  */
 const store = new AsyncLocalStorage();
-/** 在指定 ctx 下执行（executeRun 内部使用）；当前上下文对外以 current() 读取 */
 export function withRunContext(ctx, fn) {
     return store.run(ctx, fn);
 }
@@ -27,9 +28,14 @@ export class RunContext {
     get runId() {
         return this.run.runId;
     }
+    /**
+     * 读黑板。键经 `Blackboard` 声明后：字面量键 → 对应值类型；未知键 → 编译期报错。
+     * 未声明 `Blackboard` 时键为 `string`、值为 `unknown`（旧行为）。
+     */
     get(key) {
         return this.blackboard.get(key);
     }
+    /** 写黑板。值类型与 `Blackboard` 声明的键对齐（未声明时不校验）。 */
     set(key, value) {
         this.blackboard.set(key, value);
         return this;
@@ -40,6 +46,7 @@ export class RunContext {
     delete(key) {
         return this.blackboard.delete(key);
     }
+    /** 当前黑板上的全部键（扩展过 `Blackboard` 时为键联合数组，字面量有补全） */
     keys() {
         return [...this.blackboard.keys()];
     }

package/dist/runtime/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/runtime/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAIrD;;;;;;;;;;;GAWG;AACH,MAAM,KAAK,GAAG,IAAI,iBAAiB,EAAc,CAAC;AAMlD,MAAM,UAAU,cAAc,CAAI,GAAe,EAAE,EAAwB;IACzE,OAAO,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,OAAO,UAAU;IAGA,GAAG;IAFP,UAAU,GAAG,IAAI,GAAG,EAAmB,CAAC;IAEzD,YAAqB,GAAQ;mBAAR,GAAG;IAAQ,CAAC;IAEjC,2CAA2C;IAC3C,MAAM,CAAC,OAAO;QACZ,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;IAC1B,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;IACxB,CAAC;IAED;;;OAGG;IACH,GAAG,CAA0B,GAAM;QACjC,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAmC,CAAC;IACpE,CAAC;IACD,6CAA6C;IAC7C,GAAG,CAA0B,GAAM,EAAE,KAAyB;QAC5D,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,GAAG,CAAC,GAAkB;QACpB,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClC,CAAC;IACD,MAAM,CAAC,GAAkB;QACvB,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACrC,CAAC;IACD,iDAAiD;IACjD,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAoB,CAAC;IACxD,CAAC;CACF"}

package/dist/{run → runtime}/memory.d.ts

@@ -4,7 +4,7 @@
  * blackboard（RunContext）随单次 run 释放；MemoryStore 在 run 边界做
  * 水合/回写：run 开始时把 load(keys) 注入 blackboard，run 结束时把
  * 这些 key 的当前值 save 回 store —— 同一份 store 跨多次 executeRun
- * 复用即得跨 run 记忆。接线见 run/run.ts 的 ExecuteRunOptions.memory。
+ * 复用即得跨 run 记忆。接线见 runtime/run.ts 的 ExecuteRunOptions.memory。
  */
 export interface MemoryStore {
     load(keys: string[]): Record<string, unknown> | Promise<Record<string, unknown>>;

package/dist/{run → runtime}/memory.js

@@ -2,7 +2,9 @@
 export class InMemoryMemoryStore {
     data = new Map();
     load(keys) {
-        const out = {};
+        // 无原型对象：`out['__proto__'] = v` 在 {} 上会走原型 setter（改原型而非建属性），
+        // 该 key 会静默丢失 —— 与 run.ts 的 flushMemory 保持对称。
+        const out = Object.create(null);
         for (const key of keys) {
             if (this.data.has(key))
                 out[key] = this.data.get(key);

package/dist/runtime/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/runtime/memory.ts"],"names":[],"mappings":"AAaA,gCAAgC;AAChC,MAAM,OAAO,mBAAmB;IACb,IAAI,GAAG,IAAI,GAAG,EAAmB,CAAC;IAEnD,IAAI,CAAC,IAAc;QACjB,4DAA4D;QAC5D,8CAA8C;QAC9C,MAAM,GAAG,GAA4B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACzD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACxD,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,IAAI,CAAC,OAAgC;QACnC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACnD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;CACF"}

package/dist/{run → runtime}/run.d.ts

@@ -1,8 +1,11 @@
 import type { AgentRunResult, RunAgentOptions } from '../engine/types.js';
+import type { JsonSchema, SchemaType } from '../core/tool.js';
+import type { TraceSink } from '../core/trace.js';
 import { TraceRecorder } from '../engine/tracer.js';
-import type { RunMeta, RunStatus } from './types.js';
+import type { RunMeta, RunStatus } from '../core/run.js';
 import { RunContext } from './context.js';
 import type { MemoryStore } from './memory.js';
+import type { SessionStore } from './session.js';
 /**
  * Run —— 一次运行的生命周期容器（spec §2/§6.1）。
  * runId == recorder.traceId == traceId（1:1）。
@@ -28,7 +31,7 @@ export declare class Run {
     finish(result: AgentRunResult): void;
     fail(error: unknown): void;
 }
-export interface ExecuteRunOptions extends RunAgentOptions {
+export interface ExecuteRunOptions<S extends JsonSchema = JsonSchema> extends RunAgentOptions<S> {
     idempotencyKey?: string;
     /** 在 runAgent 前对本次 RunContext 做预置（blackboard 种子等） */
     contextInit?: (ctx: RunContext) => void;
@@ -41,20 +44,34 @@ export interface ExecuteRunOptions extends RunAgentOptions {
         store: MemoryStore;
         keys: string[];
     };
+    /**
+     * 会话持久化（C4）：run 开始把 `store.load(id)` 拼在**传入 messages 之前**，
+     * 收尾把「本轮消息 + 回复」`append` 回去。与 `memory`（键值黑板）正交 —— 见 SessionStore。
+     *
+     * 只记**对话轮次**：本轮传入的 messages + 最终回复（`finalText`）。
+     * run 内部的 tool_use / tool_result 往返**不进会话历史**（它们属于这次 run 的内部过程；
+     * 要重建完整过程用 trace 重放 `traceToMessages`）—— 这样历史保持干净、可长期累积。
+     */
+    session?: {
+        store: SessionStore;
+        id: string;
+    };
     /**
      * 硬失败（请求/API 层异常）是否抛出。缺省 true；
      * 异步宿主（AsyncRunner）置 false：失败也以 {run(status=failed), result.error} 返回，
      * 便于把失败 run 落库而非冒泡。
      */
     rethrow?: boolean;
+    /** trace 出口（观测）：run 收尾后逐个投递；sink 抛错被吞，不影响 run */
+    sinks?: TraceSink[];
 }
 /**
  * 高层入口：建 Run → start → 注入 recorder 跑 engine → finish。
  * run 层持有 recorder，返回后 run.recorder 里的 trace 即本次完整调用树。
  * RunContext 在整个执行期间经 AsyncLocalStorage 可被 `RunContext.current()` 读到，
- * 工具/单元执行体无需把 ctx 作为参数层层下传。
+ * 工具/能力执行体无需把 ctx 作为参数层层下传。
  */
-export declare function executeRun(options: ExecuteRunOptions): Promise<{
+export declare function executeRun<S extends JsonSchema = JsonSchema>(options: ExecuteRunOptions<S>): Promise<{
     run: Run;
-    result: AgentRunResult;
+    result: AgentRunResult<SchemaType<S>>;
 }>;

package/dist/runtime/run.js

@@ -0,0 +1,218 @@
+import { isSuccessStopReason } from '../engine/types.js';
+import { runAgent } from '../engine/loop.js';
+import { TraceRecorder } from '../engine/tracer.js';
+import { classifyError } from '../engine/errors.js';
+import { RunContext, withRunContext } from './context.js';
+/**
+ * Run —— 一次运行的生命周期容器（spec §2/§6.1）。
+ * runId == recorder.traceId == traceId（1:1）。
+ * recorder 由 engine 的 runAgent 写入（run 根 span 归 engine 开）。
+ */
+export class Run {
+    recorder;
+    runId;
+    idempotencyKey;
+    createdAt = Date.now();
+    _status = 'queued';
+    startedAt;
+    finishedAt;
+    _result;
+    constructor(opts = {}) {
+        this.recorder = new TraceRecorder();
+        this.runId = this.recorder.traceId;
+        this.idempotencyKey = opts.idempotencyKey;
+    }
+    get status() {
+        return this._status;
+    }
+    get result() {
+        return this._result;
+    }
+    /** meta（供运行记录/持久化使用） */
+    toMeta() {
+        return {
+            runId: this.runId,
+            status: this._status,
+            idempotencyKey: this.idempotencyKey,
+            createdAt: this.createdAt,
+            startedAt: this.startedAt,
+            finishedAt: this.finishedAt,
+            error: this._result?.error,
+        };
+    }
+    start() {
+        if (this._status !== 'queued')
+            throw new Error(`cannot start a run in status ${this._status}`);
+        this._status = 'running';
+        this.startedAt = Date.now();
+    }
+    finish(result) {
+        this._result = result;
+        this.finishedAt = Date.now();
+        this._status = isSuccessStopReason(result.stopReason) ? 'succeeded' : 'failed';
+    }
+    fail(error) {
+        this._status = 'failed';
+        this.finishedAt = Date.now();
+        if (!this._result) {
+            // run 根可能尚未开（如 contextInit 抛错）：补一个 error 根再 snapshot，
+            // 避免 snapshot 的 "run root not started" 掩盖原始错误。
+            if (!this.recorder.rootStarted) {
+                const rootId = this.recorder.begin('run', 'agent.run', null);
+                this.recorder.end(rootId, { status: 'error', error: classifyError(error) });
+            }
+            this._result = {
+                trace: this.recorder.snapshot('error'),
+                stopReason: 'error',
+                finalText: '',
+                iterations: 0,
+            };
+        }
+        this._result.error = classifyError(error);
+    }
+}
+/**
+ * 高层入口：建 Run → start → 注入 recorder 跑 engine → finish。
+ * run 层持有 recorder，返回后 run.recorder 里的 trace 即本次完整调用树。
+ * RunContext 在整个执行期间经 AsyncLocalStorage 可被 `RunContext.current()` 读到，
+ * 工具/能力执行体无需把 ctx 作为参数层层下传。
+ */
+export async function executeRun(options) {
+    const run = new Run({ idempotencyKey: options.idempotencyKey });
+    run.start();
+    const ctx = new RunContext(run);
+    const memory = options.memory;
+    const session = options.session;
+    return withRunContext(ctx, async () => {
+        try {
+            options.contextInit?.(ctx);
+            if (memory) {
+                // 水合是辅助动作：store 故障（Redis 挂掉等）不得杀死本次 run ——
+                // 与下面 flushMemory 对称（那里已有同款防护）。失败即当「无记忆」继续跑。
+                try {
+                    await hydrateMemory(memory, ctx);
+                }
+                catch {
+                    /* ignore：辅助动作失败不影响 run */
+                }
+            }
+            const result = await runAgent({
+                ...options,
+                // 会话历史拼在传入 messages **之前**；读不出来就当无历史（同上：辅助动作不击穿 run）
+                messages: await loadSession(session, options.messages),
+                recorder: run.recorder,
+            });
+            run.finish(result);
+            if (memory) {
+                // 回写是辅助动作：失败不得把已成功的 run 翻成 failed（会丢结果与 trace），
+                // 与下面失败路径的 flushMemory 同款防护。
+                try {
+                    await flushMemory(memory, ctx);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            // 只在**跑成功**的轮次回写会话（见 appendSession 的不变量 1）。
+            // 注意判据是 run 的终态而非「有没有抛异常」—— stopReason 为 error / max_tokens /
+            // budget_exceeded / aborted 的 run 同样是「没跑完」，不该进对话历史。
+            if (session && run.status === 'succeeded') {
+                await appendSession(session, options.messages, result.finalText);
+            }
+            await flushSinks(options.sinks, result.trace);
+            return { run, result };
+        }
+        catch (e) {
+            run.fail(e);
+            if (memory) {
+                // 失败路径也回写；save 自身出错不掩盖原始错误
+                try {
+                    await flushMemory(memory, ctx);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            await flushSinks(options.sinks, run.result.trace);
+            // 失败路径：run.fail() 造的结果没有 typed（恒为 undefined），断言只为对齐返回类型
+            if (options.rethrow === false)
+                return { run, result: run.result };
+            throw e;
+        }
+    });
+}
+/** 没有文本输出时写进会话的占位（保住「历史以 assistant 结尾」这个不变量，见 appendSession） */
+const EMPTY_REPLY_MARK = '（本次无文本输出）';
+/**
+ * 读会话历史，拼在传入 messages 之前。失败当「无历史」继续 ——
+ * 与 memory 水合同款防护：辅助动作失败不得击穿 run。
+ */
+async function loadSession(session, incoming) {
+    if (!session)
+        return incoming;
+    try {
+        const history = await session.store.load(session.id);
+        return history.length > 0 ? [...history, ...incoming] : incoming;
+    }
+    catch {
+        return incoming;
+    }
+}
+/**
+ * 把本轮消息 + 回复追加回会话（**只在成功路径调用**）。失败吞掉（同 memory 回写防护）。
+ *
+ * 三条不变量（都是为了下一轮还能把这个历史发出去）：
+ * 1. **只有成功路径回写** —— 失败时若只存下用户的提问，历史就会以 user 结尾，
+ *    下一轮再传入 user 消息即变成「连续两条 user」，撞 API 的角色交替校验；
+ * 2. 历史**以 assistant 结尾**：没有文本输出时补一条占位（`end_turn` 下极罕见）；
+ * 3. 只存**对话轮次**（用户输入 + 最终回复），run 内部的 tool 往返不进历史
+ *    —— 要完整过程请用 trace 重放 `traceToMessages`。
+ */
+async function appendSession(session, incoming, finalText) {
+    if (!session)
+        return;
+    try {
+        await session.store.append(session.id, [
+            ...incoming,
+            { role: 'assistant', content: finalText || EMPTY_REPLY_MARK },
+        ]);
+    }
+    catch {
+        /* ignore */
+    }
+}
+/** 投递 trace 给所有 sink：观测失败（sink 抛错）不得影响 run 结果（同 memory 回写防护） */
+async function flushSinks(sinks, trace) {
+    if (!sinks || sinks.length === 0)
+        return;
+    for (const sink of sinks) {
+        try {
+            await sink.export(trace);
+        }
+        catch {
+            /* 观测失败不得影响 run */
+        }
+    }
+}
+/** 水合：store 值注入 blackboard；contextInit 已写的同名 key 不覆盖（用户种子优先） */
+async function hydrateMemory(memory, ctx) {
+    const loaded = await memory.store.load(memory.keys);
+    for (const key of memory.keys) {
+        // Object.hasOwn 而非 `in`：`in` 会命中 Object.prototype 的继承属性 ——
+        // key='toString'/'constructor' 之类会把原型上的函数当成记忆值水合进黑板
+        if (Object.hasOwn(loaded, key) && !ctx.has(key))
+            ctx.set(key, loaded[key]);
+    }
+}
+/** 回写：blackboard 里这些 key 的当前值存回 store */
+async function flushMemory(memory, ctx) {
+    // 无原型对象：`entries['__proto__'] = v` 在 {} 上会走 Object.prototype 的 setter
+    // （改掉原型而非建属性），该 key 的回写值会静默丢失
+    const entries = Object.create(null);
+    for (const key of memory.keys) {
+        if (ctx.has(key))
+            entries[key] = ctx.get(key);
+    }
+    await memory.store.save(entries);
+}
+//# sourceMappingURL=run.js.map