bullswarm 0.1.4

package/src/meters/grok.js

@@ -0,0 +1,200 @@
+// bullswarm grok meter — Grok Build weekly credit pool via the billing
+// endpoint the Grok CLI itself uses. Weekly-only: five_hour stays null.
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const CREDITS_URL = 'https://cli-chat-proxy.grok.com/v1/billing?format=credits';
+const REFRESH_URL = 'https://auth.x.ai/oauth2/token';
+const TOKEN_AUTH = 'xai-grok-cli';
+const DEFAULT_CLIENT_ID = 'b1a00492-073a-47ea-816f-4c329264a828';
+const WEEKLY_PERIOD = 'USAGE_PERIOD_TYPE_WEEKLY';
+const REFRESH_BUFFER_MS = 5 * 60_000;
+
+export class GrokMeterError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code; // no_auth | http | parse | network | not_weekly
+  }
+}
+
+function authPath() {
+  const home = process.env.GROK_HOME?.trim() || path.join(os.homedir(), '.grok');
+  return path.join(home, 'auth.json');
+}
+
+function loadAuthEntry() {
+  const p = authPath();
+  if (!existsSync(p)) {
+    throw new GrokMeterError('Grok not logged in. Run `grok login`.', 'no_auth');
+  }
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(p, 'utf8'));
+  } catch {
+    throw new GrokMeterError('Grok auth.json unreadable. Re-run `grok login`.', 'no_auth');
+  }
+  for (const [entryKey, entry] of Object.entries(raw)) {
+    const token = typeof entry?.key === 'string' ? entry.key.trim() : '';
+    if (token) return { token, entry, entryKey };
+  }
+  throw new GrokMeterError('Grok auth has no access token.', 'no_auth');
+}
+
+function needsRefresh(entry) {
+  if (!entry.expires_at) return false;
+  const ms = Date.parse(entry.expires_at);
+  return Number.isFinite(ms) && Date.now() >= ms - REFRESH_BUFFER_MS;
+}
+
+async function refreshAccessToken(entry) {
+  const refresh = entry.refresh_token?.trim();
+  if (!refresh) return null;
+  const clientId = entry.oidc_client_id?.trim() || DEFAULT_CLIENT_ID;
+  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: clientId,
+        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;
+    try {
+      const p = authPath();
+      const raw = JSON.parse(readFileSync(p, 'utf8'));
+      for (const key of Object.keys(raw)) {
+        if (raw[key]?.key === entry.key || raw[key]?.refresh_token === refresh) {
+          raw[key] = {
+            ...raw[key],
+            key: j.access_token,
+            refresh_token: j.refresh_token ?? raw[key].refresh_token,
+            expires_at:
+              typeof j.expires_in === 'number'
+                ? new Date(Date.now() + j.expires_in * 1000).toISOString()
+                : raw[key].expires_at,
+          };
+          break;
+        }
+      }
+      writeFileSync(p, JSON.stringify(raw, null, 2));
+    } catch {
+      /* in-memory token still works */
+    }
+    return j.access_token;
+  } catch {
+    return null;
+  }
+}
+
+// --- pure decoder ---------------------------------------------------------------
+
+export function parseGrokCreditsConfig(body) {
+  if (!body || typeof body !== 'object') {
+    throw new GrokMeterError('Grok billing response missing body', 'parse');
+  }
+  const config = body.config;
+  if (!config || typeof config !== 'object') {
+    throw new GrokMeterError('Grok billing response missing config', 'parse');
+  }
+  const period = config.currentPeriod;
+  if (!period || typeof period !== 'object') {
+    throw new GrokMeterError('Grok billing response missing currentPeriod', 'parse');
+  }
+  const periodType = typeof period.type === 'string' ? period.type.trim() : '';
+  if (!periodType) {
+    throw new GrokMeterError('Grok billing period type missing', 'parse');
+  }
+
+  let utilization = 0;
+  if (config.creditUsagePercent !== undefined && config.creditUsagePercent !== null) {
+    const n = Number(config.creditUsagePercent);
+    if (!Number.isFinite(n)) {
+      throw new GrokMeterError('creditUsagePercent is not a number', 'parse');
+    }
+    utilization = Math.min(100, Math.max(0, n));
+  }
+
+  const end =
+    typeof period.end === 'string' && period.end ? new Date(period.end).toISOString() : null;
+
+  return {
+    utilization,
+    resets_at: end && !Number.isNaN(Date.parse(end)) ? end : null,
+    period_type: periodType,
+  };
+}
+
+async function fetchJson(url, token) {
+  let res;
+  try {
+    res = await fetch(url, {
+      headers: {
+        Authorization: `Bearer ${token.trim()}`,
+        'X-XAI-Token-Auth': TOKEN_AUTH,
+        Accept: 'application/json',
+        'User-Agent': 'bullswarm',
+      },
+    });
+  } catch (err) {
+    throw new GrokMeterError(`Network error reaching Grok billing: ${err.message}`, 'network');
+  }
+  let body = null;
+  try {
+    body = await res.json();
+  } catch {
+    /* leave null */
+  }
+  return { status: res.status, body };
+}
+
+export async function fetchGrokUsage() {
+  const loaded = loadAuthEntry();
+  let token = loaded.token;
+  if (needsRefresh(loaded.entry)) {
+    const refreshed = await refreshAccessToken(loaded.entry);
+    if (refreshed) token = refreshed;
+  }
+
+  let { status, body } = await fetchJson(CREDITS_URL, token);
+  if (status === 401 || status === 403) {
+    const refreshed = await refreshAccessToken(loaded.entry);
+    if (refreshed) {
+      token = refreshed;
+      ({ status, body } = await fetchJson(CREDITS_URL, token));
+    }
+  }
+  if (status < 200 || status >= 300) {
+    throw new GrokMeterError(
+      `Grok billing returned HTTP ${status}`,
+      status === 401 || status === 403 ? 'no_auth' : 'http',
+    );
+  }
+
+  const credits = parseGrokCreditsConfig(body);
+  if (credits.period_type !== WEEKLY_PERIOD) {
+    throw new GrokMeterError(
+      `Grok period is ${credits.period_type}, not weekly — refusing to mislabel`,
+      'not_weekly',
+    );
+  }
+
+  return {
+    captured_at: new Date().toISOString(),
+    pool: 'grok',
+    five_hour: { utilization: null, resets_at: null },
+    seven_day: { utilization: credits.utilization, resets_at: credits.resets_at },
+    monthly: null,
+    plan_type: null,
+  };
+}

