create-byan-agent 2.39.0 → 2.41.0

package/src/loadbalancer/degradation-ladder.js

@@ -0,0 +1,121 @@
+/**
+ * degradation-ladder — the 4-rung switch policy that answers the 5h pain.
+ *
+ * Driven by the subscription-window tracker (F2), NOT by 429s: it moves work to
+ * the secondary pool as the primary's rolling 5h budget heats up, BEFORE the wall
+ * — the whole point ("j'en ai marre de reach ma limite 5h"). It obeys the red
+ * line (F4, switch-tolerance): only delegable work crosses to Codex; BYAN's
+ * judgment/identity work stays on the primary, and queues rather than denatures
+ * when the primary is truly spent.
+ *
+ * Pure: takes a snapshot { primary, secondaries, pools: { name: poolState } } and
+ * a task nature; returns a routing decision. poolState is
+ * { windowProximity (0-1|null), pressureRecommendation ('ok'|'caution'|'switch_now'),
+ *   canAccept (bool), usable (bool) }. No clocks, no I/O — the caller assembles the
+ * snapshot from LoadBalancerLive.getWindowStates() + tracker states.
+ */
+
+const { isDelegable } = require('./switch-tolerance');
+
+const RUNGS = Object.freeze({
+  HEALTHY: 'HEALTHY',
+  PRIMARY_HOT: 'PRIMARY_HOT',
+  PRIMARY_EXHAUSTED: 'PRIMARY_EXHAUSTED',
+  ALL_EXHAUSTED: 'ALL_EXHAUSTED',
+});
+
+const CAUTION = 0.5;
+const SWITCH_NOW = 0.8;
+
+function poolExhausted(p) {
+  if (!p) return true;
+  if (p.canAccept === false) return true;
+  if (p.pressureRecommendation === 'switch_now') return true;
+  if (typeof p.windowProximity === 'number' && p.windowProximity >= SWITCH_NOW) return true;
+  return false;
+}
+
+function poolHot(p) {
+  if (!p || poolExhausted(p)) return false;
+  if (p.pressureRecommendation === 'caution') return true;
+  if (typeof p.windowProximity === 'number' && p.windowProximity >= CAUTION) return true;
+  return false;
+}
+
+function poolUsable(p) {
+  return !!p && p.usable !== false && p.canAccept !== false && !poolExhausted(p);
+}
+
+function firstUsableSecondary(snapshot) {
+  for (const name of snapshot.secondaries || []) {
+    if (poolUsable(snapshot.pools[name])) return name;
+  }
+  return null;
+}
+
+// System-level rung (independent of the task nature).
+function computeRung(snapshot) {
+  const primary = snapshot.pools[snapshot.primary];
+  const usableSecondary = firstUsableSecondary(snapshot);
+
+  if (poolExhausted(primary)) {
+    return {
+      rung: usableSecondary ? RUNGS.PRIMARY_EXHAUSTED : RUNGS.ALL_EXHAUSTED,
+      usableSecondary,
+    };
+  }
+  if (poolHot(primary)) return { rung: RUNGS.PRIMARY_HOT, usableSecondary };
+  return { rung: RUNGS.HEALTHY, usableSecondary };
+}
+
+// Routing decision for ONE task, given its nature. Returns
+// { action: 'route'|'queue', target: providerName|null, rung, delegable, reason }.
+function decideRoute(snapshot, nature) {
+  const { rung, usableSecondary } = computeRung(snapshot);
+  const primary = snapshot.primary;
+  const primaryPool = snapshot.pools[primary];
+  const delegable = isDelegable(nature);
+
+  // Red line: primary-only work (judgment/identity) never crosses to a secondary.
+  if (!delegable) {
+    if (primaryPool && primaryPool.canAccept !== false) {
+      return {
+        action: 'route',
+        target: primary,
+        rung,
+        delegable: false,
+        reason: `primary-only nature '${nature}' stays on ${primary} (red line: no denaturing), even at rung ${rung}`,
+      };
+    }
+    return {
+      action: 'queue',
+      target: null,
+      rung,
+      delegable: false,
+      reason: `primary '${primary}' cannot accept and nature '${nature}' is primary-only — queue rather than denature by crossing to a secondary`,
+    };
+  }
+
+  // Delegable work follows the pressure.
+  if (rung === RUNGS.HEALTHY) {
+    return { action: 'route', target: primary, rung, delegable: true, reason: `primary ${primary} healthy — no switch needed` };
+  }
+
+  if (usableSecondary) {
+    return {
+      action: 'route',
+      target: usableSecondary,
+      rung,
+      delegable: true,
+      reason: `primary ${primary} at rung ${rung} — delegable '${nature}' offloaded to ${usableSecondary}`,
+    };
+  }
+
+  // No usable secondary. Ride the primary while it still accepts, else queue.
+  if (primaryPool && primaryPool.canAccept !== false) {
+    return { action: 'route', target: primary, rung, delegable: true, reason: `no usable secondary at rung ${rung} — riding ${primary} (degraded)` };
+  }
+  return { action: 'queue', target: null, rung, delegable: true, reason: `all pools exhausted at rung ${rung} — queue with backoff` };
+}
+
+module.exports = { computeRung, decideRoute, RUNGS, poolExhausted, poolHot, poolUsable, CAUTION, SWITCH_NOW };

