agent-runway 0.2.0

package/src/cli.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+// Command line entry point. Also what the Claude Code skill shells out to.
+
+import { fetchUsage, UsageError, VERSION } from "./core.mjs";
+import { renderModels, renderProviders, renderShort, renderTable } from "./render.mjs";
+
+const HELP = `agent-runway ${VERSION}
+
+Show how much runway is left before you hit a rate limit, and which models
+each installed agent will actually accept.
+
+Usage:
+  agent-runway [options]
+  agent-runway setup [--env] [--force]
+
+Commands:
+  setup        Guided first-time setup: create a token, check it, save it.
+               --env    also export AGENT_RUNWAY_TOKEN from your shell profile
+               --force  replace a token that already works
+
+Options:
+  --all           Every provider found on this machine, not just Claude
+  --models        What each installed agent will accept as a model, and
+                  where two installs of the same agent disagree
+  --gate <N>      Decide: is there room to start work, at threshold N percent?
+                  Prints JSON. Exit 0 proceed, 10 defer, 11 unknown.
+  --short         One line, machine friendly: session=79%  weekly_all=76%
+  --json          Raw API response, unformatted
+  --plain         Skip the header, print only the windows
+  -h, --help      Show this help
+  -v, --version
+
+Providers: claude, codex, copilot, antigravity. Each is read with the
+credentials that provider already keeps, and one failing never stops the rest.
+
+Authentication, first match wins:
+  CLAUDE_CODE_OAUTH_TOKEN     token from \`claude setup-token\` (recommended)
+  AGENT_RUNWAY_TOKEN
+  ANTHROPIC_AUTH_TOKEN
+  ~/.claude/usage-token       file containing the token on a single line
+  ~/.claude/.credentials.json Claude Code's own session token, often stale
+
+  Set AGENT_RUNWAY_NO_LOCAL_CREDENTIALS=1 to never read the last source.
+
+Exit codes:
+  0 success   1 error   2 no token   3 auth rejected   4 endpoint rate limited
+`;
+
+const EXIT = { NO_TOKEN: 2, AUTH: 3, RATE_LIMITED: 4 };
+
+// A gate is a decision, so it answers in exit codes as well as on stdout, and
+// it has three outcomes rather than two: a provider that cannot be read is not
+// the same as one with room, and must never be treated as one.
+const GATE_EXIT = { proceed: 0, defer: 10, unknown: 11 };
+
+/** `--gate 90`, `--gate=90`, or `--gate` for the default. */
+function gateThreshold(argv) {
+  const index = argv.findIndex((a) => a === "--gate" || a.startsWith("--gate="));
+  if (index === -1) return null;
+  const inline = argv[index].split("=")[1];
+  const value = Number(inline ?? argv[index + 1]);
+  return Number.isFinite(value) && value >= 0 && value <= 100 ? value : 90;
+}
+
+async function main(argv) {
+  const has = (...names) => names.some((n) => argv.includes(n));
+
+  // Loaded on demand: setup pulls in child_process and readline, which the
+  // common path (a single GET) has no use for.
+  if (argv[0] === "setup") {
+    const { setup } = await import("./setup.mjs");
+    return setup(argv.slice(1));
+  }
+
+  // Everything needed to invoke one agent, in one answer. Meant for a caller
+  // that already builds command lines and only lacks the binary and a valid
+  // slug — brainclaw resolves the first with a bare `where` and never checks
+  // the second.
+  if (argv[0] === "resolve") {
+    const agent = argv[1];
+    const [{ discoverInstalls }, models] = await Promise.all([
+      import("./installs.mjs"),
+      import("./models.mjs"),
+    ]);
+
+    if (!models.SPAWNABLE.includes(agent)) {
+      process.stderr.write(`agent-runway: resolve needs one of ${models.SPAWNABLE.join(", ")}\n`);
+      return 1;
+    }
+
+    const flag = (name) => {
+      const i = argv.findIndex((a) => a === name || a.startsWith(`${name}=`));
+      return i === -1 ? null : argv[i].split("=")[1] ?? argv[i + 1] ?? null;
+    };
+
+    // Capacity is only consulted when asked: it costs a network round trip,
+    // and "which slug" is often the whole question.
+    let capacity = null;
+    if (has("--with-capacity")) {
+      const { readAll, capacity: decide } = await import("./providers/index.mjs");
+      const decision = decide(await readAll({ providers: [agent] }), { threshold: 90 });
+      capacity = decision.providers[0] ?? null;
+    }
+
+    const answer = await models.resolveAgent(agent, {
+      installs: discoverInstalls({ withVersions: true }),
+      model: flag("--model"),
+      capacity,
+    });
+
+    process.stdout.write(`${JSON.stringify(answer, null, 2)}\n`);
+    // An unresolvable agent, or a slug its binary refuses, is a failed
+    // precondition rather than a crash: exit 1 so a script can branch.
+    return answer.resolved && answer.model?.valid !== false ? 0 : 1;
+  }
+
+  // What each install will accept as a model. A separate question from quota,
+  // and the one that decides whether a delegation's -m argument is valid.
+  if (has("--models")) {
+    const [{ discoverInstalls }, models] = await Promise.all([
+      import("./installs.mjs"),
+      import("./models.mjs"),
+    ]);
+    const installs = discoverInstalls({ withVersions: true })
+      .filter((i) => models.SPAWNABLE.includes(i.agent));
+    const catalogues = await models.modelsForAll(installs);
+
+    if (has("--json")) {
+      process.stdout.write(`${JSON.stringify({ catalogues, skew: models.modelSkew(catalogues) }, null, 2)}\n`);
+      return 0;
+    }
+    process.stdout.write(`\n${renderModels(catalogues, models.modelSkew(catalogues))}\n`);
+    return 0;
+  }
+
+  // Multi-provider paths go through the registry, which isolates failures:
+  // Antigravity needs its IDE open, a Codex token expires, gh may be absent.
+  const threshold = gateThreshold(argv);
+  if (threshold !== null || has("--all")) {
+    const { readAll, capacity } = await import("./providers/index.mjs");
+    const results = await readAll();
+
+    if (threshold === null) {
+      process.stdout.write(`\n${renderProviders(results)}\n`);
+      return 0;
+    }
+
+    const decision = capacity(results, { threshold });
+    process.stdout.write(`${JSON.stringify(decision, null, 2)}\n`);
+
+    // The worst outcome decides: an unreadable provider outranks a comfortable
+    // one, because "I could not tell" must not be reported as room to work.
+    if (decision.providers.some((p) => p.decision === "proceed")) return GATE_EXIT.proceed;
+    if (decision.anyUnknown) return GATE_EXIT.unknown;
+    return GATE_EXIT.defer;
+  }
+
+  if (has("-h", "--help")) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  if (has("-v", "--version")) {
+    process.stdout.write(`${VERSION}\n`);
+    return 0;
+  }
+
+  const usage = await fetchUsage();
+
+  if (has("--json")) {
+    process.stdout.write(`${JSON.stringify(usage.raw, null, 2)}\n`);
+    return 0;
+  }
+  if (has("--short")) {
+    process.stdout.write(`${renderShort(usage)}\n`);
+    return 0;
+  }
+
+  const body = renderTable(usage);
+  if (has("--plain")) {
+    process.stdout.write(`${body}\n`);
+  } else {
+    process.stdout.write(`\nRunway - Claude\n\n${body}\n`);
+  }
+  return 0;
+}
+
+main(process.argv.slice(2))
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((error) => {
+    if (error instanceof UsageError) {
+      process.stderr.write(`agent-runway: ${error.message}\n`);
+      if (error.hint) process.stderr.write(`\n${error.hint}\n`);
+      process.exitCode = EXIT[error.code] ?? 1;
+      return;
+    }
+    process.stderr.write(`agent-runway: unexpected error: ${error?.message ?? error}\n`);
+    process.exitCode = 1;
+  });

