@migor/agentia 0.0.1

package/dist/engine/tracer.js.map

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

package/dist/engine/types.d.ts

@@ -0,0 +1,58 @@
+import type Anthropic from '@anthropic-ai/sdk';
+import type { AgentTool } from '../core/tool.js';
+import type { SpanError, Trace } from '../core/trace.js';
+export type AgentStopReason = 'end_turn' | 'max_tokens' | 'refusal' | 'pause_turn' | 'max_iterations' | 'tool_use_no_blocks' | 'error';
+/** 可携带 cache_control 的 system 文本块（见 run/systemPrompt.ts） */
+export interface SystemTextBlock {
+    type: 'text';
+    text: string;
+    cache_control?: {
+        type: 'ephemeral';
+    };
+}
+/** system 参数：纯文本，或可缓存块数组（稳定段带 breakpoint，volatile 段放其后不带） */
+export type SystemParam = string | SystemTextBlock[];
+/**
+ * 上下文预算策略（spec §5/§6 —— compaction / context editing）。
+ * 引擎在每个 llm 回合发送前调用 beforeTurn；返回的 messages 即本回合发送内容。
+ * 实现见 engine/policy.ts 的 createBudgetPolicy，或自实现（如每次用 /count_tokens）。
+ */
+export interface ContextPolicy {
+    /** 预算（估算 input tokens）；超预算的回合触发降级。供观测/文档用 */
+    readonly budgetTokens?: number;
+    beforeTurn(messages: Anthropic.MessageParam[], info: {
+        iteration: number;
+        model: string;
+    }): Promise<Anthropic.MessageParam[]>;
+}
+export interface RunAgentOptions {
+    /** 顶层 system（SystemPrompt 产物）。稳定内容应放在 tools 之后、第一个 breakpoint 前 */
+    system?: SystemParam;
+    /** 初始消息；Turn 0 由调用方给 user 起始消息 */
+    messages: Anthropic.MessageParam[];
+    /** 主 agent 可调工具（v1 裸 JSON schema） */
+    tools?: AgentTool[];
+    model?: string;
+    /** 流式请求的 max_tokens，给足避免中途截断 */
+    maxTokens?: number;
+    /** 循环安全上限，防止无限 tool 往返 */
+    maxIterations?: number;
+    /** 注入 client（默认 new Anthropic()，读 env/ant auth） */
+    client?: Anthropic;
+    /** 注入 recorder（run 层复用；不注入则内部新建，traceId 即 runId） */
+    recorder?: import('./tracer.js').TraceRecorder;
+    /** 文本增量回调（终端/SSE 用） */
+    onText?: (delta: string) => void;
+    runName?: string;
+    /** 上下文预算策略：每回合发送前可编辑/压缩消息（compaction / context editing） */
+    contextPolicy?: ContextPolicy;
+}
+export interface AgentRunResult {
+    /** 本次 run 的完整调用树 + usage（traceId == runId） */
+    trace: Trace;
+    stopReason: AgentStopReason;
+    /** 最终文本（结构化输出在后续 Turn 接入） */
+    finalText: string;
+    iterations: number;
+    error?: SpanError;
+}

package/dist/engine/types.js

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

package/dist/engine/types.js.map

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

package/dist/engine/usage.d.ts

@@ -0,0 +1,5 @@
+import type Anthropic from '@anthropic-ai/sdk';
+import type { Usage } from '../core/trace.js';
+export declare function usageFromAnthropic(u: Anthropic.Usage): Usage;
+/** 近似成本估计：缓存写≈1.25×输入，缓存读≈0.1×输入。 */
+export declare function costEstimate(model: string, usage: Usage): number | undefined;

package/dist/engine/usage.js

