subrouter-cli 0.0.0-stage → 0.1.0

package/scripts/sse-harness.ts

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+// Live SSE verification for the subrouter gateway. The router's stream shapes are not
+// documented, so run this before/while building the adapters, and record fixtures with
+// --save for the offline test suite.
+//
+//   node scripts/sse-harness.ts --model deepseek/deepseek-v4-pro --dialect openai
+//   node scripts/sse-harness.ts --model anthropic/claude-sonnet-5 --dialect anthropic --tools --save test/fixtures/anthropic-tools.sse
+//
+// Run from the repo root. Needs SUBROUTER_API_KEY in the environment (or the config file).
+
+import fs from 'node:fs';
+import { RouterClient, RouterError, dialectFor, drainBody } from '../src/client.ts';
+import { resolveConfig } from '../src/config.ts';
+import type { Dialect } from '../src/types.ts';
+
+const ECHO_TOOL_OPENAI = {
+  type: 'function',
+  function: {
+    name: 'echo',
+    description: 'Echo back the JSON object you are given.',
+    parameters: {
+      type: 'object',
+      properties: { value: { type: 'object', description: 'any JSON object to echo' } },
+      required: ['value'],
+    },
+  },
+};
+
+const ECHO_TOOL_ANTHROPIC = {
+  name: 'echo',
+  description: 'Echo back the JSON object you are given.',
+  input_schema: {
+    type: 'object',
+    properties: { value: { type: 'object', description: 'any JSON object to echo' } },
+    required: ['value'],
+  },
+};
+
+interface HarnessArgs {
+  model: string;
+  dialect: Dialect; // resolved: openai or anthropic
+  withTools: boolean;
+  savePath?: string;
+  prompt: string;
+}
+
+function parseArgs(argv: string[]): HarnessArgs | null {
+  let model = '';
+  let dialectChoice: string | null = null;
+  let withTools = false;
+  let savePath: string | undefined;
+  let prompt: string | undefined;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--model' && i + 1 < argv.length) model = argv[++i];
+    else if (arg === '--dialect' && i + 1 < argv.length) dialectChoice = argv[++i];
+    else if (arg === '--tools') withTools = true;
+    else if (arg === '--save' && i + 1 < argv.length) savePath = argv[++i];
+    else if (arg === '--prompt' && i + 1 < argv.length) prompt = argv[++i];
+    else if (arg === '--help' || arg === '-h') {
+      console.log(
+        'Usage: node scripts/sse-harness.ts --model <id> [--dialect openai|anthropic|auto] [--tools] [--save test/fixtures/name.sse] [--prompt "..."]',
+      );
+      return null;
+    } else {
+      console.error(`Unknown argument: ${arg}`);
+      return null;
+    }
+  }
+  if (!model) {
+    console.error('--model is required.');
+    return null;
+  }
+  if (dialectChoice !== null && dialectChoice !== 'openai' && dialectChoice !== 'anthropic' && dialectChoice !== 'auto') {
+    console.error('--dialect must be openai, anthropic, or auto.');
+    return null;
+  }
+  let dialect: Dialect;
+  try {
+    dialect = dialectChoice === 'openai' ? 'openai' : dialectChoice === 'anthropic' ? 'anthropic' : dialectFor(model);
+  } catch (err) {
+    console.error('× ' + (err instanceof Error ? err.message : String(err)));
+    return null;
+  }
+  return {
+    model,
+    dialect,
+    withTools,
+    savePath,
+    prompt:
+      prompt ??
+      (withTools
+        ? 'Call the echo tool with any JSON, then summarize what you did.'
+        : 'say hi'),
+  };
+}
+
+function buildBody(args: HarnessArgs): Record<string, unknown> {
+  const messages = [{ role: 'user', content: args.prompt }];
+  if (args.dialect === 'anthropic') {
+    return {
+      model: args.model,
+      max_tokens: 256,
+      messages,
+      stream: true,
+      ...(args.withTools ? { tools: [ECHO_TOOL_ANTHROPIC] } : {}),
+    };
+  }
+  return {
+    model: args.model,
+    messages,
+    stream: true,
+    ...(args.withTools ? { tools: [ECHO_TOOL_OPENAI] } : {}),
+  };
+}
+
+async function run(): Promise<number> {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args) return 2;
+
+  const { config } = resolveConfig();
+  if (!config.apiKey) {
+    console.error('No API key found — set SUBROUTER_API_KEY or create ~/.config/subrouter-cli/config.json.');
+    return 1;
+  }
+  const client = new RouterClient({ baseUrl: config.baseUrl, apiKey: config.apiKey });
+  const url = client.chatPath(args.dialect);
+  const body = buildBody(args);
+
+  console.log(`POST ${url}`);
+  console.log(`model=${args.model} dialect=${args.dialect} tools=${args.withTools ? 'yes' : 'no'}`);
+  console.log('');
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: client.headers(args.dialect),
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(300_000),
+  });
+
+  if (!response.ok) {
+    const text = await drainBody(response);
+    console.error(`HTTP ${response.status}:\n${text}`);
+    return 1;
+  }
+
+  // Raw stream collection: text so far, frame buffer, summary fields.
+  const rawFrames: string[] = [];
+  let finishReason: string | undefined;
+  let stopReason: string | undefined;
+  let inputTokens: number | undefined;
+  let outputTokens: number | undefined;
+  let frameCount = 0;
+
+  const reader = response.body?.getReader();
+  if (!reader) {
+    console.error('No response body.');
+    return 1;
+  }
+  const decoder = new TextDecoder('utf-8');
+  let pending = '';
+  let done = false;
+
+  while (!done) {
+    const { value, done: streamDone } = await reader.read();
+    if (streamDone) break;
+    pending += decoder.decode(value, { stream: true });
+    const lines = pending.split('\n');
+    pending = lines.pop() ?? '';
+    for (const line of lines) {
+      if (line.startsWith('event:')) {
+        console.log(`EVENT │ ${line.slice(6).trim()}`);
+        continue;
+      }
+      if (!line.startsWith('data:')) continue;
+      const payload = line.slice(5).trimStart();
+      if (!payload) continue; // heartbeat
+      frameCount++;
+      console.log(`RAW   │ ${payload.length > 500 ? payload.slice(0, 500) + '…' : payload}`);
+      rawFrames.push(payload);
+
+      if (payload === '[DONE]') {
+        done = true;
+        break;
+      }
+      let event: Record<string, unknown>;
+      try {
+        event = JSON.parse(payload) as Record<string, unknown>;
+      } catch {
+        console.error('× unparseable frame — the stream is not JSON SSE?');
+        done = true;
+        break;
+      }
+      if (args.dialect === 'anthropic') {
+        const type = event.type;
+        if (type === 'message_start' && typeof event.message === 'object' && event.message) {
+          const usage = (event.message as Record<string, unknown>).usage as Record<string, unknown> | undefined;
+          inputTokens = usage?.input_tokens as number | undefined;
+        } else if (type === 'message_delta') {
+          const delta = event.delta as Record<string, unknown> | undefined;
+          stopReason = delta?.stop_reason as string | undefined;
+          const usage = event.usage as Record<string, unknown> | undefined;
+          if (typeof usage?.output_tokens === 'number') outputTokens = usage.output_tokens;
+        } else if (type === 'message_stop') {
+          done = true;
+          break;
+        } else if (type === 'error') {
+          done = true;
+          break;
+        }
+      } else {
+        const choice = (event.choices as Record<string, unknown>[] | undefined)?.[0];
+        if (choice) {
+          if (typeof choice.finish_reason === 'string') finishReason = choice.finish_reason;
+        }
+        const usage = event.usage as Record<string, unknown> | undefined;
+        if (usage) {
+          if (typeof usage.prompt_tokens === 'number') inputTokens = usage.prompt_tokens;
+          if (typeof usage.completion_tokens === 'number') outputTokens = usage.completion_tokens;
+        }
+        if (event.error) done = true;
+      }
+    }
+  }
+
+  console.log('');
+  console.log('SUMMARY');
+  console.log(`frames: ${frameCount}`);
+  console.log(
+    `finish: ${args.dialect === 'anthropic' ? `stop_reason=${stopReason ?? '?'}` : `finish_reason=${finishReason ?? '?'}`}`,
+  );
+  console.log(`usage:  ${inputTokens ?? '?'} in / ${outputTokens ?? '?'} out`);
+  console.log(`ended:  ${done ? 'clean (sentinel/stop seen)' : 'stream closed without sentinel'}`);
+
+  if (args.savePath) {
+    let content = rawFrames.map((f) => 'data: ' + f).join('\n\n') + '\n\n';
+    // Defensive scrub: never persist key material into fixtures.
+    content = content.split(config.apiKey).join('REDACTED');
+    content = content.replace(/sk-sub-[A-Za-z0-9_-]+/g, 'sk-sub-REDACTED');
+    fs.writeFileSync(args.savePath, content);
+    console.log(`saved:  ${args.savePath} (${content.length} bytes)`);
+  }
+  return 0;
+}
+
+try {
+  process.exitCode = await run();
+} catch (err) {
+  const e = err as RouterError;
+  console.error('× ' + e.message);
+  process.exitCode = 1;
+}

