foldrun 15.0.0 → 16.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/bin/foldrun.mjs CHANGED
@@ -42,6 +42,7 @@
42
42
  // foldrun eval compare <eval> its cases under two to four models, side by side
43
43
  // foldrun proposals proposed fixes for repeated failures — show, apply, dismiss
44
44
  // foldrun eval grades <eval> what a grader found in the real runs it graded — eval grade <eval> --run <id> grades one
45
+ // foldrun eval trends evals by change: each eval against its last run on a different commit
45
46
  // foldrun agent run <name> run one agent once on a platform, no flow
46
47
  // foldrun tool test <name> exercise one tool alone — no model, no run
47
48
  // foldrun hook <verb> ls / add / test / rm — your own code at every tool call and step
@@ -158,10 +159,12 @@ const HELP = `foldrun — agents are just folders
158
159
  foldrun proposals --to <ws> proposed fixes (--status ready, --eval) — show|apply|dismiss <id> (apply asks; --yes)
159
160
  foldrun eval grades <eval> --to <ws> a grader's findings (trigger: runs): pass rate over --days (30), each graded run (--status fail, --limit); exit 1 on a failure
160
161
  foldrun eval grade <eval> --run <id> --to <ws> grade one finished run now, sampled or not; exit 1 unless it passed
162
+ foldrun eval trends --to <ws> evals by change, as the Observe page: each eval now against its last run on a different commit, biggest drop first (--json); exit 1 when a change made one worse
161
163
  foldrun promote <run-id> keep a finished run as a regression case in evals/ (--eval <name>, --expect "contains: …" repeatable, --case <name>); a run that went wrong takes --should "what it should have done"
162
164
  foldrun probe <model> live check: can this model hold a tool loop here?
163
165
  foldrun logs [run-id] recent runs in one workspace, or one run's full event trail (--local: this machine's)
164
- foldrun runs what has run lately, across the account — --status, --verdict, --outcome (good, done, quiet, blocked, bad, failed, needs-you, …), --since, --to, --flow <name>, --q <words>, --limit; search with --tool, --tool-error, --agent, --model, --min-tokens 50k, --min-secs, or --view <name>
166
+ foldrun runs what has run lately, across the account — --status, --verdict, --outcome (good, done, quiet, blocked, bad, failed, needs-you, …), --since, --to, --flow <name>, --q <words>, --limit; search with --tool, --tool-error, --agent, --model, --min-tokens 50k, --min-secs, or --view <name>; --limit is one page: --page <n>, --before <cursor> (printed when more match), --all, --json
167
+ foldrun runs outputs <run-id> which files the run archived from its agents' outputs/, with their sizes (--to, --json); report <run-id> get downloads one
165
168
  foldrun runs views your saved run searches (--local prints exactly what logs --local prints)
166
169
  foldrun runs views save <name> [filters] save the runs filters given (--status, --flow, --to, --since, --q, --tool, --tool-error, --agent, --model, --min-tokens, --min-secs) as a view; a name taken is replaced
167
170
  foldrun runs views rm <name> delete a saved view (asks; --yes)
@@ -197,10 +200,11 @@ const HELP = `foldrun — agents are just folders
197
200
  foldrun rerun <run-id> run it again from a step (--from <n>) or from an agent's step (--agent <name>); --instruction "…" tells that step something else this once; --wait
198
201
  foldrun rerun --status failed [--since 24h] [--until 2h] [--flow f] rerun every run a filter matches, from --from <n> (default 1) — lists, asks (--dry-run, --to)
199
202
  foldrun rerun <run-id> <run-id>… rerun several (runs/bulk), from --from <n> (default 1) — lists, asks once (--dry-run, --yes)
200
- foldrun observe where the account fails, retries and spends, per workspace (--to <workspace> in full, --since <days>, --json)
203
+ foldrun observe where the account fails, retries and spends, per workspace, then the window against the one before, why runs went wrong, the agents and tools to watch (--to <workspace> in full, --since <days>, --json)
201
204
  foldrun usage what the account consumed, and what it was charged week by week (--days <n>, --json)
202
205
  foldrun usage --limit <n> how many rows of by flow and by agent (the most charged; default 10, 0 hides them)
203
206
  foldrun usage compute cores, GiB and disk its running steps may hold — the account, each workspace, each live run — what they hold now, and the steps waiting for room (--json)
207
+ foldrun usage budget spend against each cap — the account's and each workspace's budget:, what is spent in its window (today, this week, this month) and how close it is (--to <workspace> for one, --json)
204
208
  foldrun schedule every flow that fires on a clock, its cron line and the next times (--to <workspace>)
205
209
  foldrun schedule tick fire whatever is due now — Settings' "Run scheduler now"
206
210
  foldrun guide write the coding-agent rules: a block in AGENTS.md and CLAUDE.md importing it (--check, --print)
