@plumeai/plugin-sdk 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,24 @@
+/**
+ * Where a tool result's image goes on the Responses API — learned from the endpoint, then kept.
+ *
+ * The protocol puts it inside the result: `function_call_output.output` may be a list with
+ * `input_image` parts, and that is the default. Relays that translate Responses into Chat
+ * Completions do not all carry that across. Measured 2026-09-27 on a relay serving `glm-5.3-flash`
+ * (an MCP tool returning a screenshot), the request with the image was refused outright:
+ *
+ *     Upstream request failed: [invalid_value] messages[5]: tool content: part type "image_url"
+ *     is not supported; only text is
+ *
+ * and not once: the image stays in history, so every later request in that conversation would be
+ * refused the same way. Having been told, the image moves to a user message right after the
+ * results — the shape Chat Completions uses anyway — and the request is sent again.
+ *
+ * In memory only, like the other compat axes: relearning after a restart costs one refused request.
+ */
+/** `inline`: inside `function_call_output`. `lifted`: in a user message after the results. */
+export type ToolResultImages = "inline" | "lifted";
+export declare function toolResultImages(providerId: string, modelId: string): ToolResultImages;
+/** Learn from one failure. Returns "the conclusion changed, worth resending in the new shape". */
+export declare function learnToolResultImages(providerId: string, modelId: string, error: string): boolean;
+/** For tests: forget everything learned. */
+export declare function resetToolResultImagesCompat(): void;

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

@@ -0,0 +1,20 @@
+/**
+ * 工具参数 schema 发出去之前、三种格式都要做的改写。各家专有的规整（Anthropic 的关键字白名单）留在各自的
+ * encoder 里；这里只放对所有端点都语义等价的那种。
+ */
+/**
+ * 指向 `$defs` 以外的本地 `$ref`（`#/properties/a`、`#/definitions/X`），目标复制进 `$defs`、引用改指过去。
+ *
+ * MCP 服务器的 schema 常这样复用前面某个属性的定义。Kimi 的工具 schema 要守 MFJS 规范：「`$defs` must be
+ * defined at the schema root level; `$ref` only supports referencing internal subschemas … indexed through
+ * `$defs`」（github.com/MoonshotAI/walle docs/mfjs-spec.md），原样发出过不了校验——装了那个 MCP，之后每一轮
+ * 都 400。搬过去之后引用解析到的是同一个形状，对认任意 JSON Pointer 的端点也毫无差别，所以不挂在厂商上、
+ * 三种格式一律做。
+ *
+ * 搬走的目标原处不留第二份：`definitions` 里的删掉（删空了整个去掉），别处的换成指向 `$defs` 的引用。否则
+ * 同一份定义每轮在工具列表里发两遍。
+ *
+ * 没有这种引用时返回**原来那个对象**：这在每一轮的工具列表上跑一遍，绝大多数 schema 都不会走到改写。解析
+ * 不到的引用和外部引用不动、也不抛——改不了的交给端点判，至少不比原来更糟。
+ */
+export declare function hoistLocalRefs<T>(schema: T): T;

