@plumeai/plugin-sdk 0.0.0-stage → 0.1.2

package/dist/contract/src/usage.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 使用统计（插件经 `ctx.model.usage()` 读）和存储页从 agent 进程拿到的数据。
+ */
+/**
+ * 一小时里、一个供应商的一个模型发出的那些调用，合在一起。页面按它切区间、筛选、拆成柱，逐条的流水不出 agent 进程。
+ * 来自会话库的花销表：删掉会话不影响这些数。
+ */
+export interface UsageRequestBucket {
+    /** `YYYY-MM-DD HH`，本地时间。 */
+    hour: string;
+    /** 供应商 id。 */
+    provider: string;
+    model: string;
+    requests: number;
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    /** 按调用当时记下的价格算的美元。 */
+    cost: number;
+    /** 查不到价的请求数：页面上的费用因此只能写「≥」。 */
+    unpriced: number;
+    /** 量得出生成速度的请求数，以及它们的输出 token 与生成耗时之和。 */
+    timed: number;
+    timedOutput: number;
+    streamMs: number;
+    /** 量得出首字时间的请求数与总毫秒。 */
+    firstTokens: number;
+    firstTokenMs: number;
+    /** 这些请求计费的 token（输入含缓存读写）按来源分摊，加起来是它们账单上的总数。各部分是估的比例乘实数。 */
+    parts: Record<UsageTokenPart, number>;
+    /** 发这些请求的会话 id，子会话记成它的顶层会话；已经删掉的不在。跨小时、跨模型数会话要去重，所以给 id 不给个数。 */
+    sessions: string[];
+    /** 人发的话（不含界面替人说的），记在它之后的第一次请求上。 */
+    turns: number;
+    /** 有计时的请求数，和它们从发出到收完、其中生成、生成里思考块各占的毫秒。等首字 = modelMs − generateMs。 */
+    timedReplies: number;
+    modelMs: number;
+    generateMs: number;
+    thinkingMs: number;
+    /** 工具调用次数、出错次数和执行毫秒（并行的各算各的），记在调完工具之后的那次请求上。 */
+    tools: number;
+    toolErrors: number;
+    toolMs: number;
+    /** 本该从缓存读到却按全价算的输入。 */
+    cacheMiss: UsageCacheMiss;
+}
+/**
+ * 计费 token 的来源：送进去的八类（系统提示词按段分出项目说明与记忆、技能与智能体，加上工具定义和四类消息）和吐出来的两类。
+ * `injected` 是界面或插件替人说的话（`synthetic` 的用户消息）。
+ */
+export type UsageTokenPart = "system" | "instructions" | "skills" | "toolDefs" | "user" | "injected" | "assistant" | "toolResults" | "outputThinking" | "outputReply";
+/**
+ * 缓存未命中的原因，按同一会话相邻两次请求比出来：工具定义、系统提示词变了；已发出的消息被改写；前缀没变服务商没读到；
+ * 没有前缀记录分不清（重启后的第一次请求）；压缩、撤回之后有意重写；换了模型或服务商。
+ */
+export type UsageCacheMissCause = "tools" | "prompt" | "rewrite" | "provider" | "unknown" | "compaction" | "rewind" | "model";
+export interface UsageCacheMiss {
+    tokens: number;
+    /** 按请求当时记下的费率，这些 token 比按缓存读取多花的美元。 */
+    cost: number;
+    /** 没记费率、算不出多花多少的那部分 token。 */
+    unpriced: number;
+    byCause: Partial<Record<UsageCacheMissCause, number>>;
+}
+export interface UsageScan {
+    requests: UsageRequestBucket[];
+    /** 供应商 id → 现在的名字。花销按 id 记，删掉的供应商不在这里，只剩 id。 */
+    providerNames: Record<string, string>;
+    /** 已归档的顶层会话 id，和 `UsageRequestBucket.sessions` 对着数归档了几个。 */
+    archived: string[];
+}
+/** 一天里最后活动过的那些会话：几条，占多少。 */
+export interface StorageDay {
+    day: string;
+    sessions: number;
+    bytes: number;
+}
+export interface StorageUse {
+    /** 会话记录占的字节数。 */
+    bytes: number;
+    /** 有几条会话。 */
+    sessions: number;
+    /** 最早、最晚那条会话的最后活动日（本地 `YYYY-MM-DD`）。没有会话时都是 null。 */
+    earliest: string | null;
+    latest: string | null;
+    /** 按最后活动日摊开：选了一段日子会删掉什么，按下去之前就算得出来，确认框不会拿总数去问。 */
+    days: StorageDay[];
+}
+/** 要删哪一段，两头都含当天（本地 `YYYY-MM-DD`）；空的那头不设限。 */
+export interface ClearRange {
+    from: string | null;
+    to: string | null;
+}
+export interface ClearResult {
+    /** 删掉了几条会话。 */
+    removed: number;
+    /** 释放了多少字节（按删之前量到的记录大小算）。 */
+    freed: number;
+    /** 正在跑、所以没动的那几条。 */
+    skipped: number;
+}

