foldrun 8.1.2 → 9.0.1
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 +1 -1
- package/docs/api.md +4 -4
- package/docs/budgets-and-billing.md +4 -4
- package/docs/cli.md +4 -4
- package/docs/feature-flags.md +7 -4
- package/package.json +2 -2
- package/src/commands.mjs +9 -4
package/bin/foldrun.mjs
CHANGED
|
@@ -209,7 +209,7 @@ const HELP = `foldrun — agents are just folders
|
|
|
209
209
|
foldrun webhooks redeliver <id> send one delivery again now, same X-Foldrun-Delivery id; exits 1 when refused (--to)
|
|
210
210
|
foldrun notifications what mail you get, category by category, and which are always sent (--json)
|
|
211
211
|
foldrun notifications set <category> on|off turn one off or back on — account-wide, or --to <workspace> for run-alerts and approvals
|
|
212
|
-
foldrun flags the feature flags for this account: each on or off, and why — set for this account, for every account, a staged rollout, or the default (--json). Read-only: the platform's
|
|
212
|
+
foldrun flags the feature flags for this account: each on or off, and why — set for this account, for every account, a staged rollout, or the default (--json). Read-only: the platform's operator changes them
|
|
213
213
|
foldrun history [path] every change to a deployed workspace, newest first (--id <revision> for its diff, --limit, --to)
|
|
214
214
|
foldrun history restore <path> --id <revision> put one file back as that revision left it, as a new revision — diff, asks (--yes, --dry-run, --to)
|
|
215
215
|
foldrun restore <ws> --to <revision|time|age> put a workspace's source back as it was then — shows the change, asks for the name typed back (--dry-run: the diff only, --yes)
|
package/docs/api.md
CHANGED
|
@@ -356,14 +356,14 @@ Reads return which secrets exist, never their values.
|
|
|
356
356
|
| `/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` |
|
|
357
357
|
| `/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) |
|
|
358
358
|
| `/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 |
|
|
359
|
-
| `/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
|
|
359
|
+
| `/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 |
|
|
360
360
|
| `/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) |
|
|
361
361
|
| `/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 |
|
|
362
362
|
| `/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`. See [api-usage](api-usage.md) |
|
|
363
|
-
| `/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
|
|
363
|
+
| `/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) |
|
|
364
364
|
| `/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 |
|
|
365
365
|
| `/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 |
|
|
366
|
-
| `/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
|
|
366
|
+
| `/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 |
|
|
367
367
|
| `/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 |
|
|
368
368
|
| `/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 |
|
|
369
369
|
| `/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 }` |
|
|
@@ -397,7 +397,7 @@ person: a key names an account, never a who.
|
|
|
397
397
|
|
|
398
398
|
| Route | Methods | |
|
|
399
399
|
|---|---|---|
|
|
400
|
-
| `/api/billing` | GET, POST | balance and recent ledger entries; POST answers `404` to every caller — credit comes through checkout (`/api/billing/checkout`) or the platform's
|
|
400
|
+
| `/api/billing` | GET, POST | balance and recent ledger entries; POST answers `404` to every caller — credit comes through checkout (`/api/billing/checkout`) or an adjustment by the platform's operator |
|
|
401
401
|
| `/api/billing/checkout` | POST | a Stripe session (`usd`) |
|
|
402
402
|
| `/api/billing/confirm?session_id=` | GET | settle one |
|
|
403
403
|
| `/api/billing/card` | POST | save a card |
|
|
@@ -379,8 +379,8 @@ ends, but an invoice it left unpaid is still owed and still payable, and
|
|
|
379
379
|
the account stays paused until it is paid or written off. Every step is once per invoice, however often
|
|
380
380
|
Stripe retries or redelivers; a second invoice failing during the grace
|
|
381
381
|
does not restart it. Dunning lifts only a suspension it placed: an account
|
|
382
|
-
the
|
|
383
|
-
|
|
382
|
+
the platform's operator suspended for another reason stays suspended. The
|
|
383
|
+
operator sees where it stands on the customer's overview.
|
|
384
384
|
|
|
385
385
|
**Your data, and leaving.** Settings → Your data gives the owner one JSON
|
|
386
386
|
file with the account's workspaces, members, an index of every run and the
|
|
@@ -441,7 +441,7 @@ card network already has the money). The account is found through the
|
|
|
441
441
|
disputed charge — its metadata, its payment's, then the saved customer. Won
|
|
442
442
|
(or an inquiry closed without a chargeback): the same amount goes back on,
|
|
443
443
|
once. Lost: it stays off. As with refunds, a dispute on a plan fee does not
|
|
444
|
-
touch the wallet; it is logged and left to the
|
|
444
|
+
touch the wallet; it is logged and left to the platform's operator.
|
|
445
445
|
|
|
446
446
|
**Every line says why it exists.** Each ledger line carries a reason —
|
|
447
447
|
usage, pod, fee, checkout, auto-topup, manual, operator, refund, dispute,
|
|
@@ -451,7 +451,7 @@ label lines by it. **Burn**, the 30-day spend and month-to-date count usage
|
|
|
451
451
|
and the daily fees only — not expiries, refunds, chargebacks or an
|
|
452
452
|
operator's debit.
|
|
453
453
|
|
|
454
|
-
**Hand-placed plans renew.** A plan the
|
|
454
|
+
**Hand-placed plans renew.** A plan the platform's operator grants runs a month and
|
|
455
455
|
is renewed by the hourly sweep at its period's end, with the same grant and
|
|
456
456
|
rollover rules. Granting a plan to an account Stripe is billing is refused
|
|
457
457
|
(end it first, or change it at Stripe); ending a Stripe-billed plan cancels
|
package/docs/cli.md
CHANGED
|
@@ -164,7 +164,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
164
164
|
| `foldrun webhooks redeliver <id>` | send one delivery again now, with the same `X-Foldrun-Delivery` id; prints the attempt and exits 1 when it was refused. `--to <workspace>` |
|
|
165
165
|
| `foldrun notifications` | what mail you get, category by category: `always` for the required ones (security, invites, billing, account), `on`/`off` for the rest, and the workspaces where run alerts or approvals differ. `--json` |
|
|
166
166
|
| `foldrun notifications set <category> on\|off` | turn one category off, or back on — account-wide, or for one workspace with `--to <workspace>` (`run-alerts`, `approvals`). A required category is refused with the reason |
|
|
167
|
-
| `foldrun flags` | the feature flags for this account: each one `on` or `off` and why — `account` (set for this account), `global` (set for every account), `rollout` (a share of accounts, with its percentage) or `default` — and what it does. Read-only: only the platform's
|
|
167
|
+
| `foldrun flags` | the feature flags for this account: each one `on` or `off` and why — `account` (set for this account), `global` (set for every account), `rollout` (a share of accounts, with its percentage) or `default` — and what it does. Read-only: only the platform's operator changes a flag (on foldrun's hosted platform; a self-hosted install runs every flag at its default). `--json` for the API's answer as it came. See [Feature flags](feature-flags.md) |
|
|
168
168
|
| `foldrun history [path]` | every change to a deployed workspace, newest first: revision id, when, who, the message and the files. A path narrows it to one file; `--id <revision>` prints that revision as diffs; `--limit <n>`; `--to <workspace>` |
|
|
169
169
|
| `foldrun history restore <path> --id <revision>` | the History drawer's **Restore this version**: the file is rewritten with that revision's text as a new revision, `restored <rev> from history`, so the restore is itself undone the same way. Shows the diff against the file now and asks (`--yes`, `--dry-run`); sent with `ifMatch`, so a file that changed since is refused. A version that does not pass today's checks is still restored, and the errors are printed (`--to`) |
|
|
170
170
|
| `foldrun restore <workspace> --to <revision\|time\|age>` | put a workspace's source back as it was then — `--to` is a revision id (`r-…`, from `foldrun history`), the commit a deploy named, a date/time (the last revision at or before it) or an age (`90m`, `12h`, `3d`, `2w`). Always shows the change first (`--dry-run`: the full diff and nothing else); the restore asks for the workspace's name typed back (`--yes` with no terminal) and sends the removals it showed, so a file added in between refuses it. A new revision, so it prints the `foldrun restore … --to <from>` that undoes it. Runs, `state/`, storage and secrets are not touched. See [Backups and restore](backups-and-restore.md) |
|
|
@@ -459,9 +459,9 @@ write secrets however it is used. `foldrun keys ls` on their account shows
|
|
|
459
459
|
it, and `foldrun keys revoke <id>` ends it — which is the point of doing it
|
|
460
460
|
this way: they can take it back without changing a password.
|
|
461
461
|
|
|
462
|
-
**You reset it, as the platform.** Only the platform's
|
|
463
|
-
|
|
464
|
-
from
|
|
462
|
+
**You reset it, as the platform.** Only the platform's operator can, only
|
|
463
|
+
on foldrun's hosted platform, and it ends every session that account had:
|
|
464
|
+
from the operator console, the member → **reset password**. The new password is
|
|
465
465
|
shown once. Sign in as them in a private window, then `foldrun login
|
|
466
466
|
--profile <name>` and approve the code in that window.
|
|
467
467
|
|
package/docs/feature-flags.md
CHANGED
|
@@ -13,8 +13,8 @@ and why.
|
|
|
13
13
|
|
|
14
14
|
The flags themselves are code — a name, what it changes, who owns it, a
|
|
15
15
|
default, and sometimes a rollout percentage. A name the code does not
|
|
16
|
-
register is not a flag; asking for one is a 404. What the platform's
|
|
17
|
-
|
|
16
|
+
register is not a flag; asking for one is a 404. What the platform's
|
|
17
|
+
operator sets on top is checked in this order, and the first that has an
|
|
18
18
|
answer wins:
|
|
19
19
|
|
|
20
20
|
| | source | |
|
|
@@ -30,8 +30,8 @@ within ten seconds.
|
|
|
30
30
|
## The example
|
|
31
31
|
|
|
32
32
|
`example-flag` is registered, off by default, and read by nothing: turning
|
|
33
|
-
it on changes no behaviour. It is there to try the
|
|
34
|
-
|
|
33
|
+
it on changes no behaviour. It is there to try the API and the CLI
|
|
34
|
+
against without risk.
|
|
35
35
|
|
|
36
36
|
```sh
|
|
37
37
|
foldrun flags # every flag, on or off for this account, and why
|
|
@@ -54,6 +54,9 @@ it and what it was before. The settings are rows in Postgres
|
|
|
54
54
|
(`feature_flags`), or `<data>/.feature-flags.json` without a database; an
|
|
55
55
|
account's overrides go when the account is deleted, and their audit stays.
|
|
56
56
|
|
|
57
|
+
A self-hosted install has no operator console, so nothing changes a flag
|
|
58
|
+
there: every flag runs at its registry default.
|
|
59
|
+
|
|
57
60
|
A flag is added by a line in `foldrun-platform/src/flags.ts` and asked with
|
|
58
61
|
`flagOn(account, "<name>")`. Retire it by deleting the line and the code
|
|
59
62
|
that asks, once it is on for everyone; a row left behind for a name the
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "foldrun",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "9.0.1",
|
|
4
4
|
"description": "Agents are just folders. Write them, check them, run them — on your machine.",
|
|
5
5
|
"license": "FSL-1.1-ALv2",
|
|
6
6
|
"type": "module",
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
"node": ">=22"
|
|
12
12
|
},
|
|
13
13
|
"dependencies": {
|
|
14
|
-
"@foldrun/core": "^
|
|
14
|
+
"@foldrun/core": "^8.0.0"
|
|
15
15
|
},
|
|
16
16
|
"files": [
|
|
17
17
|
"bin",
|
package/src/commands.mjs
CHANGED
|
@@ -3621,6 +3621,9 @@ async function invoke(target, flags) {
|
|
|
3621
3621
|
try {
|
|
3622
3622
|
body = await remoteCall(url, flags, `/api/workspaces/${ws}/flows/${target}/run${wait}`, {
|
|
3623
3623
|
method: "POST",
|
|
3624
|
+
// The route reads the Idempotency-Key header before the body's key, and
|
|
3625
|
+
// every write carries a fresh one — so --once must BE that header.
|
|
3626
|
+
...(typeof flags.once === "string" && flags.once ? { headers: { "idempotency-key": flags.once } } : {}),
|
|
3624
3627
|
body: JSON.stringify({
|
|
3625
3628
|
task,
|
|
3626
3629
|
...(from !== undefined ? { from } : {}),
|
|
@@ -10219,12 +10222,14 @@ const FLAG_SOURCES = {
|
|
|
10219
10222
|
* `foldrun flags` — the feature flags as they stand for this account: on or
|
|
10220
10223
|
* off, and what decided it (this account's override, the install-wide
|
|
10221
10224
|
* setting, a percentage rollout, or the default). Read-only: only the
|
|
10222
|
-
* platform's
|
|
10223
|
-
*
|
|
10225
|
+
* platform's operator changes a flag — on foldrun's hosted platform, from
|
|
10226
|
+
* its operator console, which no account and no API key reaches; a
|
|
10227
|
+
* self-hosted install runs every flag at its default. So the CLI has no
|
|
10228
|
+
* verb for it.
|
|
10224
10229
|
*/
|
|
10225
10230
|
async function flagsCmd(positional, flags) {
|
|
10226
10231
|
const url = platformFor(flags, "flags");
|
|
10227
|
-
if (positional[0]) throw new Error("`foldrun flags` lists this account's feature flags —
|
|
10232
|
+
if (positional[0]) throw new Error("`foldrun flags` lists this account's feature flags — only the platform's operator changes them, not from here");
|
|
10228
10233
|
const r = await remoteCall(url, flags, "/api/account/flags");
|
|
10229
10234
|
if (flags.json === true) {
|
|
10230
10235
|
console.log(JSON.stringify(r, null, 2));
|
|
@@ -10242,7 +10247,7 @@ async function flagsCmd(positional, flags) {
|
|
|
10242
10247
|
const state = f.on ? c.green("on ") : c.dim("off");
|
|
10243
10248
|
console.log(` ${pad(f.name, w)} ${state} ${c.dim(pad(why(f), sw))} ${f.description}`);
|
|
10244
10249
|
}
|
|
10245
|
-
console.log(`\n ${c.dim("read-only — the platform's
|
|
10250
|
+
console.log(`\n ${c.dim("read-only — the platform's operator turns flags on and off")}\n`);
|
|
10246
10251
|
return 0;
|
|
10247
10252
|
function why(f) {
|
|
10248
10253
|
const base = FLAG_SOURCES[f.source] ?? String(f.source ?? "");
|