create-byan-agent 2.9.4 → 2.9.6

package/src/loadbalancer/providers/base-provider.js

@@ -0,0 +1,80 @@
+/**
+ * BaseProvider — Abstract Provider Interface
+ *
+ * All providers (Copilot, Claude, BYAN API) extend this class.
+ * Defines the contract for the LoadBalancer to interact with any provider.
+ */
+
+class BaseProvider {
+  /**
+   * @param {string} name - Provider identifier (e.g., 'copilot', 'claude')
+   * @param {object} providerConfig - Provider section from loadbalancer config
+   */
+  constructor(name, providerConfig) {
+    if (new.target === BaseProvider) {
+      throw new Error('BaseProvider is abstract — use CopilotProvider or ClaudeProvider');
+    }
+    this.name = name;
+    this.config = providerConfig;
+    this.initialized = false;
+  }
+
+  /**
+   * Initialize the provider (SDK auth, session setup, etc.)
+   */
+  async initialize() {
+    throw new Error(`${this.name}: initialize() not implemented`);
+  }
+
+  /**
+   * Send a prompt and get a response.
+   * @param {object} opts
+   * @param {string} opts.prompt - The user prompt
+   * @param {string} [opts.model] - Model override
+   * @param {string} [opts.sessionId] - Session ID for continuity
+   * @returns {Promise<ProviderResponse>}
+   */
+  async send(opts) {
+    throw new Error(`${this.name}: send() not implemented`);
+  }
+
+  /**
+   * Check if provider is available (auth valid, SDK loaded).
+   * @returns {Promise<boolean>}
+   */
+  async isAvailable() {
+    throw new Error(`${this.name}: isAvailable() not implemented`);
+  }
+
+  /**
+   * Get provider capabilities.
+   * @returns {object} - { streaming, tools, multiTurn, maxContextTokens }
+   */
+  getCapabilities() {
+    return {
+      streaming: false,
+      tools: false,
+      multiTurn: false,
+      maxContextTokens: 0,
+    };
+  }
+
+  /**
+   * Clean up resources.
+   */
+  async destroy() {
+    this.initialized = false;
+  }
+}
+
+/**
+ * @typedef {object} ProviderResponse
+ * @property {string} provider - Provider name
+ * @property {string} content - Response text
+ * @property {string} model - Model used
+ * @property {object} [rateLimitHeaders] - Raw rate limit headers if available
+ * @property {number} latencyMs - Round-trip time in ms
+ * @property {boolean} rateLimited - Whether a 429 was encountered
+ */
+
+module.exports = { BaseProvider };

package/src/loadbalancer/providers/byan-api-provider.js

