lazyclaw 3.88.0

package/logger.mjs

@@ -0,0 +1,55 @@
+// Tiny structured logger — JSON-line output, level-gated, no transitive deps.
+//
+// Why not pino/winston: a single dep would dwarf the entire CLI. JSON-line
+// is the de-facto observability format (jq-friendly, ingestible by every
+// log shipper) and an 80-line module covers our needs.
+//
+// Levels: debug < info < warn < error. Setting LAZYCLAW_LOG_LEVEL=warn
+// silences info+debug. The default (info) keeps user-meaningful events
+// without per-request noise; the daemon's access log lives at info so
+// it's on by default once the logger is wired.
+
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+
+function levelToNum(name) {
+  const n = LEVELS[String(name || '').toLowerCase()];
+  return Number.isFinite(n) ? n : LEVELS.info;
+}
+
+/**
+ * Build a logger. The `sink` callback receives the JSON string per
+ * record so tests can capture without monkey-patching process.stderr.
+ *
+ * @param {{ level?: string, sink?: (line: string) => void, base?: object, now?: () => number }} [opts]
+ */
+export function createLogger(opts = {}) {
+  const minLevel = levelToNum(opts.level);
+  const sink = opts.sink || ((line) => { process.stderr.write(line + '\n'); });
+  const now = opts.now || (() => Date.now());
+  const base = opts.base || {};
+
+  const log = (level, msg, fields) => {
+    if (LEVELS[level] < minLevel) return;
+    const record = {
+      ts: new Date(now()).toISOString(),
+      level,
+      msg,
+      ...base,
+      ...(fields || {}),
+    };
+    sink(JSON.stringify(record));
+  };
+
+  return {
+    minLevel,
+    debug: (msg, fields) => log('debug', msg, fields),
+    info:  (msg, fields) => log('info',  msg, fields),
+    warn:  (msg, fields) => log('warn',  msg, fields),
+    error: (msg, fields) => log('error', msg, fields),
+    child(extraBase) {
+      return createLogger({ ...opts, base: { ...base, ...extraBase } });
+    },
+  };
+}
+
+export { LEVELS, levelToNum };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "lazyclaw",
+  "version": "3.88.0",
+  "description": "Lazy, elegant terminal CLI for chatting with Claude / OpenAI / Gemini / Ollama and orchestrating multi-step LLM workflows. Banner-on-launch, slash-command ghost autocomplete, persistent sessions, local HTTP gateway.",
+  "keywords": [
+    "claude",
+    "anthropic",
+    "openai",
+    "gemini",
+    "ollama",
+    "llm",
+    "cli",
+    "repl",
+    "chatbot",
+    "workflow",
+    "agent"
+  ],
+  "homepage": "https://github.com/cmblir/LazyClaude",
+  "bugs": {
+    "url": "https://github.com/cmblir/LazyClaude/issues"
+  },
+  "license": "MIT",
+  "author": "cmblir",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cmblir/LazyClaude.git",
+    "directory": "src/lazyclaw"
+  },
+  "type": "module",
+  "main": "cli.mjs",
+  "bin": {
+    "lazyclaw": "cli.mjs"
+  },
+  "files": [
+    "cli.mjs",
+    "daemon.mjs",
+    "sessions.mjs",
+    "skills.mjs",
+    "logger.mjs",
+    "ratelimit.mjs",
+    "config-validate.mjs",
+    "rates-validate.mjs",
+    "providers/",
+    "workflow/",
+    "web/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/providers/anthropic.mjs

@@ -0,0 +1,313 @@
+// Real Anthropic Messages API streaming provider for LazyClaw chat.
+//
+// Why a separate file from registry.mjs:
+//   - registry.mjs hosts the *interface* and the offline mock used by the
+//     phase 3 acceptance tests. Real network code belongs next to its own
+//     unit tests so the mock surface in registry stays trivial.
+//
+// SSE parsing strategy:
+//   - The Messages API streams `event: ... \n data: ... \n\n` blocks. We
+//     read the body as Uint8Array chunks, accumulate into a buffer, split
+//     on the blank-line boundary, and yield the `text_delta` payloads.
+//   - We tolerate both a Web ReadableStream body and a Node Readable body
+//     (so this works in Node 22+ fetch and in Playwright's injected fetch).
+//
+// Test seam:
+//   - opts.fetch overrides globalThis.fetch. The phase 6 test injects a
+//     fake fetch returning a hand-rolled SSE ReadableStream. Real code
+//     defaults to globalThis.fetch.
+
+const ANTHROPIC_VERSION = '2023-06-01';
+const DEFAULT_MAX_TOKENS = 4096;
+
+class InvalidApiKeyError extends Error {
+  constructor(message = 'invalid x-api-key') {
+    super(message);
+    this.name = 'InvalidApiKeyError';
+    this.code = 'INVALID_KEY';
+  }
+}
+
+class AbortError extends Error {
+  constructor(message = 'aborted') {
+    super(message);
+    this.name = 'AbortError';
+    this.code = 'ABORT';
+  }
+}
+
+class RateLimitError extends Error {
+  constructor(retryAfterMs, body = '') {
+    super(`anthropic api 429: rate limited (retry-after ${retryAfterMs}ms)`);
+    this.name = 'RateLimitError';
+    this.code = 'RATE_LIMIT';
+    this.status = 429;
+    this.retryAfterMs = retryAfterMs;
+    this.body = body;
+  }
+}
+
+class ApiError extends Error {
+  constructor(status, body) {
+    super(`anthropic api ${status}: ${body.slice(0, 200)}`);
+    this.name = 'AnthropicApiError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+function parseRetryAfterMs(headers) {
+  // Headers may be a Headers instance or a plain object. Accept both.
+  let raw = null;
+  if (headers && typeof headers.get === 'function') raw = headers.get('retry-after') || headers.get('Retry-After');
+  else if (headers) raw = headers['retry-after'] || headers['Retry-After'];
+  if (!raw) return 1000;
+  // Either seconds (e.g. "30") or an HTTP-date (e.g. "Wed, 21 Oct 2026 07:28:00 GMT").
+  const asInt = parseInt(String(raw), 10);
+  if (!Number.isNaN(asInt)) return Math.max(0, asInt * 1000);
+  const date = Date.parse(String(raw));
+  if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+  return 1000;
+}
+
+async function* iterateBody(body) {
+  // Web ReadableStream
+  if (body && typeof body.getReader === 'function') {
+    const reader = body.getReader();
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      if (value) yield value;
+    }
+    return;
+  }
+  // Node Readable (async iterator)
+  if (body && typeof body[Symbol.asyncIterator] === 'function') {
+    for await (const chunk of body) yield chunk;
+    return;
+  }
+  // Already a string / buffer (test convenience)
+  if (typeof body === 'string') {
+    yield new TextEncoder().encode(body);
+    return;
+  }
+  if (body instanceof Uint8Array) {
+    yield body;
+    return;
+  }
+  throw new Error('anthropic: response body is not iterable');
+}
+
+function* parseSseFrames(buffer) {
+  // Yields { event, data } per complete frame; advances the caller's
+  // buffer cursor to the byte right after each consumed frame. We
+  // implement this as a generator that returns the leftover buffer too.
+  let cursor = 0;
+  while (true) {
+    const sep = buffer.indexOf('\n\n', cursor);
+    if (sep < 0) break;
+    const frame = buffer.slice(cursor, sep);
+    cursor = sep + 2;
+    let event = 'message';
+    const dataLines = [];
+    for (const line of frame.split('\n')) {
+      if (line.startsWith('event:')) event = line.slice(6).trim();
+      else if (line.startsWith('data:')) dataLines.push(line.slice(5).trim());
+    }
+    if (dataLines.length > 0) {
+      yield { event, data: dataLines.join('\n'), nextCursor: cursor };
+    } else {
+      yield { event, data: '', nextCursor: cursor };
+    }
+  }
+  return cursor;
+}
+
+export const anthropicProvider = {
+  name: 'anthropic',
+  /**
+   * @param {Array<{role:string,content:string}>} messages
+   * @param {{apiKey?:string, model?:string, fetch?:typeof fetch, maxTokens?:number, system?:string}} opts
+   */
+  async *sendMessage(messages, opts = {}) {
+    if (!opts.apiKey) throw new InvalidApiKeyError('missing api key');
+    const fetchFn = opts.fetch || globalThis.fetch;
+    if (!fetchFn) throw new Error('anthropic: no fetch implementation available');
+
+    const model = opts.model || 'claude-opus-4-7';
+    const apiMessages = messages
+      .filter(m => m.role === 'user' || m.role === 'assistant')
+      .map(m => ({ role: m.role, content: String(m.content ?? '') }));
+
+    const body = {
+      model,
+      max_tokens: opts.maxTokens || DEFAULT_MAX_TOKENS,
+      stream: true,
+      messages: apiMessages,
+    };
+    const sys = opts.system || messages.find(m => m.role === 'system')?.content;
+    if (sys) {
+      // Prompt caching: when opts.cache is truthy, mark the system prompt
+      // as ephemeral-cacheable so repeated calls with the same system
+      // prefix only pay full input cost once. The Messages API expects
+      // an array of text blocks here, so we lift the string into one.
+      if (opts.cache) {
+        body.system = [{ type: 'text', text: String(sys), cache_control: { type: 'ephemeral' } }];
+      } else {
+        body.system = sys;
+      }
+    }
+    // Extended thinking. opts.thinking: { enabled?: boolean, budgetTokens?: number }.
+    // The thinking field is opt-in; when budget is set we always treat it as enabled
+    // because the API rejects budget without a corresponding type.
+    if (opts.thinking && (opts.thinking.enabled || opts.thinking.budgetTokens)) {
+      body.thinking = {
+        type: 'enabled',
+        budget_tokens: opts.thinking.budgetTokens || 1024,
+      };
+    }
+    // Tool-use is passthrough only: opts.tools forwards to the request
+    // body, but execution is the caller's responsibility. We surface
+    // assembled tool_use blocks via opts.onToolUse — the iterator itself
+    // continues to yield only text deltas so existing callers don't
+    // break.
+    if (Array.isArray(opts.tools) && opts.tools.length > 0) {
+      body.tools = opts.tools;
+      if (opts.toolChoice) body.tool_choice = opts.toolChoice;
+    }
+
+    // Honor opts.signal (AbortSignal) so callers can cancel mid-stream.
+    // Both the fetch itself and the body iterator check the signal — fetch
+    // for in-flight aborts, the iterator so a cancel between bytes also
+    // surfaces immediately rather than waiting for the next chunk.
+    if (opts.signal?.aborted) throw new AbortError('aborted before request');
+
+    const res = await fetchFn('https://api.anthropic.com/v1/messages', {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'x-api-key': opts.apiKey,
+        'anthropic-version': ANTHROPIC_VERSION,
+      },
+      body: JSON.stringify(body),
+      signal: opts.signal,
+    });
+
+    if (!res.ok) {
+      const text = typeof res.text === 'function' ? await res.text() : '';
+      if (res.status === 401 || res.status === 403) throw new InvalidApiKeyError(text || 'unauthorized');
+      if (res.status === 429) throw new RateLimitError(parseRetryAfterMs(res.headers), text || '');
+      throw new ApiError(res.status, text || '');
+    }
+
+    // Stream-mode TextDecoder so UTF-8 sequences split across network
+    // chunk boundaries decode correctly. Without {stream:true} a multi-byte
+    // codepoint that lands across two reads would surface as U+FFFD.
+    const decoder = new TextDecoder('utf-8', { fatal: false });
+    let buffer = '';
+    // Tool-use blocks are emitted via content_block_start (with the name
+    // + tool_use_id) followed by N content_block_delta frames carrying
+    // input_json_delta partials. We accumulate per index; at content_block_stop
+    // we hand the assembled object to opts.onToolUse.
+    const openToolBlocks = new Map();
+    // Usage accumulator. The Messages API splits totals across two events:
+    //   message_start  → message.usage.{input_tokens, cache_creation_input_tokens, cache_read_input_tokens}
+    //   message_delta  → usage.output_tokens (final)
+    // We collect both and emit a single opts.onUsage call right before
+    // we return on message_stop.
+    let usage = null;
+    for await (const chunk of iterateBody(res.body)) {
+      if (opts.signal?.aborted) throw new AbortError('aborted mid-stream');
+      buffer += typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true });
+      let consumed = 0;
+      for (const frame of parseSseFrames(buffer)) {
+        consumed = frame.nextCursor;
+        if (frame.event === 'message_start' && frame.data) {
+          try {
+            const obj = JSON.parse(frame.data);
+            const u = obj?.message?.usage;
+            if (u) {
+              usage = {
+                inputTokens: u.input_tokens ?? null,
+                outputTokens: u.output_tokens ?? null,
+                cacheCreationInputTokens: u.cache_creation_input_tokens ?? null,
+                cacheReadInputTokens: u.cache_read_input_tokens ?? null,
+              };
+            }
+          } catch { /* skip malformed */ }
+        } else if (frame.event === 'message_delta' && frame.data) {
+          try {
+            const obj = JSON.parse(frame.data);
+            const u = obj?.usage;
+            if (u && usage) {
+              // message_delta carries the final output_tokens — overwrite
+              // the input-side initial value with the canonical total.
+              if (Number.isFinite(u.output_tokens)) usage.outputTokens = u.output_tokens;
+            } else if (u) {
+              usage = { inputTokens: null, outputTokens: u.output_tokens ?? null, cacheCreationInputTokens: null, cacheReadInputTokens: null };
+            }
+          } catch { /* skip malformed */ }
+        } else if (frame.event === 'content_block_start' && frame.data) {
+          try {
+            const obj = JSON.parse(frame.data);
+            if (obj?.content_block?.type === 'tool_use') {
+              openToolBlocks.set(obj.index, {
+                id: obj.content_block.id,
+                name: obj.content_block.name,
+                inputJson: '',
+              });
+            }
+          } catch { /* skip malformed */ }
+        } else if (frame.event === 'content_block_delta' && frame.data) {
+          try {
+            const obj = JSON.parse(frame.data);
+            const delta = obj?.delta || {};
+            if (delta.type === 'text_delta' && delta.text) {
+              yield delta.text;
+            } else if (delta.type === 'thinking_delta' && delta.thinking && typeof opts.onThinking === 'function') {
+              try { opts.onThinking(delta.thinking); } catch { /* never let a callback abort the stream */ }
+            } else if (delta.type === 'input_json_delta' && typeof delta.partial_json === 'string') {
+              const t = openToolBlocks.get(obj.index);
+              if (t) t.inputJson += delta.partial_json;
+            } else if (delta.text) {
+              yield delta.text;
+            }
+          } catch {
+            // Ignore malformed frame; the buffer may still contain valid frames.
+          }
+        } else if (frame.event === 'content_block_stop' && frame.data) {
+          try {
+            const obj = JSON.parse(frame.data);
+            const t = openToolBlocks.get(obj.index);
+            if (t) {
+              openToolBlocks.delete(obj.index);
+              if (typeof opts.onToolUse === 'function') {
+                let input = {};
+                try { input = t.inputJson ? JSON.parse(t.inputJson) : {}; }
+                catch { /* malformed input → pass empty + raw for caller to inspect */ }
+                try { opts.onToolUse({ id: t.id, name: t.name, input, raw: t.inputJson }); }
+                catch { /* never let a callback abort the stream */ }
+              }
+            }
+          } catch { /* skip malformed */ }
+        } else if (frame.event === 'message_stop') {
+          if (usage && typeof opts.onUsage === 'function') {
+            try { opts.onUsage(usage); } catch { /* never let a callback abort */ }
+          }
+          return;
+        } else if (frame.event === 'error' && frame.data) {
+          let parsed = null;
+          try { parsed = JSON.parse(frame.data); } catch { /* keep raw */ }
+          const message = parsed?.error?.message || frame.data;
+          throw new ApiError(500, message);
+        }
+      }
+      if (consumed > 0) buffer = buffer.slice(consumed);
+    }
+    // Flush any pending bytes the streaming decoder was still holding.
+    const tail = decoder.decode();
+    if (tail) buffer += tail;
+  },
+};
+
+export { InvalidApiKeyError, ApiError, AbortError, RateLimitError };

