foldrun 10.0.0 → 10.1.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 CHANGED
@@ -155,7 +155,7 @@ const HELP = `foldrun — agents are just folders
155
155
  foldrun runs what has run lately, across the account — --status, --verdict, --outcome (good, done, quiet, blocked, bad, failed, needs-you, …), --since, --to, --limit; search with --tool, --tool-error, --agent, --model, --min-tokens 50k, --min-secs, or --view <name>
156
156
  foldrun runs views your saved run searches (--local prints exactly what logs --local prints)
157
157
  foldrun runs doctor <run-id> the run doctor: the assistant reads a failed run and the files it names, says why (platform, check, work or outside) and proposes the fix as diffs, saved on yes (--to, --yes, --dry-run, --json)
158
- foldrun runs rm <run-id> delete a run's record and archived outputs; a live one is stopped first — asks first, --yes means it
158
+ foldrun runs rm <run-id> delete a run's record and archived outputs (an admin); a live one is stopped first — asks first, --yes means it
159
159
  foldrun report <run-id> one run, whole: header, every step, what it wrote and what is still waiting
160
160
  foldrun report <run-id> get <agent>/<path> download a file the run archived from that agent's outputs/ (--file <path>|-, --force)
161
161
  foldrun report <run-id> --compare [<run-id>] beside the flow's last good run (or the one named): changed files and what differs step by step (--json)
@@ -217,6 +217,7 @@ const HELP = `foldrun — agents are just folders
217
217
  foldrun backups requests every restore asked of the platform team, and where each stands (--json)
218
218
  foldrun secrets set NAME store a secret (prompted, never echoed) — also ls, rm, status; --kind file|ssh|api|service-account|m2m for the other shapes; --site <domain> (repeatable) binds it as it is stored
219
219
  foldrun secrets sites NAME [site…] bind a secret to sites: the egress proxy fills it for those alone and it never enters a sandbox; no sites lists them, --clear unbinds
220
+ foldrun secrets workspaces NAME [workspace…] limit an account secret to those workspaces — every other one finds it not set; --all opens it to every workspace again, --none to no workspace, no names shows which may use it (an admin over every workspace; applies to runs that start after it)
220
221
  foldrun secrets clients the OAuth clients saved on the platform — also add <name> (--authorize-url/--token-url, --client-id, --scopes, --authorize-param name=value), rm <name>
221
222
  foldrun connect NAME OAuth sign-in from the terminal, stored as an auto-refreshing secret — --client <saved> runs it from a saved client through the platform
222
223
  foldrun deploy [dir] push the whole account, or deploy <workspace> for one of them
@@ -339,6 +340,9 @@ Options
339
340
  --value "<text>" secrets set: skip the prompt (careful with shell history)
340
341
  --site <domain> secrets set, secrets sites: a site the secret is bound to — the egress proxy fills it for those alone (repeatable, or a,b)
341
342
  --clear secrets sites: unbind it; flow compute: no cap of its own
343
+ --all secrets workspaces: every workspace may use the account secret again
344
+ --none secrets workspaces, secrets set: no workspace may use the account secret
345
+ --workspaces <a,b> secrets set: store an account secret limited to those workspaces, in the same write (with --account)
342
346
  --add <site> agent network: add a site to its network: list (repeatable)
343
347
  --remove <site> agent network: take a site off its network: list (repeatable)
344
348
  --out <file> api spec: where to write the OpenAPI document (default: stdout); check: where to write the JSON or SARIF report
@@ -406,7 +410,7 @@ if (!command || command === "--help" || command === "-h") {
406
410
  // `--value` as the account's argument and stored an empty secret; `--force
407
411
  // ./dir` swallowed the directory. A flag followed by another flag is also
408
412
  // boolean, so an unlisted switch at least does not eat its neighbour.
409
- const BOOLEAN_FLAGS = new Set(["account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear", "security", "changed", "write-baseline", "no-baseline", "rules", "calls", "tree", "tool-error", "stop", "last", "no-pkce", "export", "isolated", "no-wait", "dismissed", "unread", "team", "started", "mine"]);
413
+ const BOOLEAN_FLAGS = new Set(["account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear", "security", "changed", "write-baseline", "no-baseline", "rules", "calls", "tree", "tool-error", "stop", "last", "no-pkce", "export", "isolated", "no-wait", "dismissed", "unread", "team", "started", "mine", "none"]);
410
414
  // Flags said more than once collect into a list: `--tag a --tag b`.
411
415
  const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove", "rule", "authorize-param"]);
412
416
  // `--wait` is a switch everywhere but `flow add <flow> wait`, where it takes
package/docs/api.md CHANGED
@@ -67,16 +67,16 @@ api workspaces/$WS/flows/publish/run -X POST # start a flow
67
67
  | Route | Methods | |
68
68
  |---|---|---|
69
69
  | `/api/workspaces` | GET, POST | list; create (`name`, plus one of: `template: true` — blank, just an AGENTS.md, what the dashboard sends; `starter: true` — the example researcher, writer and publish flow; `demo: true`; `files`). A POST to a name that exists deploys over it, through the deploy's gate — files that do not check out, or a run still reading the workspace, are `422` with `issues`/`blockedBy` and nothing changes, and it is audited as `workspace.deployed`; add `ifAbsent: true` to create only — a name that exists is then `409` and nothing changes, decided atomically (the assistant's Create workspace and `foldrun assistant` send it) |
70
- | `/api/workspaces/<ws>` | GET, PATCH, DELETE | read; rename or re-describe (`name`, `description` — written as one YAML value and recorded in History), or set its defaults (`timezone`, `budget`, `compute` — `{ vcpu, memGiB, diskGiB }`, this workspace's own pool, merged over what is set —, `notify`, `network_enforce`, `owner`, `alerts`, `judge` — null clears one, edited in AGENTS.md in place; keys only the account may set are ignored); delete — its stored files and public links go with it, as a rename moves them |
70
+ | `/api/workspaces/<ws>` | GET, PATCH, DELETE | read; rename or re-describe (`name`, `description` — written as one YAML value and recorded in History), or set its defaults (`timezone`, `budget`, `compute` — `{ vcpu, memGiB, diskGiB }`, this workspace's own pool, merged over what is set —, `notify`, `network_enforce`, `owner`, `alerts`, `judge` — null clears one, edited in AGENTS.md in place; keys only the account may set are ignored); delete — its stored files and public links go with it, as a rename moves them. An account secret limited to it ([limited to some workspaces](secrets#limited-to-some-workspaces)) follows a rename and loses it on a delete, done before the folder moves or goes: 409 naming any such secret the platform's keys cannot read (nothing renamed or deleted), 503 when the vault cannot be updated; a rename onto a name that exists is 409 |
71
71
  | `/api/workspaces/<ws>/pause` | GET, POST, DELETE | the workspace's kill switch. GET `{ paused, account, workspace }` — what holds runs here (`paused` is the one that applies, `scope` saying whose), each `{ at, by, reason? }` or null. POST `{ reason?, stop?: true }` pauses: every start here — schedule, webhook, chained flow, a person's Run, a rerun — is refused `423` with who paused it, and a refused trigger is logged as `halted`; A run queued before the pause and not yet begun waits until the resume. `stop: true` also stops every running, queued and parked run (needs `run:start`) and answers `stopped` and `failed`. DELETE resumes. Needs `workspace:manage`. The account's pause holds here too and only the account's DELETE lifts it; an operator's suspension is separate and neither lifts it |
72
- | `/api/workspaces/<ws>/vocabulary` | GET | which document kinds this workspace admits — its `docs` list is what `[[ ]]` resolves: knowledge, memory, `state/` and `storage/` files, plus the folders themselves |
73
- | `/api/workspaces/<ws>/check` | GET | what `foldrun check` says about the deployed copy, as findings with rule ids — what a deploy refuses or warns about, and the scanner's secret, hidden-text, agent-risk and supply-chain rules ([Checks](checks)). `?security=1` keeps the security rules, `?rule=<id or category>` (repeatable) one, `?online=1` adds the network checks (known vulnerabilities, remote MCP tool text); `{ counts, findings: [{ rule, level, file, line, message, fingerprint }], rules, online?: { problems, sources }, rescan: { checkedAt, findings, pending, problems } | null }`. Read-only, no model call |
72
+ | `/api/workspaces/<ws>/vocabulary` | GET | which document kinds this workspace admits — its `docs` list is what `[[ ]]` resolves: knowledge, memory, `state/` and `storage/` files, plus the folders themselves. `secrets` names the workspace's secrets and, to a caller with every workspace, the account's (as `GET /api/secrets` lists them). `404` when the workspace does not exist |
73
+ | `/api/workspaces/<ws>/check` | GET | what `foldrun check` says about the deployed copy, as findings with rule ids — what a deploy refuses or warns about, and the scanner's secret, hidden-text, agent-risk and supply-chain rules ([Checks](checks)). `?security=1` keeps the security rules, `?rule=<id or category>` (repeatable) one, `?online=1` adds the network checks (known vulnerabilities, remote MCP tool text) — editor and above, since they send the server out to OSV and the workspace's MCP servers; the answer is kept for 10 minutes while the files are unchanged, and a workspace gets six fresh online passes per 10 minutes (then `429` with `Retry-After`); `{ counts, findings: [{ rule, level, file, line, message, fingerprint }], rules, online?: { problems, sources }, rescan: { checkedAt, findings, pending, problems } | null }`. Read-only, no model call |
74
74
 
75
75
  ## Source — the files themselves
76
76
 
77
77
  | Route | Methods | |
78
78
  |---|---|---|
79
- | `/api/workspaces/<ws>/source?path=` | GET, PUT, PATCH, DELETE | GET: one file (`{ path, content, sha256 }`), or the tree with no `path`. PUT `{path, content, message?, ifMatch?, check?}` writes one file (a revision, `message` its note) and answers `{ ok, path, sha256, issues }`, the deploy's checks for that file as saved. With `check: true` (what the dashboard editor sends) a file with an error a deploy would refuse is refused with `422` and the `issues`, nothing written; warnings never refuse; with `ifMatch` — the `sha256` a GET returned — it is refused with `409` and nothing written if the file has changed since; `ifMatch: null` says the caller saw no file there, and is refused the same way once one exists (History's restore and the AI draft's save send it, the draft's new files as `null`). PATCH `{from, to}` moves one. DELETE `{path}` removes a file or folder. A write names a workspace that exists — to one that does not it is `404`, and nothing is made (make it with `POST /api/workspaces`, a deploy or an import); the same holds for every route that writes a file: agents, evals, flows, assets, settings. The body carries the path on writes — a `?path=` there is a `400` |
79
+ | `/api/workspaces/<ws>/source?path=` | GET, PUT, PATCH, DELETE | GET: one file (`{ path, content, sha256 }`), or the tree with no `path`. PUT `{path, content, message?, ifMatch?, check?}` writes one file (a revision, `message` its note) and answers `{ ok, path, sha256, issues }`, the deploy's checks for that file as saved. With `check: true` (what the dashboard editor sends) a file with an error a deploy would refuse is refused with `422` and the `issues`, nothing written; warnings never refuse; with `ifMatch` — the `sha256` a GET returned — it is refused with `409` and nothing written if the file has changed since; `ifMatch: null` says the caller saw no file there, and is refused the same way once one exists (History's restore and the AI draft's save send it, the draft's new files as `null`). PATCH `{from, to}` moves one. DELETE `{path}` removes a file or folder. A write names a workspace that exists — to one that does not it is `404`, and nothing is made (make it with `POST /api/workspaces`, a deploy or an import); the same holds for every route that writes a file: agents, evals, flows, assets, settings. The body carries the path on writes — a `?path=` there is a `400`. A change to a policy key of the workspace's `AGENTS.md` (`budget`, `compute`, `notify`, `network_enforce`, `telemetry`, `alerts`, `owner`, `judge`, `timezone`) needs `workspace:manage` — `403` naming the key, nothing written ([Team and access](team-and-access#a-workspaces-policy-is-an-admins)) |
80
80
  | | PUT | write (`path`, `content`, optional `message` — recorded on the revision, as `foldrun source put --message` sends it) |
81
81
  | | PATCH | move (`from`, `to`) |
82
82
  | | DELETE | remove (`path`) |
@@ -127,8 +127,8 @@ agent wrote that the push does not mention.
127
127
 
128
128
  | Route | Methods | |
129
129
  |---|---|---|
130
- | `/api/workspaces/<ws>/deploy` | POST | deploy the whole workspace from a list of files — checked as a whole first, refused with `422` and `issues` when it does not check out. `dryRun`, `force`, `expectRemoved` below. Idempotent |
131
- | `/api/workspaces/<ws>/runtimes` | GET | the `runtime:` builds a deploy started, each with its `state` — below |
130
+ | `/api/workspaces/<ws>/deploy` | POST | deploy the whole workspace from a list of files — checked as a whole first, refused with `422` and `issues` when it does not check out. `dryRun`, `force`, `expectRemoved` below. A change to a policy key of the workspace's `AGENTS.md` (`budget`, `compute`, `notify`, `network_enforce`, `telemetry`, `alerts`, `owner`, `judge`, `timezone`) needs `workspace:manage` — `403` naming the key, nothing written ([Team and access](team-and-access#a-workspaces-policy-is-an-admins)); a dry run is not refused. Idempotent |
131
+ | `/api/workspaces/<ws>/runtimes` | GET | the `runtime:` builds a deploy started, each with its `state` — below. `404` when the workspace does not exist |
132
132
 
133
133
  `GET /api/workspaces/<ws>/runtimes` answers what a deploy started on the
134
134
  platform: every distinct `runtime:` the workspace's agents need
@@ -143,7 +143,7 @@ installer's `error`, its cause on the first line. `foldrun deploy` polls it afte
143
143
  | Route | Methods | |
144
144
  |---|---|---|
145
145
  | `/api/workspaces/<ws>/flows` | GET, POST | list; create (`name`, `pattern`) |
146
- | `/api/workspaces/<ws>/flows/<flow>` | POST, PATCH, DELETE | edit a step (`step`, `instruction`, `options`, `target`, `subflow`), rearrange (`groups`), set `trigger`, set `compute` (`{ vcpu, memGiB, diskGiB }` or `null` — what one run may hold at once, merged over what the flow says), a canvas edit (`edit`, `edits`), undo (`restore` + `expect`); delete. Every PATCH and DELETE takes `expect` — the text the step numbers were read from, or its sha256 — and is refused with `409` and the current `text`, nothing written, when the file no longer reads it (the canvas, the list view's board and step options, and the CLI's `flow add`/`rm-step`/`dup-step --to` send it; the dashboard shows the 409 as "this flow changed since you opened it — reload") |
146
+ | `/api/workspaces/<ws>/flows/<flow>` | POST, PATCH, DELETE | edit a step (`step`, `instruction`, `options`, `target`, `subflow`), rearrange (`groups`), set `trigger`, set `compute` (`{ vcpu, memGiB, diskGiB }` or `null` — what one run may hold at once, merged over what the flow says), a canvas edit (`edit`, or `edits` — at most 200 in one request, `400` past that), undo (`restore` + `expect`); delete. Every PATCH and DELETE takes `expect` — the text the step numbers were read from, or its sha256 — and is refused with `409` and the current `text`, nothing written, when the file no longer reads it (the canvas, the list view's board and step options, and the CLI's `flow add`/`rm-step`/`dup-step --to` send it; the dashboard shows the 409 as "this flow changed since you opened it — reload") |
147
147
  | `/api/workspaces/<ws>/flows/draft` | POST, PATCH, DELETE | POST draft a flow with a model: `{ description, flow? }` (`flow` redrafts that one). Returns `{ ok, files: [{ path, content, before, sha256 }], issues: [{ where, message, level }], repaired, notes }` — checked with the deploy's checks and the flow lint, repaired once. **Writes nothing**; save with the source PUT. Needs `workspace:write`; a description over 4,000 characters is `413`; a Chat-Completions `provider:` is `422`. On the platform's models the balance is checked first (`402`) and the call is charged as one ledger line, flow `ai-draft`. PATCH and DELETE, and a POST without `description`, are the edits of a flow that happens to be named `draft`, exactly as at `flows/<flow>` |
148
148
  | `/api/workspaces/<ws>/flows/<flow>/run` | POST | start it. An `Idempotency-Key` header, or `idempotencyKey` in the body, makes a retried call safe: a dropped response, a proxy timeout or a CI step that ran twice is answered `started: false` with the `runId` it already started, rather than starting a second run and billing for it. Keys are remembered for 24 hours, per flow |
149
149
  | `/api/workspaces/<ws>/flows/<flow>/filter` | POST | test the flow's `filter:` against a delivery without starting anything: `{ payload }` — a webhook's JSON body (or the body as a string, read as JSON), an email's `{ from, to, subject, text }`, a chained run's `{ run, flow, status, ending, verdict, summary }`, a storage event's `{ by, paths }`. Answers `{ flow, trigger, filter, applies, match, reason }` — `reason` names the first condition that failed; a flow with no filter matches everything. Reads the deployed flow; nothing is recorded or charged |