package/src/meters/registry.js

@@ -0,0 +1,85 @@
+// bullswarm meter registry — pool name → live reader, cache-first.
+
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { MeterCache, paceSnapshot, FRESH_MS, STALE_MS } from './framework.js';
+import { fetchCodexUsage, CodexMeterError } from './codex.js';
+import { fetchGrokUsage, GrokMeterError } from './grok.js';
+import { fetchCommandCodeUsage, CommandCodeMeterError } from './command-code.js';
+import { fetchClaudeUsage, ClaudeMeterError } from './claude.js';
+
+export const METERS_DIR = () =>
+  process.env.BULLSWARM_HOME?.trim() || join(homedir(), '.bullswarm');
+
+const READERS = {
+  codex: fetchCodexUsage,
+  grok: fetchGrokUsage,
+  'command-code': fetchCommandCodeUsage,
+  'claude-code': fetchClaudeUsage,
+  claude: fetchClaudeUsage,
+};
+
+export function readerFor(pool) {
+  return READERS[pool] ?? null;
+}
+
+/**
+ * Get a usable meter reading for a pool:
+ *   1. fresh cache hit (<= FRESH_MS old) → use it
+ *   2. live poll → cache + use
+ *   3. poll failed → stale cache labeled stale, else the error
+ * Never fabricates numbers.
+ */
+export async function getMeterReading(pool, opts = {}) {
+  const { force = false, nowMs = Date.now() } = opts;
+  const cache = new MeterCache(join(METERS_DIR(), 'meters'));
+  const cached = cache.get(pool);
+
+  if (!force && cached && nowMs - Date.parse(cached.captured_at) <= FRESH_MS) {
+    return { snapshot: cached, source: 'cache', ...paceSnapshot(cached, nowMs) };
+  }
+
+  const reader = readerFor(pool);
+  if (!reader) {
+    // No programmatic reader for this pool — declared meters (state.json)
+    // are the fallback and are handled by config.js. Signal that here.
+    return { snapshot: null, source: 'none', pacing: null, burstGate: false, windows: {} };
+  }
+
+  try {
+    const snapshot = await reader();
+    cache.put(pool, snapshot);
+    return { snapshot, source: 'live', ...paceSnapshot(snapshot, nowMs) };
+  } catch (err) {
+    if (cached) {
+      const ageMs = nowMs - Date.parse(cached.captured_at);
+      if (ageMs <= STALE_MS) {
+        return {
+          snapshot: cached,
+          source: 'stale',
+          error: err,
+          ageMs,
+          ...paceSnapshot(cached, nowMs),
+        };
+      }
+    }
+    throw err;
+  }
+}
+
+/** Best-effort reading for all pools that have readers; never throws. */
+export async function getAllMeterReadings(poolNames, opts = {}) {
+  const out = {};
+  await Promise.all(
+    poolNames.map(async (p) => {
+      try {
+        out[p] = await getMeterReading(p, opts);
+      } catch (err) {
+        out[p] = { snapshot: null, source: 'error', error: err, pacing: null, burstGate: false, windows: {} };
+      }
+    }),
+  );
+  return out;
+}
+
+export { CodexMeterError, GrokMeterError, CommandCodeMeterError, ClaudeMeterError, FRESH_MS, STALE_MS };