package/src/core.mjs

@@ -0,0 +1,300 @@
+// Core logic shared by the CLI, the Claude Code skill and the MCP server.
+//
+// Security invariant: this module never logs, prints or returns a token.
+// Callers receive usage data only. Keep it that way.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const VERSION = "0.2.0";
+
+const USER_AGENT = `agent-runway/${VERSION} (+https://github.com/jberdah/agent-runway)`;
+
+/** Errors this module throws, with a stable `code` so callers can branch. */
+export class UsageError extends Error {
+  constructor(code, message, hint) {
+    super(message);
+    this.name = "UsageError";
+    this.code = code; // NO_TOKEN | AUTH | RATE_LIMITED | NO_RESPONSE | NETWORK
+    this.hint = hint;
+  }
+}
+
+const claudeDir = () => path.join(os.homedir(), ".claude");
+
+function readCredentialsFile() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(claudeDir(), ".credentials.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function readTokenFile(file) {
+  try {
+    const value = fs.readFileSync(file, "utf8").trim();
+    return value.startsWith("sk-ant-") ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve an OAuth token, most explicit source first.
+ *
+ * The last source is the token Claude Code keeps for its own session. It is a
+ * convenience so the tool works with no setup, but it is not a stable contract:
+ * on macOS the live token lives in the Keychain and on Windows in the Credential
+ * Manager, so the file is frequently absent or stale. Set
+ * AGENT_RUNWAY_NO_LOCAL_CREDENTIALS=1 to skip it entirely.
+ *
+ * @returns {{token: string, source: string, expiredAt: string|null}|null}
+ */
+export function resolveToken(env = process.env) {
+  const fromEnv = [
+    ["CLAUDE_CODE_OAUTH_TOKEN", "env CLAUDE_CODE_OAUTH_TOKEN"],
+    ["AGENT_RUNWAY_TOKEN", "env AGENT_RUNWAY_TOKEN"],
+    ["ANTHROPIC_AUTH_TOKEN", "env ANTHROPIC_AUTH_TOKEN"],
+  ];
+  for (const [name, source] of fromEnv) {
+    if (env[name]) return { token: env[name], source, expiredAt: null };
+  }
+
+  const fileToken = readTokenFile(path.join(claudeDir(), "usage-token"));
+  if (fileToken) return { token: fileToken, source: "~/.claude/usage-token", expiredAt: null };
+
+  if (env.AGENT_RUNWAY_NO_LOCAL_CREDENTIALS === "1") return null;
+
+  const oauth = readCredentialsFile()?.claudeAiOauth;
+  if (oauth?.accessToken) {
+    const expired = oauth.expiresAt && oauth.expiresAt < Date.now();
+    return {
+      token: oauth.accessToken,
+      source: "~/.claude/.credentials.json",
+      expiredAt: expired ? new Date(oauth.expiresAt).toISOString() : null,
+    };
+  }
+  return null;
+}
+
+/**
+ * The claude.ai web session cookie, for the organizations endpoint.
+ *
+ * A separate credential from the OAuth token, and the only one that endpoint
+ * takes: it answers "This endpoint does not accept OAuth access tokens" to a
+ * Bearer, whatever its scopes. Supply the value of the `sessionKey` cookie.
+ *
+ * Never harvested from a browser profile — the user pastes it, or does not.
+ */
+export function resolveCookie(env = process.env) {
+  if (env.AGENT_RUNWAY_CLAUDE_COOKIE) {
+    return { value: env.AGENT_RUNWAY_CLAUDE_COOKIE, source: "env AGENT_RUNWAY_CLAUDE_COOKIE" };
+  }
+  try {
+    const value = fs.readFileSync(path.join(claudeDir(), "session-cookie"), "utf8").trim();
+    if (value) return { value, source: "~/.claude/session-cookie" };
+  } catch {
+    /* absent is the normal case */
+  }
+  return null;
+}
+
+/** Organization UUID, needed only by the claude.ai endpoint. */
+export function resolveOrgId(env = process.env) {
+  return env.CLAUDE_ORG_ID || readCredentialsFile()?.organizationUuid || null;
+}
+
+async function request(url, authHeaders, fetchImpl) {
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      headers: {
+        ...authHeaders,
+        Accept: "application/json",
+        "anthropic-beta": "oauth-2025-04-20",
+        "User-Agent": USER_AGENT,
+      },
+    });
+  } catch (cause) {
+    throw new UsageError("NETWORK", `Could not reach ${new URL(url).host}: ${cause.message}`);
+  }
+  const text = await response.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    body = text;
+  }
+  return { status: response.status, ok: response.ok, body };
+}
+
+const WINDOW_LABELS = {
+  session: "Session (5h)",
+  weekly_all: "Weekly - all models",
+  weekly_scoped: "Weekly",
+};
+
+/**
+ * Flatten the API payload into a shape the three surfaces can share.
+ *
+ * The endpoints are internal and undocumented, so the canonical `limits` array
+ * is used when present and a tolerant scan of the top-level window objects is
+ * the fallback. Neither path is allowed to throw on an unexpected shape.
+ */
+export function normalize(payload) {
+  const windows = [];
+
+  if (Array.isArray(payload?.limits) && payload.limits.length) {
+    for (const limit of payload.limits) {
+      const model = limit.scope?.model?.display_name ?? null;
+      const base = WINDOW_LABELS[limit.kind] ?? limit.kind;
+      windows.push({
+        id: limit.kind,
+        label: model ? `${base} - ${model}` : base,
+        percent: limit.percent,
+        severity: limit.severity ?? "normal",
+        resetsAt: limit.resets_at ?? null,
+        active: Boolean(limit.is_active),
+        model,
+      });
+    }
+  } else if (payload && typeof payload === "object") {
+    for (const [key, value] of Object.entries(payload)) {
+      if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+      if (typeof value.utilization !== "number") continue;
+      const percent = value.utilization > 0 && value.utilization <= 1
+        ? value.utilization * 100
+        : value.utilization;
+      windows.push({
+        id: key,
+        label: WINDOW_LABELS[key] ?? key,
+        percent: Math.round(percent),
+        severity: "normal",
+        resetsAt: value.resets_at ?? null,
+        active: false,
+        model: null,
+      });
+    }
+  }
+
+  const order = { session: 0, weekly_all: 1, weekly_scoped: 2 };
+  windows.sort((a, b) => (order[a.id] ?? 9) - (order[b.id] ?? 9) || b.percent - a.percent);
+
+  const extra = payload?.extra_usage;
+  const extraUsage = extra && typeof extra === "object"
+    ? {
+        enabled: Boolean(extra.is_enabled),
+        percent: typeof extra.utilization === "number"
+          ? Math.round(extra.utilization > 1 ? extra.utilization : extra.utilization * 100)
+          : null,
+        monthlyLimit: extra.monthly_limit ?? null,
+        currency: extra.currency ?? null,
+        spendLimitReached: Boolean(extra.spend_limit_reached),
+      }
+    : null;
+
+  return { windows, extraUsage };
+}
+
+/**
+ * Fetch usage for the current account.
+ *
+ * @returns {Promise<{windows: Array, extraUsage: object|null, endpoint: string, tokenSource: string, raw: object}>}
+ */
+export async function fetchUsage({ env = process.env, fetchImpl = globalThis.fetch } = {}) {
+  const resolved = resolveToken(env);
+  if (!resolved) {
+    throw new UsageError(
+      "NO_TOKEN",
+      "No Claude OAuth token found.",
+      "Run `claude setup-token` and export the result as CLAUDE_CODE_OAUTH_TOKEN."
+    );
+  }
+
+  const orgId = resolveOrgId(env);
+  const cookie = resolveCookie(env);
+
+  // Each endpoint takes exactly one kind of credential. Sending a Bearer to
+  // claude.ai is not a fallback, it is a guaranteed 403 that only adds a
+  // confusing second line to every failure, so that endpoint is offered only
+  // when a session cookie exists to authenticate it.
+  const endpoints = [
+    {
+      name: "oauth/usage",
+      url: "https://api.anthropic.com/api/oauth/usage",
+      headers: { Authorization: `Bearer ${resolved.token}` },
+    },
+  ];
+  if (orgId && cookie) {
+    endpoints.push({
+      name: "organizations/usage",
+      url: `https://claude.ai/api/organizations/${orgId}/usage`,
+      headers: { Cookie: `sessionKey=${cookie.value}` },
+    });
+  }
+
+  const failures = [];
+  for (const endpoint of endpoints) {
+    let result;
+    try {
+      result = await request(endpoint.url, endpoint.headers, fetchImpl);
+    } catch (error) {
+      // A fallback that cannot be reached must not bury what the primary
+      // endpoint already answered. Record it and keep going; the verdict is
+      // decided once every endpoint has had its turn.
+      failures.push(`${endpoint.name}: ${error.message}`);
+      continue;
+    }
+
+    if (result.ok) {
+      return {
+        ...normalize(result.body),
+        endpoint: endpoint.name,
+        tokenSource: resolved.source,
+        raw: result.body,
+      };
+    }
+
+    // Carry the API's own words through. A rejection that says which scope is
+    // missing is worth far more than a bare "rejected", and this endpoint is
+    // undocumented enough that its reasons are the only source available.
+    const apiMessage =
+      (result.body && typeof result.body === "object"
+        ? result.body.error?.message ?? result.body.message ?? result.body.error?.type
+        : null) || null;
+    failures.push(`${endpoint.name}: HTTP ${result.status}${apiMessage ? ` - ${apiMessage}` : ""}`);
+
+    if (result.status === 429) {
+      throw new UsageError(
+        "RATE_LIMITED",
+        "The usage endpoint itself is rate limiting these requests. This is not your account quota.",
+        "Wait a few minutes before retrying. Do not poll in a loop."
+      );
+    }
+  }
+
+  const authFailed = failures.some((f) => /HTTP 40[13]/.test(f));
+  if (authFailed) {
+    const stale = resolved.expiredAt ? ` The token expired at ${resolved.expiredAt}.` : "";
+    const scopeProblem = failures.some((f) => /scope|permission/i.test(f));
+    throw new UsageError(
+      "AUTH",
+      `Token rejected (source: ${resolved.source}).${stale}\n  ` + failures.join("\n  "),
+      scopeProblem
+        ? "This token is valid, but not for reading usage. The endpoint requires the\n" +
+          "user:profile scope, and `claude setup-token` does not grant it - regenerating\n" +
+          "the token produces exactly the same refusal.\n\n" +
+          "Claude usage can only be read with Claude Code's own session credentials\n" +
+          "today, which means keeping Claude Code signed in. Codex, Copilot and\n" +
+          "Antigravity are unaffected: they have durable credentials of their own."
+        : "Sign in to Claude Code, or supply a token carrying the user:profile scope."
+    );
+  }
+  const reachable = failures.some((f) => /HTTP \d/.test(f));
+  throw new UsageError(
+    "NO_RESPONSE",
+    `No usage endpoint responded (${failures.join(", ")}).`,
+    reachable ? undefined : "Every endpoint failed to connect. Check the network or a proxy."
+  );
+}