cctra 0.3.0

package/src/convert/common/tool-calls.ts

@@ -0,0 +1,29 @@
+import type { CanonicalContentBlock } from "../../canonical/types";
+import { isToolUse, isToolResult } from "./content-blocks";
+
+// ============================================================================
+// tool_use ↔ tool_calls 互转工具
+// OpenAI Chat Completions 用 tool_calls / tool role messages
+// OpenAI Responses / Anthropic 用结构化 content blocks
+// ============================================================================
+
+/** 提取消息里所有的 tool_use blocks */
+export function extractToolUses(blocks: CanonicalContentBlock[]): Array<{ id: string; name: string; input: unknown }> {
+  return blocks.filter(isToolUse).map((b) => ({ id: b.id, name: b.name, input: b.input }));
+}
+
+/** 提取消息里所有的 tool_result blocks */
+export function extractToolResults(blocks: CanonicalContentBlock[]): Array<{ toolUseId: string; content: string; isError?: boolean }> {
+  return blocks.filter(isToolResult).map((b) => ({
+    toolUseId: b.toolUseId,
+    content: typeof b.content === "string" ? b.content : extractTextFromBlocks(b.content),
+    isError: b.isError,
+  }));
+}
+
+function extractTextFromBlocks(blocks: CanonicalContentBlock[]): string {
+  return blocks
+    .filter((b): b is { type: "text"; text: string } => b.type === "text")
+    .map((b) => b.text)
+    .join("");
+}

package/src/convert/common/usage.ts

@@ -0,0 +1,19 @@
+import type { CanonicalUsage } from "../../canonical/types";
+
+// 把 CanonicalUsage 拆成 OpenAI 风格的 input/output
+export function splitUsage(u: CanonicalUsage): { prompt_tokens: number; completion_tokens: number } {
+  return {
+    prompt_tokens: u.inputTokens,
+    completion_tokens: u.outputTokens,
+  };
+}
+
+// 合并增量到 usage（流式用）
+export function mergeUsage(base: CanonicalUsage, delta: Partial<CanonicalUsage>): CanonicalUsage {
+  return {
+    inputTokens: delta.inputTokens ?? base.inputTokens,
+    outputTokens: delta.outputTokens ?? base.outputTokens,
+    cacheReadTokens: delta.cacheReadTokens ?? base.cacheReadTokens,
+    cacheWriteTokens: delta.cacheWriteTokens ?? base.cacheWriteTokens,
+  };
+}

package/src/convert/inbound/anthropic-to-canonical.ts

