agent-runway 0.2.0

package/src/models.mjs

@@ -0,0 +1,303 @@
+// Which models a given install can actually run.
+//
+// The question an agent needs answered before delegating is not "what models
+// exist" but "what slug will this binary accept". Those differ: on the machine
+// this was built against, the Codex CLI on PATH accepts four models while the
+// build inside the VS Code extension accepts five, and the extra one -
+// gpt-6-astra - is the model the user's config.toml selects. Spawning the CLI
+// with it fails.
+//
+// So every answer carries the install it came from and how it was obtained:
+//
+//   declared  the binary was asked and answered
+//   inferred  strings were read out of the binary, which is a strong signal
+//             and not a contract
+//
+// A caller that gets "inferred" should be ready for a spawn to fail anyway.
+
+import fs from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+
+import * as cache from "./cache.mjs";
+import { fingerprint } from "./installs.mjs";
+
+const IS_WINDOWS = process.platform === "win32";
+
+/** What to actually execute: the launcher when there is one, else the program. */
+const invocable = (install) => install.launcher ?? install.path;
+
+// ------------------------------------------------------------------- codex
+
+/**
+ * Codex documents its own protocol (`codex app-server generate-json-schema`)
+ * and answers `model/list` over stdio. The most honest source of the three.
+ */
+function codexModels(binary, timeoutMs = 45000) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(binary, ["app-server"], { windowsHide: true });
+    } catch (error) {
+      return resolve({ error: String(error?.message ?? error) });
+    }
+
+    let buffer = "";
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      try { child.kill(); } catch { /* already gone */ }
+      resolve(value);
+    };
+    const send = (message) => {
+      try { child.stdin.write(JSON.stringify(message) + "\n"); } catch { /* closed */ }
+    };
+
+    child.on("error", (error) => finish({ error: String(error?.message ?? error) }));
+    setTimeout(() => finish({ error: `no answer within ${timeoutMs / 1000}s` }), timeoutMs).unref?.();
+
+    child.stdout.on("data", (chunk) => {
+      buffer += chunk.toString();
+      let index;
+      while ((index = buffer.indexOf("\n")) >= 0) {
+        const line = buffer.slice(0, index).trim();
+        buffer = buffer.slice(index + 1);
+        if (!line) continue;
+
+        let message;
+        try { message = JSON.parse(line); } catch { continue; }
+
+        if (message.id === 1) {
+          // The handshake needs the notification before anything else is served.
+          send({ jsonrpc: "2.0", method: "initialized", params: {} });
+          send({ id: 2, method: "model/list", params: { includeHidden: false } });
+        }
+        if (message.id === 2) {
+          if (message.error) return finish({ error: JSON.stringify(message.error).slice(0, 200) });
+          // The payload is under `data`; reading `models` returned zero from a
+          // response that carried five.
+          const items = message.result?.data ?? [];
+          finish({
+            models: items.map((m) => ({
+              id: m.id ?? m.model,
+              displayName: m.displayName ?? null,
+              description: m.description ?? null,
+              hidden: Boolean(m.hidden),
+              reasoningEfforts: (m.supportedReasoningEfforts ?? [])
+                .map((e) => e.reasoningEffort ?? e.effort)
+                .filter(Boolean),
+            })).filter((m) => m.id),
+          });
+        }
+      }
+    });
+
+    send({
+      id: 1,
+      method: "initialize",
+      params: { clientInfo: { name: "agent-runway", version: "0.1.0", title: "agent-runway" } },
+    });
+  });
+}
+
+// ------------------------------------------------------------------ copilot
+
+/**
+ * The Copilot CLI has no list command, but its shell completion enumerates the
+ * values `--model` accepts, which is the same thing said differently.
+ */
+function copilotModels(binary, timeoutMs = 30000) {
+  const result = IS_WINDOWS
+    ? spawnSync(`"${binary}" completion bash`, { encoding: "utf-8", windowsHide: true, timeout: timeoutMs, shell: true })
+    : spawnSync(binary, ["completion", "bash"], { encoding: "utf-8", windowsHide: true, timeout: timeoutMs });
+
+  if (result.error) return { error: String(result.error.message) };
+  if (result.status !== 0) return { error: `completion exited ${result.status}` };
+
+  const slugs = new Set(
+    (result.stdout ?? "").match(/gpt-[0-9][0-9a-z.-]*|claude-[a-z0-9.-]+|gemini-[a-z0-9.-]+|grok-[a-z0-9.-]+/gi) ?? []
+  );
+  return { models: [...slugs].sort().map((id) => ({ id, displayName: null, hidden: false, reasoningEfforts: [] })) };
+}
+
+// ------------------------------------------------------------------- claude
+
+// Noise the scan below picks up: documentation filenames and alias spellings
+// that are not slugs anyone can pass to --model.
+const CLAUDE_NOISE = /\.(md|txt|json)$|^\S+\.\d+$/;
+
+/**
+ * Claude Code exposes no list, so this reads identifiers out of the binary.
+ * Strong evidence, not a contract: an absent string very likely means the build
+ * does not know that model, but the CLI may still forward an arbitrary slug.
+ */
+async function scanBinary(binary, pattern) {
+  const found = new Set();
+  let tail = "";
+  try {
+    for await (const chunk of fs.createReadStream(binary, { highWaterMark: 8 << 20 })) {
+      const text = tail + chunk.toString("latin1");
+      for (const match of text.matchAll(pattern)) found.add(match[0]);
+      tail = text.slice(-120);
+    }
+  } catch (error) {
+    return { error: String(error?.message ?? error) };
+  }
+
+  return {
+    models: [...found]
+      .filter((id) => !CLAUDE_NOISE.test(id))
+      .sort()
+      .map((id) => ({ id, displayName: null, hidden: false, reasoningEfforts: [] })),
+  };
+}
+
+const claudeModels = (binary) =>
+  scanBinary(binary, /claude-(?:opus|sonnet|haiku|fable)-[0-9][0-9a-z.-]{0,18}/g);
+
+// --------------------------------------------------------------------- api
+
+/** Same treatment as Claude: no list command, so read the bundle. */
+const geminiModels = (binary) =>
+  scanBinary(binary, /gemini-[0-9][0-9a-z.-]{0,18}/g);
+
+const READERS = {
+  codex: { authority: "declared", read: (install) => codexModels(install.path) },
+  copilot: { authority: "declared", read: (install) => copilotModels(invocable(install)) },
+  claude: { authority: "inferred", read: (install) => claudeModels(install.path) },
+  gemini: { authority: "inferred", read: (install) => geminiModels(install.path) },
+};
+
+/** Agents that can be spawned with a model argument. An IDE is not one. */
+export const SPAWNABLE = Object.keys(READERS);
+
+/**
+ * @returns {Promise<{agent, kind, version, path, authority, models, error, cached}>}
+ */
+export async function modelsFor(install, { useCache = true } = {}) {
+  const reader = READERS[install.agent];
+  const base = {
+    agent: install.agent,
+    kind: install.kind,
+    version: install.version,
+    path: install.path,
+    authority: reader?.authority ?? null,
+  };
+
+  if (!reader) return { ...base, models: [], error: "no model source for this agent" };
+
+  // Keyed on the binary, not on a duration: the answer changes when the file
+  // does, whether that is a CLI upgrade or a new extension build. Scanning a
+  // 337MB binary is seconds of work that never needs repeating otherwise.
+  const fp = install.fingerprint ?? fingerprint(install.path);
+  const key = fp ? `models-${install.agent}-${fp}` : null;
+
+  if (useCache && key) {
+    const hit = cache.read(key, Infinity, Infinity);
+    if (hit) return { ...base, ...hit.value, cached: true };
+  }
+
+  const outcome = await reader.read(install);
+  const value = { models: outcome.models ?? [], error: outcome.error ?? null };
+  // Errors are transient - an IDE mid-update, a locked file - so only a real
+  // answer is worth remembering.
+  if (key && !value.error && value.models.length) cache.write(key, value);
+
+  return { ...base, ...value, cached: false };
+}
+
+/** Read several installs at once; one failing never costs the others. */
+export async function modelsForAll(installs, options) {
+  return Promise.all(
+    installs
+      .filter((i) => READERS[i.agent])
+      .map((i) => modelsFor(i, options).catch((error) => ({
+        agent: i.agent, kind: i.kind, version: i.version, path: i.path,
+        models: [], error: String(error?.message ?? error),
+      })))
+  );
+}
+
+/**
+ * Everything needed to invoke one agent correctly, in a single answer.
+ *
+ * Shaped for the caller that already knows how to build a command line and only
+ * lacks the two facts that make it work: which binary, and which slug that
+ * binary accepts. brainclaw, for instance, carries invoke templates and a
+ * model_flag for thirteen agents but resolves the binary with a bare `where`
+ * and never checks the slug against it.
+ *
+ * `contract` is here so that consumers can depend on the shape and be told when
+ * it changes, rather than discovering it through a crash.
+ */
+export async function resolveAgent(agent, { installs, model = null, capacity = null } = {}) {
+  const mine = installs.filter((i) => i.agent === agent);
+  const catalogues = await modelsForAll(mine);
+  const usable = catalogues.filter((c) => !c.error && c.models.length);
+
+  // PATH first, because invoking the agent by name is what a spawn does. Then
+  // the highest version, as the most complete catalogue.
+  const preferred =
+    usable.find((c) => c.kind === "path") ??
+    [...usable].sort((a, b) => String(b.version ?? "").localeCompare(String(a.version ?? "")))[0] ??
+    null;
+
+  const answer = {
+    contract: 1,
+    agent,
+    resolved: Boolean(preferred),
+    binary: preferred?.path ?? null,
+    version: preferred?.version ?? null,
+    authority: preferred?.authority ?? null,
+    models: preferred?.models.map((m) => m.id) ?? [],
+    alternatives: catalogues
+      .filter((c) => c !== preferred)
+      .map((c) => ({ kind: c.kind, version: c.version, path: c.path, models: c.models.map((m) => m.id), error: c.error })),
+    capacity,
+  };
+
+  if (model) {
+    const valid = answer.models.includes(model);
+    answer.model = {
+      requested: model,
+      valid,
+      // The useful half of a rejection: the same slug often works elsewhere.
+      availableIn: valid ? [] : whoCanRun(model, catalogues).map((c) => ({ kind: c.kind, version: c.version, path: c.path })),
+      // Never invent a substitute silently; offer one and let the caller decide.
+      suggestion: valid ? null : answer.models[0] ?? null,
+    };
+  }
+  return answer;
+}
+
+/** Which of these installs will accept a given slug. */
+export function whoCanRun(slug, catalogues) {
+  return catalogues.filter((c) => c.models.some((m) => m.id === slug));
+}
+
+/**
+ * Installs that know about a model their sibling does not.
+ *
+ * This is the failure that motivated the module: a model offered by the build
+ * behind an editor, absent from the one a delegation would spawn.
+ */
+export function modelSkew(catalogues) {
+  const byAgent = new Map();
+  for (const c of catalogues) {
+    if (!byAgent.has(c.agent)) byAgent.set(c.agent, []);
+    byAgent.get(c.agent).push(c);
+  }
+
+  const skews = [];
+  for (const [agent, list] of byAgent) {
+    const usable = list.filter((c) => !c.error && c.models.length);
+    if (usable.length < 2) continue;
+
+    const union = new Set(usable.flatMap((c) => c.models.map((m) => m.id)));
+    for (const c of usable) {
+      const missing = [...union].filter((id) => !c.models.some((m) => m.id === id));
+      if (missing.length) skews.push({ agent, install: c, missing });
+    }
+  }
+  return skews;
+}