@@ -0,0 +1,30 @@
+/** $/1M tokens（输入/输出）。未知模型不估成本。 */
+const PRICING = {
+    'claude-opus-5': { in: 5, out: 25 },
+    'claude-opus-4-8': { in: 5, out: 25 },
+    'claude-opus-4-7': { in: 5, out: 25 },
+    'claude-sonnet-5': { in: 2, out: 10 },
+    'claude-sonnet-4-6': { in: 3, out: 15 },
+    'claude-haiku-4-5': { in: 1, out: 5 },
+};
+export function usageFromAnthropic(u) {
+    return {
+        inputTokens: u.input_tokens ?? 0,
+        outputTokens: u.output_tokens ?? 0,
+        cacheReadTokens: u.cache_read_input_tokens ?? 0,
+        cacheCreationTokens: u.cache_creation_input_tokens ?? 0,
+    };
+}
+/** 近似成本估计：缓存写≈1.25×输入，缓存读≈0.1×输入。 */
+export function costEstimate(model, usage) {
+    const p = PRICING[model];
+    if (!p)
+        return undefined;
+    const { inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens } = usage;
+    const cost = (inputTokens / 1e6) * p.in +
+        (outputTokens / 1e6) * p.out +
+        (cacheReadTokens / 1e6) * p.in * 0.1 +
+        (cacheCreationTokens / 1e6) * p.in * 1.25;
+    return Math.round(cost * 1e6) / 1e6;
+}
+//# sourceMappingURL=usage.js.map

package/dist/engine/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/engine/usage.ts"],"names":[],"mappings":"AAGA,mCAAmC;AACnC,MAAM,OAAO,GAAgD;IAC3D,eAAe,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE;IACnC,iBAAiB,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE;IACrC,iBAAiB,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE;IACrC,iBAAiB,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE;IACrC,mBAAmB,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE;IACvC,kBAAkB,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE;CACtC,CAAC;AAEF,MAAM,UAAU,kBAAkB,CAAC,CAAkB;IACnD,OAAO;QACL,WAAW,EAAE,CAAC,CAAC,YAAY,IAAI,CAAC;QAChC,YAAY,EAAE,CAAC,CAAC,aAAa,IAAI,CAAC;QAClC,eAAe,EAAE,CAAC,CAAC,uBAAuB,IAAI,CAAC;QAC/C,mBAAmB,EAAE,CAAC,CAAC,2BAA2B,IAAI,CAAC;KACxD,CAAC;AACJ,CAAC;AAED,qCAAqC;AACrC,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,KAAY;IACtD,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IACzB,IAAI,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACzB,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,GAAG,KAAK,CAAC;IAClF,MAAM,IAAI,GACR,CAAC,WAAW,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE;QAC1B,CAAC,YAAY,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG;QAC5B,CAAC,eAAe,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG;QACpC,CAAC,mBAAmB,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC;IAC5C,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;AACtC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+export declare const AGENTIA_VERSION = "0.0.1";
+export type { Trace, Span, SpanEvent, SpanError, SpanId, SpanKind, SpanStatus, TraceId, UnitType, Usage, } from './core/trace.js';
+export type { AgentTool, JsonSchema, RecorderBackend, ToolRunContext } from './core/tool.js';
+export { validateJsonSchema } from './core/schema.js';
+export { runAgent, resolveDefaultModel } from './engine/loop.js';
+export { TraceRecorder } from './engine/tracer.js';
+export { classifyError } from './engine/errors.js';
+export type { AgentRunResult, AgentStopReason, ContextPolicy, RunAgentOptions, SystemParam, SystemTextBlock, } from './engine/types.js';
+export { defaultEstimateTokens, estimateMessages, renderMessages, trimToolPairs, compactMessages, } from './engine/context.js';
+export type { CompactOptions, TrimOptions } from './engine/context.js';
+export { createBudgetPolicy } from './engine/policy.js';
+export type { BudgetPolicyOptions } from './engine/policy.js';
+export { Run, executeRun } from './run/run.js';
+export { RunContext, withRunContext } from './run/context.js';
+export { SystemPrompt } from './run/systemPrompt.js';
+export type { SystemSection } from './run/systemPrompt.js';
+export type { ExecuteRunOptions } from './run/run.js';
+export type { RunMeta, RunStatus } from './run/types.js';
+export { Container } from './container/container.js';
+export type { Provider, ClassProvider, ValueProvider, FactoryProvider, Token, } from './container/container.js';
+export { asset } from './toolkit/asset.js';
+export { discoverProviders } from './toolkit/discover.js';
+export { Tool, collectTools } from './toolkit/tool.js';
+export type { ToolSpec } from './toolkit/tool.js';
+export { SubAgent, collectSubAgents, subagentToTool } from './toolkit/subagent.js';
+export type { SubAgentSpec, SubAgentUnit } from './toolkit/subagent.js';
+export { Skill, collectSkills, skillToTool } from './toolkit/skill.js';
+export type { SkillContext, SkillLlmOptions, SkillLlmResult, SkillSpec, SkillUnit, } from './toolkit/skill.js';
+export { Prompt, collectPrompts } from './toolkit/prompt.js';
+export type { PromptSpec } from './toolkit/prompt.js';
+export { createApp, AgentApp } from './toolkit/module.js';
+export type { AppOptions, RunAppOptions, AgentRunOutput } from './toolkit/module.js';
+export { normalizeMessages } from './run/spec.js';
+export type { RunInput, RunSpec, RunInvocationOptions } from './run/spec.js';
+export { InMemoryTaskStore } from './run/store.js';
+export type { TaskRecord, TaskStore } from './run/store.js';
+export { FileTaskStore } from './run/fsStore.js';
+export { AsyncRunner } from './run/async.js';
+export type { AsyncRunnerOptions, AppCallable } from './run/async.js';
+export { Scheduler } from './run/scheduler.js';
+export type { ScheduleEveryOptions, ScheduleHandle } from './run/scheduler.js';
+export { runSync, createSyncHandler } from './run/transport.js';

