create-byan-agent 2.9.4 → 2.9.5

package/src/loadbalancer/capability-matrix.js

@@ -0,0 +1,157 @@
+/**
+ * CapabilityMatrix — Provider Feature Parity Routing
+ *
+ * Maps which tools/capabilities each provider supports.
+ * Routes capability-specific tasks to the right provider.
+ * Degrades gracefully when target provider lacks a capability.
+ */
+
+const DEFAULT_CAPABILITIES = {
+  claude: {
+    file_edit: true,
+    file_read: true,
+    bash: true,
+    web_search: false,
+    mcp_tools: true,
+    subagents: true,
+    git: true,
+    streaming: true,
+    multi_turn: true,
+    max_context_tokens: 200000,
+    tool_use: true,
+    image_input: true,
+  },
+  copilot: {
+    file_edit: true,
+    file_read: true,
+    bash: true,
+    web_search: true,
+    mcp_tools: true,
+    subagents: true,
+    git: true,
+    streaming: true,
+    multi_turn: true,
+    max_context_tokens: 128000,
+    tool_use: true,
+    image_input: true,
+  },
+  byan_api: {
+    file_edit: false,
+    file_read: false,
+    bash: false,
+    web_search: false,
+    mcp_tools: false,
+    subagents: false,
+    git: false,
+    streaming: false,
+    multi_turn: true,
+    max_context_tokens: 32000,
+    tool_use: false,
+    image_input: false,
+  },
+};
+
+class CapabilityMatrix {
+  /**
+   * @param {object} [overrides] - Per-provider capability overrides
+   */
+  constructor(overrides = {}) {
+    this.matrix = {};
+
+    for (const [provider, caps] of Object.entries(DEFAULT_CAPABILITIES)) {
+      this.matrix[provider] = { ...caps, ...(overrides[provider] || {}) };
+    }
+
+    for (const [provider, caps] of Object.entries(overrides)) {
+      if (!this.matrix[provider]) {
+        this.matrix[provider] = caps;
+      }
+    }
+  }
+
+  /**
+   * Check if a provider supports a specific capability.
+   * @param {string} provider
+   * @param {string} capability
+   * @returns {boolean}
+   */
+  supports(provider, capability) {
+    return !!(this.matrix[provider]?.[capability]);
+  }
+
+  /**
+   * Get all capabilities for a provider.
+   * @param {string} provider
+   * @returns {object|null}
+   */
+  getCapabilities(provider) {
+    return this.matrix[provider] || null;
+  }
+
+  /**
+   * Find providers that support a required capability.
+   * @param {string} capability
+   * @returns {string[]} Provider names that support it
+   */
+  findProviders(capability) {
+    return Object.entries(this.matrix)
+      .filter(([, caps]) => caps[capability])
+      .map(([name]) => name);
+  }
+
+  /**
+   * Find the best provider for a set of required capabilities.
+   * @param {string[]} required - Required capability names
+   * @param {string[]} preferOrder - Preferred provider order
+   * @returns {{ provider: string|null, supported: string[], missing: string[] }}
+   */
+  findBestProvider(required, preferOrder = []) {
+    let bestMatch = null;
+    let bestScore = -1;
+
+    const candidates = preferOrder.length > 0
+      ? preferOrder
+      : Object.keys(this.matrix);
+
+    for (const provider of candidates) {
+      const caps = this.matrix[provider];
+      if (!caps) continue;
+
+      const supported = required.filter(cap => caps[cap]);
+      const score = supported.length;
+
+      if (score > bestScore) {
+        bestScore = score;
+        bestMatch = {
+          provider,
+          supported,
+          missing: required.filter(cap => !caps[cap]),
+        };
+      }
+
+      if (score === required.length) break;
+    }
+
+    return bestMatch || { provider: null, supported: [], missing: required };
+  }
+
+  /**
+   * Get a comparison table of all providers.
+   * @returns {object} { capabilities: string[], providers: { name: { cap: bool } } }
+   */
+  compare() {
+    const allCaps = new Set();
+    for (const caps of Object.values(this.matrix)) {
+      for (const key of Object.keys(caps)) {
+        allCaps.add(key);
+      }
+    }
+
+    return {
+      capabilities: [...allCaps].sort(),
+      providers: { ...this.matrix },
+    };
+  }
+}
+
+module.exports = { CapabilityMatrix, DEFAULT_CAPABILITIES };

