foldrun 6.0.0 → 7.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
@@ -26,6 +26,7 @@
26
26
  // foldrun flags the feature flags for this account — on or off, and why (read-only)
27
27
  // foldrun backups how the account is backed up, its snapshots — request a restore from one, requests lists them
28
28
  // foldrun team who is in the account, their roles and workspaces (read-only)
29
+ // foldrun team invites the invites still out; `revoke <id>` takes one back
29
30
  // foldrun restore <ws> a workspace's source back to a point in its history (shows the change, asks)
30
31
  // foldrun onboarding the account's getting-started steps, the next one first
31
32
  // foldrun billing the balance, and what the money went on
@@ -249,6 +250,8 @@ Signing in
249
250
  foldrun logout forget this machine's key, and revoke it where allowed
250
251
  foldrun whoami who you are on the platform: account, role, workspaces
251
252
  foldrun team who is in the account: role, the workspaces each may open, when they joined (--json). Read-only: invites, roles, removal and transfer are a signed-in person's, in Settings → Team
253
+ foldrun team invites the account's pending invites — address or "anyone with the link", role, workspaces, who made it, when it expires, its id (--all for accepted, revoked and expired too; --json). Never the link: each works once, shown only to its maker
254
+ foldrun team invites revoke <id> take an invite back: its link stops working at once (an admin's; a key may)
252
255
  foldrun onboarding the account's getting-started steps, done or not, the next one first (--json)
253
256
  foldrun preferences your own settings on the platform — the theme; set theme system|light|dark (a key acts for whoever minted it)
254
257
  foldrun doctor check the path to the platform: node, CLI, model credential, account, DNS, a timed /api/healthz
package/docs/api.md CHANGED
@@ -40,7 +40,8 @@ read (a deploy with issues, an `Idempotency-Key` reused with a different body),
40
40
  **A person's alone.** A key carries a role and a workspace scope no wider
41
41
  than the person who minted it, and opens every route below with that — except
42
42
  the ones that are about people: `/api/team` (invite, roles, scope, remove,
43
- transfer), `/api/auth/*` (profile, password, MFA, sessions), a user's
43
+ transfer — listing and revoking invites, `/api/team/invites`, take an admin
44
+ key), `/api/auth/*` (profile, password, MFA, sessions), a user's
44
45
  `/api/avatars/user/<id>`. Those need a signed-in
45
46
  session and answer a key with `401` (a user's avatar answers a key with
46
47
  `403`: the key is read, then refused because it is not that person). Everything a workspace or an account
@@ -337,8 +338,10 @@ Reads return which secrets exist, never their values.
337
338
  |---|---|---|
338
339
  | `/api/keys` | GET, POST, DELETE | API keys — an admin's (`keys:manage`) to list, mint and revoke; any key may revoke itself (DELETE with its own `id`, audited as self — what `foldrun logout` does). POST `label`, `role` (viewer \| editor \| admin, never above your own, default editor), `workspaces` (names, or `null` for all — never wider than your own scope); `expires` (`30d`, `90d`, `365d`, any number of days up to 3650, or `never` — the default; anything else is a 400, never a key that lives forever); returns `{ ok, key, id, prefix, role, workspaces, expiresAt }`, and the key is shown once. GET lists each key with `createdAt`, `createdBy`, `expiresAt`, `lastUsedAt`, `lastIp` and `replacedBy` (the id of the key a rotation replaced it with; `null` until then) — the last-use pair written at most once a minute per key, the address cut to its /24 (IPv4) or /48 (IPv6). A key past its `expiresAt` is refused with 401 `API key expired on <date>`; the owner is emailed seven days before. Mint, revoke and rotate are written to the audit log. POST with `workspace` or `access` is refused (400): those minted deploy keys for the platform's own git, which went on 17 Oct 2026 — a deploy key minted before is refused everywhere (403). A key for one workspace is `workspaces: ["<ws>"]`. DELETE `id`. `?tenant=` / body `tenant` is read only on an install with no users yet (first-run bootstrap), and there, when the install has a setup token (`FOLDRUN_SETUP_TOKEN`, written by the self-hosting installer), only with that token in `X-Foldrun-Setup-Token` |
