@armadra/agent 0.0.0-stage → 0.2.1

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

@@ -0,0 +1,303 @@
+/**
+ * openai-completions 请求体（设计 §3.1、§3.3）：消息转换、compat 开关、思考字段、缓存。
+ *
+ * compat 开关在这里生效的位置：
+ * - maxTokensField / supportsDeveloperRole / supportsUsageInStreaming（stream_options）/
+ *   supportsStore（store:false）/ supportsStrictTools（strict:true，仅对严格兼容的 schema）；
+ * - thinkingFormat：openai → reasoning_effort；openrouter → reasoning.effort；deepseek →
+ *   thinking.type（+ reasoning_effort）；zai → thinking.type（+ reasoning_effort）；qwen →
+ *   enable_thinking（+ thinkingTokenBudgetField 预算）；none → 不发；
+ * - requiresReasoningContentOnAssistantMessages：推理模型的助手消息一律带 reasoning_content；
+ * - requiresToolResultName / requiresAssistantAfterToolResult / supportsMidConvoSystemMessages；
+ * - cacheControlFormat "anthropic"：system 末、最后一个工具、最后一条 user / tool 消息打
+ *   cache_control（OpenRouter 上的 anthropic/* 模型）。
+ * 缓存（第三波 §1.3）：`prompt_cache_key = sessionId` 只在 `sendPromptCacheKey`（官方端点缺省开）时发；
+ * `long` 在 `supportsLongCacheRetention` 时发 `prompt_cache_retention: "24h"`，否则降为 short；
+ * 保留层级未指定时读 `AMA_CACHE_RETENTION`。`toolChoice: "none"`（有工具时）→ `tool_choice: "none"`。
+ */
+import { contentText, normalizeContext, normalizeContextInline, sanitizeText, } from "../context.js";
+import { DEFAULT_THINKING_BUDGETS, clampBudgetToAnswerRoom, clampThinkingLevel, mappedThinkingValue, } from "../thinking.js";
+import { cacheControlFor } from "./anthropic-request.js";
+import { effectiveRetention, resolveCacheRetention, resolvePromptCacheCompat, } from "./cache-params.js";
+import { detectCompat } from "./openai-compat.js";
+/** 思考文本回放用的字段名；thinkingSignature 记录来源字段，回放时原样放回。 */
+export const REASONING_FIELDS = ["reasoning_content", "reasoning", "reasoning_text"];
+export const ASSISTANT_BRIDGE_TEXT = "Tool results received.";
+function imagePart(block) {
+    return { type: "image_url", image_url: { url: `data:${block.mimeType};base64,${block.data}` } };
+}
+function convertUser(message) {
+    if (typeof message.content === "string") {
+        return { role: "user", content: sanitizeText(message.content) };
+    }
+    const parts = [];
+    for (const block of message.content) {
+        if (block.type === "image")
+            parts.push(imagePart(block));
+        else if (block.text.length > 0)
+            parts.push({ type: "text", text: sanitizeText(block.text) });
+    }
+    return parts.length > 0 ? { role: "user", content: parts } : undefined;
+}
+function normalizeCallId(model, id) {
+    const base = id.includes("|") ? (id.split("|")[0] ?? id) : id;
+    return model.provider === "openai" && base.length > 40 ? base.slice(0, 40) : base;
+}
+function convertAssistant(model, message, compat) {
+    const text = message.content
+        .filter((b) => b.type === "text")
+        .map((b) => b.text)
+        .filter((t) => t.trim().length > 0)
+        .join("");
+    const thinking = message.content.filter((b) => b.type === "thinking" && !b.redacted);
+    const calls = message.content.filter((b) => b.type === "toolCall");
+    const out = { role: "assistant", content: text.length > 0 ? sanitizeText(text) : null };
+    const thinkingText = thinking
+        .map((b) => b.thinking)
+        .filter((t) => t.trim().length > 0)
+        .join("\n");
+    const field = thinking.find((b) => REASONING_FIELDS.includes(b.thinkingSignature ?? ""))?.thinkingSignature;
+    if (compat.requiresReasoningContentOnAssistantMessages && model.reasoning) {
+        out["reasoning_content"] = thinkingText;
+    }
+    else if (field && thinkingText.length > 0) {
+        out[field] = thinkingText;
+    }
+    if (calls.length > 0) {
+        out["tool_calls"] = calls.map((call) => ({
+            id: normalizeCallId(model, call.id),
+            type: "function",
+            function: { name: call.name, arguments: JSON.stringify(call.arguments) },
+        }));
+    }
+    if (out["content"] === null && calls.length === 0)
+        return undefined;
+    return out;
+}
+function convertToolResults(model, results, compat) {
+    const messages = [];
+    const images = [];
+    for (const result of results) {
+        const text = contentText(result.content);
+        const blocks = typeof result.content === "string" ? [] : result.content;
+        const hasImages = blocks.some((b) => b.type === "image");
+        const message = {
+            role: "tool",
+            tool_call_id: normalizeCallId(model, result.toolCallId),
+            content: sanitizeText(text.length > 0 ? text : hasImages ? "(see attached image)" : "(no output)"),
+        };
+        if (compat.requiresToolResultName)
+            message["name"] = result.toolName;
+        messages.push(message);
+        if (hasImages && model.input.includes("image")) {
+            for (const block of blocks)
+                if (block.type === "image")
+                    images.push(imagePart(block));
+        }
+    }
+    return { messages, images };
+}
+export function convertMessages(model, messages, compat, instructionRole, updates = []) {
+    const out = [];
+    let afterToolResult = false;
+    const flushUpdates = (index) => {
+        for (const update of updates) {
+            if (update.beforeIndex === index)
+                out.push({ role: instructionRole, content: update.text });
+        }
+    };
+    for (let i = 0; i < messages.length; i++) {
+        flushUpdates(i);
+        const message = messages[i];
+        if (!message)
+            continue;
+        if (message.role === "toolResult") {
+            const batch = [];
+            while (messages[i]?.role === "toolResult")
+                batch.push(messages[i++]);
+            i--;
+            const converted = convertToolResults(model, batch, compat);
+            out.push(...converted.messages);
+            afterToolResult = true;
+            if (converted.images.length > 0) {
+                if (compat.requiresAssistantAfterToolResult) {
+                    out.push({ role: "assistant", content: ASSISTANT_BRIDGE_TEXT });
+                }
+                out.push({
+                    role: "user",
+                    content: [{ type: "text", text: "Images from the tool results:" }, ...converted.images],
+                });
+                afterToolResult = false;
+            }
+            continue;
+        }
+        if (message.role === "user") {
+            const converted = convertUser(message);
+            if (!converted)
+                continue;
+            if (afterToolResult && compat.requiresAssistantAfterToolResult) {
+                out.push({ role: "assistant", content: ASSISTANT_BRIDGE_TEXT });
+            }
+            out.push(converted);
+        }
+        else {
+            const converted = convertAssistant(model, message, compat);
+            if (converted)
+                out.push(converted);
+        }
+        afterToolResult = false;
+    }
+    flushUpdates(messages.length);
+    return out;
+}
+/** strict 模式要求：object 关闭 additionalProperties 且全部属性必填（递归）。 */
+export function isStrictCompatible(schema) {
+    if (schema.type === "object" || schema.properties) {
+        if (schema.additionalProperties !== false)
+            return false;
+        const keys = Object.keys(schema.properties ?? {});
+        const required = new Set(schema.required ?? []);
+        if (!keys.every((key) => required.has(key)))
+            return false;
+        return Object.values(schema.properties ?? {}).every(isStrictCompatible);
+    }
+    if (schema.type === "array" && schema.items)
+        return isStrictCompatible(schema.items);
+    return true;
+}
+function convertTools(tools, compat) {
+    return tools.map((tool) => {
+        const parameters = { ...tool.parameters, type: "object" };
+        const fn = { name: tool.name, description: tool.description, parameters };
+        if (compat.supportsStrictTools && isStrictCompatible(parameters))
+            fn["strict"] = true;
+        return { type: "function", function: fn };
+    });
+}
+function addCacheControlToText(message, cacheControl) {
+    const content = message["content"];
+    if (typeof content === "string" && content.length > 0) {
+        message["content"] = [{ type: "text", text: content, cache_control: cacheControl }];
+        return true;
+    }
+    if (!Array.isArray(content))
+        return false;
+    for (let i = content.length - 1; i >= 0; i--) {
+        const part = content[i];
+        if (part["type"] === "text") {
+            part["cache_control"] = cacheControl;
+            return true;
+        }
+    }
+    return false;
+}
+function applyAnthropicCache(messages, tools, cacheControl) {
+    const system = messages.find((m) => m["role"] === "system" || m["role"] === "developer");
+    if (system)
+        addCacheControlToText(system, cacheControl);
+    const lastTool = tools?.[tools.length - 1];
+    if (lastTool)
+        lastTool["cache_control"] = cacheControl;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (message && (message["role"] === "user" || message["role"] === "tool")) {
+            if (addCacheControlToText(message, cacheControl))
+                return;
+        }
+    }
+}
+/** 写思考相关字段；返回实际发出的级别值（effort 字串或预算）。 */
+function applyThinking(body, model, compat, level, maxTokens) {
+    if (!model.reasoning || compat.thinkingFormat === "none")
+        return undefined;
+    const on = level !== "off";
+    const mapped = mappedThinkingValue(model, level);
+    const effort = on ? (typeof mapped === "string" ? mapped : level) : undefined;
+    const offValue = model.thinkingLevelMap?.off;
+    let sent;
+    switch (compat.thinkingFormat) {
+        case "openai":
+            if (compat.supportsReasoningEffort && effort)
+                sent = effort;
+            else if (compat.supportsReasoningEffort && !on && typeof offValue === "string")
+                sent = offValue;
+            if (sent !== undefined)
+                body["reasoning_effort"] = sent;
+            break;
+        case "openrouter":
+            if (effort)
+                sent = effort;
+            else if (offValue !== null)
+                sent = typeof offValue === "string" ? offValue : "none";
+            if (sent !== undefined)
+                body["reasoning"] = { effort: sent };
+            break;
+        case "deepseek":
+        case "zai":
+            if (on || offValue !== null)
+                body["thinking"] = { type: on ? "enabled" : "disabled" };
+            if (on && compat.supportsReasoningEffort && effort) {
+                body["reasoning_effort"] = effort;
+                sent = effort;
+            }
+            break;
+        case "qwen":
+            body["enable_thinking"] = on;
+            if (on && compat.supportsReasoningEffort && effort) {
+                body["reasoning_effort"] = effort;
+                sent = effort;
+            }
+            break;
+    }
+    if (compat.thinkingTokenBudgetField && level !== "off") {
+        const budget = clampBudgetToAnswerRoom(typeof mapped === "number" ? mapped : DEFAULT_THINKING_BUDGETS[level], maxTokens);
+        if (budget > 0) {
+            body[compat.thinkingTokenBudgetField] = budget;
+            sent ??= String(budget);
+        }
+    }
+    return sent;
+}
+export function buildOpenAIRequest(model, context, options) {
+    const compat = detectCompat(model);
+    const normalized = compat.supportsMidConvoSystemMessages
+        ? normalizeContextInline(context, { model })
+        : { ...normalizeContext(context, { model }), systemUpdates: [] };
+    const role = model.reasoning && compat.supportsDeveloperRole ? "developer" : "system";
+    const messages = [];
+    if (normalized.systemPrompt.length > 0) {
+        messages.push({ role, content: sanitizeText(normalized.systemPrompt) });
+    }
+    messages.push(...convertMessages(model, normalized.messages, compat, role, normalized.systemUpdates));
+    const maxTokens = options.maxTokens ?? model.maxTokens;
+    const level = clampThinkingLevel(model, options.thinkingLevel ?? "off");
+    const body = { model: model.id, messages, stream: true };
+    if (compat.supportsUsageInStreaming)
+        body["stream_options"] = { include_usage: true };
+    if (compat.supportsStore)
+        body["store"] = false;
+    body[compat.maxTokensField] = maxTokens;
+    if (options.temperature !== undefined)
+        body["temperature"] = options.temperature;
+    const tools = normalized.tools.length > 0 ? convertTools(normalized.tools, compat) : undefined;
+    if (tools)
+        body["tools"] = tools;
+    if (tools && options.toolChoice === "none")
+        body["tool_choice"] = "none";
+    const cacheCompat = resolvePromptCacheCompat(model, "openai-completions");
+    const retention = effectiveRetention(resolveCacheRetention(options.cacheRetention), cacheCompat);
+    if (options.sessionId && retention !== "none" && cacheCompat.sendPromptCacheKey) {
+        body["prompt_cache_key"] = options.sessionId.slice(0, 64);
+    }
+    if (retention === "long" && compat.cacheControlFormat !== "anthropic") {
+        body["prompt_cache_retention"] = "24h";
+    }
+    const cacheControl = cacheControlFor(retention);
+    if (compat.cacheControlFormat === "anthropic" && cacheControl) {
+        applyAnthropicCache(messages, tools, cacheControl);
+    }
+    const providerLevel = applyThinking(body, model, compat, level, maxTokens);
+    if (model.samplingParams)
+        Object.assign(body, model.samplingParams);
+    return { body, compat, thinkingLevel: level, providerThinkingLevel: providerLevel };
+}

