@migor/agentia 0.0.2 → 0.2.0

package/dist/run/openai.js

@@ -0,0 +1,181 @@
+export function createOpenAIClient(opts = {}) {
+    const baseURL = (opts.baseURL ?? 'https://api.openai.com').replace(/\/+$/, '');
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const apiKey = opts.apiKey ?? process.env.OPENAI_API_KEY;
+    return {
+        messages: {
+            stream(params) {
+                const textCallbacks = [];
+                return {
+                    on(event, cb) {
+                        if (event === 'text')
+                            textCallbacks.push(cb);
+                    },
+                    async finalMessage() {
+                        const res = await fetchImpl(`${baseURL}/v1/chat/completions`, {
+                            method: 'POST',
+                            headers: {
+                                'content-type': 'application/json',
+                                ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}),
+                            },
+                            body: JSON.stringify(toOpenAIRequest(params)),
+                        });
+                        if (!res.ok) {
+                            const body = await res.text();
+                            throw new Error(`OpenAI 请求失败 ${res.status}: ${body.slice(0, 200)}`);
+                        }
+                        const data = (await res.json());
+                        const message = toAnthropicMessage(data, params.model);
+                        // 非流式模拟：完整文本一次性发给 text 回调
+                        const fullText = message.content
+                            .filter((b) => b.type === 'text')
+                            .map((b) => b.text)
+                            .join('');
+                        if (fullText)
+                            for (const cb of textCallbacks)
+                                cb(fullText);
+                        return message;
+                    },
+                };
+            },
+        },
+    };
+}
+/** Anthropic 请求形态 → OpenAI chat.completions 请求 */
+function toOpenAIRequest(params) {
+    const messages = [];
+    if (params.system) {
+        messages.push({
+            role: 'system',
+            content: typeof params.system === 'string'
+                ? params.system
+                : params.system.map((b) => b.text).join('\n'),
+        });
+    }
+    for (const m of params.messages) {
+        if (typeof m.content === 'string') {
+            messages.push({ role: m.role, content: m.content });
+            continue;
+        }
+        if (m.role === 'user') {
+            // tool_result blocks：每个 block 一条 role=tool 消息；其余合成一条 user
+            const blocks = m.content;
+            const toolResults = blocks.filter((b) => b.type === 'tool_result');
+            const rest = blocks.filter((b) => b.type !== 'tool_result');
+            for (const tr of toolResults) {
+                messages.push({
+                    role: 'tool',
+                    tool_call_id: tr.tool_use_id,
+                    content: tr.content === undefined
+                        ? ''
+                        : typeof tr.content === 'string'
+                            ? tr.content
+                            : JSON.stringify(tr.content),
+                });
+            }
+            if (rest.length > 0)
+                messages.push({ role: 'user', content: renderBlocks(rest) });
+        }
+        else {
+            // assistant：文本部分进 content（无则 null），tool_use → tool_calls
+            const blocks = m.content;
+            const text = blocks
+                .filter((b) => b.type === 'text')
+                .map((b) => b.text)
+                .join('\n');
+            const toolUses = blocks.filter((b) => b.type === 'tool_use');
+            messages.push({
+                role: 'assistant',
+                content: text || null,
+                ...(toolUses.length > 0
+                    ? {
+                        tool_calls: toolUses.map((tu) => ({
+                            id: tu.id,
+                            type: 'function',
+                            function: { name: tu.name, arguments: JSON.stringify(tu.input) },
+                        })),
+                    }
+                    : {}),
+            });
+        }
+    }
+    return {
+        model: params.model,
+        max_tokens: params.max_tokens,
+        messages,
+        ...(params.tools && params.tools.length > 0
+            ? {
+                tools: params.tools.map((t) => ({
+                    type: 'function',
+                    function: {
+                        name: t.name,
+                        ...(t.description ? { description: t.description } : {}),
+                        parameters: t.input_schema,
+                    },
+                })),
+            }
+            : {}),
+    };
+}
+/** user 消息中非 tool_result 的 blocks 合成一段文本（text 取文本，其余 JSON 兜底） */
+function renderBlocks(blocks) {
+    return blocks
+        .map((b) => (b.type === 'text' ? b.text : JSON.stringify(b)))
+        .join('\n');
+}
+/** OpenAI chat.completions 响应 → Anthropic.Message */
+function toAnthropicMessage(data, model) {
+    const choice = data.choices?.[0];
+    const msg = choice?.message ?? {};
+    const content = [];
+    if (typeof msg.content === 'string' && msg.content) {
+        content.push({ type: 'text', text: msg.content });
+    }
+    for (const tc of msg.tool_calls ?? []) {
+        let input;
+        try {
+            input = JSON.parse(tc.function.arguments);
+        }
+        catch {
+            // arguments 非法 JSON：原样字符串兜底，交给下游 schema 校验报 is_error
+            input = tc.function.arguments;
+        }
+        content.push({
+            type: 'tool_use',
+            id: tc.id,
+            name: tc.function.name,
+            input,
+        });
+    }
+    return {
+        id: data.id ?? 'chatcmpl-unknown',
+        type: 'message',
+        role: 'assistant',
+        model: data.model ?? model,
+        content,
+        stop_reason: mapStopReason(choice?.finish_reason),
+        stop_sequence: null,
+        usage: {
+            input_tokens: data.usage?.prompt_tokens ?? 0,
+            output_tokens: data.usage?.completion_tokens ?? 0,
+            // OpenAI 形态无 cache 计量：恒 0
+            cache_creation_input_tokens: 0,
+            cache_read_input_tokens: 0,
+        },
+    };
+}
+/** finish_reason → Anthropic stop_reason（content_filter→refusal 为近似映射） */
+function mapStopReason(finish) {
+    switch (finish) {
+        case 'tool_calls':
+            return 'tool_use';
+        case 'length':
+            return 'max_tokens';
+        case 'content_filter':
+            return 'refusal';
+        case 'stop':
+        default:
+            return 'end_turn';
+    }
+}
+//# sourceMappingURL=openai.js.map