@@ -211,6 +215,7 @@ const HELP = `foldrun — agents are just folders
211
215
  foldrun runtimes the environments a deployed workspace's agents need (python, pip and npm packages) and whether each is built — failed ones with the installer's error (--wait holds on while any is building)
212
216
  foldrun billing the account's balance and its recent ledger entries (--limit <n>)
213
217
  foldrun billing statement [YYYY-MM] a month of the ledger (--csv for the file, --file <path> to save it)
218
+ foldrun billing invoices the plan's tax invoices from Stripe (number, date, amount, status, link) and every credit purchase with its receipt (--json)
214
219
  foldrun billing wallet burn, runway, auto top-up — also set auto-top-up --threshold <usd> --amount <usd> | off, set email <address>
215
220
  foldrun billing wallet clear email no receipt or low-balance email (set auto-top-up off keeps the threshold and refill for next time)
216
221
  foldrun billing details who invoices are made out to — also set --name "…" --abn … --address "line1, city, state, postcode, AU" --email …
@@ -324,7 +329,7 @@ Options
324
329
  --since <span> audit: entries from 24h, 7d, 30d ago, or a date (default 7d); --until <date> ends the window
325
330
  --action <a> audit: one action (apikey.created) or a family (apikey, secret, member, support)
326
331
  --actor <who> audit: one person or key — an email, key:<label>, support:<email>
327
- --since <days> observe, triggers: the window in days (observe default 30, triggers 7)
332
+ --since <days> observe, triggers: the window in days (observe default 7 as the account Observe page, observe --to 30 as a workspace's; triggers 7); observe takes --days too
328
333
  --until <span|date> stop, rerun (bulk): only runs started before then — 2h ago, or a date
329
334
  --verdict <v> runs: only completed runs whose summary leads with it — good, bad, quiet, blocked (comma-separated)
330
335
  --q <words> runs: the runs page's text search — every word, any order, across id, flow, workspace, status, verdict, summary and failure; assistant history: search the conversations
@@ -383,7 +388,7 @@ Options
383
388
  --name / --abn / --address / --email billing details set: the invoice's legal name, ABN, "line1, city, state, postcode, AU", receipt email
384
389
  --clear-address / --clear-email / --clear-abn billing details set: drop that one from the invoice details, the rest kept
385
390
  --clear-name / --clear-description / --clear-examples a2a publish, a2a unpublish: drop that one from the card, the rest of a2a: kept
386
- --days <n> usage: the window the charges cover (default 56); status --platform --history: 1-90 (default 90)
391
+ --days <n> usage: the window the charges cover (default 56); status --platform --history: 1-90 (default 90); observe: the same as --since
387
392
  --id <revision> history: one revision in full, as diffs
388
393
  --engine <e> login: (with a site) the browser to sign in with — chrome (default: real Google Chrome, Chromium when it is not installed), chromium, firefox or safari
389
394
  --new-client connect: enter a new OAuth client even when one is saved for the secret
@@ -396,15 +401,17 @@ Options
396
401
  --reason "<text>" account pause, workspace pause: why — shown to everyone who opens it
397
402
  --stop account pause, workspace pause: also stop every run going now (asks; --yes to mean it)
398
403
  --yes approve, stop, rerun (bulk), pause --stop, flow rotate-hook, flow draft, assistant, history restore, restore <ws>, import, billing plan, workspace set name, team remove, and every rm/revoke/unshare: skip the confirmation, deliberately (required with no terminal)
399
- --json report: the raw run record instead of the report; observe, usage, api version, changelog, find, preferences, workspace vocabulary, flags, workspaces, workspaces show, agent ls, flow ls, agent import --list, backups requests, team, hook ls, secrets ls, triggers, storage ls --all: the raw document; version: {cli, core, platform}
404
+ --json report: the raw run record instead of the report; runs: { runs, next }; runs outputs: { runId, files, totalBytes }; observe, usage, api version, changelog, find, preferences, workspace vocabulary, flags, workspaces, workspaces show, agent ls, flow ls, agent import --list, backups requests, team, hook ls, secrets ls, triggers, storage ls --all: the raw document; version: {cli, core, platform}
400
405
  --events <a,b> account set notify: failed, awaiting-approval, completed
401
406
  --failed webhooks deliveries: only the ones that gave up
402
407
  --limit <n> runs, billing, history, changelog: how many rows; triggers: how many decisions and deliveries (default 10)
408
+ --page <n> runs: the nth page of --limit, newest first
409
+ --before <cursor> runs: the page after the cursor the last page printed (a time or a run id works too)
403
410
  --limit <n> usage: rows of by flow and by agent, the most charged first (default 10; 0 hides them)
404
411
  --value "<text>" secrets set: skip the prompt (careful with shell history)
405
412
  --site <domain> secrets set, secrets sites: a site the secret is bound to — the egress proxy fills it for those alone (repeatable, or a,b)
406
413
  --clear secrets sites: unbind it; flow compute: no cap of its own; me name: no name
407
- --all secrets workspaces: every workspace may use the account secret again; storage ls: every workspace's storage; storage shares: expired and revoked links too; mcp connections: the disconnected ones too; team invite, team access: every workspace
414
+ --all runs: every run that matches, every page; secrets workspaces: every workspace may use the account secret again; storage ls: every workspace's storage; storage shares: expired and revoked links too; mcp connections: the disconnected ones too; team invite, team access: every workspace
408
415
  --none secrets workspaces, secrets set: no workspace may use the account secret; team access: no workspaces
409
416
  --if-workspaces <a,b|all|none> secrets workspaces: change it only while the list is still this one (refused, 409, when someone changed it since)
410
417
  --if-version <n> account model use: change it only while the choice is still that choiceVersion (account model --json; 0: never chosen)
package/docs/api.md CHANGED
@@ -206,6 +206,7 @@ history with each message.
206
206
  | `/api/workspaces/<ws>/export` | GET | this workspace, one flow or one agent as a `.zip` — `?kind=flow&name=<flow>` (the flow, every flow it runs as a step, every agent those steps and their colleagues name, and the workspace tools, skills and scripts they grant), `?kind=agent&name=<agent>` (its folder and what it grants), or neither for the whole authored tree. Never memory/, state/, outputs/, storage, runs or a secret's value; `foldrun-package.json` inside says what it is. Any role that can read the workspace |
207
207
  | `/api/workspaces/<ws>/import` | POST | take a package in; the body is the `.zip` (`content-type: application/zip`, at most 20 MB). `?dryRun=1` answers `{ kind, name, from, creates, added, overwritten, unchanged, needs: { secrets, tools, skills, scripts, agents, flows } }` plus `skipped` (entries it will not write: memory, state, anything outside the authored folders) and writes nothing. Without it, applies as one revision; 409 when it would replace a file with different text unless `?overwrite=1`, or when a file cannot be written there (all or nothing). Never deletes. A `Content-Length` is required (411 without). A workspace package into a name that does not exist makes that workspace (`workspace:manage`, the plan's workspace count). 400 for anything not a package, or one holding memory/, state/ or outputs/. A change to a policy key of the workspace's `AGENTS.md` (`budget`, `compute`, `notify`, `network_enforce`, `telemetry`, `alerts`, `owner`, `judge`, `timezone`) needs `workspace:manage` — `403` naming the key, nothing written ([Team and access](team-and-access#a-workspaces-policy-is-an-admins)). Idempotent |
208
208
  | `/api/workspaces/<ws>/evals` | GET, POST | list; create (`name`) |
209
+ | `/api/workspaces/<ws>/evals/trends` | GET | evals by change, the workspace Observe page's table: `{ workspace, trends: [{ eval, latest, previous, delta }] }`, biggest drop first. `latest` is the eval's newest run and `previous` the most recent run on a DIFFERENT commit (`null` when every run so far was on one) — each `{ eval, at, commit, passed, failed, costUsd }`, `commit` a git sha or a revision id (`r-…`), `null` when no change is on record; `delta` is passed now minus passed then, `null` without a previous. Not windowed: two runs on one commit differ only by the model, so the comparison is always against another commit |
209
210
  | `/api/workspaces/<ws>/evals/<eval>/run` | GET, POST | POST runs one eval and answers with its result; with `{ async: true }` it answers `202 { started, eval, runId, startedAt }` at once and the eval runs on — an eval of slow cases outlives a proxy's read timeout (Cloudflare's is 125 s by default). One run of an eval at a time: a second is `409` naming the run that holds it. `GET ?run=<runId>` is what to poll — that run alone, whatever else runs or writes the eval's latest result meanwhile: `{ runId, state, running }` where `state` is `running`, `done` (with its `result`), `failed` (with `error`), `lost` (it stopped reporting before saving a result, e.g. a restart) or `unavailable` (an id not on record — the last 20 runs are kept). Plain `GET` answers who holds the eval now (`running`, `runId`, `startedAt`) and the latest `result`. The dashboard and `foldrun eval --to` start async and poll by run id |
210
211
  | `/api/workspaces/<ws>/evals/<eval>/compare` | GET, POST | compare models on one eval: its cases under two to four settings, side by side. `POST { configs: [{ model, effort?, agent? }], repeat?, maxUsd? }` — `model` a tier (`fast`, `default`, `max`) or a model id; `effort` low…max; `agent` (flow evals) forces only that agent's steps, else every step; `repeat` 1–5 (1); `maxUsd` the spend limit, above 0 and at most 100 (5). At most 60 runs (cases × settings × repeat, else `413`). Answers `202 { started, eval, runId, startedAt, trials, maxUsd }` and runs on: every run a test run, the eval's own judge for all. `GET ?run=<runId>` → `{ runId, state, running }` — `running` (with `progress: { done, total }`), `done` (with `result`), `failed` (with `error`), `lost` or `unavailable`. `result` is `{ eval, target, judge, startedAt, finishedAt, repeat, maxUsd, spentUsd, stopped, configs: [{ model, effort, agent, label, trials, passed, notRun, rate, costUsd (runs and judges), judgeCostUsd, avgCostUsd, avgSecs (worker pick-up to end), runIds }], cases: [{ case, passed: [per setting], trials: [per setting] }] }`. Plain `GET` → `{ running, runId?, startedAt?, progress?, comparisons }` (the last 20, newest first). One comparison of an eval at a time (`409`), none while the account or workspace is paused (`409`); a grader, saved inputs or an eval with a `run:` check `400`. Needs `run:start` to start |
211
212
  | `/api/workspaces/<ws>/evals/<eval>/improve` | POST | ask for a proposed fix now: for a grader, from its failed grades no proposal has covered; for an eval that runs cases, from its last result's failed cases. Answers `202` with the proposal, `status: "drafting"` — the assistant drafts it (one reply, paid as Ask AI's are); poll `GET …/proposals/<id>`. `409` when there is nothing to fix, a proposal for this eval is open, or the account or workspace is paused. Held to Ask AI's limits — the same per-person hourly count (`429`), and on the platform's models its daily account count (`429`) and the balance (`402`). Needs `run:start` |
@@ -222,7 +223,7 @@ paying for the steps around it.
222
223
 
223
224
  | Route | Methods | |
224
225
  |---|---|---|
225
- | `/api/workspaces/<ws>/runs?limit=` | GET | `{ runs: [{ id, flow, status, verdict, outcome, startedAt, finishedAt, ... }] }`; search (see [Runs](runs#searching-runs)) with `tool` (a step called a tool whose name contains it), `tool_error=1`, `agent`, `model` (contains), `min_tokens` (`50k`), `min_secs` — `limit` counts the matches — `verdict` is the word the summary leads with (`GOOD`, `QUIET`, `BLOCKED`, `BAD` or null) and `outcome` the one word every page shows (`running`, `queued`, `waiting`, `good`, `done`, `quiet`, `blocked`, `bad`, `failed`, `stopped`); `failure` is `{ agent, reason }` for a run that failed (null otherwise), `chargedUsd` is what the account was charged for the run (one credit is one cent), null until the ledger settles it, while `costUsd` is the provider's token cost — off the run index (see [Runs](runs#the-runs-list)); a finished run's steps carry `agent`, `status`, `costUsd` and `tokens` (`{ input, output, cacheRead, cacheWrite }`, see [Runs](runs#the-record)), and the run its summed `tokens` — not their reply or trace |
226
+ | `/api/workspaces/<ws>/runs?limit=&before=` | GET | `{ runs: [{ id, flow, status, verdict, outcome, startedAt, finishedAt, ... }], next }`, newest first; `next` is the cursor for the page after (`<startedAt>~<runId>`, null on the last page) — pass it back as `before`, which also takes a time (runs that started before it) or a run id of the workspace (runs older than it); a position, not an offset, so runs starting meanwhile shift nothing and one cursor pages every workspace (`foldrun runs --before`, `--page`, `--all`); a `before` that is none of these is a `400`; search (see [Runs](runs#searching-runs)) with `tool` (a step called a tool whose name contains it), `tool_error=1`, `agent`, `model` (contains), `min_tokens` (`50k`), `min_secs` — `limit` counts the matches — `verdict` is the word the summary leads with (`GOOD`, `QUIET`, `BLOCKED`, `BAD` or null) and `outcome` the one word every page shows (`running`, `queued`, `waiting`, `good`, `done`, `quiet`, `blocked`, `bad`, `failed`, `stopped`); `failure` is `{ agent, reason }` for a run that failed (null otherwise), `chargedUsd` is what the account was charged for the run (one credit is one cent), null until the ledger settles it, while `costUsd` is the provider's token cost — off the run index (see [Runs](runs#the-runs-list)); a finished run's steps carry `agent`, `status`, `costUsd` and `tokens` (`{ input, output, cacheRead, cacheWrite }`, see [Runs](runs#the-record)), and the run its summed `tokens` — not their reply or trace |
226
227
  | `/api/workspaces/<ws>/runs/<id>/calls/<call>` | GET | one tool call's recorded content (see [Runs](runs#what-a-run-records)): `{ call: { id, tool, input, output, inputChars, outputChars, truncated, inputCut, outputCut } }` — what it was given and what it gave back, secrets masked, each at most 65,536 characters; `inputChars`/`outputChars` are the whole length, `inputCut`/`outputCut` say which part was cut (`truncated`: either). `<call>` is the tool event's `call`; an event with `captured: true` has content here. 404 when nothing was recorded: the workspace says `capture: metadata`, or the run is from before 19 Oct 2026. A run's steps also carry `calls`, each model call (`n`, `at`, `ms`, `model`, `stop`, `tokens`, `tools`, and `subagent` / `attempt` when a sub-agent or a later attempt made it); a step that handed jobs to `sandbox: own` sub-agents carries `delegations` (`id`, `agent`, `status`, `costUsd`, `ms`), and each job is a step of its own with `subagentOf` (the delegating agent), `delegation` (that `id`) and `wrote` (the workspace paths it changed — copied into the delegating step's sandbox too, up to 4 MiB a job); and the run its `revision` (the workspace's latest revision when a worker picked it up — a deploy's commit, or the id an edit through `/source` was saved as) and `drivenAt` (when that was) |
227
228
  | `/api/workspaces/<ws>/runs/<id>/trace` | GET | the run as one tree (see [Runs](runs#the-trace-tree)): `{ tree, failure }`. Each span is `{ id, kind, label, start, end, status, children, … }`, where `kind` is `run`, `step`, `model` (one model call: `model`, `stop`, `tokens`), `tool` (`call`, `captured` when its input and output were recorded) or `error` (`text`); `start`/`end` are epoch milliseconds and `status` is `ok`, `error`, `running`, `waiting`, `skipped` or `pending`. A tool call sits under the model call that asked for it. `failure` is the ids from the root to the first thing that went wrong, which the run page opens on; `[]` when nothing did |
228
229
  | `/api/workspaces/<ws>/runs/<id>/compare?with=` | GET | this run beside another of the same flow (see [Runs](runs#compare-with-the-last-good-run)): `{ comparison: { base, run, revisionChanged, changedFiles, steps }, chosen }`. Each step is `{ step, agent, base, run, changes }`: both sides' status, instruction, model, seconds, tokens, model calls, tool counts, tool errors, first errors and first line said, and `changes` in words (`status: completed → failed`, `new error: …`, `instruction changed`, `tools: +web ×3`, `took 12s → 48s`, …). `changedFiles` lists the files changed between the revisions the two ran (null when one is unknown). `with` names the other run; unasked it is the newest earlier run of the flow that finished well, else the run this one re-ran (`chosen` says which) |
@@ -234,6 +235,7 @@ paying for the steps around it.
234
235
  | `/api/workspaces/<ws>/runs/<id>/approve` | POST | release a run parked on a human: `decision` (`approve` or `reject` — anything else is a 400 that decides nothing; left out only beside `payload`), `note`, `reason`, `step` (one of several waiting, its index from 0). `payload` (a string, or JSON sent as its text, up to 20000 characters) releases a step parked on `wait: event` with that payload, as its event URL would, recorded as released by the caller — 400 with `reject` or when no such step is waiting. `run:start`. Idempotent |
235
236
  | `/api/workspaces/<ws>/runs/<id>/answer` | POST | answer a question an agent asked mid-step (`tools: [ask]`): `{question: <id>, answer}`. The agent is waiting in a live sandbox and gets it within a second or two. First answer wins — a second is `409` with the answer that stands; also `409` when the agent stopped waiting (its ask timed out) or its step is no longer running. `404` when the question is not this run's or has expired |
236
237
  | `/api/workspaces/<ws>/runs/<id>/message` | POST | say something to a running agent: `{text, step?}` (at most 4 000 characters). It reaches the model after its next tool call, as context — it never changes the step's tools. `step` is the step's index in the run; left out, the only running step. With several running (a parallel group) and no `step`, `400` listing them in `running`, so a sibling never takes a message meant for another. `409` unless the run, and that step, are running. Replies `{ok, step, message}` |
238
+ | `/api/workspaces/<ws>/runs/<id>/files` | GET | which files the run archived from its agents' `outputs/` — what the run page's Out column lists: `{ runId, files: [{ agent, path, bytes, href }], totalBytes }`, by agent then path (`[]` when it archived none); `href` is the `/archive` link that serves one (`foldrun runs outputs <id>` lists them, `foldrun report <id> get <agent>/<path>` downloads one). Per agent, not per step: an agent that ran two steps shows its files once. `404` for no such run |
237
239
  | `/api/workspaces/<ws>/runs/<id>/archive` | GET | one file the run archived from an agent's `outputs/` — `agent` and `path` name it; the run page's Out column links here, and plays a recording or shows a picture inline. Served as bytes, never as a page; a `Range` header gets `206` with that slice, which is how a video seeks |
238
240
  | `/api/workspaces/<ws>/runs/<id>/live` | GET | the live view: with no query, `{ agents: { <agent>: <last frame at> } }`; with `agent=`, the newest frame that agent's browser streamed as `image/jpeg` (or `204` when there is none), and `x-live-url`, `x-live-at`, `x-live-ended`, `x-live-engine` headers. Frames arrive from `web action=browse` through the step's egress lease and expire five minutes after the last |
239
241
  | `/api/workspaces/<ws>/runs/<id>/promote` | POST | save a finished run as a regression case in `evals/<target>-regressions.md` — `evalName` to pick the file, `caseName` to name the case, `expect` (assertion lines, e.g. `["contains: $34"]`) to replace the default judge. A run that went wrong (failed, BLOCKED or BAD) needs `should` — what it should have done, the judge's claim for the case — or `expect`: its own answer is not the one to keep. Returns `{ ok, file, created, caseName }` |
@@ -372,11 +374,13 @@ Reads return which secrets exist, never their values.
372
374
  | `/api/team/members/<id>` | PATCH, DELETE | change a member's role (`role`) and/or which workspaces they may open (`workspaces`: names, or null for all); remove them. A session, or the person's own `foldrun login` key (acting as at most admin). Removing someone revokes the keys and pending invites they made and any invite still pending to their address; a lower role or fewer workspaces revokes the keys and invites that reach beyond their new standing. `404` for an id that is not a member, whatever the body |
373
375
  | `/api/team/transfer` | POST | hand the account to a member (`to`) — owner only, signed in, and re-proving it is them: `password` (the current one) and, when two-step sign-in is on, `code` (from the app, or a backup code). 400 without them, 401 when wrong, 6 tries in 15 minutes. You become an admin |
374
376
  | `/api/usage/compute` | GET | the account's compute at every level (27 Oct 2026): `compute` is `{ vcpu, memGiB, diskGiB, stepVcpu, stepMemGiB, stepDiskGiB, source }` — the cores, GiB and GiB of disk all its running steps may hold together, the most one step may hold (each `null` for no cap), and where the pool came from (`plan`, `account` — its own `compute:` in AGENTS.md, which can only lower it — `install`, or `null`); `inUse` is `{ vcpu, memGiB, diskGiB, steps }`, what its running steps' sandboxes hold now, from their records (a step still waiting for room holds nothing; a caller scoped to some workspaces sees theirs); `workspaces` is each workspace's own `pool` (its AGENTS.md `compute:`, `null` figures for none) and `inUse`; `runs` is each live run with a pool of its own (its flow's `compute:`) or anything held, `{ workspace, runId, flow, pool, inUse }`; `waiting` lists the steps waiting for room, oldest first — `{ workspace, runId, flow, step, agent, since, why, cpus, memGiB, diskGiB, level?, runPool }`, `since` being when it first found none, its place in line, and `level` the cap that held it when it last looked. A step past any level waits, with no time limit, and starts in turn; one bigger than a level's whole cap or the step maximum fails at once ([four levels](budgets-and-billing#compute-at-four-levels), [waiting for room](budgets-and-billing#waiting-for-room)) |
377
+ | `/api/usage/budget` | GET | spend against the caps, as the Spend limits page shows it (5 Nov 2026): `account` is the account's own `budget:` — `{ budget, label, spentUsd, window }`, `budget` being `{ usd, period }` or `null` for no limit, `label` `"$60/day"` or `null`, `spentUsd` what every workspace together has spent in the cap's window (the month's with no cap) and `window` `today`, `this week` or `this month`; `workspaces` is each workspace's the same way with its name as `workspace`, most spent first. A caller scoped to some workspaces sees those, and gets `account: null` with `accountHidden: true` — the account's figure is spend over every workspace. At the cap new runs are refused until the window turns ([four caps](budgets-and-billing#four-caps)) |
375
378
  | `/api/usage/history?days=` | GET | charged spend by flow, by agent and by workspace over time, read from the ledger rather than the run records — so it survives runs being pruned and reports what was billed rather than what was consumed. Buckets by week over three weeks, by day under. Each series carries its periods, its total, and the change between the last two COMPLETE periods, so a partial week never reads as a collapse. `unattributedUsd` is charges from before a line recorded its flow. A caller scoped to some workspaces sees only the charges in those; `days` 1–365, default 56 |
376
379
  | `/api/account/model` | GET, PUT, DELETE | what every step runs on unless an agent, workspace or the account's AGENTS.md names a `provider:` — the account's own model key, or foldrun's models (the platform's keys for one provider, billed in credits at foldrun's price list; hosted only). GET: `{ set, provider, baseUrl, format, keyHint, runsOn, platformKeyAllowed, source, supply, choiceVersion, foldrunModels }` — never a key, only its last four characters; `runsOn` is `account` (its own key), `foldrun` (foldrun's models for `supply`), `platform` (the platform's credential, for the operator's accounts) or `none` (runs are refused until a key is set); `foldrunModels` is `{ offered, refused, providers: [{ name, title, available, reason, tiers }], prices: [{ provider, model, inputPerMTok, outputPerMTok, cacheReadPerMTok, cacheWritePerMTok }], dailyCapUsd, spentTodayUsd }`, the money in what the account pays. PUT `{ source: "foldrun", supply, ifVersion? }` chooses foldrun's models (`supply`: anthropic, openai, gemini, deepseek or moonshot; a provider the platform cannot serve now, or an account refused them, is a 409; a stale `ifVersion` is a 409); `{ source: "own" }` goes back to the account's own key; a key alone never changes the choice; audited as model.source_set. PUT `{ provider, apiKey, baseUrl?, format? }` (needs `secrets:write`, as does the choice): `provider` is a preset name (anthropic, openrouter, openai, groq, … — see providers) or `custom` with an https `baseUrl` and a `format` (anthropic or openai); a Claude login token (sk-ant-oat…) is refused for any account not allowed the platform's credential. Stored as the account secrets `FOLDRUN_MODEL_PROVIDER`, `FOLDRUN_MODEL_API_KEY`, `FOLDRUN_MODEL_BASE_URL`, `FOLDRUN_MODEL_FORMAT`. DELETE removes them (the choice stays). Honours Idempotency-Key on PUT; audited as model.key_set / model.key_removed |
377
380
  | `/api/account/providers` | GET, POST | GET: the model providers this account's files actually use — each one's preset name, where it is declared, the model a check would send — plus the last daily health check. POST forces one now, which spends one minimal request at each distinct endpoint, and needs the permission that runs and every workspace. A member or key scoped to some workspaces sees the account's provider blocks and its own workspaces' only, in `configured` and in the last check |
378
381
  | `/api/usage` | GET | what has been spent, by meter; each bucket's tokens are `inputTokens` (all input), `outputTokens`, `cacheReadTokens` and `cacheWriteTokens` (the part of the input the prompt cache served and stored), and `cacheHitRate` — reads over `measuredInputTokens`, the input of steps that report the split, `null` when none do. A key or member scoped to some workspaces sees those workspaces, and totals over them; `ledger` is the account's `balanceUsd` and `chargedUsd` (all time), and `waived` the legs the account is not charged for — both `null` to a caller scoped to some workspaces, since they are the whole account's money. Since API version `2026-10-26` nothing else; earlier pins see `providerCostUsd` and `marginUsd` as `null` |
379
382
  | `/api/approvals` | GET | every gate waiting on a person, across workspaces — one entry per waiting **step** (`workspace`, `runId`, `flow`, `step`, `agent`, `question`, `asked`, `waitingSince`), oldest first. By step status, not run status: a decided gate leaves the list at once, before the worker resumes the run. `wait: event` steps are not listed; no button answers them. Beside it, `questions`: every question an agent is asking mid-step in a running run (`kind: "question"`, `id`, `workspace`, `runId`, `flow`, `agent`, `question`, `options?`, `askedAt`) — answered with `…/runs/<id>/answer` |
383
+ | `/api/observe?days=` | GET | the account Observe page's analysis, the same function the page renders from: `{ days, timezone, window: { from, to }, previous: { from, to, runs }, kpis, causes, desks, agents, tools, daily }`. `kpis` is the window against the one of the same length before it — `{ runs, finished, succeeded, rate, prevRate, failed, platformFailures, deskFailures, spendUsd, prevSpendUsd, medianSecs }` (`rate` is completed ÷ (completed + failed), `null` with none finished; money is what was charged); `causes` why runs went wrong, the platform's first — `{ kind (platform, verify, timeout, error, blocked, bad, stopped), key, label, platform, count, desks, sample, newest }`; `desks` every workspace worst first — `{ workspace, runs, rate, prevRate, deskFailures, platformFailures, spendUsd, medianSecs, worst: { what, count }, lastBad }`; `agents` the agents to watch (most failures, then retries, then charged; 10 at most) — `{ workspace, agent, steps, failed, retried, costUsd, chargedUsd, seconds }`; `tools` merged across workspaces — `{ name, calls, errors, workspaces, p95ms }`; `daily` one bucket per day in `timezone`, a week at least — `{ day, good, attention, failed, platform, other, spendUsd }`. A run it names (`newest`, `lastBad`) is `{ workspace, id, what, outcome, startedAt, finishedAt, failure }`. `days` 1–365, 7 unasked (the page's default). A key scoped to some workspaces sees theirs |
380
384
  | `/api/insights?days=&workspace=` | GET | recurring problems found in the runs of the window (see [Runs](runs#insights)): `{ days, insights: [{ id, kind, workspace, agent, tool?, title, why, fix, credits, steps, evidence: [{ workspace, runId, step }] }] }`. `kind` is `cache` (an agent's big prompt mostly uncached), `big-result` (a tool result over 20k characters sent again on every later model call), `retry-loop` (a tool erroring three or more times in a step) or `timeout` (steps using 80% or more of their `timeout:`); `credits` is about what it cost in the window, null when it is not money. `days` 1–30, 7 unasked. A key scoped to some workspaces sees theirs |
381
385
  | `/api/issues?status=&workspace=` | GET | the account's issues: what went wrong, grouped and kept open until a person resolves it (see [Runs](runs#issues)). One issue is one desk's flow failing at one agent, or ending BLOCKED or BAD, or one platform cause across desks. Each carries `id`, `kind` (`platform`, `failed`, `blocked`, `bad`, `missed` — a scheduled fire that started no run), `status` (`open`, `acknowledged`, `snoozed`, `resolved`), `regressed` and `sinceRevision` (it was resolved and came back, since the revision its new run ran), `snoozedFor`, `workspace`/`workspaces`, `what`, `agent`, `reason`, `action` (what to do), `firstSeen`, `lastSeen`, `count`, the newest `runs`, `recoveredAt` (the flow's newest good run since — it closes nothing), `acknowledged`, `snoozedUntil`, `resolved` and the `history` of what people did. `status` is `active` unasked (open + acknowledged), or `open`, `acknowledged`, `snoozed`, `resolved`, `all`; `workspace` keeps the ones that hit it. A key scoped to some workspaces sees the issues of those |
382
386
  | `/api/issues/<id>` | GET POST | one issue; POST acts on it: `{ action: "acknowledge" | "snooze" | "resolve" | "reopen", for?: "30m" | "4h" | "1d" | "1w", until?: ISO, times?: n, note? }` (editor or above), kept in its history with who did it, and answers `{ issue }` as it now stands. A snooze needs `for`, a future `until`, or `times` (until it happens that many more times; with a time too, whichever comes first). A platform issue is the account's: closing it needs access to every workspace. A run that goes wrong the same way after a resolve opens the issue again |
@@ -431,6 +435,7 @@ person: a key names an account, never a who.
431
435
  | `/api/billing/card` | POST | save a card |
432
436
  | `/api/billing/details` | GET, PUT | who the invoices are made out to — GET `{ details, stripe, customer, tax }` for anyone who can see billing and every workspace (403 to a member or key scoped to some, as for the statement); PUT (the owner) `legalName` (required), `email`, `abn` (checked against the ABN rule), `address` `{ line1, line2, city, state, postcode, country }` (two-letter country) or `null`. Every problem comes back at once as `errors` with a `400`. Kept first, then sent to the Stripe customer (name, address, the ABN as its `au_abn` tax id): answers `synced`, and `syncError` with Stripe's words when Stripe refused — the details stand either way |
433
437
  | `/api/billing/portal` | POST | a Stripe Billing Portal session for the account's customer (the owner): answers `url`. Optional `returnTo`, a `/dashboard/…` path to come back to. `501` without Stripe |
438
+ | `/api/billing/invoices` | GET | the Invoices tab as data (hosted only; 5 Nov 2026): `invoices` is the plan's tax invoices from Stripe, newest first — `{ id, number, description, createdAt, amount, currency, status, url, pdfUrl }`, `amount` in the invoice's currency and `url` Stripe's hosted page; `receipts` is every credit purchase on the ledger, newest first — `{ t, usd, label, receiptUrl }`, `receiptUrl` Stripe's hosted receipt or `null` for a credit not paid by card; `stripe` is false when Stripe is not configured or the account has no customer there (no invoices then). The whole account's payments, so refused (403) to a member or key scoped to some workspaces, as the statement is |
434
439
  | `/api/billing/statement?month=&format=` | GET | one month of the ledger as a statement. JSON by default; `format=csv` downloads it with the month, the account and the spent and added totals in its header. `month` is `YYYY-MM`, default the current month. What the customer sees is the charge; the platform's provider cost is not on it. The whole account's money, so refused (403) to a member or key scoped to some workspaces, as the audit log is |
435
440
  | `/api/billing/wallet` | GET, PUT | the balance summary (burn, runway, daily spend, month to date, the suggested top-up), the refill rule and the low-balance email — GET `{ enabled, stripe, summary, cardSaved, autoTopUp, email, dunning, tomanTopUp }`, PUT `autoTopUp`, `email`. `dunning.status` is `none`, `grace` (a plan invoice failed; runs go on until `graceUntil`) or `suspended` (new runs paused until it is paid), with `payUrl`, `amountDue` (minor units) and `currency`. `tomanTopUp` is `{ url }` — foldrun.ir's charge page with this account filled in — or null where foldrun.ir cannot sell now |
436
441
  | `/api/billing/plans` | GET | the catalogue (four plans: fee, credits, per-credit price, runs at once, workspaces, lane), where this account stands (plan, status, this cycle's credits and what is left, when it resets), the balance in dollars and credits, and any overdraft the platform has allowed |
@@ -357,10 +357,10 @@ avatar, with eight tabs:
357
357
  | **Plan** | the plan you are on, this cycle's credits and when they reset, and the plans you could move to |
358
358
  | **Usage** | what was consumed, from the run records, and what each flow and agent cost by week from the ledger |
359
359
  | **Statement** | the ledger as a statement: grouped by day, human labels, month-to-date, filters, and a CSV for the month |
360
- | **Invoices** | a tax invoice for every card payment — the plan's fee and each top-up — hosted by Stripe, and a statement for every month |
360
+ | **Invoices** | a tax invoice for every card payment — the plan's fee and each top-up — hosted by Stripe, and a statement for every month; `foldrun billing invoices` lists the invoices and receipts in a terminal |
361
361
  | **Payment** | the saved card and the auto top-up rule, with defaults derived from the burn |
362
362
  | **Details** | who the invoices are made out to: legal name, ABN, address and the invoice email |
363
- | **Spend limits** | the account's cap and each workspace's — over a day, a week or a month — as bars with the warning marks drawn where they fire, editable in place |
363
+ | **Spend limits** | the account's cap and each workspace's — over a day, a week or a month — as bars with the warning marks drawn where they fire, editable in place; `foldrun usage budget` shows the same standing in a terminal |
364
364
 
365
365
  The balance also sits in the header of every page, tinted by runway, and a
366
366
  banner appears across the dashboard when the balance is under a week's cover
package/docs/cli.md CHANGED
@@ -85,11 +85,13 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
85
85
  | `foldrun proposals show\|apply\|dismiss <id> --to <workspace>` | `show`: the assistant's reasoning, the failures, the change per file as `-`/`+` lines. `apply`: prints the change and asks before writing it (`--yes` without a terminal); each file is a revision by you; refused when a file changed since. `dismiss`: set it aside |
86
86
  | `foldrun eval grades <eval> --to <workspace>` | what a grader (an eval with `trigger: runs`) found in the real runs it graded: the pass rate over `--days` (default 30), then each graded run, newest first, with the check that failed — `--status fail` for the failures alone, `--limit`, `--json`. `GET …/evals/<eval>/grades`, the Evals page's grader card. Exits 1 when a graded run in the window failed |
87
87
  | `foldrun eval grade <eval> --run <id> --to <workspace>` | grade one finished run now, sampled or not (`POST …/evals/<eval>/grade`) — **Grade a run** on the card. Prints each check; exits 1 unless it passed |
88
+ | `foldrun eval trends --to <workspace>` | evals by change, the workspace Observe page's table (`GET …/evals/trends`): each eval's latest score and the commit it ran on, against its most recent run on a different commit, and the change — biggest drop first. Exits 1 when a change made an eval worse; `--json` for the document. An eval called `trends` is still read with `--last` or `--run <id>` |
88
89
  | `foldrun eval new <name>` | the Evals page's New, on the deployed workspace (`POST …/evals { name }`): an eval whose `agent:` is the workspace's first agent and whose case is a placeholder — edit it (`source cat`/`put`), then `foldrun eval <name> --to <workspace>` runs it. `--to <workspace>` |
89
90
  | `foldrun promote <run-id>` | keep a finished run as a regression case: its task and what the next run must still say go into `evals/<target>-regressions.md` (or `--eval <name>`), appended when the file exists. `--expect "contains: $34"` — repeatable, eval syntax — replaces the default judge line that holds the next run to the recorded conclusion; `--case <name>` names the case. A run that went wrong (failed, BLOCKED, BAD) takes `--should "what it should have done"` — the judge's claim — or `--expect` |
90
91
  | `foldrun probe <model>` | can this model hold a tool loop here? A live check |
91
92
  | `foldrun logs [run-id]` | recent runs in one workspace, or one run's whole event trail. `--local` reads this machine's store even when signed in; `foldrun runs --local` is the same command and prints the same thing |
92
- | `foldrun runs` | what has run lately across the whole account: when, workspace, flow, status, steps done, how long, the credits it was charged (its token cost in dollars until the ledger settles it) and the run's own one-line summary. A completed run shows its verdict beside the status — `GOOD`, `BAD`, `QUIET`, or `BLOCKED` in red with a ⛔ mark. `--status failed`, `--verdict blocked`, search by what happened inside (`--tool web`, `--tool-error`, `--agent`, `--model haiku`, `--min-tokens 50k`, `--min-secs 120`, or `--view <name>` for a saved one — `foldrun runs views` lists yours), `--outcome blocked,failed` (the dashboard's word; `needs-you` is `waiting`), `--since 24h`, `--to <workspace>`, `--flow <name>` (that flow's runs, or a direct agent run's or an eval's name), `--q <words>` (the runs page's text search: every word, any order, across id, flow, workspace, status, verdict, summary and failure), `--limit <n>`. `--local` prints exactly what `logs --local` prints — this machine's runs, one workspace |
93
+ | `foldrun runs` | what has run lately across the whole account: when, workspace, flow, status, steps done, how long, the credits it was charged (its token cost in dollars until the ledger settles it) and the run's own one-line summary. A completed run shows its verdict beside the status — `GOOD`, `BAD`, `QUIET`, or `BLOCKED` in red with a ⛔ mark. `--status failed`, `--verdict blocked`, search by what happened inside (`--tool web`, `--tool-error`, `--agent`, `--model haiku`, `--min-tokens 50k`, `--min-secs 120`, or `--view <name>` for a saved one — `foldrun runs views` lists yours), `--outcome blocked,failed` (the dashboard's word; `needs-you` is `waiting`), `--since 24h`, `--to <workspace>`, `--flow <name>` (that flow's runs, or a direct agent run's or an eval's name), `--q <words>` (the runs page's text search: every word, any order, across id, flow, workspace, status, verdict, summary and failure), `--limit <n>` (20 by default) is one page: when more match it prints the next page's cursor — `--before <cursor>` shows that page (a time or a run id works too), `--page <n>` the nth page of `--limit`, `--all` every run that matches; `--json` prints `{ runs, next }`. `--local` prints exactly what `logs --local` prints — this machine's runs, one workspace |
94
+ | `foldrun runs outputs <run-id>` | which files the run archived from its agents' `outputs/` — the run page's **Out** column: each agent's files with their sizes, and the `foldrun report <run-id> get <agent>/<path>` that downloads one. `--to <workspace>` names the run's workspace (else it is found); `--json` prints `{ runId, files: [{ agent, path, bytes, href }], totalBytes }`. `GET /api/workspaces/<ws>/runs/<id>/files` |
93
95
  | `foldrun runs views save <name>` · `foldrun runs views rm <name>` | the runs page's **save view**: `save` keeps the filters given (`--status`, `--flow`, `--to`, `--since`, `--q`, `--tool`, `--tool-error`, `--agent`, `--model`, `--min-tokens`, `--min-secs`; `--since 24h` is kept as the dashboard's `today`) under that name, replacing a view of the same name; `rm` deletes one (asks; `--yes`). `PATCH /api/me/preferences` `{ runViews }` — the whole list, at most 20. `--json` prints the list after |
94
96
  | `foldrun runs doctor <run-id>` | the run doctor: the assistant reads a failed run and the files it names, says why (platform, check, work or outside), and proposes the fix as diffs, saved on yes — the run page's **Doctor** (`--to`, `--yes`, `--dry-run`, `--json`). Charged like one assistant reply |
95
97
  | `foldrun runs rm <run-id>` | erase a run from history: its record and its archived outputs. A run still in flight is stopped first. The ledger line stays — money is not deleted because a trace was. Needs an admin (`workspace:manage`). Asks first; `--yes` with no terminal. Several ids (`runs rm <id> <id>…`) are the runs list's **Delete** on a selection: it lists them, asks once, then deletes each — one refused does not stop the rest, and it exits 1 |
@@ -170,11 +172,13 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
170
172
  | `foldrun schedule tick` | Settings' **Run scheduler now**: fire whatever is due this minute and print which flows went (`POST /api/schedule`). They were due anyway; this only makes them go now |
171
173
  | `foldrun rerun <run-id>` | the same flow again, from a step: `--from <n>` as the flow file numbers them, or `--agent <name>` for the first step that agent runs. `--instruction "…"` tells that step something else this once, without changing the flow file. Earlier steps are recorded as skipped. This is the debug loop from the terminal: fix the file, `deploy`, `rerun --from` the step that failed. `--wait` follows the new run like `invoke --wait`; `--to <workspace>` from anywhere. With no run id and a filter (`--status failed`, `--since 24h`, `--until 2h`, `--flow <name>`) it reruns every match from `--from <n>` (default 1), listing and asking first as a bulk `stop` does; `--dry-run` lists only. Several run ids (`rerun <id> <id>…`) rerun those, from `--from <n>` (default 1) — `--agent` and `--instruction` are for one run |
172
174
  | `foldrun triggers` | why nothing ran. One row per flow that fired in the window: its trigger, how many fires became runs, when it last ran, and every reason for the difference with a count — a duplicate delivery, a throttled or debounced burst, a fire the platform slept through, an `overlap: skip`, a flow switched off by `disable_after:`. Below it, as the Triggers page: every decision, newest first (when, flow, the outcome in words with the key that decided it, the detail), and the deliveries at the hook and inbox URLs — whether a request arrived and was authentic before any flow rule had a say, with how many were refused, so a bad token shows even when nothing fired. `--limit <n>` of each (default 10). A switched-off flow is a non-zero exit; one successful run clears it. `--since <days>` (default 7), `--to <workspace>`, `--json` for the whole document (`flows`, `events`, `deliveries`) |
173
- | `foldrun observe` | where the account fails, retries and spends: one row per workspace — runs, failed and what share, steps, cost — then the recent failures in their own words. `--to <workspace>` prints that workspace in full, as the Observe page does: per flow (runs, failed, p50/p95 duration, cost), per agent (failed, retried, skipped, p95, turns, cache hit rate), per tool (calls, errors, p95 latency, result size p50/p95 and how many results were over 10k characters, which agents use it), and start-up — each phase of a step's first seconds, its own share and when it was done, p50/p95. `--since <days>` (default 30), `--json` for the document |
175
+ | `foldrun observe` | where the account fails, retries and spends: one row per workspace — runs, failed and what share, steps, cost, and its completion rate against the window before — then the account Observe page's analysis (`GET /api/observe`): the completion rate and what was charged against the window of the same length before, **why runs went wrong** (the platform's causes first, each with its desks and what the newest said), the **agents to watch** (those that failed or retried) and the **tools to watch** (those that errored), then the recent failures in their own words. 7 days unasked, as the page (until 5 Nov 2026 it was 30). `--to <workspace>` prints that workspace in full, as its Observe page does, over 30 days unasked: per flow (runs, failed, p50/p95 duration, cost), per agent (failed, retried, skipped, p95, turns, cache hit rate), per tool (calls, errors, p95 latency, result size p50/p95 and how many results were over 10k characters, which agents use it), and start-up — each phase of a step's first seconds, its own share and when it was done, p50/p95. `--since <days>` (or `--days`) picks any window; `--json` for the document — `{ days, account, workspaces }` account-wide (`account` the analysis, `null` from a platform without it), one workspace's report with `--to` |
174
176
  | `foldrun usage` | what the account consumed — runs, steps, tokens (with the share the prompt cache served), compute, storage, per workspace — and what it was charged over `--days <n>` (default 56) from the ledger, per workspace with the change against the period before. `--json` for both documents |
175
177
  | `foldrun usage --limit <n>` | the Usage page's **by flow** and **by agent** tables in the text output: what each flow and each agent was charged over the window, its runs and the change against the period before, most charged first — the first `n` of each (default 10; `0` hides them). `--json` has them all, in `history.byFlow` and `history.byAgent` |
176
178
  | `foldrun usage compute` | the cores, GiB and disk the account's running steps may hold together and in one step, at every level — the account, each workspace with a pool or anything held, each live run with its flow's pool — what each holds now, and the steps **waiting for room**, oldest first, each with its flow, agent, what it needs, how long it has waited, why and which level holds it (`GET /api/usage/compute`). A waiting step has no time limit and starts in turn; `--json` for the document. Set the levels with `foldrun account set compute …`, `foldrun workspace set compute … --to <ws>` and `foldrun flow compute <flow> …` |
179
+ | `foldrun usage budget` | the Spend limits page: the account's `budget:` and each workspace's, what is spent in its window (today, this week or this month, in the account's calendar) and how far into the cap that is — marked past the 80% warning, and at the cap with when new runs start again (`GET /api/usage/budget`). Most spent first; a workspace with no cap shows its month's spend. `--to <workspace>` for one, `--json` for the document. A key scoped to some workspaces sees those, not the account's figure. Set a cap with `foldrun account set budget …` or `foldrun workspace set budget 60/day --to <ws>` |
177
180
  | `foldrun billing` | the account's balance, whether billing is on at all, what the platform is currently waiving, and the recent ledger entries with what each was for — a run names its workspace, flow and run id; an adjustment carries its own note. `--limit <n>` shows more. `statement [YYYY-MM]` is a month of the ledger (this month by default) — `--csv` for the file an accountant wants, to stdout or `--file <path>`. `wallet` is the burn, the runway and auto top-up; `wallet set auto-top-up --threshold <usd> --amount <usd>` turns it on (a refill of 5–500), `set auto-top-up off` turns it off, `set email <address>` is where receipts go. `details` is who invoices are made out to; `details set --name "…" --abn … --address "line1, city, state, postcode, AU" --email …` changes it, merged with what is there. `portal` prints a link to Stripe's billing portal. Changing the wallet, the details, and the portal are the account owner's; anyone else is told so |
181
+ | `foldrun billing invoices` | the Invoices tab: the plan's tax invoices from Stripe — number, date, amount and currency, status, what it was for, and Stripe's link to it — and every credit purchase with its receipt link, newest first (`GET /api/billing/invoices`). `--json` for the document. Any member or key with every workspace; one scoped to some is refused, as the statement is. An install without billing says it has none |
178
182
  | `foldrun billing wallet clear email` | no address for receipts and low-balance warnings (`PUT /api/billing/wallet { email: null }`, as the wallet page's emptied field). `wallet set auto-top-up off` keeps the threshold and the refill for the next time it is turned on, as the page's switch does; `wallet` shows them beside off |
179
183
  | `foldrun billing details set --clear-address` | drops the address from who invoices are made out to, the rest kept; `--clear-email` and `--clear-abn` the same for the email and the ABN (each refused beside its own `--address`/`--email`/`--abn`) |
180
184
  | `foldrun billing plans` | the Plans page: every plan with its monthly fee, credits, runs at once and workspaces, which one the account is on and this cycle's credits left (`GET /api/billing/plans`). `billing plan <id>` chooses one — a first plan answers with Stripe's checkout page, a change on a live plan is prorated at Stripe at once (asks first; `--yes`); `plan cancel` stops it at the end of the cycle, `plan resume` undoes that until then (`POST`/`DELETE /api/billing/subscribe`) |
package/docs/evals.md CHANGED
@@ -64,6 +64,15 @@ workspace, which is what makes it a regression test rather than a thing someone
64
64
  remembers to click. Results land in `evals/.results/`, and a dated line goes to
65
65
  `history.jsonl` so movement is visible across weeks.
66
66
 
67
+ Each line is stamped with the commit the workspace was running (a git sha, or
68
+ a revision id `r-…` when it was edited on the platform), and the workspace's
69
+ **Observe** page reads them as **Evals by change**: each eval's latest score
70
+ against its most recent run on a *different* commit, the biggest drop first.
71
+ Not the run before — two runs on one commit differ only by the model, and a
72
+ "regression" that is really variance teaches people to ignore the real ones.
73
+ `foldrun eval trends --to <workspace>` prints the same table and exits 1 when a
74
+ change made an eval worse; `GET /api/workspaces/<ws>/evals/trends` answers it.
75
+
67
76
  On a platform an eval's run goes through the same queue as every other run,
68
77
  so it counts against the account's `concurrency:` and waits its turn.
69
78
 
package/docs/runs.md CHANGED
@@ -63,6 +63,14 @@ Click a step to pin it open or shut, or use **expand all** / **collapse
63
63
  all** above the column. A **json** link opens the run record exactly as the
64
64
  runner wrote it.
65
65
 
66
+ When a run finishes, whatever its agents left in `outputs/` is archived with
67
+ it, under `runs/<id>/outputs/<agent>/`, so the next run's reset does not erase
68
+ it. A step's **Out** column lists that agent's files, each opening inline (a
69
+ recording plays, a picture shows). `foldrun runs outputs <run-id>` lists the
70
+ same files with their sizes (`--json`), `foldrun report <run-id> get
71
+ <agent>/<path>` downloads one, and `GET …/runs/<id>/files` answers the list
72
+ with the link that serves each.
73
+
66
74
  A step's trace marks each line for what it is — the agent's words, a tool
67
75
  call (its name, then what it was called with, a click from whole), a verify
68
76
  result as **verified** or **verify failed**, an error, or the runner's own
@@ -200,6 +208,15 @@ credits it cost, and links the runs it was seen in:
200
208
 
201
209
  `foldrun insights` prints them; `GET /api/insights` answers them.
202
210
 
211
+ Below them the page compares the window — 24 hours, 7 days (unasked) or 30
212
+ days — with the one of the same length before it: the completion rate and
213
+ what was charged, each with its change; **why runs went wrong**, the
214
+ platform's causes first (no desk edit fixes those), then the desks' by how
215
+ often; every desk, worst first; and the **agents** and **tools to watch**.
216
+ `foldrun observe` prints the same analysis under its one-row-per-workspace
217
+ table, over the same 7 days unless `--since` says otherwise; `GET
218
+ /api/observe` answers it.
219
+
203
220
  ## Compare with the last good run
204
221
 
205
222
  On a finished run, **compare with the last good run** lays it beside the
@@ -441,6 +458,14 @@ that finds a row missing, stale, or orphaned, so it is never trusted over
441
458
  the files. The runs pages and the account-wide list read it; a run still
442
459
  live is read whole; a finished run's reply and trace are opened by id.
443
460
 
461
+ The list pages by position, not by number: `GET …/runs` answers `next`, a
462
+ cursor for the runs older than the last one it sent, and `before=<next>`
463
+ asks for that page, so runs that start meanwhile shift nothing. One cursor
464
+ pages every workspace, which is how `foldrun runs` pages the account:
465
+ `--limit` sets the page, `--page 3` or `--before <cursor>` picks one (the
466
+ command prints the next one's cursor), and `--all` reads every run that
467
+ matches.
468
+
444
469
  ## What survives the platform
445
470
 
446
471
  A step is a sandbox that keeps its own log and files until the platform
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "foldrun",
3
- "version": "15.0.0",
3
+ "version": "16.0.0",
4
4
  "description": "Agents are just folders. Write them, check them, run them — on your machine.",
5
5
  "license": "FSL-1.1-ALv2",
6
6
  "type": "module",
@@ -22,7 +22,7 @@
22
22
  ],
23
23
  "scripts": {
24
24
  "e2e": "FOLDRUN_E2E=1 FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-e2e-XXXXXX) node --test --test-timeout=300000 tests/e2e.test.ts",
25
- "test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-issues.test.ts tests/cli-capture.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-team-me.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-agent-link-isolated.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-report-cache.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts tests/cli-check-scan.test.ts tests/cli-published.test.ts tests/cli-init-target.test.ts tests/cli-flow-filter.test.ts tests/cli-eval-grades.test.ts tests/cli-eval-compare.test.ts tests/cli-proposals.test.ts tests/cli-inbox.test.ts tests/cli-usage-compute.test.ts tests/cli-fol105.test.ts tests/cli-key-renew.test.ts tests/cli-wait-failed.test.ts tests/cli-mcp.test.ts tests/cli-a2a.test.ts tests/cli-switches.test.ts tests/cli-parity-runs.test.ts tests/cli-parity-b.test.ts tests/cli-parity-clears.test.ts tests/cli-parity-c.test.ts",
25
+ "test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-issues.test.ts tests/cli-capture.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-team-me.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-agent-link-isolated.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-report-cache.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts tests/cli-check-scan.test.ts tests/cli-published.test.ts tests/cli-init-target.test.ts tests/cli-flow-filter.test.ts tests/cli-eval-grades.test.ts tests/cli-eval-compare.test.ts tests/cli-proposals.test.ts tests/cli-inbox.test.ts tests/cli-usage-compute.test.ts tests/cli-fol105.test.ts tests/cli-key-renew.test.ts tests/cli-wait-failed.test.ts tests/cli-mcp.test.ts tests/cli-a2a.test.ts tests/cli-switches.test.ts tests/cli-parity-runs.test.ts tests/cli-parity-b.test.ts tests/cli-parity-clears.test.ts tests/cli-parity-c.test.ts tests/cli-runs-paging.test.ts tests/cli-budget-invoices.test.ts tests/cli-observe-analysis.test.ts",
26
26
  "release": "node scripts/release.mjs",
27
27
  "typecheck": "tsc -p tsconfig.json",
28
28
  "docs:sync": "node scripts/sync-docs.mjs",
package/src/commands.mjs CHANGED
@@ -7958,7 +7958,8 @@ async function runsCmd(flags, layout) {
7958
7958
  }
7959
7959
  const names = typeof flags.to === "string" ? [flags.to] : await remoteWorkspaceNames(url, flags);
7960
7960
  if (!names.length) {
7961
- console.log(`\n ${c.dim(`no workspaces on ${url}`)}\n`);
7961
+ if (flags.json === true) console.log(JSON.stringify({ runs: [], next: null }, null, 2));
7962
+ else console.log(`\n ${c.dim(`no workspaces on ${url}`)}\n`);
7962
7963
  return 0;
7963
7964
  }
7964
7965
  const limit = Number(flags.limit) > 0 ? Math.floor(Number(flags.limit)) : 20;
@@ -7996,52 +7997,106 @@ async function runsCmd(flags, layout) {
7996
7997
  // A view's flow or text filters here, after the fetch: ask for the ceiling
7997
7998
  // as for a status, or matches past the newest few go missing (Codex review).
7998
7999
  const localText = typeof flags.flow === "string" || typeof flags.q === "string";
7999
- const perWorkspace = wanted || verdicts || outcomes || cutoff !== null || searching || localText ? 500 : limit;
8000
+ // Paging (5 Nov 2026): --limit is one page; --page <n> the nth, --before
8001
+ // <cursor> the one after a cursor the last page printed, --all every match.
8002
+ // Each workspace is asked for the runs older than one cursor (a position,
8003
+ // <startedAt>~<runId>, the API's `next`), so one cursor pages them all.
8004
+ if (flags.all === true && flags.page !== undefined) throw new Error("--all reads every page; leave --page out");
8005
+ const pageNo = flags.page === undefined ? 1 : Number(flags.page);
8006
+ if (!Number.isInteger(pageNo) || pageNo < 1) throw new Error(`--page is a page number from 1 — not "${flags.page}"`);
8007
+ const target = flags.all === true ? Infinity : limit * pageNo;
8008
+ const filtering = Boolean(wanted || verdicts || outcomes || cutoff !== null || searching || localText);
8009
+ const perWorkspace = filtering || flags.all === true ? 500 : Math.min(500, target);
8010
+ if (flags.before !== undefined && typeof flags.before !== "string") throw new Error("--before takes the cursor the last page printed (or a time, or a run id)");
8011
+ let cursor = typeof flags.before === "string" ? await runsCursorOf(url, flags, layout, flags.before) : null;
8000
8012
  const unreachable = [];
8001
- const lists = await pool(names, 8, async (ws) => {
8002
- try {
8003
- const forApi = new URLSearchParams([...search].filter(([k]) => ["tool", "tool_error", "agent", "model", "min_tokens", "min_secs"].includes(k)));
8004
- const { runs = [] } = await remoteCall(url, flags, `/api/workspaces/${ws}/runs?limit=${perWorkspace}${forApi.size ? `&${forApi}` : ""}`);
8005
- return runs.map((r) => ({ ...r, workspace: ws }));
8006
- } catch (err) {
8007
- unreachable.push([ws, explain(err)]);
8008
- return [];
8009
- }
8010
- });
8011
-
8012
- const rows = lists
8013
- .flat()
8013
+ /** Whether a run passes the filters the platform does not apply. */
8014
+ const keep = (r) => {
8014
8015
  // The status the dashboard shows: a stopped run is "stopped", not the
8015
8016
  // "failed" its record says (Codex review — a saved status=stopped view).
8016
- .filter((r) => (wanted ? wanted.has(r.outcome === "stopped" ? "stopped" : r.status) : true))
8017
- .filter((r) => (verdicts ? r.status === "completed" && verdicts.has(verdictOf(r)) : true))
8018
- .filter((r) => (outcomes ? typeof r.outcome === "string" && outcomes.has(r.outcome) : true))
8017
+ if (wanted && !wanted.has(r.outcome === "stopped" ? "stopped" : r.status)) return false;
8018
+ if (verdicts && !(r.status === "completed" && verdicts.has(verdictOf(r)))) return false;
8019
+ if (outcomes && !(typeof r.outcome === "string" && outcomes.has(r.outcome))) return false;
8019
8020
  // A view's flow and free text (the runs page's): "agent: x" is a direct run.
8020
8021
  // The dashboard names a run by what ran (whatRan): a direct agent run's
8021
8022
  // or an eval's own name, without adhoc:/eval: (Codex review).
8022
- .filter((r) => (typeof flags.flow === "string" ? r.flow === flags.flow || r.flow.replace(/^(adhoc|eval):/, "") === flags.flow : true))
8023
+ if (typeof flags.flow === "string" && !(r.flow === flags.flow || r.flow.replace(/^(adhoc|eval):/, "") === flags.flow)) return false;
8023
8024
  // The runs page's text search, field for field (its runSearchText): every
8024
8025
  // word, any order, across id, what ran, workspace, the status it shows,
8025
8026
  // verdict, summary and the failure (Codex review).
8026
- .filter((r) => {
8027
- if (typeof flags.q !== "string") return true;
8027
+ if (typeof flags.q === "string") {
8028
8028
  const words = flags.q.toLowerCase().replace(/\s+/g, " ").trim().split(" ").filter(Boolean);
8029
8029
  const shown = r.outcome === "stopped" ? "stopped" : r.status;
8030
8030
  const hay = [r.id, r.flow.replace(/^(adhoc|eval):/, ""), r.workspace, shown, verdictOf(r) ?? "", r.summary ?? "", r.failure ? `${r.failure.agent} ${r.failure.reason}` : ""]
8031
8031
  .join(" ")
8032
8032
  .toLowerCase()
8033
8033
  .replace(/\s+/g, " ");
8034
- return words.every((w) => hay.includes(w));
8035
- })
8036
- .filter((r) => (cutoff === null ? true : Date.parse(r.startedAt) >= cutoff))
8037
- .sort((a, b) => (a.startedAt < b.startedAt ? 1 : -1))
8038
- .slice(0, limit);
8034
+ if (!words.every((w) => hay.includes(w))) return false;
8035
+ }
8036
+ return cutoff === null || Date.parse(r.startedAt) >= cutoff;
8037
+ };
8038
+ const collected = [];
8039
+ let more = false;
8040
+ for (let round = 0; ; round++) {
8041
+ const answers = await pool(names, 8, async (ws) => {
8042
+ try {
8043
+ const forApi = new URLSearchParams([...search].filter(([k]) => ["tool", "tool_error", "agent", "model", "min_tokens", "min_secs"].includes(k)));
8044
+ forApi.set("limit", String(perWorkspace));
8045
+ if (cursor) forApi.set("before", cursor);
8046
+ const answer = await remoteCall(url, flags, `/api/workspaces/${ws}/runs?${forApi}`);
8047
+ // A platform from before paging answers no `next` and ignores before=.
8048
+ return { ws, runs: (answer.runs ?? []).map((r) => ({ ...r, workspace: ws })), next: answer.next ?? null, unpaged: !("next" in answer) };
8049
+ } catch (err) {
8050
+ // A cursor the platform refuses is the caller's mistake, not a desk
8051
+ // that is down: say so once, not as every workspace unreachable.
8052
+ if (err instanceof HttpError && err.status === 400 && cursor) throw err;
8053
+ unreachable.push([ws, explain(err)]);
8054
+ return { ws, runs: [], next: null, unpaged: false };
8055
+ }
8056
+ });
8057
+ // --all promises every run: an unpaged answer would end the loop after
8058
+ // the newest 500 per workspace and call that complete.
8059
+ if ((cursor || flags.all === true) && answers.some((a) => a.unpaged)) {
8060
+ throw new Error(`${url} does not page runs yet (no before=) — update it, or leave out --all, --before and --page`);
8061
+ }
8062
+ // A desk that has more than it sent is complete only down to its last
8063
+ // row; the merge is complete down to the newest such row (the horizon).
8064
+ // Rows older than it wait for the next round, so no desk's are skipped.
8065
+ const tails = answers.filter((a) => a.next !== null && a.runs.length).map((a) => a.runs.at(-1));
8066
+ const horizon = tails.length ? tails.sort(byRunPosition)[0] : null;
8067
+ const merged = answers
8068
+ .flatMap((a) => a.runs)
8069
+ .filter((r) => !horizon || byRunPosition(r, horizon) <= 0)
8070
+ .sort(byRunPosition);
8071
+ collected.push(...merged.filter(keep));
8072
+ if (!horizon) break;
8073
+ cursor = runCursor(horizon);
8074
+ // Newest first: once the horizon is older than --since, nothing older matches.
8075
+ if (cutoff !== null && Date.parse(horizon.startedAt) < cutoff) break;
8076
+ // Without --all a sparse filter stops after 20 rounds past the ones the
8077
+ // asked-for page needs (10,000 more runs a desk) and prints where it got
8078
+ // to, rather than reading the whole history; a deep --page is reached.
8079
+ if (collected.length >= target || (flags.all !== true && round >= 19 + Math.ceil(target / perWorkspace))) {
8080
+ more = true;
8081
+ break;
8082
+ }
8083
+ }
8084
+ const from = flags.all === true ? 0 : limit * (pageNo - 1);
8085
+ const rows = flags.all === true ? collected : collected.slice(from, from + limit);
8086
+ const next =
8087
+ flags.all === true ? null : collected.length > from + limit ? runCursor(rows.at(-1)) : more ? cursor : null;
8088
+
8089
+ if (flags.json === true) {
8090
+ console.log(JSON.stringify({ runs: rows, next }, null, 2));
8091
+ for (const [ws, why] of unreachable) console.error(` ${c.red("✗")} ${ws} ${c.dim(why)}`);
8092
+ return 0;
8093
+ }
8039
8094
 
8040
8095
  if (!rows.length) {
8041
8096
  const how = [wanted ? `status ${[...wanted].join(", ")}` : null, verdicts ? `verdict ${[...verdicts].join(", ")}` : null, outcomes ? `outcome ${[...outcomes].join(", ")}` : null, flags.since ? (String(flags.since).trim().toLowerCase() === "today" ? "today" : `the last ${flags.since}`) : null]
8042
8097
  .filter(Boolean)
8043
8098
  .join(" in ");
8044
- console.log(`\n ${c.dim(`no runs${how ? ` matching ${how}` : ""}${flags.to ? ` in ${flags.to}` : ""}`)}\n`);
8099
+ console.log(`\n ${c.dim(`no runs${how ? ` matching ${how}` : ""}${flags.to ? ` in ${flags.to}` : ""}${next ? ` on this page — older: the same with --before ${next}` : ""}`)}\n`);
8045
8100
  for (const [ws, why] of unreachable) console.error(` ${c.red("✗")} ${ws} ${c.dim(why)}`);
8046
8101
  return 0;
8047
8102
  }
@@ -8085,10 +8140,35 @@ async function runsCmd(flags, layout) {
8085
8140
  if (x.summary) console.log(` ${c.dim(x.summary)}`);
8086
8141
  }
8087
8142
  for (const [ws, why] of unreachable) console.error(` ${c.red("✗")} ${ws} ${c.dim(why)}`);
8143
+ if (next) console.log(`\n ${c.dim(`more: the same with --before ${next}${pageNo > 1 ? "" : ` (or --page ${pageNo + 1})`}`)}`);
8088
8144
  console.log(`\n ${c.dim("foldrun report <run-id> for the whole story; --status failed, --verdict blocked, --since 24h narrow this")}\n`);
8089
8145
  return 0;
8090
8146
  }
8091
8147
 
8148
+ /** The runs list's order: newest first, a tie on startedAt broken by id —
8149
+ * the order GET …/runs answers in, so a cursor means the same here. */
8150
+ export function byRunPosition(a, b) {
8151
+ if (a.startedAt !== b.startedAt) return a.startedAt < b.startedAt ? 1 : -1;
8152
+ return a.id < b.id ? 1 : a.id > b.id ? -1 : 0;
8153
+ }
8154
+
8155
+ /** A run's position as the API's `next` writes it: <startedAt>~<runId>. */
8156
+ export function runCursor(r) {
8157
+ return `${r.startedAt}~${r.id}`;
8158
+ }
8159
+
8160
+ /** What --before names, as a cursor every workspace reads alike: a cursor or
8161
+ * a time as given; a run id becomes that run's position (only its own
8162
+ * workspace could look the id up). */
8163
+ async function runsCursorOf(url, flags, layout, before) {
8164
+ const v = before.trim();
8165
+ if (v.includes("~") || /^\d{4}-\d{2}-\d{2}/.test(v)) return v;
8166
+ const ws = await workspaceOfRun(url, flags, layout, v);
8167
+ const run = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/runs/${enc(v)}`);
8168
+ if (typeof run.startedAt !== "string") throw new Error(`run ${v} has no start time to page from`);
8169
+ return runCursor({ startedAt: run.startedAt, id: v });
8170
+ }
8171
+
8092
8172
  // ---------------------------------------------------------------- report
