foldrun 23.0.2 → 24.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/bin/foldrun.mjs CHANGED
@@ -31,7 +31,7 @@
31
31
  // foldrun restore <ws> a workspace's source back to a point in its history (shows the change, asks)
32
32
  // foldrun onboarding the account's getting-started steps, the next one first
33
33
  // foldrun billing the balance, and what the money went on
34
- // foldrun gallery the tools the platform ships to every account — list, pull, upgrade <tool>
34
+ // foldrun gallery the tools and skills the platform ships to every account — list, pull, upgrade <name>
35
35
  // foldrun storage <verb> ls / cat / text / get / put / rm / share / shares / unshare — what the agents produced, and public links to it
36
36
  // foldrun text <file> a PDF, scan, document, sheet or recording on this machine, as text — read by the platform
37
37
  // foldrun runtimes the environments a workspace's agents need, and whether each is built
@@ -227,7 +227,7 @@ const HELP = `foldrun — agents are just folders
227
227
  foldrun billing plans the plans, which one the account is on and this cycle's credits — also plan <id>, plan cancel, plan resume (asks first)
228
228
  foldrun billing top-up <usd> Stripe's checkout page for adding credit (owner only; --no-browser prints it)
229
229
  foldrun billing card Stripe's page for saving a card for auto top-up (owner only)
230
- foldrun gallery the platform's built-in tools (web) and whether you keep your own copy — also pull (a copy for offline runs), upgrade <tool>
230
+ foldrun gallery the platform's built-in tools (web, docs, video) and skills (modern-website, motion-video, cloudhost-deploy), and whether you keep your own copy — also pull (a copy for offline runs), upgrade <name>, --json
231
231
  foldrun identity what your cloud must trust for keyless identities: the issuer and each agent's subject (--to <workspace>, --json)
232
232
  foldrun jobs the four jobs — governance, guardrail, observability, evaluation — and what each has set (--to <workspace>, --json)
233
233
  foldrun account the account's defaults — also set <key> <value>, clear <key> (timezone, notify, budget, concurrency, compute vcpu <n> memory <GiB> disk <GiB>, deploy_block none|secrets|security, network_enforce on|off, owner, alerts <threshold> <value>, judge model|effort <value>; or <job>.<field>, e.g. governance.owner), pause [--reason] [--stop] / resume (the kill switch), telemetry [set <url> --header name=\${SECRET} (others kept; name= drops one) | clear | test] (runs as OpenTelemetry traces), providers (--check) (singular; accounts lists logins)
package/docs/agents.md CHANGED
@@ -89,7 +89,7 @@ the point of the week; a step that weighs two arguments and picks one is not.
89
89
  |---|---|
90
90
  | `tools` | the one grant list — built-in groups, exact SDK names, and your own tools |
91
91
  | `disallowedTools` | subtract from what it would otherwise have |
92
- | `skills` | an allowlist. **Absent inherits every skill in scope**; `[]` withholds all of them |
92
+ | `skills` | an allowlist. **Absent inherits every skill in scope**; `[]` withholds all of them. The platform's [gallery skills](tools#the-gallery--platform-maintained-tools-and-skills) (`modern-website`, `motion-video`, `cloudhost-deploy`) come only by name |
93
93
  | `agents` | colleagues it may consult mid-run — an answer, no tools |
94
94
  | `subagents` | colleagues it may delegate a whole job to — own context, own tools, never more than its own ([below](#delegating-to-a-sub-agent)) |
95
95
  | `sandbox` | `own` \| `parent` (default) — delegated to as a sub-agent, run each job in a sandbox of its own, with its own tools, secrets and network ([below](#isolated-sub-agents-sandbox-own)) |
package/docs/api.md CHANGED
@@ -225,7 +225,7 @@ paying for the steps around it.
225
225
  | Route | Methods | |
226
226
  |---|---|---|
227
227
  | `/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`, `customer` (one end customer's runs, exactly), `context` (one [conversation](runs#conversations)'s runs, its id exactly; each run in it carries `context: { id, key, a2a? }`) — `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 |
228
- | `/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
+ | `/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. 502 when it was recorded but cannot be read now (the object store or the database is unavailable) — never an empty answer. 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) |
229
229
  | `/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 |
230
230
  | `/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) |