package/scripts/sub-wrapper.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+# Symlink this into your PATH (e.g. ln -s "$PWD/scripts/sub-wrapper.sh" ~/.local/bin/sub)
+# or copy it there. Runs `sub` straight from source — Node >= 24 strips TypeScript natively,
+# so there is no build step.
+self=$0
+while [ -L "$self" ]; do
+  dir=$(dirname "$self")
+  self=$(readlink "$self")
+  case "$self" in /*) ;; *) self=$dir/$self ;; esac
+done
+exec node "$(dirname "$self")/../src/index.ts" "$@"

package/src/adapters/anthropic.ts

@@ -0,0 +1,311 @@
+// Anthropic Messages wire <-> normalized types (pinned 2023-06-01, like the Swift app).
+// Tool results are batched into a single user turn (the flush pattern); signed thinking
+// is retained for continuation but never displayed; refusal text is surfaced as content.
+
+import { RouterError } from '../client.ts';
+import { parseToolArgs } from './openai.ts';
+import type {
+  AssistantTurn,
+  AnthropicThinkingBlock,
+  ChatMessage,
+  ChatRequest,
+  StopReason,
+  StreamEvent,
+  ToolCall,
+  TokenUsage,
+} from '../types.ts';
+
+type Wire = Record<string, unknown>;
+
+export const ANTHROPIC_DEFAULT_MAX_TOKENS = 8192;
+const THINKING_BUDGETS = { low: 2048, medium: 4096, high: 8192, xhigh: 16384, max: 32000 };
+
+function thinkingBlock(block: Wire): AnthropicThinkingBlock | undefined {
+  if (block.type === 'thinking') return {
+    type: 'thinking',
+    thinking: typeof block.thinking === 'string' ? block.thinking : '',
+    signature: typeof block.signature === 'string' ? block.signature : '',
+  };
+  if (block.type === 'redacted_thinking' && typeof block.data === 'string')
+    return { type: 'redacted_thinking', data: block.data };
+  return undefined;
+}
+
+/** Normalized request -> Messages body. max_tokens is required on this dialect. */
+export function toAnthropicBody(req: ChatRequest): Wire {
+  const messages: Wire[] = [];
+  let system = req.system;
+  let pendingToolResults: { id: string; content: string; isError: boolean }[] = [];
+
+  const flushToolResults = (): void => {
+    if (pendingToolResults.length === 0) return;
+    messages.push({
+      role: 'user',
+      content: pendingToolResults.map((r) => ({
+        type: 'tool_result',
+        tool_use_id: r.id,
+        content: r.content,
+        is_error: r.isError,
+      })),
+    });
+    pendingToolResults = [];
+  };
+
+  for (const m of req.messages) {
+    if (m.role === 'system') {
+      system = system ? `${system}\n${m.content}` : m.content; // stray system messages fold into the top-level prompt
+      continue;
+    }
+    if (m.role === 'assistant') {
+      flushToolResults();
+      const blocks: Wire[] = (m.thinkingBlocks ?? []).map((block) => ({ ...block }));
+      if (m.content) blocks.push({ type: 'text', text: m.content });
+      for (const c of m.toolCalls ?? []) {
+        blocks.push({ type: 'tool_use', id: c.id, name: c.name, input: c.arguments });
+      }
+      if (blocks.length === 0) continue; // content-less turns are dropped (API rejects them)
+      messages.push({ role: 'assistant', content: blocks });
+      continue;
+    }
+    if (m.role === 'tool') {
+      // Batch consecutive tool results into one user turn.
+      pendingToolResults.push({ id: m.toolCallId ?? '', content: m.content, isError: m.isError ?? false });
+      continue;
+    }
+    flushToolResults(); // any non-tool message ends the batch (ordering matters)
+    if (m.images?.length) {
+      const content: Wire[] = m.content ? [{ type: 'text', text: m.content }] : [];
+      content.push(...m.images.map((image) => ({
+        type: 'image', source: { type: 'base64', media_type: image.mediaType, data: image.data },
+      })));
+      messages.push({ role: 'user', content });
+    } else messages.push({ role: 'user', content: m.content });
+  }
+  flushToolResults();
+
+  const budget = req.effort && req.effort !== 'auto' ? THINKING_BUDGETS[req.effort] : undefined;
+  const maxTokens = req.maxTokens ?? ANTHROPIC_DEFAULT_MAX_TOKENS;
+  const body: Wire = { model: req.model, max_tokens: budget ? Math.max(maxTokens, budget + 4096) : maxTokens, messages, stream: req.stream };
+  if (budget) body.thinking = { type: 'enabled', budget_tokens: budget };
+  if (system) body.system = system;
+  if (req.tools && req.tools.length > 0) {
+    body.tools = req.tools.map((t) => ({
+      name: t.name,
+      description: t.description,
+      input_schema: t.parameters,
+    }));
+  }
+  return body;
+}
+
+/** stop_reason mapping for the Messages API (Swift parity). */
+export function mapAnthropicStopReason(reason: string): StopReason {
+  switch (reason) {
+    case 'end_turn':
+    case 'stop_sequence':
+      return 'stop';
+    case 'tool_use':
+      return 'tool_calls';
+    case 'max_tokens':
+      return 'length';
+    case 'refusal':
+      return 'refusal';
+    default:
+      return 'unknown';
+  }
+}
+
+interface BlockState {
+  text: string;
+  thinking?: AnthropicThinkingBlock;
+  tool?: { id: string; name: string; partialJson: string };
+}
+
+/**
+ * Streaming assembly for the Messages API: message_start → input tokens;
+ * content_block_start(tool_use) → tool_call_start; text_delta → text;
+ * input_json_delta → tool_call_args (accumulated, parsed only at the end);
+ * thinking/signature deltas retained silently; message_delta → stop_reason/output tokens;
+ * message_stop → single stop event. Refusals surface as text.
+ */
+export class AnthropicStreamParser {
+  private textParts: string[] = [];
+  private blocks = new Map<number, BlockState>();
+  private toolSeq = 0; // tool_use blocks get sequential indexes, gaps or not
+  private inputTokens: number | undefined;
+  private outputTokens: number | undefined;
+  private stopReason: StopReason | undefined;
+  private done = false;
+
+  push(payload: string): StreamEvent[] {
+    if (this.done) return []; // message_stop is final — later frames are ignored
+    const data = JSON.parse(payload) as Wire;
+    const type = data.type;
+    const events: StreamEvent[] = [];
+
+    if (type === 'error') {
+      const err = data.error;
+      const errObj = typeof err === 'object' && err !== null ? (err as Wire) : undefined;
+      throw new RouterError(typeof errObj?.message === 'string' ? errObj.message : 'The router returned an error event.');
+    }
+    if (type === 'ping') return events;
+
+    if (type === 'message_start') {
+      const msg = data.message;
+      if (typeof msg === 'object' && msg !== null) {
+        const usage = (msg as Wire).usage;
+        if (typeof usage === 'object' && usage !== null) {
+          const u = usage as Wire;
+          this.inputTokens = typeof u.input_tokens === 'number' ? u.input_tokens : this.inputTokens;
+        }
+      }
+      return events;
+    }
+    if (type === 'content_block_start') {
+      const block = data.content_block;
+      const index = typeof data.index === 'number' ? data.index : this.blocks.size;
+      if (typeof block === 'object' && block !== null && (block as Wire).type === 'tool_use') {
+        const b = block as Wire;
+        const seq = this.toolSeq++;
+        this.blocks.set(index, {
+          text: '',
+          tool: { id: typeof b.id === 'string' ? b.id : '', name: typeof b.name === 'string' ? b.name : '', partialJson: '' },
+        });
+        events.push({ kind: 'tool_call_start', index: seq, id: this.blocks.get(index)!.tool!.id, name: this.blocks.get(index)!.tool!.name });
+      } else {
+        this.blocks.set(index, { text: '', thinking: typeof block === 'object' && block !== null ? thinkingBlock(block as Wire) : undefined });
+      }
+      return events;
+    }
+    if (type === 'content_block_delta') {
+      const index = typeof data.index === 'number' ? data.index : 0;
+      const delta = data.delta;
+      if (typeof delta !== 'object' || delta === null) return events;
+      const d = delta as Wire;
+      const state = this.blocks.get(index) ?? { text: '' };
+      this.blocks.set(index, state);
+      if (d.type === 'text_delta' && typeof d.text === 'string') {
+        this.textParts.push(d.text);
+        events.push({ kind: 'text', text: d.text });
+      } else if (d.type === 'refusal_delta' && typeof d.refusal === 'string') {
+        this.textParts.push(d.refusal); // surfaced as content, not as a tool result
+        events.push({ kind: 'text', text: d.refusal });
+      } else if (d.type === 'input_json_delta' && typeof d.partial_json === 'string') {
+        if (!state.tool) state.tool = { id: '', name: '', partialJson: '' };
+        state.tool.partialJson += d.partial_json;
+        events.push({ kind: 'tool_call_args', index: this.seqFor(index), delta: d.partial_json });
+      } else if (state.thinking?.type === 'thinking') {
+        if (d.type === 'thinking_delta' && typeof d.thinking === 'string') state.thinking.thinking += d.thinking;
+        else if (d.type === 'signature_delta' && typeof d.signature === 'string') state.thinking.signature += d.signature;
+      }
+      // Signed thinking is retained for tool continuations, never emitted to the UI.
+      return events;
+    }
+    if (type === 'content_block_stop') {
+      return events;
+    }
+    if (type === 'message_delta') {
+      const delta = data.delta;
+      if (typeof delta === 'object' && delta !== null && typeof (delta as Wire).stop_reason === 'string') {
+        this.stopReason = mapAnthropicStopReason((delta as Wire).stop_reason as string);
+      }
+      const usage = data.usage;
+      if (typeof usage === 'object' && usage !== null && typeof (usage as Wire).output_tokens === 'number') {
+        this.outputTokens = (usage as Wire).output_tokens as number;
+      }
+      return events;
+    }
+    if (type === 'message_stop') {
+      this.done = true;
+      const usage: TokenUsage | undefined =
+        this.inputTokens !== undefined && this.outputTokens !== undefined
+          ? { inputTokens: this.inputTokens, outputTokens: this.outputTokens }
+          : undefined;
+      events.push({ kind: 'stop', stopReason: this.stopReason ?? 'unknown', usage });
+      return events;
+    }
+    return events; // unknown event types are ignored, never fatal
+  }
+
+  private seqFor(index: number): number {
+    // Map a content-block index back to the sequential tool index it was assigned.
+    const ordered = [...this.blocks.entries()];
+    let seq = 0;
+    for (const [i, s] of ordered) {
+      if (i === index) return seq;
+      if (s.tool) seq++;
+    }
+    return 0;
+  }
+
+  assistantMessage(): ChatMessage {
+    const toolCalls: ToolCall[] = [];
+    for (const s of this.blocks.values()) {
+      if (!s.tool) continue;
+      const { arguments: parsed, invalid } = parseToolArgs(s.tool.partialJson);
+      toolCalls.push({
+        id: s.tool.id,
+        name: s.tool.name,
+        arguments: parsed,
+        argumentsJson: s.tool.partialJson,
+        argumentsInvalid: invalid,
+      });
+    }
+    const message: ChatMessage = { role: 'assistant', content: this.textParts.join('') };
+    if (toolCalls.length > 0) message.toolCalls = toolCalls;
+    const thinkingBlocks = [...this.blocks.values()].flatMap((state) => state.thinking ? [{ ...state.thinking }] : []);
+    if (thinkingBlocks.length) message.thinkingBlocks = thinkingBlocks;
+    return message;
+  }
+}
+
+/** Non-streaming Messages response -> normalized turn. */
+export function parseAnthropicCompleteBody(json: unknown): AssistantTurn {
+  if (typeof json !== 'object' || json === null) {
+    throw new RouterError('Unexpected response from the router (not an object).');
+  }
+  const body = json as Wire;
+  if (body.type === 'error') {
+    const err = body.error;
+    const errObj = typeof err === 'object' && err !== null ? (err as Wire) : undefined;
+    throw new RouterError(typeof errObj?.message === 'string' ? errObj.message : 'The router returned an error.');
+  }
+  if (!Array.isArray(body.content)) {
+    throw new RouterError('Unexpected response from the router (no content array).');
+  }
+  const textParts: string[] = [];
+  const toolCalls: ToolCall[] = [];
+  const thinkingBlocks: AnthropicThinkingBlock[] = [];
+  for (const block of body.content as Wire[]) {
+    if (typeof block !== 'object' || block === null) continue;
+    const thinking = thinkingBlock(block);
+    if (thinking) thinkingBlocks.push(thinking);
+    if (block.type === 'text' && typeof block.text === 'string') textParts.push(block.text);
+    if (block.type === 'refusal' && typeof block.refusal === 'string') textParts.push(block.refusal);
+    if (block.type === 'tool_use') {
+      const input = block.input;
+      const rawArgs = typeof input === 'object' && input !== null ? JSON.stringify(input) : '';
+      const { arguments: parsed, invalid } = parseToolArgs(rawArgs);
+      toolCalls.push({
+        id: typeof block.id === 'string' ? block.id : '',
+        name: typeof block.name === 'string' ? block.name : '',
+        arguments: parsed,
+        argumentsJson: rawArgs,
+        argumentsInvalid: invalid,
+      });
+    }
+  }
+  const message: ChatMessage = { role: 'assistant', content: textParts.join('') };
+  if (toolCalls.length > 0) message.toolCalls = toolCalls;
+  if (thinkingBlocks.length) message.thinkingBlocks = thinkingBlocks;
+  const stopReason = typeof body.stop_reason === 'string' ? mapAnthropicStopReason(body.stop_reason) : 'unknown';
+  const usageWire = body.usage;
+  let usage: TokenUsage | undefined;
+  if (typeof usageWire === 'object' && usageWire !== null) {
+    const u = usageWire as Wire;
+    if (typeof u.input_tokens === 'number' && typeof u.output_tokens === 'number') {
+      usage = { inputTokens: u.input_tokens, outputTokens: u.output_tokens };
+    }
+  }
+  return { message, stopReason, usage };
+}