@codehz/ai 0.2.4 → 0.4.0

package/src/adapters/responses.ts

@@ -10,7 +10,7 @@
  */
 
 import { AdapterBase } from "../helpers/adapter-base.js";
-import { AIProviderError, AIRequestError, AIStreamError } from "../core/errors.js";
+import { AIRequestError } from "../core/errors.js";
 import {
   textBlock,
   messageItem,
@@ -18,14 +18,16 @@ import {
   toolCallItem,
   opaqueItem,
   replayFromOutput,
-  blockToText,
-  contentBlocksToText,
 } from "../helpers/mapping.js";
-import { emitMalformedStreamWarning } from "../helpers/adapter-auxiliary.js";
-import { assertOpaqueReplayEnvelope, providerHttpError } from "../helpers/adapter-security.js";
+import { assertOpaqueReplayEnvelope } from "../helpers/adapter-security.js";
 import { usageFromOpenAIResponses } from "../helpers/usage-mapping.js";
-import { NormalizedRequestMapper, splitSSEFrames, IncrementalStreamParser } from "../helpers/index.js";
-import type { ProviderProfile } from "../helpers/index.js";
+import {
+  NormalizedRequestMapper,
+  createSseJsonParser,
+  openProviderJsonStream,
+  iterateProviderStreamBatches,
+  createCompletionGate,
+} from "../helpers/index.js";
 
 import type { NormalizedRequest, AIStreamEvent, EventFactory, OutputItem, FetchFn } from "../index.js";
 
@@ -72,24 +74,7 @@ type ResponsesTool = {
   input_schema: Record<string, unknown>;
 };
 
-// ── 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"],
-  },
-};
-
-const mapper = new NormalizedRequestMapper(profile);
+const mapper = new NormalizedRequestMapper("responses");
 
 // ── SSE 事件类型 ──────────────────────────────────────────────
 
@@ -99,8 +84,8 @@ type ResponsesSSEEvent =
   | { type: "response.output_text.done"; data: { item_id: string; text: string } }
   | { type: "response.reasoning.delta"; data: { item_id: string; delta: string } }
   | { type: "response.reasoning.done"; data: { item_id: string; text: string } }