339
340
  | `/api/keys/<id>/rotate` | POST | a new key with the old one's label, role, workspaces and deploy scope — and, when it had an end, the same lifetime from today — returned once like a mint (`{ ok, key, id, prefix, role, workspaces, expiresAt, replaced: { id, endsAt } }`). `grace`: `0` (default — the old key is revoked at once), or a duration up to `7d` such as `1h` or `24h`, during which the old key still works and after which it is refused as expired. A key is rotated once: rotating a key already replaced is 409 `this key was already rotated to <prefix>…; rotate that one` — and someone who lost the new key's secret rotates the NEW key, which mints another and ends the lost one (rotating the old one again would leave the lost key working). Two rotations of one key at once mint one key. `keys:manage`; a key outside the caller's scope is 404. Audited as `apikey.rotated` |
340
- | `/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` (bound into the invite: only that address can accept it; sent through the account's `RESEND_API_KEY` unless `send: false`). Returns `path` (the invite's relative URL), `expires`, `sent` and any `sendError` either way; the full link is in the mail |
341
- | `/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 |
341
+ | `/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 |
342
+ | `/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 |
343
+ | `/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` |
344
+ | `/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 |
342
345
  | `/api/team/transfer` | POST | hand the account to a member (`to`) — owner only; you become an admin |
343
346
  | `/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)) |
344
347
  | `/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 |
package/docs/cli.md CHANGED
@@ -131,7 +131,9 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
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 |
134
- | `foldrun team` | who is in the account (`GET /api/team`): each member's email, role (the owner marked), the workspaces they may open — a scoped key sees only the ones it shares — and when they joined. `--json`. Read-only on purpose: inviting, changing a role or workspace access, removing someone and transferring the account are a signed-in person's, in Settings → Team, and the platform refuses them from a key |
134
+ | `foldrun team` | who is in the account (`GET /api/team`): each member's email, role (the owner marked), the workspaces they may open — a scoped key sees only the ones it shares — and when they joined. `--json`. Inviting, changing a role or workspace access, removing someone and transferring the account are a signed-in person's, in Settings → Team, and the platform refuses them from a key |
135
+ | `foldrun team invites` | the account's pending invites (`GET /api/team/invites`): the address, or "anyone with the link", role, workspaces, who made it, when it expires, and its id. `--all` adds accepted, revoked and expired ones; `--json`. Never the link: an invite works once and its link is shown only to the person who made it. An admin's (`team:manage`), a key included; a scoped key sees the invites inside its scope |
136
+ | `foldrun team invites revoke <id>` | take an invite back (`DELETE /api/team/invites/<id>`): its link stops working at once. One already revoked or expired says so and changes nothing; one already accepted is refused (remove the member in Settings → Team instead). An admin invite is the owner's to revoke |
135
137
  | `foldrun onboarding` | the account's getting-started steps — the model key (where the account brings its own), workspace, agent, a run, a run that completes, a secret, a schedule or webhook, a teammate, billing where the plan asks for it, the CLI — each worked out from what is really there, with the next one first and where to do it (`--json`). The dashboard card is hidden per person from the dashboard |
136
138
  | `foldrun preferences` | your own settings on the platform — today the theme (`system`, `light`, `dark`), kept with you on every browser; `preferences set theme dark` changes it (`/api/me/preferences`; a key acts for whoever minted it) |
137
139
  | `foldrun api spec` | the platform's OpenAPI 3.1 document, from `GET /api/openapi.json` (no key needed) — to stdout, or `--out <file>`. Every other command sends `Foldrun-Version` (the API version this CLI was built for), an `Idempotency-Key` on each write (reused on its own retry), and waits out one `429` for `Retry-After` before saying so. See [Using the API](api-usage) |
