bullswarm 0.1.4

package/src/meters/codex.js

@@ -0,0 +1,264 @@
+// bullswarm codex meter — ChatGPT WHAM usage API.
+// Endpoint + auth flow documented by OpenUsage (MIT, robinebers/openusage);
+// implemented here independently for bullswarm.
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const USAGE_URL = 'https://chatgpt.com/backend-api/wham/usage';
+const REFRESH_URL = 'https://auth.openai.com/oauth/token';
+const CLIENT_ID = 'app_EMoamEEZ73f0CkXaXp7hrann';
+const FIVE_HOUR_SECONDS = 5 * 60 * 60;
+const SEVEN_DAY_SECONDS = 7 * 24 * 60 * 60;
+const REFRESH_BUFFER_MS = 5 * 60_000;
+
+export class CodexMeterError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code; // no_auth | api_key_only | http | parse | network
+  }
+}
+
+function authPath() {
+  const home = process.env.CODEX_HOME?.trim() || path.join(os.homedir(), '.codex');
+  return path.join(home, 'auth.json');
+}
+
+export function loadAuth() {
+  const p = authPath();
+  if (!existsSync(p)) {
+    throw new CodexMeterError('Codex not logged in. Run `codex` to authenticate.', 'no_auth');
+  }
+  let auth;
+  try {
+    auth = JSON.parse(readFileSync(p, 'utf8'));
+  } catch {
+    throw new CodexMeterError('Codex auth.json unreadable. Re-run `codex` login.', 'no_auth');
+  }
+  const access = auth.tokens?.access_token?.trim();
+  if (!access) {
+    if (auth.OPENAI_API_KEY?.trim()) {
+      throw new CodexMeterError(
+        'Codex usage needs ChatGPT-account auth (API-key-only cannot read subscription usage).',
+        'api_key_only',
+      );
+    }
+    throw new CodexMeterError('Codex auth has no access token.', 'no_auth');
+  }
+  return { auth, path: p };
+}
+
+/** JWT exp claim in ms, or null when undecodable. */
+export function accessTokenExpiresAtMs(token) {
+  const parts = token.split('.');
+  if (parts.length < 2) return null;
+  try {
+    const pad = '='.repeat((4 - (parts[1].length % 4)) % 4);
+    const payload = JSON.parse(Buffer.from(parts[1] + pad, 'base64url').toString('utf8'));
+    return typeof payload.exp === 'number' ? payload.exp * 1000 : null;
+  } catch {
+    return null;
+  }
+}
+
+export function needsRefresh(accessToken, lastRefresh, nowMs = Date.now()) {
+  const expMs = accessTokenExpiresAtMs(accessToken);
+  if (expMs !== null) return nowMs >= expMs - REFRESH_BUFFER_MS;
+  if (!lastRefresh) return false;
+  const ms = Date.parse(lastRefresh);
+  return Number.isFinite(ms) && nowMs - ms > 8 * 24 * 3600_000;
+}
+
+async function refreshAccessToken(auth, filePath) {
+  const refresh = auth.tokens?.refresh_token?.trim();
+  if (!refresh) return null;
+  let res;
+  try {
+    res = await fetch(REFRESH_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        grant_type: 'refresh_token',
+        client_id: CLIENT_ID,
+        refresh_token: refresh,
+      }).toString(),
+    });
+  } catch {
+    return null;
+  }
+  if (!res.ok) return null;
+  try {
+    const j = await res.json();
+    if (typeof j.access_token !== 'string' || !j.access_token) return null;
+    const next = {
+      ...auth,
+      tokens: {
+        ...auth.tokens,
+        access_token: j.access_token,
+        refresh_token: j.refresh_token ?? auth.tokens?.refresh_token,
+        id_token: j.id_token ?? auth.tokens?.id_token,
+      },
+      last_refresh: new Date().toISOString(),
+    };
+    // Best-effort write-back so the CLI shares the rotated token.
+    try {
+      writeFileSync(filePath, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    } catch {
+      /* in-memory token still works */
+    }
+    return { accessToken: j.access_token, auth: next };
+  } catch {
+    return null;
+  }
+}
+
+// --- pure decoder (unit-tested without network) ------------------------------
+
+function numberOf(v) {
+  if (typeof v === 'number' && Number.isFinite(v)) return v;
+  if (typeof v === 'string' && v.trim()) {
+    const n = Number(v);
+    if (Number.isFinite(n)) return n;
+  }
+  return undefined;
+}
+
+function windowSeconds(raw) {
+  if (!raw) return undefined;
+  const sec = numberOf(raw.limit_window_seconds);
+  if (sec !== undefined) return sec;
+  const minutes = numberOf(raw.window_minutes);
+  if (minutes !== undefined) return minutes * 60;
+  return undefined;
+}
+
+function normalizeWindow(raw, headerPercent, nowMs) {
+  const used = numberOf(raw?.used_percent) ?? headerPercent;
+  if (used === undefined) return null;
+  let resetsAt = null;
+  const resetUnix = numberOf(raw?.reset_at) ?? numberOf(raw?.resets_at);
+  if (resetUnix !== undefined) {
+    resetsAt = new Date(resetUnix * 1000).toISOString();
+  } else {
+    const after = numberOf(raw?.reset_after_seconds);
+    if (after !== undefined) resetsAt = new Date(nowMs + after * 1000).toISOString();
+  }
+  return { utilization: Math.min(100, Math.max(0, used)), resets_at: resetsAt };
+}
+
+/**
+ * Decode the WHAM body (+ optional x-codex-*-used-percent headers).
+ * Classification prefers explicit limit_window_seconds over slot order:
+ * a sole weekly window can appear in the primary slot.
+ */
+export function parseCodexWhamUsage(body, headers = {}, nowMs = Date.now()) {
+  if (!body || typeof body !== 'object') {
+    throw new CodexMeterError('Codex usage response missing body', 'parse');
+  }
+  const rateLimit =
+    body.rate_limit && typeof body.rate_limit === 'object' ? body.rate_limit : {};
+  const headerPrimary = numberOf(headers['x-codex-primary-used-percent']);
+  const headerSecondary = numberOf(headers['x-codex-secondary-used-percent']);
+  const primary = rateLimit.primary_window ?? null;
+  const secondary = rateLimit.secondary_window ?? null;
+
+  const candidates = [
+    { raw: primary, headerPercent: headerPrimary, fallback: 'five_hour' },
+    { raw: secondary, headerPercent: headerSecondary, fallback: 'seven_day' },
+  ];
+
+  let fiveHour = null;
+  let sevenDay = null;
+  for (const c of candidates) {
+    const secs = windowSeconds(c.raw);
+    const w = normalizeWindow(c.raw, c.headerPercent, nowMs);
+    if (!w) continue;
+    if (secs === FIVE_HOUR_SECONDS) fiveHour ??= w;
+    else if (secs === SEVEN_DAY_SECONDS) sevenDay ??= w;
+  }
+  if (!fiveHour || !sevenDay) {
+    for (const c of candidates) {
+      const secs = windowSeconds(c.raw);
+      if (secs === FIVE_HOUR_SECONDS || secs === SEVEN_DAY_SECONDS) continue;
+      const w = normalizeWindow(c.raw, c.headerPercent, nowMs);
+      if (!w) continue;
+      if (c.fallback === 'five_hour' && !fiveHour) fiveHour = w;
+      else if (c.fallback === 'seven_day' && !sevenDay) sevenDay = w;
+    }
+  }
+
+  const planRaw = body.plan_type;
+  return {
+    five_hour: fiveHour ?? { utilization: null, resets_at: null },
+    seven_day: sevenDay ?? { utilization: null, resets_at: null },
+    plan_type: typeof planRaw === 'string' && planRaw.trim() ? planRaw.trim() : null,
+  };
+}
+
+// --- live fetch ----------------------------------------------------------------
+
+async function fetchUsageResponse(accessToken, accountId) {
+  let res;
+  try {
+    res = await fetch(USAGE_URL, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: 'application/json',
+        'User-Agent': 'bullswarm',
+        ...(accountId?.trim() ? { 'ChatGPT-Account-Id': accountId.trim() } : {}),
+      },
+    });
+  } catch (err) {
+    throw new CodexMeterError(`Network error reaching Codex usage: ${err.message}`, 'network');
+  }
+  const headers = {};
+  res.headers.forEach((value, key) => (headers[key.toLowerCase()] = value));
+  let body = null;
+  try {
+    body = await res.json();
+  } catch {
+    /* parse layer errors if needed */
+  }
+  return { status: res.status, body, headers };
+}
+
+export async function fetchCodexUsage() {
+  const loaded = loadAuth();
+  let auth = loaded.auth;
+  let access = auth.tokens.access_token.trim();
+  const accountId = auth.tokens?.account_id;
+
+  if (needsRefresh(access, auth.last_refresh)) {
+    const refreshed = await refreshAccessToken(auth, loaded.path);
+    if (refreshed) {
+      access = refreshed.accessToken;
+      auth = refreshed.auth;
+    }
+  }
+
+  let { status, body, headers } = await fetchUsageResponse(access, accountId);
+  if (status === 401 || status === 403) {
+    const refreshed = await refreshAccessToken(auth, loaded.path);
+    if (refreshed) {
+      access = refreshed.accessToken;
+      ({ status, body, headers } = await fetchUsageResponse(access, accountId));
+    }
+  }
+  if (status < 200 || status >= 300) {
+    throw new CodexMeterError(
+      `Codex usage returned HTTP ${status}`,
+      status === 401 || status === 403 ? 'no_auth' : 'http',
+    );
+  }
+
+  const windows = parseCodexWhamUsage(body, headers);
+  return {
+    captured_at: new Date().toISOString(),
+    pool: 'codex',
+    five_hour: windows.five_hour,
+    seven_day: windows.seven_day,
+    monthly: null,
+    plan_type: windows.plan_type,
+  };
+}

