create-byan-agent 2.9.4 → 2.9.5

package/src/loadbalancer/mcp-server.js

@@ -0,0 +1,304 @@
+/**
+ * BYAN LoadBalancer — MCP Server
+ *
+ * Standalone MCP server exposing loadbalancer tools to Claude Code and
+ * Copilot CLI. HTTP transport for persistence across sessions.
+ *
+ * Start: node src/loadbalancer/mcp-server.js
+ * Connect: add to .mcp.json or claude settings
+ *
+ * Architecture:
+ *   CLI (Claude/Copilot) --MCP--> this server --SDK--> providers
+ */
+
+const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} = require('@modelcontextprotocol/sdk/types.js');
+
+const { loadConfig } = require('./config');
+const { createTools } = require('./tools/index');
+const { RateLimitTracker } = require('./rate-limit-tracker');
+const { Metrics } = require('./metrics');
+const { VelocityEstimator } = require('./velocity-estimator');
+const { calculatePressure, formatPressureSummary } = require('./pressure-score');
+const { EventEmitter } = require('events');
+
+const VERSION = '0.2.0';
+
+class LoadBalancerLive extends EventEmitter {
+  constructor(config) {
+    super();
+    this.config = config;
+    this.activeProvider = config.primary;
+    this.startedAt = new Date().toISOString();
+    this.switchHistory = [];
+
+    this.trackers = {};
+    this.velocities = {};
+    this.metrics = new Metrics();
+
+    const rlOpts = config.rate_limits || {};
+    const quotaOpts = config.quota || {};
+    this.preemptiveThreshold = quotaOpts.preemptive_threshold || 75;
+    this.preemptiveEnabled = quotaOpts.preemptive_enabled !== false;
+
+    for (const [name, prov] of Object.entries(config.providers)) {
+      if (prov.enabled !== false) {
+        this.trackers[name] = new RateLimitTracker(name, rlOpts);
+        this.trackers[name].on('state_change', (evt) => {
+          this.emit('rate_limit_change', evt);
+        });
+
+        this.velocities[name] = new VelocityEstimator(name, {
+          windowMs: quotaOpts.velocity_window_ms || 120000,
+          warningThresholdPerMin: quotaOpts.warning_threshold_per_min || 10,
+          maxRequestsBeforeLimit: quotaOpts.max_requests_before_limit || 30,
+        });
+        this.velocities[name].on('threshold_warning', (evt) => {
+          this.emit('velocity_warning', evt);
+        });
+      }
+    }
+
+    this.metrics.attachToLoadBalancer(this);
+  }
+
+  getTracker(provider) {
+    return this.trackers[provider] || null;
+  }
+
+  getVelocity(provider) {
+    return this.velocities[provider] || null;
+  }
+
+  getStatus() {
+    const providers = {};
+    for (const [name, prov] of Object.entries(this.config.providers)) {
+      const tracker = this.trackers[name];
+      providers[name] = {
+        enabled: prov.enabled !== false,
+        state: tracker ? tracker.state : 'DISABLED',
+      };
+    }
+
+    return {
+      version: VERSION,
+      activeProvider: this.activeProvider,
+      primary: this.config.primary,
+      fallbackOrder: this.config.fallback_order,
+      providers,
+      uptime: Date.now() - new Date(this.startedAt).getTime(),
+    };
+  }
+
+  getRateLimitDetails() {
+    const result = {};
+    for (const [name] of Object.entries(this.config.providers)) {
+      const tracker = this.trackers[name];
+      if (tracker) {
+        const s = tracker.getState();
+        result[name] = {
+          state: s.state,
+          count429InWindow: s.count429InWindow,
+          totalRequests: s.totalRequests,
+          total429s: s.total429s,
+          windowMs: s.windowMs,
+          canAcceptRequest: s.canAcceptRequest,
+          lastStateChange: s.lastStateChange,
+        };
+      } else {
+        result[name] = { state: 'DISABLED', message: 'Provider not enabled' };
+      }
+    }
+    return result;
+  }
+
+  getSwitchoverHistory(limit = 20) {
+    const events = this.switchHistory.slice(-limit);
+    return { events, total: this.switchHistory.length, limit };
+  }
+
+  recordSuccess(provider) {
+    const tracker = this.trackers[provider];
+    if (tracker) tracker.recordSuccess();
+    const ve = this.velocities[provider];
+    if (ve) ve.recordRequest();
+    this._checkPreemptive(provider);
+  }
+
+  record429(provider, meta) {
+    const tracker = this.trackers[provider];
+    if (tracker) tracker.record429(meta);
+    const ve = this.velocities[provider];
+    if (ve) ve.recordRequest();
+    this._checkPreemptive(provider);
+  }
+
+  _checkPreemptive(provider) {
+    if (!this.preemptiveEnabled) return;
+    if (provider !== this.activeProvider) return;
+
+    const tracker = this.trackers[provider];
+    const ve = this.velocities[provider];
+    if (!tracker || !ve) return;
+
+    const trackerState = tracker.getState();
+    const velocitySnap = ve.getSnapshot();
+    const pressure = calculatePressure(trackerState, velocitySnap, {
+      blockThreshold: this.config.rate_limits?.block_threshold,
+    });
+
+    if (pressure.score >= this.preemptiveThreshold) {
+      const fallback = this._findBestFallback(provider);
+      this.emit('preemptive_switch', {
+        provider,
+        pressureScore: pressure.score,
+        recommendation: pressure.recommendation,
+        suggestedTarget: fallback,
+        timestamp: new Date().toISOString(),
+      });
+    }
+  }
+
+  _findBestFallback(excludeProvider) {
+    const order = [this.config.primary, ...(this.config.fallback_order || [])];
+    for (const name of order) {
+      if (name === excludeProvider) continue;
+      const tracker = this.trackers[name];
+      if (tracker && tracker.canAcceptRequest()) return name;
+    }
+    return null;
+  }
+
+  getQuota() {
+    const result = {};
+    for (const [name] of Object.entries(this.config.providers)) {
+      const tracker = this.trackers[name];
+      const ve = this.velocities[name];
+      if (tracker && ve) {
+        const trackerState = tracker.getState();
+        const velocitySnap = ve.getSnapshot();
+        const pressure = calculatePressure(trackerState, velocitySnap, {
+          blockThreshold: this.config.rate_limits?.block_threshold,
+        });
+        result[name] = {
+          pressureScore: pressure.score,
+          recommendation: pressure.recommendation,
+          components: pressure.components,
+          velocity: velocitySnap.velocity,
+          trend: velocitySnap.trend,
+          etaMinutes: velocitySnap.etaMinutes === Infinity ? null : velocitySnap.etaMinutes,
+          circuitBreakerState: trackerState.state,
+          summary: formatPressureSummary(name, pressure, velocitySnap),
+        };
+      } else {
+        result[name] = { pressureScore: null, recommendation: 'disabled', summary: `${name}: DISABLED` };
+      }
+    }
+    return result;
+  }
+
+  async send(opts) {
+    return {
+      provider: this.activeProvider,
+      status: 'stub',
+      message: 'ProviderAdapter not yet integrated (LB-01). Use lb_status/lb_quota for monitoring.',
+      prompt: opts.prompt?.substring(0, 100),
+    };
+  }
+
+  async switchProvider(opts) {
+    const prev = this.activeProvider;
+    this.activeProvider = opts.target;
+    const entry = {
+      timestamp: new Date().toISOString(),
+      from: prev,
+      to: opts.target,
+      reason: opts.reason || 'manual_switch',
+    };
+    this.switchHistory.push(entry);
+    this.emit('switch', entry);
+    return {
+      switched: true,
+      from: prev,
+      to: opts.target,
+      reason: opts.reason,
+      contextTransferred: false,
+      message: 'SessionBridge not yet integrated (LB-04). No context transfer.',
+    };
+  }
+
+  async getSessionContext(sessionId) {
+    return {
+      sessionId: sessionId || 'current',
+      provider: this.activeProvider,
+      context: null,
+      message: 'SharedStateStore not yet integrated (LB-STATE).',
+    };
+  }
+
+  destroy() {
+    for (const tracker of Object.values(this.trackers)) {
+      tracker.destroy();
+    }
+    for (const ve of Object.values(this.velocities)) {
+      ve.destroy();
+    }
+    this.removeAllListeners();
+  }
+}
+
+async function startServer(projectRoot) {
+  const resolvedRoot = projectRoot || process.env.BYAN_PROJECT_ROOT || process.cwd();
+  const config = loadConfig(resolvedRoot);
+  const lb = new LoadBalancerLive(config);
+  const tools = createTools(lb);
+
+  const server = new Server(
+    { name: 'byan-loadbalancer', version: VERSION },
+    { capabilities: { tools: {} } }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map(t => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema,
+    })),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const tool = tools.find(t => t.name === request.params.name);
+    if (!tool) {
+      return {
+        content: [{ type: 'text', text: `Unknown tool: ${request.params.name}` }],
+        isError: true,
+      };
+    }
+    try {
+      return await tool.handler(request.params.arguments || {});
+    } catch (err) {
+      return {
+        content: [{ type: 'text', text: `Error: ${err.message}` }],
+        isError: true,
+      };
+    }
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  return { server, lb, config };
+}
+
+if (require.main === module) {
+  startServer().catch(err => {
+    process.stderr.write(`LoadBalancer MCP server failed to start: ${err.message}\n`);
+    process.exit(1);
+  });
+}
+
+module.exports = { startServer, LoadBalancerLive, VERSION };