@@ -35,9 +35,38 @@ everyone's workspaces at once.
35
35
 
36
36
  ## Invites
37
37
 
38
- An invite carries a role, a workspace scope, and an email address it is bound
39
- to — only that address can accept it. It is sent through the account's email
40
- connection, or returned as a link to pass on yourself.
38
+ An invite carries a role, a workspace scope, and usually an email address it
39
+ is bound to — only that address can accept it. It is sent through the
40
+ account's email connection, or returned as a link to pass on yourself; an
41
+ invite with no address is a link for one person, whoever opens it first.
42
+
43
+ - **It works once.** The first signup on it uses it up, in the same step that
44
+ creates the member; a second person, or the same person again, is refused.
45
+ It lasts seven days.
46
+ - **Pending invites are listed.** Settings → Team shows the links still out —
47
+ the address or "anyone with the link", role, workspaces, who made it, when
48
+ it expires — with **Revoke** on each. The same list is
49
+ `GET /api/team/invites` (`?all=1` adds accepted, revoked and expired ones)
50
+ and `foldrun team invites`. The link itself is never listed: it is shown
51
+ once, to the person who made it.
52
+ - **Revoke one** with that button, `DELETE /api/team/invites/<id>` or
53
+ `foldrun team invites revoke <id>`; its link stops working at once. An
54
+ admin invite is the owner's to revoke, and a member scoped to some
55
+ workspaces sees and revokes only the invites inside its scope.
56
+ - **Other things revoke them too.** A new invite to an address revokes the
57
+ older ones still pending to it. Removing a member revokes every pending
58
+ invite they made and any pending invite to their address — a removed
59
+ member cannot rejoin with an old link. Lowering a member's role or
60
+ narrowing their workspaces revokes the invites they made that they could
61
+ no longer make. An invite is also checked against its maker when it is
62
+ accepted: if they have left or can no longer grant it, it is refused.
63
+ - **Old links are refused.** Invite links made before 29 October 2026 were
64
+ signed statements with no record behind them; they no longer work. Send a
65
+ new invite.
66
+
67
+ Each revocation is in the audit log as `member.invite_revoked`;
68
+ `member.removed` lists `invitesRevoked`, and `member.joined` names the
69
+ `inviteId`.
41
70
 
42
71
  ## API keys
43
72
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "foldrun",
3
- "version": "6.0.0",
3
+ "version": "7.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",
@@ -11,7 +11,7 @@
11
11
  "node": ">=22"
12
12
  },
13
13
  "dependencies": {
14
- "@foldrun/core": "^5.0.0"
14
+ "@foldrun/core": "^6.0.0"
15
15
  },