@@ -0,0 +1,106 @@
+// ============================================================================
+// Anthropic Messages → Canonical
+// Anthropic 格式跟 Canonical 几乎一样，主要是字段名 / 类型微调
+// ============================================================================
+import type { CanonicalRequest, CanonicalMessage, CanonicalContentBlock, CanonicalTool } from "../../canonical/types";
+import { splitKnownAndExtras } from "../common/extras";
+
+interface AnthropicRequest {
+  model?: string;
+  system?: string | Array<{ type: "text"; text: string; cache_control?: unknown }>;
+  messages?: Array<{
+    role: "user" | "assistant";
+    content: string | Array<AnthropicContentBlock>;
+  }>;
+  tools?: Array<{
+    name: string;
+    description?: string;
+    input_schema: Record<string, unknown>;
+  }>;
+  max_tokens?: number;
+  temperature?: number;
+  top_p?: number;
+  stop_sequences?: string[];
+  stream?: boolean;
+}
+
+type AnthropicContentBlock =
+  | { type: "text"; text: string }
+  | { type: "image"; source: { type: "base64" | "url"; media_type: string; data?: string; url?: string } }
+  | { type: "document"; source: { type: "base64" | "url"; media_type: string; data?: string; url?: string } }
+  | { type: "tool_use"; id: string; name: string; input: unknown }
+  | { type: "tool_result"; tool_use_id: string; content: string | Array<{ type: "text"; text: string }>; is_error?: boolean }
+  | { type: "thinking"; thinking: string; signature?: string };
+
+export function anthropicToCanonical(req: AnthropicRequest): CanonicalRequest {
+  const messages: CanonicalMessage[] = (req.messages ?? []).map((m) => {
+    const knownMsgKeys: ReadonlySet<keyof typeof m> = new Set(["role", "content"]);
+    const { known, extras } = splitKnownAndExtras(m as unknown as Record<string, unknown>, knownMsgKeys as ReadonlySet<keyof Record<string, unknown>>, "anthropic");
+    return {
+      ...(known as { role: "user" | "assistant" }),
+      content: messageContentToBlocks(m.content),
+      ...(Object.keys(extras).length > 0 ? { extras } : {}),
+    };
+  });
+
+  const tools: CanonicalTool[] | undefined = req.tools?.map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: t.input_schema,
+  }));
+
+  // system 可以是字符串或 text block 数组
+  let system: CanonicalRequest["system"];
+  if (typeof req.system === "string") {
+    system = req.system;
+  } else if (Array.isArray(req.system)) {
+    system = req.system.map((b) => ({ type: "text" as const, text: b.text }));
+  }
+
+  return {
+    model: req.model ?? "",
+    messages,
+    system,
+    tools: tools && tools.length > 0 ? tools : undefined,
+    maxTokens: req.max_tokens,
+    temperature: req.temperature,
+    topP: req.top_p,
+    stopSequences: req.stop_sequences,
+    stream: !!req.stream,
+  };
+}
+
+function messageContentToBlocks(content: string | AnthropicContentBlock[]): CanonicalContentBlock[] {
+  if (typeof content === "string") return [{ type: "text", text: content }];
+  return content.map((b): CanonicalContentBlock => {
+    switch (b.type) {
+      case "text":
+        return { type: "text", text: b.text };
+      case "image": {
+        const src = b.source;
+        if (src.type === "base64") {
+          return { type: "image", source: { kind: "base64", mediaType: src.media_type, data: src.data ?? "" } };
+        }
+        return { type: "image", source: { kind: "url", mediaType: src.media_type, data: src.url ?? "" } };
+      }
+      case "document": {
+        const src = b.source;
+        if (src.type === "base64") {
+          return { type: "document", source: { kind: "base64", mediaType: src.media_type, data: src.data ?? "" } };
+        }
+        return { type: "document", source: { kind: "url", mediaType: src.media_type, data: src.url ?? "" } };
+      }
+      case "tool_use":
+        return { type: "tool_use", id: b.id, name: b.name, input: b.input };
+      case "tool_result":
+        return {
+          type: "tool_result",
+          toolUseId: b.tool_use_id,
+          content: typeof b.content === "string" ? b.content : b.content.map((t) => ({ type: "text" as const, text: t.text })),
+          isError: b.is_error,
+        };
+      case "thinking":
+        return { type: "thinking", thinking: b.thinking, signature: b.signature };
+    }
+  });
+}

package/src/convert/inbound/chat-to-canonical.ts

