create-byan-agent 2.39.0 → 2.41.0

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

@@ -0,0 +1,260 @@
+/**
+ * CodexProvider — wraps the OpenAI Codex CLI (`codex exec`) as a load-balancer pool.
+ *
+ * Unlike ClaudeProvider / CopilotProvider (npm SDKs), Codex ships as a SYSTEM CLI
+ * (`/usr/bin/codex`, codex-cli). So this provider spawns the binary in headless
+ * mode (`codex exec --json`) and parses the JSON Lines stream, rather than
+ * require()-ing a package. If the binary is absent the provider degrades to
+ * initialized=false, exactly like a missing SDK — the load-balancer then skips it.
+ *
+ * Two auth pools back the same binary (the arbitrage the subscription tracker
+ * reads): CODEX_API_KEY (billed per token, no weekly cap) wins when set, else the
+ * ChatGPT-subscription session in ~/.codex/auth.json (the 5h + weekly window).
+ *
+ * Entitled-model rule (live-verified on codex-cli 0.101 against a ChatGPT
+ * subscription): the OpenAI backend REJECTS every `-codex`-suffixed model on a
+ * subscription account ("The '<model>' model is not supported when using Codex
+ * with a ChatGPT account") — those ids are API-key only. Only the plain gpt-5.x
+ * family (e.g. gpt-5.4) is entitled on a subscription. So the default model is a
+ * plain entitled id, and resolveCodexModel normalizes a `-codex` request to that
+ * default when the active pool is the subscription. On an API key, `-codex`
+ * models bill fine and pass through untouched.
+ *
+ * Security posture for automation: a bounded sandbox (`-s`, default read-only)
+ * keeps a delegated run safe; a workspace-write run is opt-in via config. There
+ * is no approval flag — `codex exec` is already non-interactive, so no `-a` is
+ * passed (it would be a hard "unexpected argument" error; see send()). The API
+ * key is read from the environment and passed to the child process env; it is
+ * never logged, never written to disk, never placed in argv.
+ *
+ * Testability: parseCodexJsonl and detectCodexAuth are pure; the spawn is behind
+ * this._runCodex and the binary probe behind this._probeBinary, so the unit tests
+ * never touch the real CLI, the network, or the user's OpenAI quota.
+ */
+
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+const { spawn } = require('child_process');
+const { BaseProvider } = require('./base-provider');
+
+// Parse a `codex exec --json` JSON Lines stream into { content, usage, threadId }.
+// Defensive by construction: blank lines and non-JSON noise are skipped (the CLI
+// may emit progress/log lines), agent-message items are concatenated in order,
+// and usage falls back to zero (never undefined) so downstream accounting is safe.
+function parseCodexJsonl(stdout) {
+  const parts = [];
+  let usage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+  let threadId = null;
+
+  for (const rawLine of String(stdout || '').split('\n')) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    let ev;
+    try {
+      ev = JSON.parse(line);
+    } catch {
+      continue; // non-JSON progress/log noise
+    }
+    if (!ev || typeof ev !== 'object') continue;
+
+    if (ev.type === 'thread.started' && ev.thread && ev.thread.id) {
+      threadId = ev.thread.id;
+      continue;
+    }
+
+    // Agent output: item events carrying a text payload. The item schema varies
+    // by codex version, so read text from the common shapes.
+    const item = ev.item || ev;
+    const itemType = item && item.type;
+    if (itemType === 'agent_message' || itemType === 'assistant_message' || itemType === 'message') {
+      const text = item.text || item.content || item.message;
+      if (typeof text === 'string' && text) parts.push(text);
+      continue;
+    }
+
+    if (ev.type === 'turn.completed' && ev.usage) {
+      const u = ev.usage;
+      const input = Number(u.input_tokens ?? u.input ?? 0) || 0;
+      const output = Number(u.output_tokens ?? u.output ?? 0) || 0;
+      usage = { inputTokens: input, outputTokens: output, totalTokens: input + output };
+    }
+  }
+
+  return { content: parts.join('\n'), usage, threadId };
+}
+
+// Decide which OpenAI pool backs the CLI. API key wins (per-token, no weekly cap);
+// else the ChatGPT-subscription session file; else no auth. Pure — env and fs are
+// injected so it is testable without a real home dir.
+function detectCodexAuth({ env = process.env, fs: fsImpl = fs, home = os.homedir() } = {}) {
+  if (env.CODEX_API_KEY) return 'api-key';
+  const authPath = path.join(home, '.codex', 'auth.json');
+  try {
+    if (fsImpl.existsSync(authPath)) return 'subscription';
+  } catch {
+    /* fall through */
+  }
+  return null;
+}
+
+// Rate-limit / quota-exhaustion detection from a failed codex exec. Codex has no
+// machine-readable quota (OpenAI issue #10233), so we key off the stderr text of
+// a non-zero exit. Conservative: only clear usage-limit language counts as a
+// rate-limit (a soft, retryable signal); any other failure is a hard error.
+const RATE_LIMIT_RE = /(usage limit|rate limit|rate_limit|quota|429|too many requests|limit reached)/i;
+
+function isRateLimitFailure({ code, stderr }) {
+  return code !== 0 && RATE_LIMIT_RE.test(String(stderr || ''));
+}
+
+// The plain gpt-5.x id verified entitled on a ChatGPT subscription (codex-cli
+// 0.101). The CLI/companion default is a `-codex` id that a subscription rejects,
+// so this is the safe default and the subscription remap target.
+const SUBSCRIPTION_DEFAULT_MODEL = 'gpt-5.4';
+
+// Pick the model that will actually be accepted by the active auth pool. On a
+// subscription, a `-codex`-suffixed id is API-only and would be rejected, so it
+// is remapped to the known-entitled default (we only remap what we KNOW fails,
+// and only to the one id verified to work — we do not guess stripped variants).
+// On an API key, or for an already-plain id, the request passes through. Pure.
+function resolveCodexModel({ requested, authPool } = {}) {
+  const model = String(requested || '').trim();
+  if (!model) return SUBSCRIPTION_DEFAULT_MODEL;
+  if (authPool === 'subscription' && /-codex$/i.test(model)) {
+    return SUBSCRIPTION_DEFAULT_MODEL;
+  }
+  return model;
+}
+
+class CodexProvider extends BaseProvider {
+  constructor(providerConfig = {}) {
+    super('codex', providerConfig);
+    this._auth = null;
+  }
+
+  // Probe whether the codex binary is on PATH (spawn `codex --version`). Seam for
+  // tests. Resolves boolean, never throws.
+  async _probeBinary() {
+    return new Promise((resolve) => {
+      let done = false;
+      const finish = (ok) => { if (!done) { done = true; resolve(ok); } };
+      try {
+        const bin = this.config.bin || 'codex';
+        const child = spawn(bin, ['--version'], { stdio: 'ignore' });
+        child.on('error', () => finish(false));
+        child.on('close', (code) => finish(code === 0));
+      } catch {
+        finish(false);
+      }
+    });
+  }
+
+  _detectAuth() {
+    return detectCodexAuth({});
+  }
+
+  async initialize() {
+    const present = await this._probeBinary();
+    this.initialized = present === true;
+    if (this.initialized) this._auth = this._detectAuth();
+  }
+
+  authPool() {
+    return this._detectAuth();
+  }
+
+  async isAvailable() {
+    if (!this.initialized) return false;
+    return this._detectAuth() !== null;
+  }
+
+  // Spawn `codex exec --json` and collect { stdout, stderr, code }. Seam for tests.
+  // The prompt is passed on stdin (never argv — avoids leaking it into ps output).
+  async _runCodex(args, input, env) {
+    return new Promise((resolve, reject) => {
+      let child;
+      try {
+        child = spawn(this.config.bin || 'codex', args, {
+          env: { ...process.env, ...env },
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+      } catch (err) {
+        reject(err);
+        return;
+      }
+      let stdout = '';
+      let stderr = '';
+      child.stdout.on('data', (d) => { stdout += d; });
+      child.stderr.on('data', (d) => { stderr += d; });
+      child.on('error', reject);
+      child.on('close', (code) => resolve({ stdout, stderr, code }));
+      if (input) child.stdin.write(input);
+      child.stdin.end();
+    });
+  }
+
+  async send(opts) {
+    if (!this.initialized) throw new Error('CodexProvider not initialized');
+
+    const start = Date.now();
+    const requested = opts.model || this.config.models?.agent || SUBSCRIPTION_DEFAULT_MODEL;
+    // Normalize to an id the active auth pool will accept (a -codex model is
+    // API-only; a subscription would reject it). See resolveCodexModel.
+    const model = resolveCodexModel({ requested, authPool: this._detectAuth() });
+    const sandbox = this.config.sandbox || 'read-only';
+
+    // Non-interactive automation contract, verified against codex-cli 0.101.0
+    // `codex exec --help`: exec is ALREADY non-interactive (reads the prompt from
+    // stdin, prints JSONL events) so there is no `-a`/approval flag on the exec
+    // subcommand — passing one is a hard "unexpected argument" error. The bounded
+    // sandbox (`-s read-only` by default) is what keeps a delegated run safe; a
+    // workspace-write run is an explicit config opt-in.
+    const args = ['exec', '--json', '-s', sandbox, '-m', model];
+
+    const { stdout, stderr, code } = await this._runCodex(args, opts.prompt, {});
+
+    if (isRateLimitFailure({ code, stderr })) {
+      return {
+        provider: this.name,
+        content: null,
+        model,
+        rateLimitHeaders: null,
+        latencyMs: Date.now() - start,
+        rateLimited: true,
+      };
+    }
+
+    if (code !== 0) {
+      throw new Error(`codex exec failed (exit ${code}): ${String(stderr).split('\n')[0]}`);
+    }
+
+    const parsed = parseCodexJsonl(stdout);
+    return {
+      provider: this.name,
+      content: parsed.content,
+      model,
+      threadId: parsed.threadId,
+      usage: parsed.usage,
+      rateLimitHeaders: null,
+      latencyMs: Date.now() - start,
+      rateLimited: false,
+    };
+  }
+
+  getCapabilities() {
+    return {
+      streaming: false, // exec is request/response; --json streams events, not tokens
+      tools: true, // codex runs tools in its sandbox
+      multiTurn: true, // thread id enables continuation
+      maxContextTokens: this.config.max_context_tokens || 256000,
+    };
+  }
+
+  async destroy() {
+    this._auth = null;
+    await super.destroy();
+  }
+}
+
+module.exports = { CodexProvider, parseCodexJsonl, detectCodexAuth, isRateLimitFailure, resolveCodexModel, SUBSCRIPTION_DEFAULT_MODEL };

package/src/loadbalancer/providers/factory.js

@@ -0,0 +1,36 @@
+/**
+ * Provider factory — build the { name: ProviderInstance } registry from config.
+ *
+ * The one place that knows which provider class backs each config name. The
+ * LoadBalancer engine and the MCP shell both consume this instead of hand-wiring
+ * instances, so adding a pool (codex) is one line here, not N call sites.
+ */
+
+const { ClaudeProvider } = require('./claude-provider');
+const { CopilotProvider } = require('./copilot-provider');
+const { CodexProvider } = require('./codex-provider');
+const { ByanApiProvider } = require('./byan-api-provider');
+
+const PROVIDER_CLASSES = Object.freeze({
+  claude: ClaudeProvider,
+  copilot: CopilotProvider,
+  codex: CodexProvider,
+  byan_api: ByanApiProvider,
+});
+
+// buildProviders(config) -> { name: instance } for every ENABLED provider whose
+// name is known. Unknown names are skipped (never fatal) so a typo in config
+// degrades to "that pool is absent", not a crash.
+function buildProviders(config) {
+  const out = {};
+  const providers = (config && config.providers) || {};
+  for (const [name, section] of Object.entries(providers)) {
+    if (section && section.enabled === false) continue;
+    const Cls = PROVIDER_CLASSES[name];
+    if (!Cls) continue;
+    out[name] = new Cls(section || {});
+  }
+  return out;
+}
+
+module.exports = { buildProviders, PROVIDER_CLASSES };

package/src/loadbalancer/subscription-window.js

@@ -0,0 +1,142 @@
+/**
+ * SubscriptionWindow — per-pool burn against the rolling 5h + weekly caps.
+ *
+ * pressure-score.js answers "am I getting 429'd right now" (an API burst signal
+ * from the circuit breaker). This module answers the ORTHOGONAL question the 5h
+ * subscription pain is actually about: "how much of my rolling 5-hour and weekly
+ * budget have I already burned on this pool" (Claude Pro/Max = chat+code shared;
+ * Codex = local+cloud shared). The degradation ladder (F5) reads THIS to switch
+ * delegable work to the other pool BEFORE the wall, not after the first 429.
+ *
+ * Honest by construction: neither Claude nor Codex exposes a machine-readable 5h
+ * quota (OpenAI issue #10233). So this is an ESTIMATE from observed token usage.
+ * Without a configured budget it reports raw burn + velocity and a NULL proximity
+ * (never a fabricated percentage); with a budget it reports proximity + an ETA to
+ * exhaustion at recent velocity. The surface (F6) reconciles against /usage.
+ *
+ * The core (computeWindowState) is pure — `now` is injected, no Date.now — so the
+ * rolling windows are deterministic under test.
+ */
+
+const FIVE_HOURS_MS = 5 * 60 * 60 * 1000;
+const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+const DEFAULT_VELOCITY_WINDOW_MS = 15 * 60 * 1000; // recent-rate window for ETA
+
+function sumTokensSince(events, cutoff) {
+  let total = 0;
+  for (const e of events) {
+    if (e && e.timestamp > cutoff && Number.isFinite(e.tokens)) total += e.tokens;
+  }
+  return total;
+}
+
+function clampProximity(tokens, budget) {
+  if (!budget || budget <= 0) return null; // no budget => estimate only, never fabricate a %
+  return Math.min(1, tokens / budget);
+}
+
+// Pure. events: [{ timestamp, tokens }]. Returns the window/week burn, proximity
+// (null when the matching budget is absent), and an ETA to window-budget
+// exhaustion at the recent velocity.
+function computeWindowState(events, opts = {}) {
+  const {
+    now,
+    windowMs = FIVE_HOURS_MS,
+    weekMs = WEEK_MS,
+    windowTokenBudget = null,
+    weeklyTokenBudget = null,
+    velocityWindowMs = DEFAULT_VELOCITY_WINDOW_MS,
+  } = opts;
+
+  const windowTokens = sumTokensSince(events, now - windowMs);
+  const weekTokens = sumTokensSince(events, now - weekMs);
+
+  const windowProximity = clampProximity(windowTokens, windowTokenBudget);
+  const weekProximity = clampProximity(weekTokens, weeklyTokenBudget);
+
+  // ETA: recent velocity (tokens/min over velocityWindowMs) projected onto the
+  // remaining window budget. Infinite when idle or when no budget is known.
+  let etaMinutes = Infinity;
+  if (windowTokenBudget && windowTokenBudget > 0) {
+    const recentTokens = sumTokensSince(events, now - velocityWindowMs);
+    const perMin = recentTokens / (velocityWindowMs / 60000);
+    const remaining = Math.max(0, windowTokenBudget - windowTokens);
+    if (perMin > 0) etaMinutes = Math.round(remaining / perMin);
+  }
+
+  return {
+    windowTokens,
+    weekTokens,
+    windowProximity,
+    weekProximity,
+    windowBudget: windowTokenBudget,
+    weeklyBudget: weeklyTokenBudget,
+    etaMinutes,
+  };
+}
+
+// Recommendation from a proximity in [0,1]. Mirrors pressure-score's bands so the
+// two signals speak the same language to the ladder. Null proximity => unknown.
+function windowRecommendation(proximity) {
+  if (proximity === null || proximity === undefined) return 'unknown';
+  if (proximity >= 0.8) return 'switch_now';
+  if (proximity >= 0.5) return 'caution';
+  return 'ok';
+}
+
+class SubscriptionWindow {
+  /**
+   * @param {string} pool - 'claude' | 'codex' | ...
+   * @param {object} opts - { windowTokenBudget, weeklyTokenBudget, windowMs, weekMs, velocityWindowMs }
+   */
+  constructor(pool, opts = {}) {
+    this.pool = pool;
+    this.opts = opts;
+    this.weekMs = opts.weekMs || WEEK_MS;
+    this.events = [];
+  }
+
+  record({ tokens, timestamp }) {
+    if (!Number.isFinite(tokens) || tokens <= 0) return;
+    this.events.push({ tokens, timestamp });
+  }
+
+  // Extract usage from a ProviderResponse ({ usage: { totalTokens } }). No-op when
+  // the response carries no usage (e.g. a rate-limited response).
+  recordFromResponse(response, timestamp) {
+    const total = response && response.usage && Number(response.usage.totalTokens);
+    if (Number.isFinite(total) && total > 0) this.record({ tokens: total, timestamp });
+  }
+
+  _prune(now) {
+    const cutoff = now - this.weekMs;
+    this.events = this.events.filter((e) => e.timestamp > cutoff);
+  }
+
+  getState(now) {
+    this._prune(now);
+    const state = computeWindowState(this.events, { now, ...this.opts });
+    return {
+      pool: this.pool,
+      ...state,
+      recommendation: windowRecommendation(state.windowProximity),
+    };
+  }
+
+  eventCount() {
+    return this.events.length;
+  }
+
+  reset() {
+    this.events = [];
+  }
+}
+
+module.exports = {
+  SubscriptionWindow,
+  computeWindowState,
+  windowRecommendation,
+  sumTokensSince,
+  FIVE_HOURS_MS,
+  WEEK_MS,
+};

package/src/loadbalancer/switch-tolerance.js

@@ -0,0 +1,63 @@
+/**
+ * switch-tolerance — WHICH task natures may cross to a secondary provider pool.
+ *
+ * The load-balancer's model tier answers "which model" (native-tiers). THIS
+ * answers the orthogonal, identity-critical axis the user drew as the red line:
+ * "reduce tokens WITHOUT denaturing BYAN". Degradation (F5) may offload only
+ * DELEGABLE work to a secondary pool (Codex): mechanical checks (machine-
+ * verifiable output), exploration (read/scan), and implementation (where tests
+ * are the objective arbiter, provider-independent). Everything that carries
+ * BYAN's judgment or identity — verification (adversarial/semantic), analysis,
+ * and anything soul/identity/review/gate — stays on the primary (Claude) whatever
+ * the subscription pressure. This module is the single source of that line.
+ *
+ * Pure and dependency-light: an optional CapabilityMatrix filters secondaries by
+ * required capability, but the tolerance decision itself is a static classification.
+ */
+
+const DELEGABLE_NATURES = Object.freeze(['exploration', 'mechanical', 'implementation']);
+const PRIMARY_ONLY_NATURES = Object.freeze([
+  'verification', // adversarial / semantic review = BYAN judgment
+  'analysis', // design / risk / evaluation = BYAN judgment
+  'soul', // identity
+  'identity',
+  'review', // the adversarial second pair of eyes stays on the primary
+  'gate', // phase / strict gates
+]);
+
+const SWITCH_TOLERANCE = Object.freeze({
+  ...Object.fromEntries(DELEGABLE_NATURES.map((n) => [n, 'delegable'])),
+  ...Object.fromEntries(PRIMARY_ONLY_NATURES.map((n) => [n, 'primary-only'])),
+});
+
+// Conservative: only an explicitly-delegable nature is delegable. Unknown /
+// missing nature => primary-only (never delegate on a guess — the red line).
+function isDelegable(nature) {
+  return SWITCH_TOLERANCE[nature] === 'delegable';
+}
+
+// eligibleProviders(nature, { primary, secondaries, capabilityMatrix, required })
+// -> ordered provider list, primary first. A primary-only nature returns only the
+// primary. A delegable nature returns primary + secondaries that satisfy the
+// required capabilities (when a matrix + required list are supplied).
+function eligibleProviders(nature, opts = {}) {
+  const { primary, secondaries = [], capabilityMatrix = null, required = [] } = opts;
+  if (!primary) return [];
+  if (!isDelegable(nature)) return [primary];
+
+  let allowed = secondaries;
+  if (capabilityMatrix && required.length > 0) {
+    allowed = secondaries.filter((name) =>
+      required.every((cap) => capabilityMatrix.supports(name, cap))
+    );
+  }
+  return [primary, ...allowed.filter((n) => n !== primary)];
+}
+
+module.exports = {
+  SWITCH_TOLERANCE,
+  DELEGABLE_NATURES,
+  PRIMARY_ONLY_NATURES,
+  isDelegable,
+  eligibleProviders,
+};

package/src/loadbalancer/tools/index.js

@@ -27,7 +27,7 @@ function createTools(lb) {
         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)' },
+          prefer_provider: { type: 'string', enum: ['claude', 'copilot', 'codex', 'auto'], description: 'Provider preference (default: auto)' },
         },
         required: ['prompt'],
       },