package/src/loadbalancer/metrics.js

@@ -0,0 +1,146 @@
+/**
+ * Metrics — LoadBalancer Observability
+ *
+ * Collects and exposes metrics for the loadbalancer:
+ *   - Provider usage percentages
+ *   - Switchover count and history
+ *   - Average latency per provider
+ *   - Rate limit hit totals
+ *   - Queue depth (graceful degradation)
+ *
+ * Integrates with LoadBalancer events. Queryable via lb_status MCP tool.
+ */
+
+class Metrics {
+  constructor() {
+    this.counters = {
+      requests_total: 0,
+      requests_by_provider: {},
+      switchovers_total: 0,
+      auto_failovers_total: 0,
+      rate_limit_hits: {},
+      queue_enqueued_total: 0,
+      queue_processed_total: 0,
+      queue_dropped_total: 0,
+    };
+
+    this.latency = {};
+    this.startedAt = Date.now();
+  }
+
+  /**
+   * Attach event listeners to a LoadBalancer instance.
+   * @param {import('./loadbalancer').LoadBalancer} lb
+   */
+  attachToLoadBalancer(lb) {
+    lb.on('rate_limit_change', (event) => {
+      if (event.to === 'BLOCKED' || event.to === 'THROTTLED') {
+        this._incrementCounter('rate_limit_hits', event.provider);
+      }
+    });
+
+    lb.on('switch', (event) => {
+      this.counters.switchovers_total++;
+    });
+
+    lb.on('auto_failover', (event) => {
+      this.counters.auto_failovers_total++;
+      this.counters.switchovers_total++;
+    });
+  }
+
+  /**
+   * Attach event listeners to a GracefulDegradation instance.
+   * @param {import('./graceful-degradation').GracefulDegradation} gd
+   */
+  attachToGracefulDegradation(gd) {
+    gd.on('enqueued', () => { this.counters.queue_enqueued_total++; });
+    gd.on('processed', () => { this.counters.queue_processed_total++; });
+  }
+
+  /**
+   * Record a provider request with latency.
+   * @param {string} provider
+   * @param {number} latencyMs
+   */
+  recordRequest(provider, latencyMs) {
+    this.counters.requests_total++;
+    this._incrementCounter('requests_by_provider', provider);
+
+    if (!this.latency[provider]) {
+      this.latency[provider] = { total: 0, count: 0, min: Infinity, max: 0 };
+    }
+
+    const l = this.latency[provider];
+    l.total += latencyMs;
+    l.count++;
+    l.min = Math.min(l.min, latencyMs);
+    l.max = Math.max(l.max, latencyMs);
+  }
+
+  /**
+   * Get all metrics as a snapshot.
+   */
+  getSnapshot() {
+    const uptimeMs = Date.now() - this.startedAt;
+
+    const providerUsage = {};
+    const total = this.counters.requests_total || 1;
+    for (const [provider, count] of Object.entries(this.counters.requests_by_provider)) {
+      providerUsage[provider] = {
+        count,
+        percentage: Math.round((count / total) * 100),
+      };
+    }
+
+    const latencyStats = {};
+    for (const [provider, l] of Object.entries(this.latency)) {
+      latencyStats[provider] = {
+        avg: l.count > 0 ? Math.round(l.total / l.count) : 0,
+        min: l.min === Infinity ? 0 : l.min,
+        max: l.max,
+        count: l.count,
+      };
+    }
+
+    return {
+      uptime_ms: uptimeMs,
+      requests_total: this.counters.requests_total,
+      provider_usage: providerUsage,
+      latency: latencyStats,
+      switchovers_total: this.counters.switchovers_total,
+      auto_failovers_total: this.counters.auto_failovers_total,
+      rate_limit_hits: { ...this.counters.rate_limit_hits },
+      queue: {
+        enqueued_total: this.counters.queue_enqueued_total,
+        processed_total: this.counters.queue_processed_total,
+        dropped_total: this.counters.queue_dropped_total,
+      },
+    };
+  }
+
+  /**
+   * Reset all metrics.
+   */
+  reset() {
+    this.counters = {
+      requests_total: 0,
+      requests_by_provider: {},
+      switchovers_total: 0,
+      auto_failovers_total: 0,
+      rate_limit_hits: {},
+      queue_enqueued_total: 0,
+      queue_processed_total: 0,
+      queue_dropped_total: 0,
+    };
+    this.latency = {};
+    this.startedAt = Date.now();
+  }
+
+  _incrementCounter(counterName, key) {
+    if (!this.counters[counterName]) this.counters[counterName] = {};
+    this.counters[counterName][key] = (this.counters[counterName][key] || 0) + 1;
+  }
+}
+
+module.exports = { Metrics };