package/dist/core/llm/ai/usage-fields.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 三条协议的用量字段：每个桶从哪几个字段读、按什么顺序回退、`input` 里含不含缓存。
+ *
+ * 从前三个适配器各写一段 `if (typeof raw.xxx === "number")`，Chat 链只认 `prompt_tokens_details.cached_tokens`、
+ * 缓存写入写死 0——DeepSeek 的命中数在 `prompt_cache_hit_tokens`、Kimi 的在顶层 `cached_tokens`，于是这两家
+ * 的缓存命中在账上一直是 0、全按原价算。服务商每多一个，三处就各要改一遍，改漏一处就是一条账不对。
+ *
+ * 现在只有一张表（`USAGE_DIALECTS`）。**新增一个服务商变体 = 在对应协议、对应桶的列表里加一行**，
+ * 写明字段路径和出处；解析逻辑一个字都不用动。
+ *
+ * 四个桶（input / output / cacheRead / cacheWrite）必须不重叠——用量页和计价器都是四个桶直接相加，
+ * 重叠一份就算两遍钱。`reasoning` 不是第五个桶，它是 output 里的一部分，只用于展示。
+ */
+import type { ApiFormat, Usage } from "../types.ts";
+/** 表里能声明的桶。 */
+export type UsageBucket = "input" | "output" | "cacheRead" | "cacheWrite" | "reasoning";
+/**
+ * 按协议读出这一帧里出现了的桶。没出现的桶不在结果里——调用方据此决定「不动」而不是「清零」。
+ *
+ * 「`input` 含缓存」的协议有一条额外约束：input 和它含着的那几个桶**一起给、一起更新**。给了 input
+ * 却没给缓存字段，缓存桶就是 0，不能沿用上一帧的值——否则扣的和存的不是同一个数，桶又重叠了。
+ */
+export declare function readUsage(api: ApiFormat, raw: Record<string, unknown>): Partial<Record<UsageBucket, number>>;
+/**
+ * 把一帧用量合进 `usage`：出现了的桶覆盖，没出现的不动，`total` 跟着重算。
+ *
+ * 「没出现的不动」是 Anthropic 那条链要的：`message_start` 带输入和缓存，`message_delta` 通常只带
+ * `output_tokens`，清零会把前一帧的输入抹掉。费用不在这里算，见 `priceAttempt`。
+ */
+export declare function applyUsage(api: ApiFormat, usage: Usage, raw: unknown): void;

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

@@ -0,0 +1,20 @@
+/**
+ * 厂商特例的唯一去处。
+ *
+ * 这里只放**事先就知道、又学不会**的事：端点不报错只是静默忽略（发 `budget_tokens` 给只认 effort 的模型），
+ * 或者报了错但报得认不出（Gemini 2.5 的 `invalid argument`），以及省掉一次必然的 400（新 Claude 的 adaptive）。
+ * 端点会报错并点名原因的，走「撞出来再学」的那几张表（`request-params-compat.ts`、`reasoning-compat.ts`、
+ * `tool-pairing-compat.ts`、Anthropic 链的 `learnAdaptiveThinking`），不写这里。
+ *
+ * 从前这些先验散在三个适配器里，同一件事在一条链上有、另一条链上没有，Gemini 关思考在 Chat 链上全挂就是
+ * 这么来的。现在适配器只问这里。
+ *
+ * 加一条的门槛：撞到过、或者官方文档写明了，而且学习表认领不了。只照着别家产品的内置表抄来的不加——
+ * 模型名正则随版本过期，每一条都是要人看着的维护负担，而判错的代价多半只是档位没送到。
+ */
+import type { ResolvedThinking } from "./types.ts";
+/** 这个端点上的这个模型，思考开关该怎么写。 */
+export declare function thinkingDialect(endpoint: string, modelId: string): ResolvedThinking;
+/** 缓存在这一家能留多久；没有规则时是 undefined，由调用方用自己的默认值。 */
+export declare function cacheHotMs(endpoint: string, modelId: string): number | undefined;
+export type { ResolvedThinking } from "./types.ts";

