foldrun 2.2.0 → 2.4.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/bin/foldrun.mjs +31 -11
- package/docs/agents.md +76 -2
- package/docs/api.md +23 -13
- package/docs/assistant.md +32 -2
- package/docs/budgets-and-billing.md +47 -6
- package/docs/checks.md +118 -4
- package/docs/cli.md +20 -11
- package/docs/evals.md +11 -6
- package/docs/flows.md +16 -2
- package/docs/four-jobs.md +95 -0
- package/docs/network.md +22 -7
- package/docs/notifications.md +59 -0
- package/docs/runs.md +196 -4
- package/docs/security.md +3 -2
- package/docs/tools.md +3 -1
- package/docs/workspaces.md +47 -0
- package/package.json +3 -3
- package/src/commands.mjs +758 -28
- package/src/guide.mjs +1 -1
package/docs/runs.md
CHANGED
|
@@ -17,6 +17,7 @@ Each run holds its steps in group order. A step carries:
|
|
|
17
17
|
| `data` | the parsed value, for a step with `output: json` |
|
|
18
18
|
| `events` | tool calls, script runs with their timing, verify verdicts, refusals. A tool call is a pair of events, the call and its completion; the completion carries `ms` and, from 18 Oct 2026, `bytes` — the result's length in characters, which every later turn sends again |
|
|
19
19
|
| `turns`, `systemPromptChars`, `stopReason` | model turns, summed across attempts; the system prompt's length in characters (it rides on every turn); why the last turn ended. With the events' `bytes`, these say where a step's input tokens went. From 18 Oct 2026 |
|
|
20
|
+
| `promptLayers` | the system prompt's layers, stable ones first: `name` (`persona`, `agents.md`, `skills`, `knowledge`, `rules`, … then `memory`, `state`, `clock`), `chars`, `hash` (12 hex characters of its SHA-256) and `stable: false` on the ones that change between runs. Two steps of one agent compared layer by layer say why the [prompt cache](budgets-and-billing#prompt-caching) missed; the run page and `foldrun report` do the comparison. From 20 Oct 2026 |
|
|
20
21
|
| `costUsd`, `tokens`, `computeSecs`, `startupSecs` | what it cost and how long the sandbox lived — **summed across its attempts**. `tokens` is `{ input, output, cacheRead, cacheWrite }`: `input` is all input, and `cacheRead` and `cacheWrite` the part of it the [prompt cache](budgets-and-billing#prompt-caching) served and stored. Steps recorded before 18 Oct 2026 have only `input` and `output` |
|
|
21
22
|
| `startup` | where the step's first seconds went: when each start-up phase ended, in seconds since the step started — `services` (the account's search/browser pods up), `room` (room on the cluster to start — see [Budgets and billing](budgets-and-billing)), `applied` (sandbox created), `ready`, `files` (workspace copied in), `go` (step released), `shim`, `system` (system packages restored), `driver`, `imports`, `tools` (runtime and tools built) and `model` (the model's first text or tool call). Only the phases the step went through; `null` for a step that ran in-process, absent before 17 Oct 2026. The last attempt's |
|
|
22
23
|
| `image` | which runner image the step's sandbox ran (isolated runs on a cluster): `variant` `full` or `slim`, `why`, and `pod: true` when a browsing step ran slim and browsed through the account's browser pod ([slim steps and a lost pod](tools#slim-steps-and-a-lost-pod)) |
|
|
@@ -72,10 +73,194 @@ step that drove a browser shows it live, then plays its recordings — see
|
|
|
72
73
|
|
|
73
74
|
The account's home opens on **mission control**: what is **running now**
|
|
74
75
|
(each run's step and agent, and anything running over an hour flagged), what
|
|
75
|
-
**needs attention** (
|
|
76
|
-
|
|
77
|
-
desk's **last 24 runs** as a strip of cells beside
|
|
78
|
-
|
|
76
|
+
**needs attention** (every open [issue](#issues), anything waiting for an
|
|
77
|
+
approval or an answer, and anything stuck), and every
|
|
78
|
+
desk's **last 24 runs** as a strip of cells beside how many of them
|
|
79
|
+
completed and what went wrong (`20/22 · 2 failed`), runs today and the
|
|
80
|
+
credits charged this week. Every row and every cell opens its run.
|
|
81
|
+
|
|
82
|
+
Money on the overviews — Home, the desks list, a workspace's flows and
|
|
83
|
+
agents, Observe, the runs list and a run's own page — is **credits charged**:
|
|
84
|
+
the ledger's line for the run, one credit to a cent. A run the ledger has not
|
|
85
|
+
settled yet shows its list price, marked estimated (`~` in the runs list,
|
|
86
|
+
"est. charge" on its page). The provider's token cost is not the bill; it is
|
|
87
|
+
on a run's page under the figure, and in Usage.
|
|
88
|
+
|
|
89
|
+
Every page counts runs the same way. **Completed** is a run that ran to the
|
|
90
|
+
end without failing, whatever it found; the rate is completed out of
|
|
91
|
+
completed plus failed, and a run a person stopped is left out. What the
|
|
92
|
+
completed runs found is counted beside it: **blocked** (BLOCKED), **problem
|
|
93
|
+
found** (BAD), and **nothing to do** (QUIET).
|
|
94
|
+
|
|
95
|
+
## What a run records
|
|
96
|
+
|
|
97
|
+
Every step keeps, beside its events:
|
|
98
|
+
|
|
99
|
+
- **each model call**: when it came back, how long until its response
|
|
100
|
+
began arriving (from the request going out), the model, why it
|
|
101
|
+
stopped (`tool_use`, `end_turn`, `max_tokens` …), its tokens with how many
|
|
102
|
+
the cache served, and how many tools it called. A step's **model calls** row
|
|
103
|
+
on the run page lists them; `foldrun report <run-id> --calls` prints them.
|
|
104
|
+
- **each tool call's input and output** — what the agent gave the tool and
|
|
105
|
+
what came back. Open **input / output** on a tool line in the trace, or
|
|
106
|
+
`foldrun report <run-id> call <call-id>`. Each part is kept up to 65,536
|
|
107
|
+
characters (the length of the whole is shown when it was cut), and a step
|
|
108
|
+
keeps at most about 4 million characters in all — past that its calls keep
|
|
109
|
+
only their names, sizes and times, and the trace says so. Secrets are
|
|
110
|
+
masked before anything is written, then the text is cut: the step's own
|
|
111
|
+
secrets by value (`[redacted:NAME]`) — a file secret such as a key by its
|
|
112
|
+
content, line by line — then anything shaped like a key, and any private
|
|
113
|
+
key block. The input is what the agent asked for; a [hook](hooks) that
|
|
114
|
+
rewrote it before it ran is in the trace beside it. The content is kept
|
|
115
|
+
beside the run, not in it, counts toward the workspace's storage, and goes
|
|
116
|
+
when the run is deleted or ages out.
|
|
117
|
+
|
|
118
|
+
And the run itself says **which files it ran** — the workspace's latest
|
|
119
|
+
revision when a worker first picked it up ("ran on abc1234"; a deploy's is
|
|
120
|
+
its commit) — and **how long it queued** before that. A step that runs after
|
|
121
|
+
an approval, or after a deploy mid-run, may run newer files than that.
|
|
122
|
+
|
|
123
|
+
A workspace that should keep no content writes `capture: metadata` in its
|
|
124
|
+
`AGENTS.md` (or the account's): model calls, tool names, sizes and timings
|
|
125
|
+
are still recorded, inputs and outputs are not.
|
|
126
|
+
|
|
127
|
+
## The trace tree
|
|
128
|
+
|
|
129
|
+
A run's page opens with its **trace**: the run as one tree, each step, each
|
|
130
|
+
model call it made, and each tool call under the model call that asked for
|
|
131
|
+
it, every line with a bar on the run's own clock. A model call shows its
|
|
132
|
+
model, tokens (and how many the cache served) and why it stopped; a tool call
|
|
133
|
+
shows how long it took and, where it was recorded, its **input / output**.
|
|
134
|
+
Errors are lines of their own. The tree opens on the first thing that went
|
|
135
|
+
wrong — a failed tool call before the step's error line, before the failed
|
|
136
|
+
step — and highlights it; **expand all** shows every call.
|
|
137
|
+
|
|
138
|
+
`foldrun report <run-id> --tree` prints the same tree in the terminal, with
|
|
139
|
+
`← what went wrong` on that line, and `GET /api/workspaces/<ws>/runs/<id>/trace`
|
|
140
|
+
answers it as JSON. Runs from before 19 Oct 2026 have no model calls on
|
|
141
|
+
record; their tool calls sit under the step.
|
|
142
|
+
|
|
143
|
+
### Sending the trace to your own tracing
|
|
144
|
+
|
|
145
|
+
The same tree can go to the OpenTelemetry collector you already run —
|
|
146
|
+
Grafana Tempo, Honeycomb, Datadog, Jaeger, Langfuse, anything that takes
|
|
147
|
+
OTLP — so agent runs sit beside the services they act on:
|
|
148
|
+
|
|
149
|
+
```yaml
|
|
150
|
+
telemetry:
|
|
151
|
+
otlp: https://otel.example.com/v1/traces # the collector's OTLP/HTTP traces URL
|
|
152
|
+
headers:
|
|
153
|
+
authorization: ${OTEL_TOKEN} # a vault secret, by name
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
In the account's `AGENTS.md` (Settings → Observability → *Send runs to your
|
|
157
|
+
tracing*, or `foldrun account telemetry set <url> --header
|
|
158
|
+
authorization='${OTEL_TOKEN}'`), or a workspace's, which replaces the
|
|
159
|
+
account's whole. Every run that finishes is sent as one trace: a span for
|
|
160
|
+
the run, each step (with `foldrun.agent` and `foldrun.owner`), each model
|
|
161
|
+
call (`gen_ai.request.model`, token counts, finish reason) and each tool call
|
|
162
|
+
(`gen_ai.tool.name`), failures as error spans. Resource attributes name the
|
|
163
|
+
account, workspace, flow and run. Ids come from the run's, so a run sent
|
|
164
|
+
twice is one trace. Test runs are not sent.
|
|
165
|
+
|
|
166
|
+
*Send a test trace* (`foldrun account telemetry test`) sends one made-up run
|
|
167
|
+
and says what the collector answered. A header whose secret is not in the
|
|
168
|
+
vault stops the send and says which; a token written into the file is
|
|
169
|
+
refused by `foldrun check` and the deploy. The collector is reached like a
|
|
170
|
+
`notify:` webhook — never a private address — and a slow or failing one
|
|
171
|
+
never holds a run up: a failed send is logged on the platform, not retried.
|
|
172
|
+
|
|
173
|
+
## Searching runs
|
|
174
|
+
|
|
175
|
+
The runs pages search by what happened inside a run, not only its status:
|
|
176
|
+
**tool** (a step called a tool whose name contains it — `web`, `crm`), **a
|
|
177
|
+
tool errored**, **agent**, **model** (contains — `haiku`), **≥ tokens** (input
|
|
178
|
+
read by all its steps, `50k`) and **≥ secs**. A search can be kept as a named
|
|
179
|
+
**view** (save view), yours on every browser; the views sit beside the search.
|
|
180
|
+
`foldrun runs --tool web --tool-error`, `--agent`, `--model`, `--min-tokens`,
|
|
181
|
+
`--min-secs` and `--view <name>` do the same (`foldrun runs views` lists
|
|
182
|
+
yours), and `GET …/runs` takes `tool`, `tool_error`, `agent`, `model`,
|
|
183
|
+
`min_tokens`, `min_secs`. Tools and models are searchable on runs from
|
|
184
|
+
19 Oct 2026; tokens and time on every run.
|
|
185
|
+
|
|
186
|
+
## Insights
|
|
187
|
+
|
|
188
|
+
The account's **Observe** page opens with **Insights**: the problems that keep
|
|
189
|
+
costing without failing anything, found in the last week of runs with nothing
|
|
190
|
+
to set up. Each says what it is, why it happens, what to do, about how many
|
|
191
|
+
credits it cost, and links the runs it was seen in:
|
|
192
|
+
|
|
193
|
+
- **mostly uncached** — an agent sends a big prompt the model's cache rarely
|
|
194
|
+
serves, step after step (something near its start changes every call);
|
|
195
|
+
- **a big tool result sent again** — a tool hands back more than 20,000
|
|
196
|
+
characters and every later model call in the step pays for it again;
|
|
197
|
+
- **a retry loop** — a tool errors three or more times in one step and the
|
|
198
|
+
agent keeps trying;
|
|
199
|
+
- **near its timeout** — steps that use 80% or more of their `timeout:`.
|
|
200
|
+
|
|
201
|
+
`foldrun insights` prints them; `GET /api/insights` answers them.
|
|
202
|
+
|
|
203
|
+
## Compare with the last good run
|
|
204
|
+
|
|
205
|
+
On a finished run, **compare with the last good run** lays it beside the
|
|
206
|
+
newest earlier run of the same flow that finished well (or, failing that, the
|
|
207
|
+
run it re-ran). It says whether the two ran the same files and which files
|
|
208
|
+
changed between them, then, step by step, what differs: status, a new error,
|
|
209
|
+
the instruction, the model, tool calls and tool errors, how long it took, the
|
|
210
|
+
tokens it read, the model calls it made, and the first line it said. Steps that
|
|
211
|
+
did not change are left out. `foldrun report <run-id> --compare [<other-run>]`
|
|
212
|
+
prints the same, and `GET …/runs/<id>/compare?with=` answers it.
|
|
213
|
+
|
|
214
|
+
## Issues
|
|
215
|
+
|
|
216
|
+
What went wrong is an **issue**, and it stays open until a person resolves
|
|
217
|
+
it. One issue is the same thing going wrong again:
|
|
218
|
+
|
|
219
|
+
- one desk's flow **failing** at the same agent;
|
|
220
|
+
- one desk's flow ending **BLOCKED**, or finding a problem (**BAD**);
|
|
221
|
+
- one desk's scheduled flow **not starting** when it was due (see below);
|
|
222
|
+
- one **platform** cause across every desk it hit — sandboxes that cannot
|
|
223
|
+
start, a model sign-in refused, the usage cap, the provider overloaded, a lost
|
|
224
|
+
worker — with what
|
|
225
|
+
to fix, none of it in the desks.
|
|
226
|
+
|
|
227
|
+
Each issue says when it was first and last seen, how many times, which runs,
|
|
228
|
+
the newest reason and what to do. A later good run does not close it: the
|
|
229
|
+
issue says "fine since …" and waits for someone to resolve it, so a failure
|
|
230
|
+
at 3am is still there at 9 whatever ran in between. **Acknowledge** says you
|
|
231
|
+
have seen it (it stays open), **Snooze** hides it for a while (it comes back
|
|
232
|
+
on its own), **Resolve** closes it, **Reopen** undoes that. Each act is kept
|
|
233
|
+
in the issue's history with who did it. The same thing going wrong after a
|
|
234
|
+
resolve opens the issue again, counting from there.
|
|
235
|
+
|
|
236
|
+
An issue that was resolved and happens again is marked **regressed**, with
|
|
237
|
+
the revision its new run ran ("regressed since abc1234"). Besides **Snooze
|
|
238
|
+
1d**, **Ignore next 5** hides it until it happens five more times — for a
|
|
239
|
+
known flake (`snooze` with `times` on the API, `--times` in the CLI).
|
|
240
|
+
|
|
241
|
+
**Doctor** on an issue opens the [run doctor](assistant#the-run-doctor) on
|
|
242
|
+
its newest run, in the workspace that run is in, wherever the card is shown
|
|
243
|
+
(Home, a workspace's home, the Issues page): the assistant says why and
|
|
244
|
+
proposes the fix as files to save. Nothing changes until you save it; then
|
|
245
|
+
resolve the issue, or rerun and let it show "fine since". A missed schedule
|
|
246
|
+
has no run, so it has no Doctor. From a terminal: `foldrun issues doctor <id>`.
|
|
247
|
+
|
|
248
|
+
A **missed schedule** is an issue too: a scheduled fire in the last week that
|
|
249
|
+
started no run — none began from two minutes before it to thirty after, and
|
|
250
|
+
none of that flow was already going. It says when it was due ("due Mon 09:00
|
|
251
|
+
(Australia/Sydney), no run started") and opens the flow. Fires from before
|
|
252
|
+
the flow file last changed are not counted.
|
|
253
|
+
|
|
254
|
+
A flow can choose to have its issues close themselves: `issues: auto-close`
|
|
255
|
+
in its frontmatter, and a run of it that goes fine resolves its open
|
|
256
|
+
failures, BLOCKED and BAD (marked "auto"); one going wrong after that opens a
|
|
257
|
+
new episode. Unset (`stay-open`) a person resolves them. Platform causes and
|
|
258
|
+
missed schedules never close on their own.
|
|
259
|
+
|
|
260
|
+
The **Issues** page lists them (Open, Snoozed, Resolved, All; a workspace's
|
|
261
|
+
own from its home), Home lists the open ones under Needs attention, and
|
|
262
|
+
`foldrun issues` and `GET /api/issues` are the same list. A platform issue
|
|
263
|
+
belongs to the account: closing it needs access to every workspace.
|
|
79
264
|
|
|
80
265
|
Each agent also has an **Activity** page: every step it has ever run, across
|
|
81
266
|
flows and direct runs, with that step's own headline. It is where "how has
|
|
@@ -156,6 +341,13 @@ tests, so "what does a test run refuse" is a file and not a search.
|
|
|
156
341
|
**Stop** ends the run and destroys its sandbox, not just the record. A
|
|
157
342
|
stopped run is recorded as stopped; it never quietly completes.
|
|
158
343
|
|
|
344
|
+
**Re-run with an edit.** On a finished run, a step's **edit & re-run** opens
|
|
345
|
+
its instruction: change it and re-run from that step, with the earlier steps
|
|
346
|
+
carried as context. The new instruction is for that one run — the flow file is
|
|
347
|
+
not changed — so you can try a fix on the real input before writing it in.
|
|
348
|
+
The new run says where it came from (`rerunOf`). From the terminal:
|
|
349
|
+
`foldrun rerun <run-id> --from <n> --instruction "…"`.
|
|
350
|
+
|
|
159
351
|
**Stop and re-run in bulk.** `POST /api/workspaces/<ws>/runs/bulk` applies
|
|
160
352
|
one of those two actions to every run a small filter names — statuses, a
|
|
161
353
|
flow, a time window, or an explicit list of ids. It is the tool for the
|
package/docs/security.md
CHANGED
|
@@ -24,8 +24,9 @@ in, and — for an agent whose [network](network) is `open` — the public
|
|
|
24
24
|
internet and its own account's search and browser pods; nothing else. An
|
|
25
25
|
agent that is `trusted` or `none` (the default for one that does not read
|
|
26
26
|
the web) reaches the internet only through the egress proxy, which holds
|
|
27
|
-
its list of sites per connection;
|
|
28
|
-
(`
|
|
27
|
+
its list of sites per connection; where it is enforced
|
|
28
|
+
(`network_enforce: true` in the account's or workspace's `AGENTS.md`, or
|
|
29
|
+
`FOLDRUN_NETWORK_ENFORCE=1` on the install) its pod has no other route, and no way to the
|
|
29
30
|
account's browser or search pods. The policy denies every private range (RFC1918) and the
|
|
30
31
|
cloud metadata endpoint — the address that, on a cloud host, hands out the
|
|
31
32
|
machine's own credentials. It cannot reach the platform's API, its
|
package/docs/tools.md
CHANGED
|
@@ -99,7 +99,7 @@ runtime:
|
|
|
99
99
|
| `args` | each argument and what it means — this is what the model reads |
|
|
100
100
|
| `timeout` | seconds; without one the program runs until it finishes |
|
|
101
101
|
| `interpreter` | what runs the file — `python3`, `bash`, `node` — when the extension does not say, or says wrong. `python3` (or `python`) means the tool's own environment when it has a `runtime:`, not the image's bare python |
|
|
102
|
-
| `secrets` | the vault names the program reads, `[RESEND_API_KEY, EMAIL_FROM]` — granting the tool grants them, so the agent does not list them again; or `proxied` when the program sends through the egress proxy itself (reads `FOLDRUN_EGRESS`, sends `${NAME}`); the default, `materialised`, puts the real values in its environment |
|
|
102
|
+
| `secrets` | the vault names the program reads, `[RESEND_API_KEY, EMAIL_FROM]` — granting the tool grants them, so the agent does not list them again; or `proxied` when the program sends through the egress proxy itself (reads `FOLDRUN_EGRESS`, sends `${NAME}`); the default, `materialised`, puts the real values in its environment. 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:` |
|
|
103
103
|
| `outward` | `true` when the program makes something happen outside — sends, posts, orders. On a [test run](runs#test-runs) a step granting it is handed no real secret at all, whatever their names |
|
|
104
104
|
| `test_mode` | `allow` for a reader that happens to use a send-capable secret (a Business Profile reader on the same token the poster uses): on a test run the step still gets the real values. An `outward` tool in the same step wins. Parsed as `testMode` |
|
|
105
105
|
| `runtime` | interpreters and packages, merged into the step's environment |
|
|
@@ -1763,6 +1763,7 @@ limits:
|
|
|
1763
1763
|
web: 150 # every web action together
|
|
1764
1764
|
crm: 20 # a tool by the name it is granted as
|
|
1765
1765
|
calls: 300 # every tool call in the step, any tool
|
|
1766
|
+
repeat: 5 # the same call — one tool, the same input — at most 5 times
|
|
1766
1767
|
```
|
|
1767
1768
|
|
|
1768
1769
|
| key | counts |
|
|
@@ -1775,6 +1776,7 @@ limits:
|
|
|
1775
1776
|
| `read` · `write` · `code` | Read/Glob/Grep · Write/Edit · Bash. An exact SDK name (`Bash`) works too |
|
|
1776
1777
|
| `search` · `history` · `desks` · `ask` | the platform's own groups; a consulted colleague by its name |
|
|
1777
1778
|
| `calls` | everything — including a delegation to a sub-agent |
|
|
1779
|
+
| `repeat` | one identical call: the same tool with the same input (key order aside). A model asking the same thing again and again is stuck, and each repeat is spend; past the cap it is told so — *this exact call 5 of 5 times in this step — repeating it will not change the answer* — and can try something else. A different input is a different call |
|
|
1778
1780
|
|
|
1779
1781
|
Values are whole numbers, 1 or more; to withhold a tool, leave it out of
|
|
1780
1782
|
`tools:`. How the count works:
|
package/docs/workspaces.md
CHANGED
|
@@ -144,6 +144,7 @@ The frontmatter is the workspace's defaults:
|
|
|
144
144
|
```yaml
|
|
145
145
|
---
|
|
146
146
|
timezone: Australia/Sydney
|
|
147
|
+
owner: ops@example.com # who answers for every agent and flow here that names no owner of its own
|
|
147
148
|
budget: 60 # a cap in USD for this workspace — per month; or 60/day, 60/week; unset is no limit
|
|
148
149
|
notify:
|
|
149
150
|
email: ops@example.com
|
|
@@ -154,6 +155,28 @@ provider: # see Providers
|
|
|
154
155
|
---
|
|
155
156
|
```
|
|
156
157
|
|
|
158
|
+
`owner:` names the person accountable for the workspace's agents and flows.
|
|
159
|
+
Each agent and flow may name its own; one that does not takes the
|
|
160
|
+
workspace's, and a workspace that does not takes the account's.
|
|
161
|
+
|
|
162
|
+
`telemetry:` sends each finished run to an OpenTelemetry collector as one
|
|
163
|
+
trace; a workspace's block replaces the account's whole. See
|
|
164
|
+
[Runs](runs#sending-the-trace-to-your-own-tracing).
|
|
165
|
+
|
|
166
|
+
The frontmatter may also group these defaults by the job they do —
|
|
167
|
+
`governance:`, `guardrail:`, `observability:` and `evaluation:` (where
|
|
168
|
+
`judge:` sets the model every grader here uses). A block reads exactly as the
|
|
169
|
+
same keys at the top. See [The four jobs](four-jobs) for which key goes where.
|
|
170
|
+
|
|
171
|
+
`network_enforce: true` refuses a site off a step's [`network:`](network)
|
|
172
|
+
list instead of only naming it in the trace. The account's `true` holds for
|
|
173
|
+
every workspace; a workspace can add it for itself but not drop the
|
|
174
|
+
account's. See [Network](network#report-only-then-refuse).
|
|
175
|
+
|
|
176
|
+
`capture:` says what runs record of each tool call: `full` (the default —
|
|
177
|
+
its input and output, secrets masked) or `metadata` (its name, size and time
|
|
178
|
+
only). See [Runs](runs#what-a-run-records).
|
|
179
|
+
|
|
157
180
|
There is an `AGENTS.md` one level up too — the account's — and the two
|
|
158
181
|
compose in a way worth learning once:
|
|
159
182
|
|
|
@@ -188,6 +211,30 @@ The value is an IANA name (`Australia/Sydney`) or a plain fixed offset —
|
|
|
188
211
|
deploy both refuse anything else; a bad value that reaches a run falls through
|
|
189
212
|
to the next level with one line in the trace rather than failing the step.
|
|
190
213
|
|
|
214
|
+
## Pausing runs — the kill switch
|
|
215
|
+
|
|
216
|
+
When something is going wrong — an agent posting what it should not, a
|
|
217
|
+
loop spending money — pause the workspace, or the whole account, from its
|
|
218
|
+
Settings → Governance → Pause, `foldrun workspace pause` / `foldrun account pause`, or
|
|
219
|
+
the API (`POST /api/workspaces/<ws>/pause`, `POST /api/account/pause`).
|
|
220
|
+
|
|
221
|
+
While paused, nothing new starts: a schedule's fire, a webhook delivery, a
|
|
222
|
+
chained flow, a person's Run and a rerun are all refused, and the
|
|
223
|
+
workspace's Triggers page logs each refused fire as *paused by a
|
|
224
|
+
person*. A refused fire is not run later. A run that was queued before
|
|
225
|
+
the pause and has not begun waits until the resume. Add `--stop` (or tick
|
|
226
|
+
*Also stop the runs going now*) to stop the runs already going — and the
|
|
227
|
+
queued and parked ones — as well; without it, a run already under way
|
|
228
|
+
finishes.
|
|
229
|
+
|
|
230
|
+
The account's pause holds every workspace, and only the account's resume
|
|
231
|
+
lifts it; a workspace paused on its own stays paused when the account
|
|
232
|
+
resumes. Who paused and why is on the page, on every dashboard page while
|
|
233
|
+
the account is paused, and in the audit log (`workspace.paused`,
|
|
234
|
+
`account.resumed`, …). A scheduled fire inside a pause is not reported as a
|
|
235
|
+
missed schedule. The pause is the platform's record, not a file, so a
|
|
236
|
+
deploy never lifts it.
|
|
237
|
+
|
|
191
238
|
## The account library
|
|
192
239
|
|
|
193
240
|
`<account>/library/` holds tools, skills, knowledge and memory shared by every
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "foldrun",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.4.0",
|
|
4
4
|
"description": "Agents are just folders. Write them, check them, run them — on your machine.",
|
|
5
5
|
"license": "SEE LICENSE IN LICENSE",
|
|
6
6
|
"type": "module",
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
"node": ">=22"
|
|
12
12
|
},
|
|
13
13
|
"dependencies": {
|
|
14
|
-
"@foldrun/core": "^2.
|
|
14
|
+
"@foldrun/core": "^2.6.0"
|
|
15
15
|
},
|
|
16
16
|
"files": [
|
|
17
17
|
"bin",
|
|
@@ -21,7 +21,7 @@
|
|
|
21
21
|
],
|
|
22
22
|
"scripts": {
|
|
23
23
|
"e2e": "FOLDRUN_E2E=1 FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-e2e-XXXXXX) node --test --test-timeout=300000 tests/e2e.test.ts",
|
|
24
|
-
"test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-report-cache.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts tests/cli-check-scan.test.ts tests/cli-published.test.ts",
|
|
24
|
+
"test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-issues.test.ts tests/cli-capture.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-report-cache.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts tests/cli-check-scan.test.ts tests/cli-published.test.ts tests/cli-init-target.test.ts",
|
|
25
25
|
"release": "node scripts/release.mjs",
|
|
26
26
|
"typecheck": "tsc -p tsconfig.json",
|
|
27
27
|
"docs:sync": "node scripts/sync-docs.mjs",
|