thebird 1.2.73 → 1.2.74

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 ## [Unreleased]
 
+### Added
+- `lib/errors.js`: Typed error hierarchy — BridgeError, AuthError, RateLimitError, TimeoutError, ContextWindowError, ContentPolicyError, ProviderError with classifyError factory. GeminiError kept as alias.
+- `lib/errors.js`: `redactKeys()` — auto-redacts API keys (AIza, sk-, key- patterns) in error messages to `...XXXX`
+- `lib/errors.js`: `parseRetryAfterHeader()` — parses standard HTTP Retry-After header (seconds and date formats) in addition to Gemini-specific retry info
+- `lib/stream-guard.js`: `guardStream()` — wraps async iterables with per-chunk timeout (30s default) and repeated-chunk detection (100 threshold)
+- `lib/circuit-breaker.js`: `createCircuitBreaker()` — per-provider failure tracking with auto-recovery after cooldown
+- `lib/capabilities.js`: `getCapabilities()` / `stripUnsupported()` — provider capability metadata with automatic feature stripping and warnings
+- `lib/router-stream.js`: Router logic extracted from index.js — circuit breaker and capability checks integrated
+
+### Changed
+- `index.js`: Trimmed from 177 to 104 lines by extracting router logic to lib/router-stream.js
+- `index.d.ts`: Added types for BridgeError hierarchy, StreamGuardOptions, CapabilitySet, CircuitBreakerOptions
+- `lib/providers/openai.js`: Passes response headers to error objects for Retry-After parsing; integrates guardStream
+
 ### Added
 - `docs/app.js`: Cerebras as OpenAI-compatible provider option (https://api.cerebras.ai/v1)
 - `docs/shell.js`: `createShell({ term, onPreviewWrite })` — POSIX shell + Node REPL using browser V8 eval + xstate v5 state machine. Dispatch table of built-ins: ls, cat, echo, pwd, cd, mkdir, rm, cp, mv, env, export, clear, help, node, npm install, exit. Pipe support via ` | ` split. `window.__debug.shell` exposes state, cwd, env, history, httpHandlers, nodeMode. `http.createServer` polyfill registers handlers in httpHandlers map.

package/index.d.ts

@@ -37,7 +37,7 @@ export interface FinishStepEvent { type: 'finish-step'; finishReason: 'stop' | '
 export interface ErrorEvent { type: 'error'; error: Error }
 export type StreamEvent = StartStepEvent | TextDeltaEvent | ToolCallEvent | ToolResultEvent | FinishStepEvent | ErrorEvent;
 export interface StreamResult { fullStream: AsyncIterable<StreamEvent>; warnings: Promise<unknown[]> }
-export interface StreamParams extends GenerationParams { onStepFinish?: () => Promise<void> | void }
+export interface StreamParams extends GenerationParams { onStepFinish?: () => Promise<void> | void; streamGuard?: StreamGuardOptions }
 export function streamGemini(params: StreamParams): StreamResult;
 export interface GenerateResult { text: string; parts: unknown[]; response: unknown }
 export function generateGemini(params: GenerationParams): Promise<GenerateResult>;
@@ -53,6 +53,7 @@ export interface ProviderConfig {
   api_key: string;
   models?: string[];
   transformer?: TransformerConfig;
+  capabilities?: Partial<CapabilitySet>;
 }
 export interface RouterConfig {
   default?: string;
@@ -69,8 +70,10 @@ export interface RouterConfiguration {
   Router?: RouterConfig;
   customRouter?: (params: GenerationParams, config: RouterConfig) => Promise<string | null>;
   configPath?: string;
+  circuitBreaker?: CircuitBreakerOptions;
 }
 export interface RouterInstance {
+  breaker: { isOpen(name: string): boolean; recordFailure(name: string): void; recordSuccess(name: string): void };
   stream(params: StreamParams): StreamResult;
   generate(params: GenerationParams): Promise<GenerateResult | { text: string; response: unknown }>;
 }
@@ -89,10 +92,35 @@ export interface GeminiContent { role: 'user' | 'model'; parts: GeminiPart[] }
 export function convertMessages(messages: Message[]): GeminiContent[];
 export function convertTools(tools: Tools): Array<{ name: string; description: string; parameters: Record<string, unknown> }>;
 export function cleanSchema(schema: unknown): unknown;
-export class GeminiError extends Error {
-  name: 'GeminiError';
+export interface StreamGuardOptions {
+  chunkTimeoutMs?: number;
+  maxRepeats?: number;
+}
+export interface CapabilitySet {
+  streaming: boolean;
+  toolUse: boolean;
+  vision: boolean;
+  systemMessage: boolean;
+  jsonMode: boolean;
+}
+export interface CircuitBreakerOptions {
+  maxFailures?: number;
+  cooldownMs?: number;
+}
+export class BridgeError extends Error {
+  name: string;
   status?: number;
   code?: string | number;
   retryable: boolean;
-  constructor(message: string, options?: { status?: number; code?: string | number; retryable?: boolean });
+  provider?: string;
+  constructor(message: string, options?: { status?: number; code?: string | number; retryable?: boolean; provider?: string; headers?: unknown });
 }
+export class AuthError extends BridgeError {}
+export class RateLimitError extends BridgeError {}
+export class TimeoutError extends BridgeError {}
+export class ContextWindowError extends BridgeError {}
+export class ContentPolicyError extends BridgeError {}
+export class ProviderError extends BridgeError {}
+export const GeminiError: typeof BridgeError;
+export function classifyError(status: number, message: string, provider?: string): BridgeError;
+export function redactKeys(str: string): string;

package/index.js

@@ -98,6 +98,6 @@ async function generateGemini({ model, system, messages, tools, apiKey, temperat
 const { streamRouter, generateRouter, createRouter } = require('./lib/router-stream');
 const { cloudGenerate, streamCloud, cloudStream } = require('./lib/cloud-generate');
 const { ensureAuth, login: oauthLogin } = require('./lib/oauth');
-const { TimeoutError } = require('./lib/stream-guard');
+const { BridgeError, AuthError, RateLimitError, TimeoutError, ContextWindowError, ContentPolicyError, ProviderError, classifyError } = require('./lib/errors');
 
-module.exports = { streamGemini, createFullStream, generateGemini, streamRouter, generateRouter, createRouter, convertMessages, convertTools, cleanSchema, GeminiError, TimeoutError, cloudGenerate, streamCloud, cloudStream, ensureAuth, oauthLogin };
+module.exports = { streamGemini, createFullStream, generateGemini, streamRouter, generateRouter, createRouter, convertMessages, convertTools, cleanSchema, GeminiError, BridgeError, AuthError, RateLimitError, TimeoutError, ContextWindowError, ContentPolicyError, ProviderError, classifyError, cloudGenerate, streamCloud, cloudStream, ensureAuth, oauthLogin };

package/lib/capabilities.js

@@ -0,0 +1,50 @@
+const DEFAULTS = {
+  streaming: true,
+  toolUse: true,
+  vision: true,
+  systemMessage: true,
+  jsonMode: false
+};
+
+function getCapabilities(provider) {
+  return { ...DEFAULTS, ...(provider.capabilities || {}) };
+}
+
+function stripImageBlocks(messages) {
+  return messages.map(msg => {
+    if (!Array.isArray(msg.content)) return msg;
+    const filtered = msg.content.filter(b => b.type !== 'image' && b.type !== 'image_url');
+    if (filtered.length === 0) return { ...msg, content: [{ type: 'text', text: '[image removed - unsupported by provider]' }] };
+    return { ...msg, content: filtered };
+  });
+}
+
+function prependSystemAsUser(messages, system) {
+  if (!system) return { messages, system: undefined };
+  const text = Array.isArray(system) ? system.map(b => b.text || '').join('\n') : system;
+  const sysMsg = { role: 'user', content: [{ type: 'text', text }] };
+  return { messages: [sysMsg, ...messages], system: undefined };
+}
+
+function stripUnsupported(params, caps) {
+  const warnings = [];
+  const result = { ...params };
+  if (!caps.toolUse && result.tools) {
+    delete result.tools;
+    delete result.tool_choice;
+    warnings.push('toolUse not supported — tools removed');
+  }
+  if (!caps.vision && result.messages) {
+    result.messages = stripImageBlocks(result.messages);
+    warnings.push('vision not supported — image blocks removed');
+  }
+  if (!caps.systemMessage && result.system) {
+    const { messages, system } = prependSystemAsUser(result.messages || [], result.system);
+    result.messages = messages;
+    result.system = system;
+    warnings.push('systemMessage not supported — prepended as user message');
+  }
+  return { params: result, warnings };
+}
+
+module.exports = { getCapabilities, stripUnsupported, DEFAULTS };

package/lib/circuit-breaker.js

@@ -0,0 +1,36 @@
+function createCircuitBreaker(opts = {}) {
+  const maxFailures = opts.maxFailures || 5;
+  const cooldownMs = opts.cooldownMs || 60000;
+  const state = new Map();
+
+  function getState(name) {
+    if (!state.has(name)) state.set(name, { failures: 0, openedAt: 0 });
+    return state.get(name);
+  }
+
+  function isOpen(name) {
+    const s = getState(name);
+    if (s.failures < maxFailures) return false;
+    if (Date.now() - s.openedAt >= cooldownMs) {
+      s.failures = maxFailures;
+      return false;
+    }
+    return true;
+  }
+
+  function recordFailure(name) {
+    const s = getState(name);
+    s.failures++;
+    if (s.failures >= maxFailures) s.openedAt = Date.now();
+  }
+
+  function recordSuccess(name) {
+    const s = getState(name);
+    s.failures = 0;
+    s.openedAt = 0;
+  }
+
+  return { isOpen, recordFailure, recordSuccess };
+}
+
+module.exports = { createCircuitBreaker };

package/lib/errors.js

@@ -1,6 +1,23 @@
+const KEY_PATTERNS = [
+  /\b(AIza[A-Za-z0-9_-]{20,})/g,
+  /\b(sk-[A-Za-z0-9]{20,})/g,
+  /\b(key-[A-Za-z0-9]{20,})/g,
+  /((?:api[_-]?key|token|secret|authorization|bearer)[=:\s"']+)([A-Za-z0-9_-]{20,})/gi,
+];
+
+function redactKeys(str) {
+  if (typeof str !== 'string') return str;
+  let result = str;
+  result = result.replace(KEY_PATTERNS[0], m => `...${m.slice(-4)}`);
+  result = result.replace(KEY_PATTERNS[1], m => `...${m.slice(-4)}`);
+  result = result.replace(KEY_PATTERNS[2], m => `...${m.slice(-4)}`);
+  result = result.replace(KEY_PATTERNS[3], (_, prefix, val) => `${prefix}...${val.slice(-4)}`);
+  return result;
+}
+
 class BridgeError extends Error {
   constructor(message, { status, code, retryable = false, provider, headers } = {}) {
-    super(message);
+    super(redactKeys(message));
     this.name = 'BridgeError';
     this.status = status;
     this.code = code;
@@ -119,5 +136,5 @@ async function withRetry(fn, maxRetries = 3) {
 module.exports = {
   BridgeError, GeminiError, AuthError, RateLimitError,
   TimeoutError, ContextWindowError, ContentPolicyError,
-  ProviderError, classifyError, isRetryable, withRetry
+  ProviderError, classifyError, isRetryable, withRetry, redactKeys
 };

package/lib/router-stream.js

@@ -3,6 +3,8 @@ const { resolveTransformers, applyRequestTransformers } = require('./transformer
 const { loadConfig } = require('./config');
 const { route } = require('./router');
 const openaiProv = require('./providers/openai');
+const { createCircuitBreaker } = require('./circuit-breaker');
+const { getCapabilities, stripUnsupported } = require('./capabilities');
 
 function isGeminiProvider(p) {
   return p.name === 'gemini' || (p.api_base_url || '').includes('generativelanguage.googleapis.com');
@@ -26,7 +28,9 @@ function resolveForProvider(provider, model, customMap) {
 
 async function* routerStream(params, resolver) {
   const { createFullStream } = require('../index');
-  const { provider, actualModel, transformers } = await resolver(params);
+  const { provider, actualModel, transformers, caps } = await resolver(params);
+  const stripped = stripUnsupported(params, caps);
+  params = stripped.params;
   if (isGeminiProvider(provider)) {
     yield* createFullStream({ ...params, model: actualModel, apiKey: provider.api_key || params.apiKey });
   } else {
@@ -43,18 +47,26 @@ function createRouter(config) {
   const { generateGemini } = require('../index');
   const providers = config.Providers || config.providers || [];
   const routerCfg = config.Router || {};
+  const breaker = createCircuitBreaker(config.circuitBreaker);
   async function resolve(params) {
     const { providerName, modelName } = await route(params, routerCfg, config.customRouter);
-    const provider = findProvider(providers, providerName, modelName) || providers[0];
+    let provider = findProvider(providers, providerName, modelName) || providers[0];
+    if (provider && breaker.isOpen(provider.name)) {
+      const fallback = providers.find(p => p !== provider && !breaker.isOpen(p.name));
+      if (fallback) provider = fallback;
+    }
     if (!provider) throw new Error('[thebird] no provider configured');
     const actualModel = modelName || (provider.models || [])[0] || extractModelId(params.model) || 'gemini-2.0-flash';
     const transformers = resolveForProvider(provider, actualModel, config._transformers);
-    return { provider, actualModel, transformers };
+    const caps = getCapabilities(provider);
+    return { provider, actualModel, transformers, caps };
   }
   return {
+    breaker,
     stream(params) { return { fullStream: routerStream(params, resolve), warnings: Promise.resolve([]) }; },
     async generate(params) {
-      const { provider, actualModel, transformers } = await resolve(params);
+      const { provider, actualModel, transformers, caps } = await resolve(params);
+      params = stripUnsupported(params, caps).params;
       if (isGeminiProvider(provider)) return generateGemini({ ...params, model: actualModel, apiKey: provider.api_key || params.apiKey });
       const oaiMsgs = openaiProv.convertMessages(params.messages, params.system);
       const oaiTools = openaiProv.convertTools(params.tools);

package/lib/stream-guard.js

@@ -1,15 +1,8 @@
-const { GeminiError } = require('./errors');
-
-class TimeoutError extends GeminiError {
-  constructor(ms) {
-    super(`Stream chunk timeout after ${ms}ms`, { retryable: true });
-    this.name = 'TimeoutError';
-  }
-}
+const { TimeoutError, BridgeError } = require('./errors');
 
 async function* guardStream(iterable, opts = {}) {
-  const timeoutMs = opts.chunkTimeoutMs ?? 30000;
-  const maxRepeats = opts.maxRepeats ?? 100;
+  const timeoutMs = opts?.chunkTimeoutMs ?? 30000;
+  const maxRepeats = opts?.maxRepeats ?? 100;
   let lastChunk = null;
   let repeatCount = 0;
   for await (const chunk of raceTimeout(iterable, timeoutMs)) {
@@ -17,7 +10,7 @@ async function* guardStream(iterable, opts = {}) {
     if (key === lastChunk && key !== '{}' && key !== 'null') {
       repeatCount++;
       if (repeatCount >= maxRepeats) {
-        throw new GeminiError(`Same chunk repeated ${maxRepeats} times`, { retryable: false });
+        throw new BridgeError(`Same chunk repeated ${maxRepeats} times`, { retryable: false });
       }
     } else {
       lastChunk = key;
@@ -32,11 +25,11 @@ async function* raceTimeout(iterable, ms) {
   while (true) {
     const result = await Promise.race([
       iter.next(),
-      new Promise((_, reject) => setTimeout(() => reject(new TimeoutError(ms)), ms))
+      new Promise((_, reject) => setTimeout(() => reject(new TimeoutError(`Stream chunk timeout after ${ms}ms`)), ms))
     ]);
     if (result.done) return;
     yield result.value;
   }
 }
 
-module.exports = { guardStream, TimeoutError };
+module.exports = { guardStream };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thebird",
-  "version": "1.2.73",
+  "version": "1.2.74",
   "description": "Anthropic SDK to Gemini streaming bridge — drop-in proxy that translates Anthropic message format and tool calls to Google Gemini",
   "scripts": {
     "start": "node serve.js"