@codehz/ai 0.2.0 → 0.2.1

package/src/adapters/responses.ts

@@ -10,7 +10,7 @@
  */
 
 import { AdapterBase } from "../helpers/adapter-base.js";
-import { AIRequestError } from "../core/errors.js";
+import { AIProviderError, AIRequestError, AIStreamError } from "../core/errors.js";
 import {
   textBlock,
   messageItem,
@@ -22,9 +22,10 @@ import {
   contentBlocksToText,
 } from "../helpers/mapping.js";
 import { emitMalformedStreamWarning } from "../helpers/adapter-auxiliary.js";
+import { assertOpaqueReplayEnvelope, providerHttpError } from "../helpers/adapter-security.js";
 import { usageFromOpenAIResponses } from "../helpers/usage-mapping.js";
-
-import { parseSSEEvents } from "../helpers/sse-parser.js";
+import { NormalizedRequestMapper, splitSSEFrames, IncrementalStreamParser } from "../helpers/index.js";
+import type { ProviderProfile } from "../helpers/index.js";
 
 import type { NormalizedRequest, AIStreamEvent, EventFactory, OutputItem, FetchFn } from "../index.js";
 
@@ -71,54 +72,24 @@ type ResponsesTool = {
   input_schema: Record<string, unknown>;
 };
 
-function ensureResponsesTextBlocks(
-  blocks: import("../index.js").ContentBlock[],
-  field: string,
-): import("../index.js").ContentBlock[] {
-  for (let i = 0; i < blocks.length; i++) {
-    const block = blocks[i];
-    if (!block) continue;
-    if (block.type !== "text" && block.type !== "json") {
-      throw new AIRequestError(
-        `responses does not support ${field}[${i}] of type "${block.type}"; only text/json blocks are supported`,
-        "UNSUPPORTED_CONTENT_BLOCK",
-      );
-    }
-  }
-
-  return blocks;
-}
-
-function ensureResponsesReasoningBlocks(
-  blocks: import("../index.js").ContentBlock[],
-  field: string,
-): Array<Extract<import("../index.js").ContentBlock, { type: "text" }>> {
-  return blocks.map((block, index) => {
-    if (block.type !== "text") {
-      throw new AIRequestError(
-        `responses does not support ${field}[${index}] of type "${block.type}"; reasoning only supports text blocks`,
-        "UNSUPPORTED_CONTENT_BLOCK",
-      );
-    }
-
-    return block;
-  });
-}
-
-function instructionsToResponsesText(instructions: string | import("../index.js").InstructionBlock[]): string {
-  return typeof instructions === "string"
-    ? instructions
-    : contentBlocksToText(ensureResponsesTextBlocks(instructions, "instructions"));
-}
+// ── ProviderProfile & Mapper ────────────────────────────────────
+
+const profile: ProviderProfile = {
+  kind: "responses",
+  instructionsMode: "instructions_field",
+  supportedBlockTypes: ["text", "json"] as const,
+  reasoningBlockTypes: ["text"] as const,
+  capabilities: {
+    textStreaming: "native",
+    reasoningStreaming: "native",
+    toolCallStreaming: "native",
+    replay: "opaque",
+    usage: "final",
+    toolResultOutcomes: ["success"],
+  },
+};
 
-function assertResponsesToolResultOutcome(outcome: import("../index.js").ToolResultItem["outcome"]): void {
-  if (outcome !== "success") {
-    throw new AIRequestError(
-      `responses does not preserve tool_result outcome "${outcome}"; only "success" is supported`,
-      "UNSUPPORTED_TOOL_RESULT_OUTCOME",
-    );
-  }
-}
+const mapper = new NormalizedRequestMapper(profile);
 
 // ── SSE 事件类型 ──────────────────────────────────────────────
 
@@ -131,12 +102,43 @@ type ResponsesSSEEvent =
   | { type: "response.tool_call.delta"; data: { item_id: string; delta: { arguments?: string } } }
   | { type: "response.tool_call.done"; data: { item_id: string; arguments?: string; name?: string } }
   | { type: "response.completed"; data: { response: ResponsesAPIResponse } }
-  | { type: "error"; data: { message: string; code?: string } };
+  | { type: "response.failed"; data: { response: ResponsesAPIResponse } }
+  | { type: "response.incomplete"; data: { response: ResponsesAPIResponse } }
+  | { type: "error"; data: { message: string; code?: string } }
+  | { type: string; data: Record<string, unknown> };
+
+/** 已处理或可安全忽略的 Responses SSE 类型（未知类型会 warning 一次）。 */
+const KNOWN_RESPONSES_SSE_TYPES = new Set([
+  "response.output_item.added",
+  "response.output_item.done",
+  "response.output_text.delta",
+  "response.output_text.done",
+  "response.reasoning.delta",
+  "response.reasoning.done",
+  "response.tool_call.delta",
+  "response.tool_call.done",
+  "response.function_call_arguments.delta",
+  "response.function_call_arguments.done",
+  "response.content_part.added",
+  "response.content_part.done",
+  "response.refusal.delta",
+  "response.refusal.done",
+  "response.in_progress",
+  "response.created",
+  "response.completed",
+  "response.failed",
+  "response.incomplete",
+  "error",
+]);
 
 type ResponsesAPIResponse = {
   id: string;
   model: string;
   output: ResponsesAPIOutputItem[];
+  status?: "completed" | "failed" | "in_progress" | "cancelled" | "queued" | "incomplete" | string;
+  incomplete_details?: { reason?: string | null } | null;
+  error?: { message?: string; code?: string } | null;
+  failure?: { message?: string; code?: string } | null;
   usage?: {
     input_tokens: number;
     output_tokens: number;
@@ -156,25 +158,18 @@ type ResponsesAPIOutputItem = {
   status?: string;
 };
 
-// ── SSE 解析 ──────────────────────────────────────────────────
-
-function parseSSE(chunk: string): { events: ResponsesSSEEvent[]; rest: string; malformedEvents: number } {
-  const result = parseSSEEvents(chunk);
-  return { events: result.events as ResponsesSSEEvent[], rest: result.rest, malformedEvents: result.malformedEvents };
-}
-
 function isReplayCanonicalInput(item: ResponsesInputItem): boolean {
   return (
     (item.type === "message" && item.role === "assistant") || item.type === "reasoning" || item.type === "function_call"
   );
 }
 
-function rollbackTrailingReplayCanonicalItems(input: ResponsesInputItem[]): void {
-  while (input.length > 0) {
-    const last = input[input.length - 1];
-    if (!last || !isReplayCanonicalInput(last)) break;
-    input.pop();
-  }
+function hasReplayCanonicalInput(input: ResponsesInputItem[]): boolean {
+  return input.some(isReplayCanonicalInput);
+}
+
+function extractFailureMessage(response: ResponsesAPIResponse): string {
+  return response.error?.message ?? response.failure?.message ?? "unknown";
 }
 
 // ── Content block 映射 ─────────────────────────────────────────
@@ -192,7 +187,7 @@ function canonicalToResponsesBlock(b: import("../index.js").ContentBlock): Respo
 
 export class ResponsesAdapter extends AdapterBase {
   readonly kind = "responses" as const;
-  readonly nativeStreaming = true;
+  readonly capabilities = profile.capabilities;
 
   private apiKey: string;
   private baseUrl: string;
@@ -215,25 +210,25 @@ export class ResponsesAdapter extends AdapterBase {
         case "message": {
           // Responses API 中只有 assistant 角色支持 content blocks
           if (item.role === "assistant") {
-            const blocks = ensureResponsesTextBlocks(item.content, `assistant message (${item.role}) content`).map(
-              canonicalToResponsesBlock,
-            );
+            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: contentBlocksToText(
-                ensureResponsesTextBlocks(item.content, `input message (${item.role}) content`),
+                mapper.ensureTextBlocks(item.content, `input message (${item.role}) content`),
               ),
             });
           }
           break;
         }
         case "reasoning": {
-          const blocks = ensureResponsesReasoningBlocks(item.content, "reasoning content").map(
-            (b): ResponsesContentBlock => ({ type: "reasoning", text: b.text }),
-          );
+          const blocks = mapper
+            .ensureReasoningBlocks(item.content, "reasoning content")
+            .map((b): ResponsesContentBlock => ({ type: "reasoning", text: b.text }));
           input.push({ type: "reasoning", content: blocks });
           break;
         }
@@ -247,8 +242,9 @@ export class ResponsesAdapter extends AdapterBase {
           break;
         }
         case "tool_result": {
-          assertResponsesToolResultOutcome(item.outcome);
-          const output = ensureResponsesTextBlocks(item.content, `tool_result ${item.callId} content`)
+          mapper.assertToolResultOutcome(item.outcome);
+          const output = mapper
+            .ensureTextBlocks(item.content, `tool_result ${item.callId} content`)
             .map(blockToText)
             .join("\n");
           input.push({
@@ -259,18 +255,20 @@ export class ResponsesAdapter extends AdapterBase {
           break;
         }
         case "opaque": {
-          // opaque items with item_reference purpose can be passed through
-          if (
-            item.source === "responses" &&
-            item.purpose === "replay" &&
-            typeof item.payload === "object" &&
-            item.payload !== null &&
-            "id" in (item.payload as Record<string, unknown>)
-          ) {
-            const { id } = item.payload as Record<string, unknown>;
-            if (typeof id === "string") {
-              rollbackTrailingReplayCanonicalItems(input);
-              input.push({ type: "item_reference", id });
+          // Canonical replay items take priority; item_reference is only a fallback
+          // when the consumer kept only the provider continuation 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) {
+              throw new AIRequestError(
+                "Invalid opaque replay payload: id must be a non-empty string (max 256)",
+                "INVALID_OPAQUE_REPLAY",
+              );
+            }
+            if (!hasReplayCanonicalInput(input)) {
+              input.push({ type: "item_reference", id: payload.id });
             }
           }
           break;
@@ -285,7 +283,7 @@ export class ResponsesAdapter extends AdapterBase {
     };
 
     if (request.instructions) {
-      body.instructions = instructionsToResponsesText(request.instructions);
+      body.instructions = mapper.mapInstructions(request.instructions);
     }
 
     if (request.tools && request.tools.length > 0) {
@@ -322,39 +320,66 @@ export class ResponsesAdapter extends AdapterBase {
     request: NormalizedRequest,
   ): AsyncIterable<AIStreamEvent> {
     const auxiliary = this.createAuxiliaryState(request);
-    const response = await this.fetchFn(`${this.baseUrl}/responses`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${this.apiKey}`,
-      },
-      body: JSON.stringify(providerRequest),
-    });
+    let response: Response;
+
+    try {
+      response = await this.fetchFn(`${this.baseUrl}/responses`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`,
+        },
+        body: JSON.stringify(providerRequest),
+      });
+    } catch (err) {
+      throw new AIProviderError(err instanceof Error ? err.message : String(err), "PROVIDER_ERROR");
+    }
 
     if (!response.ok) {
-      const errorText = await response.text().catch(() => "unknown error");
-      throw new Error(`Responses API error ${response.status}: ${errorText}`);
+      const errorBody = await response.text().catch(() => "");
+      throw providerHttpError(response.status, errorBody);
     }
 
     const reader = response.body?.getReader();
     if (!reader) {
-      throw new Error("Response body is not readable");
+      throw new AIStreamError("Response body is not readable", "STREAM_ERROR");
     }
 
     // 流式累积状态
+    const parser = new IncrementalStreamParser<ResponsesSSEEvent>(splitSSEFrames, (frame: string) => {
+      let eventType = "";
+      let dataStr = "";
+      for (const rawLine of frame.split("\n")) {
+        const line = rawLine.trim();
+        if (line.startsWith("event: ")) eventType = line.slice(7).trim();
+        else if (line.startsWith("data: ")) dataStr += line.slice(6);
+      }
+      if (!eventType) return { status: "ignored" };
+      try {
+        const data = JSON.parse(dataStr);
+        return { status: "parsed", value: { type: eventType, data } as ResponsesSSEEvent };
+      } catch {
+        return { status: "malformed" };
+      }
+    });
+
     const output: OutputItem[] = [];
-    const decoder = new TextDecoder();
-    let buffer = "";
+    let streamDone = false;
     let completedResponse: ResponsesAPIResponse | undefined;
+    let completedEmitted = false;
+    let unknownEventsWarned = false;
+    const messageItemsWithDelta = new Set<string>();
 
     try {
       while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-
-        buffer += decoder.decode(value, { stream: true });
-        const { events, rest, malformedEvents } = parseSSE(buffer);
-        buffer = rest;
+        const readResult = await reader.read().catch((err: unknown) => {
+          throw new AIStreamError(
+            `Failed to read response stream: ${err instanceof Error ? err.message : String(err)}`,
+            "STREAM_ERROR",
+          );
+        });
+        const { done, value } = readResult;
+        const { items: events, malformed: malformedEvents } = done ? parser.flush() : parser.feed(value as Uint8Array);
 
         const malformedWarning = emitMalformedStreamWarning(factory, {
           count: malformedEvents,
@@ -367,13 +392,14 @@ export class ResponsesAdapter extends AdapterBase {
 
         for (const sseEvent of events) {
           if (sseEvent.type === "error") {
-            yield factory.responseWarning(sseEvent.data.message, sseEvent.data.code);
+            const data = sseEvent.data as { message?: string; code?: string };
+            yield factory.responseWarning(data.message ?? "Provider error event", data.code);
             continue;
           }
 
           // item 级事件
           if (sseEvent.type === "response.output_item.added") {
-            const item = sseEvent.data.item;
+            const item = (sseEvent.data as { item: { id: string; type: string; [key: string]: unknown } }).item;
             switch (item.type) {
               case "message":
                 yield factory.messageStarted(item.id);
@@ -389,57 +415,96 @@ export class ResponsesAdapter extends AdapterBase {
           }
 
           if (sseEvent.type === "response.output_text.delta") {
-            yield factory.messageDelta(sseEvent.data.item_id, sseEvent.data.delta);
+            const data = sseEvent.data as { item_id: string; delta: string };
+            yield factory.messageDelta(data.item_id, textBlock(data.delta));
+            messageItemsWithDelta.add(data.item_id);
             continue;
           }
 
           if (sseEvent.type === "response.output_text.done") {
-            yield factory.messageCompleted(messageItem([textBlock(sseEvent.data.text)], { id: sseEvent.data.item_id }));
-            output.push(messageItem([textBlock(sseEvent.data.text)], { id: sseEvent.data.item_id }));
+            const data = sseEvent.data as { item_id: string; text: string };
+            if (!messageItemsWithDelta.has(data.item_id) && data.text) {
+              yield factory.messageDelta(data.item_id, textBlock(data.text));
+            }
+            yield factory.messageCompleted(data.item_id);
+            output.push(messageItem([textBlock(data.text)], { id: data.item_id }));
             continue;
           }
 
           if (sseEvent.type === "response.reasoning.delta") {
-            yield factory.reasoningDelta(sseEvent.data.item_id, textBlock(sseEvent.data.delta));
+            const data = sseEvent.data as { item_id: string; delta: string };
+            yield factory.reasoningDelta(data.item_id, textBlock(data.delta));
             continue;
           }
 
           if (sseEvent.type === "response.reasoning.done") {
-            yield factory.reasoningCompleted(
-              reasoningItem([textBlock(sseEvent.data.text)], "full", sseEvent.data.item_id),
-            );
-            output.push(reasoningItem([textBlock(sseEvent.data.text)], "full", sseEvent.data.item_id));
+            const data = sseEvent.data as { item_id: string; text: string };
+            yield factory.reasoningCompleted(data.item_id);
+            output.push(reasoningItem([textBlock(data.text)], "full", data.item_id));
             continue;
           }
 
           if (sseEvent.type === "response.tool_call.delta") {
-            if (sseEvent.data.delta.arguments) {
-              yield factory.toolCallDelta(sseEvent.data.item_id, { argumentsText: sseEvent.data.delta.arguments });
+            const data = sseEvent.data as { item_id: string; delta: { arguments?: string } };
+            if (data.delta.arguments) {
+              yield factory.toolCallDelta(data.item_id, { argumentsText: data.delta.arguments });
             }
             continue;
           }
 
           if (sseEvent.type === "response.tool_call.done") {
-            const tcItem = toolCallItem(
-              sseEvent.data.item_id,
-              sseEvent.data.name ?? "unknown",
-              sseEvent.data.arguments ?? "",
-            );
-            yield factory.toolCallCompleted(tcItem);
+            const data = sseEvent.data as { item_id: string; arguments?: string; name?: string };
+            const tcItem = toolCallItem(data.item_id, data.name ?? "unknown", data.arguments ?? "");
+            yield factory.toolCallCompleted(data.item_id);
             output.push(tcItem);
             continue;
           }
 
-          if (sseEvent.type === "response.completed") {
-            completedResponse = sseEvent.data.response;
+          if (
+            sseEvent.type === "response.completed" ||
+            sseEvent.type === "response.failed" ||
+            sseEvent.type === "response.incomplete"
+          ) {
+            const data = sseEvent.data as { response: ResponsesAPIResponse };
+            if (completedResponse) {
+              yield factory.responseWarning("Duplicate finish signal ignored", "DUPLICATE_FINISH");
+              continue;
+            }
+
+            completedResponse = data.response;
+
+            if (sseEvent.type === "response.failed") {
+              yield factory.responseWarning(
+                `Response failed: ${extractFailureMessage(data.response)}`,
+                "PROVIDER_FAILURE",
+              );
+            }
+            continue;
+          }
+
+          if (!KNOWN_RESPONSES_SSE_TYPES.has(sseEvent.type) && !unknownEventsWarned) {
+            unknownEventsWarned = true;
+            yield factory.responseWarning(
+              `Responses API sent unknown event type "${sseEvent.type}"; this may indicate an incomplete integration`,
+              "UNKNOWN_PROVIDER_EVENT",
+            );
           }
         }
+
+        if (done) {
+          streamDone = true;
+          break;
+        }
       }
     } finally {
-      reader.releaseLock();
+      try {
+        if (!streamDone) await reader.cancel().catch(() => undefined);
+      } finally {
+        reader.releaseLock();
+      }
     }
 
-    if (buffer.trim().length > 0) {
+    if (parser.getRemaining().trim().length > 0) {
       yield factory.responseWarning("Stream ended with an incomplete Responses SSE frame", "STREAM_ERROR");
     }
 
@@ -469,8 +534,9 @@ export class ResponsesAdapter extends AdapterBase {
       yield event;
     }
 
-    yield factory.responseCompleted(
-      this.buildResponse(
+    if (!completedEmitted) {
+      completedEmitted = true;
+      const finalResponse = this.buildResponse(
         request,
         {
           output,
@@ -484,23 +550,42 @@ export class ResponsesAdapter extends AdapterBase {
           rawResponseId,
         },
         factory,
-      ),
-    );
+      );
+      yield factory.responseCompleted({
+        replay: finalResponse.replay,
+        stopReason: finalResponse.stopReason,
+        trace: finalResponse.backend,
+        usage: finalResponse.usage,
+        billing: finalResponse.billing,
+        auxiliary: finalResponse.auxiliary,
+        warnings: finalResponse.warnings,
+      });
+    }
   }
 
   // ── 辅助方法 ──────────────────────────────────────────────
 
   private inferStopReason(response: ResponsesAPIResponse): import("../index.js").StopReason {
+    if (response.status === "failed") return "error";
+
+    if (response.status === "incomplete") {
+      const reason = response.incomplete_details?.reason;
+      if (reason === "content_filter") return "content_filter";
+      if (reason === "max_output_tokens") return "max_output_tokens";
+      return "max_output_tokens";
+    }
+
     const output = response.output;
-    if (!output || output.length === 0) return "unknown";
+    if (!output || output.length === 0) {
+      return response.status === "completed" ? "end_turn" : "unknown";
+    }
 
-    // 检查是否有未完成的 function_call
     const hasFunctionCall = output.some((item) => item.type === "function_call");
     if (hasFunctionCall) return "tool_call";
 
-    // 检查最后一条 message 的 status
-    const lastMsg = output[output.length - 1];
-    if (lastMsg?.status === "incomplete") return "max_output_tokens";
+    const lastItem = output[output.length - 1];
+    if (lastItem?.status === "failed") return "error";
+    if (lastItem?.status === "incomplete") return "max_output_tokens";
 
     return "end_turn";
   }