cctra 0.3.0

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

@@ -0,0 +1,219 @@
+// ============================================================================
+// OpenAI Chat Completions SSE → CanonicalChunk 流式状态机
+// ---------------------------------------------------------------------------
+// 处理：
+//   - delta.role 首次出现 → message_start
+//   - delta.content 首次/累积 → content_block_start(text) + content_block_delta(text_delta)
+//   - delta.tool_calls[i] 多 chunk 拼接 → content_block_start(tool_use) + input_json_delta
+//   - finish_reason 非 null → 关掉所有打开的 block + message_delta + message_stop
+//   - [DONE] → 安全收尾（idempotent）
+// ============================================================================
+
+import type { CanonicalChunk, StopReason } from "../../../canonical/types";
+import { parseSseStream } from "../../../server/sse";
+
+interface PendingTool {
+  id: string;
+  name: string;
+  blockIndex: number;
+  emittedStart: boolean;
+}
+
+interface ChatStreamChunk {
+  id?: string;
+  model?: string;
+  choices?: Array<{
+    delta?: {
+      role?: string;
+      content?: string | null;
+      tool_calls?: Array<{
+        index: number;
+        id?: string;
+        type?: string;
+        function?: { name?: string; arguments?: string };
+      }>;
+    };
+    finish_reason?: string | null;
+  }>;
+  usage?: { prompt_tokens?: number; completion_tokens?: number };
+}
+
+export async function* chatStreamToCanonical(
+  rawStream: ReadableStream<Uint8Array>,
+): AsyncGenerator<CanonicalChunk> {
+  // ---------- 状态 ----------
+  const pendingTools = new Map<number, PendingTool>();   // key = OpenAI tool_call index
+  let nextBlockIndex = 0;
+  let textBlockIndex: number | null = null;              // 0 通常；null 表示还没开 text block
+  let messageStarted = false;
+  let messageStopped = false;
+  let upstreamModel = "";
+  let upstreamId = "";
+
+  // ---------- 主循环 ----------
+  for await (const ev of parseSseStream(rawStream)) {
+    if (ev.data === "[DONE]") {
+      if (!messageStopped) {
+        yield* closeAll();
+      }
+      continue;
+    }
+
+    let parsed: ChatStreamChunk & { error?: { message?: unknown } };
+    try {
+      parsed = JSON.parse(ev.data) as ChatStreamChunk & { error?: { message?: unknown } };
+    } catch {
+      continue;
+    }
+
+    // 流中错：上游 SSE 内嵌 {error: {message}} 时透传为 canonical error chunk
+    if (parsed.error && typeof parsed.error.message === "string") {
+      yield { type: "error", error: parsed.error.message };
+      continue;
+    }
+
+    if (parsed.id) upstreamId = parsed.id;
+    if (parsed.model) upstreamModel = parsed.model;
+
+    const choice = parsed.choices?.[0];
+    if (!choice) {
+      // 可能是 usage-only chunk
+      if (parsed.usage && messageStarted && !messageStopped) {
+        yield {
+          type: "message_delta",
+          delta: {},
+          usage: {
+            inputTokens: parsed.usage.prompt_tokens ?? 0,
+            outputTokens: parsed.usage.completion_tokens ?? 0,
+          },
+        };
+      }
+      continue;
+    }
+
+    const delta = choice.delta;
+
+    // (1) delta.role 首次 → message_start
+    if (delta?.role && !messageStarted) {
+      yield* emitMessageStart();
+    }
+
+    // (2) text 增量
+    if (typeof delta?.content === "string" && delta.content.length > 0) {
+      if (!messageStarted) yield* emitMessageStart();
+      if (textBlockIndex === null) {
+        textBlockIndex = nextBlockIndex++;
+        yield {
+          type: "content_block_start",
+          index: textBlockIndex,
+          content_block: { type: "text", text: "" },
+        };
+      }
+      yield {
+        type: "content_block_delta",
+        index: textBlockIndex,
+        delta: { type: "text_delta", text: delta.content },
+      };
+    }
+
+    // (3) tool_calls 增量
+    if (delta?.tool_calls) {
+      if (!messageStarted) yield* emitMessageStart();
+      for (const tc of delta.tool_calls) {
+        let pending = pendingTools.get(tc.index);
+        if (!pending) {
+          // 第一次见这个 index：分配 blockIndex
+          pending = {
+            id: tc.id ?? "",
+            name: tc.function?.name ?? "",
+            blockIndex: nextBlockIndex++,
+            emittedStart: false,
+          };
+          pendingTools.set(tc.index, pending);
+        } else {
+          // 后续可能补 id 或 name（少见但要兼容）
+          if (tc.id && !pending.id) pending.id = tc.id;
+          if (tc.function?.name && !pending.name) pending.name = tc.function.name;
+        }
+
+        // 当 id 已知就可以 emit start（OpenAI 通常第一条 delta 同时有 id 和 name）
+        if (!pending.emittedStart && pending.id) {
+          pending.emittedStart = true;
+          yield {
+            type: "content_block_start",
+            index: pending.blockIndex,
+            content_block: { type: "tool_use", id: pending.id, name: pending.name, input: {} },
+          };
+        }
+
+        // arguments 增量
+        const argsPartial = tc.function?.arguments;
+        if (typeof argsPartial === "string" && argsPartial.length > 0 && pending.emittedStart) {
+          yield {
+            type: "content_block_delta",
+            index: pending.blockIndex,
+            delta: { type: "input_json_delta", partial_json: argsPartial },
+          };
+        }
+      }
+    }
+
+    // (4) finish_reason → 关掉所有 block + message_delta + message_stop
+    if (choice.finish_reason) {
+      yield* closeAll(choice.finish_reason);
+    }
+  }
+
+  // 流自然结束但没收到 [DONE] / finish_reason
+  if (!messageStopped) yield* closeAll();
+
+  // ---------- helpers (内嵌 generator，共享闭包状态) ----------
+
+  function* emitMessageStart(): Generator<CanonicalChunk> {
+    if (messageStarted) return;
+    messageStarted = true;
+    yield {
+      type: "message_start",
+      message: {
+        id: upstreamId || `msg_${Date.now()}`,
+        model: upstreamModel || "unknown",
+        content: [],
+        stopReason: "end_turn",
+        usage: { inputTokens: 0, outputTokens: 0 },
+      },
+    };
+  }
+
+  function* closeAll(finishReason?: string): Generator<CanonicalChunk> {
+    if (messageStopped) return;
+    // 关 text block
+    if (textBlockIndex !== null) {
+      yield { type: "content_block_stop", index: textBlockIndex };
+      textBlockIndex = null;
+    }
+    // 关所有 pending tool_use block
+    for (const t of pendingTools.values()) {
+      if (t.emittedStart) {
+        yield { type: "content_block_stop", index: t.blockIndex };
+      }
+    }
+    pendingTools.clear();
+
+    yield {
+      type: "message_delta",
+      delta: { stop_reason: mapStopReason(finishReason) },
+    };
+    yield { type: "message_stop" };
+    messageStopped = true;
+  }
+}
+
+function mapStopReason(r: string | undefined): StopReason {
+  switch (r) {
+    case "stop": return "end_turn";
+    case "length": return "max_tokens";
+    case "tool_calls": return "tool_use";
+    case "content_filter": return "error";
+    default: return "end_turn";
+  }
+}

