agent-runway 0.2.1 → 0.2.2

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "displayName": "Agent Runway",
       "source": "./",
       "description": "Quota and model discovery for the coding agents installed on this machine: how much runway each has left, and which model slugs each binary will actually accept.",
-      "version": "0.2.1",
+      "version": "0.2.2",
       "author": {
         "name": "jberdah",
         "url": "https://github.com/jberdah"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-runway",
   "displayName": "Agent Runway",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Quota and model discovery for the coding agents installed on this machine: how much runway each has left, and which model slugs each binary will actually accept.",
   "author": {
     "name": "jberdah",

package/README.md

@@ -226,6 +226,25 @@ claude.ai fallback endpoint.
 Before delegating work, an agent needs both halves of the answer, and getting
 them from two different tools defeats the point:
 
+### What is covered, and what is not
+
+Not every agent answers both questions. Antigravity reports a quota and cannot
+be spawned; Gemini can be spawned and publishes no usage endpoint. Reading a
+missing cell as zero would be worse than reading nothing.
+
+| Agent | Runway | Model list | `resolve` |
+| --- | --- | --- | --- |
+| Claude | yes — token, or session cookie | inferred, by scanning the binary | yes |
+| Codex | yes | declared, from `codex app-server` | yes |
+| GitHub Copilot | yes — through `gh` | declared, from shell completion | yes |
+| Gemini | **no endpoint** | inferred, by scanning the binary | yes |
+| Antigravity | yes — only while its IDE runs | **not covered** | **not spawnable** |
+
+*Declared* means the binary was asked and answered. *Inferred* means slugs were
+recovered from the binary itself: indicative, not authoritative — a spawn can
+still be refused, and every inferred catalogue is labelled as such in the
+output.
+
 **How much runway is left, per provider.**
 
 ```bash
@@ -307,8 +326,33 @@ unknown. Three outcomes rather than two, because a provider that could not be
 read has not got room — it is simply unknown, and must never be counted as
 either.
 
-The recommendation states its own rule and whether the candidates were even
-comparable: 0% of a five-hour window is not 0% of a monthly allowance.
+### Two questions that are easy to confuse
+
+*Can I keep working?* and *could anything on this machine take this job?* are
+not the same question, and answering the second when the first was asked is how
+an agent talks itself into a fan-out it has no room for. Claude at 96% beside
+Codex at 10% is **not** a green light.
+
+```bash
+agent-runway --gate 90 --provider claude   # about one agent: yours
+agent-runway --gate 90                     # defers unless every provider has room
+agent-runway --gate 90 --any               # the fan-out question, asked by name
+```
+
+The answer carries the rule that produced it, so `proceed` can never be read as
+more than it claims:
+
+```json
+"overall": {
+  "decision": "defer",
+  "rule": "all",
+  "ruleText": "every readable provider is under the threshold",
+  "scoped": null
+}
+```
+
+The recommendation likewise states its own rule and whether the candidates were
+even comparable: 0% of a five-hour window is not 0% of a monthly allowance.
 
 ## CLI reference
 
@@ -316,20 +360,35 @@ comparable: 0% of a five-hour window is not 0% of a monthly allowance.
 | --- | --- |
 | *(none)* | Claude only, readable table |
 | `--all` | Every provider found on this machine |
+| `--provider <id>` | One provider only — use it when asking about yourself |
 | `--models` | What each install accepts, and where installs disagree |
 | `resolve <agent>` | Binary, valid slugs and a verdict on one model |
 | `--gate <N>` | Decision as JSON plus an exit code |
+| `--any` | With `--gate`: proceed if any one provider has room |
 | `--short` | One line: `session=15%  weekly_all=79%  weekly_scoped=52%` |
-| `--json` | Raw response; combines with `--models` |
+| `--json` | Normalized JSON, always carrying `tool` / `toolVersion` / `kind` |
+| `--raw` | The provider's own payload, unwrapped — not a stable contract |
 | `--plain` | Table without the header |
 
+Everything printed under `--json` declares which question it answers, so a
+parser never has to know what was asked to read the answer:
+
+| `kind` | Produced by |
+| --- | --- |
+| `usage` | *(none)*, `--all` |
+| `capacity` | `--gate` |
+| `models` | `--models` |
+| `resolve` | `resolve <agent>` |
+
 | Exit code | Meaning |
 | --- | --- |
-| 0 | success |
-| 1 | unexpected error |
+| 0 | success, or a gate that says proceed |
+| 1 | unexpected error, or an unusable argument |
 | 2 | no token found |
 | 3 | token rejected — regenerate it |
 | 4 | the usage endpoint is throttling; not your quota |
+| 10 | gate: defer |
+| 11 | gate: unknown — a provider could not be read |
 
 ## Security
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-runway",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Quota and model discovery for the coding agents installed on this machine: how much runway each has left, and which model slugs each binary will actually accept.",
   "type": "module",
   "license": "MIT",
@@ -14,7 +14,7 @@
     "url": "https://github.com/jberdah/agent-runway/issues"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "bin": {
     "agent-runway": "src/cli.mjs",
@@ -31,7 +31,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test \"test/**/*.test.mjs\"",
+    "test": "node scripts/run-tests.mjs",
     "start": "node src/cli.mjs",
     "mcp": "node src/mcp.mjs",
     "smoke": "node scripts/smoke-mcp.mjs",

package/skills/agent-runway/SKILL.md

@@ -13,18 +13,48 @@ run**.
 All of these are safe, read-only, and print to stdout.
 
 ```bash
-agent-runway --all            # quota for every provider found
-agent-runway --models         # what each install accepts, and where installs disagree
-agent-runway --gate 90        # decision + exit code: 0 proceed, 10 defer, 11 unknown
+agent-runway --all                       # quota for every provider found
+agent-runway --models                    # what each install accepts, and where they disagree
+agent-runway --gate 90 --provider claude # can I keep working? 0 proceed, 10 defer, 11 unknown
+agent-runway --gate 90 --any             # could any agent here take this job?
 agent-runway resolve codex --model gpt-6-astra   # one answer before spawning
 ```
 
-Add `--json` to `--models` and `resolve` for machine-readable output. Bare
-`agent-runway` reads Claude only and is the fastest path when that is all you
-need.
+`--json` works on every command and always returns the same contract, tagged
+with `kind` (`usage`, `capacity`, `models`, `resolve`). `--raw` returns the
+provider's own payload and promises nothing. Bare `agent-runway` reads Claude
+only and is the fastest path when that is all you need.
 
 If the command is not on PATH, run it from the checkout: `node src/cli.mjs …`.
 
+## Asking the gate the right question
+
+**`--gate` without `--provider` is not about you.** It reads every provider on
+the machine, and by default defers unless all of them have room. Two failure
+modes to avoid:
+
+- Asking the bare question and reading `proceed` as *your* runway. Pass
+  `--provider claude` (or whichever agent you are running as) when the question
+  is whether to continue this session.
+- Asking `--any` and reading it as permission to work here. `--any` answers
+  *some agent on this machine has room* — which is about delegation, not about
+  you.
+
+The answer carries `overall.ruleText`. Quote it rather than paraphrasing
+`proceed`.
+
+## Coverage is uneven, and the gaps matter
+
+| Agent | Runway | Models | Spawnable |
+| --- | --- | --- | --- |
+| Claude, Codex, GitHub Copilot | yes | yes | yes |
+| Gemini | **no endpoint exists** | yes | yes |
+| Antigravity | only while its IDE runs | **no** | **no** |
+
+Never report a missing cell as zero, and never suggest delegating to
+Antigravity. If asked about Gemini's quota, say there is no endpoint to read
+rather than implying it is at zero or unknown-but-checkable.
+
 ## Reading a quota answer
 
 - A `*` marks the window **closest to its limit**, which is not the one being
@@ -71,6 +101,20 @@ refused, so a script can branch on it.
 **Offer the substitute, never apply it silently.** Running a different model
 than the user asked for, without saying so, is worse than failing.
 
+## When the answer is defer
+
+The tool stops at `retryAt` and `retryAtBasis`. It does not wake anything up,
+and it cannot save a conversation — a session that runs out of quota loses its
+context whatever this reports.
+
+So before proposing to wait for a reset, **write the state down**: what was
+done, what is left, the files and paths involved, in a file the user can hand
+to a fresh session. Offer the reset time as information the user acts on, not
+as a schedule the agent will keep.
+
+`retryAtBasis: "window_reset"` means the window rolls over then. It is not a
+promise that service resumes at that moment; say so when quoting it.
+
 ## Rules
 
 - Never print, log or copy a credential, not even a prefix. The tool never

package/src/cli.mjs

@@ -20,12 +20,19 @@ Commands:
 
 Options:
   --all           Every provider found on this machine, not just Claude
+  --provider <id> Read one provider only: claude, codex, copilot, antigravity.
+                  Use this when asking about yourself rather than the machine.
   --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.
+                  Defers unless every provider read is under the threshold.
+  --any           With --gate, proceed when any one provider has room. This is
+                  the fan-out question, and it is not the same as "can I go on".
   --short         One line, machine friendly: session=79%  weekly_all=76%
-  --json          Raw API response, unformatted
+  --json          Normalized JSON. Every shape carries tool/version/kind, so a
+                  parser can tell which question it is looking at the answer to.
+  --raw           The provider's own payload, unwrapped. Not a stable contract.
   --plain         Skip the header, print only the windows
   -h, --help      Show this help
   -v, --version
@@ -53,6 +60,31 @@ const EXIT = { NO_TOKEN: 2, AUTH: 3, RATE_LIMITED: 4 };
 // the same as one with room, and must never be treated as one.
 const GATE_EXIT = { proceed: 0, defer: 10, unknown: 11 };
 
+/**
+ * Every `--json` answer carries the same three fields.
+ *
+ * Before this the flag meant three unrelated things depending on which other
+ * flag it sat beside — a raw Anthropic payload, a decision, a model catalogue —
+ * so nothing could parse it without first knowing what had been asked. `kind`
+ * makes that readable from the answer alone. `--raw` stays outside: it exists
+ * precisely to be the unwrapped provider payload, and promising it a shape
+ * would be promising something we do not control.
+ *
+ * `toolVersion` rather than `version` because payloads already carry versions
+ * of their own that matter more than ours: `resolve` reports the version of the
+ * binary it found, and flattening a field called `version` over it would
+ * silently replace "Codex 0.149.1" with the version of this tool.
+ */
+const emit = (kind, payload) =>
+  `${JSON.stringify({ tool: "agent-runway", toolVersion: VERSION, kind, ...payload }, null, 2)}\n`;
+
+/** `--name value` or `--name=value`; null when absent. */
+function flagValue(argv, name) {
+  const i = argv.findIndex((a) => a === name || a.startsWith(`${name}=`));
+  if (i === -1) return null;
+  return argv[i].split("=")[1] ?? argv[i + 1] ?? null;
+}
+
 /** `--gate 90`, `--gate=90`, or `--gate` for the default. */
 function gateThreshold(argv) {
   const index = argv.findIndex((a) => a === "--gate" || a.startsWith("--gate="));
@@ -88,10 +120,7 @@ async function main(argv) {
       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;
-    };
+    const flag = (name) => flagValue(argv, name);
 
     // Capacity is only consulted when asked: it costs a network round trip,
     // and "which slug" is often the whole question.
@@ -108,7 +137,7 @@ async function main(argv) {
       capacity,
     });
 
-    process.stdout.write(`${JSON.stringify(answer, null, 2)}\n`);
+    process.stdout.write(emit("resolve", answer));
     // 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;
@@ -126,7 +155,7 @@ async function main(argv) {
     const catalogues = await models.modelsForAll(installs);
 
     if (has("--json")) {
-      process.stdout.write(`${JSON.stringify({ catalogues, skew: models.modelSkew(catalogues) }, null, 2)}\n`);
+      process.stdout.write(emit("models", { catalogues, skew: models.modelSkew(catalogues) }));
       return 0;
     }
     process.stdout.write(`\n${renderModels(catalogues, models.modelSkew(catalogues))}\n`);
@@ -136,23 +165,30 @@ async function main(argv) {
   // 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();
+  const provider = flagValue(argv, "--provider");
+  if (threshold !== null || has("--all") || provider) {
+    const { PROVIDER_IDS, readAll, capacity } = await import("./providers/index.mjs");
+
+    if (provider && !PROVIDER_IDS.includes(provider)) {
+      process.stderr.write(`agent-runway: --provider takes one of ${PROVIDER_IDS.join(", ")}\n`);
+      return 1;
+    }
+
+    const results = await readAll(provider ? { providers: [provider] } : {});
 
     if (threshold === null) {
-      process.stdout.write(`\n${renderProviders(results)}\n`);
+      process.stdout.write(
+        has("--json") ? emit("usage", { providers: results }) : `\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;
+    // The permissive reading has to be asked for. An agent checking whether it
+    // can keep going should pass --provider and get an answer about itself;
+    // without that, one provider over the threshold defers the whole answer.
+    const decision = capacity(results, { threshold, rule: has("--any") ? "any" : "all" });
+    process.stdout.write(emit("capacity", decision));
+    return GATE_EXIT[decision.overall.decision] ?? GATE_EXIT.unknown;
   }
 
   if (has("-h", "--help")) {
@@ -166,10 +202,27 @@ async function main(argv) {
 
   const usage = await fetchUsage();
 
-  if (has("--json")) {
+  // The escape hatch, and the only output that promises nothing: whatever the
+  // provider sent, unwrapped. Useful when the normalized view has dropped a
+  // field that turns out to matter.
+  if (has("--raw")) {
     process.stdout.write(`${JSON.stringify(usage.raw, null, 2)}\n`);
     return 0;
   }
+  if (has("--json")) {
+    // Built through the same helpers the registry uses, so reading one provider
+    // and reading four produce the same description of a window.
+    const [{ toWindows }, { ok }] = await Promise.all([
+      import("./providers/claude.mjs"),
+      import("./providers/shared.mjs"),
+    ]);
+    const result = ok("claude", {
+      windows: toWindows(usage),
+      detail: usage.extraUsage?.enabled ? "extra usage credits enabled" : null,
+    });
+    process.stdout.write(emit("usage", { providers: [{ ...result, label: "Claude" }] }));
+    return 0;
+  }
   if (has("--short")) {
     process.stdout.write(`${renderShort(usage)}\n`);
     return 0;

package/src/core.mjs

@@ -7,7 +7,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-export const VERSION = "0.2.1";
+export const VERSION = "0.2.2";
 
 const USER_AGENT = `agent-runway/${VERSION} (+https://github.com/jberdah/agent-runway)`;
 

package/src/mcp.mjs

@@ -65,7 +65,9 @@ const TOOLS = [
       "is when the window rolls over and not a promise that service resumes " +
       "exactly then. The recommendation states its own rule and whether the " +
       "candidates were comparable at all: 0% of a five-hour window is not 0% of " +
-      "a monthly allowance.",
+      "a monthly allowance. Asking whether YOU can keep working is a different " +
+      "question from whether any agent on the machine could take the job: pass " +
+      "provider for the first, rule=any for the second.",
     inputSchema: {
       type: "object",
       properties: {
@@ -77,6 +79,22 @@ const TOOLS = [
             "Percent consumed above which to defer. A policy, not a fact: at 92% " +
             "the provider is not blocked, your rule says do not start. Default 90.",
         },
+        provider: {
+          type: "string",
+          enum: [...PROVIDERS, "all"],
+          description:
+            "Restrict the decision to one agent. Pass the agent you are running " +
+            "as when the question is whether to continue this session; otherwise " +
+            "a comfortable provider elsewhere on the machine can mask yours.",
+        },
+        rule: {
+          type: "string",
+          enum: ["all", "any"],
+          description:
+            "How per-provider decisions combine. 'all' (default) defers unless " +
+            "every provider read is under the threshold. 'any' proceeds when one " +
+            "of them has room, which answers a fan-out, not your own runway.",
+        },
       },
       additionalProperties: false,
     },
@@ -84,10 +102,11 @@ const TOOLS = [
       type: "object",
       properties: {
         threshold: { type: "number" },
+        overall: LOOSE,
         providers: { type: "array", items: LOOSE },
         anyUnknown: { type: "boolean" },
       },
-      required: ["threshold", "providers", "anyUnknown"],
+      required: ["threshold", "overall", "providers", "anyUnknown"],
       additionalProperties: true,
     },
   },
@@ -151,12 +170,18 @@ async function getUsage(args) {
 
 async function checkCapacity(args) {
   const { readAll, capacity } = await import("./providers/index.mjs");
-  const decision = capacity(await readAll(), { threshold: args?.threshold ?? 90 });
 
-  const lines = decision.providers.map(
+  const wanted = args?.provider && args.provider !== "all" ? [args.provider] : undefined;
+  const decision = capacity(await readAll(wanted ? { providers: wanted } : {}), {
+    threshold: args?.threshold ?? 90,
+    rule: args?.rule === "any" ? "any" : "all",
+  });
+
+  const lines = [`${decision.overall.decision}: ${decision.overall.ruleText}`, ""];
+  lines.push(...decision.providers.map(
     (p) => `${p.provider}: ${p.decision}${p.binding ? ` (${p.binding.label} ${p.binding.percentUsed}%)` : ""}` +
       `${p.retryAt ? ` - retry at ${p.retryAt}` : ""}`
-  );
+  ));
   if (decision.recommended) {
     lines.push("");
     lines.push(

package/src/providers/claude.mjs

@@ -15,6 +15,29 @@ export const label = "Claude";
 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" };
 
+/**
+ * Core's reading, expressed in the shared window contract.
+ *
+ * Exported because the single-provider CLI path needs the same normalization
+ * the registry gets: a caller parsing `--json` and one parsing `--gate` must
+ * not receive two different descriptions of the same account.
+ */
+export function toWindows(usage) {
+  return 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,
+    });
+  });
+}
+
 export async function read({ env = process.env, fetchImpl = globalThis.fetch } = {}) {
   let usage;
   try {
@@ -30,19 +53,7 @@ export async function read({ env = process.env, fetchImpl = globalThis.fetch } =
     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,
-    });
-  });
+  const windows = toWindows(usage);
 
   // Extra credits mean a window at 100% is not necessarily a wall.
   const detail = usage.extraUsage?.enabled ? "extra usage credits enabled" : null;

package/src/providers/index.mjs

@@ -83,6 +83,40 @@ export async function readAll(options = {}) {
 
 export const readProvider = readOne;
 
+/**
+ * How the per-provider decisions combine into one answer.
+ *
+ * These are two different questions and conflating them is dangerous. "Can I
+ * keep working" is about the caller's own provider; "is there any agent that
+ * could take this" is about a fan-out. Answering the second when the first was
+ * asked reports room that the caller does not have — Claude at 96% beside
+ * Codex at 10% would come back as proceed.
+ *
+ * So the default is the conservative reading, and the permissive one has to be
+ * asked for by name. Scoping to a single provider makes the two identical,
+ * which is the form a caller asking about itself should use.
+ */
+const RULES = {
+  all: "every readable provider is under the threshold",
+  any: "at least one provider is under the threshold",
+};
+
+function overallDecision(providers, rule) {
+  if (!providers.length) return "unknown";
+  const has = (d) => providers.some((p) => p.decision === d);
+
+  if (rule === "any") {
+    if (has("proceed")) return "proceed";
+    return has("unknown") ? "unknown" : "defer";
+  }
+  // A provider known to be blocked outranks one that could not be read: both
+  // stop the work, and "blocked until 14:00" is actionable where "could not
+  // tell" is not.
+  if (has("defer")) return "defer";
+  if (has("unknown")) return "unknown";
+  return "proceed";
+}
+
 /**
  * Turn readings into a decision.
  *
@@ -90,7 +124,7 @@ export const readProvider = readOne;
  * 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 } = {}) {
+export function capacity(results, { threshold = 90, rule = "all" } = {}) {
   const providers = results.map((r) => {
     if (r.status !== "ok") {
       return { provider: r.provider, label: r.label, decision: "unknown", reason: r.status, detail: r.detail };
@@ -140,8 +174,18 @@ export function capacity(results, { threshold = 90 } = {}) {
 
   const cadences = new Set(usable.map((p) => p.binding.windowSeconds ?? "calendar"));
 
+  const decision = overallDecision(providers, rule);
+
   return {
     threshold,
+    // The one answer a caller acts on, carrying the rule that produced it so
+    // that "proceed" can never be read as more than it claims.
+    overall: {
+      decision,
+      rule: rule === "any" ? "any" : "all",
+      ruleText: RULES[rule] ?? RULES.all,
+      scoped: providers.length === 1 ? providers[0].provider : null,
+    },
     providers,
     recommended: recommended
       ? {