@plumeai/plugin-sdk 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,16 @@
+import type { AssistantMessage, LlmContext, ModelConfig, Provider, ProviderConfig, RequestOptions, StreamEvent } from "../types.ts";
+/** What provider lookup asks before falling back to the built-in adapters. */
+export interface LlmRegistry {
+    get(api: string): Provider | undefined;
+}
+/**
+ * Put a registry in front of the built-in adapters.
+ *
+ * Deliberately a binding rather than a parameter threaded through every call site: the adapter
+ * in use is a property of the running process, and passing it down through the agent loop,
+ * compaction and every tool that streams would say otherwise. Neither host binds one; the seam is
+ * for tests and scripts, and for whatever per-session injection replaces it.
+ */
+export declare function useLlmRegistry(next: LlmRegistry | null): void;
+/** Stream one assistant turn. Yields incremental events and returns the final message. */
+export declare function streamAssistant(providerConfig: ProviderConfig, model: ModelConfig, context: LlmContext, options?: RequestOptions): AsyncGenerator<StreamEvent, AssistantMessage>;

package/dist/core/llm/ai/openai-chat-completions-request.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Our messages, in the shape the OpenAI Chat Completions API wants (`POST /v1/chat/completions`).
+ */
+import type { Message, ToolCallContent, ToolSpec } from "../types.ts";
+import type { ReasoningReplay } from "./reasoning-compat.ts";
+/** 编码时需要知道的模型能力。只取用得到的那一项，免得一个纯翻译函数被整个 `ModelConfig` 绑住。 */
+export interface ChatCompletionsModelCapabilities {
+    supportsImages: boolean;
+}
+export declare function toChatCompletionsTools(tools: ToolSpec[]): unknown[];
+/**
+ * Cleans conversation history for the OpenAI Chat Completions wire protocol.
+ *
+ * Chat Completions enforces strict invariants:
+ * 1. An assistant message must have either non-empty content or tool_calls. Empty content ("")
+ *    without tool_calls causes HTTP 400 (e.g. Gemini/relays returning INVALID_ARGUMENT).
+ *    When a model spends its turn thinking and emits no text/tools, that turn is a no-op;
+ *    we prune it along with any synthetic nudge following it.
+ * 2. Tool results must correspond to an assistant tool call. Orphan tool results that have no
+ *    prior assistant call are dropped or sanitized to avoid 400 errors.
+ */
+export declare function sanitizeChatCompletionsHistory(messages: Message[]): Message[];
+export declare function toChatCompletionsMessages(systemPrompt: string, messages: Message[], reasoning?: ReasoningReplay, model?: ChatCompletionsModelCapabilities, 
+/** 缺推理的助手轮补一个空的 `reasoning_content`。撞上过才开，见 `padsMissingReasoning`。 */
+padMissingReasoning?: boolean): unknown[];
+/** 这个模型值得放缓存断点：Anthropic 的模型，经一个把请求翻译成 Anthropic 的中转（OpenRouter、LiteLLM 一类）。 */
+export declare function wantsCacheBreakpoints(modelId: string): boolean;
+/**
+ * 在 system 和最后两条消息上放 `cache_control` 断点。
+ *
+ * Anthropic 的缓存只认显式断点，而这条链原来一个都不放：Claude 经 Chat Completions 中转时每一轮都把
+ * 整段历史按全价重读。原生那条链早就在尾部滚动断点（`anthropic-messages-request.ts` 的
+ * `applyPromptCaching`）。这里放 system 和最后两条；断点挂在**内容块**上而不是消息上，所以
+ * 字符串内容要改写成一个 text 块——`prefix-fingerprint.ts` 把这样的单块认作原来那个字符串。
+ * Anthropic 一次最多四个断点，这里用三个。
+ *
+ * 只挂在有字的 text 块上：空 text 块不能带断点，只有 `tool_calls` 的助手消息（`content: ""`）跳过、往前找。
+ * 端点不认这个字段时会点名它，学到 `cache-control` 就不再放（`request-params-compat.ts`）。
+ */
+export declare function withCacheBreakpoints(messages: unknown[]): unknown[];
+/**
+ * 回放一次工具调用时发的参数串。
+ *
+ * 优先发流里收到的原文：那是上一次请求里服务商亲眼见过的字节，换成重新序列化的版本（键序、空格、
+ * 转义都可能不同）会让这一段缓存前缀失效。原文不是合法 JSON 时（截断、模型吐坏了）才改发解析后的
+ * 参数：原样透传在官方端点上没事，但把请求再翻译成 Anthropic / Gemini 的中转要先解析它，解析不了
+ * 就是 400，而这条调用进了历史，之后每一轮都是这个 400。
+ */
+export declare function replayArguments(call: ToolCallContent): string;

package/dist/core/llm/ai/openai-chat-completions.d.ts

