foldrun 26.3.3 → 26.3.5
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 +60 -60
- package/docs/a2a.md +12 -12
- package/docs/agents.md +21 -21
- package/docs/api-usage.md +2 -2
- package/docs/api.md +98 -98
- package/docs/assistant.md +21 -21
- package/docs/backups-and-restore.md +11 -11
- package/docs/budgets-and-billing.md +21 -21
- package/docs/checks.md +19 -19
- package/docs/cli.md +100 -100
- package/docs/coding-agents.md +8 -8
- package/docs/deploying.md +7 -7
- package/docs/evals.md +6 -6
- package/docs/extract.md +1 -1
- package/docs/faq.md +5 -5
- package/docs/feature-flags.md +1 -1
- package/docs/flows.md +14 -14
- package/docs/four-jobs.md +5 -5
- package/docs/getting-started.md +10 -10
- package/docs/glossary.md +9 -9
- package/docs/hooks.md +5 -5
- package/docs/how-it-works.md +1 -1
- package/docs/introduction.md +4 -4
- package/docs/knowledge-and-memory.md +6 -6
- package/docs/mcp.md +15 -15
- package/docs/network.md +9 -9
- package/docs/notifications.md +16 -16
- package/docs/oauth.md +1 -1
- package/docs/providers.md +6 -6
- package/docs/runs.md +28 -28
- package/docs/scheduling.md +1 -1
- package/docs/secrets.md +22 -22
- package/docs/security.md +15 -15
- package/docs/self-hosting.md +18 -18
- package/docs/status.md +1 -1
- package/docs/storage-and-sharing.md +14 -14
- package/docs/team-and-access.md +29 -29
- package/docs/tools.md +20 -20
- package/docs/troubleshooting.md +4 -4
- package/docs/workspaces.md +43 -43
- package/package.json +2 -2
- package/src/commands.mjs +131 -131
- package/src/guide.mjs +1 -1
package/docs/mcp.md
CHANGED
|
@@ -35,8 +35,8 @@ you choose:
|
|
|
35
35
|
|
|
36
36
|
- **what it may do** — read only (inbox, runs, flows, files), or read and act
|
|
37
37
|
(also start and stop runs, approve gates, answer and message agents, and
|
|
38
|
-
create
|
|
39
|
-
- **which
|
|
38
|
+
create projects and write or delete their files);
|
|
39
|
+
- **which projects** — every one you may open, or the ones you tick.
|
|
40
40
|
|
|
41
41
|
**Connect** sends you back to claude.ai, connected; **Deny** sends it a no.
|
|
42
42
|
It is the same in the Claude apps on a phone, which share claude.ai's
|
|
@@ -82,7 +82,7 @@ address and the same lines.
|
|
|
82
82
|
|
|
83
83
|
Every app connected over OAuth is listed in Settings → API keys → **Connected
|
|
84
84
|
AI apps**: the app, where its answers went, whose approval, what access and
|
|
85
|
-
which
|
|
85
|
+
which projects, when it was connected and last used. **Disconnect** ends it —
|
|
86
86
|
every token it holds stops at once — and the person can connect it again. You
|
|
87
87
|
see your own; an admin sees everyone's and may disconnect any.
|
|
88
88
|
|
|
@@ -93,7 +93,7 @@ foldrun mcp disconnect <id> # asks first; --yes on a pipe
|
|
|
93
93
|
|
|
94
94
|
What a connection may do is decided at every call, not only when it was
|
|
95
95
|
approved: it acts as the person who approved it, at the lower of the role
|
|
96
|
-
they chose then and the role they hold now, in the
|
|
96
|
+
they chose then and the role they hold now, in the projects both allow. A
|
|
97
97
|
person who leaves the account, or is made a viewer, takes their apps with
|
|
98
98
|
them. The access token lasts an hour and opens `/api/mcp` only — sent to any
|
|
99
99
|
other route it is refused. Refresh tokens rotate on every use, and one used
|
|
@@ -101,11 +101,11 @@ twice disconnects the app: someone else has a copy. **Machine clients.** A progr
|
|
|
101
101
|
nightly job, a CI step or another service, can sign in with client
|
|
102
102
|
credentials. An admin registers it in Settings → API keys → Connected AI apps
|
|
103
103
|
(**Add a machine client**), or with `foldrun mcp clients add <name>`, choosing
|
|
104
|
-
its role, its
|
|
104
|
+
its role, its projects, and whether it may act or only read. It gets a
|
|
105
105
|
client id and a secret, shown once, or it registers public keys and signs
|
|
106
106
|
assertions (`private_key_jwt`). It asks the token endpoint with
|
|
107
107
|
`grant_type=client_credentials` and gets an access token for an hour, with no
|
|
108
|
-
refresh token: it simply asks again. It acts within the role and
|
|
108
|
+
refresh token: it simply asks again. It acts within the role and projects of
|
|
109
109
|
the admin who registered it, and stops if that admin loses them. It is listed
|
|
110
110
|
with the connected apps, and disconnecting it ends it at once: its next token
|
|
111
111
|
request is refused with `invalid_client`.
|
|
@@ -127,15 +127,15 @@ and that automatic disconnect are in the audit log (`mcp.connected`,
|
|
|
127
127
|
|
|
128
128
|
| tool | does | route |
|
|
129
129
|
|---|---|---|
|
|
130
|
-
| `whoami` | the account, role and
|
|
131
|
-
| `list_workspaces` | the
|
|
130
|
+
| `whoami` | the account, role and projects this key acts for | `GET /api/me` |
|
|
131
|
+
| `list_workspaces` | the projects it may open | `GET /api/workspaces` |
|
|
132
132
|
| `inbox` | what waits on you: approvals, questions, issues, proposed fixes, your failed runs (`bucket`, `kind`, `workspace`) | `GET /api/me/inbox` |
|
|
133
133
|
| `list_approvals` | every gate waiting on a person, and every question an agent is asking | `GET /api/approvals` |
|
|
134
|
-
| `list_flows` | a
|
|
135
|
-
| `list_agents` | a
|
|
134
|
+
| `list_flows` | a project's flows | `GET …/flows` |
|
|
135
|
+
| `list_agents` | a project's agents: what each is for and when it last ran | `GET …/agents` |
|
|
136
136
|
| `list_runs` | recent runs, with outcome, summary and failure (`limit` up to 100, default 20; `flow` keeps that flow's among the newest 500) | `GET …/runs` |
|
|
137
137
|
| `get_run` | one run in full | `GET …/runs/<id>` |
|
|
138
|
-
| `read_file` | one file of a
|
|
138
|
+
| `read_file` | one file of a project's source (with its `sha256`), or the tree | `GET …/source` |
|
|
139
139
|
| `check_workspace` | what `foldrun check` says about a workspace: findings with rule ids (`security: true` for the security rules alone) | `GET …/check` |
|
|
140
140
|
| `run_flow` | start a flow (`task`, `test: true` for a [test run](runs#test-runs), `context` for a turn of a [conversation](runs#conversations), `inputs` for [files](runs#inputs)) | `POST …/flows/<flow>/run` |
|
|
141
141
|
| `run_agent` | run one agent on a task of your own, in its own sandbox, no flow needed (`task`, `test: true` for a [test run](runs#test-runs), `context` for a turn of a [conversation](runs#conversations), `inputs` for [files](runs#inputs)); answers a run id at once — read it with `get_run` | `POST …/agents/<agent>/run` |
|
|
@@ -143,7 +143,7 @@ and that automatic disconnect are in the audit log (`mcp.connected`,
|
|
|
143
143
|
| `answer_question` | answer an agent's question mid-step | `POST …/runs/<id>/answer` |
|
|
144
144
|
| `message_run` | say something to a running agent | `POST …/runs/<id>/message` |
|
|
145
145
|
| `stop_run` | stop a run | `POST …/runs/<id>/stop` |
|
|
146
|
-
| `create_workspace` | a new, blank
|
|
146
|
+
| `create_workspace` | a new, blank project — an `AGENTS.md` and nothing else; refused when the name is taken | `POST /api/workspaces` |
|
|
147
147
|
| `write_file` | create or replace one file — an agent, a flow, knowledge, a skill, `AGENTS.md` (`message` for the revision, `if_match` below) | `PUT …/source` |
|
|
148
148
|
| `delete_file` | delete one file or folder | `DELETE …/source` |
|
|
149
149
|
|
|
@@ -161,7 +161,7 @@ build an automation, not only drive one: `create_workspace`, then
|
|
|
161
161
|
`test: true`.
|
|
162
162
|
|
|
163
163
|
- **A file written is live at once.** The next run reads it; there is no
|
|
164
|
-
separate deploy. Each write is a revision in the
|
|
164
|
+
separate deploy. Each write is a revision in the project's
|
|
165
165
|
[History](deploying#history-and-rollback), so a mistake is undone from there.
|
|
166
166
|
- **It is checked as a deploy checks it.** A file with an error (a flow
|
|
167
167
|
naming an agent that is not there, frontmatter YAML cannot read) is
|
|
@@ -179,10 +179,10 @@ folder and `foldrun deploy` it ([CLI](cli)); both reach the same files.
|
|
|
179
179
|
|
|
180
180
|
Nothing a key could not. Each tool is a call to the route in the table, made
|
|
181
181
|
with the same key — so a viewer's key cannot start, approve or stop; a key
|
|
182
|
-
scoped to some
|
|
182
|
+
scoped to some projects sees and touches only those; an
|
|
183
183
|
[A2A key](a2a#a2a-keys) is refused (it opens `/a2a` and nothing else); and
|
|
184
184
|
every check, limit and refusal is the route's own. A tool whose route refused
|
|
185
|
-
answers `isError: true` with the route's words: `HTTP 403: this
|
|
185
|
+
answers `isError: true` with the route's words: `HTTP 403: this project is
|
|
186
186
|
not one you were given access to`.
|
|
187
187
|
|
|
188
188
|
`inbox` is a person's: a key minted by a person (every key from Settings, and
|
package/docs/network.md
CHANGED
|
@@ -81,9 +81,9 @@ A site is a domain or `*.domain` — no scheme, no path, no port; every port
|
|
|
81
81
|
of the host is covered. `*.example.com` covers `api.example.com`,
|
|
82
82
|
`a.b.example.com` and `example.com` itself. Quote a wildcard in YAML.
|
|
83
83
|
|
|
84
|
-
It is read on the agent, in the
|
|
84
|
+
It is read on the agent, in the project's `AGENTS.md` and in the account's
|
|
85
85
|
`AGENTS.md`. The level and `defaults` are nearest-wins — the agent's, else the
|
|
86
|
-
|
|
86
|
+
project's, else the account's. The `allow` lists add up across all three,
|
|
87
87
|
so a site every agent needs is written once, in the account's `AGENTS.md`.
|
|
88
88
|
|
|
89
89
|
`foldrun check` and every deploy refuse a value they cannot read — a level
|
|
@@ -229,14 +229,14 @@ say which applies to an agent.
|
|
|
229
229
|
|
|
230
230
|
The list is refused when any one of three says so:
|
|
231
231
|
|
|
232
|
-
- `network_enforce: true` in the account's `AGENTS.md` — every
|
|
233
|
-
- `network_enforce: true` in a
|
|
232
|
+
- `network_enforce: true` in the account's `AGENTS.md` — every project;
|
|
233
|
+
- `network_enforce: true` in a project's `AGENTS.md` — that project;
|
|
234
234
|
- `FOLDRUN_NETWORK_ENFORCE=1` on the install's worker — every account.
|
|
235
235
|
|
|
236
|
-
Each only switches it on. A
|
|
236
|
+
Each only switches it on. A project cannot turn off what its account
|
|
237
237
|
turned on, and nothing in an account turns off the install's. Settings →
|
|
238
|
-
Policies → Guardrail, on the account's and a
|
|
239
|
-
`foldrun account set network_enforce on` / `foldrun
|
|
238
|
+
Policies → Guardrail, on the account's and a project's Settings, has the switch, and so does
|
|
239
|
+
`foldrun account set network_enforce on` / `foldrun project set
|
|
240
240
|
network_enforce on --to <workspace>`.
|
|
241
241
|
|
|
242
242
|
Until one of them says so, the proxy only **reports**: a site off the list
|
|
@@ -394,7 +394,7 @@ each call there through the egress proxy and gets back what the call wrote:
|
|
|
394
394
|
does in the step — clicks, fills, frames, `js=` and `eval` (which run in
|
|
395
395
|
the page, as always), screenshots, PDFs, video, HAR, downloads (they come
|
|
396
396
|
back to the path the call names), uploads (the file is sent from the
|
|
397
|
-
|
|
397
|
+
project), `session=` (kept as the browser's storage state in
|
|
398
398
|
`outputs/.browser/<name>/`, as on the account's browser pod), saved logins
|
|
399
399
|
(`state:` and `state_key:`, read from and written to `state/browser/`),
|
|
400
400
|
aria numbers, `mode=diff` and `mode=crawl`. The live view streams as before.
|
|
@@ -406,7 +406,7 @@ each call there through the egress proxy and gets back what the call wrote:
|
|
|
406
406
|
- **What stays in the step**, exactly as before, saying so on the call: a
|
|
407
407
|
`live:` session, engines other than Chromium and Chrome (Firefox, WebKit,
|
|
408
408
|
Lightpanda, Obscura), `extensions:`, `proxy=`, a vendor's browser, a page
|
|
409
|
-
on the sandbox's own machine or a private address, and a
|
|
409
|
+
on the sandbox's own machine or a private address, and a project whose
|
|
410
410
|
copy of the `web` tool was edited (the service runs foldrun's own program,
|
|
411
411
|
never an edited one). A call the service could not start runs in the step;
|
|
412
412
|
a call that started there and was cut off is **not** run again — it may
|
package/docs/notifications.md
CHANGED
|
@@ -24,7 +24,7 @@ notify:
|
|
|
24
24
|
|
|
25
25
|
A bare string is whichever destination it looks like: `notify: ops@example.com`.
|
|
26
26
|
|
|
27
|
-
`${NAME}` is filled from the vault, the
|
|
27
|
+
`${NAME}` is filled from the vault, the project's first and then the
|
|
28
28
|
account's, as for an agent. A secret [bound to sites](secrets#bound-to-sites)
|
|
29
29
|
is filled only when the URL's host is one of them — bind `SLACK_WEBHOOK_URL`
|
|
30
30
|
to `hooks.slack.com` and it goes there and nowhere else; named in a URL to
|
|
@@ -95,7 +95,7 @@ which is the class of failure that otherwise reaches nobody:
|
|
|
95
95
|
|---|---|
|
|
96
96
|
| `quarantined` | a flow's `disable_after:` tripped and it has stopped firing |
|
|
97
97
|
| `sla` | a run has passed its flow's `sla:` and is still going |
|
|
98
|
-
| `budget` | a
|
|
98
|
+
| `budget` | a project has spent 80%, then 95%, of its `budget:` for the window — today, this week or this month |
|
|
99
99
|
| `security` | the daily rescan found a security finding that was not there before — see [Checks](checks#online-checks-and-the-daily-rescan) |
|
|
100
100
|
| `room` | a run has waited an hour for room to start (`FOLDRUN_ROOM_ALERT_MIN`) — it keeps its place and starts when there is room; see [waiting for room](budgets-and-billing#waiting-for-room) |
|
|
101
101
|
|
|
@@ -112,7 +112,7 @@ of them, leave `failed` out of the list.
|
|
|
112
112
|
|
|
113
113
|
## Thresholds: `alerts:`
|
|
114
114
|
|
|
115
|
-
A failure is told when it happens. A
|
|
115
|
+
A failure is told when it happens. A project can also ask to hear when a
|
|
116
116
|
pattern crosses a line, with `alerts:` in its `AGENTS.md` (or the account's):
|
|
117
117
|
|
|
118
118
|
```yaml
|
|
@@ -127,9 +127,9 @@ alerts:
|
|
|
127
127
|
new_host: true # an agent reached a site it never reached before
|
|
128
128
|
```
|
|
129
129
|
|
|
130
|
-
A
|
|
130
|
+
A project's `alerts:` replaces the account's whole: once it has its own,
|
|
131
131
|
the account's thresholds no longer apply there, and `alerts: {}` means none
|
|
132
|
-
for that
|
|
132
|
+
for that project (`new_host: false` turns off one the account has on).
|
|
133
133
|
Without an `alerts:` of its own it takes the account's.
|
|
134
134
|
|
|
135
135
|
Each comes to `notify:` as event `alert` — like the three above it follows
|
|
@@ -176,19 +176,19 @@ has checked, through a mail domain nobody has verified — and on 2026-09-06
|
|
|
176
176
|
every run email had been going to a bin for weeks, with silence as the only
|
|
177
177
|
symptom. Silence looks exactly like nothing having gone wrong.
|
|
178
178
|
|
|
179
|
-
|
|
179
|
+
Project settings has a button that sends one real message to the saved
|
|
180
180
|
destination and reports what came back, including the provider's own words
|
|
181
181
|
on a failure. Those words are the value: "domain not verified" and "you can
|
|
182
182
|
only send to your own address" send you to two different pages, and a status
|
|
183
183
|
code sends you to neither. `POST /api/workspaces/<ws>/notify/test` is the
|
|
184
|
-
same thing. A
|
|
184
|
+
same thing. A project gets 10 test sends an hour; past that the button
|
|
185
185
|
says to wait.
|
|
186
186
|
|
|
187
187
|
## Where it is set, and the rule that bites
|
|
188
188
|
|
|
189
|
-
`notify:` lives in the account's `AGENTS.md` and every
|
|
190
|
-
A
|
|
191
|
-
the account's whole, it does not merge. A
|
|
189
|
+
`notify:` lives in the account's `AGENTS.md` and every project inherits it.
|
|
190
|
+
A project may declare its own — and when it does, its block **replaces**
|
|
191
|
+
the account's whole, it does not merge. A project that wants the account's
|
|
192
192
|
destination and events simply says nothing.
|
|
193
193
|
|
|
194
194
|
## What arrives
|
|
@@ -254,7 +254,7 @@ The URL is read from `notify:` at each attempt, so fixing a typo in it is
|
|
|
254
254
|
picked up by the next retry. The body is kept as first sent, so a retry is
|
|
255
255
|
the same bytes.
|
|
256
256
|
|
|
257
|
-
**Where to see it.** The
|
|
257
|
+
**Where to see it.** The project's Triggers page ends with *Outbound
|
|
258
258
|
webhook deliveries*: every delivery, its status, its attempts, and a
|
|
259
259
|
**Redeliver** button. From a terminal, `foldrun webhooks deliveries --to
|
|
260
260
|
<ws>` (`--failed` for the ones that gave up) and `foldrun webhooks
|
|
@@ -266,7 +266,7 @@ reject links as `[redacted]`: they decide without a login, and every role
|
|
|
266
266
|
can read the log. The receiver still gets them, on a redelivery too.
|
|
267
267
|
|
|
268
268
|
**An endpoint that stays down is switched off.** When every attempt to a
|
|
269
|
-
|
|
269
|
+
project's URL has failed for **3 days running** (the operator's
|
|
270
270
|
`FOLDRUN_WEBHOOK_DISABLE_DAYS`), the next delivery to give up after all
|
|
271
271
|
six attempts switches it off, and the platform emails the account's owner
|
|
272
272
|
once. A first attempt that fails does not switch it off on its own, however
|
|
@@ -372,15 +372,15 @@ sending, so it holds for every mail, from every part of the platform.
|
|
|
372
372
|
| `invites` | an invitation to join an account | no |
|
|
373
373
|
| `billing` | a payment failed, and the grace before runs stop | no |
|
|
374
374
|
| `account` | a notification webhook switched off after days of failures; a close request; an API route the account still calls that is being switched off | no |
|
|
375
|
-
| `run-alerts` | a
|
|
376
|
-
| `approvals` | a run waiting for you, with approve and reject links | yes — per
|
|
375
|
+
| `run-alerts` | a project's `notify:` email: failed, completed, blocked, quarantined, `sla`, `budget` | yes — per project |
|
|
376
|
+
| `approvals` | a run waiting for you, with approve and reject links | yes — per project |
|
|
377
377
|
| `low-balance` | credits below the warning level | yes |
|
|
378
378
|
| `product-updates` | what changed in foldrun | yes |
|
|
379
379
|
|
|
380
380
|
The four that cannot be turned off are how you get back into the account
|
|
381
381
|
and how you hear that something you rely on has stopped; the page shows
|
|
382
382
|
them, switched on and locked, with that reason. `run-alerts` and
|
|
383
|
-
`approvals` can be off for one
|
|
383
|
+
`approvals` can be off for one project and on for the rest (`foldrun
|
|
384
384
|
notifications set run-alerts off --to seo-desk`).
|
|
385
385
|
|
|
386
386
|
**Unsubscribing from a mail.** Every mail in an optional category carries a
|
|
@@ -390,7 +390,7 @@ List-Unsubscribe=One-Click`, so the mail client's own Unsubscribe button
|
|
|
390
390
|
works, plus a "Stop …" link at the bottom that opens a page asking first
|
|
391
391
|
(opening a link never unsubscribes — inbox scanners open links). The token
|
|
392
392
|
is signed by the install, names one address, one category and — for run
|
|
393
|
-
alerts and approvals — one
|
|
393
|
+
alerts and approvals — one project, and works for 180 days. No login is
|
|
394
394
|
needed, and the address need not belong to anyone with one: a `notify:
|
|
395
395
|
email` that reaches a shared inbox can be unsubscribed by whoever reads it.
|
|
396
396
|
A choice made this way shows on that person's Profile → Notifications, and
|
package/docs/oauth.md
CHANGED
|
@@ -55,7 +55,7 @@ authorization server (Keycloak) and against recorded provider answers.
|
|
|
55
55
|
| Resource indicators | RFC 8707 | Supported | Tokens are bound to /api/mcp. |
|
|
56
56
|
| Issuer in the authorization response | RFC 9207 | Supported | Every answer carries `iss`. |
|
|
57
57
|
| Revocation endpoint | RFC 7009 | Supported | `POST /api/mcp/oauth/revoke`: an app ends its own connection. |
|
|
58
|
-
| Client credentials for machine clients | RFC 6749 §4.4 | Supported | An admin registers a machine client (Settings, or `foldrun mcp clients add`) with a role,
|
|
58
|
+
| Client credentials for machine clients | RFC 6749 §4.4 | Supported | An admin registers a machine client (Settings, or `foldrun mcp clients add`) with a role, projects and access; no refresh token; disconnecting it makes it `invalid_client`. |
|
|
59
59
|
| Signed client assertion (private_key_jwt) | RFC 7523 §2.2 | Supported | Apps that register `jwks` or `jwks_uri` sign in with assertions; each `jti` is used once. |
|
|
60
60
|
|
|
61
61
|
## Refused on purpose
|
package/docs/providers.md
CHANGED
|
@@ -6,8 +6,8 @@ The simplest way to bring a key: **Settings → Models**, or
|
|
|
6
6
|
`foldrun account model set <provider> --key <api key>`, or
|
|
7
7
|
`PUT /api/account/model`. Pick a name from the table below (or `custom`
|
|
8
8
|
with a base URL and a format), paste an **API key**, and every step in
|
|
9
|
-
every
|
|
10
|
-
an agent, a
|
|
9
|
+
every project runs on it. No `provider:` block is needed; one written in
|
|
10
|
+
an agent, a project or the account's AGENTS.md still wins over it.
|
|
11
11
|
|
|
12
12
|
The key is stored in the account's vault, encrypted under the account's own
|
|
13
13
|
key, as `FOLDRUN_MODEL_PROVIDER`, `FOLDRUN_MODEL_API_KEY` and, for a custom
|
|
@@ -48,7 +48,7 @@ billed in credits at **foldrun's price list**
|
|
|
48
48
|
shows; `ifVersion` on the PUT) makes either refused (409) when someone
|
|
49
49
|
chose since you read it, as the Settings page does.
|
|
50
50
|
- **The order** a step's model is found in is unchanged but for one rung: a
|
|
51
|
-
`provider:` block in the agent, the
|
|
51
|
+
`provider:` block in the agent, the project or the account's AGENTS.md
|
|
52
52
|
first; then foldrun's models, when chosen; then the account's own key.
|
|
53
53
|
- **Which model a tier runs** is the platform's map for that provider
|
|
54
54
|
(`model: fast | default | max`), shown on the page and by
|
|
@@ -325,7 +325,7 @@ and the platform used to find that out the way you would: a desk failing at
|
|
|
325
325
|
five in the morning.
|
|
326
326
|
|
|
327
327
|
Once a day, every provider block this account's files actually use — the
|
|
328
|
-
account's, each
|
|
328
|
+
account's, each project's, each agent's — is asked one minimal question:
|
|
329
329
|
a single request, one token of output, at the endpoint a run would use, with
|
|
330
330
|
the key a run would send. It costs a fraction of a cent, and a year of it
|
|
331
331
|
costs less than one ordinary run. Blocks sharing an endpoint and a key are
|
|
@@ -383,7 +383,7 @@ supply is configured
|
|
|
383
383
|
```
|
|
384
384
|
|
|
385
385
|
Reset times are told in the step's own timezone, resolved by the usual
|
|
386
|
-
cascade (agent → flow →
|
|
386
|
+
cascade (agent → flow → project → account → `FOLDRUN_TIMEZONE` → UTC), so
|
|
387
387
|
a run scheduled in Sydney is not told when its quota returns in UTC.
|
|
388
388
|
|
|
389
389
|
Three things the line is careful about:
|
|
@@ -408,7 +408,7 @@ implying a wait nobody promised.
|
|
|
408
408
|
**Where the step can go next is part of the sentence.** Every refusal line
|
|
409
409
|
ends with one of three states: `trying the second supply`, `the second
|
|
410
410
|
supply refused it too`, or `no second supply is configured`. The last is a
|
|
411
|
-
deliberate arrangement, not a gap — a
|
|
411
|
+
deliberate arrangement, not a gap — a project with one provider and no
|
|
412
412
|
fallback is a normal thing to run — and it is said out loud so a step never
|
|
413
413
|
ends in silence over it.
|
|
414
414
|
|
package/docs/runs.md
CHANGED
|
@@ -19,7 +19,7 @@ Each run holds its steps in group order. A step carries:
|
|
|
19
19
|
| `turns`, `systemPromptChars`, `stopReason` | model turns, summed across attempts; the system prompt's length in characters (it rides on every turn); why the last turn ended. With the events' `bytes`, these say where a step's input tokens went. From 18 Oct 2026 |
|
|
20
20
|
| `promptLayers` | the system prompt's layers, stable ones first: `name` (`persona`, `agents.md`, `skills`, `knowledge`, `rules`, … then `memory`, `state`, `clock`), `chars`, `hash` (12 hex characters of its SHA-256) and `stable: false` on the ones that change between runs. Two steps of one agent compared layer by layer say why the [prompt cache](budgets-and-billing#prompt-caching) missed; the run page and `foldrun report` do the comparison. From 20 Oct 2026 |
|
|
21
21
|
| `costUsd`, `tokens`, `computeSecs`, `startupSecs` | what it cost and how long the sandbox lived — **summed across its attempts**. `tokens` is `{ input, output, cacheRead, cacheWrite }`: `input` is all input, and `cacheRead` and `cacheWrite` the part of it the [prompt cache](budgets-and-billing#prompt-caching) served and stored. Steps recorded before 18 Oct 2026 have only `input` and `output` |
|
|
22
|
-
| `startup` | where the step's first seconds went: when each start-up phase ended, in seconds since the step started — `services` (the account's search/browser pods up), `room` (room on the cluster to start — see [Budgets and billing](budgets-and-billing)), `applied` (sandbox created), `ready`, `files` (
|
|
22
|
+
| `startup` | where the step's first seconds went: when each start-up phase ended, in seconds since the step started — `services` (the account's search/browser pods up), `room` (room on the cluster to start — see [Budgets and billing](budgets-and-billing)), `applied` (sandbox created), `ready`, `files` (project copied in), `go` (step released), `shim`, `system` (system packages restored), `driver`, `imports`, `tools` (runtime and tools built) and `model` (the model's first text or tool call). `services` can end after `ready` and `files`: the search and browser pods boot beside the step pod, and `go` waits for them. Only the phases the step went through; `null` for a step that ran in-process, absent before 17 Oct 2026. The last attempt's |
|
|
23
23
|
| `image` | which runner image the step's sandbox ran (isolated runs on a cluster): `variant` `full` or `slim`, `why`, and `pod: true` when a browsing step ran slim and browsed through the account's browser pod ([slim steps and a lost pod](tools#slim-steps-and-a-lost-pod)) |
|
|
24
24
|
| `browserPod` | on a step that browsed through the pod from slim: `reconnects` (tries), `reconnected` (how many got through: the call went on after it) and `closedAgain` (how many reached the pod only for the call to drop again at once, when any did); when the pod was lost, `lost` (`cause` `lost` or `needs-full`, and `detail`) and `writes` (what the step had written by then, worded); then `fallback: "browser pod lost; re-ran on full"` when it had only read and ran again on the full image, or `failure` — `browser pod died after the step had written <what>` — when it had written and was not re-run |
|
|
25
25
|
| `tries` | one row per attempt, oldest first (and a `status: "lost"` row, `image: "slim"`, before the full re-run when the browser pod was lost under a slim step that had only read — see [tools](tools#slim-steps-and-a-lost-pod)): `n` (the try, numbered in the order they ran), `attempt` (the step's attempt it belongs to, only when that is not `n` — the full re-run after a lost slim try 1 is `n: 2, attempt: 1`), `status`, `costUsd`, `tokens`, `turns`, `computeSecs`, `startedAt`, `finishedAt`, the attempt's `image` and its `browserPod` line when it had one, and the attempt's last `error` when it failed. A `retry: 2` step that failed twice and then passed has three rows, and its `costUsd` is all three — the run's spend, the flow's `budget:` and the bill read the step's figure, so the figure is the total. A retry is handed what is left of the budget after the failed attempt spent, and nothing left means no retry, said on the record |
|
|
@@ -55,7 +55,7 @@ reach the model's first word; hover it for each phase's share. When the
|
|
|
55
55
|
account's search or browser pod was still booting as the step pod came up,
|
|
56
56
|
`services` reads as its own lane (`services 8.00s alongside the pod`), the
|
|
57
57
|
pod's phases keep their own shares, and `go` says how long it was held for
|
|
58
|
-
the services (`go +0.10s (held 4.00s for services)`). The
|
|
58
|
+
the services (`go +0.10s (held 4.00s for services)`). The project's
|
|
59
59
|
**Observe** page and `foldrun observe --to` roll the same breakdown up over
|
|
60
60
|
every step.
|
|
61
61
|
|
|
@@ -93,7 +93,7 @@ desk's **last 24 runs** as a strip of cells beside how many of them
|
|
|
93
93
|
completed and what went wrong (`20/22 · 2 failed`), runs today and the
|
|
94
94
|
credits charged this week. Every row and every cell opens its run.
|
|
95
95
|
|
|
96
|
-
Money on the overviews — Home, the desks list, a
|
|
96
|
+
Money on the overviews — Home, the desks list, a project's flows and
|
|
97
97
|
agents, Observe, the runs list and a run's own page — is **credits charged**:
|
|
98
98
|
the ledger's line for the run, one credit to a cent. A run the ledger has not
|
|
99
99
|
settled yet shows its list price, marked estimated (`~` in the runs list,
|
|
@@ -129,7 +129,7 @@ What each says:
|
|
|
129
129
|
`resources:`, or a plan that allows more. *The step ran out of memory.
|
|
130
130
|
Memory limit: 4 GiB; last recorded peak: 3.9 GiB* — a larger `size:` or
|
|
131
131
|
`resources: { memory: … }`. The same for cores, disk and `timeout:`. A
|
|
132
|
-
step bigger than its flow's or
|
|
132
|
+
step bigger than its flow's or project's `compute:` names that
|
|
133
133
|
`compute:`; only a limit a plan sets mentions a plan. A machine running
|
|
134
134
|
short and the cluster evicting the step is said as that — not as the
|
|
135
135
|
step over its own limit.
|
|
@@ -172,15 +172,15 @@ Every step keeps, beside its events:
|
|
|
172
172
|
content, line by line — then anything shaped like a key, and any private
|
|
173
173
|
key block. The input is what the agent asked for; a [hook](hooks) that
|
|
174
174
|
rewrote it before it ran is in the trace beside it. The content is kept
|
|
175
|
-
beside the run, not in it, counts toward the
|
|
175
|
+
beside the run, not in it, counts toward the project's storage, and goes
|
|
176
176
|
when the run is deleted or ages out.
|
|
177
177
|
|
|
178
|
-
And the run itself says **which files it ran** — the
|
|
178
|
+
And the run itself says **which files it ran** — the project's latest
|
|
179
179
|
revision when a worker first picked it up ("ran on abc1234"; a deploy's is
|
|
180
180
|
its commit) — and **how long it queued** before that. A step that runs after
|
|
181
181
|
an approval, or after a deploy mid-run, may run newer files than that.
|
|
182
182
|
|
|
183
|
-
A
|
|
183
|
+
A project that should keep no content writes `capture: metadata` in its
|
|
184
184
|
`AGENTS.md` (or the account's): model calls, tool names, sizes and timings
|
|
185
185
|
are still recorded, inputs and outputs are not.
|
|
186
186
|
|
|
@@ -215,9 +215,9 @@ telemetry:
|
|
|
215
215
|
|
|
216
216
|
In the account's `AGENTS.md` (Settings → Policies → Observability → *Send runs to your
|
|
217
217
|
tracing*, or `foldrun account telemetry set <url> --header
|
|
218
|
-
authorization='${OTEL_TOKEN}'`), or a
|
|
218
|
+
authorization='${OTEL_TOKEN}'`), or a project's, which replaces the
|
|
219
219
|
account's whole. Every run that finishes is sent as one trace. Resource
|
|
220
|
-
attributes name the account,
|
|
220
|
+
attributes name the account, project, flow and run. Ids come from the
|
|
221
221
|
run's, so a run sent twice is one trace. Test runs are not sent.
|
|
222
222
|
|
|
223
223
|
The spans follow the [OpenTelemetry GenAI semantic
|
|
@@ -351,8 +351,8 @@ the revision its new run ran ("regressed since abc1234"). Besides **Snooze
|
|
|
351
351
|
known flake (`snooze` with `times` on the API, `--times` in the CLI).
|
|
352
352
|
|
|
353
353
|
**Doctor** on an issue opens the [run doctor](assistant#the-run-doctor) on
|
|
354
|
-
its newest run, in the
|
|
355
|
-
(Home, a
|
|
354
|
+
its newest run, in the project that run is in, wherever the card is shown
|
|
355
|
+
(Home, a project's home, the Issues page): the assistant says why and
|
|
356
356
|
proposes the fix as files to save. Nothing changes until you save it; then
|
|
357
357
|
resolve the issue, or rerun and let it show "fine since". A missed schedule
|
|
358
358
|
has no run, so it has no Doctor. From a terminal: `foldrun issues doctor <id>`.
|
|
@@ -369,10 +369,10 @@ failures, BLOCKED and BAD (marked "auto"); one going wrong after that opens a
|
|
|
369
369
|
new episode. Unset (`stay-open`) a person resolves them. Platform causes and
|
|
370
370
|
missed schedules never close on their own.
|
|
371
371
|
|
|
372
|
-
The **Issues** page lists them (Open, Snoozed, Resolved, All; a
|
|
372
|
+
The **Issues** page lists them (Open, Snoozed, Resolved, All; a project's
|
|
373
373
|
own from its home), Home lists the open ones under Needs attention, and
|
|
374
374
|
`foldrun issues` and `GET /api/issues` are the same list. A platform issue
|
|
375
|
-
belongs to the account: closing it needs access to every
|
|
375
|
+
belongs to the account: closing it needs access to every project.
|
|
376
376
|
|
|
377
377
|
Each agent also has an **Activity** page: every step it has ever run, across
|
|
378
378
|
flows and direct runs, with that step's own headline. It is where "how has
|
|
@@ -381,7 +381,7 @@ this agent been going" is answered without opening runs one at a time.
|
|
|
381
381
|
## Your inbox
|
|
382
382
|
|
|
383
383
|
**Inbox**, top right and under View in the account's sidebar, is what waits
|
|
384
|
-
on *you*, across every
|
|
384
|
+
on *you*, across every project you may see, in one list: gates to approve,
|
|
385
385
|
questions agents are asking, open [issues](#issues), [proposed
|
|
386
386
|
fixes](evals#proposed-fixes) to review, and your own runs that went wrong.
|
|
387
387
|
|
|
@@ -389,9 +389,9 @@ Three tabs that never mix:
|
|
|
389
389
|
|
|
390
390
|
| tab | what is in it |
|
|
391
391
|
|---|---|
|
|
392
|
-
| **For me** | assigned to you: you are named in the flow's `approvers:`, you own the flow or agent (`owner:`, down to the
|
|
392
|
+
| **For me** | assigned to you: you are named in the flow's `approvers:`, you own the flow or agent (`owner:`, down to the project's and the account's), or you asked for the proposal |
|
|
393
393
|
| **Started by me** | runs you started: one that failed or ended BLOCKED or BAD in the last week, a gate on one (someone else must decide it — your own approval is refused), a question one is asking |
|
|
394
|
-
| **Team** | everything else waiting in your
|
|
394
|
+
| **Team** | everything else waiting in your projects, for whoever picks it up — a gate anyone may decide, an issue nobody owns |
|
|
395
395
|
|
|
396
396
|
Nothing is kept in it: each item is read from where it lives and leaves on
|
|
397
397
|
its own when it is done there — the gate decided, the issue resolved, the
|
|
@@ -403,7 +403,7 @@ so an issue that happens again after you set it aside comes back. The count
|
|
|
403
403
|
on the top bar is what is unread in For me and Started by me.
|
|
404
404
|
|
|
405
405
|
`foldrun inbox` prints the same (`--team`, `--all`, `--kind approval`); a key
|
|
406
|
-
reads the inbox of the person who minted it, within the key's own
|
|
406
|
+
reads the inbox of the person who minted it, within the key's own projects.
|
|
407
407
|
The API is `GET /api/me/inbox`.
|
|
408
408
|
|
|
409
409
|
## Gates
|
|
@@ -429,7 +429,7 @@ but skip the third one" is an instruction the publisher reads.
|
|
|
429
429
|
|
|
430
430
|
**Who may answer.** A flow's `approvers:` names the addresses that may decide
|
|
431
431
|
its gates, or `admins` for anyone at admin or above; unset, anyone who can
|
|
432
|
-
run the
|
|
432
|
+
run the project can answer. On top of that, and whatever the list says,
|
|
433
433
|
**nobody approves a run they started themselves** — a gate exists so a second
|
|
434
434
|
person looks. Rejecting your own run is always allowed. An API key carries a
|
|
435
435
|
role but no address, so a key is not caught by the self-approval rule and
|
|
@@ -466,7 +466,7 @@ What the platform does on a test run, in the order a step meets it:
|
|
|
466
466
|
| the egress proxy | any `POST`, `PUT`, `PATCH` or `DELETE` to a host that is not a model provider or a read-only service is **refused** with `403` and a JSON body `{ "test_mode": true, "would_have": { method, host, path, to, body } }`. A Resend `POST /emails` is instead **redirected**: the recipients become `delivered@resend.dev` (Resend's sink), the subject is prefixed `[TEST] `, and the call goes through — so a desk still gets a real message id. Reads (`GET`, `HEAD`, `OPTIONS`) pass. A host with no granted secret is refused as always |
|
|
467
467
|
| the sandbox | secrets whose name says they can send — `RESEND_API_KEY`, `TWILIO_*`, `GETREACH_API_KEY`, `GITHUB_TOKEN`, `MONDAY_API_TOKEN`, `OI_CRM_API_KEY`, `CLOUDFLARE_*`, `LINKEDIN_*`, `MEDIUM_COOKIES`, `TIKTOK_*` — are **withheld**: the env var reads `TEST_MODE_WITHHELD`, so a script that never checked fails at the provider with an auth error rather than sending. A step granting a script tool marked `outward: true` gets no real secret at all; one granting a tool marked `test_mode: allow` gets them all. The sandbox also has `FOLDRUN_TEST_MODE=1` and `FOLDRUN_RUN_TEST=1`, for scripts that branch on it. The http tools still go through the proxy, where the table above applies |
|
|
468
468
|
| the browser | the step is handed no account [browser pod](tools#where-the-browser-runs): the tool launches Chromium inside the run pod, which the run namespace's policy denies the internet, so a `web action=browse` call fails closed rather than fetching the world through a pod the policy does not select |
|
|
469
|
-
| the write-back | `state/` and `storage/` go into the sandbox as they are; what the step wrote there comes out under `runs/<id>/test-writes/state/…` and `…/storage/…`, and the
|
|
469
|
+
| the write-back | `state/` and `storage/` go into the sandbox as they are; what the step wrote there comes out under `runs/<id>/test-writes/state/…` and `…/storage/…`, and the project's copies are untouched. Each later step of the run gets those writes laid over its copy, times kept, so a flow that hands work on through `storage/` is tested as it runs live — the step's log says how many files it sees. Nothing is harvested to the file store and nothing under `storage/public/` is published |
|
|
470
470
|
| the record | `test: true`; the summary opens with `[test]`; a **TEST** badge beside the status in the runs list and on the run page; every refusal, redirect, diversion and withheld secret is an event carrying an `effect`, and the run page's **Test run** panel lists them — "would have written state/sends.md, +3 lines" |
|
|
471
471
|
| the rest | gates still park, and the approve page says it is a test run; notifications go out only for `failed`; a `trigger: flow` chained on a test run starts as a test run |
|
|
472
472
|
|
|
@@ -497,7 +497,7 @@ morning when one broken thing failed seventy runs. A call naming no filter is
|
|
|
497
497
|
refused rather than treated as everything, `dryRun: true` shows what would be
|
|
498
498
|
touched, and each run is its own outcome so one that cannot be stopped does
|
|
499
499
|
not abort the rest. On the runs pages, tick runs and choose **Stop** or
|
|
500
|
-
**Rerun**: the bar makes this call, once per
|
|
500
|
+
**Rerun**: the bar makes this call, once per project in the selection.
|
|
501
501
|
|
|
502
502
|
**Re-run from a group** (`from: N`) starts a new run at group N with the
|
|
503
503
|
earlier groups recorded as skipped, not invented — the step reads what earlier
|
|
@@ -517,7 +517,7 @@ waited out, a throttled trigger, a flow switched off after a bad week, an
|
|
|
517
517
|
already had its most runs waiting (*too many runs waiting* —
|
|
518
518
|
[how many runs may wait](budgets-and-billing#how-many-runs-may-wait)).
|
|
519
519
|
|
|
520
|
-
The Triggers page on each
|
|
520
|
+
The Triggers page on each project records all of it: one row per flow
|
|
521
521
|
saying how often its trigger fired, how often that became a run, and what
|
|
522
522
|
the difference was, with the key in the flow file that decided each one. Its
|
|
523
523
|
last section is the delivery log, which answers the separate and earlier
|
|
@@ -553,7 +553,7 @@ The API takes the same field: `context` on `POST …/agents/<agent>/run` and
|
|
|
553
553
|
`POST …/flows/<flow>/run` (not with `from`), and on MCP's `run_agent` and
|
|
554
554
|
`run_flow`. Over [A2A](a2a), a task's `contextId` is its context.
|
|
555
555
|
|
|
556
|
-
**What counts as an earlier turn:** a run of the same
|
|
556
|
+
**What counts as an earlier turn:** a run of the same project and context,
|
|
557
557
|
completed or failed, that had finished before this run was started. A test
|
|
558
558
|
run reads only test runs, and a real run only real ones. The cutoff is fixed
|
|
559
559
|
when the run is made, so a retry, a park at a gate or a rescue reads the same
|
|
@@ -572,7 +572,7 @@ that do not fit are left out. The step's trail says what it was given:
|
|
|
572
572
|
`conversation order-42: given 3 earlier runs (4,210 characters)`.
|
|
573
573
|
|
|
574
574
|
**Who shares a context:** runs started through the API, the dashboard, the
|
|
575
|
-
CLI or MCP share the
|
|
575
|
+
CLI or MCP share the project's contexts, so anyone who can start runs there
|
|
576
576
|
can continue one — and could read those runs anyway. A context is a way to
|
|
577
577
|
group runs, not a lock. Each outside caller over A2A has its own: two A2A keys
|
|
578
578
|
that send the same `contextId` never see each other's turns, and an A2A
|
|
@@ -584,7 +584,7 @@ list them.
|
|
|
584
584
|
|
|
585
585
|
## Inputs
|
|
586
586
|
|
|
587
|
-
A run may be handed **files**: storage paths, as the
|
|
587
|
+
A run may be handed **files**: storage paths, as the project's storage lists
|
|
588
588
|
them. The step the task reaches finds them at `inputs/` in its working
|
|
589
589
|
directory, under the same paths (`inputs/reports/q4.pdf`), and is told which
|
|
590
590
|
they are. An agent reads them with its Read tool; images and PDFs are shown to
|
|
@@ -662,7 +662,7 @@ What follows from it:
|
|
|
662
662
|
|
|
663
663
|
- **Held alone.** Each customer is held to its own limits, checked before the
|
|
664
664
|
account's own: by default **30 run starts a minute** and **10 runs open at
|
|
665
|
-
once** (queued, running or waiting at a gate, across every
|
|
665
|
+
once** (queued, running or waiting at a gate, across every project). One
|
|
666
666
|
customer past a limit is refused while your other customers carry on: too
|
|
667
667
|
many starts is `429` with `Retry-After` and code `customer_rate`; too many
|
|
668
668
|
open is `429` with code `customer_open_runs` — one must finish first. Open
|
|
@@ -675,7 +675,7 @@ What follows from it:
|
|
|
675
675
|
so calls at once cannot pass it together. A run past it is refused at its
|
|
676
676
|
next model call. None is set by default. `GET /api/customers/usage?days=7`
|
|
677
677
|
and `foldrun customers usage` show what each customer was charged.
|
|
678
|
-
- **Blocked.** An admin with every
|
|
678
|
+
- **Blocked.** An admin with every project can block a customer
|
|
679
679
|
(Settings → API keys → Customers, `foldrun customers block <id>`, or
|
|
680
680
|
`PUT /api/customers/<id>/block`). Its runs are refused at start (`403`,
|
|
681
681
|
code `customer_blocked`), and a run of it already going stops at its next
|
|
@@ -704,7 +704,7 @@ code `customer_required`).
|
|
|
704
704
|
|
|
705
705
|
Every step records what it cost. A flow's `budget:` is checked between
|
|
706
706
|
groups: the group that crosses it is the last that runs, and the run fails
|
|
707
|
-
saying so. The
|
|
707
|
+
saying so. The project's and the account's `budget:` over time sit above
|
|
708
708
|
that. See [Budgets and billing](budgets-and-billing).
|
|
709
709
|
|
|
710
710
|
## How long a run is kept
|
|
@@ -752,7 +752,7 @@ live is read whole; a finished run's reply and trace are opened by id.
|
|
|
752
752
|
The list pages by position, not by number: `GET …/runs` answers `next`, a
|
|
753
753
|
cursor for the runs older than the last one it sent, and `before=<next>`
|
|
754
754
|
asks for that page, so runs that start meanwhile shift nothing. One cursor
|
|
755
|
-
pages every
|
|
755
|
+
pages every project, which is how `foldrun runs` pages the account:
|
|
756
756
|
`--limit` sets the page, `--page 3` or `--before <cursor>` picks one (the
|
|
757
757
|
command prints the next one's cursor), and `--all` reads every run that
|
|
758
758
|
matches.
|
package/docs/scheduling.md
CHANGED
|
@@ -14,7 +14,7 @@ frontmatter.
|
|
|
14
14
|
| `webhook` | an HTTP POST reaches the flow's hook URL | the request body |
|
|
15
15
|
| `email` | a message arrives at the flow's inbox URL | from, to, subject, text |
|
|
16
16
|
| `flow` | the flow in `after:` settles the way `on:` says | that run's id, status, summary, result |
|
|
17
|
-
| `storage` | a file lands under `path:` in this
|
|
17
|
+
| `storage` | a file lands under `path:` in this project's storage | the paths and who wrote them |
|
|
18
18
|
| `watch` | the content at `url:` changes (polled every `every:`, default 15m) | the new content |
|
|
19
19
|
|
|
20
20
|
A flow may not chain on itself. `watch` records its first sighting without
|