package/dist/index.js

@@ -0,0 +1,31 @@
+export const AGENTIA_VERSION = '0.0.1';
+export { validateJsonSchema } from './core/schema.js';
+// engine：Turn 0 内核
+export { runAgent, resolveDefaultModel } from './engine/loop.js';
+export { TraceRecorder } from './engine/tracer.js';
+export { classifyError } from './engine/errors.js';
+// engine：Turn 4 长上下文策略
+export { defaultEstimateTokens, estimateMessages, renderMessages, trimToolPairs, compactMessages, } from './engine/context.js';
+export { createBudgetPolicy } from './engine/policy.js';
+// run：Turn 1 生命周期
+export { Run, executeRun } from './run/run.js';
+export { RunContext, withRunContext } from './run/context.js';
+export { SystemPrompt } from './run/systemPrompt.js';
+// container：Turn 2 显式 DI
+export { Container } from './container/container.js';
+// toolkit：Turn 2 声明式单元 + 应用装配
+export { asset } from './toolkit/asset.js';
+export { discoverProviders } from './toolkit/discover.js';
+export { Tool, collectTools } from './toolkit/tool.js';
+export { SubAgent, collectSubAgents, subagentToTool } from './toolkit/subagent.js';
+export { Skill, collectSkills, skillToTool } from './toolkit/skill.js';
+export { Prompt, collectPrompts } from './toolkit/prompt.js';
+export { createApp, AgentApp } from './toolkit/module.js';
+// run：Turn 5 触发传输 + run 存储
+export { normalizeMessages } from './run/spec.js';
+export { InMemoryTaskStore } from './run/store.js';
+export { FileTaskStore } from './run/fsStore.js';
+export { AsyncRunner } from './run/async.js';
+export { Scheduler } from './run/scheduler.js';
+export { runSync, createSyncHandler } from './run/transport.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,eAAe,GAAG,OAAO,CAAC;AAgBvC,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtD,mBAAmB;AACnB,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAUnD,uBAAuB;AACvB,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAGxD,kBAAkB;AAClB,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAKrD,yBAAyB;AACzB,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AASrD,8BAA8B;AAC9B,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEnF,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAQvE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE7D,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG1D,2BAA2B;AAC3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/run/async.d.ts