package/dist/run/openai.js.map

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

package/dist/run/otlp.d.ts

@@ -0,0 +1,26 @@
+import type { Trace } from '../core/trace.js';
+/**
+ * Agentia —— OTLP trace 导出（spec §9.3 生产方向，roadmap R3）。
+ *
+ * 把一次 run 的 Trace 映射为 OTLP/JSON（resourceSpans → scopeSpans → spans），
+ * 用全局 fetch POST 到 `${endpoint}/v1/traces`，零外部依赖：
+ * - traceId/spanId/parentSpanId：内部用 UUID，OTLP 要求 hex —— 去掉 '-' 即 32 位 hex；
+ * - kind 固定 SPAN_KIND_INTERNAL(1)；时间 ms × 1e6 转 string 纳秒；
+ * - status：ok → STATUS_CODE_OK，error → STATUS_CODE_ERROR（附 error.message）；
+ * - attributes 展平 span.attributes + usage（usage.* 前缀）；
+ * - events → OTLP events（body 的原始类型字段进 attributes，其余 JSON 化）。
+ *
+ * 非 2xx 抛错（含状态码与响应前 200 字符）。导出失败不影响 run 本身 —— 调用方自行取舍。
+ */
+export interface OtlpExporterOptions {
+    /** collector 基地址，例如 http://localhost:4318（尾部斜杠会被去掉） */
+    endpoint: string;
+    /** 额外请求头（鉴权等） */
+    headers?: Record<string, string>;
+    /** resource 的 service.name，缺省 'agentia' */
+    serviceName?: string;
+}
+export interface OtlpExporter {
+    export(trace: Trace): Promise<void>;
+}
+export declare function createOtlpExporter(opts: OtlpExporterOptions): OtlpExporter;

package/dist/run/otlp.js