@@ -0,0 +1,132 @@
+// ============================================================================
+// OpenAI Chat Completions → Canonical
+// ============================================================================
+import type { CanonicalRequest, CanonicalMessage, CanonicalContentBlock, CanonicalTool } from "../../canonical/types";
+import { splitKnownAndExtras } from "../common/extras";
+
+// OpenAI Chat Completions 的请求格式（我们只关心字段，不严格类型化）
+type ChatContentPart = { type: string; text?: string; image_url?: { url: string } };
+type ChatMessage = {
+  role: "system" | "user" | "assistant" | "tool" | "function";
+  content?: string | null | ChatContentPart[];
+  name?: string;
+  tool_call_id?: string;
+  tool_calls?: Array<{
+    id: string;
+    type: "function";
+    function: { name: string; arguments: string };
+  }>;
+};
+interface ChatRequest {
+  model?: string;
+  messages?: ChatMessage[];
+  tools?: Array<{
+    type: "function";
+    function: { name: string; description?: string; parameters?: Record<string, unknown> };
+  }>;
+  max_tokens?: number;
+  temperature?: number;
+  top_p?: number;
+  stop?: string | string[];
+  stream?: boolean;
+}
+
+export function chatToCanonical(req: ChatRequest): CanonicalRequest {
+  const messages: CanonicalMessage[] = [];
+  let system: string | CanonicalContentBlock[] | undefined;
+
+  for (const m of req.messages ?? []) {
+    // system 单独提到顶级
+    if (m.role === "system") {
+      const text = typeof m.content === "string" ? m.content : "";
+      if (text) {
+        if (typeof system === "string") system = system + "\n\n" + text;
+        else if (Array.isArray(system)) system.push({ type: "text", text });
+        else system = text;
+      }
+      continue;
+    }
+
+    // tool 消息 → tool_result block，挂到上一条 assistant 的回复里
+    // 简化：把 tool 消息变成 user 消息的 tool_result
+    if (m.role === "tool") {
+      const blocks: CanonicalContentBlock[] = [
+        {
+          type: "tool_result",
+          toolUseId: m.tool_call_id ?? "",
+          content: typeof m.content === "string" ? m.content : "",
+        },
+      ];
+      messages.push({ role: "user", content: blocks });
+      continue;
+    }
+
+    if (m.role === "user") {
+      const blocks = contentToBlocks(m.content ?? null);
+      messages.push({ role: "user", content: blocks });
+      continue;
+    }
+
+    if (m.role === "assistant") {
+      const blocks: CanonicalContentBlock[] = [];
+      if (m.content) blocks.push(...contentToBlocks(m.content));
+      // tool_calls → tool_use blocks
+      if (m.tool_calls) {
+        for (const tc of m.tool_calls) {
+          let input: unknown = {};
+          try { input = JSON.parse(tc.function.arguments); } catch { /* keep empty */ }
+          blocks.push({ type: "tool_use", id: tc.id, name: tc.function.name, input });
+        }
+      }
+      // extras：把原始 m 整体塞 openaiChat 桶
+      const knownMsgKeys = new Set(["role", "content", "tool_calls"]);
+      const { known: _k, extras } = splitKnownAndExtras(m as unknown as Record<string, unknown>, knownMsgKeys, "openaiChat");
+      void _k;
+      messages.push({
+        role: "assistant",
+        content: blocks,
+        ...(Object.keys(extras).length > 0 ? { extras } : {}),
+      });
+      continue;
+    }
+  }
+
+  const tools: CanonicalTool[] | undefined = req.tools?.map((t) => ({
+    name: t.function.name,
+    description: t.function.description,
+    inputSchema: t.function.parameters ?? { type: "object", properties: {} },
+  }));
+
+  return {
+    model: req.model ?? "",
+    messages,
+    system,
+    tools: tools && tools.length > 0 ? tools : undefined,
+    maxTokens: req.max_tokens,
+    temperature: req.temperature,
+    topP: req.top_p,
+    stopSequences: Array.isArray(req.stop) ? req.stop : req.stop ? [req.stop] : undefined,
+    stream: !!req.stream,
+  };
+}
+
+function contentToBlocks(content: string | null | ChatContentPart[]): CanonicalContentBlock[] {
+  if (content == null) return [];
+  if (typeof content === "string") return [{ type: "text", text: content }];
+  const blocks: CanonicalContentBlock[] = [];
+  for (const part of content) {
+    if (part.type === "text" && part.text) {
+      blocks.push({ type: "text", text: part.text });
+    } else if (part.type === "image_url" && part.image_url) {
+      const url = part.image_url.url;
+      if (url.startsWith("data:")) {
+        // data:image/png;base64,xxxx
+        const match = url.match(/^data:([^;]+);base64,(.+)$/);
+        if (match) blocks.push({ type: "image", source: { kind: "base64", mediaType: match[1]!, data: match[2]! } });
+      } else {
+        blocks.push({ type: "image", source: { kind: "url", mediaType: "image/*", data: url } });
+      }
+    }
+  }
+  return blocks;
+}

package/src/convert/inbound/responses-to-canonical.ts

