foldrun 19.3.2 → 20.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
@@ -303,6 +303,7 @@ Signing in
303
303
  foldrun use <name> act as one of them from here on
304
304
  foldrun keys ls the account's API keys: created, last used, expires, scope, and which are a machine's CLI sign-in (they renew themselves) — also create <label> [--expires 90d], rotate <id> [--grace 1h], revoke <id>
305
305
  foldrun keys create <label> --a2a --to <ws> --flows a,b a key for an OUTSIDE agent: it opens /a2a for those published flows and no /api route (--max-tasks N open at once, default 10; --expires); shown once
306
+ foldrun keys create <label> --gateway --cap <usd> [--daily <usd>] a key for a CODING agent (Claude Code: ANTHROPIC_BASE_URL + this key) — it spends the account's credits on foldrun's models through the gateway, up to its own limits, and opens no /api route; an admin of every workspace; shown once
306
307
  foldrun a2a ls --to <ws> what a workspace serves over A2A: each flow's a2a:, card and endpoint URLs, its A2A keys (admins), recent tasks and the key that asked (--json)
307
308
  foldrun a2a publish <flow> set a2a: publish: true in the flow (--to <ws>: the deployed copy, an admin's) — --name, --description, --example "…" (repeatable), --public-card | --private-card; diff, checked, --dry-run
308
309
  foldrun a2a publish <flow> --clear-name | --clear-description | --clear-examples drop the card's name, description or examples (also on unpublish)
@@ -451,6 +452,8 @@ Options
451
452
  --expires <span> keys create: when it stops working — 30d, 90d (default, as in the dashboard), 365d or never; --forever is never
452
453
  --grace <span> keys rotate: keep the old key working for 1h or 24h while you swap the new one in (default 0: revoked now)
453
454
  --a2a keys create: an A2A key for an outside agent — with --to <workspace> and --flows a,b; --max-tasks <n> caps its open tasks (1–100, default 10)
455
+ --gateway keys create: a gateway key for Claude Code — with --cap <usd> (in all) and/or --daily <usd> (per UTC day)
456
+ --cap <usd>, --daily <usd> keys create --gateway: the key's own spending limits, $0.01–$100000
454
457
  --key-env <NAME> a2a call, a2a status, a2a cancel, a2a card: the environment variable holding the A2A key (default FOLDRUN_A2A_KEY) — a key is never taken on the command line
455
458
  --card <url> a2a status, a2a cancel: the agent card of the agent that holds the task
456
459
 
@@ -495,7 +498,7 @@ if (!command || command === "--help" || command === "-h") {
495
498
  // `--value` as the account's argument and stored an empty secret; `--force
496
499
  // ./dir` swallowed the directory. A flag followed by another flag is also
497
500
  // boolean, so an unlisted switch at least does not eat its neighbour.
498
- const BOOLEAN_FLAGS = new Set(["read-only", "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", "generate-key", "device", "write", "dpop", "export", "isolated", "no-wait", "dismissed", "unread", "team", "started", "mine", "none", "a2a", "public-card", "private-card", "return-immediately", "online", "overwrite", "no-send", "event-wait", "with-client", "use", "clear-name", "clear-description", "clear-examples", "clear-accept-risk", "clear-address", "clear-email", "clear-abn", "no-task", "empty"]);
501
+ const BOOLEAN_FLAGS = new Set(["read-only", "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", "generate-key", "device", "write", "dpop", "export", "isolated", "no-wait", "dismissed", "unread", "team", "started", "mine", "none", "a2a", "gateway", "public-card", "private-card", "return-immediately", "online", "overwrite", "no-send", "event-wait", "with-client", "use", "clear-name", "clear-description", "clear-examples", "clear-accept-risk", "clear-address", "clear-email", "clear-abn", "no-task", "empty"]);
499
502
  // Flags said more than once collect into a list: `--tag a --tag b`.
500
503
  const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove", "rule", "authorize-param", "example", "accept-risk"]);
501
504
  // `--wait` is a switch everywhere but `flow add <flow> wait`, where it takes
package/docs/api.md CHANGED
@@ -366,7 +366,7 @@ Reads return which secrets exist, never their values.
366
366
 
367
367
  | Route | Methods | |
368
368
  |---|---|---|
369
- | `/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 }`. POST `{ purpose: "a2a", workspace, flows, maxTasks?, label?, expires? }` mints an A2A key instead: for an outside agent, it opens `/a2a/<account>/<workspace>/…` for the named flows (each must say `a2a: { publish: true }` when the key is minted — a flow not published is refused, 400 — and still say it on every call) and every `/api` route refuses it (403); `maxTasks` (1–100, default 10) caps its tasks open at once; it answers `{ ok, key, id, prefix, purpose, workspace, flows, maxTasks, role, workspaces, expiresAt }`, and rotating one keeps the tasks it made, 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` |
369
+ | `/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 }`. POST `{ purpose: "a2a", workspace, flows, maxTasks?, label?, expires? }` mints an A2A key instead: for an outside agent, it opens `/a2a/<account>/<workspace>/…` for the named flows (each must say `a2a: { publish: true }` when the key is minted — a flow not published is refused, 400 — and still say it on every call) and every `/api` route refuses it (403); `maxTasks` (1–100, default 10) caps its tasks open at once; it answers `{ ok, key, id, prefix, purpose, workspace, flows, maxTasks, role, workspaces, expiresAt }`, and rotating one keeps the tasks it made, and the key is shown once. POST `{ purpose: "gateway", capUsd?, dailyUsd?, label?, expires? }` mints a gateway key: for a coding agent such as Claude Code (`ANTHROPIC_BASE_URL` + the key, [Claude Code](claude-code.md)), it spends the account's credits on foldrun's Anthropic models through the gateway and every `/api` route refuses it (403); it needs `capUsd` (USD in all) or `dailyUsd` (USD per UTC day), $0.01–$100,000 after rounding to cents, is minted only by an admin of every workspace (a scoped admin is 403) and only on the hosted platform (400 elsewhere), and answers `{ ok, key, id, prefix, purpose, capUsd, dailyUsd, expiresAt, gatewayUrl }`; rotating one keeps its limits. 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), a gateway key's `gateway: { capUsd, dailyUsd, spentUsd, todayUsd }` (spent in all and today, UTC, calls in flight at their hold), and at the top `gatewayUrl` (the gateway's address; `null` where the install has none) — 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` |
370
370
  | `/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 — except that a key `foldrun login` minted may rotate **itself**, whatever its role: same label, role, workspaces and 90-day lifetime from today, the old key ending 10 minutes later (`grace` is not read). A retry with the old key inside those 10 minutes — the CLI lost the answer, or could not store it — rotates that replacement instead, when nobody has used it and it is at least 30 seconds old (a younger one is a 409: another command may have just stored it). That is how the CLI renews its sign-in; any other key rotating itself still needs `keys:manage`. Audited as `apikey.rotated` (`self: true` for a self-rotation). A `foldrun login` key stays one only when it renews itself or its own person rotates it, signed in; rotated by any other caller the new key is an ordinary one |
371
371
  | `/api/team` | GET, POST | members with their roles and workspace scope; mint an invite (a session, or the person's own `foldrun login` key, which invites no admin) — `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 |
372
372
  | `/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 |
@@ -0,0 +1,93 @@
1
+ # Claude Code on foldrun's models
2
+
3
+ Claude Code — and any tool that takes an Anthropic base URL and key — can run
4
+ on your foldrun account's credits instead of an Anthropic account of your
5
+ own. You mint a **gateway key**, point the tool at foldrun's gateway, and
6
+ every call is billed to the account at foldrun's price list, up to the key's
7
+ own limits.
8
+
9
+ ```sh
10
+ export ANTHROPIC_BASE_URL=https://<the gateway URL> # Settings → API keys shows it
11
+ export ANTHROPIC_API_KEY=mda_… # the gateway key
12
+ claude
13
+ ```
14
+
15
+ `ANTHROPIC_AUTH_TOKEN` works in place of `ANTHROPIC_API_KEY` (it is sent as
16
+ `Authorization: Bearer`). This is on the hosted platform only; a self-hosted
17
+ install has no gateway.
18
+
19
+ ## Minting a gateway key
20
+
21
+ On **Settings → API keys**, pick **Gateway key — Claude Code** as the kind,
22
+ or from a terminal:
23
+
24
+ ```sh
25
+ foldrun keys create laptop --gateway --cap 20 --daily 5
26
+ ```
27
+
28
+ - **A limit of its own is required:** `--cap` (USD, in all) or `--daily`
29
+ (USD, per UTC day), or both — from $0.01 to $100,000.
30
+ Limits are in dollars charged — what the account pays at foldrun's price
31
+ list — and so is the spend `keys ls` shows. Spend is counted at the margin in force
32
+ now, so if foldrun changes its margin, a key's past spend is counted at the
33
+ new one.
34
+ - **Who may mint one:** an admin of every workspace. The key spends the
35
+ whole account's balance, so a workspace-scoped admin cannot.
36
+ - **What it opens:** the gateway only. Every `/api` route refuses it (403),
37
+ so it cannot read a workspace, start a run or mint a key. An account API
38
+ key is refused by the gateway the same way.
39
+ - **Shown once**, like every key. `foldrun keys ls` (and the Settings list)
40
+ shows what it has spent against each limit; `rotate` keeps its limits, and
41
+ the new key's spend starts afresh; `revoke` ends it at once.
42
+
43
+ The API is `POST /api/keys { purpose: "gateway", capUsd?, dailyUsd?, label?, expires? }`
44
+ ([API](api.md)).
45
+
46
+ ## What the gateway serves
47
+
48
+ | Route | |
49
+ |---|---|
50
+ | `POST /v1/messages` | metered, streamed or not |
51
+ | `POST /v1/messages/count_tokens` | free |
52
+ | `GET /v1/models` | free |
53
+
54
+ Anything else is a 404; a query string (`/v1/models?after_id=…`) goes on as
55
+ it came. Anthropic's models only. Your key never reaches
56
+ Anthropic: the gateway sends the call with the platform's own key, and only
57
+ the headers Anthropic's API reads (`anthropic-version`, `anthropic-beta`,
58
+ `content-type`, `accept`).
59
+
60
+ ## Limits and refusals
61
+
62
+ Each call is checked the way a run's call on foldrun's models is
63
+ ([budgets and billing](budgets-and-billing.md)):
64
+
65
+ - the account must have credit, and foldrun's models must be on for it;
66
+ - the model must be on the price list;
67
+ - the call is held at the most it could cost (its input, and every output
68
+ token it may ask for) against the account's daily limit **and** the key's
69
+ own limits, before it is sent — so calls at once cannot pass a limit
70
+ together, and a call that would pass one is refused, not cut off midway;
71
+ - it is charged what Anthropic reports it used, or its hold if no usage
72
+ came back (a reply cut short).
73
+
74
+ Because a call is held at its most, a key's limit needs room for the
75
+ calls Claude Code makes at once — a few dollars, not cents.
76
+
77
+ Request fields billed outside tokens are refused until they have a price:
78
+ server tools (web search, code execution), a one-hour prompt cache, a
79
+ priority tier.
80
+
81
+ A refusal comes back in Anthropic's own error shape, so Claude Code prints
82
+ the reason:
83
+
84
+ | Status | Why |
85
+ |---|---|
86
+ | `401` | no key, an unknown, revoked or expired key |
87
+ | `403` | not a gateway key; foldrun's models off for the account |
88
+ | `402` | out of credits; the key's limit or the account's daily limit has no room; a model with no price |
89
+ | `400` | a request field that is not offered (named in the message) |
90
+
91
+ A spent limit is a `402`, not a `429`: Claude Code retries a `429` for minutes,
92
+ and no retry makes room under a limit. A `429` from Anthropic itself comes
93
+ back as it was.
package/docs/cli.md CHANGED
@@ -208,6 +208,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
208
208
  | `foldrun keys ls` | the account's API keys, each with its role and scope, when it was created, when it was last used and from where (a /24 or /48), and when it expires; a key `foldrun login` minted is tagged `CLI sign-in · renews itself` (revoke it to sign that machine out) — also `create <label>` (`--expires 30d\|90d\|365d\|never`), `rotate <id>` and `revoke <id>` |
209
209
  | `foldrun keys rotate <id>` | a new key with the old one's label, role, workspaces and deploy scope, printed once; the old key is revoked at once (asks first; `--yes` on a pipe), or keeps working for `--grace 1h` / `24h` while you swap the new one in. A key already rotated is refused (409) and the command names the key that replaced it — rotate that one, also if its secret was lost; `keys ls` shows `rotated → <id>`. The owner is emailed a week before any key expires |
210
210
  | `foldrun keys create <label> --a2a --to <ws> --flows a,b` | a key for an outside agent ([A2A](a2a.md)): it opens `/a2a/<account>/<ws>/…` — the agent card and JSON-RPC endpoint of those flows, each published with `a2a:` (a flow not published when the key is minted is refused: publish first) — and no `/api` route. `--max-tasks <n>` caps the tasks it may have open at once (1–100, default 10); `--expires` as for any key. Printed once; `keys ls` shows it as `A2A · <ws> · <flows>`. `POST /api/keys { purpose: "a2a", workspace, flows, maxTasks }`, an admin's |
211
+ | `foldrun keys create <label> --gateway --cap <usd>` | a gateway key for a coding agent ([Claude Code](claude-code.md)): `ANTHROPIC_BASE_URL` + this key run Claude Code on the account's credits, through foldrun's gateway, and it opens no `/api` route. `--cap` (USD in all) and/or `--daily` (USD per UTC day) — at least one, $0.01–$100,000; `--expires` as for any key. Printed once with the two `export` lines; `keys ls` shows it as `gateway · Claude Code · $spent of $cap · $today of $daily today`. `POST /api/keys { purpose: "gateway", capUsd, dailyUsd }`, an admin of every workspace |
211
212
  | `foldrun a2a ls --to <ws>` | what a workspace serves over A2A (`GET /api/workspaces/<ws>/a2a`): every flow that says `a2a:`, published or not, with its public/private card and its card and endpoint URLs; the workspace's A2A keys (an admin's view; `null` otherwise); and the newest tasks — state, flow, run, and `A2A · <key label>`; then, under **Secret and code**, every agent that holds a secret and can run code, accepted or not, with the `--accept-risk` line that accepts it. `--json` prints the answer as it came |
212
213
  | `foldrun a2a publish <flow>` | sets `a2a: { publish: true }` in the flow, keeping the rest of its block: `--name`, `--description`, `--example "…"` (repeatable — the card's examples), `--public-card` (the card is readable without a key; calling never is) or `--private-card`. Checked with core's `a2a:` rules before anything is written; shows the diff, `--dry-run` writes nothing. Without `--to` it edits this folder (`deploy` ships it); `--to <workspace>` sends the flow page's `PATCH …/flows/<flow> { a2a, expect }` — an admin's, the platform refuses an editor — and prints the card URL. A caller also needs an A2A key that names the flow |
213
214
  | `foldrun a2a unpublish <flow>` | `a2a: publish: false` — no outside agent may call it, whatever keys name it; the rest of `a2a:` stays for the next publish. `--to`, `--dry-run` as for `publish` |
@@ -313,6 +314,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
313
314
  | `--expires <span>` | `keys create`: when it stops working — `30d`, `90d` (the default, as in the dashboard; before CLI 15.0.0 the default was never), `365d` or `never`; `--forever` is `never` |
314
315
  | `--grace <span>` | `keys rotate`: keep the old key working for `1h` or `24h` (default `0`: revoked now) |
315
316
  | `--a2a` | `keys create`: an A2A key for an outside agent, with `--to <workspace>`, `--flows a,b` and optionally `--max-tasks <n>` |
317
+ | `--gateway` | `keys create`: a gateway key for Claude Code, with `--cap <usd>` and/or `--daily <usd>` |
316
318
  | `--key-env <NAME>` | `a2a call`, `a2a status`, `a2a cancel`, `a2a card`: the environment variable that holds the A2A key (default `FOLDRUN_A2A_KEY`) |
317
319
  | `--card <url>` | `a2a status`, `a2a cancel`: the agent card of the agent that holds the task |
318
320
  | `--force` | `deploy`: deploy while runs are in flight. `pull`, `storage get`: overwrite local files |
@@ -214,6 +214,54 @@ Nothing about the folder changes. What the platform adds is the operating around
214
214
  [Secrets](secrets) in a vault, [Notifications](notifications),
215
215
  [Budgets and billing](budgets-and-billing), [Team and access](team-and-access).
216
216
 
217
+ ## Moving records into the database
218
+
219
+ Runs, the trigger log and the storage file index used to be files on the data
220
+ volume. With a database configured they move into Postgres, one workspace at a
221
+ time, while the other processes keep running.
222
+
223
+ A row per workspace in `records_routing` says where its records are, and every
224
+ process with a database reads the same rows:
225
+
226
+ | State | Meaning |
227
+ |---|---|
228
+ | `files` | The files are the records. |
229
+ | `moving` | An import is making the rows match the files. A record call waits up to 5 s, then is refused as busy. |
230
+ | `database` | The rows are the records, for good. There is no way back to files. |
231
+
232
+ A workspace with no row follows `('*', '*')`, the install's default, which
233
+ stays `files` until a move has taken everything. `FOLDRUN_RECORDS=files` means
234
+ only "this process never starts a move": a workspace another process moved is
235
+ read and written as rows there too, and a process that cannot read the routing
236
+ for 10 s refuses record calls rather than guess.
237
+
238
+ A move copies the files into rows, holds the workspaces at `moving` until every
239
+ process seen in the last 30 s has acknowledged it, makes the rows exactly what
240
+ the files say, flips them to `database`, and only then sets the files aside as
241
+ `.imported-<date>`.
242
+
243
+ **Upgrading:**
244
+
245
+ 1. Deploy this release with `FOLDRUN_RECORDS=files` on every process (web,
246
+ worker, assistant) and wait until no process of the old release is left
247
+ (`kubectl rollout status deploy/<name>` for each). An older process reads no
248
+ routing, so a move while one runs would hide what it reads.
249
+ 2. Remove `FOLDRUN_RECORDS=files`. A rolling restart is fine: the first process
250
+ to boot in database mode moves everything. Pick a quiet moment — a run
251
+ saving while its workspace is held can fail as busy.
252
+ 3. Watch the ops log: `records.on_files` (workspaces still on files, with the
253
+ `records.import_failed` that says why; the next boot tries again),
254
+ `records.move_abandoned` (`reason=not_acknowledged`: an old or stuck process
255
+ did not answer within 60 s) and `records.stray_set_aside` (a record file
256
+ found in a workspace already in the database; kept as `.stray-<date>`, never
257
+ merged in).
258
+
259
+ The timings are `FOLDRUN_RECORDS_ROUTING_BEAT_MS` (1000),
260
+ `FOLDRUN_RECORDS_ROUTING_LEASE_MS` (10000), `FOLDRUN_RECORDS_MOVING_WAIT_MS`
261
+ (5000), `FOLDRUN_RECORDS_ACK_WAIT_MS` (60000) and `FOLDRUN_RECORDS_SETTLE_MS`
262
+ (120000, raise it for very large workspaces); keep them the same on every
263
+ process.
264
+
217
265
  ## Where the data is
218
266
 
219
267
  On your machine: in the folder. On the platform: your workspace's files and
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "foldrun",
3
- "version": "19.3.2",
3
+ "version": "20.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": "^17.4.0"
14
+ "@foldrun/core": "^18.0.0"
15
15
  },
16
16
  "files": [
17
17
  "bin",
@@ -22,7 +22,7 @@
22
22
  ],
23
23
  "scripts": {
24
24
  "e2e": "FOLDRUN_E2E=1 FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-e2e-XXXXXX) node --test --test-timeout=300000 tests/e2e.test.ts",
25
- "test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-issues.test.ts tests/cli-capture.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-team-me.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-agent-link-isolated.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-report-cache.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts tests/cli-check-scan.test.ts tests/cli-published.test.ts tests/cli-init-target.test.ts tests/cli-flow-filter.test.ts tests/cli-eval-grades.test.ts tests/cli-eval-compare.test.ts tests/cli-proposals.test.ts tests/cli-inbox.test.ts tests/cli-usage-compute.test.ts tests/cli-fol105.test.ts tests/cli-key-renew.test.ts tests/cli-wait-failed.test.ts tests/cli-mcp.test.ts tests/cli-a2a.test.ts tests/cli-switches.test.ts tests/cli-parity-runs.test.ts tests/cli-parity-b.test.ts tests/cli-parity-clears.test.ts tests/cli-parity-c.test.ts tests/cli-runs-paging.test.ts tests/cli-budget-invoices.test.ts tests/cli-observe-analysis.test.ts tests/cli-failure-retention.test.ts",
25
+ "test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-issues.test.ts tests/cli-capture.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-team-me.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-agent-link-isolated.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-report-cache.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts tests/cli-check-scan.test.ts tests/cli-published.test.ts tests/cli-init-target.test.ts tests/cli-flow-filter.test.ts tests/cli-eval-grades.test.ts tests/cli-eval-compare.test.ts tests/cli-proposals.test.ts tests/cli-inbox.test.ts tests/cli-usage-compute.test.ts tests/cli-fol105.test.ts tests/cli-key-renew.test.ts tests/cli-wait-failed.test.ts tests/cli-mcp.test.ts tests/cli-a2a.test.ts tests/cli-gateway.test.ts tests/cli-switches.test.ts tests/cli-parity-runs.test.ts tests/cli-parity-b.test.ts tests/cli-parity-clears.test.ts tests/cli-parity-c.test.ts tests/cli-runs-paging.test.ts tests/cli-budget-invoices.test.ts tests/cli-observe-analysis.test.ts tests/cli-failure-retention.test.ts",
26
26
  "release": "node scripts/release.mjs",
27
27
  "typecheck": "tsc -p tsconfig.json",
28
28
  "docs:sync": "node scripts/sync-docs.mjs",
package/src/commands.mjs CHANGED
@@ -4695,6 +4695,7 @@ async function doctor(flags) {
4695
4695
  * keys revoke <id>
4696
4696
  * keys create <label> --expires 90d it stops working in 90 days (30d, 365d, never)
4697
4697
  * keys create <label> --a2a --to <ws> --flows a,b [--max-tasks N] a key for an outside agent: /a2a only
4698
+ * keys create <label> --gateway --cap <usd> [--daily <usd>] a coding agent's key (Claude Code): the gateway only
4698
4699
  * keys rotate <id> [--grace 1h] a new key, same label/role/scope; the old
4699
4700
  * one ends now, or when the grace runs out.
4700
4701
  * A key already rotated is refused (409):
@@ -4719,6 +4720,8 @@ async function keysCmd(positional, flags) {
4719
4720
  // A deploy key opened the platform's own git, gone since 17 Oct 2026.
4720
4721
  const what = k.scope
4721
4722
  ? "deploy key · opens nothing since the platform's git went — revoke it"
4723
+ : k.purpose === "gateway"
4724
+ ? gatewayLine(k.gateway)
4722
4725
  : k.purpose === "a2a"
4723
4726
  ? `A2A · ${k.a2a?.workspace ?? "?"} · ${(k.a2a?.flows ?? []).join(",")}${k.a2a?.maxTasks ? ` · up to ${k.a2a.maxTasks} open` : ""}`
4724
4727
  : `${k.role ?? "admin"} · ${k.workspaces ? k.workspaces.join(",") || "no workspaces" : "all workspaces"}`;
@@ -4738,7 +4741,9 @@ async function keysCmd(positional, flags) {
4738
4741
  }
4739
4742
  if (verb === "create" || verb === "new") {
4740
4743
  if (!arg) throw new Error("what is the key for? foldrun keys create <label>");
4744
+ if (flags.a2a === true && flags.gateway === true) throw new Error("--a2a or --gateway, not both");
4741
4745
  if (flags.a2a === true) return keysCreateA2a(url, arg, flags);
4746
+ if (flags.gateway === true) return keysCreateGateway(url, arg, flags);
4742
4747
  const body = { label: arg };
4743
4748
  if (typeof flags.role === "string") body.role = flags.role;
4744
4749
  // --expires 30d|90d|365d|never (--forever is never); unsaid, 90 days —
@@ -4821,6 +4826,57 @@ async function keysCreateA2a(url, label, flags) {
4821
4826
  return 0;
4822
4827
  }
4823
4828
 
4829
+ /** How `keys ls` describes a gateway key: its limits, and what it has spent. */
4830
+ function gatewayLine(g) {
4831
+ const usd = (n) => `$${Number(n ?? 0).toFixed(2)}`;
4832
+ const parts = ["gateway · Claude Code"];
4833
+ if (g?.capUsd != null) parts.push(`${usd(g.spentUsd)} of ${usd(g.capUsd)}`);
4834
+ else if (g?.spentUsd != null) parts.push(`${usd(g.spentUsd)} spent`);
4835
+ if (g?.dailyUsd != null) parts.push(`${usd(g.todayUsd)} of ${usd(g.dailyUsd)} today`);
4836
+ return parts.join(" · ");
4837
+ }
4838
+
4839
+ /** A dollar limit from a flag: above 0, at most 100000 (what the platform takes). */
4840
+ function usdFlag(v, name) {
4841
+ if (v === undefined) return undefined;
4842
+ const n = Number(v);
4843
+ if (v === true || !Number.isFinite(n) || n <= 0 || n > 100_000) throw new Error(`${name} takes a number of dollars above 0 and at most 100000 — e.g. ${name} 20`);
4844
+ return n;
4845
+ }
4846
+
4847
+ /**
4848
+ * `foldrun keys create <label> --gateway --cap <usd> [--daily <usd>]` — a
4849
+ * key for a CODING agent (Claude Code, or any tool that takes an Anthropic
4850
+ * base URL and key): it spends the account's credits on foldrun's Anthropic
4851
+ * models through the gateway, up to its own limits, and opens no /api route.
4852
+ * An admin of every workspace mints it.
4853
+ */
4854
+ async function keysCreateGateway(url, label, flags) {
4855
+ if (flags.role !== undefined || flags.workspaces !== undefined || flags.to !== undefined || flags.flows !== undefined) {
4856
+ throw new Error("a gateway key takes --cap and --daily, not --role, --workspaces, --to or --flows — it opens the gateway only, never the API");
4857
+ }
4858
+ const capUsd = usdFlag(flags.cap, "--cap");
4859
+ const dailyUsd = usdFlag(flags.daily, "--daily");
4860
+ if (capUsd === undefined && dailyUsd === undefined) throw new Error("a gateway key needs a limit of its own: --cap <usd> in all, or --daily <usd> per UTC day (or both)");
4861
+ const body = { label, purpose: "gateway" };
4862
+ if (capUsd !== undefined) body.capUsd = capUsd;
4863
+ if (dailyUsd !== undefined) body.dailyUsd = dailyUsd;
4864
+ if (flags.forever === true && flags.expires !== undefined) throw new Error("--forever or --expires <span>, not both");
4865
+ // As for an API key: a bare --expires is refused, never read as 90 days (Codex review).
4866
+ if (flags.expires !== undefined && typeof flags.expires !== "string") throw new Error("--expires needs a span: 30d, 90d, 365d or never");
4867
+ body.expires = flags.forever === true ? "never" : typeof flags.expires === "string" ? flags.expires : "90d";
4868
+ const made = await remoteCall(url, flags, "/api/keys", { method: "POST", body: JSON.stringify(body) });
4869
+ console.log(`\n ${c.green("✓")} ${c.bold(label)} ${c.dim(made.id)} ${c.dim(gatewayLine({ capUsd: made.capUsd ?? null, dailyUsd: made.dailyUsd ?? null, spentUsd: 0, todayUsd: 0 }))}${made.expiresAt ? c.dim(` expires ${made.expiresAt.slice(0, 10)}`) : ""}\n`);
4870
+ if (made.key == null) return lostSecret(made.id);
4871
+ console.log(` ${made.key}\n`);
4872
+ const base = made.gatewayUrl ?? "<the gateway URL — not set on this platform yet>";
4873
+ console.log(` ${c.dim("Shown once. Point Claude Code at it:")}\n`);
4874
+ console.log(` export ANTHROPIC_BASE_URL=${base}`);
4875
+ console.log(` export ANTHROPIC_API_KEY=<key>\n`);
4876
+ console.log(` ${c.dim(`It opens the gateway only. \`foldrun keys ls\` shows what it has spent; \`foldrun keys revoke ${made.id}\` ends it.`)}\n`);
4877
+ return 0;
4878
+ }
4879
+
4824
4880
  /** A retried mint or rotate is answered from the first call, and the server
4825
4881
  * never stores a key's secret — so a retry after a lost answer has none. */
4826
4882
  function lostSecret(id) {