foldrun 16.0.2 → 16.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/docs/api-usage.md CHANGED
@@ -165,6 +165,9 @@ Every error is JSON with one field you can show a person:
165
165
  { "error": "flow nightly not found" }
166
166
  ```
167
167
 
168
+ Some carry a `code` a program can branch on beside it — `unknown_api_version`,
169
+ `mail_not_configured`, `waiting_cap` — and the figures that go with it.
170
+
168
171
  | Status | Means |
169
172
  |---|---|
170
173
  | 400 | the request is malformed, or names an unknown `Foldrun-Version` |
@@ -172,7 +175,7 @@ Every error is JSON with one field you can show a person:
172
175
  | 402 | out of credit |
173
176
  | 403 | your role or scope does not cover this |
174
177
  | 404 | no such thing |
175
- | 409 | conflict — a run already live (`overlap: skip`), a file changed under `ifMatch`, an idempotent request still in flight |
178
+ | 409 | conflict — a run already live (`overlap: skip`), a file changed under `ifMatch`, an idempotent request still in flight, or the account already has its most runs waiting for their turn (`code: "waiting_cap"`, with `limit` and `waiting` — [how many runs may wait](budgets-and-billing#how-many-runs-may-wait); a webhook or inbound email gets this as a `503` with `Retry-After`) |
176
179
  | 413 | body over 10 MB |
177
180
  | 422 | a refusal to read: a deploy with issues, an Idempotency-Key reused with a different body |
178
181
  | 429 | rate limited — wait `Retry-After` |
package/docs/api.md CHANGED
@@ -159,7 +159,7 @@ installer's `error`, its cause on the first line. `foldrun deploy` polls it afte
159
159
  | `/api/workspaces/<ws>/a2a` | GET | what this workspace serves to outside agents over A2A 1.0: `{ flows: [{ flow, published, publicCard, name, description, hasInputSchema, card, url }], keys, tasks: [{ id, flow, state, runId, contextId, key: { id, label, prefix, revoked }, createdAt, updatedAt }] }` — every flow whose frontmatter says `a2a:`, the URL of its agent card and of its JSON-RPC endpoint (`/a2a/<account>/<ws>/flows/<flow>`), the workspace's live A2A keys (`[{ id, label, prefix, flows, maxTasks, expiresAt }]`, or `null` unless you may manage keys), and the 50 newest A2A tasks (`state` a `TASK_STATE_*`) with the key that asked. Publishing is the flow's `a2a:` field, written like any other — changing it needs `workspace:manage`. `404` when the workspace does not exist |
160
160
  | `/api/workspaces/<ws>/flows/<flow>` | POST, PATCH, DELETE | edit a step (`step`, `instruction`, `options`, `target`, `subflow`), rearrange (`groups`), set `trigger`, set `compute` (`{ vcpu, memGiB, diskGiB }` or `null` — what one run may hold at once, merged over what the flow says), set `a2a` (`{ publish, name, description, examples, public_card, input }` merged over the flow's `a2a:` — a key sent replaces it, `null` removes it; `a2a: null` removes the block; refused `400` when the result would not read, `403` without the admin role — see [A2A](a2a.md)), a canvas edit (`edit`, or `edits` — at most 200 in one request, `400` past that), undo (`restore` + `expect`); delete. Every PATCH and DELETE takes `expect` — the text the step numbers were read from, or its sha256 — and is refused with `409` and the current `text`, nothing written, when the file no longer reads it (the canvas, the list view's board and step options, and the CLI's `flow add`/`rm-step`/`dup-step --to` send it; the dashboard shows the 409 as "this flow changed since you opened it — reload") |
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
- | `/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 |
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 |
164
164
 
