foldrun 18.0.1 → 18.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/agents.md CHANGED
@@ -518,12 +518,16 @@ step restores the snapshot instead, in about a second (154 packages, 432 MB:
518
518
  30 s through apt, under 1 s from the snapshot). A snapshot belongs to the
519
519
  runner image it was built on: it is restored only onto an image whose
520
520
  installed packages are exactly the same, because the files in it were built
521
- against those packages. A release whose image did not move any package keeps
522
- it; one that did (a Debian security update, a new Chrome) builds a new
523
- snapshot beside the old one the first time the set is needed — the run log
524
- then says `(apt, 30s, 1 snapshot did not fit this image)`. A snapshot is
525
- rebuilt 14 days after it was made, so the packages in it pick up Debian's
526
- fixes. The run log says `system packages ready: … (snapshot, 1s)` or
521
+ against those packages. On the hosted platform the runner's operating system,
522
+ its Debian packages and its browsers are a base image of their own, which
523
+ changes only when it is refreshed: once a week, and at once when a critical
524
+ security fix is out for something in it. A release that changes only
525
+ foldrun's own code is built on the same base, so your snapshots keep working
526
+ after it. After a refresh, the first step that needs a set builds a new
527
+ snapshot beside the old one — the run log then says
528
+ `(apt, 30s, 1 snapshot did not fit this image)` — and every step after it
529
+ restores that one. A snapshot is also rebuilt 14 days after it was made, so
530
+ the packages in it pick up Debian's fixes. The run log says `system packages ready: … (snapshot, 1s)` or
527
531
  `(apt, 30s)`, or fails the step with apt's own reason.
528
532
 
529
533
  A snapshot is written into the account's runtime cache, which steps can
