@armadra/agent 0.0.0-stage → 0.3.0

package/dist/ai/cache/warmer.js

@@ -0,0 +1,224 @@
+/**
+ * 缓存保温状态机（第三波 §1.7）。[W3-C1b]
+ *
+ * 注入 now / 计时器 / 发送函数，fake 时钟可测：
+ * - `start(record, ttlMs)`：每个 turn 请求完成后调用（替换上一轮）；计时**从请求发出算**：
+ *   `delay = max(1s, floor(min(0.9·TTL, TTL − 10s)))`，TTL ≤ 10 s 不保温。
+ * - 截止 `deadline = nextWarmAt + (TTL − delay) / 2`：计时器迟到超过截止（睡眠、事件循环阻塞）
+ *   直接停——迟到的刷新大概率是一次全价写入。
+ * - 上限：streaming 相 60 min、idle 相 30 min（从起始真实请求算）；连续 2 次保温响应读写都为
+ *   0 即停。
+ * - 每次刷新前：`isCurrent(record)` 不成立 → 停；内置经济性决策交给否决钩子 `decide`（出错
+ *   回落内置决策）。
+ * - `onAgentSettled()`：streaming 模式静默结束本轮；idle 模式转空闲相。
+ * - `pause()`：真实请求发出时静默挂起（新请求本身就刷新了缓存）；`cancel()` 同时丢弃记录。
+ * 只有已排期之后的异常停止（截止、上限、零命中、过期、否决、失败）回调 `onStopped`。
+ */
+import { expectedSavings } from "./economics.js";
+export const WARM_MIN_TTL_MS = 10_000;
+export const WARM_STREAMING_CAP_MS = 60 * 60_000;
+export const WARM_IDLE_CAP_MS = 30 * 60_000;
+export const WARM_ZERO_HIT_LIMIT = 2;
+/** 真实计时器：`unref()`，保温不拖住进程退出。 */
+export const REAL_TIMERS = {
+    set(fn, ms) {
+        const handle = setTimeout(fn, ms);
+        handle.unref?.();
+        return handle;
+    },
+    clear(handle) {
+        clearTimeout(handle);
+    },
+};
+export function warmDelay(ttlMs) {
+    return Math.max(1000, Math.floor(Math.min(0.9 * ttlMs, ttlMs - 10_000)));
+}
+/**
+ * 不保温的原因（undefined = 可以保温）：
+ * - `cacheRetention: "none"` 的请求；被 `onPayload` 替换过请求体的请求；
+ * - anthropic-messages 开思考且不是自适应思考：预算从 `max_tokens` 推导，`max_tokens: 1` 会
+ *   去掉 thinking 块、改变缓存键；
+ * - 端点不是 `reported`（未知或不报缓存时看不出保温有没有用，第三波 §4 R2）。
+ */
+export function replayBlocker(check) {
+    if (check.options.cacheRetention === "none")
+        return "retention_none";
+    if (check.payloadReplaced)
+        return "payload_replaced";
+    const thinking = check.options.thinkingLevel !== undefined && check.options.thinkingLevel !== "off";
+    if (check.model.api === "anthropic-messages" &&
+        check.model.reasoning &&
+        thinking &&
+        check.model.compat?.adaptiveThinking !== true) {
+        return "thinking_budget";
+    }
+    if (check.reporting !== "reported")
+        return `reporting_${check.reporting}`;
+    return undefined;
+}
+export class CacheWarmer {
+    deps;
+    timers;
+    record;
+    origin = 0;
+    ttl = 0;
+    phase = "streaming";
+    timer;
+    inflight;
+    generation = 0;
+    zeroHits = 0;
+    state = "inactive";
+    reason;
+    nextWarmAt;
+    deadline = 0;
+    sent = 0;
+    costUsd = 0;
+    savings;
+    constructor(deps) {
+        this.deps = deps;
+        this.timers = deps.timers ?? REAL_TIMERS;
+    }
+    start(record, ttlMs) {
+        this.reset();
+        this.record = record;
+        this.origin = record.at;
+        this.ttl = ttlMs;
+        this.phase = "streaming";
+        this.zeroHits = 0;
+        if (this.deps.mode() === "off")
+            return;
+        if (ttlMs <= WARM_MIN_TTL_MS)
+            return this.block("ttl_too_short");
+        this.schedule(record.at);
+    }
+    /** 不排期并记下原因（无事件：不可重放、端点未报告、经济性不划算等）。 */
+    block(reason) {
+        this.reset();
+        this.state = "stopped";
+        this.reason = reason;
+    }
+    onAgentSettled() {
+        if (this.state !== "scheduled")
+            return;
+        if (this.deps.mode() === "idle")
+            this.phase = "idle";
+        else
+            this.reset();
+    }
+    /** 真实请求发出：静默挂起，保留统计。 */
+    pause() {
+        this.reset();
+    }
+    cancel() {
+        this.reset();
+        this.record = undefined;
+    }
+    get status() {
+        const status = { mode: this.deps.mode(), state: this.state };
+        if (this.state === "scheduled") {
+            status.phase = this.phase;
+            if (this.nextWarmAt !== undefined)
+                status.nextWarmAt = this.nextWarmAt;
+        }
+        if (this.state === "stopped" && this.reason !== undefined)
+            status.reason = this.reason;
+        if (this.sent > 0) {
+            status.sent = this.sent;
+            status.costUsd = this.costUsd;
+        }
+        if (this.savings !== undefined)
+            status.expectedSavingsUsd = this.savings;
+        return status;
+    }
+    reset() {
+        this.generation++;
+        if (this.timer !== undefined)
+            this.timers.clear(this.timer);
+        this.timer = undefined;
+        this.inflight?.abort();
+        this.inflight = undefined;
+        this.state = "inactive";
+        this.reason = undefined;
+        this.nextWarmAt = undefined;
+    }
+    stop(reason) {
+        this.reset();
+        this.state = "stopped";
+        this.reason = reason;
+        this.deps.onStopped(reason);
+    }
+    cap() {
+        return this.phase === "idle" ? WARM_IDLE_CAP_MS : WARM_STREAMING_CAP_MS;
+    }
+    schedule(base) {
+        const delay = warmDelay(this.ttl);
+        const next = base + delay;
+        if (next - this.origin > this.cap())
+            return this.stop("max_duration");
+        this.deadline = next + (this.ttl - delay) / 2;
+        this.state = "scheduled";
+        this.reason = undefined;
+        this.nextWarmAt = next;
+        const generation = this.generation;
+        this.timer = this.timers.set(() => void this.fire(generation), Math.max(0, next - this.deps.now()));
+        this.deps.onScheduled?.(next);
+    }
+    async decide(decision) {
+        const handler = this.deps.decide;
+        if (handler === undefined)
+            return decision.action;
+        try {
+            const answer = await handler(decision);
+            return answer === "warm" || answer === "stop" ? answer : decision.action;
+        }
+        catch {
+            return decision.action;
+        }
+    }
+    async fire(generation) {
+        if (generation !== this.generation || this.record === undefined)
+            return;
+        this.timer = undefined;
+        const record = this.record;
+        const now = this.deps.now();
+        const mode = this.deps.mode();
+        if (now > this.deadline)
+            return this.stop("late");
+        if (mode === "off" || (this.phase === "idle" && mode !== "idle"))
+            return this.stop("off");
+        if (now - this.origin > this.cap())
+            return this.stop("max_duration");
+        if (!this.deps.isCurrent(record))
+            return this.stop("stale");
+        const decision = this.deps.evaluate(record, this.phase);
+        const action = await this.decide(decision);
+        if (generation !== this.generation)
+            return;
+        this.savings = expectedSavings(decision);
+        if (action === "stop")
+            return this.stop(decision.reason ?? "declined");
+        const controller = new AbortController();
+        this.inflight = controller;
+        const sentAt = this.deps.now();
+        let message;
+        try {
+            message = await this.deps.send(record, controller.signal);
+        }
+        catch {
+            message = undefined;
+        }
+        if (generation !== this.generation)
+            return;
+        this.inflight = undefined;
+        if (message === undefined || message.stopReason === "error" || message.stopReason === "aborted")
+            return this.stop("error");
+        this.sent++;
+        this.costUsd += message.usage.cost?.total ?? 0;
+        this.deps.onWarmed(record, message, sentAt);
+        const hits = message.usage.cacheRead + message.usage.cacheWrite;
+        this.zeroHits = hits === 0 ? this.zeroHits + 1 : 0;
+        if (this.zeroHits >= WARM_ZERO_HIT_LIMIT)
+            return this.stop("no_cache_hits");
+        this.schedule(sentAt);
+    }
+}