package/src/loadbalancer/config.js

@@ -0,0 +1,141 @@
+/**
+ * LoadBalancer Configuration Loader
+ *
+ * Loads loadbalancer.yaml, merges with defaults, resolves env vars.
+ * Config resolution order:
+ *   1. loadbalancer.default.yaml (bundled defaults)
+ *   2. {project-root}/_byan/loadbalancer.yaml (user overrides)
+ *   3. Environment variables (BYAN_LB_PRIMARY, etc.)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+const DEFAULT_CONFIG_PATH = path.join(__dirname, 'loadbalancer.default.yaml');
+
+function deepMerge(target, source) {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    if (
+      source[key] &&
+      typeof source[key] === 'object' &&
+      !Array.isArray(source[key]) &&
+      target[key] &&
+      typeof target[key] === 'object' &&
+      !Array.isArray(target[key])
+    ) {
+      result[key] = deepMerge(target[key], source[key]);
+    } else {
+      result[key] = source[key];
+    }
+  }
+  return result;
+}
+
+function loadYaml(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  const content = fs.readFileSync(filePath, 'utf8');
+  return yaml.load(content);
+}
+
+function resolveEnvOverrides(config) {
+  const envMap = {
+    BYAN_LB_PRIMARY: 'primary',
+    BYAN_LB_PORT: 'mcp_server.port',
+    BYAN_LB_HOST: 'mcp_server.host',
+    BYAN_LB_LOG_LEVEL: 'logging.level',
+  };
+
+  for (const [envKey, configPath] of Object.entries(envMap)) {
+    const val = process.env[envKey];
+    if (val === undefined) continue;
+
+    const parts = configPath.split('.');
+    let target = config;
+    for (let i = 0; i < parts.length - 1; i++) {
+      if (!target[parts[i]]) target[parts[i]] = {};
+      target = target[parts[i]];
+    }
+
+    const lastKey = parts[parts.length - 1];
+    target[lastKey] = isNaN(val) ? val : Number(val);
+  }
+
+  return config;
+}
+
+function validateConfig(config) {
+  const errors = [];
+
+  if (!config.providers || typeof config.providers !== 'object') {
+    errors.push('providers: must be an object with at least one provider');
+  }
+
+  if (!config.primary) {
+    errors.push('primary: must specify a primary provider');
+  } else if (!config.providers?.[config.primary]) {
+    errors.push(`primary: provider "${config.primary}" not found in providers`);
+  }
+
+  if (!Array.isArray(config.fallback_order)) {
+    errors.push('fallback_order: must be an array');
+  }
+
+  const rl = config.rate_limits;
+  if (rl) {
+    if (typeof rl.window_ms !== 'number' || rl.window_ms <= 0) {
+      errors.push('rate_limits.window_ms: must be a positive number');
+    }
+    if (typeof rl.max_429_in_window !== 'number' || rl.max_429_in_window <= 0) {
+      errors.push('rate_limits.max_429_in_window: must be a positive number');
+    }
+  }
+
+  return errors;
+}
+
+function loadConfig(projectRoot) {
+  const defaults = loadYaml(DEFAULT_CONFIG_PATH) || {};
+
+  const userConfigPath = path.join(projectRoot, '_byan', 'loadbalancer.yaml');
+  const userConfig = loadYaml(userConfigPath) || {};
+
+  let config = deepMerge(defaults, userConfig);
+  config = resolveEnvOverrides(config);
+
+  const errors = validateConfig(config);
+  if (errors.length > 0) {
+    throw new Error(`LoadBalancer config validation failed:\n  - ${errors.join('\n  - ')}`);
+  }
+
+  config._resolved = {
+    projectRoot,
+    configSources: [
+      DEFAULT_CONFIG_PATH,
+      ...(fs.existsSync(userConfigPath) ? [userConfigPath] : []),
+    ],
+  };
+
+  return config;
+}
+
+function getEnabledProviders(config) {
+  return Object.entries(config.providers)
+    .filter(([, p]) => p.enabled !== false)
+    .map(([name, p]) => ({ name, ...p }));
+}
+
+function getProviderOrder(config) {
+  const order = [config.primary, ...config.fallback_order];
+  return order.filter(name => config.providers[name]?.enabled !== false);
+}
+
+module.exports = {
+  loadConfig,
+  validateConfig,
+  getEnabledProviders,
+  getProviderOrder,
+  deepMerge,
+  DEFAULT_CONFIG_PATH,
+};

package/src/loadbalancer/graceful-degradation.js

@@ -0,0 +1,212 @@
+/**
+ * GracefulDegradation — Queue + Backoff When All Providers Rate-Limited
+ *
+ * When no provider can accept requests:
+ *   1. Queue pending tasks by priority (P1 > P2 > P3)
+ *   2. Exponential backoff (1s, 2s, 4s, 8s... cap 60s)
+ *   3. Notify user with estimated wait time
+ *   4. Auto-resume when any provider recovers
+ *
+ * Integrates with LoadBalancer via event listeners.
+ */
+
+const { EventEmitter } = require('events');
+
+const PRIORITY = { P1: 1, P2: 2, P3: 3, DEFAULT: 2 };
+const MIN_BACKOFF_MS = 1000;
+const MAX_BACKOFF_MS = 60000;
+
+class GracefulDegradation extends EventEmitter {
+  /**
+   * @param {object} opts
+   * @param {import('./loadbalancer').LoadBalancer} opts.lb
+   */
+  constructor(opts = {}) {
+    super();
+    this.lb = opts.lb;
+    this.queue = [];
+    this.backoffMs = MIN_BACKOFF_MS;
+    this.retryTimer = null;
+    this.processing = false;
+    this.totalQueued = 0;
+    this.totalProcessed = 0;
+    this.totalDropped = 0;
+
+    if (this.lb) {
+      this.lb.on('auto_failover', () => this._onProviderRecovery());
+      this.lb.on('rate_limit_change', (event) => {
+        if (event.to === 'HEALTHY' || event.to === 'RECOVERING') {
+          this._onProviderRecovery();
+        }
+      });
+    }
+  }
+
+  /**
+   * Enqueue a request when all providers are down.
+   * @param {object} request - { prompt, sessionId, preferProvider, priority }
+   * @returns {{ queued: true, position: number, estimatedWaitMs: number }}
+   */
+  enqueue(request) {
+    const priority = PRIORITY[request.priority] || PRIORITY.DEFAULT;
+
+    const entry = {
+      id: `q-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+      request,
+      priority,
+      enqueuedAt: Date.now(),
+      resolve: null,
+      reject: null,
+    };
+
+    const promise = new Promise((resolve, reject) => {
+      entry.resolve = resolve;
+      entry.reject = reject;
+    });
+
+    this.queue.push(entry);
+    this.queue.sort((a, b) => a.priority - b.priority || a.enqueuedAt - b.enqueuedAt);
+    this.totalQueued++;
+
+    const position = this.queue.indexOf(entry) + 1;
+    const estimatedWaitMs = this.backoffMs * position;
+
+    this.emit('enqueued', {
+      id: entry.id,
+      position,
+      estimatedWaitMs,
+      queueSize: this.queue.length,
+    });
+
+    this._scheduleRetry();
+
+    entry.promise = promise;
+    return { queued: true, position, estimatedWaitMs, id: entry.id, promise };
+  }
+
+  /**
+   * Get queue status.
+   */
+  getStatus() {
+    return {
+      queueSize: this.queue.length,
+      backoffMs: this.backoffMs,
+      processing: this.processing,
+      totalQueued: this.totalQueued,
+      totalProcessed: this.totalProcessed,
+      totalDropped: this.totalDropped,
+      items: this.queue.map((e, i) => ({
+        id: e.id,
+        position: i + 1,
+        priority: e.priority,
+        waitingMs: Date.now() - e.enqueuedAt,
+      })),
+    };
+  }
+
+  /**
+   * Drop a queued item by ID.
+   */
+  drop(id) {
+    const idx = this.queue.findIndex(e => e.id === id);
+    if (idx === -1) return false;
+
+    const entry = this.queue.splice(idx, 1)[0];
+    entry.reject(new Error('Request dropped from queue'));
+    this.totalDropped++;
+    return true;
+  }
+
+  /**
+   * Drop all queued items.
+   */
+  dropAll() {
+    for (const entry of this.queue) {
+      entry.reject(new Error('Queue flushed'));
+    }
+    this.totalDropped += this.queue.length;
+    this.queue = [];
+  }
+
+  _scheduleRetry() {
+    if (this.retryTimer || this.processing) return;
+
+    this.retryTimer = setTimeout(() => {
+      this.retryTimer = null;
+      this._processQueue();
+    }, this.backoffMs);
+
+    if (this.retryTimer.unref) this.retryTimer.unref();
+  }
+
+  async _processQueue() {
+    if (this.queue.length === 0 || this.processing) return;
+
+    this.processing = true;
+
+    const entry = this.queue[0];
+
+    try {
+      const result = await this.lb.send(entry.request);
+
+      if (result.rateLimited && result.error) {
+        this._increaseBackoff();
+        this.emit('retry_failed', {
+          id: entry.id,
+          backoffMs: this.backoffMs,
+          queueSize: this.queue.length,
+        });
+        this._scheduleRetry();
+      } else {
+        this.queue.shift();
+        entry.resolve(result);
+        this.totalProcessed++;
+        this.backoffMs = MIN_BACKOFF_MS;
+
+        this.emit('processed', {
+          id: entry.id,
+          provider: result.provider,
+          queueRemaining: this.queue.length,
+        });
+
+        if (this.queue.length > 0) {
+          this._scheduleRetry();
+        }
+      }
+    } catch (err) {
+      this._increaseBackoff();
+      this._scheduleRetry();
+    }
+
+    this.processing = false;
+  }
+
+  _onProviderRecovery() {
+    this.backoffMs = MIN_BACKOFF_MS;
+
+    if (this.retryTimer) {
+      clearTimeout(this.retryTimer);
+      this.retryTimer = null;
+    }
+
+    if (this.queue.length > 0) {
+      this.emit('recovery_detected', { queueSize: this.queue.length });
+      this._processQueue();
+    }
+  }
+
+  _increaseBackoff() {
+    this.backoffMs = Math.min(this.backoffMs * 2, MAX_BACKOFF_MS);
+  }
+
+  destroy() {
+    if (this.retryTimer) {
+      clearTimeout(this.retryTimer);
+      this.retryTimer = null;
+    }
+    this.dropAll();
+    this.removeAllListeners();
+  }
+}
+
+module.exports = { GracefulDegradation, PRIORITY };

package/src/loadbalancer/health-probe.js

@@ -0,0 +1,151 @@
+/**
+ * HealthProbe — Proactive Provider Availability Monitoring
+ *
+ * Periodically pings each provider with a cheap request to detect:
+ *   - Complete unavailability (no response / error)
+ *   - Silent degradation (response time > threshold)
+ *   - Pre-throttle signals (rate limit headers on probe)
+ *
+ * Updates RateLimitTracker proactively before user hits a wall.
+ */
+
+const { EventEmitter } = require('events');
+
+class HealthProbe extends EventEmitter {
+  /**
+   * @param {object} opts
+   * @param {object} opts.providers - { name: ProviderAdapter } map
+   * @param {object} opts.trackers - { name: RateLimitTracker } map
+   * @param {object} [opts.config] - health_probe section from loadbalancer config
+   */
+  constructor(opts) {
+    super();
+    this.providers = opts.providers;
+    this.trackers = opts.trackers || {};
+    this.config = opts.config || {};
+
+    this.intervalMs = this.config.interval_ms || 30000;
+    this.timeoutMs = this.config.timeout_ms || 5000;
+    this.enabled = this.config.enabled !== false;
+
+    this.timer = null;
+    this.probeResults = {};
+    this.running = false;
+  }
+
+  /**
+   * Start periodic health probing.
+   */
+  start() {
+    if (!this.enabled || this.running) return;
+    this.running = true;
+
+    this._probeAll();
+
+    this.timer = setInterval(() => this._probeAll(), this.intervalMs);
+    if (this.timer.unref) this.timer.unref();
+  }
+
+  /**
+   * Stop health probing.
+   */
+  stop() {
+    this.running = false;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  /**
+   * Get latest probe results for all providers.
+   */
+  getResults() {
+    return { ...this.probeResults };
+  }
+
+  /**
+   * Run a single probe against one provider.
+   * @param {string} name - Provider name
+   * @returns {Promise<object>} Probe result
+   */
+  async probeOne(name) {
+    const provider = this.providers[name];
+    if (!provider) {
+      return { provider: name, available: false, error: 'Provider not found' };
+    }
+
+    const start = Date.now();
+
+    try {
+      const available = await Promise.race([
+        provider.isAvailable(),
+        new Promise((_, reject) =>
+          setTimeout(() => reject(new Error('Probe timeout')), this.timeoutMs)
+        ),
+      ]);
+
+      const latencyMs = Date.now() - start;
+
+      const result = {
+        provider: name,
+        available: !!available,
+        latencyMs,
+        degraded: latencyMs > this.timeoutMs * 0.8,
+        probedAt: new Date().toISOString(),
+      };
+
+      this.probeResults[name] = result;
+
+      if (result.degraded && this.trackers[name]) {
+        this.trackers[name].recordHeaders({ 'x-ratelimit-remaining': '5' });
+        this.emit('degradation', { provider: name, latencyMs });
+      }
+
+      if (!result.available && this.trackers[name]) {
+        this.trackers[name].record429({ source: 'health_probe', reason: 'unavailable' });
+        this.emit('unavailable', { provider: name });
+      }
+
+      return result;
+    } catch (err) {
+      const latencyMs = Date.now() - start;
+      const result = {
+        provider: name,
+        available: false,
+        latencyMs,
+        degraded: true,
+        error: err.message,
+        probedAt: new Date().toISOString(),
+      };
+
+      this.probeResults[name] = result;
+
+      if (this.trackers[name]) {
+        this.trackers[name].record429({ source: 'health_probe', reason: err.message });
+      }
+
+      this.emit('probe_error', { provider: name, error: err.message });
+      return result;
+    }
+  }
+
+  async _probeAll() {
+    const names = Object.keys(this.providers);
+    const results = await Promise.allSettled(
+      names.map(name => this.probeOne(name))
+    );
+
+    this.emit('probe_cycle', {
+      results: results.map(r => r.value || r.reason),
+      timestamp: new Date().toISOString(),
+    });
+  }
+
+  destroy() {
+    this.stop();
+    this.removeAllListeners();
+  }
+}
+
+module.exports = { HealthProbe };

package/src/loadbalancer/hooks/claude-hooks.js

@@ -0,0 +1,53 @@
+/**
+ * Claude Hooks — Rate Limit Detection for Claude Agent SDK
+ *
+ * Integrates with Claude Agent SDK hooks (PostToolUseFailure, Stop)
+ * to detect rate limit errors and feed them to RateLimitTracker.
+ */
+
+/**
+ * Create Claude hook handlers that report rate limits to the tracker.
+ * @param {import('../rate-limit-tracker').RateLimitTracker} tracker
+ * @returns {object} Hook configuration for Claude Agent SDK
+ */
+function createClaudeHooks(tracker) {
+  return {
+    PostToolUseFailure: [
+      {
+        matcher: { toolName: '*' },
+        callback: (event) => {
+          const error = event.error || {};
+          const isRateLimit =
+            error.name === 'RateLimitError' ||
+            error.status === 429 ||
+            (error.message && error.message.includes('rate_limit'));
+
+          if (isRateLimit) {
+            const retryAfter = error.headers?.['retry-after'] || error.retryAfter;
+            tracker.record429({
+              source: 'claude-hook',
+              toolName: event.toolName,
+              retryAfter,
+            });
+          }
+        },
+      },
+    ],
+
+    Stop: [
+      {
+        matcher: {},
+        callback: (event) => {
+          const reason = event.reason || '';
+          if (reason.includes('rate_limit') || reason.includes('overloaded')) {
+            tracker.record429({ source: 'claude-stop', reason });
+          } else {
+            tracker.recordSuccess();
+          }
+        },
+      },
+    ],
+  };
+}
+
+module.exports = { createClaudeHooks };