package/dist/core/llm/ai/anthropic-messages-request.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Our messages, in the shape the Messages API wants.
+ *
+ * A translation and nothing else. Anthropic's shape differs from ours in two ways that matter and
+ * are easy to get wrong: tool results are user-role blocks rather than their own role, and a
+ * thinking block has to be replayed with a `signature` field — though **whether that signature has
+ * to verify depends on the endpoint**, which is why `thinkingReplay` is a parameter and not a
+ * constant. See `thinkingReplay` in `anthropic-messages.ts`.
+ */
+import type { Message, ToolSpec } from "../types.ts";
+/**
+ * One block of content, in the wire shape.
+ *
+ * Open-ended on purpose: the API keeps adding block kinds, and a closed type would mean this file
+ * has to be edited before a new one can be passed through untouched.
+ */
+interface AnthropicBlock {
+    type: string;
+    [key: string]: unknown;
+}
+/** One message in the wire shape. Exported because the caller assembles a request around it. */
+export interface AnthropicMessage {
+    role: "user" | "assistant";
+    content: AnthropicBlock[];
+}
+/**
+ * 无签名的思考块在下一轮请求里的去向。
+ *
+ * 三档，从发得最多到发得最少。**没有一档对所有端点都对**——这正是它是参数的原因，默认值由
+ * `anthropic-messages.ts` 按端点算，撞了再往下走一格。
+ *
+ *   - `"unsigned"`：连没签名的也回放，送 `signature: ""`。非签名端点（DeepSeek / Z.AI / Moonshot
+ *     的 Anthropic 兼容端点）上的推理模型要的是这一档：它们不签名，但要求把推理带回来。
+ *   - `"signed-only"`：只发带签名的，没签名的整块丢掉。官方 `api.anthropic.com` 要的是这一档——它
+ *     会验签，`signature: ""` 过不去。
+ *   - `"none"`：一块都不发。签名是别的部署签的、连剥都救不回来时的最后一格。
+ *
+ * 丢掉而不是降级成文本块，是刻意的：官方 Anthropic 上把推理改写成普通文本会撞上
+ * reasoning_extraction 分类器。
+ */
+export type ThinkingReplay = "unsigned" | "signed-only" | "none";
+export interface AnthropicEncodeOptions {
+    /** 无签名思考块的去向。默认 `"signed-only"`——官方端点的行为，也是这个文件一直以来的行为。 */
+    thinkingReplay?: ThinkingReplay;
+    /** 这个模型收不收图片。默认 `true`。 */
+    supportsImages?: boolean;
+    /**
+     * 在消息尾部滚动几个提示缓存断点。默认 0。
+     *
+     * Anthropic 一个请求总共只给 4 个断点（官方文档：`Max 4 cache_control breakpoints per
+     * request`），system 和工具列表各占一个，所以这里最多 2。
+     */
+    cacheBreakpoints?: number;
+}
+/**
+ * Anthropic requires tool results to arrive as `tool_result` blocks inside a *user* message,
+ * and consecutive results must be merged into one message. Our flat message list has one
+ * entry per result, so this collapses runs of them.
+ *
+ * The merged blocks are put back into the order the calls were made, which is not the order the
+ * results were recorded in: tools run in parallel and each result is written down as it finishes,
+ * so a history rebuilt from the log has the quickest tool first. Anthropic matches by
+ * `tool_use_id` and accepts either, but the request should not differ depending on which tool won
+ * the race — an identical conversation that serialises two ways defeats prompt caching for
+ * everything after it.
+ */
+export declare function toAnthropicMessages(messages: Message[], options?: AnthropicEncodeOptions): AnthropicMessage[];
+/**
+ * Anthropic 收的图片就这四种。
+ *
+ * 不在表里的换成文字，而不是原样透传：`tools/paths.ts` 的 `IMAGE_EXTENSIONS` 里有 `.bmp`，MCP 服务器
+ * 也可以给回任意 mimeType，而**那个 tool_result 一旦进了历史，之后每一轮都带着它**——透传换来的不是
+ * 一次失败，是一个再也说不了话的会话。
+ *
+ * `image/jpg` 是个常见的写法，改成 `image/jpeg` 而不是判死刑。
+ */
+export declare function normalizeImageMediaType(mimeType: string): string | undefined;
+/** 同上，但走遍一个任意深度的值。没有任何一处需要改时，返回的是**原来那个对象**。 */
+export declare function wellFormedDeep(value: unknown): unknown;
+export declare function toAnthropicTools(tools: ToolSpec[]): unknown[];
+export declare function normalizeToolSchema(schema: unknown): unknown;
+export {};

