@codehz/ai 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codehz/ai",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "module": "dist/index.mjs",
   "exports": {

package/src/adapters/chat-completions.ts

@@ -9,7 +9,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,
@@ -21,7 +21,10 @@ import {
   contentBlocksToText,
 } from "../helpers/mapping.js";
 import { emitMalformedStreamWarning } from "../helpers/adapter-auxiliary.js";
+import { assertOpaqueReplayEnvelope, providerHttpError } from "../helpers/adapter-security.js";
 import { usageFromChatCompletions } from "../helpers/usage-mapping.js";
+import { NormalizedRequestMapper, splitLines, IncrementalStreamParser } from "../helpers/index.js";
+import type { ProviderProfile } from "../helpers/index.js";
 
 import type { NormalizedRequest, AIStreamEvent, EventFactory, OutputItem, FetchFn } from "../index.js";
 
@@ -44,6 +47,7 @@ type ChatRequest = {
   temperature?: number;
   max_tokens?: number;
   stream: true;
+  n: 1;
 };
 
 type ChatMessage = {
@@ -114,75 +118,24 @@ type ReasoningFieldName = "reasoning" | "reasoning_content";
 
 const REASONING_FIELDS: readonly ReasoningFieldName[] = ["reasoning_content", "reasoning"];
 
-function assertChatToolResultOutcome(outcome: import("../index.js").ToolResultItem["outcome"]): void {
-  if (outcome !== "success") {
-    throw new AIRequestError(
-      `chat-completions does not preserve tool_result outcome "${outcome}"; only "success" is supported`,
-      "UNSUPPORTED_TOOL_RESULT_OUTCOME",
-    );
-  }
-}
-
-// ── SSE 解析 ──────────────────────────────────────────────────
-
-/**
- * Chat Completions 的简化 SSE 解析器。
- *
- * 约束：
- * - 每条 `data:` 行必须已经是一个完整 JSON 对象
- * - 允许传输层把单行拆成多个 chunk，但不接受 provider 把一个 JSON event 改写成多条 `data:` 行
- */
-function parseChatSSE(buffer: string): { chunks: ChatChunk[]; rest: string; malformedEvents: number } {
-  const chunks: ChatChunk[] = [];
-  let rest = buffer;
-  let malformedEvents = 0;
-
-  while (true) {
-    const lineEnd = rest.indexOf("\n");
-    if (lineEnd === -1) {
-      // 没有更多完整行，剩余部分保留到下次
-      break;
-    }
-
-    const line = rest.slice(0, lineEnd).trim();
-    rest = rest.slice(lineEnd + 1);
-
-    if (!line.startsWith("data: ")) continue;
-
-    const data = line.slice(6).trim();
-    if (data === "[DONE]") continue;
-
-    try {
-      chunks.push(JSON.parse(data));
-    } catch {
-      malformedEvents++;
-    }
-  }
-
-  return { chunks, rest, malformedEvents };
-}
-
-function ensureTextCompatibleBlocks(
-  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(
-        `chat-completions does not support ${field}[${i}] of type "${block.type}"; only text/json blocks are supported`,
-        "UNSUPPORTED_CONTENT_BLOCK",
-      );
-    }
-  }
-
-  return blocks;
-}
+// ── ProviderProfile & Mapper ────────────────────────────────────
+
+const profile: ProviderProfile = {
+  kind: "chat-completions",
+  instructionsMode: "system_message",
+  supportedBlockTypes: ["text", "json"] as const,
+  reasoningBlockTypes: ["text"] as const,
+  capabilities: {
+    textStreaming: "native",
+    reasoningStreaming: "native",
+    toolCallStreaming: "native",
+    replay: "opaque",
+    usage: "final",
+    toolResultOutcomes: ["success"],
+  },
+};
 
