aigetwey 1.0.1

package/src/stream/anthropic-stream.ts

@@ -0,0 +1,310 @@
+/**
+ * Anthropic streaming <-> canonical (OpenAI) chunks. The hard part.
+ *
+ * Anthropic streams a structured event sequence:
+ *   message_start
+ *   content_block_start / content_block_delta / content_block_stop  (per block)
+ *   message_delta (carries stop_reason + output usage)
+ *   message_stop
+ *
+ * OpenAI streams flat `choices[].delta` chunks. Translating requires a state
+ * machine: tracking the message id, which block is open, and the mapping
+ * between OpenAI tool-call indices and Anthropic block indices.
+ */
+import type { CanonicalChunk, CanonicalDeltaToolCall, ChunkFinishReason } from "./chunk.js";
+import type { SSEEvent } from "./sse.js";
+
+// ============================================================
+// Anthropic SSE  ->  canonical chunks   (provider=anthropic, client=openai)
+// ============================================================
+
+interface AnthStreamState {
+  id: string;
+  model: string;
+  /** anthropic block index -> openai tool-call index (only tool_use blocks) */
+  toolIndexByBlock: Map<number, number>;
+  nextToolIndex: number;
+  promptTokens: number;
+  cachedTokens?: number;
+  cacheCreationTokens?: number;
+}
+
+export async function* streamToCanonical(events: AsyncIterable<SSEEvent>): AsyncGenerator<CanonicalChunk> {
+  const state: AnthStreamState = {
+    id: "",
+    model: "",
+    toolIndexByBlock: new Map(),
+    nextToolIndex: 0,
+    promptTokens: 0,
+  };
+
+  for await (const ev of events) {
+    const data = ev.data.trim();
+    if (!data || data === "[DONE]") continue;
+    let msg: Record<string, unknown>;
+    try {
+      msg = JSON.parse(data) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+
+    const type = ev.event ?? (msg.type as string | undefined);
+
+    switch (type) {
+      case "message_start": {
+        const message = msg.message as
+          | { id?: string; model?: string; usage?: Record<string, number> }
+          | undefined;
+        state.id = message?.id ?? "";
+        state.model = message?.model ?? "";
+        const u = message?.usage;
+        if (u) {
+          state.promptTokens = u.input_tokens ?? 0;
+          state.cachedTokens = u.cache_read_input_tokens;
+          state.cacheCreationTokens = u.cache_creation_input_tokens;
+        }
+        const startChunk = baseChunk(state, { role: "assistant", content: "" }, null);
+        startChunk.usage = {
+          prompt_tokens: state.promptTokens,
+          cached_tokens: state.cachedTokens,
+          cache_creation_tokens: state.cacheCreationTokens,
+        };
+        yield startChunk;
+        break;
+      }
+
+      case "content_block_start": {
+        const block = msg.content_block as { type?: string; id?: string; name?: string } | undefined;
+        const index = msg.index as number;
+        if (block?.type === "tool_use") {
+          const toolIndex = state.nextToolIndex++;
+          state.toolIndexByBlock.set(index, toolIndex);
+          const tc: CanonicalDeltaToolCall = {
+            index: toolIndex,
+            id: block.id,
+            type: "function",
+            function: { name: block.name, arguments: "" },
+          };
+          yield baseChunk(state, { tool_calls: [tc] }, null);
+        }
+        // text/thinking block_start carries no text; deltas follow
+        break;
+      }
+
+      case "content_block_delta": {
+        const delta = msg.delta as
+          | { type?: string; text?: string; thinking?: string; partial_json?: string }
+          | undefined;
+        const index = msg.index as number;
+        if (delta?.type === "text_delta") {
+          yield baseChunk(state, { content: delta.text ?? "" }, null);
+        } else if (delta?.type === "thinking_delta") {
+          yield baseChunk(state, { reasoning: delta.thinking ?? "" }, null);
+        } else if (delta?.type === "input_json_delta") {
+          const toolIndex = state.toolIndexByBlock.get(index);
+          if (toolIndex !== undefined) {
+            const tc: CanonicalDeltaToolCall = {
+              index: toolIndex,
+              function: { arguments: delta.partial_json ?? "" },
+            };
+            yield baseChunk(state, { tool_calls: [tc] }, null);
+          }
+        }
+        break;
+      }
+
+      case "message_delta": {
+        const delta = msg.delta as { stop_reason?: string | null } | undefined;
+        const usage = msg.usage as { output_tokens?: number } | undefined;
+        const finish = mapStopReason(delta?.stop_reason);
+        const chunk = baseChunk(state, {}, finish);
+        chunk.usage = {
+          prompt_tokens: state.promptTokens,
+          completion_tokens: usage?.output_tokens ?? 0,
+          cached_tokens: state.cachedTokens,
+          cache_creation_tokens: state.cacheCreationTokens,
+        };
+        yield chunk;
+        break;
+      }
+
+      // content_block_stop, message_stop, ping -> no canonical output
+      default:
+        break;
+    }
+  }
+}
+
+function baseChunk(
+  state: AnthStreamState,
+  delta: CanonicalChunk["choices"][0]["delta"],
+  finish: ChunkFinishReason,
+): CanonicalChunk {
+  return {
+    id: state.id || "chatcmpl-stream",
+    model: state.model,
+    created: 0,
+    choices: [{ index: 0, delta, finish_reason: finish }],
+  };
+}
+
+function mapStopReason(reason: string | null | undefined): ChunkFinishReason {
+  switch (reason) {
+    case "end_turn":
+    case "stop_sequence":
+      return "stop";
+    case "max_tokens":
+      return "length";
+    case "tool_use":
+      return "tool_calls";
+    default:
+      return null;
+  }
+}
+
+// ============================================================
+// canonical chunks  ->  Anthropic SSE   (provider=openai, client=anthropic)
+// ============================================================
+
+interface BuildState {
+  id: string;
+  model: string;
+  started: boolean;
+  /** the currently-open anthropic block index, or -1 if none */
+  openBlock: number;
+  /** what kind of block is open */
+  openKind: "text" | "thinking" | "tool" | null;
+  nextBlockIndex: number;
+  /** openai tool index -> anthropic block index */
+  toolBlockByIndex: Map<number, number>;
+  promptTokens: number;
+  completionTokens: number;
+  finish: string | null;
+}
+
+function ev(event: string, data: Record<string, unknown>): SSEEvent {
+  return { event, data: JSON.stringify({ type: event, ...data }) };
+}
+
+export async function* streamFromCanonical(chunks: AsyncIterable<CanonicalChunk>): AsyncGenerator<SSEEvent> {
+  const s: BuildState = {
+    id: "",
+    model: "",
+    started: false,
+    openBlock: -1,
+    openKind: null,
+    nextBlockIndex: 0,
+    toolBlockByIndex: new Map(),
+    promptTokens: 0,
+    completionTokens: 0,
+    finish: null,
+  };
+
+  function* closeOpen(): Generator<SSEEvent> {
+    if (s.openBlock !== -1) {
+      yield ev("content_block_stop", { index: s.openBlock });
+      s.openBlock = -1;
+      s.openKind = null;
+    }
+  }
+
+  for await (const chunk of chunks) {
+    if (!s.started) {
+      s.id = chunk.id || "msg_stream";
+      s.model = chunk.model || "";
+      s.promptTokens = chunk.usage?.prompt_tokens ?? 0;
+      yield ev("message_start", {
+        message: {
+          id: s.id,
+          type: "message",
+          role: "assistant",
+          model: s.model,
+          content: [],
+          stop_reason: null,
+          stop_sequence: null,
+          usage: { input_tokens: s.promptTokens, output_tokens: 0 },
+        },
+      });
+      s.started = true;
+    }
+
+    const choice = chunk.choices?.[0];
+    if (!choice) continue;
+    const delta = choice.delta ?? {};
+
+    // reasoning -> thinking block
+    if (delta.reasoning) {
+      if (s.openKind !== "thinking") {
+        yield* closeOpen();
+        s.openBlock = s.nextBlockIndex++;
+        s.openKind = "thinking";
+        yield ev("content_block_start", {
+          index: s.openBlock,
+          content_block: { type: "thinking", thinking: "" },
+        });
+      }
+      yield ev("content_block_delta", {
+        index: s.openBlock,
+        delta: { type: "thinking_delta", thinking: delta.reasoning },
+      });
+    }
+
+    // text -> text block
+    if (typeof delta.content === "string" && delta.content.length > 0) {
+      if (s.openKind !== "text") {
+        yield* closeOpen();
+        s.openBlock = s.nextBlockIndex++;
+        s.openKind = "text";
+        yield ev("content_block_start", { index: s.openBlock, content_block: { type: "text", text: "" } });
+      }
+      yield ev("content_block_delta", {
+        index: s.openBlock,
+        delta: { type: "text_delta", text: delta.content },
+      });
+    }
+
+    // tool calls -> tool_use blocks
+    for (const tc of delta.tool_calls ?? []) {
+      let block = s.toolBlockByIndex.get(tc.index);
+      if (block === undefined) {
+        yield* closeOpen();
+        block = s.nextBlockIndex++;
+        s.toolBlockByIndex.set(tc.index, block);
+        s.openBlock = block;
+        s.openKind = "tool";
+        yield ev("content_block_start", {
+          index: block,
+          content_block: { type: "tool_use", id: tc.id ?? `toolu_${block}`, name: tc.function?.name ?? "", input: {} },
+        });
+      }
+      const frag = tc.function?.arguments;
+      if (frag) {
+        yield ev("content_block_delta", { index: block, delta: { type: "input_json_delta", partial_json: frag } });
+      }
+    }
+
+    if (choice.finish_reason) s.finish = choice.finish_reason;
+    if (chunk.usage?.completion_tokens) s.completionTokens = chunk.usage.completion_tokens;
+  }
+
+  // finalize
+  yield* closeOpen();
+  yield ev("message_delta", {
+    delta: { stop_reason: reverseStop(s.finish), stop_sequence: null },
+    usage: { output_tokens: s.completionTokens },
+  });
+  yield ev("message_stop", {});
+}
+
+function reverseStop(reason: string | null): string | null {
+  switch (reason) {
+    case "stop":
+      return "end_turn";
+    case "length":
+      return "max_tokens";
+    case "tool_calls":
+      return "tool_use";
+    default:
+      return null;
+  }
+}

package/src/stream/chunk.ts

@@ -0,0 +1,46 @@
+/**
+ * Canonical streaming unit = OpenAI Chat Completion *chunk*.
+ * Provider SSE is translated INTO a stream of these; client SSE is translated
+ * OUT of them. Mirrors the non-streaming canonical shape.
+ */
+
+export interface CanonicalDeltaToolCall {
+  index: number;
+  id?: string;
+  type?: "function";
+  function?: {
+    name?: string;
+    /** partial JSON fragment of arguments */
+    arguments?: string;
+  };
+}
+
+export interface CanonicalChunkDelta {
+  role?: "assistant";
+  content?: string | null;
+  /** reasoning/thinking text, normalized across providers */
+  reasoning?: string;
+  tool_calls?: CanonicalDeltaToolCall[];
+}
+
+export interface CanonicalChunkUsage {
+  prompt_tokens?: number;
+  completion_tokens?: number;
+  cached_tokens?: number;
+  cache_creation_tokens?: number;
+  reasoning_tokens?: number;
+}
+
+export type ChunkFinishReason = "stop" | "length" | "tool_calls" | "content_filter" | null;
+
+export interface CanonicalChunk {
+  id: string;
+  model: string;
+  created: number;
+  choices: Array<{
+    index: number;
+    delta: CanonicalChunkDelta;
+    finish_reason: ChunkFinishReason;
+  }>;
+  usage?: CanonicalChunkUsage;
+}

package/src/stream/gemini-stream.ts

@@ -0,0 +1,158 @@
+/**
+ * Gemini streaming <-> canonical (OpenAI) chunks.
+ *
+ * Gemini's SSE (alt=sse) emits `data: {...}` frames, each a partial
+ * GenerateContentResponse: candidates[0].content.parts carry text deltas,
+ * functionCall parts arrive whole (not fragmented), and the final frame carries
+ * finishReason + usageMetadata.
+ */
+import type { CanonicalChunk, CanonicalDeltaToolCall, ChunkFinishReason } from "./chunk.js";
+import type { SSEEvent } from "./sse.js";
+
+interface GeminiPart {
+  text?: string;
+  functionCall?: { name: string; args: Record<string, unknown> };
+}
+
+function mapFinish(reason: string | undefined): ChunkFinishReason {
+  switch (reason) {
+    case "STOP":
+      return "stop";
+    case "MAX_TOKENS":
+      return "length";
+    case "SAFETY":
+    case "RECITATION":
+      return "content_filter";
+    default:
+      return null;
+  }
+}
+
+// ============================================================
+// Gemini SSE -> canonical chunks   (provider=gemini)
+// ============================================================
+
+export async function* streamToCanonical(events: AsyncIterable<SSEEvent>): AsyncGenerator<CanonicalChunk> {
+  let toolIndex = 0;
+  let started = false;
+
+  for await (const ev of events) {
+    const data = ev.data.trim();
+    if (!data || data === "[DONE]") continue;
+    let msg: Record<string, unknown>;
+    try {
+      msg = JSON.parse(data) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+
+    const cand = (msg.candidates as Array<{ content?: { parts?: GeminiPart[] }; finishReason?: string }>)?.[0];
+    const model = (msg.modelVersion as string | undefined) ?? "";
+    const base = (delta: CanonicalChunk["choices"][0]["delta"], finish: ChunkFinishReason): CanonicalChunk => ({
+      id: "gemini-stream",
+      model,
+      created: 0,
+      choices: [{ index: 0, delta, finish_reason: finish }],
+    });
+
+    if (!started) {
+      started = true;
+      yield base({ role: "assistant", content: "" }, null);
+    }
+
+    for (const p of cand?.content?.parts ?? []) {
+      if (typeof p.text === "string" && p.text.length > 0) {
+        yield base({ content: p.text }, null);
+      } else if (p.functionCall) {
+        const tc: CanonicalDeltaToolCall = {
+          index: toolIndex,
+          id: `call_${p.functionCall.name}_${toolIndex}`,
+          type: "function",
+          function: { name: p.functionCall.name, arguments: JSON.stringify(p.functionCall.args ?? {}) },
+        };
+        toolIndex++;
+        yield base({ tool_calls: [tc] }, null);
+      }
+    }
+
+    const usageMetadata = msg.usageMetadata as
+      | { promptTokenCount?: number; candidatesTokenCount?: number; cachedContentTokenCount?: number }
+      | undefined;
+    if (cand?.finishReason || usageMetadata) {
+      const chunk = base({}, mapFinish(cand?.finishReason));
+      if (usageMetadata) {
+        chunk.usage = {
+          prompt_tokens: usageMetadata.promptTokenCount ?? 0,
+          completion_tokens: usageMetadata.candidatesTokenCount ?? 0,
+          cached_tokens: usageMetadata.cachedContentTokenCount,
+        };
+      }
+      yield chunk;
+    }
+  }
+}
+
+// ============================================================
+// canonical chunks -> Gemini SSE   (client=gemini)
+// ============================================================
+
+export async function* streamFromCanonical(chunks: AsyncIterable<CanonicalChunk>): AsyncGenerator<SSEEvent> {
+  let promptTokens = 0;
+  let completionTokens = 0;
+  let finish: string | null = null;
+
+  for await (const chunk of chunks) {
+    const choice = chunk.choices?.[0];
+    if (!choice) continue;
+    const delta = choice.delta ?? {};
+    const parts: GeminiPart[] = [];
+
+    if (typeof delta.content === "string" && delta.content.length > 0) {
+      parts.push({ text: delta.content });
+    }
+    for (const tc of delta.tool_calls ?? []) {
+      if (tc.function?.name) {
+        let args: Record<string, unknown> = {};
+        try {
+          args = tc.function.arguments ? JSON.parse(tc.function.arguments) : {};
+        } catch {
+          args = {};
+        }
+        parts.push({ functionCall: { name: tc.function.name, args } });
+      }
+    }
+
+    if (chunk.usage?.prompt_tokens) promptTokens = chunk.usage.prompt_tokens;
+    if (chunk.usage?.completion_tokens) completionTokens = chunk.usage.completion_tokens;
+    if (choice.finish_reason) finish = reverseFinish(choice.finish_reason);
+
+    // emit a frame whenever there's content; the terminal frame also carries
+    // finishReason + usage.
+    if (parts.length > 0 || choice.finish_reason) {
+      const payload: Record<string, unknown> = {
+        candidates: [
+          { content: { role: "model", parts }, ...(choice.finish_reason ? { finishReason: finish } : {}), index: 0 },
+        ],
+      };
+      if (choice.finish_reason) {
+        payload.usageMetadata = {
+          promptTokenCount: promptTokens,
+          candidatesTokenCount: completionTokens,
+          totalTokenCount: promptTokens + completionTokens,
+        };
+      }
+      yield { data: JSON.stringify(payload) };
+    }
+  }
+}
+
+function reverseFinish(reason: string): string {
+  switch (reason) {
+    case "length":
+      return "MAX_TOKENS";
+    case "content_filter":
+      return "SAFETY";
+    default:
+      return "STOP";
+  }
+}

package/src/stream/index.ts

@@ -0,0 +1,23 @@
+import type { CanonicalChunk } from "./chunk.js";
+import type { SSEEvent } from "./sse.js";
+import type { WireFormat } from "../core/canonical.js";
+import * as openaiStream from "./openai-stream.js";
+import * as anthropicStream from "./anthropic-stream.js";
+import * as geminiStream from "./gemini-stream.js";
+
+export interface StreamAdapter {
+  /** provider SSE events -> canonical chunks */
+  streamToCanonical(events: AsyncIterable<SSEEvent>): AsyncGenerator<CanonicalChunk>;
+  /** canonical chunks -> client SSE events */
+  streamFromCanonical(chunks: AsyncIterable<CanonicalChunk>): AsyncGenerator<SSEEvent>;
+}
+
+const STREAM_ADAPTERS: Record<WireFormat, StreamAdapter> = {
+  openai: openaiStream,
+  anthropic: anthropicStream,
+  gemini: geminiStream,
+};
+
+export function streamAdapterFor(format: WireFormat): StreamAdapter {
+  return STREAM_ADAPTERS[format];
+}

package/src/stream/openai-stream.ts

@@ -0,0 +1,41 @@
+/**
+ * OpenAI streaming <-> canonical chunks.
+ * The canonical chunk IS the OpenAI chunk shape, so these are light passes:
+ *  - streamToCanonical:   parse provider `data: {...}` frames into chunks
+ *  - streamFromCanonical: serialize chunks back to `data: {...}` + `[DONE]`
+ */
+import type { CanonicalChunk } from "./chunk.js";
+import type { SSEEvent } from "./sse.js";
+
+export async function* streamToCanonical(events: AsyncIterable<SSEEvent>): AsyncGenerator<CanonicalChunk> {
+  for await (const ev of events) {
+    const data = ev.data.trim();
+    if (!data || data === "[DONE]") continue;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(data);
+    } catch {
+      continue;
+    }
+    yield normalize(parsed as CanonicalChunk);
+  }
+}
+
+/** Lift vendor reasoning fields into the canonical `delta.reasoning`. */
+function normalize(chunk: CanonicalChunk): CanonicalChunk {
+  for (const choice of chunk.choices ?? []) {
+    const d = choice.delta as Record<string, unknown> & { reasoning?: string };
+    if (d.reasoning === undefined) {
+      const vendor = (d["reasoning_content"] as string | undefined) ?? (d["reasoning"] as string | undefined);
+      if (vendor) d.reasoning = vendor;
+    }
+  }
+  return chunk;
+}
+
+export async function* streamFromCanonical(chunks: AsyncIterable<CanonicalChunk>): AsyncGenerator<SSEEvent> {
+  for await (const chunk of chunks) {
+    yield { data: JSON.stringify(chunk) };
+  }
+  yield { data: "[DONE]" };
+}

package/src/stream/sse.ts

@@ -0,0 +1,72 @@
+/**
+ * Minimal SSE (Server-Sent Events) parsing & serialization.
+ *
+ * Providers stream `data: {...}\n\n` frames (Anthropic also sets `event: <type>`).
+ * Parse a byte stream into events, let a translator transform them, re-serialize.
+ * Parsing is incremental: provider chunks may split mid-frame.
+ */
+
+export interface SSEEvent {
+  /** the `event:` field, if present (Anthropic uses it; OpenAI does not) */
+  event?: string;
+  /** the `data:` payload, raw string (may be `[DONE]`) */
+  data: string;
+}
+
+/** Parse a (possibly chunked) byte stream into SSE events. */
+export async function* parseSSE(stream: AsyncIterable<Uint8Array>): AsyncGenerator<SSEEvent> {
+  const decoder = new TextDecoder();
+  let buf = "";
+
+  for await (const chunk of stream) {
+    buf += decoder.decode(chunk, { stream: true });
+
+    let sep: number;
+    // frames are separated by a blank line (\n\n)
+    while ((sep = buf.indexOf("\n\n")) !== -1) {
+      const frame = buf.slice(0, sep);
+      buf = buf.slice(sep + 2);
+      const ev = parseFrame(frame);
+      if (ev) yield ev;
+    }
+  }
+
+  // flush a trailing frame that lacked the terminator
+  const tail = buf.trim();
+  if (tail) {
+    const ev = parseFrame(tail);
+    if (ev) yield ev;
+  }
+}
+
+function parseFrame(frame: string): SSEEvent | null {
+  let event: string | undefined;
+  const dataLines: string[] = [];
+
+  for (const rawLine of frame.split("\n")) {
+    const line = rawLine.replace(/\r$/, "");
+    if (!line || line.startsWith(":")) continue; // comment / empty
+    const colon = line.indexOf(":");
+    const field = colon === -1 ? line : line.slice(0, colon);
+    let value = colon === -1 ? "" : line.slice(colon + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+
+    if (field === "event") event = value;
+    else if (field === "data") dataLines.push(value);
+  }
+
+  if (dataLines.length === 0 && event === undefined) return null;
+  return { event, data: dataLines.join("\n") };
+}
+
+/** Serialize an event to an SSE frame string. */
+export function serializeSSE(ev: SSEEvent): string {
+  let out = "";
+  if (ev.event) out += `event: ${ev.event}\n`;
+  out += `data: ${ev.data}\n\n`;
+  return out;
+}
+
+export function encodeSSE(ev: SSEEvent): Uint8Array {
+  return new TextEncoder().encode(serializeSSE(ev));
+}