@@ -0,0 +1,37 @@
+/**
+ * OpenAI Chat Completions API adapter (`POST /v1/chat/completions`).
+ */
+import type { Provider } from "../types.ts";
+import { type SentParams } from "./request-params-compat.ts";
+export declare const openaiChatCompletionsProvider: Provider;
+/**
+ * 输出上限该写在哪个键上——这条只能靠撞出来。
+ *
+ * 和 `reasoning-compat.ts`、`request-params-compat.ts` 同一个路子，理由也同一个：**我们手上没有普查
+ * 表**。按厂商、主机名、模型家族把这件事查出来，要的是几百个端点的实测积累，攒不起来也维护不起。
+ *
+ * 能靠的是另一样东西：**这种 400 的错误串自带诊断**——它直接点名该用哪个字段。所以默认保持这条链现在
+ * 发的那个键（不动任何现在能用的端点），撞上那句话就学到结论、换个键重发一次。
+ *
+ * 采样参数和 `tool_choice` 那两条轴**不在这里**，在 `request-params-compat.ts`——那是三条链共用的一份，
+ * 两条链各写一份同样的正则是纯负债。这里只留「换字段名」这一条，因为它不是「撤掉一个参数」，撤不掉：
+ * 输出上限必须发，只是键名有两种。
+ *
+ * 记在内存里，不落盘，理由见 `reasoning-compat.ts` 顶部：进程重启后重新学一次的代价是一次自愈的重发，
+ * 换来的是不必为它做设置迁移，也不必担心一条学错的结论永久粘在用户的配置里。
+ */
+export type MaxTokensField = "max_tokens" | "max_completion_tokens";
+/** 这个模型该用哪个键。没撞过之前就是这条链一直在发的那个。 */
+export declare function maxTokensField(providerId: string, modelId: string): MaxTokensField;
+/** 测试用：把学到的都忘掉。 */
+export declare function resetChatCompletionsCompat(): void;
+/**
+ * 从一次失败里学点东西。返回「结论变了，值得换个形状重发一次」。
+ *
+ * 签名对上 `withReasoningRetry` 的 `alsoLearn`，而且**排在推理那条梯子前面**看——理由见那个参数的注释：
+ * 指向明确的轴先看，误判的机会小得多。这里两条的指向再明确不过，错误串里点着字段名。
+ *
+ * 两个学习器都要问，**不能用 `||` 短路**：一句话可以同时点名两样（`max_tokens` 该换名、`temperature`
+ * 不该发），短路会漏掉后一条，然后下一次重发再撞一遍同一句话。
+ */
+export declare function learnChatCompletionsCompat(providerId: string, modelId: string, error: string, sent?: SentParams): boolean;

package/dist/core/llm/ai/openai-responses-request.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Our messages, in the shape the Responses API wants.
+ *
+ * Purely a translation: no network, no state, no decisions beyond how each kind of content maps.
+ * Separated from the streaming half because the two are read for different reasons — this one when
+ * a message is not being sent correctly, the other when a reply is not being read correctly.
+ */
+import type { Message, ToolSpec } from "../types.ts";
+import type { ReasoningReplay } from "./reasoning-compat.ts";
+import type { ToolPairing } from "./tool-pairing-compat.ts";
+import type { ToolResultImages } from "./tool-result-images-compat.ts";
+/**
+ * Who this request is going to, so a handle from someone else can be told apart from our own.
+ *
+ * Every assistant message records the provider and model that produced it. A reasoning item id is
+ * that provider's private handle on its own chain of thought — it means nothing to anyone else, and
+ * is rejected rather than ignored when replayed to them.
+ */
+export interface ResponsesHome {
+    provider: string;
+    model: string;
+    /**
+     * 这个模型收不收图片。省略按「收」算。
+     *
+     * 省略等于收，是因为老会话和大部分调用点并不知道这件事，而把「不知道」当成「不收」会把图片从本来好好
+     * 的请求里抹掉。反过来错的代价小：多发一张图给不收图的端点会被拒，而那正是下面要防的；漏判只是维持
+     * 现状。
+     */
+    supportsImages?: boolean;
+    /** Where a tool result's image goes; see `tool-result-images-compat.ts`. Omitted means inline. */
+    toolImages?: ToolResultImages;
+    /**
+     * 这个端点要不要每个助手轮都以推理项开头（没有就补一个合成的，见 `toResponsesInput` 的补位分支）。
+     * 省略按「要」算。
+     *
+     * 省略等于要，理由同 `supportsImages`：不知道的调用点维持原来的形状。适配器知道发往哪里，由它说
+     * 「不要」——补出来的那一项在官方 OpenAI 上是一次必然的 400（`maximum length 0`）。
+     */
+    leadingReasoning?: boolean;
+}
+/**
+ * 一轮里的多个工具调用怎么排：成组（所有调用，然后所有结果）还是交错（一问一答）。
+ *
+ * 两家要求相反，见 `tool-pairing-compat.ts`。这里只负责按给定的那一档编码，选哪一档是那边的事。
+ *
+ * 这段原本写死交错，理由是把 Responses 翻译成 Chat Completions 的中转需要它——那个理由是真的，错的是
+ * 把它当成了**普适**的形状：
+ *
+ *     an assistant message with 'tool_calls' must be followed by tool messages responding to
+ *     each 'tool_call_id'. The following tool_call_ids did not have response messages: bash:0
+ *
+ * 代价是 2026-09-11 的两个报废会话。`api.deepseek.com` 的 Responses 要成组，交错排一律 400，而它报的是
+ * `The reasoning_text in the thinking mode must be passed back to the API.`——一句跟工具无关的话。真实端点
+ * 上二分过：一对调用/结果 200，第二对一加就 400；改成成组之后，推理项发不发、带不带文本，全都 200。
+ *
+ * 不管哪一档，这里都保证结果按**调用顺序**排，而不是按完成顺序。结果是各个工具跑完的时候记下来的，从日志
+ * 重建的历史里它们按完成先后躺着；在这里配对意味着发出去的形状不取决于哪个工具更快。
+ *
+ * 一条结果如果在它前面的助手消息里找不到对应的调用——日志被截断、有人编辑掉了那次调用——保留在原位，不
+ * 丢弃：它是历史，而凭空造一个调用去挂住它比原样传过去更糟。
+ */
+export declare function toResponsesInput(messages: Message[], home?: ResponsesHome, reasoning?: ReasoningReplay, pairing?: ToolPairing): unknown[];
+export declare function toResponsesTools(tools: ToolSpec[]): unknown[];