package/dist/core/llm/ai/anthropic-messages.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Anthropic Messages API adapter.
+ *
+ * Maps the neutral message model onto `/v1/messages` with `stream: true`,
+ * including extended thinking and its signature round-trip.
+ */
+import { type ThinkingReplay } from "./anthropic-messages-request.ts";
+import type { ModelConfig, Provider, ProviderConfig, RequestOptions } from "../types.ts";
+export declare const anthropicMessagesProvider: Provider;
+/**
+ * 这个地址上的端点会验思考签名吗。
+ *
+ * 官方那条必须**精确**匹配 origin 或者后面紧跟一个 `/`——前缀匹配会把
+ * `https://api.anthropic.com.evil.com` 当成官方。空地址按官方算：那是配置没填好，而按官方算等于保持
+ * 现状，是两个方向里安全的那个。
+ *
+ * 其余几个是把 Claude 转在自己身份后面、但照样执行 Anthropic 签名协议的网关。
+ */
+export declare function signsThinkingSignatures(baseUrl: string | undefined): boolean;
+/** 这个模型现在该发哪一档。给了会话（`cacheKey`）时，那个会话自己学到的优先。 */
+export declare function thinkingReplay(provider: ProviderConfig, model: ModelConfig, session?: string): ThinkingReplay;
+/**
+ * 「你这个签名我不认」的三种说法——往下走一格。返回「结论变了，值得换个形状重发」。
+ *
+ * 第一条是官方 Anthropic 和挡在它前面的中转的原话（`400 Invalid \`signature\` in \`thinking\` block`）；
+ * 第二条是 Bedrock 系中转的——空串在它那边先过不了 schema 校验，于是报成
+ * `messages.N.content.M.thinking.signature: Field required`。第三条是官方对「最新那条助手消息里的思考块
+ * 和它当初返回的不一样」的原话（`` `thinking` or `redacted_thinking` blocks in the latest assistant message
+ * cannot be modified ``）。
+ *
+ * `[^"\n]{0,32}` 这一段是刻意收紧的：这样它只匹配同一条错误信息里紧挨着的那句，不会跨过一个引号或者
+ * 换行去捞另一件事的 `required`。
+ *
+ * 只认这三条。多认一条的代价是把别的原因造成的 400 误判成签名问题，然后拿一个改坏了的请求去重发。第三条
+ * 加得进来，是因为它点名的就是思考块，而补救方向一致：思考块发得越少越不会撞上它。
+ *
+ * 这一个直接改进程级的表，流里不走它——流里的降级先只算这一次请求，见文件这一段开头。
+ */
+export declare function learnThinkingReplay(providerId: string, modelId: string, error: string, from?: ThinkingReplay): boolean;
+/** 测试用：把学到的都忘掉。 */
+export declare function resetThinkingReplay(): void;
+/** 这一份请求该带哪些采样参数。见 `THINKING_FORBIDS_SAMPLING`。 */
+export declare function samplingFor(thinkingEnabled: boolean, model: Pick<ModelConfig, "samplingParams">, options: Pick<RequestOptions, "temperature" | "samplingParams">): Record<string, unknown>;

package/dist/core/llm/ai/cache-routing.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 缓存路由键（`RequestOptions.cacheKey`）怎么带给服务商。
+ *
+ * 缓存命中是按机器算的。同一条对话前缀的请求被负载均衡打散到别的机器、号池中转换了一个上游账号，
+ * 前缀再一样也是全价重算。路由键就是告诉服务商「这几次请求是同一条对话，送到同一处」。
+ *
+ * 不按端点区分，每个请求都带同一套，一共这几项：
+ *
+ *   - OpenAI 系两条链：请求头 `x-session-id`（OpenRouter 的粘性路由键）、
+ *     请求头 `session_id`（Codex CLI 发的；sub2api 一类号池选账号先看它，其次 `conversation_id` 头和
+ *     `prompt_cache_key`，都没有就随机分，见 Wei-Shaw/sub2api#1421）、请求体 `prompt_cache_key`
+ *     （OpenAI 官方字段，Kimi、通用中转也认）。未知请求头各家都是忽略；严格端点对未知的请求体字段
+ *     会 400 并点名它，撞一次就学会不发（`request-params-compat.ts` 的 `cache-key`），两个头照带。
+ *   - Anthropic 协议：请求体 `metadata.user_id`，写成 Claude Code 的 JSON，
+ *     Claude 号池类中转按其中的 `session_id` 粘住账号。缓存本身仍由
+ *     `cache_control` 断点声明。
+ *
+ * 端点硬性要求的会话头（例如 OpenCode Go 的 `x-opencode-session`，缺了直接 400）另见 `sessionHeaders`：
+ * 三种协议都带，没有 `cacheKey` 时也带。
+ */
+import type { DroppedParam } from "./request-params-compat.ts";
+/** 这次请求要加到请求体和请求头里的东西。 */
+export interface CacheRouting {
+    body: Record<string, string>;
+    headers: Record<string, string>;
+}
+/**
+ * 键放得进这个位置就原样用；放不进（超长，或有请求头容不下的字符）就压成「可读前缀-摘要」。
+ *
+ * 不照抄 pi 的截断：主会话 `<会话 id>` 和子代理 `<会话 id>-sub-<n>` 这类共享长前缀的键，截到 64 字符
+ * 后会变成同一个，子代理和主会话被路由成同一条对话。摘要取的是整条键，区分得开。
+ * 请求头的值必须是可见 ASCII，否则 `fetch` 直接抛 TypeError——整个请求发不出去。
+ */
+export declare function fitKey(key: string, maxLength: number): string;
+/**
+ * OpenAI 系两条链这次该带什么。没有 `cacheKey` 返回空；请求体字段被这个模型拒过就只带请求头。
+ */
+export declare function cacheRouting(cacheKey: string | undefined, dropped: ReadonlySet<DroppedParam>): CacheRouting;
+/** Anthropic 协议这次该在请求体里加什么。没有 `cacheKey` 返回空，请求和从前一样。 */
+export declare function anthropicMetadata(cacheKey: string | undefined): {
+    metadata?: {
+        user_id: string;
+    };
+};
+/**
+ * 端点硬性要求的会话头。三种协议都走这里，Anthropic 协议也不例外——
+ * 这不是可选的路由提示，缺了请求就发不出去。
+ *
+ * 目前只有 OpenCode Go 的 `x-opencode-session`（缺了直接 400），写死。
+ * 没有 `cacheKey`（压缩、测试连接这类一次性请求）时换成一个随机 id 而不是不带：随机 id 只是失去路由，
+ * 请求照样能发。调用方每次请求算一次，重试沿用同一个结果。
+ */
+export declare function sessionHeaders(baseUrl: string, cacheKey: string | undefined): Record<string, string>;