@@ -0,0 +1,64 @@
+import type Anthropic from '@anthropic-ai/sdk';
+import type { AgentRunResult } from '../engine/types.js';
+import type { RunStatus } from './types.js';
+import type { RunInvocationOptions } from './spec.js';
+import type { TaskRecord, TaskStore } from './store.js';
+/**
+ * Agentia —— 异步任务宿主（spec §6.3 异步 / §6.5 确定性 / §6.6 换宿主不换语义）。
+ *
+ * - submit 即回（queued），后台驱动状态机 queued → running → succeeded/failed；
+ * - **at-least-once 去重**：同一 idempotencyKey 重复 submit，若上一任务仍在
+ *   queued/running/succeeded 则直接返回既有记录，不重复执行（失败可重试新任务）；
+ * - run 记录落 TaskStore（v1 InMemoryTaskStore），trace 随 result 一同保留；
+ *   DB/队列宿主只需实现 TaskStore。
+ */
+export interface AsyncRunnerOptions {
+    client?: Anthropic;
+    store?: TaskStore;
+    /** 同时执行的任务上限；缺省不限。超出部分排队等槽位（状态保持 queued） */
+    concurrency?: number;
+}
+/** 应用最小调用面（agent 装配无关，避免 run 层向上依赖 toolkit） */
+export interface AppCallable {
+    readonly name: string;
+    run(messages: Anthropic.MessageParam[], opts?: RunInvocationOptions): Promise<{
+        run: {
+            runId: string;
+            status: RunStatus;
+        };
+        result: AgentRunResult;
+    }>;
+}
+export declare class AsyncRunner {
+    #private;
+    private readonly app;
+    readonly store: TaskStore;
+    private readonly client?;
+    private readonly concurrency;
+    private running;
+    private readonly waitQueue;
+    constructor(app: AppCallable, opts?: AsyncRunnerOptions);
+    /**
+     * 提交一次异步任务。入参可为 string / messages / {prompt|text|messages}。
+     * 幂等键存在且上一任务未失败 → 直接返回既有记录（去重）；失败的同键可产生新任务。
+     */
+    submit(input: unknown, opts?: {
+        idempotencyKey?: string;
+        source?: string;
+        options?: RunInvocationOptions;
+    }): TaskRecord;
+    /** 查任务当前记录 */
+    poll(taskId: string): TaskRecord | undefined;
+    byIdempotency(key: string): TaskRecord | undefined;
+    list(): TaskRecord[];
+    /** 等到任务终态；超时抛错。 */
+    awaitTask(taskId: string, opts?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<TaskRecord>;
+    /**
+     * 宿主重启续跑：把 store 里 queued | running 的记录重新派发执行
+     * （running 视为进程中断）。返回重派数量。幂等键去重照常生效。
+     */
+    resumePending(): number;
+}

package/dist/run/async.js

@@ -0,0 +1,135 @@
+import { classifyError } from '../engine/errors.js';
+import { normalizeMessages } from './spec.js';
+import { InMemoryTaskStore } from './store.js';
+export class AsyncRunner {
+    app;
+    store;
+    client;
+    concurrency;
+    running = 0;
+    waitQueue = [];
+    constructor(app, opts = {}) {
+        this.app = app;
+        this.app = app;
+        this.store = opts.store ?? new InMemoryTaskStore();
+        this.client = opts.client;
+        this.concurrency = opts.concurrency ?? Number.POSITIVE_INFINITY;
+        if (!(this.concurrency > 0)) {
+            throw new Error(`concurrency 必须为正数，收到 ${opts.concurrency}`);
+        }
+    }
+    /**
+     * 提交一次异步任务。入参可为 string / messages / {prompt|text|messages}。
+     * 幂等键存在且上一任务未失败 → 直接返回既有记录（去重）；失败的同键可产生新任务。
+     */
+    submit(input, opts = {}) {
+        const messages = normalizeMessages(input);
+        if (opts.idempotencyKey) {
+            const existing = this.store.byIdempotency(opts.idempotencyKey);
+            if (existing && existing.status !== 'failed') {
+                return { ...existing }; // at-least-once 去重：不重复执行
+            }
+        }
+        const rec = {
+            taskId: InMemoryTaskStore.nextTaskId(),
+            status: 'queued',
+            idempotencyKey: opts.idempotencyKey,
+            spec: { messages, options: opts.options, source: opts.source ?? 'async' },
+            createdAt: Date.now(),
+        };
+        this.store.save(rec);
+        void this.#execute(rec.taskId);
+        // 返回浅拷贝：记录会被后台状态机原地推进，调用方拿到的是提交时刻的快照
+        return { ...rec };
+    }
+    /** 查任务当前记录 */
+    poll(taskId) {
+        return this.store.get(taskId);
+    }
+    byIdempotency(key) {
+        return this.store.byIdempotency(key);
+    }
+    list() {
+        return this.store.list();
+    }
+    /** 等到任务终态；超时抛错。 */
+    async awaitTask(taskId, opts = {}) {
+        const timeoutMs = opts.timeoutMs ?? 30_000;
+        const intervalMs = opts.intervalMs ?? 5;
+        const start = Date.now();
+        for (;;) {
+            const rec = this.store.get(taskId);
+            if (!rec)
+                throw new Error(`task 不存在: ${taskId}`);
+            if (rec.status === 'succeeded' || rec.status === 'failed')
+                return rec;
+            if (Date.now() - start > timeoutMs) {
+                throw new Error(`task ${taskId} 等待超时（${rec.status}）`);
+            }
+            await new Promise((r) => setTimeout(r, intervalMs));
+        }
+    }
+    /**
+     * 宿主重启续跑：把 store 里 queued | running 的记录重新派发执行
+     * （running 视为进程中断）。返回重派数量。幂等键去重照常生效。
+     */
+    resumePending() {
+        const pending = this.store
+            .list()
+            .filter((r) => r.status === 'queued' || r.status === 'running');
+        for (const rec of pending) {
+            rec.status = 'queued'; // 重新入队，由 #execute 统一推进
+            void this.#execute(rec.taskId);
+        }
+        return pending.length;
+    }
+    async #execute(taskId) {
+        const rec = this.store.get(taskId);
+        if (!rec)
+            return;
+        await this.#acquireSlot();
+        rec.status = 'running';
+        rec.startedAt = Date.now();
+        this.store.save(rec);
+        try {
+            const callOpts = {
+                ...(rec.spec.options ?? {}),
+                client: rec.spec.options?.client ?? this.client,
+                idempotencyKey: rec.idempotencyKey,
+                rethrow: false, // 硬失败也以 failed 记录落库
+            };
+            const out = await this.app.run(rec.spec.messages, callOpts);
+            rec.runId = out.run.runId;
+            rec.status = out.run.status;
+            rec.result = out.result;
+            rec.error = out.result.error;
+        }
+        catch (e) {
+            rec.error = classifyError(e);
+            rec.status = 'failed';
+        }
+        finally {
+            rec.finishedAt = Date.now();
+            this.store.save(rec);
+            this.#releaseSlot();
+        }
+    }
+    /** 并发槽位：超限则排队等待（任务记录保持 queued，由 store 可见） */
+    #acquireSlot() {
+        if (this.running < this.concurrency) {
+            this.running++;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => this.waitQueue.push(resolve));
+    }
+    #releaseSlot() {
+        const next = this.waitQueue.shift();
+        if (next) {
+            next(); // 槽位直接移交给等待者，running 计数不变
+        }
+        else {
+            this.running--;
+        }
+    }
+}
+//# sourceMappingURL=async.js.map