package/dist/core/llm/ai/openai-responses.d.ts

@@ -0,0 +1,11 @@
+/**
+ * OpenAI Responses API adapter (`POST /v1/responses`).
+ *
+ * The Responses format is item-based rather than message-based: assistant text, reasoning
+ * and function calls are sibling items in one flat `input` array. Reasoning items carry an
+ * opaque `encrypted_content` that must be replayed verbatim for the model to keep its chain
+ * of thought across tool calls, which is why `include: ["reasoning.encrypted_content"]` is
+ * always requested.
+ */
+import type { Provider } from "../types.ts";
+export declare const openaiResponsesProvider: Provider;

package/dist/core/llm/ai/prefix-fingerprint.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 请求前缀在哪里变了：缓存诊断的归因证据。
+ *
+ * 诊断只从 usage 看得出「本该读到的没读到」，看不出是本地改了前缀（提示词、工具、剪枝、协议编码），
+ * 还是服务商那边清掉了缓存。这里把最终请求体按缓存前缀的顺序切段——工具定义、系统提示词、请求参数、
+ * 逐条消息——各算一个哈希，和同一会话的上一次请求比出第一处不同。只留位置和长度，不留正文。
+ *
+ * 三条协议的请求体都按这个形状切：Anthropic `tools`/`system`/`messages`，Responses
+ * `tools`/`instructions`/`input`，Chat Completions `tools`/`messages`（系统提示词是开头那条 `system` 消息，同样记成 `system`）。
+ * 协议放的 `cache_control` 断点每次跟着最后一条消息挪，不算内容，哈希前去掉（只去协议放的那几处）。
+ */
+import type { RequestPrefix } from "../types.ts";
+export interface PrefixSegment {
+    name: string;
+    hash: string;
+    chars: number;
+}
+export declare function payloadSegments(body: unknown): PrefixSegment[];
+/** `after` 和 `before` 比：`before` 原样是 `after` 的前缀时没有 `change`。 */
+export declare function comparePrefix(before: readonly PrefixSegment[], after: readonly PrefixSegment[]): RequestPrefix;

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