package/src/convert/streaming/inbound/pick.ts

@@ -0,0 +1,21 @@
+// ============================================================================
+// 按上游 apiFormat 选择 inbound stream parser
+// 关键：必须用 ready.apiFormat（plugin 真实返回的），而不是 route.apiFormat（plugin 占位）
+// ============================================================================
+import type { ApiFormat } from "../../../types";
+import type { CanonicalChunk } from "../../../canonical/types";
+import { chatStreamToCanonical } from "./chat-stream";
+import { anthropicStreamToCanonical } from "./anthropic-stream";
+import { responsesStreamToCanonical } from "./responses-stream";
+
+export type InboundStreamParser = (
+  raw: ReadableStream<Uint8Array>,
+) => AsyncGenerator<CanonicalChunk>;
+
+export function pickInboundStreamParser(apiFormat: ApiFormat): InboundStreamParser {
+  switch (apiFormat) {
+    case "anthropic-messages": return anthropicStreamToCanonical;
+    case "openai-responses":   return responsesStreamToCanonical;
+    case "openai-chat":        return chatStreamToCanonical;
+  }
+}

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

@@ -0,0 +1,276 @@
+// ============================================================================
+// OpenAI Responses SSE → CanonicalChunk 流式状态机
+// ---------------------------------------------------------------------------
+// 处理 12+ 种 response.* 事件：
+//   - response.created                              → message_start
+//   - response.output_item.added (message)          → content_block_start(text)
+//   - response.output_item.added (function_call)    → content_block_start(tool_use)
+//   - response.output_item.added (reasoning)        → content_block_start(thinking)
+//   - response.output_text.delta                    → content_block_delta(text_delta)
+//   - response.function_call_arguments.delta        → content_block_delta(input_json_delta)
+//   - response.reasoning_summary_text.delta         → content_block_delta(thinking_delta)
+//   - response.refusal.delta                        → content_block_delta(text_delta with prefix)
+//   - response.output_item.done                     → content_block_stop
+//   - response.error                                → error
+//   - response.completed                            → message_delta + message_stop
+//
+// 内置工具（web_search/code_interpreter/file_search/mcp_call/computer_use_call）
+// 在 v1 跳过：Canonical 不承载这些 block 类型。
+// ============================================================================
+
+import type { CanonicalChunk, CanonicalContentBlock, StopReason } from "../../../canonical/types";
+import { parseSseStream } from "../../../server/sse";
+
+interface ResponsesEvent {
+  type?: string;
+  output_index?: number;
+  item_id?: string;
+  delta?: string;
+  item?: {
+    id?: string;
+    type?: string;          // "message" | "function_call" | "reasoning" | "refusal" | builtins
+    name?: string;
+    arguments?: string;
+    call_id?: string;
+    role?: string;
+  };
+  response?: {
+    id?: string;
+    model?: string;
+    status?: string;
+    incomplete_details?: { reason?: string };
+    usage?: { input_tokens?: number; output_tokens?: number };
+  };
+  error?: { message?: string; code?: string };
+}
+
+export async function* responsesStreamToCanonical(
+  rawStream: ReadableStream<Uint8Array>,
+): AsyncGenerator<CanonicalChunk> {
+  // 状态：output_index → Canonical block_index（直接 1:1 用 output_index）
+  // 同时记住每个 output_index 对应的 block kind（关掉时无需查）
+  const openBlocks = new Set<number>();
+  let messageStarted = false;
+  let messageStopped = false;
+  let upstreamModel = "";
+  let upstreamId = "";
+
+  for await (const ev of parseSseStream(rawStream)) {
+    if (ev.data === "[DONE]") {
+      if (!messageStopped) yield* finalize("end_turn");
+      continue;
+    }
+
+    let parsed: ResponsesEvent;
+    try {
+      parsed = JSON.parse(ev.data) as ResponsesEvent;
+    } catch {
+      continue;
+    }
+
+    switch (parsed.type) {
+      case "response.created": {
+        if (parsed.response?.id) upstreamId = parsed.response.id;
+        if (parsed.response?.model) upstreamModel = parsed.response.model;
+        if (!messageStarted) {
+          messageStarted = true;
+          yield {
+            type: "message_start",
+            message: {
+              id: upstreamId || `resp_${Date.now()}`,
+              model: upstreamModel || "unknown",
+              content: [],
+              stopReason: "end_turn",
+              usage: { inputTokens: 0, outputTokens: 0 },
+            },
+          };
+        }
+        break;
+      }
+
+      case "response.in_progress":
+        // 状态信号，无需转发
+        break;
+
+      case "response.output_item.added": {
+        const idx = parsed.output_index;
+        if (idx === undefined || openBlocks.has(idx)) break;
+        const block = itemToBlock(parsed.item);
+        if (!block) break;
+        openBlocks.add(idx);
+        yield { type: "content_block_start", index: idx, content_block: block };
+        break;
+      }
+
+      case "response.output_text.delta": {
+        const idx = parsed.output_index;
+        if (idx === undefined || typeof parsed.delta !== "string") break;
+        yield {
+          type: "content_block_delta",
+          index: idx,
+          delta: { type: "text_delta", text: parsed.delta },
+        };
+        break;
+      }
+
+      case "response.function_call_arguments.delta": {
+        const idx = parsed.output_index;
+        if (idx === undefined || typeof parsed.delta !== "string") break;
+        yield {
+          type: "content_block_delta",
+          index: idx,
+          delta: { type: "input_json_delta", partial_json: parsed.delta },
+        };
+        break;
+      }
+
+      case "response.function_call_arguments.done": {
+        // 单独的 done 事件不发；统一由 output_item.done 关 block
+        break;
+      }
+
+      case "response.reasoning_summary_part.added": {
+        const idx = parsed.output_index;
+        if (idx === undefined || openBlocks.has(idx)) break;
+        openBlocks.add(idx);
+        yield {
+          type: "content_block_start",
+          index: idx,
+          content_block: { type: "thinking", thinking: "" },
+        };
+        break;
+      }
+
+      case "response.reasoning_summary_text.delta":
+      case "response.reasoning.delta": {
+        const idx = parsed.output_index;
+        if (idx === undefined || typeof parsed.delta !== "string") break;
+        yield {
+          type: "content_block_delta",
+          index: idx,
+          delta: { type: "thinking_delta", thinking: parsed.delta },
+        };
+        break;
+      }
+
+      case "response.reasoning_summary_part.done": {
+        const idx = parsed.output_index;
+        if (idx === undefined) break;
+        if (openBlocks.has(idx)) {
+          openBlocks.delete(idx);
+          yield { type: "content_block_stop", index: idx };
+        }
+        break;
+      }
+
+      case "response.refusal.delta": {
+        // ContentBlockDelta 联合没有 refusal_delta；用 text_delta 加前缀承载
+        const idx = parsed.output_index;
+        if (idx === undefined || typeof parsed.delta !== "string") break;
+        if (!openBlocks.has(idx)) {
+          openBlocks.add(idx);
+          yield {
+            type: "content_block_start",
+            index: idx,
+            content_block: { type: "text", text: "" },
+          };
+        }
+        yield {
+          type: "content_block_delta",
+          index: idx,
+          delta: { type: "text_delta", text: `[refusal] ${parsed.delta}` },
+        };
+        break;
+      }
+
+      case "response.output_item.done": {
+        const idx = parsed.output_index;
+        if (idx === undefined) break;
+        if (openBlocks.has(idx)) {
+          openBlocks.delete(idx);
+          yield { type: "content_block_stop", index: idx };
+        }
+        break;
+      }
+
+      case "response.error": {
+        yield { type: "error", error: parsed.error?.message ?? "upstream_error" };
+        break;
+      }
+
+      case "response.failed":
+      case "response.incomplete": {
+        if (!messageStopped) {
+          yield* finalize(parsed.response?.incomplete_details?.reason === "max_output_tokens" ? "max_tokens" : "error");
+        }
+        break;
+      }
+
+      case "response.completed": {
+        if (!messageStopped) {
+          const usage = parsed.response?.usage;
+          // 一次性把 usage 一起带在 message_delta 里
+          if (usage) {
+            yield* finalizeWithUsage("end_turn", usage.input_tokens ?? 0, usage.output_tokens ?? 0);
+          } else {
+            yield* finalize("end_turn");
+          }
+        }
+        break;
+      }
+
+      default:
+        // 内置工具事件（response.web_search_call.* / code_interpreter.* / ...）
+        // v1 跳过：Canonical 不承载
+        break;
+    }
+  }
+
+  if (!messageStopped) yield* finalize("end_turn");
+
+  // ---------- helpers ----------
+
+  function itemToBlock(item: ResponsesEvent["item"]): CanonicalContentBlock | null {
+    if (!item) return null;
+    switch (item.type) {
+      case "message":
+        return { type: "text", text: "" };
+      case "function_call":
+        return { type: "tool_use", id: item.call_id ?? item.id ?? "", name: item.name ?? "", input: {} };
+      case "reasoning":
+        return { type: "thinking", thinking: "" };
+      default:
+        // 内置工具 / 未知类型：跳
+        return null;
+    }
+  }
+
+  function* finalize(stopReason: StopReason): Generator<CanonicalChunk> {
+    // 关掉所有还开着的 block
+    for (const idx of openBlocks) {
+      yield { type: "content_block_stop", index: idx };
+    }
+    openBlocks.clear();
+    yield { type: "message_delta", delta: { stop_reason: stopReason } };
+    yield { type: "message_stop" };
+    messageStopped = true;
+  }
+
+  function* finalizeWithUsage(
+    stopReason: StopReason,
+    inputTokens: number,
+    outputTokens: number,
+  ): Generator<CanonicalChunk> {
+    for (const idx of openBlocks) {
+      yield { type: "content_block_stop", index: idx };
+    }
+    openBlocks.clear();
+    yield {
+      type: "message_delta",
+      delta: { stop_reason: stopReason },
+      usage: { inputTokens, outputTokens },
+    };
+    yield { type: "message_stop" };
+    messageStopped = true;
+  }
+}