@@ -0,0 +1,105 @@
+function toValue(v) {
+    if (typeof v === 'string')
+        return { stringValue: v };
+    if (typeof v === 'boolean')
+        return { boolValue: v };
+    // OTLP int64 走 string；小数用 double
+    return Number.isInteger(v) ? { intValue: String(v) } : { doubleValue: v };
+}
+/** 内部 UUID → OTLP hex（去掉 '-' 即 32 位小写 hex） */
+function hexId(id) {
+    return id.replaceAll('-', '');
+}
+/** ms → string 纳秒 */
+function nanos(ms) {
+    return String(Math.round(ms * 1e6));
+}
+function spanAttributes(span) {
+    const attrs = Object.entries(span.attributes).map(([key, v]) => ({
+        key,
+        value: toValue(v),
+    }));
+    if (span.usage) {
+        const u = span.usage;
+        attrs.push({ key: 'usage.inputTokens', value: toValue(u.inputTokens) }, { key: 'usage.outputTokens', value: toValue(u.outputTokens) }, { key: 'usage.cacheReadTokens', value: toValue(u.cacheReadTokens) }, { key: 'usage.cacheCreationTokens', value: toValue(u.cacheCreationTokens) });
+        if (u.costEstimate !== undefined) {
+            attrs.push({ key: 'usage.costEstimate', value: toValue(u.costEstimate) });
+        }
+    }
+    return attrs;
+}
+function eventAttributes(body) {
+    if (body === undefined)
+        return [];
+    if (body && typeof body === 'object' && !Array.isArray(body)) {
+        return Object.entries(body).map(([key, v]) => ({
+            key,
+            value: typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean'
+                ? toValue(v)
+                : { stringValue: JSON.stringify(v) },
+        }));
+    }
+    return [{ key: 'body', value: { stringValue: JSON.stringify(body) } }];
+}
+function mapEvent(e) {
+    return {
+        timeUnixNano: nanos(e.time),
+        name: e.name,
+        attributes: eventAttributes(e.body),
+    };
+}
+function mapSpan(span) {
+    return {
+        traceId: hexId(span.traceId),
+        spanId: hexId(span.spanId),
+        ...(span.parentSpanId ? { parentSpanId: hexId(span.parentSpanId) } : {}),
+        name: span.name,
+        kind: 1, // SPAN_KIND_INTERNAL
+        startTimeUnixNano: nanos(span.startedAt),
+        ...(span.endedAt !== undefined ? { endTimeUnixNano: nanos(span.endedAt) } : {}),
+        attributes: spanAttributes(span),
+        events: span.events.map(mapEvent),
+        status: span.status === 'error'
+            ? {
+                code: 'STATUS_CODE_ERROR',
+                ...(span.error ? { message: span.error.message } : {}),
+            }
+            : { code: 'STATUS_CODE_OK' },
+    };
+}
+export function createOtlpExporter(opts) {
+    const endpoint = opts.endpoint.replace(/\/+$/, '');
+    const serviceName = opts.serviceName ?? 'agentia';
+    return {
+        async export(trace) {
+            const payload = {
+                resourceSpans: [
+                    {
+                        resource: {
+                            attributes: [{ key: 'service.name', value: { stringValue: serviceName } }],
+                        },
+                        scopeSpans: [
+                            {
+                                scope: { name: 'agentia' },
+                                spans: trace.spans.map(mapSpan),
+                            },
+                        ],
+                    },
+                ],
+            };
+            const res = await fetch(`${endpoint}/v1/traces`, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    ...opts.headers,
+                },
+                body: JSON.stringify(payload),
+            });
+            if (!res.ok) {
+                const text = (await res.text()).slice(0, 200);
+                throw new Error(`OTLP 导出失败: HTTP ${res.status} ${text}`);
+            }
+        },
+    };
+}
+//# sourceMappingURL=otlp.js.map

package/dist/run/otlp.js.map

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

package/dist/run/redisStore.d.ts