-  | { 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.function_call_arguments.delta"; data: { item_id: string; delta: string } }
+  | { type: "response.function_call_arguments.done"; data: { item_id: string; arguments: string } }
   | { type: "response.completed"; data: { response: ResponsesAPIResponse } }
   | { type: "response.failed"; data: { response: ResponsesAPIResponse } }
   | { type: "response.incomplete"; data: { response: ResponsesAPIResponse } }
@@ -115,8 +100,6 @@ const KNOWN_RESPONSES_SSE_TYPES = new Set([
   "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",
@@ -187,7 +170,7 @@ function canonicalToResponsesBlock(b: import("../index.js").ContentBlock): Respo
 
 export class ResponsesAdapter extends AdapterBase {
   readonly kind = "responses" as const;
-  readonly capabilities = profile.capabilities;
+  readonly isSyntheticStream = false;
 
   private apiKey: string;
   private baseUrl: string;
@@ -218,9 +201,7 @@ export class ResponsesAdapter extends AdapterBase {
             input.push({
               type: "message",
               role: item.role,
-              content: contentBlocksToText(
-                mapper.ensureTextBlocks(item.content, `input message (${item.role}) content`),
-              ),
+              content: mapper.textFromBlocks(item.content, `input message (${item.role}) content`),
             });
           }
           break;
@@ -242,11 +223,7 @@ export class ResponsesAdapter extends AdapterBase {
           break;
         }
         case "tool_result": {
-          mapper.assertToolResultOutcome(item.outcome);
-          const output = mapper
-            .ensureTextBlocks(item.content, `tool_result ${item.callId} content`)
-            .map(blockToText)
-            .join("\n");
+          const output = mapper.textFromBlocks(item.content, `tool_result ${item.callId} content`);
           input.push({
             type: "function_call_output",
             call_id: item.callId,
@@ -286,24 +263,24 @@ export class ResponsesAdapter extends AdapterBase {
       body.instructions = mapper.mapInstructions(request.instructions);
     }
 
-    if (request.tools && request.tools.length > 0) {
-      body.tools = request.tools.map(
-        (t): ResponsesTool => ({
-          type: "function",
-          name: t.name,
-          description: t.description,
-          input_schema: t.inputSchema,
-        }),
-      );
-    }
-
-    if (request.toolChoice) {
-      if (request.toolChoice === "auto") body.tool_choice = "auto";
-      else if (request.toolChoice === "none") body.tool_choice = "none";
-      else if (request.toolChoice.type === "tool") {
-        body.tool_choice = { type: "function", name: request.toolChoice.name };
-      }
-    }
+    body.tools = mapper.mapToolsIfPresent(
+      request.tools,
+      (t): ResponsesTool => ({
+        type: "function",
+        name: t.name,
+        description: t.description,
+        input_schema: t.inputSchema,
+      }),
+    );
+
+    body.tool_choice = mapper.mapToolChoice<Exclude<ResponsesAPIRequest["tool_choice"], undefined>>(
+      request.toolChoice,
+      {
+        auto: "auto",
+        none: "none",
+        tool: (name) => ({ type: "function" as const, name }),
+      },
+    );
 
     if (request.temperature !== undefined) body.temperature = request.temperature;
     if (request.maxOutputTokens !== undefined) body.max_output_tokens = request.maxOutputTokens;
@@ -320,198 +297,139 @@ export class ResponsesAdapter extends AdapterBase {
     request: NormalizedRequest,
   ): AsyncIterable<AIStreamEvent> {
     const auxiliary = this.createAuxiliaryState(request);
-    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),
-        signal: request.signal,
-      });
-    } catch (err) {
-      throw new AIProviderError(err instanceof Error ? err.message : String(err), "PROVIDER_ERROR");
-    }
-
-    if (!response.ok) {
-      const errorBody = await response.text().catch(() => "");
-      throw providerHttpError(response.status, errorBody);
-    }
-
-    const reader = response.body?.getReader();
-    if (!reader) {
-      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 gate = createCompletionGate();
+
+    const { reader } = await openProviderJsonStream({
+      fetchFn: this.fetchFn,
+      url: `${this.baseUrl}/responses`,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: providerRequest,
+      signal: request.signal,
     });
 
+    const parser = createSseJsonParser<ResponsesSSEEvent>();
     const output: OutputItem[] = [];
-    let streamDone = false;
     let completedResponse: ResponsesAPIResponse | undefined;
-    let completedEmitted = false;
     let unknownEventsWarned = false;
     const messageItemsWithDelta = new Set<string>();
-
-    try {
-      while (true) {
-        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,
-          providerLabel: "Responses",
-          transportLabel: "SSE event(s)",
-        });
-        if (malformedWarning) {
-          yield malformedWarning;
+    const toolCallNames = new Map<string, string>();
+
+    for await (const batch of iterateProviderStreamBatches({
+      reader,
+      parser,
+      factory,
+      providerLabel: "Responses",
+      transportLabel: "SSE event(s)",
+      incompleteMessage: "Stream ended with an incomplete Responses SSE frame",
+    })) {
+      for (const warning of batch.warnings) yield warning;
+
+      for (const sseEvent of batch.items) {
+        if (sseEvent.type === "error") {
+          const data = sseEvent.data as { message?: string; code?: string };
+          yield factory.responseWarning(data.message ?? "Provider error event", data.code);
+          continue;
         }
 
-        for (const sseEvent of events) {
-          if (sseEvent.type === "error") {
-            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 as { item: { id: string; type: string; [key: string]: unknown } }).item;
-            switch (item.type) {
-              case "message":
-                yield factory.messageStarted(item.id);
-                break;
-              case "reasoning":
-                yield factory.reasoningStarted(item.id, "full");
-                break;
-              case "function_call":
-                yield factory.toolCallStarted(item.id, ((item as Record<string, unknown>).name as string) ?? "unknown");
-                break;
-            }
-            continue;
-          }
-
-          if (sseEvent.type === "response.output_text.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") {
-            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));
+        if (sseEvent.type === "response.output_item.added") {
+          const item = (sseEvent.data as { item: { id: string; type: string; [key: string]: unknown } }).item;
+          switch (item.type) {
+            case "message":
+              yield factory.messageStarted(item.id);
+              break;
+            case "reasoning":
+              yield factory.reasoningStarted(item.id, "full");
+              break;
+            case "function_call": {
+              const name = typeof item.name === "string" ? item.name : "unknown";
+              toolCallNames.set(item.id, name);
+              yield factory.toolCallStarted(item.id, name);
+              break;
             }
-            yield factory.messageCompleted(data.item_id);
-            output.push(messageItem([textBlock(data.text)], { id: data.item_id }));
-            continue;
           }
+          continue;
+        }
 
-          if (sseEvent.type === "response.reasoning.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.output_text.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.reasoning.done") {
-            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.output_text.done") {
+          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.tool_call.delta") {
-            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.reasoning.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.tool_call.done") {
-            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.reasoning.done") {
+          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.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;
-            }
+        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 });
+          continue;
+        }
 
-            completedResponse = data.response;
+        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);
+          output.push(tcItem);
+          continue;
+        }
 
-            if (sseEvent.type === "response.failed") {
-              yield factory.responseWarning(
-                `Response failed: ${extractFailureMessage(data.response)}`,
-                "PROVIDER_FAILURE",
-              );
-            }
+        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;
           }
 
-          if (!KNOWN_RESPONSES_SSE_TYPES.has(sseEvent.type) && !unknownEventsWarned) {
-            unknownEventsWarned = true;
+          completedResponse = data.response;
+
+          if (sseEvent.type === "response.failed") {
             yield factory.responseWarning(
-              `Responses API sent unknown event type "${sseEvent.type}"; this may indicate an incomplete integration`,
-              "UNKNOWN_PROVIDER_EVENT",
+              `Response failed: ${extractFailureMessage(data.response)}`,
+              "PROVIDER_FAILURE",
             );
           }
+          continue;
         }
 
-        if (done) {
-          streamDone = true;
-          break;
+        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",
+          );
         }
       }