package/dist/run/async.js.map

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

package/dist/run/context.d.ts

@@ -0,0 +1,16 @@
+import type { Run } from './run.js';
+/** 在指定 ctx 下执行（executeRun 内部使用）；当前上下文对外以 current() 读取 */
+export declare function withRunContext<T>(ctx: RunContext, fn: () => T | Promise<T>): Promise<T>;
+export declare class RunContext {
+    readonly run: Run;
+    private readonly blackboard;
+    constructor(run: Run);
+    /** 当前 run 的上下文。不在 run 内调用时返回 undefined。 */
+    static current(): RunContext | undefined;
+    get runId(): string;
+    get<T>(key: string): T | undefined;
+    set(key: string, value: unknown): this;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    keys(): string[];
+}

package/dist/run/context.js

@@ -0,0 +1,48 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+/**
+ * Agentia —— run 作用域上下文（spec §2/§9：blackboard + 上下文传播载体）。
+ *
+ * 传播机制（Turn 2 接入）：executeRun 在建 Run 后、跑 engine 前，把本次
+ * RunContext 放进 AsyncLocalStorage；runAgent 内任何异步调用（含工具执行、
+ * 后续 subagent/skill 执行体）同处该 async 上下文，因此工具方法体内可直接
+ * `RunContext.current()` 拿到当前 run —— 无需把 ctx 作为参数层层下传。
+ *
+ * blackboard：单次 run 内累积的项目事实/产物，随 run 释放（spec §2）。
+ * 当前 span 句柄与单元 span 容器在后续 Turn（unit span + TraceInterceptor）接入。
+ */
+const store = new AsyncLocalStorage();
+/** 在指定 ctx 下执行（executeRun 内部使用）；当前上下文对外以 current() 读取 */
+export function withRunContext(ctx, fn) {
+    return store.run(ctx, fn);
+}
+export class RunContext {
+    run;
+    blackboard = new Map();
+    constructor(run) {
+        this.run = run;
+    }
+    /** 当前 run 的上下文。不在 run 内调用时返回 undefined。 */
+    static current() {
+        return store.getStore();
+    }
+    get runId() {
+        return this.run.runId;
+    }
+    get(key) {
+        return this.blackboard.get(key);
+    }
+    set(key, value) {
+        this.blackboard.set(key, value);
+        return this;
+    }
+    has(key) {
+        return this.blackboard.has(key);
+    }
+    delete(key) {
+        return this.blackboard.delete(key);
+    }
+    keys() {
+        return [...this.blackboard.keys()];
+    }
+}
+//# sourceMappingURL=context.js.map