package/src/loadbalancer/native/claude-integration.js

@@ -0,0 +1,64 @@
+/**
+ * Claude Native Integration
+ *
+ * Wires LoadBalancer into Claude Code's agent system.
+ * Ensures Claude executes BYAN logic natively via Claude Agent SDK,
+ * with hooks feeding the LoadBalancer tracker.
+ */
+
+const { createClaudeHooks } = require('../hooks/claude-hooks');
+
+class ClaudeIntegration {
+  /**
+   * @param {import('../loadbalancer').LoadBalancer} lb
+   */
+  constructor(lb) {
+    this.lb = lb;
+    this.tracker = lb.getTracker('claude');
+  }
+
+  /**
+   * Get Claude Agent SDK hooks wired to the rate limit tracker.
+   * @returns {object} Hook configuration for Claude Agent SDK
+   */
+  getHooks() {
+    if (!this.tracker) return {};
+    return createClaudeHooks(this.tracker);
+  }
+
+  /**
+   * Generate .mcp.json entry for connecting Claude to the LB MCP server.
+   * @returns {object} MCP configuration fragment
+   */
+  getMcpConfig() {
+    return {
+      'byan-loadbalancer': {
+        command: 'node',
+        args: ['src/loadbalancer/mcp-server.js'],
+        env: {
+          BYAN_PROJECT_ROOT: '{project-root}',
+        },
+      },
+    };
+  }
+
+  /**
+   * Generate CLAUDE.md directive for LoadBalancer awareness.
+   * @returns {string} Markdown directive
+   */
+  getClaudeMdDirective() {
+    return [
+      '## LoadBalancer Integration',
+      '',
+      'This project uses BYAN LoadBalancer for automatic failover between',
+      'GitHub Copilot CLI and Claude Code. The MCP tool `byan-loadbalancer`',
+      'provides: lb_status, lb_send, lb_switch, lb_get_context, lb_rate_limits,',
+      'lb_history.',
+      '',
+      'When rate-limited, the LoadBalancer automatically switches to the',
+      'alternate provider with context transfer.',
+    ].join('\n');
+  }
+}
+
+module.exports = { ClaudeIntegration };