package/dist/core/llm/ai/vendors/thinking.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 把 `thinkingDialect` 查到的写法翻成三种格式各自的请求体字段。
+ *
+ * 适配器只做一件事：把这里返回的对象展开进请求体。写法的选择在 `index.ts`，学到的结论（adaptive、被撤掉的
+ * 参数）由适配器查好传进来——这里不碰任何一张学习表，所以是纯函数，能直接测。
+ */
+import type { AnthropicThinkingOn, ResolvedThinking } from "./types.ts";
+type Fields = Record<string, unknown>;
+export interface AnthropicThinkingInput {
+    /** 开着时的档位；`undefined` 表示关着。 */
+    effort: string | undefined;
+    /**
+     * 没填（`undefined`）时开着照发——从前就是这样；关着时什么都不发：不知道这个模型有没有思考，就别给
+     * 它发一个它可能不认的 `thinking` 字段，被拒了也没有哪条学习轴能撤掉它。
+     */
+    supportsThinking: boolean | undefined;
+    budget: number | undefined;
+    maxTokens: number;
+    /** 这个模型撞出过「不认 budget_tokens」。只在写法本来是 `budget` 时起作用。 */
+    learnedAdaptive: boolean;
+}
+/** 这一次实际用哪种写法开思考。budget 写法要校验 budget、要带交错思考的头，适配器靠它判断。 */
+export declare function anthropicThinkingOn(dialect: ResolvedThinking, learnedAdaptive: boolean): AnthropicThinkingOn;
+export declare function anthropicThinkingFields(dialect: ResolvedThinking, input: AnthropicThinkingInput): Fields;
+export interface OpenAiThinkingInput {
+    /** 开着时的档位；`undefined` 表示关着。 */
+    effort: string | undefined;
+    supportsThinking: boolean | undefined;
+    /** 这个端点撞过之后要求别发的参数，见 `request-params-compat.ts`。 */
+    dropped: ReadonlySet<string>;
+}
+/** Chat Completions。关着时 `reasoning_effort: "none"` 撞过就撤（`reasoning-off`）。 */
+export declare function chatThinkingFields(dialect: ResolvedThinking, input: OpenAiThinkingInput): Fields;
+/**
+ * Responses。摘要要组织验证过才给，没验证的账号整个请求 400——撞过就只撤它（`reasoning-summary`），effort
+ * 照发；密文同理（`include-encrypted`）。关着时 `effort: "none"` 撞过就撤（`reasoning-off`）。
+ */
+export declare function responsesThinkingFields(dialect: ResolvedThinking, input: OpenAiThinkingInput): Fields;
+export {};

package/dist/core/llm/ai/vendors/types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 厂商特例的描述方式。见 `index.ts` 顶上那段：为什么有这一层、和「撞出来再学」的那几张表怎么分工。
+ *
+ * 一条规则只是数据：在哪些模型 / 端点上、思考开关在每种格式下该怎么写。怎么把它翻成请求体是 `thinking.ts`
+ * 的事，适配器只问结果，不认识任何一家厂商。
+ */
+/**
+ * Anthropic 格式开思考的写法。
+ *
+ *   - `budget`：`thinking: {type: "enabled", budget_tokens}`。默认；端点点名不认时会学成 `adaptive`。
+ *   - `adaptive`：`thinking: {type: "adaptive"}` + `output_config.effort`。
+ *   - `enabled-effort`：`thinking: {type: "enabled"}` + `output_config.effort`——认 effort、忽略 budget 的兼容端点。
+ *   - `effort-only`：只发 `output_config.effort`，不发 `thinking`——请求结构里根本没有这个字段的端点。
+ */
+export type AnthropicThinkingOn = "budget" | "adaptive" | "enabled-effort" | "effort-only";
+/** 一个模型族在思考开关上的脾气。只写和默认不同的那几项，其余由 `index.ts` 的默认值补齐。 */
+interface ThinkingDialect {
+    anthropic?: AnthropicThinkingOn;
+    /** Chat Completions 关思考时不收 `reasoning_effort: "none"`，整个字段不发。 */
+    chatRefusesNone?: boolean;
+    /** Responses 关思考时不收 `reasoning: {effort: "none"}`，整个 `reasoning` 不发。 */
+    responsesRefusesNone?: boolean;
+    /** Responses 上每个助手轮都要以推理项开头（DeepSeek）。见 `openai-responses-request.ts` 的补位分支。 */
+    leadingReasoning?: boolean;
+    /**
+     * 关不掉：服务端强制思考，发关闭参数会报错。界面上不给「关闭」，请求里也不发关闭参数。
+     */
+    alwaysOn?: boolean;
+}
+/** 补齐默认值之后的结果。适配器拿到的就是这个。 */
+export type ResolvedThinking = Required<ThinkingDialect>;
+/** 一条规则。`model` 和 `endpoint` 都写时两个都要命中；要「任一命中」就写成两条。 */
+export interface VendorRule {
+    /** 线上模型名（`model.modelId`）。不写表示不看模型。 */
+    model?: RegExp;
+    /** 端点地址（`provider.baseUrl`）。不写表示不看端点。 */
+    endpoint?: RegExp;
+    thinking: ThinkingDialect;
+    /**
+     * 同一前缀隔多久以内多半还读得到缓存，毫秒。不写就用分叉的默认值（`compaction-fork.ts` 的 `FORK_HOT_MS`，
+     * 按最短的常见有效期定）。写错的代价是一次压缩：分叉时缓存已凉，完整历史按原价读一遍。
+     */
+    cacheHotMs?: number;
+    /** 出处：官方原话、实测记录。说不出出处的不要加。 */
+    source: string;
+}
+export {};

