@reinsjs/lowering-fetch 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,855 @@
+import * as _reinsjs_core from '@reinsjs/core';
+import { Event, ContentPart, SystemNotePayload, LandingRecord, TokenUsage, LoweringStreamContext, CoreEventDraft, LoweringOutcome, LandingSpec, ModelRef, LoweringCapabilities, ToolSpec, BoundModel, Lowering, ToRequestInput, LoweredRequest, LossMatrix } from '@reinsjs/core';
+
+/**
+ * 事件 → 中间表示（IR）：三条线协议共用的一趟遍历。
+ *
+ * 这一步只做与协议无关的事：
+ * 1. **分组**——连续的 model 事件（thinking / text / tool_call）合成一条 assistant 轮，遇到非 model 事件或来源变了就收口；
+ * 2. **后移**——"同批 tool_result 必须紧跟 tool_use"是厂商硬规则，而时间线里说明、摘要、用户插话都可能落在两者之间；
+ *    结果没到齐时它们先攒着，到齐后按原顺序放出（`deferred: true`）。日志顺序不动（宪法二），只在翻译产物里挪位；
+ * 3. **trust 标注**——untrusted 内容包 `<untrusted source=…>`（core 的同一份纯函数），转义过的记 `escaped`。
+ *
+ * 每种事件落到线协议的哪个位置、算 exact 还是 lossy，由各协议的 encoder 决定并记 LandingRecord；IR 只提供判定所需的事实。
+ * 输出顺序就是线上顺序；`orderLandings` 把 encoder 记下的落点按输入事件顺序排回去（LoweredRequest.landings 的契约）。
+ */
+
+/** 模型事件 replay 里记录的来源，产出与回放两头共用（与 lowering-pi 同字段，两条路线的事件可互换） */
+interface ModelOrigin {
+    provider: string;
+    api: string;
+    model: string;
+}
+type IrBlock = {
+    type: "thinking";
+    event: Event;
+    text: string;
+    replay: Record<string, unknown>;
+} | {
+    type: "text";
+    event: Event;
+    text: string;
+    replay: Record<string, unknown>;
+} | {
+    type: "tool_call";
+    event: Event;
+    id: string;
+    name: string;
+    args: unknown;
+    replay: Record<string, unknown>;
+};
+type IrItem = {
+    kind: "user";
+    event: Event;
+    parts: ContentPart[];
+    escaped: boolean;
+    deferred: boolean;
+} | {
+    kind: "assistant";
+    origin: ModelOrigin;
+    blocks: IrBlock[];
+    at: number;
+} | {
+    kind: "tool_result";
+    event: Event;
+    toolCallId: string;
+    name: string;
+    parts: ContentPart[];
+    isError: boolean;
+    escaped: boolean;
+} | {
+    kind: "system_note";
+    event: Event;
+    noteKind: SystemNotePayload["kind"];
+    text: string;
+    escaped: boolean;
+    deferred: boolean;
+} | {
+    kind: "compaction";
+    event: Event;
+    text: string;
+    escaped: boolean;
+    deferred: boolean;
+}
+/** 运维事件与 ext.*：不下发，encoder 只记落点 */
+ | {
+    kind: "dropped";
+    event: Event;
+    note: string;
+};
+interface IrInput {
+    events: readonly Event[];
+    /** 当前请求的目标模型：replay 没写来源的模型事件按它算 */
+    target: ModelOrigin;
+    /** trust=untrusted 的内容包 <untrusted source=…>（§14）。缺省 true；关掉是宿主自担风险 */
+    trustMarkers?: boolean;
+}
+declare function sameOrigin(a: ModelOrigin, b: ModelOrigin): boolean;
+/**
+ * 是否来自别家：只比 provider 与 api。响应里报告的模型 id 常与请求的不同（日期后缀、别名、网关改名），
+ * 同家同协议下回放数据仍可用，不算有损。
+ */
+declare function foreignOrigin(a: ModelOrigin, target: ModelOrigin): boolean;
+declare function eventsToIr(input: IrInput): IrItem[];
+/** 把 encoder 记下的落点按输入事件顺序排回去：LoweredRequest.landings 承诺"每条输入事件一条记录，顺序与输入一致" */
+declare function orderLandings(events: readonly Event[], landings: readonly LandingRecord[]): LandingRecord[];
+
+/**
+ * Server-Sent Events 解析（WHATWG 规范的字段子集）：`event:` / `data:` / `id:`，多行 data 以 \n 拼接，
+ * 空行分发一条消息，`:` 开头是注释，`retry:` 与未知字段忽略。行尾兼容 \r\n、\n、\r。
+ *
+ * 比规范宽一处：流结束时缓冲区里还有没被空行收口的消息，也照样分发——部分上游最后一条事件后不发空行。
+ * `data` 的 JSON 解析不在这里做：`[DONE]` 这类哨兵是各协议自己的约定。
+ */
+interface SseMessage {
+    event?: string;
+    data: string;
+    id?: string;
+}
+declare function parseSse(body: ReadableStream<Uint8Array>): AsyncGenerator<SseMessage>;
+
+/**
+ * 用量与成本（三线共用）。`TokenUsage` 语义跟随 core：`input` 是**未命中缓存**的输入 token，缓存读 / 写另计。
+ * 各协议的原生用量字段在各自 from-stream 里换算成这个形状，这里只算钱。
+ */
+
+/** 每百万 token 的美元价。厂商有峰谷价的（DeepSeek）内置表存峰值价，算出来的是估算上限 */
+interface ModelCost {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+}
+/** 算不出（没有价目）返回 undefined，LoweringOutcome.costUsd 相应缺省 */
+declare function costOf(usage: TokenUsage, cost: ModelCost | undefined): number | undefined;
+
+/**
+ * Anthropic Messages 流 → 事件草稿。
+ *
+ * 只在流收尾时按拼好的内容块产出草稿（signature 在 content_block_stop 前才齐），增量经 onDelta 给 UI。
+ * 中断或出错时把已拼出的部分内容也交出去——日志要记录"发生过什么"，是否继续由循环决定。
+ *
+ * 事件形状（厂商 SSE，按 data.type 分派，不看 event: 行；F0 A7 实测）：
+ *   message_start{ message: { id, model, usage: { input_tokens, cache_creation_input_tokens, cache_read_input_tokens } } }
+ *   content_block_start{ index, content_block: text | thinking | redacted_thinking | tool_use }
+ *   content_block_delta{ index, delta: text_delta | thinking_delta | signature_delta | input_json_delta }
+ *   content_block_stop{ index }
+ *   message_delta{ delta: { stop_reason, stop_sequence, stop_details? }, usage: { output_tokens, … } }
+ *   message_stop / ping / error{ error: { type, message } }
+ * 未知字段一律忽略（厂商自带 "p" 填充；CF 网关原样透传）。
+ */
+
+interface AnthropicUsage {
+    input_tokens?: unknown;
+    output_tokens?: unknown;
+    cache_creation_input_tokens?: unknown;
+    cache_read_input_tokens?: unknown;
+}
+interface AnthropicStreamInput {
+    messages: AsyncIterable<SseMessage>;
+    origin: ModelOrigin;
+    cost?: ModelCost;
+    signal?: AbortSignal;
+    timedOut?: () => boolean;
+    timeoutMs?: number;
+}
+/**
+ * Anthropic 的 input_tokens 本就不含缓存部分（与 core 语义一致）；message_start 报输入侧，message_delta 报输出
+ * （累计值）并可能再报一次输入侧，以后到的为准。
+ */
+declare function usageOf$2(start: AnthropicUsage | undefined, delta: AnthropicUsage | undefined): TokenUsage;
+declare function consumeAnthropicStream(input: AnthropicStreamInput, ctx?: LoweringStreamContext): AsyncGenerator<CoreEventDraft, LoweringOutcome>;
+
+/**
+ * Anthropic Messages 的有损矩阵（P7：有损必声明）。每条实际落点必须命中其中一条，矩阵里不能有死条目（loss-matrix.test.ts）。
+ * 与 lowering-pi 的 "anthropic-messages" 表逐格对照：能 exact 的一样（user / assistant-text / tool_use / tool_result /
+ * thinking-block / system），不同处只有三格——无签名 thinking 这里 dropped 而非 pi-ai 的"降为正文"、redacted 单列、
+ * tool_result 图片按模型能力处置。
+ */
+
+declare const ANTHROPIC_LOSS_MATRIX: Readonly<Record<string, readonly LandingSpec[]>>;
+
+/**
+ * 模型表与解析。只放一张**最小表**（上下文窗口、能力位、价目），`ModelRef` 找不到就抛；宿主用 `models` 选项
+ * 声明表外模型或覆盖表内字段（DECISIONS 2026-09-14 立项：表过期不阻塞使用）。
+ *
+ * 表里的数字来自厂商公开文档（2026-09-14 查阅）；价目是每百万 token 美元，DeepSeek 有峰谷价、存的是峰值价。
+ */
+
+/** 本包实现的三条线协议（F1 Chat Completions、F2 Anthropic Messages、F3 OpenAI Responses） */
+type FetchApi = "openai-chat" | "anthropic-messages" | "openai-responses";
+/** 当前已实现、可发请求的协议；toRequest / stream 遇到别的就抛 unsupported_api */
+declare const SUPPORTED_APIS: ReadonlySet<string>;
+/** 一个模型在本降级层眼里的全部描述。字段与 LoweringCapabilities 对齐，方言开关单独成组 */
+interface FetchModel {
+    provider: string;
+    id: string;
+    api: FetchApi;
+    /** 协议根地址：Chat 在其后接 /chat/completions（OpenAI 给到 …/v1，DeepSeek 给到域名即可） */
+    baseUrl: string;
+    contextWindow: number;
+    maxOutputTokens: number;
+    /** 模型会产出 thinking / reasoning */
+    reasoning: boolean;
+    images?: boolean;
+    cost?: ModelCost;
+    /** 额外请求头（私有网关鉴权等），与降级层级别的 headers 合并、以模型级为准 */
+    headers?: Record<string, string>;
+    name?: string;
+    /**
+     * 是否接受会话中途的 `role:"system"` 消息（system_note 的 exact 落点）。缺省按协议定：Chat 为 true
+     * （OpenAI 官方经 CF 网关、DeepSeek 直连 2026-09-14 均实测到达）。
+     */
+    midConversationSystem?: boolean;
+    /**
+     * 凭证怎么带。缺省按协议：Chat / Responses 用 `Authorization: Bearer`，Anthropic 用 `x-api-key`。
+     * "none" 表示凭证在 headers 里（如 Cloudflare AI Gateway 的 cf-aig-authorization），不再向 apiKey 回调要 key。
+     */
+    auth?: "bearer" | "x-api-key" | "none";
+    /** Chat Completions 方言，只收已验证的扩展（Boss 定：严格按 OpenAI 规范，方言等真有人用再加） */
+    chat?: ChatDialect;
+    /** Anthropic Messages 线的请求整形选项（beta 头、缓存断点处置） */
+    anthropic?: AnthropicDialect;
+    /** OpenAI Responses 线的请求整形选项（说明角色、加密推理项） */
+    responses?: ResponsesDialect;
+}
+interface ResponsesDialect {
+    /**
+     * 系统提示与 system_note 用哪个角色。缺省：推理模型 developer、其它 system（与 lowering-pi 同一选择，矩阵同格）。
+     * 第三方 Responses 兼容上游不认 developer 时改 "system"。
+     */
+    systemRole?: "developer" | "system";
+    /**
+     * 推理模型是否带 `include: ["reasoning.encrypted_content"]`（缺省 true）。`store: false` 下 OpenAI 不保存推理状态，
+     * 只有加密项能把上一轮推理带回下一轮（F0 R3 实测回放接受、伪造 400）；不带则 reasoning 项无法回放、一律 dropped。
+     * 第三方兼容上游不认 include 参数时可关。
+     */
+    encryptedReasoning?: boolean;
+}
+interface ChatDialect {
+    /**
+     * DeepSeek 的 `reasoning_content`（2026-09-14 直连实测）：响应里思考正文与 `content` 平级；带 `tools` 的请求里
+     * **每条** assistant 消息都必须回传该字段（缺了 400，空串可过），不带 tools 时忽略。开了：读侧 → core.model_thinking，
+     * 写侧把自家 thinking 回填、没有就回空串。关着（OpenAI 官方）：thinking 无处可放，矩阵记 dropped。
+     */
+    reasoningContent?: boolean;
+}
+/**
+ * 感知说明殿后（messages 末条是 system）时，"最后一条 user 末块"的断点没处打，B1 实测三种处置（spikes/b1-perception-cache）：
+ * - "automatic"（缺省）：改在请求顶层放 `cache_control`（Anthropic 自动缓存：断点落在最后一个可缓存块上），命中率与不注入持平；
+ * - "previous-user"：仍打在最后一条 user 的末块上，实测低 3～6 个点（后续请求对不上前一次写入的前缀）；
+ * - "drop"：不打。只在上游自己会补自动缓存（如 DeepSeek 的兼容端口）时不吃亏。
+ * 把断点留在 system 消息上实测几乎零命中，不提供。
+ */
+type MidSystemCacheBreakpoint = "automatic" | "previous-user" | "drop";
+interface AnthropicDialect {
+    /**
+     * `anthropic-beta` 头的取值，用到才带（F0 结论：中途 system 不需要 beta；某些 beta 会抬高 reasoning_extraction
+     * 拒答率）。模型级 `headers["anthropic-beta"]` 若也给了，以 headers 为准。
+     */
+    betas?: readonly string[];
+    /** 是否打缓存断点（system 末块、tools 末项、最后一条 user 末块）。缺省 true；上游不认断点时可关 */
+    cacheBreakpoints?: boolean;
+    /** 断点存活期，缺省 5 分钟（不发 ttl 字段）；"1h" 走 `{ type: "ephemeral", ttl: "1h" }` */
+    cacheTtl?: "5m" | "1h";
+    /** 说明殿后时的断点处置，缺省 "automatic" */
+    midSystemCacheBreakpoint?: MidSystemCacheBreakpoint;
+    /**
+     * 是否走 `defer_loading` + `tool_reference` 的原生延迟加载（L1，2026-09-15 经 CF 网关实测 Haiku 4.5 / Opus 5 均支持、GA 无 beta 头）。
+     * 缺省：provider 为 "anthropic" 时开，第三方 Anthropic 协议上游（DeepSeek 兼容端口等）关——它们对这两个字段的态度各异，
+     * 宿主实测接受后再显式打开。关着时 deferLoading 的工具不发、引用段展开成文本
+     */
+    deferredTools?: boolean;
+}
+/**
+ * 内置最小表。同一 provider + id 可能两条协议各一份（OpenAI 的 gpt-4o-mini 等既能走 Chat 也能走 Responses）：
+ * `findBuiltin` 带 api 时精确取（工厂函数总是带），不带时取先列的一份——OpenAI 官方 id 的 Responses 条目列在前，所以
+ * `resolveModel({ provider: "openai", id })` 缺省走 OpenAI 的主协议 Responses（F3 起；F1 时只有 Chat 条目），要走 Chat 用
+ * `openaiChat()` 或在 `models` 里自己声明。Anthropic 列当前一代 + 常用上一代。
+ */
+declare const BUILTIN_MODELS: readonly FetchModel[];
+/** 带 api 精确取该协议的条目；不带取先列的一份 */
+declare function findBuiltin(provider: string, id: string, api?: FetchApi): FetchModel | undefined;
+/** 宿主声明的优先于内置表 */
+declare function resolveModel(ref: ModelRef, extra?: readonly FetchModel[]): FetchModel;
+/** 协议端点：baseUrl 去掉尾部斜杠再接路径 */
+declare function endpointOf(model: FetchModel): string;
+
+/**
+ * IR → Anthropic Messages 请求体，并为每条事件记落点。
+ *
+ * 与 Chat 线相比 Anthropic 规矩最多，这里逐条落实（规则原文 F0 实测，spikes/cf-gateway-fidelity）：
+ * - **tool_result 紧跟**：同批 tool_result 必须在 tool_use 所在 assistant 的下一条 user 里；后移由 IR 完成，这里只把连续的
+ *   user 侧内容（tool_result、用户消息、摘要）并进同一条 user（F0 A5b 实测同条 user 里 tool_result 后接文本可达）；
+ * - **中途 system 摆放**（S1）：不能是首条、必须紧跟 user（含只带 tool_result 的 user）、后接 assistant 或收尾。所以说明
+ *   一律攒到"下一条 assistant 之前"或末尾再放出；此刻前一条不是 user（是 assistant 或什么都没有）就退成 `<system_note>`
+ *   框住的 user 文本，记 lossy(user-role)。放出位置比时间线晚了一条 user 的，仍算 exact（说明只换位置，见 CLAUDE.md）；
+ * - **thinking 回放**：带 signature 原样回放（F0 A7b 接受、伪造签名 400）；无签名（流中断）与来自别家的一律 dropped 声明——
+ *   不像 pi-ai 那样降成正文，模型的私下推理不该以它"说过的话"出现在历史里；`redacted_thinking` 用 data 原样回放；
+ * - **缓存断点**：最多 4 个。我们打三处——system 末块、tools 末项、最后一条 user 末块（厂商按前缀向前找命中，20 块回看窗口）；
+ *   说明殿后（末条是 system）时按 `midSystemCacheBreakpoint` 处置，缺省顶层 `cache_control`（B1 实测与不注入持平）；
+ * - `max_tokens` 必填：宿主 requestOptions 没给就用模型声明的 maxOutputTokens；`thinking` 不缺省设置——Opus 5 起厂商缺省
+ *   就是 adaptive，是否开、开多深由宿主按模型代次决定（Fable 5.1 对 `type:"disabled"` 400）；
+ * - **延迟加载**（L1，spikes/l1-deferred-tools 实测）：`ToolSpec.deferLoading` → `defer_loading: true`，工具留在 tools 块里、
+ *   表整段不变；结果里的 `tool_reference` 段 → `tool_reference` 块由厂商就地展开。厂商规矩：tool_result 内引用不能与文本混放
+ *   （文本段改放同条 user 里紧随的 text 块，记 lossy）；引用指向 tools 里没有的名字 400（整段历史都校验，所以未绑定的引用一律
+ *   展开成文本）；全部工具 defer_loading 400（此时不延迟）；defer_loading 工具不能带 cache_control（断点打在最后一个非延迟工具上）。
+ *   能力位关着（第三方上游）时 deferLoading 的工具不发、引用段展开成文本。
+ */
+
+interface AnthropicCacheControl {
+    type: "ephemeral";
+    ttl?: "5m" | "1h";
+}
+type AnthropicUserBlock = {
+    type: "text";
+    text: string;
+    cache_control?: AnthropicCacheControl;
+} | {
+    type: "image";
+    source: {
+        type: "base64";
+        media_type: string;
+        data: string;
+    };
+    cache_control?: AnthropicCacheControl;
+} | {
+    type: "tool_result";
+    tool_use_id: string;
+    content?: AnthropicToolResultBlock[];
+    is_error?: true;
+    cache_control?: AnthropicCacheControl;
+};
+/** 文本与图片块：user 消息与 tool_result 内容共用的形状 */
+type AnthropicContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    source: {
+        type: "base64";
+        media_type: string;
+        data: string;
+    };
+};
+type AnthropicToolResultBlock = AnthropicContentBlock
+/** 工具定义引用：厂商就地展开成完整定义，不能与其他块混放（L1） */
+ | {
+    type: "tool_reference";
+    tool_name: string;
+};
+type AnthropicAssistantBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "thinking";
+    thinking: string;
+    signature: string;
+} | {
+    type: "redacted_thinking";
+    data: string;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+};
+type AnthropicMessage = {
+    role: "user";
+    content: AnthropicUserBlock[];
+} | {
+    role: "assistant";
+    content: AnthropicAssistantBlock[];
+} | {
+    role: "system";
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+interface AnthropicTool {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+    /** 声明但不载入上下文，历史里出现 tool_reference 后才可见；不能与 cache_control 同在（L1） */
+    defer_loading?: true;
+    cache_control?: AnthropicCacheControl;
+}
+/** 发出去的请求体本体。宿主的 requestOptions 先铺、我们的字段后盖：model / messages / system / tools / stream 不可被覆盖 */
+interface AnthropicRequestBody extends Record<string, unknown> {
+    model: string;
+    max_tokens: number;
+    system?: {
+        type: "text";
+        text: string;
+        cache_control?: AnthropicCacheControl;
+    }[];
+    messages: AnthropicMessage[];
+    tools?: AnthropicTool[];
+    stream: true;
+    cache_control?: AnthropicCacheControl;
+}
+interface AnthropicEncodeInput {
+    ir: readonly IrItem[];
+    events: readonly Event[];
+    model: FetchModel;
+    capabilities: LoweringCapabilities;
+    tools?: readonly ToolSpec[];
+    systemPrompt?: string;
+    requestOptions?: Record<string, unknown>;
+}
+/** Anthropic 每个请求最多 4 个断点（顶层自动缓存也占一个），超出即 400 */
+declare const MAX_ANTHROPIC_BREAKPOINTS = 4;
+declare function encodeAnthropicRequest(input: AnthropicEncodeInput): {
+    body: AnthropicRequestBody;
+    landings: LandingRecord[];
+};
+
+/**
+ * 按模型声明能力（技术方案 §11）。脑子模块只看这些布尔值，不看模型名。
+ */
+
+declare function capabilitiesOf(model: FetchModel): LoweringCapabilities;
+
+/**
+ * Chat Completions 流 → 事件草稿。
+ *
+ * 只在流收尾时按拼好的块产出草稿（与 lowering-pi 同策略：日志里只存完整块），增量经 onDelta 给 UI。
+ * 中断或出错时把已拼出的部分内容也交出去——日志要记录"发生过什么"，是否继续由循环决定。
+ *
+ * chunk 形状（OpenAI 规范 + DeepSeek 已验证的 `delta.reasoning_content`）：
+ *   choices[0].delta.{ content, reasoning_content, tool_calls[{ index, id?, function: { name?, arguments? } }] }
+ *   choices[0].finish_reason 在末块；usage 在带 stream_options.include_usage 的最后一个 chunk（choices 可能为空数组）
+ *   `data: [DONE]` 收尾。未知字段一律忽略（CF 网关会多个 "p"，OpenAI 常带 system_fingerprint / obfuscation）。
+ */
+
+interface ChatUsage {
+    prompt_tokens?: unknown;
+    completion_tokens?: unknown;
+    prompt_tokens_details?: {
+        cached_tokens?: unknown;
+    } | null;
+    /** DeepSeek 原生字段，与 prompt_tokens_details.cached_tokens 同值 */
+    prompt_cache_hit_tokens?: unknown;
+}
+interface ChatStreamInput {
+    messages: AsyncIterable<SseMessage>;
+    origin: ModelOrigin;
+    cost?: ModelCost;
+    /** 宿主中止信号：读流被中止时据此判"aborted"还是本地超时 */
+    signal?: AbortSignal;
+    timedOut?: () => boolean;
+    timeoutMs?: number;
+}
+/** OpenAI 的 prompt_tokens 含缓存命中部分；core 的 input 是未命中数，所以要减掉 */
+declare function usageOf$1(u: ChatUsage | undefined): TokenUsage;
+declare function consumeChatStream(input: ChatStreamInput, ctx?: LoweringStreamContext): AsyncGenerator<CoreEventDraft, LoweringOutcome>;
+
+/**
+ * Chat Completions 的有损矩阵（P7：有损必声明）。事件 type → 可能落点；toRequest 记录的每条实际落点必须命中其中一条，
+ * 矩阵里不能有从未命中的死条目（loss-matrix.test.ts）。新增事件类型或改落点不补表，测试就红。
+ */
+
+declare const CHAT_LOSS_MATRIX: Readonly<Record<string, readonly LandingSpec[]>>;
+
+/**
+ * IR → OpenAI Chat Completions 请求体，并为每条事件记落点。
+ *
+ * 严格按 OpenAI 官方规范（Boss 定），方言只收 DeepSeek 已验证的 `reasoning_content`（见 models.ts ChatDialect）。
+ * 角色只有 system / user / assistant / tool 四种，这是全包唯一出现"角色"的地方之一（宪法二）。
+ *
+ * Chat 线天然有损、矩阵里如实声明：
+ * - thinking 没有回放位（无签名、无加密项）——除 DeepSeek 方言外 dropped；
+ * - 没有显式缓存断点——什么都不做（厂商自动前缀缓存）；
+ * - assistant 的 content 是单个字符串（DeepSeek 只接受 string | null）——同一轮多段正文合并，lossy(merged-text)；
+ * - tool 消息没有错误位——isError 以文本前缀表达，lossy；tool 消息只收文本——图片换成占位文本，lossy。
+ */
+
+type ChatContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image_url";
+    image_url: {
+        url: string;
+    };
+};
+interface ChatToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+type ChatMessage = {
+    role: "system";
+    content: string;
+} | {
+    role: "user";
+    content: string | ChatContentPart[];
+} | {
+    role: "assistant";
+    content: string | null;
+    tool_calls?: ChatToolCall[];
+    reasoning_content?: string;
+} | {
+    role: "tool";
+    tool_call_id: string;
+    content: string;
+};
+interface ChatTool {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+/** 发出去的请求体本体。宿主的 requestOptions 先铺、我们的字段后盖：messages / tools / model / stream 不可被覆盖 */
+interface ChatRequestBody extends Record<string, unknown> {
+    model: string;
+    messages: ChatMessage[];
+    tools?: ChatTool[];
+    stream: true;
+    stream_options: {
+        include_usage: true;
+    };
+}
+interface ChatEncodeInput {
+    ir: readonly IrItem[];
+    events: readonly Event[];
+    model: FetchModel;
+    capabilities: LoweringCapabilities;
+    tools?: readonly ToolSpec[];
+    systemPrompt?: string;
+    requestOptions?: Record<string, unknown>;
+}
+declare function encodeChatRequest(input: ChatEncodeInput): {
+    body: ChatRequestBody;
+    landings: LandingRecord[];
+};
+
+/**
+ * 一行拿到"模型 + 降级层"：`deepseek("deepseek-flash", { apiKey })`、`openaiChat("gpt-4o-mini", { apiKey })`、
+ * `openai("gpt-5-mini", { apiKey })`（Responses）、`anthropic("claude-opus-5", { apiKey })`；任何 OpenAI 兼容端点用
+ * `chatCompletions("qwen-max", { provider: "qwen", baseUrl, apiKey })`，任何 Anthropic 协议端点（DeepSeek 兼容端口、CF 网关）用
+ * `anthropicMessages(id, { provider, baseUrl, apiKey })`，任何 Responses 协议端点用 `openaiResponses(id, { provider, baseUrl, apiKey })`。
+ * 返回 BoundModel，直接给 `createAgent({ model })`；要多模型共享一个降级层就自己 new FetchLowering。
+ *
+ * 表内模型取内置定义再按选项覆盖；表外模型用保守缺省（128k 窗口、16k 输出、无推理、不收图），宿主按需覆盖。
+ * 本包不读环境变量，apiKey 必填、由宿主决定来源（auth:"none" 时可给空串占位）。
+ */
+
+interface ModelOptions {
+    apiKey: string;
+    /** 协议根地址（Chat 在其后接 /chat/completions，Anthropic 接 /messages）；表内模型缺省用厂商官方地址 */
+    baseUrl?: string;
+    contextWindow?: number;
+    maxOutputTokens?: number;
+    reasoning?: boolean;
+    images?: boolean;
+    cost?: ModelCost;
+    /** 上游是否接受中途 role:"system"；Chat 缺省 true，Anthropic 按模型族推断 */
+    midConversationSystem?: boolean;
+    /** Chat 方言开关，见 models.ts ChatDialect */
+    chat?: ChatDialect;
+    /** Anthropic 线的 beta 头与缓存断点处置，见 models.ts AnthropicDialect */
+    anthropic?: AnthropicDialect;
+    /** Responses 线的说明角色与加密推理项开关，见 models.ts ResponsesDialect */
+    responses?: ResponsesDialect;
+    /** 凭证怎么带；网关自带凭证头时用 "none" 并把头放 headers */
+    auth?: FetchModel["auth"];
+    headers?: Record<string, string>;
+    /** 铺进请求体的额外字段（max_tokens、temperature、thinking …） */
+    requestOptions?: Record<string, unknown>;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    trustMarkers?: boolean;
+}
+/** @deprecated 改名为 ModelOptions（三条线共用同一组选项），保留别名 */
+type ChatModelOptions = ModelOptions;
+interface ProviderModelOptions extends ModelOptions {
+    /** 用作 ModelRef.provider 与 apiKey 回调的键；表外厂商必填 */
+    provider: string;
+}
+/** @deprecated 改名为 ProviderModelOptions */
+type ChatCompletionsOptions = ProviderModelOptions;
+/** 内置定义打底，选项里给了的字段覆盖；表外模型从保守缺省起 */
+declare function definitionOf(provider: string, id: string, api: FetchApi, opts: Omit<ModelOptions, "apiKey" | "requestOptions" | "fetch" | "timeoutMs" | "trustMarkers">): FetchModel;
+/** 任何 OpenAI Chat Completions 兼容端点 */
+declare function chatCompletions(id: string, opts: ProviderModelOptions): BoundModel;
+/** DeepSeek 直连：缺省官方地址、开 reasoning_content 方言（带 tools 时缺它 400） */
+declare function deepseek(id: string, opts: ModelOptions): BoundModel;
+/** OpenAI 官方 Chat Completions（推理系列请用 Responses 线的 openai()） */
+declare function openaiChat(id: string, opts: ModelOptions): BoundModel;
+/**
+ * 任何 OpenAI Responses 协议端点：Cloudflare AI Gateway 透传路径（`auth: "none"` + `cf-aig-authorization` 头）、
+ * 兼容网关。表外模型从保守缺省起（reasoning 假、不收图），宿主按需声明；不认 developer 角色或 include 参数的上游用 `responses` 方言关掉。
+ */
+declare function openaiResponses(id: string, opts: ProviderModelOptions): BoundModel;
+/**
+ * OpenAI 官方 Responses：缺省官方地址、Bearer 鉴权；表内模型带价目与能力位。`reasoning` 参数不缺省设置——
+ * gpt-5 缺省 medium、gpt-5.1 起缺省 none，开不开、开多深由宿主按型号在 requestOptions 里定（与 Anthropic 线的 thinking 同一原则）。
+ */
+declare function openai(id: string, opts: ModelOptions): BoundModel;
+/**
+ * 任何 Anthropic Messages 协议端点：DeepSeek 的兼容端口（`provider: "deepseek", baseUrl: "https://api.deepseek.com/anthropic"`）、
+ * Cloudflare AI Gateway 透传路径（`auth: "none"` + `cf-aig-authorization` 头）。表外模型从保守缺省起（reasoning 假、不收图），宿主按需声明。
+ */
+declare function anthropicMessages(id: string, opts: ProviderModelOptions): BoundModel;
+/** Anthropic 官方直连：缺省官方地址、x-api-key 鉴权；表内模型带价目与能力位 */
+declare function anthropic(id: string, opts: ModelOptions): BoundModel;
+
+/**
+ * 三线共用的 fetch 封装：超时、宿主中止、非 2xx 转成带状态码的错误。
+ *
+ * 错误文案刻意用 "<status> <body>" 格式（与两家官方 SDK 同款）：core 的瞬断判据（retry.ts）先看错误对象上的
+ * `status` / `headers`，再看文案开头的三位数字，所以这里抛出的错误不用任何额外约定就能被正确判成
+ * "429 / 5xx 重试、400 不重试"。`headers` 保留原样，`x-should-retry` 由 core 自己读。
+ *
+ * 不读环境变量、不碰 node:*，Workers / Deno / 浏览器同一份代码。
+ */
+declare class HttpError extends Error {
+    readonly status: number;
+    readonly headers: Headers;
+    /** 响应正文原文（厂商错误体或网关信封，不假定形状） */
+    readonly body: string;
+    readonly url: string;
+    readonly name = "HttpError";
+    constructor(status: number, headers: Headers, 
+    /** 响应正文原文（厂商错误体或网关信封，不假定形状） */
+    body: string, url: string);
+}
+/** 一次请求的时限（整条响应，含流式读完），与两家 SDK 缺省一致 */
+declare const DEFAULT_TIMEOUT_MS = 600000;
+interface RequestSignals {
+    /** 交给 fetch 与流读取的组合信号 */
+    signal: AbortSignal;
+    /** 中止后判定是哪一方：宿主中止（ctx.signal）还是本地超时 */
+    timedOut: () => boolean;
+}
+/**
+ * 把宿主的 signal 与本地超时合成一个信号。超时到点后 `timedOut()` 为真；宿主中止优先（两者都发生时算宿主中止，
+ * 因为宿主中止是有意为之、不该被当成瞬断重试）。
+ */
+declare function requestSignals(hostSignal: AbortSignal | undefined, timeoutMs: number): RequestSignals;
+interface PostJsonInput {
+    url: string;
+    headers: Record<string, string>;
+    body: unknown;
+    signal: AbortSignal;
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * POST JSON；非 2xx 读完正文抛 HttpError。网络层失败（DNS、连接被掐、超时）由 fetch 自己抛出，原样上抛——
+ * 那些错误对象上的 `cause.code` / `name` 正是 core 判瞬断要看的东西，包一层反而会盖掉。
+ */
+declare function postJson(input: PostJsonInput): Promise<Response>;
+
+/**
+ * FetchLowering：@reinsjs/core 的 Lowering 接口只用 fetch 的实现（零依赖、零 node:*）。
+ *
+ * 与 lowering-pi 的分工见 DECISIONS 2026-09-14「lowering-fetch 立项」：两包并存，宿主 import 谁用谁。
+ * 这里 `LoweredRequest.payload.body` 就是真正发出去的请求体——没有第二跳改写，排查 400 直接看它。
+ */
+
+/** Anthropic Messages 的协议版本头，当前唯一稳定值 */
+declare const ANTHROPIC_VERSION = "2023-06-01";
+interface FetchLoweringOptions {
+    /** 按 provider 取 key；返回 undefined 视为未配置。本包不读环境变量，由宿主决定来源 */
+    apiKey: (provider: string) => string | undefined;
+    /** 自定义 fetch（测试注入、代理、Workers 绑定）；缺省 globalThis.fetch */
+    fetch?: typeof globalThis.fetch;
+    /** 附加请求头，所有请求都带；模型级 headers 优先 */
+    headers?: Record<string, string>;
+    /** 内置表之外的模型，或覆盖表内同名模型 */
+    models?: readonly FetchModel[];
+    /**
+     * 铺进请求体的额外字段（max_tokens、temperature、DeepSeek 的 thinking / reasoning_effort、OpenAI 的
+     * parallel_tool_calls …），键名以厂商文档为准。按模型返回，便于分族配置。messages / tools / model / stream 不可覆盖。
+     */
+    requestOptions?: (model: ModelRef) => Record<string, unknown>;
+    /** 整条请求（含读完流）的时限，缺省 600 000 ms；到点判 error（可重试），宿主 signal 中止判 aborted */
+    timeoutMs?: number;
+    /**
+     * trust 标注（技术方案 §14）：trust=untrusted 的事件翻译时包上 `<untrusted source="tool:<name>">…</untrusted>`，
+     * 事件本身不动。缺省 true；传 false 关掉是宿主自担提示注入风险
+     */
+    trustMarkers?: boolean;
+}
+/** 对外暴露的请求体：就是要 POST 的 JSON，鉴权头与 URL 在 stream 时才拼（不进 payload，日志里不落凭证） */
+interface FetchLoweredPayload {
+    api: FetchApi;
+    body: Record<string, unknown>;
+}
+declare class FetchLowering implements Lowering<FetchLoweredPayload> {
+    private readonly opts;
+    private readonly extraModels;
+    private readonly timeoutMs;
+    constructor(opts: FetchLoweringOptions);
+    capabilities(ref: ModelRef): LoweringCapabilities;
+    toRequest(input: ToRequestInput): LoweredRequest<FetchLoweredPayload>;
+    stream(req: LoweredRequest<FetchLoweredPayload>, ctx?: LoweringStreamContext): AsyncGenerator<CoreEventDraft, LoweringOutcome>;
+    /**
+     * 鉴权头按协议缺省（Chat / Responses bearer、Anthropic x-api-key），模型声明 auth:"none" 时凭证由 headers 自带。
+     * Anthropic 线固定带 `anthropic-version`，`anthropic-beta` 只在模型声明了 betas 时带（F0 结论：用到才带）；模型级 headers 最后盖。
+     */
+    private headersFor;
+}
+
+/**
+ * OpenAI Responses 流 → 事件草稿。
+ *
+ * 只在流收尾时按拼好的输出项产出草稿（reasoning 项的 encrypted_content 在 output_item.done 才齐），增量经 onDelta 给 UI。
+ * 中断或出错时把已拼出的部分内容也交出去——日志要记录"发生过什么"，是否继续由循环决定。
+ *
+ * 事件形状（厂商 SSE，按 data.type 分派；F0 R2 实测事件序列完整）：
+ *   response.created / response.in_progress { response: { id, model } }
+ *   response.output_item.added { output_index, item: reasoning | message | function_call | … }
+ *   response.reasoning_summary_part.added / response.reasoning_summary_text.delta { output_index, delta } / response.reasoning_text.delta
+ *   response.output_text.delta / response.refusal.delta { output_index, delta }
+ *   response.function_call_arguments.delta { output_index, delta } / response.function_call_arguments.done { arguments }
+ *   response.output_item.done { output_index, item }           ← 项的最终形状（reasoning 带 encrypted_content、message 带 id）
+ *   response.completed / response.incomplete { response: { status, incomplete_details, usage, output } }
+ *   response.failed { response: { error: { code, message } } } / error { code, message }
+ * 未知字段一律忽略（CF 网关会多个 "p"）。
+ */
+
+interface ResponsesUsage {
+    input_tokens?: unknown;
+    output_tokens?: unknown;
+    input_tokens_details?: {
+        cached_tokens?: unknown;
+        cache_write_tokens?: unknown;
+    } | null;
+    output_tokens_details?: {
+        reasoning_tokens?: unknown;
+    } | null;
+}
+interface ResponsesStreamInput {
+    messages: AsyncIterable<SseMessage>;
+    origin: ModelOrigin;
+    cost?: ModelCost;
+    signal?: AbortSignal;
+    timedOut?: () => boolean;
+    timeoutMs?: number;
+}
+/**
+ * OpenAI 的 input_tokens 含缓存命中与缓存写入部分（F0 R1 / R4 实测 `input_tokens_details.cached_tokens` / `cache_write_tokens`），
+ * core 的 input 是未命中数，所以两者都要减掉。
+ */
+declare function usageOf(u: ResponsesUsage | undefined): TokenUsage;
+declare function consumeResponsesStream(input: ResponsesStreamInput, ctx?: LoweringStreamContext): AsyncGenerator<CoreEventDraft, LoweringOutcome>;
+
+/**
+ * OpenAI Responses 的有损矩阵（P7：有损必声明）。每条实际落点必须命中其中一条，矩阵里不能有死条目（loss-matrix.test.ts）。
+ * 与 lowering-pi 的 "openai-responses" 表逐格对照：能 exact 的一样（user / assistant-message / reasoning-item / function_call /
+ * function_call_output / developer / system）。不同处三格——无加密项或别家的 reasoning 这里 dropped 而非 pi-ai 的
+ * "降为正文 / 厂商看着办"、tool_call 入参不是对象也照发（arguments 本就是 JSON 字符串，不必包 { value }）、
+ * tool_result 的 isError 以前缀表达（协议没有错误位）并按模型能力处置图片。
+ */
+
+declare const RESPONSES_LOSS_MATRIX: Readonly<Record<string, readonly LandingSpec[]>>;
+
+/**
+ * IR → OpenAI Responses 请求体，并为每条事件记落点。
+ *
+ * Responses 是三条线里规矩最少的一条，但有两处与"时间线是唯一真源"直接相关，这里逐条落实（规则原文 F0 实测，
+ * spikes/cf-gateway-fidelity 的 R2 / R3 / R3b）：
+ * - **服务端不留状态**：`store: false` 强制、宿主传的 `previous_response_id` 剥掉。每个请求把模型该看到的历史全量放进 `input`，
+ *   与别的两条线同一形状；OpenAI 侧的会话状态永远不是我们依赖的东西。
+ * - **reasoning 回放判据是 encrypted_content**：推理模型缺省带 `include: ["reasoning.encrypted_content"]`，上一轮的 reasoning 项
+ *   （整项 JSON 存在事件 `replay.thinkingSignature` 里，与 lowering-pi 同字段）原样放回 `input`；没有加密项（未开 include、流中断）
+ *   或来自别家的一律 dropped 声明，不降成正文。伪造的加密项厂商回原文 400，所以回放的必须是原件。
+ * - **中途 system 不用归位**：`developer` / `system` 消息在 `input` 里任意位置合法（F0 R3 中途 developer 到达）；推理模型用
+ *   developer、其它用 system（与 pi 版矩阵同格），宿主可用 `responses.systemRole` 钉死。
+ * - **工具调用两个 id**：`call_id`（配对 function_call_output 用）是 core 的 toolCallId；`fc_` 项 id 存 `replay.itemId`，只在同一模型
+ *   回放时带回——OpenAI 会校验 fc 项与 rs 项的配对，换了模型就不带（与 pi-ai 同一取向）。
+ * - `reasoning` / `max_output_tokens` 不缺省设置：gpt-5 缺省 medium、gpt-5.1 起缺省 none，开不开由宿主按型号在 requestOptions 里定
+ *   （与 Anthropic 线的 thinking 同一原则）。
+ */
+
+type ResponsesInputContent = {
+    type: "input_text";
+    text: string;
+} | {
+    type: "input_image";
+    image_url: string;
+    detail: "auto";
+};
+type ResponsesInputItem = 
+/** user / developer / system 消息 */
+{
+    role: "user" | "developer" | "system";
+    content: ResponsesInputContent[];
+}
+/** 上一轮的 assistant 正文：type:message 输出项原样放回 */
+ | {
+    type: "message";
+    role: "assistant";
+    id: string;
+    status: "completed";
+    content: {
+        type: "output_text";
+        text: string;
+        annotations: [];
+    }[];
+    phase?: string;
+}
+/** 上一轮的 reasoning 项：整项原样放回（id / summary / encrypted_content 等字段以厂商给的为准） */
+ | {
+    type: "reasoning";
+    id: string;
+    encrypted_content: string;
+    [k: string]: unknown;
+} | {
+    type: "function_call";
+    id?: string;
+    call_id: string;
+    name: string;
+    arguments: string;
+} | {
+    type: "function_call_output";
+    call_id: string;
+    output: string | ResponsesInputContent[];
+};
+interface ResponsesTool {
+    type: "function";
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    /** 我们的 JSON Schema 不保证满足 strict 模式（additionalProperties:false、全部 required），一律不开 */
+    strict: false;
+}
+/** 发出去的请求体本体。宿主的 requestOptions 先铺、我们的字段后盖：model / input / tools / stream / store 不可被覆盖 */
+interface ResponsesRequestBody extends Record<string, unknown> {
+    model: string;
+    input: ResponsesInputItem[];
+    tools?: ResponsesTool[];
+    stream: true;
+    store: false;
+    include?: string[];
+}
+interface ResponsesEncodeInput {
+    ir: readonly IrItem[];
+    events: readonly Event[];
+    model: FetchModel;
+    capabilities: LoweringCapabilities;
+    tools?: readonly ToolSpec[];
+    systemPrompt?: string;
+    requestOptions?: Record<string, unknown>;
+}
+/** replay.thinkingSignature 里存的 reasoning 项：必须是带非空 encrypted_content 的对象才可回放 */
+declare function reasoningItemOf(replay: Record<string, unknown>): Record<string, unknown> | undefined;
+declare function encodeResponsesRequest(input: ResponsesEncodeInput): {
+    body: ResponsesRequestBody;
+    landings: LandingRecord[];
+};
+
+/** api → 事件 type → 可能落点；与 lowering-pi 的 LOSS_MATRIX 同形，逐格对照用 */
+declare const LOSS_MATRIX: LossMatrix;
+/** 查某 api 下某事件 type 的声明落点；ext.* 归到通配项 */
+declare function declaredLandings(api: string, type: string): readonly _reinsjs_core.LandingSpec[];
+
+export { ANTHROPIC_LOSS_MATRIX, ANTHROPIC_VERSION, type AnthropicAssistantBlock, type AnthropicCacheControl, type AnthropicDialect, type AnthropicMessage, type AnthropicRequestBody, type AnthropicTool, type AnthropicUserBlock, BUILTIN_MODELS, CHAT_LOSS_MATRIX, type ChatCompletionsOptions, type ChatContentPart, type ChatDialect, type ChatMessage, type ChatModelOptions, type ChatRequestBody, type ChatTool, type ChatToolCall, DEFAULT_TIMEOUT_MS, type FetchApi, type FetchLoweredPayload, FetchLowering, type FetchLoweringOptions, type FetchModel, HttpError, type IrBlock, type IrItem, LOSS_MATRIX, MAX_ANTHROPIC_BREAKPOINTS, type MidSystemCacheBreakpoint, type ModelCost, type ModelOptions, type ModelOrigin, type ProviderModelOptions, RESPONSES_LOSS_MATRIX, type ResponsesDialect, type ResponsesInputContent, type ResponsesInputItem, type ResponsesRequestBody, type ResponsesTool, SUPPORTED_APIS, type SseMessage, anthropic, anthropicMessages, usageOf$2 as anthropicUsageOf, capabilitiesOf, chatCompletions, usageOf$1 as chatUsageOf, consumeAnthropicStream, consumeChatStream, consumeResponsesStream, costOf, declaredLandings, deepseek, definitionOf, encodeAnthropicRequest, encodeChatRequest, encodeResponsesRequest, endpointOf, eventsToIr, findBuiltin, foreignOrigin, openai, openaiChat, openaiResponses, orderLandings, parseSse, postJson, reasoningItemOf, requestSignals, resolveModel, usageOf as responsesUsageOf, sameOrigin };