package/src/loadbalancer/native/copilot-integration.js

@@ -0,0 +1,59 @@
+/**
+ * Copilot Native Integration
+ *
+ * Wires LoadBalancer into GitHub Copilot CLI's agent system.
+ * Ensures Copilot executes BYAN logic natively via its own SDK,
+ * with rate limit hooks feeding the LoadBalancer tracker.
+ */
+
+const { attachCopilotHooks, wrapCopilotSend } = require('../hooks/copilot-hooks');
+
+class CopilotIntegration {
+  /**
+   * @param {import('../loadbalancer').LoadBalancer} lb
+   */
+  constructor(lb) {
+    this.lb = lb;
+    this.tracker = lb.getTracker('copilot');
+  }
+
+  /**
+   * Enhance a Copilot SDK session with rate limit tracking.
+   * @param {object} session - Copilot SDK session object
+   * @returns {object} Enhanced session
+   */
+  enhanceSession(session) {
+    if (!this.tracker) return session;
+    attachCopilotHooks(session, this.tracker);
+    return session;
+  }
+
+  /**
+   * Wrap a sendAndWait function with rate limit tracking.
+   * @param {Function} sendFn
+   * @returns {Function}
+   */
+  wrapSend(sendFn) {
+    if (!this.tracker) return sendFn;
+    return wrapCopilotSend(sendFn, this.tracker);
+  }
+
+  /**
+   * Generate .mcp.json entry for connecting Copilot to the LB MCP server.
+   * @returns {object} MCP configuration fragment
+   */
+  getMcpConfig() {
+    const mcpConfig = this.lb.config.mcp_server || {};
+    return {
+      'byan-loadbalancer': {
+        command: 'node',
+        args: ['src/loadbalancer/mcp-server.js'],
+        env: {
+          BYAN_PROJECT_ROOT: '{project-root}',
+        },
+      },
+    };
+  }
+}
+
+module.exports = { CopilotIntegration };