@@ -0,0 +1,92 @@
+// ============================================================================
+// OpenAI Responses API → Canonical
+// 处理 input 字符串/数组、tools、stream、previous_response_id、reasoning
+// 跳过：5 个内置工具（web_search/code_interpreter/file_search/mcp/computer_use）
+// ============================================================================
+import type { CanonicalRequest, CanonicalMessage, CanonicalContentBlock, CanonicalTool } from "../../canonical/types";
+import { splitKnownAndExtras } from "../common/extras";
+
+interface ResponsesRequest {
+  model?: string;
+  input?: string | Array<{
+    role?: "user" | "assistant" | "system" | "developer";
+    content: string | Array<{
+      type: string;
+      text?: string;
+      image_url?: string;
+    }>;
+  }>;
+  instructions?: string;
+  tools?: Array<{
+    type: "function";
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+  }>;
+  max_output_tokens?: number;
+  temperature?: number;
+  top_p?: number;
+  stream?: boolean;
+  previous_response_id?: string;
+  reasoning?: { effort?: "low" | "medium" | "high" };
+}
+
+export function responsesToCanonical(req: ResponsesRequest): CanonicalRequest {
+  const messages: CanonicalMessage[] = [];
+
+  if (typeof req.input === "string") {
+    messages.push({ role: "user", content: [{ type: "text", text: req.input }] });
+  } else if (Array.isArray(req.input)) {
+    for (const m of req.input) {
+      const role = m.role === "assistant" ? "assistant" : "user";
+      const blocks: CanonicalContentBlock[] = [];
+      if (typeof m.content === "string") {
+        blocks.push({ type: "text", text: m.content });
+      } else {
+        for (const part of m.content) {
+          if (part.type === "input_text" && part.text) {
+            blocks.push({ type: "text", text: part.text });
+          } else if (part.type === "input_image" && part.image_url) {
+            const url = part.image_url;
+            if (url.startsWith("data:")) {
+              const match = url.match(/^data:([^;]+);base64,(.+)$/);
+              if (match) blocks.push({ type: "image", source: { kind: "base64", mediaType: match[1]!, data: match[2]! } });
+            } else {
+              blocks.push({ type: "image", source: { kind: "url", mediaType: "image/*", data: url } });
+            }
+          }
+        }
+      }
+      // extras：未识别字段塞 openaiResponses 桶
+      const knownMsgKeys = new Set(["role", "content"]);
+      const { known: _k, extras } = splitKnownAndExtras(m as unknown as Record<string, unknown>, knownMsgKeys, "openaiResponses");
+      void _k;
+      messages.push({
+        role,
+        content: blocks,
+        ...(Object.keys(extras).length > 0 ? { extras } : {}),
+      });
+    }
+  }
+
+  const tools: CanonicalTool[] | undefined = req.tools
+    ?.filter((t) => t.type === "function")
+    .map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.parameters ?? { type: "object", properties: {} },
+    }));
+
+  return {
+    model: req.model ?? "",
+    messages,
+    system: req.instructions,
+    tools: tools && tools.length > 0 ? tools : undefined,
+    maxTokens: req.max_output_tokens,
+    temperature: req.temperature,
+    topP: req.top_p,
+    stream: !!req.stream,
+    previousResponseId: req.previous_response_id,
+    reasoning: req.reasoning,
+  };
+}

package/src/convert/outbound/canonical-to-anthropic.ts

@@ -0,0 +1,62 @@
+// ============================================================================
+// Canonical → Anthropic Messages 响应
+// ============================================================================
+import type { CanonicalResponse, StopReason } from "../../canonical/types";
+
+interface AnthropicResponse {
+  id: string;
+  type: "message";
+  role: "assistant";
+  model: string;
+  content: Array<{ type: "text"; text: string } | { type: "tool_use"; id: string; name: string; input: unknown }>;
+  stop_reason: StopReason | null;
+  stop_sequence: string | null;
+  usage: {
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+  };
+}
+
+/** Anthropic 错误响应：{ type: "error", error: { type, message } } */
+interface AnthropicErrorResponse {
+  type: "error";
+  error: { type: string; message: string };
+}
+
+export function canonicalToAnthropicResponse(res: CanonicalResponse): AnthropicResponse | AnthropicErrorResponse {
+  // 错误响应：短路返回 Anthropic 错误 shape
+  if (res.error) {
+    return {
+      type: "error",
+      error: {
+        type: res.error.type ?? "api_error",
+        message: res.error.message,
+      },
+    };
+  }
+
+  const content: AnthropicResponse["content"] = [];
+  for (const b of res.content) {
+    if (b.type === "text") content.push({ type: "text", text: b.text });
+    else if (b.type === "tool_use") content.push({ type: "tool_use", id: b.id, name: b.name, input: b.input });
+    // 其他 block 类型（image / tool_result）不应出现在 assistant 消息里
+  }
+
+  return {
+    id: res.id,
+    type: "message",
+    role: "assistant",
+    model: res.model,
+    content,
+    stop_reason: res.stopReason,
+    stop_sequence: null,
+    usage: {
+      input_tokens: res.usage.inputTokens,
+      output_tokens: res.usage.outputTokens,
+      ...(res.usage.cacheReadTokens !== undefined && { cache_read_input_tokens: res.usage.cacheReadTokens }),
+      ...(res.usage.cacheWriteTokens !== undefined && { cache_creation_input_tokens: res.usage.cacheWriteTokens }),
+    },
+  };
+}

