foldrun 14.4.1 → 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 +15 -8
- package/docs/api.md +7 -1
- package/docs/budgets-and-billing.md +2 -2
- package/docs/cli.md +9 -5
- package/docs/evals.md +9 -0
- package/docs/runs.md +25 -0
- package/package.json +2 -2
- package/src/commands.mjs +445 -133
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
|
|
@@ -374,7 +379,7 @@ Options
|
|
|
374
379
|
--tag <t> invoke, flow run: a label on the run — repeatable, sent as tags
|
|
375
380
|
--inputs <set> invoke, flow run: the task is a saved input set (evals/<flow>-inputs.md, or an eval case for the flow)
|
|
376
381
|
--preview storage cat: the platform reads the file and prints what is in it
|
|
377
|
-
--ttl <days> storage share: how long the link works (default 7); --forever: it never expires
|
|
382
|
+
--ttl <days> storage share: how long the link works (default 7); --forever: it never expires (keys create: the key never expires)
|
|
378
383
|
--into <folder/> storage put: upload under that folder of storage/
|
|
379
384
|
--as <path> storage put: the path one uploaded file lands at; agent import: the name the copy gets
|
|
380
385
|
--csv billing statement: the CSV file instead of the table
|
|
@@ -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)
|
|
@@ -437,7 +444,7 @@ Options
|
|
|
437
444
|
--authorize-param name=value connect, secrets clients add: an extra authorize-URL parameter the provider documents (repeatable — e.g. access_type=offline)
|
|
438
445
|
--role <r> keys create, team invite: viewer, editor (default) or admin
|
|
439
446
|
--no-send team invite: make the link, mail nothing
|
|
440
|
-
--expires <span> keys create: when it stops working — 30d, 90d, 365d or never
|
|
447
|
+
--expires <span> keys create: when it stops working — 30d, 90d (default, as in the dashboard), 365d or never; --forever is never
|
|
441
448
|
--grace <span> keys rotate: keep the old key working for 1h or 24h while you swap the new one in (default 0: revoked now)
|
|
442
449
|
--a2a keys create: an A2A key for an outside agent — with --to <workspace> and --flows a,b; --max-tasks <n> caps its open tasks (1–100, default 10)
|
|
443
450
|
--key-env <NAME> a2a call, a2a status, a2a cancel, a2a card: the environment variable holding the A2A key (default FOLDRUN_A2A_KEY) — a key is never taken on the command line
|
package/docs/api.md
CHANGED
|
@@ -92,6 +92,7 @@ api workspaces/$WS/flows/publish/run -X POST # start a flow
|
|
|
92
92
|
| | PUT | write (`path`, `content`, optional `message` — recorded on the revision, as `foldrun source put --message` sends it) |
|
|
93
93
|
| | PATCH | move (`from`, `to`) |
|
|
94
94
|
| | DELETE | remove (`path`) |
|
|
95
|
+
| `/api/workspaces/<ws>/source/share` | POST | **Move to shared**: a skill, tool, script, knowledge or memory file into the account library and out of the workspace, in one call — `path` (`skills/x/SKILL.md`, `tools/x/tool.md` or the folder moves the whole folder), `overwrite` (replace library files already there; `409` otherwise), `dryRun` (what would move, nothing written). Everything is checked first: a folder holding a file the library cannot hold (an image, a binary), one too large or with broken frontmatter is refused `409` and nothing changes. `{ ok, kind, unit, files: [{ from, to, replaces }], moved }`. Account-wide callers only (`workspace:write`), as for the library itself. Hooks are refused. Idempotent |
|
|
95
96
|
|
|
96
97
|
Editing one file at a time. For a whole tree, deploy. The files this door
|
|
97
98
|
writes are text: markdown, and a script's or a register's own formats —
|
|
@@ -205,6 +206,7 @@ history with each message.
|
|
|
205
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 |
|
|
206
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 |
|
|
207
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 |
|
|
208
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 |
|
|
209
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 |
|
|
210
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` |
|
|
@@ -221,7 +223,7 @@ paying for the steps around it.
|
|
|
221
223
|
|
|
222
224
|
| Route | Methods | |
|
|
223
225
|
|---|---|---|
|
|
224
|
-
| `/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 |
|
|
225
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) |
|
|
226
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 |
|
|
227
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) |
|
|
@@ -233,6 +235,7 @@ paying for the steps around it.
|
|
|
233
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 |
|
|
234
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 |
|
|
235
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 |
|
|
236
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 |
|
|
237
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 |
|
|
238
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 }` |
|
|
@@ -371,11 +374,13 @@ Reads return which secrets exist, never their values.
|
|
|
371
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 |
|
|
372
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 |
|
|
373
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)) |
|
|
374
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 |
|
|
375
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 |
|
|
376
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 |
|
|
377
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` |
|
|
378
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 |
|
|
379
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 |
|
|
380
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 |
|
|
381
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 |
|
|
@@ -430,6 +435,7 @@ person: a key names an account, never a who.
|
|
|
430
435
|
| `/api/billing/card` | POST | save a card |
|
|
431
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 |
|
|
432
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 |
|
|
433
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 |
|
|
434
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 |
|
|
435
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 |
|
|
@@ -141,7 +143,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
141
143
|
| `foldrun invoke <flow>` | start a flow on a running platform — `--watch` follows its trace here; `--test` makes it a [test run](runs#test-runs) `--once <key>` sends the key as the run's idempotency key, so a CI step that retries after a dropped response is answered with the run it already started instead of paying for a second. `--tag <t>`, repeatable, labels the run (the API's `tags`). `--inputs <name>` sends a saved input set as the task — a case of `evals/<flow>-inputs.md` or of an eval that runs the flow, as the platform has it (see [Run with saved inputs](flows#run-with-saved-inputs)). `foldrun flow run <flow>` is the same command |
|
|
142
144
|
| `foldrun source <verb>` | one workspace file on a platform: `ls [dir]`, `cat <path>`, `put <path>` (from `--file`, else stdin; `--message` goes on the revision), `new <kind> <name>`, `mv <from> <to>`, `rm <path>` — the editor's own door, so every write is a revision. `new` is the dashboard's New button for any document (`POST …/assets { kind, name, agent?, template?, language? }`): `tools`, `knowledge`, `memory`, `skills`, `scripts` (and `agents`, `flows`, `evals`), the template written by the platform; `--agent <name>` puts a knowledge, memory, skill or script document inside that agent. For a whole tree, `deploy` |
|
|
143
145
|
| `foldrun source put <path> --check` | the dashboard editor's checked save (`PUT …/source { check: true }`): a file a deploy would refuse is refused — HTTP 422, the issues printed with their rule ids, exit 1, nothing written; a save that passes prints its warnings. Without `--check` a save is written as before (the editor's **Save anyway**). `--empty` writes an empty file on purpose, as the file tree's **+ Add file** does; an empty input without it is refused, since that is nearly always a pipe that broke |
|
|
144
|
-
| `foldrun source share <path>` | the dashboard's **Move to shared
|
|
146
|
+
| `foldrun source share <path>` | the dashboard's **Move to shared** (`POST /api/workspaces/<ws>/source/share`): a skill, tool, script, knowledge or memory file into the account library and out of the workspace, moved by the platform in one call. A skill or folder tool (`skills/x/SKILL.md`, `tools/x/tool.md`, or the folder) moves whole, subfolders in place. It lists what would move first (the platform's dry run), asks (`--yes` with no terminal), then moves. A folder holding a file the library cannot hold (an image, a binary) is refused and nothing moves; a library file of the same path is refused unless `--overwrite`; `--dry-run` stops after the list; `--json` prints the answer. A hook is refused — `hook add --library` makes a shared one. `--to <workspace>`; the library is every workspace's, so it needs an account-wide sign-in |
|
|
145
147
|
| `foldrun open [page]` | the dashboard for this workspace, in the browser (`runs`, `agents`, `graph`, `repo`…) |
|
|
146
148
|
| `foldrun login` | sign this machine in from the browser — no key to copy. Type the code it shows on the page and approve within five minutes |
|
|
147
149
|
| `foldrun login <site> --url <address>` | a browser window to sign in to a site by hand; the session is stored for an agent |
|
|
@@ -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`) |
|
|
@@ -250,7 +254,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
250
254
|
| `--tag <t>` | `invoke`, `flow run`: a label on the run — repeatable |
|
|
251
255
|
| `--inputs <name>` | `invoke`, `flow run`: the task is that saved input set; not with `--task` |
|
|
252
256
|
| `--preview` | `storage cat`: the platform reads the file and prints what is in it |
|
|
253
|
-
| `--ttl <days>`, `--forever` | `storage share`: how long the link works (default 7 days), or never expires |
|
|
257
|
+
| `--ttl <days>`, `--forever` | `storage share`: how long the link works (default 7 days), or never expires. `--forever` on `keys create`: the key never expires |
|
|
254
258
|
| `--into <folder/>` | `storage put`: upload under that folder of `storage/` |
|
|
255
259
|
| `--all` (storage) | `storage ls`: every workspace's storage; `storage shares`: expired and revoked links too |
|
|
256
260
|
| `--backup <id>` | `backups request`: the snapshot to restore from, by its id (optional; `--at` names the point either way) |
|
|
@@ -302,7 +306,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
302
306
|
| `--generate-key` | with `--token-auth jwt`: foldrun makes the key (EC P-256) and prints the public JWK to register with the provider; `connect` waits for Enter before it opens the consent |
|
|
303
307
|
| `--role <r>` | `keys create`, `team invite`: `viewer`, `editor` (default) or `admin` |
|
|
304
308
|
| `--no-send` | `team invite`: make the link and mail nothing |
|
|
305
|
-
| `--expires <span>` | `keys create`: when it stops working — `30d`, `90d
|
|
309
|
+
| `--expires <span>` | `keys create`: when it stops working — `30d`, `90d` (the default, as in the dashboard; before CLI 15.0.0 the default was never), `365d` or `never`; `--forever` is `never` |
|
|
306
310
|
| `--grace <span>` | `keys rotate`: keep the old key working for `1h` or `24h` (default `0`: revoked now) |
|
|
307
311
|
| `--a2a` | `keys create`: an A2A key for an outside agent, with `--to <workspace>`, `--flows a,b` and optionally `--max-tasks <n>` |
|
|
308
312
|
| `--key-env <NAME>` | `a2a call`, `a2a status`, `a2a cancel`, `a2a card`: the environment variable that holds the A2A key (default `FOLDRUN_A2A_KEY`) |
|
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
|
@@ -4730,8 +4730,12 @@ async function keysCmd(positional, flags) {
|
|
|
4730
4730
|
if (flags.a2a === true) return keysCreateA2a(url, arg, flags);
|
|
4731
4731
|
const body = { label: arg };
|
|
4732
4732
|
if (typeof flags.role === "string") body.role = flags.role;
|
|
4733
|
-
// --expires 30d|90d|365d|never; unsaid,
|
|
4734
|
-
|
|
4733
|
+
// --expires 30d|90d|365d|never (--forever is never); unsaid, 90 days —
|
|
4734
|
+
// the dashboard's default since it was built, and the CLI's since
|
|
4735
|
+
// 5 Nov 2026: a key that ends is a key that cannot leak forever.
|
|
4736
|
+
if (flags.forever === true && flags.expires !== undefined) throw new Error("--forever or --expires <span>, not both");
|
|
4737
|
+
if (flags.expires !== undefined && typeof flags.expires !== "string") throw new Error("--expires needs a span: 30d, 90d, 365d or never");
|
|
4738
|
+
body.expires = flags.forever === true ? "never" : typeof flags.expires === "string" ? flags.expires : "90d";
|
|
4735
4739
|
// --workspaces a,b narrows the key to those; --workspaces all opens
|
|
4736
4740
|
// every one you can. Unsaid, the key inherits your own scope.
|
|
4737
4741
|
if (typeof flags.workspaces === "string") body.workspaces = flags.workspaces === "all" ? null : flags.workspaces.split(",").map((w) => w.trim()).filter(Boolean);
|
|
@@ -4983,110 +4987,65 @@ async function sourceCmd(positional, flags) {
|
|
|
4983
4987
|
throw new Error(`source: unknown verb "${verb}" — ls, cat, put, new, mv, rm, share`);
|
|
4984
4988
|
}
|
|
4985
4989
|
|
|
4986
|
-
/** The workspace folders "Move to shared" applies to — the library kinds
|
|
4987
|
-
* but hooks (`foldrun hook add --library` makes a shared one). */
|
|
4988
|
-
const SHAREABLE_KINDS = ["skills", "tools", "scripts", "knowledge", "memory"];
|
|
4989
|
-
|
|
4990
4990
|
/**
|
|
4991
4991
|
* `foldrun source share <path> --to <ws>` — the dashboard's "Move to shared":
|
|
4992
|
-
*
|
|
4993
|
-
*
|
|
4994
|
-
*
|
|
4995
|
-
*
|
|
4996
|
-
*
|
|
4997
|
-
*
|
|
4998
|
-
*
|
|
4992
|
+
* POST /api/workspaces/<ws>/source/share, which moves it on the server in one
|
|
4993
|
+
* call. A skill or folder tool (skills/x/SKILL.md, tools/x/tool.md, or the
|
|
4994
|
+
* folder) moves whole; a folder holding a file the library cannot hold (an
|
|
4995
|
+
* image, a binary) is refused and nothing moves. It asks the platform what
|
|
4996
|
+
* would move first (dryRun), lists it, asks (--yes with no terminal), then
|
|
4997
|
+
* moves. A library file of the same path is refused unless --overwrite;
|
|
4998
|
+
* --dry-run stops after the list. Done here file by file (4 Nov) it could
|
|
4999
|
+
* not delete a skill's SKILL.md alone, nor reach its other files safely.
|
|
4999
5000
|
*/
|
|
5000
5001
|
async function sourceShare(url, flags, ws, base, spec) {
|
|
5001
5002
|
if (!spec) throw new Error("which file? `foldrun source share skills/house-style --to <workspace>` — a skill, tool, script, knowledge or memory file");
|
|
5002
|
-
const
|
|
5003
|
-
const
|
|
5004
|
-
|
|
5005
|
-
|
|
5006
|
-
|
|
5007
|
-
|
|
5008
|
-
|
|
5009
|
-
|
|
5010
|
-
|
|
5011
|
-
|
|
5012
|
-
|
|
5013
|
-
/** Which of these the library already has. */
|
|
5014
|
-
const inLibrary = async (list) => {
|
|
5015
|
-
const hits = [];
|
|
5016
|
-
for (const f of list) {
|
|
5017
|
-
try {
|
|
5018
|
-
await remoteCall(url, flags, `/api/library/${kind}?path=${enc(relOf(f))}`);
|
|
5019
|
-
hits.push(f);
|
|
5020
|
-
} catch (err) {
|
|
5021
|
-
if (!(err instanceof HttpError) || !(err.status === 404 || /not found/i.test(err.message))) throw err;
|
|
5022
|
-
}
|
|
5003
|
+
const route = `/api/workspaces/${enc(ws)}/source/share`;
|
|
5004
|
+
const ask = (extra) => remoteCall(url, flags, route, { method: "POST", body: JSON.stringify({ path: spec, ...(flags.overwrite === true ? { overwrite: true } : {}), ...extra }) });
|
|
5005
|
+
let plan;
|
|
5006
|
+
try {
|
|
5007
|
+
plan = await ask({ dryRun: true });
|
|
5008
|
+
} catch (err) {
|
|
5009
|
+
// The route's own 404 says "no <path> in <ws>"; any other 404 is a
|
|
5010
|
+
// platform from before the route.
|
|
5011
|
+
if (err instanceof HttpError && err.status === 404 && !/^no /.test(err.message)) {
|
|
5012
|
+
throw new Error(`${url} has no "Move to shared" route yet — it is newer than this platform; move it in Settings → the workspace's assets, or update the platform`);
|
|
5023
5013
|
}
|
|
5024
|
-
|
|
5025
|
-
}
|
|
5026
|
-
const
|
|
5027
|
-
|
|
5028
|
-
|
|
5029
|
-
|
|
5014
|
+
throw err;
|
|
5015
|
+
}
|
|
5016
|
+
const json = flags.json === true;
|
|
5017
|
+
const taken = plan.files.filter((f) => f.replaces);
|
|
5018
|
+
// --json: the platform's answer and nothing else — the plan on a dry run
|
|
5019
|
+
// or a refusal, the move's answer once moved.
|
|
5020
|
+
if (json && (flags["dry-run"] === true || (taken.length && flags.overwrite !== true))) {
|
|
5021
|
+
console.log(JSON.stringify(plan, null, 2));
|
|
5022
|
+
return taken.length && flags.overwrite !== true ? 1 : 0;
|
|
5023
|
+
}
|
|
5024
|
+
if (!json) {
|
|
5025
|
+
console.log(`\n ${c.bold(plan.unit)} ${c.dim(`· ${ws} → the shared library`)}\n`);
|
|
5026
|
+
for (const f of plan.files) console.log(` ${c.dim("·")} ${f.from} → library/${plan.kind}/${f.to}${f.replaces ? c.amber(" (the library has one — replaced)") : ""}`);
|
|
5027
|
+
console.log();
|
|
5028
|
+
}
|
|
5030
5029
|
if (taken.length && flags.overwrite !== true) {
|
|
5031
|
-
console.log(` ${c.red("✗")} the library already has ${taken.map((f) => `${kind}/${
|
|
5030
|
+
console.log(` ${c.red("✗")} the library already has ${taken.map((f) => `${plan.kind}/${f.to}`).join(", ")} — nothing was moved; --overwrite replaces ${taken.length === 1 ? "it" : "them"}\n`);
|
|
5032
5031
|
return 1;
|
|
5033
5032
|
}
|
|
5034
5033
|
if (flags["dry-run"] === true) {
|
|
5035
5034
|
console.log(` ${c.dim("--dry-run: nothing moved")}\n`);
|
|
5036
5035
|
return 0;
|
|
5037
5036
|
}
|
|
5038
|
-
if (!(await confirmed(flags, "source share", `Move ${unit} to shared? Every workspace in the account will be able to use it, and it leaves ${ws}. [y/N] `))) {
|
|
5037
|
+
if (!(await confirmed(flags, "source share", `Move ${plan.unit} to shared? Every workspace in the account will be able to use it, and it leaves ${ws}. [y/N] `))) {
|
|
5039
5038
|
console.log(`\n ${c.dim("nothing moved")}\n`);
|
|
5040
5039
|
return 0;
|
|
5041
5040
|
}
|
|
5042
|
-
//
|
|
5043
|
-
//
|
|
5044
|
-
|
|
5045
|
-
if (flags.
|
|
5046
|
-
|
|
5047
|
-
|
|
5048
|
-
}
|
|
5049
|
-
const copied = new Map();
|
|
5050
|
-
for (const f of members) {
|
|
5051
|
-
const { content } = await remoteCall(url, flags, `${base}?path=${enc(f)}`);
|
|
5052
|
-
copied.set(f, content ?? "");
|
|
5053
|
-
try {
|
|
5054
|
-
await remoteCall(url, flags, `/api/library/${kind}`, { method: "PUT", body: JSON.stringify({ path: relOf(f), content: content ?? "" }) });
|
|
5055
|
-
} catch (err) {
|
|
5056
|
-
throw new Error(`could not copy ${f} to the library — ${explain(err)}. ${unit} is still in ${ws}${f === members[0] ? "" : "; what was copied before it is in the library too"}`);
|
|
5057
|
-
}
|
|
5058
|
-
}
|
|
5059
|
-
// The DELETE takes no ifMatch, so read it all again first: a file edited
|
|
5060
|
-
// or added while this copied would be deleted without ever reaching the
|
|
5061
|
-
// library. Changed, it stays in both places and nothing is deleted.
|
|
5062
|
-
const { files: now = [] } = await remoteCall(url, flags, base);
|
|
5063
|
-
const nowMembers = now.filter((f) => f === unit || f.startsWith(`${unit}/`));
|
|
5064
|
-
const moved = [];
|
|
5065
|
-
for (const f of nowMembers) {
|
|
5066
|
-
if (!copied.has(f)) moved.push(f);
|
|
5067
|
-
else if ((await remoteCall(url, flags, `${base}?path=${enc(f)}`)).content !== copied.get(f)) moved.push(f);
|
|
5068
|
-
}
|
|
5069
|
-
if (moved.length) {
|
|
5070
|
-
throw new Error(`copied to shared, but ${moved.join(", ")} changed in ${ws} while it was copied — nothing was deleted, so it is in both places; run it again with --overwrite to copy the new text`);
|
|
5071
|
-
}
|
|
5072
|
-
// Only once every file is in the library, and only the files that were
|
|
5073
|
-
// copied, one by one — never the folder: the source API lists text files
|
|
5074
|
-
// alone, so deleting a skill's folder would take an image or other asset
|
|
5075
|
-
// in it that never reached the library. A failure leaves the rest in both
|
|
5076
|
-
// places, never in neither, and says so.
|
|
5077
|
-
for (const [i, f] of members.entries()) {
|
|
5078
|
-
try {
|
|
5079
|
-
await remoteCall(url, flags, base, { method: "DELETE", body: JSON.stringify({ path: f }) });
|
|
5080
|
-
} catch (err) {
|
|
5081
|
-
const left = members.slice(i);
|
|
5082
|
-
throw new Error(`copied to shared, but ${f} could not be removed from ${ws} — ${explain(err)}. ${left.length === 1 ? "It is" : `These ${left.length} are`} in both now; ${left.map((x) => `\`foldrun source rm ${x} --to ${ws}\``).join(", ")} finish${left.length === 1 ? "es" : ""} the move`);
|
|
5083
|
-
}
|
|
5084
|
-
}
|
|
5085
|
-
console.log(` ${c.green("✓")} ${unit} ${c.dim(`moved to library/${kind}/${relOf(unit)} — every workspace in the account can use it`)}`);
|
|
5086
|
-
if (unit !== clean || members.length > 1 || members[0] !== unit) {
|
|
5087
|
-
console.log(` ${c.dim(`only its text files move: anything else in ${unit}/ (an image, a binary) stays in ${ws}`)}`);
|
|
5041
|
+
// The platform checks it all again: a library file made while this asked
|
|
5042
|
+
// is refused (409) without --overwrite, and nothing moves.
|
|
5043
|
+
const done = await ask({});
|
|
5044
|
+
if (flags.json === true) {
|
|
5045
|
+
console.log(JSON.stringify(done, null, 2));
|
|
5046
|
+
return 0;
|
|
5088
5047
|
}
|
|
5089
|
-
console.log();
|
|
5048
|
+
console.log(` ${c.green("✓")} ${done.unit} ${c.dim(`moved to library/${done.kind}/${done.unit.slice(done.kind.length + 1)} — every workspace in the account can use it`)}\n`);
|
|
5090
5049
|
return 0;
|
|
5091
5050
|
}
|
|
5092
5051
|
|
|
@@ -7999,7 +7958,8 @@ async function runsCmd(flags, layout) {
|
|
|
7999
7958
|
}
|
|
8000
7959
|
const names = typeof flags.to === "string" ? [flags.to] : await remoteWorkspaceNames(url, flags);
|
|
8001
7960
|
if (!names.length) {
|
|
8002
|
-
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`);
|
|
8003
7963
|
return 0;
|
|
8004
7964
|
}
|
|
8005
7965
|
const limit = Number(flags.limit) > 0 ? Math.floor(Number(flags.limit)) : 20;
|
|
@@ -8037,52 +7997,106 @@ async function runsCmd(flags, layout) {
|
|
|
8037
7997
|
// A view's flow or text filters here, after the fetch: ask for the ceiling
|
|
8038
7998
|
// as for a status, or matches past the newest few go missing (Codex review).
|
|
8039
7999
|
const localText = typeof flags.flow === "string" || typeof flags.q === "string";
|
|
8040
|
-
|
|
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;
|
|
8041
8012
|
const unreachable = [];
|
|
8042
|
-
|
|
8043
|
-
|
|
8044
|
-
const forApi = new URLSearchParams([...search].filter(([k]) => ["tool", "tool_error", "agent", "model", "min_tokens", "min_secs"].includes(k)));
|
|
8045
|
-
const { runs = [] } = await remoteCall(url, flags, `/api/workspaces/${ws}/runs?limit=${perWorkspace}${forApi.size ? `&${forApi}` : ""}`);
|
|
8046
|
-
return runs.map((r) => ({ ...r, workspace: ws }));
|
|
8047
|
-
} catch (err) {
|
|
8048
|
-
unreachable.push([ws, explain(err)]);
|
|
8049
|
-
return [];
|
|
8050
|
-
}
|
|
8051
|
-
});
|
|
8052
|
-
|
|
8053
|
-
const rows = lists
|
|
8054
|
-
.flat()
|
|
8013
|
+
/** Whether a run passes the filters the platform does not apply. */
|
|
8014
|
+
const keep = (r) => {
|
|
8055
8015
|
// The status the dashboard shows: a stopped run is "stopped", not the
|
|
8056
8016
|
// "failed" its record says (Codex review — a saved status=stopped view).
|
|
8057
|
-
|
|
8058
|
-
|
|
8059
|
-
|
|
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;
|
|
8060
8020
|
// A view's flow and free text (the runs page's): "agent: x" is a direct run.
|
|
8061
8021
|
// The dashboard names a run by what ran (whatRan): a direct agent run's
|
|
8062
8022
|
// or an eval's own name, without adhoc:/eval: (Codex review).
|
|
8063
|
-
|
|
8023
|
+
if (typeof flags.flow === "string" && !(r.flow === flags.flow || r.flow.replace(/^(adhoc|eval):/, "") === flags.flow)) return false;
|
|
8064
8024
|
// The runs page's text search, field for field (its runSearchText): every
|
|
8065
8025
|
// word, any order, across id, what ran, workspace, the status it shows,
|
|
8066
8026
|
// verdict, summary and the failure (Codex review).
|
|
8067
|
-
.
|
|
8068
|
-
if (typeof flags.q !== "string") return true;
|
|
8027
|
+
if (typeof flags.q === "string") {
|
|
8069
8028
|
const words = flags.q.toLowerCase().replace(/\s+/g, " ").trim().split(" ").filter(Boolean);
|
|
8070
8029
|
const shown = r.outcome === "stopped" ? "stopped" : r.status;
|
|
8071
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}` : ""]
|
|
8072
8031
|
.join(" ")
|
|
8073
8032
|
.toLowerCase()
|
|
8074
8033
|
.replace(/\s+/g, " ");
|
|
8075
|
-
|
|
8076
|
-
}
|
|
8077
|
-
|
|
8078
|
-
|
|
8079
|
-
|
|
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
|
+
}
|
|
8080
8094
|
|
|
8081
8095
|
if (!rows.length) {
|
|
8082
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]
|
|
8083
8097
|
.filter(Boolean)
|
|
8084
8098
|
.join(" in ");
|
|
8085
|
-
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`);
|
|
8086
8100
|
for (const [ws, why] of unreachable) console.error(` ${c.red("✗")} ${ws} ${c.dim(why)}`);
|
|
8087
8101
|
return 0;
|
|
8088
8102
|
}
|
|
@@ -8126,10 +8140,35 @@ async function runsCmd(flags, layout) {
|
|
|
8126
8140
|
if (x.summary) console.log(` ${c.dim(x.summary)}`);
|
|
8127
8141
|
}
|
|
8128
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})`}`)}`);
|
|
8129
8144
|
console.log(`\n ${c.dim("foldrun report <run-id> for the whole story; --status failed, --verdict blocked, --since 24h narrow this")}\n`);
|
|
8130
8145
|
return 0;
|
|
8131
8146
|
}
|
|
8132
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
|
+
|
|
8133
8172
|
// ---------------------------------------------------------------- report
|
|
8134
8173
|
|
|
8135
8174
|
/** Files a run wrote, as its own steps recorded them. */
|
|
@@ -10206,6 +10245,50 @@ function printGrade(g) {
|
|
|
10206
10245
|
console.log(` ${mark} ${c.bold(g.runId)} ${c.dim(String(g.at ?? "").slice(0, 16).replace("T", " "))}${why}`);
|
|
10207
10246
|
}
|
|
10208
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
|
+
|
|
10209
10292
|
/**
|
|
10210
10293
|
* `foldrun eval grades <eval> --to <workspace>` — what a grader (an eval with
|
|
10211
10294
|
* `trigger: runs`) found in the real runs it graded: the pass rate over
|
|
@@ -10917,6 +11000,43 @@ async function reportGetCmd(runId, spec, flags, layout) {
|
|
|
10917
11000
|
return writeDownload(bytes, path.basename(rel), flags, `${runId} · ${spec}`);
|
|
10918
11001
|
}
|
|
10919
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
|
+
|
|
10920
11040
|
/** Days, for a window: `30`, or `30d`. */
|
|
10921
11041
|
function sinceDays(flags, fallback) {
|
|
10922
11042
|
if (flags.since === undefined) return fallback;
|
|
@@ -10963,32 +11083,96 @@ function printObservation(o) {
|
|
|
10963
11083
|
}
|
|
10964
11084
|
}
|
|
10965
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
|
+
|
|
10966
11138
|
/**
|
|
10967
11139
|
* `foldrun observe` — where the account fails, retries and spends, per
|
|
10968
|
-
* workspace
|
|
10969
|
-
* 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.
|
|
10970
11146
|
*/
|
|
10971
11147
|
async function observeCmd(flags, layout) {
|
|
10972
11148
|
const url = platformFor(flags, "observe");
|
|
10973
|
-
const
|
|
10974
|
-
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);
|
|
10975
11152
|
const unreachable = [];
|
|
10976
|
-
const obs = (
|
|
10977
|
-
|
|
11153
|
+
const [obs, account] = await Promise.all([
|
|
11154
|
+
pool(names, 8, async (ws) => {
|
|
10978
11155
|
try {
|
|
10979
11156
|
return await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/observe?days=${since}`);
|
|
10980
11157
|
} catch (err) {
|
|
10981
|
-
if (
|
|
11158
|
+
if (one) throw err;
|
|
10982
11159
|
unreachable.push([ws, explain(err)]);
|
|
10983
11160
|
return null;
|
|
10984
11161
|
}
|
|
10985
|
-
})
|
|
10986
|
-
|
|
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
|
+
]);
|
|
10987
11171
|
if (flags.json === true) {
|
|
10988
|
-
console.log(JSON.stringify(
|
|
11172
|
+
console.log(JSON.stringify(one ? obs[0] : { days: since, account, workspaces: obs }, null, 2));
|
|
10989
11173
|
return 0;
|
|
10990
11174
|
}
|
|
10991
|
-
if (
|
|
11175
|
+
if (one) {
|
|
10992
11176
|
printObservation(obs[0]);
|
|
10993
11177
|
console.log(`\n ${c.dim("--since <days> widens it · --json for the whole document")}\n`);
|
|
10994
11178
|
return 0;
|
|
@@ -10997,22 +11181,31 @@ async function observeCmd(flags, layout) {
|
|
|
10997
11181
|
console.log(`\n ${c.dim(`no workspaces on ${url}`)}\n`);
|
|
10998
11182
|
return 0;
|
|
10999
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
|
+
};
|
|
11000
11192
|
const rows = obs.sort((a, b) => b.failedRuns - a.failedRuns || b.runs - a.runs);
|
|
11001
11193
|
const w = Math.max(9, ...rows.map((o) => o.workspace.length));
|
|
11002
|
-
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`)}`);
|
|
11003
11195
|
for (const o of rows) {
|
|
11004
11196
|
const failed = pad(`${o.failedRuns} ${pct(o.failedRuns, o.runs)}`, 9);
|
|
11005
|
-
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)}` : ""}`);
|
|
11006
11198
|
}
|
|
11007
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 });
|
|
11008
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);
|
|
11009
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);
|
|
11010
11203
|
if (fails.length) {
|
|
11011
11204
|
console.log(`\n ${c.dim("recent failures")}`);
|
|
11012
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))}`);
|
|
11013
11206
|
}
|
|
11014
11207
|
for (const [ws, why] of unreachable) console.error(` ${c.red("✗")} ${ws} ${c.dim(why)}`);
|
|
11015
|
-
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`);
|
|
11016
11209
|
return 0;
|
|
11017
11210
|
}
|
|
11018
11211
|
|
|
@@ -11355,7 +11548,7 @@ async function billingVerbCmd(positional, flags) {
|
|
|
11355
11548
|
// the platform team credits an account from its console. Nothing is sent.
|
|
11356
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");
|
|
11357
11550
|
}
|
|
11358
|
-
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)`);
|
|
11359
11552
|
}
|
|
11360
11553
|
|
|
11361
11554
|
/** The defaults a workspace's AGENTS.md sets, read from its source. */
|
|
@@ -14039,6 +14232,115 @@ async function a2aCardCmd(flow, flags, layout) {
|
|
|
14039
14232
|
return 0;
|
|
14040
14233
|
}
|
|
14041
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
|
+
|
|
14042
14344
|
export async function run(command, positional, flags, workspace, layout) {
|
|
14043
14345
|
// Nothing outside the CLI's own entry point passes a layout — the tests
|
|
14044
14346
|
// that call run() directly, an embedder. A lone workspace is the safe
|
|
@@ -14133,6 +14435,11 @@ export async function run(command, positional, flags, workspace, layout) {
|
|
|
14133
14435
|
if (positional[0] === "grade" && positional[1]) return evalGradeCmd(positional[1], flags, layout);
|
|
14134
14436
|
if (positional[0] === "compare" && positional[1]) return evalCompareCmd(positional[1], flags, layout);
|
|
14135
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);
|
|
14136
14443
|
// --to names a deployed workspace: its evals run there.
|
|
14137
14444
|
if (typeof flags.to === "string") return remoteEvalsCmd(positional[0], flags, layout);
|
|
14138
14445
|
// --last reads the platform's results; a local eval has none to read,
|
|
@@ -14149,6 +14456,7 @@ export async function run(command, positional, flags, workspace, layout) {
|
|
|
14149
14456
|
return observeCmd(flags, layout);
|
|
14150
14457
|
case "usage":
|
|
14151
14458
|
if (positional[0] === "compute") return usageComputeCmd(flags);
|
|
14459
|
+
if (positional[0] === "budget") return usageBudgetCmd(flags);
|
|
14152
14460
|
return usageCmd(flags);
|
|
14153
14461
|
case "workspace":
|
|
14154
14462
|
if (positional[0] === "vocabulary") return vocabularyCmd(flags, layout);
|
|
@@ -14195,6 +14503,7 @@ export async function run(command, positional, flags, workspace, layout) {
|
|
|
14195
14503
|
// the local store has no table to draw across workspaces, because a
|
|
14196
14504
|
// folder on a laptop is one workspace.
|
|
14197
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);
|
|
14198
14507
|
if (positional[0] === "views" && positional[1]) return runViewsEditCmd(positional.slice(1), flags);
|
|
14199
14508
|
if (positional[0] === "views") return runViewsCmd(flags);
|
|
14200
14509
|
// The run doctor (FOL-22): the assistant reads the run and its files,
|
|
@@ -14253,8 +14562,11 @@ export async function run(command, positional, flags, workspace, layout) {
|
|
|
14253
14562
|
case "docs":
|
|
14254
14563
|
return docsCmd(positional, flags);
|
|
14255
14564
|
case "billing":
|
|
14256
|
-
|
|
14257
|
-
|
|
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
|
+
});
|
|
14258
14570
|
case "library":
|
|
14259
14571
|
return libraryCmd(positional, flags);
|
|
14260
14572
|
case "preferences":
|