@@ -0,0 +1,69 @@
+/**
+ * 一个端点对「把模型自己的推理还回去」这件事的态度，问出来之后记住。
+ *
+ * 这里不是可有可无的优化，是因为**各家的要求互相矛盾，一个全局形状在数学上满足不了**。两条都是真实
+ * 端点上量出来的：
+ *
+ *   - 某中转上的 Claude：推理项可以有，但**必须带得动签名**。换过模型之后签名被
+ *     `stripStaleHandles` 剥掉了，剩下一个没有句柄的思考块，于是
+ *     `messages.1.content.0.thinking.signature: Field required`——补上 summary 也只是换成
+ *     `thinking.thinking: Field required`，因为缺的那样东西我们根本没有。
+ *   - 某中转上的 `gpt-oss-120b-medium`：input 里**只要有** reasoning 项就 400，四种形状全试过。
+ *
+ * 所以是三档，不是开关。三档之间是一条梯子，越往下发得越少：
+ *
+ *     replay（都发） → handled（只发带句柄的） → omit（一个都不发）
+ *
+ * 被顶回来一次就往下走一格，重发。往下走是安全的方向——少发一点推理最多让模型接不回自己那条思维链，
+ * 而多发一格是整个请求被拒。第二种信号（「你得还回来」）把它一次拉回顶格。
+ *
+ * 只认有实测证据的错误串。多认一条的代价是把别的原因造成的 400 误判成形状问题，然后拿一个改坏了的
+ * 请求去重发——那比不认还糟。
+ *
+ * 记在内存里，不落盘。进程重启后重新学一次，代价是一次自愈的重发；换来的是不必为它做一次设置迁移，
+ * 也不必担心一条学错的结论永久粘在用户的配置里。
+ */
+/** 推理块在下一轮请求里的去向。 */
+export type ReasoningReplay = "replay" | "handled" | "omit";
+/** 这个模型该发哪一档。默认顶格——那是绝大多数端点要的，也是没撞过之前唯一有依据的猜测。 */
+export declare function reasoningReplay(providerId: string, modelId: string): ReasoningReplay;
+/**
+ * 从一次失败里学点东西。返回「结论变了，值得换个形状重发一次」。
+ *
+ * 已经在梯子最底下还被顶回来，返回 false——再往下没有格子了，重发只是多烧一次钱。
+ */
+export declare function learnReasoningReplay(providerId: string, modelId: string, error: string): boolean;
+/** 这个模型的历史助手轮缺推理时，要不要补一个空的 `reasoning_content`。 */
+export declare function padsMissingReasoning(providerId: string, modelId: string): boolean;
+/**
+ * 撞上「必须带回来」时，先学会补空串，再轮到 `learnReasoningReplay` 那次原样重试。
+ *
+ * 只有 Chat Completions 链把它挂进 `withReasoningRetry` 的 `alsoLearn`：Responses 链不读这个结论，在那里学到
+ * 等于白白多发一次一模一样的请求。只在梯子顶格时学——不在顶格说明还有推理没发，先让梯子把它拉回来。
+ */
+export declare function learnReasoningPadding(providerId: string, modelId: string, error: string): boolean;
+/** 测试用：把学到的都忘掉。 */
+export declare function resetReasoningCompat(): void;
+/**
+ * 跑一次请求；被端点用「推理形状不对」顶回来时，换成它要的那一档，重发。
+ *
+ * 套在 `retryStream` **外面**，因为那一层按定义不会重试一个 400——同一个请求再发一遍还是同一个 400，
+ * 它拒绝得对。这里重发的是一个**不同的**请求，所以是另一件事。
+ *
+ * 两条闸：
+ *
+ *   - 最多走完整条梯子，外加一步留给 `alsoLearn` 那个轴（它自己也只学一次）。每个学习器到底了都返回
+ *     false，循环自己停。任何一个轴加格子，这里的上界要跟着改——它是两个轴的步数之和，不是某一个的。
+ *   - 已经吐过字（`costIncurred`）就不重来。那些 token 服务商已经收过钱了，而且界面上已经画出了
+ *     半个回答，重发会让它凭空再来一遍。请求形状的 400 发生在生成之前，这一条正常不会挡住它。
+ */
+export declare function withReasoningRetry<T>(providerId: string, modelId: string, reset: () => void, 
+/**
+ * 别的轴也来看一眼这次失败——返回 true 表示它学到了东西，值得换个形状重发。
+ *
+ * 先问它再问推理那条梯子，因为**这两个轴会抢同一句话**。DeepSeek 的 Responses 在工具排列不对时报的
+ * 是 `The reasoning_text in the thinking mode must be passed back to the API.`，一句跟工具毫无关系
+ * 的话，而它正好落进下面 `REQUIRES` 的正则里。让推理那条先看，它会把这次失败认成自己的、退回一个
+ * 于事无补的结论；让指向明确的那条先看，误判的机会小得多。
+ */
+alsoLearn: ((providerId: string, modelId: string, error: string) => boolean) | undefined, run: (replay: ReasoningReplay) => AsyncGenerator<T, void>): AsyncGenerator<T, void>;