-    } finally {
-      try {
-        if (!streamDone) await reader.cancel().catch(() => undefined);
-      } finally {
-        reader.releaseLock();
-      }
-    }
-
-    if (parser.getRemaining().trim().length > 0) {
-      yield factory.responseWarning("Stream ended with an incomplete Responses SSE frame", "STREAM_ERROR");
     }
 
-    // 解析完成响应中的 usage 和 replay
     let rawResponseId: string | undefined;
-
     if (completedResponse) {
       rawResponseId = completedResponse.id;
       if (completedResponse.usage) {
@@ -519,47 +437,19 @@ export class ResponsesAdapter extends AdapterBase {
       }
     }
 
-    // 构造 replay：在 output 基础上追加 opaque continuation
     const replay = [...replayFromOutput(output)];
-
-    // 如果有 provider continuation id，附加 opaque replay item
     if (completedResponse?.id) {
       replay.push(opaqueItem("responses", "replay", { id: completedResponse.id }));
     }
 
-    // 从 completedResponse 推断 stop reason
     const stopReason = completedResponse ? this.inferStopReason(completedResponse) : undefined;
 
-    const auxiliaryResult = await auxiliary.finalize(factory);
-    for (const event of auxiliaryResult.events) {
-      yield event;
-    }
-
-    if (!completedEmitted) {
-      completedEmitted = true;
-      const finalResponse = this.buildResponse(
-        request,
-        {
-          output,
-          replay,
-          stopReason,
-          usage: auxiliaryResult.usage,
-          billing: auxiliaryResult.billing,
-          auxiliary: auxiliaryResult.auxiliary,
-          warnings: auxiliaryResult.warnings,
-          metadataSources: auxiliaryResult.metadataSources,
-          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,
+    if (gate.tryComplete()) {
+      yield* this.emitStreamCompleted(factory, request, auxiliary, {
+        output,
+        replay,
+        stopReason,
+        rawResponseId,
       });
     }
   }

package/src/core/validation.ts

@@ -136,6 +136,25 @@ function validateInputItem(item: unknown, field: string, issues: ValidationIssue
           "TOOL_CALL_ARGUMENTS_INVALID",
           `${field}.argumentsText must be a string`,
         );
+      } else {
+        try {
+          const parsed: unknown = JSON.parse(item.argumentsText);
+          if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            pushIssue(
+              issues,
+              `${field}.argumentsText`,
+              "TOOL_CALL_ARGUMENTS_INVALID",
+              `${field}.argumentsText must encode a JSON object`,
+            );
+          }
+        } catch {
+          pushIssue(
+            issues,
+            `${field}.argumentsText`,
+            "TOOL_CALL_ARGUMENTS_INVALID",
+            `${field}.argumentsText must encode a JSON object`,
+          );
+        }
       }
       return;
     case "tool_result":

package/src/helpers/adapter-auxiliary.ts

@@ -1,13 +1,6 @@
 import { WarningCode } from "../core/errors.js";
 import type { EventFactory } from "../core/event-factory.js";
-import type {
-  AIStreamEvent,
-  BillingInfo,
-  NormalizedRequest,
-  Usage,
-  AuxiliaryInfo,
-  BackendTrace,
-} from "../types/index.js";
+import type { AIStreamEvent, BillingInfo, NormalizedRequest, Usage, AuxiliaryInfo } from "../types/index.js";
 import { AuxiliaryCollector, type BillingSource, type LookupResult, type UsageSource } from "./auxiliary-collector.js";
 
 type MaybePromise<T> = T | Promise<T>;
@@ -157,21 +150,6 @@ export function emitMalformedStreamWarning(
   );
 }
 