package/src/setup.js

@@ -0,0 +1,272 @@
+// bullswarm setup wizard — the front door.
+//
+// Doctrine:
+//   U1. Discovery = binary on PATH + config dir present + (never) credential
+//       entry. Burn rate starts EMPTY and is labeled "learning".
+//   U2. The wizard suggests a routing table as an EDITABLE ARTIFACT, never a
+//       questionnaire.
+//   U3. CLAUDE.md / AGENTS.md integration is a DIFF with explicit approval
+//       before any write, delimited by versioned bullswarm:begin/end
+//       markers, idempotent on re-run.
+//   U4. `bullswarm setup` on a configured machine reports state and repairs
+//       broken connector files.
+
+import { execFileSync } from 'node:child_process';
+import {
+  existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, copyFileSync,
+} from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { stdin as input } from 'node:process';
+import { loadState, saveState } from './lib/state.js';
+
+const REPO_ROOT = fileURLToPath(new URL('..', import.meta.url));
+const MARKER_BEGIN = '<!-- bullswarm:begin v1 -->';
+const MARKER_END = '<!-- bullswarm:end -->';
+
+// --- prompting ------------------------------------------------------------
+// Sequential prompts that work identically on a TTY and with piped answers.
+// (readline/promises question() drops lines when stdin is a pipe: the second
+// question re-arms after buffered data was already consumed. Preload pipes;
+// readline only per-question on a real TTY.)
+class Prompter {
+  #lines = [];
+  #preloaded = false;
+
+  async #preload() {
+    if (this.#preloaded) return;
+    this.#preloaded = true;
+    if (!input.isTTY) {
+      input.setEncoding?.('utf8');
+      let data = '';
+      for await (const chunk of input) data += chunk;
+      this.#lines = data.split('\n').filter((x) => x.length > 0);
+    }
+  }
+
+  async question(prompt) {
+    await this.#preload();
+    if (input.isTTY) {
+      const { createInterface } = await import('node:readline/promises');
+      const rl = createInterface({ input, output: process.stderr });
+      const answer = (await rl.question(prompt)).trim();
+      rl.close();
+      return answer;
+    }
+    return this.#lines.shift() ?? '';
+  }
+}
+
+// --- discovery ---------------------------------------------------------------
+
+function onPath(bin) {
+  try {
+    execFileSync('which', [bin], { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function expandHome(p) {
+  return p.startsWith('~') ? join(process.env.HOME ?? '', p.slice(1)) : p;
+}
+
+export function discoverConnectors() {
+  const dir = join(REPO_ROOT, 'connectors');
+  const found = [];
+  for (const f of readdirSync(dir).sort()) {
+    if (!f.endsWith('.json') || f.startsWith('_')) continue;
+    let conn;
+    try {
+      conn = JSON.parse(readFileSync(join(dir, f), 'utf8'));
+    } catch {
+      found.push({ file: f, broken: true });
+      continue;
+    }
+    const binFound = onPath(conn.bin);
+    const cfgFound = (conn.configDirs ?? []).some((d) => existsSync(expandHome(d)));
+    found.push({
+      file: f,
+      name: conn.name,
+      bin: conn.bin,
+      binFound,
+      cfgFound,
+      discovered: binFound || cfgFound,
+      meter: conn.meter?.type ?? 'none',
+      costRank: conn.costRank,
+      lanes: conn.lanes,
+    });
+  }
+  return found;
+}
+
+// --- routing suggestion --------------------------------------------------------
+
+export function suggestRoutingTable(enabledPools) {
+  const byLane = { analyze: [], build: [], chore: [] };
+  for (const p of enabledPools) {
+    for (const lane of p.lanes ?? ['analyze', 'build', 'chore']) {
+      byLane[lane]?.push(p.name);
+    }
+  }
+  // Suggest: cheapest pool as default per lane; caller as final fallback.
+  const suggestion = {};
+  for (const [lane, names] of Object.entries(byLane)) {
+    suggestion[lane] = { order: names, fallback: 'caller' };
+  }
+  return suggestion;
+}
+
+// --- integration block ------------------------------------------------------------
+
+export function integrationBlock() {
+  return `${MARKER_BEGIN}
+## bullswarm offload policy
+
+When a task fits a bounded lane, prefer offloading it:
+
+    bullswarm run --lane <analyze|build|chore> --add-dir <repo-dir> --task-file <file> --json
+
+Read the verdict JSON: ok:true -> use outFile; keepOnClaude:true -> do it in-session;
+ok:false -> the why field names the failed gate. Delegate output is INPUT you verify,
+never the answer. Final synthesis, architecture decisions, and live-context work stay
+with you. Run \`bullswarm health\` after every offload round.
+${MARKER_END}`;
+}
+
+export function applyIntegrationBlock(filePath, { approved }) {
+  if (!approved) return { changed: false, reason: 'not approved' };
+  let existing = '';
+  try {
+    existing = readFileSync(filePath, 'utf8');
+  } catch {
+    /* new file */
+  }
+  const stripped = existing
+    .replace(new RegExp(`${MARKER_BEGIN}[\\s\\S]*?${MARKER_END}\n?`), '')
+    .trimEnd();
+  const next = stripped
+    ? `${stripped}\n\n${integrationBlock()}\n`
+    : `${integrationBlock()}\n`;
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, next);
+  return { changed: true };
+}
+
+export function integrationBlockPresent(filePath) {
+  try {
+    return readFileSync(filePath, 'utf8').includes(MARKER_BEGIN);
+  } catch {
+    return false;
+  }
+}
+
+// --- repair ---------------------------------------------------------------
+
+export function repairConnectors(bullswarmDir) {
+  const target = join(bullswarmDir, 'connectors');
+  mkdirSync(target, { recursive: true });
+  const repaired = [];
+  for (const f of readdirSync(join(REPO_ROOT, 'connectors'))) {
+    if (!f.endsWith('.json') || f.startsWith('_')) continue;
+    const dst = join(target, f);
+    let broken = false;
+    try {
+      JSON.parse(readFileSync(dst, 'utf8'));
+    } catch {
+      broken = true;
+    }
+    if (!existsSync(dst) || broken) {
+      copyFileSync(join(REPO_ROOT, 'connectors', f), dst);
+      repaired.push(f);
+    }
+  }
+  return repaired;
+}
+
+// --- wizard -------------------------------------------------------------------
+
+export async function runWizard(bullswarmDir, opts = {}) {
+  const state = loadState(bullswarmDir);
+  const discovered = discoverConnectors();
+
+  if (opts.json) {
+    console.log(JSON.stringify({ discovered, state: !!state.pools }, null, 2));
+    return 0;
+  }
+
+  const rl = new Prompter();
+  console.log('bullswarm setup\n');
+
+  // 1. Discovery table
+  console.log('Discovered agent CLIs:');
+  for (const d of discovered) {
+    if (d.broken) {
+      console.log(`  ${d.file.padEnd(22)} BROKEN (will repair)`);
+      continue;
+    }
+    const meter =
+      d.meter === 'none'
+        ? 'quota: unmetered'
+        : `quota: ${d.meter} window (burn rate: learning)`;
+    console.log(
+      `  ${d.name.padEnd(14)} ${d.discovered ? 'found' : 'not found'}  ${meter}`,
+    );
+  }
+  console.log('');
+
+  // 2. Toggle pools
+  const enabled = [];
+  for (const d of discovered.filter((x) => !x.broken && x.discovered)) {
+    const ans = (await rl.question(`enable ${d.name}? [Y/n] `)).trim().toLowerCase();
+    if (ans !== 'n') enabled.push(d.name);
+  }
+
+  if (enabled.length === 0) {
+    console.log('\nNo pools enabled — bullswarm will keep every task in-session.');
+  }
+
+  // 3. Routing suggestion (editable artifact)
+  const chosen = discovered.filter((d) => enabled.includes(d.name));
+  const table = suggestRoutingTable(chosen);
+  console.log('\nSuggested routing table (edit ~/.bullswarm/routing.json to change):');
+  console.log(JSON.stringify(table, null, 2));
+
+  // 4. Write config
+  mkdirSync(join(bullswarmDir, 'connectors'), { recursive: true });
+  const repaired = repairConnectors(bullswarmDir);
+  state.pools ??= {};
+  for (const d of discovered.filter((x) => !x.broken)) {
+    state.pools[d.name] ??= {};
+    state.pools[d.name].enabled = enabled.includes(d.name);
+  }
+  saveState(bullswarmDir, state);
+  writeFileSync(
+    join(bullswarmDir, 'routing.json'),
+    `${JSON.stringify(table, null, 2)}\n`,
+  );
+  console.log(`\nWrote ${bullswarmDir}/state.json and routing.json`);
+  if (repaired.length) console.log(`Repaired connector files: ${repaired.join(', ')}`);
+
+  // 5. Integration blocks — diff + approval
+  for (const [label, path] of [
+    ['CLAUDE.md', join(process.env.HOME ?? '', '.claude', 'CLAUDE.md')],
+    ['AGENTS.md', join(process.cwd(), 'AGENTS.md')],
+  ]) {
+    const present = integrationBlockPresent(path);
+    const preview = present
+      ? 'block already present (idempotent re-run)'
+      : `will append to ${path}:\n\n${integrationBlock()}\n`;
+    console.log(`\n${label}: ${preview}`);
+    const ans = (
+      await rl.question(`write ${label} integration block? [y/N] `)
+    ).trim().toLowerCase();
+    const result = applyIntegrationBlock(path, { approved: ans === 'y' && !present });
+    console.log(result.changed ? `  wrote ${path}` : `  skipped ${label}`);
+  }
+
+  rl.close();
+  console.log('\nSetup complete. Try: bullswarm pools');
+  return 0;
+}