@@ -0,0 +1,132 @@
+/**
+ * ByanApiProvider — Third Provider via BYAN API
+ *
+ * When BYAN_API_TOKEN is set, registers as a third provider.
+ * Uses existing BYAN API (port 3737) with BSP tree + context resolver.
+ * Lightweight fallback when both Copilot and Claude are rate-limited.
+ */
+
+const { BaseProvider } = require('./base-provider');
+
+class ByanApiProvider extends BaseProvider {
+  constructor(providerConfig) {
+    super('byan_api', providerConfig);
+    this.baseUrl = providerConfig.url || 'http://localhost:3737';
+    this.token = null;
+  }
+
+  async initialize() {
+    this.token = process.env[this.config.auth_env || 'BYAN_API_TOKEN'];
+    this.initialized = !!this.token;
+  }
+
+  async isAvailable() {
+    if (!this.token) return false;
+
+    try {
+      const http = require('http');
+      return new Promise((resolve) => {
+        const url = new URL('/api/health', this.baseUrl);
+        const req = http.get(url, { timeout: 3000 }, (res) => {
+          resolve(res.statusCode === 200);
+        });
+        req.on('error', () => resolve(false));
+        req.on('timeout', () => { req.destroy(); resolve(false); });
+      });
+    } catch {
+      return false;
+    }
+  }
+
+  async send(opts) {
+    if (!this.initialized) throw new Error('ByanApiProvider not initialized');
+
+    const start = Date.now();
+    const http = require('http');
+
+    const body = JSON.stringify({
+      prompt: opts.prompt,
+      session_id: opts.sessionId,
+      model: opts.model,
+    });
+
+    return new Promise((resolve, reject) => {
+      const url = new URL('/api/agent/execute', this.baseUrl);
+      const req = http.request(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${this.token}`,
+          'Content-Length': Buffer.byteLength(body),
+        },
+        timeout: 30000,
+      }, (res) => {
+        let data = '';
+        res.on('data', chunk => { data += chunk; });
+        res.on('end', () => {
+          const latencyMs = Date.now() - start;
+
+          if (res.statusCode === 429) {
+            const retryAfter = res.headers['retry-after'];
+            resolve({
+              provider: this.name,
+              content: null,
+              model: 'byan-api',
+              rateLimitHeaders: { 'retry-after': retryAfter },
+              latencyMs,
+              rateLimited: true,
+            });
+            return;
+          }
+
+          if (res.statusCode >= 400) {
+            reject(new Error(`BYAN API error ${res.statusCode}: ${data}`));
+            return;
+          }
+
+          try {
+            const parsed = JSON.parse(data);
+            resolve({
+              provider: this.name,
+              content: parsed.response || parsed.content || data,
+              model: parsed.model || 'byan-api',
+              rateLimitHeaders: null,
+              latencyMs,
+              rateLimited: false,
+            });
+          } catch {
+            resolve({
+              provider: this.name,
+              content: data,
+              model: 'byan-api',
+              rateLimitHeaders: null,
+              latencyMs,
+              rateLimited: false,
+            });
+          }
+        });
+      });
+
+      req.on('error', reject);
+      req.on('timeout', () => { req.destroy(); reject(new Error('BYAN API timeout')); });
+      req.write(body);
+      req.end();
+    });
+  }
+
+  getCapabilities() {
+    return {
+      streaming: false,
+      tools: false,
+      multiTurn: true,
+      maxContextTokens: 32000,
+    };
+  }
+
+  async destroy() {
+    this.token = null;
+    await super.destroy();
+  }
+}
+
+module.exports = { ByanApiProvider };

package/src/loadbalancer/providers/claude-provider.js

@@ -0,0 +1,113 @@
+/**
+ * ClaudeProvider — Wraps @anthropic-ai/claude-agent-sdk
+ *
+ * Uses Claude Agent SDK to query and resume sessions.
+ * Catches RateLimitError for circuit breaker integration.
+ */
+
+const { BaseProvider } = require('./base-provider');
+
+class ClaudeProvider extends BaseProvider {
+  constructor(providerConfig) {
+    super('claude', providerConfig);
+    this.sdk = null;
+  }
+
+  async initialize() {
+    try {
+      this.sdk = require('@anthropic-ai/claude-code');
+      this.initialized = true;
+    } catch (err) {
+      if (err.code === 'MODULE_NOT_FOUND') {
+        this.initialized = false;
+        return;
+      }
+      throw err;
+    }
+  }
+
+  async isAvailable() {
+    if (!this.initialized || !this.sdk) return false;
+    try {
+      const token = process.env[this.config.auth_env || 'ANTHROPIC_API_KEY'];
+      return !!token;
+    } catch {
+      return false;
+    }
+  }
+
+  async send(opts) {
+    if (!this.initialized) throw new Error('ClaudeProvider not initialized');
+
+    const start = Date.now();
+    const model = opts.model || this.config.models?.agent || 'claude-sonnet-4-20250514';
+
+    try {
+      const messages = [];
+      const result = this.sdk.query({
+        prompt: opts.prompt,
+        options: {
+          model,
+          maxTurns: 1,
+          ...(opts.sessionId ? { continue: opts.sessionId } : {}),
+        },
+      });
+
+      for await (const event of result) {
+        if (event.type === 'assistant' && event.message?.content) {
+          for (const block of event.message.content) {
+            if (block.type === 'text') {
+              messages.push(block.text);
+            }
+          }
+        }
+      }
+
+      return {
+        provider: this.name,
+        content: messages.join('\n'),
+        model,
+        rateLimitHeaders: null,
+        latencyMs: Date.now() - start,
+        rateLimited: false,
+      };
+    } catch (err) {
+      const isRateLimit =
+        err.name === 'RateLimitError' ||
+        err.status === 429 ||
+        (err.message && err.message.includes('rate_limit'));
+
+      if (isRateLimit) {
+        const retryAfter = err.headers?.['retry-after'] || err.retryAfter;
+        return {
+          provider: this.name,
+          content: null,
+          model,
+          rateLimitHeaders: {
+            'retry-after': retryAfter ? String(retryAfter) : undefined,
+          },
+          latencyMs: Date.now() - start,
+          rateLimited: true,
+        };
+      }
+
+      throw err;
+    }
+  }
+
+  getCapabilities() {
+    return {
+      streaming: true,
+      tools: true,
+      multiTurn: true,
+      maxContextTokens: 200000,
+    };
+  }
+
+  async destroy() {
+    this.sdk = null;
+    await super.destroy();
+  }
+}
+
+module.exports = { ClaudeProvider };

package/src/loadbalancer/providers/copilot-provider.js

@@ -0,0 +1,104 @@
+/**
+ * CopilotProvider — Wraps @github/copilot-sdk
+ *
+ * Uses the Copilot SDK to create sessions and send prompts.
+ * Extracts rate limit signals from HTTP headers and error events.
+ */
+
+const { BaseProvider } = require('./base-provider');
+
+class CopilotProvider extends BaseProvider {
+  constructor(providerConfig) {
+    super('copilot', providerConfig);
+    this.sdk = null;
+    this.session = null;
+  }
+
+  async initialize() {
+    try {
+      const { createClient } = require('@github/copilot-sdk');
+      this.sdk = createClient();
+      this.initialized = true;
+    } catch (err) {
+      if (err.code === 'MODULE_NOT_FOUND') {
+        this.initialized = false;
+        return;
+      }
+      throw err;
+    }
+  }
+
+  async isAvailable() {
+    if (!this.initialized || !this.sdk) return false;
+    try {
+      const token = process.env[this.config.auth_env || 'COPILOT_GITHUB_TOKEN'];
+      return !!token;
+    } catch {
+      return false;
+    }
+  }
+
+  async send(opts) {
+    if (!this.initialized) throw new Error('CopilotProvider not initialized');
+
+    const start = Date.now();
+    const model = opts.model || this.config.models?.agent || 'gpt-4.1';
+
+    try {
+      const { createSession } = require('@github/copilot-sdk');
+      const session = createSession({
+        model,
+        onPermissionRequest: () => ({ allow: true }),
+      });
+
+      const response = await session.sendAndWait({ prompt: opts.prompt });
+
+      return {
+        provider: this.name,
+        content: response.content || response.data?.content || '',
+        model,
+        rateLimitHeaders: null,
+        latencyMs: Date.now() - start,
+        rateLimited: false,
+      };
+    } catch (err) {
+      const is429 = err.status === 429 || err.statusCode === 429 ||
+        (err.message && err.message.includes('rate limit'));
+
+      if (is429) {
+        const headers = err.headers || err.response?.headers || {};
+        return {
+          provider: this.name,
+          content: null,
+          model,
+          rateLimitHeaders: {
+            'x-ratelimit-remaining': headers['x-ratelimit-remaining'],
+            'x-ratelimit-reset': headers['x-ratelimit-reset'],
+            'retry-after': headers['retry-after'],
+          },
+          latencyMs: Date.now() - start,
+          rateLimited: true,
+        };
+      }
+
+      throw err;
+    }
+  }
+
+  getCapabilities() {
+    return {
+      streaming: true,
+      tools: true,
+      multiTurn: true,
+      maxContextTokens: 128000,
+    };
+  }
+
+  async destroy() {
+    this.sdk = null;
+    this.session = null;
+    await super.destroy();
+  }
+}
+
+module.exports = { CopilotProvider };

package/src/loadbalancer/rate-limit-tracker.js

@@ -0,0 +1,216 @@
+/**
+ * RateLimitTracker — CircuitBreaker State Machine
+ *
+ * Per-provider rate limit tracking with circuit breaker pattern.
+ *
+ * States:
+ *   HEALTHY     → Normal operation, all requests pass through
+ *   THROTTLED   → Approaching limit, requests allowed but monitored
+ *   BLOCKED     → Circuit open, no requests pass. Waiting for recovery.
+ *   RECOVERING  → Half-open, limited probe requests to test recovery
+ *
+ * Transitions:
+ *   HEALTHY     → THROTTLED    (429 count >= throttle_threshold in window)
+ *   THROTTLED   → BLOCKED      (429 count >= block_threshold in window)
+ *   BLOCKED     → RECOVERING   (recovery_probe_interval elapsed)
+ *   RECOVERING  → HEALTHY      (probe succeeded, no 429 in half_open_max_requests)
+ *   RECOVERING  → BLOCKED      (probe failed, got another 429)
+ *   THROTTLED   → HEALTHY      (window elapsed with no new 429s)
+ *   any         → HEALTHY      (manual reset)
+ */
+
+const { EventEmitter } = require('events');
+
+const STATES = {
+  HEALTHY: 'HEALTHY',
+  THROTTLED: 'THROTTLED',
+  BLOCKED: 'BLOCKED',
+  RECOVERING: 'RECOVERING',
+};
+
+class RateLimitTracker extends EventEmitter {
+  /**
+   * @param {string} providerName
+   * @param {object} opts - from config.rate_limits
+   */
+  constructor(providerName, opts = {}) {
+    super();
+    this.provider = providerName;
+    this.state = STATES.HEALTHY;
+
+    this.windowMs = opts.window_ms || 60000;
+    this.throttleThreshold = opts.throttle_threshold || 2;
+    this.blockThreshold = opts.block_threshold || 3;
+    this.recoveryProbeMs = opts.recovery_probe_interval_ms || 10000;
+    this.halfOpenMax = opts.half_open_max_requests || 2;
+
+    this.events429 = [];
+    this.lastStateChange = Date.now();
+    this.recoveryTimer = null;
+    this.halfOpenRequests = 0;
+    this.halfOpenSuccesses = 0;
+    this.totalRequests = 0;
+    this.total429s = 0;
+  }
+
+  getState() {
+    return {
+      provider: this.provider,
+      state: this.state,
+      count429InWindow: this._countInWindow(),
+      windowMs: this.windowMs,
+      lastStateChange: this.lastStateChange,
+      totalRequests: this.totalRequests,
+      total429s: this.total429s,
+      canAcceptRequest: this.canAcceptRequest(),
+    };
+  }
+
+  canAcceptRequest() {
+    switch (this.state) {
+      case STATES.HEALTHY:
+      case STATES.THROTTLED:
+        return true;
+      case STATES.RECOVERING:
+        return this.halfOpenRequests < this.halfOpenMax;
+      case STATES.BLOCKED:
+        return false;
+      default:
+        return false;
+    }
+  }
+
+  /**
+   * Record a successful request (no rate limit error).
+   */
+  recordSuccess() {
+    this.totalRequests++;
+
+    if (this.state === STATES.RECOVERING) {
+      this.halfOpenSuccesses++;
+      if (this.halfOpenSuccesses >= this.halfOpenMax) {
+        this._transition(STATES.HEALTHY, 'Recovery probes all succeeded');
+      }
+      return;
+    }
+
+    if (this.state === STATES.THROTTLED) {
+      this._pruneWindow();
+      if (this._countInWindow() === 0) {
+        this._transition(STATES.HEALTHY, 'Window cleared, no recent 429s');
+      }
+    }
+  }
+
+  /**
+   * Record a 429 rate limit error.
+   * @param {object} [meta] - Optional metadata (headers, retry-after, etc.)
+   */
+  record429(meta = {}) {
+    this.totalRequests++;
+    this.total429s++;
+
+    const now = Date.now();
+    this.events429.push({ timestamp: now, meta });
+    this._pruneWindow();
+
+    const count = this._countInWindow();
+
+    if (this.state === STATES.RECOVERING) {
+      this._transition(STATES.BLOCKED, `429 during recovery (count: ${count})`);
+      this._scheduleRecovery();
+      return;
+    }
+
+    if (count >= this.blockThreshold) {
+      this._transition(STATES.BLOCKED, `429 count ${count} >= block threshold ${this.blockThreshold}`);
+      this._scheduleRecovery();
+    } else if (count >= this.throttleThreshold && this.state === STATES.HEALTHY) {
+      this._transition(STATES.THROTTLED, `429 count ${count} >= throttle threshold ${this.throttleThreshold}`);
+    }
+  }
+
+  /**
+   * Record a response with rate limit headers (preemptive detection).
+   * @param {object} headers - { 'x-ratelimit-remaining', 'x-ratelimit-reset', 'retry-after' }
+   */
+  recordHeaders(headers = {}) {
+    const remaining = parseInt(headers['x-ratelimit-remaining'], 10);
+    const retryAfter = parseInt(headers['retry-after'], 10);
+
+    if (retryAfter > 0) {
+      this.record429({ retryAfter, source: 'header' });
+      return;
+    }
+
+    if (!isNaN(remaining) && remaining <= 2 && this.state === STATES.HEALTHY) {
+      this._transition(STATES.THROTTLED, `Preemptive: x-ratelimit-remaining=${remaining}`);
+    }
+  }
+
+  /**
+   * Force reset to HEALTHY state.
+   */
+  reset() {
+    this._clearRecoveryTimer();
+    this.events429 = [];
+    this.halfOpenRequests = 0;
+    this.halfOpenSuccesses = 0;
+    this._transition(STATES.HEALTHY, 'Manual reset');
+  }
+
+  destroy() {
+    this._clearRecoveryTimer();
+    this.removeAllListeners();
+  }
+
+  _transition(newState, reason) {
+    const prev = this.state;
+    if (prev === newState) return;
+
+    this.state = newState;
+    this.lastStateChange = Date.now();
+
+    if (newState === STATES.RECOVERING) {
+      this.halfOpenRequests = 0;
+      this.halfOpenSuccesses = 0;
+    }
+
+    this.emit('state_change', {
+      provider: this.provider,
+      from: prev,
+      to: newState,
+      reason,
+      timestamp: this.lastStateChange,
+    });
+  }
+
+  _scheduleRecovery() {
+    this._clearRecoveryTimer();
+    this.recoveryTimer = setTimeout(() => {
+      if (this.state === STATES.BLOCKED) {
+        this._transition(STATES.RECOVERING, `Recovery probe after ${this.recoveryProbeMs}ms`);
+      }
+    }, this.recoveryProbeMs);
+    if (this.recoveryTimer.unref) this.recoveryTimer.unref();
+  }
+
+  _clearRecoveryTimer() {
+    if (this.recoveryTimer) {
+      clearTimeout(this.recoveryTimer);
+      this.recoveryTimer = null;
+    }
+  }
+
+  _pruneWindow() {
+    const cutoff = Date.now() - this.windowMs;
+    this.events429 = this.events429.filter(e => e.timestamp > cutoff);
+  }
+
+  _countInWindow() {
+    this._pruneWindow();
+    return this.events429.length;
+  }
+}
+
+module.exports = { RateLimitTracker, STATES };