package/docs/cli.md CHANGED
@@ -49,7 +49,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
49
49
  | `foldrun agent import <workspace>/<agent>` | copy an agent you already have in another workspace into this one: its `agent.md` and own `skills/`, `scripts/`, `knowledge/` — never `memory/`, `outputs/` or `state/`. Into the workspace you stand in, or `--workspace <name>`; `--as <name>` imports it under another name (and rewrites `name:`), which a name clash requires. `--to <workspace>` does it on the platform (`POST /api/workspaces/<ws>/agents/import`) and lists the tools, skills, scripts and secrets the copy uses that the workspace lacks. See [Importing an agent](workspaces#importing-an-agent-you-already-have) |
50
50
  | `foldrun agent import --list` | what could be imported into a deployed workspace: every other workspace this key may read, and each one's agents with their descriptions (`GET …/agents/import`). Imports nothing. `--to <workspace>`, `--json` |
51
51
  | `foldrun agent unlink <agent>` | take one away: `--subagent <name>`, `--consult <name>` or `--can-ask`. An emptied list is written `key: []`, not deleted. In this folder, refused the same way, nothing written, when the file changed since it was read |
52
- | `foldrun agent network <agent> [open\|trusted\|none\|inherit]` | which sites the agent's sandbox may reach ([Network](network)). Alone, prints what a run resolves — the level, where it came from, the sites added. With a level and/or `--add <site>` / `--remove <site>` (repeatable), rewrites the one `network:` line of its `agent.md` — the edit the dashboard's Network card makes — prints the diff and the new resolution; `inherit` drops the agent's own level, and a line with nothing left to say is removed. `--dry-run` writes nothing; `--to <workspace>` edits the deployed copy through `PATCH /api/workspaces/<ws>/agents/<name>` |
52
+ | `foldrun agent network <agent> [open\|trusted\|none\|inherit]` | which sites the agent's sandbox may reach ([Network](network)). Alone, prints what a run resolves — the level, where it came from, the sites added — and, for an agent that searches, how a step walled to that list searches (through the egress proxy's search door, or not at all under a list narrow on purpose whose `web:` names no actions). With a level and/or `--add <site>` / `--remove <site>` (repeatable), rewrites the one `network:` line of its `agent.md` — the edit the dashboard's Network card makes — prints the diff and the new resolution; `inherit` drops the agent's own level, and a line with nothing left to say is removed. `--dry-run` writes nothing; `--to <workspace>` edits the deployed copy through `PATCH /api/workspaces/<ws>/agents/<name>` |
53
53
  | `foldrun flow add <flow> <pattern>` | one palette block from the [flow canvas](flows#editing-on-the-canvas), as the same markdown edit the canvas writes (core's `flow-patterns`): `chain` (alias `step`: `--agent <name>`, `--instruction "…"`, `--after <n>` or `--before <n>`, default last), `parallel` (`--agent`, `--group <n>`), `router` (`--agent <triage>`, `--cases BUG=bugs,DOCS=docs`, `--else <agent>`, `--after`), `fan-out` (`--step`, `--each lines\|items\|"rows of <path>"`, `--max <n>`), `loop` (alias `evaluator`: `--step`, `--loop <n>` default 3, `--until <MARKER>` default APPROVED, `--judge "<claim>"` adds `verify: judge:`), `approval` (`--step`; the `!` marker, `approve: true` on a `?` step), `ask` (`--step`, `--question "…"`), `wait` (`--step`, `--wait 30m\|event`), `rescue` (`--step`, `--on-fail <agent>`), `subflow` (`--flow <other>`, `--after`). `--step` is the step's place in the file (1 = the first step line) or the agent it runs; `--off` takes a step pattern back off. Prints the diff, runs the rules `check` runs over the result and refuses — writing nothing — an edit that would add an error; one that was there before does not block it. `--dry-run` shows the diff and writes nothing. In this folder by default; `--to <workspace>` edits the deployed copy through the canvas's own route (`PATCH …/flows/<flow>` with `{ edit }`), and the sha256 of the file it read as `expect`: one edited meanwhile is refused (`409`), nothing written. In this folder it re-reads the file just before writing — after the y/N, after `check` — and refuses the same way, writing nothing, when it changed since it was read |
54
54
  | `foldrun flow rm-step <flow> --step <n\|agent>` | delete one step, as the canvas's × does (core's `removeStep`): the step line and its indented options go, the groups after an emptied one renumber, prose and the agent's file are untouched. Says what else changes first (`case:`/`when:` steps that will route on the step before, the renumbering), prints the diff, refuses one `foldrun check` would call a new error, then asks — no terminal needs `--yes`. `--step` is the step's place in the file (1 = the first step line) or the agent it runs. `--dry-run` writes nothing; `--to <workspace>` sends the canvas's `PATCH …/flows/<flow>` with `{ edit: { op: "remove", step } }`, and the sha256 of the file it read as `expect`: one edited meanwhile is refused (`409`), nothing written. In this folder it re-reads the file just before writing — after the y/N, after `check` — and refuses the same way, writing nothing, when it changed since it was read |
55
55
  | `foldrun flow rm-step <flow> --step 2,4` | delete several steps in one revision, as the canvas's multi-select delete: a comma list of step numbers or agent names, removed highest first so each names the step it did when the list was made. One write in this folder; with `--to <workspace>`, one `PATCH …/flows/<flow> { edits: [{ op: "remove", step }, …], expect }`. Says what else changes for each, shows the diff, refuses a new `check` error, asks (`--yes`), `--dry-run` |
package/docs/network.md CHANGED
@@ -135,7 +135,8 @@ On a cluster the pod's network policy backs this up. A step whose level is
135
135
  `trusted` or `none` runs in a pod that may reach the proxy and nothing else,
136
136
  so a program that ignores the proxy variables finds no route instead of
137
137
  going round the list; it cannot reach the account's browser or search pods
