agent-runway 0.2.0

package/src/providers/index.mjs

@@ -0,0 +1,155 @@
+// Provider registry: read one, or read them all at once.
+//
+// Reading several providers must never fail as a whole. Antigravity only
+// answers while its IDE runs, a Codex token expires, `gh` may be absent — any
+// of those is a per-provider status, never an exception that loses the other
+// three. Every adapter is wrapped so a throw or a hang degrades that provider
+// alone.
+
+import * as cache from "../cache.mjs";
+import * as antigravity from "./antigravity.mjs";
+import * as claude from "./claude.mjs";
+import * as codex from "./codex.mjs";
+import * as copilot from "./copilot.mjs";
+import { bindingWindow, secondsUntilReset, unavailable } from "./shared.mjs";
+
+export const ADAPTERS = { claude, codex, copilot, antigravity };
+export const PROVIDER_IDS = Object.keys(ADAPTERS);
+
+const HARD_TIMEOUT_MS = 20000;
+
+/** Never throws, never hangs: an adapter's failure becomes that provider's status. */
+async function readOne(name, options) {
+  const adapter = ADAPTERS[name];
+  if (!adapter) return unavailable(name, "error", "unknown provider");
+
+  const maxAge = options.cacheMs ?? cache.ttlMs(options.env ?? process.env);
+
+  // A recent answer beats asking again: these endpoints rate-limit reads, and a
+  // 429 on a usage endpoint reads like the account quota it reports on.
+  const hit = cache.read(name, maxAge);
+  if (hit?.fresh) {
+    return { ...hit.value, cached: true, ageMs: hit.ageMs, latencyMs: 0 };
+  }
+
+  const started = Date.now();
+  const guard = new Promise((resolve) =>
+    setTimeout(
+      () => resolve(unavailable(name, "unreachable", `no answer within ${HARD_TIMEOUT_MS / 1000}s`)),
+      options.hardTimeoutMs ?? HARD_TIMEOUT_MS
+    ).unref?.()
+  );
+
+  let result;
+  try {
+    result = await Promise.race([adapter.read(options), guard]);
+  } catch (error) {
+    result = unavailable(name, "error", String(error?.message ?? error));
+  }
+
+  const enriched = { ...result, label: adapter.label ?? name, latencyMs: Date.now() - started };
+
+  if (enriched.status === "ok") {
+    cache.write(name, enriched);
+    return enriched;
+  }
+
+  // Failed. Stale numbers about a five-hour window still say more than silence,
+  // so long as they are labelled as stale rather than passed off as current.
+  if (hit) {
+    return {
+      ...hit.value,
+      cached: true,
+      stale: true,
+      ageMs: hit.ageMs,
+      latencyMs: enriched.latencyMs,
+      detail: `serving a cached reading ${Math.round(hit.ageMs / 1000)}s old: ${enriched.detail ?? enriched.status}`,
+    };
+  }
+  return enriched;
+}
+
+/**
+ * @param {object} [options]
+ * @param {string[]} [options.providers] subset to read; defaults to all
+ * @returns {Promise<Array>} one result per provider, in registry order
+ */
+export async function readAll(options = {}) {
+  const names = options.providers?.length ? options.providers : PROVIDER_IDS;
+  // In parallel: Antigravity spawns two processes and Copilot shells out to gh,
+  // so serial reads would add up to seconds.
+  return Promise.all(names.map((name) => readOne(name, options)));
+}
+
+export const readProvider = readOne;
+
+/**
+ * Turn readings into a decision.
+ *
+ * `threshold` is a policy, not a fact: at 92% the provider is not blocked, the
+ * caller's own rule says not to start. Three outcomes, because two are not
+ * enough — a provider that cannot be read is "unknown", never "fine".
+ */
+export function capacity(results, { threshold = 90 } = {}) {
+  const providers = results.map((r) => {
+    if (r.status !== "ok") {
+      return { provider: r.provider, label: r.label, decision: "unknown", reason: r.status, detail: r.detail };
+    }
+
+    const binding = bindingWindow(r.windows);
+    if (!binding || binding.percentUsed == null) {
+      return { provider: r.provider, label: r.label, decision: "unknown", reason: "no_readable_window" };
+    }
+
+    // Codex states outright whether it will serve a request; that beats a
+    // percentage we interpreted ourselves.
+    if (r.allowed === false) {
+      return {
+        provider: r.provider, label: r.label, decision: "defer", reason: "provider_says_limit_reached",
+        binding, retryAt: binding.resetsAt, retryAtBasis: "reported_reset",
+      };
+    }
+
+    const over = binding.percentUsed >= threshold;
+    return {
+      provider: r.provider,
+      label: r.label,
+      decision: over ? "defer" : "proceed",
+      reason: over ? "threshold_exceeded" : "within_threshold",
+      binding,
+      retryAt: over ? binding.resetsAt : null,
+      // The reset is when the window rolls over, not a promise that service
+      // resumes exactly then. Naming the basis keeps the two apart.
+      retryAtBasis: over ? "window_reset" : null,
+    };
+  });
+
+  const usable = providers.filter((p) => p.decision === "proceed" && p.binding);
+
+  // Ranking rule, stated rather than implied: most headroom in the window that
+  // would bind first. Windows of different cadence are NOT interchangeable —
+  // 0% of a five-hour window is far less capacity than 0% of a monthly
+  // allowance — so the basis travels with the recommendation.
+  const recommended = usable.length
+    ? usable.reduce((best, p) => (p.binding.percentUsed < best.binding.percentUsed ? p : best))
+    : null;
+
+  const cadences = new Set(usable.map((p) => p.binding.windowSeconds ?? "calendar"));
+
+  return {
+    threshold,
+    providers,
+    recommended: recommended
+      ? {
+          provider: recommended.provider,
+          percentUsed: recommended.binding.percentUsed,
+          window: recommended.binding.label,
+          windowSeconds: recommended.binding.windowSeconds,
+          secondsUntilReset: secondsUntilReset(recommended.binding),
+          rule: "least consumed binding window among providers under the threshold",
+          comparable: cadences.size <= 1,
+        }
+      : null,
+    anyUnknown: providers.some((p) => p.decision === "unknown"),
+  };
+}