package/src/convert/outbound/canonical-to-chat.ts

@@ -0,0 +1,101 @@
+// ============================================================================
+// Canonical → OpenAI Chat Completions 响应
+// ============================================================================
+import type { CanonicalResponse, CanonicalContentBlock } from "../../canonical/types";
+
+interface ChatResponse {
+  id: string;
+  object: "chat.completion";
+  created: number;
+  model: string;
+  choices: Array<{
+    index: number;
+    message: {
+      role: "assistant";
+      content: string | null;
+      tool_calls?: Array<{
+        id: string;
+        type: "function";
+        function: { name: string; arguments: string };
+      }>;
+    };
+    finish_reason: "stop" | "length" | "tool_calls" | "content_filter" | null;
+  }>;
+  usage?: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+}
+
+/** OpenAI Chat 错误响应：{ error: { message, type, code? } }，无 choices/usage */
+interface ChatErrorResponse {
+  error: { message: string; type: string; code?: number };
+}
+
+export function canonicalToChatResponse(res: CanonicalResponse): ChatResponse | ChatErrorResponse {
+  // 错误响应：短路返回 OpenAI Chat 错误 shape
+  if (res.error) {
+    return {
+      error: {
+        message: res.error.message,
+        type: res.error.type ?? "upstream_error",
+        ...(res.error.status !== undefined && { code: res.error.status }),
+      },
+    };
+  }
+
+  const text = extractText(res.content);
+  const toolUses = res.content.filter((b): b is { type: "tool_use"; id: string; name: string; input: unknown } => b.type === "tool_use");
+
+  const message: ChatResponse["choices"][number]["message"] = {
+    role: "assistant",
+    content: text || null,
+  };
+  if (toolUses.length > 0) {
+    message.tool_calls = toolUses.map((u) => ({
+      id: u.id,
+      type: "function",
+      function: {
+        name: u.name,
+        arguments: typeof u.input === "string" ? u.input : JSON.stringify(u.input ?? {}),
+      },
+    }));
+  }
+
+  return {
+    id: res.id,
+    object: "chat.completion",
+    created: Math.floor(Date.now() / 1000),
+    model: res.model,
+    choices: [
+      {
+        index: 0,
+        message,
+        finish_reason: mapStopReason(res.stopReason),
+      },
+    ],
+    usage: {
+      prompt_tokens: res.usage.inputTokens,
+      completion_tokens: res.usage.outputTokens,
+      total_tokens: res.usage.inputTokens + res.usage.outputTokens,
+    },
+  };
+}
+
+function extractText(blocks: CanonicalContentBlock[]): string {
+  return blocks
+    .filter((b): b is { type: "text"; text: string } => b.type === "text")
+    .map((b) => b.text)
+    .join("");
+}
+
+function mapStopReason(r: CanonicalResponse["stopReason"]): ChatResponse["choices"][number]["finish_reason"] {
+  switch (r) {
+    case "end_turn": return "stop";
+    case "max_tokens": return "length";
+    case "tool_use": return "tool_calls";
+    case "stop_sequence": return "stop";
+    case "error": return "content_filter";
+  }
+}

package/src/convert/outbound/canonical-to-responses.ts