package/providers/cache.mjs

@@ -0,0 +1,132 @@
+// Response cache decorator for providers — opt-in, in-memory, LRU.
+//
+// Why a decorator and not a per-provider option:
+//   - Same reasoning as withRateLimitRetry / withFallback: caching is
+//     *policy* (caller decides how aggressive), not transport. The
+//     providers themselves stay pure async iterators over a single call.
+//   - A single decorator works across every concrete provider — anthropic,
+//     openai, ollama, gemini, mock — without each having to grow its own
+//     cache machinery.
+//
+// Hashing strategy:
+//   - JSON-stringify the messages + model + cache-relevant opts and SHA-256
+//     it. We use a stable property order (Object.keys.sort) so that
+//     `{a:1,b:2}` and `{b:2,a:1}` hash identically — JSON.stringify alone
+//     respects insertion order, which would cause spurious misses.
+//   - opts that don't affect the response (signal, fetch, onThinking,
+//     onToolUse) are excluded from the hash on purpose.
+//
+// LRU + TTL:
+//   - On every hit/miss we touch the entry's recency. Eviction at
+//     maxEntries removes the oldest. TTL wins over LRU — an entry
+//     past its ttlMs is dropped before being treated as a hit.
+//
+// Streaming semantics:
+//   - On a hit, the wrapper replays the cached chunks via the same
+//     async-iterable shape callers expect. We don't re-introduce
+//     the original delays — the cache is a perf feature.
+//   - On a miss, we stream-through (yield each chunk as it arrives)
+//     and accumulate into a buffer. The buffer lands in the cache
+//     only when the source iterator completes successfully. Errors
+//     and aborts mid-stream do not poison the cache.
+
+import crypto from 'node:crypto';
+
+const DEFAULT_MAX_ENTRIES = 256;
+const DEFAULT_TTL_MS = 60 * 60 * 1000;  // 1 hour
+
+function stableStringify(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return '[' + value.map(stableStringify).join(',') + ']';
+  const keys = Object.keys(value).sort();
+  return '{' + keys.map(k => JSON.stringify(k) + ':' + stableStringify(value[k])).join(',') + '}';
+}
+
+function hashKey(messages, model, opts) {
+  const cacheable = {
+    messages,
+    model: model || null,
+    thinking: opts?.thinking || null,
+    system: opts?.system || null,
+    tools: opts?.tools || null,
+    toolChoice: opts?.toolChoice || null,
+  };
+  return crypto.createHash('sha256').update(stableStringify(cacheable)).digest('hex');
+}
+
+/**
+ * @typedef {{ chunks: string[], expiresAt: number }} CacheEntry
+ */
+
+/**
+ * Wrap a provider so identical calls are served from an in-memory cache.
+ *
+ * @param {{ name: string, sendMessage: Function }} provider
+ * @param {{
+ *   maxEntries?: number,
+ *   ttlMs?: number,
+ *   now?: () => number,
+ *   onHit?: (info: { keyHash: string, size: number }) => void,
+ *   onMiss?: (info: { keyHash: string }) => void,
+ * }} [opts]
+ */
+export function withResponseCache(provider, opts = {}) {
+  const maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
+  const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+  const now = opts.now ?? (() => Date.now());
+  const onHit = typeof opts.onHit === 'function' ? opts.onHit : null;
+  const onMiss = typeof opts.onMiss === 'function' ? opts.onMiss : null;
+  /** @type {Map<string, CacheEntry>} */
+  const cache = new Map();
+  let hits = 0;
+  let misses = 0;
+
+  const touch = (key, entry) => {
+    cache.delete(key);
+    cache.set(key, entry);
+  };
+
+  return {
+    name: `${provider.name}+cache`,
+    /** Inspectable counters — useful for benchmarks and dashboards. */
+    cacheStats() { return { hits, misses, size: cache.size, maxEntries }; },
+    cacheClear() { cache.clear(); hits = 0; misses = 0; },
+    async *sendMessage(messages, sendOpts = {}) {
+      const key = hashKey(messages, sendOpts.model, sendOpts);
+      const cached = cache.get(key);
+      if (cached && cached.expiresAt > now()) {
+        hits += 1;
+        touch(key, cached);
+        if (onHit) { try { onHit({ keyHash: key, size: cache.size }); } catch { /* swallow */ } }
+        for (const chunk of cached.chunks) yield chunk;
+        return;
+      }
+      misses += 1;
+      if (onMiss) { try { onMiss({ keyHash: key }); } catch { /* swallow */ } }
+      // Drop expired entry if we found one
+      if (cached) cache.delete(key);
+
+      const captured = [];
+      try {
+        for await (const chunk of provider.sendMessage(messages, sendOpts)) {
+          captured.push(chunk);
+          yield chunk;
+        }
+      } catch (err) {
+        // Don't poison the cache with partial results — a half-stream is
+        // useless to a future caller and would surface as a partial reply.
+        throw err;
+      }
+
+      // Insert. LRU eviction if we're at the cap.
+      while (cache.size >= maxEntries) {
+        const oldestKey = cache.keys().next().value;
+        if (oldestKey === undefined) break;
+        cache.delete(oldestKey);
+      }
+      cache.set(key, { chunks: captured, expiresAt: now() + ttlMs });
+    },
+  };
+}
+
+export { stableStringify, hashKey };

