subrouter-cli 0.0.0-stage → 0.1.0

package/src/client.ts

@@ -0,0 +1,398 @@
+// RouterClient — HTTP against the subrouter gateway. Mirrors the error handling of
+// subrouter-web-chat/server.js and the Swift RouterClient: same envelope parsing,
+// per-status hints, and digit-only Retry-After handling.
+
+import { AnthropicStreamParser, parseAnthropicCompleteBody, toAnthropicBody } from './adapters/anthropic.ts';
+import { OpenAiStreamParser, parseCompleteBody, toWireBody } from './adapters/openai.ts';
+import { sseFrames } from './sse.ts';
+import type { AssistantTurn, ChatMessage, ChatRequest, Dialect, StreamEvent, ToolDefinition } from './types.ts';
+
+export const ANTHROPIC_VERSION = '2023-06-01';
+const MAX_ERROR_TEXT = 1000;
+
+type JsonObject = Record<string, unknown>;
+
+export class RouterError extends Error {
+  status?: number;
+  type?: string;
+  code?: string;
+  param?: string;
+  requestId?: string;
+  retryAfterSeconds?: number;
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'RouterError';
+  }
+}
+
+export function statusHint(status: number): string {
+  switch (status) {
+    case 400:
+      return 'Check the request and model ID (run /models for the live catalog).';
+    case 401:
+      return 'The API key is missing or invalid — set SUBROUTER_API_KEY or edit ~/.config/subrouter-cli/config.json.';
+    case 403:
+      return 'This model is not on your allowlist, or the router admin turned it off.';
+    case 429:
+      return 'Rate limit, daily cap, or shared-pool pacing is limiting this request; try later or check quota via /usage.';
+    case 502:
+      return 'The provider is disconnected or its credentials need renewal.';
+    default:
+      return 'The router could not complete the request.';
+  }
+}
+
+function bounded(value: string): string {
+  const trimmed = value.trim();
+  return trimmed.length > MAX_ERROR_TEXT ? trimmed.slice(0, MAX_ERROR_TEXT) + '…' : trimmed;
+}
+
+/** Display copy for any failure: bare fetch network errors get actionable text. */
+export function errorMessage(err: unknown): string {
+  if (err instanceof TypeError) return 'Network error — could not reach the router.';
+  return err instanceof Error ? err.message : String(err);
+}
+
+function scalarString(value: unknown): string | undefined {
+  if (typeof value === 'string') return bounded(value);
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  return undefined;
+}
+
+function safeJson(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+async function drainBody(response: Response, cap = 4096): Promise<string> {
+  try {
+    const text = await response.text();
+    return text.length > cap ? text.slice(0, cap) : text;
+  } catch {
+    return '';
+  }
+}
+
+/** delta-seconds only: all digits, capped at 60s (Swift parity — no HTTP dates). */
+function retryAfterSecondsFrom(headers: Headers): number | undefined {
+  const raw = headers.get('retry-after')?.trim();
+  if (!raw || !/^\d+$/.test(raw)) return undefined;
+  const value = Number(raw);
+  if (!Number.isFinite(value)) return undefined;
+  return Math.min(value, 60);
+}
+
+async function routerErrorFromResponse(status: number, response: Response): Promise<RouterError> {
+  const body = safeJson(await drainBody(response)) as JsonObject | undefined;
+  const nested = body?.error;
+  const nestedObj = typeof nested === 'object' && nested !== null ? (nested as JsonObject) : undefined;
+  const message =
+    (typeof nestedObj?.message === 'string' && nestedObj.message) ||
+    (typeof body?.message === 'string' && body.message) ||
+    (typeof nested === 'string' ? nested : undefined) ||
+    statusHint(status);
+  const err = new RouterError(bounded(message));
+  err.status = status;
+  if (nestedObj) {
+    err.type = scalarString(nestedObj.type);
+    err.code = scalarString(nestedObj.code);
+    err.param = scalarString(nestedObj.param);
+    err.requestId = scalarString(nestedObj.request_id ?? nestedObj.requestId);
+  }
+  const retryAfter = retryAfterSecondsFrom(response.headers);
+  if (retryAfter !== undefined) {
+    err.retryAfterSeconds = retryAfter;
+    err.message += ` Retry after ${retryAfter} seconds.`;
+  }
+  return err;
+}
+
+/**
+ * Which wire dialect a model id speaks. A provider prefix always wins, so
+ * `openai/claude-proxy` is not silently rerouted (Swift parity).
+ */
+export function dialectFor(model: string): Dialect {
+  const id = model.trim().toLowerCase();
+  if (!id) throw new RouterError('Model id is empty.');
+  if (id.startsWith('anthropic/')) return 'anthropic';
+  if (id.includes('/')) return 'openai';
+  if (id.startsWith('claude-') || id.startsWith('claude.')) return 'anthropic';
+  if (id.startsWith('gpt-') || id.startsWith('grok-') || id.startsWith('deepseek-')) return 'openai';
+  throw new RouterError(
+    `Cannot route model "${model}" — use the full provider-prefixed id from /models (e.g. opencode/glm-5.3-flash).`,
+  );
+}
+
+/** Strip the /v1 suffix: the Anthropic endpoints hang off the bare root. */
+export function rootFromBase(baseUrl: string): string {
+  const url = new URL(baseUrl);
+  if (url.pathname === '/v1' || url.pathname === '/v1/') {
+    url.pathname = '';
+  } else {
+    url.pathname = url.pathname.replace(/\/+$/, '');
+  }
+  return url.toString().replace(/\/$/, '');
+}
+
+export interface ModelCatalogEntry {
+  id: string;
+  displayName?: string;
+  ownedBy?: string;
+  contextLength?: number;
+  maxOutputTokens?: number;
+}
+
+/** Pure catalog parsing; accepts {"data":[...]} and {"models":[...]} (Swift parity). */
+export function parseModelCatalog(json: unknown): ModelCatalogEntry[] | null {
+  if (typeof json !== 'object' || json === null) return null;
+  const root = json as JsonObject;
+  const entries = Array.isArray(root.data) ? root.data : Array.isArray(root.models) ? root.models : null;
+  if (!entries) return null;
+  const result: ModelCatalogEntry[] = [];
+  for (const entry of entries) {
+    if (typeof entry === 'string') {
+      result.push({ id: entry });
+      continue;
+    }
+    if (typeof entry !== 'object' || entry === null) continue;
+    const e = entry as JsonObject;
+    const id = typeof e.id === 'string' ? e.id : typeof e.name === 'string' ? e.name : undefined;
+    if (!id) continue;
+    result.push({
+      id,
+      displayName: typeof e.display_name === 'string' ? e.display_name : undefined,
+      ownedBy: typeof e.owned_by === 'string' ? e.owned_by : undefined,
+      contextLength: positiveInteger(e.context_length),
+      maxOutputTokens: positiveInteger(e.max_output_tokens),
+    });
+  }
+  return result;
+}
+
+function positiveInteger(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+
+export interface RouterClientOptions {
+  baseUrl: string; // OpenAI-compatible root, e.g. https://router.eva.pink/v1
+  apiKey: string;
+  debug?: (line: string) => void;
+  sleep?: (ms: number) => Promise<void>; // test seam: replaces the retry wait
+}
+
+export class RouterClient {
+  private baseUrl: string;
+  private apiKey: string;
+  private debug: (line: string) => void;
+  private wait: (ms: number) => Promise<void>;
+
+  constructor(options: RouterClientOptions) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+    this.apiKey = options.apiKey;
+    this.debug = options.debug ?? (() => {});
+    this.wait = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  }
+
+  /** Bare root without /v1 — Anthropic endpoints hang off this. */
+  rootUrl(): string {
+    return rootFromBase(this.baseUrl);
+  }
+
+  /** The completion endpoint for a dialect (used by the harness and adapters). */
+  chatPath(dialect: Dialect): string {
+    return dialect === 'anthropic'
+      ? this.rootUrl() + '/v1/messages'
+      : this.baseUrl + '/chat/completions';
+  }
+
+  /** Auth headers per dialect; the router accepts Bearer everywhere (Swift parity). */
+  headers(dialect?: Dialect): Record<string, string> {
+    const h: Record<string, string> = {
+      Authorization: `Bearer ${this.apiKey}`,
+      'Content-Type': 'application/json',
+    };
+    if (dialect === 'anthropic') {
+      h['x-api-key'] = this.apiKey;
+      h['anthropic-version'] = ANTHROPIC_VERSION;
+    }
+    return h;
+  }
+
+  /** GET {root}/healthz, no auth. */
+  async healthz(): Promise<boolean> {
+    try {
+      const res = await fetch(this.rootUrl() + '/healthz', { signal: AbortSignal.timeout(10_000) });
+      if (!res.ok) return false;
+      return (await res.text()).trim() === 'ok';
+    } catch {
+      return false;
+    }
+  }
+
+  async listModels(signal?: AbortSignal): Promise<ModelCatalogEntry[]> {
+    const res = await fetch(this.baseUrl + '/models', {
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+      signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000),
+      cache: 'no-store',
+    });
+    if (!res.ok) throw await routerErrorFromResponse(res.status, res);
+    const entries = parseModelCatalog(await res.json());
+    if (!entries) {
+      throw new RouterError('GET /models: unexpected response shape (no "data" or "models" array).');
+    }
+    return entries;
+  }
+
+  /** The /usage endpoint only exists on the subrouter itself (Swift's supportsUsage guard). */
+  supportsUsage(): boolean {
+    try {
+      const url = new URL(this.baseUrl);
+      return url.protocol === 'https:' && url.host === 'router.eva.pink';
+    } catch {
+      return false;
+    }
+  }
+
+  /** GET /usage — typed/rendered in usage.ts; raw shape for now. */
+  async usage(signal?: AbortSignal): Promise<unknown> {
+    if (!this.supportsUsage()) {
+      throw new RouterError('Usage is unavailable for this connection.');
+    }
+    const res = await fetch(this.baseUrl + '/usage', {
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+      signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000),
+      cache: 'no-store',
+    });
+    if (!res.ok) throw await routerErrorFromResponse(res.status, res);
+    return await res.json();
+  }
+
+  /** Non-streaming chat. One retry for retryable failures (429/502/503/network). */
+  async complete(req: ChatRequest, signal?: AbortSignal): Promise<AssistantTurn> {
+    return await this.withRetry(async () => {
+      const res = await fetch(this.chatPath(req.dialect), {
+        method: 'POST',
+        headers: this.headers(req.dialect),
+        body: JSON.stringify(req.dialect === 'anthropic' ? toAnthropicBody(req) : toWireBody(req)),
+        signal: signal ?? AbortSignal.timeout(300_000),
+      });
+      if (!res.ok) throw await routerErrorFromResponse(res.status, res);
+      const json = (await res.json()) as unknown;
+      return req.dialect === 'anthropic' ? parseAnthropicCompleteBody(json) : parseCompleteBody(json);
+    });
+  }
+
+  /**
+   * Streaming chat. Events flow to onEvent as they arrive; resolves with the assembled
+   * turn. Retried once on retryable failures, and only when nothing has been emitted yet
+   * (a mid-stream retry would duplicate text).
+   */
+  async chat(req: ChatRequest, onEvent: (e: StreamEvent) => void, signal?: AbortSignal): Promise<AssistantTurn> {
+    let emitted = false;
+    const wrap = (e: StreamEvent): void => {
+      emitted = true;
+      onEvent(e);
+    };
+    const attempt = async (): Promise<AssistantTurn> => {
+      const res = await fetch(this.chatPath(req.dialect), {
+        method: 'POST',
+        headers: this.headers(req.dialect),
+        body: JSON.stringify(req.dialect === 'anthropic' ? toAnthropicBody(req) : toWireBody(req)),
+        signal: signal ?? AbortSignal.timeout(300_000),
+      });
+      if (!res.ok) throw await routerErrorFromResponse(res.status, res);
+      if (!res.body) throw new RouterError('The router returned an empty stream.');
+      const parser = req.dialect === 'anthropic' ? new AnthropicStreamParser() : new OpenAiStreamParser();
+      for await (const frame of sseFrames(res.body)) {
+        if (req.dialect === 'openai' && frame.data.trim() === '[DONE]') break;
+        this.debug(`sse: ${frame.event ? frame.event + ' ' : ''}${frame.data.slice(0, 300)}`);
+        if (req.dialect === 'anthropic' && frame.event === 'message_stop') {
+          const events = parser.push(frame.data);
+          return { message: parser.assistantMessage(), stopReason: events[0]?.kind === 'stop' ? events[0].stopReason : 'unknown', usage: events[0]?.kind === 'stop' ? events[0].usage : undefined };
+        }
+        const events = parser.push(frame.data);
+        for (const e of events) {
+          if (e.kind === 'stop') {
+            return { message: parser.assistantMessage(), stopReason: e.stopReason, usage: e.usage };
+          }
+          wrap(e);
+        }
+      }
+      throw new RouterError('The router closed the response before it finished.');
+    };
+    try {
+      return await attempt();
+    } catch (err) {
+      if (emitted || !this.isRetryable(err)) throw err;
+      await this.sleep(this.retryDelayMs(err as RouterError));
+      return await attempt();
+    }
+  }
+
+  /**
+   * Exact token count via POST /v1/messages/count_tokens (Messages body only, free).
+   * Advisory: callers must fall back to estimation on any failure.
+   */
+  async countTokens(model: string, system: string, messages: ChatMessage[], tools?: ToolDefinition[]): Promise<number> {
+    const body: Record<string, unknown> = toAnthropicBody({
+      model,
+      dialect: 'anthropic',
+      messages,
+      system,
+      tools,
+      stream: false,
+    });
+    const res = await fetch(this.rootUrl() + '/v1/messages/count_tokens', {
+      method: 'POST',
+      headers: this.headers('anthropic'),
+      body: JSON.stringify(body),
+      signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000),
+    });
+    if (!res.ok) throw await routerErrorFromResponse(res.status, res);
+    const json = (await res.json()) as { input_tokens?: unknown };
+    if (typeof json.input_tokens !== 'number') {
+      throw new RouterError('count_tokens: unexpected response shape (no input_tokens).');
+    }
+    return json.input_tokens;
+  }
+
+  /** One retry for 429/502/503 and network failures; 400/401/403 pass through. */
+  private async withRetry<T>(attempt: () => Promise<T>): Promise<T> {
+    try {
+      return await attempt();
+    } catch (err) {
+      if (!this.isRetryable(err)) throw err;
+      await this.sleep(this.retryDelayMs(err as RouterError));
+      return await attempt();
+    }
+  }
+
+  private isRetryable(err: unknown): boolean {
+    // A user abort (Ctrl+C) is never retried.
+    if (err instanceof DOMException && err.name === 'AbortError') return false;
+    const e = err as RouterError;
+    return (
+      !e.status ||
+      e.status === 429 ||
+      e.status === 502 ||
+      e.status === 503 ||
+      err instanceof TypeError // fetch network failure
+    );
+  }
+
+  private retryDelayMs(err: RouterError): number {
+    if (err.retryAfterSeconds) return err.retryAfterSeconds * 1000;
+    return err.status === 429 ? 2000 : 1000;
+  }
+
+  private async sleep(ms: number): Promise<void> {
+    this.debug(`retrying after ${ms}ms`);
+    await this.wait(ms);
+  }
+}
+
+export { routerErrorFromResponse, drainBody, bounded };