@@ -46,7 +46,7 @@ function createTools(lb) {
       inputSchema: {
         type: 'object',
         properties: {
-          target_provider: { type: 'string', enum: ['claude', 'copilot'], description: 'Provider to switch to' },
+          target_provider: { type: 'string', enum: ['claude', 'copilot', 'codex'], description: 'Provider to switch to' },
           session_id: { type: 'string', description: 'Session to transfer context from' },
           reason: { type: 'string', description: 'Reason for the switch' },
         },
@@ -117,6 +117,21 @@ function createTools(lb) {
         return { content: [{ type: 'text', text: summaries + '\n\n' + JSON.stringify(quota, null, 2) }] };
       },
     },
+    {
+      name: 'lb_budget',
+      description: 'Unified cross-pool subscription budget: rolling-5h + weekly token burn per pool (Claude / Codex), proximity to the cap (null when no budget configured), ETA to exhaustion, and the current degradation rung. The anti-"5h limit reached" dashboard. Honest estimate: no provider exposes a machine-readable 5h quota, and load-balancing doubles the ceiling across pools without removing it.',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+      },
+      handler: async () => {
+        if (typeof lb.getBudget !== 'function') {
+          return { content: [{ type: 'text', text: 'lb_budget requires LoadBalancerLive with the subscription-window tracker.' }] };
+        }
+        const budget = lb.getBudget();
+        return { content: [{ type: 'text', text: JSON.stringify(budget, null, 2) }] };
+      },
+    },
   ];
 }