-function contentBlocksToChatText(blocks: import("../index.js").ContentBlock[], field: string): string {
-  return contentBlocksToText(ensureTextCompatibleBlocks(blocks, field));
-}
+const mapper = new NormalizedRequestMapper(profile);
 
 function extractReasoningText(value: unknown): string {
   if (typeof value === "string") return value;
@@ -215,9 +168,51 @@ function extractReasoningDeltas(delta: ChatChunkChoice["delta"]): Array<{ field:
   return deltas;
 }
 
-function rollbackTrailingAssistantMessages(messages: ChatMessage[]): void {
-  while (messages.length > 0 && messages[messages.length - 1]?.role === "assistant") {
-    messages.pop();
+function isChatReplayToolCall(value: unknown): value is ChatToolCall {
+  if (!value || typeof value !== "object") return false;
+  const entry = value as Record<string, unknown>;
+  if (typeof entry.id !== "string" || entry.type !== "function") return false;
+  const fn = entry.function;
+  if (!fn || typeof fn !== "object") return false;
+  const f = fn as Record<string, unknown>;
+  return typeof f.name === "string" && typeof f.arguments === "string";
+}
+
+function isChatReplayMessage(value: unknown): value is ChatMessage {
+  if (!value || typeof value !== "object") return false;
+  const msg = value as Record<string, unknown>;
+  const role = msg.role;
+  if (role !== "system" && role !== "user" && role !== "assistant" && role !== "tool") {
+    return false;
+  }
+  if (!(msg.content === null || typeof msg.content === "string")) {
+    return false;
+  }
+  if (msg.tool_calls !== undefined) {
+    if (!Array.isArray(msg.tool_calls) || !msg.tool_calls.every(isChatReplayToolCall)) {
+      return false;
+    }
+  }
+  if (msg.tool_call_id !== undefined && typeof msg.tool_call_id !== "string") {
+    return false;
+  }
+  if (msg.name !== undefined && typeof msg.name !== "string") {
+    return false;
+  }
+  return true;
+}
+
+function assertChatReplayMessages(messages: unknown, field: string): asserts messages is ChatMessage[] {
+  if (!Array.isArray(messages)) {
+    throw new AIRequestError(`Invalid opaque replay payload: ${field} must be an array`, "INVALID_OPAQUE_REPLAY");
+  }
+  for (let i = 0; i < messages.length; i++) {
+    if (!isChatReplayMessage(messages[i])) {
+      throw new AIRequestError(
+        `Invalid opaque replay payload: ${field}[${i}] is not a valid chat message`,
+        "INVALID_OPAQUE_REPLAY",
+      );
+    }
   }
 }
 
@@ -256,7 +251,7 @@ function buildAssistantReplayMessage(params: {
 
 export class ChatCompletionsAdapter extends AdapterBase {
   readonly kind = "chat-completions" as const;
-  readonly nativeStreaming = true;
+  readonly capabilities = profile.capabilities;
 
   private apiKey: string;
   private baseUrl: string;
@@ -276,18 +271,16 @@ export class ChatCompletionsAdapter extends AdapterBase {
 
     // handle instructions → system message
     if (request.instructions) {
-      const content =
-        typeof request.instructions === "string"
-          ? request.instructions
-          : contentBlocksToChatText(request.instructions, "instructions");
-      messages.push({ role: "system", content });
+      messages.push({ role: "system", content: mapper.mapInstructions(request.instructions) });
     }
 
     for (const item of request.input) {
       switch (item.type) {
         case "message": {
           const role = item.role;
-          const text = contentBlocksToChatText(item.content, `input message (${item.role}) content`);
+          const text = contentBlocksToText(
+            mapper.ensureTextBlocks(item.content, `input message (${item.role}) content`),
+          );
           messages.push({ role, content: text || null });
           break;
         }
@@ -310,12 +303,12 @@ export class ChatCompletionsAdapter extends AdapterBase {
           break;
         }
         case "tool_result": {
-          assertChatToolResultOutcome(item.outcome);
+          mapper.assertToolResultOutcome(item.outcome);
           messages.push({
             role: "tool",
             tool_call_id: item.callId,
             name: item.toolName,
-            content: contentBlocksToChatText(item.content, `tool_result ${item.callId} content`),
+            content: contentBlocksToText(mapper.ensureTextBlocks(item.content, `tool_result ${item.callId} content`)),
           });
           break;
         }
@@ -324,25 +317,27 @@ export class ChatCompletionsAdapter extends AdapterBase {
           // Convert to a text message for best-effort
           messages.push({
             role: "assistant",
-            content: contentBlocksToChatText(item.content, "reasoning content"),
+            content: contentBlocksToText(mapper.ensureTextBlocks(item.content, "reasoning content")),
           });
           break;
         }
         case "opaque": {
           // Try to restore from opaque replay
-          if (item.purpose === "replay" && typeof item.payload === "object" && item.payload !== null) {
-            const payload = item.payload as Record<string, unknown>;
-            if (payload.role === "assistant" && typeof payload.content === "string") {
-              messages.push({ role: "assistant", content: payload.content as string });
-            } else if (payload.replaceCanonical === true && Array.isArray(payload.messages)) {
-              rollbackTrailingAssistantMessages(messages);
-              for (const m of payload.messages as ChatMessage[]) {
-                messages.push(m);
-              }
-            } else if (Array.isArray(payload.messages)) {
-              for (const m of payload.messages as ChatMessage[]) {
-                messages.push(m);
-              }
+          if (item.purpose !== "replay") break;
+          assertOpaqueReplayEnvelope(item.payload);
+          const payload = item.payload as Record<string, unknown>;
+          if (payload.role === "assistant" && typeof payload.content === "string") {
+            messages.push({ role: "assistant", content: payload.content });
+          } else if (payload.replaceCanonical === true && "messages" in payload) {
+            assertChatReplayMessages(payload.messages, "messages");
+            mapper.rollbackTrailingAssistantMessages(messages);
+            for (const m of payload.messages) {
+              messages.push(m);
+            }
+          } else if ("messages" in payload) {
+            assertChatReplayMessages(payload.messages, "messages");
+            for (const m of payload.messages) {
+              messages.push(m);
             }
           }
           break;
@@ -354,6 +349,7 @@ export class ChatCompletionsAdapter extends AdapterBase {
       model: request.model,
       messages,
       stream: true,
+      n: 1,
     };
 
     if (request.tools && request.tools.length > 0) {
@@ -392,28 +388,45 @@ export class ChatCompletionsAdapter extends AdapterBase {
     request: NormalizedRequest,
   ): AsyncIterable<AIStreamEvent> {
     const auxiliary = this.createAuxiliaryState(request);
-    const response = await this.fetchFn(`${this.baseUrl}/chat/completions`, {
-      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}/chat/completions`, {
+        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(`Chat Completions 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<ChatChunk>(splitLines, (item: string) => {
+      const trimmed = item.trim();
+      if (!trimmed.startsWith("data: ")) return { status: "ignored" };
+      const data = trimmed.slice(6).trim();
+      if (data === "[DONE]") return { status: "ignored" };
+      try {
+        return { status: "parsed", value: JSON.parse(data) as ChatChunk };
+      } catch {
+        return { status: "malformed" };
+      }
+    });
+
     const output: OutputItem[] = [];
-    const decoder = new TextDecoder();
-    let buffer = "";
+    let streamDone = false;
 
     // 累积状态 — 支持多 choice，此处只取 index 0
     let responseId: string | undefined;
@@ -423,6 +436,9 @@ export class ChatCompletionsAdapter extends AdapterBase {
     let currentReasoningId = "";
     let hasMessageStarted = false;
     let hasReasoningStarted = false;
+    let completedEmitted = false;
+    let warnedNonZeroChoice = false;
+    const buildResponse = this.buildResponse.bind(this);
 
     // tool_calls 累积: tool call index → { id, name, args }
     const pendingToolCalls = new Map<number, PendingToolCall>();
@@ -435,19 +451,19 @@ export class ChatCompletionsAdapter extends AdapterBase {
 
       if (hasReasoningStarted && accumulatedReasoning) {
         const reasoning = reasoningItem([textBlock(accumulatedReasoning)], "full", currentReasoningId);
-        events.push(factory.reasoningCompleted(reasoning));
+        events.push(factory.reasoningCompleted(currentReasoningId));
         output.push(reasoning);
       }
 
-      if (hasMessageStarted && accumulatedContent) {
+      if (hasMessageStarted) {
         const message = messageItem([textBlock(accumulatedContent)], { id: currentMessageId });
-        events.push(factory.messageCompleted(message));
+        events.push(factory.messageCompleted(currentMessageId));
         output.push(message);
       }
 
       for (const pending of finalizedToolCalls) {
         const toolCall = toolCallItem(pending.id, pending.name, pending.args);
-        events.push(factory.toolCallCompleted(toolCall));
+        events.push(factory.toolCallCompleted(pending.id));
         output.push(toolCall);
       }
 
@@ -469,14 +485,70 @@ export class ChatCompletionsAdapter extends AdapterBase {
       return { events, assistantReplayMessage };
     };
 
+    const emitCompleted = async function* (
+      stopReason: import("../index.js").StopReason | undefined,
+      assistantReplayMessage: ChatMessage | null,
+      rawResponseId: string | undefined,
+    ): AsyncIterable<AIStreamEvent> {
+      if (completedEmitted) {
+        yield factory.responseWarning("Duplicate finish signal ignored", "DUPLICATE_FINISH");
+        return;
+      }
+
+      completedEmitted = true;
+
+      const replay = [...replayFromOutput(output)];
+
+      if (assistantReplayMessage) {
+        replay.push(
+          opaqueItem("chat.completions", "replay", {
+            replaceCanonical: true,
+            messages: [assistantReplayMessage],
+          }),
+        );
+      }
+
+      const auxiliaryResult = await auxiliary.finalize(factory);
+      for (const event of auxiliaryResult.events) {
+        yield event;
+      }
+
+      const finalResponse = 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,
+      });
+    };
+
     try {
       while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-
-        buffer += decoder.decode(value, { stream: true });
-        const { chunks, rest, malformedEvents } = parseChatSSE(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: chunks, malformed: malformedEvents } = done ? parser.flush() : parser.feed(value as Uint8Array);
 
         const malformedWarning = emitMalformedStreamWarning(factory, {
           count: malformedEvents,
@@ -496,19 +568,34 @@ export class ChatCompletionsAdapter extends AdapterBase {
           }
 
           for (const choice of chunk.choices) {
-            if (choice.index !== 0) continue;
+            if (choice.index !== 0) {
+              if (!warnedNonZeroChoice) {
+                yield factory.responseWarning(
+                  `Chat Completions returned choice index ${choice.index}; only the first choice (index 0) is supported. This choice is ignored.`,
+                  "MULTIPLE_CHOICES_IGNORED",
+                );
+                warnedNonZeroChoice = true;
+              }
+              continue;
+            }
+
+            if (completedEmitted) {
+              if (choice.finish_reason) {
+                yield factory.responseWarning("Duplicate finish signal ignored", "DUPLICATE_FINISH");
+              }
+              continue;
+            }
 
             const delta = choice.delta;
             const finishReason = choice.finish_reason;
             const reasoningDeltas = extractReasoningDeltas(delta);
 
-            // 处理 role: assistant (首块标识)
-            if (delta.role === "assistant" && typeof delta.content === "string" && !hasMessageStarted) {
+            const ensureMessageStarted = (): void => {
+              if (hasMessageStarted) return;
               currentMessageId = `msg-${chunk.id}`;
               hasMessageStarted = true;
               accumulatedContent = "";
-              yield factory.messageStarted(currentMessageId);
-            }
+            };
 
             // 处理 third-party reasoning delta
             if (reasoningDeltas.length > 0) {
@@ -532,16 +619,20 @@ export class ChatCompletionsAdapter extends AdapterBase {
             // 处理 content delta
             if (delta.content) {
               if (!hasMessageStarted) {
-                currentMessageId = `msg-${chunk.id}`;
-                hasMessageStarted = true;
+                ensureMessageStarted();
                 yield factory.messageStarted(currentMessageId);
               }
               accumulatedContent += delta.content;
-              yield factory.messageDelta(currentMessageId, delta.content);
+              yield factory.messageDelta(currentMessageId, textBlock(delta.content));
             }
 
             // 处理 tool_calls delta
             if (delta.tool_calls) {
+              if (!hasMessageStarted) {
+                ensureMessageStarted();
+                yield factory.messageStarted(currentMessageId);
+              }
+
               for (const tc of delta.tool_calls) {
                 const idx = tc.index;
 
@@ -562,6 +653,11 @@ export class ChatCompletionsAdapter extends AdapterBase {
 
             // 处理 function_call delta (legacy format)
             if (delta.function_call) {
+              if (!hasMessageStarted) {
+                ensureMessageStarted();
+                yield factory.messageStarted(currentMessageId);
+              }
+
               if (delta.function_call.name) {
                 const fcId = `fc-${chunk.id}-0`;
                 pendingToolCalls.set(0, { id: fcId, name: delta.function_call.name, args: "" });
@@ -583,58 +679,31 @@ export class ChatCompletionsAdapter extends AdapterBase {
                 yield event;
               }
 
-              // 构建 stop reason
               const stopReason = mapStopReason(finishReason);
-
-              // 构建 replay
-              const replay = [...replayFromOutput(output)];
-
-              // 附加 opaque replay
-              if (assistantReplayMessage) {
-                replay.push(
-                  opaqueItem("chat.completions", "replay", {
-                    replaceCanonical: true,
-                    messages: [assistantReplayMessage],
-                  }),
-                );
-              }
-
-              const auxiliaryResult = await auxiliary.finalize(factory);
-              for (const event of auxiliaryResult.events) {
-                yield event;
-              }
-
-              yield factory.responseCompleted(
-                this.buildResponse(
-                  request,
-                  {
-                    output,
-                    replay,
-                    stopReason,
-                    usage: auxiliaryResult.usage,
-                    billing: auxiliaryResult.billing,
-                    auxiliary: auxiliaryResult.auxiliary,
-                    warnings: auxiliaryResult.warnings,
-                    metadataSources: auxiliaryResult.metadataSources,
-                    rawResponseId: chunk.id,
-                  },
-                  factory,
-                ),
-              );
+              yield* emitCompleted(stopReason, assistantReplayMessage, chunk.id);
             }
           }
         }
+
+        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 Chat Completions SSE frame", "STREAM_ERROR");
     }
 
     // 如果流结束时没有 finish_reason（断流），也尝试关闭
-    if (hasMessageStarted || hasReasoningStarted || pendingToolCalls.size > 0) {
+    if (!completedEmitted && (hasMessageStarted || hasReasoningStarted || pendingToolCalls.size > 0)) {
       yield factory.responseWarning("Stream ended without a finish_reason", "INCOMPLETE_STREAM");
 
       const { events, assistantReplayMessage } = finalizePendingTurn();
@@ -642,37 +711,7 @@ export class ChatCompletionsAdapter extends AdapterBase {
         yield event;
       }
 
-      const replay = [...replayFromOutput(output)];
-      if (assistantReplayMessage) {
-        replay.push(
-          opaqueItem("chat.completions", "replay", {
-            replaceCanonical: true,
-            messages: [assistantReplayMessage],
-          }),
-        );
-      }
-
-      const auxiliaryResult = await auxiliary.finalize(factory);
-      for (const event of auxiliaryResult.events) {
-        yield event;
-      }
-
-      yield factory.responseCompleted(
-        this.buildResponse(
-          request,
-          {
-            output,
-            replay,
-            usage: auxiliaryResult.usage,
-            billing: auxiliaryResult.billing,
-            auxiliary: auxiliaryResult.auxiliary,
-            warnings: auxiliaryResult.warnings,
-            metadataSources: auxiliaryResult.metadataSources,
-            rawResponseId: responseId,
-          },
-          factory,
-        ),
-      );
+      yield* emitCompleted(undefined, assistantReplayMessage, responseId);
     }
   }
 }