package/dist/run/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/run/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD;;;;;;;;;;GAUG;AACH,MAAM,KAAK,GAAG,IAAI,iBAAiB,EAAc,CAAC;AAElD,yDAAyD;AACzD,MAAM,UAAU,cAAc,CAAI,GAAe,EAAE,EAAwB;IACzE,OAAO,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAe,CAAC;AAC1C,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,GAAG,CAAI,GAAW;QAChB,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAkB,CAAC;IACnD,CAAC;IACD,GAAG,CAAC,GAAW,EAAE,KAAc;QAC7B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClC,CAAC;IACD,MAAM,CAAC,GAAW;QAChB,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACrC,CAAC;IACD,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;IACrC,CAAC;CACF"}

package/dist/run/fsStore.d.ts

@@ -0,0 +1,29 @@
+import type { TaskRecord, TaskStore } from './store.js';
+/**
+ * Agentia —— 文件宿主 TaskStore（spec §6.6：异步耐久 = 换宿主不换语义）。
+ *
+ * InMemoryTaskStore 在进程重启即丢；FileTaskStore 用 JSONL 把任务记录落到磁盘，
+ * AsyncRunner/Scheduler/触发层**零改动** —— 证明耐久只是换个 store 实现。
+ *
+ * 语义：
+ * - 一行一条记录快照；save 覆写内存 Map 并 append（boot 重读时 last-wins，无顺序依赖）；
+ * - 构造即 load：文件不存在则从空开始，写入自动建目录；
+ * - 宿主重启后：new FileTaskStore(path) 读回记录 → AsyncRunner.resumePending() 续跑
+ *   queued/running（running 视为中断）。幂等键去重照常生效（失败可重提）。
+ *
+ * 前提：**单宿主写者**。append 用同步写保证进程内串行；多进程写同一文件会交错，
+ * 跨进程协调（锁/队列）属于部署层职责，不在本实现内。
+ */
+export declare class FileTaskStore implements TaskStore {
+    private readonly file;
+    private readonly byTask;
+    private readonly byKey;
+    constructor(file: string);
+    private load;
+    private append;
+    save(rec: TaskRecord): void;
+    get(taskId: string): TaskRecord | undefined;
+    byIdempotency(key: string): TaskRecord | undefined;
+    list(): TaskRecord[];
+    clear(): void;
+}

package/dist/run/fsStore.js

