@armadra/agent 0.0.0-stage → 0.2.1

package/dist/ai/apis/openai-responses.js

@@ -0,0 +1,303 @@
+/**
+ * openai-responses 协议（设计 §3.1）：POST `{baseUrl}/responses`（stream），`event: response.*` →
+ * 事件；没有 `[DONE]`，以 `response.completed / incomplete / failed` 结束。
+ *
+ * - 每个 output item 一个内容块（按 `output_index` 对应，缺省时按 item id）：reasoning → 思考、
+ *   message → 文本、function_call → 工具调用；`output_item.done` 关块并记签名：reasoning 记完整
+ *   item（含 `encrypted_content`，供无状态回放），message 记 id / phase，function_call 记 `fc_` id；
+ * - 思考文本来自 `reasoning_summary_text.delta`（多段 summary 之间空一行）或
+ *   `reasoning_text.delta`；增量缺失而 done 里有全文时补齐；
+ * - `function_call_arguments.done` 与已拼接的增量不一致时以前缀补齐；
+ * - 停止：completed → stop（有工具调用则 toolUse）；incomplete + max_output_tokens → length，其它
+ *   incomplete 原因 → error；failed / `error` 事件 → error（`code: message`）；无终止事件 → 断流；
+ * - usage：input = input_tokens − input_tokens_details.cached_tokens，reasoning =
+ *   output_tokens_details.reasoning_tokens（已含在 output_tokens 里）；cached_tokens 出现（含 0）即
+ *   `cacheReported: true`。
+ */
+import { AssistantEventStreamImpl } from "../event-stream.js";
+import { USER_AGENT, authHeaders, describeErrorJson, joinUrl, mergeHeaders } from "../http.js";
+import { readSseEvents } from "../sse.js";
+import { affinityHeaders, postWithCacheFallback, resolveCacheRetention } from "./cache-params.js";
+import { buildResponsesRequest, detectResponsesCompat, encodeMessageSignature, } from "./openai-responses-request.js";
+import { BlockTracker, ProviderStopError, STREAM_ENDED_MESSAGE, createOutput, finishDone, finishError, requireApiKey, } from "./shared.js";
+function num(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function obj(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function str(value) {
+    return typeof value === "string" ? value : undefined;
+}
+export function parseResponsesUsage(raw) {
+    const input = num(raw["input_tokens"]) ?? 0;
+    const cached = num(obj(raw["input_tokens_details"])?.["cached_tokens"]);
+    const cacheRead = cached ?? 0;
+    const usage = {
+        input: Math.max(0, input - cacheRead),
+        output: num(raw["output_tokens"]) ?? 0,
+        cacheRead,
+        cacheWrite: 0,
+        totalTokens: 0,
+        cacheReported: cached !== undefined,
+    };
+    const reasoning = num(obj(raw["output_tokens_details"])?.["reasoning_tokens"]);
+    if (reasoning !== undefined)
+        usage.reasoning = reasoning;
+    return usage;
+}
+export function mapResponsesStatus(status, incomplete) {
+    if (status === "incomplete") {
+        if (incomplete === "max_output_tokens")
+            return { reason: "length" };
+        return {
+            reason: "error",
+            message: incomplete ? `Response incomplete: ${incomplete}` : "Response incomplete",
+        };
+    }
+    if (status === "failed" || status === "cancelled") {
+        return { reason: "error", message: `Response ${status}` };
+    }
+    return { reason: "stop" };
+}
+function appendArgs(state, tracker, index, delta) {
+    if (delta.length === 0)
+        return;
+    state.args.set(index, (state.args.get(index) ?? "") + delta);
+    tracker.appendToolArgs(index, delta);
+}
+/** done 给出的全文与已拼接的增量对齐：是前缀则补尾巴，尚无增量则整段补上。 */
+function reconcileArgs(state, tracker, index, full) {
+    const sofar = state.args.get(index) ?? "";
+    if (full.startsWith(sofar))
+        appendArgs(state, tracker, index, full.slice(sofar.length));
+}
+function slotOf(state, data, kind) {
+    const outputIndex = num(data["output_index"]);
+    const itemId = str(data["item_id"]) ?? str(obj(data["item"])?.["id"]);
+    const slot = (outputIndex !== undefined ? state.byOutput.get(outputIndex) : undefined) ??
+        (itemId !== undefined ? state.byItem.get(itemId) : undefined);
+    return slot?.kind === kind ? slot : undefined;
+}
+function openSlot(state, data, tracker) {
+    const item = obj(data["item"]);
+    const type = str(item?.["type"]);
+    let slot;
+    if (type === "reasoning")
+        slot = { index: tracker.startThinking(), kind: "thinking" };
+    else if (type === "message")
+        slot = { index: tracker.startText(), kind: "text" };
+    else if (type === "function_call") {
+        const callId = str(item?.["call_id"]) || str(item?.["id"]) || `call_${state.byOutput.size}`;
+        const index = tracker.startToolCall(callId, str(item?.["name"]) ?? "");
+        const block = tracker.toolCallBlock(index);
+        const itemId = str(item?.["id"]);
+        if (block && itemId)
+            block.thoughtSignature = itemId;
+        slot = { index, kind: "toolCall" };
+        appendArgs(state, tracker, index, str(item?.["arguments"]) ?? "");
+    }
+    if (!slot)
+        return undefined;
+    const outputIndex = num(data["output_index"]);
+    if (outputIndex !== undefined)
+        state.byOutput.set(outputIndex, slot);
+    const itemId = str(item?.["id"]);
+    if (itemId)
+        state.byItem.set(itemId, slot);
+    return slot;
+}
+function texts(value, field) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map((part) => str(obj(part)?.[field]) ?? "").filter((t) => t.length > 0);
+}
+function closeSlot(state, data, tracker) {
+    const item = obj(data["item"]) ?? {};
+    const type = str(item["type"]);
+    const kind = type === "reasoning" ? "thinking" : type === "message" ? "text" : "toolCall";
+    if (type !== "reasoning" && type !== "message" && type !== "function_call")
+        return;
+    const slot = slotOf(state, data, kind) ?? openSlot(state, data, tracker);
+    if (!slot || !tracker.isOpen(slot.index))
+        return;
+    const block = tracker.output.content[slot.index];
+    if (type === "reasoning" && block?.type === "thinking") {
+        if (block.thinking.length === 0) {
+            const full = texts(item["summary"], "text");
+            const raw = full.length > 0 ? full : texts(item["content"], "text");
+            tracker.appendThinking(slot.index, raw.join("\n\n"));
+        }
+        block.thinkingSignature = JSON.stringify(item);
+    }
+    else if (type === "message" && block?.type === "text") {
+        if (block.text.length === 0) {
+            const parts = Array.isArray(item["content"]) ? item["content"] : [];
+            const full = parts.map((p) => str(obj(p)?.["text"]) ?? str(obj(p)?.["refusal"]) ?? "");
+            tracker.appendText(slot.index, full.join(""));
+        }
+        const id = str(item["id"]);
+        if (id)
+            block.textSignature = encodeMessageSignature(id, str(item["phase"]));
+    }
+    else if (type === "function_call" && block?.type === "toolCall") {
+        const args = str(item["arguments"]);
+        if (args !== undefined)
+            reconcileArgs(state, tracker, slot.index, args);
+    }
+    tracker.end(slot.index);
+}
+/** 处理一个事件；返回 true 表示已到终止事件。 */
+function handleEvent(data, state, tracker) {
+    const output = tracker.output;
+    const type = str(data["type"]);
+    switch (type) {
+        case "response.created":
+        case "response.in_progress": {
+            const id = str(obj(data["response"])?.["id"]);
+            if (id && !output.responseId)
+                output.responseId = id;
+            return false;
+        }
+        case "response.output_item.added":
+            openSlot(state, data, tracker);
+            return false;
+        case "response.reasoning_summary_part.added": {
+            const slot = slotOf(state, data, "thinking");
+            const block = slot ? output.content[slot.index] : undefined;
+            if (slot && (num(data["summary_index"]) ?? 0) > 0 && block?.type === "thinking") {
+                if (block.thinking.length > 0)
+                    tracker.appendThinking(slot.index, "\n\n");
+            }
+            return false;
+        }
+        case "response.reasoning_summary_text.delta":
+        case "response.reasoning_text.delta": {
+            const slot = slotOf(state, data, "thinking");
+            if (slot)
+                tracker.appendThinking(slot.index, str(data["delta"]) ?? "");
+            return false;
+        }
+        case "response.output_text.delta":
+        case "response.refusal.delta": {
+            const slot = slotOf(state, data, "text");
+            if (slot)
+                tracker.appendText(slot.index, str(data["delta"]) ?? "");
+            return false;
+        }
+        case "response.function_call_arguments.delta": {
+            const slot = slotOf(state, data, "toolCall");
+            if (slot)
+                appendArgs(state, tracker, slot.index, str(data["delta"]) ?? "");
+            return false;
+        }
+        case "response.function_call_arguments.done": {
+            const slot = slotOf(state, data, "toolCall");
+            const full = str(data["arguments"]);
+            if (slot && full !== undefined)
+                reconcileArgs(state, tracker, slot.index, full);
+            return false;
+        }
+        case "response.output_item.done":
+            closeSlot(state, data, tracker);
+            return false;
+        case "response.completed":
+        case "response.incomplete":
+        case "response.failed": {
+            const response = obj(data["response"]) ?? {};
+            const id = str(response["id"]);
+            if (id)
+                output.responseId = id;
+            const usage = obj(response["usage"]);
+            if (usage)
+                output.usage = parseResponsesUsage(usage);
+            const status = str(response["status"]) ?? type.slice("response.".length);
+            const reason = str(obj(response["incomplete_details"])?.["reason"]);
+            output.rawStopReason = reason ?? status;
+            if (type === "response.failed") {
+                const error = obj(response["error"]);
+                throw new Error((error ? describeErrorJson({ error }) : undefined) ??
+                    (reason ? `Response failed: ${reason}` : "Response failed"));
+            }
+            state.stop = mapResponsesStatus(status, reason);
+            return true;
+        }
+        case "error":
+            throw new Error(describeErrorJson(data) ?? JSON.stringify(data));
+        default:
+            return false;
+    }
+}
+function buildHeaders(model, options) {
+    return mergeHeaders({ "content-type": "application/json", accept: "text/event-stream", "user-agent": USER_AGENT }, authHeaders(options.apiKey, model.authHeader, "authorization-bearer"), affinityHeaders(model, "openai-responses", options.sessionId, resolveCacheRetention(options.cacheRetention)), model.headers, options.headers);
+}
+async function run(stream, model, context, options) {
+    const tracker = new BlockTracker(stream, createOutput(model));
+    try {
+        const request = buildResponsesRequest(model, context, options);
+        tracker.output.thinkingLevel = request.thinkingLevel;
+        if (request.providerThinkingLevel !== undefined) {
+            tracker.output.providerThinkingLevel = request.providerThinkingLevel;
+        }
+        const replaced = options.onPayload?.(request.body);
+        const baseUrl = model.baseUrl ?? "https://api.openai.com/v1";
+        const response = await postWithCacheFallback(model, joinUrl(baseUrl, "/responses"), {
+            headers: buildHeaders(model, options),
+            body: replaced === undefined ? request.body : replaced,
+            signal: options.signal,
+            timeoutMs: options.timeoutMs,
+            onResponse: options.onResponse,
+        });
+        stream.push({ type: "start", partial: tracker.output });
+        const state = {
+            byOutput: new Map(),
+            byItem: new Map(),
+            args: new Map(),
+            stop: undefined,
+        };
+        let finished = false;
+        const body = response.body;
+        for await (const sse of readSseEvents(body, options.signal)) {
+            const raw = sse.data.trim();
+            if (raw === "" || raw === "[DONE]")
+                continue;
+            let data;
+            try {
+                data = obj(JSON.parse(raw)) ?? {};
+            }
+            catch {
+                throw new Error(`Malformed SSE data (${sse.event ?? "message"}): ${raw.slice(0, 200)}`);
+            }
+            if (data["type"] === undefined && sse.event)
+                data["type"] = sse.event;
+            if (handleEvent(data, state, tracker)) {
+                finished = true;
+                break;
+            }
+        }
+        if (options.signal.aborted)
+            throw new Error("aborted");
+        if (!finished || !state.stop)
+            throw new Error(STREAM_ENDED_MESSAGE);
+        if (state.stop.reason === "error")
+            throw new ProviderStopError(state.stop.message);
+        const reason = state.stop.reason === "stop" && tracker.hasToolCalls ? "toolUse" : state.stop.reason;
+        finishDone(stream, tracker, model, reason);
+    }
+    catch (error) {
+        finishError(stream, tracker, model, error, options.signal);
+    }
+}
+function stream(model, context, options) {
+    requireApiKey(model, options);
+    const events = new AssistantEventStreamImpl();
+    void run(events, model, context, options).finally(() => events.end());
+    return events;
+}
+export const openAIResponsesApi = {
+    id: "openai-responses",
+    stream,
+    detectCompat: detectResponsesCompat,
+};

package/dist/ai/apis/shared.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 协议实现共用的流辅助：输出消息骨架、key 预检、内容块跟踪（保证块事件配对）、终止处理。
+ *
+ * 块事件规则（两条协议与 fake 一致，契约测试逐条断言）：
+ * - 每个 `*_start` 恰好对应一个 `*_end`；终止事件之前所有打开的块都会被关闭（出错 / 中止时也
+ *   先关块再发 error，消费者不必处理悬空块）；
+ * - `toolcall_end` 时 `toolCall.arguments` 一定是对象（容错解析，坏 JSON 退化为 `{}`）；
+ * - 流式期间 `arguments` 随增量更新为「到目前为止」的部分对象。
+ */
+import type { AssistantEventStreamImpl } from "../event-stream.js";
+import type { AssistantMessage, Model, StreamOptions, TextBlock, ThinkingBlock, ToolCallBlock } from "../types.js";
+export declare function createOutput(model: Model): AssistantMessage;
+/** 缺 key 时同步抛 `AmaError{code:"no_api_key"}`（§3.1 流契约唯一的同步异常）。 */
+export declare function requireApiKey(model: Model, options: StreamOptions): void;
+type OpenBlock = {
+    kind: "text";
+    block: TextBlock;
+} | {
+    kind: "thinking";
+    block: ThinkingBlock;
+} | {
+    kind: "toolCall";
+    block: ToolCallBlock;
+    json: string;
+};
+export declare class BlockTracker {
+    private readonly stream;
+    readonly output: AssistantMessage;
+    private readonly open;
+    constructor(stream: AssistantEventStreamImpl, output: AssistantMessage);
+    isOpen(index: number): boolean;
+    kindOf(index: number): OpenBlock["kind"] | undefined;
+    startText(text?: string): number;
+    appendText(index: number, delta: string): void;
+    startThinking(thinking?: string, signature?: string, redacted?: boolean): number;
+    appendThinking(index: number, delta: string): void;
+    appendSignature(index: number, delta: string): void;
+    startToolCall(id: string, name: string, initialArgs?: Record<string, unknown>): number;
+    appendToolArgs(index: number, delta: string): void;
+    toolCallBlock(index: number): ToolCallBlock | undefined;
+    end(index: number): void;
+    endAll(): void;
+    get hasToolCalls(): boolean;
+    private push;
+}
+export declare const ABORTED_MESSAGE = "Request was aborted";
+export declare const STREAM_ENDED_MESSAGE = "Stream ended before completion";
+/** 正常结束：关块、算 usage / cost、发 done。 */
+export declare function finishDone(stream: AssistantEventStreamImpl, tracker: BlockTracker, model: Model, reason: "stop" | "length" | "toolUse"): void;
+/** 出错或中止：关块、写 errorMessage、发 error（signal 已中止 → aborted）。 */
+export declare function finishError(stream: AssistantEventStreamImpl, tracker: BlockTracker, model: Model, error: unknown, signal: AbortSignal): void;
+/** 内部用：可携带供应商原始 stop reason 的错误（content_filter、refusal 等）。 */
+export declare class ProviderStopError extends Error {
+    constructor(message: string);
+}
+export {};

package/dist/ai/apis/shared.js

@@ -0,0 +1,179 @@
+/**
+ * 协议实现共用的流辅助：输出消息骨架、key 预检、内容块跟踪（保证块事件配对）、终止处理。
+ *
+ * 块事件规则（两条协议与 fake 一致，契约测试逐条断言）：
+ * - 每个 `*_start` 恰好对应一个 `*_end`；终止事件之前所有打开的块都会被关闭（出错 / 中止时也
+ *   先关块再发 error，消费者不必处理悬空块）；
+ * - `toolcall_end` 时 `toolCall.arguments` 一定是对象（容错解析，坏 JSON 退化为 `{}`）；
+ * - 流式期间 `arguments` 随增量更新为「到目前为止」的部分对象。
+ */
+import { AmaError } from "../../errors.js";
+import { finalizeUsage, emptyUsage } from "../cost.js";
+import { errorText, hasAuthHeader } from "../http.js";
+import { parseToolArguments } from "../json-partial.js";
+export function createOutput(model) {
+    return {
+        role: "assistant",
+        content: [],
+        api: model.api,
+        provider: model.provider,
+        model: model.id,
+        usage: emptyUsage(),
+        stopReason: "stop",
+        timestamp: Date.now(),
+    };
+}
+/** 缺 key 时同步抛 `AmaError{code:"no_api_key"}`（§3.1 流契约唯一的同步异常）。 */
+export function requireApiKey(model, options) {
+    if (options.apiKey)
+        return;
+    if (model.requiresApiKey === false)
+        return;
+    if (hasAuthHeader(model.headers) || hasAuthHeader(options.headers))
+        return;
+    throw new AmaError("no_api_key", `No API key for provider "${model.provider}"`, {
+        detail: { provider: model.provider, model: model.id },
+    });
+}
+export class BlockTracker {
+    stream;
+    output;
+    open = new Map();
+    constructor(stream, output) {
+        this.stream = stream;
+        this.output = output;
+    }
+    isOpen(index) {
+        return this.open.has(index);
+    }
+    kindOf(index) {
+        return this.open.get(index)?.kind;
+    }
+    startText(text = "") {
+        const block = { type: "text", text: "" };
+        const index = this.push(block);
+        this.open.set(index, { kind: "text", block });
+        this.stream.push({ type: "text_start", contentIndex: index, partial: this.output });
+        if (text)
+            this.appendText(index, text);
+        return index;
+    }
+    appendText(index, delta) {
+        const entry = this.open.get(index);
+        if (entry?.kind !== "text" || delta.length === 0)
+            return;
+        entry.block.text += delta;
+        this.stream.push({ type: "text_delta", contentIndex: index, delta, partial: this.output });
+    }
+    startThinking(thinking = "", signature, redacted = false) {
+        const block = { type: "thinking", thinking: "" };
+        if (signature !== undefined)
+            block.thinkingSignature = signature;
+        if (redacted)
+            block.redacted = true;
+        const index = this.push(block);
+        this.open.set(index, { kind: "thinking", block });
+        this.stream.push({ type: "thinking_start", contentIndex: index, partial: this.output });
+        if (thinking)
+            this.appendThinking(index, thinking);
+        return index;
+    }
+    appendThinking(index, delta) {
+        const entry = this.open.get(index);
+        if (entry?.kind !== "thinking" || delta.length === 0)
+            return;
+        entry.block.thinking += delta;
+        this.stream.push({ type: "thinking_delta", contentIndex: index, delta, partial: this.output });
+    }
+    appendSignature(index, delta) {
+        const entry = this.open.get(index);
+        if (entry?.kind !== "thinking")
+            return;
+        entry.block.thinkingSignature = (entry.block.thinkingSignature ?? "") + delta;
+    }
+    startToolCall(id, name, initialArgs) {
+        const block = { type: "toolCall", id, name, arguments: initialArgs ?? {} };
+        const index = this.push(block);
+        this.open.set(index, { kind: "toolCall", block, json: "" });
+        this.stream.push({
+            type: "toolcall_start",
+            contentIndex: index,
+            id,
+            name,
+            partial: this.output,
+        });
+        return index;
+    }
+    appendToolArgs(index, delta) {
+        const entry = this.open.get(index);
+        if (entry?.kind !== "toolCall" || delta.length === 0)
+            return;
+        entry.json += delta;
+        entry.block.arguments = parseToolArguments(entry.json);
+        this.stream.push({ type: "toolcall_delta", contentIndex: index, delta, partial: this.output });
+    }
+    toolCallBlock(index) {
+        const entry = this.open.get(index);
+        return entry?.kind === "toolCall" ? entry.block : undefined;
+    }
+    end(index) {
+        const entry = this.open.get(index);
+        if (!entry)
+            return;
+        this.open.delete(index);
+        if (entry.kind === "text") {
+            this.stream.push({ type: "text_end", contentIndex: index, partial: this.output });
+        }
+        else if (entry.kind === "thinking") {
+            this.stream.push({ type: "thinking_end", contentIndex: index, partial: this.output });
+        }
+        else {
+            if (entry.json.length > 0)
+                entry.block.arguments = parseToolArguments(entry.json);
+            this.stream.push({
+                type: "toolcall_end",
+                contentIndex: index,
+                toolCall: entry.block,
+                partial: this.output,
+            });
+        }
+    }
+    endAll() {
+        for (const index of [...this.open.keys()].sort((a, b) => a - b))
+            this.end(index);
+    }
+    get hasToolCalls() {
+        return this.output.content.some((block) => block.type === "toolCall");
+    }
+    push(block) {
+        this.output.content.push(block);
+        return this.output.content.length - 1;
+    }
+}
+export const ABORTED_MESSAGE = "Request was aborted";
+export const STREAM_ENDED_MESSAGE = "Stream ended before completion";
+/** 正常结束：关块、算 usage / cost、发 done。 */
+export function finishDone(stream, tracker, model, reason) {
+    tracker.endAll();
+    const output = tracker.output;
+    output.stopReason = reason;
+    finalizeUsage(model, output.usage);
+    stream.push({ type: "done", reason, message: output });
+}
+/** 出错或中止：关块、写 errorMessage、发 error（signal 已中止 → aborted）。 */
+export function finishError(stream, tracker, model, error, signal) {
+    tracker.endAll();
+    const output = tracker.output;
+    const aborted = signal.aborted;
+    output.stopReason = aborted ? "aborted" : "error";
+    output.errorMessage = aborted ? ABORTED_MESSAGE : errorText(error);
+    finalizeUsage(model, output.usage);
+    stream.push({ type: "error", reason: aborted ? "aborted" : "error", message: output });
+}
+/** 内部用：可携带供应商原始 stop reason 的错误（content_filter、refusal 等）。 */
+export class ProviderStopError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ProviderStopError";
+    }
+}

