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/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 +1 -1
- package/src/commands.mjs +131 -131
- package/src/guide.mjs +1 -1
package/docs/coding-agents.md
CHANGED
|
@@ -30,9 +30,9 @@ foldrun deploy # push the account (or `deploy <workspace>`) to the p
|
|
|
30
30
|
|
|
31
31
|
| Path | What |
|
|
32
32
|
|---|---|
|
|
33
|
-
| `AGENTS.md` | the account's shared context and defaults — every agent in every
|
|
33
|
+
| `AGENTS.md` | the account's shared context and defaults — every agent in every project reads it (except the managed coding-agent block, which the runtime strips) |
|
|
34
34
|
| `workspaces/<name>/` | one workspace: a desk, a pipeline, a product |
|
|
35
|
-
| `workspaces/<name>/AGENTS.md` | that
|
|
35
|
+
| `workspaces/<name>/AGENTS.md` | that project's context and settings |
|
|
36
36
|
| `workspaces/<name>/agents/<name>/agent.md` | one role: its persona, model, tools |
|
|
37
37
|
| `workspaces/<name>/flows/<name>.md` | steps, in order, naming the agents that run them |
|
|
38
38
|
| `workspaces/<name>/knowledge/` | reference material agents read |
|
|
@@ -42,7 +42,7 @@ foldrun deploy # push the account (or `deploy <workspace>`) to the p
|
|
|
42
42
|
| `workspaces/<name>/tools/` | a folder tool: its definition and its code together |
|
|
43
43
|
| `workspaces/<name>/scripts/` | code the agents call, referenced by `scripts:` |
|
|
44
44
|
| `workspaces/<name>/state/` | what runs accumulate. Yours to read, never deployed over |
|
|
45
|
-
| `library/` | skills, tools, scripts and knowledge shared by every
|
|
45
|
+
| `library/` | skills, tools, scripts and knowledge shared by every project here |
|
|
46
46
|
| `.claude/agents/<name>.md` | a Claude Code subagent — deploys AS an agent |
|
|
47
47
|
|
|
48
48
|
`knowledge/` is what you tell the agents; `memory/` is what they worked out.
|
|
@@ -78,26 +78,26 @@ api workspaces/$WS/flows/<flow>/run -X POST # start one
|
|
|
78
78
|
|
|
79
79
|
| Route (`/api/workspaces/<ws>` unless noted) | Methods | For |
|
|
80
80
|
|---|---|---|
|
|
81
|
-
| `/` | GET DELETE PATCH | the
|
|
81
|
+
| `/` | GET DELETE PATCH | the project itself |
|
|
82
82
|
| `/deploy` | POST | what `foldrun deploy` calls |
|
|
83
83
|
| `/source` | GET PUT PATCH DELETE | read and write single files |
|
|
84
84
|
| `/runs` · `/runs/<id>` | GET · GET DELETE | list runs; one run, every step |
|
|
85
85
|
| `/runs/<id>/stream` | GET | live events, server-sent |
|
|
86
86
|
| `/runs/<id>/stop` · `/rerun` · `/approve` | POST | kill it; again from a step; release a gate |
|
|
87
87
|
| `/flows` · `/flows/<f>` · `/flows/<f>/run` | GET POST · POST DELETE PATCH · POST | list, create, edit, start |
|
|
88
|
-
| `/agents` · `/agents/<a>/run` · `/agents/import` | GET POST · POST · GET POST | list agents, run one, copy one in from another
|
|
88
|
+
| `/agents` · `/agents/<a>/run` · `/agents/import` | GET POST · POST · GET POST | list agents, run one, copy one in from another project |
|
|
89
89
|
| `/evals` · `/evals/<e>/run` | GET POST · POST | list evals, run one |
|
|
90
90
|
| `/tools/<t>/test` | POST | exercise one tool alone |
|
|
91
91
|
| `/storage` · `/storage/download` · `/storage/upload-url` · `/storage/preview` · `/shares` | GET POST PUT DELETE · GET · POST · GET · POST GET DELETE | files agents produced and people uploaded, any type; a file parsed for reading; public links to them |
|
|
92
92
|
| `/triggers?since=` | GET | why nothing ran: fired vs started per flow, with reasons |
|
|
93
93
|
| `/hooks/<f>/rotate` | POST | new webhook token for a flow |
|
|
94
|
-
| `/export` · `/import` | GET · POST | the
|
|
95
|
-
| `/restore` | POST | the
|
|
94
|
+
| `/export` · `/import` | GET · POST | the project, a flow (`?kind=flow&name=`) or an agent as a .zip; take one in (`?dryRun=1` first, `?overwrite=1` to replace) |
|
|
95
|
+
| `/restore` | POST | the project's source back to a point in its history — `dryRun` first, then `confirm` |
|
|
96
96
|
| `/notify/deliveries` · `/notify/deliveries/<id>/redeliver` | GET · POST | every notify: webhook sent and each attempt; send one again |
|
|
97
97
|
| `/api/secrets` · `/api/schedule` · `/api/account` · `/api/keys` | account-level | the vault, the clock, defaults, API keys |
|
|
98
98
|
| `/api/me/notifications` | GET PATCH | what mail you get, per category; a key acts for whoever minted it |
|
|
99
99
|
|
|
100
|
-
A key carries a role (viewer, editor, admin) and a
|
|
100
|
+
A key carries a role (viewer, editor, admin) and a project scope no wider
|
|
101
101
|
than the person who minted it. Team, profile and MFA routes are a person's
|
|
102
102
|
alone and refuse a key. The full reference with request and response shapes
|
|
103
103
|
is the platform's `docs/api.md`.
|
package/docs/deploying.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Deploying
|
|
2
2
|
|
|
3
|
-
A
|
|
3
|
+
A project deploys by sending its files: `foldrun deploy` from a folder,
|
|
4
4
|
from your laptop or from CI. Every deploy is checked before anything goes
|
|
5
5
|
live, refuses to swap files under a run in flight, and never touches what
|
|
6
6
|
the platform owns.
|
|
@@ -16,18 +16,18 @@ foldrun deploy --to leads --commit $(git rev-parse HEAD)
|
|
|
16
16
|
|
|
17
17
|
In CI there is no browser: set `FOLDRUN_URL` and `FOLDRUN_TOKEN` (a key from
|
|
18
18
|
Settings → API keys, or `foldrun keys create`) and the same commands run. A
|
|
19
|
-
key for CI should open the one
|
|
19
|
+
key for CI should open the one project it deploys:
|
|
20
20
|
`foldrun keys create ci --workspaces leads`.
|
|
21
21
|
|
|
22
22
|
`--commit` records which commit of your own repository the files came from;
|
|
23
|
-
the
|
|
23
|
+
the project page and its History show it.
|
|
24
24
|
|
|
25
25
|
## Your own GitHub or GitLab
|
|
26
26
|
|
|
27
27
|
Keep the folder in your own repository and deploy it from CI with the
|
|
28
28
|
commands above. A connected app — a push to your main branch deploys,
|
|
29
29
|
other branches become previews, a check on every commit — is coming, for
|
|
30
|
-
GitHub first, then GitLab. Until 17 October 2026 every
|
|
30
|
+
GitHub first, then GitLab. Until 17 October 2026 every project was also a
|
|
31
31
|
git remote on the platform, with deploy keys, branch previews, a mirror and
|
|
32
32
|
a GitHub push webhook; those went, and history moved to the platform's own
|
|
33
33
|
snapshots (below).
|
|
@@ -37,7 +37,7 @@ snapshots (below).
|
|
|
37
37
|
The tree is validated the way `foldrun check` validates it — a step naming an
|
|
38
38
|
agent that does not exist, a tool that resolves to nothing, a knowledge
|
|
39
39
|
concept with no `type:` — and a deploy with issues is refused with the list.
|
|
40
|
-
The
|
|
40
|
+
The project on disk is unchanged.
|
|
41
41
|
|
|
42
42
|
## What a deploy never touches
|
|
43
43
|
|
|
@@ -55,8 +55,8 @@ overrides that when you mean it.
|
|
|
55
55
|
|
|
56
56
|
## History and rollback
|
|
57
57
|
|
|
58
|
-
Every change to a
|
|
59
|
-
import — with who, when and a diff, on the
|
|
58
|
+
Every change to a project is a revision — a deploy, a dashboard edit, an
|
|
59
|
+
import — with who, when and a diff, on the project's History page and at
|
|
60
60
|
`/api/workspaces/<ws>/history`. Every revision also keeps a snapshot of the
|
|
61
61
|
whole source as it stood just after it: the platform's own deploy history,
|
|
62
62
|
so rolling back never needs a repository.
|
package/docs/evals.md
CHANGED
|
@@ -33,7 +33,7 @@ satisfy. The heading is the case's name, so make it the thing being checked.
|
|
|
33
33
|
|---|---|
|
|
34
34
|
| `name` | the eval's identity |
|
|
35
35
|
| `agent` **or** `flow` | what runs. A flow eval runs the whole flow per case |
|
|
36
|
-
| `model` | the **judge's** tier, not the subject's — cases run the agent on its own model. Unset, the
|
|
36
|
+
| `model` | the **judge's** tier, not the subject's — cases run the agent on its own model. Unset, the project's `judge:` in `AGENTS.md` (see [The four jobs](four-jobs#judge--the-evaluation-default)), else the fast tier |
|
|
37
37
|
| `effort` | the judge's effort. PASS/FAIL against one sentence is not deep work |
|
|
38
38
|
| `trigger` | `deploy` (default), `manual`, or `runs` — grade real finished runs instead of running cases (see [Grading live runs](#grading-live-runs)) |
|
|
39
39
|
| `sample` | `trigger: runs` — the percent of finished runs graded, 0 to 100 (default 25) |
|
|
@@ -60,12 +60,12 @@ wrong. The same vocabulary is a step's `verify:`, so a flow and an eval say
|
|
|
60
60
|
## When they run
|
|
61
61
|
|
|
62
62
|
`trigger: deploy` — the default — runs the eval on every deploy of the
|
|
63
|
-
|
|
63
|
+
project, which is what makes it a regression test rather than a thing someone
|
|
64
64
|
remembers to click. Results land in `evals/.results/`, and a dated line goes to
|
|
65
65
|
`history.jsonl` so movement is visible across weeks.
|
|
66
66
|
|
|
67
|
-
Each line is stamped with the commit the
|
|
68
|
-
a revision id `r-…` when it was edited on the platform), and the
|
|
67
|
+
Each line is stamped with the commit the project was running (a git sha, or
|
|
68
|
+
a revision id `r-…` when it was edited on the platform), and the project's
|
|
69
69
|
**Observe** page reads them as **Evals by change**: each eval's latest score
|
|
70
70
|
against its most recent run on a *different* commit, the biggest drop first.
|
|
71
71
|
Not the run before — two runs on one commit differ only by the model, and a
|
|
@@ -115,7 +115,7 @@ expect:
|
|
|
115
115
|
hash of the run id, so the same run is always in or out.
|
|
116
116
|
- **When.** The platform grades a few runs every five minutes, at most four
|
|
117
117
|
per account a pass, so a backlog drains steadily rather than spending at
|
|
118
|
-
once. A paused account or
|
|
118
|
+
once. A paused account or project is not graded.
|
|
119
119
|
- **The checks.** `contains:`, `not-contains:` and `judge:`, cheap ones
|
|
120
120
|
first; the judge only runs when they pass. `file:` and `run:` are refused
|
|
121
121
|
(`foldrun check` and the deploy say so): a finished run's sandbox is gone,
|
|
@@ -128,7 +128,7 @@ expect:
|
|
|
128
128
|
after an hour, three times at most.
|
|
129
129
|
- **What it costs.** One judge call per `judge:` line per graded run — at
|
|
130
130
|
most five lines in a grader — on the account's own model key like any
|
|
131
|
-
eval judge. A paused account or
|
|
131
|
+
eval judge. A paused account or project is not graded, by the pass or
|
|
132
132
|
by **Grade a run**. The card shows what the
|
|
133
133
|
judges cost; the runs' own cost is on the runs.
|
|
134
134
|
|
package/docs/extract.md
CHANGED
|
@@ -135,7 +135,7 @@ The answer:
|
|
|
135
135
|
|
|
136
136
|
Every route, field and refusal is in [api](api.md#files-to-text). Starting
|
|
137
137
|
an extraction of a file you send takes what starting a run takes; reading a
|
|
138
|
-
stored file takes read access to its
|
|
138
|
+
stored file takes read access to its project, writing its `.txt` beside it
|
|
139
139
|
takes write access.
|
|
140
140
|
|
|
141
141
|
## Engines and their licences
|
package/docs/faq.md
CHANGED
|
@@ -2,11 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
**Is this a framework?** No. There is nothing to import. An agent is a folder,
|
|
4
4
|
a flow is a numbered list in a markdown file, and the CLI or the platform
|
|
5
|
-
reads them. You can write a working
|
|
5
|
+
reads them. You can write a working project in an editor with no
|
|
6
6
|
dependency installed.
|
|
7
7
|
|
|
8
8
|
**Do I need an account to try it?** No. `npm install -g foldrun`, a model key,
|
|
9
|
-
and `foldrun init` gives you a
|
|
9
|
+
and `foldrun init` gives you a project that runs on your machine. The
|
|
10
10
|
account is for running it somewhere that is not your laptop, on a schedule,
|
|
11
11
|
with a team.
|
|
12
12
|
|
|
@@ -14,7 +14,7 @@ with a team.
|
|
|
14
14
|
tier — `fast`, `default`, `max` — and the platform resolves the tier to a
|
|
15
15
|
model. Bring your own key for any provider that speaks the Anthropic or the
|
|
16
16
|
Chat Completions API — once for the whole account in Settings → Models
|
|
17
|
-
(`foldrun account model set`), or per
|
|
17
|
+
(`foldrun account model set`), or per project or agent with a `provider:`
|
|
18
18
|
block — and the platform bills you nothing for those tokens. On a hosted
|
|
19
19
|
platform every account brings its own API key — Claude login tokens are not
|
|
20
20
|
accepted — or, on foldrun's own platform, chooses **foldrun's models**:
|
|
@@ -31,7 +31,7 @@ file names a tool that can, and the reference pattern is to give that tool
|
|
|
31
31
|
only to the step after a human gate. An agent with no tool that writes cannot
|
|
32
32
|
write, whatever it is told.
|
|
33
33
|
|
|
34
|
-
**What stops a runaway?** Three caps — per run, per
|
|
34
|
+
**What stops a runaway?** Three caps — per run, per project per month, per
|
|
35
35
|
account per month — and the stop button, which destroys the sandbox. A
|
|
36
36
|
step with no `timeout:` runs until it finishes; that is deliberate, and the
|
|
37
37
|
caps are the ceiling.
|
|
@@ -49,7 +49,7 @@ other with `trigger: flow`.
|
|
|
49
49
|
`.claude/agents/<name>.md` deploys as a foldrun agent with no conversion.
|
|
50
50
|
The scaffolded `CLAUDE.md` tells your editor the layout.
|
|
51
51
|
|
|
52
|
-
**Where is my data?** In your
|
|
52
|
+
**Where is my data?** In your project's folder, as files — on your machine,
|
|
53
53
|
or on the hosted platform's data volume — and its blobs in the
|
|
54
54
|
file store. Nothing is hidden in a database only the platform can read, and
|
|
55
55
|
a deploy never touches what an agent learned or a run recorded.
|
package/docs/feature-flags.md
CHANGED
|
@@ -36,7 +36,7 @@ account in the beta first, then for a rollout, then for everyone. The
|
|
|
36
36
|
features are finished, but may still change.
|
|
37
37
|
|
|
38
38
|
Joining or leaving is the account's own choice, made by an admin of every
|
|
39
|
-
|
|
39
|
+
project, and it can be undone at any time:
|
|
40
40
|
|
|
41
41
|
- the dashboard: **Settings → General → Beta features**;
|
|
42
42
|
- `foldrun account beta on` (or `off`; bare `foldrun account beta` shows where
|
package/docs/flows.md
CHANGED
|
@@ -103,7 +103,7 @@ begins.
|
|
|
103
103
|
| `loop:` | send the flow back one group up to N times (capped at 5) |
|
|
104
104
|
| `until:` | the marker that ends the loop |
|
|
105
105
|
| `output:` | `json` — the reply must end with one ```json block, parsed and passed on losslessly |
|
|
106
|
-
| `schema:` | with `output: json` — the JSON Schema the value must satisfy: one-line JSON, a YAML block under the key, or a file under the
|
|
106
|
+
| `schema:` | with `output: json` — the JSON Schema the value must satisfy: one-line JSON, a YAML block under the key, or a file under the project |
|
|
107
107
|
| `model:` | override the tier for this step |
|
|
108
108
|
| `effort:` | override how hard it thinks for this step |
|
|
109
109
|
| `max_output_tokens:` | the longest one model reply may be for this step, in tokens — over the flow's and the agent's |
|
|
@@ -111,12 +111,12 @@ begins.
|
|
|
111
111
|
| `timeout:` | seconds, or `90s` / `15m` / `4h` / `3d` — **the only clock there is** |
|
|
112
112
|
| `max_turns:` | the most model turns before the step is stopped (1 to 500) — the third bound beside `budget:` and `timeout:` |
|
|
113
113
|
| `limits:` | this step's call limits, on one line — `limits: {web.search: 10, calls: 50}` — over the agent's, key by key. A call past one is refused, never run ([Tools](tools#limits--how-many-calls-a-step-may-make)) |
|
|
114
|
-
| `verify:` | a shell command, or an assertion (`contains:`, `matches:`, `file:`, `judge:`). The shell runs in the agent's folder and gets the step's final turn in the file `$FOLDRUN_REPLY_FILE`; `workspace/…` reaches the
|
|
114
|
+
| `verify:` | a shell command, or an assertion (`contains:`, `matches:`, `file:`, `judge:`). The shell runs in the agent's folder and gets the step's final turn in the file `$FOLDRUN_REPLY_FILE`; `workspace/…` reaches the project root there, and in `file: workspace/storage/x.md`; `node workspace/tools/x/check.mjs` runs as its own main module, so a check it makes counts ([Agents](agents#where-files-live-from-the-agents-point-of-view)). The check runs on what is left of the step's `timeout:` (at least 30 s of it); with no `timeout:` it has no clock either. A stop ends it |
|
|
115
115
|
| `approve:` | park until a person releases it |
|
|
116
116
|
| `ask:` | the same gate carrying a question; the typed answer reaches the prompt (a plain approval with no note reaches it as "approved with no note") |
|
|
117
117
|
| `preview:` | what the gate shows: paths under `storage/` (a `workspace/storage/` prefix is accepted), comma-separated, globs allowed — `draft/*.mdx, draft/images/*.webp`; at most 12 files |
|
|
118
118
|
| `wait:` | `3d` (`s`/`m`/`h`/`d`, capped at 30 days) or `event` — the run page shows the event URL and can release it with a payload, recorded as released by you (approve with `payload`) |
|
|
119
|
-
| `on-fail:` | another agent takes the step over, with the failure as context — and, for a gated step, the person's approval and answer, which it acts within. The rescuer owes what the step owed: its `verify:`, its `output:`, and a `loop:` step's `until:` marker (a loop that runs out of cycles goes to its rescuer too). A `verify:` that accepts `BLOCKED` never fails, so it never reaches the rescuer. A step refused by the model supply itself — a spent usage window, a credential refused — is not handed to a rescuer on the same supply (the same `provider:`, or both on the
|
|
119
|
+
| `on-fail:` | another agent takes the step over, with the failure as context — and, for a gated step, the person's approval and answer, which it acts within. The rescuer owes what the step owed: its `verify:`, its `output:`, and a `loop:` step's `until:` marker (a loop that runs out of cycles goes to its rescuer too). A `verify:` that accepts `BLOCKED` never fails, so it never reaches the rescuer. A step refused by the model supply itself — a spent usage window, a credential refused — is not handed to a rescuer on the same supply (the same `provider:`, or both on the project's): it would be refused the same way, and the issue is filed as the cap or the credential |
|
|
120
120
|
| `delegate:` | the step's agent picks who runs next, from this set |
|
|
121
121
|
|
|
122
122
|
### What is retried without a `retry:`
|
|
@@ -132,7 +132,7 @@ tried again whoever wrote the flow:
|
|
|
132
132
|
| a `web` provider timed out or answered busy | tried three times, about 2 s and 6 s apart (see the web tool) |
|
|
133
133
|
|
|
134
134
|
None of the step-level ones runs again once a tool that can act outside the
|
|
135
|
-
|
|
135
|
+
project has run in that attempt: the post may already be up. When a step
|
|
136
136
|
still fails, the run says so — `notify:` sends `failed` (and `blocked`, for a
|
|
137
137
|
run that finished but refused), and the run page's **Re-run from here**,
|
|
138
138
|
`foldrun rerun <run-id> --from <n>` or `POST …/runs/<id>/rerun` start it
|
|
@@ -192,7 +192,7 @@ On a day with nothing in the queue the writer skips itself, and without the
|
|
|
192
192
|
`when:` the sheet and the gate would still run — a skipped fan-out leaves no
|
|
193
193
|
result, so there is no marker to read, and a person is asked to approve
|
|
194
194
|
nothing. With it, the run ends after the scan. A missing file, a header on
|
|
195
|
-
its own, or a path outside the
|
|
195
|
+
its own, or a path outside the project all skip, and the step says which.
|
|
196
196
|
|
|
197
197
|
For `case:` it matters more, because routing is exclusive. A label picked
|
|
198
198
|
out of a sentence does not merely run an extra step: "this is not a
|
|
@@ -270,7 +270,7 @@ rides the run record as `data`. A shell `verify:` receives it on stdin.
|
|
|
270
270
|
```
|
|
271
271
|
|
|
272
272
|
One-line JSON works too (`schema: {"type": "array"}`), and so does a file
|
|
273
|
-
under the
|
|
273
|
+
under the project (`schema: workspace/schemas/lead.json`, JSON or YAML). The
|
|
274
274
|
schema is quoted whole in the step's prompt, so the model is told what it
|
|
275
275
|
must produce rather than left to guess from field names, and the value is
|
|
276
276
|
checked where it is parsed. One that does not fit fails the step with the
|
|
@@ -322,7 +322,7 @@ normal outcome, recorded as one.
|
|
|
322
322
|
|---|---|
|
|
323
323
|
| `name` | the flow's identity |
|
|
324
324
|
| `description` | what it is for |
|
|
325
|
-
| `owner` | the person who answers for it — an email or a name; unset, the
|
|
325
|
+
| `owner` | the person who answers for it — an email or a name; unset, the project's `owner:`, then the account's |
|
|
326
326
|
| `trigger` | how it starts — see below |
|
|
327
327
|
| `schedule` / `timezone` | 5-field cron, and the zone it fires in — which is also the calendar every step in this flow works to (see below) |
|
|
328
328
|
| `at` | ISO 8601 instant, for `trigger: once` |
|
|
@@ -334,7 +334,7 @@ normal outcome, recorded as one.
|
|
|
334
334
|
| `model` / `effort` | defaults for every step |
|
|
335
335
|
| `max_output_tokens` | every step's longest reply, in tokens, unless the step says (over the agent's) |
|
|
336
336
|
| `budget` | the most one run may spend, in USD — a number, or `unlimited`; unset is no limit |
|
|
337
|
-
| `compute` | what one run's steps may hold together at once — `{ vcpu: 2, memory: 4Gi, disk: 20Gi }`, any of them. Each run has its own; it only narrows the
|
|
337
|
+
| `compute` | what one run's steps may hold together at once — `{ vcpu: 2, memory: 4Gi, disk: 20Gi }`, any of them. Each run has its own; it only narrows the project's and account's. A step past it waits for one of its run's steps to finish; one bigger than it fails at once ([four levels](budgets-and-billing#compute-at-four-levels)) |
|
|
338
338
|
| `overlap` | `skip` or `queue` when a run is already live |
|
|
339
339
|
| `issues` | `stay-open` (the default: a person resolves this flow's [issues](runs#issues)) or `auto-close` (a run that goes fine closes them) |
|
|
340
340
|
| `priority` | `high`, `normal` or `low` — where this flow's runs stand in the queue against everyone else's |
|
|
@@ -455,7 +455,7 @@ The rules, all of them:
|
|
|
455
455
|
|
|
456
456
|
A filtered delivery counts toward nothing: not `idempotency:`, not
|
|
457
457
|
`throttle:`, not `debounce:`, not `disable_after:`. A paused account or
|
|
458
|
-
|
|
458
|
+
project is still told it is paused first. `filter:` on a `schedule`,
|
|
459
459
|
`once`, `watch` or `manual` flow does nothing, and `foldrun check` says so.
|
|
460
460
|
|
|
461
461
|
Try a delivery without sending one: the Triggers page has a **Test filter**
|
|
@@ -510,7 +510,7 @@ and a slow run may still be doing the work. What to do about it is yours.
|
|
|
510
510
|
|
|
511
511
|
`approvers:` is the list of email addresses that may decide this flow's
|
|
512
512
|
gates, or the single word `admins` for anyone at admin or above. Unset, the
|
|
513
|
-
existing rule applies: anyone who can run the
|
|
513
|
+
existing rule applies: anyone who can run the project can answer.
|
|
514
514
|
|
|
515
515
|
Whatever the list says, **nobody approves a run they started themselves**. A
|
|
516
516
|
gate exists so a second person looks, and a run someone kicked off and then
|
|
@@ -542,7 +542,7 @@ a literal, never an expression, so the cap is readable off the file. An
|
|
|
542
542
|
agent's own `budget:` — the most it may spend in one run — applies to its
|
|
543
543
|
steps too, and the tighter of the two wins. It is shared the same way: the
|
|
544
544
|
agent's steps running at once split what is left of it, so a fan-out of
|
|
545
|
-
twenty copies cannot spend the agent's cap twenty times. The
|
|
545
|
+
twenty copies cannot spend the agent's cap twenty times. The project's and the
|
|
546
546
|
account's caps over time still apply on top.
|
|
547
547
|
|
|
548
548
|
`overlap:` decides what a new fire does while a run of the same flow is live.
|
|
@@ -732,14 +732,14 @@ inputs file — in this folder, or the deployed copy with `--to <workspace>`.
|
|
|
732
732
|
|
|
733
733
|
**Draft with AI** (beside New flow) and **Redraft with AI** (on a card) take
|
|
734
734
|
a description in words and propose the flow file, plus an `agent.md` for each
|
|
735
|
-
agent it needs that the
|
|
735
|
+
agent it needs that the project does not have — existing agents are used by
|
|
736
736
|
name. The proposal is checked with the deploy's own checks and the flow lint
|
|
737
737
|
`foldrun check` runs; if they find errors the model is shown them and
|
|
738
738
|
repairs once, and anything still wrong is listed beside the files. Each file
|
|
739
739
|
is shown as a diff against what is there. **Nothing is written** until you
|
|
740
740
|
press Save and confirm; then each file is saved as an ordinary revision.
|
|
741
741
|
|
|
742
|
-
The model is the
|
|
742
|
+
The model is the project's own Anthropic-format `provider:` when it has
|
|
743
743
|
one (a Chat-Completions provider is refused), else the platform's models,
|
|
744
744
|
billed to the account like a run (one ledger line, flow `ai-draft`). A
|
|
745
745
|
description is at most 4,000 characters and an answer at most 8,000 tokens.
|
|
@@ -766,5 +766,5 @@ abc`, `retry: 9`, `loop: 0`, `each: columns`, `output: yaml` each fail
|
|
|
766
766
|
second.
|
|
767
767
|
|
|
768
768
|
A required step failing fails the flow, and the remaining groups are skipped. A
|
|
769
|
-
|
|
769
|
+
project with one agent and no flows is normal — `foldrun run <agent>` runs it
|
|
770
770
|
as a one-step flow, so there is a single execution path either way.
|
package/docs/four-jobs.md
CHANGED
|
@@ -64,7 +64,7 @@ as `verify:` and `limits:` under a step, stay where they are.
|
|
|
64
64
|
other document, `governance:` and the rest are that document's own words
|
|
65
65
|
and are left as written.
|
|
66
66
|
- **The cascade is unchanged.** The account's `AGENTS.md`, then the
|
|
67
|
-
|
|
67
|
+
project's, then the agent, then the step: a block at one level and a flat
|
|
68
68
|
key at another combine exactly as two flat keys would.
|
|
69
69
|
|
|
70
70
|
## `judge:` — the evaluation default
|
|
@@ -72,8 +72,8 @@ as `verify:` and `limits:` under a step, stay where they are.
|
|
|
72
72
|
`judge: {model, effort}` in `AGENTS.md` is the model, and how hard it
|
|
73
73
|
thinks, for every grader in the workspace: each eval's `judge:` checks and
|
|
74
74
|
every flow step's `verify: judge:`. An eval that names its own `model:` keeps
|
|
75
|
-
it. Unset, judges run on the fast tier. Field by field, the
|
|
76
|
-
a
|
|
75
|
+
it. Unset, judges run on the fast tier. Field by field, the project's wins:
|
|
76
|
+
a project that sets only `effort` keeps the account's `model`.
|
|
77
77
|
|
|
78
78
|
## Where each job shows
|
|
79
79
|
|
|
@@ -86,10 +86,10 @@ a workspace that sets only `effort` keeps the account's `model`.
|
|
|
86
86
|
|
|
87
87
|
`foldrun jobs` prints all four; with `--to <workspace>`, each field's value
|
|
88
88
|
there, the account's, and how the two combine. They do not all simply
|
|
89
|
-
override: `network_enforce` is on when either turns it on, a
|
|
89
|
+
override: `network_enforce` is on when either turns it on, a project's
|
|
90
90
|
`budget` and the account's both apply, `hooks` run from both, `network`
|
|
91
91
|
takes its level from the nearest setting and its sites from every level, `limits` merge key by key, `judge`
|
|
92
92
|
field by field, and `priority` and `concurrency` are read from the account
|
|
93
93
|
alone. The rest — `owner`, `notify`, `alerts`, `telemetry` and others — the
|
|
94
|
-
|
|
94
|
+
project's replaces the account's whole. Fields the CLI cannot set (`limits`,
|
|
95
95
|
`network`, `hooks`, `capture`, …) are written in `AGENTS.md`.
|
package/docs/getting-started.md
CHANGED
|
@@ -16,8 +16,8 @@ foldrun check # free: no model is called
|
|
|
16
16
|
foldrun run publish --task "write about rain"
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
-
`init` scaffolds an **account folder** with one
|
|
20
|
-
|
|
19
|
+
`init` scaffolds an **account folder** with one project in it, and that
|
|
20
|
+
project already works: two agents, a flow that names them, an eval, and
|
|
21
21
|
knowledge they share. `check` validates all of it offline —
|
|
22
22
|
run it after edits the way you would run a typecheck. It is the cheapest
|
|
23
23
|
feedback in the system and it catches a broken flow before a schedule fires it
|
|
@@ -42,7 +42,7 @@ my-account/
|
|
|
42
42
|
```
|
|
43
43
|
|
|
44
44
|
That is the shape the platform keeps, so the folder you edit is the folder that
|
|
45
|
-
runs. `--workspace <name>` names the first
|
|
45
|
+
runs. `--workspace <name>` names the first project (default `main`) and
|
|
46
46
|
`foldrun new <name>` adds another. `foldrun init --flat` makes the older
|
|
47
47
|
single-folder shape instead, and every command still reads it.
|
|
48
48
|
|
|
@@ -114,21 +114,21 @@ foldrun secrets set STRIPE_KEY # prompted, never echoed, never in a fil
|
|
|
114
114
|
```
|
|
115
115
|
|
|
116
116
|
Agents name them in `secrets:` and receive the value at run time. They are never
|
|
117
|
-
written into the
|
|
117
|
+
written into the project, so a project is always safe to commit.
|
|
118
118
|
|
|
119
119
|
## The checklist on the dashboard
|
|
120
120
|
|
|
121
|
-
The first time you open an account that has no
|
|
121
|
+
The first time you open an account that has no project, the dashboard
|
|
122
122
|
starts you in the **welcome flow** (`/dashboard/welcome`): add your model key
|
|
123
123
|
(on a hosted platform, where the account brings its own — every run is
|
|
124
124
|
refused until it has one), choose what to start with — the demo pipeline, a
|
|
125
|
-
blank
|
|
125
|
+
blank project, an imported .zip, the CLI, or connecting your AI app over
|
|
126
126
|
MCP — then run it once and watch each step live, ending on the run's page or,
|
|
127
127
|
if it stops, the reason and the Doctor. Every screen can be skipped, and the
|
|
128
128
|
flow picks up wherever the account really is, however you did the work.
|
|
129
129
|
|
|
130
130
|
After that the home page shows a **Getting started** card: add your model
|
|
131
|
-
key, create a
|
|
131
|
+
key, create a project, write or deploy an agent, run a flow, get a run to
|
|
132
132
|
finish, add a secret, schedule a flow or give it a webhook, invite a
|
|
133
133
|
teammate, set up billing (where the plan asks for it) and install the CLI —
|
|
134
134
|
"4 of 8", with the next step opened up and a link to where to do it, and
|
|
@@ -143,10 +143,10 @@ models, billed in credits). A step's **…** menu hides that step for you; the
|
|
|
143
143
|
card's hides the whole card, and the line at the foot of the page brings it
|
|
144
144
|
back. It goes away by itself once every step is done.
|
|
145
145
|
|
|
146
|
-
Each
|
|
146
|
+
Each project's overview has a **Project checklist** of what a desk needs
|
|
147
147
|
before it can be left to run on its own: a flow that ran to the end, a
|
|
148
148
|
schedule or webhook, an owner, an eval, and `notify:` so someone is told
|
|
149
|
-
when a run fails — each ticked from the
|
|
149
|
+
when a run fails — each ticked from the project itself (the owner and
|
|
150
150
|
`notify:` count when the account's AGENTS.md sets them), each a link to
|
|
151
151
|
where it is done. Hide an item, or the card, for yourself.
|
|
152
152
|
|
|
@@ -162,5 +162,5 @@ a key.
|
|
|
162
162
|
## Where to go next
|
|
163
163
|
|
|
164
164
|
- **The grammar** — every field an agent or flow can carry: Help
|
|
165
|
-
- **The API** — driving a deployed
|
|
165
|
+
- **The API** — driving a deployed project over HTTP: the API reference
|
|
166
166
|
- **The CLI** — every command and flag: the CLI reference
|
package/docs/glossary.md
CHANGED
|
@@ -6,26 +6,26 @@ to outside agents holding an **A2A key**; an agent's `remotes:` are the
|
|
|
6
6
|
outside agents it may call. See [A2A](a2a).
|
|
7
7
|
|
|
8
8
|
**account** — the top level: people, keys, the library, the wallet, and the
|
|
9
|
-
|
|
9
|
+
projects under it. Has one owner.
|
|
10
10
|
|
|
11
11
|
**agent** — one role: a folder with an `agent.md` whose frontmatter grants and
|
|
12
12
|
whose prose is the prompt.
|
|
13
13
|
|
|
14
|
-
**AGENTS.md** — context and defaults, at the account and at each
|
|
14
|
+
**AGENTS.md** — context and defaults, at the account and at each project.
|
|
15
15
|
Prose accumulates downward; a frontmatter key replaces whole.
|
|
16
16
|
|
|
17
17
|
**budget** — a cap: per run (in a flow, or on an agent for its own steps),
|
|
18
|
-
per
|
|
18
|
+
per project over a day, week or month, per account the same. Unset is no
|
|
19
19
|
limit.
|
|
20
20
|
|
|
21
21
|
**conclusion** — a step's final reply, as opposed to every turn joined. What
|
|
22
22
|
checks and headlines read.
|
|
23
23
|
|
|
24
|
-
**desk** — an everyday name for a
|
|
24
|
+
**desk** — an everyday name for a project that does one job on its own —
|
|
25
25
|
a blog desk, a Reddit desk — its agents and flows, running on a schedule.
|
|
26
|
-
Nothing in the format is called a desk; it is a
|
|
26
|
+
Nothing in the format is called a desk; it is a project.
|
|
27
27
|
|
|
28
|
-
**deploy** — sending a
|
|
28
|
+
**deploy** — sending a project's source tree to the platform with
|
|
29
29
|
`foldrun deploy`. Never touches runs, state, secrets or memory.
|
|
30
30
|
|
|
31
31
|
**eval** — a test for an agent or a flow: a task and what a good answer
|
|
@@ -44,12 +44,12 @@ headline is the last step's.
|
|
|
44
44
|
**knowledge** — what people give an agent. Read by all, written by none.
|
|
45
45
|
|
|
46
46
|
**library** — the account's shared tools, skills, knowledge and memory.
|
|
47
|
-
Nearest wins: a
|
|
47
|
+
Nearest wins: a project shadows it by defining the same name.
|
|
48
48
|
|
|
49
49
|
**memory** — what an agent learned, one fact per file. The one place it
|
|
50
50
|
writes without a grant.
|
|
51
51
|
|
|
52
|
-
**preview** — a copy of a
|
|
52
|
+
**preview** — a copy of a project deployed from a branch, evals run,
|
|
53
53
|
schedules off, deleted with the branch.
|
|
54
54
|
|
|
55
55
|
**run** — the record of a flow being driven: every step, event and cost.
|
|
@@ -79,5 +79,5 @@ another flow, a file, a URL that changed.
|
|
|
79
79
|
**verify** — a check on a step's outcome: a shell command, or `contains:`,
|
|
80
80
|
`matches:`, `file:`, `judge:`. Where arithmetic goes.
|
|
81
81
|
|
|
82
|
-
**
|
|
82
|
+
**project** — a folder, and the unit of editing, deploying, permission,
|
|
83
83
|
budget and backup.
|
package/docs/hooks.md
CHANGED
|
@@ -20,10 +20,10 @@ hooks: [no-force-push]
|
|
|
20
20
|
```
|
|
21
21
|
|
|
22
22
|
`hooks:` in an agent's frontmatter turns hooks on for that agent. The same
|
|
23
|
-
key in a
|
|
24
|
-
the account's `AGENTS.md` for every agent in every
|
|
25
|
-
that order (account,
|
|
26
|
-
in the
|
|
23
|
+
key in a project's `AGENTS.md` turns them on for every agent in it, and in
|
|
24
|
+
the account's `AGENTS.md` for every agent in every project. They run in
|
|
25
|
+
that order (account, project, agent), each name once. A name is looked up
|
|
26
|
+
in the project's `hooks/` first, then the library's. A name that resolves
|
|
27
27
|
to nothing is a `foldrun check` error, and a step that names one is refused
|
|
28
28
|
rather than run without its hooks.
|
|
29
29
|
|
|
@@ -115,7 +115,7 @@ a `tool.call` hook uses a provider's own search.
|
|
|
115
115
|
|
|
116
116
|
Every refusal, rewrite, added context and failure is a line on the step's
|
|
117
117
|
trail (`hook no-force-push denied Bash: force push — use --force-with-lease`)
|
|
118
|
-
and a badge on the run page. The
|
|
118
|
+
and a badge on the run page. The project's Hooks page lists its hooks and
|
|
119
119
|
what each one refused or rewrote lately.
|
|
120
120
|
|
|
121
121
|
## Trying one
|
package/docs/how-it-works.md
CHANGED
|
@@ -23,7 +23,7 @@ write.
|
|
|
23
23
|
|---|---|---|
|
|
24
24
|
| **knowledge/** | nobody | given to it; reading is denied to nothing, writing to everything |
|
|
25
25
|
| **memory/** | the agent | what it learned, one fact per file, indexed |
|
|
26
|
-
| **state/** | the
|
|
26
|
+
| **state/** | the project | the bookmark between runs |
|
|
27
27
|
| **storage/** | anyone | bytes, not source — PDFs, CSVs, images |
|
|
28
28
|
|
|
29
29
|
The line between the last two is worth learning early: a value **regenerated**
|
package/docs/introduction.md
CHANGED
|
@@ -35,15 +35,15 @@ The design bets on three things:
|
|
|
35
35
|
| **Your own server** | Docker and the public repositories | the whole platform on one machine of yours, for you or your organisation |
|
|
36
36
|
| **Hosted** | an account | ours: schedules, sandboxes, a vault, a team — nothing to run |
|
|
37
37
|
|
|
38
|
-
The same
|
|
39
|
-
Start locally; that is where every
|
|
38
|
+
The same project moves between them with `foldrun deploy`.
|
|
39
|
+
Start locally; that is where every project should be born. foldrun is
|
|
40
40
|
source-available under the Functional Source License: free for your own
|
|
41
41
|
use and your organisation's, not for offering it to others as a service —
|
|
42
42
|
see [Running it yourself](self-hosting).
|
|
43
43
|
|
|
44
44
|
## Where to go
|
|
45
45
|
|
|
46
|
-
- [Getting started](getting-started) — install, make a
|
|
46
|
+
- [Getting started](getting-started) — install, make a project, run it.
|
|
47
47
|
- [How it works](how-it-works) — the eight nouns and the flow grammar, in one read.
|
|
48
|
-
- [
|
|
48
|
+
- [Projects](workspaces), [Agents](agents), [Flows](flows), [Tools](tools) — the format, field by field.
|
|
49
49
|
- [Runs](runs), [Budgets and billing](budgets-and-billing), [Security](security) — what happens when it runs.
|
|
@@ -8,14 +8,14 @@ one that repeats itself.
|
|
|
8
8
|
|---|---|---|
|
|
9
9
|
| **knowledge/** | people | what you tell the agents: reference material, standards, the price list |
|
|
10
10
|
| **memory/** | the agent | what it worked out: one fact per file, indexed |
|
|
11
|
-
| **state/** | the
|
|
11
|
+
| **state/** | the project | the bookmark between runs: a cursor, an append-only history |
|
|
12
12
|
| **storage/** | anyone | bytes a person reads — see [Storage and sharing](storage-and-sharing) |
|
|
13
13
|
|
|
14
14
|
## Knowledge is given, not learned
|
|
15
15
|
|
|
16
|
-
`knowledge/` at the
|
|
16
|
+
`knowledge/` at the project is read by every agent there; `knowledge/`
|
|
17
17
|
inside an agent's folder by that agent alone; the account library's by
|
|
18
|
-
every
|
|
18
|
+
every project. Writing to any of them is denied outright — through the
|
|
19
19
|
file tools and through a script. An agent that rewrites the price list it was
|
|
20
20
|
handed has corrupted its own source of truth; what it discovers goes to
|
|
21
21
|
`memory/`.
|
|
@@ -47,7 +47,7 @@ writes it there and finds it next run — and a deploy never overwrites memory
|
|
|
47
47
|
a push does not mention, so what was learned survives the next edit to the
|
|
48
48
|
prompt.
|
|
49
49
|
|
|
50
|
-
Memory is per agent by default; the
|
|
50
|
+
Memory is per agent by default; the project's `memory/` is shared by the
|
|
51
51
|
desk, and the library's by the account.
|
|
52
52
|
|
|
53
53
|
## Finding it: search and history
|
|
@@ -55,7 +55,7 @@ desk, and the library's by the account.
|
|
|
55
55
|
Two tool groups give an agent its own past at scale:
|
|
56
56
|
|
|
57
57
|
- **`tools: [search]`** — `search_files(query)`: ranked full-text search over
|
|
58
|
-
knowledge, memory, state and storage, at the agent's, the
|
|
58
|
+
knowledge, memory, state and storage, at the agent's, the project's and
|
|
59
59
|
the library's scope. Lexical (BM25), not embeddings — nothing leaves the
|
|
60
60
|
box, and the queries an agent makes are rare exact tokens where that
|
|
61
61
|
wins. Behind it is an inverted index built inside the step on the first
|
|
@@ -64,7 +64,7 @@ Two tool groups give an agent its own past at scale:
|
|
|
64
64
|
re-read, and nothing is persisted, so the index can never be stale across
|
|
65
65
|
a deploy or a hand edit. Search first, then read the hit.
|
|
66
66
|
- **`tools: [history]`** — `recall_runs()` and `read_run(id)`: what this
|
|
67
|
-
|
|
67
|
+
project's earlier runs concluded and what their steps said. A reporter
|
|
68
68
|
that wants "what did last week's run find" asks, rather than being handed
|
|
69
69
|
every prior run.
|
|
70
70
|
|