package/src/meters/command-code.js

@@ -0,0 +1,218 @@
+// bullswarm command-code meter — Command Code alpha billing endpoints
+// (the same ones the CLI's /usage overlay calls). Monthly credits plus
+// 5-hour and weekly rate-limit windows.
+
+import { existsSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const DEFAULT_API_BASE = 'https://api.commandcode.ai';
+const CREDITS_PATH = '/alpha/billing/credits';
+const SUBSCRIPTIONS_PATH = '/alpha/billing/subscriptions';
+
+const PLAN_NAMES = {
+  'individual-go': 'Go',
+  'individual-goat': 'GOAT',
+  'individual-pro': 'Pro',
+  'individual-pro-v1': 'Pro',
+  'individual-provider': 'Provider',
+  'individual-max': 'Max',
+  'individual-ultra': 'Ultra',
+  'teams-pro': 'Teams Pro',
+};
+
+const PLAN_CREDITS = {
+  'individual-go': 10,
+  'individual-goat': 70,
+  'individual-pro': 30,
+  'individual-pro-v1': 80,
+  'individual-provider': 15,
+  'individual-max': 150,
+  'individual-ultra': 300,
+  'teams-pro': 40,
+};
+
+export class CommandCodeMeterError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code; // no_auth | http | parse | network
+  }
+}
+
+function authPath() {
+  const home =
+    process.env.COMMANDCODE_HOME?.trim() || path.join(os.homedir(), '.commandcode');
+  return path.join(home, 'auth.json');
+}
+
+export function loadApiKey() {
+  const p = authPath();
+  if (!existsSync(p)) {
+    throw new CommandCodeMeterError('Command Code not logged in. Run `cmd login`.', 'no_auth');
+  }
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(p, 'utf8'));
+  } catch {
+    throw new CommandCodeMeterError('Command Code auth.json unreadable.', 'no_auth');
+  }
+  const key = typeof raw.apiKey === 'string' ? raw.apiKey.trim() : '';
+  if (!key) {
+    throw new CommandCodeMeterError('Command Code auth has no API key.', 'no_auth');
+  }
+  return key;
+}
+
+// --- pure decoders ---------------------------------------------------------------
+
+export function parseCommandCodeCredits(body) {
+  if (!body || typeof body !== 'object') {
+    throw new CommandCodeMeterError('credits response missing body', 'parse');
+  }
+  const credits = body.credits;
+  if (!credits || typeof credits !== 'object') {
+    throw new CommandCodeMeterError('credits response missing credits object', 'parse');
+  }
+  const asCredit = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+  return {
+    remaining: asCredit(credits.monthlyCredits),
+    purchased: asCredit(credits.purchasedCredits) ?? 0,
+    free: asCredit(credits.freeCredits) ?? 0,
+    planId: typeof credits.planId === 'string' && credits.planId.trim() ? credits.planId.trim() : null,
+  };
+}
+
+export function parseCommandCodeWindow(raw) {
+  if (!raw || typeof raw !== 'object') return { utilization: null, resets_at: null };
+  const used = Number(raw.used);
+  const cap = Number(raw.cap);
+  let utilization = null;
+  if (Number.isFinite(used) && Number.isFinite(cap) && cap > 0) {
+    utilization = Math.min(100, Math.max(0, (used / cap) * 100));
+  }
+  let resets_at = null;
+  const resetAt = Number(raw.resetAt);
+  if (Number.isFinite(resetAt) && resetAt > 0) {
+    const iso = new Date(resetAt).toISOString();
+    resets_at = Number.isNaN(Date.parse(iso)) ? null : iso;
+  }
+  return { utilization, resets_at };
+}
+
+export function parseCommandCodeWindows(body) {
+  const empty = { utilization: null, resets_at: null };
+  const limits = body?.windowLimits;
+  if (!limits || typeof limits !== 'object') return { five_hour: empty, seven_day: empty };
+  return {
+    five_hour: parseCommandCodeWindow(limits.fiveHour),
+    seven_day: parseCommandCodeWindow(limits.weekly),
+  };
+}
+
+export function planMonthlyCredits(planId) {
+  if (typeof planId !== 'string' || !planId.trim()) return null;
+  const key = planId.trim().toLowerCase().replace(/_/g, '-');
+  if (PLAN_CREDITS[key] !== undefined) return PLAN_CREDITS[key];
+  const match = Object.keys(PLAN_NAMES)
+    .sort((a, b) => b.length - a.length)
+    .find((p) => key.startsWith(p));
+  return match ? PLAN_CREDITS[match] ?? null : null;
+}
+
+export function parseCommandCodeSubscription(body) {
+  const data = body?.data;
+  const planId = typeof data?.planId === 'string' && data.planId.trim() ? data.planId.trim() : null;
+  const periodEnd = data?.currentPeriodEnd;
+  return {
+    planId,
+    plan_type: planId ? (PLAN_NAMES[planId.toLowerCase()] ?? planId) : null,
+    currentPeriodEnd:
+      typeof periodEnd === 'string' && Number.isFinite(Date.parse(periodEnd))
+        ? new Date(periodEnd).toISOString()
+        : null,
+  };
+}
+
+/** Monthly window from remaining credits + plan allocation. */
+export function computeMonthly({ credits, subscription }) {
+  const planId = subscription.planId ?? credits.planId;
+  const limit = planMonthlyCredits(planId);
+  const remaining = credits.remaining;
+  let used = null;
+  let utilization = null;
+  if (limit != null && limit > 0 && remaining != null) {
+    used = Math.round(Math.max(0, limit - remaining) * 100) / 100;
+    utilization = Math.min(100, Math.max(0, (used / limit) * 100));
+  }
+  return {
+    monthly: { utilization, resets_at: subscription.currentPeriodEnd },
+    monthly_quota: {
+      used,
+      limit,
+      remaining: remaining == null ? null : Math.round(Math.max(0, remaining) * 100) / 100,
+      unit: 'credits',
+    },
+    plan_type: subscription.plan_type,
+  };
+}
+
+// --- live fetch -----------------------------------------------------------------
+
+async function fetchJson(url, key) {
+  let res;
+  try {
+    res = await fetch(url, {
+      headers: {
+        Authorization: `Bearer ${key}`,
+        Accept: 'application/json',
+        'User-Agent': 'bullswarm',
+      },
+    });
+  } catch (err) {
+    throw new CommandCodeMeterError(`Network error reaching Command Code billing: ${err.message}`, 'network');
+  }
+  let body = null;
+  try {
+    body = await res.json();
+  } catch {
+    /* leave null */
+  }
+  return { status: res.status, body };
+}
+
+export async function fetchCommandCodeUsage() {
+  const key = loadApiKey();
+  const base = (process.env.COMMANDCODE_API_URL?.trim() || DEFAULT_API_BASE).replace(/\/$/, '');
+
+  const creditsRes = await fetchJson(`${base}${CREDITS_PATH}`, key);
+  if (creditsRes.status === 401 || creditsRes.status === 403) {
+    throw new CommandCodeMeterError(`Command Code credits HTTP ${creditsRes.status}`, 'no_auth');
+  }
+  if (creditsRes.status < 200 || creditsRes.status >= 300) {
+    throw new CommandCodeMeterError(`Command Code credits HTTP ${creditsRes.status}`, 'http');
+  }
+
+  const credits = parseCommandCodeCredits(creditsRes.body);
+  const windows = parseCommandCodeWindows(creditsRes.body);
+
+  let subscription = { planId: null, plan_type: null, currentPeriodEnd: null };
+  try {
+    const subRes = await fetchJson(`${base}${SUBSCRIPTIONS_PATH}`, key);
+    if (subRes.status >= 200 && subRes.status < 300) {
+      subscription = parseCommandCodeSubscription(subRes.body);
+    }
+  } catch {
+    /* best-effort */
+  }
+
+  const monthly = computeMonthly({ credits, subscription });
+  return {
+    captured_at: new Date().toISOString(),
+    pool: 'command-code',
+    five_hour: windows.five_hour,
+    seven_day: windows.seven_day,
+    monthly: monthly.monthly,
+    monthly_quota: monthly.monthly_quota,
+    plan_type: monthly.plan_type,
+  };
+}