@@ -0,0 +1,54 @@
+import type { TaskRecord, TaskStore } from './store.js';
+/**
+ * Agentia —— Redis 宿主 TaskStore（spec §6.6：异步耐久 = 换宿主不换语义，roadmap R6）。
+ *
+ * duck-typed 客户端：框架不 import 任何 redis 包，用户传 ioredis / node-redis /
+ * 任何满足 RedisLike 结构面的客户端（含测试 fake）。TaskStore 方法已放宽为
+ * MaybePromise（见 store.ts），本实现全部异步。
+ *
+ * 存储模型（prefix 缺省 'agentia:'）：
+ * - `${prefix}task:<taskId>` → 整行记录 JSON（save = SET 覆写，last-wins）；
+ * - `${prefix}idem:<idempotencyKey>` → taskId（同键重提覆写，byIdempotency last-wins）。
+ *
+ * 语义对照 FileTaskStore / SqliteTaskStore：save 覆写、byIdempotency 取最近、
+ * clear 清空本前缀全部 key。差异在 list 序：Redis 本身无序，按 createdAt
+ * （同刻按 taskId）排序 —— 「写入顺序」语义的确定性近似（FileTaskStore 保插入位、
+ * SqliteTaskStore 覆写后移到末尾，三者本就不逐字一致，排序给出稳定契约）。
+ *
+ * 前提：**单宿主写者**。save 是两次 SET（记录 + 幂等索引），未走 MULTI 事务；
+ * 多写者并发下同键写可能交错，跨进程协调属部署层职责（与 FileTaskStore 一致）。
+ */
+export interface RedisLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<unknown>;
+    /** 单键删除（ioredis / node-redis 的公共最小面；批量清理由多次单删组成） */
+    del(key: string): Promise<unknown>;
+    /** 模式枚举（node-redis / ioredis 均有）；与 scanIterator 至少提供其一 */
+    keys?(pattern: string): Promise<string[]>;
+    /**
+     * 增量枚举（node-redis v4+ 形态，生产友好不阻塞）；yield 单键或一批键均可。
+     * 提供时优先于 keys 使用。
+     */
+    scanIterator?(opts?: {
+        MATCH?: string;
+        COUNT?: number;
+    }): AsyncIterable<string | string[]>;
+}
+export interface RedisTaskStoreOptions {
+    /** key 前缀，缺省 'agentia:' */
+    prefix?: string;
+}
+export declare class RedisTaskStore implements TaskStore {
+    private readonly client;
+    private readonly prefix;
+    constructor(client: RedisLike, opts?: RedisTaskStoreOptions);
+    private taskKey;
+    private idemKey;
+    save(rec: TaskRecord): Promise<void>;
+    get(taskId: string): Promise<TaskRecord | undefined>;
+    byIdempotency(key: string): Promise<TaskRecord | undefined>;
+    list(): Promise<TaskRecord[]>;
+    clear(): Promise<void>;
+    /** 按键枚举：优先 scanIterator，缺则退回 keys(pattern) */
+    private enumerate;
+}

package/dist/run/redisStore.js

