@codehz/ai 0.1.4 → 0.1.6

package/package.json

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

package/src/adapters/chat-completions.ts

@@ -21,6 +21,7 @@ import {
   contentBlocksToText,
 } from "../helpers/mapping.js";
 import { emitMalformedStreamWarning } from "../helpers/adapter-auxiliary.js";
+import { usageFromChatCompletions } from "../helpers/usage-mapping.js";
 
 import type { NormalizedRequest, AIStreamEvent, EventFactory, OutputItem, FetchFn } from "../index.js";
 
@@ -73,7 +74,13 @@ type ChatChunk = {
   created: number;
   model: string;
   choices: ChatChunkChoice[];
-  usage?: { prompt_tokens: number; completion_tokens: number; total_tokens: number };
+  usage?: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    prompt_tokens_details?: { cached_tokens?: number };
+    completion_tokens_details?: { reasoning_tokens?: number };
+  };
 };
 
 type ChatChunkChoice = {
@@ -279,14 +286,7 @@ export class ChatCompletionsAdapter extends AdapterBase {
     for (const item of request.input) {
       switch (item.type) {
         case "message": {
-          const role =
-            item.role === "developer"
-              ? "system"
-              : item.role === "system"
-                ? "system"
-                : item.role === "user"
-                  ? "user"
-                  : "assistant";
+          const role = item.role;
           const text = contentBlocksToChatText(item.content, `input message (${item.role}) content`);
           messages.push({ role, content: text || null });
           break;
@@ -492,15 +492,7 @@ export class ChatCompletionsAdapter extends AdapterBase {
 
           // usage 可能在最终 chunk 中
           if (chunk.usage) {
-            auxiliary.recordUsage(
-              {
-                inputTokens: chunk.usage.prompt_tokens,
-                outputTokens: chunk.usage.completion_tokens,
-                totalTokens: chunk.usage.total_tokens,
-              },
-              "final",
-              chunk.usage,
-            );
+            auxiliary.recordUsage(usageFromChatCompletions(chunk.usage), "final", chunk.usage);
           }
 
           for (const choice of chunk.choices) {

package/src/adapters/messages.ts

@@ -24,6 +24,7 @@ import {
   contentBlocksToText,
 } from "../helpers/mapping.js";
 import { emitMalformedStreamWarning } from "../helpers/adapter-auxiliary.js";
+import { usageFromAnthropicMessages } from "../helpers/usage-mapping.js";
 
 import { parseSSEEvents } from "../helpers/sse-parser.js";
 
@@ -105,7 +106,7 @@ function ensureMessagesReasoningBlocks(
   });
 }
 
-function instructionsToMessagesText(instructions: string | import("../index.js").ContentBlock[]): string {
+function instructionsToMessagesText(instructions: string | import("../index.js").InstructionBlock[]): string {
   return typeof instructions === "string"
     ? instructions
     : contentBlocksToText(ensureMessagesTextBlocks(instructions, "instructions"));
@@ -131,7 +132,12 @@ type MessagesSSEEvent =
       type: "message_delta";
       data: {
         delta: { stop_reason?: string; stop_sequence?: string | null };
-        usage: { input_tokens: number; output_tokens: number };
+        usage: {
+          input_tokens: number;
+          output_tokens: number;
+          cache_creation_input_tokens?: number;
+          cache_read_input_tokens?: number;
+        };
       };
     }
   | { type: "message_stop"; data: Record<string, never> }
@@ -162,6 +168,11 @@ function rollbackTrailingAssistantMessages(messages: MessagesAPIMessage[]): void
   }
 }
 
+/** 用 response 级别的命名空间合成 content block 的 item ID，避免多轮工具循环 ID 碰撞 */
+function synthesizeItemId(kind: "msg" | "reason" | "reason-redacted", blockIndex: number, responseId: string): string {
+  return `${kind}-${blockIndex}-${responseId}`;
+}
+
 function parseToolUseInput(input: string): Record<string, unknown> {
   try {
     const parsed = JSON.parse(input);
@@ -272,16 +283,6 @@ export class MessagesAdapter extends AdapterBase {
     for (const item of request.input) {
       switch (item.type) {
         case "message": {
-          if (item.role === "system" || item.role === "developer") {
-            // Anthropic 不支持 system/developer role 在 messages 中
-            // 合并到 system prompt
-            const text = contentBlocksToText(
-              ensureMessagesTextBlocks(item.content, `input message (${item.role}) content`),
-            );
-            systemPrompt = systemPrompt ? `${systemPrompt}\n${text}` : text;
-            break;
-          }
-
           const role = item.role === "user" ? "user" : "assistant";
           const supportedContent = ensureMessagesTextBlocks(item.content, `input message (${item.role}) content`);
           if (supportedContent.length === 1 && supportedContent[0]?.type === "text") {
@@ -456,7 +457,7 @@ export class MessagesAdapter extends AdapterBase {
     // 完成响应数据
     let stopReason: string | undefined;
     let stopSequence: string | null | undefined;
-    let rawResponseId: string | undefined;
+    let rawResponseId = "";
 
     if (request.include?.providerMetadata !== "off") {
       const headerMetadata = pickProviderHeaders(response.headers);
@@ -513,7 +514,7 @@ export class MessagesAdapter extends AdapterBase {
               switch (block.type) {
                 case "text": {
                   currentItemType = "message";
-                  currentItemId = `msg-${block.type}-${currentContentBlockIndex}`;
+                  currentItemId = synthesizeItemId("msg", currentContentBlockIndex, rawResponseId);
                   textBuffer = "";
                   yield factory.messageStarted(currentItemId);
                   break;
@@ -521,7 +522,7 @@ export class MessagesAdapter extends AdapterBase {
                 case "thinking": {
                   hasStreamedReasoning = true;
                   currentItemType = "reasoning";
-                  currentItemId = `reason-${currentContentBlockIndex}`;
+                  currentItemId = synthesizeItemId("reason", currentContentBlockIndex, rawResponseId);
                   currentThinkingVisibility = "full";
                   thinkingBuffer = "";
                   yield factory.reasoningStarted(currentItemId, "full");
@@ -530,7 +531,7 @@ export class MessagesAdapter extends AdapterBase {
                 case "redacted_thinking": {
                   hasStreamedReasoning = true;
                   currentItemType = "reasoning";
-                  currentItemId = `reason-redacted-${currentContentBlockIndex}`;
+                  currentItemId = synthesizeItemId("reason-redacted", currentContentBlockIndex, rawResponseId);
                   currentThinkingVisibility = "redacted";
                   const data = (block as unknown as { data: string }).data;
                   yield factory.reasoningStarted(currentItemId, "redacted");
@@ -621,15 +622,7 @@ export class MessagesAdapter extends AdapterBase {
               stopSequence = sseEvent.data.delta.stop_sequence;
               const u = sseEvent.data.usage;
               if (u) {
-                auxiliary.recordUsage(
-                  {
-                    inputTokens: u.input_tokens,
-                    outputTokens: u.output_tokens,
-                    totalTokens: u.input_tokens + u.output_tokens,
-                  },
-                  "stream",
-                  u,
-                );
+                auxiliary.recordUsage(usageFromAnthropicMessages(u), "stream", u);
               }
               continue;
             }

package/src/adapters/ollama.ts

@@ -27,6 +27,7 @@ import {
   contentBlocksToText,
 } from "../helpers/mapping.js";
 import { emitMalformedStreamWarning } from "../helpers/adapter-auxiliary.js";
+import { usageFromOllama } from "../helpers/usage-mapping.js";
 
 import type { NormalizedRequest, AIStreamEvent, EventFactory, OutputItem, FetchFn } from "../index.js";
 
@@ -112,7 +113,7 @@ function ensureOllamaReasoningBlocks(
   });
 }
 
-function instructionsToOllamaText(instructions: string | import("../index.js").ContentBlock[]): string {
+function instructionsToOllamaText(instructions: string | import("../index.js").InstructionBlock[]): string {
   return typeof instructions === "string"
     ? instructions
     : contentBlocksToText(ensureOllamaTextBlocks(instructions, "instructions"));
@@ -259,14 +260,7 @@ export class OllamaAdapter extends AdapterBase {
     for (const item of request.input) {
       switch (item.type) {
         case "message": {
-          const role =
-            item.role === "developer"
-              ? "system"
-              : item.role === "system"
-                ? "system"
-                : item.role === "user"
-                  ? "user"
-                  : "assistant";
+          const role = item.role;
           messages.push({
             role,
             content: contentBlocksToText(ensureOllamaTextBlocks(item.content, `input message (${item.role}) content`)),
@@ -485,14 +479,10 @@ export class OllamaAdapter extends AdapterBase {
               (chunk.prompt_eval_count !== undefined || chunk.eval_count !== undefined)
             ) {
               auxiliary.recordUsage(
-                {
-                  inputTokens: chunk.prompt_eval_count,
-                  outputTokens: chunk.eval_count,
-                  totalTokens:
-                    chunk.prompt_eval_count !== undefined && chunk.eval_count !== undefined
-                      ? chunk.prompt_eval_count + chunk.eval_count
-                      : undefined,
-                },
+                usageFromOllama({
+                  prompt_eval_count: chunk.prompt_eval_count,
+                  eval_count: chunk.eval_count,
+                }),
                 "final",
                 {
                   prompt_eval_count: chunk.prompt_eval_count,

package/src/adapters/responses.ts

@@ -22,6 +22,7 @@ import {
   contentBlocksToText,
 } from "../helpers/mapping.js";
 import { emitMalformedStreamWarning } from "../helpers/adapter-auxiliary.js";
+import { usageFromOpenAIResponses } from "../helpers/usage-mapping.js";
 
 import { parseSSEEvents } from "../helpers/sse-parser.js";
 
@@ -51,7 +52,7 @@ type ResponsesAPIRequest = {
 };
 
 type ResponsesInputItem =
-  | { type: "message"; role: "user" | "assistant" | "system" | "developer"; content: string }
+  | { type: "message"; role: "user" | "assistant"; content: string }
   | { type: "message"; role: "assistant"; content: ResponsesContentBlock[] }
   | { type: "function_call"; id: string; name: string; arguments: string; call_id?: string }
   | { type: "function_call_output"; call_id: string; output: string }
@@ -104,7 +105,7 @@ function ensureResponsesReasoningBlocks(
   });
 }
 
-function instructionsToResponsesText(instructions: string | import("../index.js").ContentBlock[]): string {
+function instructionsToResponsesText(instructions: string | import("../index.js").InstructionBlock[]): string {
   return typeof instructions === "string"
     ? instructions
     : contentBlocksToText(ensureResponsesTextBlocks(instructions, "instructions"));
@@ -448,15 +449,7 @@ export class ResponsesAdapter extends AdapterBase {
     if (completedResponse) {
       rawResponseId = completedResponse.id;
       if (completedResponse.usage) {
-        auxiliary.recordUsage(
-          {
-            inputTokens: completedResponse.usage.input_tokens,
-            outputTokens: completedResponse.usage.output_tokens,
-            totalTokens: completedResponse.usage.total_tokens,
-          },
-          "final",
-          completedResponse.usage,
-        );
+        auxiliary.recordUsage(usageFromOpenAIResponses(completedResponse.usage), "final", completedResponse.usage);
       }
     }
 

package/src/core/validation.ts

@@ -14,7 +14,7 @@ export type ValidationIssue = {
   message: string;
 };
 
-const MESSAGE_ROLES = new Set(["user", "assistant", "system", "developer"]);
+const MESSAGE_ROLES = new Set(["user", "assistant"]);
 const REASONING_VISIBILITIES = new Set(["full", "summary", "redacted", "opaque"]);
 const TOOL_RESULT_OUTCOMES = new Set(["success", "error", "rejected"]);
 const INCLUDE_MODES = new Set(["off", "best_effort"]);
@@ -75,6 +75,24 @@ function validateContentArray(content: unknown, field: string, issues: Validatio
   }
 }
 
+function validateInstructionArray(content: unknown, field: string, issues: ValidationIssue[]): void {
+  if (!Array.isArray(content)) {
+    pushIssue(issues, field, "INSTRUCTIONS_INVALID", `${field} must be an InstructionBlock[]`);
+    return;
+  }
+
+  for (let i = 0; i < content.length; i++) {
+    const block = content[i];
+    const blockField = `${field}[${i}]`;
+    validateContentBlock(block, blockField, issues);
+
+    if (!isRecord(block) || typeof block.type !== "string") continue;
+    if (block.type !== "text" && block.type !== "json") {
+      pushIssue(issues, blockField, "INSTRUCTIONS_INVALID", `${blockField} only supports text/json blocks`);
+    }
+  }
+}
+
 function validateInputItem(item: unknown, field: string, issues: ValidationIssue[]): void {
   if (!isRecord(item)) {
     pushIssue(issues, field, "INPUT_INVALID_ITEM", `${field} must be a valid InputItem`);
@@ -219,9 +237,9 @@ export function validateRequest(request: AIRequest): ValidationIssue[] {
     if (typeof request.instructions === "string") {
       // no-op
     } else if (Array.isArray(request.instructions)) {
-      validateContentArray(request.instructions, "instructions", issues, "INSTRUCTIONS_INVALID");
+      validateInstructionArray(request.instructions, "instructions", issues);
     } else {
-      pushIssue(issues, "instructions", "INSTRUCTIONS_INVALID", "instructions must be a string or ContentBlock[]");
+      pushIssue(issues, "instructions", "INSTRUCTIONS_INVALID", "instructions must be a string or InstructionBlock[]");
     }
   }
 

package/src/helpers/index.ts

@@ -34,3 +34,9 @@ export { syntheticStream } from "./synthetic-stream.js";
 export type { SyntheticStreamOptions } from "./synthetic-stream.js";
 export { AuxiliaryCollector } from "./auxiliary-collector.js";
 export type { UsageSource, BillingSource, LookupResult } from "./auxiliary-collector.js";
+export {
+  usageFromAnthropicMessages,
+  usageFromChatCompletions,
+  usageFromOllama,
+  usageFromOpenAIResponses,
+} from "./usage-mapping.js";

package/src/helpers/mapping.ts

@@ -12,6 +12,7 @@
 import type {
   StopReason,
   ContentBlock,
+  InstructionBlock,
   MessageItem,
   ReasoningItem,
   ToolCallItem,
@@ -179,9 +180,9 @@ export function contentBlocksToText(blocks: ContentBlock[]): string {
 }
 
 /**
- * 将 instructions（string | ContentBlock[]）归一化为纯文本。
+ * 将 instructions（string | InstructionBlock[]）归一化为纯文本。
  */
-export function instructionsToText(instructions: string | ContentBlock[]): string {
+export function instructionsToText(instructions: string | InstructionBlock[]): string {
   return typeof instructions === "string" ? instructions : contentBlocksToText(instructions);
 }
 

package/src/helpers/usage-mapping.ts

@@ -0,0 +1,150 @@
+/**
+ * Provider usage → canonical Usage 映射
+ *
+ * best-effort 提取 reasoning / cache / billable 等扩展字段。
+ */
+
+import type { Usage } from "../types/index.js";
+
+function num(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function record(obj: Record<string, number | undefined>): Partial<Usage> {
+  const out: Partial<Usage> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value !== undefined) {
+      (out as Record<string, number>)[key] = value;
+    }
+  }
+  return out;
+}
+
+function billableFromOpenAIStyle(
+  inputTokens: number | undefined,
+  outputTokens: number | undefined,
+  cachedInputTokens: number | undefined,
+  reasoningTokens: number | undefined,
+): Pick<Usage, "billableInputTokens" | "billableOutputTokens"> {
+  let billableInputTokens: number | undefined;
+  if (inputTokens !== undefined) {
+    billableInputTokens =
+      cachedInputTokens !== undefined ? Math.max(0, inputTokens - cachedInputTokens) : inputTokens;
+  }
+
+  let billableOutputTokens: number | undefined;
+  if (outputTokens !== undefined) {
+    billableOutputTokens =
+      reasoningTokens !== undefined ? Math.max(0, outputTokens - reasoningTokens) : outputTokens;
+  }
+
+  return record({ billableInputTokens, billableOutputTokens });
+}
+
+/** OpenAI Chat Completions `usage` */
+export function usageFromChatCompletions(raw: {
+  prompt_tokens?: number;
+  completion_tokens?: number;
+  total_tokens?: number;
+  prompt_tokens_details?: { cached_tokens?: number; [key: string]: unknown };
+  completion_tokens_details?: { reasoning_tokens?: number; [key: string]: unknown };
+}): Partial<Usage> {
+  const inputTokens = num(raw.prompt_tokens);
+  const outputTokens = num(raw.completion_tokens);
+  const cachedInputTokens = num(raw.prompt_tokens_details?.cached_tokens);
+  const reasoningTokens = num(raw.completion_tokens_details?.reasoning_tokens);
+  const totalTokens =
+    num(raw.total_tokens) ??
+    (inputTokens !== undefined && outputTokens !== undefined ? inputTokens + outputTokens : undefined);
+
+  return record({
+    inputTokens,
+    outputTokens,
+    totalTokens,
+    cachedInputTokens,
+    reasoningTokens,
+    ...billableFromOpenAIStyle(inputTokens, outputTokens, cachedInputTokens, reasoningTokens),
+  });
+}
+
+/** OpenAI Responses API `usage` */
+export function usageFromOpenAIResponses(raw: {
+  input_tokens?: number;
+  output_tokens?: number;
+  total_tokens?: number;
+  input_tokens_details?: { cached_tokens?: number; [key: string]: unknown };
+  output_tokens_details?: { reasoning_tokens?: number; [key: string]: unknown };
+  [key: string]: unknown;
+}): Partial<Usage> {
+  const inputTokens = num(raw.input_tokens);
+  const outputTokens = num(raw.output_tokens);
+  const cachedInputTokens = num(raw.input_tokens_details?.cached_tokens);
+  const reasoningTokens = num(raw.output_tokens_details?.reasoning_tokens);
+  const totalTokens =
+    num(raw.total_tokens) ??
+    (inputTokens !== undefined && outputTokens !== undefined ? inputTokens + outputTokens : undefined);
+
+  return record({
+    inputTokens,
+    outputTokens,
+    totalTokens,
+    cachedInputTokens,
+    reasoningTokens,
+    ...billableFromOpenAIStyle(inputTokens, outputTokens, cachedInputTokens, reasoningTokens),
+  });
+}
+
+/** Anthropic Messages `usage`（message_start / message_delta） */
+export function usageFromAnthropicMessages(raw: {
+  input_tokens?: number;
+  output_tokens?: number;
+  cache_creation_input_tokens?: number;
+  cache_read_input_tokens?: number;
+  [key: string]: unknown;
+}): Partial<Usage> {
+  const inputTokens = num(raw.input_tokens);
+  const outputTokens = num(raw.output_tokens);
+  const cacheWriteInputTokens = num(raw.cache_creation_input_tokens);
+  const cachedInputTokens = num(raw.cache_read_input_tokens);
+
+  const inputParts = [inputTokens, cacheWriteInputTokens, cachedInputTokens].filter(
+    (n): n is number => n !== undefined,
+  );
+  const summedInput = inputParts.length > 0 ? inputParts.reduce((sum, n) => sum + n, 0) : undefined;
+  const totalTokens =
+    summedInput !== undefined && outputTokens !== undefined ? summedInput + outputTokens : undefined;
+
+  let billableInputTokens: number | undefined;
+  if (inputTokens !== undefined || cacheWriteInputTokens !== undefined) {
+    billableInputTokens = (inputTokens ?? 0) + (cacheWriteInputTokens ?? 0);
+  }
+
+  return record({
+    inputTokens,
+    outputTokens,
+    totalTokens,
+    cachedInputTokens,
+    cacheWriteInputTokens,
+    billableInputTokens,
+    billableOutputTokens: outputTokens,
+  });
+}
+
+/** Ollama 流式 chunk（无 cache / reasoning 细分时仅填基础与 billable 镜像） */
+export function usageFromOllama(raw: {
+  prompt_eval_count?: number;
+  eval_count?: number;
+}): Partial<Usage> {
+  const inputTokens = num(raw.prompt_eval_count);
+  const outputTokens = num(raw.eval_count);
+  const totalTokens =
+    inputTokens !== undefined && outputTokens !== undefined ? inputTokens + outputTokens : undefined;
+
+  return record({
+    inputTokens,
+    outputTokens,
+    totalTokens,
+    billableInputTokens: inputTokens,
+    billableOutputTokens: outputTokens,
+  });
+}

package/src/types/content.ts

@@ -4,9 +4,12 @@
  * 覆盖文本、JSON、图片、二进制引用和后端私有内容。
  */
 
+export type TextContentBlock = { type: "text"; text: string };
+export type JsonContentBlock = { type: "json"; json: unknown };
+export type InstructionBlock = TextContentBlock | JsonContentBlock;
+
 export type ContentBlock =
-  | { type: "text"; text: string }
-  | { type: "json"; json: unknown }
+  | InstructionBlock
   | { type: "image"; imageUrl: string }
   | { type: "binary_ref"; ref: string }
   | { type: "opaque"; payload: unknown };

package/src/types/index.ts

@@ -6,7 +6,7 @@
  */
 
 // 基础内容块
-export type { ContentBlock } from "./content.js";
+export type { TextContentBlock, JsonContentBlock, InstructionBlock, ContentBlock } from "./content.js";
 
 // Item 类型体系
 export type {

package/src/types/items.ts

@@ -11,7 +11,7 @@ import type { ContentBlock } from "./content.js";
 export type MessageItem = {
   type: "message";
   id?: string;
-  role: "user" | "assistant" | "system" | "developer";
+  role: "user" | "assistant";
   content: ContentBlock[];
 };
 

package/src/types/request.ts

@@ -4,7 +4,7 @@
  * 所有 adapter 都接受同一形状的 canonical request。
  */
 
-import type { ContentBlock } from "./content.js";
+import type { InstructionBlock } from "./content.js";
 import type { InputItem } from "./items.js";
 
 // ── 工具定义 ──────────────────────────────────────────────────
@@ -28,7 +28,7 @@ export type IncludeSettings = {
 // ── 统一请求 ──────────────────────────────────────────────────
 
 export type AIRequest = {
-  instructions?: string | ContentBlock[];
+  instructions?: string | InstructionBlock[];
   input: InputItem[];
   tools?: ToolDefinition[];
   toolChoice?: ToolChoice;

package/src/types/response.ts

@@ -13,13 +13,20 @@ export type StopReason = "end_turn" | "tool_call" | "max_output_tokens" | "conte
 // ── 辅助信息类型 ──────────────────────────────────────────────
 
 export type Usage = {
+  /** Provider prompt / input token count */
   inputTokens?: number;
+  /** Provider completion / output token count */
   outputTokens?: number;
+  /** Reasoning tokens when provider exposes output breakdown (e.g. OpenAI Responses) */
   reasoningTokens?: number;
   totalTokens?: number;
+  /** Tokens read from prompt cache (OpenAI cached_tokens, Anthropic cache_read_input_tokens) */
   cachedInputTokens?: number;
+  /** Tokens written to prompt cache (Anthropic cache_creation_input_tokens) */
   cacheWriteInputTokens?: number;
+  /** Best-effort billable input (full-rate input; excludes discounted cache reads where known) */
   billableInputTokens?: number;
+  /** Best-effort billable output (non-reasoning slice when provider gives reasoning breakdown) */
   billableOutputTokens?: number;
 };