package/providers/fallback.mjs

@@ -0,0 +1,90 @@
+// Auto-fallback wrapper for provider chains.
+//
+// Why a wrapper, not a registry feature:
+//   - Fallback policy is caller-specific. The daemon may want
+//     "anthropic → openai" while a CLI script wants "ollama only" with
+//     no remote fallback at all.
+//   - Wrapping keeps each provider self-contained and testable.
+//
+// Strategy:
+//   - Try providers in order. The first one that yields any chunk
+//     "wins" — we forward its stream and never touch the next one.
+//   - Fall through happens when the active provider throws BEFORE
+//     yielding any chunk. Once a provider has yielded text, we cannot
+//     retry without producing duplicate output, so post-yield errors
+//     bubble unchanged. This mirrors `withRateLimitRetry`.
+//   - Which errors are recoverable is configurable via `opts.shouldFallback`.
+//     Default: every error code except 'INVALID_KEY' (auth errors are
+//     usually structural — falling back doesn't fix them, it just delays
+//     the diagnosis). Callers can pass their own predicate.
+
+const DEFAULT_RECOVERABLE = new Set([
+  'RATE_LIMIT',
+  'CONNECTION_REFUSED',
+  // Generic 5xx surfaces as ApiError without a code; we let the default
+  // predicate fall back on them based on err.status >= 500.
+]);
+
+function defaultShouldFallback(err) {
+  if (!err) return false;
+  if (err.code === 'INVALID_KEY' || err.code === 'ABORT') return false;
+  if (DEFAULT_RECOVERABLE.has(err.code)) return true;
+  // Provider-side ApiError with a 5xx status → fall back.
+  if (Number.isFinite(err.status) && err.status >= 500 && err.status < 600) return true;
+  // Network-layer fetch failures (no status, no code) → fall back.
+  if (!err.code && !err.status) return true;
+  return false;
+}
+
+/**
+ * Wrap a primary provider with a sequence of fallbacks.
+ *
+ * @param {Array<{ name: string, sendMessage: Function }>} chain
+ *   Ordered list — the first provider is the primary. Must have at least one entry.
+ * @param {{
+ *   shouldFallback?: (err: Error) => boolean,
+ *   onFallback?: (info: { from: string, to: string, err: Error }) => void,
+ * }} fallbackOpts
+ */
+export function withFallback(chain, fallbackOpts = {}) {
+  if (!Array.isArray(chain) || chain.length === 0) {
+    throw new Error('withFallback: chain must contain at least one provider');
+  }
+  const shouldFallback = fallbackOpts.shouldFallback || defaultShouldFallback;
+  const onFallback = fallbackOpts.onFallback;
+
+  return {
+    name: `fallback(${chain.map(p => p.name).join('→')})`,
+    async *sendMessage(messages, opts = {}) {
+      let lastErr = null;
+      for (let i = 0; i < chain.length; i++) {
+        const prov = chain[i];
+        let yieldedAny = false;
+        try {
+          for await (const chunk of prov.sendMessage(messages, opts)) {
+            yieldedAny = true;
+            yield chunk;
+          }
+          return;
+        } catch (err) {
+          lastErr = err;
+          // Cannot fall back once we've started yielding — would duplicate text.
+          if (yieldedAny) throw err;
+          // Last provider in the chain — re-throw, no more fallbacks.
+          if (i === chain.length - 1) throw err;
+          // Caller-controlled predicate decides what's worth falling back on.
+          if (!shouldFallback(err)) throw err;
+          if (typeof onFallback === 'function') {
+            try { onFallback({ from: prov.name, to: chain[i + 1].name, err }); }
+            catch { /* swallow */ }
+          }
+        }
+      }
+      // Loop exits only when all providers have been tried; lastErr is set
+      // (we wouldn't have entered the catch otherwise).
+      throw lastErr;
+    },
+  };
+}
+
+export { defaultShouldFallback };