package/src/providers/antigravity.mjs

@@ -0,0 +1,132 @@
+// Google Antigravity, through the IDE's local language server.
+//
+// The odd one out, and the reason an adapter must be "produce windows" rather
+// than "call a URL": there is no cloud endpoint. The IDE runs
+// language_server.exe, which serves a Connect RPC on loopback. Both the port
+// and the CSRF token change on every launch, so each read rediscovers them, and
+// nothing works at all while the IDE is closed — which is reported as unknown
+// rather than as empty.
+//
+// The header name is x-codeium-csrf-token; the product descends from Codeium.
+
+import { spawnSync } from "node:child_process";
+
+import { fromRemainingFraction, makeWindow, ok, unavailable } from "./shared.mjs";
+
+export const id = "antigravity";
+export const label = "Antigravity";
+
+const IS_WINDOWS = process.platform === "win32";
+const METHOD = "/exa.language_server_pb.LanguageServerService/GetUserStatus";
+const PROC = "language_server";
+
+const run = (cmd, args, timeout) =>
+  spawnSync(cmd, args, { encoding: "utf-8", timeout, windowsHide: true });
+
+/** The CSRF token is an argument of the running server; read it from the process table. */
+function findCsrfToken(timeoutMs) {
+  const r = IS_WINDOWS
+    ? run("powershell", ["-NoProfile", "-NonInteractive", "-Command",
+        `(Get-CimInstance Win32_Process -Filter "Name='${PROC}.exe'").CommandLine`], timeoutMs)
+    : run("ps", ["-eo", "args="], timeoutMs);
+
+  const line = (r.stdout ?? "").split(/\r?\n/).find((l) => l.includes("--csrf_token")) ?? "";
+  return line.match(/--csrf_token[= ]+(\S+)/)?.[1] ?? null;
+}
+
+/** The server listens on two loopback ports; only one speaks plain HTTP. */
+function findPorts(timeoutMs) {
+  if (IS_WINDOWS) {
+    const r = run("powershell", ["-NoProfile", "-NonInteractive", "-Command",
+      `Get-Process ${PROC} -ErrorAction SilentlyContinue | ForEach-Object { ` +
+      `Get-NetTCPConnection -State Listen -OwningProcess $_.Id -ErrorAction SilentlyContinue } | ` +
+      `Select-Object -ExpandProperty LocalPort`], timeoutMs);
+    return [...new Set((r.stdout ?? "").split(/\r?\n/).map((l) => Number(l.trim())).filter(Boolean))];
+  }
+  // POSIX: lsof is the portable-enough option. Untested on macOS and Linux.
+  const r = run("lsof", ["-nP", "-iTCP", "-sTCP:LISTEN", "-a", "-c", PROC], timeoutMs);
+  return [...new Set(
+    [...(r.stdout ?? "").matchAll(/:(\d+)\s+\(LISTEN\)/g)].map((m) => Number(m[1]))
+  )];
+}
+
+export async function read({ fetchImpl = globalThis.fetch, timeoutMs = 8000 } = {}) {
+  const csrf = findCsrfToken(timeoutMs);
+  const ports = findPorts(timeoutMs);
+
+  if (!csrf || !ports.length) {
+    // Not "no quota left" — genuinely not knowable right now.
+    return unavailable(id, "unreachable", "the Antigravity IDE is not running, so its quota cannot be read");
+  }
+
+  let body = null;
+  for (const port of ports) {
+    try {
+      const response = await fetchImpl(`http://127.0.0.1:${port}${METHOD}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Connect-Protocol-Version": "1",
+          "x-codeium-csrf-token": csrf,
+        },
+        body: "{}",
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      if (!response.ok) continue; // the sibling port serves HTTPS and 400s here
+      body = await response.json();
+      break;
+    } catch {
+      /* try the next port */
+    }
+  }
+
+  if (!body) return unavailable(id, "unreachable", "the local language server did not answer");
+
+  const status = body.userStatus ?? {};
+  const plan = status.planStatus ?? {};
+  const info = plan.planInfo ?? {};
+  const windows = [];
+
+  // Per-model weekly quotas. Every model config repeats the same reset time, so
+  // collapse them rather than emitting one window per model.
+  const quotas = (status.cascadeModelConfigData?.clientModelConfigs ?? [])
+    .map((c) => c.quotaInfo)
+    .filter((q) => q && Number.isFinite(q.remainingFraction));
+
+  if (quotas.length) {
+    const worst = quotas.reduce((a, b) => (a.remainingFraction <= b.remainingFraction ? a : b));
+    windows.push(
+      makeWindow({
+        kind: "model_quota",
+        label: "Model quota",
+        percentUsed: fromRemainingFraction(worst.remainingFraction),
+        resetsAt: worst.resetTime ?? null,
+      })
+    );
+  }
+
+  // Credits are a separate currency from the window above.
+  const credits = [
+    ["prompt_credits", "Prompt credits", plan.availablePromptCredits, info.monthlyPromptCredits],
+    ["flow_credits", "Flow credits", plan.availableFlowCredits, info.monthlyFlowCredits],
+  ];
+  for (const [kind, label_, available, monthly] of credits) {
+    if (!Number.isFinite(available) || !Number.isFinite(monthly) || monthly <= 0) continue;
+    windows.push(
+      makeWindow({
+        kind,
+        label: label_,
+        percentUsed: Math.max(0, Math.min(100, Math.round(100 - (available / monthly) * 100))),
+        remaining: available,
+        entitlement: monthly,
+        unit: "credits",
+      })
+    );
+  }
+
+  return ok(id, {
+    plan: info.planName ?? null,
+    windows,
+    detail: info.canBuyMoreCredits ? "more credits can be purchased" : null,
+  });
+}

package/src/providers/claude.mjs

@@ -0,0 +1,51 @@
+// Claude Code / claude.ai subscription.
+//
+// Verified shape: a `limits` array of {kind, percent, severity, resets_at,
+// scope, is_active}. Window durations are NOT reported, so they are inferred
+// from the kind and marked as derived.
+
+import { fetchUsage, UsageError } from "../core.mjs";
+import { fromUsedPercent, makeWindow, ok, unavailable } from "./shared.mjs";
+
+export const id = "claude";
+export const label = "Claude";
+
+// Not reported by the API. The field names (five_hour, seven_day) and the
+// observed reset cadence support these, but they remain an inference.
+const DERIVED_SECONDS = { session: 5 * 3600, weekly_all: 7 * 86400, weekly_scoped: 7 * 86400 };
+const LABELS = { session: "Session (5h)", weekly_all: "Weekly - all models", weekly_scoped: "Weekly" };
+
+export async function read({ env = process.env, fetchImpl = globalThis.fetch } = {}) {
+  let usage;
+  try {
+    usage = await fetchUsage({ env, fetchImpl });
+  } catch (error) {
+    if (error instanceof UsageError) {
+      const status =
+        error.code === "NO_TOKEN" ? "no_credentials"
+        : error.code === "AUTH" ? "no_credentials"
+        : "unreachable";
+      return unavailable(id, status, error.message);
+    }
+    return unavailable(id, "error", String(error?.message ?? error));
+  }
+
+  const windows = usage.windows.map((w) => {
+    const seconds = DERIVED_SECONDS[w.id] ?? null;
+    return makeWindow({
+      kind: w.id,
+      label: LABELS[w.id] ?? w.label,
+      percentUsed: fromUsedPercent(w.percent),
+      resetsAt: w.resetsAt,
+      windowSeconds: seconds,
+      windowSource: seconds ? "derived" : null,
+      severity: w.severity,
+      model: w.model,
+    });
+  });
+
+  // Extra credits mean a window at 100% is not necessarily a wall.
+  const detail = usage.extraUsage?.enabled ? "extra usage credits enabled" : null;
+
+  return ok(id, { windows, detail });
+}

package/src/providers/codex.mjs

@@ -0,0 +1,119 @@
+// OpenAI Codex, via the ChatGPT backend.
+//
+// The best-instrumented of the four: it reports the window duration
+// (limit_window_seconds) rather than making us infer it, and exposes `allowed`
+// and `limit_reached` directly, which is a real gate signal instead of a
+// percentage we have to interpret.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { fromUsedPercent, makeWindow, ok, unavailable } from "./shared.mjs";
+
+export const id = "codex";
+export const label = "OpenAI Codex";
+
+const ENDPOINT = "https://chatgpt.com/backend-api/codex/usage";
+
+const WINDOW_LABELS = {
+  primary_window: "Session",
+  secondary_window: "Weekly",
+};
+
+function readAuth(home) {
+  try {
+    const auth = JSON.parse(fs.readFileSync(path.join(home, ".codex", "auth.json"), "utf8"));
+    const token = auth?.tokens?.access_token;
+    const account = auth?.tokens?.account_id;
+    return token && account ? { token, account } : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function read({
+  home = os.homedir(),
+  fetchImpl = globalThis.fetch,
+  timeoutMs = 10000,
+} = {}) {
+  const auth = readAuth(home);
+  if (!auth) {
+    return unavailable(id, "no_credentials", "~/.codex/auth.json missing or incomplete - run `codex login`");
+  }
+
+  let response;
+  try {
+    response = await fetchImpl(ENDPOINT, {
+      headers: {
+        Authorization: `Bearer ${auth.token}`,
+        "chatgpt-account-id": auth.account,
+        Accept: "application/json",
+        // Without a User-Agent, Cloudflare answers with an HTML challenge page
+        // instead of JSON. Found the hard way.
+        "User-Agent": "agent-runway",
+      },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (error) {
+    return unavailable(id, "unreachable", `chatgpt.com unreachable: ${error?.message ?? error}`);
+  }
+
+  const text = await response.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    return unavailable(id, "unreachable", `expected JSON, got ${response.status} ${text.slice(0, 60)}`);
+  }
+
+  if (response.status === 401 || response.status === 403) {
+    return unavailable(id, "no_credentials", "token rejected - run `codex login`");
+  }
+  if (!response.ok) {
+    return unavailable(id, "error", `HTTP ${response.status}`);
+  }
+
+  const rate = body.rate_limit ?? {};
+  const windows = [];
+
+  for (const key of ["primary_window", "secondary_window"]) {
+    const w = rate[key];
+    if (!w) continue;
+    windows.push(
+      makeWindow({
+        kind: key === "primary_window" ? "session" : "weekly_all",
+        label: WINDOW_LABELS[key],
+        percentUsed: fromUsedPercent(w.used_percent),
+        resetsAt: Number.isFinite(w.reset_at) ? new Date(w.reset_at * 1000).toISOString() : null,
+        windowSeconds: w.limit_window_seconds ?? null,
+        // Reported by the provider, not inferred from a field name.
+        windowSource: w.limit_window_seconds ? "reported" : null,
+      })
+    );
+  }
+
+  // Any further caps the account carries. Kept rather than dropped: the field
+  // exists precisely because the set is not fixed.
+  for (const [key, w] of Object.entries(rate.additional_rate_limits ?? {})) {
+    if (!w || !Number.isFinite(w.used_percent)) continue;
+    windows.push(
+      makeWindow({
+        kind: key,
+        label: key.replace(/_/g, " "),
+        percentUsed: fromUsedPercent(w.used_percent),
+        resetsAt: Number.isFinite(w.reset_at) ? new Date(w.reset_at * 1000).toISOString() : null,
+        windowSeconds: w.limit_window_seconds ?? null,
+        windowSource: w.limit_window_seconds ? "reported" : null,
+      })
+    );
+  }
+
+  return ok(id, {
+    plan: body.plan_type ?? null,
+    // The only provider that answers "can I proceed" without us inferring it.
+    allowed: typeof rate.allowed === "boolean" ? rate.allowed : null,
+    windows,
+    detail: rate.limit_reached ? "limit reached" : null,
+  });
+}

package/src/providers/copilot.mjs

@@ -0,0 +1,87 @@
+// GitHub Copilot, through the GitHub CLI's stored credentials.
+//
+// Different model from the other three: a monthly allowance of requests rather
+// than rolling time windows, reported as a percentage REMAINING plus raw
+// counts. The trap is `has_quota: false` — on the free tier
+// premium_interactions reads 0 of 0, which a naive percentage call "exhausted"
+// when it actually means "not included in this plan".
+
+import { spawnSync } from "node:child_process";
+
+import { fromCounts, fromRemainingPercent, makeWindow, ok, unavailable } from "./shared.mjs";
+
+export const id = "copilot";
+export const label = "GitHub Copilot";
+
+const IS_WINDOWS = process.platform === "win32";
+
+const LABELS = {
+  chat: "Chat requests",
+  completions: "Completions",
+  premium_interactions: "Premium requests",
+};
+
+/** `gh` holds the token; shelling out avoids ever touching it ourselves. */
+function ghApi(endpoint, timeoutMs) {
+  const base = { encoding: "utf-8", timeout: timeoutMs, windowsHide: true };
+  const r = IS_WINDOWS
+    ? spawnSync(`gh api ${endpoint}`, { ...base, shell: true })
+    : spawnSync("gh", ["api", endpoint], base);
+
+  if (r.error) return { ok: false, reason: r.error.code === "ENOENT" ? "not_installed" : "error" };
+  if (r.status !== 0) {
+    const err = (r.stderr ?? "").toLowerCase();
+    if (err.includes("auth") || err.includes("401")) return { ok: false, reason: "no_credentials" };
+    return { ok: false, reason: "unreachable", detail: (r.stderr ?? "").trim().slice(0, 120) };
+  }
+  try {
+    return { ok: true, body: JSON.parse(r.stdout) };
+  } catch {
+    return { ok: false, reason: "error", detail: "gh returned non-JSON" };
+  }
+}
+
+export async function read({ timeoutMs = 15000, gh = ghApi } = {}) {
+  const result = gh("copilot_internal/user", timeoutMs);
+  if (!result.ok) {
+    const hint = {
+      not_installed: "the GitHub CLI is not installed",
+      no_credentials: "not signed in - run `gh auth login`",
+    }[result.reason];
+    return unavailable(id, result.reason, hint ?? result.detail ?? "gh api failed");
+  }
+
+  const body = result.body ?? {};
+  const snapshots = body.quota_snapshots ?? {};
+  // Monthly, and reported once for the account rather than per quota.
+  const resetsAt = body.quota_reset_date ? `${body.quota_reset_date}T00:00:00Z` : null;
+
+  const windows = Object.entries(snapshots).map(([key, q]) => {
+    const entitled = Boolean(q.has_quota) && !(q.entitlement === 0);
+    const percentUsed = q.unlimited
+      ? 0
+      : Number.isFinite(q.percent_remaining)
+        ? fromRemainingPercent(q.percent_remaining)
+        : fromCounts(q.quota_remaining, q.entitlement);
+
+    return makeWindow({
+      kind: `monthly_${key}`,
+      label: LABELS[key] ?? key.replace(/_/g, " "),
+      percentUsed: entitled ? percentUsed : null,
+      remaining: Number.isFinite(q.quota_remaining) ? q.quota_remaining : null,
+      entitlement: Number.isFinite(q.entitlement) ? q.entitlement : null,
+      entitled,
+      resetsAt,
+      windowSeconds: null, // a calendar month, not a fixed number of seconds
+      unit: "requests",
+    });
+  });
+
+  const overage = Object.values(snapshots).some((q) => q.overage_permitted);
+
+  return ok(id, {
+    plan: body.copilot_plan ?? null,
+    windows,
+    detail: overage ? "overage permitted" : null,
+  });
+}