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 +13 -6
- package/docs/api.md +6 -1
- package/docs/budgets-and-billing.md +2 -2
- package/docs/cli.md +6 -2
- package/docs/evals.md +9 -0
- package/docs/runs.md +25 -0
- package/package.json +2 -2
- package/src/commands.mjs +397 -44
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
|
|
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
|
|
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
|
|
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": "
|
|
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(
|
|
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
|
-
|
|
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
|
-
|
|
8002
|
-
|
|
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
|
-
|
|
8017
|
-
|
|
8018
|
-
|
|
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
|
-
|
|
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
|
-
.
|
|
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
|
-
|
|
8035
|
-
}
|
|
8036
|
-
|
|
8037
|
-
|
|
8038
|
-
|
|
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
|
|
10928
|
-
* the
|
|
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
|
|
10933
|
-
const
|
|
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
|
-
|
|
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 (
|
|
11158
|
+
if (one) throw err;
|
|
10941
11159
|
unreachable.push([ws, explain(err)]);
|
|
10942
11160
|
return null;
|
|
10943
11161
|
}
|
|
10944
|
-
})
|
|
10945
|
-
|
|
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(
|
|
11172
|
+
console.log(JSON.stringify(one ? obs[0] : { days: since, account, workspaces: obs }, null, 2));
|
|
10948
11173
|
return 0;
|
|
10949
11174
|
}
|
|
10950
|
-
if (
|
|
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
|
|
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)}
|
|
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
|
-
|
|
14216
|
-
|
|
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":
|