package/src/convert/streaming/outbound/format-anthropic.ts

@@ -0,0 +1,19 @@
+// ============================================================================
+// CanonicalChunk → Anthropic Messages SSE 流式输出格式化
+// ---------------------------------------------------------------------------
+// CanonicalChunk 形状几乎对齐 Anthropic SSE，所以基本直接 JSON.stringify 透传。
+// 唯一精细化：发严格的双行格式 `event: <name>\ndata: <json>\n\n`（Anthropic 客户端通常按 event 名分类）
+// ============================================================================
+
+import type { CanonicalChunk } from "../../../canonical/types";
+
+export class AnthropicStreamFormatter {
+  // 流中错已发 error event：抑制 message_stop（避免"错 + 完成"矛盾信号）
+  private _streamEndedWithError = false;
+
+  format(chunk: CanonicalChunk): string[] {
+    if (chunk.type === "error") this._streamEndedWithError = true;
+    if (chunk.type === "message_stop" && this._streamEndedWithError) return [];
+    return [`event: ${chunk.type}\ndata: ${JSON.stringify(chunk)}\n\n`];
+  }
+}

package/src/convert/streaming/outbound/format-chat.ts

@@ -0,0 +1,133 @@
+// ============================================================================
+// CanonicalChunk → OpenAI Chat Completions SSE 流式输出格式化
+// ---------------------------------------------------------------------------
+// 关键状态：
+//   - 每个 tool_use Canonical block 在 OpenAI Chat 里对应一个 tool_calls[i] 槽位
+//   - 第一次见到 tool_use 时必须发完整 skeleton（id+name+type+空 arguments）
+//   - 后续 arguments 增量只发 {tool_calls:[{index,function:{arguments:partial}}]}
+//   - thinking/signature delta 在 OpenAI Chat 协议无对应 → 静默丢弃
+// ============================================================================
+
+import type { CanonicalChunk, StopReason } from "../../../canonical/types";
+
+interface ToolSlot {
+  toolIndex: number;
+  id: string;
+  name: string;
+}
+
+export class ChatStreamFormatter {
+  private id = `chatcmpl-${Date.now()}`;
+  private created = Math.floor(Date.now() / 1000);
+  private model = "";
+  private nextToolIndex = 0;
+  // Canonical block_index → OpenAI tool_calls 槽位
+  private blockToToolSlot = new Map<number, ToolSlot>();
+  // 流中错已发 error event：抑制 [DONE]（避免"错 + 完成"矛盾信号）
+  private _streamEndedWithError = false;
+
+  format(chunk: CanonicalChunk): string[] {
+    switch (chunk.type) {
+      case "message_start": {
+        if (chunk.message.id) this.id = chunk.message.id;
+        if (chunk.message.model) this.model = chunk.message.model;
+        return [];
+      }
+
+      case "content_block_start": {
+        if (chunk.content_block.type === "tool_use") {
+          const slot: ToolSlot = {
+            toolIndex: this.nextToolIndex++,
+            id: chunk.content_block.id,
+            name: chunk.content_block.name,
+          };
+          this.blockToToolSlot.set(chunk.index, slot);
+          return [this.makeChunk({
+            tool_calls: [{
+              index: slot.toolIndex,
+              id: slot.id,
+              type: "function",
+              function: { name: slot.name, arguments: "" },
+            }],
+          })];
+        }
+        // text / thinking block_start 不发（OpenAI Chat 不预声明 text block）
+        return [];
+      }
+
+      case "content_block_delta": {
+        if (chunk.delta.type === "text_delta") {
+          return [this.makeChunk({ content: chunk.delta.text })];
+        }
+        if (chunk.delta.type === "input_json_delta") {
+          const slot = this.blockToToolSlot.get(chunk.index);
+          if (!slot) return [];
+          return [this.makeChunk({
+            tool_calls: [{
+              index: slot.toolIndex,
+              function: { arguments: chunk.delta.partial_json },
+            }],
+          })];
+        }
+        // thinking_delta / signature_delta → OpenAI Chat 无对应，丢
+        return [];
+      }
+
+      case "content_block_stop":
+        // OpenAI Chat 不显式 stop content block
+        return [];
+
+      case "message_delta": {
+        const stop = chunk.delta.stop_reason;
+        if (!stop) return [];
+        return [this.makeFinishChunk(stop)];
+      }
+
+      case "message_stop":
+        // 流中错时抑制 [DONE]（cc-switch 二元化约束）
+        if (this._streamEndedWithError) return [];
+        return ["data: [DONE]\n\n"];
+
+      case "ping":
+        return [];
+
+      case "error": {
+        // 流中错：发 error SSE event + 设抑制标志
+        this._streamEndedWithError = true;
+        return [`data: ${JSON.stringify({
+          error: { message: chunk.error, type: "upstream_error" },
+        })}\n\n`];
+      }
+    }
+  }
+
+  private makeChunk(delta: Record<string, unknown>): string {
+    return `data: ${JSON.stringify({
+      id: this.id,
+      object: "chat.completion.chunk",
+      created: this.created,
+      model: this.model,
+      choices: [{ index: 0, delta, finish_reason: null }],
+    })}\n\n`;
+  }
+
+  private makeFinishChunk(stop: StopReason): string {
+    return `data: ${JSON.stringify({
+      id: this.id,
+      object: "chat.completion.chunk",
+      created: this.created,
+      model: this.model,
+      choices: [{ index: 0, delta: {}, finish_reason: mapStopReason(stop) }],
+    })}\n\n`;
+  }
+}
+
+function mapStopReason(r: StopReason): string {
+  switch (r) {
+    case "end_turn": return "stop";
+    case "max_tokens": return "length";
+    case "stop_sequence": return "stop";
+    case "tool_use": return "tool_calls";
+    case "error": return "content_filter";
+  }
+}