@@ -187,14 +187,14 @@ history with each message.
187
187
  | `/api/workspaces/<ws>/agents/<agent>` | PATCH | edit one line of an agent's frontmatter in place, as the flow canvas does: `{ list: { key, name, action } }` — `key` one of `subagents`, `agents`, `tools`; `action` `add` or `remove` — or `{ set: { key: "description" | "sandbox", value } }` (`sandbox` takes `own` or `parent`, else 400), or `{ network }` — the sites its sandbox may reach: `"open"`, `"trusted"`, `"none"`, a list of sites, or `{ level, allow, defaults }`; `null` removes the line so it inherits ([Network](network)). A `network` nobody could read is a 400 that says why. Only that key's lines change — comments, key order and prose stay. Answers `{ ok, changed }`; 404 for an unknown agent. `workspace:write` |
188
188
  | `/api/workspaces/<ws>/agents/<agent>/run` | POST | run one agent alone (`task`; `test: true` for a test run) |
189
189
  | `/api/workspaces/<ws>/agents/import` | GET, POST | copy an agent in from another workspace of the account. GET lists what could be imported (every other workspace you can read, with its agents). POST `{ from, agent, as? }` copies `agents/<agent>/` — its agent.md and own skills/, scripts/, knowledge/; never memory/, outputs/, state/ — and answers `{ name, files, warnings }`; `warnings` names tools, skills, scripts and secrets the copy uses that this workspace lacks. 409 on a name clash (pass `as`), 404 for an unknown workspace or agent, 403 when `from` is outside your key's scope. Idempotent |