package/dist/core/llm/config/image-models.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Which configured models draw pictures, and which one a request means.
+ *
+ * Browser-safe on purpose: the chat picker has to leave these out and the
+ * settings page has to list them, and both are the renderer. Nothing here imports a value.
+ */
+import type { ModelConfig, ProviderConfig } from "../types/provider.ts";
+export declare function isImageModelId(modelId: string): boolean;
+/** A stored choice first; the name only when nobody has said. */
+export declare function isImageModel(model: Pick<ModelConfig, "modelId" | "imageOutput">): boolean;
+export interface ImageModelRow {
+    provider: ProviderConfig;
+    model: ModelConfig;
+}
+/** Every image model on an enabled provider, in the order they are configured. */
+export declare function imageModelRows(providers: readonly ProviderConfig[] | undefined): ImageModelRow[];
+/**
+ * The image model a call means.
+ *
+ * `asked` is whatever the conversation named — "gpt-image-2.5", "Nano Banana" — so it is matched the
+ * way a person would mean it: the local id, then the provider's id or the display name exactly, then
+ * a unique partial match. An ambiguous or unknown name is not quietly replaced by the default: the
+ * person asked for a particular model, and drawing with another one is the wrong answer billed to them.
+ *
+ * Without `asked`, the configured default (`Settings.imageModelId`) if it still resolves, else the
+ * first image model there is.
+ */
+export declare function resolveImageModel(providers: readonly ProviderConfig[] | undefined, preferred: string | null | undefined, asked?: string): {
+    row: ImageModelRow;
+} | {
+    row?: undefined;
+    reason: "none" | "unknown" | "ambiguous";
+    candidates: ImageModelRow[];
+};

package/dist/core/llm/config/retry-policy.d.ts

@@ -0,0 +1,35 @@
+export interface RetryRule {
+    /** Retries after the initial request; null means until cancelled. */
+    retries: number | null;
+    strategy: "fixed" | "linear";
+    intervalMs: number;
+    maxIntervalMs: number;
+}
+export interface RetryPolicy {
+    network: RetryRule;
+    upstream: RetryRule;
+}
+export type RetryFailure = keyof RetryPolicy;
+/**
+ * A policy, or a way to read the current one.
+ *
+ * A request that is retrying every five seconds until the network comes back can outlive several
+ * visits to the settings page, and taking a copy at the start meant those edits reached it only
+ * after it had finished — which for the unlimited rule is never. Handed a function instead, the
+ * budget reads the live setting before each wait, so raising a limit or shortening an interval
+ * applies from the next retry on. Callers with a fixed policy of their own still pass a value.
+ */
+export type RetryPolicySource = RetryPolicy | (() => RetryPolicy | undefined);
+export declare const DEFAULT_RETRY_RULE: RetryRule;
+export declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+/** Separate fault policies, each bounded the same way wherever it was written. */
+export declare function normalizeRetryPolicy(value: unknown): RetryPolicy;
+/**
+ * How long this wait is. A fixed interval carries ±20% jitter; on average it is still the setting.
+ *
+ * It was deliberately exact once, so that "every 5 seconds" meant exactly that. The cost: when a relay
+ * hiccups, every client on it drops at the same instant and comes back in lockstep every 5 seconds,
+ * knocking the recovering end over on the same beat each time. A second either way makes no
+ * difference to the person waiting. `random` is injected only by tests.
+ */
+export declare function policyDelay(policy: RetryRule, retry: number, random?: () => number): number;

package/dist/core/llm/images/chat-images.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Drawing through a chat completion that is asked for image output.
+ *
+ * The route for hosts that never grew an Images API — OpenRouter, and the Gemini models that write and
+ * draw on endpoints that only speak chat. The request is an ordinary user turn with
+ * `modalities: ["image", "text"]`; the picture comes back in one of three places depending on who
+ * translated the upstream answer, and all three are read.
+ */
+import type { ModelConfig, ProviderConfig } from "../types/provider.ts";
+import type { ImageCallOptions, ImageRequest, ImageResult } from "./types.ts";
+export declare function viaChatCompletions(provider: ProviderConfig, model: ModelConfig, request: ImageRequest, options: ImageCallOptions): Promise<ImageResult>;