package/dist/core/llm/ai/chat-delta.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Chat Completions 流的入站解码：一个 chunk 里的各个字段各是什么意思。
+ *
+ * 这里全是一帧看一帧、不碰网络的判断（跨 chunk 的 `<think>` 切分在 `think-tag.ts`）——各家把同一件事
+ * 写成不同的形状，认形状的规则住在这里，`openai-chat-completions.ts` 只管把它们接进一条流的状态里。
+ */
+import type { StopReason } from "../types.ts";
+/** 这个 delta 里的推理文本，和它挂着的那个键。三个都看，取第一个非空的。 */
+export declare function reasoningFromDelta(delta: Record<string, unknown>): {
+    field: string;
+    text: string;
+} | undefined;
+/** 把泄漏的特殊 token 去掉。首尾被剥掉的那一个连带它旁边的空白一起去，免得留下一行空格。 */
+export declare function stripDeepseekTokens(text: string): string;
+/**
+ * 结尾那个还没闭合的 token，扣下来等下一个 chunk。
+ *
+ * 一个 token 会被 SSE 切成两半（`<｜tool` / `▁calls▁begin｜>`），分开看两半都不匹配。末尾单独一个 `<`
+ * 也扣着——它可能是下一个 token 的开头。扣留长度设上限，免得正文里一个孤零零的 `<｜` 让缓冲无限长。
+ */
+export declare function trailingPartialDeepseekToken(text: string): string;
+/**
+ * `finish_reason` 说的是什么。认不出来的，名字里带着出错的意思才算失败。
+ *
+ * 从前只认 `stop` / `tool_calls` / `length` 三个，其余留在 `pending`，最后被兜成 `stop` 或 `toolUse`
+ * ——**上游中途挂掉报 `finish_reason: "error"`，我们判成功**，把截断的半截答案交给 agent loop 接着跑。
+ * 用户看到的是无声截断：没有错误，没有重试，就是话说到一半。
+ *
+ * 映射里每一条的来历：
+ *
+ *   - 先折大小写：网关顶着 Google Gemini 后端时会发原生的大写 `STOP` / `MAX_TOKENS`。
+ *   - `error`：网关把上游模型的故障报成一个
+ *     不带细节的裸 `error`，多数是临时的。
+ *   - `insufficient_system_resource`：DeepSeek 自己的文档说这是推理系统资源不足导致的
+ *     中断，属于服务端容量问题。
+ *   - `content_filter`：内容策略。
+ *
+ * 后来补的几家：TGI 的 `eos_token` / `stop_sequence` 是正常说完，Mistral 的 `model_length` 是撞上长度上限，
+ * 智谱的 `sensitive` 是内容审核。
+ *
+ * **认不出来的不再一律当失败**。一律当失败的规则要防的是上面 `error` 那种被判成成功的无声截断，而它的代价落在另一头：一个只是**说法不同**的正常结束（上面这几家
+ * 补进来之前就是这样）每次都被作废、重试，重试拿到的还是同一个说法——同一家端点上**每一轮都失败**，
+ * 用户手上没有任何办法绕过去。两头都会错的时候，看名字：带着出错、中断、超限意思的仍然是失败（防的那
+ * 件事照旧防住），像内容审核的落进内容策略，剩下的按说完了交付。
+ *
+ * 返回 `stopReason` 表示这是一个正常的结束；返回 `error` 表示要抛，抛什么由调用方交给 `failure.ts` 判。
+ */
+export declare function mapFinishReason(reason: string): {
+    stopReason?: StopReason;
+    error?: string;
+};
+/**
+ * 一个 delta 的 `content` 里，正文和推理各是什么。
+ *
+ * 协议写的是字符串，Mistral（Medium、Magistral）发的是**内容片段数组**：`[{type:"text",text}]`，推理模型
+ * 还有 `{type:"thinking",thinking:[{type:"text",text}]}`。从前直接 `+=`，数组被转成 `[object Object]`
+ * 写进正文、进了历史。
+ *
+ * 认不出来的片段一律丢掉，不转成字符串——宁可少一段，不能让对象的字面写法进正文。
+ */
+export declare function contentOfDelta(content: unknown): {
+    text: string;
+    thinking: string;
+};
+/**
+ * 这一帧是不是一个错误，是的话它说了什么。
+ *
+ * 从前只认 `error` 且**没有** `choices` 的帧。OpenRouter 的流内错误偏偏两样都带：顶层
+ * `error: {code, message}`，外加 `choices: [{delta: {content: ""}, finish_reason: "error"}]`——于是错误被
+ * 放过去，落到 `finish_reason: "error"` 上，原话丢了，只剩一句「上游报告这次生成失败」去重试：额度不足、
+ * 上下文超长都认不出来，后者本该触发压缩。`{error, choices: []}` 更糟，落成一条空回答。
+ *
+ * 所以：`error` 带着一句话（字符串，或对象上的 `message`）就是错误，不看 `choices`；什么都没说的
+ * `error` 只在没有可读的 `choices` 时才算——那是这里原来的判据，不收紧。
+ *
+ * 不写 `error` 的错误帧也有好几种，从前都落成空回答：SSE 自己的 `event: error`（`frameEvent`）、国内中转
+ * 爱用的 `{code: 500, msg}` 和 `{success: false}`。后两种只在没有 `choices` 时才算：正常帧也有带着 `code: 0` 的，而真正的错误帧
+ * 不会再带一份回答；`code` 还得是个错误码，见 `isErrorCode`。没给原话的返回 `{}`，分类器会从整帧原文里自己找。
+ */
+export declare function streamErrorOf(event: Record<string, unknown>, frameEvent?: string): {
+    message?: string;
+} | undefined;
+/**
+ * 这一帧的用量。顶层没有就看 `choices[0].usage`。
+ *
+ * Kimi / Moonshot 把 usage 放在 choice 里，从前只读顶层，这几家的花费全记成 0。
+ */
+export declare function usageOf(event: Record<string, unknown>, choice: Record<string, unknown> | undefined): object | undefined;
+/**
+ * 一个工具调用的参数，接上这一片之后是什么。
+ *
+ * 协议写的是「字符串分片，按顺序拼」。实际有三种别的发法：
+ *
+ *   - **字符串，但收尾又重发了一遍整串**：先给完整的 `{"path":"a"}`，在带 `finish_reason` 的那一片里再给
+ *     一次。拼起来是两份，解析失败，工具拒绝执行。判据：已攒的是一段完整 JSON，新来的也是完整 JSON，并且
+ *     等于已攒的或以它开头——增量流里一段完整 JSON 后面不会再接一段以它整个开头的东西，所以只可能是快照。
+ *   - **对象，每片带一部分键**：`{path:"a"}` 再 `{offset:10}`。从前按「对象就是整份参数」覆盖，前面的
+ *     键丢了。改成合并。浅合并就够：见过的分片都是按顶层键分的，没见过把一个键的值拆成两半发的；真要拆，
+ *     嵌套对象被后一片整个替换，和从前的覆盖是同一个结果，不会更坏。
+ *   - **对象，每片重发同一整份**：合并同一份等于它自己，行为不变。
+ *
+ * 对象碰上 `+` 会变成 `[object Object]`，所以序列化走 `argumentFragment`。
+ */
+export declare function nextArguments(text: string, object: Record<string, unknown> | undefined, raw: unknown): {
+    text: string;
+    object?: Record<string, unknown>;
+};