package/src/loadbalancer/pressure-score.js

@@ -0,0 +1,102 @@
+/**
+ * PressureScore — Composite Rate Limit Pressure (0-100)
+ *
+ * Single number per provider answering: "How close am I to hitting the wall?"
+ *
+ * Components (weights configurable):
+ *   - 429 ratio    (40%) — total429s / totalRequests in circuit breaker
+ *   - Proximity    (30%) — count429InWindow / blockThreshold
+ *   - Velocity     (20%) — current req/min / warningThreshold
+ *   - State bonus  (10%) — HEALTHY=0, THROTTLED=50, RECOVERING=70, BLOCKED=100
+ *
+ * Pure computation — takes tracker + velocity snapshots, returns score.
+ */
+
+const STATE_SCORES = {
+  HEALTHY: 0,
+  THROTTLED: 50,
+  RECOVERING: 70,
+  BLOCKED: 100,
+};
+
+const DEFAULT_WEIGHTS = {
+  ratio429: 0.40,
+  proximity: 0.30,
+  velocity: 0.20,
+  statePenalty: 0.10,
+};
+
+/**
+ * Calculate pressure score for a single provider.
+ *
+ * @param {object} trackerState — from RateLimitTracker.getState()
+ * @param {object} velocitySnap — from VelocityEstimator.getSnapshot()
+ * @param {object} [opts] — override weights and thresholds
+ * @returns {object} { score, components, recommendation }
+ */
+function calculatePressure(trackerState, velocitySnap, opts = {}) {
+  const weights = { ...DEFAULT_WEIGHTS, ...opts.weights };
+  const blockThreshold = opts.blockThreshold || trackerState.windowMs ? 3 : 3;
+
+  const ratio429 = trackerState.totalRequests > 0
+    ? Math.min(1, trackerState.total429s / trackerState.totalRequests)
+    : 0;
+
+  const proximity = Math.min(1, trackerState.count429InWindow / (blockThreshold || 3));
+
+  const velocityRatio = velocitySnap.warningThreshold > 0
+    ? Math.min(1, velocitySnap.velocity / velocitySnap.warningThreshold)
+    : 0;
+
+  const stateScore = (STATE_SCORES[trackerState.state] || 0) / 100;
+
+  const raw = (
+    ratio429 * weights.ratio429 +
+    proximity * weights.proximity +
+    velocityRatio * weights.velocity +
+    stateScore * weights.statePenalty
+  );
+
+  const score = Math.round(Math.min(100, raw * 100));
+
+  let recommendation;
+  if (score >= 80) recommendation = 'switch_now';
+  else if (score >= 50) recommendation = 'caution';
+  else recommendation = 'ok';
+
+  return {
+    score,
+    components: {
+      ratio429: Math.round(ratio429 * 100),
+      proximity: Math.round(proximity * 100),
+      velocity: Math.round(velocityRatio * 100),
+      statePenalty: Math.round(stateScore * 100),
+    },
+    recommendation,
+  };
+}
+
+/**
+ * Human-readable summary for lb_quota tool output.
+ */
+function formatPressureSummary(provider, pressure, velocitySnap) {
+  const etaStr = velocitySnap.etaMinutes === Infinity
+    ? 'no limit in sight'
+    : `~${velocitySnap.etaMinutes} min before limit`;
+
+  const lines = [
+    `${provider}: ${pressure.score}/100 [${pressure.recommendation.toUpperCase()}]`,
+    `  velocity: ${velocitySnap.velocity} req/min (${velocitySnap.trend})`,
+    `  eta: ${etaStr}`,
+    `  breakdown: 429_ratio=${pressure.components.ratio429}% proximity=${pressure.components.proximity}% velocity=${pressure.components.velocity}% state=${pressure.components.statePenalty}%`,
+  ];
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  calculatePressure,
+  formatPressureSummary,
+  STATE_SCORES,
+  DEFAULT_WEIGHTS,
+};