package/dist/ai/apis/openai-responses-request.d.ts

@@ -0,0 +1,52 @@
+/**
+ * openai-responses 请求体（设计 §3.1、§3.3、§3.6）：input items、instructions、工具、reasoning、
+ * 缓存键、无状态回放。
+ *
+ * - 系统提示折叠后放 `instructions`（不进 input，前缀稳定利于缓存）；
+ * - 助手消息拆成 items：思考块的 `thinkingSignature` 是完整的 reasoning item（JSON，含
+ *   `encrypted_content`），只回放给同 provider / 同模型 / 同协议；文本块的 `textSignature` 记
+ *   message item 的 id（与 phase），同模型时以带 id 的 message item 回放，否则退回
+ *   `{role:"assistant", content}`；工具调用 `id` 是 `call_id`，`thoughtSignature` 记 function_call
+ *   item 的 `fc_…` id（同模型才带回，跨模型由 transform.ts 去掉）；
+ * - `supportsStore`：发 `store: false`，推理模型同时要 `include: ["reasoning.encrypted_content"]`
+ *   （不落服务端也能多轮回放推理）；
+ * - reasoning：`{effort, summary:"auto"}`（summary 需 `supportsReasoningSummary`）；off 只在映射表
+ *   给了 off 的字串时发（例如 "none"），否则不发（服务端缺省）；
+ * - 工具 `strict` 显式给出：Responses 缺省按严格模式校验 schema，非严格兼容的 schema 必须发 false；
+ * - 缓存（第三波 §1.3）：`prompt_cache_key = sessionId` 只在 `sendPromptCacheKey`（官方端点缺省开）
+ *   时发，`cacheRetention: "none"` 不发；`long` 在 `supportsExplicitPromptCacheMode` 时发
+ *   `prompt_cache_options: {ttl:"30m"}`，否则在 `supportsLongCacheRetention` 时发
+ *   `prompt_cache_retention: "24h"`，两者都不支持按 short；
+ * - `toolChoice: "none"`（有工具时）→ `tool_choice: "none"`。
+ */
+import type { AssistantMessage, Model, ModelThinkingLevel, OpenAIResponsesCompat, ProviderData, StreamOptions, ToolResultMessage, TranscriptContext, UserMessage } from "../types.js";
+type Json = Record<string, unknown>;
+type Conversation = UserMessage | AssistantMessage | ToolResultMessage;
+export declare const RESPONSES_API = "openai-responses";
+/** 缺省（未知的 Responses 兼容服务）：不要 summary、不发 store。 */
+export declare const CONSERVATIVE_RESPONSES_COMPAT: Readonly<OpenAIResponsesCompat>;
+/** 推断表：先 provider id，后 baseUrl 子串。 */
+export declare const RESPONSES_INFERENCE_RULES: readonly {
+    provider: string;
+    baseUrl: string;
+    patch: Partial<OpenAIResponsesCompat>;
+}[];
+/** compat：保守缺省 ← 推断表 ← provider.compat ← model.compat。 */
+export declare function detectResponsesCompat(model: Model, provider?: ProviderData): OpenAIResponsesCompat;
+export interface MessageSignature {
+    id: string;
+    phase?: string;
+}
+export declare function encodeMessageSignature(id: string, phase?: string): string;
+export declare function parseMessageSignature(signature: string | undefined): MessageSignature | undefined;
+/** thinkingSignature → reasoning item（不是 reasoning item 的 JSON 返回 undefined）。 */
+export declare function parseReasoningItem(signature: string | undefined): Json | undefined;
+export declare function convertResponsesInput(model: Model, messages: readonly Conversation[]): Json[];
+export interface ResponsesRequest {
+    body: Json;
+    compat: OpenAIResponsesCompat;
+    thinkingLevel: ModelThinkingLevel;
+    providerThinkingLevel: string | undefined;
+}
+export declare function buildResponsesRequest(model: Model, context: TranscriptContext, options: StreamOptions): ResponsesRequest;
+export {};

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