package/dist/ai/context.d.ts

@@ -0,0 +1,35 @@
+/**
+ * normalizeContext（设计 §1.2 ai/context.ts）：把循环交来的转录（含 `system` 补丁消息）变成
+ * 协议可直接拼请求体的形状。
+ *
+ * - system 折叠：按出现顺序重放全部 system 消息的 `sections`（节名级替换，null 删除），得到
+ *   `systemSections`（保持节首次出现的顺序）与拼好的 `systemPrompt`（节间空一行）；
+ * - 工具表：按顺序重放 `toolsRemoved`（先）与 `toolsAdded`（后），同名后者覆盖；
+ * - 模态过滤：模型不收图片时，用户消息与工具结果里的图片块换成文字占位。
+ *
+ * 支持「中途 system 消息」的协议（compat.supportsMidConvoSystemMessages）用
+ * `normalizeContextInline()`：首条非 system 消息之前的 system 折叠进系统提示，之后的补丁
+ * 渲染为文本、按位置插回对话。
+ */
+import type { ContentBlock, Model, NormalizedContext, SystemMessage, TranscriptContext } from "./types.js";
+export interface NormalizeOptions {
+    /** 提供时按 `model.input` 过滤模态。 */
+    model?: Pick<Model, "input"> | undefined;
+}
+export declare const IMAGE_OMITTED_TEXT = "[image omitted: the model does not accept image input]";
+export declare function normalizeContext(context: TranscriptContext, options?: NormalizeOptions): NormalizedContext;
+/** 渲染一条中途 system 补丁的文本（节变更；工具表变化由请求的工具列表体现）。 */
+export declare function renderSystemUpdate(message: SystemMessage): string;
+export interface InlineSystemUpdate {
+    /** 插在 `messages[beforeIndex]` 之前；等于 messages.length 表示放在末尾。 */
+    beforeIndex: number;
+    text: string;
+}
+export interface InlineNormalizedContext extends NormalizedContext {
+    systemUpdates: InlineSystemUpdate[];
+}
+export declare function normalizeContextInline(context: TranscriptContext, options?: NormalizeOptions): InlineNormalizedContext;
+/** 文本内容（用户消息 / 工具结果），图片块忽略。 */
+export declare function contentText(content: string | ContentBlock[], separator?: string): string;
+/** 去掉孤立代理项（部分供应商对非法 UTF-16 直接 400）。 */
+export declare function sanitizeText(text: string): string;