@@ -0,0 +1,79 @@
+import { mkdirSync, readFileSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * Agentia —— 文件宿主 TaskStore（spec §6.6：异步耐久 = 换宿主不换语义）。
+ *
+ * InMemoryTaskStore 在进程重启即丢；FileTaskStore 用 JSONL 把任务记录落到磁盘，
+ * AsyncRunner/Scheduler/触发层**零改动** —— 证明耐久只是换个 store 实现。
+ *
+ * 语义：
+ * - 一行一条记录快照；save 覆写内存 Map 并 append（boot 重读时 last-wins，无顺序依赖）；
+ * - 构造即 load：文件不存在则从空开始，写入自动建目录；
+ * - 宿主重启后：new FileTaskStore(path) 读回记录 → AsyncRunner.resumePending() 续跑
+ *   queued/running（running 视为中断）。幂等键去重照常生效（失败可重提）。
+ *
+ * 前提：**单宿主写者**。append 用同步写保证进程内串行；多进程写同一文件会交错，
+ * 跨进程协调（锁/队列）属于部署层职责，不在本实现内。
+ */
+export class FileTaskStore {
+    file;
+    byTask = new Map();
+    byKey = new Map(); // idempotencyKey → taskId
+    constructor(file) {
+        this.file = file;
+        this.load();
+    }
+    load() {
+        if (!existsSync(this.file))
+            return;
+        let raw;
+        try {
+            raw = readFileSync(this.file, 'utf8');
+        }
+        catch {
+            return; // 读失败按空宿主启动（宿主可另行告警）
+        }
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const rec = JSON.parse(line);
+                if (!rec || typeof rec.taskId !== 'string')
+                    continue;
+                this.byTask.set(rec.taskId, rec);
+                if (rec.idempotencyKey)
+                    this.byKey.set(rec.idempotencyKey, rec.taskId);
+            }
+            catch {
+                // 单条损坏跳过，不整库崩
+            }
+        }
+    }
+    append(rec) {
+        mkdirSync(dirname(this.file), { recursive: true });
+        writeFileSync(this.file, `${JSON.stringify(rec)}\n`, { flag: 'a' });
+    }
+    save(rec) {
+        this.byTask.set(rec.taskId, rec);
+        if (rec.idempotencyKey)
+            this.byKey.set(rec.idempotencyKey, rec.taskId);
+        this.append(rec);
+    }
+    get(taskId) {
+        return this.byTask.get(taskId);
+    }
+    byIdempotency(key) {
+        const taskId = this.byKey.get(key);
+        return taskId ? this.byTask.get(taskId) : undefined;
+    }
+    list() {
+        return [...this.byTask.values()];
+    }
+    clear() {
+        this.byTask.clear();
+        this.byKey.clear();
+        if (existsSync(this.file))
+            rmSync(this.file);
+    }
+}
+//# sourceMappingURL=fsStore.js.map

package/dist/run/fsStore.js.map

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

package/dist/run/run.d.ts

@@ -0,0 +1,50 @@
+import type { AgentRunResult, RunAgentOptions } from '../engine/types.js';
+import { TraceRecorder } from '../engine/tracer.js';
+import type { RunMeta, RunStatus } from './types.js';
+import { RunContext } from './context.js';
+/**
+ * Run —— 一次运行的生命周期容器（spec §2/§6.1）。
+ * runId == recorder.traceId == traceId（1:1）。
+ * recorder 由 engine 的 runAgent 写入（run 根 span 归 engine 开）。
+ */
+export declare class Run {
+    readonly recorder: TraceRecorder;
+    readonly runId: string;
+    readonly idempotencyKey?: string;
+    readonly createdAt: number;
+    private _status;
+    startedAt?: number;
+    finishedAt?: number;
+    private _result?;
+    constructor(opts?: {
+        idempotencyKey?: string;
+    });
+    get status(): RunStatus;
+    get result(): AgentRunResult | undefined;
+    /** meta（供运行记录/持久化使用） */
+    toMeta(): RunMeta;
+    start(): void;
+    finish(result: AgentRunResult): void;
+    fail(error: unknown): void;
+}
+export interface ExecuteRunOptions extends RunAgentOptions {
+    idempotencyKey?: string;
+    /** 在 runAgent 前对本次 RunContext 做预置（blackboard 种子等） */
+    contextInit?: (ctx: RunContext) => void;
+    /**
+     * 硬失败（请求/API 层异常）是否抛出。缺省 true；
+     * 异步宿主（AsyncRunner）置 false：失败也以 {run(status=failed), result.error} 返回，
+     * 便于把失败 run 落库而非冒泡。
+     */
+    rethrow?: boolean;
+}
+/**
+ * 高层入口：建 Run → start → 注入 recorder 跑 engine → finish。
+ * run 层持有 recorder，返回后 run.recorder 里的 trace 即本次完整调用树。
+ * RunContext 在整个执行期间经 AsyncLocalStorage 可被 `RunContext.current()` 读到，
+ * 工具/单元执行体无需把 ctx 作为参数层层下传。
+ */
+export declare function executeRun(options: ExecuteRunOptions): Promise<{
+    run: Run;
+    result: AgentRunResult;
+}>;