package/dist/core/llm/ai/compat-key.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 「撞出来之后记住」的那几张表（`reasoning-compat.ts`、`tool-pairing-compat.ts`、
+ * `request-params-compat.ts`、Anthropic 链的思考回放/思考形状、Chat 链的输出上限字段名）共用的键。
+ *
+ * 学和查必须用同一个键，否则学到的结论永远查不到：Responses 链曾经查排列时用 `model.modelId`、
+ * 学的时候用 `model.id`，于是撞一次学一次、下一次请求照旧按默认形状发，同一个 400 每轮都来一遍。
+ * 两边各自拼字符串迟早会再漂一次，所以键只在这里拼，模型那一半也只从这里取。
+ *
+ * 取 `model.id`（配置里的唯一 id）而不是 `model.modelId`（线上模型名）：同一个服务商下可以配两条
+ * 指向同一个线上模型、参数不同的配置，它们该各学各的。
+ */
+import type { ModelConfig, ProviderConfig } from "../types.ts";
+/** 学习表的键。所有 learnXxx / 查表函数内部都只用它。 */
+export declare const compatKey: (providerId: string, modelId: string) => string;
+/** 适配器调 learnXxx / 查表函数时传的那一对 id。三条链都从这里取，不自己挑字段。 */
+export declare function compatScope(provider: Pick<ProviderConfig, "id">, model: Pick<ModelConfig, "id">): {
+    providerId: string;
+    modelId: string;
+};

