foldrun 9.0.0 → 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 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 super admin changes them
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 super admin 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 |
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 super admin changes a flag. See [Feature flags](feature-flags.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 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 super admin's own levers (`operator.*`) are the platform's record and not listed. Kept for the life of the account |
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 console adjustment |
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 super admin suspended for another reason stays suspended. The super
383
- admin sees where it stands on the customer's overview.
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 super admin.
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 super admin grants runs a month and
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 super admin changes a flag, in the console. `--json` for the API's answer as it came. See [Feature flags](feature-flags.md) |
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 own super admin can,
463
- only on the hosted platform, and it ends every session that account had:
464
- from its console, the member → **reset password**. The new password is
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
 
@@ -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 super
17
- admin sets on top is checked in this order, and the first that has an
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 console, the API and the
34
- CLI against without risk.
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": "9.0.0",
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",
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 super admin changes a flag, in the console, with a session —
10223
- * an API key never reaches those routes, so the CLI has no verb for them.
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 — they are changed by the platform's super admin, not from here");
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 super admin turns flags on and off")}\n`);
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 ?? "");