thebird 1.2.73 → 1.2.75

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/CLAUDE.md

@@ -133,14 +133,41 @@ Run examples against real Gemini API to validate message translation.
 - Cannot bundle index.js directly for browser — it imports Node-only modules (oauth.js, config.js, cloud-generate.js) at top level. Create a separate browser entry that imports only lib/client.js, lib/errors.js, lib/convert.js. Use ESM wrapper (not CJS module.exports) to preserve named exports in bundle.
 - Tool parameter types must be lowercase for Gemini API — `object`, `string`, `number` not `OBJECT`, `STRING`, `NUMBER`. Uppercase types fail schema validation.
 - agentGenerate passes raw Anthropic-format messages to streamGemini internally, which calls convertMessages. Do NOT pre-convert in app.js — double-conversion breaks tool schemas.
+- Anthropic format IS the canonical message format — do NOT add an intermediate transformation layer. Direct translation to provider-native formats is cleaner than another abstraction level.
+
+## Error Architecture
+
+**Error hierarchy** (lib/errors.js):
+- `BridgeError(message, { status, code, retryable, provider, headers })` — base class, `GeminiError` alias for backwards compat
+- `AuthError` (401/403), `RateLimitError` (429, retryable), `TimeoutError` (408, retryable), `ContextWindowError` (413), `ContentPolicyError` (451), `ProviderError` (5xx, retryable)
+- `classifyError(status, message, provider)` — factory returns typed error from status code
+- `redactKeys(str)` — masks API keys (AIza, sk-, key- patterns) to `...XXXX`
+- `parseRetryAfterHeader(err)` — standard HTTP Retry-After (seconds + date formats)
+
+**Stream guards** (lib/stream-guard.js):
+- `guardStream(iterable, { chunkTimeoutMs, maxRepeats })` — wraps async iterables
+- Chunk timeout default 30s, repeat threshold default 100
+
+**Circuit breaker** (lib/circuit-breaker.js):
+- `createCircuitBreaker({ maxFailures, cooldownMs })` — per-provider failure tracking
+- Auto-recovery after cooldown, reset on success
+
+**Capabilities** (lib/capabilities.js):
+- `getCapabilities(provider)` — merges provider.capabilities with defaults
+- `stripUnsupported(params, caps)` — removes unsupported features, returns warnings
+- Defaults: streaming, toolUse, vision, systemMessage = true; jsonMode = false
 
 ## Files
 
 - `lib/convert.js`: Message/tool translation logic
 - `lib/client.js`: Provider client factory
-- `lib/errors.js`: Error handling and retry logic
+- `lib/errors.js`: Typed error hierarchy (BridgeError, AuthError, RateLimitError, etc.), classifyError, redactKeys, withRetry
+- `lib/stream-guard.js`: guardStream — chunk timeout and repeated-chunk detection for async iterables
+- `lib/circuit-breaker.js`: Per-provider failure tracking with auto-recovery
+- `lib/capabilities.js`: Provider capability metadata and unsupported feature stripping
+- `lib/router-stream.js`: Router streaming/generation with circuit breaker and capability integration
 - `lib/providers/`: Provider-specific streaming implementations
-- `index.js`: Main entry point, streaming and generation wrappers
+- `index.js`: Main entry point, Gemini streaming/generation, re-exports
 - `index.d.ts`: TypeScript type definitions
 - `examples/`: Working examples using Anthropic SDK format
 - `wasi/cli.ts`: Deno streaming CLI — `deno run --allow-net --allow-env wasi/cli.ts [--model M] [--system S] <prompt>`

package/README.md

@@ -152,6 +152,68 @@ Pass options as a nested array: `["maxtoken", { "max_tokens": 16384 }]`.
 }
 ```
 
+## Error Handling
+
+thebird uses a typed error hierarchy. All errors extend `BridgeError`:
+
+| Error | Status | Retryable | When |
+|---|---|---|---|
+| `AuthError` | 401, 403 | No | Invalid API key |
+| `RateLimitError` | 429 | Yes | Quota exceeded |
+| `TimeoutError` | 408 | Yes | Stream chunk timeout |
+| `ContextWindowError` | 413 | No | Input too long |
+| `ContentPolicyError` | 451 | No | Safety filter triggered |
+| `ProviderError` | 5xx | Yes | Upstream server error |
+
+`GeminiError` is an alias for `BridgeError` (backwards compatible). API keys are auto-redacted in error messages.
+
+```js
+const { classifyError, BridgeError } = require('thebird');
+try { /* ... */ } catch (err) {
+  if (err instanceof BridgeError && err.retryable) { /* retry */ }
+}
+```
+
+## Streaming Resilience
+
+Pass `streamGuard` to protect against stalled or looping streams:
+
+```js
+streamGemini({
+  messages,
+  streamGuard: { chunkTimeoutMs: 30000, maxRepeats: 100 }
+});
+```
+
+- **Chunk timeout** — throws `TimeoutError` if no chunk received within the timeout (default 30s)
+- **Repeat detection** — throws if the same chunk appears consecutively N times (default 100)
+
+## Circuit Breaker
+
+The router tracks per-provider failures. After consecutive failures exceed the threshold, the provider is temporarily skipped:
+
+```js
+createRouter({
+  Providers: [/* ... */],
+  circuitBreaker: { maxFailures: 5, cooldownMs: 60000 }
+});
+```
+
+## Provider Capabilities
+
+Declare what each provider supports. Unsupported features are stripped automatically with warnings:
+
+```json
+{
+  "name": "groq",
+  "api_base_url": "...",
+  "api_key": "$GROQ_API_KEY",
+  "capabilities": { "vision": false, "jsonMode": true }
+}
+```
+
+Defaults: `streaming: true, toolUse: true, vision: true, systemMessage: true, jsonMode: false`.
+
 ## Gemini Direct API
 
 `streamGemini` / `generateGemini` bypass routing and call Gemini natively via `@google/genai`. Requires `GEMINI_API_KEY`.

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.75",
   "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"