package/dist/core/llm/ai/endpoint.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 三条链都要做、而且必须做得一样的几件小事：拼地址、带上同一个 User-Agent、把 fetch 的失败说成人话。
+ *
+ * 它们原来住在 `anthropic-messages.ts` 里，被另外两条链跨适配器 import——也就是说「OpenAI 那条链
+ * 的 URL 怎么拼」这件事的答案，写在 Anthropic 那个文件的第 619 行。审计把这一条列在「三条链共用
+ * 零件、不共用骨架」下面，理由不是体积：一个住在某一条链里的共享零件，改它的时候看不见另外两个
+ * 使用者，而这两个函数恰好都是「错了不会报错、只会行为变怪」的那种。
+ *
+ * `joinUrl` 的那条 `/v1` 规则是真事故留下的：用户把 baseUrl 填成 `https://host/v1`，而适配器又拼
+ * 上 `/v1/messages`，得到 `/v1/v1/messages`。三条链都拼地址，所以三条链都需要这条规则——放在这里
+ * 之后，它是一个大家都看得见的决定，而不是某条链的私事。
+ */
+import type { AssistantMessage, ModelConfig, StreamEvent, Usage } from "../types.ts";
+/** 模型请求的 User-Agent。不写的话 Node 的 fetch 会自己填 `node`，端点那边认不出是谁在调。 */
+export declare const USER_AGENT = "Plume";
+/** `base` 与 `path` 拼成一个地址，避开 `/v1` 重复。 */
+export declare function joinUrl(base: string, path: string): string;
+/**
+ * 一次尝试的用量，算好合计和费用。每次尝试各算各的，再用 `addUsage` 相加。
+ *
+ * 不能先加总再计价：`selectPricingRates` 按「这一次请求的上下文有多长」挑长上下文档位，三次 150k
+ * 的尝试加起来是 450k，会被按 >200k 那一档整体计价——每一次都没到那个档，账却按那个档记。
+ * `addUsage` 本来就逐项相加费用，所以先各自 `computeCost` 再加，得到的正是每次各按自己的档位计价之和。
+ */
+export declare function priceAttempt(usage: Usage, model: ModelConfig): Usage;
+/**
+ * Price the final attempt and fold in what earlier attempts cost.
+ *
+ * The final attempt is also kept on its own when there is anything to fold: the sum is the bill,
+ * but only this one request ever sat in the context window, and reading the sum as window size
+ * made a single retry look like twice the conversation. See `lastAttemptUsage`.
+ */
+export declare function settleUsage(partial: AssistantMessage, model: ModelConfig, spentOnRetries: Usage): void;
+/**
+ * 一次流失败或被中止，把它收成一条错误消息。
+ *
+ * 这 21 行原来在三条链里各抄一遍，逐字相同（只有一条链少了一行注释）。逐字重复的代价不是体积，
+ * 是漂移：审计记下的「三条链已经产生可观测分歧」全部出在这种地方——改一处忘两处，而三处看起来
+ * 都对。这一段管的是「失败时消息长什么样」，三条协议没有任何理由长得不一样。
+ *
+ * 成功那一侧**没有**抽出来，而且不该抽：`stopReason` 怎么算是真协议差异（Anthropic 有
+ * `stop_reason` 字段、chat/completions 靠 `finish_reason` 加工具调用推断、Responses 看收尾事件），
+ * 把三种算法塞进一个带 flag 的函数只会让每一条都更难读。
+ *
+ * 返回那个事件而不是 yield 它：这是个普通函数，调用方是生成器，`yield` 只能发生在生成器自己
+ * 那一层。
+ */
+export declare function failedStreamEvent(partial: AssistantMessage, context: {
+    error: unknown;
+    signal: AbortSignal | undefined;
+    model: ModelConfig;
+    /** 前几次失败尝试各自花掉的 token，**已经各自计过价**（`priceAttempt`），要算进账。 */
+    spentOnRetries: Usage;
+    startTime: number;
+    /** 第一个 token 到达的时刻，`null` 表示一个都没到。 */
+    firstTokenTime: number | null;
+}): StreamEvent;

package/dist/core/llm/ai/failure.d.ts