8093
8173
 
8094
8174
  /** Files a run wrote, as its own steps recorded them. */
@@ -10165,6 +10245,50 @@ function printGrade(g) {
10165
10245
  console.log(` ${mark} ${c.bold(g.runId)} ${c.dim(String(g.at ?? "").slice(0, 16).replace("T", " "))}${why}`);
10166
10246
  }
10167
10247
 
10248
+ /**
10249
+ * `foldrun eval trends --to <workspace>` — evals by change, the workspace
10250
+ * Observe page's table (GET …/evals/trends): per eval, where it stands now and
10251
+ * against the most recent run on a DIFFERENT commit, biggest drop first. Two
10252
+ * runs on one commit differ only by the model, so that is the comparison
10253
+ * that names a change. Exit 1 when a change made an eval worse.
10254
+ */
10255
+ async function evalTrendsCmd(flags, layout) {
10256
+ const url = platformFor(flags, "eval trends");
10257
+ const ws = platformWorkspace(flags, layout, "eval trends");
10258
+ const r = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/evals/trends`);
10259
+ const trends = r.trends ?? [];
10260
+ const worse = trends.some((t) => t.delta != null && t.delta < 0);
10261
+ if (flags.json === true) {
10262
+ console.log(JSON.stringify(r, null, 2));
10263
+ return worse ? 1 : 0;
10264
+ }
10265
+ if (!trends.length) {
10266
+ console.log(`\n ${c.dim(`no eval has run in ${ws} yet — \`foldrun eval <name> --to ${ws}\` runs one, and a deploy runs every trigger: deploy eval`)}\n`);
10267
+ return 0;
10268
+ }
10269
+ // A git sha when the workspace deploys from git; a revision id (r-…) when it was edited on the platform.
10270
+ const commit = (x) => (!x ? "—" : x.startsWith("r-") ? x.slice(0, 12) : x.slice(0, 7));
10271
+ const score = (e) => `${e.passed}/${e.passed + e.failed}`;
10272
+ const rows = trends.map((t) => [
10273
+ t.eval,
10274
+ score(t.latest),
10275
+ t.latest.commit ? commit(t.latest.commit) : "no change on record",
10276
+ t.previous ? `${score(t.previous)} ${commit(t.previous.commit)}` : "first commit with a run",
10277
+ t.delta == null ? "—" : t.delta < 0 ? `${t.delta} — this change made it worse` : t.delta > 0 ? `+${t.delta}` : "unchanged",
10278
+ ]);
10279
+ const head = ["eval", "now", "at", "before", "change"];
10280
+ const w = head.map((_, i) => Math.max(...[head, ...rows].map((x) => String(x[i]).length)));
10281
+ console.log(`\n ${c.bold(ws)} ${c.dim("evals by change")}`);
10282
+ console.log(`\n ${c.dim(head.map((x, i) => pad(x, w[i])).join(" "))}`);
10283
+ trends.forEach((t, n) => {
10284
+ const cells = rows[n].map((x, i) => pad(x, w[i]));
10285
+ const tone = t.delta == null || t.delta === 0 ? (x) => x : t.delta < 0 ? c.red : c.green;
10286
+ console.log(` ${c.bold(cells[0])} ${cells[1]} ${c.dim(cells[2])} ${cells[3]} ${tone(cells[4])}`);
10287
+ });
10288
+ console.log(`\n ${c.dim("compared with the last run on a different commit · --json for the document")}\n`);
10289
+ return worse ? 1 : 0;
10290
+ }
10291
+
10168
10292
  /**
10169
10293
  * `foldrun eval grades <eval> --to <workspace>` — what a grader (an eval with
10170
10294
  * `trigger: runs`) found in the real runs it graded: the pass rate over
@@ -10876,6 +11000,43 @@ async function reportGetCmd(runId, spec, flags, layout) {
10876
11000
  return writeDownload(bytes, path.basename(rel), flags, `${runId} · ${spec}`);
10877
11001
  }
10878
11002
 
11003
+ /**
11004
+ * `foldrun runs outputs <run-id>` — which files a run archived: the run
11005
+ * page's Out column, each agent's files with their sizes, and the command
11006
+ * that downloads one (`report <run-id> get <agent>/<path>`).
11007
+ */
11008
+ async function runsOutputsCmd(args, flags, layout) {
11009
+ const runId = args[0];
11010
+ if (args.length !== 1 || !/^[A-Za-z0-9_.-]{1,80}$/.test(runId ?? "")) {
11011
+ throw new Error("`foldrun runs outputs <run-id>` — the files that run archived from its agents' outputs/ (--to <workspace>, --json)");
11012
+ }
11013
+ const url = platformFor(flags, "runs outputs");
11014
+ const ws = await workspaceOfRun(url, flags, layout, runId);
11015
+ const answer = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/runs/${enc(runId)}/files`);
11016
+ if (flags.json === true) {
11017
+ console.log(JSON.stringify(answer, null, 2));
11018
+ return 0;
11019
+ }
11020
+ const files = answer.files ?? [];
11021
+ if (!files.length) {
11022
+ console.log(`\n ${c.dim(`${runId} archived no files — its agents left nothing in outputs/`)}\n`);
11023
+ return 0;
11024
+ }
11025
+ const total = answer.totalBytes ?? files.reduce((t, f) => t + (f.bytes ?? 0), 0);
11026
+ console.log(`\n ${c.bold(runId)} ${c.dim(`in ${ws} · ${files.length} file${files.length === 1 ? "" : "s"} · ${humanBytes(total)}`)}`);
11027
+ const wide = Math.max(...files.map((f) => humanBytes(f.bytes).length));
11028
+ let agent = null;
11029
+ for (const f of files) {
11030
+ if (f.agent !== agent) {
11031
+ agent = f.agent;
11032
+ console.log(`\n ${c.bold(agent)}`);
11033
+ }
11034
+ console.log(` ${c.dim(pad(humanBytes(f.bytes), wide))} ${f.path}`);
11035
+ }
11036
+ console.log(`\n ${c.dim(`foldrun report ${runId} get <agent>/<path> downloads one (--file <path>|-)`)}\n`);
11037
+ return 0;
11038
+ }
11039
+
10879
11040
  /** Days, for a window: `30`, or `30d`. */