package/dist/ai/context.js

@@ -0,0 +1,114 @@
+/**
+ * normalizeContext（设计 §1.2 ai/context.ts）：把循环交来的转录（含 `system` 补丁消息）变成
+ * 协议可直接拼请求体的形状。
+ *
+ * - system 折叠：按出现顺序重放全部 system 消息的 `sections`（节名级替换，null 删除），得到
+ *   `systemSections`（保持节首次出现的顺序）与拼好的 `systemPrompt`（节间空一行）；
+ * - 工具表：按顺序重放 `toolsRemoved`（先）与 `toolsAdded`（后），同名后者覆盖；
+ * - 模态过滤：模型不收图片时，用户消息与工具结果里的图片块换成文字占位。
+ *
+ * 支持「中途 system 消息」的协议（compat.supportsMidConvoSystemMessages）用
+ * `normalizeContextInline()`：首条非 system 消息之前的 system 折叠进系统提示，之后的补丁
+ * 渲染为文本、按位置插回对话。
+ */
+export const IMAGE_OMITTED_TEXT = "[image omitted: the model does not accept image input]";
+class SystemState {
+    sections = new Map();
+    tools = new Map();
+    apply(message) {
+        for (const [name, value] of Object.entries(message.sections)) {
+            if (value === null)
+                this.sections.delete(name);
+            else
+                this.sections.set(name, value);
+        }
+        for (const name of message.toolsRemoved ?? [])
+            this.tools.delete(name);
+        for (const tool of message.toolsAdded ?? [])
+            this.tools.set(tool.name, tool);
+    }
+    snapshot() {
+        const systemSections = [...this.sections.entries()]
+            .filter(([, text]) => text.length > 0)
+            .map(([name, text]) => ({ name, text }));
+        return {
+            systemPrompt: systemSections.map((section) => section.text).join("\n\n"),
+            systemSections,
+            tools: [...this.tools.values()],
+        };
+    }
+}
+function filterContent(content, allowImages) {
+    if (typeof content === "string" || allowImages)
+        return content;
+    if (!content.some((block) => block.type === "image"))
+        return content;
+    return content.map((block) => block.type === "image" ? { type: "text", text: IMAGE_OMITTED_TEXT } : block);
+}
+function filterMessage(message, allowImages) {
+    if (message.role === "assistant" || allowImages)
+        return message;
+    const content = filterContent(message.content, allowImages);
+    return content === message.content ? message : { ...message, content };
+}
+function allowsImages(options) {
+    return options?.model === undefined || options.model.input.includes("image");
+}
+export function normalizeContext(context, options) {
+    const state = new SystemState();
+    const messages = [];
+    const allowImages = allowsImages(options);
+    for (const message of context.messages) {
+        if (message.role === "system")
+            state.apply(message);
+        else
+            messages.push(filterMessage(message, allowImages));
+    }
+    return { ...state.snapshot(), messages };
+}
+/** 渲染一条中途 system 补丁的文本（节变更；工具表变化由请求的工具列表体现）。 */
+export function renderSystemUpdate(message) {
+    const parts = [];
+    for (const [name, value] of Object.entries(message.sections)) {
+        parts.push(value === null
+            ? `System prompt section "${name}" was removed.`
+            : `System prompt section "${name}" was updated:\n\n${value}`);
+    }
+    return parts.join("\n\n");
+}
+export function normalizeContextInline(context, options) {
+    const head = new SystemState();
+    const tools = new SystemState();
+    const messages = [];
+    const systemUpdates = [];
+    const allowImages = allowsImages(options);
+    for (const message of context.messages) {
+        if (message.role !== "system") {
+            messages.push(filterMessage(message, allowImages));
+            continue;
+        }
+        tools.apply(message);
+        if (messages.length === 0) {
+            head.apply(message);
+            continue;
+        }
+        const text = renderSystemUpdate(message);
+        if (text.length > 0)
+            systemUpdates.push({ beforeIndex: messages.length, text });
+    }
+    const snapshot = head.snapshot();
+    return { ...snapshot, tools: tools.snapshot().tools, messages, systemUpdates };
+}
+/** 文本内容（用户消息 / 工具结果），图片块忽略。 */
+export function contentText(content, separator = "\n") {
+    if (typeof content === "string")
+        return content;
+    return content
+        .filter((block) => block.type === "text")
+        .map((block) => block.text)
+        .join(separator);
+}
+/** 去掉孤立代理项（部分供应商对非法 UTF-16 直接 400）。 */
+export function sanitizeText(text) {
+    return text.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "�");
+}