package/dist/ai/cache/economics.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 保温经济性（第三波 §1.7「经济性」）。[W3-C1b]
+ *
+ * P = 上一次真实请求的 input + cacheRead + cacheWrite：
+ * - `hitCost = price({cacheRead: P})`
+ * - `missCost = price(cacheWrite 价 > 0 ? {cacheWrite: P} : {input: P}) − hitCost`
+ * - `warmCost = price({cacheRead: P, output: 1})`
+ * - 概率 p：streaming 1、idle 0.15；`p·missCost − warmCost ≥ minSavingsUsd` 才发。
+ * 无价格或价格全为 0 → 「经济性不可算」，不发（reason `no_price`）。
+ *
+ * 计价用 `src/ai/cost.ts` 的 `priceTokens`（与 calculateCost 同一套阶梯与 1h 写入规则）。
+ */
+import { priceTokens } from "../cost.js";
+import type { Model } from "../types.js";
+import type { WarmDecision, WarmingPhase } from "./types.js";
+export declare const WARM_PROBABILITY: Readonly<Record<WarmingPhase, number>>;
+export { priceTokens };
+export declare function evaluateWarm(model: Pick<Model, "cost">, promptTokens: number, phase: WarmingPhase, minSavingsUsd: number): WarmDecision;
+/** 期望节省（美元）；不可算时 undefined。 */
+export declare function expectedSavings(decision: WarmDecision): number | undefined;
+/**
+ * 盈亏点：前缀至少多少 token 保温才划算（不计阶梯价）。永不划算或超过上下文窗口 → undefined。
+ */
+export declare function warmBreakEven(model: Pick<Model, "cost" | "contextWindow">, phase: WarmingPhase, minSavingsUsd: number): number | undefined;