package/dist/core/llm/images/dimensions.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Width and height out of an image's own header.
+ *
+ * The card holds the picture's place at its real shape before the bytes have loaded, and the model is
+ * told what it got. Asking the provider is not enough: the Images API reports a requested size, not
+ * the delivered one, and a relay in front of Gemini reports nothing at all. PNG, JPEG and WebP — what
+ * image models return — and `null` for anything else rather than a guess.
+ */
+export interface Dimensions {
+    width: number;
+    height: number;
+}
+export declare function imageDimensions(bytes: Uint8Array): Dimensions | null;
+/** The MIME type the bytes actually are, which is not always what the response claimed. */
+export declare function sniffImageType(bytes: Uint8Array): string | null;

package/dist/core/llm/images/generate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Draw with an image model, through whichever endpoint its provider actually has.
+ *
+ * There is no field that says. An OpenAI-compatible base URL may serve the Images API, chat
+ * completions with image output, or both, and which one is a property of the host and the model
+ * together: the same Gemini model is reachable through `/v1/images` on one relay and only through chat
+ * on OpenRouter. So the first call tries the likelier route, a "this endpoint is not here" answer
+ * switches to the other, and the route that worked is remembered for the rest of the run — one wasted
+ * request per model per launch, not per picture.
+ */
+import type { ModelConfig, ProviderConfig } from "../types/provider.ts";
+import type { ImageCallOptions, ImageRequest, ImageResult } from "./types.ts";
+/** Forget the routes learned so far. For tests. */
+export declare function resetImageRoutes(): void;
+export declare function generateImages(provider: ProviderConfig, model: ModelConfig, request: ImageRequest, options?: ImageCallOptions): Promise<ImageResult>;

package/dist/core/llm/images/openai-images.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Drawing through the OpenAI Images API: `/v1/images/generations`, and `/v1/images/edits` when there
+ * are pictures to work from.
+ *
+ * The common denominator: OpenAI's own image models, and the relays that put Gemini, Flux or Seedream
+ * behind the same two endpoints. A chat-only host answers 404 here, and `generate.ts` takes that as
+ * the cue to try a chat completion instead.
+ */
+import type { ModelConfig, ProviderConfig } from "../types/provider.ts";
+import type { ImageCallOptions, ImageRequest, ImageResult } from "./types.ts";
+export declare function viaImagesApi(provider: ProviderConfig, model: ModelConfig, request: ImageRequest, options: ImageCallOptions): Promise<ImageResult>;

package/dist/core/llm/images/quota.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A spent quota, told apart from a busy moment before anything waits on it.
+ *
+ * Both arrive as 429. A busy moment is worth a retry a second later; a spent quota answers the same
+ * for hours — Antigravity says "Your quota will reset after 1h52m45s" — and every retry against it is
+ * a turn held open with the card spinning, for an answer that was already final. So the response is
+ * read before the retry loop sees it, and a spent quota leaves as final, with the wait it named.
+ */
+export declare function quotaGuard(doFetch: typeof globalThis.fetch): typeof globalThis.fetch;

