foldrun 17.0.0 → 17.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/foldrun.mjs +6 -3
- package/docs/a2a.md +103 -5
- package/docs/agents.md +10 -4
- package/docs/api.md +9 -9
- package/docs/budgets-and-billing.md +42 -0
- package/docs/checks.md +25 -5
- package/docs/cli.md +9 -6
- package/docs/flows.md +1 -1
- package/docs/runs.md +125 -8
- package/docs/security.md +93 -0
- package/docs/self-hosting.md +4 -1
- package/docs/team-and-access.md +3 -3
- package/package.json +3 -3
- package/src/commands.mjs +124 -12
- package/src/guide.mjs +1 -1
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
|
|
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**.
|
|
93
|
-
|
|
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
|
-
-
|
|
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
|
-
—
|
|
317
|
-
|
|
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,16 @@ 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
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
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. On a laptop (`foldrun run` with no container) there is nothing to
|
|
522
528
|
install into: the list is reported as assumed present.
|
|
523
529
|
|
|
524
530
|
Manim, for one, needs all four of its kinds at once:
|
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
|
|
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`);
|
|
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
|
|
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
|
|
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 `
|
|
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
|
|
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
|
|
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
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
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
|
|
98
|
-
| `foldrun
|
|
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
|
|
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
|
|
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,
|
|
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
|
|
174
|
-
the
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
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
|
-
|
|
457
|
-
|
|
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
|
@@ -137,6 +137,23 @@ The pattern that follows from it, and that the reference desks use: the
|
|
|
137
137
|
tool that *proposes* a change and the tool that *applies* it are two tools,
|
|
138
138
|
and only the step after a human gate holds the second.
|
|
139
139
|
|
|
140
|
+
### Flows published to outside agents
|
|
141
|
+
|
|
142
|
+
A flow published over [A2A](a2a) answers whoever holds a key for it, so its
|
|
143
|
+
**answer is a way out** as much as a network is. Two rules hold on the
|
|
144
|
+
platform, by every door into the files (since 5 Nov 2026):
|
|
145
|
+
|
|
146
|
+
- **Secret and code.** An agent of a published flow that holds a secret in
|
|
147
|
+
its sandbox and can run code could be asked to print the secret into its
|
|
148
|
+
answer. Such a flow is not published, and takes no new task, until an
|
|
149
|
+
admin names the agent in `a2a: accept_risk` — recorded in the flow's
|
|
150
|
+
history and the audit log ([accept_risk](a2a#secret-and-code-accept_risk)).
|
|
151
|
+
- **Only an admin widens it.** Publishing is an admin's approval of what the
|
|
152
|
+
flow's agents can reach. An editor's change that gives one of them a new
|
|
153
|
+
tool, secret, API, network, sub-agent or step, or takes a hook away, is
|
|
154
|
+
refused; an admin's is audited
|
|
155
|
+
([details](a2a#an-editor-cannot-widen-a-published-flow)).
|
|
156
|
+
|
|
140
157
|
## Gates and the record
|
|
141
158
|
|
|
142
159
|
A `!` on a step parks the run for a person, and the run cannot proceed
|
|
@@ -153,6 +170,82 @@ use and role change is in the audit log; every step's tool calls, script
|
|
|
153
170
|
runs and refusals are in the run's events. A run can be reconstructed from
|
|
154
171
|
its record.
|
|
155
172
|
|
|
173
|
+
## What our telemetry carries
|
|
174
|
+
|
|
175
|
+
Your run's record — its prompts, replies, files, tool arguments and errors —
|
|
176
|
+
is yours, in your workspace, and goes where you send it (`telemetry:` to your
|
|
177
|
+
own OpenTelemetry collector, `notify:` to your webhook). The platform's own
|
|
178
|
+
logs and metrics are a different thing: they leave the cluster for our
|
|
179
|
+
operations stack, and they never carry your content.
|
|
180
|
+
|
|
181
|
+
| Carries | Never carries |
|
|
182
|
+
|---|---|
|
|
183
|
+
| ids: account, run, job, task, lease, pod | prompts, replies, a step's output |
|
|
184
|
+
| the names of your workspaces, flows, agents and evals | file names or contents, knowledge, memory |
|
|
185
|
+
| counts, durations, bytes, dollars, HTTP status | tool or script arguments and results |
|
|
186
|
+
| an error's class (`timeout`, `oom`, `disk_full`, `model_error`, `network_error`, `policy_denied`, `user_code_error`, `not_found`, `cancelled`, `platform_error`), its type, its errno or SQLSTATE, and where in **our** code it happened | an error's message or stack text, a model process's stderr, a query or its values |
|
|
187
|
+
| a reason word from a fixed set (`paused`, `no_egress_url`) | URLs, email addresses, anything with a space in it |
|
|
188
|
+
|
|
189
|
+
It holds by construction, not by care:
|
|
190
|
+
|
|
191
|
+
- **One writer.** Every platform log line is built from a closed list of
|
|
192
|
+
fields, each with a shape: a number, a short word, or an id with no space,
|
|
193
|
+
quote, slash, colon or `@`. A value that does not fit is dropped, not
|
|
194
|
+
shortened. An error gives its class and code, never its words.
|
|
195
|
+
- **One boundary.** Every hosted process (web, worker, egress, assistant)
|
|
196
|
+
replaces its console and its stdout/stderr at start. Anything else that
|
|
197
|
+
prints — our older code, a dependency, Next.js — becomes "a line was
|
|
198
|
+
printed here", never what it said.
|
|
199
|
+
- **A second line at the collector.** The log shipper forwards a line only
|
|
200
|
+
if it is exactly such a line, and never reads the namespace where steps
|
|
201
|
+
run.
|
|
202
|
+
- **Tests.** A process inside the boundary tries every way to print a
|
|
203
|
+
marker (an error's message, stack, name and code; a forged envelope; a
|
|
204
|
+
raw write; an uncaught rejection) and the test reads the raw bytes; the
|
|
205
|
+
source of core, platform and web is scanned for any log call that prints
|
|
206
|
+
more than a literal; and metrics may only have fixed names and labels.
|
|
207
|
+
|
|
208
|
+
The incident this answers: a judge's model process crashed, and the full
|
|
209
|
+
text of its error — which carried prompt text — went to the server log.
|
|
210
|
+
Today that line is `model.process_failed` with `errorClass: model_error`.
|
|
211
|
+
|
|
212
|
+
A self-hosted install writes the same lines to its own logs;
|
|
213
|
+
`FOLDRUN_LOG_MODE=raw` on a process puts it outside the boundary, for
|
|
214
|
+
debugging on your own machine. On a laptop (`foldrun run`, `next dev`) there
|
|
215
|
+
is no boundary: the reader is the person whose content it is, and errors
|
|
216
|
+
print in full.
|
|
217
|
+
|
|
218
|
+
## What we keep, and for how long
|
|
219
|
+
|
|
220
|
+
Two kinds of record, kept for different lengths of time (5 Nov 2026). The
|
|
221
|
+
install's operator sets both. These are what foldrun's hosted platform uses;
|
|
222
|
+
an install that sets neither keeps everything, as before 5 Nov 2026.
|
|
223
|
+
|
|
224
|
+
| What | Holds | Kept | Deleted by |
|
|
225
|
+
|---|---|---|---|
|
|
226
|
+
| **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)) |
|
|
227
|
+
| Your files | `storage/`, `knowledge/`, `memory/`, `state/`, your agents and flows | until you delete them | you (`foldrun storage rm`, a deploy that drops a file) |
|
|
228
|
+
| **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 |
|
|
229
|
+
| The ledger | what each run and pod session was charged | for good — a financial record | never |
|
|
230
|
+
| 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 |
|
|
231
|
+
|
|
232
|
+
Every period counts from when the record was written (a run: when it
|
|
233
|
+
finished), and the daily pass deletes on its first round after the day. A
|
|
234
|
+
run whose charge has not yet been recorded is kept until it is. `0` keeps a
|
|
235
|
+
record for ever. An install without a database keeps its audit log in a
|
|
236
|
+
file, numbered by line, and does not prune it.
|
|
237
|
+
|
|
238
|
+
Closing the account (Settings → Account) suspends it at once and tells the
|
|
239
|
+
platform team, who settle the last invoice and delete the account's data:
|
|
240
|
+
its records, files, keys and sessions. The ledger and the audit entry that
|
|
241
|
+
says it was deleted are kept. Backups are their own matter:
|
|
242
|
+
[what they hold](backups-and-restore).
|
|
243
|
+
|
|
244
|
+
When a run fails because a platform security control stopped it, the run
|
|
245
|
+
says only that — *This step was stopped by a platform security control* —
|
|
246
|
+
never what was seen or how. What the control recorded is security evidence
|
|
247
|
+
and is kept with it.
|
|
248
|
+
|
|
156
249
|
## People
|
|
157
250
|
|
|
158
251
|
Four roles, least privilege by route, one owner. See
|
package/docs/self-hosting.md
CHANGED
|
@@ -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).
|
|
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
|
|
package/docs/team-and-access.md
CHANGED
|
@@ -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
|
|
182
|
-
|
|
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.
|
|
3
|
+
"version": "17.1.0",
|
|
4
4
|
"description": "Agents are just folders. Write them, check them, run them — on your machine.",
|
|
5
5
|
"license": "FSL-1.1-ALv2",
|
|
6
6
|
"type": "module",
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
"node": ">=22"
|
|
12
12
|
},
|
|
13
13
|
"dependencies": {
|
|
14
|
-
"@foldrun/core": "^15.
|
|
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.
|
|
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
|
|
10798
|
-
*
|
|
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
|
-
|
|
10816
|
-
|
|
10817
|
-
|
|
10818
|
-
|
|
10819
|
-
|
|
10820
|
-
|
|
10821
|
-
|
|
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
|
|