231
231
  | `/api/workspaces/<ws>/runs/<id>` | GET, DELETE | the whole run: every step, its output, cost, timing, its money — `chargedUsd` (what the account was charged, the ledger's line; `null` until the run settles: the worker settles it as it ends, and an hourly pass retries one that failed to), `estimatedUsd` (its list price, the figure until then) and `settled` — `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`) |
@@ -430,7 +430,7 @@ Reads return which secrets exist, never their values.
430
430
  | `/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 |
431
431
  | `/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: []` |
432
432
  | `/api/library/<kind>?path=` | GET, POST, PUT, DELETE | account-level shared documents (`name`, `content`, `path`, `template`); DELETE `{ path }` removes one file or folder — `.` (the whole shelf) is refused |
433
- | `/api/library/gallery` | GET, POST | GET: every tool the platform ships to every account, whole (`tools: [{ name, kind, title, description, files: [{ kind, file, content }], installed }]`, `installed` being `current`, `differs` or null for this account's own copy) — what `foldrun gallery` reads and lays down on a laptop. POST: update an installed gallery tool to the version the platform ships (`tool`) — written through the revision log, so the previous copy is one revision back |
433
+ | `/api/library/gallery` | GET, POST | GET: every tool and skill the platform ships to every account, whole (`tools: [{ name, kind, title, description, files: [{ kind, file, content }], installed }]`, `kind` being `tools`, `skills` or `scripts`, `installed` being `current`, `differs` or null for this account's own copy) — what `foldrun gallery` reads and lays down on a laptop. POST: update an installed gallery tool or skill to the version the platform ships (`tool`, its name) — written through the revision log, so the previous copy is one revision back |
434
434
 
435
435
  ## Roles
436
436
 
package/docs/cli.md CHANGED
@@ -189,7 +189,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
189
189
  | `foldrun billing details set --clear-address` | drops the address from who invoices are made out to, the rest kept; `--clear-email` and `--clear-abn` the same for the email and the ABN (each refused beside its own `--address`/`--email`/`--abn`) |
190
190
  | `foldrun billing plans` | the Plans page: every plan with its monthly fee, credits, runs at once and workspaces, which one the account is on and this cycle's credits left (`GET /api/billing/plans`). `billing plan <id>` chooses one — a first plan answers with Stripe's checkout page, a change on a live plan is prorated at Stripe at once (asks first; `--yes`); `plan cancel` stops it at the end of the cycle, `plan resume` undoes that until then (`POST`/`DELETE /api/billing/subscribe`) |
191
191
  | `foldrun billing top-up <usd>` | the Payment page's top-up: Stripe's checkout page for that amount, opened in the browser (`--no-browser`, or no terminal, prints it). The credit lands when Stripe confirms the payment. `billing card` is the same for saving a card for auto top-up. Both need `billing:manage` |
192
- | `foldrun gallery` | the tools the platform ships to every account (`web`), and for each whether this account keeps its own copy and whether that copy still matches. `pull` lays the shelf down under `~/.foldrun/gallery/<host>/` for offline runs (`foldrun run` and `foldrun eval` refresh it themselves before each run); `upgrade <tool>` replaces the account's copy with the current gallery version, the old one a revision back |
192
+ | `foldrun gallery` | the tools (`web`, `docs`, `video`) and skills (`modern-website`, `motion-video`, `cloudhost-deploy`) the platform ships to every account, by shelf, and for each whether this account keeps its own copy and whether that copy still matches; `--json` for a script. `pull` lays the shelf down under `~/.foldrun/gallery/<host>/` for offline runs (`foldrun run` and `foldrun eval` refresh it themselves before each run); `upgrade <name>` replaces the account's copy of a tool or skill with the current gallery version, the old one a revision back. `foldrun check` knows the gallery's names, so a signed-out check warns rather than calling them missing |
193
193
  | `foldrun identity` | keyless cloud identity: the issuer your cloud must trust and the subject each agent's tokens carry (`GET /api/identity`); `--to <workspace>` fills the workspace in, `--json` |
194
194
  | `foldrun jobs` | the four jobs — governance, guardrail, observability, evaluation — and every `AGENTS.md` field of each, with what is set (`GET /api/account/jobs`). `--to <workspace>` shows the workspace's value beside the account's and how the two combine; `--json` the document. `account set <job>.<field>` and `workspace set <job>.<field>` refuse a field that scope cannot set and name the `AGENTS.md` to write it in. See [The four jobs](four-jobs) |
195
195
  | `foldrun account` | the account's own defaults — the AGENTS.md frontmatter every workspace under it inherits: `timezone`, `notify`, `budget`, `concurrency`, `deploy_block`, `network_enforce`. `foldrun account set timezone Australia/Sydney`, `set notify email you@example.com` (`--events failed,awaiting-approval,completed`), `set notify url https://…`, `set budget 60/month`, `set concurrency 4`, `set compute vcpu 4 memory 8 disk 40` (GiB; any of them, merged over what is set — the account's own pool, lower than the plan's), `set deploy_block secrets` (`none`, `secrets` or `security` — what the scanner's findings do to a deploy), `set network_enforce on` (every workspace refuses a site off an agent's `network:` list; `off` reports only), `set owner <email or name>`, `set alerts <threshold> <value>` (merged into what is set; `off` removes one), `set judge model|effort <value>`. Any setting may be named by its job — `set governance.deploy_block secrets`, `set observability.alerts stale_days 30` — and one named under the wrong job is refused with the right one, `pause` (`--reason "…"`, `--stop` to also stop every run going now — asks, or `--yes`) and `resume`: the kill switch, no new run starts in any workspace while paused, `telemetry` — where each finished run goes as an OpenTelemetry trace: bare shows it, `set <url> --header authorization='${OTEL_TOKEN}'` (repeatable; a value is a vault secret's name; the headers already set are kept, as the dashboard's card keeps them, and `--header name=` drops one), `clear`, `test` (one made-up run, and what the collector answered; exit 1 when not delivered), and `clear <key>` to unset one. `set notify` merges against what is there, because the platform replaces the whole block. `providers` lists the model providers the account's files use and the last daily key check — `--check` asks now, and a dead key is a non-zero exit. `model` is what every step runs on unless a `provider:` block names another — the account's own model key, or foldrun's models: `foldrun account model` shows it (never a key, only its last four; on foldrun's models, the provider, its tier map and today's spend against the daily cap; exit 1 when runs are refused — no key, or foldrun's models refused for the account), `model set <provider> --key <api key>` sets the key — a preset name (anthropic, openrouter, openai, groq, …) or `custom --base-url https://… --format anthropic|openai`, `--key -` reads the key from stdin, and in a terminal it (or no `--key`) asks for it hidden — a pasted key works, `--use` also runs on it from now on in the same request (as `model use own`, which the dashboard's Save does) — and `model remove` removes it (the choice stays); a Claude login token is refused for any account not allowed the platform's own credential. `model use foldrun --provider <anthropic|openai|gemini|deepseek|moonshot>` runs every step on foldrun's models — the platform's keys, billed in credits at foldrun's price list, hosted only; a provider the platform cannot serve now is refused — and `model use own` goes back to the account's own key, which is kept. `model prices` (`--provider <p>`, `--json`) lists foldrun's price list as the account pays it, USD per million tokens. `export` downloads everything the platform holds about the account — workspaces, runs, members and the whole ledger — as one JSON file (owner only; `--file <path>`, `--force`). Singular — `accounts` below is the list of logins on this machine |
package/docs/network.md CHANGED
@@ -25,7 +25,9 @@ network: [api.hubapi.com] # the trusted list, plus this
25
25
  **What the step declares** is always allowed, at every level: the hosts of
26
26
  its `apis:`, its remote MCP servers, its web providers (`web: {search: brave}`),
27
27
  the card of each outside agent in its `remotes:` (that card's own site — never
28
- one the card names), and the sites its [secrets are bound to](secrets#bound-to-sites).
28
+ one the card names), the sites a granted script tool's own definition names
29
+ (`network:` in its [tool.md](tools#script--code-as-a-tool) — the gallery's
30
+ `docs` names `context7.com`), and the sites its [secrets are bound to](secrets#bound-to-sites).
29
31
  You never list those twice.
30
32
 
31
33
  No level is ever a way into private space: the cluster, the LAN and the
@@ -262,6 +262,79 @@ The timings are `FOLDRUN_RECORDS_ROUTING_BEAT_MS` (1000),
262
262
  (120000, raise it for very large workspaces); keep them the same on every
263
263
  process.
264
264
 
265
+ ## Moving secrets into the database
266
+
267
+ Each account's secrets, and each workspace's own, are a sealed `secrets.json`
268
+ on the data volume. With a database configured they can be rows in Postgres
269
+ instead, one row per account or workspace (`vault_scopes`), holding the same
270
+ sealed records: nothing in the database ever holds a value in the clear, and
271
+ nothing below opens one except `verify --open`, in memory.
272
+
273
+ Two settings (Settings, owners only; the same names as the variables in
274
+ [Environment](environment)):
275
+
276
+ | Setting | Meaning |
277
+ |---|---|
278
+ | `secrets.store` | The rows are the vault. A scope moves from its file the first time it is used. |
279
+ | `secrets.mirror` | On (the default): every change is also written to the scope's file, so switching the store off or rolling back reads current secrets. Off: only the rows are written; the files go stale and are retired. |
280
+
281
+ `vault-fleet.ts` runs in the worker pod, which has the database, the data
282
+ volume and the keys (`scripts/vault-fleet.ts` from `/app/foldrun-platform`):
283
+
284
+ ```
285
+ node --experimental-strip-types scripts/vault-fleet.ts verify [--open] [--mirror-off] [--tenant a,b]
286
+ node --experimental-strip-types scripts/vault-fleet.ts import [--tenant a,b]
287
+ node --experimental-strip-types scripts/vault-fleet.ts export [--tenant a,b]
288
+ ```
289
+
290
+ - `verify` is read-only. It prints counts and `account/workspace` names, never a
291
+ value: scopes that are only a file (never used since the switch, so never
292
+ moved), only a row, or differ from their file. `--open` also tries every
293
+ record with this process's keys and names those that do not open. Exit 0 when
294
+ clean, 1 when not. `--mirror-off` is for after the mirror stopped: files are
295
+ expected to be stale there, so a differing scope or one with no file is fine;
296
+ a scope with no row, or a record that does not open, still is not.
297
+ - `import` copies each file-only scope into its row, as stored, under the
298
+ file's lock. A row that exists is never replaced by a file. It is safe to
299
+ repeat and to run while `secrets.store` is on.
300
+ - `export` is the way back: it writes every row into its file as stored. A
301
+ workspace row whose folder is gone is skipped and named; the folder is never
302
+ brought back.
303
+
304
+ **Moving, and then stopping the files:**
305
+
306
+ 1. Deploy this release on every process (web, worker, assistant, egress) and
307
+ wait until no process of an older release is left.
308
+ 2. Turn `secrets.store` on (it asks for a reason). Scopes move as they are used.
309
+ 3. `vault-fleet.ts import`, then `verify --open`. Clean means every scope is a
310
+ row that equals its file and every record opens. Fix what it names first: a
311
+ record that does not open here will not open from the row either.
312
+ 4. Soak with the mirror on for as long as you like; `verify` again before the
313
+ next step.
314
+ 5. Turn `secrets.mirror` off (it asks for a reason). From now on the files are
315
+ not written. Watch `vault-fleet.ts verify --open --mirror-off`.
316
+
317
+ **The way back from the mirror being off.** The files are stale, so they must
318
+ not be read until they are brought up to date:
319
+
320
+ 1. Turn `secrets.mirror` on: from then on every change also reaches its file.
321
+ 2. `vault-fleet.ts export`, then `verify`: export writes each row as it is
322
+ when the file's lock is held, so a change made during the export is not
323
+ lost; `verify` is clean when every file equals its row.
324
+ 3. Only then, if you want the files back as the vault, turn `secrets.store`
325
+ off.
326
+
327
+ The platform holds you to this order. `secrets.store` cannot be turned off
328
+ while `secrets.mirror` is off (the change is refused, naming the export), and a
329
+ process whose setting says the store is off while the mirror is off still reads
330
+ the rows as long as any row exists, and logs `vault.store_held_by_rows`. With the
331
+ mirror on before the export, a change made while it runs reaches the file
332
+ either way: through the mirror, or through the export reading the row again.
333
+
334
+ Turning `secrets.store` off with the mirror on needs no copying: the files are
335
+ current. A scope with a file and no row is read from the file again; one with a
336
+ row is only ever read from the row while the store is on.
337
+
265
338
  ## Where the data is
266
339
 
267
340
  On your machine: in the folder. On the platform: your workspace's files and
package/docs/tools.md CHANGED
@@ -103,6 +103,7 @@ runtime:
103
103
  | `outward` | `true` when the program makes something happen outside — sends, posts, orders. On a [test run](runs#test-runs) a step granting it is handed no real secret at all, whatever their names |
104
104
  | `test_mode` | `allow` for a reader that happens to use a send-capable secret (a Business Profile reader on the same token the poster uses): on a test run the step still gets the real values. An `outward` tool in the same step wins. Parsed as `testMode` |
105
105
  | `runtime` | interpreters and packages, merged into the step's environment |
106
+ | `network` | the sites its program reaches, `[api.example.com, *.cdn.example.com]` — sites only, no scheme or path. Granting the tool adds them to the step's [network](network) list, the way an `apis:` base or a bound secret's site is added, so an agent on `trusted` or `none` reaches them without naming them — granting the tool is the declaration. The level (`open`, `trusted`, `none`) stays the agent's to set. `foldrun check` reports a value that is not a site, or a level written where a site goes |
106
107
 
107
108
  A folder tool may declare its dependencies the way its ecosystem does
108
109
  instead: a `requirements.txt` beside the program counts as
@@ -172,25 +173,27 @@ still shadow it by defining the same name locally.
172
173
  The Library page lists, for every shared file, which agents granted it and
173
174
  where a nearer copy overrides it. That list is the blast radius of changing it.
174
175
 
175
- ## The gallery — platform-maintained tools
176
+ ## The gallery — platform-maintained tools and skills
176
177
 
177
- Every tool the platform ships — `web` — is **available in every account
178
- from the start**.
179
- An agent grants one the same way it grants anything: `tools: [web]`
180
- in its `agent.md`, and it runs, with nothing installed first. The gallery
181
- is a shelf beneath your account library, laid down on the box at boot, so
182
- a platform upgrade reaches every account at once.
178
+ Every tool and skill the platform ships is **available in every account
179
+ from the start**. An agent grants a tool the way it grants anything —
180
+ `tools: [web]` in its `agent.md` — and a skill by naming it,
181
+ `skills: [modern-website]`; it runs, with nothing installed first. The
182
+ gallery is a shelf beneath your account library, laid down on the box at
183
+ boot, so a platform upgrade reaches every account at once.
183
184
 
184
185
  **Installing** is still there, and it means something narrower now: it
185
- copies the tool into your account library (or one workspace), and your
186
- copy shadows the platform's by name. A copy you have **not edited** follows
187
- the gallery: every platform deploy brings it to the current version. A copy
188
- you **have** edited is yours and is never changed under you. The Library
189
- page marks each copy **gallery · current** or **gallery · differs**, with a
190
- one-click *update to gallery version* for an edited copy — it writes the
191
- current files through the revision log, so your version is one revision
192
- back. Nothing from the gallery is granted
193
- to any agent until its `agent.md` names it.
186
+ copies the tool or skill into your account library (or one workspace), and
187
+ your copy shadows the platform's by name. A copy you have **not edited**
188
+ follows the gallery: every platform deploy brings it to the current
189
+ version. A copy you **have** edited is yours and is never changed under
190
+ you. The Library page marks each copy **gallery · current** or
191
+ **gallery · differs**, with a one-click *update to gallery version* for an
192
+ edited copy — it writes the current files through the revision log, so
193
+ your version is one revision back. **New** on the Library page offers each
194
+ gallery entry as a template to start your own from. Nothing from the
195
+ gallery reaches an agent until its `agent.md` names it — a gallery skill is
196
+ not one of the skills an agent with no `skills:` list inherits.
194
197
 
195
198
  **On a laptop** the shelf comes from the platform you are signed in to.
196
199
  `foldrun run` and `foldrun eval` fetch the gallery before they start and keep
@@ -198,8 +201,8 @@ a copy under `~/.foldrun/gallery/<host>/`, so an agent granting `web`
198
201
  runs locally exactly as it does on a deploy, with the same lookup order: the
199
202
  workspace's copy, then the account library's, then the shelf. Offline, the
200
203
  last copy is used and the run says so. `foldrun gallery` lists the shelf and
201
- marks which tools your account keeps its own copy of, `foldrun gallery pull`
202
- refreshes the copy by hand, and `foldrun gallery upgrade <tool>` is the
204
+ marks which entries your account keeps its own copy of, `foldrun gallery pull`
205
+ refreshes the copy by hand, and `foldrun gallery upgrade <name>` is the
203
206
  Library page's *update to gallery version*. A browser tool also needs
204
207
  Playwright on the laptop (`npm i -g playwright@1.63.0`, then `npx playwright
205
208
  install chromium`); `web action=browse` finds it globally, Homebrew's included, or
@@ -207,20 +210,83 @@ in the project, and says how to install it when it is missing.
207
210
 
208
211
  | tool | what it does | the key it needs |
209
212
  |---|---|---|
210
- | `web action=search` | searches the web on the account's own engine — titles, links, snippets | none |
211
- | `web action=fetch` | reads one URL, or up to twenty: the page itself, as markdown, text, html, meta or links | none |
212
- | `web action=browse` | a real browser: JavaScript runs, and it can click, fill, scroll, screenshot, download and extract | none |
213
-
214
- The gallery is deliberately just these three — the web capability that is
215
- hard to build from a plain HTTP call. **Everything else you integrate
216
- yourself**, as your own tool in the library: Slack, GitHub, Stripe, email, a
217
- CRM, your own service. An `apis:` block turns an OpenAPI or a base URL into a
218
- tool; a folder tool runs a script. Credentials come from your vault, declared
219
- under the agent's `secrets:`, and the value never appears in a file. The
220
- platform ships no third-party integrations, so it never carries their keys or
221
- versions — you own the tool, its scope and its blast radius. See
213
+ | `web` | the web, as eight actions: search, fetch, browse, crawl, map, extract, answer, monitor — [Reaching the web](#reaching-the-web) | none |
214
+ | `docs` | a library's current documentation and code examples, pinned to a version, from Context7's index — [Library docs](#library-docs--docs) | none; your own `CONTEXT7_API_KEY` for a higher limit |
215
+ | `video` | motion graphics and video written as React code with Remotion: start a project, render a frame, render the video — [Video](#video--video) | none (Remotion's own licence applies) |
216
+
217
+ | skill | what it is for |
218
+ |---|---|
219
+ | `modern-website` | building a modern, high-end website or app: Astro for content sites and Next.js for apps when nothing is named, the current stack, design, bundled assets, the launch checks |
220
+ | `motion-video` | motion graphics and short videos with the `video` tool: scenes, easing, stills before renders, video on a website |
221
+ | `cloudhost-deploy` | deploying to [cloudhost](https://cloudhost.ir) through its MCP tools: `cloudhost.toml`, bindings, previews first, production on approval |
222
+
223
+ The gallery is deliberately small: capabilities that are hard to build from
224
+ a plain HTTP call and that agents building things keep reaching for.
225
+ **Everything else you integrate yourself**, as your own tool in the
226
+ library: Slack, GitHub, Stripe, email, a CRM, your own service. An `apis:`
227
+ block turns an OpenAPI or a base URL into a tool; a folder tool runs a
228
+ script. Credentials come from your vault, declared under the agent's
229
+ `secrets:`, and the value never appears in a file. A gallery tool that
230
+ calls a third party carries no platform key: it works without one where the
231
+ third party allows, and uses your own from the vault when you add one. See
222
232
  [HTTP — an API as a tool](#http--an-api-as-a-tool) and [Script — code as a tool](#script--code-as-a-tool).
223
233
 
234
+ ### Library docs — `docs`
235
+
236
+ ```yaml
237
+ tools: [docs]
238
+ ```
239
+
240
+ ```
241
+ docs action=search library=next.js query="metadata and Open Graph images"
242
+ docs action=get library=/vercel/next.js version=16 query="generateMetadata and opengraph-image"
243
+ ```
244
+
245
+ `search` turns a name into Context7 library ids, with the versions indexed
246
+ and how well each is maintained; `get` returns the passages and code
247
+ examples that answer `query`, from an id or a name (the best match is used,
248
+ and the answer says which). `version=` pins one — the closest indexed
249
+ version answers when the exact one is not. `max_output=` (2,000–60,000
250
+ characters, default 15,000) and `save=` keep a long answer.
251
+
252
+ Without a key Context7 serves a low rate shared by every keyless caller.
253
+ For your own limit: `foldrun secrets set CONTEXT7_API_KEY`, then
254
+ `foldrun secrets sites CONTEXT7_API_KEY context7.com` (the value never
255
+ enters a sandbox), and `secrets: [CONTEXT7_API_KEY]` on the agent. The tool
256
+ reaches `context7.com` only (`network: [context7.com]` in its definition).
257
+
258
+ ### Video — `video`
259
+
260
+ ```yaml
261
+ tools: [video]
262
+ size: large
263
+ ```
264
+
265
+ ```
266
+ video action=new project=workspace/storage/video/launch
267
+ video action=compositions project=workspace/storage/video/launch
268
+ video action=still project=workspace/storage/video/launch frame=45
269
+ video action=render project=workspace/storage/video/launch props={"title":"Launch day"} codec=vp9
270
+ ```
271
+
272
+ A project is a small Remotion app the agent writes: `new` starts one from
273
+ foldrun's template (one composition, 1920x1080 at 30 fps, Persian and
274
+ English text in Vazirmatn); `compositions` lists what it defines; `still`
275
+ renders one frame as a PNG — look at it before rendering the whole video;
276
+ `render` writes MP4 (`h264`, default, or `h265`), WebM (`vp8`, `vp9`), GIF
277
+ or ProRes, with `props=` as the composition's input, `frames=` for a range,
278
+ `scale=` and `concurrency=`. Output goes to `out/` in the project unless
279
+ `out=` names a file. The first call in a project installs its packages and
280
+ Remotion's browser; the tool's definition declares the Debian libraries the
281
+ browser needs and the sites it downloads from. Rendering is CPU-bound:
282
+ give the agent `size: large`.
283
+
284
+ **Remotion's licence.** Remotion is source-available, not open source: free
285
+ for individuals and companies of up to three people; a company of four or
286
+ more needs a [Remotion Company License](https://www.remotion.pro/license).
287
+ The account whose agents render is the licensee. foldrun runs the code, it
288
+ does not license Remotion to you.
289
+
224
290
  ## Reaching the web
225
291
 
226
292
  One tool, `web`, and eight **actions** — `action=` picks one, and the other
@@ -1463,8 +1529,18 @@ is on the secret itself. `check` refuses `state` beside `cookies` without
1463
1529
 
1464
1530
  ### Where the browser runs
1465
1531
 
1532
+ On a cluster, a browsing step's browser is chosen in this order
1533
+ (`run-k8s.ts`, the worker's step services):
1534
+
1535
+ | The step | Its browser |
1536
+ |---|---|
1537
+ | held to its `network:` list | Chromium inside its own run pod, walled to the egress proxy |
1538
+ | not held, with `FOLDRUN_BROWSE_SERVICE=1` | a [browse-service pod](network#the-browse-service) of its own, deleted with the step |
1539
+ | names a vendor (`web: {browse: browserbase}`) | the vendor's browser; no pod of ours |
1540
+ | anything else | the account's browser pods, below |
1541
+
1466
1542
  Locally — the CLI, a compose install — Chromium launches inside the step,
1467
- and always did. On a cluster it runs in **the account's own browser pods**:
1543
+ and always did. Otherwise, on a cluster, it runs in **the account's own browser pods**:
1468
1544
  Playwright servers on the runner image (Playwright pinned to an exact
1469
1545
  version, 1.63.0, in `run-container.ts` — the numbered snapshot needs 1.59
1470
1546
  or later, and a floating `@1` would move the pods and the tool under a
@@ -1847,7 +1923,10 @@ is the reason to move a procedure out of `agent.md` in the first place.
1847
1923
  Skills are discovered in the agent's own `skills/`, the workspace's, the
1848
1924
  account library, and the cross-client `.agents/skills/` convention that other
1849
1925
  tools read and write. A skill written here drops into them, and one they
1850
- install is visible here.
1926
+ install is visible here. The platform's [gallery](#the-gallery--platform-maintained-tools-and-skills)
1927
+ adds a few more — `modern-website`, `motion-video`, `cloudhost-deploy` —
1928
+ that load only for an agent whose `skills:` names them; your own skill of
1929
+ the same name wins.
1851
1930
 
1852
1931
  **A tool is what an agent may call; a skill is how to do something well.** The
1853
1932
  test for moving text out of an agent body: is it procedure (not role), does it
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "foldrun",
3
- "version": "23.0.2",
3
+ "version": "24.0.0",
4
4
  "description": "Agents are just folders. Write them, check them, run them — on your machine.",
5
5
  "license": "FSL-1.1-ALv2",
6
6
  "type": "module",
@@ -11,7 +11,7 @@
11
11
  "node": ">=22"
12
12
  },
13
13
  "dependencies": {
14
- "@foldrun/core": "^21.2.0"
14
+ "@foldrun/core": "^22.0.0"
15
15
  },
16
16
  "files": [
17
17
  "bin",
package/src/commands.mjs CHANGED
@@ -1306,11 +1306,11 @@ async function checkProblems(workspace, flags = {}) {
1306
1306
  note("info", `agents/${a.name}`, `tools: [${t}] — from the library on ${platform.url}`);
1307
1307
  continue;
1308
1308
  }
1309
- if (t === WEB_TOOL) {
1309
+ if (GALLERY_TOOLS.has(t)) {
1310
1310
  // Built in: the platform's gallery grants it in every account
1311
1311
  // without an install, and a local run fetches the gallery when
1312
1312
  // signed in. Signed out there is nothing on disk to run.
1313
- if (!platform.url) note("warn", `agents/${a.name}`, `tools: [${t}] — the platform's web tool; sign in (\`foldrun login\`) to run it locally`);
1313
+ if (!platform.url) note("warn", `agents/${a.name}`, `tools: [${t}] — the platform's ${t} tool; sign in (\`foldrun login\`) to run it locally`);
1314
1314
  continue;
1315
1315
  }
1316
1316
  const hint = platform.url
@@ -1369,6 +1369,12 @@ async function checkProblems(workspace, flags = {}) {
1369
1369
  note("warn", `agents/${a.name}`, "skills: [] withholds every skill — omit the field to inherit them");
1370
1370
  }
1371
1371
  for (const s of a.skills) {
1372
+ if (!skillNames.has(s) && GALLERY_SKILLS.has(s)) {
1373
+ // The platform's gallery ships it to every account; a local run
1374
+ // loads it from the gallery copy `foldrun run` fetches.
1375
+ if (!platform.url) note("warn", `agents/${a.name}`, `skills: [${s}] — the platform's ${s} skill; sign in (\`foldrun login\`) to load it locally`);
1376
+ continue;
1377
+ }
1372
1378
  if (!skillNames.has(s)) {
1373
1379
  note("error", `agents/${a.name}`, `skills: [${s}] — no skill of that name in this agent, the workspace or the library`);
1374
1380
  }
@@ -1575,6 +1581,13 @@ async function checkHooks(workspace, agents, libraryRoot, platform, note) {
1575
1581
  * built-in that takes a provider. */
1576
1582
  const WEB_TOOL = "web";
1577
1583
 
1584
+ /** What the platform's gallery ships to every account (foldrun-platform
1585
+ * src/gallery.ts): granted by name with nothing installed — tools with
1586
+ * `tools:`, skills with `skills:`. Listed here so `check` on a laptop that
1587
+ * is signed out does not call them missing. */
1588
+ const GALLERY_TOOLS = new Set([WEB_TOOL, "docs", "video"]);
1589
+ const GALLERY_SKILLS = new Set(["modern-website", "motion-video", "cloudhost-deploy"]);
1590
+
1578
1591
  /** Transports a pre-v0.1 tool could put in `type:`. */
1579
1592
  const TRANSPORTS = new Set(["http", "script", "mcp"]);
1580
1593
 
@@ -1706,9 +1719,9 @@ async function runTarget(target, flags) {
1706
1719
  // ---------------------------------------------------------------- gallery
1707
1720
 
1708
1721
  /**
1709
- * The platform's gallery — `web`, the tool it ships to every account — is
1710
- * a shelf every run on the platform reads beneath the account's own
1711
- * library. A laptop had no shelf, so an agent granting a gallery tool ran
1722
+ * The platform's gallery — the tools (`web`, `docs`, `video`) and skills it
1723
+ * ships to every account — is a shelf every run on the platform reads
1724
+ * beneath the account's own library. A laptop had no shelf, so an agent granting a gallery tool ran
1712
1725
  * fine on a deploy and had no program under `foldrun run`.
1713
1726
  * The CLI keeps a copy per platform here and points the local runner at it:
1714
1727
  * the same lookup order, the workspace first, then the account, then this.
@@ -1758,7 +1771,7 @@ async function galleryCmd(positional, flags) {
1758
1771
  const url = platformFor(flags, "gallery");
1759
1772
  const [verb, name] = positional;
1760
1773
  if (verb === "upgrade") {
1761
- if (!name) throw new Error("which tool? `foldrun gallery upgrade <tool>` — `foldrun gallery` lists them");
1774
+ if (!name) throw new Error("which one? `foldrun gallery upgrade <tool or skill>` — `foldrun gallery` lists them");
1762
1775
  const body = await remoteCall(url, flags, "/api/library/gallery", { method: "POST", body: JSON.stringify({ tool: name }) });
1763
1776
  console.log(`\n ${c.green("upgraded")} ${c.bold(name)} ${c.dim(`in the account library to the gallery's current version (${body.path}) — the previous copy is one revision back`)}\n`);
1764
1777
  return 0;
@@ -1768,19 +1781,28 @@ async function galleryCmd(positional, flags) {
1768
1781
  if (verb === "pull") {
1769
1782
  const dir = galleryCacheDir(url);
1770
1783
  const files = writeGalleryCache(dir, tools);
1771
- console.log(`\n ${c.green("✓")} ${tools.length} gallery tools, ${files} files ${c.dim(`→ ${dir}`)}`);
1784
+ const skills = tools.filter((t) => t.kind === "skills").length;
1785
+ console.log(`\n ${c.green("✓")} ${tools.length - skills} gallery tools and ${skills} skills, ${files} files ${c.dim(`→ ${dir}`)}`);
1772
1786
  console.log(` ${c.dim("`foldrun run` refreshes this itself before each run; this is for offline work")}\n`);
1773
1787
  return 0;
1774
1788
  }
1775
1789
  if (verb) throw new Error(`\`foldrun gallery ${verb}\` — the verbs are \`pull\` and \`upgrade <tool>\`, or none to list`);
1776
- console.log("");
1777
- for (const t of tools) {
1778
- const own = t.installed === "current" ? c.dim("your copy, current")
1779
- : t.installed === "differs" ? c.amber("your copy differs — `foldrun gallery upgrade " + t.name + "`")
1780
- : c.dim("from the platform");
1781
- console.log(` ${c.bold(t.name.padEnd(18))} ${t.title} ${own}`);
1790
+ if (flags.json) {
1791
+ console.log(JSON.stringify(tools.map(({ name, kind, title, description, installed }) => ({ name, kind, title, description, installed })), null, 2));
1792
+ return 0;
1793
+ }
1794
+ for (const [kind, heading, grant] of [["tools", "tools", "tools: [name]"], ["skills", "skills", "skills: [name]"], ["scripts", "scripts", "scripts: [name]"]]) {
1795
+ const shelf = tools.filter((t) => (t.kind ?? "tools") === kind);
1796
+ if (!shelf.length) continue;
1797
+ console.log(`\n ${c.bold(heading)} ${c.dim(`— grant with \`${grant}\``)}`);
1798
+ for (const t of shelf) {
1799
+ const own = t.installed === "current" ? c.dim("your copy, current")
1800
+ : t.installed === "differs" ? c.amber("your copy differs — `foldrun gallery upgrade " + t.name + "`")
1801
+ : c.dim("from the platform");
1802
+ console.log(` ${c.bold(t.name.padEnd(18))} ${t.title} ${own}`);
1803
+ }
1782
1804
  }
1783
- console.log(`\n ${c.dim(`${tools.length} tools on ${url} — grant one with \`tools: [name]\`; nothing to install`)}\n`);
1805
+ console.log(`\n ${c.dim(`on ${url} — in every account, nothing to install`)}\n`);
1784
1806
  return 0;
1785
1807
  }
1786
1808
 
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\`). A step held to its list still searches the web through the proxy's search door; at \`none\` or \`defaults: false\` write \`web: {actions: [search, fetch]}\` to accept that its queries leave. 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\`).
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, and its \`network: [sites]\` join the step's network list; list on an agent only the secrets it uses directly. The platform's gallery ships tools and skills to every account, granted by name with nothing installed: \`docs\` (a library's current docs, pinned to a version — use it before writing against any framework API), \`video\` (Remotion video), and the skills \`modern-website\`, \`motion-video\` and \`cloudhost-deploy\`, which load only for an agent whose \`skills:\` names them (\`foldrun gallery\`). 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\`). A step held to its list still searches the web through the proxy's search door; at \`none\` or \`defaults: false\` write \`web: {actions: [search, fetch]}\` to accept that its queries leave. 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