@@ -0,0 +1,266 @@
+/**
+ * openai-responses 请求体（设计 §3.1、§3.3、§3.6）：input items、instructions、工具、reasoning、
+ * 缓存键、无状态回放。
+ *
+ * - 系统提示折叠后放 `instructions`（不进 input，前缀稳定利于缓存）；
+ * - 助手消息拆成 items：思考块的 `thinkingSignature` 是完整的 reasoning item（JSON，含
+ *   `encrypted_content`），只回放给同 provider / 同模型 / 同协议；文本块的 `textSignature` 记
+ *   message item 的 id（与 phase），同模型时以带 id 的 message item 回放，否则退回
+ *   `{role:"assistant", content}`；工具调用 `id` 是 `call_id`，`thoughtSignature` 记 function_call
+ *   item 的 `fc_…` id（同模型才带回，跨模型由 transform.ts 去掉）；
+ * - `supportsStore`：发 `store: false`，推理模型同时要 `include: ["reasoning.encrypted_content"]`
+ *   （不落服务端也能多轮回放推理）；
+ * - reasoning：`{effort, summary:"auto"}`（summary 需 `supportsReasoningSummary`）；off 只在映射表
+ *   给了 off 的字串时发（例如 "none"），否则不发（服务端缺省）；
+ * - 工具 `strict` 显式给出：Responses 缺省按严格模式校验 schema，非严格兼容的 schema 必须发 false；
+ * - 缓存（第三波 §1.3）：`prompt_cache_key = sessionId` 只在 `sendPromptCacheKey`（官方端点缺省开）
+ *   时发，`cacheRetention: "none"` 不发；`long` 在 `supportsExplicitPromptCacheMode` 时发
+ *   `prompt_cache_options: {ttl:"30m"}`，否则在 `supportsLongCacheRetention` 时发
+ *   `prompt_cache_retention: "24h"`，两者都不支持按 short；
+ * - `toolChoice: "none"`（有工具时）→ `tool_choice: "none"`。
+ */
+import { contentText, normalizeContext, sanitizeText } from "../context.js";
+import { clampThinkingLevel, mappedThinkingValue } from "../thinking.js";
+import { resolveCacheRetention, resolvePromptCacheCompat } from "./cache-params.js";
+import { isStrictCompatible } from "./openai-request.js";
+export const RESPONSES_API = "openai-responses";
+const RESPONSES_COMPAT_KEYS = [
+    "supportsReasoningSummary",
+    "supportsStore",
+];
+/** 缺省（未知的 Responses 兼容服务）：不要 summary、不发 store。 */
+export const CONSERVATIVE_RESPONSES_COMPAT = {
+    supportsReasoningSummary: false,
+    supportsStore: false,
+};
+/** 推断表：先 provider id，后 baseUrl 子串。 */
+export const RESPONSES_INFERENCE_RULES = [
+    {
+        provider: "openai",
+        baseUrl: "api.openai.com",
+        patch: { supportsReasoningSummary: true, supportsStore: true },
+    },
+    // xAI：store 与 encrypted_content 可用；未验证 reasoning summary，不发
+    { provider: "xai", baseUrl: "api.x.ai", patch: { supportsStore: true } },
+];
+function pick(compat) {
+    const out = {};
+    for (const key of RESPONSES_COMPAT_KEYS) {
+        const value = compat?.[key];
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+/** compat：保守缺省 ← 推断表 ← provider.compat ← model.compat。 */
+export function detectResponsesCompat(model, provider) {
+    const providerId = provider?.id ?? model.provider;
+    const baseUrl = (model.baseUrl ?? provider?.baseUrl ?? "").toLowerCase();
+    const rule = RESPONSES_INFERENCE_RULES.find((r) => r.provider === providerId) ??
+        RESPONSES_INFERENCE_RULES.find((r) => baseUrl.includes(r.baseUrl));
+    return {
+        ...CONSERVATIVE_RESPONSES_COMPAT,
+        ...rule?.patch,
+        ...pick(provider?.compat),
+        ...pick(model.compat),
+    };
+}
+export function encodeMessageSignature(id, phase) {
+    return JSON.stringify(phase ? { v: 1, id, phase } : { v: 1, id });
+}
+export function parseMessageSignature(signature) {
+    if (!signature?.startsWith("{"))
+        return undefined;
+    try {
+        const parsed = JSON.parse(signature);
+        if (parsed["v"] !== 1 || typeof parsed["id"] !== "string")
+            return undefined;
+        return typeof parsed["phase"] === "string"
+            ? { id: parsed["id"], phase: parsed["phase"] }
+            : { id: parsed["id"] };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** thinkingSignature → reasoning item（不是 reasoning item 的 JSON 返回 undefined）。 */
+export function parseReasoningItem(signature) {
+    if (!signature?.startsWith("{"))
+        return undefined;
+    try {
+        const parsed = JSON.parse(signature);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            return undefined;
+        const item = parsed;
+        return item["type"] === "reasoning" && typeof item["id"] === "string" ? item : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---------------------------------------------------------------------------
+// input items
+// ---------------------------------------------------------------------------
+function imagePart(block) {
+    return {
+        type: "input_image",
+        detail: "auto",
+        image_url: `data:${block.mimeType};base64,${block.data}`,
+    };
+}
+function convertUser(message) {
+    const blocks = typeof message.content === "string"
+        ? [{ type: "text", text: message.content }]
+        : message.content;
+    const content = [];
+    for (const block of blocks) {
+        if (block.type === "image")
+            content.push(imagePart(block));
+        else if (block.text.length > 0) {
+            content.push({ type: "input_text", text: sanitizeText(block.text) });
+        }
+    }
+    return content.length > 0 ? { role: "user", content } : undefined;
+}
+function convertAssistant(model, message) {
+    const sameModel = message.provider === model.provider &&
+        message.model === model.id &&
+        message.api === RESPONSES_API;
+    const items = [];
+    for (const block of message.content) {
+        if (block.type === "thinking") {
+            // 推理只能以 reasoning item 回放；没有可用 item 的（别家 / 中止）不发
+            const item = sameModel ? parseReasoningItem(block.thinkingSignature) : undefined;
+            if (item)
+                items.push(item);
+        }
+        else if (block.type === "text") {
+            const signature = sameModel ? parseMessageSignature(block.textSignature) : undefined;
+            if (signature) {
+                items.push({
+                    type: "message",
+                    role: "assistant",
+                    id: signature.id,
+                    status: "completed",
+                    content: [{ type: "output_text", text: sanitizeText(block.text), annotations: [] }],
+                    ...(signature.phase ? { phase: signature.phase } : {}),
+                });
+            }
+            else if (block.text.trim().length > 0) {
+                items.push({ role: "assistant", content: sanitizeText(block.text) });
+            }
+        }
+        else {
+            const itemId = block.thoughtSignature;
+            items.push({
+                type: "function_call",
+                ...(sameModel && itemId?.startsWith("fc") ? { id: itemId } : {}),
+                call_id: block.id,
+                name: block.name,
+                arguments: JSON.stringify(block.arguments),
+            });
+        }
+    }
+    return items;
+}
+function convertToolResult(model, message) {
+    const text = contentText(message.content);
+    const images = typeof message.content === "string" || !model.input.includes("image")
+        ? []
+        : message.content.filter((b) => b.type === "image");
+    let output;
+    if (images.length === 0) {
+        const hadImages = typeof message.content !== "string" && message.content.length > 0;
+        output = sanitizeText(text.length > 0 ? text : hadImages ? "(see attached image)" : "(no output)");
+    }
+    else {
+        output = [
+            ...(text.length > 0 ? [{ type: "input_text", text: sanitizeText(text) }] : []),
+            ...images.map(imagePart),
+        ];
+    }
+    return { type: "function_call_output", call_id: message.toolCallId, output };
+}
+export function convertResponsesInput(model, messages) {
+    const input = [];
+    for (const message of messages) {
+        if (message.role === "user") {
+            const converted = convertUser(message);
+            if (converted)
+                input.push(converted);
+        }
+        else if (message.role === "assistant") {
+            input.push(...convertAssistant(model, message));
+        }
+        else {
+            input.push(convertToolResult(model, message));
+        }
+    }
+    return input;
+}
+function convertTools(tools) {
+    return tools.map((tool) => {
+        const parameters = { ...tool.parameters, type: "object" };
+        return {
+            type: "function",
+            name: tool.name,
+            description: tool.description,
+            parameters,
+            strict: isStrictCompatible(parameters),
+        };
+    });
+}
+/** 写 reasoning；返回实际发出的 effort。 */
+function applyReasoning(body, model, compat, level) {
+    if (!model.reasoning)
+        return undefined;
+    if (level === "off") {
+        const off = model.thinkingLevelMap?.off;
+        if (typeof off !== "string")
+            return undefined;
+        body["reasoning"] = { effort: off };
+        return off;
+    }
+    const mapped = mappedThinkingValue(model, level);
+    const effort = typeof mapped === "string" ? mapped : level;
+    body["reasoning"] = compat.supportsReasoningSummary ? { effort, summary: "auto" } : { effort };
+    return effort;
+}
+export function buildResponsesRequest(model, context, options) {
+    const compat = detectResponsesCompat(model);
+    const normalized = normalizeContext(context, { model });
+    const level = clampThinkingLevel(model, options.thinkingLevel ?? "off");
+    const body = { model: model.id, stream: true };
+    if (normalized.systemPrompt.length > 0) {
+        body["instructions"] = sanitizeText(normalized.systemPrompt);
+    }
+    body["input"] = convertResponsesInput(model, normalized.messages);
+    body["max_output_tokens"] = options.maxTokens ?? model.maxTokens;
+    if (compat.supportsStore) {
+        body["store"] = false;
+        if (model.reasoning)
+            body["include"] = ["reasoning.encrypted_content"];
+    }
+    if (normalized.tools.length > 0) {
+        body["tools"] = convertTools(normalized.tools);
+        if (options.toolChoice === "none")
+            body["tool_choice"] = "none";
+    }
+    if (options.temperature !== undefined)
+        body["temperature"] = options.temperature;
+    const cacheCompat = resolvePromptCacheCompat(model, RESPONSES_API);
+    const retention = resolveCacheRetention(options.cacheRetention);
+    if (options.sessionId && retention !== "none" && cacheCompat.sendPromptCacheKey) {
+        body["prompt_cache_key"] = options.sessionId.slice(0, 64);
+    }
+    if (retention === "long" && cacheCompat.supportsExplicitPromptCacheMode) {
+        body["prompt_cache_options"] = { ttl: "30m" };
+    }
+    else if (retention === "long" && cacheCompat.supportsLongCacheRetention) {
+        body["prompt_cache_retention"] = "24h";
+    }
+    const providerLevel = applyReasoning(body, model, compat, level);
+    if (model.samplingParams)
+        Object.assign(body, model.samplingParams);
+    return { body, compat, thinkingLevel: level, providerThinkingLevel: providerLevel };
+}

package/dist/ai/apis/openai-responses.d.ts

@@ -0,0 +1,28 @@
+/**
+ * openai-responses 协议（设计 §3.1）：POST `{baseUrl}/responses`（stream），`event: response.*` →
+ * 事件；没有 `[DONE]`，以 `response.completed / incomplete / failed` 结束。
+ *
+ * - 每个 output item 一个内容块（按 `output_index` 对应，缺省时按 item id）：reasoning → 思考、
+ *   message → 文本、function_call → 工具调用；`output_item.done` 关块并记签名：reasoning 记完整
+ *   item（含 `encrypted_content`，供无状态回放），message 记 id / phase，function_call 记 `fc_` id；
+ * - 思考文本来自 `reasoning_summary_text.delta`（多段 summary 之间空一行）或
+ *   `reasoning_text.delta`；增量缺失而 done 里有全文时补齐；
+ * - `function_call_arguments.done` 与已拼接的增量不一致时以前缀补齐；
+ * - 停止：completed → stop（有工具调用则 toolUse）；incomplete + max_output_tokens → length，其它
+ *   incomplete 原因 → error；failed / `error` 事件 → error（`code: message`）；无终止事件 → 断流；
+ * - usage：input = input_tokens − input_tokens_details.cached_tokens，reasoning =
+ *   output_tokens_details.reasoning_tokens（已含在 output_tokens 里）；cached_tokens 出现（含 0）即
+ *   `cacheReported: true`。
+ */
+import type { ApiImplementation, OpenAIResponsesCompat, Usage } from "../types.js";
+type Json = Record<string, unknown>;
+export declare function parseResponsesUsage(raw: Json): Usage;
+type MappedStop = {
+    reason: "stop" | "length";
+} | {
+    reason: "error";
+    message: string;
+};
+export declare function mapResponsesStatus(status: string | undefined, incomplete?: string): MappedStop;
+export declare const openAIResponsesApi: ApiImplementation<OpenAIResponsesCompat>;
+export {};