package/src/loadbalancer/loadbalancer.default.yaml

@@ -3,6 +3,9 @@
 
 providers:
   copilot:
+    # Optional pool. Needs @github/copilot-sdk, an EXTERNAL optional dep NOT pinned
+    # in package.json (no fabricated version): the provider degrades to disabled if
+    # the SDK is absent. Install it manually to enable this pool.
     enabled: true
     sdk: "@github/copilot-sdk"
     transport: "json-rpc"
@@ -20,13 +23,32 @@ providers:
       worker: "claude-haiku-4.5"
       agent: "claude-sonnet-4.5"
 
+  codex:
+    # OpenAI Codex pool. Backed by the `codex` SYSTEM CLI (codex-cli), spawned in
+    # headless `codex exec --json` mode — NOT an npm SDK, so nothing to install via
+    # package.json; the provider degrades to disabled if the binary is absent.
+    # Two auth pools back the same binary: CODEX_API_KEY (per-token, no weekly cap)
+    # wins when set, else the ChatGPT-subscription session (~/.codex/auth.json,
+    # the 5h + weekly window). Sandbox is bounded for automation.
+    enabled: true
+    bin: "codex"
+    transport: "cli-exec"
+    auth_env: "CODEX_API_KEY"
+    sandbox: "read-only"
+    max_context_tokens: 256000
+    # Plain gpt-5.x is the entitled family on a ChatGPT subscription; -codex ids
+    # are API-key only (rejected on subscription). See resolveCodexModel.
+    models:
+      worker: "gpt-5.4"
+      agent: "gpt-5.4"
+
   byan_api:
     enabled: false
     url: "http://localhost:3737"
     auth_env: "BYAN_API_TOKEN"
 
 primary: "claude"
-fallback_order: ["copilot", "byan_api"]
+fallback_order: ["codex", "copilot", "byan_api"]
 
 rate_limits:
   window_ms: 60000

package/src/loadbalancer/mcp-server.js

@@ -24,12 +24,22 @@ const { RateLimitTracker } = require('./rate-limit-tracker');
 const { Metrics } = require('./metrics');
 const { VelocityEstimator } = require('./velocity-estimator');
 const { calculatePressure, formatPressureSummary } = require('./pressure-score');
