foldrun 17.0.1 → 17.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/bin/foldrun.mjs CHANGED
@@ -170,7 +170,8 @@ const HELP = `foldrun — agents are just folders
170
170
  foldrun runs views rm <name> delete a saved view (asks; --yes)
171
171
  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 (--to, --yes, --dry-run, --json)
172
172
  foldrun runs rm <run-id> delete a run's record and archived outputs (an admin); a live one is stopped first — asks first, --yes means it
173
- foldrun runs rm <run-id> <run-id>… delete several: lists them, asks once, then deletes each
173
+ foldrun runs rm <run-id> <run-id>… delete several: lists them, asks once, then deletes them in one runs/bulk call per workspace, as the dashboard does
174
+ foldrun runs rm --until <30d|date> delete every finished run that started before then — records, captured calls, archived outputs (an admin; --to <workspace>, --dry-run, --yes); live runs are left alone
174
175
  foldrun report <run-id> one run, whole: header, every step, what it wrote and what is still waiting
175
176
  foldrun report <run-id> get <agent>/<path> download a file the run archived from that agent's outputs/ (--file <path>|-, --force)
176
177
  foldrun report <run-id> --compare [<run-id>] beside the flow's last good run (or the one named): changed files and what differs step by step (--json)
@@ -304,6 +305,7 @@ Signing in
304
305
  foldrun a2a ls --to <ws> what a workspace serves over A2A: each flow's a2a:, card and endpoint URLs, its A2A keys (admins), recent tasks and the key that asked (--json)
305
306
  foldrun a2a publish <flow> set a2a: publish: true in the flow (--to <ws>: the deployed copy, an admin's) — --name, --description, --example "…" (repeatable), --public-card | --private-card; diff, checked, --dry-run
306
307
  foldrun a2a publish <flow> --clear-name | --clear-description | --clear-examples drop the card's name, description or examples (also on unpublish)
308
+ foldrun a2a publish <flow> --accept-risk <agent,…> accept that these agents hold a secret while they can run code (a2a: accept_risk, every one named; their answer goes to the caller) — without it such a flow is not published; --clear-accept-risk takes it out
307
309
  foldrun a2a unpublish <flow> a2a: publish: false — no outside agent may call it; the rest of a2a: is kept (--to <ws>, --dry-run)
308
310
  foldrun a2a card <flow> --to <ws> the flow's agent card URL and endpoint, then the card (a private card needs an A2A key in $FOLDRUN_A2A_KEY or --key-env)
309
311
  foldrun a2a call <card-url> "<text>" send one message to an A2A 1.0 agent — a published flow or anyone's — and wait for the task (--data <json|@file>, --context <id>, --no-wait or --return-immediately, --max-wait <s>, --json); the A2A key comes from $FOLDRUN_A2A_KEY or --key-env NAME, never this CLI's API key
@@ -388,6 +390,7 @@ Options
388
390
  --name / --abn / --address / --email billing details set: the invoice's legal name, ABN, "line1, city, state, postcode, AU", receipt email
389
391
  --clear-address / --clear-email / --clear-abn billing details set: drop that one from the invoice details, the rest kept
390
392
  --clear-name / --clear-description / --clear-examples a2a publish, a2a unpublish: drop that one from the card, the rest of a2a: kept
393
+ --accept-risk <agent,…> / --clear-accept-risk a2a publish: the agents accepted holding a secret while they can run code (a2a: accept_risk)
391
394
  --days <n> usage: the window the charges cover (default 56); status --platform --history: 1-90 (default 90); observe: the same as --since
392
395
  --id <revision> history: one revision in full, as diffs
393
396
  --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
@@ -491,9 +494,9 @@ if (!command || command === "--help" || command === "-h") {
491
494
  // `--value` as the account's argument and stored an empty secret; `--force
492
495
  // ./dir` swallowed the directory. A flag followed by another flag is also
493
496
  // boolean, so an unlisted switch at least does not eat its neighbour.
494
- const BOOLEAN_FLAGS = new Set(["read-only", "account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear", "security", "changed", "write-baseline", "no-baseline", "rules", "calls", "tree", "tool-error", "stop", "last", "no-pkce", "generate-key", "device", "write", "dpop", "export", "isolated", "no-wait", "dismissed", "unread", "team", "started", "mine", "none", "a2a", "public-card", "private-card", "return-immediately", "online", "overwrite", "no-send", "event-wait", "with-client", "use", "clear-name", "clear-description", "clear-examples", "clear-address", "clear-email", "clear-abn", "no-task", "empty"]);
497
+ const BOOLEAN_FLAGS = new Set(["read-only", "account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear", "security", "changed", "write-baseline", "no-baseline", "rules", "calls", "tree", "tool-error", "stop", "last", "no-pkce", "generate-key", "device", "write", "dpop", "export", "isolated", "no-wait", "dismissed", "unread", "team", "started", "mine", "none", "a2a", "public-card", "private-card", "return-immediately", "online", "overwrite", "no-send", "event-wait", "with-client", "use", "clear-name", "clear-description", "clear-examples", "clear-accept-risk", "clear-address", "clear-email", "clear-abn", "no-task", "empty"]);
495
498
  // Flags said more than once collect into a list: `--tag a --tag b`.
496
- const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove", "rule", "authorize-param", "example"]);
499
+ const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove", "rule", "authorize-param", "example", "accept-risk"]);
497
500
  // `--wait` is a switch everywhere but `flow add <flow> wait`, where it takes
498
501
  // a span: `--wait 30m`, `--wait event`. Only a value that reads as one is
499
502
  // taken, so `invoke x --wait` and friends are as they were.
package/docs/a2a.md CHANGED
@@ -31,6 +31,7 @@ a2a:
31
31
  type: object
32
32
  required: [city]
33
33
  properties: { city: { type: string } }
34
+ accept_risk: [researcher] # only if needed: see "Secret and code" below
34
35
  ---
35
36
 
36
37
  1. [[researcher]] — Find three leads for the request.
@@ -45,6 +46,7 @@ a2a:
45
46
  | `examples` | up to 10 example requests, 500 characters each |
46
47
  | `public_card` | `true` lets anyone read the card without a key. Calling the flow always needs one. Default `false` |
47
48
  | `input` | a JSON Schema (up to 16,000 bytes as JSON). With it, every request must carry a data part that matches it, and a request that does not is refused before anything starts |
49
+ | `accept_risk` | a list of this flow's agents that an admin accepts **holding a secret while they can run code** ([below](#secret-and-code-accept_risk)). Up to 50 names |
48
50
 
49
51
  A block `foldrun check` cannot read publishes nothing — a typo never opens a
50
52
  flow nobody meant to open. Whether a flow is published is the workspace's
@@ -73,6 +75,86 @@ the newest tasks with the key that asked.
73
75
  `foldrun check` warns on a published flow that is risky to open