16
16
  "files": [
17
17
  "bin",
package/src/commands.mjs CHANGED
@@ -11666,12 +11666,15 @@ async function evalNewCmd(name, flags, layout) {
11666
11666
 
11667
11667
  /**
11668
11668
  * `foldrun team` — who is in the account, their role and which workspaces
11669
- * they may open (GET /api/team). Read-only on purpose: inviting, changing a
11670
- * role or workspace access, removing someone and transferring the account are
11671
- * a person's acts, and the platform refuses them from a key (requirePerson,
11672
- * server/api.ts) — so there is nothing for a key-holding CLI to send.
11669
+ * they may open (GET /api/team). Inviting, changing a role or workspace
11670
+ * access, removing someone and transferring the account are a person's acts,
11671
+ * and the platform refuses them from a key (requirePerson, server/api.ts) —
11672
+ * so there is nothing for a key-holding CLI to send. The one write a key may
11673
+ * make is taking an invite back: `foldrun team invites` lists the links
11674
+ * still out, `foldrun team invites revoke <id>` ends one.
11673
11675
  */
11674
11676
  async function teamCmd(positional, flags) {
11677
+ if (positional[0] === "invites") return teamInvitesCmd(positional.slice(1), flags);
11675
11678
  if (positional[0]) {
11676
11679
  throw new Error("`foldrun team` lists the members — inviting, changing a role or workspace access, removing a member and transferring the account are a signed-in person's acts, done in Settings → Team; the platform refuses them from a key");
11677
11680
  }
@@ -11695,6 +11698,51 @@ async function teamCmd(positional, flags) {
11695
11698
  return 0;
11696
11699
  }
11697
11700
 
11701
+ /**
11702
+ * `foldrun team invites [--all] [--json]` — the account's invites (GET
11703
+ * /api/team/invites): pending ones, or every one with --all. Never a link:
11704
+ * that is shown once, to the person who made it. `foldrun team invites
11705
+ * revoke <id>` takes one back (DELETE /api/team/invites/<id>) — its link
11706
+ * stops working at once. Settings → Team does the same.
11707
+ */
11708
+ async function teamInvitesCmd(positional, flags) {
11709
+ const url = platformFor(flags, "team invites");
11710
+ if (positional[0] === "revoke") {
11711
+ const id = positional[1];
11712
+ if (!id) throw new Error("which invite? `foldrun team invites revoke <id>` — `foldrun team invites` lists them");
11713
+ const r = await remoteCall(url, flags, `/api/team/invites/${enc(id)}`, { method: "DELETE" });
11714
+ if (flags.json === true) {
11715
+ console.log(JSON.stringify(r, null, 2));
11716
+ return 0;
11717
+ }
11718
+ const who = r.invite?.email ?? "anyone with the link";
11719
+ console.log(r.revoked
11720
+ ? `\n ${c.green("revoked")} the invite for ${c.bold(who)} ${c.dim(`(${id}) — its link no longer works`)}\n`
11721
+ : `\n ${c.dim(`the invite for ${who} (${id}) was already ${r.invite?.status ?? "revoked"} — nothing changed`)}\n`);
11722
+ return 0;
11723
+ }
11724
+ if (positional[0]) throw new Error(`\`foldrun team invites\` lists the invites; \`foldrun team invites revoke <id>\` takes one back — not "${positional[0]}"`);
11725
+ const { invites = [] } = await remoteCall(url, flags, `/api/team/invites${flags.all === true ? "?all=1" : ""}`);
11726
+ if (flags.json === true) {
11727
+ console.log(JSON.stringify(invites, null, 2));
11728
+ return 0;
11729
+ }
11730
+ if (!invites.length) {
11731
+ console.log(`\n ${c.dim(flags.all === true ? "no invites" : "no pending invites")}\n`);
11732
+ return 0;
11733
+ }
11734
+ const label = (i) => i.email ?? "anyone with the link";
11735
+ const w = Math.max(...invites.map((i) => label(i).length));
11736
+ console.log();
11737
+ for (const i of invites) {
11738
+ const scope = i.workspaces === null || i.workspaces === undefined ? "every workspace" : i.workspaces.length ? i.workspaces.join(", ") : "no workspaces";
11739
+ const state = i.status === "pending" ? `expires ${when(i.expiresAt)}` : i.status;
11740
+ console.log(` ${c.bold(pad(label(i), w))} ${pad(i.role, 6)} ${c.dim(scope)} ${c.dim(`by ${i.invitedBy} · ${state}`)} ${c.dim(i.id)}`);
11741
+ }
11742
+ console.log(`\n ${c.dim(`${invites.length} invite${invites.length === 1 ? "" : "s"} · each works once · foldrun team invites revoke <id> takes one back`)}\n`);
11743
+ return 0;
11744
+ }
11745
+
11698
11746
  async function workspacesDemoCmd(flags) {
11699
11747
  const url = platformFor(flags, "workspaces demo");
11700
11748
  const r = await remoteCall(url, flags, "/api/workspaces", { method: "POST", body: JSON.stringify({ demo: true }) });