agent-runway 0.2.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,31 @@
+{
+  "name": "agent-runway",
+  "description": "Single-plugin marketplace for agent-runway.",
+  "owner": {
+    "name": "jberdah",
+    "url": "https://github.com/jberdah"
+  },
+  "plugins": [
+    {
+      "name": "agent-runway",
+      "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.0",
+      "author": {
+        "name": "jberdah",
+        "url": "https://github.com/jberdah"
+      },
+      "homepage": "https://github.com/jberdah/agent-runway#readme",
+      "repository": "https://github.com/jberdah/agent-runway",
+      "license": "MIT",
+      "category": "productivity",
+      "keywords": [
+        "usage",
+        "quota",
+        "rate-limit",
+        "mcp"
+      ]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,27 @@
+{
+  "name": "agent-runway",
+  "displayName": "Agent Runway",
+  "version": "0.2.0",
+  "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",
+    "url": "https://github.com/jberdah"
+  },
+  "homepage": "https://github.com/jberdah/agent-runway#readme",
+  "repository": "https://github.com/jberdah/agent-runway",
+  "license": "MIT",
+  "keywords": [
+    "usage",
+    "quota",
+    "rate-limit",
+    "mcp"
+  ],
+  "mcpServers": {
+    "agent-runway": {
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/src/mcp.mjs"
+      ]
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jberdah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,376 @@
+# agent-runway
+
+How much runway is left before your coding agent hits a rate limit — which
+windows are consumed, and when each one resets.
+
+Same answer three ways: a **CLI**, a **Claude Code skill**, and an **MCP tool**
+any client can call, so the reasoning happens once instead of in every model.
+
+> **Unofficial.** This reads undocumented Anthropic endpoints. It can stop
+> working without notice and is not a compatibility contract with anyone.
+
+Covers **Claude, Codex, GitHub Copilot, Gemini CLI and Antigravity**, each read
+with the credentials that agent already keeps. One provider failing never costs
+the others their answer.
+
+*Part of the [brainclaw](https://brainclaw.dev) toolkit.*
+
+```
+$ agent-runway
+
+Runway - Claude
+
+  Session (5h)                    [###.................]  15 %
+                                  resets 2026-09-12 02:40Z (in 4h 44m)
+* Weekly - all models             [################....]  79 %  <-- warning
+                                  resets 2026-09-15 03:00Z (in 3d 5h)
+  Weekly - Opus                   [##########..........]  52 %
+                                  resets 2026-09-15 03:00Z (in 3d 5h)
+
+  Extra usage credits: disabled
+
+  * = closest to its limit, as the API flags it
+```
+
+## Why
+
+Claude Code shows this behind `/usage`, interactively. That does not help an
+agent decide whether a long task or a fan-out of subagents will fit in the
+remaining budget, and it does not help a script. This exposes the same numbers
+to the terminal, to a skill, and to any MCP client.
+
+## Install
+
+### Quickest path
+
+```bash
+npm install -g agent-runway
+agent-runway setup
+```
+
+Or without installing anything globally:
+
+```bash
+git clone https://github.com/jberdah/agent-runway && cd agent-runway
+node src/cli.mjs setup
+```
+
+`setup` is one guided pass, identical on Windows, macOS and Linux. It reads a
+token back without echoing it, **validates it against the API before saving
+anything**, then writes it to `~/.claude/usage-token` with mode 0600 and prints
+your current usage. `setup --stdin` takes the token from a pipe instead, so it
+never has to be displayed or pasted.
+
+Most of the tool needs no credential at all: `--models` and `resolve` read local
+binaries. Only quota requires signing in.
+
+Re-running it is safe: it reports that things already work and changes nothing
+unless you pass `--force`.
+
+### As a Claude Code plugin (skill + MCP tool)
+
+```
+/plugin marketplace add jberdah/agent-runway
+/plugin install agent-runway@agent-runway
+```
+
+Claude then reads your usage whenever it is relevant — ask "how much quota do I
+have left?" or let it check before a long task.
+
+### As an MCP server, in any client
+
+No install step: it has no dependencies, so pointing a client at the file is
+enough.
+
+```jsonc
+// Claude Desktop: claude_desktop_config.json
+{
+  "mcpServers": {
+    "agent-runway": {
+      "command": "node",
+      "args": ["/absolute/path/to/agent-runway/src/mcp.mjs"]
+    }
+  }
+}
+```
+
+For Claude Code specifically:
+
+```bash
+claude mcp add agent-runway -- node /absolute/path/to/agent-runway/src/mcp.mjs
+```
+
+### As a CLI
+
+```bash
+npm install -g agent-runway    # or: git clone && npm link
+agent-runway --short
+```
+
+Cloning is enough to run it — `node src/cli.mjs` needs nothing installed.
+
+## Authentication
+
+`agent-runway setup` handles this. What follows is what it does, for anyone who
+would rather do it by hand or automate it.
+
+### Claude has no durable credential today
+
+This is the project's sharpest limitation, and it was found by trying rather
+than by reading docs.
+
+`claude setup-token` mints a long-lived token, and it does **not** work here:
+
+```
+HTTP 403 - OAuth token does not meet scope requirement user:profile
+```
+
+That command grants inference scopes. The usage endpoint wants `user:profile`,
+which it does not issue, so regenerating the token produces the same refusal
+every time. There is no flag to ask for a wider scope.
+
+What does carry `user:profile` is the session credential Claude Code keeps for
+itself, and that is refreshed only while Claude Code is running. So:
+
+| Situation | Claude usage readable |
+| --- | --- |
+| Claude Code in active use | yes |
+| Claude Code idle for hours, or signed out | no |
+| A scheduled job on an otherwise quiet machine | no |
+
+In practice this bites less than it sounds: an agent checking its own runway
+mid-task is running inside Claude Code, so the credential is fresh exactly when
+it is needed. What it does rule out is the unattended case — waking up at a
+reset to see whether the quota came back.
+
+**Codex, Copilot and Antigravity are unaffected.** Each has a durable credential
+of its own, which is part of why this tool covers more than one provider.
+
+Refreshing Claude Code's token ourselves is possible in principle and is
+deliberately not done: the refresh token rotates on use, so a background tool
+racing Claude Code for it could sign the user out of their own editor.
+
+### The one durable path: a session cookie
+
+There are two usage endpoints, and they take different credentials:
+
+| Endpoint | Credential | Verified |
+| --- | --- | --- |
+| `api.anthropic.com/api/oauth/usage` | Bearer OAuth, needs `user:profile` | 200 with Claude Code's session token, 403 with `setup-token` |
+| `claude.ai/api/organizations/{org}/usage` | **cookie only** | 403 to any Bearer: *"This endpoint does not accept OAuth access tokens"* |
+
+So the claude.ai endpoint is not a fallback for the first — it is a different
+door. Give it the `sessionKey` cookie from a signed-in claude.ai browser
+session and it answers, no OAuth scope involved, and it keeps working while
+Claude Code is closed:
+
+```bash
+# the value of the sessionKey cookie, pasted by you
+echo "sk-ant-sid01-..." > "$HOME/.claude/session-cookie"   # or AGENT_RUNWAY_CLAUDE_COOKIE
+```
+
+Weigh it honestly before using it. A session cookie is a **broader credential
+than an OAuth token** — it is the browser's full account session, not a scoped
+grant. It dies when you sign out, and it cannot be narrowed. This tool will
+never read it out of a browser profile: you paste it, or you go without.
+
+### Why a file rather than an environment variable
+
+Setup writes the token to `~/.claude/usage-token` (mode 0600) instead of
+exporting it. On macOS and Linux, a persistent environment variable means
+writing the secret into a shell rc file, which is commonly mode 644 and
+sometimes committed to a dotfiles repository. One 0600 file is safer, behaves
+identically on all three platforms, is picked up by every invocation whatever
+your shell, and is revoked by deleting it.
+
+`agent-runway setup --env` still wires up the variable if you want it. On POSIX
+it appends an indirection rather than a second copy of the secret:
+
+```sh
+export AGENT_RUNWAY_TOKEN="$(cat $HOME/.claude/usage-token 2>/dev/null)"
+```
+
+On Windows it sets a user-level variable, passing the value through stdin so the
+token never appears in a process list.
+
+Environment variables remain the right mechanism in CI, where the secret comes
+from the platform's own secret store.
+
+Sources are tried in this order, first match wins:
+
+| Source | Notes |
+| --- | --- |
+| `CLAUDE_CODE_OAUTH_TOKEN` | a token carrying `user:profile` — note that `claude setup-token` does not mint one |
+| `AGENT_RUNWAY_TOKEN` | if you want a variable scoped to this tool |
+| `ANTHROPIC_AUTH_TOKEN` | already set in many setups |
+| `~/.claude/usage-token` | a file holding the token on one line |
+| `~/.claude/.credentials.json` | Claude Code's own session token |
+
+The last one makes the tool work with no setup at all, but it is a convenience
+rather than a contract: on macOS the live token lives in the Keychain and on
+Windows in the Credential Manager, so that file is often absent or stale. Set
+`AGENT_RUNWAY_NO_LOCAL_CREDENTIALS=1` to skip it entirely.
+
+`CLAUDE_ORG_ID` overrides the organization UUID, which is only needed by the
+claude.ai fallback endpoint.
+
+## Two questions, one tool
+
+Before delegating work, an agent needs both halves of the answer, and getting
+them from two different tools defeats the point:
+
+**How much runway is left, per provider.**
+
+```bash
+agent-runway --all
+```
+
+```
+Claude              Session (5h)   4 %   |  Weekly - all models  87 %
+OpenAI Codex plus   Session        0 %   |  Weekly                0 %
+GitHub Copilot      Chat  200/200 requests | Premium: not included in this plan
+Antigravity Pro     Flow credits 100 %
+```
+
+**Which models each install will actually accept.**
+
+```bash
+agent-runway --models
+```
+
+```
+codex path      0.149.1              4 models  [declared]
+    gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5
+codex vscode    0.154.0-alpha.6.1    5 models  [declared]
+    gpt-6-astra, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5
+
+Disagreements between installs of the same agent:
+  codex path 0.149.1 does not offer: gpt-6-astra
+```
+
+That last line is the point. A machine carries several builds of the same agent
+— five of Claude here — and they do not agree. `gpt-6-astra` is what this
+machine's `config.toml` selects: it runs under the editor extension and does not
+exist for the CLI a delegation would spawn.
+
+Each catalogue says how it was obtained. **declared** means the binary was asked
+and answered, through `codex app-server`'s `model/list` or the Copilot CLI's own
+shell completion. **inferred** means identifiers were read out of the binary,
+which Claude Code requires because it exposes no list: strong evidence, not a
+contract, and occasionally plausible-looking rubbish.
+
+## Before spawning another agent
+
+One call returns everything needed to build a command that works:
+
+```bash
+agent-runway resolve codex --model gpt-6-astra
+```
+
+```jsonc
+{
+  "contract": 1,
+  "binary": "…/OpenAI/Codex/bin/codex.exe",
+  "version": "0.149.1",
+  "models": ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5"],
+  "model": {
+    "requested": "gpt-6-astra",
+    "valid": false,
+    "availableIn": [{ "kind": "vscode", "version": "0.154.0-alpha.6.1", "path": "…" }],
+    "suggestion": "gpt-5.6-sol"
+  }
+}
+```
+
+Exit 1 when the agent cannot be resolved or the slug is refused, so a script can
+branch. The substitute is **offered, never applied**: running a different model
+than was asked for, silently, is worse than failing.
+
+This is meant to compose with tools that already know how to build command
+lines. It deliberately does not spawn anything.
+
+## Deciding, rather than reporting
+
+```bash
+agent-runway --gate 90
+```
+
+Prints JSON and answers in the exit code: **0** proceed, **10** defer, **11**
+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.
+
+## CLI reference
+
+| Flag | Output |
+| --- | --- |
+| *(none)* | Claude only, readable table |
+| `--all` | Every provider found on this machine |
+| `--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 |
+| `--short` | One line: `session=15%  weekly_all=79%  weekly_scoped=52%` |
+| `--json` | Raw response; combines with `--models` |
+| `--plain` | Table without the header |
+
+| Exit code | Meaning |
+| --- | --- |
+| 0 | success |
+| 1 | unexpected error |
+| 2 | no token found |
+| 3 | token rejected — regenerate it |
+| 4 | the usage endpoint is throttling; not your quota |
+
+## Security
+
+- **No token is ever printed, logged or returned**, not even a prefix. A unit
+  test asserts this against every rendered output.
+- The MCP tool returns usage numbers only, never credentials.
+- The tool never runs `claude setup-token` for you, and never reads browser
+  cookies or an OS keychain.
+- Read-only: every request is a `GET`.
+
+## How it works
+
+Two internal endpoints, tried in order, both authenticated with
+`Authorization: Bearer sk-ant-oat01-...` and `anthropic-beta: oauth-2025-04-20`:
+
+1. `https://api.anthropic.com/api/oauth/usage`
+2. `https://claude.ai/api/organizations/{org}/usage`
+
+**These endpoints are internal and undocumented. They can change or disappear
+without notice.** Parsing is written to degrade rather than break: it prefers
+the canonical `limits` array, falls back to scanning top-level window objects,
+and prints raw JSON if it recognises nothing. If the output ever looks wrong,
+`--json` shows exactly what the API returned.
+
+## Development
+
+```bash
+npm install     # dev only: the MCP SDK, used to test the server as a real client
+npm test        # unit tests, no network
+npm run smoke   # drives the MCP server over stdio; needs network and a token
+```
+
+The runtime has **zero dependencies**. `src/mcp.mjs` speaks JSON-RPC directly
+rather than importing the MCP SDK, because a Claude Code plugin installed from
+git is never `npm install`ed — an imported dependency would have to be vendored.
+`scripts/smoke-mcp.mjs` connects the official SDK client to it, so the
+hand-rolled framing is checked against the real implementation.
+
+```
+src/core.mjs     token resolution, HTTP, response normalization
+src/render.mjs   text rendering
+src/cli.mjs      CLI entry point, also what the skill shells out to
+src/setup.mjs    guided cross-platform first-time setup
+src/mcp.mjs      MCP stdio server
+skills/          the Claude Code skill
+.claude-plugin/  plugin and marketplace manifests
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "agent-runway",
+  "version": "0.2.0",
+  "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",
+  "author": "jberdah (https://github.com/jberdah)",
+  "homepage": "https://github.com/jberdah/agent-runway#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jberdah/agent-runway.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jberdah/agent-runway/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "agent-runway": "src/cli.mjs",
+    "agent-runway-mcp": "src/mcp.mjs"
+  },
+  "exports": {
+    ".": "./src/core.mjs"
+  },
+  "files": [
+    "src",
+    "skills",
+    ".claude-plugin",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test \"test/**/*.test.mjs\"",
+    "start": "node src/cli.mjs",
+    "mcp": "node src/mcp.mjs",
+    "smoke": "node scripts/smoke-mcp.mjs",
+    "prepublishOnly": "npm test",
+    "pack:check": "npm pack --dry-run"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "mcp",
+    "usage",
+    "rate-limit",
+    "quota"
+  ],
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0"
+  }
+}

package/skills/agent-runway/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: agent-runway
+description: Answers two questions about the coding agents installed on this machine - how much rate-limit quota each has left, and which model slugs each installed binary will actually accept. Use when the user asks how much usage or quota is left, whether they are near a limit, when a window resets, or which models are available; and before delegating work to another agent, to pick a binary and a model argument that will not be rejected. Covers Claude, Codex, GitHub Copilot, Gemini CLI and Antigravity.
+---
+
+# Agent runway
+
+Two questions, one tool: **is there room to work**, and **what can actually be
+run**.
+
+## Commands
+
+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 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.
+
+If the command is not on PATH, run it from the checkout: `node src/cli.mjs …`.
+
+## Reading a quota answer
+
+- A `*` marks the window **closest to its limit**, which is not the one being
+  consumed right now: a session at 3% in active use goes unmarked while an
+  untouched weekly at 87% carries it. Report it as the constraint, never as
+  "the window you are using".
+- `not included in this plan` means the account has no entitlement to that
+  quota. It is not an exhausted quota, and must never be reported as one.
+- A provider may come back `unreachable` or `no_credentials`. That is
+  information: say the provider could not be read rather than omitting it,
+  because silently showing three of four invites a delegation to the missing
+  one. Antigravity in particular only answers while its IDE is running.
+
+## Reading a model answer
+
+Every catalogue says how it was obtained, and the difference matters:
+
+| Authority | Meaning |
+| --- | --- |
+| `declared` | the binary was asked and answered — trust it |
+| `inferred` | identifiers were read out of the binary — strong evidence, not a contract |
+
+An `inferred` list can contain plausible-looking rubbish, so when a spawn is
+built from one, be ready for it to fail anyway and say so up front.
+
+The same agent usually has several installs — a CLI on PATH, one inside a VS
+Code extension, one inside a desktop app — **and they disagree**. A slug the
+editor accepts may be unknown to the binary a delegation would spawn. Always
+name the install an answer came from.
+
+## Before delegating to another agent
+
+`resolve` is the single call that prevents the common failure:
+
+```bash
+agent-runway resolve codex --model gpt-6-astra --json
+```
+
+It returns the binary to invoke, its version, the slugs it accepts, and for a
+requested model: whether it is valid, which other installs would accept it, and
+a suggested substitute. Exit 1 when the agent cannot be resolved or the slug is
+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.
+
+## Rules
+
+- Never print, log or copy a credential, not even a prefix. The tool never
+  emits one; do not work around that with `cat`, `echo` or a grep over
+  credential files.
+- Never run `claude setup-token`, `codex login` or `gh auth login` on the
+  user's behalf. They open a browser and print account secrets; the user runs
+  them.
+- Do not poll. Readings are cached for 60 seconds and the endpoints rate-limit
+  reads; a 429 there is the endpoint throttling, not the account quota.
+- Exit 3 means a token was rejected. If the message mentions a scope, the token
+  is valid but minted for another purpose and regenerating it will not help.
+
+## Caveat
+
+Quota comes from endpoints that are internal and undocumented, so the shape can
+change without notice. Model lists come from each binary, which is more stable
+but version-specific. When something looks wrong, `--json` shows exactly what
+was read.

package/src/cache.mjs

@@ -0,0 +1,90 @@
+// A short-lived read cache, so repeated questions cost one request.
+//
+// The usage endpoints rate-limit reads: eight probes in quick succession during
+// development were enough to earn a 429, and a 429 on a usage endpoint is
+// especially confusing because it looks like the account quota it is meant to
+// report on.
+//
+// Comparable tools sidestep this entirely by never calling an API — they read
+// the rate_limits block Claude Code already hands a statusline on stdin. That
+// source is free but only exists inside a statusline invocation, so an
+// on-demand or multi-provider read still has to make a request, and still has
+// to be careful with it.
+//
+// Two defences here: serve a recent answer instead of asking again, and when a
+// provider does fail, fall back to the last good answer marked stale rather
+// than reporting nothing. Stale numbers about a five-hour window are far more
+// useful than silence.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const DEFAULT_TTL_MS = 60_000;
+
+// Beyond this, a reading is not stale, it is wrong: a five-hour window has
+// turned over several times and a weekly one has moved on. Serving it as a
+// fallback would be worse than admitting the provider could not be reached.
+// The same bound, and the same reasoning, as cclimits (STALE_CACHE_MAX_AGE).
+const STALE_MAX_MS = 24 * 60 * 60 * 1000;
+
+// Overridable so a test suite never writes fabricated readings into the cache a
+// real run would then serve as genuine.
+const dir = () => process.env.AGENT_RUNWAY_CACHE_DIR || path.join(os.tmpdir(), "agent-runway-cache");
+const fileFor = (key) => path.join(dir(), `${key.replace(/[^a-z0-9_-]/gi, "_")}.json`);
+
+/** How long a cached answer stays fresh. 0 disables the cache entirely. */
+export function ttlMs(env = process.env) {
+  const raw = env.AGENT_RUNWAY_CACHE_MS;
+  if (raw === undefined) return DEFAULT_TTL_MS;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_TTL_MS;
+}
+
+/**
+ * @returns {{value: any, ageMs: number, fresh: boolean}|null}
+ */
+export function read(key, maxAgeMs = DEFAULT_TTL_MS, maxStaleMs = STALE_MAX_MS) {
+  try {
+    const { at, value } = JSON.parse(fs.readFileSync(fileFor(key), "utf8"));
+    const ageMs = Date.now() - at;
+    if (!Number.isFinite(ageMs) || ageMs < 0) return null;
+    // Quota readings expire with time. Anything derived from a binary does not:
+    // it changes when the file changes, which the key already encodes, so those
+    // callers pass Infinity rather than a duration.
+    if (ageMs > maxStaleMs) return null;
+    return { value, ageMs, fresh: maxAgeMs > 0 && ageMs <= maxAgeMs };
+  } catch {
+    return null; // absent or unreadable is simply a miss
+  }
+}
+
+export function write(key, value) {
+  try {
+    fs.mkdirSync(dir(), { recursive: true });
+    fs.writeFileSync(fileFor(key), JSON.stringify({ at: Date.now(), value }), "utf8");
+  } catch {
+    // A cache that cannot be written must never break the read it was helping.
+  }
+}
+
+export function clear(key) {
+  try {
+    fs.rmSync(key ? fileFor(key) : dir(), { recursive: true, force: true });
+  } catch {
+    /* nothing to clear */
+  }
+}
+
+/**
+ * Seconds a 429 asks us to wait, when the server says so.
+ * Retry-After is either a delay in seconds or an HTTP date.
+ */
+export function retryAfterSeconds(headers) {
+  const raw = headers?.get?.("retry-after");
+  if (!raw) return null;
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds)) return Math.max(0, Math.round(seconds));
+  const when = Date.parse(raw);
+  return Number.isFinite(when) ? Math.max(0, Math.round((when - Date.now()) / 1000)) : null;
+}