@@ -0,0 +1,72 @@
+export class RedisTaskStore {
+    client;
+    prefix;
+    constructor(client, opts = {}) {
+        this.client = client;
+        if (!client.scanIterator && !client.keys) {
+            throw new Error('RedisTaskStore 需要 client 提供 scanIterator 或 keys 之一（list/clear 依赖按键枚举）');
+        }
+        this.prefix = opts.prefix ?? 'agentia:';
+    }
+    taskKey(taskId) {
+        return `${this.prefix}task:${taskId}`;
+    }
+    idemKey(key) {
+        return `${this.prefix}idem:${key}`;
+    }
+    async save(rec) {
+        await this.client.set(this.taskKey(rec.taskId), JSON.stringify(rec));
+        if (rec.idempotencyKey)
+            await this.client.set(this.idemKey(rec.idempotencyKey), rec.taskId);
+    }
+    async get(taskId) {
+        return parseRecord(await this.client.get(this.taskKey(taskId)));
+    }
+    async byIdempotency(key) {
+        const taskId = await this.client.get(this.idemKey(key));
+        return taskId ? this.get(taskId) : undefined;
+    }
+    async list() {
+        const keys = await this.enumerate(`${this.prefix}task:*`);
+        const recs = [];
+        for (const k of keys) {
+            const rec = parseRecord(await this.client.get(k));
+            if (rec)
+                recs.push(rec);
+        }
+        recs.sort((a, b) => a.createdAt - b.createdAt || (a.taskId < b.taskId ? -1 : a.taskId > b.taskId ? 1 : 0));
+        return recs;
+    }
+    async clear() {
+        const keys = await this.enumerate(`${this.prefix}*`);
+        for (const k of keys)
+            await this.client.del(k);
+    }
+    /** 按键枚举：优先 scanIterator，缺则退回 keys(pattern) */
+    async enumerate(pattern) {
+        if (this.client.scanIterator) {
+            const out = [];
+            for await (const batch of this.client.scanIterator({ MATCH: pattern, COUNT: 100 })) {
+                if (Array.isArray(batch))
+                    out.push(...batch);
+                else
+                    out.push(batch);
+            }
+            return out;
+        }
+        return this.client.keys(pattern);
+    }
+}
+/** 解析整行 JSON；单条损坏按缺失处理，不整库崩（与 FileTaskStore 对齐） */
+function parseRecord(raw) {
+    if (!raw)
+        return undefined;
+    try {
+        const rec = JSON.parse(raw);
+        return rec && typeof rec.taskId === 'string' ? rec : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=redisStore.js.map

package/dist/run/redisStore.js.map

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

package/dist/run/run.d.ts

@@ -2,6 +2,7 @@ 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';
+import type { MemoryStore } from './memory.js';
 /**
  * Run —— 一次运行的生命周期容器（spec §2/§6.1）。
  * runId == recorder.traceId == traceId（1:1）。
@@ -31,6 +32,15 @@ export interface ExecuteRunOptions extends RunAgentOptions {
     idempotencyKey?: string;
     /** 在 runAgent 前对本次 RunContext 做预置（blackboard 种子等） */
     contextInit?: (ctx: RunContext) => void;
+    /**
+     * 跨 run 记忆（R4）：run 开始把 store.load(keys) 水合进 blackboard
+     * （在 contextInit 之后执行，且用户种子优先 —— 不覆盖已有同名 key）；
+     * run 结束（finish/fail 两条路径）把这些 key 的当前值 save 回 store。
+     */
+    memory?: {
+        store: MemoryStore;
+        keys: string[];
+    };
     /**
      * 硬失败（请求/API 层异常）是否抛出。缺省 true；
      * 异步宿主（AsyncRunner）置 false：失败也以 {run(status=failed), result.error} 返回，

package/dist/run/run.js

@@ -80,19 +80,50 @@ export async function executeRun(options) {
     const run = new Run({ idempotencyKey: options.idempotencyKey });
     run.start();
     const ctx = new RunContext(run);
+    const memory = options.memory;
     return withRunContext(ctx, async () => {
         try {
             options.contextInit?.(ctx);
+            if (memory)
+                await hydrateMemory(memory, ctx);
             const result = await runAgent({ ...options, recorder: run.recorder });
             run.finish(result);
+            if (memory)
+                await flushMemory(memory, ctx);
             return { run, result };
         }
         catch (e) {
             run.fail(e);
+            if (memory) {
+                // 失败路径也回写；save 自身出错不掩盖原始错误
+                try {
+                    await flushMemory(memory, ctx);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
             if (options.rethrow === false)
                 return { run, result: run.result };
             throw e;
         }
     });
 }
+/** 水合：store 值注入 blackboard；contextInit 已写的同名 key 不覆盖（用户种子优先） */
+async function hydrateMemory(memory, ctx) {
+    const loaded = await memory.store.load(memory.keys);
+    for (const key of memory.keys) {
+        if (key in loaded && !ctx.has(key))
+            ctx.set(key, loaded[key]);
+    }
+}
+/** 回写：blackboard 里这些 key 的当前值存回 store */
+async function flushMemory(memory, ctx) {
+    const entries = {};
+    for (const key of memory.keys) {
+        if (ctx.has(key))
+            entries[key] = ctx.get(key);
+    }
+    await memory.store.save(entries);
+}
 //# sourceMappingURL=run.js.map

package/dist/run/run.js.map

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

package/dist/run/spec.d.ts

@@ -1,4 +1,5 @@
 import type Anthropic from '@anthropic-ai/sdk';
+import type { ModelClient } from '../core/tool.js';
 import type { AgentTool } from '../core/tool.js';
 import type { ContextPolicy } from '../engine/types.js';
 /**
@@ -11,7 +12,7 @@ export interface RunInvocationOptions {
     model?: string;
     maxTokens?: number;
     maxIterations?: number;
-    client?: Anthropic;
+    client?: ModelClient;
     onText?: (delta: string) => void;
     /** 预置进本次 RunContext.blackboard */
     blackboard?: Record<string, unknown>;

package/dist/run/spec.js.map

@@ -1 +1 @@
-{"version":3,"file":"spec.js","sourceRoot":"","sources":["../../src/run/spec.ts"],"names":[],"mappings":"AA0CA,wCAAwC;AACxC,MAAM,UAAU,iBAAiB,CAAC,KAAyB;IACzD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACzD,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC;QAC5D,OAAO,KAAiC,CAAC;IAC3C,CAAC;IACD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,CAAC,GAAG,KAAiE,CAAC;QAC5E,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC;YACjE,OAAO,CAAC,CAAC,QAAoC,CAAC;QAChD,CAAC;QACD,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM;YAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QAC3F,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI;YAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;AACxE,CAAC"}
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../../src/run/spec.ts"],"names":[],"mappings":"AA2CA,wCAAwC;AACxC,MAAM,UAAU,iBAAiB,CAAC,KAAyB;IACzD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACzD,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC;QAC5D,OAAO,KAAiC,CAAC;IAC3C,CAAC;IACD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,CAAC,GAAG,KAAiE,CAAC;QAC5E,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC;YACjE,OAAO,CAAC,CAAC,QAAoC,CAAC;QAChD,CAAC;QACD,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM;YAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QAC3F,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI;YAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;AACxE,CAAC"}

package/dist/run/sqliteStore.d.ts

@@ -0,0 +1,24 @@
+import type { TaskRecord, TaskStore } from './store.js';
+/**
+ * Agentia —— SQLite 宿主 TaskStore（spec §6.6：异步耐久 = 换宿主不换语义，roadmap R3）。
+ *
+ * 基于 Node 内置 node:sqlite（DatabaseSync），零外部依赖。语义与 FileTaskStore 逐字对齐：
+ * - save = INSERT OR REPLACE（整行记录 JSON 存 json 列，last-wins）；
+ * - byIdempotency 取该键最近一次 save 的记录（按 rowid 倒序，失败重提产生的新任务胜出）；
+ * - list 按写入顺序返回；clear 清空整表；
+ * - 构造即就绪（建表 + 索引，无异步），重启续跑同样交给 AsyncRunner.resumePending()。
+ *
+ * 对比 FileTaskStore 的**单写者前提**：多进程安全由 SQLite WAL/事务天然保证 ——
+ * 多个宿主进程可同时打开同一库文件，写事务由 SQLite 串行化，无需部署层加锁。
+ */
+export declare class SqliteTaskStore implements TaskStore {
+    private readonly db;
+    constructor(path: string);
+    save(rec: TaskRecord): void;
+    get(taskId: string): TaskRecord | undefined;
+    byIdempotency(key: string): TaskRecord | undefined;
+    list(): TaskRecord[];
+    clear(): void;
+    /** 关闭底层连接（测试/进程收尾用；TaskStore 接口之外的能力） */
+    close(): void;
+}