package/src/clipboard.ts

@@ -0,0 +1,62 @@
+// User-triggered macOS clipboard access only; never exposed as an agent tool.
+import { execFile } from 'node:child_process';
+import { imageFromBytes, MAX_IMAGE_BYTES, type ImageAttachment } from './images.ts';
+
+// Fixed JXA reads AppKit's pasteboard directly. No shell, temp files, dependencies,
+// or clipboard-derived code/arguments. Screenshots commonly arrive as TIFF.
+export const CLIPBOARD_SCRIPT = `
+ObjC.import('AppKit');
+function encode(data) {
+  if (data.length > ${MAX_IMAGE_BYTES}) return JSON.stringify({ error: 'large' });
+  return JSON.stringify({ data: ObjC.unwrap(data.base64EncodedStringWithOptions(0)) });
+}
+function run() {
+  const board = $.NSPasteboard.generalPasteboard;
+  const png = board.dataForType($.NSPasteboardTypePNG);
+  if (png && !png.isNil()) return encode(png);
+  const tiff = board.dataForType($.NSPasteboardTypeTIFF);
+  if (!tiff || tiff.isNil()) return JSON.stringify({ error: 'empty' });
+  if (tiff.length > 40 * 1024 * 1024) return JSON.stringify({ error: 'large' });
+  const image = $.NSBitmapImageRep.imageRepWithData(tiff);
+  if (!image || image.isNil()) return JSON.stringify({ error: 'invalid' });
+  if (image.pixelsWide * image.pixelsHigh > 40000000) return JSON.stringify({ error: 'dimensions' });
+  const data = image.representationUsingTypeProperties($.NSBitmapImageFileTypePNG, $({}));
+  if (!data || data.isNil()) return JSON.stringify({ error: 'invalid' });
+  return encode(data);
+}
+`;
+
+const MAX_BASE64_LENGTH = Math.ceil(MAX_IMAGE_BYTES / 3) * 4;
+const unreadable = 'could not read the clipboard image — copy it again and press Ctrl+V';
+
+export function decodeClipboardImage(output: string): ImageAttachment {
+  if (output.length > MAX_BASE64_LENGTH + 100) throw new Error('clipboard image exceeds the 10 MiB attachment limit');
+  let result: unknown;
+  try { result = JSON.parse(output); }
+  catch { throw new Error(unreadable); }
+  if (!result || typeof result !== 'object') throw new Error(unreadable);
+  const record = result as Record<string, unknown>;
+  if (record.error === 'empty') throw new Error('no image in the clipboard — copy an image or use Ctrl+Cmd+Shift+4; Cmd+V pastes text');
+  if (record.error === 'large') throw new Error('clipboard image exceeds the 10 MiB attachment limit');
+  if (record.error === 'dimensions') throw new Error('clipboard image is too large to convert — copy a smaller screenshot');
+  if (typeof record.data !== 'string' || !record.data || /[^A-Za-z0-9+/=]/.test(record.data)) throw new Error(unreadable);
+  const bytes = Buffer.from(record.data, 'base64');
+  if (bytes.toString('base64') !== record.data) throw new Error(unreadable);
+  return imageFromBytes(bytes, 'clipboard.png');
+}
+
+export async function readClipboardImage(signal?: AbortSignal): Promise<ImageAttachment> {
+  signal?.throwIfAborted();
+  if (process.platform !== 'darwin') throw new Error('clipboard images are supported on macOS only');
+  const output = await new Promise<string>((resolve, reject) => {
+    execFile('/usr/bin/osascript', ['-l', 'JavaScript', '-e', CLIPBOARD_SCRIPT], {
+      encoding: 'utf8', shell: false, timeout: 10_000,
+      maxBuffer: MAX_BASE64_LENGTH + 1024, signal,
+    }, (err, stdout) => {
+      if (err) reject(signal?.aborted ? signal.reason : new Error(unreadable));
+      else resolve(stdout);
+    });
+  });
+  signal?.throwIfAborted();
+  return decodeClipboardImage(output);
+}