package/dist/core/llm/ai/request-params-compat.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 请求体里那些「这个端点不吃这个字段」的参数，撞出来之后记住。
+ *
+ * 和另外两个轴（`reasoning-compat.ts` 管推理怎么还、`tool-pairing-compat.ts` 管工具怎么排）是并列的
+ * 第三件事，各学各的。压进同一条梯子的代价上一轮付过了：端点说 A、梯子退 B，对不上号时只能靠碰巧。
+ *
+ * 这里管的七个参数有一个共同点——**它们都不是必需品**。少发一个最多损失一点控制力（思考没关干净、
+ * 采样参数没生效），而多发一个是整个请求被拒。所以默认全发、撞了就撤，方向永远是安全的那边。
+ *
+ * 为什么是「学」而不是「配」：这四条在作者能测到的两个端点上**全部 200**（2026-09-11，
+ * `test/responses-params-probe.ts`）。也就是说我们手上
+ * 没有能复现它们的端点，没有资格替所有人改默认值。我们也没有一张人工普查出来的表能直接查——但错误串
+ * 自带诊断，撞一次就够了。
+ *
+ * 已知的先验不靠学，写在 `vendors/`：Gemini 系、OpenAI 的 o 系列和旧 gpt-5 拒 `effort: "none"`。这里的
+ * 机制是给**没见过的端点**兜底的。
+ *
+ * 记在内存里，不落盘，理由同另外两个轴。
+ */
+/** 一个可以在撞墙后撤掉的请求参数。 */
+export type DroppedParam = "reasoning-off" | "reasoning-summary" | "tool-choice" | "sampling" | "include-encrypted" | "cache-key" | "cache-control";
+/** 这个模型上该省掉哪些参数。没撞过就是一个都不省。 */
+export declare function droppedParams(providerId: string, modelId: string): ReadonlySet<DroppedParam>;
+/** 这次被拒的请求里实际发了什么。给了就用来排除「撤掉它也不会改变请求」的信号。 */
+export interface SentParams {
+    /** 发了「关推理」那个值（`effort: "none"` / `reasoning_effort: "none"`）没有。 */
+    reasoningOff?: boolean;
+}
+/**
+ * 从一次失败里学点东西。返回「结论变了，值得削掉这个参数重发一次」。
+ *
+ * 已经撤过同一个参数还被同一句话顶回来，返回 false——再发一次还是同样的结果，只是多烧一次钱。
+ *
+ * `sent` 不给时按从前的行为只看错误串；适配器应当给——请求里根本没有 `none` 时，一句提到 effort 的
+ * 400 说的一定是别的档位，撤「关推理」既改不了这次的请求，还会让这个模型以后关不掉思考。
+ */
+export declare function learnDroppedParam(providerId: string, modelId: string, error: string, sent?: SentParams): boolean;
+/** 测试用：把学到的都忘掉。 */
+export declare function resetRequestParamsCompat(): void;

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

@@ -0,0 +1,130 @@
+/** Shared request/stream budget prevents nested retry loops from multiplying the configured limit. */
+import { type RetryPolicy, type RetryPolicySource, type RetryFailure } from "../config/retry-policy.ts";
+import { type Failure } from "./failure.ts";
+export declare class RetryBudget {
+    private used;
+    /**
+     * 自带上限的失败（`Failure.retryLimit`）各自重试过几次，按指纹记。
+     *
+     * 不能和 `used[kind]` 共用：那是同一类所有失败的总账。先连着 503 重试四次，轮到空回答时总账已经是
+     * 4，它自己一次没试就被判「用满了」。它的上限说的是「这一种重发了几次」，账得单独记。
+     */
+    private limited;
+    private readonly read;
+    private readonly attempts?;
+    private cache?;
+    constructor(policy?: RetryPolicySource, attempts?: number);
+    /**
+     * The rules in force right now, not the ones this request started under.
+     *
+     * Normalising is not free and this is read on every attempt, so the result is kept until the
+     * settings object itself is replaced — which is what saving the settings page does.
+     */
+    get policy(): RetryPolicy;
+    /**
+     * 还能不能再试一次。
+     *
+     * 失败可以选择传进来，因为有那么几种失败自己带着上限（见 `Failure.retryLimit`），而它比用户
+     * 的策略更有发言权的情形只有一种：重发不可能改变结果。两个数取更严的那个——用户设了 2 次就
+     * 是 2 次，这里不会把它放宽成 4。
+     *
+     * 不传也是对的：调用方手里没有分类结论时（还没发出去的那一次），问的就是纯粹的策略。
+     */
+    available(kind: RetryFailure, failure?: Failure): boolean;
+    /** 传入 `failure` 时，自带上限的那种失败另记一笔，见 `limited`。 */
+    next(kind: RetryFailure, failure?: Failure): {
+        attempt: number;
+        delayMs: number;
+    };
+}
+export interface RetryOptions {
+    budget?: RetryBudget;
+    /** Total attempts, including the first. */
+    attempts?: number;
+    signal?: AbortSignal;
+    /** Called before each wait, so a caller can tell the user what is happening. */
+    onRetry?: (info: {
+        attempt: number;
+        delayMs: number;
+        reason: string;
+        failure?: Failure;
+    }) => void;
+    /** Injected in tests so they do not sleep. */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * 这个请求要的是 SSE。200 而正文明摆着不是（见 `streamOrFailure`）的，当失败判，不交给流解析。
+     *
+     * 要调用方开口说，因为不是每个经过这里的请求都要流：一次性的 JSON 请求，200 加 JSON 就是成功。
+     */
+    stream?: boolean;
+}
+/**
+ * 值得再试一次吗——问的是 `failure.ts`，不是这里。
+ *
+ * 这两个函数从前各自守着一份白名单，是四份互不知情的判断里的两份。留下这层薄壳是因为调用点还在
+ * 用它们的名字，而壳里已经换成了同一个分类器：认不出来的东西现在会被重试，而不是被拒之门外。
+ */
+export declare function isRetryableError(error: unknown): boolean;
+export declare function isRetryableStatus(status: number, body?: string): boolean;
+/**
+ * How long to wait, honouring the server's own answer when it gives one.
+ *
+ * A server under load knows better than any curve we could pick, so its number wins outright —
+ * only capped, never shortened. Ours is the fallback, and it starts where a person would expect a
+ * retry to start rather than where a tight loop would: the first version began at 600ms and
+ * tripled, which spent three attempts inside two and a half seconds and read as the app hammering
+ * a server that had just said it was busy.
+ */
+export declare function retryDelay(attempt: number, response?: Response, body?: string): number;
+/**
+ * Perform a request, retrying everything except what is certain not to change.
+ *
+ * 成功的响应原样返回。其余一律抛 `FailureError`——包括 4xx：从前它们是被「原样返回，由调用方
+ * 自己去报」的，而三个调用方拿到之后做的第一件事都是 `if (!response.ok) throw`，于是那个结论在
+ * 路上被重新猜了一遍，猜出来的东西还不如原来准（一个 `HTTP 401: ...` 字符串在流那一层看起来像
+ * 「没见过的连接问题」）。判断带着结论一起走。
+ */
+export declare function fetchWithRetry(doFetch: typeof globalThis.fetch, url: string, init: RequestInit, options?: RetryOptions): Promise<Response>;
+/**
+ * A tool call's id, invented if the provider did not supply one.
+ *
+ * The id is the only thing tying a call to its result and to the card on screen. A provider
+ * that omits it — some relays drop `call_id` on a truncated stream — used to yield the empty
+ * string for every such call, so they all collided on one entry: the newest call reset the
+ * shared record to "running" and every earlier card in the transcript started spinning again,
+ * all showing the same elapsed time because they were all reading the same object.
+ *
+ * The fallback is remembered per output index, because one call arrives across several events
+ * and they have to agree on what it is called.
+ */
+export declare function toolCallId(given: unknown, outputIndex: number, invented: Map<number, string>): string;
+/**
+ * Run a streamed request, and start it over if the stream itself dies.
+ *
+ * `fetchWithRetry` covers getting the connection; this covers keeping it. They are different
+ * failures with the same cause and very different odds: a request that takes forty seconds to
+ * stream a large reply is exposed to a dropped socket for the whole of it, and a long piece of
+ * work is exactly where the replies are longest. Losing one there ends the turn — and with it a
+ * plan the agent was eight steps into.
+ *
+ * Starting over is safe because nothing has happened yet. Tools are executed by the caller after
+ * a complete reply arrives, so a half-streamed one has changed nothing; the only cost is the
+ * tokens spent saying it again.
+ *
+ * `reset` is called before every attempt to clear whatever the last one accumulated. Anything
+ * already emitted to the UI is replaced by what the retry emits, because each update carries the
+ * whole message rather than a delta to apply.
+ */
+export declare function retryStream<T>(attempt: (attemptNumber: number) => AsyncGenerator<T, void>, options: {
+    budget?: RetryBudget;
+    attempts?: number;
+    signal?: AbortSignal;
+    reset: () => void;
+    onRetry?: (info: {
+        attempt: number;
+        delayMs: number;
+        reason: string;
+        failure?: Failure;
+    }) => void;
+    sleep?: (ms: number) => Promise<void>;
+}): AsyncGenerator<T, void>;

