foldrun 18.0.1 → 19.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/docs/agents.md +10 -6
- package/docs/cli.md +1 -1
- package/docs/network.md +102 -5
- package/docs/security.md +5 -1
- package/package.json +2 -2
- package/src/commands.mjs +20 -0
- package/src/guide.mjs +1 -1
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.
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
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
|
|
256
|
-
walled
|
|
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
|
|
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.
|
|
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": "
|
|
3
|
+
"version": "19.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": "^
|
|
14
|
+
"@foldrun/core": "^17.0.0"
|
|
15
15
|
},
|
|
16
16
|
"files": [
|
|
17
17
|
"bin",
|
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
|
|