-export function metadataSourceList(
-  ...groups: Array<Array<NonNullable<BackendTrace["metadataSources"]>[number]> | undefined>
-): string[] | undefined {
-  const sources = new Set<string>();
-
-  for (const group of groups) {
-    if (!group) continue;
-    for (const source of group) {
-      sources.add(source);
-    }
-  }
-
-  return sources.size > 0 ? [...sources] : undefined;
-}
-
 function isEmptyRecord(value: object): boolean {
   return Object.keys(value).length === 0;
 }

package/src/helpers/adapter-base.ts

@@ -56,7 +56,7 @@ export type StreamResult = {
 
 export abstract class AdapterBase implements BackendAdapter {
   abstract readonly kind: "chat-completions" | "messages" | "responses" | "ollama" | "mock";
-  abstract readonly capabilities: import("../types/index.js").AdapterCapabilities;
+  abstract readonly isSyntheticStream: boolean;
 
   /**
    * stream 模板方法：
@@ -70,7 +70,7 @@ export abstract class AdapterBase implements BackendAdapter {
 
     const factory = createEventFactory({
       responseId: request.requestId,
-      backend: { kind: this.kind, isSynthetic: this.capabilities.textStreaming === "synthetic" },
+      backend: { kind: this.kind, isSynthetic: this.isSyntheticStream },
     });
 
     yield factory.responseStarted(request.model);
@@ -129,7 +129,7 @@ export abstract class AdapterBase implements BackendAdapter {
    * 子类可在返回前自定义覆盖。
    */
   protected buildResponse(request: NormalizedRequest, result: StreamResult, _factory: EventFactory): AIResponse {
-    const text = this.extractText(result.output);
+    const text = extractText(result.output);
     const warnings = mergeWarnings(result.warnings, _factory.warnings);
     const auxiliary = mergeAuxiliary(
       result.auxiliary,
@@ -151,16 +151,50 @@ export abstract class AdapterBase implements BackendAdapter {
         requestId: request.requestId,
         rawResponseId: result.rawResponseId,
         adapter: this.kind,
-        isSyntheticStream: this.capabilities.textStreaming === "synthetic",
+        isSyntheticStream: this.isSyntheticStream,
         metadataSources: result.metadataSources,
         warnings,
       },
     };
   }
 
-  /** 从 output items 中提取文本内容。 */
-  protected extractText(output: OutputItem[]): string {
-    return extractText(output);
+  /**
+   * 统一 finalize auxiliary → response.completed。
+   * adapter 在调用前组装 output / replay / stopReason 等业务字段。
+   */
+  protected async *emitStreamCompleted(
+    factory: EventFactory,
+    request: NormalizedRequest,
+    auxiliary: AdapterAuxiliaryState,
+    result: StreamResult,
+  ): AsyncIterable<AIStreamEvent> {
+    const auxiliaryResult = await auxiliary.finalize(factory);
+    for (const event of auxiliaryResult.events) {
+      yield event;
+    }
+
+    const finalResponse = this.buildResponse(
+      request,
+      {
+        ...result,
+        usage: result.usage ?? auxiliaryResult.usage,
+        billing: result.billing ?? auxiliaryResult.billing,
+        auxiliary: mergeAuxiliary(result.auxiliary, auxiliaryResult.auxiliary),
+        warnings: mergeWarnings(result.warnings, auxiliaryResult.warnings),
+        metadataSources: result.metadataSources ?? auxiliaryResult.metadataSources,
+      },
+      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,
+    });
   }
 
   protected createAuxiliaryState(request: NormalizedRequest): AdapterAuxiliaryState {