package/src/providers/shared.mjs

@@ -0,0 +1,123 @@
+// The normalized contract every provider adapter must produce.
+//
+// Four providers were probed to design this, and each reports "how full is it"
+// differently: Claude and Codex give a percentage consumed, Copilot gives a
+// percentage remaining plus raw counts, Antigravity gives a 0-1 fraction
+// remaining plus credits. Adapters convert into one direction — percentUsed —
+// and keep the raw numbers when a provider supplies them, because "200 of 2000
+// chat requests" says more than "90%".
+
+/** @typedef {"ok"|"no_credentials"|"not_installed"|"unreachable"|"error"} ProviderStatus */
+
+export const UNKNOWN = null;
+
+// ---------------------------------------------------------------- percentages
+
+export const fromUsedPercent = (n) => clampPercent(n);
+export const fromRemainingPercent = (n) => clampPercent(100 - n);
+export const fromRemainingFraction = (f) => clampPercent(100 - f * 100);
+
+/** Copilot-style: remaining out of an entitlement. */
+export function fromCounts(remaining, entitlement) {
+  if (!Number.isFinite(remaining) || !Number.isFinite(entitlement) || entitlement <= 0) return UNKNOWN;
+  return clampPercent(100 - (remaining / entitlement) * 100);
+}
+
+function clampPercent(n) {
+  if (!Number.isFinite(n)) return UNKNOWN;
+  return Math.max(0, Math.min(100, Math.round(n)));
+}
+
+// -------------------------------------------------------------------- windows
+
+/**
+ * One quota window, whatever its cadence.
+ *
+ * `kind` is an open string on purpose. Codex already exposes a field called
+ * `additional_rate_limits`, and providers state they may add model- or
+ * feature-scoped caps, so an unrecognised kind must survive to the caller
+ * rather than be dropped.
+ *
+ * `startsAt` is only ever computed when `windowSeconds` is known, and
+ * `windowSource` records whether the provider reported that duration (Codex) or
+ * whether we inferred it (Claude). A caller can then choose to trust it or not.
+ */
+export function makeWindow({
+  kind,
+  label,
+  percentUsed,
+  resetsAt = null,
+  windowSeconds = null,
+  windowSource = null,
+  remaining = null,
+  entitlement = null,
+  entitled = true,
+  severity = null,
+  model = null,
+  unit = "requests",
+}) {
+  const startsAt =
+    resetsAt && Number.isFinite(windowSeconds)
+      ? new Date(Date.parse(resetsAt) - windowSeconds * 1000).toISOString()
+      : null;
+
+  return {
+    kind,
+    label: label ?? kind,
+    percentUsed,
+    remaining,
+    entitlement,
+    entitled,
+    unit,
+    resetsAt,
+    windowSeconds,
+    windowSource,
+    startsAt,
+    severity,
+    model,
+  };
+}
+
+/** Seconds until a window resets; null when unknown or already elapsed. */
+export function secondsUntilReset(window, now = Date.now()) {
+  if (!window?.resetsAt) return UNKNOWN;
+  const delta = Math.round((Date.parse(window.resetsAt) - now) / 1000);
+  return Number.isFinite(delta) ? delta : UNKNOWN;
+}
+
+/**
+ * The window that will bite first: the most consumed one among those the
+ * account is actually entitled to. A quota the plan does not include is not a
+ * constraint, it is an absence — Copilot's free tier reports
+ * premium_interactions at 0 of 0, which a naive reading calls "exhausted".
+ */
+export function bindingWindow(windows = []) {
+  const real = windows.filter((w) => w.entitled && Number.isFinite(w.percentUsed));
+  if (!real.length) return null;
+  return real.reduce((worst, w) => (w.percentUsed > worst.percentUsed ? w : worst));
+}
+
+// ------------------------------------------------------------------- results
+
+export function ok(provider, { plan = null, allowed = null, windows = [], detail = null }) {
+  return { provider, status: "ok", plan, allowed, windows, detail, checkedAt: new Date().toISOString() };
+}
+
+export function unavailable(provider, status, detail) {
+  return {
+    provider,
+    status,
+    plan: null,
+    allowed: null,
+    windows: [],
+    detail,
+    checkedAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Identity fields travel in three of the four payloads (name, email, user id).
+ * Adapters must never copy them into a result: `--json` output ends up in CI
+ * logs and shared terminals.
+ */
+export const IDENTITY_KEYS = /^(email|name|user_?id|account_?id|login|analytics_tracking_id)$/i;

package/src/render.mjs

@@ -0,0 +1,162 @@
+// Text rendering. Kept separate from fetching so the MCP server can reuse it.
+
+const LABEL_WIDTH = 32;
+const BAR_WIDTH = 20;
+
+const SEVERITY_NOTE = {
+  normal: "",
+  warning: "  <-- warning",
+  critical: "  <-- critical",
+};
+
+export function bar(percent) {
+  const filled = Math.max(0, Math.min(BAR_WIDTH, Math.round(percent / (100 / BAR_WIDTH))));
+  return `[${"#".repeat(filled)}${".".repeat(BAR_WIDTH - filled)}]`;
+}
+
+export function formatReset(value, now = Date.now()) {
+  if (value == null) return null;
+  const date = typeof value === "number"
+    ? new Date(value < 1e12 ? value * 1000 : value)
+    : new Date(value);
+  if (Number.isNaN(date.getTime())) return String(value);
+
+  const minutes = Math.round((date.getTime() - now) / 60000);
+  let relative;
+  if (minutes < 0) relative = "elapsed";
+  else if (minutes < 60) relative = `in ${minutes}m`;
+  else if (minutes < 2880) relative = `in ${Math.floor(minutes / 60)}h ${String(minutes % 60).padStart(2, "0")}m`;
+  else relative = `in ${Math.floor(minutes / 1440)}d ${Math.floor((minutes % 1440) / 60)}h`;
+
+  return `${date.toISOString().slice(0, 16).replace("T", " ")}Z (${relative})`;
+}
+
+/** One line per window, for humans. */
+export function renderTable(usage, now = Date.now()) {
+  const lines = [];
+  if (!usage.windows.length) {
+    lines.push("  No usage window reported.");
+    return lines.join("\n");
+  }
+
+  for (const window of usage.windows) {
+    const marker = window.active ? "* " : "  ";
+    const note = SEVERITY_NOTE[window.severity] ?? "";
+    lines.push(
+      marker +
+        window.label.padEnd(LABEL_WIDTH) +
+        bar(window.percent) +
+        ` ${String(Math.round(window.percent)).padStart(3)} %` +
+        note
+    );
+    const reset = formatReset(window.resetsAt, now);
+    if (reset) lines.push(" ".repeat(LABEL_WIDTH + 2) + `resets ${reset}`);
+  }
+
+  if (usage.extraUsage) {
+    lines.push("");
+    if (!usage.extraUsage.enabled) {
+      lines.push("  Extra usage credits: disabled");
+    } else {
+      const percent = usage.extraUsage.percent == null ? "?" : `${usage.extraUsage.percent} %`;
+      const cap = usage.extraUsage.monthlyLimit
+        ? ` of ${usage.extraUsage.monthlyLimit} ${usage.extraUsage.currency ?? ""}`.trimEnd()
+        : "";
+      lines.push(`  Extra usage credits: enabled, ${percent} used${cap}`);
+      if (usage.extraUsage.spendLimitReached) lines.push("  !! spend limit reached");
+    }
+  }
+
+  if (usage.windows.some((w) => w.active)) {
+    lines.push("");
+    // The API's is_active flag does NOT mark the window being consumed right
+    // now: observed three times, twice with the ordering reversed, it lands on
+    // whichever window is furthest along. A session at 3% while actively in use
+    // goes unflagged and an untouched weekly at 87% carries it.
+    lines.push("  * = closest to its limit, as the API flags it");
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Every provider at once, each with the state of its own read.
+ *
+ * A provider that could not be reached gets a line saying so rather than being
+ * dropped: the absence is information, and silently showing three of four would
+ * invite a delegation to the missing one.
+ */
+export function renderProviders(results) {
+  const lines = [];
+  for (const provider of results) {
+    const name = (provider.label ?? provider.provider).padEnd(16);
+    const age = provider.cached ? `  (cached ${Math.round(provider.ageMs / 1000)}s${provider.stale ? ", stale" : ""})` : "";
+
+    if (provider.status !== "ok") {
+      lines.push(`${name}${provider.status}${provider.detail ? ` - ${provider.detail}` : ""}`);
+      lines.push("");
+      continue;
+    }
+
+    lines.push(`${name}${provider.plan ?? ""}${age}`);
+    for (const w of provider.windows) {
+      if (!w.entitled) {
+        lines.push(`    ${w.label.padEnd(26)} not included in this plan`);
+        continue;
+      }
+      const counts = w.remaining != null && w.entitlement != null
+        ? `  ${w.remaining}/${w.entitlement} ${w.unit}`
+        : "";
+      lines.push(
+        `    ${w.label.padEnd(26)}${bar(w.percentUsed)} ${String(w.percentUsed).padStart(3)} %${counts}`
+      );
+      const reset = formatReset(w.resetsAt);
+      if (reset) lines.push(`    ${" ".repeat(26)}resets ${reset}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd();
+}
+
+/**
+ * What each install will accept as a model, and where they disagree.
+ *
+ * The disagreement is the point: a slug offered by the build behind an editor
+ * and missing from the one on PATH is a delegation that fails.
+ */
+export function renderModels(catalogues, skews = []) {
+  const lines = [];
+  for (const c of catalogues) {
+    const head = `${c.agent} ${c.kind}`.padEnd(18) + (c.version ?? "?").padEnd(20);
+    if (c.error) {
+      lines.push(`${head}unreadable - ${c.error}`);
+      continue;
+    }
+    // "declared" means the binary answered; "inferred" means we read strings
+    // out of it, which can produce plausible-looking rubbish.
+    lines.push(`${head}${String(c.models.length).padStart(2)} models  [${c.authority}]`);
+    lines.push(`    ${c.models.map((m) => m.id).join(", ")}`);
+  }
+
+  if (skews.length) {
+    lines.push("");
+    lines.push("Disagreements between installs of the same agent:");
+    for (const s of skews) {
+      lines.push(`  ${s.agent} ${s.install.kind} ${s.install.version ?? ""} does not offer: ${s.missing.join(", ")}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+/** Single line, for an agent checking headroom before a long task. */
+export function renderShort(usage) {
+  if (!usage.windows.length) return "no usage data";
+  return usage.windows.map((w) => `${w.id}=${Math.round(w.percent)}%`).join("  ");
+}
+
+/** Highest window, useful for a one-glance verdict. */
+export function peak(usage) {
+  return usage.windows.reduce(
+    (max, w) => (w.percent > (max?.percent ?? -1) ? w : max),
+    null
+  );
+}