@@ -0,0 +1,105 @@
+// ============================================================================
+// Canonical → OpenAI Responses API 响应
+// 输出 message (output_text/refusal) + function_call + reasoning 块
+// 跳过：5 个内置工具调用（Canonical 不承载）
+// ============================================================================
+import type { CanonicalResponse, CanonicalContentBlock } from "../../canonical/types";
+
+type MessageContent =
+  | { type: "output_text"; text: string }
+  | { type: "refusal"; refusal: string };
+
+type ResponsesOutput =
+  | { type: "message"; id?: string; role: "assistant"; content: MessageContent[] }
+  | { type: "function_call"; id: string; name: string; arguments: string; call_id: string }
+  | { type: "reasoning"; id: string; summary: Array<{ type: "summary_text"; text: string }> };
+
+interface ResponsesResponse {
+  id: string;
+  object: "response";
+  created_at: number;
+  model: string;
+  status: "completed" | "incomplete" | "failed";
+  output: ResponsesOutput[];
+  usage: {
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+  };
+}
+
+/** OpenAI Responses 错误响应：{ error: { code, message } } */
+interface ResponsesErrorResponse {
+  error: { code: string; message: string };
+}
+
+export function canonicalToResponsesResponse(res: CanonicalResponse): ResponsesResponse | ResponsesErrorResponse {
+  // 错误响应：短路返回 Responses 错误 shape
+  if (res.error) {
+    return {
+      error: {
+        code: res.error.status?.toString() ?? "upstream_error",
+        message: res.error.message,
+      },
+    };
+  }
+
+  const output: ResponsesOutput[] = [];
+
+  // 把所有 text + refusal 合并成一个 message item
+  const messageContent: MessageContent[] = [];
+  for (const b of res.content) {
+    if (b.type === "text" && b.text) {
+      messageContent.push({ type: "output_text", text: b.text });
+    } else if (b.type === "refusal") {
+      messageContent.push({ type: "refusal", refusal: b.refusal });
+    }
+  }
+  if (messageContent.length > 0) {
+    output.push({ type: "message", id: `msg_${res.id}`, role: "assistant", content: messageContent });
+  }
+
+  // tool_use → function_call
+  for (const b of res.content) {
+    if (b.type === "tool_use") {
+      output.push({
+        type: "function_call",
+        id: b.id,
+        name: b.name,
+        arguments: typeof b.input === "string" ? b.input : JSON.stringify(b.input ?? {}),
+        call_id: b.id,
+      });
+    }
+  }
+
+  // thinking → reasoning summary
+  let reasoningSeq = 0;
+  for (const b of res.content) {
+    if (b.type === "thinking" && b.thinking) {
+      output.push({
+        type: "reasoning",
+        id: `rs_${res.id}_${reasoningSeq++}`,
+        summary: [{ type: "summary_text", text: b.thinking }],
+      });
+    }
+  }
+
+  return {
+    id: res.id,
+    object: "response",
+    created_at: Math.floor(Date.now() / 1000),
+    model: res.model,
+    status: res.stopReason === "error" ? "failed" : "completed",
+    output,
+    usage: {
+      input_tokens: res.usage.inputTokens,
+      output_tokens: res.usage.outputTokens,
+      total_tokens: res.usage.inputTokens + res.usage.outputTokens,
+    },
+  };
+}
+
+// 现在不用了，但保留 reference（旧测试可能 import）
+export function _extractText(blocks: CanonicalContentBlock[]): string {
+  return blocks.filter((b): b is { type: "text"; text: string } => b.type === "text").map((b) => b.text).join("");
+}

package/src/convert/streaming/inbound/anthropic-stream.ts

@@ -0,0 +1,14 @@
+// v1 简化：Anthropic SSE 已经是 CanonicalChunk 的近亲，直接透传
+import type { CanonicalChunk } from "../../../canonical/types";
+import { parseSseStream } from "../../../server/sse";
+
+export async function* anthropicStreamToCanonical(rawStream: ReadableStream<Uint8Array>): AsyncGenerator<CanonicalChunk> {
+  for await (const ev of parseSseStream(rawStream)) {
+    try {
+      const parsed = JSON.parse(ev.data) as CanonicalChunk;
+      yield parsed;
+    } catch {
+      // 跳过
+    }
+  }
+}