package/src/meters/framework.js

@@ -0,0 +1,128 @@
+// bullswarm meters — live subscription usage per pool.
+//
+// Doctrine:
+//   M1. Numbers come from the PROVIDER, never from session logs or
+//       declarations when a reader exists. Declared meters are the last
+//       resort and are labeled as such.
+//   M2. elapsed% derives from the provider's resets_at minus the window
+//       length — never from a locally assumed window start.
+//   M3. Weekly/monthly windows pace routing; 5h windows are burst gates
+//       only (block dispatch near exhaustion, never pace by them).
+//   M4. Readers fail closed: an unreadable response is an error, not a
+//       zero. A stale cached reading is shown with its age.
+//   M5. Auth tokens are read from each CLI's native store; refresh
+//       write-back is best-effort so the CLI keeps working.
+
+export const WINDOW_MS = {
+  '5h': 5 * 3600_000,
+  weekly: 7 * 24 * 3600_000,
+};
+
+/** Compute pace for one window from a provider reading. */
+export function windowPace({ usedPct, resetsAtMs, windowMs, nowMs = Date.now() }) {
+  if (![usedPct, resetsAtMs, windowMs].every(Number.isFinite) || windowMs <= 0) {
+    return null;
+  }
+  const startMs = resetsAtMs - windowMs;
+  const elapsedPct = Math.max(0, Math.min(100, ((nowMs - startMs) / windowMs) * 100));
+  const used = Math.max(0, Math.min(100, usedPct));
+  return {
+    usedPct: Math.round(used * 10) / 10,
+    elapsedPct: Math.round(elapsedPct * 10) / 10,
+    // surplus = elapsed − used; higher = more quota expiring unspent.
+    surplus: Math.round((elapsedPct - used) * 10) / 10,
+    resetsAt: new Date(resetsAtMs).toISOString(),
+  };
+}
+
+/**
+ * Pace a snapshot per doctrine M3:
+ *   - pacing window = weekly ?? monthly ?? none (never 5h)
+ *   - burst gate = 5h utilization >= BURST_BLOCK_PCT blocks dispatch
+ */
+export const BURST_BLOCK_PCT = 90;
+
+export function paceSnapshot(snapshot, nowMs = Date.now()) {
+  if (!snapshot) return { pacing: null, burstGate: false, windows: {} };
+
+  const windows = {};
+  for (const kind of ['five_hour', 'seven_day', 'monthly']) {
+    const w = snapshot[kind];
+    if (!w || w.utilization == null) continue;
+    const resetsAtMs = w.resets_at ? Date.parse(w.resets_at) : NaN;
+    const windowMs =
+      kind === 'five_hour' ? WINDOW_MS['5h']
+      : kind === 'monthly' ? monthlyWindowMs(resetsAtMs)
+      : WINDOW_MS.weekly;
+    windows[kind] = windowPace({
+      usedPct: w.utilization,
+      resetsAtMs,
+      windowMs,
+      nowMs,
+    });
+  }
+
+  const pacing = windows.seven_day ?? windows.monthly ?? null;
+  const fiveHourUsed = snapshot.five_hour?.utilization;
+  const burstGate =
+    Number.isFinite(fiveHourUsed) && fiveHourUsed >= BURST_BLOCK_PCT;
+
+  return { pacing, burstGate, windows };
+}
+
+/** UTC calendar month ending at resetsAt (Copilot/cmd period-end semantics). */
+export function monthlyWindowMs(resetsAtMs) {
+  if (!Number.isFinite(resetsAtMs)) return NaN;
+  const reset = new Date(resetsAtMs);
+  const start = new Date(reset);
+  start.setUTCMonth(start.getUTCMonth() - 1);
+  return Math.max(3600_000, reset.getTime() - start.getTime());
+}
+
+// --- snapshot cache ---------------------------------------------------------
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** How old a cached reading may be before we re-poll (fleetlens cadence). */
+export const FRESH_MS = 5 * 60_000;
+/** Beyond this age the reading is labeled stale in output. */
+export const STALE_MS = 60 * 60_000;
+
+export class MeterCache {
+  constructor(dir) {
+    this.dir = dir;
+    mkdirSync(dir, { recursive: true });
+  }
+
+  #path(pool) {
+    return join(this.dir, `${pool}.json`);
+  }
+
+  get(pool) {
+    const p = this.#path(pool);
+    if (!existsSync(p)) return null;
+    try {
+      return JSON.parse(readFileSync(p, 'utf8'));
+    } catch {
+      return null;
+    }
+  }
+
+  put(pool, snapshot) {
+    writeFileSync(this.#path(pool), `${JSON.stringify(snapshot, null, 2)}\n`);
+  }
+
+  /**
+   * Fresh reading or null. A reading is fresh if its captured_at is within
+   * FRESH_MS of now — otherwise callers should re-poll (and fall back to
+   * showing the stale value with its age on failure).
+   */
+  fresh(pool, nowMs = Date.now()) {
+    const s = this.get(pool);
+    if (!s?.captured_at) return null;
+    const ms = Date.parse(s.captured_at);
+    if (!Number.isFinite(ms)) return null;
+    return nowMs - ms <= FRESH_MS ? s : null;
+  }
+}