@stevederico/dotbot 0.16.0

package/core/events.js

@@ -0,0 +1,229 @@
+/**
+ * SSE Event Schema Definitions
+ *
+ * All events emitted by the agent loop conform to these schemas.
+ * Provider-specific differences are normalized before emission.
+ */
+
+/**
+ * Text delta event - incremental text from the model
+ * @typedef {Object} TextDeltaEvent
+ * @property {'text_delta'} type
+ * @property {string} text - Incremental text chunk
+ */
+
+/**
+ * Thinking event - model's internal reasoning
+ * @typedef {Object} ThinkingEvent
+ * @property {'thinking'} type
+ * @property {string} text - Reasoning text (empty string if no thinking available)
+ * @property {boolean} hasNativeThinking - True if provider natively supports thinking
+ */
+
+/**
+ * Tool start event - tool execution beginning
+ * @typedef {Object} ToolStartEvent
+ * @property {'tool_start'} type
+ * @property {string} name - Tool name
+ * @property {Object} input - Tool input parameters (already parsed)
+ */
+
+/**
+ * Tool result event - tool execution completed successfully
+ * @typedef {Object} ToolResultEvent
+ * @property {'tool_result'} type
+ * @property {string} name - Tool name
+ * @property {Object} input - Tool input parameters
+ * @property {string} result - Tool result (JSON string if object)
+ */
+
+/**
+ * Tool error event - tool execution failed
+ * @typedef {Object} ToolErrorEvent
+ * @property {'tool_error'} type
+ * @property {string} name - Tool name
+ * @property {string} error - Error message
+ */
+
+/**
+ * Done event - agent loop completed
+ * @typedef {Object} DoneEvent
+ * @property {'done'} type
+ * @property {string} content - Final assistant response text
+ */
+
+/**
+ * Max iterations event - loop exhausted iteration limit
+ * @typedef {Object} MaxIterationsEvent
+ * @property {'max_iterations'} type
+ * @property {string} message - Warning message
+ */
+
+/**
+ * Error event - fatal error occurred
+ * @typedef {Object} ErrorEvent
+ * @property {'error'} type
+ * @property {string} error - Error message
+ */
+
+/**
+ * Stats event - token usage statistics (standardized across providers)
+ * @typedef {Object} StatsEvent
+ * @property {'stats'} type
+ * @property {string} model - Model name
+ * @property {number} inputTokens - Input tokens consumed
+ * @property {number} outputTokens - Output tokens generated
+ */
+
+/**
+ * Followup event - suggested followup question
+ * @typedef {Object} FollowupEvent
+ * @property {'followup'} type
+ * @property {string} text - Suggested followup text
+ */
+
+/**
+ * Image event - generated image from tool
+ * @typedef {Object} ImageEvent
+ * @property {'image'} type
+ * @property {string} url - Image URL
+ * @property {string} prompt - Generation prompt
+ */
+
+/**
+ * @typedef {TextDeltaEvent|ThinkingEvent|ToolStartEvent|ToolResultEvent|ToolErrorEvent|DoneEvent|MaxIterationsEvent|ErrorEvent|StatsEvent|FollowupEvent|ImageEvent} AgentEvent
+ */
+
+/**
+ * Validate an event against the schema
+ * @param {AgentEvent} event - Event to validate
+ * @returns {boolean} True if valid
+ * @throws {Error} If validation fails
+ */
+export function validateEvent(event) {
+  if (!event || typeof event !== 'object') {
+    throw new Error('Event must be an object');
+  }
+
+  if (!event.type) {
+    throw new Error('Event must have a type property');
+  }
+
+  switch (event.type) {
+    case 'text_delta':
+      if (typeof event.text !== 'string') {
+        throw new Error('text_delta event must have text string');
+      }
+      break;
+
+    case 'thinking':
+      if (typeof event.text !== 'string') {
+        throw new Error('thinking event must have text string');
+      }
+      if (typeof event.hasNativeThinking !== 'boolean') {
+        throw new Error('thinking event must have hasNativeThinking boolean');
+      }
+      break;
+
+    case 'tool_start':
+      if (typeof event.name !== 'string') {
+        throw new Error('tool_start event must have name string');
+      }
+      if (typeof event.input !== 'object') {
+        throw new Error('tool_start event must have input object');
+      }
+      break;
+
+    case 'tool_result':
+      if (typeof event.name !== 'string') {
+        throw new Error('tool_result event must have name string');
+      }
+      if (typeof event.input !== 'object') {
+        throw new Error('tool_result event must have input object');
+      }
+      if (typeof event.result !== 'string') {
+        throw new Error('tool_result event must have result string');
+      }
+      break;
+
+    case 'tool_error':
+      if (typeof event.name !== 'string') {
+        throw new Error('tool_error event must have name string');
+      }
+      if (typeof event.error !== 'string') {
+        throw new Error('tool_error event must have error string');
+      }
+      break;
+
+    case 'done':
+      if (typeof event.content !== 'string') {
+        throw new Error('done event must have content string');
+      }
+      break;
+
+    case 'max_iterations':
+      if (typeof event.message !== 'string') {
+        throw new Error('max_iterations event must have message string');
+      }
+      break;
+
+    case 'error':
+      if (typeof event.error !== 'string') {
+        throw new Error('error event must have error string');
+      }
+      break;
+
+    case 'stats':
+      if (typeof event.model !== 'string') {
+        throw new Error('stats event must have model string');
+      }
+      if (typeof event.inputTokens !== 'number') {
+        throw new Error('stats event must have inputTokens number');
+      }
+      if (typeof event.outputTokens !== 'number') {
+        throw new Error('stats event must have outputTokens number');
+      }
+      break;
+
+    case 'followup':
+      if (typeof event.text !== 'string') {
+        throw new Error('followup event must have text string');
+      }
+      break;
+
+    case 'compaction':
+      // Compaction events don't have strict schema requirements
+      break;
+
+    case 'image':
+      if (typeof event.url !== 'string') {
+        throw new Error('image event must have url string');
+      }
+      if (typeof event.prompt !== 'string') {
+        throw new Error('image event must have prompt string');
+      }
+      break;
+
+    default:
+      throw new Error(`Unknown event type: ${event.type}`);
+  }
+
+  return true;
+}
+
+/**
+ * Normalize a stats event from provider-specific format to standard format
+ * @param {Object} stats - Raw stats from provider
+ * @param {string} provider - Provider ID ('anthropic', 'openai', 'xai', 'ollama')
+ * @returns {StatsEvent} Standardized stats event
+ */
+export function normalizeStatsEvent(stats, provider) {
+  const isAnthropic = provider === 'anthropic';
+
+  return {
+    type: 'stats',
+    model: stats.model,
+    inputTokens: isAnthropic ? stats.input_tokens : stats.prompt_tokens,
+    outputTokens: isAnthropic ? stats.output_tokens : stats.completion_tokens,
+  };
+}