138
- either, which are the world fetched on a run's behalf.
138
+ either, which are the world fetched on a run's behalf. Its web search goes
139
+ through the proxy instead ([Search](#search), below).
139
140
 
140
141
  ### DNS
141
142
 
@@ -170,6 +171,58 @@ egress: CONNECT pypi.org:443 × 3 (840ms total)
170
171
  network: example.com is not a site this step may reach (network: trusted). To allow it, add just this site to the agent's network: list — network: [example.com] — which keeps network: trusted for everything else. Refused.
171
172
  ```
172
173
 
174
+ ### Search
175
+
176
+ A step walled to its list (on a cluster, with the list restricted and
177
+ enforced) cannot reach the account's search engine — it is a pod with the
178
+ world, and the wall lets the step reach only the egress proxy. So the proxy
179
+ asks it on the step's behalf: the web tool's `search`, `answer` and
180
+ `monitor` (a query) go to the proxy's **search door**, which only a step
181
+ the runner gave it may use. The engine is a platform service, not a site on
182
+ the list, and nothing about it widens the list. The trace says so:
183
+
184
+ ```
185
+ search: through the egress proxy — the account's search engine answers this step's queries from a fixed set of engines; a query's words leave for those engines, and each query is a line in this trace; a result is data, and fetching it is held to network: like any other site
186
+ search: a query (37 characters, 5 words) sent to yandex, naver, brave, wikipedia through the account's engine — its words may reach those public search engines
187
+ ```
188
+
189
+ What that means, plainly:
190
+
191
+ - **A query is a message out.** Its words reach public search engines, and
192
+ nothing can stop words carrying what the step knows. The door bounds
193
+ *where* they go — a fixed set of engines (`yandex`, `naver`, `brave`,
194
+ `wikipedia`; `arxiv`, `pubmed` for `categories: science`; `github`,
195
+ `stackoverflow` for `it`), each asking its own provider with the text —
196
+ and records *that* each one went. No engine that fetches a URL named in
197
+ the query, none that reaches a server the query picks; no engine, bang or
198
+ timeout chosen inside the query (`!name`, `!!bang`, `<5` are refused), no
199
+ URL and no `${NAME}` in it, no plugin or DOI resolver chosen by the step.
200
+ Any program in the step can use the door, not only the web tool, and each
201
+ is held the same.
202
+ - **Results are data.** Titles and snippets of any site may come back,
203
+ including sites off the list — that is what a search is. Opening one is a
204
+ fetch, held to the list like any other: `answer` reads each result page
205
+ through the proxy, so a page off the list is refused (its snippet may
206
+ still be quoted, marked as one). Held results open with a line saying they
207
+ are outside content, not instructions.
208
+ - **On the record.** The proxy's trace line gives the engines and the
209
+ query's length, not its words; a query the web tool made is on the step's
210
+ record with the tool call, as every call is (secret values redacted). At most 500 searches per step go
211
+ through the door (fewer when `limits:` caps `web` or every searching
212
+ action), four at a time.
213
+ - **Named on purpose where the list is narrow on purpose.** At `none`, or
214
+ with `defaults: false`, a bare `tools: [web]` is not given the door: write
215
+ the action out — `web: {actions: [search, fetch]}` — to accept that its
216
+ queries leave. At `trusted` with the trusted list, the web tool's searching
217
+ actions are offered as they are.
218
+
219
+ A search provider named in `web:` (`web: {search: brave}`) is unchanged: its
220
+ host is a site the step declares, and its key is filled at the proxy. A
221
+ step that is not walled — an open list, one only reported, `foldrun run` on
222
+ your machine, the single-container tier — searches the engine directly, as
223
+ it always has. The dashboard's Network card and `foldrun agent network`
224
+ say which applies to an agent.
225
+
173
226
  ### Report-only, then refuse
174
227
 
175
228
  The list is refused when any one of three says so:
@@ -252,9 +305,8 @@ What a held step does differently:
252
305
  - **Sites a secret is granted to** are where the proxy ends TLS to fill the
253
306
  secret. Chromium is told to trust the egress CA for them; Firefox and
254
307
  WebKit are not, and a page there fails its certificate check.
255
- - **Web search** through the account's search pod is not reachable from a
256
- walled pod either; the trace says so. Name a search provider in `web:`
257
- (it goes through the proxy) or leave search out of that step.
308
+ - **Web search** goes through the egress proxy's search door, as for any
309
+ walled step ([Search](#search)).
258
310
 
259
311
  Not covered: DNS lookups on a cluster that does not wall them (see
260
312
  [DNS](#dns)), and — as for every tunnel — which origins a page loads inside
@@ -263,7 +315,9 @@ a connection to an allowed site.
263
315
  Everywhere else — `foldrun run` on your machine, the single-container tier,
264
316
  an install without the switch, a report-only list, `network: open` — a
265
317
  browsing step is **not** held: it gets no proxy, and the browser and every
266
- other program in the step reach sites directly. The trace says that too:
318
+ other program in the step reach sites directly (unless the install runs the
319
+ [browse service](#the-browse-service), below, which takes the browser out of
320
+ the step). The trace says that too:
267
321
 
268
322
  ```
269
323
  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).
@@ -281,3 +335,46 @@ The dashboard's Network card and `foldrun agent network <agent>` say which
281
335
  applies to an agent. An agent that must stay inside its list where browsing
282
336
  is not held should not browse: give it `web: {actions: [search, fetch]}`,
283
337
  which goes through the proxy like any other program.
338
+
339
+ ### The browse service
340
+
341
+ On a cluster whose operator has switched it on (`FOLDRUN_BROWSE_SERVICE=1`,
342
+ off by default), a step that browses but is **not** held to its list — an
343
+ open list, a report-only one, an install that does not confine browsing —
344
+ runs its browse calls outside its sandbox. Each such step gets a pod of its
345
+ own beside its run pod, on the same runner image, running foldrun's own
346
+ browse program; the pod goes when the step does. The step's `web` tool sends
347
+ each call there through the egress proxy and gets back what the call wrote:
348
+
349
+ - **The same calls, the same answers.** Every mode and action works as it
350
+ does in the step — clicks, fills, frames, `js=` and `eval` (which run in
351
+ the page, as always), screenshots, PDFs, video, HAR, downloads (they come
352
+ back to the path the call names), uploads (the file is sent from the
353
+ workspace), `session=` (kept as the browser's storage state in
354
+ `outputs/.browser/<name>/`, as on the account's browser pod), saved logins
355
+ (`state:` and `state_key:`, read from and written to `state/browser/`),
356
+ aria numbers, `mode=diff` and `mode=crawl`. The live view streams as before.
357
+ - **Its browser goes through the egress proxy** under the step's own lease:
358
+ a site off the list is refused where the list is enforced, and named in
359
+ the trace where it is only reported. The pod's network reaches the proxy
360
+ and DNS, nothing else. The other programs in the step are not held by this
361
+ — only the browser is.
362
+ - **What stays in the step**, exactly as before, saying so on the call: a
363
+ `live:` session, engines other than Chromium and Chrome (Firefox, WebKit,
364
+ Lightpanda, Obscura), `extensions:`, `proxy=`, a vendor's browser, a page
365
+ on the sandbox's own machine or a private address, and a workspace whose
366
+ copy of the `web` tool was edited (the service runs foldrun's own program,
367
+ never an edited one). A call the service could not start runs in the step;
368
+ a call that started there and was cut off is **not** run again — it may
369
+ have clicked — and fails saying so.
370
+ - **A step held to its list** never uses it: its browser stays in its own
371
+ walled pod ([above](#browsing)). Nor does a [test run](runs#test-runs).
372
+
373
+ The trace says which way a step went:
374
+
375
+ ```
376
+ browser: foldrun's browse service — this step's browse calls run outside its sandbox, in a pod of the step's own, and every page goes through the egress proxy under this step's network: list (…)
377
+ egress: browse service × 4 (21.3s total)
378
+ ```
379
+
380
+ The pod's time is on the account's bill like the account's browser pod's.
package/docs/security.md CHANGED
@@ -43,7 +43,11 @@ its list of sites per connection; where it is enforced
43
43
  `FOLDRUN_NETWORK_ENFORCE=1` on the install) its pod has no other route, and no way to the
44
44
  account's browser or search pods. A step that browses is held the same way where the
45
45
  install sets `FOLDRUN_BROWSE_ENFORCE=1`: its browser runs inside that walled pod
46
- ([Browsing](network#browsing)); elsewhere a browsing step is not held to its list. The policy denies every private range (RFC1918) and the
46
+ ([Browsing](network#browsing)); elsewhere a browsing step is not held to its list.
47
+ (The [browse service](network#the-browse-service), where an install runs it, sends
48
+ such a step's eligible browse calls through the proxy from a pod outside the sandbox —
49
+ the browser only: the step's other programs, and the calls the service does not
50
+ serve, still reach sites directly.) The policy denies every private range (RFC1918) and the
47
51
  cloud metadata endpoint — the address that, on a cloud host, hands out the
48
52
  machine's own credentials. It cannot reach the platform's API, its
49
53
  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": "18.0.1",
3
+ "version": "18.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",
package/src/commands.mjs CHANGED
@@ -9898,6 +9898,24 @@ function browsingLine(p) {
9898
9898
  : `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).`;
9899
9899
  }
9900
9900
 
9901
+ /** What a held step's web search does under this list (FOL-128), from
9902
+ * core's `network.search` (core ≥ the FOL-128 release; null before): the
9903
+ * rule of core search-egress.ts searchDoorWanted, read loosely because the
9904
+ * CLI typechecks against the published core. Null when it does not apply. */
9905
+ export function searchLine(p) {
9906
+ const s = p?.search;
9907
+ if (!s || typeof s !== "object" || s.web !== true || p.level === "open") return null;
9908
+ const actions = Array.isArray(s.actions) ? s.actions : null;
9909
+ const provided = Array.isArray(s.provided) ? s.provided : [];
9910
+ const ours = ["search", "answer", "monitor"].filter((a) => (!actions || actions.includes(a)) && !provided.includes(a));
9911
+ if (!ours.length) return null;
9912
+ const enforce = p.enforceWanted === true ? " (network_enforce: true here)" : "";
9913
+ if ((p.level === "none" || p.defaults === false) && !actions) {
9914
+ return `search: on a platform that walls this list, with it enforced${enforce}, this agent is offered no web search — the list is narrow on purpose and web: names no actions; write web: {actions: [search, …]} to let it search through the egress proxy (\`foldrun docs network\`, Search).`;
9915
+ }
9916
+ return `search: on a platform that walls this list, with it enforced${enforce}, web search goes through the egress proxy — the account's engine asks a fixed set of engines, a query's words reach them and each query is on the run's trace; opening a result is held to this list (\`foldrun docs network\`, Search).`;
9917
+ }
9918
+
9901
9919
  /**
9902
9920
  * `foldrun agent network <agent> [open|trusted|none|inherit] [--add <site>]…
9903
9921
  * [--remove <site>]…` — which sites the agent's sandbox may reach, its
@@ -9945,6 +9963,8 @@ async function agentNetworkCmd(positional, flags, layout) {
9945
9963
  console.log(` ${net.networkLine(p, true)}`);
9946
9964
  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")}`);
9947
9965
  if (browses && p.level !== "open") console.log(` ${c.yellow(browsingLine(p))}`);
9966
+ const search = searchLine(p);
9967
+ if (search) console.log(` ${c.dim(search)}`);
9948
9968
  };
9949
9969
  const raw = desk.files.get(rel);
9950
9970
  const now = await resolve(desk.files);
package/src/guide.mjs CHANGED
@@ -30,7 +30,7 @@ export function agentRulesBlock() {
30
30
 
31
31
  # Read foldrun's docs before you edit this folder
32
32
 
33
- This is a foldrun account: agents, flows, tools and knowledge as markdown, run by foldrun. Its formats — frontmatter fields, step options, \`verify:\` prefixes, which folder a file goes in — are foldrun's own and may differ from your training data. Before you write or change an agent, flow, tool or skill, read the relevant guide: \`foldrun docs\` lists them and \`foldrun docs <page>\` prints one (start with \`foldrun docs coding-agents\`). They ship with the CLI, so they match the version you are driving. Check every edit with \`foldrun check\` — offline, no model calls; it is also the security scanner (a key written into a file, hidden text, an agent that can leak), and \`foldrun check --security\` fails on what it finds. Never paste a credential into a file: \`foldrun secrets set NAME\` and write \`\${NAME}\`. For a flow's shape, \`foldrun flow show <flow>\` draws it, and \`foldrun flow add\`, \`foldrun flow rm-step\`, \`foldrun flow dup-step\` and \`foldrun agent link\` make the same edits as the dashboard canvas (patterns, sub-agents, consults, \`ask\`). An agent with \`tools: [peers]\` can message the steps running beside it in its parallel group (\`peers_message\`) and ask for what they have instead of guessing or failing (\`foldrun docs agents\`). A sub-agent that reads untrusted content (web pages, mail, uploads) gets \`sandbox: own\` in its own file: each job then runs in a sandbox of its own with its own tools, secrets and network, and only its reply and the files it wrote reach the agent that delegated (\`foldrun agent link <agent> --subagent <worker> --isolated\`). A script tool's own \`secrets: [NAMES]\` are granted with the tool; list on an agent only the secrets it uses directly. A hook (\`hooks/<name>/hook.md\` + \`run.mjs\`, turned on with \`hooks: [name]\`) is code at every tool call, step start and step end — \`foldrun hook add\`/\`test\` and \`foldrun docs hooks\`. Paths to the workspace's own folders are written \`workspace/storage/…\` and \`workspace/state/…\` — in an agent's prose, a flow's options and a script's arguments — not \`../../\`, which still works but is the older spelling. Which sites a step's sandbox may reach is \`network:\` — open for an agent that may fetch or browse the web, the trusted list plus what it declares for every other; add a site with \`foldrun agent network <agent> --add <site>\` (\`foldrun docs network\`). Bind a secret to the sites it is for (\`foldrun secrets sites NAME <site>\`) and no sandbox ever holds its value. What a step's sandbox may use is \`size:\` (\`small\` 1 core/1Gi, \`large\`, \`heavy\` 4 cores/8Gi — hard limits and the billed figures); \`resources: {cpu, memory, disk}\` sets the numbers yourself, key by key over the class (\`foldrun docs agents\`). What steps may hold together is capped at four levels, each only narrowing the one above: the account's and a workspace's \`compute: {vcpu, memory, disk}\` in AGENTS.md, a flow's \`compute:\` for each of its runs, and the plan's most for one step; a step past a cap waits its turn, one bigger than a whole cap fails (\`foldrun usage compute\`, \`foldrun docs budgets-and-billing\`). A webhook, email, chained or storage flow says which deliveries start it with \`filter:\` (\`foldrun flow filter <flow> --payload body.json\` tries one); an eval with \`trigger: runs\` grades a \`sample:\` of real finished runs instead of running cases, \`foldrun eval compare\` runs an eval's cases under several models side by side, and \`improve: true\` turns repeated failures into a proposed fix a person applies (\`foldrun docs evals\`). A flow is served to outside agents over A2A 1.0 when its frontmatter says \`a2a: { publish: true }\` (an admin's change, 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; 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\`).
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