10880
11041
  function sinceDays(flags, fallback) {
10881
11042
  if (flags.since === undefined) return fallback;
@@ -10922,32 +11083,96 @@ function printObservation(o) {
10922
11083
  }
10923
11084
  }
10924
11085
 
11086
+ /**
11087
+ * The account Observe page's analysis (GET /api/observe), printed under the
11088
+ * per-workspace table: the window against the one before it, why runs went
11089
+ * wrong, the agents and tools to watch.
11090
+ */
11091
+ function printAccountAnalysis(a) {
11092
+ const k = a.kpis ?? {};
11093
+ const before = a.days === 1 ? "the day before" : `the ${a.days} days before`;
11094
+ const pts = (now, then) => {
11095
+ if (now == null || then == null) return c.dim("no earlier window to compare");
11096
+ const d = Math.round((now - then) * 100);
11097
+ if (d === 0) return c.dim(`same as ${before}`);
11098
+ return `${d > 0 ? c.green(`▲ ${d} pts`) : c.red(`▼ ${-d} pts`)} ${c.dim(`vs ${before}`)}`;
11099
+ };
11100
+ const spend = (now, then) => {
11101
+ if (!a.previous?.runs) return "";
11102
+ const d = now - then;
11103
+ if (Math.abs(d) < 0.005) return c.dim(` (same as ${before})`);
11104
+ return ` ${d > 0 ? c.red(`▲ $${d.toFixed(2)}`) : c.green(`▼ $${(-d).toFixed(2)}`)}`;
11105
+ };
11106
+ const wrong = (k.deskFailures ?? 0) + (k.platformFailures ?? 0);
11107
+ console.log(`\n ${c.bold(k.rate == null ? "—" : `${Math.round(k.rate * 100)}%`)} completed ${pts(k.rate, k.prevRate)}`);
11108
+ console.log(` ${k.runs ?? 0} runs (${a.previous?.runs ?? 0} ${before}) · ${wrong ? c.red(`${wrong} went wrong`) : "0 went wrong"} ${c.dim(`(${k.deskFailures ?? 0} desk · ${k.platformFailures ?? 0} platform)`)} · charged $${Number(k.spendUsd ?? 0).toFixed(2)}${spend(Number(k.spendUsd ?? 0), Number(k.prevSpendUsd ?? 0))} · median run ${secs(k.medianSecs)}`);
11109
+ const why = a.causes ?? [];
11110
+ if (why.length) {
11111
+ console.log(`\n ${c.dim("why runs went wrong")}`);
11112
+ for (const x of why) {
11113
+ const who = pad(x.platform ? "platform" : x.kind === "stopped" ? "person" : "desk", 8);
11114
+ console.log(` ${x.platform ? c.red(who) : x.kind === "stopped" ? c.dim(who) : who} ${c.bold(x.label)} ×${x.count} ${c.dim(x.desks.join(", "))}`);
11115
+ if (x.sample) console.log(` ${c.dim(`${firstLine(x.sample, 100)} — ${x.newest.workspace} ${x.newest.id}`)}`);
11116
+ }
11117
+ if (why.some((x) => x.platform)) console.log(` ${c.dim("no desk edit fixes a platform cause; once the platform is right, rerun them")}`);
11118
+ }
11119
+ const agents = (a.agents ?? []).filter((x) => x.failed || x.retried);
11120
+ if (agents.length) {
11121
+ const rows = agents.map((x) => [x.agent, x.workspace, `${x.failed}/${x.steps}`, x.retried, secs(x.seconds?.p50), `$${Number(x.chargedUsd ?? x.costUsd ?? 0).toFixed(2)}`]);
11122
+ const head = ["agents to watch", "workspace", "failed", "retried", "p50", "charged"];
11123
+ const w = head.map((_, i) => Math.max(...[head, ...rows].map((r) => String(r[i]).length)));
11124
+ console.log(`\n ${c.dim(head.map((x, i) => pad(x, w[i])).join(" "))}`);
11125
+ for (const r of rows) console.log(` ${r.map((x, i) => (i === 0 ? c.bold(pad(x, w[i])) : pad(x, w[i]))).join(" ")}`);
11126
+ }
11127
+ const tools = (a.tools ?? []).filter((t) => t.errors);
11128
+ if (tools.length) {
11129
+ const ms = (v) => (v == null ? "—" : v >= 1000 ? `${(v / 1000).toFixed(1)}s` : `${Math.round(v)}ms`);
11130
+ const rows = tools.map((t) => [t.name, t.calls, `${t.errors} ${pct(t.errors, t.calls)}`, ms(t.p95ms), t.workspaces.length === 1 ? t.workspaces[0] : `${t.workspaces.length} workspaces`]);
11131
+ const head = ["tools to watch", "calls", "errors", "slowest p95", "used by"];
11132
+ const w = head.map((_, i) => Math.max(...[head, ...rows].map((r) => String(r[i]).length)));
11133
+ console.log(`\n ${c.dim(head.map((x, i) => pad(x, w[i])).join(" "))}`);
11134
+ for (const r of rows) console.log(` ${r.map((x, i) => (i === 0 ? c.bold(pad(x, w[i])) : pad(x, w[i]))).join(" ")}`);
11135
+ }
11136
+ }
11137
+
10925
11138
  /**
10926
11139
  * `foldrun observe` — where the account fails, retries and spends, per
10927
- * workspace. `--to <workspace>` for one in full: flows, agents, tools, and
10928
- * the recent failures in their own words.
11140
+ * workspace, then the account Observe page's analysis (GET /api/observe):
11141
+ * the window against the one before, why runs went wrong, the agents and
11142
+ * tools to watch. 7 days unasked, as the page. `--to <workspace>` for one in
11143
+ * full — flows, agents, tools, the recent failures in their own words — 30
11144
+ * days unasked, as that workspace's Observe page. `--since`/`--days` pick
11145
+ * any window.
10929
11146
  */