@@ -0,0 +1,181 @@
+/**
+ * 一次失败是什么、值不值得再试一次——只在这里回答一次。
+ *
+ * 从前这个判断被写了四遍：HTTP 状态码一份白名单（`isRetryableStatus`），传输异常一份白名单
+ * （`isRetryableError`），流内 error 事件干脆当成「服务商本人拒绝了」直接早退，整轮恢复那层再
+ * 拿一个 `retryable` 布尔自己判一次。四份名单互不知情，于是同一个故障在这一层算「可以再试」、
+ * 在下一层算「没救了」，设置页写着「无限重试」而请求在第一次就放弃——因为那种失败压根没进过
+ * 重试的门。
+ *
+ * 更要命的是四份都是**白名单**：只有见过的才重试。中转每换一种错法就多一个漏网的，而中转换错法
+ * 这件事是不会停的。所以这里把默认值翻过来：
+ *
+ *   只有明确「再问一百遍也是这个答复」的才是 `fatal`，其余一切都值得再试。
+ *
+ * 黑名单是有限的、确定的、几乎不增长的——密钥、模型名、请求体、配额、内容策略，就这几样。而
+ * 「其余一切」是敞开的：下一个没见过的状态码、下一种错误体格式、下一个只写着 `Unknown provider
+ * error` 的空事件，不改一行代码就自动落进 `upstream`。
+ *
+ * 两个可重试的值刻意只有两个，因为设置页上就是两行（`RetryPolicy`）。类型层面保证「界面上能配
+ * 的」和「实际会重试的」不会各说各话——想加第三类，改这个枚举，编译器会把该改的地方全指出来。
+ */
+type FailureKind = "network" | "upstream" | "fatal";
+/**
+ * 界面据此挂动作：401 旁边给「去检查密钥」，404 给「换个模型」。
+ *
+ * 是分类的产物而不是界面自己猜的，所以加一个动作不用碰分类逻辑，认一种新错误也不用碰界面。
+ */
+type FailureHint = "check-key" | "check-model" | "check-billing" | "check-request" | "blocked";
+/**
+ * 循环自己能处理的那几种 `fatal`，给程序认的名字。
+ *
+ * `hint` 是给界面挂动作的，粒度按「人该去改哪儿」分；这里按「循环能做什么」分，两者不重合：
+ * 上下文超长和请求体格式错误在界面上都是 `check-request`，而只有前者压缩一次历史就可能过。
+ */
+type FailureCode = "context-overflow";
+export interface Failure {
+    kind: FailureKind;
+    /** 一句话，一行放得下，给人看的。 */
+    summary: string;
+    /** 服务商原文，展开或悬停才看。 */
+    detail?: string;
+    /** 服务器自己说的等待时间，比任何我们猜的曲线都准。 */
+    retryAfterMs?: number;
+    hint?: FailureHint;
+    /** 见 `FailureCode`。只在认出来时有，缺省不代表「不是」——旧日志里的失败都没有它。 */
+    code?: FailureCode;
+    /**
+     * 「还是刚才那个错误吗」的答案。
+     *
+     * 无限重试撞上一个我们不认识的终局错误时，界面唯一能说的真话就是「已经重连 47 次，一直是
+     * 同一个错误」。指纹让这句话不需要认识任何具体的错误就能说出口——真正的临时故障，文案和状态
+     * 码会变；一字不差重复几十次的，人一眼就知道不是在排队。
+     */
+    fingerprint: string;
+    /**
+     * 这一种失败自己的重试上限，和用户的策略取更严的那个。
+     *
+     * 绝大多数失败不该有这个——「重试几次」是用户的决定，设置页上那个「一直重试」写着的就是
+     * 「网络回来之前别放弃」，那是他要的。
+     *
+     * 例外是重发根本不可能改变结果的那些。空回答是眼下唯一一种：重发的是逐字节相同的请求体，
+     * 拿回来的是逐字节相同的空。服务端状态的波动（503、限流、实例在换）几次之内就会变个样子，
+     * 而几十次一模一样的，只说明这个请求在这个端点上就是会得到空——再等一百次也是。
+     *
+     * 真实日志里量到过一次：同一个请求重发 222 次、34 分钟，直到人工按停。
+     */
+    retryLimit?: number;
+    /**
+     * 这次失败有没有已经花掉 token。
+     *
+     * 流已经开始吐字，说明请求被受理了，那些 token 服务商已经收过钱——重试就是再付一次。连接在
+     * 握手阶段就断掉则一分钱没花。两者都该重试，但只有前者需要把代价摆到界面上，否则一个开着
+     * 无限重试的窗口可以安静地烧穿账单。
+     */
+    costIncurred?: boolean;
+}
+export type FailureInput = 
+/**
+ * fetch 本身抛了：连接没建立，或者建立后断了。
+ *
+ * `sending`：异常是从发请求那一下（`fetch(...)` 本身）抛出来的，而不是读流、解码时。只有调用 fetch
+ * 的那一处知道这件事，见 `fromTransport` 里用到它的那一段。
+ */
+{
+    from: "transport";
+    error: unknown;
+    sending?: boolean;
+}
+/** 服务器答了，但状态码不是 2xx。 */
+ | {
+    from: "status";
+    status: number;
+    body?: string;
+}
+/**
+ * 连接和状态码都正常，错误写在流里面。
+ *
+ * `streamed`：出错之前已经流到窗口里的正文（`spokenSoFar`）。服务商有时把拒绝当成回答写出来，再由中转
+ * 补一个泛泛的错误收尾，单看那个错误像是一次抖动——见 `refusalIn`。
+ */
+ | {
+    from: "stream";
+    message?: string;
+    raw?: string;
+    spent?: boolean;
+    streamed?: string;
+}
+/**
+ * 流正常结束，但一个字都没有——见 `fromEmpty`。
+ *
+ * `not-stream`：状态码 200、content-type 却明说是 JSON 或网页，正文根本不是 SSE（见 `retry.ts` 的
+ * `streamOrFailure`）。`output.truncated`：是不是撞了输出上限——撞上限的空不是故障。
+ */
+ | {
+    from: "empty";
+    why: "no-content" | "no-frames" | "unparsable" | "not-stream";
+    body?: string;
+    output?: SpentOutput;
+};
+/** 空回答那一次，是不是撞了输出上限。 */
+type SpentOutput = {
+    truncated: boolean;
+};
+/**
+ * 写在错误正文里的终局理由。
+ *
+ * 中转很少给出规矩的状态码——一个欠费的账号可能收到 200 加一个流内 error 事件。能认出来的就认，
+ * 认不出来的落进 `upstream` 去重试，再由界面把「一直是同一个错误」说出来。所以这张表宁可短一些
+ * 也不要猜：错判成 `fatal` 会让一次本可以自愈的抖动直接终止，那比多重试几次糟得多。
+ */
+/** 模型拒绝作答时交给分类器的那句话；上面的内容策略那条认它，判成 `blocked`、不重试。 */
+export declare const REFUSAL_MESSAGE = "\u6A21\u578B\u62D2\u7EDD\u56DE\u7B54\u8FD9\u6B21\u8BF7\u6C42";
+/** 这次失败是不是上下文超长——循环据此决定要不要强制压缩一次再发。 */
+export declare const isContextOverflow: (failure: Failure | undefined) => boolean;
+/**
+ * 错误正文里那句真正说明问题的话。
+ *
+ * 每家中转把它放在不同的地方，所以按常见程度依次找。找不到就返回空，让调用方退回到状态码的固定
+ * 说法——那也比把整个 JSON 糊在界面上强。
+ */
+export declare function messageFromBody(body: string | undefined): string;
+/**
+ * 服务器说要等多久，毫秒。
+ *
+ * 从 `Retry-After` 头和错误正文两处找，因为两边都有人用。正文那一路尤其要紧：我们面前这个中转
+ * 用 `{"reset_seconds":54}` 回答 503 而完全不发头，从前每一次等待都因此退回到猜的曲线上，几秒钟
+ * 就把整个重试预算花在一场它早就说明要持续一分钟的故障上。
+ */
+export declare function serverDelayMs(header: string | null | undefined, body?: string): number | undefined;
+/**
+ * `1m2s`、`6m0s`、`11.05s`、`20ms` 这种时长写法，毫秒。OpenAI 的 `x-ratelimit-reset-*` 头和
+ * 限流原话都这么写。整串都得是时长，认不出就是 `undefined`。
+ */
+export declare function durationMs(text: string): number | undefined;
+export declare function classifyFailure(input: FailureInput): Failure;
+/** 进行中的回复里已经显示出来的正文——人已经看到的那部分，不含思考。 */
+export declare function spokenSoFar(content: readonly {
+    type: string;
+    text?: string;
+}[]): string;
+/** 值得再试一次吗。三层重试问的都是这一个问题。 */
+export declare const worthRetrying: (failure: Failure) => boolean;
+/**
+ * 一个已经判过的失败，被包成异常往上抛。
+ *
+ * 少了它就会判两遍，而第二遍是错的：一个 401 在状态码那一路被正确地判成 `fatal`，调用方把它抛成
+ * `new Error("HTTP 401: invalid key")`，到了流重试那一层就只剩一个字符串——从异常的角度看它既没有
+ * `cause.code` 也不认识自己，于是落进「认不出来的连接问题」，然后被无限重试。判断带着结论一起走，
+ * 上面每一层就都不必再猜。
+ */
+export declare class FailureError extends Error {
+    readonly failure: Failure;
+    constructor(failure: Failure);
+}
+/**
+ * 这个异常代表的失败是什么。
+ *
+ * 已经判过的照搬，没判过的当传输故障判——那是异常唯一可能的另一个来源。
+ */
+export declare function failureOf(error: unknown): Failure;
+export {};