package/dist/core/llm/ai/sanitize-history.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Enforces protocol-level invariants on conversation history before sending to providers.
+ *
+ * All major LLM providers enforce strict tool pairing rules on the wire:
+ * 1. OpenAI Responses:
+ *    Every `function_call` must be accompanied by its `function_call_output`.
+ *    An unanswered tool call causes HTTP 400 (`No tool output found for function call ...`).
+ * 2. Anthropic Messages:
+ *    Every `tool_use` block in an assistant message must have a matching `tool_result`
+ *    in the immediately following user message. Missing results cause HTTP 400.
+ * 3. OpenAI Chat Completions:
+ *    An assistant message with `tool_calls` must be followed by `role: "tool"` messages
+ *    responding to each `tool_call_id`. Missing results cause HTTP 400.
+ *
+ * If a session's history contains an assistant message with tool calls that were never
+ * answered (e.g. aborted mid-turn, process crash before execution, or network disconnect),
+ * sending it raw crashes the conversation irrevocably.
+ *
+ * This sanitizer synthesizes a clear error toolResult for any unanswered toolCall,
+ * preserving turn atomicity and repairing protocol invariants without losing history.
+ */
+import type { Message } from "../types.ts";
+export declare function sanitizeToolPairing(messages: Message[]): Message[];