package/core/failover.js

@@ -0,0 +1,193 @@
+// failover.js
+// Model failover: retry on transient errors, fall back to alternative providers.
+
+import { AI_PROVIDERS } from "../utils/providers.js";
+
+/** Ordered list of cloud providers to try during failover. Local providers excluded. */
+const FALLBACK_ORDER = ['xai', 'anthropic', 'openai'];
+
+/** How long (ms) a failed provider stays cooled down. */
+const COOLDOWN_MS = 5 * 60 * 1000;
+
+/** Default retry delay (ms) when Retry-After header is absent. */
+const DEFAULT_RETRY_DELAY_MS = 1500;
+
+/** HTTP status codes that warrant a retry/failover. */
+const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
+
+/** In-memory cooldown map: providerId -> expiresAt timestamp. Resets on restart. */
+const cooldownMap = new Map();
+
+/**
+ * Custom error thrown when all providers (primary + fallbacks) are exhausted.
+ * @extends Error
+ */
+class FailoverError extends Error {
+  /**
+   * @param {string} message - Error summary.
+   * @param {Array<{provider: string, status: number, body: string}>} attempts - Record of each failed attempt.
+   */
+  constructor(message, attempts) {
+    super(message);
+    this.name = 'FailoverError';
+    this.attempts = attempts;
+  }
+}
+
+/**
+ * Check whether a provider is currently in cooldown.
+ * @param {string} providerId - Provider identifier (e.g. 'anthropic').
+ * @returns {boolean}
+ */
+function isProviderCooledDown(providerId) {
+  const expiresAt = cooldownMap.get(providerId);
+  if (!expiresAt) return false;
+  if (Date.now() >= expiresAt) {
+    cooldownMap.delete(providerId);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Mark a provider as failed, placing it in cooldown for COOLDOWN_MS.
+ * @param {string} providerId - Provider identifier.
+ */
+function markProviderFailed(providerId) {
+  cooldownMap.set(providerId, Date.now() + COOLDOWN_MS);
+}
+
+/**
+ * Sleep for a given duration, respecting an AbortSignal.
+ * @param {number} ms - Milliseconds to sleep.
+ * @param {AbortSignal} [signal] - Optional abort signal.
+ * @returns {Promise<void>}
+ */
+function abortableSleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new DOMException('Aborted', 'AbortError'));
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new DOMException('Aborted', 'AbortError'));
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+/**
+ * Attempt a fetch with retry and cross-provider failover.
+ *
+ * On retryable HTTP errors (429, 5xx): waits Retry-After or 1.5s, retries once.
+ * If still failing: marks the provider cooled down, tries the next cloud provider.
+ * On non-retryable errors (400, 401, 403): throws immediately (no failover).
+ * On all providers exhausted: throws FailoverError with attempts array.
+ *
+ * @param {Object} options
+ * @param {Object} options.provider - Primary provider config from AI_PROVIDERS.
+ * @param {function(Object): {url: string, headers: Object, body: string}} options.buildRequest
+ *   Callback that builds fetch params for any target provider.
+ * @param {AbortSignal} [options.signal] - Optional abort signal.
+ * @param {Object} [options.logger] - Optional logger with .info() and .error().
+ * @returns {Promise<{response: Response, activeProvider: Object}>}
+ *   The successful HTTP response and the provider that served it.
+ * @throws {FailoverError} When all providers are exhausted.
+ * @throws {DOMException} When aborted via signal (name: 'AbortError').
+ */
+async function fetchWithFailover({ provider, buildRequest, signal, logger }) {
+  const attempts = [];
+
+  // Build ordered list: primary first, then fallbacks (skip local, skip duplicates)
+  const providersToTry = [provider];
+  for (const id of FALLBACK_ORDER) {
+    if (id === provider.id) continue;
+    const p = AI_PROVIDERS[id];
+    if (p && !p.local) providersToTry.push(p);
+  }
+
+  for (const targetProvider of providersToTry) {
+    // Skip cooled-down providers (unless it's the primary — always try primary once)
+    if (targetProvider !== provider && isProviderCooledDown(targetProvider.id)) {
+      continue;
+    }
+
+    // Check that the target provider has an API key configured
+    if (targetProvider.envKey && !process.env[targetProvider.envKey]) {
+      continue;
+    }
+
+    const { url, headers, body } = buildRequest(targetProvider);
+    let lastStatus = 0;
+    let lastBody = '';
+
+    // Up to 2 attempts per provider (initial + 1 retry)
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        const response = await fetch(url, {
+          method: 'POST',
+          headers,
+          body,
+          signal,
+        });
+
+        if (response.ok) {
+          return { response, activeProvider: targetProvider };
+        }
+
+        lastStatus = response.status;
+        lastBody = await response.text();
+
+        // Non-retryable — throw immediately, no failover
+        if (!RETRYABLE_STATUSES.has(lastStatus)) {
+          console.error(`[failover] ${targetProvider.name} returned ${lastStatus}`);
+          console.error(`[failover] Error body:`, lastBody);
+          console.error(`[failover] Request URL:`, url);
+          console.error(`[failover] Request body:`, body.slice(0, 500));
+          throw new FailoverError(
+            `${targetProvider.name} returned ${lastStatus}: ${lastBody}`,
+            [{ provider: targetProvider.id, status: lastStatus, body: lastBody }]
+          );
+        }
+
+        // Retryable — wait and retry (only on first attempt)
+        if (attempt === 0) {
+          const retryAfter = response.headers.get('retry-after');
+          const delayMs = retryAfter
+            ? Math.min(parseInt(retryAfter, 10) * 1000 || DEFAULT_RETRY_DELAY_MS, 10000)
+            : DEFAULT_RETRY_DELAY_MS;
+
+          if (logger) {
+            logger.info(`[failover] ${targetProvider.name} returned ${lastStatus}, retrying in ${delayMs}ms`);
+          }
+          await abortableSleep(delayMs, signal);
+        }
+      } catch (err) {
+        // Re-throw abort errors and non-retryable FailoverErrors
+        if (err.name === 'AbortError' || err instanceof FailoverError) throw err;
+
+        // Network error — treat as retryable
+        lastStatus = 0;
+        lastBody = err.message;
+        if (attempt === 0) {
+          await abortableSleep(DEFAULT_RETRY_DELAY_MS, signal);
+        }
+      }
+    }
+
+    // Both attempts failed for this provider
+    attempts.push({ provider: targetProvider.id, status: lastStatus, body: lastBody });
+
+    markProviderFailed(targetProvider.id);
+
+    if (logger) {
+      logger.error(`[failover] ${targetProvider.name} exhausted (${lastStatus}), trying next provider`);
+    }
+  }
+
+  throw new FailoverError('All providers exhausted', attempts);
+}
+
+export { fetchWithFailover, FailoverError };

