foldrun 16.0.0 → 16.0.2
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/api.md +1 -1
- package/docs/cli.md +1 -1
- package/docs/runs.md +8 -2
- package/package.json +2 -2
- package/src/commands.mjs +24 -3
package/docs/api.md
CHANGED
|
@@ -243,7 +243,7 @@ paying for the steps around it.
|
|
|
243
243
|
| `/api/workspaces/<ws>/notify/deliveries` | GET | the outbound webhook log: every `notify:` url delivery from this workspace, newest first — `{ deliveries, total, limit, offset, endpoint }`. A delivery is `{ id, event, status, destination, attempts, attemptLog, lastStatusCode, lastError, nextAttemptAt, createdAt, updatedAt, body }`: `id` is the `X-Foldrun-Delivery` header; `status` is `pending` (a retry is due at `nextAttemptAt`), `delivered`, `failed` (gave up after six attempts) or `skipped` (the endpoint was switched off); each attempt is `{ n, at, statusCode, durationMs, response (first 500 characters), error, manual? }`. `body` is what was sent, except that a gate's `approveUrl`/`rejectUrl` (top level and in `links`) read `[redacted]` — they decide without a login, and this log is readable by every role; the receiver still gets them, on a redelivery too. `?status=`, `?event=`, `?limit=` (50, at most 200), `?offset=`. `endpoint` is `{ failingSince, lastSuccessAt, lastFailureAt, disabledAt, disabledReason }` or null. Kept 30 days |
|
|
244
244
|
| `/api/workspaces/<ws>/notify/deliveries/<id>/redeliver` | POST | send one delivery again now — the same id and body, signed afresh, to the URL `notify:` names today. `{ ok, attempt, delivery }`, always `200` when the delivery exists (whether the receiver took it is the answer); `404` when it does not. An accepted redelivery switches a disabled endpoint back on. Needs the permission that runs |
|
|
245
245
|
| `/api/workspaces/<ws>/notify/test` | POST | sends one real notification to whatever this workspace's `notify:` resolves to, and answers `{ ok, destination, detail }` — including the provider's own words when it failed, which are what name the problem. Always `200`: the request was handled, and the result is the answer — except past 10 test sends an hour for one workspace, a `429` with `Retry-After`. Needs the permission that runs, because it sends real mail |
|
|
246
|
-
| `/api/workspaces/<ws>/observe?days=` | GET | the observability report the Observe page renders — `tally` (the shared outcome counts) and `chargedUsd` beside `costUsd` on the report, each flow, day and agent (what was charged, the ledger's line or list price until settled, versus the provider's token cost); per-agent failures, retries, tokens, `cacheHitRate`, `turns` and `systemPromptChars` (each `{ n, p50, p95, max }`), per-tool calls/errors/latency and `resultSize` (characters per result, same shape), `resultChars` (their sum) and `heavyCalls` (results over 10,000 characters), per-flow duration, day series, recent failures, and `startup` — one row per start-up phase in order, `{ phase, took, at }`, each `{ n, p50, p95, max }` in seconds (`took` is the phase's own share, `at` when it ended counted from the step's start; percentiles need five samples). `days` 1–365, default 30 (`since=`, its older name, still works — deprecated) |
|
|
246
|
+
| `/api/workspaces/<ws>/observe?days=` | GET | the observability report the Observe page renders — `tally` (the shared outcome counts) and `chargedUsd` beside `costUsd` on the report, each flow, day and agent (what was charged, the ledger's line or list price until settled, versus the provider's token cost); per-agent failures, retries, tokens, `cacheHitRate`, `turns` and `systemPromptChars` (each `{ n, p50, p95, max }`), per-tool calls/errors/latency and `resultSize` (characters per result, same shape), `resultChars` (their sum) and `heavyCalls` (results over 10,000 characters), per-flow duration, day series, recent failures, and `startup` — one row per start-up phase in order, `{ phase, took, from, at, parallel, waited }`, the four spreads each `{ n, p50, p95, max }` in seconds (`took` is the phase's own share, from when it could begin to when it ended; `from` when it began and `at` when it ended, counted from the step's start; percentiles need five samples). The search and browser pods boot beside the step pod, so on a cold run `services` ends after `ready` and `files`: it is then a parallel lane from 0 — `parallel` counts the steps where it was — the step pod's phases keep their own shares, and `go` starts once services is up, `waited` being how long it was held (0 on every other phase). `days` 1–365, default 30 (`since=`, its older name, still works — deprecated) |
|
|
247
247
|
| `/api/workspaces/<ws>/history?path=&id=&limit=` | GET | every change to the workspace, newest first — `path` narrows to one file, `id` returns one revision with its before/after and a line diff, `limit` 1–500, default 100. A deploy's revision id is its commit |
|
|
248
248
|
| `/api/workspaces/<ws>/restore` | POST | put the workspace's source back as it was at a point in its history. `to`: a revision id (`r-…`), the commit a deploy named (or its prefix), an ISO date/time (the last revision at or before it) or an age (`90m`, `12h`, `3d`, `2w`) — every revision since 17 Oct 2026 holds a snapshot of the whole source. `{ to, dryRun: true }` answers `{ to: { id, sha, at, by, message }, from, added, updated, removed, files: [{ path, change, diff }], blockedBy, noop, issues, warnings }` and writes nothing; `issues` are the deploy checks that would refuse that tree, `warnings` the ones it would deploy with. The restore needs `confirm` set to the workspace's name (400 without) and takes the dry run's `expectRemoved`; it deploys that revision's snapshot as a new revision (undo: restore to `from`; `to.sha` is the same id as `to.id`, kept from when revisions were git commits), keeps runs, `state/`, storage, secrets and agent-written memory, and is refused 409 while runs are in flight or when it would remove something not in `expectRemoved`. `workspace:write`, and `workspace:manage` when the restored `AGENTS.md` has different policy keys (`403` naming them; a dry run is not refused); audited as `workspace.restored` |
|
|
249
249
|
|
package/docs/cli.md
CHANGED
|
@@ -172,7 +172,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
172
172
|
| `foldrun schedule tick` | Settings' **Run scheduler now**: fire whatever is due this minute and print which flows went (`POST /api/schedule`). They were due anyway; this only makes them go now |
|
|
173
173
|
| `foldrun rerun <run-id>` | the same flow again, from a step: `--from <n>` as the flow file numbers them, or `--agent <name>` for the first step that agent runs. `--instruction "…"` tells that step something else this once, without changing the flow file. Earlier steps are recorded as skipped. This is the debug loop from the terminal: fix the file, `deploy`, `rerun --from` the step that failed. `--wait` follows the new run like `invoke --wait`; `--to <workspace>` from anywhere. With no run id and a filter (`--status failed`, `--since 24h`, `--until 2h`, `--flow <name>`) it reruns every match from `--from <n>` (default 1), listing and asking first as a bulk `stop` does; `--dry-run` lists only. Several run ids (`rerun <id> <id>…`) rerun those, from `--from <n>` (default 1) — `--agent` and `--instruction` are for one run |
|
|
174
174
|
| `foldrun triggers` | why nothing ran. One row per flow that fired in the window: its trigger, how many fires became runs, when it last ran, and every reason for the difference with a count — a duplicate delivery, a throttled or debounced burst, a fire the platform slept through, an `overlap: skip`, a flow switched off by `disable_after:`. Below it, as the Triggers page: every decision, newest first (when, flow, the outcome in words with the key that decided it, the detail), and the deliveries at the hook and inbox URLs — whether a request arrived and was authentic before any flow rule had a say, with how many were refused, so a bad token shows even when nothing fired. `--limit <n>` of each (default 10). A switched-off flow is a non-zero exit; one successful run clears it. `--since <days>` (default 7), `--to <workspace>`, `--json` for the whole document (`flows`, `events`, `deliveries`) |
|
|
175
|
-
| `foldrun observe` | where the account fails, retries and spends: one row per workspace — runs, failed and what share, steps, cost, and its completion rate against the window before — then the account Observe page's analysis (`GET /api/observe`): the completion rate and what was charged against the window of the same length before, **why runs went wrong** (the platform's causes first, each with its desks and what the newest said), the **agents to watch** (those that failed or retried) and the **tools to watch** (those that errored), then the recent failures in their own words. 7 days unasked, as the page (until 5 Nov 2026 it was 30). `--to <workspace>` prints that workspace in full, as its Observe page does, over 30 days unasked: per flow (runs, failed, p50/p95 duration, cost), per agent (failed, retried, skipped, p95, turns, cache hit rate), per tool (calls, errors, p95 latency, result size p50/p95 and how many results were over 10k characters, which agents use it), and start-up — each phase of a step's first seconds, its own share and when it was done, p50/p95. `--since <days>` (or `--days`) picks any window; `--json` for the document — `{ days, account, workspaces }` account-wide (`account` the analysis, `null` from a platform without it), one workspace's report with `--to` |
|
|
175
|
+
| `foldrun observe` | where the account fails, retries and spends: one row per workspace — runs, failed and what share, steps, cost, and its completion rate against the window before — then the account Observe page's analysis (`GET /api/observe`): the completion rate and what was charged against the window of the same length before, **why runs went wrong** (the platform's causes first, each with its desks and what the newest said), the **agents to watch** (those that failed or retried) and the **tools to watch** (those that errored), then the recent failures in their own words. 7 days unasked, as the page (until 5 Nov 2026 it was 30). `--to <workspace>` prints that workspace in full, as its Observe page does, over 30 days unasked: per flow (runs, failed, p50/p95 duration, cost), per agent (failed, retried, skipped, p95, turns, cache hit rate), per tool (calls, errors, p95 latency, result size p50/p95 and how many results were over 10k characters, which agents use it), and start-up — each phase of a step's first seconds, its own share, when it began and when it was done, p50/p95; `services` says **in parallel** where the search and browser pods booted beside the step pod, and `go` how long it was **held** for them. `--since <days>` (or `--days`) picks any window; `--json` for the document — `{ days, account, workspaces }` account-wide (`account` the analysis, `null` from a platform without it), one workspace's report with `--to` |
|
|
176
176
|
| `foldrun usage` | what the account consumed — runs, steps, tokens (with the share the prompt cache served), compute, storage, per workspace — and what it was charged over `--days <n>` (default 56) from the ledger, per workspace with the change against the period before. `--json` for both documents |
|
|
177
177
|
| `foldrun usage --limit <n>` | the Usage page's **by flow** and **by agent** tables in the text output: what each flow and each agent was charged over the window, its runs and the change against the period before, most charged first — the first `n` of each (default 10; `0` hides them). `--json` has them all, in `history.byFlow` and `history.byAgent` |
|
|
178
178
|
| `foldrun usage compute` | the cores, GiB and disk the account's running steps may hold together and in one step, at every level — the account, each workspace with a pool or anything held, each live run with its flow's pool — what each holds now, and the steps **waiting for room**, oldest first, each with its flow, agent, what it needs, how long it has waited, why and which level holds it (`GET /api/usage/compute`). A waiting step has no time limit and starts in turn; `--json` for the document. Set the levels with `foldrun account set compute …`, `foldrun workspace set compute … --to <ws>` and `foldrun flow compute <flow> …` |
|
package/docs/runs.md
CHANGED
|
@@ -19,7 +19,7 @@ Each run holds its steps in group order. A step carries:
|
|
|
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
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 |
|
|
21
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` |
|
|
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
|
+
| `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). `services` can end after `ready` and `files`: the search and browser pods boot beside the step pod, and `go` waits for them. Only the phases the step went through; `null` for a step that ran in-process, absent before 17 Oct 2026. The last attempt's |
|
|
23
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)) |
|
|
24
24
|
| `browserPod` | on a step that browsed through the pod from slim: `reconnects` (tries), `reconnected` (how many got through: the call went on after it) and `closedAgain` (how many reached the pod only for the call to drop again at once, when any did); when the pod was lost, `lost` (`cause` `lost` or `needs-full`, and `detail`) and `writes` (what the step had written by then, worded); then `fallback: "browser pod lost; re-ran on full"` when it had only read and ran again on the full image, or `failure` — `browser pod died after the step had written <what>` — when it had written and was not re-run |
|
|
25
25
|
| `tries` | one row per attempt, oldest first (and a `status: "lost"` row, `image: "slim"`, before the full re-run when the browser pod was lost under a slim step that had only read — see [tools](tools#slim-steps-and-a-lost-pod)): `n` (the try, numbered in the order they ran), `attempt` (the step's attempt it belongs to, only when that is not `n` — the full re-run after a lost slim try 1 is `n: 2, attempt: 1`), `status`, `costUsd`, `tokens`, `turns`, `computeSecs`, `startedAt`, `finishedAt`, the attempt's `image` and its `browserPod` line when it had one, and the attempt's last `error` when it failed. A `retry: 2` step that failed twice and then passed has three rows, and its `costUsd` is all three — the run's spend, the flow's `budget:` and the bill read the step's figure, so the figure is the total. A retry is handed what is left of the budget after the failed attempt spent, and nothing left means no retry, said on the record |
|
|
@@ -51,7 +51,13 @@ says which step was slow. Every step shows its instruction, what it was
|
|
|
51
51
|
handed from earlier groups, what it returned, its cost, and how many times it
|
|
52
52
|
reached for a path it was not allowed and was refused (see [Security](security)).
|
|
53
53
|
A **start-up** chip in a step's header says how long it took the step to
|
|
54
|
-
reach the model's first word; hover it for each phase's share.
|
|
54
|
+
reach the model's first word; hover it for each phase's share. When the
|
|
55
|
+
account's search or browser pod was still booting as the step pod came up,
|
|
56
|
+
`services` reads as its own lane (`services 8.00s alongside the pod`), the
|
|
57
|
+
pod's phases keep their own shares, and `go` says how long it was held for
|
|
58
|
+
the services (`go +0.10s (held 4.00s for services)`). The workspace's
|
|
59
|
+
**Observe** page and `foldrun observe --to` roll the same breakdown up over
|
|
60
|
+
every step.
|
|
55
61
|
|
|
56
62
|
The page follows the run as it moves, gates included, without a reload: a
|
|
57
63
|
**live** dot beside the status says the stream is connected (amber while it
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "foldrun",
|
|
3
|
-
"version": "16.0.
|
|
3
|
+
"version": "16.0.2",
|
|
4
4
|
"description": "Agents are just folders. Write them, check them, run them — on your machine.",
|
|
5
5
|
"license": "FSL-1.1-ALv2",
|
|
6
6
|
"type": "module",
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
"node": ">=22"
|
|
12
12
|
},
|
|
13
13
|
"dependencies": {
|
|
14
|
-
"@foldrun/core": "^14.
|
|
14
|
+
"@foldrun/core": "^14.4.0"
|
|
15
15
|
},
|
|
16
16
|
"files": [
|
|
17
17
|
"bin",
|
package/src/commands.mjs
CHANGED
|
@@ -11059,6 +11059,25 @@ const spreadOf = (s, unit) => {
|
|
|
11059
11059
|
return `${unit(s.p50)}/${unit(s.p95)}`;
|
|
11060
11060
|
};
|
|
11061
11061
|
|
|
11062
|
+
/**
|
|
11063
|
+
* The start-up table's rows (FOL-29): each phase's own share, when it began
|
|
11064
|
+
* and when it was done, counted from the step's start. The platform places
|
|
11065
|
+
* the phases on their lanes (FOL-74, core startup.ts#startupBreakdown): a
|
|
11066
|
+
* services phase that booted beside the step pod says "in parallel", and go
|
|
11067
|
+
* how long it was held for it. A platform from before FOL-74 sends no
|
|
11068
|
+
* `from`, `parallel` or `waited`: "—" and no note.
|
|
11069
|
+
*/
|
|
11070
|
+
export function startupRows(startup) {
|
|
11071
|
+
return (startup ?? []).map((p) => {
|
|
11072
|
+
const n = p.took?.n ?? 0;
|
|
11073
|
+
const note = [
|
|
11074
|
+
p.parallel > 0 ? `in parallel${p.parallel < n ? ` on ${p.parallel} of ${n}` : ""}` : null,
|
|
11075
|
+
p.waited?.max > 0 ? `held ${spreadOf(p.waited, fine)} for services` : null,
|
|
11076
|
+
].filter(Boolean).join(" · ");
|
|
11077
|
+
return [p.phase, n, fine(p.took?.p50), fine(p.took?.p95), fine(p.from?.p50), fine(p.at?.p50), fine(p.at?.p95), note];
|
|
11078
|
+
});
|
|
11079
|
+
}
|
|
11080
|
+
|
|
11062
11081
|
/** One workspace's observability report, as the Observe page reads it. */
|
|
11063
11082
|
function printObservation(o) {
|
|
11064
11083
|
console.log(`\n ${c.bold(o.workspace)} ${c.dim(`last ${o.sinceDays} days`)}`);
|
|
@@ -11073,9 +11092,11 @@ function printObservation(o) {
|
|
|
11073
11092
|
table("flows", ["flow", "runs", "failed", "p50", "p95", "cost"], (o.flows ?? []).map((f) => [f.flow, f.runs, f.failed, secs(f.seconds?.p50), secs(f.seconds?.p95), `$${f.costUsd.toFixed(2)}`]));
|
|
11074
11093
|
table("agents", ["agent", "steps", "failed", "retried", "skipped", "p95", "turns", "cached", "cost"], (o.agents ?? []).map((a) => [a.agent, a.steps, a.failed, a.retried, a.skipped, secs(a.seconds?.p95), spreadOf(a.turns, String), a.cacheHitRate == null ? "—" : `${Math.round(a.cacheHitRate * 100)}%`, `$${a.costUsd.toFixed(2)}`]));
|
|
11075
11094
|
table("tools", ["tool", "calls", "errors", "p95", "result size", "heavy", "used by"], (o.tools ?? []).map((t) => [t.name, t.calls, t.errors, t.ms?.p95 == null ? "—" : `${Math.round(t.ms.p95)}ms`, spreadOf(t.resultSize, kchars), t.heavyCalls || "—", (t.agents ?? []).join(", ")]));
|
|
11076
|
-
// Where a step's first seconds go, phase by phase
|
|
11077
|
-
//
|
|
11078
|
-
|
|
11095
|
+
// Where a step's first seconds go, phase by phase — startupRows. The note
|
|
11096
|
+
// column only when a phase has one.
|
|
11097
|
+
const up = startupRows(o.startup);
|
|
11098
|
+
const noted = up.some((r) => r[7]);
|
|
11099
|
+
table("start-up", ["start-up", "n", "took p50", "p95", "from p50", "done by p50", "p95", ...(noted ? [""] : [])], noted ? up : up.map((r) => r.slice(0, 7)));
|
|
11079
11100
|
const fails = (o.failures ?? []).slice(0, 8);
|
|
11080
11101
|
if (fails.length) {
|
|
11081
11102
|
console.log(`\n ${c.dim("recent failures")}`);
|