10930
11147
  async function observeCmd(flags, layout) {
10931
11148
  const url = platformFor(flags, "observe");
10932
- const since = sinceDays(flags, 30);
10933
- const names = typeof flags.to === "string" ? [flags.to] : await remoteWorkspaceNames(url, flags);
11149
+ const one = typeof flags.to === "string";
11150
+ const since = sinceDays(flags.since === undefined && flags.days !== undefined ? { since: flags.days } : flags, one ? 30 : 7);
11151
+ const names = one ? [flags.to] : await remoteWorkspaceNames(url, flags);
10934
11152
  const unreachable = [];
10935
- const obs = (
10936
- await pool(names, 8, async (ws) => {
11153
+ const [obs, account] = await Promise.all([
11154
+ pool(names, 8, async (ws) => {
10937
11155
  try {
10938
11156
  return await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/observe?days=${since}`);
10939
11157
  } catch (err) {
10940
- if (typeof flags.to === "string") throw err;
11158
+ if (one) throw err;
10941
11159
  unreachable.push([ws, explain(err)]);
10942
11160
  return null;
10943
11161
  }
10944
- })
10945
- ).filter(Boolean);
11162
+ }).then((all) => all.filter(Boolean)),
11163
+ // A platform from before 5 Nov 2026 has no account analysis: the table alone.
11164
+ one
11165
+ ? null
11166
+ : remoteCall(url, flags, `/api/observe?days=${since}`).catch((err) => {
11167
+ if (err instanceof HttpError && err.status === 404) return null;
11168
+ throw err;
11169
+ }),
11170
+ ]);
10946
11171
  if (flags.json === true) {
10947
- console.log(JSON.stringify(typeof flags.to === "string" ? obs[0] : obs, null, 2));
11172
+ console.log(JSON.stringify(one ? obs[0] : { days: since, account, workspaces: obs }, null, 2));
10948
11173
  return 0;
10949
11174
  }
10950
- if (typeof flags.to === "string") {
11175
+ if (one) {
10951
11176
  printObservation(obs[0]);
10952
11177
  console.log(`\n ${c.dim("--since <days> widens it · --json for the whole document")}\n`);
10953
11178
  return 0;
@@ -10956,22 +11181,31 @@ async function observeCmd(flags, layout) {
10956
11181
  console.log(`\n ${c.dim(`no workspaces on ${url}`)}\n`);
10957
11182
  return 0;
10958
11183
  }
11184
+ // Each workspace's completion rate against the window before, from the analysis.
11185
+ const trendOf = new Map((account?.desks ?? []).map((d) => [d.workspace, d.rate != null && d.prevRate != null ? d.rate - d.prevRate : null]));
11186
+ const trend = (ws) => {
11187
+ const t = trendOf.get(ws);
11188
+ if (t == null) return c.dim("—");
11189
+ const d = Math.round(t * 100);
11190
+ return d === 0 ? c.dim("steady") : d > 0 ? c.green(`▲ ${d} pts`) : c.red(`▼ ${-d} pts`);
11191
+ };
10959
11192
  const rows = obs.sort((a, b) => b.failedRuns - a.failedRuns || b.runs - a.runs);
10960
11193
  const w = Math.max(9, ...rows.map((o) => o.workspace.length));
10961
- console.log(`\n ${c.dim(`${pad("workspace", w)} ${pad("runs", 5)} ${pad("failed", 9)} ${pad("steps", 6)} cost last ${since} days`)}`);
11194
+ console.log(`\n ${c.dim(`${pad("workspace", w)} ${pad("runs", 5)} ${pad("failed", 9)} ${pad("steps", 6)} ${pad("cost", 6)} ${account ? "vs before " : ""}last ${since} days`)}`);
10962
11195
  for (const o of rows) {
10963
11196
  const failed = pad(`${o.failedRuns} ${pct(o.failedRuns, o.runs)}`, 9);
10964
- console.log(` ${o.failedRuns ? c.red("✗") : c.green("✓")} ${c.bold(pad(o.workspace, w))} ${pad(o.runs, 5)} ${o.failedRuns ? c.red(failed) : failed} ${pad(o.steps, 6)} $${o.costUsd.toFixed(2)}`);
11197
+ console.log(` ${o.failedRuns ? c.red("✗") : c.green("✓")} ${c.bold(pad(o.workspace, w))} ${pad(o.runs, 5)} ${o.failedRuns ? c.red(failed) : failed} ${pad(o.steps, 6)} ${pad(`$${o.costUsd.toFixed(2)}`, 6)}${account ? ` ${trend(o.workspace)}` : ""}`);
10965
11198
  }
10966
11199
  const total = rows.reduce((t, o) => ({ runs: t.runs + o.runs, failed: t.failed + o.failedRuns, cost: t.cost + o.costUsd }), { runs: 0, failed: 0, cost: 0 });
10967
11200
  console.log(`\n ${c.dim(`${total.runs} runs · ${total.failed} failed · $${total.cost.toFixed(2)} across ${rows.length} workspace${rows.length === 1 ? "" : "s"}`)}`);
11201
+ if (account) printAccountAnalysis(account);
10968
11202
  const fails = rows.flatMap((o) => (o.failures ?? []).map((f) => ({ ...f, ws: o.workspace }))).sort((a, b) => (a.at < b.at ? 1 : -1)).slice(0, 8);
10969
11203
  if (fails.length) {
10970
11204
  console.log(`\n ${c.dim("recent failures")}`);
10971
11205
  for (const f of fails) console.log(` ${c.red("✗")} ${c.dim(when(f.at))} ${f.ws}/${f.flow} · ${c.bold(f.agent)} ${c.dim(f.runId)}\n ${c.dim(firstLine(f.text, 100))}`);
10972
11206
  }
10973
11207
  for (const [ws, why] of unreachable) console.error(` ${c.red("✗")} ${ws} ${c.dim(why)}`);
10974
- console.log(`\n ${c.dim("foldrun observe --to <workspace> for its flows, agents and tools")}\n`);
11208
+ console.log(`\n ${c.dim("foldrun observe --to <workspace> for its flows, agents and tools · --since <days> for another window")}\n`);
10975
11209
  return 0;
10976
11210
  }
10977
11211
 
@@ -11314,7 +11548,7 @@ async function billingVerbCmd(positional, flags) {
11314
11548
  // the platform team credits an account from its console. Nothing is sent.
11315
11549
  throw new Error("credit is not added by hand — `foldrun billing top-up <usd>` opens Stripe's checkout; for a credit from the platform, ask the platform team");
11316
11550
  }
11317
- throw new Error(`unknown billing verb "${verb}" — statement, wallet, details or portal (bare \`foldrun billing\` is the balance)`);
11551
+ throw new Error(`unknown billing verb "${verb}" — statement, invoices, wallet, details or portal (bare \`foldrun billing\` is the balance)`);
11318
11552
  }
11319
11553
 
11320
11554
  /** The defaults a workspace's AGENTS.md sets, read from its source. */
@@ -13998,6 +14232,115 @@ async function a2aCardCmd(flow, flags, layout) {
13998
14232
  return 0;
13999
14233
  }
14000
14234
 
14235
+ // --------------------------------------------------- spend limits, invoices
14236
+
14237
+ /**
14238
+ * `foldrun usage budget [--to <ws>]` — the Spend limits page: each cap, what
14239
+ * is spent in its window (today, this week, this month) and how far that is,
14240
+ * from GET /api/usage/budget. A key scoped to some workspaces sees those, and
14241
+ * not the account's figure.
14242
+ */
14243
+ async function usageBudgetCmd(flags) {
14244
+ const url = platformFor(flags, "usage budget");
14245
+ const d = await remoteCall(url, flags, "/api/usage/budget");
14246
+ const ws = typeof flags.to === "string" ? flags.to : null;
14247
+ const rows = (Array.isArray(d.workspaces) ? d.workspaces : []).filter((w) => !ws || w.workspace === ws);
14248
+ if (ws && !rows.length) throw new Error(`no workspace "${ws}" among the ones this credential may open`);
14249
+ if (flags.json === true) {
14250
+ console.log(JSON.stringify(ws ? { workspaces: rows } : d, null, 2));
14251
+ return 0;
14252
+ }
14253
+ const money = (n) => `$${Number(n ?? 0).toFixed(2)}`;
14254
+ const line = (s) => {
14255
+ if (!s.budget) return `${money(s.spentUsd)} spent this month ${c.dim("· no cap")}`;
14256
+ // Decided on the money, shown as a rounded percent: $995 of $1,000 rounds
14257
+ // to 100% but is not at the cap.
14258
+ const ratio = s.budget.usd > 0 ? s.spentUsd / s.budget.usd : 1;
14259
+ const pct = Math.round(ratio * 100);
14260
+ const atCap = ratio >= 1;
14261
+ const turns = s.budget.period === "day" ? "tomorrow" : s.budget.period === "week" ? "next week" : "the new month";
14262
+ const mark = atCap ? c.red("✗") : ratio >= 0.8 ? c.amber("!") : c.green("✓");
14263
+ const said = atCap ? c.red(` · at the cap, new runs are refused until ${turns}`) : ratio >= 0.8 ? c.amber(" · past the 80% warning") : "";
14264
+ return `${mark} ${money(s.spentUsd)} of ${s.label} ${s.window} · ${pct}%${said}`;
14265
+ };
14266
+ console.log();
14267
+ if (!ws) {
14268
+ if (d.account) console.log(` ${c.bold("account")} ${line(d.account)}`);
14269
+ else if (d.accountHidden) console.log(` ${c.bold("account")} ${c.dim("shown only to a member or key with every workspace — it is spend over all of them")}`);
14270
+ }
14271
+ if (rows.length) {
14272
+ const width = Math.max(...rows.map((w) => w.workspace.length));
14273
+ if (!ws) console.log(`\n ${c.bold("workspaces")} ${c.dim("most spent first")}`);
14274
+ for (const w of rows) console.log(` ${pad(w.workspace, width)} ${line(w)}`);
14275
+ } else console.log(` ${c.dim("no workspaces yet")}`);
14276
+ console.log(`\n ${c.dim("set a cap: foldrun account set budget 500 · foldrun workspace set budget 60/day --to <ws>")}\n`);
14277
+ return 0;
14278
+ }
14279
+
14280
+ /**
14281
+ * `foldrun billing invoices` — the Invoices tab: the plan's tax invoices from
14282
+ * Stripe with their links, and every credit purchase with its receipt, from
14283
+ * GET /api/billing/invoices. An install without billing has no such route.
14284
+ */
14285
+ /**
14286
+ * Every `foldrun billing …` verb: a platform without billing (self-hosted,
14287
+ * or the public build) answers its routes with a bare 404 "not found" —
14288
+ * say that, rather than print the 404.
14289
+ */
14290
+ async function noBillingSaid(flags, run) {
14291
+ try {
14292
+ return await run();
14293
+ } catch (err) {
14294
+ if (err instanceof HttpError && err.status === 404 && /^(not found|404|this page could not be found\.?)$/i.test(String(err.message).trim())) {
14295
+ const host = (() => {
14296
+ try {
14297
+ return new URL(remoteUrl(flags) ?? "").host;
14298
+ } catch {
14299
+ return "this platform";
14300
+ }
14301
+ })();
14302
+ throw new Error(`${host} has no billing — it is the hosted platform's (a self-hosted install has none)`);
14303
+ }
14304
+ throw err;
14305
+ }
14306
+ }
14307
+
14308
+ async function billingInvoicesCmd(flags) {
14309
+ const url = platformFor(flags, "billing invoices");
14310
+ let d;
14311
+ try {
14312
+ d = await remoteCall(url, flags, "/api/billing/invoices");
14313
+ } catch (err) {
14314
+ if (err instanceof HttpError && err.status === 404) throw new Error(`${new URL(url).host} has no billing — invoices are the hosted platform's (or it runs a platform from before 5 Nov 2026)`);
14315
+ if (err instanceof HttpError && err.status === 403) throw new Error(`invoices need a member or key with every workspace — ${err.message}`);
14316
+ throw err;
14317
+ }
14318
+ if (flags.json === true) {
14319
+ console.log(JSON.stringify(d, null, 2));
14320
+ return 0;
14321
+ }
14322
+ const day = (iso) => (iso ? String(iso).slice(0, 10) : "—");
14323
+ const invoices = Array.isArray(d.invoices) ? d.invoices : [];
14324
+ const receipts = Array.isArray(d.receipts) ? d.receipts : [];
14325
+ console.log(`\n ${c.bold("tax invoices")} ${c.dim("the plan's fee and card top-ups, from Stripe")}`);
14326
+ if (!invoices.length) console.log(` ${c.dim(d.stripe ? "no invoices yet" : "none — Stripe is not set up for this account")}`);
14327
+ for (const inv of invoices) {
14328
+ const amount = `${Number(inv.amount ?? 0).toFixed(2)}${inv.currency ? ` ${String(inv.currency).toUpperCase()}` : ""}`;
14329
+ const said = inv.status ?? "—";
14330
+ const status = (inv.status === "paid" ? c.green : c.amber)(said) + " ".repeat(Math.max(0, 13 - said.length));
14331
+ console.log(` ${pad(inv.number ?? inv.id, 14)} ${day(inv.createdAt)} ${pad(amount, 12)} ${status} ${inv.description ?? ""}`);
14332
+ if (inv.url) console.log(` ${" ".repeat(14)} ${c.dim(inv.url)}`);
14333
+ }
14334
+ console.log(`\n ${c.bold("credit purchases")}`);
14335
+ if (!receipts.length) console.log(` ${c.dim("no payments yet")}`);
14336
+ for (const r of receipts) {
14337
+ console.log(` ${day(r.t)} ${pad(`+$${Number(r.usd ?? 0).toFixed(2)}`, 10)} ${r.label ?? ""}`);
14338
+ console.log(` ${r.receiptUrl ? c.dim(r.receiptUrl) : c.dim("no receipt — not paid by card")}`);
14339
+ }
14340
+ console.log(`\n ${c.dim("a month's statement: foldrun billing statement [YYYY-MM] (--csv)")}\n`);
14341
+ return 0;
14342
+ }
14343
+
14001
14344
  export async function run(command, positional, flags, workspace, layout) {
14002
14345
  // Nothing outside the CLI's own entry point passes a layout — the tests
14003
14346
  // that call run() directly, an embedder. A lone workspace is the safe
@@ -14092,6 +14435,11 @@ export async function run(command, positional, flags, workspace, layout) {
14092
14435
  if (positional[0] === "grade" && positional[1]) return evalGradeCmd(positional[1], flags, layout);
14093
14436
  if (positional[0] === "compare" && positional[1]) return evalCompareCmd(positional[1], flags, layout);
14094
14437
  if (positional[0] === "improve" && positional[1]) return evalImproveCmd(positional[1], flags, layout);
14438
+ // `eval trends`: evals by change on the deployed workspace. Nothing
14439
+ // follows it, so it takes the name: an eval called "trends" is still
14440
+ // read with `--last` / `--run <id>`, and runs with the rest in
14441
+ // `foldrun eval --to <ws>`.
14442
+ if (positional[0] === "trends" && !positional[1] && flags.last !== true && flags.run === undefined) return evalTrendsCmd(flags, layout);
14095
14443
  // --to names a deployed workspace: its evals run there.
14096
14444
  if (typeof flags.to === "string") return remoteEvalsCmd(positional[0], flags, layout);
14097
14445
  // --last reads the platform's results; a local eval has none to read,
@@ -14108,6 +14456,7 @@ export async function run(command, positional, flags, workspace, layout) {
14108
14456
  return observeCmd(flags, layout);
14109
14457
  case "usage":
14110
14458
  if (positional[0] === "compute") return usageComputeCmd(flags);
14459
+ if (positional[0] === "budget") return usageBudgetCmd(flags);
14111
14460
  return usageCmd(flags);
14112
14461
  case "workspace":
14113
14462
  if (positional[0] === "vocabulary") return vocabularyCmd(flags, layout);
@@ -14154,6 +14503,7 @@ export async function run(command, positional, flags, workspace, layout) {
14154
14503
  // the local store has no table to draw across workspaces, because a
14155
14504
  // folder on a laptop is one workspace.
14156
14505
  if (positional[0] === "rm") return positional.length > 2 ? runsRmManyCmd(positional.slice(1), flags, layout) : runRmCmd(positional[1], flags, layout);
14506
+ if (positional[0] === "outputs") return runsOutputsCmd(positional.slice(1), flags, layout);
14157
14507
  if (positional[0] === "views" && positional[1]) return runViewsEditCmd(positional.slice(1), flags);
14158
14508
  if (positional[0] === "views") return runViewsCmd(flags);
14159
14509
  // The run doctor (FOL-22): the assistant reads the run and its files,
@@ -14212,8 +14562,11 @@ export async function run(command, positional, flags, workspace, layout) {
14212
14562
  case "docs":
14213
14563
  return docsCmd(positional, flags);
14214
14564
  case "billing":
14215
- if (["plans", "plan", "top-up", "card"].includes(positional[0])) return billingPlansCmd(positional[0], positional[1], flags);
14216
- return positional.length ? billingVerbCmd(positional, flags) : billingCmd(flags);
14565
+ return noBillingSaid(flags, () => {
14566
+ if (positional[0] === "invoices") return billingInvoicesCmd(flags);
14567
+ if (["plans", "plan", "top-up", "card"].includes(positional[0])) return billingPlansCmd(positional[0], positional[1], flags);
14568
+ return positional.length ? billingVerbCmd(positional, flags) : billingCmd(flags);
14569
+ });
14217
14570
  case "library":
14218
14571
  return libraryCmd(positional, flags);
14219
14572
  case "preferences":