package/core/gptoss_tool_parser.js

@@ -0,0 +1,173 @@
+/**
+ * Text-Based Tool Call Parser
+ *
+ * Parses tool calls from model output in four formats:
+ *
+ * 1. Instructed format (via system prompt):
+ *    <tool_call>{"name": "tool_name", "arguments": {"key": "value"}}</tool_call>
+ *
+ * 2. Native gpt-oss format (from model fine-tuning):
+ *    commentary to=tool_name json{"key": "value"}
+ *
+ * 3. LFM2.5 native format with markers:
+ *    <|tool_call_start|>[tool_name(arg1="value1")]<|tool_call_end|>
+ *
+ * 4. LFM2.5 bare Pythonic format (markers stripped by mlx_lm.server):
+ *    [tool_name(arg1="value1", arg2="value2")]
+ *
+ * Used when the model doesn't support native OpenAI-style tool calling
+ * (e.g., mlx_lm.server) and tool definitions are injected via system prompt.
+ */
+
+const TOOL_CALL_RE = /<tool_call>([\s\S]*?)<\/tool_call>/g;
+const NATIVE_TOOL_CALL_RE = /commentary\s+to=(\w+)\s+json(\{[\s\S]*?\})(?:\s|$)/g;
+const LFM_TOOL_CALL_RE = /<\|tool_call_start\|>\[(\w+)\(([\s\S]*?)\)\]<\|tool_call_end\|>/g;
+
+// Bare Pythonic: [func_name(key="val")] or [func_name(key='val')]
+// Requires at least one key=quoted_value pair to avoid false positives on markdown links
+const BARE_PYTHONIC_RE = /\[(\w+)\((\w+\s*=\s*(?:"[^"]*"|'[^']*')(?:\s*,\s*\w+\s*=\s*(?:"[^"]*"|'[^']*'|[\w.+-]+))*)\)\]/g;
+
+/**
+ * Detect if text contains tool call markers in any supported format.
+ *
+ * @param {string} text - Model output text
+ * @returns {boolean} True if at least one tool call pattern is found
+ */
+export function hasToolCallMarkers(text) {
+  if (text.includes('<tool_call>') && text.includes('</tool_call>')) return true;
+  if (/commentary\s+to=\w+\s+json\{/.test(text)) return true;
+  if (text.includes('<|tool_call_start|>') && text.includes('<|tool_call_end|>')) return true;
+  // Bare Pythonic: [word(word="...")]
+  if (/\[\w+\(\w+\s*=\s*["']/.test(text)) return true;
+  return false;
+}
+
+/**
+ * Parse Pythonic keyword arguments from LFM tool call format.
+ * Handles: key="value", key='value', key=123, key=true
+ *
+ * @param {string} argsStr - Raw arguments string (e.g., 'location="New York", units="fahrenheit"')
+ * @returns {Object} Parsed key-value pairs
+ */
+function parsePythonicArgs(argsStr) {
+  const args = {};
+  if (!argsStr || !argsStr.trim()) return args;
+
+  // Match key=value pairs where value can be quoted string, number, or boolean
+  const argRe = /(\w+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([\w.+-]+))/g;
+  let m;
+  while ((m = argRe.exec(argsStr)) !== null) {
+    const key = m[1];
+    // Prefer double-quoted, then single-quoted, then unquoted
+    const val = m[2] !== undefined ? m[2] : m[3] !== undefined ? m[3] : m[4];
+    args[key] = val;
+  }
+  return args;
+}
+
+/**
+ * Extract all tool calls from text, returning them in the same shape
+ * that parseOpenAIStream produces so the existing execution loop works unchanged.
+ * Handles four formats: `<tool_call>` XML, gpt-oss `commentary to=`,
+ * LFM `<|tool_call_start|>`, and bare Pythonic `[func(args)]`.
+ *
+ * @param {string} text - Model output containing tool call patterns
+ * @returns {Array<{id: string, function: {name: string, arguments: Object}}>}
+ */
+export function parseToolCalls(text) {
+  const calls = [];
+  let idx = 0;
+
+  // Format 1: <tool_call>{"name":"...","arguments":{...}}</tool_call>
+  TOOL_CALL_RE.lastIndex = 0;
+  let match;
+  while ((match = TOOL_CALL_RE.exec(text)) !== null) {
+    try {
+      const parsed = JSON.parse(match[1].trim());
+      const name = parsed.name || parsed.function;
+      let args = parsed.arguments || parsed.params || parsed.input || {};
+      if (typeof args === 'string') {
+        try { args = JSON.parse(args); } catch {}
+      }
+      calls.push({
+        id: `text_call_${idx}`,
+        function: { name, arguments: args },
+      });
+      idx++;
+    } catch (err) {
+      console.warn('[tool_parser] Failed to parse <tool_call> JSON:', match[1], err.message);
+    }
+  }
+
+  // Format 2: commentary to=TOOL_NAME json{...}  (gpt-oss native)
+  if (calls.length === 0) {
+    NATIVE_TOOL_CALL_RE.lastIndex = 0;
+    while ((match = NATIVE_TOOL_CALL_RE.exec(text)) !== null) {
+      try {
+        const name = match[1];
+        const args = JSON.parse(match[2]);
+        calls.push({
+          id: `native_call_${idx}`,
+          function: { name, arguments: args },
+        });
+        idx++;
+      } catch (err) {
+        console.warn('[tool_parser] Failed to parse native tool call:', match[0], err.message);
+      }
+    }
+  }
+
+  // Format 3: <|tool_call_start|>[func_name(args)]<|tool_call_end|>  (LFM with markers)
+  if (calls.length === 0) {
+    LFM_TOOL_CALL_RE.lastIndex = 0;
+    while ((match = LFM_TOOL_CALL_RE.exec(text)) !== null) {
+      try {
+        const name = match[1];
+        const args = parsePythonicArgs(match[2]);
+        calls.push({
+          id: `lfm_call_${idx}`,
+          function: { name, arguments: args },
+        });
+        idx++;
+      } catch (err) {
+        console.warn('[tool_parser] Failed to parse LFM tool call:', match[0], err.message);
+      }
+    }
+  }
+
+  // Format 4: [func_name(key="val")]  (bare Pythonic, markers stripped by mlx_lm.server)
+  if (calls.length === 0) {
+    BARE_PYTHONIC_RE.lastIndex = 0;
+    while ((match = BARE_PYTHONIC_RE.exec(text)) !== null) {
+      try {
+        const name = match[1];
+        const args = parsePythonicArgs(match[2]);
+        calls.push({
+          id: `lfm_call_${idx}`,
+          function: { name, arguments: args },
+        });
+        idx++;
+      } catch (err) {
+        console.warn('[tool_parser] Failed to parse bare Pythonic tool call:', match[0], err.message);
+      }
+    }
+  }
+
+  return calls;
+}
+
+/**
+ * Remove all tool call patterns from text (all four formats),
+ * leaving only the surrounding natural language content.
+ *
+ * @param {string} text - Model output containing tool call markers
+ * @returns {string} Text with all tool call blocks removed
+ */
+export function stripToolCallMarkers(text) {
+  let cleaned = text;
+  cleaned = cleaned.replace(TOOL_CALL_RE, '');
+  cleaned = cleaned.replace(NATIVE_TOOL_CALL_RE, '');
+  cleaned = cleaned.replace(LFM_TOOL_CALL_RE, '');
+  cleaned = cleaned.replace(BARE_PYTHONIC_RE, '');
+  return cleaned.trim();
+}