package/dist/ai/cost.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 成本（设计 §3.6「成本」）：价格单位为美元 / 百万 token。
+ *
+ * - 阶梯：按 `input + cacheRead + cacheWrite`（本次请求的全部输入）选**严格超过**阈值的最高一档，
+ *   整单按该档计价；
+ * - `Usage.input` 不含缓存部分；
+ * - 1 小时缓存写入（`cacheWrite1h`，已包含在 `cacheWrite` 中）按 2× 基础输入价计；
+ * - 模型无 `cost` → 不写 `usage.cost`（界面显示 `$?`）；
+ * - `priceTokens` 给假想用量估价（保温经济性、未命中重计费、cache-probe 预估，第三波 §3.2）。
+ */
+import type { Model, Usage, UsageCost } from "./types.js";
+export declare function emptyUsage(): Usage;
+/** 计算并写回 `usage.cost`；无价格时删除 `usage.cost` 并返回 undefined。 */
+export declare function calculateCost(model: Pick<Model, "cost">, usage: Usage): UsageCost | undefined;
+/**
+ * [W3-C1a] 按目录价给一组假想 token 估价（美元）：与 `calculateCost` 同一套阶梯与 1h 写入规则，
+ * 缺省字段按 0；模型无 `cost` → undefined（价格为 0 时返回 0，「不可算」由调用方判断）。
+ */
+export declare function priceTokens(model: Pick<Model, "cost">, tokens: Partial<Pick<Usage, "input" | "output" | "cacheRead" | "cacheWrite">>): number | undefined;
+/** 重新计算 totalTokens（各家多数不直接给，或给的口径不同）。 */
+export declare function finalizeUsage(model: Pick<Model, "cost">, usage: Usage): Usage;

