create-byan-agent 2.9.4 → 2.9.5

package/src/loadbalancer/session-bridge.js

@@ -0,0 +1,179 @@
+/**
+ * SessionBridge — Cross-Provider Context Transfer
+ *
+ * Serializes conversation state from one provider into a provider-agnostic
+ * format, then injects it as context into the target provider.
+ *
+ * Strategy:
+ *   1. Extract: conversation messages + files touched + decisions made
+ *   2. Summarize: if transcript > max_tokens, use LLM to compress
+ *   3. Package: provider-agnostic JSON (PortableContext)
+ *   4. Inject: as system prompt prefix on target provider
+ */
+
+/**
+ * @typedef {object} PortableContext
+ * @property {string} conversationId
+ * @property {string} sourceProvider
+ * @property {string} targetProvider
+ * @property {string} summary - Concise conversation summary
+ * @property {string[]} filesTouched - Files read/modified
+ * @property {string[]} decisions - Key decisions made
+ * @property {string} currentTask - What was being worked on
+ * @property {object} agentState - BYAN agent state (soul, tao, FD phase, etc.)
+ * @property {number} fidelityPct - Estimated context preservation %
+ * @property {string} transferredAt - ISO timestamp
+ */
+
+class SessionBridge {
+  /**
+   * @param {object} opts
+   * @param {import('./state/db').SharedStateStore} opts.store
+   * @param {number} [opts.maxTokens] - Max summary tokens (default: 2000)
+   */
+  constructor(opts = {}) {
+    this.store = opts.store;
+    this.maxTokens = opts.maxTokens || 2000;
+  }
+
+  /**
+   * Extract context from source provider's session.
+   * @param {object} provider - ProviderAdapter instance
+   * @param {string} conversationId
+   * @returns {Promise<PortableContext>}
+   */
+  async extract(provider, conversationId) {
+    const conversation = this.store?.getConversation(conversationId);
+    const existingContext = conversation?.context_json
+      ? JSON.parse(conversation.context_json)
+      : {};
+
+    const switchHistory = this.store?.getSwitchoversForConversation(conversationId) || [];
+
+    return {
+      conversationId,
+      sourceProvider: provider.name,
+      targetProvider: null,
+      summary: existingContext.summary || 'No conversation summary available.',
+      filesTouched: existingContext.filesTouched || [],
+      decisions: existingContext.decisions || [],
+      currentTask: existingContext.currentTask || 'Unknown task',
+      agentState: existingContext.agentState || {},
+      switchHistory: switchHistory.map(s => ({
+        from: s.from_provider,
+        to: s.to_provider,
+        reason: s.reason,
+        at: s.switched_at,
+      })),
+      fidelityPct: existingContext.summary ? 85 : 50,
+      transferredAt: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Update the stored context for a conversation.
+   * Called periodically during normal operation to keep context fresh.
+   * @param {string} conversationId
+   * @param {object} contextUpdate - Partial context to merge
+   */
+  updateContext(conversationId, contextUpdate) {
+    if (!this.store) return;
+
+    const conversation = this.store.getConversation(conversationId);
+    if (!conversation) return;
+
+    const existing = conversation.context_json
+      ? JSON.parse(conversation.context_json)
+      : {};
+
+    const merged = {
+      ...existing,
+      ...contextUpdate,
+      filesTouched: [
+        ...new Set([...(existing.filesTouched || []), ...(contextUpdate.filesTouched || [])]),
+      ],
+      decisions: [
+        ...(existing.decisions || []),
+        ...(contextUpdate.decisions || []),
+      ],
+      updatedAt: new Date().toISOString(),
+    };
+
+    this.store.updateConversation(conversationId, {
+      context_json: JSON.stringify(merged),
+    });
+  }
+
+  /**
+   * Format a PortableContext into a system prompt for the target provider.
+   * @param {PortableContext} ctx
+   * @returns {string} - Formatted context injection prompt
+   */
+  formatInjectionPrompt(ctx) {
+    const lines = [
+      '--- CONTEXT TRANSFER ---',
+      `Transferred from: ${ctx.sourceProvider}`,
+      `Conversation: ${ctx.conversationId}`,
+      `Fidelity: ~${ctx.fidelityPct}%`,
+      '',
+      '## Summary',
+      ctx.summary,
+    ];
+
+    if (ctx.currentTask) {
+      lines.push('', '## Current Task', ctx.currentTask);
+    }
+
+    if (ctx.filesTouched.length > 0) {
+      lines.push('', '## Files Touched', ...ctx.filesTouched.map(f => `- ${f}`));
+    }
+
+    if (ctx.decisions.length > 0) {
+      lines.push('', '## Key Decisions', ...ctx.decisions.map(d => `- ${d}`));
+    }
+
+    if (ctx.agentState && Object.keys(ctx.agentState).length > 0) {
+      lines.push('', '## Agent State', JSON.stringify(ctx.agentState, null, 2));
+    }
+
+    if (ctx.switchHistory && ctx.switchHistory.length > 0) {
+      lines.push(
+        '', '## Switch History',
+        ...ctx.switchHistory.map(s => `- ${s.from} -> ${s.to} (${s.reason}) at ${s.at}`)
+      );
+    }
+
+    lines.push('', '--- END CONTEXT TRANSFER ---');
+    return lines.join('\n');
+  }
+
+  /**
+   * Full transfer: extract from source, record switchover, format for target.
+   * @param {object} sourceProvider
+   * @param {string} targetProviderName
+   * @param {string} conversationId
+   * @param {string} reason
+   * @returns {Promise<{context: PortableContext, injectionPrompt: string}>}
+   */
+  async transfer(sourceProvider, targetProviderName, conversationId, reason) {
+    const context = await this.extract(sourceProvider, conversationId);
+    context.targetProvider = targetProviderName;
+
+    if (this.store) {
+      this.store.recordSwitchover({
+        conversationId,
+        from: sourceProvider.name,
+        to: targetProviderName,
+        reason,
+        contextSnapshot: JSON.stringify(context),
+        fidelityPct: context.fidelityPct,
+      });
+    }
+
+    const injectionPrompt = this.formatInjectionPrompt(context);
+
+    return { context, injectionPrompt };
+  }
+}
+
+module.exports = { SessionBridge };

package/src/loadbalancer/state/db.js

@@ -0,0 +1,211 @@
+/**
+ * SharedStateStore — SQLite-backed state for LoadBalancer
+ *
+ * Manages conversations, switchover events, rate limit logs, and
+ * provider statistics. Shared between providers via MCP tools.
+ *
+ * Uses better-sqlite3 for synchronous, fast access.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const MIGRATION_DIR = path.join(__dirname, 'migrations');
+
+class SharedStateStore {
+  /**
+   * @param {string} dbPath - Path to SQLite database file
+   */
+  constructor(dbPath) {
+    this.dbPath = dbPath;
+    this.db = null;
+  }
+
+  /**
+   * Initialize database and run migrations.
+   */
+  open() {
+    let Database;
+    try {
+      Database = require('better-sqlite3');
+    } catch {
+      throw new Error('better-sqlite3 required for SharedStateStore. Run: npm install better-sqlite3');
+    }
+
+    const dir = path.dirname(this.dbPath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    this.db = new Database(this.dbPath);
+    this.db.pragma('journal_mode = WAL');
+    this.db.pragma('foreign_keys = ON');
+
+    this._runMigrations();
+    return this;
+  }
+
+  _runMigrations() {
+    const files = fs.readdirSync(MIGRATION_DIR)
+      .filter(f => f.endsWith('.sql'))
+      .sort();
+
+    for (const file of files) {
+      const sql = fs.readFileSync(path.join(MIGRATION_DIR, file), 'utf8');
+      this.db.exec(sql);
+    }
+  }
+
+  // --- Conversations ---
+
+  createConversation(id, provider) {
+    const stmt = this.db.prepare(
+      'INSERT INTO lb_conversations (id, active_provider) VALUES (?, ?)'
+    );
+    stmt.run(id, provider);
+    return this.getConversation(id);
+  }
+
+  getConversation(id) {
+    return this.db.prepare('SELECT * FROM lb_conversations WHERE id = ?').get(id);
+  }
+
+  getActiveConversations() {
+    return this.db.prepare(
+      "SELECT * FROM lb_conversations WHERE status = 'active' ORDER BY updated_at DESC"
+    ).all();
+  }
+
+  updateConversation(id, fields) {
+    const allowed = ['active_provider', 'context_json', 'status'];
+    const sets = [];
+    const values = [];
+
+    for (const [key, val] of Object.entries(fields)) {
+      if (!allowed.includes(key)) continue;
+      sets.push(`${key} = ?`);
+      values.push(val);
+    }
+
+    if (sets.length === 0) return;
+
+    sets.push("updated_at = datetime('now')");
+    values.push(id);
+
+    this.db.prepare(
+      `UPDATE lb_conversations SET ${sets.join(', ')} WHERE id = ?`
+    ).run(...values);
+  }
+
+  // --- Switchovers ---
+
+  recordSwitchover({ conversationId, from, to, reason, contextSnapshot, fidelityPct }) {
+    const stmt = this.db.prepare(`
+      INSERT INTO lb_switchovers (conversation_id, from_provider, to_provider, reason, context_snapshot, context_fidelity_pct)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `);
+    const info = stmt.run(conversationId, from, to, reason, contextSnapshot || null, fidelityPct || null);
+
+    if (conversationId) {
+      this.updateConversation(conversationId, {
+        active_provider: to,
+        status: 'active',
+      });
+    }
+
+    this._updateProviderStat(from, { total_switchovers_from: 1 });
+    this._updateProviderStat(to, { total_switchovers_to: 1 });
+
+    return info.lastInsertRowid;
+  }
+
+  getSwitchoverHistory(limit = 20) {
+    return this.db.prepare(
+      'SELECT * FROM lb_switchovers ORDER BY switched_at DESC LIMIT ?'
+    ).all(limit);
+  }
+
+  getSwitchoversForConversation(conversationId) {
+    return this.db.prepare(
+      'SELECT * FROM lb_switchovers WHERE conversation_id = ? ORDER BY switched_at'
+    ).all(conversationId);
+  }
+
+  // --- Rate Limit Log ---
+
+  logRateLimit({ provider, eventType, stateBefore, stateAfter, meta }) {
+    const stmt = this.db.prepare(`
+      INSERT INTO lb_rate_limit_log (provider, event_type, state_before, state_after, meta_json)
+      VALUES (?, ?, ?, ?, ?)
+    `);
+    stmt.run(provider, eventType, stateBefore, stateAfter, meta ? JSON.stringify(meta) : null);
+
+    if (eventType === '429') {
+      this._updateProviderStat(provider, { total_429s: 1 });
+    }
+  }
+
+  getRateLimitLog(provider, limit = 50) {
+    if (provider) {
+      return this.db.prepare(
+        'SELECT * FROM lb_rate_limit_log WHERE provider = ? ORDER BY logged_at DESC LIMIT ?'
+      ).all(provider, limit);
+    }
+    return this.db.prepare(
+      'SELECT * FROM lb_rate_limit_log ORDER BY logged_at DESC LIMIT ?'
+    ).all(limit);
+  }
+
+  // --- Provider Stats ---
+
+  recordRequest(provider, latencyMs) {
+    this._ensureProviderStat(provider);
+    const current = this.db.prepare('SELECT * FROM lb_provider_stats WHERE provider = ?').get(provider);
+
+    const newTotal = current.total_requests + 1;
+    const newAvg = ((current.avg_latency_ms * current.total_requests) + latencyMs) / newTotal;
+
+    this.db.prepare(`
+      UPDATE lb_provider_stats
+      SET total_requests = ?, avg_latency_ms = ?, last_used_at = datetime('now'), updated_at = datetime('now')
+      WHERE provider = ?
+    `).run(newTotal, newAvg, provider);
+  }
+
+  getProviderStats() {
+    return this.db.prepare('SELECT * FROM lb_provider_stats ORDER BY provider').all();
+  }
+
+  _ensureProviderStat(provider) {
+    this.db.prepare(
+      'INSERT OR IGNORE INTO lb_provider_stats (provider) VALUES (?)'
+    ).run(provider);
+  }
+
+  _updateProviderStat(provider, increments) {
+    this._ensureProviderStat(provider);
+    const sets = [];
+    const values = [];
+
+    for (const [key, inc] of Object.entries(increments)) {
+      sets.push(`${key} = ${key} + ?`);
+      values.push(inc);
+    }
+
+    sets.push("updated_at = datetime('now')");
+    values.push(provider);
+
+    this.db.prepare(
+      `UPDATE lb_provider_stats SET ${sets.join(', ')} WHERE provider = ?`
+    ).run(...values);
+  }
+
+  // --- Lifecycle ---
+
+  close() {
+    if (this.db) {
+      this.db.close();
+      this.db = null;
+    }
+  }
+}
+
+module.exports = { SharedStateStore };

package/src/loadbalancer/state/migrations/001-initial.sql

@@ -0,0 +1,50 @@
+-- LoadBalancer SharedStateStore — Initial Schema
+-- Tracks conversations, switchover events, and rate limit history
+
+CREATE TABLE IF NOT EXISTS lb_conversations (
+    id TEXT PRIMARY KEY,
+    active_provider TEXT NOT NULL,
+    started_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+    context_json TEXT,
+    status TEXT NOT NULL DEFAULT 'active'
+        CHECK (status IN ('active', 'paused', 'completed', 'transferred'))
+);
+
+CREATE TABLE IF NOT EXISTS lb_switchovers (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    conversation_id TEXT,
+    from_provider TEXT NOT NULL,
+    to_provider TEXT NOT NULL,
+    reason TEXT NOT NULL,
+    context_snapshot TEXT,
+    context_fidelity_pct INTEGER,
+    switched_at TEXT NOT NULL DEFAULT (datetime('now')),
+    FOREIGN KEY (conversation_id) REFERENCES lb_conversations(id)
+);
+
+CREATE TABLE IF NOT EXISTS lb_rate_limit_log (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    provider TEXT NOT NULL,
+    event_type TEXT NOT NULL CHECK (event_type IN ('429', 'header_warning', 'retry_after', 'recovery')),
+    state_before TEXT NOT NULL,
+    state_after TEXT NOT NULL,
+    meta_json TEXT,
+    logged_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS lb_provider_stats (
+    provider TEXT PRIMARY KEY,
+    total_requests INTEGER NOT NULL DEFAULT 0,
+    total_429s INTEGER NOT NULL DEFAULT 0,
+    total_switchovers_from INTEGER NOT NULL DEFAULT 0,
+    total_switchovers_to INTEGER NOT NULL DEFAULT 0,
+    avg_latency_ms REAL NOT NULL DEFAULT 0,
+    last_used_at TEXT,
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_switchovers_conversation ON lb_switchovers(conversation_id);
+CREATE INDEX IF NOT EXISTS idx_switchovers_time ON lb_switchovers(switched_at);
+CREATE INDEX IF NOT EXISTS idx_rate_limit_provider ON lb_rate_limit_log(provider, logged_at);
+CREATE INDEX IF NOT EXISTS idx_conversations_status ON lb_conversations(status);

package/src/loadbalancer/tools/index.js

@@ -0,0 +1,123 @@
+/**
+ * LoadBalancer MCP Tool Definitions
+ *
+ * Tools exposed to both Claude Code and Copilot CLI via MCP protocol.
+ * Each tool is a { name, description, inputSchema, handler } object.
+ */
+
+function createTools(lb) {
+  return [
+    {
+      name: 'lb_status',
+      description: 'Get current loadbalancer status: active provider, rate limit states, session info.',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+      },
+      handler: async () => {
+        const status = lb.getStatus();
+        return { content: [{ type: 'text', text: JSON.stringify(status, null, 2) }] };
+      },
+    },
+    {
+      name: 'lb_send',
+      description: 'Send a prompt through the loadbalancer. Routes to healthiest provider automatically.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          prompt: { type: 'string', description: 'The prompt to send' },
+          session_id: { type: 'string', description: 'Optional session ID for sticky routing' },
+          prefer_provider: { type: 'string', enum: ['claude', 'copilot', 'auto'], description: 'Provider preference (default: auto)' },
+        },
+        required: ['prompt'],
+      },
+      handler: async (args) => {
+        const result = await lb.send({
+          prompt: args.prompt,
+          sessionId: args.session_id,
+          preferProvider: args.prefer_provider || 'auto',
+        });
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+      },
+    },
+    {
+      name: 'lb_switch',
+      description: 'Force switch to a specific provider. Triggers context transfer via SessionBridge.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          target_provider: { type: 'string', enum: ['claude', 'copilot'], description: 'Provider to switch to' },
+          session_id: { type: 'string', description: 'Session to transfer context from' },
+          reason: { type: 'string', description: 'Reason for the switch' },
+        },
+        required: ['target_provider'],
+      },
+      handler: async (args) => {
+        const result = await lb.switchProvider({
+          target: args.target_provider,
+          sessionId: args.session_id,
+          reason: args.reason || 'manual_switch',
+        });
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+      },
+    },
+    {
+      name: 'lb_get_context',
+      description: 'Get the current session context in provider-agnostic format. Useful before manual switch.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          session_id: { type: 'string', description: 'Session to get context for' },
+        },
+      },
+      handler: async (args) => {
+        const context = await lb.getSessionContext(args.session_id);
+        return { content: [{ type: 'text', text: JSON.stringify(context, null, 2) }] };
+      },
+    },
+    {
+      name: 'lb_rate_limits',
+      description: 'Get detailed rate limit state for all providers. Shows circuit breaker state, 429 counts, reset times.',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+      },
+      handler: async () => {
+        const limits = lb.getRateLimitDetails();
+        return { content: [{ type: 'text', text: JSON.stringify(limits, null, 2) }] };
+      },
+    },
+    {
+      name: 'lb_history',
+      description: 'Get switchover history. Shows when and why provider switches occurred.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          limit: { type: 'number', description: 'Max events to return (default: 20)' },
+        },
+      },
+      handler: async (args) => {
+        const history = lb.getSwitchoverHistory(args.limit || 20);
+        return { content: [{ type: 'text', text: JSON.stringify(history, null, 2) }] };
+      },
+    },
+    {
+      name: 'lb_quota',
+      description: 'Get real-time rate limit pressure per provider as percentage (0-100). Shows pressure score, velocity (req/min), trend, ETA to limit, and recommendation (ok/caution/switch_now).',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+      },
+      handler: async () => {
+        if (typeof lb.getQuota !== 'function') {
+          return { content: [{ type: 'text', text: 'lb_quota requires LoadBalancerLive (not stub). Upgrade mcp-server.' }] };
+        }
+        const quota = lb.getQuota();
+        const summaries = Object.values(quota).map(q => q.summary).join('\n\n');
+        return { content: [{ type: 'text', text: summaries + '\n\n' + JSON.stringify(quota, null, 2) }] };
+      },
+    },
+  ];
+}
+
+module.exports = { createTools };