package/dist/ai/cache/economics.js

@@ -0,0 +1,69 @@
+/**
+ * 保温经济性（第三波 §1.7「经济性」）。[W3-C1b]
+ *
+ * P = 上一次真实请求的 input + cacheRead + cacheWrite：
+ * - `hitCost = price({cacheRead: P})`
+ * - `missCost = price(cacheWrite 价 > 0 ? {cacheWrite: P} : {input: P}) − hitCost`
+ * - `warmCost = price({cacheRead: P, output: 1})`
+ * - 概率 p：streaming 1、idle 0.15；`p·missCost − warmCost ≥ minSavingsUsd` 才发。
+ * 无价格或价格全为 0 → 「经济性不可算」，不发（reason `no_price`）。
+ *
+ * 计价用 `src/ai/cost.ts` 的 `priceTokens`（与 calculateCost 同一套阶梯与 1h 写入规则）。
+ */
+import { priceTokens } from "../cost.js";
+export const WARM_PROBABILITY = {
+    streaming: 1,
+    idle: 0.15,
+};
+export { priceTokens };
+function priced(model) {
+    const cost = model.cost;
+    return cost !== undefined && (cost.input > 0 || cost.cacheWrite > 0);
+}
+export function evaluateWarm(model, promptTokens, phase, minSavingsUsd) {
+    const probability = WARM_PROBABILITY[phase];
+    const decision = {
+        action: "stop",
+        phase,
+        promptTokens,
+        warmCost: undefined,
+        missCost: undefined,
+        probability,
+    };
+    if (!priced(model)) {
+        decision.reason = "no_price";
+        return decision;
+    }
+    const P = promptTokens;
+    const writes = (model.cost?.cacheWrite ?? 0) > 0;
+    const hit = priceTokens(model, { cacheRead: P }) ?? 0;
+    const full = priceTokens(model, writes ? { cacheWrite: P } : { input: P }) ?? 0;
+    decision.missCost = full - hit;
+    decision.warmCost = priceTokens(model, { cacheRead: P, output: 1 }) ?? 0;
+    if (probability * decision.missCost - decision.warmCost >= minSavingsUsd)
+        decision.action = "warm";
+    else
+        decision.reason = "below_min_savings";
+    return decision;
+}
+/** 期望节省（美元）；不可算时 undefined。 */
+export function expectedSavings(decision) {
+    if (decision.missCost === undefined || decision.warmCost === undefined)
+        return undefined;
+    return decision.probability * decision.missCost - decision.warmCost;
+}
+/**
+ * 盈亏点：前缀至少多少 token 保温才划算（不计阶梯价）。永不划算或超过上下文窗口 → undefined。
+ */
+export function warmBreakEven(model, phase, minSavingsUsd) {
+    const cost = model.cost;
+    if (cost === undefined || !priced(model))
+        return undefined;
+    const p = WARM_PROBABILITY[phase];
+    const full = cost.cacheWrite > 0 ? cost.cacheWrite : cost.input;
+    const perToken = (p * (full - cost.cacheRead) - cost.cacheRead) / 1e6;
+    if (perToken <= 0)
+        return undefined;
+    const tokens = Math.ceil((minSavingsUsd + cost.output / 1e6) / perToken);
+    return model.contextWindow !== undefined && tokens > model.contextWindow ? undefined : tokens;
+}