165
165
  `POST .../run` takes `task` (the input), `from` (start at step N — a rerun of
@@ -373,7 +373,7 @@ Reads return which secrets exist, never their values.
373
373
  | `/api/team/invites/<id>` | DELETE | revoke an invite: its link stops working at once. `{ ok, revoked, invite }` — `revoked: false` when it was already revoked or expired; `404` for an id that is not this account's; `409` for one already accepted (remove the member instead). `team:manage`, a key included; a scoped caller only inside its scope, and an admin invite only by the owner. Audited as `member.invite_revoked` |
374
374
  | `/api/team/members/<id>` | PATCH, DELETE | change a member's role (`role`) and/or which workspaces they may open (`workspaces`: names, or null for all); remove them. A session, or the person's own `foldrun login` key (acting as at most admin). Removing someone revokes the keys and pending invites they made and any invite still pending to their address; a lower role or fewer workspaces revokes the keys and invites that reach beyond their new standing. `404` for an id that is not a member, whatever the body |
375
375
  | `/api/team/transfer` | POST | hand the account to a member (`to`) — owner only, signed in, and re-proving it is them: `password` (the current one) and, when two-step sign-in is on, `code` (from the app, or a backup code). 400 without them, 401 when wrong, 6 tries in 15 minutes. You become an admin |
376
- | `/api/usage/compute` | GET | the account's compute at every level (27 Oct 2026): `compute` is `{ vcpu, memGiB, diskGiB, stepVcpu, stepMemGiB, stepDiskGiB, source }` — the cores, GiB and GiB of disk all its running steps may hold together, the most one step may hold (each `null` for no cap), and where the pool came from (`plan`, `account` — its own `compute:` in AGENTS.md, which can only lower it — `install`, or `null`); `inUse` is `{ vcpu, memGiB, diskGiB, steps }`, what its running steps' sandboxes hold now, from their records (a step still waiting for room holds nothing; a caller scoped to some workspaces sees theirs); `workspaces` is each workspace's own `pool` (its AGENTS.md `compute:`, `null` figures for none) and `inUse`; `runs` is each live run with a pool of its own (its flow's `compute:`) or anything held, `{ workspace, runId, flow, pool, inUse }`; `waiting` lists the steps waiting for room, oldest first — `{ workspace, runId, flow, step, agent, since, why, cpus, memGiB, diskGiB, level?, runPool }`, `since` being when it first found none, its place in line, and `level` the cap that held it when it last looked. A step past any level waits, with no time limit, and starts in turn; one bigger than a level's whole cap or the step maximum fails at once ([four levels](budgets-and-billing#compute-at-four-levels), [waiting for room](budgets-and-billing#waiting-for-room)) |
376
+ | `/api/usage/compute` | GET | the account's compute at every level (27 Oct 2026): `compute` is `{ vcpu, memGiB, diskGiB, stepVcpu, stepMemGiB, stepDiskGiB, source }` — the cores, GiB and GiB of disk all its running steps may hold together, the most one step may hold (each `null` for no cap), and where the pool came from (`plan`, `account` — its own `compute:` in AGENTS.md, which can only lower it — `install`, or `null`); `inUse` is `{ vcpu, memGiB, diskGiB, steps }`, what its running steps' sandboxes hold now, from their records (a step still waiting for room holds nothing; a caller scoped to some workspaces sees theirs); `workspaces` is each workspace's own `pool` (its AGENTS.md `compute:`, `null` figures for none) and `inUse`; `runs` is each live run with a pool of its own (its flow's `compute:`) or anything held, `{ workspace, runId, flow, pool, inUse }`; `waiting` lists the steps waiting for room, oldest first — `{ workspace, runId, flow, step, agent, since, why, cpus, memGiB, diskGiB, level?, runPool }`, `since` being when it first found none, its place in line, and `level` the cap that held it when it last looked; `runsWaiting` is `{ waiting, limit, source, slots? }` — the account's runs waiting for their turn (`null` for a caller scoped to some workspaces) and the most before a new run is refused (`null`: no limit), `source` `install` (`FOLDRUN_MAX_WAITING_RUNS`) or `derived` (20 × `slots`, the runs it may drive at once, at least 50) ([how many runs may wait](budgets-and-billing#how-many-runs-may-wait)); `compute.stepDefault`, when present, names the step figures that are the hosted default for an account whose plan sets none. A step past any level waits, with no time limit, and starts in turn; one bigger than a level's whole cap or the step maximum fails at once ([four levels](budgets-and-billing#compute-at-four-levels), [waiting for room](budgets-and-billing#waiting-for-room)) |
377
377
  | `/api/usage/budget` | GET | spend against the caps, as the Spend limits page shows it (5 Nov 2026): `account` is the account's own `budget:` — `{ budget, label, spentUsd, window }`, `budget` being `{ usd, period }` or `null` for no limit, `label` `"$60/day"` or `null`, `spentUsd` what every workspace together has spent in the cap's window (the month's with no cap) and `window` `today`, `this week` or `this month`; `workspaces` is each workspace's the same way with its name as `workspace`, most spent first. A caller scoped to some workspaces sees those, and gets `account: null` with `accountHidden: true` — the account's figure is spend over every workspace. At the cap new runs are refused until the window turns ([four caps](budgets-and-billing#four-caps)) |
378
378
  | `/api/usage/history?days=` | GET | charged spend by flow, by agent and by workspace over time, read from the ledger rather than the run records — so it survives runs being pruned and reports what was billed rather than what was consumed. Buckets by week over three weeks, by day under. Each series carries its periods, its total, and the change between the last two COMPLETE periods, so a partial week never reads as a collapse. `unattributedUsd` is charges from before a line recorded its flow. A caller scoped to some workspaces sees only the charges in those; `days` 1–365, default 56 |
379
379
  | `/api/account/model` | GET, PUT, DELETE | what every step runs on unless an agent, workspace or the account's AGENTS.md names a `provider:` — the account's own model key, or foldrun's models (the platform's keys for one provider, billed in credits at foldrun's price list; hosted only). GET: `{ set, provider, baseUrl, format, keyHint, runsOn, platformKeyAllowed, source, supply, choiceVersion, foldrunModels }` — never a key, only its last four characters; `runsOn` is `account` (its own key), `foldrun` (foldrun's models for `supply`), `platform` (the platform's credential, for the operator's accounts) or `none` (runs are refused until a key is set); `foldrunModels` is `{ offered, refused, providers: [{ name, title, available, reason, tiers }], prices: [{ provider, model, inputPerMTok, outputPerMTok, cacheReadPerMTok, cacheWritePerMTok }], dailyCapUsd, spentTodayUsd }`, the money in what the account pays. PUT `{ source: "foldrun", supply, ifVersion? }` chooses foldrun's models (`supply`: anthropic, openai, gemini, deepseek or moonshot; a provider the platform cannot serve now, or an account refused them, is a 409; a stale `ifVersion` is a 409); `{ source: "own" }` goes back to the account's own key; a key alone never changes the choice; audited as model.source_set. PUT `{ provider, apiKey, baseUrl?, format? }` (needs `secrets:write`, as does the choice): `provider` is a preset name (anthropic, openrouter, openai, groq, … — see providers) or `custom` with an https `baseUrl` and a `format` (anthropic or openai); a Claude login token (sk-ant-oat…) is refused for any account not allowed the platform's credential. Stored as the account secrets `FOLDRUN_MODEL_PROVIDER`, `FOLDRUN_MODEL_API_KEY`, `FOLDRUN_MODEL_BASE_URL`, `FOLDRUN_MODEL_FORMAT`. DELETE removes them (the choice stays). Honours Idempotency-Key on PUT; audited as model.key_set / model.key_removed |
@@ -68,7 +68,7 @@ level only narrows the one above it; a step must fit all of them.
68
68
  | **account** | the plan (or the install's `FOLDRUN_ACCOUNT_*`); `compute:` in the account's `AGENTS.md`, Settings → Governance or `foldrun account set compute` lowers it | everything the account's running steps hold together |
69
69
  | **workspace** | `compute:` in the workspace's `AGENTS.md`, its Settings → Governance, or `foldrun workspace set compute … --to <ws>` | what that workspace's running steps hold together |
70
70
  | **run** | `compute:` in the flow, the flow's card, or `foldrun flow compute <flow> …` | what one run of the flow holds at once across its parallel steps — each run has its own |
71
- | **step** | the agent's `size:` or `resources: { cpu, memory, disk }`; the plan's (or install's `FOLDRUN_STEP_MAX_*`) most for one step | one step's sandbox |
71
+ | **step** | the agent's `size:` or `resources: { cpu, memory, disk }`; the plan's (or install's `FOLDRUN_STEP_MAX_*`) most for one step — on foldrun's hosted platform an account without a plan, or whose plan sets none, gets the entry plan's | one step's sandbox |
72
72
 
73
73
  ```yaml
74
74
  # AGENTS.md (the account's or a workspace's), or a flow's frontmatter
@@ -130,6 +130,41 @@ claim that does not exist, no node that matches and none being added)
130
130
  still fails. On a self-hosted Docker install there is no room gate, so nothing
131
131
  waits.
132
132
 
133
+ ### How many runs may wait
134
+
135
+ Waiting is the rule, but not without end. An account may have a limited
136
+ number of runs **waiting for their turn** at once — lined up and not yet
137
+ started, sent back to the queue to wait for room, or let out of an approval
138
+ or a `wait:` and waiting for a worker. A run asleep on its own `wait:` timer,
139
+ at an approval gate or waiting for an event does not count, nor does a run
140
+ that is running.
141
+
142
+ - **The limit.** 20 for each run the account may drive at once (its plan's
143
+ runs at once, its own `concurrency:`, or the install's), and never fewer
144
+ than 50: Starter 50, Creator 50, Pro 80, Scale 160. An install sets one
145
+ number for every account with `FOLDRUN_MAX_WAITING_RUNS` (`0`: no limit).
146
+ - **Past it, a new run is refused at once** — never lined up and dropped
147
+ later. A person or a key gets `409` with `code: "waiting_cap"`, `limit`
148
+ and `waiting`, and the sentence: *this account already has 50 runs
149
+ waiting for their turn, its limit … nothing was started*. The dashboard
150
+ shows it where you pressed Run, and the CLI prints it. A webhook or an
151
+ inbound email gets `503` with `Retry-After: 60`, so its sender tries
152
+ again, and the delivery is not remembered as handled. An outside agent
153
+ over A2A is told the agent is busy.
154
+ - **A trigger that fires into it is skipped, not delayed.** A schedule's
155
+ fire, a watched page's change, a debounced burst, a chained or storage
156
+ trigger: each is written on the workspace's Triggers page as
157
+ *too many runs waiting*, with the sentence, and the flow waits for its
158
+ next fire. (A webhook's sender retries; nothing else does.)
159
+ - **A threshold, not a ceiling.** The limit is checked when a new run is
160
+ admitted. Runs already admitted still come back — out of a gate, a
161
+ `wait:`, or back for room — so the count can pass the limit for a while;
162
+ new runs are refused until it falls below. Two starts in the same instant
163
+ may both take the last place.
164
+ - **Seen.** Settings → Governance → Compute and `foldrun usage compute`
165
+ show *N of M runs waiting for their turn* (`runsWaiting` in
166
+ `GET /api/usage/compute`).
167
+
133
168
  ## Plans and credits
134
169
 
135
170
  Usage is sold in **credits: one credit is one cent** of what a step consumes
package/docs/cli.md CHANGED
@@ -175,7 +175,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
175
175
  | `foldrun observe` | where the account fails, retries and spends: one row per workspace — runs, failed and what share, steps, cost, and its completion rate against the window before — then the account Observe page's analysis (`GET /api/observe`): the completion rate and what was charged against the window of the same length before, **why runs went wrong** (the platform's causes first, each with its desks and what the newest said), the **agents to watch** (those that failed or retried) and the **tools to watch** (those that errored), then the recent failures in their own words. 7 days unasked, as the page (until 5 Nov 2026 it was 30). `--to <workspace>` prints that workspace in full, as its Observe page does, over 30 days unasked: per flow (runs, failed, p50/p95 duration, cost), per agent (failed, retried, skipped, p95, turns, cache hit rate), per tool (calls, errors, p95 latency, result size p50/p95 and how many results were over 10k characters, which agents use it), and start-up — each phase of a step's first seconds, its own share, when it began and when it was done, p50/p95; `services` says **in parallel** where the search and browser pods booted beside the step pod, and `go` how long it was **held** for them. `--since <days>` (or `--days`) picks any window; `--json` for the document — `{ days, account, workspaces }` account-wide (`account` the analysis, `null` from a platform without it), one workspace's report with `--to` |
176
176
  | `foldrun usage` | what the account consumed — runs, steps, tokens (with the share the prompt cache served), compute, storage, per workspace — and what it was charged over `--days <n>` (default 56) from the ledger, per workspace with the change against the period before. `--json` for both documents |
177
177
  | `foldrun usage --limit <n>` | the Usage page's **by flow** and **by agent** tables in the text output: what each flow and each agent was charged over the window, its runs and the change against the period before, most charged first — the first `n` of each (default 10; `0` hides them). `--json` has them all, in `history.byFlow` and `history.byAgent` |
178
- | `foldrun usage compute` | the cores, GiB and disk the account's running steps may hold together and in one step, at every level — the account, each workspace with a pool or anything held, each live run with its flow's pool — what each holds now, and the steps **waiting for room**, oldest first, each with its flow, agent, what it needs, how long it has waited, why and which level holds it (`GET /api/usage/compute`). A waiting step has no time limit and starts in turn; `--json` for the document. Set the levels with `foldrun account set compute …`, `foldrun workspace set compute … --to <ws>` and `foldrun flow compute <flow> …` |
178
+ | `foldrun usage compute` | the cores, GiB and disk the account's running steps may hold together and in one step, at every level — the account, each workspace with a pool or anything held, each live run with its flow's pool — what each holds now, and the steps **waiting for room**, oldest first, each with its flow, agent, what it needs, how long it has waited, why and which level holds it (`GET /api/usage/compute`). A waiting step has no time limit and starts in turn. It also prints how many of the account's **runs wait for their turn** against its limit: while that many wait, a new run is refused at once (409, `waiting_cap`) rather than lined up, and the CLI says so where you started it. `--json` for the document. Set the levels with `foldrun account set compute …`, `foldrun workspace set compute … --to <ws>` and `foldrun flow compute <flow> …` |
179
179
  | `foldrun usage budget` | the Spend limits page: the account's `budget:` and each workspace's, what is spent in its window (today, this week or this month, in the account's calendar) and how far into the cap that is — marked past the 80% warning, and at the cap with when new runs start again (`GET /api/usage/budget`). Most spent first; a workspace with no cap shows its month's spend. `--to <workspace>` for one, `--json` for the document. A key scoped to some workspaces sees those, not the account's figure. Set a cap with `foldrun account set budget …` or `foldrun workspace set budget 60/day --to <ws>` |
180
180
  | `foldrun billing` | the account's balance, whether billing is on at all, what the platform is currently waiving, and the recent ledger entries with what each was for — a run names its workspace, flow and run id; an adjustment carries its own note. `--limit <n>` shows more. `statement [YYYY-MM]` is a month of the ledger (this month by default) — `--csv` for the file an accountant wants, to stdout or `--file <path>`. `wallet` is the burn, the runway and auto top-up; `wallet set auto-top-up --threshold <usd> --amount <usd>` turns it on (a refill of 5–500), `set auto-top-up off` turns it off, `set email <address>` is where receipts go. `details` is who invoices are made out to; `details set --name "…" --abn … --address "line1, city, state, postcode, AU" --email …` changes it, merged with what is there. `portal` prints a link to Stripe's billing portal. Changing the wallet, the details, and the portal are the account owner's; anyone else is told so |
181
181
  | `foldrun billing invoices` | the Invoices tab: the plan's tax invoices from Stripe — number, date, amount and currency, status, what it was for, and Stripe's link to it — and every credit purchase with its receipt link, newest first (`GET /api/billing/invoices`). `--json` for the document. Any member or key with every workspace; one scoped to some is refused, as the statement is. An install without billing says it has none |
package/docs/network.md CHANGED
@@ -180,24 +180,71 @@ in, so a program that ignores the variables still goes direct.
180
180
 
181
181
  ### Browsing
182
182
 
183
- A step that may **browse** with the `web` tool is not held to its list yet.
184
- Its browser cannot send the proxy's password the way the other programs do,
185
- so the step gets no proxy: the browser, and every other program in that
186
- step, reach sites directly. The trace says so on its network line —
183
+ A step that may **browse** with the `web` tool is held to its list where the
184
+ platform can wall the step in: on a cluster whose operator has switched it
185
+ on (`FOLDRUN_BROWSE_ENFORCE=1`), for a step whose list is restricted
186
+ (`trusted` or `none`) and enforced. Such a step gets the proxy like any
187
+ other, its pod is walled to the egress proxy and DNS, and the browser runs
188
+ inside that pod — the step's own, shared with no other step. Whatever the
189
+ browser is told — another proxy, a new context with a proxy of its own, a
190
+ page's script — the only way out is the egress proxy, which holds the list
191
+ per connection, over IPv4 and IPv6, TCP and UDP alike. The trace says so —
187
192
 
188
193
  ```
189
- network: trusted (agent) — the trusted list (207 sites); added: example.com — not enforced in this step: it may browse, and browsing does not go through the egress proxy yet, so the browser and every other program in this step reach sites directly. Its browser is foldrun's own browser: it comes under network: when hosted enforcement ships (FOL-110).
194
+ network: trusted (agent) — the trusted list (207 sites); added: example.com — enforced — hosted: the browser runs inside this step's sandbox, whose network reaches only the egress proxy (which holds the list) and DNS, so a page, a script or a changed proxy setting reaches no site off the list; DNS lookups themselves are not restricted.
190
195
  ```
191
196
 
192
- — and names which of three tiers the step's browser falls in, which is
193
- where it is headed:
197
+ A site off the list fails in the browser as a failed tunnel
198
+ (`ERR_TUNNEL_CONNECTION_FAILED`), and the trace names it with the usual
199
+ advice: add just that site.
200
+
201
+ What a held step does differently:
202
+
203
+ - **foldrun's own browser, in the step.** The account's browser pod is not
204
+ used (it reaches the world, and a walled pod cannot reach it), so the step
205
+ runs on the image with browsers. Chromium and Chrome take the proxy and its
206
+ password as launch options (checked through an authenticating proxy);
207
+ Firefox and WebKit are given the same.
208
+ - **Refused, saying why:** a vendor's browser (`web: {browse: browserbase}`
209
+ and every other — they browse from their own network, which no list here
210
+ holds), `proxy=` (a proxy of your own is not reachable), `live:` sessions,
211
+ and the Lightpanda and Obscura engines (no way through the proxy verified
212
+ yet). A vendor step is refused before it connects; to accept browsing that
213
+ no list holds for one agent, give that agent `network: open`.
214
+ - **Secrets bound to sites** stay out of the sandbox: a `headers=` value can
215
+ carry the `${NAME}`, which the proxy fills; `auth=`, `cookies=` and
216
+ `storage=` need the value in the browser and are refused for a bound
217
+ secret — unbind it to use it there.
218
+ - **Sites a secret is granted to** are where the proxy ends TLS to fill the
219
+ secret. Chromium is told to trust the egress CA for them; Firefox and
220
+ WebKit are not, and a page there fails its certificate check.
221
+ - **Web search** through the account's search pod is not reachable from a
222
+ walled pod either; the trace says so. Name a search provider in `web:`
223
+ (it goes through the proxy) or leave search out of that step.
224
+
225
+ Not covered: DNS lookups through the cluster's resolver (the wall admits
226
+ DNS, and nothing restricts the names asked), WebSocket upgrades to a host a
227
+ secret is granted to (they fail), and — as for every tunnel — which origins
228
+ a page loads inside a connection to an allowed site.
229
+
230
+ Everywhere else — `foldrun run` on your machine, the single-container tier,
231
+ an install without the switch, a report-only list, `network: open` — a
232
+ browsing step is **not** held: it gets no proxy, and the browser and every
233
+ other program in the step reach sites directly. The trace says that too:
234
+
235
+ ```
236
+ network: trusted (agent) — the trusted list (207 sites); added: example.com — not enforced in this step: it may browse, and browsing does not go through the egress proxy here, so the browser and every other program in this step reach sites directly. Its browser is foldrun's own browser: it is held to network: on an install that confines browsing, with the list enforced (FOL-110).
237
+ ```
238
+
239
+ The trace names which of three tiers the step's browser falls in:
194
240
 
195
241
  | tier | browsers | under `network:` |
196
242
  |---|---|---|
197
- | hosted | foldrun's own: the account's browser, Lightpanda, Obscura, a live session | yes, when hosted enforcement ships: its network will reach only the egress proxy |
198
- | vendor | Browserbase, Steel, Hyperbrowser, Browserless — they take a customer proxy | through the egress proxy, once each vendor passes our own tests |
199
- | none | Bright Data, ZenRows, any DevTools address — they browse through their own network | never; a restricted, enforced `network:` will refuse them |
200
-
201
- An agent that must stay inside its list should not browse until then: give
202
- it `web: {actions: [search, fetch]}`, which goes through the proxy like any
203
- other program.
243
+ | hosted | foldrun's own browser | held, where the platform confines browsing and the list is enforced |
244
+ | vendor | Browserbase, Steel, Hyperbrowser, Browserless — they take a customer proxy | not yet: each comes under the list through the egress proxy once it passes our own tests; until then a held list refuses it |
245
+ | none | Bright Data, ZenRows, any DevTools address — they browse through their own network | never; a held list refuses them |
246
+
247
+ The dashboard's Network card and `foldrun agent network <agent>` say which
248
+ applies to an agent. An agent that must stay inside its list where browsing
249
+ is not held should not browse: give it `web: {actions: [search, fetch]}`,
250
+ which goes through the proxy like any other program.
package/docs/runs.md CHANGED
@@ -424,7 +424,9 @@ The hardest question this platform gets is not about a run — it is about a
424
424
  run that does not exist. Every honest answer to it is a thing that
425
425
  deliberately did not happen: a duplicate delivery, a burst still being
426
426
  waited out, a throttled trigger, a flow switched off after a bad week, an
427
- `overlap: skip`, a fire missed while nothing was running.
427
+ `overlap: skip`, a fire missed while nothing was running, an account that
428
+ already had its most runs waiting (*too many runs waiting* —
429
+ [how many runs may wait](budgets-and-billing#how-many-runs-may-wait)).
428
430
 
429
431
  The Triggers page on each workspace records all of it: one row per flow
430
432
  saying how often its trigger fired, how often that became a run, and what
package/docs/security.md CHANGED
@@ -27,7 +27,9 @@ the web) reaches the internet only through the egress proxy, which holds
27
27
  its list of sites per connection; where it is enforced
28
28
  (`network_enforce: true` in the account's or workspace's `AGENTS.md`, or
29
29
  `FOLDRUN_NETWORK_ENFORCE=1` on the install) its pod has no other route, and no way to the
30
- account's browser or search pods. The policy denies every private range (RFC1918) and the
30
+ account's browser or search pods. A step that browses is held the same way where the
31
+ install sets `FOLDRUN_BROWSE_ENFORCE=1`: its browser runs inside that walled pod
32
+ ([Browsing](network#browsing)); elsewhere a browsing step is not held to its list. The policy denies every private range (RFC1918) and the
31
33
  cloud metadata endpoint — the address that, on a cloud host, hands out the
32
34
  machine's own credentials. It cannot reach the platform's API, its
33
35
  database, its object store, or another account's pods. Workspace files
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "foldrun",
3
- "version": "16.0.2",
3
+ "version": "16.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": "^14.4.0"
14
+ "@foldrun/core": "^14.5.0"
15
15
  },
16
16
  "files": [
17
17
  "bin",
package/src/commands.mjs CHANGED
@@ -2621,7 +2621,9 @@ async function remoteCall(url, flags, apiPath, init = {}, { seconds } = {}) {
2621
2621
  // run that failed with 500 and a full record of why — status, steps, the
2622
2622
  // agent's last words — and a caller that prints only "HTTP 500" sends the
2623
2623
  // reader hunting for an outage that never happened.
2624
- const hint = res.status === 401 || res.status === 403 ? refusedHint(url, flags) : res.status === 429 ? rateLimitHint(res, body) : "";
2624
+ // The account's waiting limit (FOL-100): the sentence says why; where
2625
+ // to see the figures is the CLI's to add.
2626
+ const hint = res.status === 401 || res.status === 403 ? refusedHint(url, flags) : res.status === 429 ? rateLimitHint(res, body) : body?.code === "waiting_cap" ? " — `foldrun usage compute` shows the runs waiting and the limit" : "";
2625
2627
  throw new HttpError(`${body.error ?? `${apiPath} → HTTP ${res.status}`}${hint}`, res.status, body);
2626
2628
  }
2627
2629
  return body;
@@ -6252,6 +6254,7 @@ const TRIGGER_REASON = {
6252
6254
  "overlap-skipped": ["previous run still live", "overlap: skip"],
6253
6255
  missed: ["missed while down", "catchup: none"],
6254
6256
  filtered: ["did not match the filter", "filter:"],
6257
+ "queue-full": ["too many runs waiting", "the account's waiting limit (foldrun usage compute)"],
6255
6258
  failed: ["could not start", ""],
6256
6259
  };
6257
6260
 
@@ -9865,6 +9868,24 @@ async function agentLinkCmd(positional, flags, layout) {
9865
9868
  return 0;
9866
9869
  }
9867
9870
 
9871
+ /**
9872
+ * The browsing line `agent network` prints for an agent that may browse with
9873
+ * a restricted list (FOL-110). Whether the list holds is decided per step:
9874
+ * on a platform that confines browsing (the k8s tier, FOLDRUN_BROWSE_ENFORCE)
9875
+ * and with the list enforced, the browser runs walled in the step's sandbox
9876
+ * and a vendor's browser is refused; on a laptop, or with a report-only list,
9877
+ * it is not held. This folder's half — network_enforce and the vendor — comes
9878
+ * from core's listAgents when it says (core ≥ the FOL-110 phase 3 release).
9879
+ * @param {{ level?: string, enforceWanted?: unknown, browseVendor?: unknown }} p
9880
+ */
9881
+ function browsingLine(p) {
9882
+ const vendor = typeof p.browseVendor === "string" && p.browseVendor ? p.browseVendor : null;
9883
+ const enforce = p.enforceWanted === true ? " (network_enforce: true here)" : "";
9884
+ return vendor
9885
+ ? `browsing: this agent browses with ${vendor}, which browses from its own network — on a platform that confines browsing, with this list enforced${enforce}, its steps are refused before they connect; elsewhere they are not held to the list (\`foldrun docs network\`, Browsing). Drop browse: ${vendor} to use foldrun's own browser, which is held to it.`
9886
+ : `browsing: this agent may browse. On a platform that confines browsing, with this list enforced${enforce}, its browser runs walled in the step's sandbox and the list holds for it; on this machine, or with the list only reported, its browser and its other programs reach sites directly (\`foldrun docs network\`, Browsing).`;
9887
+ }
9888
+
9868
9889
  /**
9869
9890
  * `foldrun agent network <agent> [open|trusted|none|inherit] [--add <site>]…
9870
9891
  * [--remove <site>]…` — which sites the agent's sandbox may reach, its
@@ -9897,7 +9918,8 @@ async function agentNetworkCmd(positional, flags, layout) {
9897
9918
  // from AGENTS.md); an older core gets the runner's own test on this
9898
9919
  // file: the web tool, with browse among its actions (trimmed and
9899
9920
  // lowercased as webConfig reads them) or no actions: list at all.
9900
- // Such a step is not held to its list yet (FOL-110).
9921
+ // Whether such a step is held to its list is the platform's to say as
9922
+ // well (FOL-110 phase 3) — browsingLine says what this folder decides.
9901
9923
  const actions = front.web && typeof front.web === "object" && Array.isArray(front.web.actions) ? front.web.actions.map((a) => String(a).trim().toLowerCase()) : null;
9902
9924
  const fromCore = /** @type {{ browses?: unknown }} */ (info?.network ?? {}).browses; // core ≥ the FOL-110 release
9903
9925
  const browses = typeof fromCore === "boolean"
@@ -9910,7 +9932,7 @@ async function agentNetworkCmd(positional, flags, layout) {
9910
9932
  if (!p) return;
9911
9933
  console.log(` ${net.networkLine(p, true)}`);
9912
9934
  if (p.level !== "open") console.log(` ${c.dim("a run also allows its MCP servers, its web providers and the sites its secrets are bound to")}`);
9913
- if (browses) console.log(` ${c.yellow("browsing: this agent may browse, and a browsing step is not held to this list yet — its browser and its other programs reach sites directly (`foldrun docs network`, Browsing). Give it web: {actions: [search, fetch]} to keep it inside the list.")}`);
9935
+ if (browses && p.level !== "open") console.log(` ${c.yellow(browsingLine(p))}`);
9914
9936
  };
9915
9937
  const raw = desk.files.get(rel);
9916
9938
  const now = await resolve(desk.files);
@@ -11387,7 +11409,14 @@ async function usageComputeCmd(flags) {
11387
11409
  const from = { plan: "the plan's", account: "the account's own compute:", install: "this install's" }[p.source] ?? null;
11388
11410
  console.log(`\n ${c.bold("account")} ${c.dim(from ? `${from} — what all running steps may hold together` : "no pool set")}`);
11389
11411
  console.log(` ${held(u, p)} ${c.dim(`held by ${u.steps} running step${u.steps === 1 ? "" : "s"}`)}`);
11390
- if (p.stepVcpu != null || p.stepMemGiB != null || p.stepDiskGiB != null) console.log(` ${c.dim(`one step: up to ${p.stepVcpu ?? "any"} vCPU · ${p.stepMemGiB ?? "any"} GiB · ${p.stepDiskGiB ?? "any"} GiB disk`)}`);
11412
+ if (p.stepVcpu != null || p.stepMemGiB != null || p.stepDiskGiB != null) console.log(` ${c.dim(`one step: up to ${p.stepVcpu ?? "any"} vCPU · ${p.stepMemGiB ?? "any"} GiB · ${p.stepDiskGiB ?? "any"} GiB disk${Array.isArray(p.stepDefault) && p.stepDefault.length ? " — the most for an account without a plan of its own" : ""}`)}`);
11413
+ // Runs waiting for their turn (FOL-100): while the limit wait, a new run
11414
+ // is refused at once (409, code waiting_cap) instead of lined up.
11415
+ const rw = d.runsWaiting;
11416
+ if (rw && rw.limit != null) {
11417
+ const count = rw.waiting == null ? `up to ${rw.limit}` : `${rw.waiting} of ${rw.limit}`;
11418
+ console.log(` ${c.dim(`runs waiting for their turn: ${count} — past the limit a new run is refused, not lined up${rw.source === "install" ? " (FOLDRUN_MAX_WAITING_RUNS)" : rw.slots ? ` (20 × ${rw.slots} at once, at least 50)` : ""}`)}`);
11419
+ }
11391
11420
  // Each workspace's own pool and each live run's (27 Oct 2026): a step
11392
11421
  // must fit every level it belongs to.
11393
11422
  const wss = Array.isArray(d.workspaces) ? d.workspaces.filter((w) => w.inUse?.steps || w.pool?.vcpu != null || w.pool?.memGiB != null || w.pool?.diskGiB != null) : [];