+const { buildProviders } = require('./providers/factory');
+const { SessionBridge } = require('./session-bridge');
+const { GracefulDegradation } = require('./graceful-degradation');
+const { SubscriptionWindow } = require('./subscription-window');
+const { decideRoute } = require('./degradation-ladder');
 const { EventEmitter } = require('events');
 
 const VERSION = '0.2.0';
 
 class LoadBalancerLive extends EventEmitter {
-  constructor(config) {
+  /**
+   * @param {object} config - loaded loadbalancer config
+   * @param {object} [deps] - injectable seams for tests: { providers, bridge,
+   *   degradation, windows }. Omitted in production -> built from config.
+   */
+  constructor(config, deps = {}) {
     super();
     this.config = config;
     this.activeProvider = config.primary;
@@ -38,6 +48,7 @@ class LoadBalancerLive extends EventEmitter {
 
     this.trackers = {};
     this.velocities = {};
+    this.windows = {}; // subscription-window tracker per pool (F2 -> F3 wiring)
     this.metrics = new Metrics();
 
     const rlOpts = config.rate_limits || {};
@@ -60,12 +71,61 @@ class LoadBalancerLive extends EventEmitter {
         this.velocities[name].on('threshold_warning', (evt) => {
           this.emit('velocity_warning', evt);
         });
+
+        // Subscription-window burn tracker per pool (5h + weekly). Budgets are
+        // optional per-provider config; absent -> honest null proximity.
+        this.windows[name] = (deps.windows && deps.windows[name]) || new SubscriptionWindow(name, {
+          windowTokenBudget: prov.window_token_budget || null,
+          weeklyTokenBudget: prov.weekly_token_budget || null,
+        });
       }
     }
 
+    // Real execution surface (LB-01/LB-04/LB-STATE unblocked): a provider
+    // registry, a session bridge for cross-provider context transfer, and the
+    // graceful-degradation queue wired to this emitter's rate_limit_change events.
+    this.providers = deps.providers || buildProviders(config);
+    this.bridge = deps.bridge || (deps.store ? new SessionBridge({ store: deps.store, maxTokens: config.sessions?.context_summary_max_tokens }) : null);
+    this._initializedProviders = new Set();
+    this.degradation = deps.degradation || new GracefulDegradation({ lb: this });
+
     this.metrics.attachToLoadBalancer(this);
   }
 
+  // Order of pools to try: preferred first (if not 'auto'), then primary, then
+  // configured fallback order. Deduped, enabled-only.
+  _providerOrder(prefer) {
+    const order = [];
+    if (prefer && prefer !== 'auto') order.push(prefer);
+    order.push(this.config.primary, ...(this.config.fallback_order || []));
+    return [...new Set(order)].filter((n) => this.trackers[n]);
+  }
+
+  async _ensureAvailable(name) {
+    const provider = this.providers[name];
+    if (!provider) return false;
+    if (!this._initializedProviders.has(name)) {
+      try {
+        await provider.initialize();
+      } catch {
+        return false;
+      }
+      this._initializedProviders.add(name);
+    }
+    try {
+      return await provider.isAvailable();
+    } catch {
+      return false;
+    }
+  }
+
+  _recordWindowUsage(name, response) {
+    const w = this.windows[name];
+    if (w && typeof w.recordFromResponse === 'function') {
+      w.recordFromResponse(response, Date.now());
+    }
+  }
+
   getTracker(provider) {
     return this.trackers[provider] || null;
   }
@@ -201,45 +261,164 @@ class LoadBalancerLive extends EventEmitter {
     return result;
   }
 
-  async send(opts) {
+  // Real send (LB-01 unblocked): walk the provider order, skip pools that are
+  // rate-limited (tracker) or unauthenticated/absent (isAvailable), call the
+  // first healthy one, record success/429 + window usage. When NONE can serve,
+  // return a graceful degraded result (never a throw, never a stub message).
+  async send(opts = {}) {
+    for (const name of this._providerOrder(opts.preferProvider)) {
+      const tracker = this.trackers[name];
+      const provider = this.providers[name];
+      if (!provider || !tracker || !tracker.canAcceptRequest()) continue;
+      if (!(await this._ensureAvailable(name))) continue;
+
+      try {
+        const res = await provider.send({ prompt: opts.prompt, model: opts.model, sessionId: opts.sessionId });
+        if (res && res.rateLimited) {
+          this.record429(name, res.rateLimitHeaders || {});
+          continue; // try the next pool
+        }
+        this.recordSuccess(name);
+        this._recordWindowUsage(name, res);
+        this.activeProvider = name;
+        return { ...res, provider: name, degraded: false };
+      } catch (err) {
+        // Hard failure on this pool: record and try the next one.
+        this.record429(name, { source: 'send_error' });
+        continue;
+      }
+    }
+
     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),
+      content: null,
+      degraded: true,
+      rateLimited: true,
+      reason: 'no provider available (all rate-limited, unauthenticated, or absent)',
     };
   }
 
-  async switchProvider(opts) {
+  // Real switch (LB-04 unblocked): flip the active pool + record history, and —
+  // when a session bridge is configured — transfer the portable context so the
+  // target pool resumes with the summary/decisions, not a cold start. Without a
+  // bridge, the switch still happens; contextTransferred is honestly false.
+  async switchProvider(opts = {}) {
     const prev = this.activeProvider;
-    this.activeProvider = opts.target;
+    const target = opts.target;
+
+    let injectionPrompt = null;
+    let contextTransferred = false;
+    if (this.bridge && opts.sessionId && this.providers[prev]) {
+      try {
+        const transfer = await this.bridge.transfer(
+          this.providers[prev], target, opts.sessionId, opts.reason || 'manual_switch'
+        );
+        injectionPrompt = transfer.injectionPrompt;
+        contextTransferred = true;
+      } catch {
+        contextTransferred = false;
+      }
+    }
+
+    this.activeProvider = target;
     const entry = {
       timestamp: new Date().toISOString(),
       from: prev,
-      to: opts.target,
+      to: target,
       reason: opts.reason || 'manual_switch',
+      contextTransferred,
     };
     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.',
-    };
+
+    return { switched: true, from: prev, to: target, reason: opts.reason, contextTransferred, injectionPrompt };
   }
 
+  // Real context read (LB-STATE unblocked): the portable context via the bridge
+  // when a store is configured; otherwise the honest current-provider view with a
+  // note that no session store is wired (no fabricated "not yet integrated" stub).
   async getSessionContext(sessionId) {
+    const id = sessionId || 'current';
+    if (this.bridge && sessionId && this.providers[this.activeProvider]) {
+      try {
+        const context = await this.bridge.extract(this.providers[this.activeProvider], sessionId);
+        return { sessionId, provider: this.activeProvider, context };
+      } catch {
+        /* fall through to the no-context view */
+      }
+    }
     return {
-      sessionId: sessionId || 'current',
+      sessionId: id,
       provider: this.activeProvider,
       context: null,
-      message: 'SharedStateStore not yet integrated (LB-STATE).',
+      note: 'no session store configured; context transfer is unavailable this run',
+    };
+  }
+
+  // Per-pool subscription-window burn (F2), for the degradation ladder (F5) and
+  // the budget surface (F6).
+  getWindowStates(now = Date.now()) {
+    const out = {};
+    for (const [name, w] of Object.entries(this.windows)) {
+      out[name] = w.getState(now);
+    }
+    return out;
+  }
+
+  getDegradationStatus() {
+    return this.degradation ? this.degradation.getStatus() : null;
+  }
+
+  // Unified cross-pool budget view — the anti-"limite atteinte" dashboard. Per
+  // pool: rolling-5h + weekly burn, proximity (null when no budget is configured
+  // -> honest estimate), ETA, recommendation. Plus the current ladder rung. The
+  // note states the two hard truths plainly: this is an ESTIMATE (no provider
+  // exposes a machine-readable 5h quota), and load-balancing DOUBLES the ceiling,
+  // it does not remove it (Codex has its own 5h window).
+  getBudget(now = Date.now()) {
+    const windows = this.getWindowStates(now);
+    const pools = {};
+    for (const [name, w] of Object.entries(windows)) {
+      pools[name] = {
+        windowTokens: w.windowTokens,
+        windowProximity: w.windowProximity,
+        weekTokens: w.weekTokens,
+        weekProximity: w.weekProximity,
+        etaMinutes: w.etaMinutes === Infinity ? null : w.etaMinutes,
+        recommendation: w.recommendation,
+        budgetConfigured: w.windowBudget != null,
+      };
+    }
+    return {
+      pools,
+      rung: this.planRoute('exploration', now).rung,
+      note: 'estimate from observed token usage (no provider exposes a machine-readable 5h quota); load-balancing doubles the ceiling across pools, it does not remove it',
     };
   }
 
+  // Advisory routing plan for a task of a given nature: assembles the ladder
+  // snapshot from the window tracker + pressure + circuit-breaker state and
+  // returns the degradation decision (route to a pool, or queue). Side-effect
+  // free (uses canAccept, does not probe provider availability), so it is safe
+  // to call for planning; the actual send() still verifies isAvailable.
+  planRoute(nature, now = Date.now()) {
+    const quota = this.getQuota();
+    const windows = this.getWindowStates(now);
+    const secondaries = (this.config.fallback_order || []).filter((n) => this.trackers[n]);
+    const pools = {};
+    for (const name of [this.config.primary, ...secondaries]) {
+      const tracker = this.trackers[name];
+      if (!tracker) continue;
+      pools[name] = {
+        windowProximity: windows[name] ? windows[name].windowProximity : null,
+        pressureRecommendation: quota[name] ? quota[name].recommendation : 'ok',
+        canAccept: tracker.canAcceptRequest(),
+        usable: tracker.canAcceptRequest(),
+      };
+    }
+    return decideRoute({ primary: this.config.primary, secondaries, pools }, nature);
+  }
+
   destroy() {
     for (const tracker of Object.values(this.trackers)) {
       tracker.destroy();
@@ -247,6 +426,9 @@ class LoadBalancerLive extends EventEmitter {
     for (const ve of Object.values(this.velocities)) {
       ve.destroy();
     }
+    if (this.degradation && typeof this.degradation.destroy === 'function') {
+      this.degradation.destroy();
+    }
     this.removeAllListeners();
   }
 }