package/dist/ai/cache/fingerprint.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 前缀指纹（第三波 §1.2）：一次请求的「可缓存前缀」= 折叠后的系统提示 + 工具表 + 模型。[W3-C1b]
+ *
+ * - `system` = sha256(normalizeContext().systemPrompt) 前 64 bit；
+ * - `tools` = sha256(JSON.stringify(工具表按名排序)) 前 64 bit；
+ * - `model` = `${provider}/${id}` 原文。
+ * 纯函数、零请求；每次真实请求算一次（system + tools 通常 < 20 KB）。未命中归因时与上一条
+ * 记录比对，说出「变了什么」。
+ */
+import type { Model, ModelRef, TranscriptContext } from "../types.js";
+import type { PrefixFingerprint } from "./types.js";
+/** sha256 的前 16 位 hex（64 bit）。 */
+export declare function hash16(text: string): string;
+export declare function modelKey(model: Pick<Model, "provider" | "id"> | ModelRef): string;
+export declare function fingerprintContext(context: TranscriptContext, model: Pick<Model, "provider" | "id">): PrefixFingerprint;
+/** 两个指纹的差异（按归因顺序：system → tools → model）；相同返回 undefined。 */
+export declare function fingerprintChange(prev: PrefixFingerprint, cur: PrefixFingerprint): "system" | "tools" | "model" | undefined;