package/dist/ai/cost.js

@@ -0,0 +1,60 @@
+/**
+ * 成本（设计 §3.6「成本」）：价格单位为美元 / 百万 token。
+ *
+ * - 阶梯：按 `input + cacheRead + cacheWrite`（本次请求的全部输入）选**严格超过**阈值的最高一档，
+ *   整单按该档计价；
+ * - `Usage.input` 不含缓存部分；
+ * - 1 小时缓存写入（`cacheWrite1h`，已包含在 `cacheWrite` 中）按 2× 基础输入价计；
+ * - 模型无 `cost` → 不写 `usage.cost`（界面显示 `$?`）；
+ * - `priceTokens` 给假想用量估价（保温经济性、未命中重计费、cache-probe 预估，第三波 §3.2）。
+ */
+export function emptyUsage() {
+    return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0 };
+}
+function selectRates(cost, totalInput) {
+    let rates = cost;
+    let threshold = -1;
+    for (const tier of cost.tiers ?? []) {
+        if (totalInput > tier.inputTokensAbove && tier.inputTokensAbove > threshold) {
+            rates = tier;
+            threshold = tier.inputTokensAbove;
+        }
+    }
+    return rates;
+}
+/** 计算并写回 `usage.cost`；无价格时删除 `usage.cost` 并返回 undefined。 */
+export function calculateCost(model, usage) {
+    if (!model.cost) {
+        delete usage.cost;
+        return undefined;
+    }
+    const rates = selectRates(model.cost, usage.input + usage.cacheRead + usage.cacheWrite);
+    const longWrite = Math.min(usage.cacheWrite1h ?? 0, usage.cacheWrite);
+    const shortWrite = usage.cacheWrite - longWrite;
+    const cost = {
+        input: (rates.input * usage.input) / 1e6,
+        output: (rates.output * usage.output) / 1e6,
+        cacheRead: (rates.cacheRead * usage.cacheRead) / 1e6,
+        cacheWrite: (rates.cacheWrite * shortWrite + rates.input * 2 * longWrite) / 1e6,
+        total: 0,
+    };
+    cost.total = cost.input + cost.output + cost.cacheRead + cost.cacheWrite;
+    usage.cost = cost;
+    return cost;
+}
+/**
+ * [W3-C1a] 按目录价给一组假想 token 估价（美元）：与 `calculateCost` 同一套阶梯与 1h 写入规则，
+ * 缺省字段按 0；模型无 `cost` → undefined（价格为 0 时返回 0，「不可算」由调用方判断）。
+ */
+export function priceTokens(model, tokens) {
+    if (!model.cost)
+        return undefined;
+    const usage = { ...emptyUsage(), ...tokens };
+    return calculateCost(model, usage)?.total;
+}
+/** 重新计算 totalTokens（各家多数不直接给，或给的口径不同）。 */
+export function finalizeUsage(model, usage) {
+    usage.totalTokens = usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
+    calculateCost(model, usage);
+    return usage;
+}