package/dist/core/llm/images/shape.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The shape and detail a picture is asked for in, said the way each model family understands it.
+ *
+ * The tool speaks in aspect ratios because that is what a person asks for ("a 16:9 banner") and what
+ * the card needs to hold the picture's place. Providers each want their own spelling, and a wrong one
+ * is refused outright rather than approximated:
+ *
+ * - OpenAI's lines take a short list of pixel sizes each.
+ * - A relay in front of Gemini (CliRelay) takes `aspect_ratio` and `image_size` (`512`, `1K`, `2K`,
+ *   `4K`), refuses `"16:9"` as a `size`, and ignores `quality` — so detail has to travel as
+ *   `image_size` or it is lost.
+ * - Anything else gets a pixel size in the ratio's proportions, which hosts with fixed sizes snap to.
+ */
+import type { ImageRequest } from "./types.ts";
+export declare const ASPECT_RATIOS: readonly ["1:1", "4:3", "3:4", "3:2", "2:3", "16:9", "9:16", "21:9", "5:4", "4:5"];
+export declare const QUALITIES: readonly ["low", "medium", "high", "max"];
+/** `"16:9"` as numbers, or `null` for `auto`, empty, or anything that is not a ratio. */
+export declare function parseRatio(value: string | undefined): {
+    width: number;
+    height: number;
+} | null;
+/**
+ * The fields of an Images API request that depend on the model, beyond `model`, `prompt` and `n`.
+ *
+ * Unknown fields are not sent to a family that might refuse them: OpenAI answers an unrecognised
+ * parameter with a 400.
+ */
+export declare function imageFields(modelId: string, request: Pick<ImageRequest, "aspectRatio" | "quality" | "background">): Record<string, string>;
+/**
+ * How many pictures one request may ask for.
+ *
+ * DALL·E 3 draws one per request. A relay in front of Gemini runs `n` one after another and fails the
+ * lot if any one fails, so pictures there are asked for one per request — side by side, which is also
+ * faster than its own queue.
+ */
+export declare function perRequestLimit(modelId: string): number;
+/**
+ * Whether an edit goes as JSON with data URLs rather than multipart.
+ *
+ * The relay takes both for Gemini, and refuses a disallowed model on JSON with a clear 403 where the
+ * multipart form gets past its model check and fails later as a bare 502. OpenAI's own edits endpoint
+ * is multipart only.
+ */
+export declare function editsAsJson(modelId: string): boolean;

package/dist/core/llm/images/types.d.ts

@@ -0,0 +1,118 @@
+/**
+ * A request to draw, and what comes back — independent of which endpoint does the drawing.
+ */
+import type { RetryPolicySource } from "../config/retry-policy.ts";
+import type { RequestOptions } from "../types/provider.ts";
+/** The tool's name, in one place: the transcript is searched for its results by it. */
+export declare const IMAGE_TOOL_NAME = "image_generate";
+/** An image going in: something to edit, or to draw after. */
+export interface ImageInput {
+    /** base64, no `data:` prefix. */
+    data: string;
+    mimeType: string;
+    /** A file name for the multipart upload; some endpoints reject a part without one. */
+    name?: string;
+}
+export interface ImageRequest {
+    prompt: string;
+    /** Present means an edit: these are the pictures the prompt is about. */
+    images?: ImageInput[];
+    /** `"16:9"` and friends; absent or `auto` leaves the shape to the model. */
+    aspectRatio?: string;
+    /** `max` is the largest the model offers — 4K on Gemini — and is slow to arrive over a relay. */
+    quality?: "low" | "medium" | "high" | "max";
+    count?: number;
+    background?: "transparent" | "opaque";
+}
+export interface GeneratedImage {
+    data: string;
+    mimeType: string;
+}
+/** Which endpoint drew it: the Images API, or a chat completion asked for image output. */
+export type ImageRoute = "images" | "chat";
+export interface ImageResult {
+    images: GeneratedImage[];
+    /** What the provider says it actually drew from, when it rewrote the prompt. */
+    revisedPrompt?: string;
+    route: ImageRoute;
+    usage?: {
+        input?: number;
+        output?: number;
+        total?: number;
+    };
+    /** Why the pictures that did not arrive did not, when only some of several did. */
+    failures?: string[];
+}
+export interface ImageCallOptions {
+    signal?: AbortSignal;
+    fetch?: typeof globalThis.fetch;
+    retryAttempts?: number;
+    retryPolicy?: RetryPolicySource;
+    onRetry?: RequestOptions["onRetry"];
+}
+/** A picture already in the conversation, not yet read: inline pixels or a file under `session-media`. */
+export interface ImagePointer {
+    data?: string;
+    media?: string;
+    mimeType: string;
+}
+/**
+ * What `image_generate` hands the window: once as the call starts, so the place can be held at the
+ * right shape before anything arrives, and again in the result.
+ */
+export interface ImageGenerateDetails {
+    kind: typeof IMAGE_TOOL_NAME;
+    /** As asked, `"16:9"`; absent for `auto`. */
+    aspectRatio?: string;
+    count: number;
+    /**
+     * The pictures that went in, by `session-media` name, in the order they were given.
+     *
+     * What makes a picture's history drawable in the gallery: the dog, the dog in a hat, the girl
+     * holding it. Absent on results written before it existed; those are traced back from the call's
+     * own `#1`/path arguments instead (`lineage.ts`).
+     */
+    sources?: string[];
+    /**
+     * The shape the picture will most likely come back in, when none was asked for: an edit keeps the
+     * shape of the picture it starts from. Width over height.
+     *
+     * Without it the place was a square, and an edit of a wide picture landed as a square snapping to
+     * its real shape — the card, and everything under it, jumping on the frame the picture arrived.
+     */
+    shapeHint?: number;
+    /** Which model, by id and by the name the card shows; with the two below, what the estimate is timed against. */
+    model?: string;
+    modelName?: string;
+    quality?: string;
+    /** Pictures went in: an edit, which takes a little longer. */
+    edit?: boolean;
+    startedAt?: number;
+    /** The wait the call is in, while it is in one: the card says so instead of a stage that is not happening. */
+    retry?: {
+        attempt: number;
+        delayMs: number;
+        reason: string;
+    };
+    /** Why it failed, for the card: a spent quota or a key without the model is something the user acts on. */
+    error?: {
+        summary: string;
+        detail?: string;
+        hint?: string;
+        retryAfterMs?: number;
+    };
+    /** The rest is there once it has drawn. */
+    /** Where each picture was saved, in the order of the pictures. */
+    paths?: string[];
+    /** The same pictures by `session-media` name, with the size read from their headers: what `#N` and the card read. */
+    images?: {
+        media: string;
+        mimeType: string;
+        width?: number;
+        height?: number;
+    }[];
+    references?: number;
+    route?: ImageRoute;
+    revisedPrompt?: string;
+    failures?: string[];
+}

