foldrun 26.3.4 → 26.3.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/foldrun.mjs +60 -60
- package/docs/a2a.md +12 -12
- package/docs/agents.md +21 -21
- package/docs/api-usage.md +2 -2
- package/docs/api.md +98 -98
- package/docs/assistant.md +21 -21
- package/docs/backups-and-restore.md +11 -11
- package/docs/budgets-and-billing.md +21 -21
- package/docs/checks.md +19 -19
- package/docs/cli.md +100 -100
- package/docs/coding-agents.md +8 -8
- package/docs/deploying.md +7 -7
- package/docs/evals.md +6 -6
- package/docs/extract.md +1 -1
- package/docs/faq.md +5 -5
- package/docs/feature-flags.md +1 -1
- package/docs/flows.md +14 -14
- package/docs/four-jobs.md +5 -5
- package/docs/getting-started.md +10 -10
- package/docs/glossary.md +9 -9
- package/docs/hooks.md +5 -5
- package/docs/how-it-works.md +1 -1
- package/docs/introduction.md +4 -4
- package/docs/knowledge-and-memory.md +6 -6
- package/docs/mcp.md +15 -15
- package/docs/network.md +9 -9
- package/docs/notifications.md +16 -16
- package/docs/oauth.md +1 -1
- package/docs/providers.md +6 -6
- package/docs/runs.md +28 -28
- package/docs/scheduling.md +1 -1
- package/docs/secrets.md +22 -22
- package/docs/security.md +15 -15
- package/docs/self-hosting.md +18 -18
- package/docs/status.md +1 -1
- package/docs/storage-and-sharing.md +14 -14
- package/docs/team-and-access.md +29 -29
- package/docs/tools.md +20 -20
- package/docs/troubleshooting.md +4 -4
- package/docs/workspaces.md +43 -43
- package/package.json +2 -2
- package/src/commands.mjs +131 -131
- package/src/guide.mjs +1 -1
package/docs/agents.md
CHANGED
|
@@ -29,7 +29,7 @@ and new posts. Write the digest to outputs/digest.md.
|
|
|
29
29
|
|---|---|
|
|
30
30
|
| `name` | kebab-case, unique in the account. The agent's identity — the folder must match |
|
|
31
31
|
| `description` | what it does *and when to use it*. Other agents read this when consulting; people read it in the dashboard |
|
|
32
|
-
| `owner` | the person who answers for it — an email or a name. Unset, it is the
|
|
32
|
+
| `owner` | the person who answers for it — an email or a name. Unset, it is the project `AGENTS.md`'s `owner:`, then the account's. Shown on the agent list, the agent's page and `foldrun agent ls` |
|
|
33
33
|
|
|
34
34
|
### Who owns it, and whether anyone still uses it
|
|
35
35
|
|
|
@@ -94,13 +94,13 @@ the point of the week; a step that weighs two arguments and picks one is not.
|
|
|
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)) |
|
|
96
96
|
| `scripts` | programs in `scripts/`, each becoming a callable tool |
|
|
97
|
-
| `hooks` | your own code at every tool call, step start and step end — refuse, rewrite, add context — the same on every model ([Hooks](hooks)). Also in a
|
|
97
|
+
| `hooks` | your own code at every tool call, step start and step end — refuse, rewrite, add context — the same on every model ([Hooks](hooks)). Also in a project's or the account's `AGENTS.md` for every agent under it |
|
|
98
98
|
| `apis` | an HTTP API declared inline, as one tool |
|
|
99
99
|
| `mcpServers` | an MCP server declared inline |
|
|
100
100
|
| `remotes` | outside agents it may call over A2A — `[{name, card, secret?, description?}]`: the four `a2a_*` tools, and each card's own site added to its network ([below](#calling-an-outside-agent-remotes)) |
|
|
101
101
|
| `secrets` | vault entries its tools may use — names only, never values. The names the step's own model call uses (`ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_CUSTOM_HEADERS`, the `ANTHROPIC_*_MODEL` tiers, `CLAUDE_CODE_OAUTH_TOKEN`, `FOLDRUN_MODEL_KEY`) never replace the model's own settings, and `foldrun check` warns: script and API tools and `verify:` get the declared value under that name, but the agent's own shell sees the model's — give it another name (`MY_ANTHROPIC_KEY`), or run the model on it with `provider:` |
|
|
102
102
|
| `limits` | the most calls one step may make — per tool, per web action, or in all: `limits: {web.search: 40, crm: 20, calls: 300, repeat: 5}` (`repeat`: the same call with the same input). A call past a limit is refused, never run; every step has `calls: 1000, repeat: 25` unless set, and one refused 20 times is stopped ([Tools](tools#limits--how-many-calls-a-step-may-make)) |
|
|
103
|
-
| `network` | which sites its sandbox may reach: `open`, `trusted` or `none`, or a list of sites added to the trusted list — `network: [api.hubapi.com]`. Unset, an agent that may fetch or browse the web is `open` and every other `trusted`. Also in a
|
|
103
|
+
| `network` | which sites its sandbox may reach: `open`, `trusted` or `none`, or a list of sites added to the trusted list — `network: [api.hubapi.com]`. Unset, an agent that may fetch or browse the web is `open` and every other `trusted`. Also in a project's or the account's `AGENTS.md` ([Network](network)) |
|
|
104
104
|
| `permissionMode` | `plan` makes the run read-only, whatever else was granted |
|
|
105
105
|
| `web` | the `web` tool's settings: `actions:` — which of its eight it may use (all when absent) — and who does each, `web: {search: brave, fetch: jina, browse: browserbase, crawl: firecrawl}`, with the key named in the vault. Unset is foldrun's own. `search:` also takes a block of the own engine's settings — engines, categories, safesearch, plugins ([Tools](tools#tuning-the-accounts-own-engine)); `browse:` a block of the browser's ([below](#webbrowse--which-browser-and-how-it-presents-itself)), and `browse:` alone cascades from `AGENTS.md`. The providers and their keys: [Tools](tools#reaching-the-web). A per-action key outside the block is not read — `check` errors on it |
|
|
106
106
|
|
|
@@ -115,7 +115,7 @@ only Web takes a provider:
|
|
|
115
115
|
| | `text` | `extract_text(path, lang?, ocr?, save?)` — a file it can reach as text: images and scanned PDFs (Persian and English OCR), text PDFs, DOCX, PPTX, XLSX, EPUB, HTML, and the speech in audio and video, read by foldrun's own extraction service ([Files to text](extract)). `lang` is `fa`, `en` or `auto` (default); `save: true` also writes `<path>.txt` beside the file (or under `outputs/` where it cannot write, or where that file already exists — it never overwrites). Text over 200 KB returns its start; `save: true` keeps all of it in the file (a second call is answered from the cache); files over 200 MB are refused; a long recording may take minutes. Platform runs only — on `foldrun run` it says so and sends nothing. Named `text`, not `extract`, because `extract` is one of `web`'s actions. Platform limits: files up to the install's extraction limit (100 MB by default), 30 files a minute per step, 3 extractions at once per account (shared with the dashboard and API) — past one the tool says when to try again; the same file with the same options is answered from the account's earlier result. `limits: {text: 20}` caps it per step | — |
|
|
116
116
|
| **Code** | `code` | Bash — runs anything in the sandbox: Python and Node (packages via `runtime:`), Debian programs (`runtime: system:`), or a binary you ship | — |
|
|
117
117
|
| **Memory** | `search` | `search_files(query)` over knowledge, memory, state and storage at every scope | — |
|
|
118
|
-
| | `history` | `recall_runs()` and `read_run(id)` — the
|
|
118
|
+
| | `history` | `recall_runs()` and `read_run(id)` — the project's last thirty finished runs | — |
|
|
119
119
|
| | `desks` | `recall_desk_runs()` and `read_desk_run(id)` — the same, across the account's *other* workspaces: ten recent runs each, named per line, up to 100 runs in all. Run records, not files: the way a digest agent reads what every desk concluded this week | — |
|
|
120
120
|
| **People** | `ask` | `ask_person(question, options?)` — asks the person running the desk mid-step and waits for the answer ([below](#asking-a-person-mid-step)) | — |
|
|
121
121
|
| | `peers` | `peers_list()` and `peers_message(to, text)` — the other steps running beside it in its parallel group, and a message to one of them (or all), which reaches that agent after its next tool call ([below](#asking-a-colleague-beside-you)) | — |
|
|
@@ -127,7 +127,7 @@ only Web takes a provider:
|
|
|
127
127
|
`tools: [ask]` gives the agent `ask_person`. It posts a question — with up to
|
|
128
128
|
ten `options` when the answer is one of a few — and waits. The question shows
|
|
129
129
|
on the run page, in the dashboard's banner, in `foldrun approvals`, and goes
|
|
130
|
-
wherever the
|
|
130
|
+
wherever the project's `notify:` sends approvals. A person answers with a
|
|
131
131
|
click, a sentence, `foldrun answer <run-id> "…"` or `POST
|
|
132
132
|
…/runs/<id>/answer`; the agent gets the answer within a second or two and
|
|
133
133
|
carries on in the same step. Nobody answering in time is an answer too: the
|
|
@@ -199,7 +199,7 @@ error in `foldrun check` naming what to write instead: `files` and `bash`
|
|
|
199
199
|
under `web:` (`web: {search: zai}`), and anything else is an unknown tool.
|
|
200
200
|
|
|
201
201
|
Anything in `tools:` that no built-in claims is one of your own tools,
|
|
202
|
-
resolved against the
|
|
202
|
+
resolved against the project's `tools/` and then the account library. A
|
|
203
203
|
`[[link]]` makes that explicit and is the only way to grant a tool whose name
|
|
204
204
|
a built-in would otherwise shadow:
|
|
205
205
|
|
|
@@ -272,7 +272,7 @@ What it may reach and send:
|
|
|
272
272
|
most 50 messages and polls at most 600 times whatever `limits:` says.
|
|
273
273
|
- **Test runs** send nothing: `a2a_send`, `a2a_reply` and `a2a_cancel` say
|
|
274
274
|
what they would have sent.
|
|
275
|
-
- **Retries.** An agent with `remotes:` acts outside the
|
|
275
|
+
- **Retries.** An agent with `remotes:` acts outside the project, like one
|
|
276
276
|
holding an `outward: true` tool: a step that called a tool and then failed
|
|
277
277
|
its `verify:` or `output:` check is not run again on its own, so the work is
|
|
278
278
|
not asked for twice in other words.
|
|
@@ -387,12 +387,12 @@ What holds:
|
|
|
387
387
|
- **Only the reply comes back.** The reply is still text the parent reads —
|
|
388
388
|
it can carry an instruction — but it reaches a model whose sandbox never
|
|
389
389
|
held the page.
|
|
390
|
-
- **Files.** What it writes reaches the
|
|
390
|
+
- **Files.** What it writes reaches the project when its job ends, and is
|
|
391
391
|
copied into the parent's sandbox at the same paths before the reply comes
|
|
392
392
|
back — so the parent's model, its `verify: file:` and the next step all see
|
|
393
393
|
it. The reply lists the paths. Up to 4 MiB and 100 files a job are copied
|
|
394
394
|
back; what is larger is listed as not in the parent's sandbox and reaches
|
|
395
|
-
the
|
|
395
|
+
the project for the next step only. A file the parent had already
|
|
396
396
|
changed in its own sandbox is not overwritten: the job's version is put
|
|
397
397
|
beside it as `<name>.from-<agent><ext>`, and the reply says so. If both
|
|
398
398
|
write one path, the parent, finishing later, wins — as between two steps of
|
|
@@ -450,9 +450,9 @@ All three are **hard ceilings**:
|
|
|
450
450
|
class gets a bigger share.
|
|
451
451
|
- **Disk:** a step over it is evicted rather than the node filling up.
|
|
452
452
|
This is the step's scratch space, not the account's storage: the
|
|
453
|
-
sandbox's copy of the
|
|
453
|
+
sandbox's copy of the project and whatever the step writes while it
|
|
454
454
|
runs. When the step ends, the files it changed are copied back to the
|
|
455
|
-
|
|
455
|
+
project and the sandbox, scratch space included, is deleted.
|
|
456
456
|
|
|
457
457
|
Pick `small` for an agent that mostly waits on an API, `heavy` for one that
|
|
458
458
|
renders a browser or holds real data. The step's `resources:` line reports CPU
|
|
@@ -581,7 +581,7 @@ none — no environment is built for them.
|
|
|
581
581
|
On a platform, a deploy builds the environments its agents need before any
|
|
582
582
|
step does: `foldrun deploy` waits for them and prints each one, ready or
|
|
583
583
|
failed with the installer's own error, and `foldrun runtimes` asks again
|
|
584
|
-
later — as does the **Runtimes** panel on the
|
|
584
|
+
later — as does the **Runtimes** panel on the project's overview page. A package that will not install is heard at deploy, not from the
|
|
585
585
|
first scheduled run.
|
|
586
586
|
|
|
587
587
|
## Installing what a step needs
|
|
@@ -699,7 +699,7 @@ the file tools and through bash.
|
|
|
699
699
|
### Where files live, from the agent's point of view
|
|
700
700
|
|
|
701
701
|
An agent's working directory is its own folder, `agents/<name>/`, and every
|
|
702
|
-
path is relative to it. The
|
|
702
|
+
path is relative to it. The project root is `workspace/` — write that,
|
|
703
703
|
everywhere: in the agent's prose, in a flow's options, in a script's
|
|
704
704
|
arguments and in a shell command.
|
|
705
705
|
|
|
@@ -713,7 +713,7 @@ arguments and in a shell command.
|
|
|
713
713
|
`workspace/` resolves the same in the file tools (Read, Write, Edit, Glob,
|
|
714
714
|
Grep), in Bash and the scripts it runs, in `scripts:` and folder tools, and
|
|
715
715
|
in a shell `verify:` — for the length of a step the agent's folder holds a
|
|
716
|
-
`workspace` link to the
|
|
716
|
+
`workspace` link to the project root, removed when the step ends. The older
|
|
717
717
|
`../../storage/…` reaches the same place and keeps working; `foldrun check`
|
|
718
718
|
points it out as a hint, never an error.
|
|
719
719
|
|
|
@@ -732,9 +732,9 @@ an agent's folder with the same link, so a tool that reads
|
|
|
732
732
|
`workspace/state/…` tests as it runs.
|
|
733
733
|
|
|
734
734
|
There is no `/tmp` for an agent, and no absolute path is inside its
|
|
735
|
-
|
|
735
|
+
project. A directory a tool made outside the project — a repository it
|
|
736
736
|
cloned, say — is reached only through that tool's own read or find action.
|
|
737
|
-
A path outside the
|
|
737
|
+
A path outside the project is refused with a message naming the path the
|
|
738
738
|
agent probably meant; the run page and the agent's Activity page count those
|
|
739
739
|
refusals per step, because each one is a wasted turn and a prompt that names
|
|
740
740
|
the exact path brings the count to zero.
|
|
@@ -751,7 +751,7 @@ concluded; the file is the record.
|
|
|
751
751
|
## AGENTS.md — context above the agent
|
|
752
752
|
|
|
753
753
|
Two scopes, both optional, both inherited: `<account>/AGENTS.md` for everyone,
|
|
754
|
-
`<workspace>/AGENTS.md` for one
|
|
754
|
+
`<workspace>/AGENTS.md` for one project. Frontmatter there sets defaults —
|
|
755
755
|
### `language:` — the language this agent works in
|
|
756
756
|
|
|
757
757
|
```yaml
|
|
@@ -767,7 +767,7 @@ gains one sentence naming the language, `web action=search` asks the engine in i
|
|
|
767
767
|
page's locale, and `web action=fetch` requests it. A `language=` argument on
|
|
768
768
|
`web action=search`, or `locale=` on `web action=browse`, overrides it for one call.
|
|
769
769
|
|
|
770
|
-
It cascades like the clock: agent frontmatter →
|
|
770
|
+
It cascades like the clock: agent frontmatter → project `AGENTS.md` →
|
|
771
771
|
account `AGENTS.md` → `FOLDRUN_LANGUAGE` → English. Leave it out to
|
|
772
772
|
inherit. A value that is not a tag — `Persian` where `fa` was meant — is
|
|
773
773
|
refused by `check` and by the deploy, in one sentence, rather than being
|
|
@@ -791,7 +791,7 @@ rather than a cookie), `device`, `locale` and `timezone` complete the picture. `
|
|
|
791
791
|
runs the same browser with a window (on a virtual screen where the machine
|
|
792
792
|
has none); unset is the usual no-window browser. The same key still
|
|
793
793
|
takes a vendor name on its own (`web: {browse: browserbase}`), and inside a
|
|
794
|
-
block that is `via:`. It cascades like the clock — agent,
|
|
794
|
+
block that is `via:`. It cascades like the clock — agent, project, account
|
|
795
795
|
— and a call argument overrides it for one call. Full table and the reasons:
|
|
796
796
|
[Tools](tools#how-this-agents-browser-presents-itself).
|
|
797
797
|
|
|
@@ -800,7 +800,7 @@ are locks, not defaults: `allowed_domains:` (the only hosts it can reach — a
|
|
|
800
800
|
call may narrow the list, never widen it) and `deny:` (actions it may never
|
|
801
801
|
take, like `eval` or `download`; a misspelt one is refused by `check`).
|
|
802
802
|
Beside them: `boundaries: true` marks the page's words in every reply,
|
|
803
|
-
`init:` runs
|
|
803
|
+
`init:` runs project scripts before each page's own, `extensions:` loads
|
|
804
804
|
unpacked Chrome extensions, `webgpu: true`, `ignore_https_errors: true`, and
|
|
805
805
|
`state_key:` names a secret that encrypts saved logins; `state:` names a saved login every call uses (beside `cookies:` it needs `state_key:`, and the secret then seeds it once — see tools.md); `video: true`
|
|
806
806
|
records every call for the run page to play, and `live_view: false` stops
|
|
@@ -843,7 +843,7 @@ derivation is wrong for a business — `currency: usd` for an Iranian firm
|
|
|
843
843
|
that invoices in dollars, `calendar: gregory` for one that files to a
|
|
844
844
|
Gregorian regulator, `units: imperial` — and nothing else is a key.
|
|
845
845
|
|
|
846
|
-
It cascades like `language:`: agent →
|
|
846
|
+
It cascades like `language:`: agent → project `AGENTS.md` → account
|
|
847
847
|
`AGENTS.md` → `FOLDRUN_REGION` → the region in the language tag (`en-AU`
|
|
848
848
|
says AU) → none. With none, nothing is invented: no currency, metric,
|
|
849
849
|
Gregorian. `region: Australia`, `currency: dollars`, `units: both` and a
|
package/docs/api-usage.md
CHANGED
|
@@ -13,7 +13,7 @@ curl -H "Authorization: Bearer $FOLDRUN_TOKEN" "$FOLDRUN_URL/api/workspaces"
|
|
|
13
13
|
```
|
|
14
14
|
|
|
15
15
|
A key comes from **Settings → API keys** and carries a role (viewer, editor,
|
|
16
|
-
admin) and a
|
|
16
|
+
admin) and a project scope no wider than the person who minted it. The
|
|
17
17
|
dashboard uses the session cookie instead; both go through the same funnel. A
|
|
18
18
|
handful of routes are a person's alone and refuse a key — see
|
|
19
19
|
[api](api.md#authentication).
|
|
@@ -185,5 +185,5 @@ Some carry a `code` a program can branch on beside it — `unknown_api_version`,
|
|
|
185
185
|
There is no cursor yet. The lists that can grow — runs — answer newest first
|
|
186
186
|
and take `limit` (`/api/workspaces/<ws>/runs?limit=`, default 50, at most
|
|
187
187
|
500). Everything else (flows, agents, keys,
|
|
188
|
-
secrets,
|
|
188
|
+
secrets, projects) comes whole. A cursor, when one is added, will be a new
|
|
189
189
|
optional parameter and will not move the API version.
|