package/dist/ai/event-stream.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 助手事件流（设计 §3.1）：生产者 push 事件，消费者 `for await` 读取，`result()` 拿最终消息。
+ *
+ * 不变量（由本类守住，协议实现不必各自防御）：
+ * - 终止事件（done / error）之后的 push 一律丢弃，只会有**一个**终止事件；
+ * - `result()` 在终止事件时 resolve（error 也 resolve，不 reject）；
+ * - `end()` 前没有终止事件属于实现缺陷：补一个 error 事件兜底，消费者不会永远挂起。
+ */
+import type { AssistantEvent, AssistantEventStream, AssistantMessage } from "./types.js";
+export declare class AssistantEventStreamImpl implements AssistantEventStream {
+    private readonly queue;
+    private readonly waiters;
+    private finished;
+    private closed;
+    private lastPartial;
+    private resolveResult;
+    private readonly resultPromise;
+    constructor();
+    /** 最近一个事件携带的部分消息。 */
+    get partial(): AssistantMessage | undefined;
+    /** 已经推过终止事件。 */
+    get isFinished(): boolean;
+    push(event: AssistantEvent): void;
+    /** 结束流；若还没有终止事件，补一个 error。 */
+    end(fallback?: AssistantMessage): void;
+    result(): Promise<AssistantMessage>;
+    [Symbol.asyncIterator](): AsyncIterator<AssistantEvent>;
+    private close;
+}
+/** 把一个异步生产函数包成事件流；生产函数抛出的异常编码为 error 事件（流函数不抛错）。 */
+export declare function runEventStream(initial: () => AssistantMessage, produce: (stream: AssistantEventStreamImpl) => Promise<void>): AssistantEventStreamImpl;
+/** 读完一个事件流，返回全部事件（测试与非流式调用用）。 */
+export declare function collectEvents(stream: AsyncIterable<AssistantEvent>): Promise<AssistantEvent[]>;

package/dist/ai/event-stream.js

@@ -0,0 +1,101 @@
+/**
+ * 助手事件流（设计 §3.1）：生产者 push 事件，消费者 `for await` 读取，`result()` 拿最终消息。
+ *
+ * 不变量（由本类守住，协议实现不必各自防御）：
+ * - 终止事件（done / error）之后的 push 一律丢弃，只会有**一个**终止事件；
+ * - `result()` 在终止事件时 resolve（error 也 resolve，不 reject）；
+ * - `end()` 前没有终止事件属于实现缺陷：补一个 error 事件兜底，消费者不会永远挂起。
+ */
+export class AssistantEventStreamImpl {
+    queue = [];
+    waiters = [];
+    finished = false;
+    closed = false;
+    lastPartial;
+    resolveResult;
+    resultPromise;
+    constructor() {
+        this.resultPromise = new Promise((resolve) => {
+            this.resolveResult = resolve;
+        });
+    }
+    /** 最近一个事件携带的部分消息。 */
+    get partial() {
+        return this.lastPartial;
+    }
+    /** 已经推过终止事件。 */
+    get isFinished() {
+        return this.finished;
+    }
+    push(event) {
+        if (this.finished || this.closed)
+            return;
+        if ("partial" in event)
+            this.lastPartial = event.partial;
+        if (event.type === "done" || event.type === "error") {
+            this.finished = true;
+            this.resolveResult(event.message);
+        }
+        const waiter = this.waiters.shift();
+        if (waiter)
+            waiter({ value: event, done: false });
+        else
+            this.queue.push(event);
+        if (this.finished)
+            this.close();
+    }
+    /** 结束流；若还没有终止事件，补一个 error。 */
+    end(fallback) {
+        if (!this.finished) {
+            const message = fallback ?? this.lastPartial;
+            if (message) {
+                message.stopReason = "error";
+                message.errorMessage ??= "Stream ended without a terminal event";
+                this.push({ type: "error", reason: "error", message });
+            }
+        }
+        this.close();
+    }
+    result() {
+        return this.resultPromise;
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                const value = this.queue.shift();
+                if (value)
+                    return Promise.resolve({ value, done: false });
+                if (this.closed)
+                    return Promise.resolve({ value: undefined, done: true });
+                return new Promise((resolve) => this.waiters.push(resolve));
+            },
+            return: () => Promise.resolve({ value: undefined, done: true }),
+        };
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const waiter of this.waiters.splice(0))
+            waiter({ value: undefined, done: true });
+    }
+}
+/** 把一个异步生产函数包成事件流；生产函数抛出的异常编码为 error 事件（流函数不抛错）。 */
+export function runEventStream(initial, produce) {
+    const stream = new AssistantEventStreamImpl();
+    void produce(stream).then(() => stream.end(), (error) => {
+        const message = stream.partial ?? initial();
+        message.stopReason = "error";
+        message.errorMessage = error instanceof Error ? error.message : String(error);
+        stream.push({ type: "error", reason: "error", message });
+        stream.end();
+    });
+    return stream;
+}
+/** 读完一个事件流，返回全部事件（测试与非流式调用用）。 */
+export async function collectEvents(stream) {
+    const events = [];
+    for await (const event of stream)
+        events.push(event);
+    return events;
+}