package/dist/core/llm/ai/think-tag.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 写在 content 里的 `<think>…</think>`，流式切成思考。
+ *
+ * 单独一个文件，因为它是这条链上唯一一段**跨 chunk 带状态**的文本切分；其余的入站判断都是一帧看一帧的
+ * 纯函数，在 `chat-delta.ts`。
+ */
+/**
+ * 内联 `<think>` 切出来的思考块记在 `reasoningField` 上的标记。
+ *
+ * 它不是一个字段名：回放时编码那边见到它，就把思考按原样包回 `<think>…</think>` 放在正文前面（见
+ * `openai-chat-completions-request.ts`）。MiniMax M2 的文档要求多轮里把带 `<think>` 的整段回答原样带回，
+ * 拆成 `reasoning_content` 发回去它不认。
+ */
+export declare const THINK_TAG_FIELD = "<think>";
+/** 切出来的一段：思考还是正文。 */
+interface ThinkSegment {
+    kind: "thinking" | "text";
+    text: string;
+}
+/**
+ * 把正文开头的 `<think>…</think>` 切成思考。
+ *
+ * 没开 reasoning parser 的 Ollama / vLLM 上的 Qwen3、R1，和默认配置的 MiniMax M2，都把推理写在 content 里。
+ * 从前它们原样进正文：用户看见一大段思考，只有思考没有结论的一轮也不会被当成「没有回答」。
+ *
+ * 只认**正文最开头**（允许前导空白）的那个 `<think>`。正文中间出现的是模型在讨论这个标签，切了就是吞掉
+ * 回答。标签会被 SSE 切开（`<thi` / `nk>`），所以开头那几个字和结尾那几个字要扣着等下一个 chunk。
+ */
+export declare class ThinkTagSplitter {
+    /** 还没看到正文的第一个字 → 在 `<think>` 里 → 刚出 `</think>`、吃掉它后面的空行 → 正文。 */
+    private state;
+    private held;
+    push(chunk: string): ThinkSegment[];
+    /** 流结束：扣着的那一截按它所在的位置交出去。没闭合的 `<think>` 里的全是思考。 */
+    end(): ThinkSegment[];
+}
+export {};

package/dist/core/llm/ai/thinking-options.d.ts

@@ -0,0 +1,35 @@
+import type { ModelConfig, ThinkingLevel, ThinkingOption } from "../types/provider.ts";
+/** 标准档位，从浅到深。选中的档位模型没有时，按这个顺序就近找。 */
+export declare const THINKING_LEVELS: readonly ThinkingLevel[];
+/**
+ * 一组标准档位的选项。默认档是 `preferredDefault`（没给就是 medium）在这组里就近落到的那一档。
+ *
+ * 模型目录（pi 的 `thinkingLevelMap`）和模型编辑器都用它把「支持哪几档」变成模型配置里的
+ * `thinkingOptions`。列表里没有 `off`，就表示这个模型关不掉思考。
+ */
+export declare function thinkingOptionsFor(levels: readonly ThinkingLevel[], preferredDefault?: ThinkingLevel): ThinkingOption[];
+/**
+ * 没配置档位的模型用这一组：几乎所有推理接口都认的四档。
+ *
+ * 档位不再按模型名猜。按名字写死的表和厂商的实际能力对不上（给不认 `minimal` 的模型 `minimal`、
+ * 给关不掉思考的模型「关闭」），猜错了也不报错。真实档位从模型目录填入，或在模型编辑器里勾选。
+ */
+export declare const DEFAULT_THINKING_OPTIONS: ThinkingOption[];
+/**
+ * 模型可选的档位：配置了就用配置的，否则用默认那一组；不支持思考的模型一档都没有。
+ *
+ * 关不掉思考的模型（`vendors/` 的 `alwaysOn`）不给「关闭」：适配器对它们什么都不发，选了「关闭」照样思考、
+ * 照样计费，界面却显示已关。`catalogFill` 填配置时已经去掉，但没配档位的（默认那一组带 `off`）、在那之前
+ * 保存的配置都还带着，所以在这里统一再收一次。这里只有模型名、没有端点，只按模型名的规则判。
+ */
+export declare function resolveModelThinkingOptions(model?: ModelConfig | null): ThinkingOption[];
+/**
+ * 选中的档位在这个模型上实际是哪一档。
+ *
+ * 模型没有这一档时就近取：先往深找，再往浅找（和 pi 的 `clampThinkingLevel` 同一个规则）。
+ * 换模型后留下的「最高」落到新模型最深的那档，而不是退回默认的「中」；没有「关闭」的模型上
+ * 选「关闭」，落到它最浅的那档。只有不在标准序列里的自定义档位名才退回模型的默认档。
+ */
+export declare function resolveThinkingOption(level: ThinkingLevel, model?: ModelConfig | null): ThinkingOption | undefined;
+/** 发给接口的推理档位；`undefined` 表示关闭思考。和界面显示的是同一档。 */
+export declare function resolveReasoningEffort(level: ThinkingLevel | undefined, model?: ModelConfig | null): string | undefined;

