@codehz/ai 0.4.3 → 0.4.5

package/src/adapters/responses.ts

@@ -27,6 +27,9 @@ import {
   openProviderJsonStream,
   iterateProviderStreamBatches,
   createCompletionGate,
+  mergeProviderHeaders,
+  applyExtraBody,
+  mapResponsesReasoning,
 } from "../helpers/index.js";
 
 import type { NormalizedRequest, AIStreamEvent, EventFactory, OutputItem, FetchFn } from "../index.js";
@@ -38,9 +41,17 @@ export type ResponsesAdapterOptions = {
   baseUrl?: string;
   /** 可注入自定义 fetch 实现（用于测试／代理） */
   fetch?: FetchFn;
+  /** 额外请求头；后写覆盖内置 Authorization / Content-Type */
+  headers?: Record<string, string>;
+  /** 额外 body 顶层字段；浅层合并，同名键可覆盖 */
+  extraBody?: Record<string, unknown>;
 };
 
-// ── Responses API 请求类型 ────────────────────────────────────
+// ── Responses API 请求类型（对齐 OpenAI Responses schema）────
+//
+// input 是 untagged enum ModelInput = string | InputItem[]。
+// 每个 InputItem 也必须命中官方 variant，否则会 422：
+//   "data did not match any variant of untagged enum ModelInput"
 
 type ResponsesAPIRequest = {
   model: string;
@@ -51,27 +62,72 @@ type ResponsesAPIRequest = {
   metadata?: Record<string, string>;
   temperature?: number;
   max_output_tokens?: number;
+  /** Portable reasoningLevel → effort；summary 等特化字段不在此层 */
+  reasoning?: { effort: string };
+  /** 服务端多轮续写；opaque replay 的 response id 映射到此字段，而非 item_reference */
+  previous_response_id?: string;
   stream: true;
 };
 
+/** EasyInputMessage：content 可为 string，或 input_* content parts */
+type ResponsesEasyMessage = {
+  type: "message";
+  role: "user" | "assistant" | "system" | "developer";
+  content: string | ResponsesInputContentPart[];
+};
+
+type ResponsesInputContentPart =
+  | { type: "input_text"; text: string }
+  | { type: "input_image"; image_url: string; detail?: "auto" | "low" | "high" }
+  | { type: "input_file"; file_url?: string; file_id?: string; filename?: string };
+
+/** function_call：call_id 必填；id 是可选的 item id */
+type ResponsesFunctionCall = {
+  type: "function_call";
+  call_id: string;
+  name: string;
+  arguments: string;
+  id?: string;
+  status?: "in_progress" | "completed" | "incomplete";
+};
+
+type ResponsesFunctionCallOutput = {
+  type: "function_call_output";
+  call_id: string;
+  output: string;
+  id?: string;
+  status?: "in_progress" | "completed" | "incomplete";
+};
+
+/** reasoning：id + summary/content/encrypted_content，不是任意 content blocks */
+type ResponsesReasoningInput = {
+  type: "reasoning";
+  id: string;
+  summary: Array<{ type: "summary_text"; text: string }>;
+  content?: Array<{ type: "reasoning_text"; text: string }>;
+  encrypted_content?: string | null;
+  status?: "in_progress" | "completed" | "incomplete";
+};
+
+/** 引用既有 item（不是 response id） */
+type ResponsesItemReference = {
+  type: "item_reference";
+  id: string;
+};
+
 type ResponsesInputItem =
-  | { type: "message"; role: "user" | "assistant"; content: string }
-  | { type: "message"; role: "assistant"; content: ResponsesContentBlock[] }
-  | { type: "function_call"; id: string; name: string; arguments: string; call_id?: string }
-  | { type: "function_call_output"; call_id: string; output: string }
-  | { type: "reasoning"; content: ResponsesContentBlock[] }
-  | { type: "item_reference"; id: string };
-
-type ResponsesContentBlock =
-  | { type: "text"; text: string }
-  | { type: "reasoning"; text: string }
-  | { type: "refusal"; refusal: string };
+  | ResponsesEasyMessage
+  | ResponsesFunctionCall
+  | ResponsesFunctionCallOutput
+  | ResponsesReasoningInput
+  | ResponsesItemReference;
 
 type ResponsesTool = {
   type: "function";
   name: string;
   description?: string;
   parameters: Record<string, unknown>;
+  strict?: boolean | null;
 };
 
 const mapper = new NormalizedRequestMapper("responses");
@@ -209,11 +265,12 @@ type ResponsesAPIOutputItem = {
   id: string;
   type: "message" | "reasoning" | "function_call" | string;
   role?: string;
-  content?: ResponsesContentBlock[] | Array<{ type: string; text?: string; [key: string]: unknown }>;
+  content?: Array<{ type: string; text?: string; [key: string]: unknown }>;
   summary?: Array<{ type: string; text?: string; [key: string]: unknown }>;
   encrypted_content?: string | null;
   name?: string;
   arguments?: string;
+  call_id?: string;
   status?: string;
   [key: string]: unknown;
 };
@@ -232,15 +289,56 @@ function extractFailureMessage(response: ResponsesAPIResponse): string {
   return response.error?.message ?? response.failure?.message ?? "unknown";
 }
 
-// ── Content block 映射 ─────────────────────────────────────────
+function readNonEmptyString(value: unknown, maxLen = 256): string | undefined {
+  if (typeof value !== "string" || value.length === 0 || value.length > maxLen) return undefined;
+  return value;
+}
+
+/** 将 canonical text/json blocks 压成 EasyInputMessage 的 string content。 */
+function messageContentAsString(
+  blocks: import("../index.js").ContentBlock[],
+  field: string,
+): string {
+  return mapper.textFromBlocks(blocks, field);
+}
 
-function canonicalToResponsesBlock(b: import("../index.js").ContentBlock): ResponsesContentBlock {
-  if (b.type === "text") return { type: "text", text: b.text };
-  if (b.type === "json") return { type: "text", text: JSON.stringify(b.json) };
-  throw new AIRequestError(
-    `responses does not support content block type "${b.type}" in canonical mapping`,
-    "UNSUPPORTED_CONTENT_BLOCK",
+function mapReasoningInput(item: import("../index.js").ReasoningItem, index: number): ResponsesReasoningInput {
+  const text = mapper.textFromBlocks(
+    mapper.ensureReasoningBlocks(item.content, "reasoning content"),
+    "reasoning content",
   );
+  const id = item.id && item.id.length > 0 ? item.id : `reasoning_replay_${index}`;
+
+  if (item.visibility === "full") {
+    return {
+      type: "reasoning",
+      id,
+      summary: [],
+      content: text ? [{ type: "reasoning_text", text }] : undefined,
+    };
+  }
+
+  // summary / redacted / opaque：公开可回传的是 summary_text
+  return {
+    type: "reasoning",
+    id,
+    summary: text ? [{ type: "summary_text", text }] : [],
+  };
+}
+
+function extractOpaqueContinuationId(payload: Record<string, unknown>): {
+  previousResponseId?: string;
+  itemReferenceId?: string;
+} {
+  // 优先显式 previous_response_id；历史 payload 用 id 存 response 续写句柄
+  const previousResponseId =
+    readNonEmptyString(payload.previous_response_id) ??
+    (typeof payload.item_id === "string" ? undefined : readNonEmptyString(payload.id));
+
+  // 仅在显式给出 item_id 时使用 item_reference（引用的是 item，不是 response）
+  const itemReferenceId = readNonEmptyString(payload.item_id);
+
+  return { previousResponseId, itemReferenceId };
 }
 
 // ── Adapter ───────────────────────────────────────────────────
@@ -252,48 +350,46 @@ export class ResponsesAdapter extends AdapterBase {
   private apiKey: string;
   private baseUrl: string;
   private fetchFn: FetchFn;
+  private headers: Record<string, string> | undefined;
+  private extraBody: Record<string, unknown> | undefined;
 
   constructor(options: ResponsesAdapterOptions) {
     super();
     this.apiKey = options.apiKey;
     this.baseUrl = options.baseUrl ?? "https://api.openai.com/v1";
     this.fetchFn = options.fetch ?? globalThis.fetch;
+    this.headers = options.headers;
+    this.extraBody = options.extraBody;
   }
 
   // ── buildRequest ──────────────────────────────────────────
 
   protected buildRequest(request: NormalizedRequest): ResponsesAPIRequest {
     const input: ResponsesInputItem[] = [];
+    let previousResponseId: string | undefined;
+    let reasoningIndex = 0;
 
     for (const item of request.input) {
       switch (item.type) {
         case "message": {
-          // Responses API 中只有 assistant 角色支持 content blocks
-          if (item.role === "assistant") {
-            const blocks = mapper
-              .ensureTextBlocks(item.content, `assistant message (${item.role}) content`)
-              .map(canonicalToResponsesBlock);
-            input.push({ type: "message", role: item.role, content: blocks });
-          } else {
-            input.push({
-              type: "message",
-              role: item.role,
-              content: mapper.textFromBlocks(item.content, `input message (${item.role}) content`),
-            });
-          }
+          // EasyInputMessage：string content 对 user/assistant 都合法，且最不易触发 ModelInput 反序列化失败。
+          // 切勿发送 { type: "text" } —— 官方 content part 是 input_text / output_text。
+          input.push({
+            type: "message",
+            role: item.role,
+            content: messageContentAsString(item.content, `input message (${item.role}) content`),
+          });
           break;
         }
         case "reasoning": {
-          const blocks = mapper
-            .ensureReasoningBlocks(item.content, "reasoning content")
-            .map((b): ResponsesContentBlock => ({ type: "reasoning", text: b.text }));
-          input.push({ type: "reasoning", content: blocks });
+          input.push(mapReasoningInput(item, reasoningIndex++));
           break;
         }
         case "tool_call": {
+          // call_id 必填；canonical ToolCallItem.id 即 call_id（流里会优先取 call_id）
           input.push({
             type: "function_call",
-            id: item.id,
+            call_id: item.id,
             name: item.name,
             arguments: item.argumentsText,
           });
@@ -309,20 +405,28 @@ export class ResponsesAdapter extends AdapterBase {
           break;
         }
         case "opaque": {
-          // Canonical replay items take priority; item_reference is only a fallback
-          // when the consumer kept only the provider continuation id.
+          // Canonical replay 优先；否则用 previous_response_id 做服务端续写。
+          // 注意：response id 不能塞进 item_reference（那是 item id）。
           if (item.source !== "responses" || item.purpose !== "replay") break;
           assertOpaqueReplayEnvelope(item.payload);
           const payload = item.payload as Record<string, unknown>;
-          if ("id" in payload) {
-            if (typeof payload.id !== "string" || payload.id.length === 0 || payload.id.length > 256) {
+
+          // 显式字段校验：id / previous_response_id / item_id 若存在必须是合法 string
+          for (const key of ["id", "previous_response_id", "item_id"] as const) {
+            if (key in payload && (typeof payload[key] !== "string" || payload[key].length === 0 || payload[key].length > 256)) {
               throw new AIRequestError(
-                "Invalid opaque replay payload: id must be a non-empty string (max 256)",
+                `Invalid opaque replay payload: ${key} must be a non-empty string (max 256)`,
                 "INVALID_OPAQUE_REPLAY",
               );
             }
-            if (!hasReplayCanonicalInput(input)) {
-              input.push({ type: "item_reference", id: payload.id });
+          }
+
+          const { previousResponseId: prevId, itemReferenceId } = extractOpaqueContinuationId(payload);
+          if (!hasReplayCanonicalInput(input)) {
+            if (prevId && !previousResponseId) {
+              previousResponseId = prevId;
+            } else if (itemReferenceId) {
+              input.push({ type: "item_reference", id: itemReferenceId });
             }
           }
           break;
@@ -336,6 +440,10 @@ export class ResponsesAdapter extends AdapterBase {
       stream: true,
     };
 
+    if (previousResponseId) {
+      body.previous_response_id = previousResponseId;
+    }
+
     if (request.instructions) {
       body.instructions = mapper.mapInstructions(request.instructions);
     }
@@ -362,8 +470,11 @@ export class ResponsesAdapter extends AdapterBase {
     if (request.temperature !== undefined) body.temperature = request.temperature;
     if (request.maxOutputTokens !== undefined) body.max_output_tokens = request.maxOutputTokens;
     if (request.metadata) body.metadata = request.metadata;
+    if (request.reasoningLevel !== undefined) {
+      body.reasoning = mapResponsesReasoning(request.reasoningLevel);
+    }
 
-    return body;
+    return applyExtraBody(body, this.extraBody);
   }
 
   // ── runStream ─────────────────────────────────────────────
@@ -379,10 +490,13 @@ export class ResponsesAdapter extends AdapterBase {
     const { reader } = await openProviderJsonStream({
       fetchFn: this.fetchFn,
       url: `${this.baseUrl}/responses`,
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${this.apiKey}`,
-      },
+      headers: mergeProviderHeaders(
+        {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`,
+        },
+        this.headers,
+      ),
       body: providerRequest,
       signal: request.signal,
     });
@@ -392,9 +506,14 @@ export class ResponsesAdapter extends AdapterBase {
     let completedResponse: ResponsesAPIResponse | undefined;
     let unknownEventsWarned = false;
     const messageItemsWithDelta = new Set<string>();
+    /** item_id → function name */
     const toolCallNames = new Map<string, string>();
+    /** item_id → call_id（canonical ToolCallItem.id / function_call_output.call_id） */
+    const toolCallIds = new Map<string, string>();
     const reasoningStates = new Map<string, ReasoningStreamState>();
 
+    const resolveToolCallId = (itemId: string): string => toolCallIds.get(itemId) ?? itemId;
+
     const ensureReasoningState = (itemId: string, visibility: ReasoningVisibility = "summary"): ReasoningStreamState => {
       let state = reasoningStates.get(itemId);
       if (!state) {
@@ -449,8 +568,12 @@ export class ResponsesAdapter extends AdapterBase {
             }
             case "function_call": {
               const name = typeof item.name === "string" ? item.name : "unknown";
+              // Responses 用 call_id 关联 function_call_output；item.id 是 fc_* item id
+              const callId =
+                typeof item.call_id === "string" && item.call_id.length > 0 ? item.call_id : item.id;
               toolCallNames.set(item.id, name);
-              yield factory.toolCallStarted(item.id, name);
+              toolCallIds.set(item.id, callId);
+              yield factory.toolCallStarted(callId, name);
               break;
             }
           }
@@ -569,14 +692,19 @@ export class ResponsesAdapter extends AdapterBase {
 
         if (sseEvent.type === "response.function_call_arguments.delta") {
           const data = sseEvent.data as { item_id: string; delta: string };
-          if (data.delta) yield factory.toolCallDelta(data.item_id, { argumentsText: data.delta });
+          if (data.delta) {
+            yield factory.toolCallDelta(resolveToolCallId(data.item_id), { argumentsText: data.delta });
+          }
           continue;
         }
 
         if (sseEvent.type === "response.function_call_arguments.done") {
           const data = sseEvent.data as { item_id: string; arguments: string };
-          const tcItem = toolCallItem(data.item_id, toolCallNames.get(data.item_id) ?? "unknown", data.arguments);
-          yield factory.toolCallCompleted(data.item_id);
+          const callId = resolveToolCallId(data.item_id);
+          // 若 added 事件缺失，done 时仍尽量从 completed payload 之外兜底 call_id
+          if (!toolCallIds.has(data.item_id)) toolCallIds.set(data.item_id, callId);
+          const tcItem = toolCallItem(callId, toolCallNames.get(data.item_id) ?? "unknown", data.arguments);
+          yield factory.toolCallCompleted(callId);
           output.push(tcItem);
           continue;
         }
@@ -640,7 +768,13 @@ export class ResponsesAdapter extends AdapterBase {
 
     const replay = [...replayFromOutput(output)];
     if (completedResponse?.id) {
-      replay.push(opaqueItem("responses", "replay", { id: completedResponse.id }));
+      // 同时保留 id（向后兼容）与 previous_response_id（语义明确）
+      replay.push(
+        opaqueItem("responses", "replay", {
+          id: completedResponse.id,
+          previous_response_id: completedResponse.id,
+        }),
+      );
     }
 
     const stopReason = completedResponse ? this.inferStopReason(completedResponse) : undefined;

package/src/core/validation.ts

@@ -18,6 +18,7 @@ const MESSAGE_ROLES = new Set(["user", "assistant"]);
 const REASONING_VISIBILITIES = new Set(["full", "summary", "redacted", "opaque"]);
 const TOOL_RESULT_OUTCOMES = new Set(["success", "error", "rejected"]);
 const INCLUDE_MODES = new Set(["off", "best_effort"]);
+const REASONING_LEVELS = new Set(["none", "minimal", "low", "medium", "high", "xhigh"]);
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
@@ -333,6 +334,18 @@ export function validateRequest(request: AIRequest): ValidationIssue[] {
     }
   }
 
+  // reasoningLevel 枚举
+  if (request.reasoningLevel !== undefined) {
+    if (typeof request.reasoningLevel !== "string" || !REASONING_LEVELS.has(request.reasoningLevel)) {
+      pushIssue(
+        issues,
+        "reasoningLevel",
+        "REASONING_LEVEL_INVALID",
+        'reasoningLevel must be one of: none, minimal, low, medium, high, xhigh',
+      );
+    }
+  }
+
   if (request.include !== undefined) {
     validateInclude(request.include, issues);
   }

package/src/helpers/index.ts

@@ -70,4 +70,18 @@ export type {
   ProviderStreamBatchOptions,
 } from "./provider-stream.js";
 
+export { mergeProviderHeaders, applyExtraBody } from "./provider-request-options.js";
+
+export {
+  REASONING_LEVELS,
+  REASONING_LEVEL_SET,
+  assertSupportedReasoningLevel,
+  mapResponsesReasoning,
+  mapChatCompletionsReasoningEffort,
+  mapMessagesThinkingBudget,
+  mapMessagesThinking,
+  mapOllamaThink,
+} from "./reasoning-level.js";
+export type { OpenAIReasoningEffort, MessagesThinkingConfig, OllamaThinkValue } from "./reasoning-level.js";
+
 export { NormalizedRequestMapper } from "./request-mapper.js";

package/src/helpers/provider-request-options.ts

@@ -0,0 +1,25 @@
+/**
+ * Provider 请求 headers / body 扩展合并
+ *
+ * 供真实后端 adapter 构造选项 `headers` / `extraBody` 使用：
+ * - headers：内置鉴权头为基，自定义后写覆盖
+ * - extraBody：已构建 body 为基，额外字段浅层 spread，同名顶层键可覆盖
+ */
+
+/** 合并内置 headers 与自定义 headers；自定义后写覆盖同名键。 */
+export function mergeProviderHeaders(
+  base: Record<string, string>,
+  custom?: Record<string, string>,
+): Record<string, string> {
+  if (!custom) return base;
+  return { ...base, ...custom };
+}
+
+/**
+ * 将构造期 extraBody 浅层合并到已构建的 provider body。
+ * 无 extraBody 时原样返回；有则允许覆盖同名顶层键。
+ */
+export function applyExtraBody<T extends object>(body: T, extraBody?: Record<string, unknown>): T {
+  if (!extraBody) return body;
+  return { ...body, ...extraBody };
+}

package/src/helpers/reasoning-level.ts

@@ -0,0 +1,85 @@
+/**
+ * Portable reasoningLevel → provider wire 字段映射
+ *
+ * 第一版只处理 level 枚举；budget/summary 等特化字段不在此层。
+ * 无法映射的 level 抛 AIRequestError(UNSUPPORTED_REASONING_LEVEL)。
+ */
+
+import { AIRequestError } from "../core/errors.js";
+import type { ReasoningLevel } from "../types/request.js";
+
+export const REASONING_LEVELS = ["none", "minimal", "low", "medium", "high", "xhigh"] as const satisfies readonly ReasoningLevel[];
+
+export const REASONING_LEVEL_SET: ReadonlySet<string> = new Set(REASONING_LEVELS);
+
+const MESSAGES_BUDGET_RATIOS: Record<Exclude<ReasoningLevel, "none">, number> = {
+  minimal: 0.02,
+  low: 0.1,
+  medium: 0.3,
+  high: 0.6,
+  xhigh: 0.9,
+};
+
+const OLLAMA_SUPPORTED = new Set<ReasoningLevel>(["none", "low", "medium", "high"]);
+
+export type OpenAIReasoningEffort = ReasoningLevel;
+
+export type MessagesThinkingConfig =
+  | { type: "disabled" }
+  | { type: "enabled"; budget_tokens: number };
+
+export type OllamaThinkValue = false | "low" | "medium" | "high";
+
+/** 若 level 不在 supported 集合内则抛 AIRequestError。 */
+export function assertSupportedReasoningLevel(
+  level: ReasoningLevel,
+  supported: ReadonlySet<ReasoningLevel>,
+  adapterKind: string,
+): void {
+  if (supported.has(level)) return;
+  throw new AIRequestError(
+    `reasoningLevel "${level}" is not supported by the ${adapterKind} adapter`,
+    "UNSUPPORTED_REASONING_LEVEL",
+  );
+}
+
+/** Responses API：`reasoning: { effort }` */
+export function mapResponsesReasoning(level: ReasoningLevel): { effort: OpenAIReasoningEffort } {
+  return { effort: level };
+}
+
+/** Chat Completions：顶层 `reasoning_effort` */
+export function mapChatCompletionsReasoningEffort(level: ReasoningLevel): OpenAIReasoningEffort {
+  return level;
+}
+
+/**
+ * Messages thinking budget。
+ * 基于 maxTokens 按比例推导，clamp 到 [1024, max(1024, maxTokens - 1)]，
+ * 满足 Anthropic budget_tokens < max_tokens。
+ */
+export function mapMessagesThinkingBudget(level: Exclude<ReasoningLevel, "none">, maxTokens: number): number {
+  const ratio = MESSAGES_BUDGET_RATIOS[level];
+  const raw = Math.round(maxTokens * ratio);
+  const upper = Math.max(1024, maxTokens - 1);
+  return Math.min(Math.max(raw, 1024), upper);
+}
+
+/** Messages API：`thinking` 字段 */
+export function mapMessagesThinking(level: ReasoningLevel, maxTokens: number): MessagesThinkingConfig {
+  if (level === "none") {
+    return { type: "disabled" };
+  }
+  return {
+    type: "enabled",
+    budget_tokens: mapMessagesThinkingBudget(level, maxTokens),
+  };
+}
+
+/** Ollama：`think` 字段；minimal/xhigh 不支持 */
+export function mapOllamaThink(level: ReasoningLevel): OllamaThinkValue {
+  assertSupportedReasoningLevel(level, OLLAMA_SUPPORTED, "ollama");
+  if (level === "none") return false;
+  // narrow after assert: only low|medium|high remain
+  return level as Exclude<OllamaThinkValue, false>;
+}

package/src/types/index.ts

@@ -21,7 +21,7 @@ export type {
 } from "./items.js";
 
 // 请求模型
-export type { AIRequest, ToolDefinition, ToolChoice, IncludeSettings } from "./request.js";
+export type { AIRequest, ToolDefinition, ToolChoice, IncludeSettings, ReasoningLevel } from "./request.js";
 
 // 响应模型
 export type { AIResponse, StopReason, Usage, BillingInfo, AuxiliaryInfo, BackendTrace } from "./response.js";

package/src/types/request.ts

@@ -25,6 +25,11 @@ export type IncludeSettings = {
   providerMetadata?: "off" | "best_effort";
 };
 
+// ── reasoning level ───────────────────────────────────────────
+
+/** Portable reasoning / thinking effort. Mapped per-adapter to provider wire fields. */
+export type ReasoningLevel = "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+
 // ── 统一请求 ──────────────────────────────────────────────────
 
 export type AIRequest = {
@@ -36,6 +41,12 @@ export type AIRequest = {
   metadata?: Record<string, string>;
   temperature?: number;
   maxOutputTokens?: number;
+  /**
+   * Portable reasoning effort. Adapters map this to provider-native fields
+   * (e.g. Responses `reasoning.effort`, Chat Completions `reasoning_effort`,
+   * Messages `thinking`, Ollama `think`). Unsupported levels throw.
+   */
+  reasoningLevel?: ReasoningLevel;
   /** AbortSignal 用于打断请求。abort 时 fetch 调用会被取消，流迭代器抛出 AbortError。 */
   signal?: AbortSignal;
 };