190
- | `/api/workspaces/<ws>/proposals` | GET | the workspace's proposed fixes, newest first: `{ proposals: [{ id, workspace, eval, by (auto, or who asked), createdAt, updatedAt, status, failures: [{ runId?, case?, check, detail, at }], jobId, reply (the assistant's reasoning), files: [{ path, content, before, sha256 }], issues: [{ where, message, level }], error?, notes?, decidedBy?, decidedAt?, applied? }] }`. `status` is `drafting`, `ready`, `failed`, `applying`, `applied`, `partial` (a write failed part-way; `applied` names what was written) or `dismissed`. `?status=`, `?eval=`. A drafting one is settled as it is read |
190
+ | `/api/workspaces/<ws>/proposals` | GET | the workspace's proposed fixes, newest first (`404` when the workspace does not exist): `{ proposals: [{ id, workspace, eval, by (auto, or who asked), createdAt, updatedAt, status, failures: [{ runId?, case?, check, detail, at }], jobId, reply (the assistant's reasoning), files: [{ path, content, before, sha256 }], issues: [{ where, message, level }], error?, notes?, decidedBy?, decidedAt?, applied? }] }`. `status` is `drafting`, `ready`, `failed`, `applying`, `applied`, `partial` (a write failed part-way; `applied` names what was written) or `dismissed`. `?status=`, `?eval=`. A drafting one is settled as it is read |
191
191
  | `/api/workspaces/<ws>/proposals/<id>` | GET, POST | one proposal. `POST { action: "apply" }` writes its files, each a revision by the caller, only when every one still reads what it was drawn against (`409` naming the file that changed) and can be written (`422`; a check error the deploy would refuse is `422` too); `POST { action: "dismiss" }` sets it aside — its failures stay looked at. Only agents, flows and skills are ever in one. Needs `workspace:write` |
192
192
  | `/api/workspaces/<ws>/export` | GET | this workspace, one flow or one agent as a `.zip` — `?kind=flow&name=<flow>` (the flow, every flow it runs as a step, every agent those steps and their colleagues name, and the workspace tools, skills and scripts they grant), `?kind=agent&name=<agent>` (its folder and what it grants), or neither for the whole authored tree. Never memory/, state/, outputs/, storage, runs or a secret's value; `foldrun-package.json` inside says what it is. Any role that can read the workspace |
193
- | `/api/workspaces/<ws>/import` | POST | take a package in; the body is the `.zip` (`content-type: application/zip`, at most 20 MB). `?dryRun=1` answers `{ kind, name, from, creates, added, overwritten, unchanged, needs: { secrets, tools, skills, scripts, agents, flows } }` plus `skipped` (entries it will not write: memory, state, anything outside the authored folders) and writes nothing. Without it, applies as one revision; 409 when it would replace a file with different text unless `?overwrite=1`, or when a file cannot be written there (all or nothing). Never deletes. A `Content-Length` is required (411 without). A workspace package into a name that does not exist makes that workspace (`workspace:manage`, the plan's workspace count). 400 for anything not a package, or one holding memory/, state/ or outputs/. Idempotent |
193
+ | `/api/workspaces/<ws>/import` | POST | take a package in; the body is the `.zip` (`content-type: application/zip`, at most 20 MB). `?dryRun=1` answers `{ kind, name, from, creates, added, overwritten, unchanged, needs: { secrets, tools, skills, scripts, agents, flows } }` plus `skipped` (entries it will not write: memory, state, anything outside the authored folders) and writes nothing. Without it, applies as one revision; 409 when it would replace a file with different text unless `?overwrite=1`, or when a file cannot be written there (all or nothing). Never deletes. A `Content-Length` is required (411 without). A workspace package into a name that does not exist makes that workspace (`workspace:manage`, the plan's workspace count). 400 for anything not a package, or one holding memory/, state/ or outputs/. A change to a policy key of the workspace's `AGENTS.md` (`budget`, `compute`, `notify`, `network_enforce`, `telemetry`, `alerts`, `owner`, `judge`, `timezone`) needs `workspace:manage` — `403` naming the key, nothing written ([Team and access](team-and-access#a-workspaces-policy-is-an-admins)). Idempotent |
194
194
  | `/api/workspaces/<ws>/evals` | GET, POST | list; create (`name`) |
195
195
  | `/api/workspaces/<ws>/evals/<eval>/run` | GET, POST | POST runs one eval and answers with its result; with `{ async: true }` it answers `202 { started, eval, runId, startedAt }` at once and the eval runs on — an eval of slow cases outlives a proxy's read timeout (Cloudflare's is 125 s by default). One run of an eval at a time: a second is `409` naming the run that holds it. `GET ?run=<runId>` is what to poll — that run alone, whatever else runs or writes the eval's latest result meanwhile: `{ runId, state, running }` where `state` is `running`, `done` (with its `result`), `failed` (with `error`), `lost` (it stopped reporting before saving a result, e.g. a restart) or `unavailable` (an id not on record — the last 20 runs are kept). Plain `GET` answers who holds the eval now (`running`, `runId`, `startedAt`) and the latest `result`. The dashboard and `foldrun eval --to` start async and poll by run id |
196
- | `/api/workspaces/<ws>/evals/<eval>/compare` | GET, POST | compare models on one eval: its cases under two to four settings, side by side. `POST { configs: [{ model, effort?, agent? }], repeat?, maxUsd? }` — `model` a tier (`fast`, `default`, `max`) or a model id; `effort` low…max; `agent` (flow evals) forces only that agent's steps, else every step; `repeat` 1–5 (1); `maxUsd` the spend limit, above 0 and at most 100 (5). At most 60 runs (cases × settings × repeat, else `413`). Answers `202 { started, eval, runId, startedAt, trials, maxUsd }` and runs on: every run a test run, the eval's own judge for all. `GET ?run=<runId>` → `{ runId, state, running }` — `running` (with `progress: { done, total }`), `done` (with `result`), `failed` (with `error`), `lost` or `unavailable`. `result` is `{ eval, target, judge, startedAt, finishedAt, repeat, maxUsd, spentUsd, stopped, configs: [{ model, effort, agent, label, trials, passed, notRun, rate, costUsd (runs and judges), judgeCostUsd, avgCostUsd, avgSecs (worker pick-up to end), runIds }], cases: [{ case, passed: [per setting], trials: [per setting] }] }`. Plain `GET` → `{ running, runId?, startedAt?, progress?, comparisons }` (the last 20, newest first). One comparison of an eval at a time (`409`); a grader, saved inputs or an eval with a `run:` check `400`. Needs `run:start` to start |
197
- | `/api/workspaces/<ws>/evals/<eval>/improve` | POST | ask for a proposed fix now: for a grader, from its failed grades no proposal has covered; for an eval that runs cases, from its last result's failed cases. Answers `202` with the proposal, `status: "drafting"` — the assistant drafts it (one reply, paid as Ask AI's are); poll `GET …/proposals/<id>`. `409` when there is nothing to fix, a proposal for this eval is open, or the account or workspace is paused. Needs `run:start` |
196
+ | `/api/workspaces/<ws>/evals/<eval>/compare` | GET, POST | compare models on one eval: its cases under two to four settings, side by side. `POST { configs: [{ model, effort?, agent? }], repeat?, maxUsd? }` — `model` a tier (`fast`, `default`, `max`) or a model id; `effort` low…max; `agent` (flow evals) forces only that agent's steps, else every step; `repeat` 1–5 (1); `maxUsd` the spend limit, above 0 and at most 100 (5). At most 60 runs (cases × settings × repeat, else `413`). Answers `202 { started, eval, runId, startedAt, trials, maxUsd }` and runs on: every run a test run, the eval's own judge for all. `GET ?run=<runId>` → `{ runId, state, running }` — `running` (with `progress: { done, total }`), `done` (with `result`), `failed` (with `error`), `lost` or `unavailable`. `result` is `{ eval, target, judge, startedAt, finishedAt, repeat, maxUsd, spentUsd, stopped, configs: [{ model, effort, agent, label, trials, passed, notRun, rate, costUsd (runs and judges), judgeCostUsd, avgCostUsd, avgSecs (worker pick-up to end), runIds }], cases: [{ case, passed: [per setting], trials: [per setting] }] }`. Plain `GET` → `{ running, runId?, startedAt?, progress?, comparisons }` (the last 20, newest first). One comparison of an eval at a time (`409`), none while the account or workspace is paused (`409`); a grader, saved inputs or an eval with a `run:` check `400`. Needs `run:start` to start |
197
+ | `/api/workspaces/<ws>/evals/<eval>/improve` | POST | ask for a proposed fix now: for a grader, from its failed grades no proposal has covered; for an eval that runs cases, from its last result's failed cases. Answers `202` with the proposal, `status: "drafting"` — the assistant drafts it (one reply, paid as Ask AI's are); poll `GET …/proposals/<id>`. `409` when there is nothing to fix, a proposal for this eval is open, or the account or workspace is paused. Held to Ask AI's limits — the same per-person hourly count (`429`), and on the platform's models its daily account count (`429`) and the balance (`402`). Needs `run:start` |
198
198
  | `/api/workspaces/<ws>/evals/<eval>/grades` | GET | a grader's grades (an eval with `trigger: runs`): `{ eval, flow, agent, sample, improve, days, summary, grades }`. `summary` is the window's `{ graded, passed, failed, errors, rate, costUsd, byDay: [{ day, graded, passed, failed }] }` (`rate` is passed ÷ decided, `null` when nothing was decided); `grades` the newest first, one per run — `{ eval, runId, flow, at, status (pass, fail or error — not decided), checks: [{ name, passed, error?, assertions: [{ type, value, passed, detail }] }], costUsd (the judges'), model, evalRevision, runRevision, runFinishedAt, by }`. `?days=` 1–90 (30), `?status=` pass, fail or error, `?limit=` 1–500 (100). An eval that runs cases is `400` |
199
199
  | `/api/workspaces/<ws>/evals/<eval>/grade` | POST | grade one finished run now, sampled or not: `{ run }` → the grade (the shape above), kept like any other — the newest grade of a run is the one shown. Needs `run:start`; the judges run on the account's model key. A run that is not this grader's (another flow, or no step by its agent) is `400`, a run still going `409`, one with no reply to grade `409`, an eval that runs cases `400`, a paused account or workspace `409` |
200
200
  | `/api/workspaces/<ws>/tools/<tool>/test` | POST | exercise one tool (`args`, `path`). An http tool with an `operations:` allowlist is probed only with a GET to one of its operations (no `path`: the first GET without parameters), and fails if the allowlist resolves nothing, as a run does |
@@ -212,7 +212,7 @@ paying for the steps around it.
212
212
  | `/api/workspaces/<ws>/runs/<id>/calls/<call>` | GET | one tool call's recorded content (see [Runs](runs#what-a-run-records)): `{ call: { id, tool, input, output, inputChars, outputChars, truncated, inputCut, outputCut } }` — what it was given and what it gave back, secrets masked, each at most 65,536 characters; `inputChars`/`outputChars` are the whole length, `inputCut`/`outputCut` say which part was cut (`truncated`: either). `<call>` is the tool event's `call`; an event with `captured: true` has content here. 404 when nothing was recorded: the workspace says `capture: metadata`, or the run is from before 19 Oct 2026. A run's steps also carry `calls`, each model call (`n`, `at`, `ms`, `model`, `stop`, `tokens`, `tools`, and `subagent` / `attempt` when a sub-agent or a later attempt made it); a step that handed jobs to `sandbox: own` sub-agents carries `delegations` (`id`, `agent`, `status`, `costUsd`, `ms`), and each job is a step of its own with `subagentOf` (the delegating agent), `delegation` (that `id`) and `wrote` (the workspace paths it changed — copied into the delegating step's sandbox too, up to 4 MiB a job); and the run its `revision` (the workspace's latest revision when a worker picked it up — a deploy's commit, or the id an edit through `/source` was saved as) and `drivenAt` (when that was) |
213
213
  | `/api/workspaces/<ws>/runs/<id>/trace` | GET | the run as one tree (see [Runs](runs#the-trace-tree)): `{ tree, failure }`. Each span is `{ id, kind, label, start, end, status, children, … }`, where `kind` is `run`, `step`, `model` (one model call: `model`, `stop`, `tokens`), `tool` (`call`, `captured` when its input and output were recorded) or `error` (`text`); `start`/`end` are epoch milliseconds and `status` is `ok`, `error`, `running`, `waiting`, `skipped` or `pending`. A tool call sits under the model call that asked for it. `failure` is the ids from the root to the first thing that went wrong, which the run page opens on; `[]` when nothing did |
214
214
  | `/api/workspaces/<ws>/runs/<id>/compare?with=` | GET | this run beside another of the same flow (see [Runs](runs#compare-with-the-last-good-run)): `{ comparison: { base, run, revisionChanged, changedFiles, steps }, chosen }`. Each step is `{ step, agent, base, run, changes }`: both sides' status, instruction, model, seconds, tokens, model calls, tool counts, tool errors, first errors and first line said, and `changes` in words (`status: completed → failed`, `new error: …`, `instruction changed`, `tools: +web ×3`, `took 12s → 48s`, …). `changedFiles` lists the files changed between the revisions the two ran (null when one is unknown). `with` names the other run; unasked it is the newest earlier run of the flow that finished well, else the run this one re-ran (`chosen` says which) |
215
- | `/api/workspaces/<ws>/runs/<id>` | GET, DELETE | the whole run: every step, its output, cost, timing, the runner `image` it ran on and — for a step that browsed through the account's pod from slim — its `browserPod` reconnects and fallback ([runs](runs#the-record)). `?wait=true&timeout=<s>` instead blocks until the run stops (or `timeout`, default 300, max 900) and answers the verdict the run routes give — `200` once the run has ended, however it ended: `ok: true` when it completed, `ok: false` with its `status` and `failure: { agent, reason }` when it failed or was stopped (a run that fails is the answer, not a fault in the call — it was a `500` before 29 Oct 2026); `202` still going (`timedOut`) or parked on a person (`awaitingApproval`). A start refused before any run exists — a paused account or workspace (`423`), an agent or flow that is not there (`404`), `overlap: skip` (`409`) — is answered as such and waits for nothing. Ask in short pieces: whatever sits in front of the platform cuts a request that stays silent too long (Cloudflare at 100 s, an AWS ALB at 60 s), and a flow can run for many minutes — the CLI's `--wait` asks 25 s at a time and comes back here on every `202` |
215
+ | `/api/workspaces/<ws>/runs/<id>` | GET, DELETE | the whole run: every step, its output, cost, timing, the runner `image` it ran on and — for a step that browsed through the account's pod from slim — its `browserPod` reconnects and fallback ([runs](runs#the-record)). `?wait=true&timeout=<s>` instead blocks until the run stops (or `timeout`, default 300, max 900) and answers the verdict the run routes give — `200` once the run has ended, however it ended: `ok: true` when it completed, `ok: false` with its `status` and `failure: { agent, reason }` when it failed or was stopped (a run that fails is the answer, not a fault in the call — it was a `500` before 29 Oct 2026); `202` still going (`timedOut`) or parked on a person (`awaitingApproval`). A start refused before any run exists — a paused account or workspace (`423`), an agent or flow that is not there (`404`), `overlap: skip` (`409`) — is answered as such and waits for nothing. Ask in short pieces: whatever sits in front of the platform cuts a request that stays silent too long (Cloudflare at 100 s, an AWS ALB at 60 s), and a flow can run for many minutes — the CLI's `--wait` asks 25 s at a time and comes back here on every `202`. DELETE erases the run's record and archived outputs (a run still going is stopped first; the ledger line stays) and needs `workspace:manage` — an admin — since 30 Oct 2026 (it was `run:start`) |
216
216
  | `/api/workspaces/<ws>/runs/<id>/stream` | GET | server-sent events, live |
217
217
  | `/api/workspaces/<ws>/runs/<id>/stop` | POST | destroys the sandbox, not just the record. `404` for no such run, `409` for one already finished |
218
218
  | `/api/workspaces/<ws>/runs/<id>/rerun` | POST | again — `step` to start partway, or `agent` to start at the first step that agent runs (one of the two is required). `instruction` tells that step something else this once, in place of the flow's (the flow file is not changed); the new run's `rerunOf` says `{ run, step, instruction }`. Takes `?wait=true&timeout=` like a flow start. `404` for no such run, `409` for one not finished, `400` for a `step` that is not a whole number |
@@ -226,10 +226,10 @@ paying for the steps around it.
226
226
  | `/api/workspaces/<ws>/triggers?days=` | GET | why nothing happened: one row per flow saying how often its trigger fired, how often that became a run, and what the difference was — a duplicate delivery, a throttled burst, a debounced burst still being waited out, a quarantined flow, a workspace or account paused by a person (`halted`), an `overlap: skip`, a fire missed while the platform was down. Plus every decision newest-first, and the hook/inbox delivery log, which answers the separate question of whether a request arrived and was authentic. `days` 1–365, default 7 (`since=`, its older name, still works — deprecated) |
227
227
  | `/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 |
228
228
  | `/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 |
229
- | `/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. Needs the permission that runs, because it sends real mail |
229
+ | `/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 |
230
230
  | `/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) |
231
231
  | `/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 |
232
- | `/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`; audited as `workspace.restored` |
232
+ | `/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` |
233
233
 
234
234
  `status` is one of `queued`, `running`, `awaiting-approval`, `completed`,
235
235
  `failed`.
@@ -302,10 +302,15 @@ URLs mean nothing in a run pod ever holds the bucket credential.
302
302
 
303
303
  | Route | Methods | |
304
304
  |---|---|---|
305
- | `/api/workspaces/<ws>/shares` | POST, GET, DELETE | mint (`path`, `ttlDays`: days, `null` never; returns `url`, `token`, `path`, `contentType`, `expiresAt`), list, revoke (`?token=`, only a link of this workspace) |
306
- | `/s/<token>` | GET, HEAD | the file itself, no credential, streamed; HEAD reads only its length. `429` past 120 a minute from one caller or 1,200 a minute for one link |
305
+ | `/api/workspaces/<ws>/shares` | POST, GET, DELETE | mint (`path`, `ttlDays`: days, `null` never; returns `url`, `token`, `id`, `path`, `contentType`, `expiresAt`), list, revoke (`?token=` or `?id=`, only a link of this workspace) |
306
+ | `/s/<token>` | GET, HEAD | the file itself, no credential, streamed; HEAD reads only its length. `Cache-Control: private, no-store`, so no shared cache serves a link after it is revoked or expires. `429` past 120 a minute from one caller or 1,200 a minute for one link |
307
307
 
308
- From the terminal: `foldrun storage share <path>`, `shares`, `unshare <token>`.
308
+ From the terminal: `foldrun storage share <path>`, `shares`, `unshare <token|id>`.
309
+
310
+ The list hands a link's token (and `url`) only to an admin and to the person
311
+ who made it — a token is the link, and it outlives the access of whoever
312
+ copied it. Everyone else gets the row with `masked: true`, the token cut to a
313
+ stub, `url: null`, and `id` (`sh_…`, a hash of the token) to revoke it by.
309
314
 
310
315
  `POST` returns a `url` under `/s/<token>`. That URL answers without a
311
316
  credential — the token *is* the authorisation, so it carries 24 random bytes
@@ -333,7 +338,7 @@ its header and requires a URL it can GET for itself.
333
338
 
334
339
  | Route | Methods | |
335
340
  |---|---|---|
336
- | `/api/secrets?workspace=` | GET, PUT, PATCH, DELETE | the vault: list which secrets exist (never a value), each with the `sites` it is bound to; set one (`name` plus one shape, below, and optionally `sites`); bind one to sites with PATCH `{ name, sites }` — `sites` a list like `["api.example.com", "*.example.com"]`, `[]` unbinds, the value untouched, 404 for a secret that is not there, 400 for a site with a scheme, path or port and for a file, ssh or api secret ([bound to sites](secrets#bound-to-sites)); delete one (`name`). `workspace` names a workspace's own store; unsaid is the account's, which a key scoped to some workspaces may not touch. `name` is a string (400 otherwise). The account's `RESEND_API_KEY` and `EMAIL_FROM` — the sender of everyone's sign-in mail — are set, rebound and deleted by the owner alone (403 to anyone else), here and through an OAuth connect. An oauth2 recipe from a caller scoped to some workspaces links to the account's saved OAuth app with the same token URL and client id but never saves or changes one (as `POST /api/oauth/clients` refuses them). PUT is idempotent; PATCH and a PUT with `sites` are audited as `secret.sites` / `secret.set` |
341
+ | `/api/secrets?workspace=` | GET, PUT, PATCH, DELETE | the vault: list which secrets exist (never a value), each with the `sites` it is bound to; set one (`name` plus one shape, below, and optionally `sites`); bind one to sites with PATCH `{ name, sites }` — `sites` a list like `["api.example.com", "*.example.com"]`, `[]` unbinds, the value untouched, 404 for a secret that is not there, 400 for a site with a scheme, path or port and for a file, ssh or api secret ([bound to sites](secrets#bound-to-sites)); delete one (`name`). `workspace` names a workspace's own store; unsaid is the account's, which a key scoped to some workspaces may not touch. `name` is a string (400 otherwise). The account's `RESEND_API_KEY` and `EMAIL_FROM` — the sender of everyone's sign-in mail — are set, rebound and deleted by the owner alone (403 to anyone else), here and through an OAuth connect — the owner in person: their signed-in session or the key their own `foldrun login` minted, never another key they minted. An oauth2 recipe from a caller scoped to some workspaces links to the account's saved OAuth app with the same token URL and client id but never saves or changes one (as `POST /api/oauth/clients` refuses them). PATCH also takes `workspaces` (with or instead of `sites`): `{ name, workspaces: ["sales", "ops"] }` limits an **account** secret to those workspaces — every other one finds it not set, in runs, tool tests, `notify:` (its email too), the egress proxy and MCP, for runs that start after it ([limited to some workspaces](secrets#limited-to-some-workspaces)); `null` opens it to every workspace, `[]` to none; the answer carries `workspaces` (sorted, or `null`). `ifWorkspaces` — the list you loaded, `null` for every workspace — makes it conditional: 409 when the list changed since, nothing written. PUT takes the same `workspaces` and saves it with the value in one write (the answer carries it too); it is never ignored. Account store only (400 with `workspace`), an admin over every workspace (403 for a scoped caller), names of workspaces that exist, checked under the vault's lock (400 otherwise), 404 for a secret that is not there; audited as `secret.workspaces` (PATCH) and in `secret.set` (PUT). GET of the account store lists each limited secret's `workspaces`, and `?workspace=` leaves out an account secret that workspace may not use. PUT is idempotent; PATCH and a PUT with `sites` are audited as `secret.sites` / `secret.set` |
337
342
 
338
343
  `PUT` takes `name` plus exactly one shape: `value` (a string), `file` (a PEM,
339
344
  a cert), `oauth2`, `service_account`, `ssh`, `api`, `client_cert` (`{ cert, key, passphrase?, export? }` — mutual TLS, presented by the egress proxy to the exact sites the secret is bound to), or `identity` (`{ audience }` — keyless cloud access). They go to the vault;
@@ -350,32 +355,32 @@ Reads return which secrets exist, never their values.
350
355
  | `/api/team` | GET, POST | members with their roles and workspace scope; mint an invite — `role` (viewer \| editor \| admin, default editor), `workspaces` (names, or omit for all), `email` (only that address can accept it; sent through the account's `RESEND_API_KEY` unless `send: false`). An invite works **once**, for seven days, and a newer invite to the same address revokes the older ones still pending. Returns `id`, `path` (the invite's relative URL, shown only here), `expires`, `sent` and any `sendError` either way; the full link is in the mail. Links made before 29 Oct 2026 (`inv1`–`inv3`) are refused |
351
356
  | `/api/team/invites?all=1` | GET | the account's invites, newest first — pending ones unless `all=1` (then accepted, revoked and expired too): `{ invites: [{ id, email, role, workspaces, invitedBy, createdAt, expiresAt, status }] }`, `email` `null` for a link anyone may use, `workspaces` `null` for all, `status` `pending` \| `accepted` \| `revoked` \| `expired`. Never the link. `team:manage` — an admin key included; a caller scoped to some workspaces sees only the invites inside its scope |
352
357
  | `/api/team/invites/<id>` | DELETE | revoke an invite: its link stops working at once. `{ ok, revoked, invite }` — `revoked: false` when it was already revoked or expired; `404` for an id that is not this account's; `409` for one already accepted (remove the member instead). `team:manage`, a key included; a scoped caller only inside its scope, and an admin invite only by the owner. Audited as `member.invite_revoked` |
353
- | `/api/team/members/<id>` | PATCH, DELETE | change a member's role (`role`) and/or which workspaces they may open (`workspaces`: names, or null for all); remove them. Removing someone revokes the keys and pending invites they made and any invite still pending to their address; a lower role or fewer workspaces revokes the keys and invites that reach beyond their new standing |
354
- | `/api/team/transfer` | POST | hand the account to a member (`to`) — owner only; you become an admin |
358
+ | `/api/team/members/<id>` | PATCH, DELETE | change a member's role (`role`) and/or which workspaces they may open (`workspaces`: names, or null for all); remove them. Removing someone revokes the keys and pending invites they made and any invite still pending to their address; a lower role or fewer workspaces revokes the keys and invites that reach beyond their new standing. `404` for an id that is not a member, whatever the body |
359
+ | `/api/team/transfer` | POST | hand the account to a member (`to`) — owner only, signed in, and re-proving it is them: `password` (the current one) and, when two-step sign-in is on, `code` (from the app, or a backup code). 400 without them, 401 when wrong, 6 tries in 15 minutes. You become an admin |
355
360
  | `/api/usage/compute` | GET | the account's compute at every level (27 Oct 2026): `compute` is `{ vcpu, memGiB, diskGiB, stepVcpu, stepMemGiB, stepDiskGiB, source }` — the cores, GiB and GiB of disk all its running steps may hold together, the most one step may hold (each `null` for no cap), and where the pool came from (`plan`, `account` — its own `compute:` in AGENTS.md, which can only lower it — `install`, or `null`); `inUse` is `{ vcpu, memGiB, diskGiB, steps }`, what its running steps' sandboxes hold now, from their records (a step still waiting for room holds nothing; a caller scoped to some workspaces sees theirs); `workspaces` is each workspace's own `pool` (its AGENTS.md `compute:`, `null` figures for none) and `inUse`; `runs` is each live run with a pool of its own (its flow's `compute:`) or anything held, `{ workspace, runId, flow, pool, inUse }`; `waiting` lists the steps waiting for room, oldest first — `{ workspace, runId, flow, step, agent, since, why, cpus, memGiB, diskGiB, level?, runPool }`, `since` being when it first found none, its place in line, and `level` the cap that held it when it last looked. A step past any level waits, with no time limit, and starts in turn; one bigger than a level's whole cap or the step maximum fails at once ([four levels](budgets-and-billing#compute-at-four-levels), [waiting for room](budgets-and-billing#waiting-for-room)) |
356
361
  | `/api/usage/history?days=` | GET | charged spend by flow, by agent and by workspace over time, read from the ledger rather than the run records — so it survives runs being pruned and reports what was billed rather than what was consumed. Buckets by week over three weeks, by day under. Each series carries its periods, its total, and the change between the last two COMPLETE periods, so a partial week never reads as a collapse. `unattributedUsd` is charges from before a line recorded its flow. A caller scoped to some workspaces sees only the charges in those; `days` 1–365, default 56 |
357
362
  | `/api/account/model` | GET, PUT, DELETE | the account's own model key — what every step runs on unless an agent, workspace or the account's AGENTS.md names a `provider:`. GET: `{ set, provider, baseUrl, format, keyHint, runsOn, platformKeyAllowed }` — never the key, only its last four characters; `runsOn` is `account` (its own key), `platform` (the platform's credential, for the operator's accounts) or `none` (runs are refused until a key is set). PUT `{ provider, apiKey, baseUrl?, format? }` (needs `secrets:write`): `provider` is a preset name (anthropic, openrouter, openai, groq, … — see providers) or `custom` with an https `baseUrl` and a `format` (anthropic or openai); a Claude login token (sk-ant-oat…) is refused for any account not allowed the platform's credential. Stored as the account secrets `FOLDRUN_MODEL_PROVIDER`, `FOLDRUN_MODEL_API_KEY`, `FOLDRUN_MODEL_BASE_URL`, `FOLDRUN_MODEL_FORMAT`. DELETE removes them. Honours Idempotency-Key on PUT; audited as model.key_set / model.key_removed |
358
363
  | `/api/account/providers` | GET, POST | GET: the model providers this account's files actually use — each one's preset name, where it is declared, the model a check would send — plus the last daily health check. POST forces one now, which spends one minimal request at each distinct endpoint, and needs the permission that runs and every workspace. A member or key scoped to some workspaces sees the account's provider blocks and its own workspaces' only, in `configured` and in the last check |
359
- | `/api/usage` | GET | what has been spent, by meter; each bucket's tokens are `inputTokens` (all input), `outputTokens`, `cacheReadTokens` and `cacheWriteTokens` (the part of the input the prompt cache served and stored), and `cacheHitRate` — reads over `measuredInputTokens`, the input of steps that report the split, `null` when none do. A key or member scoped to some workspaces sees those workspaces, and totals over them; `ledger` is the account's `balanceUsd` and `chargedUsd` (all time), the account's as the wallet's are — since API version `2026-10-26` nothing else; earlier pins see `providerCostUsd` and `marginUsd` as `null` |
364
+ | `/api/usage` | GET | what has been spent, by meter; each bucket's tokens are `inputTokens` (all input), `outputTokens`, `cacheReadTokens` and `cacheWriteTokens` (the part of the input the prompt cache served and stored), and `cacheHitRate` — reads over `measuredInputTokens`, the input of steps that report the split, `null` when none do. A key or member scoped to some workspaces sees those workspaces, and totals over them; `ledger` is the account's `balanceUsd` and `chargedUsd` (all time), and `waived` the legs the account is not charged for — both `null` to a caller scoped to some workspaces, since they are the whole account's money. Since API version `2026-10-26` nothing else; earlier pins see `providerCostUsd` and `marginUsd` as `null` |
360
365
  | `/api/approvals` | GET | every gate waiting on a person, across workspaces — one entry per waiting **step** (`workspace`, `runId`, `flow`, `step`, `agent`, `question`, `asked`, `waitingSince`), oldest first. By step status, not run status: a decided gate leaves the list at once, before the worker resumes the run. `wait: event` steps are not listed; no button answers them. Beside it, `questions`: every question an agent is asking mid-step in a running run (`kind: "question"`, `id`, `workspace`, `runId`, `flow`, `agent`, `question`, `options?`, `askedAt`) — answered with `…/runs/<id>/answer` |
361
366
  | `/api/insights?days=&workspace=` | GET | recurring problems found in the runs of the window (see [Runs](runs#insights)): `{ days, insights: [{ id, kind, workspace, agent, tool?, title, why, fix, credits, steps, evidence: [{ workspace, runId, step }] }] }`. `kind` is `cache` (an agent's big prompt mostly uncached), `big-result` (a tool result over 20k characters sent again on every later model call), `retry-loop` (a tool erroring three or more times in a step) or `timeout` (steps using 80% or more of their `timeout:`); `credits` is about what it cost in the window, null when it is not money. `days` 1–30, 7 unasked. A key scoped to some workspaces sees theirs |
362
367
  | `/api/issues?status=&workspace=` | GET | the account's issues: what went wrong, grouped and kept open until a person resolves it (see [Runs](runs#issues)). One issue is one desk's flow failing at one agent, or ending BLOCKED or BAD, or one platform cause across desks. Each carries `id`, `kind` (`platform`, `failed`, `blocked`, `bad`, `missed` — a scheduled fire that started no run), `status` (`open`, `acknowledged`, `snoozed`, `resolved`), `regressed` and `sinceRevision` (it was resolved and came back, since the revision its new run ran), `snoozedFor`, `workspace`/`workspaces`, `what`, `agent`, `reason`, `action` (what to do), `firstSeen`, `lastSeen`, `count`, the newest `runs`, `recoveredAt` (the flow's newest good run since — it closes nothing), `acknowledged`, `snoozedUntil`, `resolved` and the `history` of what people did. `status` is `active` unasked (open + acknowledged), or `open`, `acknowledged`, `snoozed`, `resolved`, `all`; `workspace` keeps the ones that hit it. A key scoped to some workspaces sees the issues of those |
363
368
  | `/api/issues/<id>` | GET POST | one issue; POST acts on it: `{ action: "acknowledge" | "snooze" | "resolve" | "reopen", for?: "30m" | "4h" | "1d" | "1w", until?: ISO, times?: n, note? }` (editor or above), kept in its history with who did it, and answers `{ issue }` as it now stands. A snooze needs `for`, a future `until`, or `times` (until it happens that many more times; with a time too, whichever comes first). A platform issue is the account's: closing it needs access to every workspace. A run that goes wrong the same way after a resolve opens the issue again |
364
- | `/api/account/export` | GET | the owner's copy of what the platform holds about the account, as one JSON file (`foldrun-<account>-export.json`): `workspaces` (with their flows), `members` (email, role, scope, since), `runs` (an index — id, workspace, flow, status, times, headline) and the whole `ledger` (each line's charge; the platform's provider cost is left out). `billing:manage`, so the owner; audited as `account.exported`. The markdown itself comes from `foldrun pull` or the source API |
369
+ | `/api/account/export` | GET | the owner's copy of what the platform holds about the account, as one JSON file (`foldrun-<account>-export.json`): `workspaces` (with their flows), `members` (email, role, scope, since), `runs` (an index — id, workspace, flow, status, times, headline) and the whole `ledger` (each line's charge and what it was for; the platform's provider cost, its internal dedup `key` and `pricingVersion` are left out). `billing:manage`, so the owner; audited as `account.exported`. The markdown itself comes from `foldrun pull` or the source API |
365
370
  | `/api/account/telemetry/test` | POST | send one made-up run as an OpenTelemetry trace to the collector `telemetry:` names — the account's, or `{ workspace }`'s — with its header secrets filled from the vault; `{ ok, status?, error?, spans?, endpoint }`. `409` when no `telemetry:` is set. Needs `workspace:manage` |
366
- | `/api/account/jobs?workspace=` | GET | the four jobs (governance, guardrail, observability, evaluation) and each `AGENTS.md` field of each: `{ jobs: [{ name, title, what, fields: [{ key, account, workspace?, combine, writable }] }] }` — the account's value and the workspace's when `workspace` is given (null: unset), as written with blocks folded; `combine` is how the two meet at run time (`workspace replaces`, `either turns it on`, `both apply`, `per key`, `per field`, `level nearest, sites from both`, `account only`); `writable` is whether that scope's settings PATCH (`/api/account`, or the workspace's) writes it — the rest are written in `AGENTS.md`. See [The four jobs](four-jobs) |
371
+ | `/api/account/jobs?workspace=` | GET | the four jobs (governance, guardrail, observability, evaluation) and each `AGENTS.md` field of each: `{ jobs: [{ name, title, what, fields: [{ key, account, workspace?, combine, writable }] }] }` — the account's value and the workspace's when `workspace` is given (null: unset), as written with blocks folded — to a caller scoped to some workspaces the account's `notify` and `telemetry` are `{ hidden: true, … }` (set; no URL, headers or token); `combine` is how the two meet at run time (`workspace replaces`, `either turns it on`, `both apply`, `per key`, `per field`, `level nearest, sites from both`, `account only`); `writable` is whether that scope's settings PATCH (`/api/account`, or the workspace's) writes it — the rest are written in `AGENTS.md`. See [The four jobs](four-jobs) |
367
372
  | `/api/account/pause` | GET, POST, DELETE | the account's kill switch: the same as a workspace's `/pause`, for every workspace at once. GET `{ paused, account, workspaces }` (`workspaces`: those paused on their own). POST `{ reason?, stop?: true }`, DELETE resumes the account — a workspace paused on its own stays paused. Needs `workspace:manage` and access to every workspace |
368
373
  | `/api/account/close` | POST | the owner asks to close the account — in person, never a key, with `confirm` set to the account's name and an optional `reason`. Not a delete: the account is suspended at once (runs in flight finish, sign-in and the export still work), `closeRequested` is set on its admin state, and the platform's operator is mailed to settle the last invoice and any refund. A plan's subscription is set to stop at the end of the period already paid for — nothing renews, no refund — and `billing` says what was done (the close stands even if Stripe could not be reached; `billing` then says so). Returns `{ ok, suspended, notified, billing }`; 409 when already asked. Hosted installs only |
369
- | `/api/account/backups` | GET | what is backed up for this account: `policy` (`schedule`, `keepLocal`, `keepOffsiteDays`, `encrypted`, `covers`, `excludes`), `last`, `backups` (each nightly archive that holds this account, newest first: `id`, `at`, `bytes` (the encrypted object), `sha256` (the archive inside the encryption — what a decrypt must reproduce), `kinds` — files, database, keys — `verified`, `offsite`, `keepDays`, `encrypted` (sealed with age before it left the server; false for archives taken before October 2026), `recipient` (the key's fingerprint, `sha256:<16 hex>`, or null)), `requests` (earlier restore requests) and `workspaces` (`name`, `head`, `history`, `lastChange`) — what a restore can reach. See [Backups and restore](backups-and-restore.md) |
374
+ | `/api/account/backups` | GET | what is backed up for this account: `policy` (`schedule`, `keepLocal`, `keepOffsiteDays`, `encrypted`, `covers`, `excludes`), `last`, `backups` (each nightly archive that holds this account, newest first: `id`, `at`, `bytes`, `files`, `runs` (always null: they measured the whole archive, which holds every account on the server, so they are not shown to one — 30 Oct 2026), `sha256` (the archive inside the encryption — what a decrypt must reproduce), `kinds` — files, database, keys — `verified`, `offsite`, `keepDays`, `encrypted` (sealed with age before it left the server; false for archives taken before October 2026), `recipient` (the key's fingerprint, `sha256:<16 hex>`, or null)), `requests` (earlier restore requests) and `workspaces` (`name`, `head`, `history`, `lastChange`) — what a restore can reach. See [Backups and restore](backups-and-restore.md) |
370
375
  | `/api/account/backups/requests` | GET, POST | ask the platform team to restore what an account cannot restore itself. POST `{ what, target, workspace?, backupId?, note? }` (`what` is runs, state, storage or everything) records the request, mails the operator and audits it as `backup.restore_requested`; answers 201 `{ ok, request }` with `notified` saying whether the mail went. Restores nothing. `workspace:manage`, and a member scoped to some workspaces must name one. GET lists this account's requests |
371
- | `/api/account/api` | GET, PATCH | how this account meets the API — GET `{ version: { current, pinned, effective, supported, supportMonths }, limits: { plan, windowSeconds, perCredential: { read, write }, perAccount: { read, write } }, usage }`. `usage` is the last 30 days — `{ days, versions: [{ version, requests, lastSeen }], deprecated: [{ route, requests, lastSeen, deprecatedAt, sunsetAt, link, callers: [{ credential, requests, lastSeen }] }] }`, `credential` naming a key by its label and prefix — or `null` when it could not be read; PATCH `{ version: "YYYY-MM-DD" \| null }` pins the version API-key requests without a `Foldrun-Version` header get (null: always current); the dashboard always gets current. `keys:manage`; PATCH also needs every workspace (403 to a member or key scoped to some), since the pin is every key's. See [api-usage](api-usage.md) |
376
+ | `/api/account/api` | GET, PATCH | how this account meets the API — GET `{ version: { current, pinned, effective, supported, supportMonths }, limits: { plan, windowSeconds, perCredential: { read, write }, perAccount: { read, write } }, usage }`. `usage` is the last 30 days — `{ days, versions: [{ version, requests, lastSeen }], deprecated: [{ route, requests, lastSeen, deprecatedAt, sunsetAt, link, callers: [{ credential, requests, lastSeen }] }] }`, `credential` naming a key by its label and prefix — or `null` when it could not be read. A caller scoped to some workspaces gets `usage: null` and `usageHidden: true`: who calls which route is the whole account's; PATCH `{ version: "YYYY-MM-DD" \| null }` pins the version API-key requests without a `Foldrun-Version` header get (null: always current); the dashboard always gets current. `keys:manage`; PATCH also needs every workspace (403 to a member or key scoped to some), since the pin is every key's. See [api-usage](api-usage.md) |
372
377
  | `/api/account/flags` | GET | the feature flags as they stand for this account — `{ flags: [{ name, description, owner, default, on, source, rollout }] }`, `source` being what decided it: `account` (an override for this account), `global` (the install-wide setting), `rollout` (a percentage of accounts, by a stable hash of account and flag; `rollout` is the percentage) or `default`. Read-only, every role; only the platform's operator changes a flag (a self-hosted install runs every flag at its default). See [Feature flags](feature-flags.md) |
373
378
  | `/api/openapi.json` | GET | this API as an OpenAPI 3.1 document — every route and method, bearer auth, the rate-limit, version and Idempotency-Key headers, and request/response schemas for runs, flow runs, deploy, source, secrets, keys and billing. No key needed. Generated from the route files by `scripts/gen-openapi.mjs`; the dashboard renders it at Docs → API reference, `foldrun api spec` saves it |
374
- | `/api/account` | GET, PATCH | the account's defaults from its AGENTS.md frontmatter — `timezone`, `budget` (a USD cap — a number for a month, `"60/day"`, `"60/week"`, or `{ usd, period }`; null is no limit), `notify` (`{ url?, email?, events }`), `concurrency`, `compute` (`{ vcpu, memGiB, diskGiB }` — the account's own cap on what its running steps hold together, lower than the plan's; PATCH writes it as `compute: { vcpu, memory, disk }`, merged over what is set: a figure not sent is kept, `null` drops one, `compute: null` drops all), `deploy_block` (`none`, `secrets` or `security` — answered as `deployBlock`), `network_enforce` (answered as `networkEnforce`), `owner`, `alerts` (as written), `judge` (`{ model?, effort? }`), `telemetry` (`{ otlp, headers }` — header values are `${SECRET}` names; answered as `{ endpoint, headers }`); PATCH sets the keys sent, null clears one, and edits the file in place |
379
+ | `/api/account` | GET, PATCH | the account's defaults from its AGENTS.md frontmatter — `timezone`, `budget` (a USD cap — a number for a month, `"60/day"`, `"60/week"`, or `{ usd, period }`; null is no limit), `notify` (`{ url?, email?, events }`), `concurrency`, `compute` (`{ vcpu, memGiB, diskGiB }` — the account's own cap on what its running steps hold together, lower than the plan's; PATCH writes it as `compute: { vcpu, memory, disk }`, merged over what is set: a figure not sent is kept, `null` drops one, `compute: null` drops all), `deploy_block` (`none`, `secrets` or `security` — answered as `deployBlock`), `network_enforce` (answered as `networkEnforce`), `owner`, `alerts` (as written), `judge` (`{ model?, effort? }`), `telemetry` (`{ otlp, headers }` — header values are `${SECRET}` names; answered as `{ endpoint, headers }`); PATCH sets the keys sent, null clears one, and edits the file in place. To a caller scoped to some workspaces GET says these are set, never where they go: `notify` loses its `url` and carries `hidden: true` when one is set, and `telemetry` is `{ endpoint: "", headers: {}, hidden: true }`. PATCH needs every workspace |
375
380
  | `/api/audit?since&until&action&actor&workspace&limit&cursor&format` | GET | the account's audit log, newest first — the caller's account only, whatever a header, query or body names. The owner and unscoped admins (people, or `admin` keys); `audit:read`, and refused to a member or key scoped to some workspaces, because the log is the whole account's. `since`/`until`: `7d`, `24h`, `30m` or a date; `action`: exact (`apikey.created`) or a family (`apikey`); `actor`: exact (an email, `key:<label>`, `support:<email>`); `workspace`: entries about one; `limit` 1–1000 (100; 1000 for CSV); `cursor`: the `next` of the page before. JSON `{ entries: [{ id, at, actor, action, subject, detail }], next, retention }`; `format=csv` downloads the same rows (`x-next-cursor` header when there are more). Records sign-ins and refusals, sign-outs, session revokes, password and email changes, MFA on/off, key mint/rotate/revoke, invites, joins, role/scope changes, removals, ownership transfers, secrets set/deleted (by name — never a value), deploys, workspace deletes, plan and billing changes, export and close requests, and `support.viewed`/`support.ended`. The platform operator's own levers (`operator.*`) are the platform's record and not listed. Kept for the life of the account |
376
- | `/api/avatars/<kind>/<id>` | GET, PUT, DELETE | a picture for a `user` (their own id), a `workspace` (its name) or the `account` (the tenant). PUT the bytes of a PNG, JPEG or WebP under 1 MB; a person sets their own, an admin a workspace's or the account's. GET needs a signed-in tenant and is privately cached for a year — the URL's `?v=` changes with the picture |
381
+ | `/api/avatars/<kind>/<id>` | GET, PUT, DELETE | a picture for a `user` (their own id), a `workspace` (its name) or the `account` (the tenant). PUT the bytes of a PNG, JPEG or WebP under 1 MB; a person sets their own, an admin a workspace's or the account's. GET needs a signed-in tenant — a workspace's picture, a caller who may open that workspace (403 otherwise) — and is privately cached for a year — the URL's `?v=` changes with the picture |
377
382
  | `/api/search?q=` | GET | find anything in the account by name — workspaces, agents, flows, tools, skills, knowledge, memory, runs (by id, flow or headline); ranked, at most six per kind. The dashboard's Find palette reads it |
378
- | `/api/schedule` | GET, POST | GET: every scheduled flow with `valid` (the cron parses) and `upcoming` (the next three fires). POST: tick the scheduler now — install-wide, so `workspace:manage`; returns `{ ok, fired }` |
383
+ | `/api/schedule` | GET, POST | GET: every scheduled flow with `valid` (the cron parses) and `upcoming` (the next three fires). POST: tick the scheduler now for this account alone — its due cron, `once:` and watch flows go now (they were due anyway); `workspace:manage` over every workspace; returns `{ ok, fired }`. An impossible cron (`0 0 30 2 *`) is `valid` with `upcoming: []` |
379
384
  | `/api/library/<kind>?path=` | GET, POST, PUT, DELETE | account-level shared documents (`name`, `content`, `path`, `template`); DELETE `{ path }` removes one file or folder — `.` (the whole shelf) is refused |
380
385
  | `/api/library/gallery` | GET, POST | GET: every tool the platform ships to every account, whole (`tools: [{ name, kind, title, description, files: [{ kind, file, content }], installed }]`, `installed` being `current`, `differs` or null for this account's own copy) — what `foldrun gallery` reads and lays down on a laptop. POST: update an installed gallery tool to the version the platform ships (`tool`) — written through the revision log, so the previous copy is one revision back |
381
386
 
@@ -441,19 +446,19 @@ X-Foldrun-Cli: 0.6.0 # the CLI released with this version (absent
441
446
  | Route | Methods | |
442
447
  |---|---|---|
443
448
  | `/api/auth/signup` | POST | `email`, `password`, `account`, `invite`, `setup`. An install with `FOLDRUN_SETUP_TOKEN` set creates its first account only with `setup` equal to it (403 otherwise); once an account exists the token does nothing. Rate limited per address and per caller. With signups closed every address gets the same refusal, so the form cannot be used to discover which addresses are registered |
444
- | `/api/auth/login` | POST | `email`, `password` |
449
+ | `/api/auth/login` | POST | `email`, `password`. Wrong passwords are limited per account: 8 a quarter hour from one caller when a trusted proxy names the caller (`FOLDRUN_TRUST_PROXY`), so a stranger failing as someone locks out only themselves, and 40 from every caller together, reaching which mails the person; with no caller address, 8 per account from anyone. A 429 carries `Retry-After` |
445
450
  | `/api/auth/logout` | POST | ends the session |
446
451
  | `/api/auth/session` | GET | who am I |
447
452
  | `/api/auth/sessions` | GET, DELETE | list; revoke one (`id`) or the rest (`others`) |
448
453
  | `/api/auth/password` | POST | `current`, `next` — at least 10 characters, not your email, not in a known breach |
449
- | `/api/auth/email` | POST | `email`, `password` — ask to move your login to a new address. Nothing moves yet: that address is mailed a link, and clicking it makes the move, verifies the address, ends your other sessions and tells the old address. The answer (`pending: true`) is the same whether or not the address already has a login — if it does, the mail there says so instead. 5 a day. An install that sends no mail moves at once (`pending: false`) |
454
+ | `/api/auth/email` | POST | `email`, `password` — ask to move your login to a new address. Nothing moves yet: that address is mailed a link, and clicking it makes the move, verifies the address, ends your other sessions and tells the old address. The answer (`pending: true`) is the same whether or not the address already has a login — if it does, the mail there says so instead. 5 a day. An install that can send no mail (no platform mail key and no account `RESEND_API_KEY`/`EMAIL_FROM`) refuses with 409 `{ error, code: "mail_not_configured" }` saying how to set mail up — the login stays where it is |
450
455
  | `/api/auth/name` | POST | `firstName`, `lastName` — optional halves, null clears one; shown by email when empty |
451
- | `/api/auth/forgot` | POST | `email`. Always 200 with the same sentence, whatever the address; a reset link goes to the inbox if there is an account. 3 per address per hour |
456
+ | `/api/auth/forgot` | POST | `email`. Always 200 with the same sentence, whatever the address; a reset link goes to the inbox if there is an account. 3 per address per hour (a 429, the same for any address), 20 per caller per hour when a trusted proxy names the caller; and on the mail itself, a ceiling for the install per hour of which one caller may spend at most 10 — past either, the answer is the same sentence and no mail goes |
452
457
  | `/api/auth/reset` | POST | `token` (from the link), `password`. Works once and for 30 minutes; every other session of yours ends; signs you in |
453
458
  | `/api/auth/verify?token=` | GET | the link in the confirmation email — marks the address verified and lands on the dashboard. The link an email change mails moves the login here too, once, and not after a password change |
454
459
  | `/api/auth/verify/resend` | POST | send the confirmation again, to the signed-in person, 3 an hour |
455
460
  | `/api/auth/mfa/setup` | POST | start enrolling a second factor: `secret`, `uri`, a `qr` data URL, and an `enrol` token — nothing is stored yet |
456
- | `/api/auth/mfa/enable` | POST | `enrol`, `code` from the app. Stores the secret (sealed) and returns eight `backup` codes exactly once |
461
+ | `/api/auth/mfa/enable` | POST | `enrol`, `code` from the app. Stores the secret (sealed) and returns eight `backup` codes exactly once, and ends the person's other sessions as a password change does (`otherSessionsEnded`; this browser stays signed in) |
457
462
  | `/api/auth/mfa/verify` | POST | the second step of a sign-in: `challenge` (from `/api/auth/login` when it answered `mfa: true`) and `code` — six digits or a backup code. 6 tries per five minutes; after 10 wrong six-digit codes in a row they are paused for up to a day (a backup code still works) and the person is mailed. A 429 carries `Retry-After` |
458
463
  | `/api/auth/mfa/disable` | POST | `password` and `code` — a session alone is not enough to remove the second factor |
459
464
  | `/api/auth/timezone` | POST | `timezone` — what a cron expression means |
@@ -472,9 +477,9 @@ signed-in person, never by a key — mints an ordinary API key at their role.
472
477
  |---|---|---|
473
478
  | `/api/cli/login` | POST | `hostname` → `{ id, code, verifyUrl, expiresAt, interval }`. Open: there is no credential yet. Ten-minute lifetime |
474
479
  | `/api/cli/login/<id>` | GET | `{ status }` — `pending`, `denied`, `expired`, or `approved` with `token`, `account`, `email`, `role`. The key is returned once; the request is gone after |
475
- | `/api/cli/authorize` | GET, POST | `?code=` describes the request (machine, expiry). POST `{ code, decision }` from a session approves (mints the key, labelled `cli · <hostname>`, ending in 90 days — the CLI renews it itself before then, see `/api/keys/<id>/rotate`) or denies — `decision` is `approve` or `deny`, and absent approves; any other word is a `400`. Every role may sign its own CLI in; an owner's key is an admin's |
480
+ | `/api/cli/authorize` | GET, POST | `?code=` describes the request: machine, expiry, `createdAt`, `requestedFrom` (the asking network as an IPv4 /24 or IPv6 /48, from the trusted proxy — null when not known), `requestedCountry` (behind Cloudflare; else null), `sameNetwork` (whether the browser looking is on that network; null when either is not known) and `approveBy`. POST `{ code, decision }` from a session approves (mints the key, labelled `cli · <hostname>`, ending in 90 days — the CLI renews it itself before then, see `/api/keys/<id>/rotate`) or denies — `decision` is `approve` or `deny`, and absent approves; any other word is a `400`. A request more than five minutes old can no longer be approved (`410`; it can still be denied) — device-code phishing, RFC 8628 §5.4. Every role may sign its own CLI in; an owner's key is an admin's |
476
481
  | `/api/me` | GET | who is calling: `account`, `owner`, `role`, `workspaces` (null: all), and the `actor` — a person's email, or a key's id, label, prefix, who minted it, `expiresAt` (null: never) and `origin` (`cli-login` for a key `foldrun login` minted, else null) |
477
- | `/api/me/onboarding` | GET, PATCH | the account's getting-started steps, each derived from what is really there — `{ steps: [{ id, title, why, href, cli?, done }], done, total, complete, next, dismissed, dismissedAt }`. Steps: `model` (first; only for an account that must bring its own key — done once it has one, or a `provider:` block in the account's AGENTS.md), `workspace`, `agent` (an agent written or deployed after the workspace was made), `run`, `success` (a completed run), `secret`, `trigger` (a schedule or webhook), `teammate` (a second member), `billing` (hosted, not fully waived: a saved card or a plan), `cli` (any API key or CLI login). PATCH `{ dismissed: true or false }` hides or brings back the dashboard card for the signed-in person (kept in their prefs); a key reads `dismissed: false` and cannot PATCH |
482
+ | `/api/me/onboarding` | GET, PATCH | the account's getting-started steps, each derived from what is really there — `{ steps: [{ id, title, why, href, cli?, done }], done, total, complete, next, dismissed, dismissedAt }`. Steps: `model` (first; only for an account that must bring its own key — done once it has one, or a `provider:` block in the account's AGENTS.md), `workspace`, `agent` (an agent written or deployed after the workspace was made), `run`, `success` (a completed run), `secret`, `trigger` (a schedule or webhook), `teammate` (a second member), `billing` (hosted, not fully waived: a saved card or a plan), `cli` (any API key or CLI login). A caller scoped to some workspaces is answered over those workspaces alone — no other workspace's name is in a step's `href`. PATCH `{ dismissed: true or false }` hides or brings back the dashboard card for the signed-in person (kept in their prefs); a key reads `dismissed: false` and cannot PATCH |
478
483
  | `/api/me/inbox` | GET, POST | your inbox — what waits on you across the workspaces you may see. GET `{ person, items: [{ id, kind (approval, question, issue, proposal, run), bucket (mine, started, team), why, workspace, title, detail, at, href, read, dismissed }], counts: { mine, started, team, unread } }`, newest first. `mine` is assigned to you (named in `approvers:`, owner of the flow or agent, or you asked for the proposal); `started` is runs you started — failed or BLOCKED/BAD this week, a gate on one (someone else decides it), a question it asked; `team` is the rest that waits in your workspaces. By default `mine` and `started`; `?bucket=mine\|started\|team\|all`, `?kind=`, `?workspace=`, `?dismissed=1` for what you set aside. `counts.unread` is unread `mine` + `started`. POST `{ ids \| id, action: read\|unread\|dismiss\|restore }` changes your view only — dismissing never decides a gate or resolves an issue; ids name an occurrence, so a thing that happens again is new. A key acts for the person who minted it, inside the key's own scope; one no person minted is a `400` |
479
484
  | `/api/me/notifications` | GET, PATCH | what mail you get. GET `{ email, categories: [{ category, label, description, required, why?, perWorkspace, enabled, workspaces: { <ws>: bool } }] }` for `security`, `invites`, `billing`, `account` (required — always sent) and `run-alerts`, `approvals` (per workspace), `low-balance`, `product-updates`. PATCH `{ category, enabled, workspace? }` or `{ preferences: [ … ] }`; answers the same as GET. Turning a required category off is a `409` with the reason; `workspace` on an account-wide category is a `400`; `enabled: true` account-wide clears that category's per-workspace offs. A key acts for the person who minted it |
480
485
  | `/api/me/preferences` | GET, PATCH | your own display preferences: `{ theme, runViews }` — `theme` is `system` (the default: follow the computer's light or dark setting), `light` or `dark`; `runViews` your saved run searches, `[{ name, query }]` (see [Runs](runs#searching-runs)). PATCH `{ theme }` and/or `{ runViews }` (the whole list, at most 20, each query of the runs filters) answers the same; anything else is a `400`. Kept in your prefs, so it follows you to every browser; the dashboard applies it on the server, before the first paint. A key acts for the person who minted it; a key minted by nobody is a `400` |
@@ -498,7 +503,7 @@ signed-in person, never by a key — mints an ordinary API key at their role.
498
503
  |---|---|---|
499
504
  | `/api/hooks/<tenant>/<ws>/<flow>` | POST | run a flow from outside. The token may be sent as `Authorization: Bearer <token>`, as `X-Foldrun-Token`, or as `?token=` in the URL — in that order of preference, because a URL leaks into proxy logs, access logs and browser history while a header does not; the query string stays supported because most webhook senders have nowhere to put a header. The token is derived, not stored. A flow with `signature:` (github, stripe, slack, hmac) and `signing_secret:` also has the provider's HMAC checked — a Slack `url_verification` body is answered with its challenge and starts nothing; refused deliveries are logged as `invalid-signature`. The signature, `idempotency: body:` and `filter:` read the whole body; the run is handed its first 20,000 characters. Wrong tokens from one caller are limited (30 a minute, then `429`) where the install knows the caller's address (`FOLDRUN_TRUST_PROXY`), as for an inbox and an event URL |
500
505
  | `/api/inbox/<tenant>/<ws>/<flow>` | POST | the token as for a hook (`Authorization: Bearer`, `X-Foldrun-Token`, or `?token=`). An inbound email for a `trigger: email` flow — JSON (`from`, `to`, `subject`, `text` or `html`; Resend's `data` wrapper understood) or an inbound-parse form (Mailgun, SendGrid). Same token as the hook |
501
- | `/api/events/<tenant>/<ws>/<id>?token=` | POST | release a run parked on `wait: event`; the body becomes the step's event payload. The token is derived from the run id, and the URL is printed in the waiting step's trace. `409` when the run is not waiting on an event. Wrong tokens are limited per caller as a hook's are |
506
+ | `/api/events/<tenant>/<ws>/<id>?token=` | POST | release a run parked on `wait: event`; the body becomes the step's event payload. The URL is printed in the waiting step's trace and carries `&step=<index>`: its token is that step's, for that one park, so it releases that step only and a later `wait: event` of the same run gets its own URL. `409` once that gate is no longer waiting (released already, or parked again under a new URL). URLs printed before 30 Oct 2026 (no `step=`) still release a step parked under them. Wrong tokens are a `401`, limited per caller as a hook's are |
502
507
  | `/api/approve/<tenant>/<ws>/<id>?token=` | GET, POST | decide a run parked on a human, from the link in its notification. GET shows what is waiting and two buttons — it never decides, because inbox link-checkers follow GETs. POST `decision` (`approve` or `reject`) and an optional `note`, form-encoded or JSON; answers JSON when `Accept` prefers it. The token is derived from the run id under the install key, not stored, so a key rotation kills every link. Needs `FOLDRUN_PUBLIC_URL` to be minted at all |
503
508
  | `/api/workspaces/<ws>/hooks/<flow>` | GET | read the flow's webhook URL without changing it: `{ ok, flow, path, url }` — `path` carries the token, `url` is it made absolute with `FOLDRUN_PUBLIC_URL` (null when that is unset). `workspace:manage`, as rotate and the settings page that shows it, since the URL is a credential. `404` for no such flow, `409` for a flow that is not `trigger: webhook` |
504
- | `/api/workspaces/<ws>/hooks/<flow>/rotate` | POST | new token, old URLs stop working |
509
+ | `/api/workspaces/<ws>/hooks/<flow>/rotate` | POST | new token, old URLs stop working. `404` for no such flow, `409` for a flow that is not `trigger: webhook`, as GET `…/hooks/<flow>` answers |
package/docs/checks.md CHANGED
@@ -95,7 +95,10 @@ and the tool text of MCP servers reached by URL
95
95
  ([`content/mcp-tool-text`](#contentmcp-tool-text)).
96
96
 
97
97
  - **When you ask:** Checks → **Online checks**, `foldrun check --to <ws>
98
- --online`, or `GET /api/workspaces/<ws>/check?online=1`.
98
+ --online`, or `GET /api/workspaces/<ws>/check?online=1` — editor and
99
+ above, since it sends the platform out to OSV and your MCP servers. The
100
+ answer is kept for 10 minutes while the files are unchanged, and a
101
+ workspace gets six fresh online passes per 10 minutes.
99
102
  - **Every day by itself:** the platform rescans every workspace, offline and
100
103
  online. The first rescan of each source records what is there. After
101
104
  that, a security finding that was not there before goes to the
@@ -206,6 +209,20 @@ key**: it has already been copied, into git history if nowhere else.
206
209
  References (`${NAME}`, `$NAME`, `process.env.X`), names, and obvious samples
207
210
  (`your-key-here`, `xxxx`, AWS's `…EXAMPLE`) are not findings.
208
211
 
212
+ ### secret/signing-secret-value
213
+
214
+ *warn · ASI03.* A flow's `signing_secret:` or `notify: signing_secret:` holds
215
+ something that is not a secret's name. Both name a vault entry —
216
+ `signing_secret: GITHUB_WEBHOOK_SECRET` or `${GITHUB_WEBHOOK_SECRET}` — and
217
+ are looked up by that name. A value written there is never found, so every
218
+ signed delivery to the flow is refused and every notification goes out
219
+ unsigned, and the value itself is deployed and versioned in plain text.
220
+
221
+ Put it in the vault (`foldrun secrets set NAME`), write the name, and rotate
222
+ it. The finding never repeats the value, and neither does any answer that
223
+ shows the setting (notify's test send names the secret, or says it is not a
224
+ name).
225
+
209
226
  ### content/hidden-unicode
210
227
 
211
228
  *warn · ASI01, ASI04, ASI06.* Zero-width characters, bidirectional overrides
@@ -361,6 +378,15 @@ place in `@foldrun/core` (`frontmatter-fields.ts`). The editor's completions
361
378
  come from the same list, so what the editor suggests and what `check`
362
379
  accepts cannot drift apart.
363
380
 
381
+ ### config/cron-never-fires
382
+
383
+ *warn.* A `schedule:` the scheduler can read but whose day never comes:
384
+ `0 0 30 2 *` — every field is in range, and no February has a 30th. The flow
385
+ never runs and the schedule page lists no next run for it. Checked with the
386
+ scheduler's own rule (`cronCanFire` in `@foldrun/core`), so `check` and the
387
+ scheduler always agree. A day every named month has, or a weekday beside the
388
+ day (either then matches), fixes it.
389
+
364
390
  ### config/conflict
365
391
 
366
392
  *error.* A field written twice: at the top of the frontmatter and inside its
package/docs/cli.md CHANGED
@@ -42,7 +42,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
42
42
  | `foldrun check [dir]` | validate agents, flows, tools, evals, knowledge — offline. At an account root: every workspace, then the shared library. Includes each agent's colleagues: an `agents:` or `subagents:` name that is not an agent, a sub-agent with no `description:`, a sub-agent that would hold none of its tools inside its parent's. Signed in, it also asks the platform's open `/api/version` which Chrome its runner image has, and warns when a pinned `web.browse.user_agent:` claims another major ([why](tools#how-this-agents-browser-presents-itself)); it warns about the old `web.browse.session:` key too (now `vendor_session:`). Hooks: a `hooks/<name>/` folder that is not a valid hook (`on:`, `run.mjs` beside `hook.md`, `tool:` only on tool events, `timeout:` 1 to 120), and a `hooks:` name in an agent or an AGENTS.md that is in neither `hooks/` nor the library, are errors; a `tool.call` hook on an agent whose `web.search:` (or `web.fetch:`) the model provider runs on its own servers is a warning — those calls never reach the hook. It is also the security scanner: a credential written into any file, invisible Unicode, override phrases in knowledge and skills, an agent that reads the web while holding a secret and an open way out, `curl \| sh`, an MCP server at no fixed version, a typo of a frontmatter field. Every finding names its rule (`secret/hardcoded`, `agent/config`, …); see [Checks](checks) |
43
43
  | `foldrun check --security` | only the security rules (secret, security, content, supply-chain), exiting 1 on a warning. Also `--rule <id or category>` (repeatable), `--fail-on error\|warn\|info\|never`, `--format text\|json\|sarif` (`--json`; `--out <file>`), `--changed` (only files changed against git HEAD; `--base <ref>`), `--write-baseline` (accept today's findings into `.foldrun/check-baseline.json`; `--no-baseline`), `--rules` (list every rule). A `foldrun-ignore <rule>: <reason>` comment on the line before a finding silences it; the reason is required. [Checks](checks) |
44
44
  | `foldrun extract [dir]` | move each single-file script tool — a `tools/<name>.md` with its program in a fenced block — into a folder: `tools/<name>/tool.md` with `run:` pointing at `run.js`, `run.py` or `run.sh` beside it. Frontmatter is edited as text, never re-serialised, so the diff is only what moved. A tool that already has a folder is left for you; `--dry-run` lists what it would do |
45
- | `foldrun check --to <ws>` | validate the copy that is DEPLOYED, rather than the folder in front of you — a workspace edited through the API, by an agent or by `foldrun source put`, has had no way to be checked short of spending a run. The files are fetched into a temporary folder and the ordinary check runs over them, so there is one copy of the rules; the output names the workspace and the platform it checked. `--online` adds the network checks the platform runs: known vulnerabilities for exact runtime pins and remote MCP servers' tool text, and what could not be checked |
45
+ | `foldrun check --to <ws>` | validate the copy that is DEPLOYED, rather than the folder in front of you — a workspace edited through the API, by an agent or by `foldrun source put`, has had no way to be checked short of spending a run. The files are fetched into a temporary folder and the ordinary check runs over them, so there is one copy of the rules; the output names the workspace and the platform it checked. `--online` adds the network checks the platform runs: known vulnerabilities for exact runtime pins and remote MCP servers' tool text, and what could not be checked (an editor's key or above; the platform keeps the answer 10 minutes while the files are unchanged) |
46
46
  | `foldrun agent run <name>` | run one agent once on a platform, with no flow file: a flow of one step. `--task "…"` is the instruction and is required. Prints the run id and how to follow it; `--wait` holds on (in 25-second pieces, as `invoke` does) and then prints the same report `foldrun report` would; `--test` makes it a [test run](runs#test-runs) |
47
47
  | `foldrun agent link <agent>` | add to an agent's team, in its own frontmatter — `--subagent <worker>` (`subagents:`, a worker it delegates to), `--consult <agent>` (`agents:`, a colleague it asks) or `--can-ask` (`ask` in `tools:`, so it may ask you mid-step). The edit is core's, the one the canvas's docks make: only the lines of that one list change, flow style stays flow style, comments and the prose stay byte for byte. A sub-agent without a `description:` needs one, because the model picks a sub-agent by it — asked for at a terminal, `--description "…"` otherwise, and written into the worker's file first. `--isolated` also writes `sandbox: own` on the worker: each job it is handed runs in its own sandbox, with its own tools, secrets and network, not cut to the delegating agent's; its reply comes back with the files it wrote (`foldrun docs agents`). Says which flows use the agent ("used by 3 flows"), since the change reaches all of them. Prints the diff, and refuses an edit `foldrun check` would call an error; `--dry-run` writes nothing. In this folder by default (`--workspace <name>` in an account with several); `--to <workspace>` edits the deployed copy through `PATCH /api/workspaces/<ws>/agents/<name>`. In this folder it re-reads each file just before writing — after the description prompt, after `check` — and refuses, writing nothing to either file, when one changed since it was read |
48
48
  | `foldrun agent import <workspace>/<agent>` | copy an agent you already have in another workspace into this one: its `agent.md` and own `skills/`, `scripts/`, `knowledge/` — never `memory/`, `outputs/` or `state/`. Into the workspace you stand in, or `--workspace <name>`; `--as <name>` imports it under another name (and rewrites `name:`), which a name clash requires. `--to <workspace>` does it on the platform (`POST /api/workspaces/<ws>/agents/import`) and lists the tools, skills, scripts and secrets the copy uses that the workspace lacks. See [Importing an agent](workspaces#importing-an-agent-you-already-have) |
@@ -85,7 +85,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
85
85
  | `foldrun logs [run-id]` | recent runs in one workspace, or one run's whole event trail. `--local` reads this machine's store even when signed in; `foldrun runs --local` is the same command and prints the same thing |
86
86
  | `foldrun runs` | what has run lately across the whole account: when, workspace, flow, status, steps done, how long, the credits it was charged (its token cost in dollars until the ledger settles it) and the run's own one-line summary. A completed run shows its verdict beside the status — `GOOD`, `BAD`, `QUIET`, or `BLOCKED` in red with a ⛔ mark. `--status failed`, `--verdict blocked`, search by what happened inside (`--tool web`, `--tool-error`, `--agent`, `--model haiku`, `--min-tokens 50k`, `--min-secs 120`, or `--view <name>` for a saved one — `foldrun runs views` lists yours), `--outcome blocked,failed` (the dashboard's word; `needs-you` is `waiting`), `--since 24h`, `--to <workspace>`, `--limit <n>`. `--local` prints exactly what `logs --local` prints — this machine's runs, one workspace |
87
87
  | `foldrun runs doctor <run-id>` | the run doctor: the assistant reads a failed run and the files it names, says why (platform, check, work or outside), and proposes the fix as diffs, saved on yes — the run page's **Doctor** (`--to`, `--yes`, `--dry-run`, `--json`). Charged like one assistant reply |
88
- | `foldrun runs rm <run-id>` | erase a run from history: its record and its archived outputs. A run still in flight is stopped first. The ledger line stays — money is not deleted because a trace was. Asks first; `--yes` with no terminal |
88
+ | `foldrun runs rm <run-id>` | erase a run from history: its record and its archived outputs. A run still in flight is stopped first. The ledger line stays — money is not deleted because a trace was. Needs an admin (`workspace:manage`). Asks first; `--yes` with no terminal |
89
89
  | `foldrun report <run-id>` | one run, whole, without opening the dashboard: the header, then every step with its group, agent, attempts, the runner image it ran on (`slim · browser pod` when it browsed through the account's pod from slim), cost, how much of its input the prompt cache served (`90% cached`; nothing for a step recorded before 18 Oct 2026) and, under a step that wrote a fifth or more of its input to the cache, why (`prompt cache: 75% of input written to the cache — memory changed since step 1`), how many model turns it took, duration, what happened to the browser pod under it (reconnects, `browser pod lost; re-ran on full` with its tries — `slim · lost` then `full` — or why it was not re-run), whether its `verify:` held and the first line of what it said — and for a failed step, the error and the last events before it. Then what it wrote, what it published and what is still waiting on a person. `--json` prints the run record instead |
90
90
  | `foldrun report <run-id> --compare [<run-id>]` | this run beside the flow's [last good run](runs#compare-with-the-last-good-run), or the one named: whether they ran the same files and which changed, then what differs step by step (status, new errors, instruction, model, tools, time, tokens). `--json` |
91
91
  | `foldrun report <run-id> --tree` | the run as [one tree](runs#the-trace-tree): each step, each model call (model, tokens, why it stopped) and each tool call under the call that asked for it, with how long each took and `← what went wrong` on the first failure. `--json` gives the tree and the failure path |
@@ -127,7 +127,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
127
127
  | `foldrun invoke <flow>` | start a flow on a running platform — `--watch` follows its trace here; `--test` makes it a [test run](runs#test-runs) `--once <key>` sends the key as the run's idempotency key, so a CI step that retries after a dropped response is answered with the run it already started instead of paying for a second. `--tag <t>`, repeatable, labels the run (the API's `tags`). `--inputs <name>` sends a saved input set as the task — a case of `evals/<flow>-inputs.md` or of an eval that runs the flow, as the platform has it (see [Run with saved inputs](flows#run-with-saved-inputs)). `foldrun flow run <flow>` is the same command |
128
128
  | `foldrun source <verb>` | one workspace file on a platform: `ls [dir]`, `cat <path>`, `put <path>` (from `--file`, else stdin; `--message` goes on the revision), `new <kind> <name>`, `mv <from> <to>`, `rm <path>` — the editor's own door, so every write is a revision. `new` is the dashboard's New button for any document (`POST …/assets { kind, name, agent?, template?, language? }`): `tools`, `knowledge`, `memory`, `skills`, `scripts` (and `agents`, `flows`, `evals`), the template written by the platform; `--agent <name>` puts a knowledge, memory, skill or script document inside that agent. For a whole tree, `deploy` |
129
129
  | `foldrun open [page]` | the dashboard for this workspace, in the browser (`runs`, `agents`, `graph`, `repo`…) |
130
- | `foldrun login` | sign this machine in from the browser — no key to copy |
130
+ | `foldrun login` | sign this machine in from the browser — no key to copy. Type the code it shows on the page and approve within five minutes |
131
131
  | `foldrun login <site> --url <address>` | a browser window to sign in to a site by hand; the session is stored for an agent |
132
132
  | `foldrun logout` | forget this machine's key, and revoke it if `login` made it |
133
133
  | `foldrun whoami` | who you are on the platform: account, role, which workspaces |
@@ -141,7 +141,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
141
141
  | `foldrun changelog` | What's new: first the API — its current version, the breaking changes each dated version brought, and the routes deprecated with their sunset dates — then the platform's release notes, newest first — features, fixes, docs — and which release this install runs (`GET /api/changelog`; `--limit <n>` up to 50, `--json`) |
142
142
  | `foldrun version` | this CLI's version, its `@foldrun/core`'s, and — when a platform is known (`--url`, `--profile`, `FOLDRUN_URL` or where you signed in) — that platform's: version, release time, API version, each component's commit and the browsers its runner image has (with versions where known: `chrome 154.0.8037.58`), from `GET /api/version` (no key needed). Warns when the platform was released with a newer CLI than this one. An unreachable platform is a dim line, not a failure. `--json` prints `{ cli, core, platform }`. `foldrun --version` (or `-v`) prints only the CLI's version, offline. See [Versions and releases](versions) |
143
143
  | `foldrun doctor` | check the road to the platform, one line each: Node (22 or newer), the CLI and core versions, which of `FOLDRUN_URL`, `FOLDRUN_TOKEN`, `FOLDRUN_TIMEOUT`, `HTTPS_PROXY` are set (never their values), which model credential a local run would use (by its variable, never its value), the account it would act as, DNS for the platform's host, and a timed `GET /api/healthz`. The first thing to run when a command cannot reach the platform |
144
- | `foldrun storage <verb>` | what a workspace PRODUCED, as opposed to what you wrote — `source` is the other half. `ls [prefix]` lists every file with its size, when it was written, how long ago and which run wrote it (`run:<id>`, `user:<email>` for an upload, `api-key` for a key), newest first, plus what the store holds against its quota. `cat <path>` prints a text file and refuses one that is not text; `cat <path> --preview` asks the platform to read it instead and prints what is in it — a PDF or Word document as paragraphs, a spreadsheet or CSV as a table, a deck as slides, an archive as its listing. `get <path>` downloads it beside you — `--file <path>` names somewhere else, `--force` overwrites. `put <file|folder>...` uploads any files, of any type, into storage under their own names, walking folders whole (`.git`, `node_modules` and `.DS_Store` are skipped); `--into <folder/>` puts them under a folder, `--as <path>` renames a single file, and large files go straight to the bucket by a presigned URL, so size is not capped by the platform's request limit; `rm <path>` removes one. `share <path>` mints a public link to one produced file (7 days; `--ttl <days>`, `--forever`) and prints the URL; `shares` lists the live links (`--all` includes expired and revoked); `unshare <token>` revokes one — the link answers 404 from then on and the token is never reused. `--to <workspace>` from anywhere; inside a workspace folder it is already known |
144
+ | `foldrun storage <verb>` | what a workspace PRODUCED, as opposed to what you wrote — `source` is the other half. `ls [prefix]` lists every file with its size, when it was written, how long ago and which run wrote it (`run:<id>`, `user:<email>` for an upload, `api-key` for a key), newest first, plus what the store holds against its quota. `cat <path>` prints a text file and refuses one that is not text; `cat <path> --preview` asks the platform to read it instead and prints what is in it — a PDF or Word document as paragraphs, a spreadsheet or CSV as a table, a deck as slides, an archive as its listing. `get <path>` downloads it beside you — `--file <path>` names somewhere else, `--force` overwrites. `put <file|folder>...` uploads any files, of any type, into storage under their own names, walking folders whole (`.git`, `node_modules` and `.DS_Store` are skipped); `--into <folder/>` puts them under a folder, `--as <path>` renames a single file, and large files go straight to the bucket by a presigned URL, so size is not capped by the platform's request limit; `rm <path>` removes one. `share <path>` mints a public link to one produced file (7 days; `--ttl <days>`, `--forever`) and prints the URL; `shares` lists the live links (`--all` includes expired and revoked); `unshare <token|id>` revokes one — the link answers 404 from then on and the token is never reused. Only an admin, or the person who made a link, sees its token; anyone else sees the link with its token masked and an id (`sh_…`) to unshare it by. `--to <workspace>` from anywhere; inside a workspace folder it is already known |
145
145
  | `foldrun runtimes` | the environments a deployed workspace's agents need — each distinct `runtime:` (an agent's own merged with its tools'), the packages in it, which agents use it, and whether the platform has built it: ready, building, or failed with the installer's own error. `foldrun deploy` prints the same thing after a deploy and waits up to two minutes for builds in progress (`--no-runtimes` skips the wait); this asks again later, and `--wait` holds on while any is building. Exits 1 when one has failed. `--to <workspace>` from anywhere |
146
146
  | `foldrun schedule` | every flow in the account whose `trigger:` is a clock: workspace, flow, the cron line, its timezone, how many steps, whether the scheduler can parse it, and the next three times it fires. The times are the point — `0 5 1-7 * 5` reads as "the first Friday" and fires eight times in twenty-eight days, because day-of-month and day-of-week are OR'd. Exits 1 if any line is unparseable, since an invalid schedule errors nowhere and simply never runs. `--to <workspace>` narrows it |
147
147
  | `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 |
package/docs/flows.md CHANGED
@@ -328,7 +328,7 @@ normal outcome, recorded as one.
328
328
  | `after` / `on` | the flow to chain on, and whether on `completed` (default), `failed`, `blocked` or `any` |
329
329
  | `path` | the `storage/` prefix to watch, for `trigger: storage` |
330
330
  | `url` / `every` | what to poll and how often (default 15m), for `trigger: watch` |
331
- | `signature` / `signing_secret` | `github` \| `stripe` \| `slack` \| `hmac`, and the vault entry to check it against |
331
+ | `signature` / `signing_secret` | `github` \| `stripe` \| `slack` \| `hmac`, and the NAME of the vault entry to check it against — never the value (`foldrun check` warns: [secret/signing-secret-value](checks#secret-signing-secret-value)) |
332
332
  | `filter` | for a `webhook`, `email`, `flow` or `storage` trigger: the fields a delivery must have to start a run — see [Which deliveries start a run](#which-deliveries-start-a-run) |
333
333
  | `model` / `effort` | defaults for every step |
334
334
  | `budget` | the most one run may spend, in USD — a number, or `unlimited`; unset is no limit |
@@ -175,7 +175,8 @@ destination and reports what came back, including the provider's own words
175
175
  on a failure. Those words are the value: "domain not verified" and "you can
176
176
  only send to your own address" send you to two different pages, and a status
177
177
  code sends you to neither. `POST /api/workspaces/<ws>/notify/test` is the
178
- same thing.
178
+ same thing. A workspace gets 10 test sends an hour; past that the button
179
+ says to wait.
179
180
 
180
181
  ## Where it is set, and the rule that bites
181
182
 
package/docs/runs.md CHANGED
@@ -304,7 +304,9 @@ run until a person decides. Three doors open it, and the trace says which:
304
304
  - **the emailed link** — the notification carries approve and reject links
305
305
  when the install has a public URL;
306
306
  - **an external event** — a `wait: event` step is released by a POST to the
307
- run's event URL, and what was posted reaches the next step. A person can
307
+ event URL printed in its trace, and what was posted reaches the next step.
308
+ The URL is that step's, for that one wait: it does not release a later
309
+ `wait: event` of the same run, and once used it answers `409`. A person can
308
310
  release it the same way from the run page (or `approve` with a `payload`):
309
311
  the payload reaches the step just the same, and the trace names them, not
310
312
  "an external event". The approvers and self-approval rules below are for
package/docs/secrets.md CHANGED
@@ -72,6 +72,57 @@ Put a credential at the account when every workspace should use the same one
72
72
  — your model provider, your email sender. Put it in a workspace when it is
73
73
  that job's — a customer's Search Console, a CRM key.
74
74
 
75
+ ### Limited to some workspaces
76
+
77
+ An account secret is open to every workspace by default. To share one
78
+ credential with a few workspaces but not the rest — the way GitHub limits an
79
+ organisation secret to selected repositories — limit it:
80
+
81
+ ```sh
82
+ foldrun secrets set STRIPE_KEY --account --workspaces sales,billing # a new one, limited from the start
83
+ foldrun secrets workspaces STRIPE_KEY sales billing # only these two
84
+ foldrun secrets workspaces STRIPE_KEY # which may use it
85
+ foldrun secrets workspaces STRIPE_KEY --none # no workspace
86
+ foldrun secrets workspaces STRIPE_KEY --all # every workspace again
87
+ ```
88
+
89
+ In the dashboard it is **Workspaces: all / selected** on the secret's row in
90
+ Settings → Secrets, and on the form that adds one; over the API,
91
+ `PATCH /api/secrets { name, workspaces }` (`null` for every workspace, `[]`
92
+ for none), or `workspaces` on the `PUT` that stores the value. Given with the
93
+ value, the two are saved in one write: the secret is never open to every
94
+ workspace in between. "All" includes workspaces made later. Every other workspace finds the
95
+ secret **not set**, exactly as if it had never been stored: a run reports it
96
+ missing, a tool test and a `notify:` or `telemetry:` header leave
97
+ `${NAME}` unfilled, the egress proxy has nothing to fill, an MCP server does
98
+ not get it, a notification email it sends does not go out through the
99
+ account's `RESEND_API_KEY` or `EMAIL_FROM` (the platform's sender is used, if
100
+ there is one), and the workspace's secret list and the editor's completions
101
+ leave it out. A workspace's own secret of the same name still works there.
102
+
103
+ A limit applies to runs that **start after it**. A run already going keeps
104
+ what it was given when it started — values in its sandbox, and the ones the
105
+ egress proxy fills for it — so stop a running one to cut it off at once.
106
+
107
+ The names must be workspaces that exist. Renaming a workspace carries its
108
+ place on every list; deleting one takes it off first, so a new workspace
109
+ given the old name inherits nothing. If a secret limited to it cannot be read
110
+ with the platform's keys, the rename or delete is refused and names it — set
111
+ it again or delete it, then try again. Only an admin with access to every
112
+ workspace sets the limit, and the account's `RESEND_API_KEY` and `EMAIL_FROM`
113
+ stay the owner's. The account's own uses of a secret — its model key in
114
+ Settings → Model, and the mail the platform sends for the account (password
115
+ resets, invites, billing) — are not a workspace's and are not limited. A new
116
+ value or a new site binding keeps the limit. Limiting a secret seals the list
117
+ with the value, like `sites` (see [How they are kept](#how-they-are-kept)),
118
+ whatever form the secret was stored in before: a list changed on disk makes
119
+ the secret unreadable, never open to everyone.
120
+
121
+ On a platform you run yourself, set limits only once every pod — web,
122
+ worker and egress proxy — runs a version that has them: an older one cannot
123
+ read a limited secret, and one that stores a new value over it drops the
124
+ limit.
125
+
75
126
  ## How an agent gets it
76
127
 
77
128
  ```yaml
package/docs/security.md CHANGED
@@ -167,25 +167,41 @@ Signing in, in particular:
167
167
  - a password reset or change, two-step sign-in turned on or off, and a new
168
168
  API key each send a notice to the person's address;
169
169
  - signing out ends the session on the server, not just in the browser;
170
+ - changing your password or login address, or turning two-step sign-in
171
+ on, signs out every other browser;
170
172
  - a two-step code works once; replacing a second factor means turning it
171
173
  off first, which needs the password and a code;
174
+ - wrong passwords are counted per account and per caller: someone failing
175
+ as you locks out only their own address, never yours; a guesser spread
176
+ over many addresses meets a ceiling for the account, and you are mailed
177
+ when it is reached (this needs `FOLDRUN_TRUST_PROXY`, so callers can be
178
+ told apart — without it the count is per account, from anyone);
179
+ - a password reset mails at most three links an hour to one address, and
180
+ one caller can use at most a small share of the install's hourly reset
181
+ mail, so nobody can spend everyone else's;
172
182
  - ten wrong two-step codes in a row pause codes from the app for up to a
173
183
  day and mail the person — a backup code still signs in, and the pause
174
184
  lifts by itself;
175
185
  - changing your login address only mails the new address a link, and the
176
186
  move happens when that link is clicked; asking answers the same whether
177
187
  or not the address already has a login, so it cannot be used to find out
178
- who has an account;
188
+ who has an account. An install that can send no mail refuses the change
189
+ until mail is set up, rather than moving the login unconfirmed;
179
190
  - the sign-in forms refuse a request from another site, and `?next=` only
180
191
  ever leads to a page on the same site;
181
192
  - `foldrun login` asks you to type the code your terminal shows — a link
182
193
  with the code in it, sent by someone else, cannot sign their machine in
183
- as you;
194
+ as you. The page shows when and from which network the terminal asked,
195
+ warns when that is not the network you are on, and a request more than
196
+ five minutes old can no longer be approved;
184
197
  - before the first sign-up, a self-hosted install's setup token guards key
185
198
  minting as it guards sign-up;
186
199
  - only the account's owner can set, rebind or remove the account's
187
200
  `RESEND_API_KEY` and `EMAIL_FROM`, because that sender carries everyone's
188
- reset links — whether through the secrets API or an OAuth connect;
201
+ reset links — whether through the secrets API or an OAuth connect. The
202
+ owner means the owner in person: their signed-in session, or the key
203
+ their own `foldrun login` made. Any other key they minted (CI, a key
204
+ handed to a contractor) is refused;
189
205
  - a key rotated by a caller that is no person (a key known only by its
190
206
  label) acts as nobody, never as the rotated key's owner;
191
207
  - a member or key limited to some workspaces cannot change what every
@@ -66,7 +66,7 @@ the terminal:
66
66
  ```
67
67
  foldrun storage share cover.jpg --to <ws> # 7 days; --ttl 30, or --forever
68
68
  foldrun storage shares --to <ws> # live links; --all shows expired and revoked
69
- foldrun storage unshare <token> --to <ws>
69
+ foldrun storage unshare <token|id> --to <ws>
70
70
  ```
71
71
 
72
72
  - Links expire in **7 days** unless you say otherwise; `null` never expires.
@@ -76,6 +76,11 @@ foldrun storage unshare <token> --to <ws>
76
76
  into sharing is confined to what the workspace produced and can never hand
77
77
  out `memory/`, a prompt, or a credential.
78
78
  - Revoking is permanent; a re-share mints a new token.
79
+ - Revoking takes effect at once: a link is served `Cache-Control: private,
80
+ no-store`, so no CDN keeps answering it after a revoke or its expiry.
81
+ - Only an admin, or the person who made a link, sees its token and can copy
82
+ it. Everyone else sees that the file is shared, by whom and until when;
83
+ an editor can still revoke it (by its id).
79
84
  - Deleting a workspace revokes its links and deletes its stored files.
80
85
  Renaming one moves both: its links keep working, under the new name.
81
86
  - A link answers at most 120 requests a minute to one caller (where a trusted
@@ -11,16 +11,37 @@ whose supervisors cannot see what the agents did is not supervised.
11
11
  |---|---|
12
12
  | **viewer** | read everything — workspaces, runs and their output, files, history, usage |
13
13
  | **editor** | + edit files, upload, deploy (to a workspace that exists — a deploy that makes one is an admin's), push; run, stop, re-run, approve and promote runs; test tools |
14
- | **admin** | + create and delete workspaces; write secrets and connect credentials; mint keys; invite, re-role and remove editors and viewers |
14
+ | **admin** | + create and delete workspaces; delete a run from history; write secrets and connect credentials; mint keys; invite, re-role and remove editors and viewers |
15
15
  | **owner** | + billing; make and unmake admins; transfer the account |
16
16
 
17
17
  There is exactly one owner: the account's creator until they transfer it.
18
- The owner is never re-roled or removed — transfer first. Nobody changes their
18
+ Transferring asks for the owner's password again, and a code from their app
19
+ when two-step sign-in is on — a session left open is not enough to give the
20
+ account away. The owner is never re-roled or removed — transfer first. Nobody changes their
19
21
  own role, and an admin cannot make or remove another admin: an admin who can
20
22
  promote peers is an owner with extra steps.
21
23
 
22
24
  A refused call answers `403` with the role that was needed.
23
25
 
26
+ ### A workspace's policy is an admin's
27
+
28
+ The keys in a workspace's `AGENTS.md` that set policy for the whole
29
+ workspace — `budget`, `compute`, `notify`, `network_enforce`, `telemetry`,
30
+ `alerts`, `owner`, `judge` and `timezone` (also when written under a
31
+ `governance:`, `guardrail:`, `observability:` or `evaluation:` block) — need
32
+ the **admin** role to change, whichever way the file is written: the
33
+ workspace's settings, a save in the editor (`PUT …/source`), `foldrun deploy`,
34
+ an import, or a restore to an older point. An editor still edits the rest of
35
+ `AGENTS.md` — its prose and every other key — and may deploy, import or
36
+ restore anything that leaves those keys as they are; a change to one of them
37
+ is refused with a `403` that names the key, and nothing is written. Removing
38
+ the file, or saving one whose frontmatter does not parse, drops the keys, so
39
+ it counts as a change too. A dry run (deploy, import, restore) is not
40
+ refused.
41
+
42
+ The account's own `AGENTS.md` is written only through the account's settings
43
+ (`PATCH /api/account`), which needs an admin with access to every workspace.
44
+
24
45
  ## Scoped members
25
46
 
26
47
  A member can be limited to some workspaces. The customer whose desk lives in
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "foldrun",
3
- "version": "10.0.0",
3
+ "version": "10.1.0",
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",
package/src/commands.mjs CHANGED
@@ -3270,6 +3270,82 @@ async function localSetSites(name, sites, scope) {
3270
3270
  return k.setSecretSites("default", name, sites, scope);
3271
3271
  }
3272
3272
 
3273
+ /** The workspaces this machine's vault serves: an account folder's, or the
3274
+ * one folder a flat workspace is — what a local limit may name, as the
3275
+ * platform allows only workspaces that exist. */
3276
+ function localWorkspaceNames(layout) {
3277
+ if (layout?.kind === "account") return layout.workspaces;
3278
+ return [path.basename(process.env.FOLDRUN_WORKSPACE ?? process.cwd())];
3279
+ }
3280
+
3281
+ /** A core from before the limit would take the list as an argument it does
3282
+ * not know and store the secret open to every workspace: refused instead.
3283
+ * Typed loosely: the installed core's types may predate the limit, which is
3284
+ * exactly the case the check below refuses at run time.
3285
+ * @returns {Promise<any>} */
3286
+ async function limitingCore() {
3287
+ /** @type {any} */
3288
+ const k = await core();
3289
+ if (typeof k.setSecretWorkspaces !== "function") throw new Error("limiting a secret to workspaces needs a newer @foldrun/core — update foldrun");
3290
+ return k;
3291
+ }
3292
+
3293
+ /** Limit an account secret on this machine's vault. */
3294
+ async function localSetWorkspaces(name, workspaces, layout) {
3295
+ const known = localWorkspaceNames(layout);
3296
+ return (await limitingCore()).setSecretWorkspaces("default", name, workspaces, { exists: (w) => known.includes(w) });
3297
+ }
3298
+
3299
+ /** `--workspaces a,b` (or `--none`) on `secrets set`: the limit sent with
3300
+ * the value, so the secret is never open to every workspace in between.
3301
+ * Undefined when neither was given. */
3302
+ function workspacesFlag(flags) {
3303
+ if (flags.none === true && flags.workspaces !== undefined) throw new Error("either --workspaces or --none, not both");
3304
+ if (flags.none === true) return [];
3305
+ if (flags.workspaces === undefined) return undefined;
3306
+ if (typeof flags.workspaces !== "string") throw new Error("--workspaces takes the names: --workspaces sales,ops");
3307
+ const list = flags.workspaces.split(",").map((v) => v.trim()).filter(Boolean);
3308
+ if (!list.length) throw new Error("--workspaces takes the names: --workspaces sales,ops (--none for no workspace)");
3309
+ return list;
3310
+ }
3311
+
3312
+ /**
3313
+ * `foldrun secrets workspaces NAME [workspace…] [--all | --none]` — which
3314
+ * workspaces may use an ACCOUNT secret: every one (the default), only those
3315
+ * named (GitHub's "selected repositories" for an organisation secret), or
3316
+ * none. Every other workspace finds it not set. No names and no flag prints
3317
+ * what it is now. On the platform (PATCH /api/secrets { name, workspaces },
3318
+ * an admin over every workspace), or this machine's vault with --local —
3319
+ * where, as on the platform, only workspaces that exist may be named.
3320
+ */
3321
+ async function secretWorkspacesCmd(args, flags, url, layout) {
3322
+ const [name, ...rest] = args;
3323
+ if (!name) throw new Error("which secret? `foldrun secrets workspaces NAME [workspace …]`, `--all` for every workspace, `--none` for none");
3324
+ const named = rest.flatMap((v) => v.split(",")).map((v) => v.trim()).filter(Boolean);
3325
+ if ([flags.all === true, flags.none === true, named.length > 0].filter(Boolean).length > 1) {
3326
+ throw new Error("one of: workspace names, --all, or --none");
3327
+ }
3328
+ const describe = (list) =>
3329
+ list === null || list === undefined
3330
+ ? `${c.bold(name)} may be used in every workspace`
3331
+ : list.length
3332
+ ? `${c.bold(name)} may be used only in ${list.join(", ")} — every other workspace finds it not set`
3333
+ : `${c.bold(name)} may be used in no workspace`;
3334
+ if (!named.length && flags.all !== true && flags.none !== true) {
3335
+ const entries = url ? (await remoteCall(url, flags, "/api/secrets")).secrets : (await core()).listSecrets("default");
3336
+ const hit = entries.find((s) => s.name === name && s.scope === "account");
3337
+ if (!hit) throw new Error(`no secret ${name} in the account — this limits an account secret; a workspace's own is that workspace's already`);
3338
+ console.log(`\n ${describe(hit.workspaces)}${hit.workspaces ? "" : c.dim(` — limit it: foldrun secrets workspaces ${name} <workspace> …`)}\n`);
3339
+ return 0;
3340
+ }
3341
+ const workspaces = flags.all === true ? null : flags.none === true ? [] : named;
3342
+ const stored = url
3343
+ ? (await remoteCall(url, flags, "/api/secrets", { method: "PATCH", body: JSON.stringify({ name, workspaces }) })).workspaces
3344
+ : await localSetWorkspaces(name, workspaces, layout);
3345
+ console.log(`\n ${c.green("✓")} ${describe(stored)}\n`);
3346
+ return 0;
3347
+ }
3348
+
3273
3349
  /** `--site a.com --site "*.b.org"` or `--site a.com,b.org`, as one list. */
3274
3350
  function siteFlags(flags) {
3275
3351
  const raw = flags.site === undefined ? [] : Array.isArray(flags.site) ? flags.site : [flags.site];
@@ -3281,6 +3357,9 @@ async function secretsCmd(positional, flags, layout) {
3281
3357
  // hatch deploy and keys have. Without it, a signed-in laptop sent every
3282
3358
  // secret to the platform and the local store could not be reached at all.
3283
3359
  const url = flags.local === true ? undefined : remoteUrl(flags);
3360
+ // An account secret's workspaces: always the account's store, so no
3361
+ // workspace is asked for (or taken from the folder).
3362
+ if (positional[0] === "workspaces") return secretWorkspacesCmd(positional.slice(1), flags, url, layout);
3284
3363
  // The scope is the workspace's own store, named the way the runner names
3285
3364
  // it — the folder's basename. It was the literal string "workspace", so a
3286
3365
  // secret set from the terminal landed under workspaces/workspace/ and every
@@ -3306,7 +3385,7 @@ async function secretsCmd(positional, flags, layout) {
3306
3385
  console.log();
3307
3386
  for (const s of entries) {
3308
3387
  console.log(
3309
- ` ${c.bold(s.name)} ${c.dim(`${s.scope}${s.shadowed ? " · shadowed" : ""} · ${s.updatedAt ?? ""}${s.sites?.length ? ` · sent only to ${s.sites.join(", ")}` : ""}`)}`,
3388
+ ` ${c.bold(s.name)} ${c.dim(`${s.scope}${s.shadowed ? " · shadowed" : ""} · ${s.updatedAt ?? ""}${s.sites?.length ? ` · sent only to ${s.sites.join(", ")}` : ""}${Array.isArray(s.workspaces) ? ` · ${s.workspaces.length ? `only in ${s.workspaces.join(", ")}` : "in no workspace"}` : ""}`)}`,
3310
3389
  );
3311
3390
  }
3312
3391
  console.log();
@@ -3367,12 +3446,26 @@ async function secretsCmd(positional, flags, layout) {
3367
3446
  }
3368
3447
 
3369
3448
  if (verb === "set") {
3449
+ // --workspaces a,b / --none: an ACCOUNT secret limited to those
3450
+ // workspaces, sent with the value so it is never open in between.
3451
+ const limitTo = workspacesFlag(flags);
3452
+ if (limitTo !== undefined && scope) throw new Error("--workspaces limits an account secret — add --account (a workspace's own secret is that workspace's already)");
3453
+ const withLimit = limitTo !== undefined ? { workspaces: limitTo } : {};
3454
+ /** @returns {Promise<{ k: any, limit: object }>} — typed loosely, as limitingCore is. */
3455
+ const localLimit = async () => {
3456
+ if (limitTo === undefined) return { k: await core(), limit: {} };
3457
+ const known = localWorkspaceNames(layout);
3458
+ return { k: await limitingCore(), limit: { workspaces: limitTo, exists: (w) => known.includes(w) } };
3459
+ };
3370
3460
  // --kind: the other shapes the Connections form stores — a file, an SSH
3371
3461
  // login, API headers, a service account's key, a client-credentials app.
3372
3462
  if (typeof flags.kind === "string") {
3373
3463
  const { body, local } = await secretOfKind(flags.kind, flags);
3374
- if (url) await remoteCall(url, flags, "/api/secrets", { method: "PUT", body: JSON.stringify({ name, ...body, workspace: scope }) });
3375
- else local(await core(), name, body, scope);
3464
+ if (url) await remoteCall(url, flags, "/api/secrets", { method: "PUT", body: JSON.stringify({ name, ...body, workspace: scope, ...withLimit }) });
3465
+ else {
3466
+ const { k, limit } = await localLimit();
3467
+ local(k, name, body, scope, limit);
3468
+ }
3376
3469
  console.log(`\n ${c.green("✓")} ${name} stored as ${flags.kind}${url ? "" : " on this machine"} — declare it in agent.md under \`secrets:\` to use it\n`);
3377
3470
  return 0;
3378
3471
  }
@@ -3389,10 +3482,11 @@ async function secretsCmd(positional, flags, layout) {
3389
3482
  if (url) {
3390
3483
  await remoteCall(url, flags, "/api/secrets", {
3391
3484
  method: "PUT",
3392
- body: JSON.stringify({ name, oauth2: config, workspace: scope }),
3485
+ body: JSON.stringify({ name, oauth2: config, workspace: scope, ...withLimit }),
3393
3486
  });
3394
3487
  } else {
3395
- (await core()).setOAuth2Secret("default", name, config, scope);
3488
+ const { k, limit } = await localLimit();
3489
+ k.setOAuth2Secret("default", name, config, scope, limit);
3396
3490
  }
3397
3491
  console.log(`\n ${c.green("✓")} ${name} stored as an auto-refreshing oauth2 credential\n`);
3398
3492
  return 0;
@@ -3405,14 +3499,15 @@ async function secretsCmd(positional, flags, layout) {
3405
3499
  if (url) {
3406
3500
  await remoteCall(url, flags, "/api/secrets", {
3407
3501
  method: "PUT",
3408
- body: JSON.stringify({ name, value, workspace: scope, ...(sites.length ? { sites } : {}) }),
3502
+ body: JSON.stringify({ name, value, workspace: scope, ...(sites.length ? { sites } : {}), ...withLimit }),
3409
3503
  });
3410
3504
  } else {
3411
- const k = await core();
3412
- k.setSecret("default", name, value, scope);
3505
+ const { k, limit } = await localLimit();
3506
+ k.setSecret("default", name, value, scope, undefined, limit);
3413
3507
  if (sites.length) await localSetSites(name, sites, scope);
3414
3508
  }
3415
- console.log(`\n ${c.green("✓")} ${name} stored${sites.length ? ` and sent only to ${sites.join(", ")}` : ""} — declare it in agent.md under \`secrets:\` to use it\n`);
3509
+ const limited = limitTo === undefined ? "" : limitTo.length ? `, only for ${limitTo.join(", ")}` : ", for no workspace yet";
3510
+ console.log(`\n ${c.green("✓")} ${name} stored${sites.length ? ` and sent only to ${sites.join(", ")}` : ""}${limited} — declare it in agent.md under \`secrets:\` to use it\n`);
3416
3511
  return 0;
3417
3512
  }
3418
3513
 
@@ -3975,7 +4070,9 @@ async function login(flags) {
3975
4070
  console.log(`\n Confirm this code in your browser: ${c.bold(start.code)}\n`);
3976
4071
  console.log(` ${c.dim(start.verifyUrl)}\n`);
3977
4072
  const opened = flags["no-browser"] === true ? false : await openInBrowser(start.verifyUrl);
3978
- console.log(` ${c.dim(opened ? "Opening the browser… waiting for you to approve." : "Open that address on any device and enter the code. Waiting…")}`);
4073
+ // The platform refuses to approve a request older than five minutes
4074
+ // (RFC 8628 §5.4: a code someone else started and sent goes stale).
4075
+ console.log(` ${c.dim(opened ? "Opening the browser… waiting for you to approve (within five minutes)." : "Open that address on any device and enter the code within five minutes. Waiting…")}`);
3979
4076
 
3980
4077
  const interval = Math.max(1, Number(start.interval) || 3) * 1000;
3981
4078
  const deadline = Date.parse(start.expiresAt) || Date.now() + 10 * 60 * 1000;
@@ -5248,20 +5345,23 @@ async function storageCmd(positional, flags, layout) {
5248
5345
  console.log(`\n ${c.dim(`no ${flags.all === true ? "" : "live "}links in ${ws} — \`foldrun storage share <path>\` mints one${flags.all === true ? "" : ", --all shows expired and revoked ones too"}`)}\n`);
5249
5346
  return 0;
5250
5347
  }
5251
- const w = { path: Math.max(...rows.map((x) => x.path.length)), token: Math.max(...rows.map((x) => x.token.length)) };
5348
+ // Only an admin, or a link's own maker, is handed its token (30 Oct
5349
+ // 2026); anyone else gets it masked, with an id to unshare it by.
5350
+ const handle = (x) => (x.masked && x.id ? x.id : x.token);
5351
+ const w = { path: Math.max(...rows.map((x) => x.path.length)), token: Math.max(...rows.map((x) => handle(x).length)) };
5252
5352
  console.log();
5253
5353
  for (const x of rows) {
5254
5354
  const state = x.revokedAt ? c.red(`revoked ${ago(x.revokedAt)} ago`) : !live(x) ? c.red(`expired ${ago(x.expiresAt)} ago`) : x.expiresAt ? `until ${when(x.expiresAt)}` : "never expires";
5255
- console.log(` ${live(x) ? c.green("✓") : c.dim("·")} ${c.bold(pad(x.path, w.path))} ${c.dim(pad(x.token, w.token))} ${c.dim(`${state} · by ${x.createdBy ?? "api-key"} · ${ago(x.createdAt)} ago`)}`);
5355
+ console.log(` ${live(x) ? c.green("✓") : c.dim("·")} ${c.bold(pad(x.path, w.path))} ${c.dim(pad(handle(x), w.token))} ${c.dim(`${state} · by ${x.createdBy ?? "api-key"} · ${ago(x.createdAt)} ago`)}`);
5256
5356
  }
5257
- console.log(`\n ${c.dim(`${rows.length} link${rows.length === 1 ? "" : "s"} · a link is <platform>/s/<token> · \`foldrun storage unshare <token> --to ${ws}\``)}\n`);
5357
+ console.log(`\n ${c.dim(`${rows.length} link${rows.length === 1 ? "" : "s"} · a link is <platform>/s/<token> · \`foldrun storage unshare <token|id> --to ${ws}\``)}\n`);
5258
5358
  return 0;
5259
5359
  }
5260
5360
  if (verb === "unshare") {
5261
5361
  const token = positional[1];
5262
- if (!token) throw new Error("`foldrun storage unshare <token>` — `foldrun storage shares` lists them");
5362
+ if (!token) throw new Error("`foldrun storage unshare <token|id>` — `foldrun storage shares` lists them (an id, sh_…, where the token is not yours to see)");
5263
5363
  if (!(await sureToDelete(flags, "storage unshare", `share link ${token} (anyone holding it gets 404)`))) return 1;
5264
- const { revoked } = await remoteCall(url, flags, `/api/workspaces/${ws}/shares?token=${encodeURIComponent(token)}`, { method: "DELETE" });
5364
+ const { revoked } = await remoteCall(url, flags, `/api/workspaces/${ws}/shares?${token.startsWith("sh_") ? "id" : "token"}=${encodeURIComponent(token)}`, { method: "DELETE" });
5265
5365
  if (!revoked) {
5266
5366
  console.log(`\n ${c.dim(`nothing revoked — ${token} is not a live link of this account's`)}\n`);
5267
5367
  return 1;
@@ -5736,10 +5836,14 @@ async function billingCmd(flags) {
5736
5836
  /** The events a notify block may name, as the platform validates them. */
5737
5837
  const NOTIFY_EVENTS = ["failed", "awaiting-approval", "completed"];
5738
5838
 
5839
+ /** Why a caller limited to some workspaces sees "set" for the account's
5840
+ * notify: URL or telemetry: (GET /api/account answers `hidden: true`). */
5841
+ const HIDDEN_NOTE = "where it goes is shown only to a member or key with every workspace";
5842
+
5739
5843
  /** The account's defaults, as one readable block. */
5740
5844
  function printDefaults(d) {
5741
5845
  const notify = d.notify
5742
- ? [d.notify.email, d.notify.url].filter(Boolean).join(", ") + c.dim(` on ${(d.notify.events ?? []).join(", ") || "nothing"}`)
5846
+ ? [d.notify.email, d.notify.url, d.notify.hidden ? `a webhook ${c.dim(`(${HIDDEN_NOTE})`)}` : null].filter(Boolean).join(", ") + c.dim(` on ${(d.notify.events ?? []).join(", ") || "nothing"}`)
5743
5847
  : c.dim("nobody is told anything");
5744
5848
  console.log(`\n ${c.bold("account defaults")} ${c.dim("every workspace here inherits these")}\n`);
5745
5849
  console.log(` timezone ${d.timezone ?? c.dim("unset — schedules read UTC")}`);
@@ -5805,6 +5909,10 @@ async function telemetryCmd(url, args, flags) {
5805
5909
  console.log(`\n ${c.dim("runs are not sent anywhere — foldrun account telemetry set https://<collector>/v1/traces --header authorization=\${OTEL_TOKEN}")}\n`);
5806
5910
  return 0;
5807
5911
  }
5912
+ if (t.hidden) {
5913
+ console.log(`\n ${c.bold("telemetry")} set ${c.dim(`— ${HIDDEN_NOTE}`)}\n`);
5914
+ return 0;
5915
+ }
5808
5916
  console.log(`\n ${c.bold("telemetry")} ${t.endpoint}`);
5809
5917
  for (const [k, v] of Object.entries(t.headers ?? {})) console.log(` ${c.dim(k)} ${v}`);
5810
5918
  console.log();
@@ -5913,6 +6021,9 @@ async function mergedEntry(url, flags, key, args, workspace, view, how) {
5913
6021
  /** A setting's value as one short line. */
5914
6022
  function shortValue(v) {
5915
6023
  if (v === null || v === undefined) return null;
6024
+ // The account's notify:/telemetry: to a key limited to some workspaces:
6025
+ // set, and where it goes is not shown (30 Oct 2026).
6026
+ if (v && typeof v === "object" && v.hidden === true) return `set ${c.dim(`(${HIDDEN_NOTE})`)}`;
5916
6027
  return typeof v === "object" ? JSON.stringify(v).replace(/"([a-z_]+)":/g, "$1: ").replace(/,/g, ", ") : String(v);
5917
6028
  }
5918
6029
 
@@ -11439,12 +11550,12 @@ async function secretOfKind(kind, flags) {
11439
11550
  };
11440
11551
  switch (kind) {
11441
11552
  case "file":
11442
- return { body: { file: read(flags.file, "--file <path> — the file the secret holds") }, local: (k, n, b, s) => k.setFileSecret("default", n, b.file, s) };
11553
+ return { body: { file: read(flags.file, "--file <path> — the file the secret holds") }, local: (k, n, b, s, l) => k.setFileSecret("default", n, b.file, s, l) };
11443
11554
  case "ssh": {
11444
11555
  if (typeof flags.host !== "string" || typeof flags.user !== "string") throw new Error("--kind ssh needs --host <host> --user <user> (--port, and --key-file <path> or a password, prompted)");
11445
11556
  const port = flags.port !== undefined ? Number(flags.port) : undefined;
11446
11557
  const auth = typeof flags["key-file"] === "string" ? { private_key: read(flags["key-file"], "--key-file <path>") } : { password: typeof flags.value === "string" ? flags.value : await promptHidden(" password: ") };
11447
- return { body: { ssh: { host: flags.host, user: flags.user, ...(port ? { port } : {}), ...auth } }, local: (k, n, b, s) => k.setSshSecret("default", n, b.ssh, s) };
11558
+ return { body: { ssh: { host: flags.host, user: flags.user, ...(port ? { port } : {}), ...auth } }, local: (k, n, b, s, l) => k.setSshSecret("default", n, b.ssh, s, l) };
11448
11559
  }
11449
11560
  case "api": {
11450
11561
  const lines = [].concat(flags.header ?? []);
@@ -11461,13 +11572,13 @@ async function secretOfKind(kind, flags) {
11461
11572
  }),
11462
11573
  );
11463
11574
  const base = typeof flags["base-url"] === "string" ? { base_url: flags["base-url"] } : {};
11464
- return { body: { api: { ...base, headers, ...basic } }, local: (k, n, b, s) => k.setApiSecret("default", n, b.api, s) };
11575
+ return { body: { api: { ...base, headers, ...basic } }, local: (k, n, b, s, l) => k.setApiSecret("default", n, b.api, s, l) };
11465
11576
  }
11466
11577
  case "identity": {
11467
11578
  // A keyless cloud identity: only the audience; the platform signs the
11468
11579
  // tokens (`foldrun identity` prints what the cloud must trust).
11469
11580
  if (typeof flags.audience !== "string" || !flags.audience.trim()) throw new Error("--kind identity needs --audience <value your cloud's trust expects in aud>");
11470
- return { body: { identity: { audience: flags.audience } }, local: (k, n, b, s) => k.setIdentitySecret("default", n, b.identity, s) };
11581
+ return { body: { identity: { audience: flags.audience } }, local: (k, n, b, s, l) => k.setIdentitySecret("default", n, b.identity, s, l) };
11471
11582
  }
11472
11583
  case "client-cert": {
11473
11584
  // A client certificate for mutual TLS. Bind it to the exact hosts it is
@@ -11477,7 +11588,7 @@ async function secretOfKind(kind, flags) {
11477
11588
  const key = read(flags["key-file"], "--key-file <key.pem> — its private key");
11478
11589
  const passphrase = typeof flags.passphrase === "string" ? flags.passphrase : undefined;
11479
11590
  const client_cert = { cert, key, ...(passphrase ? { passphrase } : {}), ...(flags.export === true ? { export: true } : {}) };
11480
- return { body: { client_cert }, local: (k, n, b, s) => k.setClientCertSecret("default", n, b.client_cert, s) };
11591
+ return { body: { client_cert }, local: (k, n, b, s, l) => k.setClientCertSecret("default", n, b.client_cert, s, l) };
11481
11592
  }
11482
11593
  case "service-account": {
11483
11594
  let j;
@@ -11490,14 +11601,14 @@ async function secretOfKind(kind, flags) {
11490
11601
  // --subject: the user it acts as (domain-wide delegation, granted by the
11491
11602
  // provider's admin); without it the account acts as itself.
11492
11603
  const sa = { token_url: j.token_uri ?? "https://oauth2.googleapis.com/token", issuer: j.client_email, private_key: j.private_key, scope: flags.scopes ?? "", ...(typeof flags.subject === "string" ? { subject: flags.subject } : {}) };
11493
- return { body: { service_account: sa }, local: (k, n, b, s) => k.setServiceAccountSecret("default", n, b.service_account, s) };
11604
+ return { body: { service_account: sa }, local: (k, n, b, s, l) => k.setServiceAccountSecret("default", n, b.service_account, s, l) };
11494
11605
  }
11495
11606
  case "m2m": {
11496
11607
  if (typeof flags["token-url"] !== "string") throw new Error("--kind m2m needs --token-url, --client-id (and the client secret, prompted or --client-secret)");
11497
11608
  const client_id = flags["client-id"] ?? (await promptVisible(" client_id: "));
11498
11609
  const client_secret = flags["client-secret"] ?? (await promptHidden(" client_secret: "));
11499
11610
  const oauth2 = { token_url: flags["token-url"], client_id, client_secret, grant_type: "client_credentials", ...(flags.scopes ? { extra: { scope: flags.scopes } } : {}) };
11500
- return { body: { oauth2 }, local: (k, n, b, s) => k.setOAuth2Secret("default", n, b.oauth2, s) };
11611
+ return { body: { oauth2 }, local: (k, n, b, s, l) => k.setOAuth2Secret("default", n, b.oauth2, s, l) };
11501
11612
  }
11502
11613
  default:
11503
11614
  throw new Error(`unknown --kind "${kind}" — file, ssh, api, service-account, m2m, client-cert or identity (a plain value needs no --kind; --oauth2 a refresh token; \`foldrun connect\` a browser sign-in)`);
@@ -11605,7 +11716,8 @@ async function apiVersionCmd(positional, flags) {
11605
11716
  console.log(`\n ${c.bold("API version")} ${v.effective} ${c.dim(v.pinned ? `pinned (current is ${v.current})` : "current — not pinned")}`);
11606
11717
  console.log(` ${c.dim(`served: ${(v.supported ?? []).join(", ") || "—"} · each for ${v.supportMonths ?? "?"} months after the next · this CLI sends ${API_VERSION}`)}`);
11607
11718
  if (l.perCredential) console.log(` ${c.bold("rate limits")} ${c.dim(`${l.plan} · per key ${l.perCredential.read} reads / ${l.perCredential.write} writes, per account ${l.perAccount?.read} / ${l.perAccount?.write} — every ${l.windowSeconds}s`)}`);
11608
- apiUsageLines(facts.usage);
11719
+ if (facts.usageHidden) console.log(` ${c.bold("your use")} ${c.dim("shown only to a member or key with every workspace")}`);
11720
+ else apiUsageLines(facts.usage);
11609
11721
  console.log(`\n ${c.dim("foldrun api version pin YYYY-MM-DD · unpin")}\n`);
11610
11722
  return 0;
11611
11723
  }