package/dist/core/llm/ai/tool-names.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 工具名在流进来、发出去两头的规整。三条链共用，各自的 adapter / encoder 只调这里。
+ *
+ * 模型给的名字不一定合规：空的、两头带空白的，gpt-oss 经 vLLM 还会给出 `read<|channel|>commentary`。
+ * 工具找不到不要紧——那一轮照常以「工具不存在」收场；要紧的是那次调用留在了历史里，而两种 OpenAI 格式
+ * 对 `function.name` 要求 `^[a-zA-Z0-9_-]+$` 且非空，原样回放就是之后每一轮 400，没有学习器认领，会话报废。
+ */
+/** 流里收到的工具名：两头的空白去掉。别的不动——名字认不认得是执行那一层的事（`agent/tool-args.ts`）。 */
+export declare function toolNameFromStream(raw: unknown): string;
+/**
+ * 回放历史里一次工具调用时发的名字。
+ *
+ * 合规的名字原样返回，一个字节都不动——这在每一轮的整段历史上跑一遍，改动合规的名字会让提示缓存作废。
+ * 不合规的逐字符替换而不是换成固定占位：`read__channel__commentary` 比 `unknown_tool` 更能让模型看出自己
+ * 上次叫错了什么。只改名字不改 id，调用和结果的配对不受影响；名字也不参与配对（三种格式的结果都只带 id）。
+ */
+export declare function toolNameForReplay(name: string): string;

package/dist/core/llm/ai/tool-pairing-compat.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 一轮里的多个工具调用，`function_call` 和它们的结果该怎么排——问出来之后记住。
+ *
+ * 两家的要求直接冲突，一个全局形状满足不了：
+ *
+ *   - `api.deepseek.com` 的 Responses：**成组**。所有 `function_call`，然后所有 `function_call_output`。
+ *     交错排会被拒，而且它报的是
+ *     `The reasoning_text in the thinking mode must be passed back to the API.`——一句跟工具毫无关系的
+ *     话。推理项一个都不发时它报的还是这句，所以那不是字面意思，是它对工具配对问题的统一说法。
+ *   - 把 Responses 翻译成 Chat Completions 的中转：**交错**。它们把每个 `function_call` 变成一条独立的
+ *     助手消息，而 Chat Completions 要求带 `tool_calls` 的消息后面紧跟回答它的 tool 消息，于是两个调用
+ *     连排就成了两条背靠背的助手消息：
+ *     `an assistant message with 'tool_calls' must be followed by tool messages responding to each
+ *     'tool_call_id'. The following tool_call_ids did not have response messages: bash:0`
+ *
+ * 默认成组，不是因为哪家更重要，是因为**认错的代价不对称**：
+ *
+ *   - 默认成组、撞上要交错的中转时，它给的错误明确点名 `tool_call_ids`，一看就知道该换哪个形状，学得准。
+ *   - 默认交错、撞上要成组的端点时，它只会说「推理没带回来」。拿这句话去猜「其实是工具排错了」，猜不出来
+ *     ——这次就是这么埋了两个报废的会话，而且把排查带偏了一整天。
+ *
+ * 成组也是 Responses 协议本来的样子：结果靠 `call_id` 找它的调用，不靠位置。OpenAI 官方两种都收。
+ *
+ * **这个默认值的证据覆盖面**（写下来是因为将来有人质疑它时，第一个该看的就是这个）：2026-09-11 用
+ * `test/tool-pairing-survey-probe.ts` 普查了用户配置里的 2 个 Responses 端点，各发三次（单个调用做对照、
+ * 交错、成组）——
+ *
+ *   - `api.deepseek.com` / `deepseek-flash`：对照 200，交错 400，成组 200 → **只收成组**
+ *   - 某中转 / `claude-opus-4-6-thinking`：三发全 400，连单个调用的对照都拒，理由与排列无关 → 对照作废
+ *
+ * 也就是**有效样本 n=1**，而且没有任何现存端点被证明需要交错。要交错的那条路来自更早的一次真实报障
+ * （错误原文见上），那个端点已不在用户的配置里，所以它现在无法复验。样本这么小仍然改默认值，靠的是上面
+ * 那条不对称，不是样本量——这一点必须诚实写在这里。
+ *
+ * 和 `reasoning-compat.ts` 是**两个独立的轴**，各学各的。上一版把「发几块推理」和「一块里带哪些字段」
+ * 压进同一条梯子，结果是端点说 A、梯子退 B，对不上号的时候只能靠碰巧。同一个错误不犯第二次。
+ *
+ * 记在内存里，不落盘——理由同 `reasoning-compat.ts`：重启后重学一次的代价是一次自愈重发，换来不必做
+ * 设置迁移，也不必担心一条学错的结论永久粘在用户的配置里。
+ */
+/** 一轮里多个工具调用的排法。 */
+export type ToolPairing = "grouped" | "interleaved";
+/** 这个模型该怎么排。默认成组，理由见文件头。 */
+export declare function toolPairing(providerId: string, modelId: string): ToolPairing;
+/**
+ * 从一次失败里学点东西。返回「结论变了，值得换个形状重发一次」。
+ *
+ * 只有一个方向：成组 → 交错。反向不学——要成组的那家给的错误话里没有任何能指认排列问题的东西（见文件头），
+ * 拿它当信号只会误判。成组已经是默认，真需要反向时应该是有人拿着新证据来改这里，而不是让它自己猜。
+ */
+export declare function learnToolPairing(providerId: string, modelId: string, error: string): boolean;
+/** 测试用：把学到的都忘掉。 */
+export declare function resetToolPairingCompat(): void;