@codehz/ai 0.2.0 → 0.2.1

package/src/adapters/messages.ts

@@ -11,7 +11,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,
@@ -24,9 +24,10 @@ import {
   contentBlocksToText,
 } from "../helpers/mapping.js";
 import { emitMalformedStreamWarning } from "../helpers/adapter-auxiliary.js";
+import { assertOpaqueReplayEnvelope, providerHttpError } from "../helpers/adapter-security.js";
 import { usageFromAnthropicMessages } 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";
 
@@ -72,52 +73,68 @@ type MessagesAPITool = {
   input_schema: Record<string, unknown>;
 };
 
-function ensureMessagesTextBlocks(
-  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(
-        `messages does not support ${field}[${i}] of type "${block.type}"; only text/json blocks are supported`,
-        "UNSUPPORTED_CONTENT_BLOCK",
+// ── ProviderProfile & Mapper ────────────────────────────────────
+
+const profile: ProviderProfile = {
+  kind: "messages",
+  instructionsMode: "system_message",
+  supportedBlockTypes: ["text", "json"] as const,
+  reasoningBlockTypes: ["text"] as const,
+  capabilities: {
+    textStreaming: "native",
+    reasoningStreaming: "native",
+    toolCallStreaming: "synthetic",
+    replay: "opaque",
+    usage: "stream",
+    toolResultOutcomes: ["success", "error"],
+  },
+};
+
+const mapper = new NormalizedRequestMapper(profile);
+
+function isMessagesReplayContentBlock(value: unknown): value is MessagesAPIContentBlock {
+  if (!value || typeof value !== "object" || !("type" in value)) return false;
+  const block = value as Record<string, unknown>;
+  switch (block.type) {
+    case "text":
+      return typeof block.text === "string";
+    case "thinking":
+      return (
+        typeof block.thinking === "string" && (block.signature === undefined || typeof block.signature === "string")
+      );
+    case "redacted_thinking":
+      return typeof block.data === "string";
+    case "tool_use":
+      return (
+        typeof block.id === "string" &&
+        typeof block.name === "string" &&
+        !!block.input &&
+        typeof block.input === "object" &&
+        !Array.isArray(block.input)
       );
+    case "tool_result": {
+      if (typeof block.tool_use_id !== "string") return false;
+      if (block.is_error !== undefined && typeof block.is_error !== "boolean") return false;
+      if (typeof block.content === "string") return true;
+      if (!Array.isArray(block.content)) return false;
+      return block.content.every(isMessagesReplayContentBlock);
     }
+    default:
+      return false;
   }
-
-  return blocks;
 }
 
-function ensureMessagesReasoningBlocks(
-  blocks: import("../index.js").ContentBlock[],
-  field: string,
-): Array<Extract<import("../index.js").ContentBlock, { type: "text" }>> {
-  return blocks.map((block, index) => {
-    if (block.type !== "text") {
+function assertMessagesReplayContent(content: unknown): asserts content is MessagesAPIContentBlock[] {
+  if (!Array.isArray(content)) {
+    throw new AIRequestError("Invalid opaque replay payload: content must be an array", "INVALID_OPAQUE_REPLAY");
+  }
+  for (let i = 0; i < content.length; i++) {
+    if (!isMessagesReplayContentBlock(content[i])) {
       throw new AIRequestError(
-        `messages does not support ${field}[${index}] of type "${block.type}"; reasoning only supports text blocks`,
-        "UNSUPPORTED_CONTENT_BLOCK",
+        `Invalid opaque replay payload: content[${i}] is not a valid Messages content block`,
+        "INVALID_OPAQUE_REPLAY",
       );
     }
-
-    return block;
-  });
-}
-
-function instructionsToMessagesText(instructions: string | import("../index.js").InstructionBlock[]): string {
-  return typeof instructions === "string"
-    ? instructions
-    : contentBlocksToText(ensureMessagesTextBlocks(instructions, "instructions"));
-}
-
-function assertMessagesToolResultOutcome(outcome: import("../index.js").ToolResultItem["outcome"]): void {
-  if (outcome === "rejected") {
-    throw new AIRequestError(
-      'messages does not preserve tool_result outcome "rejected"; only "success" and "error" are supported',
-      "UNSUPPORTED_TOOL_RESULT_OUTCOME",
-    );
   }
 }
 
@@ -155,19 +172,6 @@ type MessagesAPIMessageResponse = {
   usage: { input_tokens: number; output_tokens: number };
 };
 
-// ── SSE 解析 ──────────────────────────────────────────────────
-
-function parseMessagesSSE(chunk: string): { events: MessagesSSEEvent[]; rest: string; malformedEvents: number } {
-  const result = parseSSEEvents(chunk);
-  return { events: result.events as MessagesSSEEvent[], rest: result.rest, malformedEvents: result.malformedEvents };
-}
-
-function rollbackTrailingAssistantMessages(messages: MessagesAPIMessage[]): void {
-  while (messages.length > 0 && messages[messages.length - 1]?.role === "assistant") {
-    messages.pop();
-  }
-}
-
 /** 用 response 级别的命名空间合成 content block 的 item ID，避免多轮工具循环 ID 碰撞 */
 function synthesizeItemId(kind: "msg" | "reason" | "reason-redacted", blockIndex: number, responseId: string): string {
   return `${kind}-${blockIndex}-${responseId}`;
@@ -247,13 +251,12 @@ function buildStreamMetadata(options: {
 
 export class MessagesAdapter extends AdapterBase {
   readonly kind = "messages" as const;
-  readonly nativeStreaming = true;
+  readonly capabilities = profile.capabilities;
 
   private apiKey: string;
   private apiVersion: string;
   private baseUrl: string;
   private fetchFn: FetchFn;
-  private warningAccumulator: string[];
 
   constructor(options: MessagesAdapterOptions) {
     super();
@@ -261,11 +264,6 @@ export class MessagesAdapter extends AdapterBase {
     this.apiVersion = options.apiVersion ?? "2023-06-01";
     this.baseUrl = options.baseUrl ?? "https://api.anthropic.com/v1";
     this.fetchFn = options.fetch ?? globalThis.fetch;
-    this.warningAccumulator = [];
-  }
-
-  protected warn(message: string, _code?: string): void {
-    this.warningAccumulator.push(message);
   }
 
   // ── buildRequest ──────────────────────────────────────────
@@ -277,7 +275,7 @@ export class MessagesAdapter extends AdapterBase {
 
     // 处理 instructions → system prompt
     if (request.instructions) {
-      systemPrompt = instructionsToMessagesText(request.instructions);
+      systemPrompt = mapper.mapInstructions(request.instructions);
     }
 
     // 处理 input items
@@ -289,7 +287,7 @@ export class MessagesAdapter extends AdapterBase {
       switch (item.type) {
         case "message": {
           const role = item.role === "user" ? "user" : "assistant";
-          const supportedContent = ensureMessagesTextBlocks(item.content, `input message (${item.role}) content`);
+          const supportedContent = mapper.ensureTextBlocks(item.content, `input message (${item.role}) content`);
           if (supportedContent.length === 1 && supportedContent[0]?.type === "text") {
             messages.push({ role, content: supportedContent[0].text });
           } else {
@@ -315,8 +313,9 @@ export class MessagesAdapter extends AdapterBase {
           break;
         }
         case "tool_result": {
-          assertMessagesToolResultOutcome(item.outcome);
-          const content = ensureMessagesTextBlocks(item.content, `tool_result ${item.callId} content`)
+          mapper.assertToolResultOutcome(item.outcome);
+          const content = mapper
+            .ensureTextBlocks(item.content, `tool_result ${item.callId} content`)
             .map(blockToText)
             .join("\n");
           const block: MessagesAPIContentBlock = {
@@ -335,7 +334,7 @@ export class MessagesAdapter extends AdapterBase {
         }
         case "reasoning": {
           // 将 reasoning item 转为 thinking block 在 assistant message 中
-          const text = contentBlocksToText(ensureMessagesReasoningBlocks(item.content, "reasoning content"));
+          const text = contentBlocksToText(mapper.ensureReasoningBlocks(item.content, "reasoning content"));
           const block: MessagesAPIContentBlock = { type: "thinking", thinking: text };
           const lastMsg = messages[messages.length - 1];
           if (lastMsg && lastMsg.role === "assistant" && typeof lastMsg.content !== "string") {
@@ -347,29 +346,16 @@ export class MessagesAdapter extends AdapterBase {
         }
         case "opaque": {
           // 尝试从 opaque replay item 中提取 assistant message
-          if (item.purpose === "replay" && typeof item.payload === "object" && item.payload !== null) {
-            const payload = item.payload as Record<string, unknown>;
-            if (payload.role === "assistant" && Array.isArray(payload.content)) {
-              // 验证 content 是合法的 MessagesAPIContentBlock[]
-              const isValidContent = payload.content.every(
-                (b): b is MessagesAPIContentBlock =>
-                  typeof b === "object" &&
-                  b !== null &&
-                  "type" in b &&
-                  (b.type === "text" ||
-                    b.type === "thinking" ||
-                    b.type === "redacted_thinking" ||
-                    b.type === "tool_use" ||
-                    b.type === "tool_result"),
-              );
-              if (isValidContent) {
-                rollbackTrailingAssistantMessages(messages);
-                messages.push({
-                  role: "assistant",
-                  content: payload.content as MessagesAPIContentBlock[],
-                });
-              }
-            }
+          if (item.purpose !== "replay") break;
+          assertOpaqueReplayEnvelope(item.payload);
+          const payload = item.payload as Record<string, unknown>;
+          if (payload.role === "assistant" && "content" in payload) {
+            assertMessagesReplayContent(payload.content);
+            mapper.rollbackTrailingAssistantMessages(messages);
+            messages.push({
+              role: "assistant",
+              content: payload.content,
+            });
           }
           break;
         }
@@ -415,8 +401,8 @@ export class MessagesAdapter extends AdapterBase {
     factory: EventFactory,
     request: NormalizedRequest,
   ): AsyncIterable<AIStreamEvent> {
-    this.warningAccumulator = [];
     const auxiliary = this.createAuxiliaryState(request);
+    let completedEmitted = false;
 
     if (request.metadata) {
       yield factory.responseWarning(
@@ -425,30 +411,52 @@ export class MessagesAdapter extends AdapterBase {
       );
     }
 
-    const response = await this.fetchFn(`${this.baseUrl}/messages`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "x-api-key": this.apiKey,
-        "anthropic-version": this.apiVersion,
-      },
-      body: JSON.stringify(providerRequest),
-    });
+    let response: Response;
+
+    try {
+      response = await this.fetchFn(`${this.baseUrl}/messages`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-api-key": this.apiKey,
+          "anthropic-version": this.apiVersion,
+        },
+        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(`Messages 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<MessagesSSEEvent>(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 MessagesSSEEvent };
+      } catch {
+        return { status: "malformed" };
+      }
+    });
+
     const output: OutputItem[] = [];
-    const decoder = new TextDecoder();
-    let buffer = "";
+    let streamDone = false;
     let messageResponse: MessagesAPIMessageResponse | undefined;
     let currentContentBlockIndex = -1;
     let currentItemType: "message" | "reasoning" | "tool_call" | null = null;
@@ -479,12 +487,14 @@ export class MessagesAdapter extends AdapterBase {
 
     try {
       while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-
-        buffer += decoder.decode(value, { stream: true });
-        const { events, rest, malformedEvents } = parseMessagesSSE(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,
@@ -503,7 +513,6 @@ export class MessagesAdapter extends AdapterBase {
             case "error": {
               const err = sseEvent.data.error;
               yield factory.responseWarning(err.message, err.type);
-              this.warn(err.message, err.type);
               continue;
             }
 
@@ -547,7 +556,7 @@ export class MessagesAdapter extends AdapterBase {
                   yield factory.reasoningStarted(currentItemId, "redacted");
                   yield factory.reasoningDelta(currentItemId, textBlock(data));
                   const redactedItem = reasoningItem([textBlock(data)], "redacted", currentItemId);
-                  yield factory.reasoningCompleted(redactedItem);
+                  yield factory.reasoningCompleted(currentItemId);
                   output.push(redactedItem);
                   rawReplayContent.push({ type: "redacted_thinking", data });
                   currentItemType = null;
@@ -575,7 +584,7 @@ export class MessagesAdapter extends AdapterBase {
                   if (currentItemType === "message" && currentItemId) {
                     const txt = (delta as unknown as { text: string }).text;
                     textBuffer += txt;
-                    yield factory.messageDelta(currentItemId, txt);
+                    yield factory.messageDelta(currentItemId, textBlock(txt));
                   }
                   break;
                 }
@@ -601,18 +610,16 @@ export class MessagesAdapter extends AdapterBase {
 
             case "content_block_stop": {
               if (currentItemType === "message" && currentItemId) {
-                yield factory.messageCompleted(messageItem([textBlock(textBuffer)], { id: currentItemId }));
+                yield factory.messageCompleted(currentItemId);
                 output.push(messageItem([textBlock(textBuffer)], { id: currentItemId }));
                 rawReplayContent.push({ type: "text", text: textBuffer });
               } else if (currentItemType === "reasoning" && currentItemId && currentThinkingVisibility !== "redacted") {
-                yield factory.reasoningCompleted(
-                  reasoningItem([textBlock(thinkingBuffer)], currentThinkingVisibility, currentItemId),
-                );
+                yield factory.reasoningCompleted(currentItemId);
                 output.push(reasoningItem([textBlock(thinkingBuffer)], currentThinkingVisibility, currentItemId));
                 rawReplayContent.push({ type: "thinking", thinking: thinkingBuffer });
               } else if (currentItemType === "tool_call" && currentItemId) {
                 const tcItem = toolCallItem(currentItemId, currentToolName, currentArgsText || argsBuffer);
-                yield factory.toolCallCompleted(tcItem);
+                yield factory.toolCallCompleted(currentItemId);
                 output.push(tcItem);
                 rawReplayContent.push({
                   type: "tool_use",
@@ -643,12 +650,21 @@ export class MessagesAdapter extends AdapterBase {
             }
           }
         }
+
+        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 Messages SSE frame", "STREAM_ERROR");
     }
 
@@ -692,8 +708,9 @@ export class MessagesAdapter extends AdapterBase {
       yield event;
     }
 
-    yield factory.responseCompleted(
-      this.buildResponse(
+    if (!completedEmitted) {
+      completedEmitted = true;
+      const finalResponse = this.buildResponse(
         request,
         {
           output,
@@ -707,7 +724,16 @@ export class MessagesAdapter 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,
+      });
+    }
   }
 }

package/src/adapters/mock.ts

@@ -264,7 +264,14 @@ export function assertMockRequest(
 
 export class MockAdapter extends AdapterBase {
   readonly kind = "mock" as const;
-  readonly nativeStreaming = false;
+  readonly capabilities = {
+    textStreaming: "synthetic",
+    reasoningStreaming: "synthetic",
+    toolCallStreaming: "synthetic",
+    replay: "canonical",
+    usage: "final",
+    toolResultOutcomes: ["success", "error", "rejected"],
+  } as const;
 
   private readonly handler: MockHandler;
   private readonly providerMetadata?: Record<string, unknown>;
@@ -358,13 +365,21 @@ export class MockAdapter extends AdapterBase {
             break;
           }
           case "complete": {
-            const response = this.finalizeTurn(request, factory, mockRequest, output, step, stepCount);
-            yield factory.responseCompleted(response);
+            const finalResponse = this.finalizeTurn(request, factory, mockRequest, output, step, stepCount);
+            yield factory.responseCompleted({
+              replay: finalResponse.replay,
+              stopReason: finalResponse.stopReason,
+              trace: finalResponse.backend,
+              usage: finalResponse.usage,
+              billing: finalResponse.billing,
+              auxiliary: finalResponse.auxiliary,
+              warnings: finalResponse.warnings,
+            });
             return;
           }
           case "error": {
             yield factory.responseWarning(step.message, step.code);
-            const response = this.finalizeTurn(
+            const finalResponse = this.finalizeTurn(
               request,
               factory,
               mockRequest,
@@ -376,7 +391,15 @@ export class MockAdapter extends AdapterBase {
               },
               stepCount,
             );
-            yield factory.responseCompleted(response);
+            yield factory.responseCompleted({
+              replay: finalResponse.replay,
+              stopReason: finalResponse.stopReason,
+              trace: finalResponse.backend,
+              usage: finalResponse.usage,
+              billing: finalResponse.billing,
+              auxiliary: finalResponse.auxiliary,
+              warnings: finalResponse.warnings,
+            });
             return;
           }
           case "interrupt":
@@ -387,7 +410,7 @@ export class MockAdapter extends AdapterBase {
         }
       }
 
-      const response = this.finalizeTurn(
+      const finalResponse = this.finalizeTurn(
         request,
         factory,
         mockRequest,
@@ -397,7 +420,15 @@ export class MockAdapter extends AdapterBase {
         },
         stepCount,
       );
-      yield factory.responseCompleted(response);
+      yield factory.responseCompleted({
+        replay: finalResponse.replay,
+        stopReason: finalResponse.stopReason,
+        trace: finalResponse.backend,
+        usage: finalResponse.usage,
+        billing: finalResponse.billing,
+        auxiliary: finalResponse.auxiliary,
+        warnings: finalResponse.warnings,
+      });
     } finally {
       this.activeStream = false;
     }
@@ -610,13 +641,15 @@ async function* emitMessage(
     if (block.type === "text") {
       for (const chunk of chunkText(block.text, stream)) {
         await delayForChunk(stream, chunkIndex, chunk.length);
-        yield factory.messageDelta(item.id, chunk);
+        yield factory.messageDelta(item.id, textBlock(chunk));
         chunkIndex += 1;
       }
+    } else {
+      yield factory.messageDelta(item.id, block);
     }
   }
 
-  yield factory.messageCompleted(item);
+  yield factory.messageCompleted(item.id);
 }
 
 async function* emitReasoning(
@@ -644,7 +677,7 @@ async function* emitReasoning(
     }
   }
 
-  yield factory.reasoningCompleted(item);
+  yield factory.reasoningCompleted(item.id);
 }
 
 async function* emitToolCall(
@@ -664,7 +697,7 @@ async function* emitToolCall(
     }
   }
 
-  yield factory.toolCallCompleted(item);
+  yield factory.toolCallCompleted(item.id);
 }
 
 function resolveStepStreamOptions(