package/dist/core/llm/model-catalog-format.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 模型目录的数据格式：类型、校验，以及把 pi 的原始目录压成这个格式。
+ *
+ * 单独成文件而不放在 `model-catalog.ts`：那边一加载就要校验打包的快照，生成快照的脚本和远程同步
+ * 不能依赖一份可能还是旧格式的快照。这里没有状态，也不碰文件系统和网络。
+ */
+import type { ModelPricingTier, ThinkingLevel } from "./types/provider.ts";
+/** 唯一的目录来源：pi 的公开模型目录。 */
+export declare const MODEL_CATALOG_URL = "https://pi.dev/api/models";
+export interface CatalogModel {
+    id: string;
+    name: string;
+    /** 这个条目所在端点。个别条目为空或带占位符，那样的只能按型号参考，匹配不到端点。 */
+    baseUrl: string;
+    contextWindow: number;
+    maxOutputTokens: number;
+    supportsThinking: boolean;
+    /** 可选的思考档位，按 pi 的 `thinkingLevelMap` 折算（见 `thinkingLevels`）。只在支持思考时有。 */
+    thinkingLevels?: ThinkingLevel[];
+    supportsImages: boolean;
+    inputPrice?: number;
+    outputPrice?: number;
+    cacheReadPrice?: number;
+    cacheWritePrice?: number;
+    tiers?: ModelPricingTier[];
+}
+export interface CatalogProvider {
+    id: string;
+    models: CatalogModel[];
+}
+export interface ModelCatalogDocument {
+    /** 3：条目带上思考档位。旧格式的缓存整份不认，下次同步重新拉。 */
+    schema: 3;
+    source: {
+        name: string;
+        url: string;
+        /** 上游给的目录版本号（`x-pi-model-catalog-revision`），也进计价缓存的 key。 */
+        revision: string;
+        /** 上游的 `last-modified`：远程目录只在比当前的新时才换上。 */
+        updatedAt: string;
+    };
+    providers: CatalogProvider[];
+}
+/** 校验一份目录。远程拉来的内容走同一道校验，不合法就整份拒绝，不会半套生效。 */
+export declare function parseModelCatalog(value: unknown): ModelCatalogDocument;
+/**
+ * pi 目录（`{ 供应商 id: { 模型 id: 条目 } }`）压成自己的目录格式，只留上限、思考与档位、图片、端点和价格。
+ * 字段不全的条目跳过，不猜。
+ */
+export declare function compactPiCatalog(raw: unknown, source: ModelCatalogDocument["source"]): ModelCatalogDocument;