74
76
  ([below](#security)).
75
77
 
78
+ ### Secret and code: `accept_risk`
79
+
80
+ The flow's answer goes back to the caller, so **the answer is a way out**.
81
+ An agent of a published flow that holds a secret in its sandbox and can run
82
+ code (`tools: [code]`, `Bash`) can be asked to print the secret into its
83
+ reply — no network needed. A secret reaches the sandbox when the agent lists
84
+ it in `secrets:`, an `apis:` header or a granted tool names it as `${NAME}`,
85
+ or a `web:` provider needs one. "Its agents" means every agent a run of the
86
+ flow can put to work: each step's, its `on-fail:` rescuer and `delegate:`
87
+ choices, the steps of every `[[flow:…]]` it runs, and their `subagents:`.
88
+
89
+ So the platform does not publish such a flow until an **admin** accepts it,
90
+ agent by agent:
91
+
92
+ ```yaml
93
+ a2a:
94
+ publish: true
95
+ accept_risk: [researcher]
96
+ ```
97
+
98
+ - Publishing (or keeping published while adding Bash or a secret) without it
99
+ is refused for everyone, admins too: `400`, `code: a2a_secret_code`, naming
100
+ the agent and what it holds. A name in `accept_risk` that no agent of the
101
+ flow answers to is refused (`a2a_accept_risk`), so an old entry never waits
102
+ to cover the next agent given that name.
103
+ - A published flow that already had such an agent before 5 Nov 2026 keeps
104
+ its files, but **takes no new task** until it is accepted: `SendMessage`
105
+ answers `NOT_SERVING`. Tasks already running are not stopped, and `GetTask`,
106
+ `ListTasks` and `CancelTask` still answer. The check runs every time a task
107
+ is admitted, against the files as they are then.
108
+ - Rather than accept: take Bash away (`disallowedTools: [Bash]`, or a step
109
+ without code), move the secret to an agent of a flow that is not published,
110
+ or bind the secret to its sites (`foldrun secrets sites NAME host`) so it
111
+ never enters the sandbox. The platform reads binding from the vault at each
112
+ check, and again before every task it starts, so unbinding it later stops
113
+ new tasks at once. `foldrun check`, offline, cannot see the vault and still
114
+ warns on a bound secret.
115
+ - Every acceptance is in the flow file's history (who, when, the diff) and in
116
+ the audit log as `a2a.risk_accepted` with the agent and what it holds.
117
+
118
+ The **Publish over A2A** control names each such agent before the first
119
+ publish and has an **Accept for <agent>** box (admins); Save stays off until
120
+ each is ticked. From the terminal:
121
+ `foldrun a2a publish <flow> --to <ws> --accept-risk <agent,…>` (every agent
122
+ accepted, as the list replaces the flow's; `--clear-accept-risk` takes it
123
+ out). `foldrun a2a ls --to <ws>` lists them, and
124
+ [`security/published-flow-secret-code`](checks#securitypublished-flow-secret-code)
125
+ is `foldrun check`'s warning.
126
+
127
+ ### An editor cannot widen a published flow
128
+
129
+ Publishing is an admin's decision about what the flow's agents can do. So
130
+ once a flow is published, a change that lets one of its agents reach **more**
131
+ needs the admin role too, by every door — the editor, `PUT /source`, a rename
132
+ or delete, a deploy, an import, a restore, a proposed fix:
133
+
134
+ - a new tool (a `{Bash: ask}` turned into a plain grant counts), secret, API,
135
+ MCP server, outside agent (`remotes:`), script or sub-agent; a changed API,
136
+ MCP or remote spec;
137
+ - a wider network — the agent's, or the workspace's `network:` in AGENTS.md
138
+ (a higher level, or a new site);
139
+ - a hook gone (the agent's own, or the workspace's `hooks:`),
140
+ `permissionMode: plan` dropped, `sandbox: own` added;
141
+ - a new agent behind the flow — a step, rescuer, delegate, sub-agent or
142
+ subflow that was not there.
143
+
144
+ An editor's write that does any of it is refused `403`
145
+ (`code: a2a_widening`), naming the agent, the flow and what widened; the rest
146
+ of a change goes through when they leave those alone. Prose, narrowing, and
147
+ removing a step or the flow stay an editor's. An admin's widening goes
148
+ through and is written to the audit log as `a2a.agent_widened`.
149
+ `foldrun deploy --dry-run` (`POST …/deploy { dryRun: true }`) says
150
+ `policy: { status, code, error }` when the real deploy would be refused.
151
+
152
+ What this does not cover: the **code** of a script, hook or folder tool, and
153
+ an agent's prose, stay an editor's — they change how an agent uses what it
154
+ has, not what it has. A change to the account library (`/api/library`) is
155
+ not checked here; the serve-time check above still refuses new tasks for a
156
+ secret-and-code agent it creates.
157
+
76
158
  ## A2A keys
77
159
 
78
160
  A caller needs an **A2A key**: a key of its own kind, minted by an admin of
@@ -89,8 +171,10 @@ shown once.
89
171
  - It opens `/a2a/<account>/<workspace>/…` for its flows and nothing else.
90
172
  Every `/api` route refuses it (`403`): not runs, not source, not approvals,
91
173
  not storage, not secrets.
92
- - A flow must be both **named by the key** and **published**. Both are read
93
- on every call, so unpublishing a flow closes it to every key at once.
174
+ - A flow must be both **named by the key** and **published**. A key is
175
+ minted for published flows only (since 5 Nov 2026 — publish first, then
176
+ mint); both are read again on every call, so unpublishing a flow closes it
177
+ to every key at once.
94
178
  - `maxTasks` — its tasks open at once, 1 to 100, default 10. Past it,
95
179
  `SendMessage` is refused with `TOO_MANY_TASKS` until one ends or is
96
180
  canceled.
@@ -242,6 +326,7 @@ request foldrun cannot take **now** is `-32000` with a foldrun reason:
242
326
  | `UNAVAILABLE` | out of budget or funds, or otherwise not taking work |
243
327
  | `RATE_LIMITED` | the key's rate limit (`429` from the proxy carries `Retry-After`) |
244
328
  | `TOO_MANY_TASKS` | the key has `maxTasks` open |
329
+ | `NOT_SERVING` | an agent of the flow holds a secret and can run code, and no admin has accepted it ([accept_risk](#secret-and-code-accept_risk)) — the caller is told nothing more |
245
330
  | `UNAUTHENTICATED` | no key, or a wrong, revoked or expired one (HTTP `401`) |
246
331
  | `PERMISSION_DENIED` | a key that is not an A2A key (HTTP `403`) |
247
332
  | `AGENT_NOT_FOUND` | the flow is not published, not named by the key, or not there — all alike (HTTP `404`) |
@@ -311,14 +396,27 @@ Ended tasks are kept 90 days.
311
396
  as data, fenced; your tool grants, network, bound secrets and human gates
312
397
  hold whatever it says. Publishing does not widen what an agent may do — it
313
398
  widens who can ask.
314
- - **`foldrun check` warns on two shapes** of published flow (warnings, not
399
+ - **The answer is a way out.** The last step's answer goes to the caller, so
400
+ an agent that holds a secret and can run code is refused publishing and new
401
+ tasks until an admin accepts it ([accept_risk](#secret-and-code-accept_risk)),
402
+ and an editor cannot widen any agent of a published flow
403
+ ([above](#an-editor-cannot-widen-a-published-flow)).
404
+ - **`foldrun check` warns on three shapes** of published flow (warnings, not
315
405
  errors): [`security/published-flow-trifecta`](checks#securitypublished-flow-trifecta)
316
- — a step agent that holds something private and has a way out, which a
317
- caller could steer into sending it; and
406
+ — an agent of the flow that holds something private, which a caller could
407
+ ask for in the answer or steer into sending;
408
+ [`security/published-flow-secret-code`](checks#securitypublished-flow-secret-code)
409
+ — one that holds a secret and can run code (info once accepted); and
318
410
  [`security/published-flow-ungated`](checks#securitypublished-flow-ungated)
319
411
  — a step that acts outside the workspace with no approval or `ask:` before
320
412
  it, which any key holder starts. Put a gate (`2!.`) on it, or take a leg
321
413
  away.
414
+ - **Left as they are** (FOL-112 N7, N8): one key can hold up to its
415
+ `maxTasks` runs waiting in the approvals queue — `maxTasks` bounds it; give
416
+ a partner's key a small one. A card URL carries the account and workspace
417
+ names (`/a2a/<account>/<ws>/…`) — treat them as disclosed to every key
418
+ holder, and to everyone when `public_card: true`; name a workspace you
419
+ publish from accordingly.
322
420
  - **A public card is metadata only**: the name, description and examples you
323
421
  wrote, the endpoint and the auth scheme — never steps, agents or files.
324
422
  It never lets anyone call the flow. Anonymous card reads are rate-limited.
package/docs/agents.md CHANGED
@@ -515,10 +515,29 @@ always. A name is checked against Debian's own naming rule, so it can never
515
515
  become an apt option. The first step that needs a set installs it with apt and
516
516
  saves the result as a snapshot in the account's runtime cache; every later
517
517
  step restores the snapshot instead, in about a second (154 packages, 432 MB:
518
- 30 s through apt, under 1 s from the snapshot). A new runner image gets new
519
- snapshots of its own, never the old one's files. The run log says
520
- `system packages ready: … (snapshot, 1s)` or `(apt, 30s)`, or fails the step
521
- with apt's own reason. On a laptop (`foldrun run` with no container) there is nothing to
518
+ 30 s through apt, under 1 s from the snapshot). A snapshot belongs to the
519
+ runner image it was built on: it is restored only onto an image whose
520
+ installed packages are exactly the same, because the files in it were built
521
+ against those packages. A release whose image did not move any package keeps
522
+ it; one that did (a Debian security update, a new Chrome) builds a new
523
+ snapshot beside the old one the first time the set is needed — the run log
524
+ then says `(apt, 30s, 1 snapshot did not fit this image)`. A snapshot is
525
+ rebuilt 14 days after it was made, so the packages in it pick up Debian's
526
+ fixes. The run log says `system packages ready: … (snapshot, 1s)` or
527
+ `(apt, 30s)`, or fails the step with apt's own reason.
528
+
529
+ A snapshot is written into the account's runtime cache, which steps can
530
+ write — and it is restored as root. So it is **sealed**: the platform keeps a
531
+ key for each account that steps never see, and a snapshot is restored only if
532
+ its seal, made with that key when the start-up built it, matches the package
533
+ set, the image and every byte of the file. A snapshot a step rewrote, or one
534
+ whose seal does not match, is not restored; the step installs with apt and the
535
+ run log says why on the next line — `snapshot refused: its contents do not
536
+ match its seal`. Even a sealed snapshot can only put package files where
537
+ packages go (`/etc`, `/usr`, `/var`, `/opt`), never a setuid file, a device,
538
+ or anything through a link or a folder a step could change. A package set
539
+ that installs a setuid program is installed with apt every time
540
+ (`no snapshot kept: … is setuid or setgid`). On a laptop (`foldrun run` with no container) there is nothing to
522
541
  install into: the list is reported as assumed present.
523
542
 
524
543
  Manim, for one, needs all four of its kinds at once:
@@ -579,9 +598,12 @@ destroyed when the step ends.
579
598
  The agent is never root. A Debian package is installed by a small helper the
580
599
  container's root start-up leaves running before it drops to the agent user;
581
600
  the agent can only ask it, by name, and each name is checked against Debian's
582
- naming rule, so nothing but a package name reaches apt. It uses the same cache
583
- and snapshots as `runtime: system:`, so a package anyone in the account
584
- installed before is back in about a second. pip and npm packages need no root
601
+ naming rule, so nothing but a package name reaches apt. It restores the same
602
+ snapshots as `runtime: system:`, so a set the account's steps declare is back
603
+ in about a second; it never saves one, because it runs beside the agent's own
604
+ code, and only a step's start-up, before any of that code exists, seals a
605
+ snapshot. Declare a package in `runtime: system:` to have it from a snapshot.
606
+ pip and npm packages need no root
585
607
  and are installed as the agent, into a directory of the step's own.
586
608
 
587
609
  A pip or npm package runs none of its own code on the way in. npm installs
package/docs/api.md CHANGED
@@ -140,7 +140,7 @@ agent wrote that the push does not mention.
140
140
 
141
141
  | Route | Methods | |
142
142
  |---|---|---|
143
- | `/api/workspaces/<ws>/deploy` | POST | deploy the whole workspace from a list of files — checked as a whole first, refused with `422` and `issues` when it does not check out. `dryRun`, `force`, `expectRemoved` below. 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)); a dry run is not refused. Idempotent |
143
+ | `/api/workspaces/<ws>/deploy` | POST | deploy the whole workspace from a list of files — checked as a whole first, refused with `422` and `issues` when it does not check out. `dryRun`, `force`, `expectRemoved` below. 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)); a dry run is not refused, and answers `policy: { status, code, error }` when the real deploy would be. Behind a flow published over A2A, an editor's deploy that widens an agent is `403` `code: a2a_widening`, and anyone's that makes a secret-and-code agent with no `a2a: accept_risk` is `400` `code: a2a_secret_code` — on every write door: this, `PUT`/`PATCH`/`DELETE /source`, import, restore, a proposed fix ([A2A](a2a.md#an-editor-cannot-widen-a-published-flow)). Idempotent |
144
144
  | `/api/workspaces/<ws>/runtimes` | GET | the `runtime:` builds a deploy started, each with its `state` — below. `404` when the workspace does not exist |
145
145
 
146
146
  `GET /api/workspaces/<ws>/runtimes` answers what a deploy started on the
@@ -156,8 +156,8 @@ installer's `error`, its cause on the first line. `foldrun deploy` polls it afte
156
156
  | Route | Methods | |
157
157
  |---|---|---|
158
158
  | `/api/workspaces/<ws>/flows` | GET, POST | list; create (`name`, `pattern`) |
159
- | `/api/workspaces/<ws>/a2a` | GET | what this workspace serves to outside agents over A2A 1.0: `{ flows: [{ flow, published, publicCard, name, description, hasInputSchema, card, url }], keys, tasks: [{ id, flow, state, runId, contextId, key: { id, label, prefix, revoked }, createdAt, updatedAt }] }` — every flow whose frontmatter says `a2a:`, the URL of its agent card and of its JSON-RPC endpoint (`/a2a/<account>/<ws>/flows/<flow>`), the workspace's live A2A keys (`[{ id, label, prefix, flows, maxTasks, expiresAt }]`, or `null` unless you may manage keys), and the 50 newest A2A tasks (`state` a `TASK_STATE_*`) with the key that asked. Publishing is the flow's `a2a:` field, written like any other — changing it needs `workspace:manage`. `404` when the workspace does not exist |
160
- | `/api/workspaces/<ws>/flows/<flow>` | POST, PATCH, DELETE | edit a step (`step`, `instruction`, `options`, `target`, `subflow`), rearrange (`groups`), set `trigger`, set `compute` (`{ vcpu, memGiB, diskGiB }` or `null` — what one run may hold at once, merged over what the flow says), set `a2a` (`{ publish, name, description, examples, public_card, input }` merged over the flow's `a2a:` — a key sent replaces it, `null` removes it; `a2a: null` removes the block; refused `400` when the result would not read, `403` without the admin role — see [A2A](a2a.md)), a canvas edit (`edit`, or `edits` — at most 200 in one request, `400` past that), undo (`restore` + `expect`); delete. Every PATCH and DELETE takes `expect` — the text the step numbers were read from, or its sha256 — and is refused with `409` and the current `text`, nothing written, when the file no longer reads it (the canvas, the list view's board and step options, and the CLI's `flow add`/`rm-step`/`dup-step --to` send it; the dashboard shows the 409 as "this flow changed since you opened it — reload") |
159
+ | `/api/workspaces/<ws>/a2a` | GET | what this workspace serves to outside agents over A2A 1.0: `{ flows: [{ flow, published, publicCard, name, description, hasInputSchema, acceptRisk, card, url }], risks: [{ flow, agent, secrets, accepted }], keys, tasks: [{ id, flow, state, runId, contextId, key: { id, label, prefix, revoked }, createdAt, updatedAt }] }` — every flow whose frontmatter says `a2a:`; `risks`, every flow's agents (published or not) that hold a secret and can run code, with whether its `a2a: accept_risk` names them — a published flow with one not accepted takes no new task ([accept_risk](a2a.md#secret-and-code-accept_risk)); the URL of its agent card and of its JSON-RPC endpoint (`/a2a/<account>/<ws>/flows/<flow>`), the workspace's live A2A keys (`[{ id, label, prefix, flows, maxTasks, expiresAt }]`, or `null` unless you may manage keys), and the 50 newest A2A tasks (`state` a `TASK_STATE_*`) with the key that asked. Publishing is the flow's `a2a:` field, written like any other — changing it needs `workspace:manage`. `404` when the workspace does not exist |
160
+ | `/api/workspaces/<ws>/flows/<flow>` | POST, PATCH, DELETE | edit a step (`step`, `instruction`, `options`, `target`, `subflow`), rearrange (`groups`), set `trigger`, set `compute` (`{ vcpu, memGiB, diskGiB }` or `null` — what one run may hold at once, merged over what the flow says), set `a2a` (`{ publish, name, description, examples, public_card, input, accept_risk }` merged over the flow's `a2a:` — a key sent replaces it, `null` removes it; `a2a: null` removes the block; refused `400` when the result would not read, `403` without the admin role, `400` `code: a2a_secret_code` when an agent of the published flow holds a secret and can run code and `accept_risk` does not name it — see [A2A](a2a.md)), a canvas edit (`edit`, or `edits` — at most 200 in one request, `400` past that; adding a step is `edit: { op: "insert", target, subflow?, instruction?, at: { rail } }`, removing one `edit: { op: "remove", step }`), undo (`restore` + `expect`). POST (`{ target, subflow?, instruction? }`, a step at the end) and DELETE (`{ step, expect? }`) make the same two edits and are deprecated since 5 Nov 2026 — every client (the canvas, the list view's board, the CLI) sends PATCH `{ edit }`, so one mechanism does each change; they still answer, with `Deprecation` headers. Every PATCH and DELETE takes `expect` — the text the step numbers were read from, or its sha256 — and is refused with `409` and the current `text`, nothing written, when the file no longer reads it (the canvas, the list view's board and step options, and the CLI's `flow add`/`rm-step`/`dup-step --to` send it; the dashboard shows the 409 as "this flow changed since you opened it — reload") |
161
161
  | `/api/workspaces/<ws>/flows/draft` | POST, PATCH, DELETE | POST draft a flow with a model: `{ description, flow? }` (`flow` redrafts that one). Returns `{ ok, files: [{ path, content, before, sha256 }], issues: [{ where, message, level }], repaired, notes }` — checked with the deploy's checks and the flow lint, repaired once. **Writes nothing**; save with the source PUT. Needs `workspace:write`; a description over 4,000 characters is `413`; a Chat-Completions `provider:` is `422`. On the platform's models the balance is checked first (`402`) and the call is charged as one ledger line, flow `ai-draft`. PATCH and DELETE, and a POST without `description`, are the edits of a flow that happens to be named `draft`, exactly as at `flows/<flow>` |
162
162
  | `/api/workspaces/<ws>/flows/<flow>/run` | POST | start it. An `Idempotency-Key` header, or `idempotencyKey` in the body, makes a retried call safe: a dropped response, a proxy timeout or a CI step that ran twice is answered `started: false` with the `runId` it already started, rather than starting a second run and billing for it. Keys are remembered for 24 hours, per flow. While the account has its most runs waiting for their turn it answers 409 `{ error, code: "waiting_cap", limit, waiting }` and starts nothing ([how many runs may wait](budgets-and-billing#how-many-runs-may-wait)); so do the agent run and rerun routes (an A2A caller is told the agent is busy), and a webhook or inbound email gets the same as a 503 with `Retry-After: 60` |
163
163
  | `/api/workspaces/<ws>/flows/<flow>/filter` | POST | test the flow's `filter:` against a delivery without starting anything: `{ payload }` — a webhook's JSON body (or the body as a string, read as JSON), an email's `{ from, to, subject, text }`, a chained run's `{ run, flow, status, ending, verdict, summary }`, a storage event's `{ by, paths }`. Answers `{ flow, trigger, filter, applies, match, reason }` — `reason` names the first condition that failed; a flow with no filter matches everything. Reads the deployed flow; nothing is recorded or charged |
@@ -223,15 +223,15 @@ paying for the steps around it.
223
223
 
224
224
  | Route | Methods | |
225
225
  |---|---|---|
226
- | `/api/workspaces/<ws>/runs?limit=&before=` | GET | `{ runs: [{ id, flow, status, verdict, outcome, startedAt, finishedAt, ... }], next }`, newest first; `next` is the cursor for the page after (`<startedAt>~<runId>`, null on the last page) — pass it back as `before`, which also takes a time (runs that started before it) or a run id of the workspace (runs older than it); a position, not an offset, so runs starting meanwhile shift nothing and one cursor pages every workspace (`foldrun runs --before`, `--page`, `--all`); a `before` that is none of these is a `400`; search (see [Runs](runs#searching-runs)) with `tool` (a step called a tool whose name contains it), `tool_error=1`, `agent`, `model` (contains), `min_tokens` (`50k`), `min_secs` — `limit` counts the matches — `verdict` is the word the summary leads with (`GOOD`, `QUIET`, `BLOCKED`, `BAD` or null) and `outcome` the one word every page shows (`running`, `queued`, `waiting`, `good`, `done`, `quiet`, `blocked`, `bad`, `failed`, `stopped`); `failure` is `{ agent, reason }` for a run that failed (null otherwise), `chargedUsd` is what the account was charged for the run (one credit is one cent), null until the ledger settles it, while `costUsd` is the provider's token cost — off the run index (see [Runs](runs#the-runs-list)); a finished run's steps carry `agent`, `status`, `costUsd` and `tokens` (`{ input, output, cacheRead, cacheWrite }`, see [Runs](runs#the-record)), and the run its summed `tokens` — not their reply or trace |
226
+ | `/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 why a run failed (null otherwise) — `{ agent, reason, class, kind, message, fix }` and, for a limit, `used`, `allowed`, `unit` and `scope`, for a refused site `host` (see [Runs](runs#why-it-failed)), `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 |
227
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) |
228
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 |
229
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) |
230
- | `/api/workspaces/<ws>/runs/<id>` | GET, DELETE | the whole run: every step, its output, cost, timing, the runner `image` it ran on and — for a step that browsed through the account's pod from slim — its `browserPod` reconnects and fallback ([runs](runs#the-record)). `?wait=true&timeout=<s>` instead blocks until the run stops (or `timeout`, default 300, max 900) and answers the verdict the run routes give — `200` once the run has ended, however it ended: `ok: true` when it completed, `ok: false` with its `status` and `failure: { agent, reason }` when it failed or was stopped (a run that fails is the answer, not a fault in the call — it was a `500` before 29 Oct 2026); `202` still going (`timedOut`) or parked on a person (`awaitingApproval`). A start refused before any run exists — a paused account or workspace (`423`), an agent or flow that is not there (`404`), `overlap: skip` (`409`) — is answered as such and waits for nothing. Ask in short pieces: whatever sits in front of the platform cuts a request that stays silent too long (Cloudflare at 100 s, an AWS ALB at 60 s), and a flow can run for many minutes — the CLI's `--wait` asks 25 s at a time and comes back here on every `202`. DELETE erases the run's record and archived outputs (a run still going is stopped first; the ledger line stays) and needs `workspace:manage` — an admin — since 30 Oct 2026 (it was `run:start`) |
231
- | `/api/workspaces/<ws>/runs/<id>/stream` | GET | server-sent events, live |
230
+ | `/api/workspaces/<ws>/runs/<id>` | GET, DELETE | the whole run: every step, its output, cost, timing, `failure` (why it failed, the same object the runs list gives — see [Runs](runs#why-it-failed); null when it did not), the runner `image` it ran on and — for a step that browsed through the account's pod from slim — its `browserPod` reconnects and fallback ([runs](runs#the-record)). `?wait=true&timeout=<s>` instead blocks until the run stops (or `timeout`, default 300, max 900) and answers the verdict the run routes give — `200` once the run has ended, however it ended: `ok: true` when it completed, `ok: false` with its `status` and `failure` when it failed or was stopped (a run that fails is the answer, not a fault in the call — it was a `500` before 29 Oct 2026); `202` still going (`timedOut`) or parked on a person (`awaitingApproval`). A start refused before any run exists — a paused account or workspace (`423`), an agent or flow that is not there (`404`), `overlap: skip` (`409`) — is answered as such and waits for nothing. Ask in short pieces: whatever sits in front of the platform cuts a request that stays silent too long (Cloudflare at 100 s, an AWS ALB at 60 s), and a flow can run for many minutes — the CLI's `--wait` asks 25 s at a time and comes back here on every `202`. DELETE erases the run's record and archived outputs (a run still going is stopped first; the ledger line stays) and needs `workspace:manage` — an admin — since 30 Oct 2026 (it was `run:start`) |
231
+ | `/api/workspaces/<ws>/runs/<id>/stream` | GET | server-sent events, live: `run` (the whole record, each time it changes), `done` (`{ status }`) at the end. A stream that cannot start is refused like every other route — `401`/`403`/`404` with `{ error }` JSON (before 5 Nov 2026 it was plain text). The dashboard's run page and `foldrun logs --follow` (and `invoke --watch`, `agent run --wait`) read it |
232
232
  | `/api/workspaces/<ws>/runs/<id>/stop` | POST | destroys the sandbox, not just the record. `404` for no such run, `409` for one already finished |
233
233
  | `/api/workspaces/<ws>/runs/<id>/rerun` | POST | again — `step` to start partway, or `agent` to start at the first step that agent runs (one of the two is required). `instruction` tells that step something else this once, in place of the flow's (the flow file is not changed); the new run's `rerunOf` says `{ run, step, instruction }`. Takes `?wait=true&timeout=` like a flow start. `404` for no such run, `409` for one not finished, `400` for a `step` that is not a whole number |
234
- | `/api/workspaces/<ws>/runs/bulk` | POST | one action on many runs at once. `action` is `stop` or `rerun`; the runs are named by any of `runIds`, `status`, `flow`, `since`, `until`, AND-ed together (`status: ["stopped"]` names a run a person stopped, whose record says `failed`; `failed` names it too), and a call naming none of them is refused rather than treated as "everything". `from` picks the step a rerun starts at, `dryRun: true` answers with what would be touched and touches nothing. At most 100 runs per call — past that it answers `422` with the count, because a filter matching more than that is almost certainly the wrong filter. Each run is its own outcome: the reply carries `matched`, `succeeded`, `failed` and a `runs` array, so one run that finished a second ago does not abort the other thirty |
234
+ | `/api/workspaces/<ws>/runs/bulk` | POST | one action on many runs at once. `action` is `stop`, `rerun` or `delete`; the runs are named by any of `runIds`, `status`, `flow`, `since`, `until`, AND-ed together (`status: ["stopped"]` names a run a person stopped, whose record says `failed`; `failed` names it too), and a call naming none of them is refused rather than treated as "everything". `from` picks the step a rerun starts at (a delete is refused one). `delete` is what DELETE `…/runs/<id>` does, run by run — a run still going is stopped first, its record and archived outputs go, the ledger line stays — and needs the same admin permission (`workspace:manage`); the runs list's selection bar and `foldrun runs rm <id> <id>…` use it. `dryRun: true` answers with what would be touched and touches nothing. At most 100 runs per call — past that it answers `422` with the count, because a filter matching more than that is almost certainly the wrong filter. Each run is its own outcome: the reply carries `matched`, `succeeded`, `failed` and a `runs` array, so one run that finished a second ago does not abort the other thirty. With a filter instead of ids (`until`, `since`, `status`, `flow`), `delete` (5 Nov 2026) erases finished runs — record, captured calls, archived outputs; the ledger lines stay — for "everything that started before" a date (`until`): it needs `workspace:manage` (an admin), dry runs too; a live run is never in it (stop it, or delete it alone, which stops it first); each run's status is read again right before it goes; and more than 100 matches is not a `422`: the call deletes 100 and answers `remaining`, so the caller asks again (`foldrun runs rm --until 30d` does) |
235
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 |
236
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 |
237
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}` |
@@ -366,7 +366,7 @@ Reads return which secrets exist, never their values.
366
366
 
367
367
  | Route | Methods | |
368
368
  |---|---|---|
369
- | `/api/keys` | GET, POST, DELETE | API keys — an admin's (`keys:manage`) to list, mint and revoke; any key may revoke itself (DELETE with its own `id`, audited as self — what `foldrun logout` does). POST `label`, `role` (viewer \| editor \| admin, never above your own, default editor), `workspaces` (names, or `null` for all — never wider than your own scope); `expires` (`30d`, `90d`, `365d`, any number of days up to 3650, or `never` — the default; anything else is a 400, never a key that lives forever); returns `{ ok, key, id, prefix, role, workspaces, expiresAt }`. POST `{ purpose: "a2a", workspace, flows, maxTasks?, label?, expires? }` mints an A2A key instead: for an outside agent, it opens `/a2a/<account>/<workspace>/…` for the named flows (each must also say `a2a: { publish: true }`) and every `/api` route refuses it (403); `maxTasks` (1–100, default 10) caps its tasks open at once; it answers `{ ok, key, id, prefix, purpose, workspace, flows, maxTasks, role, workspaces, expiresAt }`, and rotating one keeps the tasks it made, and the key is shown once. GET lists each key with `createdAt`, `createdBy`, `expiresAt`, `lastUsedAt`, `lastIp` and `replacedBy` (the id of the key a rotation replaced it with; `null` until then) — the last-use pair written at most once a minute per key, the address cut to its /24 (IPv4) or /48 (IPv6). A key past its `expiresAt` is refused with 401 `API key expired on <date>`; the owner is emailed seven days before. Mint, revoke and rotate are written to the audit log. POST with `workspace` or `access` is refused (400): those minted deploy keys for the platform's own git, which went on 17 Oct 2026 — a deploy key minted before is refused everywhere (403). A key for one workspace is `workspaces: ["<ws>"]`. DELETE `id`. `?tenant=` / body `tenant` is read only on an install with no users yet (first-run bootstrap), and there, when the install has a setup token (`FOLDRUN_SETUP_TOKEN`, written by the self-hosting installer), only with that token in `X-Foldrun-Setup-Token` |
369
+ | `/api/keys` | GET, POST, DELETE | API keys — an admin's (`keys:manage`) to list, mint and revoke; any key may revoke itself (DELETE with its own `id`, audited as self — what `foldrun logout` does). POST `label`, `role` (viewer \| editor \| admin, never above your own, default editor), `workspaces` (names, or `null` for all — never wider than your own scope); `expires` (`30d`, `90d`, `365d`, any number of days up to 3650, or `never` — the default; anything else is a 400, never a key that lives forever); returns `{ ok, key, id, prefix, role, workspaces, expiresAt }`. POST `{ purpose: "a2a", workspace, flows, maxTasks?, label?, expires? }` mints an A2A key instead: for an outside agent, it opens `/a2a/<account>/<workspace>/…` for the named flows (each must say `a2a: { publish: true }` when the key is minted — a flow not published is refused, 400 — and still say it on every call) and every `/api` route refuses it (403); `maxTasks` (1–100, default 10) caps its tasks open at once; it answers `{ ok, key, id, prefix, purpose, workspace, flows, maxTasks, role, workspaces, expiresAt }`, and rotating one keeps the tasks it made, and the key is shown once. GET lists each key with `createdAt`, `createdBy`, `expiresAt`, `lastUsedAt`, `lastIp` and `replacedBy` (the id of the key a rotation replaced it with; `null` until then) — the last-use pair written at most once a minute per key, the address cut to its /24 (IPv4) or /48 (IPv6). A key past its `expiresAt` is refused with 401 `API key expired on <date>`; the owner is emailed seven days before. Mint, revoke and rotate are written to the audit log. POST with `workspace` or `access` is refused (400): those minted deploy keys for the platform's own git, which went on 17 Oct 2026 — a deploy key minted before is refused everywhere (403). A key for one workspace is `workspaces: ["<ws>"]`. DELETE `id`. `?tenant=` / body `tenant` is read only on an install with no users yet (first-run bootstrap), and there, when the install has a setup token (`FOLDRUN_SETUP_TOKEN`, written by the self-hosting installer), only with that token in `X-Foldrun-Setup-Token` |
370
370
  | `/api/keys/<id>/rotate` | POST | a new key with the old one's label, role, workspaces and deploy scope — and, when it had an end, the same lifetime from today — returned once like a mint (`{ ok, key, id, prefix, role, workspaces, expiresAt, replaced: { id, endsAt } }`). `grace`: `0` (default — the old key is revoked at once), or a duration up to `7d` such as `1h` or `24h`, during which the old key still works and after which it is refused as expired. A key is rotated once: rotating a key already replaced is 409 `this key was already rotated to <prefix>…; rotate that one` — and someone who lost the new key's secret rotates the NEW key, which mints another and ends the lost one (rotating the old one again would leave the lost key working). Two rotations of one key at once mint one key. `keys:manage`; a key outside the caller's scope is 404 — except that a key `foldrun login` minted may rotate **itself**, whatever its role: same label, role, workspaces and 90-day lifetime from today, the old key ending 10 minutes later (`grace` is not read). A retry with the old key inside those 10 minutes — the CLI lost the answer, or could not store it — rotates that replacement instead, when nobody has used it and it is at least 30 seconds old (a younger one is a 409: another command may have just stored it). That is how the CLI renews its sign-in; any other key rotating itself still needs `keys:manage`. Audited as `apikey.rotated` (`self: true` for a self-rotation). A `foldrun login` key stays one only when it renews itself or its own person rotates it, signed in; rotated by any other caller the new key is an ordinary one |
371
371
  | `/api/team` | GET, POST | members with their roles and workspace scope; mint an invite (a session, or the person's own `foldrun login` key, which invites no admin) — `role` (viewer \| editor \| admin, default editor), `workspaces` (names, or omit for all), `email` (only that address can accept it; sent through the account's `RESEND_API_KEY` unless `send: false`). An invite works **once**, for seven days, and a newer invite to the same address revokes the older ones still pending. Returns `id`, `path` (the invite's relative URL, shown only here), `expires`, `sent` and any `sendError` either way; the full link is in the mail. Links made before 29 Oct 2026 (`inv1`–`inv3`) are refused |
372
372
  | `/api/team/invites?all=1` | GET | the account's invites, newest first — pending ones unless `all=1` (then accepted, revoked and expired too): `{ invites: [{ id, email, role, workspaces, invitedBy, createdAt, expiresAt, status }] }`, `email` `null` for a link anyone may use, `workspaces` `null` for all, `status` `pending` \| `accepted` \| `revoked` \| `expired`. Never the link. `team:manage` — an admin key included; a caller scoped to some workspaces sees only the invites inside its scope |
@@ -395,7 +395,7 @@ Reads return which secrets exist, never their values.
395
395
  | `/api/account/flags` | GET | the feature flags as they stand for this account — `{ flags: [{ name, description, owner, default, on, source, rollout }] }`, `source` being what decided it: `account` (an override for this account), `global` (the install-wide setting), `rollout` (a percentage of accounts, by a stable hash of account and flag; `rollout` is the percentage) or `default`. Read-only, every role; only the platform's operator changes a flag (a self-hosted install runs every flag at its default). See [Feature flags](feature-flags.md) |
396
396
  | `/api/openapi.json` | GET | this API as an OpenAPI 3.1 document — every route and method, bearer auth, the rate-limit, version and Idempotency-Key headers, and request/response schemas for runs, flow runs, deploy, source, secrets, keys and billing. No key needed. Generated from the route files by `scripts/gen-openapi.mjs`; the dashboard renders it at Docs → API reference, `foldrun api spec` saves it |
397
397
  | `/api/account` | GET, PATCH | the account's defaults from its AGENTS.md frontmatter — `timezone`, `budget` (a USD cap — a number for a month, `"60/day"`, `"60/week"`, or `{ usd, period }`; null is no limit), `notify` (`{ url?, email?, events }`), `concurrency`, `compute` (`{ vcpu, memGiB, diskGiB }` — the account's own cap on what its running steps hold together, lower than the plan's; PATCH writes it as `compute: { vcpu, memory, disk }`, merged over what is set: a figure not sent is kept, `null` drops one, `compute: null` drops all), `deploy_block` (`none`, `secrets` or `security` — answered as `deployBlock`), `network_enforce` (answered as `networkEnforce`), `owner`, `alerts` (as written), `judge` (`{ model?, effort? }`), `telemetry` (`{ otlp, headers }` — header values are `${SECRET}` names; answered as `{ endpoint, headers }`); PATCH sets the keys sent, null clears one, and edits the file in place. To a caller scoped to some workspaces GET says these are set, never where they go: `notify` loses its `url` and carries `hidden: true` when one is set, and `telemetry` is `{ endpoint: "", headers: {}, hidden: true }`. PATCH needs every workspace |
398
- | `/api/audit?since&until&action&actor&workspace&limit&cursor&format` | GET | the account's audit log, newest first — the caller's account only, whatever a header, query or body names. The owner and unscoped admins (people, or `admin` keys); `audit:read`, and refused to a member or key scoped to some workspaces, because the log is the whole account's. `since`/`until`: `7d`, `24h`, `30m` or a date; `action`: exact (`apikey.created`) or a family (`apikey`); `actor`: exact (an email, `key:<label>`, `support:<email>`); `workspace`: entries about one; `limit` 1–1000 (100; 1000 for CSV); `cursor`: the `next` of the page before. JSON `{ entries: [{ id, at, actor, action, subject, detail }], next, retention }`; `format=csv` downloads the same rows (`x-next-cursor` header when there are more). Records sign-ins and refusals, sign-outs, session revokes, password and email changes, MFA on/off, key mint/rotate/revoke, invites, joins, role/scope changes, removals, ownership transfers, secrets set/deleted (by name — never a value), deploys, workspace deletes, plan and billing changes, export and close requests, and `support.viewed`/`support.ended`. The platform operator's own levers (`operator.*`) are the platform's record and not listed. Kept for the life of the account |
398
+ | `/api/audit?since&until&action&actor&workspace&limit&cursor&format` | GET | the account's audit log, newest first — the caller's account only, whatever a header, query or body names. The owner and unscoped admins (people, or `admin` keys); `audit:read`, and refused to a member or key scoped to some workspaces, because the log is the whole account's. `since`/`until`: `7d`, `24h`, `30m` or a date; `action`: exact (`apikey.created`) or a family (`apikey`); `actor`: exact (an email, `key:<label>`, `support:<email>`); `workspace`: entries about one; `limit` 1–1000 (100; 1000 for CSV); `cursor`: the `next` of the page before. JSON `{ entries: [{ id, at, actor, action, subject, detail }], next, retention }`; `format=csv` downloads the same rows (`x-next-cursor` header when there are more). Records sign-ins and refusals, sign-outs, session revokes, password and email changes, MFA on/off, key mint/rotate/revoke, invites, joins, role/scope changes, removals, ownership transfers, secrets set/deleted (by name — never a value), deploys, workspace deletes, plan and billing changes, export and close requests, and `support.viewed`/`support.ended`. The platform operator's own levers (`operator.*`) are the platform's record and not listed. Kept 365 days (`audit.retention_days`; an install without a database keeps its file-backed log), and no longer than the account |
399
399
  | `/api/avatars/<kind>/<id>` | GET, PUT, DELETE | a picture for a `user` (their own id), a `workspace` (its name) or the `account` (the tenant). PUT the bytes of a PNG, JPEG or WebP under 1 MB; a person sets their own, an admin a workspace's or the account's. GET needs a signed-in tenant — a workspace's picture, a caller who may open that workspace (403 otherwise) — and is privately cached for a year — the URL's `?v=` changes with the picture |
400
400
  | `/api/search?q=` | GET | find anything in the account by name — workspaces, agents, flows, tools, skills, knowledge, memory, runs (by id, flow or headline); ranked, at most six per kind. The dashboard's Find palette reads it |
401
401
  | `/api/schedule` | GET, POST | GET: every scheduled flow with `valid` (the cron parses) and `upcoming` (the next three fires). POST: tick the scheduler now for this account alone — its due cron, `once:` and watch flows go now (they were due anyway); `workspace:manage` over every workspace; returns `{ ok, fired }`. An impossible cron (`0 0 30 2 *`) is `valid` with `upcoming: []` |
@@ -165,6 +165,48 @@ that is running.
165
165
  show *N of M runs waiting for their turn* (`runsWaiting` in
166
166
  `GET /api/usage/compute`).
167
167
 
168
+ ### Fair share across accounts
169
+
170
+ The platform's workers are shared, and one account sending a thousand runs
171
+ does not make anyone else's wait (FOL-123). Four things hold it, in order:
172
+
173
+ - **Turns in the queue.** A run's place is its account's runs already going
174
+ plus its place among its account's own waiting runs, so every account's
175
+ first run goes before anyone's second, and an account with work running
176
+ waits behind one with none. Within one account it is first come, first
177
+ served. A plan's lane weighs it — a fast lane takes more turns than a slow
178
+ one, never all of them — and a run that has waited long gains a turn
179
+ every ten minutes, so nothing waits for ever. The test the platform is
180
+ held to: one account floods 500 runs while three others keep sending
181
+ theirs, and the others' longest wait stays where it was without the flood.
182
+ - **Runs at once** (above): an account at its number has its next run
183
+ stepped over, not refused; it starts when one of its own ends.
184
+ - **Compute at once** (above): a step waits to start until its account's
185
+ running steps leave room for it in the account's pool. This is where a
186
+ plan's cores, memory and disk are enforced — before a sandbox exists, so
187
+ a step over it waits instead of failing. It is not a Kubernetes
188
+ `ResourceQuota`, on purpose: a quota refuses the pod at creation, which
189
+ would fail the step, and does not queue anything. It is also not as hard
190
+ as one: the gate is held by each worker for its own steps, so workers
191
+ looking at the cluster in the same moment can each start one more step
192
+ than the pool allows; a cluster that cannot be listed is not treated as
193
+ full; and nothing outside the gate stops the extra pods from running if
194
+ the cluster has the room. Each step's own limits are hard: its sandbox
195
+ cannot use more cores, memory or disk than it holds.
196
+ - **How many may wait** (above): past it, new runs are refused with a
197
+ reason, never dropped.
198
+
199
+ That is all the platform does on its own: it queues, it holds a step back,
200
+ it refuses a new run with a reason. It never suspends an account for its
201
+ load — that is a person's decision (the operator's), and the account sees
202
+ why. An unpaid invoice past its grace is the one automatic pause
203
+ ([dunning](#the-billing-section)).
204
+
205
+ The operator watches it on the metrics scrape:
206
+ `foldrun_queue_account_pending`, `foldrun_queue_account_claimed` and
207
+ `foldrun_queue_account_oldest_pending_seconds`, each for the five busiest
208
+ accounts by rank (`rank="1"` … `"5"`) and never by name.
209
+
168
210
  ## Plans and credits
169
211
 
170
212
  Usage is sold in **credits: one credit is one cent** of what a step consumes
package/docs/checks.md CHANGED
@@ -295,11 +295,31 @@ stays visible ([agents](agents#isolated-sub-agents-sandbox-own)).
295
295
  ### security/published-flow-trifecta
296
296
 
297
297
  *warn · ASI01, ASI02, ASI03.* A flow published over A2A (`a2a: {publish:
298
- true}`) runs a step whose agent holds something private and has a way out —
299
- the trifecta above, with the outside caller as the untrusted content: what a
300
- caller sends reaches every step. Take a leg away from that agent (the same
301
- three ways as above), or do not publish the flow. A warning, like every new
302
- rule; `deploy_block: security` makes it refuse a deploy.
298
+ true}`) runs an agent that holds something private — a secret, an API, an
299
+ MCP server. What a caller sends reaches every step, and the flow's answer
300
+ goes back to that caller, so **the answer itself is a way out** (since 5 Nov
301
+ 2026): the agent needs no network to hand over what it holds or reads, and a
302
+ `hooks:` gate, which guards tool calls, does not close it. The finding names
303
+ the network or outward tool too when there is one. Give that agent only what
304
+ a stranger may see, move the private part to a flow that is not published,
305
+ or do not publish the flow. "Its agents" are every agent a run can put to
306
+ work — steps, rescuers, delegates, subflows' steps and sub-agents. A warning,
307
+ like every new rule; `deploy_block: security` makes it refuse a deploy.
308
+
309
+ ### security/published-flow-secret-code
310
+
311
+ *warn · ASI01, ASI03.* An agent of a published flow holds a secret that
312
+ reaches its sandbox (`secrets:`, a `${NAME}` in `apis:` or a granted tool,
313
+ a `web:` provider's key) and can run code (`Bash`, `tools: [code]`). Code
314
+ reads the sandbox's environment, and the answer goes back to the caller — so
315
+ a caller can ask for the secret in the reply. Take Bash away
316
+ (`disallowedTools: [Bash]`), take the secret away or bind it to its sites, or
317
+ have an admin accept it: `a2a: { accept_risk: [<agent>] }`
318
+ ([A2A](a2a#secret-and-code-accept_risk)). This is check's half of a platform
319
+ rule: until accepted, the platform refuses to publish the flow and refuses
320
+ new A2A tasks for it. Accepted, the finding stays as `info`. Offline, check
321
+ cannot see which secrets are bound to sites, so it counts them all; the
322
+ platform does not count one that is bound.
303
323
 
304
324
  ### security/published-flow-ungated
305
325
 
package/docs/cli.md CHANGED
@@ -89,13 +89,14 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
89
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>` |
90
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` |
91
91
  | `foldrun probe <model>` | can this model hold a tool loop here? A live check |
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 |
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 |
92
+ | `foldrun logs [run-id]` | recent runs in one workspace, or one run's whole event trail. `--follow` tails a live run: on a platform it reads the run's server-sent events (`GET …/runs/<id>/stream`, what the dashboard's run page reads — `invoke --watch` and `agent run --wait` too), reconnecting up to three times if the stream goes quiet; a run on this machine is read from its file. `--local` reads this machine's store even when signed in; `foldrun runs --local` is the same command and prints the same thing |
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 — or, for a failed run, why it failed: `✗ agent: ` and the sentence every surface gives ([why it failed](runs#why-it-failed)). 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
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` |
95
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 |
96
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 |
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 |
98
- | `foldrun report <run-id>` | one run, whole, without opening the dashboard: the header, then every step with its group, agent, attempts, the runner image it ran on (`slim · browser pod` when it browsed through the account's pod from slim), cost, how much of its input the prompt cache served (`90% cached`; nothing for a step recorded before 18 Oct 2026) and, under a step that wrote a fifth or more of its input to the cache, why (`prompt cache: 75% of input written to the cache — memory changed since step 1`), how many model turns it took, duration, what happened to the browser pod under it (reconnects, `browser pod lost; re-ran on full` with its tries — `slim · lost` then `full` — or why it was not re-run), whether its `verify:` held and the first line of what it said — and for a failed step, the error and the last events before it. Then what it wrote, what it published and what is still waiting on a person. `--json` prints the run record instead |
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, through the same route (`POST …/runs/bulk` `{ action: "delete" }`, one call per workspace): it lists them, asks once, then deletes them — each run its own outcome, so one refused does not stop the rest, and it exits 1 |
98
+ | `foldrun runs rm --until <30d\|date>` | delete every **finished** run that started before then — its record, captured calls and archived outputs — in every workspace, or one with `--to` ([how long a run is kept](runs#how-long-a-run-is-kept)). Counts what would go, asks once (`--yes` with no terminal; `--dry-run` only counts), then deletes 100 at a time until none match (`POST …/runs/bulk { action: "delete", until }`). Runs still going are left alone; the ledger lines stay. Needs an admin (`workspace:manage`) |
99
+ | `foldrun report <run-id>` | one run, whole, without opening the dashboard: the header — and for a failed run why it failed and what to do (`✗ agent: The step ran out of memory. Memory limit: 4 GiB; …` and `fix: …`, [why it failed](runs#why-it-failed)) — then every step with its group, agent, attempts, the runner image it ran on (`slim · browser pod` when it browsed through the account's pod from slim), cost, how much of its input the prompt cache served (`90% cached`; nothing for a step recorded before 18 Oct 2026) and, under a step that wrote a fifth or more of its input to the cache, why (`prompt cache: 75% of input written to the cache — memory changed since step 1`), how many model turns it took, duration, what happened to the browser pod under it (reconnects, `browser pod lost; re-ran on full` with its tries — `slim · lost` then `full` — or why it was not re-run), whether its `verify:` held and the first line of what it said — and for a failed step, the error and the last events before it. Then what it wrote, what it published and what is still waiting on a person. `--json` prints the run record instead |
99
100
  | `foldrun report <run-id> --compare [<run-id>]` | this run beside the flow's [last good run](runs#compare-with-the-last-good-run), or the one named: whether they ran the same files and which changed, then what differs step by step (status, new errors, instruction, model, tools, time, tokens). `--json` |
100
101
  | `foldrun report <run-id> --tree` | the run as [one tree](runs#the-trace-tree): each step, each model call (model, tokens, why it stopped) and each tool call under the call that asked for it, with how long each took and `← what went wrong` on the first failure. `--json` gives the tree and the failure path |
101
102
  | `foldrun report <run-id> --calls` · `foldrun report <run-id> call <call-id>` | what the run [recorded](runs#what-a-run-records): `--calls` adds every model call (model, time, tokens and cache share, why it stopped, tools) and lists the tool calls whose input and output were kept; `call <call-id>` prints one of those, secrets masked (`--json`). The header says which commit the run ran and how long it queued |
@@ -205,10 +206,11 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
205
206
  | `foldrun use <name>` | act as one of them from here on. `foldrun switch <name>` is the same command |
206
207
  | `foldrun keys ls` | the account's API keys, each with its role and scope, when it was created, when it was last used and from where (a /24 or /48), and when it expires; a key `foldrun login` minted is tagged `CLI sign-in · renews itself` (revoke it to sign that machine out) — also `create <label>` (`--expires 30d\|90d\|365d\|never`), `rotate <id>` and `revoke <id>` |
207
208
  | `foldrun keys rotate <id>` | a new key with the old one's label, role, workspaces and deploy scope, printed once; the old key is revoked at once (asks first; `--yes` on a pipe), or keeps working for `--grace 1h` / `24h` while you swap the new one in. A key already rotated is refused (409) and the command names the key that replaced it — rotate that one, also if its secret was lost; `keys ls` shows `rotated → <id>`. The owner is emailed a week before any key expires |
208
- | `foldrun keys create <label> --a2a --to <ws> --flows a,b` | a key for an outside agent ([A2A](a2a.md)): it opens `/a2a/<account>/<ws>/…` — the agent card and JSON-RPC endpoint of those flows, each also published with `a2a:` — and no `/api` route. `--max-tasks <n>` caps the tasks it may have open at once (1–100, default 10); `--expires` as for any key. Printed once; `keys ls` shows it as `A2A · <ws> · <flows>`. `POST /api/keys { purpose: "a2a", workspace, flows, maxTasks }`, an admin's |
209
- | `foldrun a2a ls --to <ws>` | what a workspace serves over A2A (`GET /api/workspaces/<ws>/a2a`): every flow that says `a2a:`, published or not, with its public/private card and its card and endpoint URLs; the workspace's A2A keys (an admin's view; `null` otherwise); and the newest tasks — state, flow, run, and `A2A · <key label>`. `--json` prints the answer as it came |
209
+ | `foldrun keys create <label> --a2a --to <ws> --flows a,b` | a key for an outside agent ([A2A](a2a.md)): it opens `/a2a/<account>/<ws>/…` — the agent card and JSON-RPC endpoint of those flows, each published with `a2a:` (a flow not published when the key is minted is refused: publish first) — and no `/api` route. `--max-tasks <n>` caps the tasks it may have open at once (1–100, default 10); `--expires` as for any key. Printed once; `keys ls` shows it as `A2A · <ws> · <flows>`. `POST /api/keys { purpose: "a2a", workspace, flows, maxTasks }`, an admin's |
210
+ | `foldrun a2a ls --to <ws>` | what a workspace serves over A2A (`GET /api/workspaces/<ws>/a2a`): every flow that says `a2a:`, published or not, with its public/private card and its card and endpoint URLs; the workspace's A2A keys (an admin's view; `null` otherwise); and the newest tasks — state, flow, run, and `A2A · <key label>`; then, under **Secret and code**, every agent that holds a secret and can run code, accepted or not, with the `--accept-risk` line that accepts it. `--json` prints the answer as it came |
210
211
  | `foldrun a2a publish <flow>` | sets `a2a: { publish: true }` in the flow, keeping the rest of its block: `--name`, `--description`, `--example "…"` (repeatable — the card's examples), `--public-card` (the card is readable without a key; calling never is) or `--private-card`. Checked with core's `a2a:` rules before anything is written; shows the diff, `--dry-run` writes nothing. Without `--to` it edits this folder (`deploy` ships it); `--to <workspace>` sends the flow page's `PATCH …/flows/<flow> { a2a, expect }` — an admin's, the platform refuses an editor — and prints the card URL. A caller also needs an A2A key that names the flow |
211
212
  | `foldrun a2a unpublish <flow>` | `a2a: publish: false` — no outside agent may call it, whatever keys name it; the rest of `a2a:` stays for the next publish. `--to`, `--dry-run` as for `publish` |
213
+ | `foldrun a2a publish <flow> --accept-risk <agent,…>` | `a2a: accept_risk` — the flow's agents an admin accepts holding a secret while they can run code: their answer goes back to the caller, so without it such a flow is not published (`400`, `a2a_secret_code`) and takes no new task ([A2A](a2a.md#secret-and-code-accept_risk)). Name every agent accepted — the list replaces the flow's; `--clear-accept-risk` takes it out. With `--to`, an admin's |
212
214
  | `foldrun a2a publish <flow> --clear-name` | drops the card's name from `a2a:` (null, as the flow page's emptied field sends); `--clear-description` and `--clear-examples` the same for the description and the examples. Each works on `unpublish` too, and is refused beside its own `--name`/`--description`/`--example` |
213
215
  | `foldrun a2a card <flow> --to <ws>` | the flow's card URL and JSON-RPC endpoint, then the card itself. A private card is read with an A2A key from `$FOLDRUN_A2A_KEY` (or `--key-env NAME`); without one the URLs are printed and the card is not |
214
216
  | `foldrun a2a call <card-url> "<text>"` | a small A2A 1.0 client (core's `a2a-client`), to try a published flow or any A2A agent: reads the card (its JSON-RPC interface must be at the card's own origin; redirects are never followed), sends `SendMessage` with the text and `--data <json\|@file>` as a data part (`--context <id>` continues a conversation), prints the task id, then polls `GetTask` until the task ends or `--max-wait <s>` (default 300) runs out — `--no-wait` (or `--return-immediately`, A2A's name for it) returns at once. Prints the state and the answer (`--json` the task). The key is an A2A key from `$FOLDRUN_A2A_KEY` or `--key-env NAME`, never this CLI's API key and never a command-line value. Exit 0 when completed or still open, 1 when failed, canceled or rejected |
@@ -264,6 +266,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
264
266
  | `--name`, `--abn`, `--address`, `--email` | `billing details set`: the legal name, the ABN, `"line1, city, state, postcode, AU"` (the last part is the two-letter country), the receipt email |
265
267
  | `--clear-address`, `--clear-email`, `--clear-abn` | `billing details set`: drop that one from the invoice details, the rest kept |
266
268
  | `--clear-name`, `--clear-description`, `--clear-examples` | `a2a publish`, `a2a unpublish`: drop that one from the card, the rest of `a2a:` kept |
269
+ | `--accept-risk <agent,…>`, `--clear-accept-risk` | `a2a publish`: the agents accepted holding a secret while they can run code (`a2a: accept_risk`), or none |
267
270
  | `--days <n>` | `usage`: the window the charges cover (default 56). `status --platform --history`: 1–90 days (default 90) |
268
271
  | `--id <revision>` | `history`: one revision, as diffs |
269
272
  | `--engine <e>` | `login <site>`: the browser to sign in with — `chrome` (default; it signs in with Chromium, so `chromium` is the same), `firefox` or `safari` (`webkit`). Not `lightpanda` or `obscura`, which keep no profile to sign in with — the full list is [Engines](tools#engines) |
package/docs/flows.md CHANGED
@@ -348,7 +348,7 @@ normal outcome, recorded as one.
348
348
  | `approvers` | who may decide this flow's gates — addresses, or `admins` |
349
349
  | `approve_within` | how long a gate waits before the run is rejected |
350
350
  | `live` | `true` to make this flow's runs real where the platform would otherwise make them [test runs](runs#test-runs): as an eval's subject. Only ever an opt-out of the safe default |
351
- | `a2a` | serve this flow to outside agents over A2A 1.0 — `{ publish: true, name?, description?, examples?, public_card?, input? }`: the agent card's name, description and example requests (else the flow's own), `public_card: true` to let the card be read without a key, and `input` a JSON Schema the request's data part must match. A caller still needs an A2A key that names the flow; a block `foldrun check` cannot read publishes nothing. Changing it needs `workspace:manage`. See [A2A](a2a) |
351
+ | `a2a` | serve this flow to outside agents over A2A 1.0 — `{ publish: true, name?, description?, examples?, public_card?, input?, accept_risk? }`: the agent card's name, description and example requests (else the flow's own), `public_card: true` to let the card be read without a key, `input` a JSON Schema the request's data part must match, and `accept_risk` the agents an admin accepts holding a secret while they can run code (without it such a flow is not published — [A2A](a2a#secret-and-code-accept_risk)). A caller still needs an A2A key that names the flow; a block `foldrun check` cannot read publishes nothing. Changing it needs `workspace:manage`. See [A2A](a2a) |
352
352
 
353
353
  Every duration here is written the way `wait:` is — `45s`, `10m`, `2h`, `3d`,
354
354
  or bare seconds — and capped at thirty days.
package/docs/runs.md CHANGED
@@ -106,6 +106,52 @@ completed plus failed, and a run a person stopped is left out. What the
106
106
  completed runs found is counted beside it: **blocked** (BLOCKED), **problem
107
107
  found** (BAD), and **nothing to do** (QUIET).
108
108
 
109
+ ## Why it failed
110
+
111
+ A failed run says why in one sentence, the same on the run page, the runs
112
+ list, `GET …/runs/<id>` and `…/runs` (`failure`), `foldrun runs` and
113
+ `foldrun report`. Beside the step's own last error (`reason`, as its trail
114
+ has it) it carries:
115
+
116
+ | Field | What |
117
+ |---|---|
118
+ | `class` | one word, from the same list the platform's operations logs count failures by: `policy_denied`, `timeout`, `oom`, `disk_full`, `model_error`, `network_error`, `user_code_error`, `not_found`, `cancelled`, `platform_error` |
119
+ | `kind` | what the message and fix are about: `memory`, `cpu`, `disk`, `timeout`, `network`, `security`, `budget`, `check`, `model`, `credential`, `stopped`, `code`, `platform`, `other` |
120
+ | `message` | the sentence |
121
+ | `fix` | what to do, or null |
122
+ | `used`, `allowed`, `unit`, `scope` | for a limit: what the step used or asked for (null when the sandbox ended before it could be read), what it may hold, in `GiB`, `vCPU` or `s`, and whose limit it is — `step`, `run`, `workspace`, `account`, `install` or `node` |
123
+ | `host` | for a refused site: which |
124
+
125
+ What each says:
126
+
127
+ - **A limit is said in figures.** *This step asks for 8 GiB of memory; one
128
+ step on this account may hold 4 GiB* — ask for less with `size:` or
129
+ `resources:`, or a plan that allows more. *The step ran out of memory.
130
+ Memory limit: 4 GiB; last recorded peak: 3.9 GiB* — a larger `size:` or
131
+ `resources: { memory: … }`. The same for cores, disk and `timeout:`. A
132
+ step bigger than its flow's or workspace's `compute:` names that
133
+ `compute:`; only a limit a plan sets mentions a plan. A machine running
134
+ short and the cluster evicting the step is said as that — not as the
135
+ step over its own limit.
136
+ - **A refused site is named** — your `network:` list is your own: *The step
137
+ was refused api.example.com: it is not on this agent's network: list*,
138
+ and the fix is the one site to add if the agent should reach it. When the
139
+ step's own program failed and a site was also refused on its trail, both
140
+ are said, the program's error first.
141
+ - **A security control is generic.** *This step was stopped by a platform
142
+ security control.* Nothing else is said — not what was seen, not how —
143
+ on any surface; if you think it is a mistake, write to hello@foldrun.io
144
+ with the run's id. Only the platform writes this (a step's own output
145
+ saying the words is not one).
146
+ - A budget, a stop, the model's cap or credential, a check that did not hold
147
+ and the account's own code each say so in their own words; anything else
148
+ is the step's last error as it was, classed `platform_error` — a bucket,
149
+ not a finding that the platform was at fault.
150
+
151
+ A run that failed with no failed step — a budget hit or a stop between
152
+ groups — says that too. Runs listed before 5 Nov 2026 say the class and
153
+ sentence but not a limit's figures until the run is read whole.
154
+
109
155
  ## What a run records
110
156
 
111
157
  Every step keeps, beside its events:
@@ -170,12 +216,54 @@ telemetry:
170
216
  In the account's `AGENTS.md` (Settings → Observability → *Send runs to your
171
217
  tracing*, or `foldrun account telemetry set <url> --header
172
218
  authorization='${OTEL_TOKEN}'`), or a workspace's, which replaces the
173
- account's whole. Every run that finishes is sent as one trace: a span for
174
- the run, each step (with `foldrun.agent` and `foldrun.owner`), each model
175
- call (`gen_ai.request.model`, token counts, finish reason) and each tool call
176
- (`gen_ai.tool.name`), failures as error spans. Resource attributes name the
177
- account, workspace, flow and run. Ids come from the run's, so a run sent
178
- twice is one trace. Test runs are not sent.
219
+ account's whole. Every run that finishes is sent as one trace. Resource
220
+ attributes name the account, workspace, flow and run. Ids come from the
221
+ run's, so a run sent twice is one trace. Test runs are not sent.
222
+
223
+ The spans follow the [OpenTelemetry GenAI semantic
224
+ conventions](https://github.com/open-telemetry/semantic-conventions-genai)
225
+ (agent spans and client inference spans, as of November 2026; the spec is
226
+ still marked *Development*), so a GenAI-aware backend draws them without
227
+ any mapping:
228
+
229
+ | Span | Name | `gen_ai.operation.name` | Also |
230
+ |---|---|---|---|
231
+ | the run | `invoke_workflow <flow>` | `invoke_workflow` | `gen_ai.workflow.name` |
232
+ | each step | `invoke_agent <agent>` | `invoke_agent` | `gen_ai.agent.name`, `foldrun.agent`, `foldrun.owner`, `foldrun.step` |
233
+ | each model call | `chat <model>` (kind CLIENT) | `chat` | `gen_ai.request.model`, `gen_ai.provider.name`, `gen_ai.usage.input_tokens` / `output_tokens` / `cache_read.input_tokens` / `cache_write.input_tokens`, `gen_ai.response.finish_reasons` |
234
+ | each tool call | `execute_tool <tool>` | `execute_tool` | `gen_ai.tool.name`, `gen_ai.tool.call.id`, `gen_ai.agent.name` |
235
+ | an error line | `error` | — | the step's error, as the status message |
236
+
237
+ A run of one agent on its own (`foldrun agent run`, `POST …/agents/<a>/run`)
238
+ is not a workflow: its root span is `run adhoc:<agent>` with no operation,
239
+ and the step under it is the `invoke_agent`. `gen_ai.provider.name` is set
240
+ where the run record says whose model it was — the platform's Claude
241
+ (`anthropic`) or one of foldrun's models — and left out for your own
242
+ `provider:` block, and for a step that was retried on its fallback model
243
+ (the record does not say which call went where). Every span also carries `foldrun.span.kind` (`run`,
244
+ `step`, `model`, `tool`, `error`): filter on that, not on span names.
245
+
246
+ A failed span has status ERROR and `error.type`, one of `timeout`,
247
+ `cancelled` (a person or a caller stopped the run), `model_error` (the model
248
+ credential refused, the usage cap spent, the provider overloaded), `oom`,
249
+ `disk_full`, `network_error`, `not_found`, `policy_denied`,
250
+ `platform_error` (the sandbox never started, the worker was lost), or
251
+ `_OTHER` when the error's words match none of these — a failed `verify:`,
252
+ say, or a failed tool call, whose record holds no words. The run's comes
253
+ from its failing step.
254
+
255
+ No content goes on a span: not the prompt, not the reply, not a tool
256
+ call's input or output. The spec makes all of those opt-in, and the trace
257
+ is built from the run record alone. What a failed span says is its class and
258
+ the step's error line (at most 500 characters).
259
+
260
+ Before 5 Nov 2026 spans were named `run <flow>`, `step <agent>`,
261
+ `chat <model>` and `tool <name>`, and carried `gen_ai.response.finish_reason`
262
+ (one string), `gen_ai.usage.cache_read_tokens` and
263
+ `gen_ai.usage.cache_write_tokens`. Those three attributes are still sent
264
+ beside the spec's names for one release, then dropped; move queries to
265
+ `gen_ai.response.finish_reasons` and `gen_ai.usage.cache_read.input_tokens`
266
+ / `cache_write.input_tokens`.
179
267
 
180
268
  *Send a test trace* (`foldrun account telemetry test`) sends one made-up run
181
269
  and says what the collector answered. A header whose secret is not in the
@@ -453,8 +541,37 @@ groups: the group that crosses it is the last that runs, and the run fails
453
541
  saying so. The workspace's and the account's `budget:` over time sit above
454
542
  that. See [Budgets and billing](budgets-and-billing).
455
543
 
456
- Finished runs older than the install's retention are pruned. Their headline
457
- survives in the eval history and in what agents can recall.
544
+ ## How long a run is kept
545
+
546
+ A run's record — its prompts, replies, tool input and output, errors — its
547
+ captured calls and its archived outputs are your content. On foldrun's
548
+ hosted platform they are kept **90 days after the run finished**, then
549
+ deleted by the platform's daily pass (on the first pass after the day, not
550
+ at that second). The install's operator sets the period
551
+ (`runs.retention_days`; unset or `0` keeps runs for ever, which is what a
552
+ self-hosted install does until its operator chooses);
553
+ a run whose charge is still being recorded waits for that first.
554
+
555
+ Sooner is yours to decide:
556
+
557
+ - one run or a few: tick them on the runs pages and choose **Delete**, or
558
+ `foldrun runs rm <run-id> [<run-id>…]` (`DELETE …/runs/<id>`; a run still
559
+ going is stopped first);
560
+ - everything that started before a date: `foldrun runs rm --until 30d`
561
+ (or `--until 2026-08-01`, `--to <workspace>`, `--dry-run`), which is
562
+ `POST …/runs/bulk { action: "delete", until }` — finished runs only;
563
+ - the whole account: close it (Settings → Account); the platform team then
564
+ deletes its data.
565
+
566
+ Deleting needs an admin (`workspace:manage`). What the charge was stays on
567
+ the ledger — money is not deleted because a trace was.
568
+
569
+ What is **not** the run record, and so not deleted with it: the files a run
570
+ wrote to `storage/`, `memory/` and `state/` (yours, kept until you delete
571
+ them — `foldrun storage rm`), a run's headline where an eval's history
572
+ recorded it, and backups, which this window does not reach — what they
573
+ hold and how long they are kept is under [backups](backups-and-restore). See [Security](security#what-we-keep-and-for-how-long)
574
+ for the whole list.
458
575
 
459
576
  ## The runs list
460
577
 
package/docs/security.md CHANGED
@@ -17,6 +17,17 @@ Startup is under a second warm, so this is not the latency it sounds like;
17
17
  it is the boundary that lets one account's agent and another's share a
18
18
  machine.
19
19
 
20
+ What a sandbox keeps between steps is the account's runtime cache: the
21
+ environments its `runtime:` declares, built once and reused. Steps write it,
22
+ so nothing in it is trusted by the part of a step's start-up that runs as
23
+ root. That part installs `runtime: system:` packages before the drop to the
24
+ unprivileged agent user, in an environment with none of the step's variables
25
+ but the proxy's, and touches the cache only as the agent user. The package
26
+ snapshots it restores carry a seal made with a key per account that no step
27
+ ever holds; a snapshot that does not match its seal is not restored, and even
28
+ a sealed one can only write package files where packages go
29
+ ([system packages](agents#where-it-runs)).
30
+
20
31
  ## What the network allows
21
32
 
22
33
  A run pod may reach DNS, the egress proxy where its credentials are filled
@@ -137,6 +148,23 @@ The pattern that follows from it, and that the reference desks use: the
137
148
  tool that *proposes* a change and the tool that *applies* it are two tools,
138
149
  and only the step after a human gate holds the second.
139
150
 
151
+ ### Flows published to outside agents
152
+
153
+ A flow published over [A2A](a2a) answers whoever holds a key for it, so its
154
+ **answer is a way out** as much as a network is. Two rules hold on the
155
+ platform, by every door into the files (since 5 Nov 2026):
156
+
157
+ - **Secret and code.** An agent of a published flow that holds a secret in
158
+ its sandbox and can run code could be asked to print the secret into its
159
+ answer. Such a flow is not published, and takes no new task, until an
160
+ admin names the agent in `a2a: accept_risk` — recorded in the flow's
161
+ history and the audit log ([accept_risk](a2a#secret-and-code-accept_risk)).
162
+ - **Only an admin widens it.** Publishing is an admin's approval of what the
163
+ flow's agents can reach. An editor's change that gives one of them a new
164
+ tool, secret, API, network, sub-agent or step, or takes a hook away, is
165
+ refused; an admin's is audited
166
+ ([details](a2a#an-editor-cannot-widen-a-published-flow)).
167
+
140
168
  ## Gates and the record
141
169
 
142
170
  A `!` on a step parks the run for a person, and the run cannot proceed
@@ -198,6 +226,37 @@ debugging on your own machine. On a laptop (`foldrun run`, `next dev`) there
198
226
  is no boundary: the reader is the person whose content it is, and errors
199
227
  print in full.
200
228
 
229
+ ## What we keep, and for how long
230
+
231
+ Two kinds of record, kept for different lengths of time (5 Nov 2026). The
232
+ install's operator sets both. These are what foldrun's hosted platform uses;
233
+ an install that sets neither keeps everything, as before 5 Nov 2026.
234
+
235
+ | What | Holds | Kept | Deleted by |
236
+ |---|---|---|---|
237
+ | **Run records** — your content | a run's prompts, replies, tool input and output, errors, captured calls, archived outputs | **90 days** after the run finished on the hosted platform (`runs.retention_days`; unset: kept) | the daily pass; or you, sooner — one run, a selection, or everything before a date ([how](runs#how-long-a-run-is-kept)) |
238
+ | Your files | `storage/`, `knowledge/`, `memory/`, `state/`, your agents and flows | until you delete them | you (`foldrun storage rm`, a deploy that drops a file) |
239
+ | **Audit log** — security evidence | sign-ins and refusals, keys, roles, invites, secrets set or deleted (by name, never a value), deploys, exports, support access, the operator's own actions | **365 days** on the hosted platform (`audit.retention_days`; unset: kept) | the daily pass |
240
+ | The ledger | what each run and pod session was charged | for good — a financial record | never |
241
+ | The platform's own logs and metrics | ids, counts, classes — never your content ([above](#what-our-telemetry-carries)) | as the operations stack keeps them | the operations stack |
242
+
243
+ Every period counts from when the record was written (a run: when it
244
+ finished), and the daily pass deletes on its first round after the day. A
245
+ run whose charge has not yet been recorded is kept until it is. `0` keeps a
246
+ record for ever. An install without a database keeps its audit log in a
247
+ file, numbered by line, and does not prune it.
248
+
249
+ Closing the account (Settings → Account) suspends it at once and tells the
250
+ platform team, who settle the last invoice and delete the account's data:
251
+ its records, files, keys and sessions. The ledger and the audit entry that
252
+ says it was deleted are kept. Backups are their own matter:
253
+ [what they hold](backups-and-restore).
254
+
255
+ When a run fails because a platform security control stopped it, the run
256
+ says only that — *This step was stopped by a platform security control* —
257
+ never what was seen or how. What the control recorded is security evidence
258
+ and is kept with it.
259
+
201
260
  ## People
202
261
 
203
262
  Four roles, least privilege by route, one owner. See
@@ -116,7 +116,10 @@ edit `~/foldrun/.env` and run `docker compose up -d` there.
116
116
  | `FOLDRUN_DATA_DIR` | a named volume | a host path for the data instead |
117
117
 
118
118
  `docker-compose.yml` lists the rest (concurrency, retention, gVisor, other
119
- model endpoints). Put your own changes in `docker-compose.override.yml`
119
+ model endpoints). Finished runs are deleted 90 days after they finished
120
+ unless `FOLDRUN_RETENTION_DAYS` says otherwise (`0` keeps them for ever) —
121
+ since 5 Nov 2026; before, an install kept every run. Set it before updating
122
+ if you want to keep older history ([how long we keep what](security#what-we-keep-and-for-how-long)). Put your own changes in `docker-compose.override.yml`
120
123
  beside it, which Compose reads too: the installer replaces
121
124
  `docker-compose.yml` on an update and keeps a copy of one you edited.
122
125
 
@@ -178,9 +178,9 @@ workspace, page back, and download it as CSV for an auditor.
178
178
  The owner and admins who can open every workspace read it — people, or an
179
179
  `admin` key. A member or key scoped to some workspaces cannot: the log is
180
180
  the whole account's. It is the caller's own account, always; another
181
- account's entries are never in it. Entries are kept for the life of the
182
- account (no plan sets a shorter retention) and go when the account is
183
- deleted. Also `GET /api/audit` and `foldrun audit --since 7d --csv`.
181
+ account's entries are never in it. Entries are kept 365 days on the hosted platform (an install sets its own) — security
182
+ evidence, [how long we keep what](security#what-we-keep-and-for-how-long) —
183
+ and go sooner when the account is deleted. Also `GET /api/audit` and `foldrun audit --since 7d --csv`.
184
184
 
185
185
  What agents did is a different record: every run's trail, under Runs.
186
186
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "foldrun",
3
- "version": "17.0.1",
3
+ "version": "17.1.1",
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",
@@ -11,7 +11,7 @@
11
11
  "node": ">=22"
12
12
  },
13
13
  "dependencies": {
14
- "@foldrun/core": "^15.0.0"
14
+ "@foldrun/core": "^15.1.0"
15
15
  },
16
16
  "files": [
17
17
  "bin",
@@ -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 tests/cli-runs-paging.test.ts tests/cli-budget-invoices.test.ts tests/cli-observe-analysis.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 tests/cli-failure-retention.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
@@ -8030,7 +8030,7 @@ async function runsCmd(flags, layout) {
8030
8030
  if (typeof flags.q === "string") {
8031
8031
  const words = flags.q.toLowerCase().replace(/\s+/g, " ").trim().split(" ").filter(Boolean);
8032
8032
  const shown = r.outcome === "stopped" ? "stopped" : r.status;
8033
- const hay = [r.id, r.flow.replace(/^(adhoc|eval):/, ""), r.workspace, shown, verdictOf(r) ?? "", r.summary ?? "", r.failure ? `${r.failure.agent} ${r.failure.reason}` : ""]
8033
+ const hay = [r.id, r.flow.replace(/^(adhoc|eval):/, ""), r.workspace, shown, verdictOf(r) ?? "", r.summary ?? "", r.failure ? `${r.failure.agent} ${r.failure.reason}${r.failure.message ? ` ${r.failure.message}` : ""}` : ""]
8034
8034
  .join(" ")
8035
8035
  .toLowerCase()
8036
8036
  .replace(/\s+/g, " ");
@@ -8121,6 +8121,9 @@ async function runsCmd(flags, layout) {
8121
8121
  cost: typeof r.chargedUsd === "number" ? `${Math.round(r.chargedUsd * 100)} credits` : `$${runCost(r).toFixed(2)}`,
8122
8122
  id: r.id,
8123
8123
  summary: firstLine(r.summary, 110),
8124
+ // Why it failed, as the dashboard's list says it (FOL-124); a
8125
+ // platform from before then sends the last error alone.
8126
+ failure: r.failure ? `${r.failure.agent}: ${firstLine(r.failure.message ?? r.failure.reason, 104)}` : null,
8124
8127
  };
8125
8128
  });
8126
8129
  const widest = (key) => Math.max(...cells.map((x) => x[key].length));
@@ -8140,7 +8143,8 @@ async function runsCmd(flags, layout) {
8140
8143
  ` ${x.mark} ${c.dim(pad(x.when, w.when))} ${pad(x.workspace, w.workspace)} ${c.bold(pad(x.flow, w.flow))} ` +
8141
8144
  `${pad(x.status, w.status)} ${x.verdict}${" ".repeat(Math.max(...cells.map((y) => y.verdictWidth)) - x.verdictWidth)} ${c.dim(`${pad(x.steps, w.steps)} ${pad(x.took, w.took)} ${pad(x.cost, w.cost)}`)} ${c.dim(x.id)}`,
8142
8145
  );
8143
- if (x.summary) console.log(` ${c.dim(x.summary)}`);
8146
+ if (x.failure) console.log(` ${c.red(`✗ ${x.failure}`)}`);
8147
+ else if (x.summary) console.log(` ${c.dim(x.summary)}`);
8144
8148
  }
8145
8149
  for (const [ws, why] of unreachable) console.error(` ${c.red("✗")} ${ws} ${c.dim(why)}`);
8146
8150
  if (next) console.log(`\n ${c.dim(`more: the same with --before ${next}${pageNo > 1 ? "" : ` (or --page ${pageNo + 1})`}`)}`);
@@ -8437,6 +8441,14 @@ async function reportCmd(runId, flags, layout) {
8437
8441
  console.log();
8438
8442
  for (const line of wrap(run.summary, 84)) console.log(` ${line}`);
8439
8443
  }
8444
+ // Why it failed (FOL-124): the sentence and the fix every surface gives.
8445
+ // A platform from before then sends no `failure` on one run.
8446
+ if (run.failure?.message) {
8447
+ console.log();
8448
+ const lines = wrap(`${run.failure.agent}: ${run.failure.message}`, 82);
8449
+ lines.forEach((line, i) => console.log(` ${i ? " " : c.red("✗")} ${c.red(line)}`));
8450
+ if (run.failure.fix) for (const line of wrap(`fix: ${run.failure.fix}`, 82)) console.log(` ${c.dim(line)}`);
8451
+ }
8440
8452
 
8441
8453
  console.log();
8442
8454
  (run.steps ?? []).forEach((step, i) => {
@@ -10793,9 +10805,61 @@ async function runRmCmd(runId, flags, layout) {
10793
10805
  return 0;
10794
10806
  }
10795
10807
 
10808
+ /**
10809
+ * `foldrun runs rm --until 30d [--to <ws>] [--dry-run]` — every finished run
10810
+ * that started before then, deleted: record, captured calls, archived
10811
+ * outputs (POST …/runs/bulk { action: "delete", until }, FOL-124). The
10812
+ * customer's way to erase run content sooner than the retention window.
10813
+ * Counted first and asked once; then each workspace is asked again until
10814
+ * nothing matches (the route deletes 100 a call and answers `remaining`),
10815
+ * stopping at a call that deleted nothing.
10816
+ */
10817
+ async function runsRmUntilCmd(ids, flags) {
10818
+ const url = platformFor(flags, "runs rm");
10819
+ if (ids.length) throw new Error("name the runs or give --until, not both — `foldrun runs rm --until 30d`");
10820
+ const until = untilInstant(flags.until);
10821
+ const names = typeof flags.to === "string" ? [flags.to] : await remoteWorkspaceNames(url, flags);
10822
+ const plans = await pool(names, 8, async (ws) => {
10823
+ const r = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/runs/bulk`, { method: "POST", body: JSON.stringify({ action: "delete", until, dryRun: true }) });
10824
+ return { ws, count: (Array.isArray(r.matched) ? r.matched.length : 0) + (Number(r.remaining) || 0) };
10825
+ });
10826
+ const total = plans.reduce((n, p) => n + p.count, 0);
10827
+ console.log();
10828
+ for (const p of plans.filter((x) => x.count)) console.log(` ${c.bold(p.ws)} ${c.dim(`${p.count} finished run${p.count === 1 ? "" : "s"}`)}`);
10829
+ if (!total) {
10830
+ console.log(` ${c.dim(`no finished run started before ${until} — nothing to delete`)}\n`);
10831
+ return 0;
10832
+ }
10833
+ if (flags["dry-run"] === true) {
10834
+ console.log(`\n ${c.dim(`--dry-run: ${total} run${total === 1 ? "" : "s"} started before ${until} would be deleted; nothing touched`)}\n`);
10835
+ return 0;
10836
+ }
10837
+ const what = `${total} finished run${total === 1 ? "" : "s"} that started before ${until} — their records, captured calls and archived outputs. Runs still going are left alone. The ledger lines stay`;
10838
+ if (!(await sureToDelete(flags, "runs rm", what))) return 1;
10839
+ let deleted = 0;
10840
+ let bad = 0;
10841
+ console.log();
10842
+ for (const p of plans.filter((x) => x.count)) {
10843
+ for (let round = 0; round < 10_000; round++) {
10844
+ const r = await remoteCall(url, flags, `/api/workspaces/${enc(p.ws)}/runs/bulk`, { method: "POST", body: JSON.stringify({ action: "delete", until }) });
10845
+ deleted += r.succeeded ?? 0;
10846
+ for (const x of (r.runs ?? []).filter((x) => !x.ok)) {
10847
+ bad++;
10848
+ console.log(` ${c.red("✗")} ${p.ws} ${x.runId}${x.error ? c.dim(` — ${x.error}`) : ""}`);
10849
+ }
10850
+ if (!r.remaining || !r.succeeded) break;
10851
+ }
10852
+ console.log(` ${c.green("✓")} ${p.ws}`);
10853
+ }
10854
+ console.log(`\n ${c.dim(`${deleted} deleted${bad ? ` · ${bad} refused` : ""}`)}\n`);
10855
+ return bad ? 1 : 0;
10856
+ }
10857
+
10796
10858
  /** `foldrun runs rm <run-id> <run-id>…` — the selection bar's Delete: lists
10797
- * them, asks once, then one DELETE per run (there is no bulk delete route),
10798
- * each its own outcome so one refusal does not stop the rest. */
10859
+ * them, asks once, then deletes them as the bar does — POST …/runs/bulk
10860
+ * { action: "delete", runIds }, once per workspace in calls of at most 100
10861
+ * (FOL-75, 5 Nov 2026; it was one DELETE per run). Each run its own
10862
+ * outcome, so one refusal does not stop the rest. */
10799
10863
  async function runsRmManyCmd(ids, flags, layout) {
10800
10864
  const url = platformFor(flags, "runs rm");
10801
10865
  const unique = [...new Set(ids)];
@@ -10812,13 +10876,31 @@ async function runsRmManyCmd(ids, flags, layout) {
10812
10876
  if (!(await sureToDelete(flags, "runs rm", what))) return 1;
10813
10877
  let bad = 0;
10814
10878
  console.log();
10815
- for (const { id, ws } of runs) {
10816
- try {
10817
- await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/runs/${enc(id)}`, { method: "DELETE" });
10818
- console.log(` ${c.green("✓")} ${ws} ${id} deleted`);
10819
- } catch (err) {
10820
- bad++;
10821
- console.log(` ${c.red("✗")} ${ws} ${id}${c.dim(` — ${explain(err)}`)}`);
10879
+ const byWs = new Map();
10880
+ for (const { id, ws } of runs) byWs.set(ws, [...(byWs.get(ws) ?? []), id]);
10881
+ for (const [ws, all] of byWs) {
10882
+ for (let i = 0; i < all.length; i += 100) {
10883
+ const ids = all.slice(i, i + 100);
10884
+ /** @type {any} */
10885
+ let r;
10886
+ try {
10887
+ r = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/runs/bulk`, { method: "POST", body: JSON.stringify({ action: "delete", runIds: ids }) });
10888
+ } catch (err) {
10889
+ // Refused whole (a 403 without workspace:manage): every run it carried.
10890
+ for (const id of ids) console.log(` ${c.red("✗")} ${ws} ${id}${c.dim(` — ${explain(err)}`)}`);
10891
+ bad += ids.length;
10892
+ continue;
10893
+ }
10894
+ const answered = new Set();
10895
+ for (const x of r.runs ?? []) {
10896
+ answered.add(x.runId);
10897
+ if (!x.ok) bad++;
10898
+ console.log(x.ok ? ` ${c.green("✓")} ${ws} ${x.runId} deleted` : ` ${c.red("✗")} ${ws} ${x.runId}${c.dim(` — ${x.error ?? "refused"}`)}`);
10899
+ }
10900
+ for (const id of ids.filter((x) => !answered.has(x))) {
10901
+ bad++;
10902
+ console.log(` ${c.red("✗")} ${ws} ${id}${c.dim(" — not found (deleted since it was listed?)")}`);
10903
+ }
10822
10904
  }
10823
10905
  }
10824
10906
  console.log(`\n ${c.dim(`${runs.length - bad} of ${runs.length} deleted${bad ? ` · ${bad} refused` : ""}`)}\n`);
@@ -13895,7 +13977,7 @@ function printPreview(p, rel) {
13895
13977
  * account's published flows, and this terminal calling any A2A agent.
13896
13978
  *
13897
13979
  * a2a ls --to <ws> what the workspace serves: flows, cards, keys, recent tasks
13898
- * a2a publish <flow> [--to <ws>] [--name --description --example … --public-card|--private-card]
13980
+ * a2a publish <flow> [--to <ws>] [--name --description --example … --public-card|--private-card] [--accept-risk <agent,…>|--clear-accept-risk]
13899
13981
  * a2a unpublish <flow> [--to <ws>] publish: false, the rest of a2a: kept
13900
13982
  * a2a card <flow> --to <ws> the card's URL, then the card
13901
13983
  * a2a call <card-url> "<text>" [--data <json|@file>] [--context <id>] [--no-wait] [--max-wait <s>]
@@ -13961,6 +14043,7 @@ async function a2aLsCmd(flags, layout) {
13961
14043
  const flows = view.flows ?? [];
13962
14044
  console.log(`\n ${c.bold(ws)} ${c.dim("· over A2A")}\n`);
13963
14045
  if (!flows.length) console.log(` ${c.dim(`no flow says a2a: — \`foldrun a2a publish <flow> --to ${ws}\` publishes one`)}`);
14046
+ const risks = Array.isArray(view.risks) ? view.risks : [];
13964
14047
  for (const f of flows) {
13965
14048
  const state = f.published ? c.green("published".padEnd(13)) : c.dim("not published");
13966
14049
  const extra = [f.publicCard ? "public card" : "private card", f.hasInputSchema ? "input schema" : null].filter(Boolean).join(" · ");
@@ -13970,6 +14053,22 @@ async function a2aLsCmd(flags, layout) {
13970
14053
  console.log(` ${" ".repeat(10)}${c.dim("url ")} ${printable(f.url)}`);
13971
14054
  }
13972
14055
  }
14056
+ // FOL-112: agents that hold a secret and can run code — their answer goes
14057
+ // to the caller. Not accepted, a published flow takes no new task.
14058
+ if (risks.length) {
14059
+ console.log(`\n ${c.bold("Secret and code")} ${c.dim("· the answer goes back to the caller")}`);
14060
+ for (const r of risks) {
14061
+ const mark = r.accepted ? c.dim("accepted".padEnd(12)) : c.yellow("not accepted");
14062
+ console.log(` ${mark} ${c.bold(printable(r.flow))} · ${printable(r.agent)} ${c.dim(printable(`holds ${(r.secrets ?? []).join(", ")} and can run code`))}`);
14063
+ }
14064
+ // One line per flow with an agent not accepted, naming EVERY agent of
14065
+ // that flow (accepted ones too): the list replaces the flow's, so a line
14066
+ // naming only the new one would take the others' acceptance away.
14067
+ for (const flow of [...new Set(risks.filter((r) => !r.accepted).map((r) => r.flow))]) {
14068
+ const all = [...new Set(risks.filter((r) => r.flow === flow).map((r) => printable(r.agent)))].sort().join(",");
14069
+ console.log(` ${c.dim(`Take Bash or the secret away, or accept: \`foldrun a2a publish ${printable(flow)} --to ${ws} --accept-risk ${all}\` (an admin's)`)}`);
14070
+ }
14071
+ }
13973
14072
  if (Array.isArray(view.keys)) {
13974
14073
  console.log(`\n ${c.bold("A2A keys")}`);
13975
14074
  if (!view.keys.length) console.log(` ${c.dim(`none — \`foldrun keys create <label> --a2a --to ${ws} --flows <flow>\` mints one`)}`);
@@ -14012,6 +14111,13 @@ export function a2aPatchFor(verb, flags) {
14012
14111
  if (flags["public-card"] === true && flags["private-card"] === true) throw new Error("--public-card or --private-card, not both");
14013
14112
  if (flags["public-card"] === true) patch.public_card = true;
14014
14113
  if (flags["private-card"] === true) patch.public_card = null;
14114
+ // --accept-risk a,b (FOL-112): the agents of this flow an admin accepts
14115
+ // holding a secret while they can run code — every one, as the list is
14116
+ // written (it replaces the flow's). --clear-accept-risk takes it out.
14117
+ const accept = many(flags["accept-risk"]).flatMap((v) => v.split(",")).map((v) => v.trim()).filter(Boolean);
14118
+ if (accept.length && flags["clear-accept-risk"] === true) throw new Error("--accept-risk or --clear-accept-risk, not both");
14119
+ if (accept.length) patch.accept_risk = [...new Set(accept)].sort();
14120
+ if (flags["clear-accept-risk"] === true) patch.accept_risk = null;
14015
14121
  return patch;
14016
14122
  }
14017
14123
 
@@ -14041,6 +14147,11 @@ async function a2aPublishCmd(verb, flow, flags, layout) {
14041
14147
  const matter = (await import("gray-matter")).default;
14042
14148
  const { patchFrontmatter } = await import("@foldrun/core/agents-md");
14043
14149
  const patch = a2aPatchFor(verb, flags);
14150
+ // accept_risk (FOL-112) is a newer key: a core that does not read it would
14151
+ // call it unknown and refuse the edit for a reason that is not one.
14152
+ if ("accept_risk" in patch && pub.parseA2aPublish?.({ publish: true, accept_risk: ["x"] }) == null) {
14153
+ throw new Error("--accept-risk needs an @foldrun/core that knows a2a: accept_risk — this install's is older; update foldrun (npm i -g foldrun@latest)");
14154
+ }
14044
14155
  const code = await flowEditCmd(flags, layout, {
14045
14156
  flow,
14046
14157
  what: `a2a ${verb}`,
@@ -14552,6 +14663,7 @@ export async function run(command, positional, flags, workspace, layout) {
14552
14663
  // `runs` was a second spelling of `logs`, and --local keeps it one:
14553
14664
  // the local store has no table to draw across workspaces, because a
14554
14665
  // folder on a laptop is one workspace.
14666
+ if (positional[0] === "rm" && flags.until !== undefined) return runsRmUntilCmd(positional.slice(1), flags);
14555
14667
  if (positional[0] === "rm") return positional.length > 2 ? runsRmManyCmd(positional.slice(1), flags, layout) : runRmCmd(positional[1], flags, layout);
14556
14668
  if (positional[0] === "outputs") return runsOutputsCmd(positional.slice(1), flags, layout);
14557
14669
  if (positional[0] === "views" && positional[1]) return runViewsEditCmd(positional.slice(1), flags);
package/src/guide.mjs CHANGED
@@ -30,7 +30,7 @@ export function agentRulesBlock() {
30
30
 
31
31
  # Read foldrun's docs before you edit this folder
32
32
 
33
- This is a foldrun account: agents, flows, tools and knowledge as markdown, run by foldrun. Its formats — frontmatter fields, step options, \`verify:\` prefixes, which folder a file goes in — are foldrun's own and may differ from your training data. Before you write or change an agent, flow, tool or skill, read the relevant guide: \`foldrun docs\` lists them and \`foldrun docs <page>\` prints one (start with \`foldrun docs coding-agents\`). They ship with the CLI, so they match the version you are driving. Check every edit with \`foldrun check\` — offline, no model calls; it is also the security scanner (a key written into a file, hidden text, an agent that can leak), and \`foldrun check --security\` fails on what it finds. Never paste a credential into a file: \`foldrun secrets set NAME\` and write \`\${NAME}\`. For a flow's shape, \`foldrun flow show <flow>\` draws it, and \`foldrun flow add\`, \`foldrun flow rm-step\`, \`foldrun flow dup-step\` and \`foldrun agent link\` make the same edits as the dashboard canvas (patterns, sub-agents, consults, \`ask\`). An agent with \`tools: [peers]\` can message the steps running beside it in its parallel group (\`peers_message\`) and ask for what they have instead of guessing or failing (\`foldrun docs agents\`). A sub-agent that reads untrusted content (web pages, mail, uploads) gets \`sandbox: own\` in its own file: each job then runs in a sandbox of its own with its own tools, secrets and network, and only its reply and the files it wrote reach the agent that delegated (\`foldrun agent link <agent> --subagent <worker> --isolated\`). A script tool's own \`secrets: [NAMES]\` are granted with the tool; list on an agent only the secrets it uses directly. A hook (\`hooks/<name>/hook.md\` + \`run.mjs\`, turned on with \`hooks: [name]\`) is code at every tool call, step start and step end — \`foldrun hook add\`/\`test\` and \`foldrun docs hooks\`. Paths to the workspace's own folders are written \`workspace/storage/…\` and \`workspace/state/…\` — in an agent's prose, a flow's options and a script's arguments — not \`../../\`, which still works but is the older spelling. Which sites a step's sandbox may reach is \`network:\` — open for an agent that may fetch or browse the web, the trusted list plus what it declares for every other; add a site with \`foldrun agent network <agent> --add <site>\` (\`foldrun docs network\`). Bind a secret to the sites it is for (\`foldrun secrets sites NAME <site>\`) and no sandbox ever holds its value. What a step's sandbox may use is \`size:\` (\`small\` 1 core/1Gi, \`large\`, \`heavy\` 4 cores/8Gi — hard limits and the billed figures); \`resources: {cpu, memory, disk}\` sets the numbers yourself, key by key over the class (\`foldrun docs agents\`). What steps may hold together is capped at four levels, each only narrowing the one above: the account's and a workspace's \`compute: {vcpu, memory, disk}\` in AGENTS.md, a flow's \`compute:\` for each of its runs, and the plan's most for one step; a step past a cap waits its turn, one bigger than a whole cap fails (\`foldrun usage compute\`, \`foldrun docs budgets-and-billing\`). A webhook, email, chained or storage flow says which deliveries start it with \`filter:\` (\`foldrun flow filter <flow> --payload body.json\` tries one); an eval with \`trigger: runs\` grades a \`sample:\` of real finished runs instead of running cases, \`foldrun eval compare\` runs an eval's cases under several models side by side, and \`improve: true\` turns repeated failures into a proposed fix a person applies (\`foldrun docs evals\`). A flow is served to outside agents over A2A 1.0 when its frontmatter says \`a2a: { publish: true }\` (an admin's change; callers need an A2A key naming the flow — \`foldrun a2a publish\`, \`foldrun keys create --a2a\`), and an agent calls outside A2A agents listed in \`remotes: [{name, card, secret?}]\` with the \`a2a_send\`/\`a2a_status\` tools — never send a request twice to retry, poll its handle (\`foldrun docs a2a\`).
33
+ This is a foldrun account: agents, flows, tools and knowledge as markdown, run by foldrun. Its formats — frontmatter fields, step options, \`verify:\` prefixes, which folder a file goes in — are foldrun's own and may differ from your training data. Before you write or change an agent, flow, tool or skill, read the relevant guide: \`foldrun docs\` lists them and \`foldrun docs <page>\` prints one (start with \`foldrun docs coding-agents\`). They ship with the CLI, so they match the version you are driving. Check every edit with \`foldrun check\` — offline, no model calls; it is also the security scanner (a key written into a file, hidden text, an agent that can leak), and \`foldrun check --security\` fails on what it finds. Never paste a credential into a file: \`foldrun secrets set NAME\` and write \`\${NAME}\`. For a flow's shape, \`foldrun flow show <flow>\` draws it, and \`foldrun flow add\`, \`foldrun flow rm-step\`, \`foldrun flow dup-step\` and \`foldrun agent link\` make the same edits as the dashboard canvas (patterns, sub-agents, consults, \`ask\`). An agent with \`tools: [peers]\` can message the steps running beside it in its parallel group (\`peers_message\`) and ask for what they have instead of guessing or failing (\`foldrun docs agents\`). A sub-agent that reads untrusted content (web pages, mail, uploads) gets \`sandbox: own\` in its own file: each job then runs in a sandbox of its own with its own tools, secrets and network, and only its reply and the files it wrote reach the agent that delegated (\`foldrun agent link <agent> --subagent <worker> --isolated\`). A script tool's own \`secrets: [NAMES]\` are granted with the tool; list on an agent only the secrets it uses directly. A hook (\`hooks/<name>/hook.md\` + \`run.mjs\`, turned on with \`hooks: [name]\`) is code at every tool call, step start and step end — \`foldrun hook add\`/\`test\` and \`foldrun docs hooks\`. Paths to the workspace's own folders are written \`workspace/storage/…\` and \`workspace/state/…\` — in an agent's prose, a flow's options and a script's arguments — not \`../../\`, which still works but is the older spelling. Which sites a step's sandbox may reach is \`network:\` — open for an agent that may fetch or browse the web, the trusted list plus what it declares for every other; add a site with \`foldrun agent network <agent> --add <site>\` (\`foldrun docs network\`). Bind a secret to the sites it is for (\`foldrun secrets sites NAME <site>\`) and no sandbox ever holds its value. What a step's sandbox may use is \`size:\` (\`small\` 1 core/1Gi, \`large\`, \`heavy\` 4 cores/8Gi — hard limits and the billed figures); \`resources: {cpu, memory, disk}\` sets the numbers yourself, key by key over the class (\`foldrun docs agents\`). What steps may hold together is capped at four levels, each only narrowing the one above: the account's and a workspace's \`compute: {vcpu, memory, disk}\` in AGENTS.md, a flow's \`compute:\` for each of its runs, and the plan's most for one step; a step past a cap waits its turn, one bigger than a whole cap fails (\`foldrun usage compute\`, \`foldrun docs budgets-and-billing\`). A webhook, email, chained or storage flow says which deliveries start it with \`filter:\` (\`foldrun flow filter <flow> --payload body.json\` tries one); an eval with \`trigger: runs\` grades a \`sample:\` of real finished runs instead of running cases, \`foldrun eval compare\` runs an eval's cases under several models side by side, and \`improve: true\` turns repeated failures into a proposed fix a person applies (\`foldrun docs evals\`). A flow is served to outside agents over A2A 1.0 when its frontmatter says \`a2a: { publish: true }\` (an admin's change, as is widening what its agents may reach once it is published; callers need an A2A key naming the flow — \`foldrun a2a publish\`, \`foldrun keys create --a2a\`; its answer goes back to the caller, so an agent of it that holds a secret and can run code is refused until an admin names it in \`accept_risk:\`), and an agent calls outside A2A agents listed in \`remotes: [{name, card, secret?}]\` with the \`a2a_send\`/\`a2a_status\` tools — never send a request twice to retry, poll its handle (\`foldrun docs a2a\`).
34
34
 
35
35
  This block is for coding tools. It is written and re-added by the foldrun CLI, and the runtime strips it, so the agents that run here never see it; the rest of this file is the account's own context, which they do read. Committing the block with your work keeps the tree clean.
36
36