foldrun 26.3.4 → 26.3.5

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
@@ -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 workspace `AGENTS.md`'s `owner:`, then the account's. Shown on the agent list, the agent's page and `foldrun agent ls` |
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 workspace's or the account's `AGENTS.md` for every agent under it |
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 workspace's or the account's `AGENTS.md` ([Network](network)) |
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 workspace's last thirty finished runs | — |
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 workspace's `notify:` sends approvals. A person answers with a
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 workspace's `tools/` and then the account library. A
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 workspace, like one
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 workspace when its job ends, and is
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 workspace for the next step only. A file the parent had already
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 workspace and whatever the step writes while it
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
- workspace and the sandbox, scratch space included, is deleted.
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 workspace's overview page. A package that will not install is heard at deploy, not from 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 workspace root is `workspace/` — write that,
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 workspace root, removed when the step ends. The older
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
- workspace. A directory a tool made outside the workspace — a repository it
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 workspace is refused with a message naming the path 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 workspace. Frontmatter there sets defaults —
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 → workspace `AGENTS.md` →
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, workspace, account
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 workspace scripts before each page's own, `extensions:` loads
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 → workspace `AGENTS.md` → account
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 workspace scope no wider than the person who minted it. The
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, workspaces) comes whole. A cursor, when one is added, will be a new
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.