package/dist/ai/fake/fake-provider.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 脚本化供应商（设计 D16、§15）：供应商 id `fake`、协议 id `fake`，模型 `fake/echo`、
+ * `fake/reasoning`。无脚本时回显最后一条用户消息；有脚本时第 n 次调用（跨模型计数）按
+ * `responses[n]` 产出文本 / 思考 / 工具调用 / 429 / 溢出 / 断流 / 延迟。
+ *
+ * 事件形状与真实协议完全一致（同一个 BlockTracker），契约测试对两条协议与 fake 跑同一套断言。
+ *
+ * 用法：
+ * - 测试：`const fake = new FakeProvider([...])`，把 `fake.api` 注册进 ApiRegistry（或直接
+ *   `fake.api.stream(...)`），`fake.calls` 记录每次调用的上下文与选项；
+ * - CLI：`--provider fake`；`AMA_FAKE_SCRIPT=<path.json>` 指定脚本（首次调用时读取）。
+ * - 录制（第三波 §2.4，bundle 级缓存测试）：`AMA_FAKE_RECORD=<file>` 时每次请求向文件追加一行
+ *   JSON `{ index, purpose, model, system, tools, messagesCount }`——`system` 是折叠后的系统提示
+ *   原文，`tools` 是发给供应商的工具表（按注册顺序），与真实协议请求体的前缀同口径。
+ */
+import type { ApiImplementation, AssistantEventStream, Model, ProviderData, StreamOptions, TranscriptContext } from "../types.js";
+import { type FakeResponse, type FakeScript } from "./fake-script.js";
+export declare const FAKE_PROVIDER_ID = "fake";
+export declare const FAKE_API_ID = "fake";
+export declare const FAKE_SCRIPT_ENV = "AMA_FAKE_SCRIPT";
+export declare const FAKE_RECORD_ENV = "AMA_FAKE_RECORD";
+/** `AMA_FAKE_RECORD` 文件的一行。 */
+export interface FakeRecordLine {
+    index: number;
+    purpose: string;
+    model: string;
+    system: string;
+    tools: unknown[];
+    messagesCount: number;
+}
+export interface FakeProviderOptions {
+    /** 录制文件路径（每次请求取一次；undefined = 不录）。 */
+    recordFile?: string | (() => string | undefined);
+}
+export declare const FAKE_MODELS: readonly Model[];
+export declare function fakeProviderData(): ProviderData;
+export interface FakeCall {
+    /** 从 0 开始。 */
+    index: number;
+    model: Model;
+    context: TranscriptContext;
+    options: Omit<StreamOptions, "signal" | "onPayload" | "onResponse">;
+}
+export declare class FakeProvider {
+    readonly calls: FakeCall[];
+    private script;
+    private readonly scriptLoader;
+    private loaded;
+    private readonly recordFile;
+    constructor(script?: FakeScript | FakeResponse[] | (() => FakeScript | undefined), options?: FakeProviderOptions);
+    readonly api: ApiImplementation;
+    get callCount(): number;
+    setScript(script: FakeScript | FakeResponse[]): void;
+    append(...responses: FakeResponse[]): void;
+    reset(): void;
+    private ensureLoaded;
+    /** 第 index 次调用的响应；undefined = 回显。 */
+    private responseFor;
+    stream(model: Model, context: TranscriptContext, options: StreamOptions): AssistantEventStream;
+    /** 录制一行；写失败不影响请求（测试会因缺行而失败）。 */
+    private record;
+    private run;
+    /** 产出一步，返回产出的文本（估算 output token 用）。 */
+    private emitStep;
+}
+/** 进程级缺省实例（`--provider fake`）：脚本来自 AMA_FAKE_SCRIPT，录制到 AMA_FAKE_RECORD。 */
+export declare const defaultFakeProvider: FakeProvider;
+export declare const fakeApi: ApiImplementation;