package/dist/core/llm/model-catalog.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 模型目录：一个模型的上下文窗口、最大输出、思考能力与档位、图片能力，以及参考价格，都从这里查。
+ *
+ * 数据来自 pi 的公开模型目录（https://pi.dev/api/models）。仓库里打包一份压缩过的快照
+ * `catalog/model-catalog.json`，桌面主进程运行时定期拉最新的换上（`model-catalog-sync.ts`），
+ * 所以离线也能用，联网时自动更新。这个文件不碰文件系统和网络——渲染进程也要用它。
+ *
+ * 目录只是参考：导入模型、在编辑器里搜索选中时，把条目的上限、能力、思考档位和价格一次性填进模型配置，
+ * 之后配置归用户，目录更新不会改动它。用量页给没有配置价格的历史记录估算费用时也查这里。
+ *
+ * 自动匹配顺序：同一端点（Base URL）下的同名模型 → 按型号家族找厂商官方条目和 OpenRouter 的参考值。
+ * 发送给供应商的模型 ID 从不改写。
+ */
+import { type CatalogModel, type CatalogProvider, type ModelCatalogDocument } from "./model-catalog-format.ts";
+import type { ModelConfig, ModelPricing, ProviderConfig } from "./types/provider.ts";
+export type { CatalogModel, CatalogProvider, ModelCatalogDocument } from "./model-catalog-format.ts";
+export interface CatalogMatch {
+    provider: CatalogProvider;
+    model: CatalogModel;
+    match: "exact" | "alias" | "reference";
+}
+/** 从目录填进模型配置的那几项。 */
+export type CatalogFill = Pick<ModelConfig, "contextWindow" | "maxOutputTokens" | "supportsThinking" | "thinkingOptions" | "supportsImages" | "supportsTools" | "pricing">;
+/**
+ * 目录里找不到时的初始值：新建模型和导入时没匹配上的模型用它。
+ *
+ * 能力全开：这一档接的是中转起的私有名字、刚发布的型号、自建端点，如今几乎都会思考、看图、调工具。
+ * 猜错的代价不对等——开着而不支持，供应商回一个说得清楚的错；关着而支持，是能力凭空少一块还不报错。
+ */
+export declare const DEFAULT_MODEL_LIMITS: Omit<CatalogFill, "pricing">;
+/** 当前生效的目录：打包的那份，或更新过的远程版本。 */
+export declare function activeModelCatalog(): ModelCatalogDocument;
+/** 目录版本，进计价缓存的 key 和价格快照：目录一换，旧的估价重算。 */
+export declare function modelCatalogVersion(): string;
+/**
+ * 换上一份目录，只在它比当前的新时生效。返回是否真的换了。
+ *
+ * 按 `updatedAt` 比而不是无条件替换：应用升级后打包的快照可能比本地缓存的远程版本还新。
+ */
+export declare function installModelCatalog(document: ModelCatalogDocument): boolean;
+/** 测试用：回到打包的快照。 */
+export declare function resetModelCatalog(): void;
+export declare function catalogModelFor(provider: Pick<ProviderConfig, "baseUrl">, modelId: string): CatalogMatch | null;
+export declare function catalogPricing(model: CatalogModel): ModelPricing | undefined;
+/**
+ * 一个目录条目要填进模型配置的值。输出上限不超过窗口；全零价格的订阅制条目不填价格。
+ *
+ * 关不掉思考的模型（`vendors/` 的 `alwaysOn`）不给「关闭」这一档：目录里的档位不一定知道这一点，而界面上
+ * 多一个点了没用的「关闭」，用户以为省了钱。给了端点就连端点一起看，规则可以按端点写。
+ */
+export declare function catalogFill(model: CatalogModel, provider?: Pick<ProviderConfig, "baseUrl">): CatalogFill;