foldrun 21.2.1 → 21.3.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 +4 -2
- package/docs/api.md +4 -2
- package/docs/cli.md +2 -1
- package/docs/runs.md +23 -7
- package/package.json +1 -1
- package/src/commands.mjs +55 -8
package/bin/foldrun.mjs
CHANGED
|
@@ -306,6 +306,7 @@ Signing in
|
|
|
306
306
|
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>
|
|
307
307
|
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
|
|
308
308
|
foldrun keys set <id> --sonnet openai/gpt-6 which model a gateway key runs each Claude Code tier on (--opus, --haiku; - clears one, --clear all)
|
|
309
|
+
foldrun keys set <id> --customer required|optional whether every run (API key) or gateway call (gateway key) with it must name an end customer — create one that requires it with keys create … --require-customer
|
|
309
310
|
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
|
|
310
311
|
foldrun keys create laptop --gateway --cap 20 --claude-code the same, and Claude Code is set up on this machine: the URL and key go into its settings, and its status line shows the key's spend
|
|
311
312
|
foldrun gateway status-line one line for Claude Code's status line: what the gateway key in ANTHROPIC_AUTH_TOKEN has spent, of its limits (asks the gateway; kept 10 s, --cache <s>)
|
|
@@ -318,7 +319,7 @@ Signing in
|
|
|
318
319
|
foldrun a2a card <flow> --to <ws> the flow's agent card URL and endpoint, then the card (a private card needs an A2A key in $FOLDRUN_A2A_KEY or --key-env)
|
|
319
320
|
foldrun a2a call <card-url> "<text>" send one message to an A2A 1.0 agent — a published flow or anyone's — and wait for the task (--data <json|@file>, --context <id>, --no-wait or --return-immediately, --max-wait <s>, --json); the A2A key comes from $FOLDRUN_A2A_KEY or --key-env NAME, never this CLI's API key
|
|
320
321
|
foldrun a2a status <task-id> --card <url> the task as it stands now (--json) — cancel <task-id> --card <url> stops it (asks; --yes)
|
|
321
|
-
foldrun customers your own users, by the id on their runs and gateway calls: the limits each is held to and who is blocked — block <id> [--reason], unblock <id>, limits --starts-per-minute N --gateway-rpm N --gateway-concurrency N (default puts one back), --json
|
|
322
|
+
foldrun customers your own users, by the id on their runs and gateway calls: the limits each is held to and who is blocked — block <id> [--reason], unblock <id>, usage [--days 7] (model spend per customer), limits --starts-per-minute N --max-open-runs N --gateway-rpm N --gateway-concurrency N --daily-model-usd D (default / none puts one back), --json
|
|
322
323
|
foldrun audit the account's audit log, newest first: sign-ins, keys, invites, secrets by name, deploys, support views (--since 7d, --action, --actor, --to, --all, --csv)
|
|
323
324
|
foldrun --version this CLI's version, offline (\`foldrun version\` also asks the platform)
|
|
324
325
|
foldrun --help everything; \`foldrun <command> --help\`, \`-h\` or \`foldrun help <command>\` for one (never runs it)
|
|
@@ -335,6 +336,7 @@ Options
|
|
|
335
336
|
--task "<text>" flow inputs save: the task the saved set holds (--file <path> reads it from a file)
|
|
336
337
|
--test run, invoke: a test run — nothing outward, state/ untouched, receipts on the run page
|
|
337
338
|
--file <path> invoke, agent run: a file handed to the run (repeatable) — a storage path, or ./local-file uploaded to storage/inputs/ first; the first step finds them in inputs/ and can read images and PDFs (FOL-163)
|
|
339
|
+
--require-customer keys create: every run (or gateway call) with the key must name an end customer (FOL-168)
|
|
338
340
|
--customer <id> invoke, agent run: which of your own users the run is for (FOL-168) — limits and blocks follow it; runs: only that customer's runs
|
|
339
341
|
--reason "<text>" customers block: why, kept on the block and the audit log
|
|
340
342
|
--context <id> invoke, agent run: a turn of that conversation — the first step reads the earlier runs started with the same context (any id you choose, 1–200 printable characters); runs: only that conversation's runs
|
|
@@ -512,7 +514,7 @@ if (!command || command === "--help" || command === "-h") {
|
|
|
512
514
|
// `--value` as the account's argument and stored an empty secret; `--force
|
|
513
515
|
// ./dir` swallowed the directory. A flag followed by another flag is also
|
|
514
516
|
// boolean, so an unlisted switch at least does not eat its neighbour.
|
|
515
|
-
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", "claude-code", "login", "unreachable", "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", "plain", "no-beep"]);
|
|
517
|
+
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", "claude-code", "login", "unreachable", "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", "plain", "no-beep", "require-customer"]);
|
|
516
518
|
// Flags said more than once collect into a list: `--tag a --tag b`.
|
|
517
519
|
const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove", "rule", "authorize-param", "example", "accept-risk"]);
|
|
518
520
|
/** Flags that become a list only when given more than once (FOL-163 `--file`). */
|
package/docs/api.md
CHANGED
|
@@ -199,7 +199,7 @@ history with each message.
|
|
|
199
199
|
|---|---|---|
|
|
200
200
|
| `/api/workspaces/<ws>/agents` | GET, POST | list — each agent's frontmatter as read, `owner` and `ownerFrom` (its own `owner:`, else the workspace's, else the account's), `lastRunAt` (when its latest step that ran started, from the runs kept; null for none) and `stale` (past `alerts: stale_days`); create (`name`) |
|
|
201
201
|
| `/api/workspaces/<ws>/agents/<agent>` | PATCH | edit one line of an agent's frontmatter in place, as the flow canvas does: `{ list: { key, name, action } }` — `key` one of `subagents`, `agents`, `tools`; `action` `add` or `remove` — or `{ set: { key: "description" | "sandbox", value } }` (`sandbox` takes `own` or `parent`, else 400), or `{ network }` — the sites its sandbox may reach: `"open"`, `"trusted"`, `"none"`, a list of sites, or `{ level, allow, defaults }`; `null` removes the line so it inherits ([Network](network)). A `network` nobody could read is a 400 that says why. Only that key's lines change — comments, key order and prose stay. Answers `{ ok, changed }`; 404 for an unknown agent. `workspace:write` |
|
|
202
|
-
| `/api/workspaces/<ws>/agents/<agent>/run` | POST | run one agent alone (`task`; `test: true` for a test run; `customer`: which of your own users it is for ([end customers](runs#end-customers): its limits and blocks follow it; `403` code `customer_blocked`, `429` code `customer_rate` with `Retry-After`); `inputs`: storage paths handed to the step at `inputs/` ([inputs](runs#inputs): at most 20 and 100 MiB, held as they are when the run is made; `404` names a path with no stored file, `409` where the install has no sandbox to stage them; the answer lists them); `context`: a [conversation](runs#conversations) the run is a turn of — the agent reads the earlier runs of the same context before the task, and the answer carries `context`; `snapshot`: a folder to work on, the id `POST …/snapshots` answered — the step finds it in `snapshot/`, only its `outputs/` come back to the workspace, and the run's outputs hold `snapshot.patch`, the change as a git patch, with `snapshot.json` saying what it touched or why there is none. Needs the k8s sandbox: `409` on an install without it, `404` for a snapshot not in this workspace) |
|
|
202
|
+
| `/api/workspaces/<ws>/agents/<agent>/run` | POST | run one agent alone (`task`; `test: true` for a test run; `customer`: which of your own users it is for ([end customers](runs#end-customers): its limits and blocks follow it; `403` code `customer_blocked`, `429` code `customer_rate` with `Retry-After`, or `customer_open_runs`); `inputs`: storage paths handed to the step at `inputs/` ([inputs](runs#inputs): at most 20 and 100 MiB, held as they are when the run is made; `404` names a path with no stored file, `409` where the install has no sandbox to stage them; the answer lists them); `context`: a [conversation](runs#conversations) the run is a turn of — the agent reads the earlier runs of the same context before the task, and the answer carries `context`; `snapshot`: a folder to work on, the id `POST …/snapshots` answered — the step finds it in `snapshot/`, only its `outputs/` come back to the workspace, and the run's outputs hold `snapshot.patch`, the change as a git patch, with `snapshot.json` saying what it touched or why there is none. Needs the k8s sandbox: `409` on an install without it, `404` for a snapshot not in this workspace) |
|
|
203
203
|
| `/api/workspaces/<ws>/agents/import` | GET, POST | copy an agent in from another workspace of the account. GET lists what could be imported (every other workspace you can read, with its agents). POST `{ from, agent, as? }` copies `agents/<agent>/` — its agent.md and own skills/, scripts/, knowledge/; never memory/, outputs/, state/ — and answers `{ name, files, warnings }`; `warnings` names tools, skills, scripts and secrets the copy uses that this workspace lacks. 409 on a name clash (pass `as`), 404 for an unknown workspace or agent, 403 when `from` is outside your key's scope. Idempotent |
|
|
204
204
|
| `/api/workspaces/<ws>/proposals` | GET | the workspace's proposed fixes, newest first (`404` when the workspace does not exist): `{ proposals: [{ id, workspace, eval, by (auto, or who asked), createdAt, updatedAt, status, failures: [{ runId?, case?, check, detail, at }], jobId, reply (the assistant's reasoning), files: [{ path, content, before, sha256 }], issues: [{ where, message, level }], error?, notes?, decidedBy?, decidedAt?, applied? }] }`. `status` is `drafting`, `ready`, `failed`, `applying`, `applied`, `partial` (a write failed part-way; `applied` names what was written) or `dismissed`. `?status=`, `?eval=`. A drafting one is settled as it is read |
|
|
205
205
|
| `/api/workspaces/<ws>/proposals/<id>` | GET, POST | one proposal. `POST { action: "apply" }` writes its files, each a revision by the caller, only when every one still reads what it was drawn against (`409` naming the file that changed) and can be written (`422`; a check error the deploy would refuse is `422` too); `POST { action: "dismiss" }` sets it aside — its failures stay looked at. Only agents, flows and skills are ever in one. Needs `workspace:write` |
|
|
@@ -368,6 +368,7 @@ Reads return which secrets exist, never their values.
|
|
|
368
368
|
| Route | Methods | |
|
|
369
369
|
|---|---|---|
|
|
370
370
|
| `/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 }`. A key's prefix says what it is: `fr_api_` an API key, `fr_a2a_` an A2A key (`fr_dep_` is reserved for deploy keys); keys minted before 11 Nov 2026 start `mda_` (or `mdk_`) and keep working — a key is looked up by its hash, never its prefix, and `prefix` is its first 12 characters. 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` |
|
|
371
|
+
| `/api/keys/<id>` | PATCH | `{ requireCustomer: true \| false }` — whether every run the key starts must name an end customer ([end customers](runs#end-customers)); a run without one is refused `400`, code `customer_required`. Not for an A2A key. An admin of every workspace; audited as `apikey.require_customer`. `POST /api/keys` takes `requireCustomer` too |
|
|
371
372
|
| `/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 |
|
|
372
373
|
| `/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 |
|
|
373
374
|
| `/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 |
|
|
@@ -396,7 +397,8 @@ Reads return which secrets exist, never their values.
|
|
|
396
397
|
| `/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) |
|
|
397
398
|
| `/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 |
|
|
398
399
|
| `/api/account` | GET, PATCH | the account's defaults from its AGENTS.md frontmatter — `timezone`, `budget` (a USD cap — a number for a month, `"60/day"`, `"60/week"`, or `{ usd, period }`; null is no limit), `notify` (`{ url?, email?, events }`), `concurrency`, `compute` (`{ vcpu, memGiB, diskGiB }` — the account's own cap on what its running steps hold together, lower than the plan's; PATCH writes it as `compute: { vcpu, memory, disk }`, merged over what is set: a figure not sent is kept, `null` drops one, `compute: null` drops all), `deploy_block` (`none`, `secrets` or `security` — answered as `deployBlock`), `network_enforce` (answered as `networkEnforce`), `owner`, `alerts` (as written), `judge` (`{ model?, effort? }`), `telemetry` (`{ otlp, headers }` — header values are `${SECRET}` names; answered as `{ endpoint, headers }`); PATCH sets the keys sent, null clears one, and edits the file in place. To a caller scoped to some workspaces GET says these are set, never where they go: `notify` loses its `url` and carries `hidden: true` when one is set, and `telemetry` is `{ endpoint: "", headers: {}, hidden: true }`. PATCH needs every workspace |
|
|
399
|
-
| `/api/customers` | GET, PATCH | your own users' limits and block list ([end customers](runs#end-customers)): GET `{ limits: { startsPerMinute, gatewayRpm, gatewayConcurrency }, defaults, blocked: [{ customer, by, reason, at }] }` — anyone in the account; PATCH changes the limits (whole numbers 1–100,000, `null` puts one back to the default) — an admin over every workspace (`403` otherwise), audited as `customer.limits` |
|
|
400
|
+
| `/api/customers` | GET, PATCH | your own users' limits and block list ([end customers](runs#end-customers)): GET `{ limits: { startsPerMinute, maxOpenRuns, gatewayRpm, gatewayConcurrency, dailyModelUsd }, defaults, blocked: [{ customer, by, reason, at }] }` — anyone in the account; PATCH changes the limits (whole numbers 1–100,000; `dailyModelUsd` dollars a day, kept to the cent; `null` puts one back to the default) — an admin over every workspace (`403` otherwise), audited as `customer.limits` |
|
|
401
|
+
| `/api/customers/usage?days=` | GET | what each end customer's calls on foldrun's models were charged over the last `days` UTC days (1–90, default 7): `{ days, customers: [{ customer, chargedUsd, todayUsd, calls }] }`, newest-spending first, at most 500, open estimates included — anyone in the account |
|
|
400
402
|
| `/api/customers/<customer>/block` | PUT, DELETE | block one end customer (`{ reason? }`) — its runs are refused at start and stop at their next model call — or unblock it (`404` when it was not blocked). An admin over every workspace; audited as `customer.blocked` / `customer.unblocked` |
|
|
401
403
|
| `/api/account/agents-md` | GET, PUT | the account's own `AGENTS.md`, whole — the shared context and defaults every agent in every workspace reads, above its workspace's AGENTS.md. GET answers `{ content, sha256, exists }`. PUT `{ content, ifMatch?, message? }` writes it whole and answers `{ ok, sha256, issues }` (`unchanged: true` when it already said that). Checked as a deploy checks AGENTS.md: a problem a deploy would refuse is `422` with the `issues` and nothing written; warnings come back with the write. `ifMatch` — the `sha256` a GET answered, or `null` for "there was no file" — makes it a `409` if the file changed since. At most 256 KB. Account-wide callers only, both ways (a member or key scoped to some workspaces is `403`: the file can name notify and telemetry targets for every workspace); PUT needs `workspace:manage` (an admin). `foldrun deploy` at an account root sends it and `foldrun pull` fetches it; Settings → Policies → AGENTS.md edits it. Audited as `account.agents_md_set`. Idempotent |
|
|
402
404
|
| `/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 365 days (`audit.retention_days`; an install without a database keeps its file-backed log), and no longer than the account |
|
package/docs/cli.md
CHANGED
|
@@ -92,7 +92,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
92
92
|
| `foldrun logs [run-id]` | recent runs in one workspace, or one run's whole event trail. `--follow` tails a live run: on a platform it reads the run's server-sent events (`GET …/runs/<id>/stream`, what the dashboard's run page reads — `invoke --watch` and `agent run --wait` too), reconnecting up to three times if the stream goes quiet; a run on this machine is read from its file. `--local` reads this machine's store even when signed in; `foldrun runs --local` is the same command and prints the same thing |
|
|
93
93
|
| `foldrun runs` | what has run lately across the whole account: when, workspace, flow, status, steps done, how long, the credits it was charged (its token cost in dollars until the ledger settles it) and the run's own one-line summary — or, for a failed run, why it failed: `✗ agent: ` and the sentence every surface gives ([why it failed](runs#why-it-failed)). A completed run shows its verdict beside the status — `GOOD`, `BAD`, `QUIET`, or `BLOCKED` in red with a ⛔ mark. `--status failed`, `--verdict blocked`, search by what happened inside (`--tool web`, `--tool-error`, `--agent`, `--model haiku`, `--min-tokens 50k`, `--min-secs 120`, `--context <id>` (one [conversation](runs#conversations)'s runs), or `--view <name>` for a saved one — `foldrun runs views` lists yours), `--outcome blocked,failed` (the dashboard's word; `needs-you` is `waiting`), `--since 24h`, `--to <workspace>`, `--flow <name>` (that flow's runs, or a direct agent run's or an eval's name), `--q <words>` (the runs page's text search: every word, any order, across id, flow, workspace, status, verdict, summary and failure), `--limit <n>` (20 by default) is one page: when more match it prints the next page's cursor — `--before <cursor>` shows that page (a time or a run id works too), `--page <n>` the nth page of `--limit`, `--all` every run that matches; `--json` prints `{ runs, next }`. `--local` prints exactly what `logs --local` prints — this machine's runs, one workspace |
|
|
94
94
|
| `foldrun runs outputs <run-id>` | which files the run archived from its agents' `outputs/` — the run page's **Out** column: each agent's files with their sizes, and the `foldrun report <run-id> get <agent>/<path>` that downloads one. `--to <workspace>` names the run's workspace (else it is found); `--json` prints `{ runId, files: [{ agent, path, bytes, href }], totalBytes }`. `GET /api/workspaces/<ws>/runs/<id>/files` |
|
|
95
|
-
| `foldrun customers` | your own users, by the id on their runs ([end customers](runs#end-customers)): the limits each is held to and who is blocked; `block <id> [--reason "…"]`, `unblock <id>` (asks; `--yes`), `limits --starts-per-minute N` (also `--gateway-rpm`, `--gateway-concurrency`; `default` puts one back); `--json`. `GET`/`PATCH /api/customers`, `PUT`/`DELETE /api/customers/<id>/block` |
|
|
95
|
+
| `foldrun customers` | your own users, by the id on their runs ([end customers](runs#end-customers)): the limits each is held to and who is blocked; `block <id> [--reason "…"]`, `unblock <id>` (asks; `--yes`), `usage [--days 7]` (model spend per customer), `limits --starts-per-minute N` (also `--max-open-runs`, `--gateway-rpm`, `--gateway-concurrency`, `--daily-model-usd`; `default` — or `none` for the spend — puts one back); `--json`. `GET`/`PATCH /api/customers`, `GET /api/customers/usage`, `PUT`/`DELETE /api/customers/<id>/block` |
|
|
96
96
|
| `foldrun runs views save <name>` · `foldrun runs views rm <name>` | the runs page's **save view**: `save` keeps the filters given (`--status`, `--flow`, `--to`, `--since`, `--q`, `--tool`, `--tool-error`, `--agent`, `--model`, `--min-tokens`, `--min-secs`, `--context`, `--customer`; `--since 24h` is kept as the dashboard's `today`) under that name, replacing a view of the same name; `rm` deletes one (asks; `--yes`). `PATCH /api/me/preferences` `{ runViews }` — the whole list, at most 20. `--json` prints the list after |
|
|
97
97
|
| `foldrun runs doctor <run-id>` | the run doctor: the assistant reads a failed run and the files it names, says why (platform, check, work or outside), and proposes the fix as diffs, saved on yes — the run page's **Doctor** (`--to`, `--yes`, `--dry-run`, `--json`). Charged like one assistant reply |
|
|
98
98
|
| `foldrun runs rm <run-id>` | erase a run from history: its record and its archived outputs. A run still in flight is stopped first. The ledger line stays — money is not deleted because a trace was. Needs an admin (`workspace:manage`). Asks first; `--yes` with no terminal. Several ids (`runs rm <id> <id>…`) are the runs list's **Delete** on a selection, through the same route (`POST …/runs/bulk` `{ action: "delete" }`, one call per workspace): it lists them, asks once, then deletes them — each run its own outcome, so one refused does not stop the rest, and it exits 1 |
|
|
@@ -209,6 +209,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
209
209
|
| `foldrun use <name>` | act as one of them from here on. `foldrun switch <name>` is the same command |
|
|
210
210
|
| `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>` |
|
|
211
211
|
| `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 |
|
|
212
|
+
| `foldrun keys set <id> --customer required\|optional` | whether every run the key starts must name an end customer ([end customers](runs#end-customers)); make one that requires it from the start with `foldrun keys create <label> --require-customer`. `PATCH /api/keys/<id>` |
|
|
212
213
|
| `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 |
|
|
213
214
|
| `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 |
|
|
214
215
|
| `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 |
|
package/docs/runs.md
CHANGED
|
@@ -646,10 +646,20 @@ re-run is for the same customer.
|
|
|
646
646
|
What follows from it:
|
|
647
647
|
|
|
648
648
|
- **Held alone.** Each customer is held to its own limits, checked before the
|
|
649
|
-
account's own: by default **30 run starts a minute
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
649
|
+
account's own: by default **30 run starts a minute** and **10 runs open at
|
|
650
|
+
once** (queued, running or waiting at a gate, across every workspace). One
|
|
651
|
+
customer past a limit is refused while your other customers carry on: too
|
|
652
|
+
many starts is `429` with `Retry-After` and code `customer_rate`; too many
|
|
653
|
+
open is `429` with code `customer_open_runs` — one must finish first. Open
|
|
654
|
+
runs are counted from the runs themselves, so two starts at once cannot both
|
|
655
|
+
take the last place. Runs that name no customer are held to the account's
|
|
656
|
+
limits alone, as before.
|
|
657
|
+
- **A daily spend of its own.** Set **model spend a day** and each customer's
|
|
658
|
+
calls on foldrun's models may be charged at most that much in a UTC day,
|
|
659
|
+
held with the account's daily limit — each call at the most it could cost —
|
|
660
|
+
so calls at once cannot pass it together. A run past it is refused at its
|
|
661
|
+
next model call. None is set by default. `GET /api/customers/usage?days=7`
|
|
662
|
+
and `foldrun customers usage` show what each customer was charged.
|
|
653
663
|
- **Blocked.** An admin with every workspace can block a customer
|
|
654
664
|
(Settings → API keys → Customers, `foldrun customers block <id>`, or
|
|
655
665
|
`PUT /api/customers/<id>/block`). Its runs are refused at start (`403`,
|
|
@@ -664,10 +674,16 @@ What follows from it:
|
|
|
664
674
|
to it; `foldrun runs --customer c-8812` and `GET …/runs?customer=c-8812` list
|
|
665
675
|
them.
|
|
666
676
|
|
|
667
|
-
The limits are the account's to change
|
|
668
|
-
`foldrun customers limits --
|
|
677
|
+
The limits are the account's to change, in Settings → API keys → Customers,
|
|
678
|
+
with `PATCH /api/customers`, or `foldrun customers limits --max-open-runs 20
|
|
679
|
+
--daily-model-usd 5` (`default`, or `none` for the spend, puts one back).
|
|
669
680
|
A customer is a grouping and a limit, not an access boundary: anyone who may
|
|
670
|
-
start runs in the account may name any customer.
|
|
681
|
+
start runs in the account may name any customer. To make sure nothing slips
|
|
682
|
+
past the limits by leaving the id out, mark the key your product uses
|
|
683
|
+
**Require a customer id** (Settings → API keys, `foldrun keys create <label>
|
|
684
|
+
--require-customer`, or `foldrun keys set <id> --customer required`): every
|
|
685
|
+
run it starts must then name one, and one that does not is refused (`400`,
|
|
686
|
+
code `customer_required`).
|
|
671
687
|
|
|
672
688
|
## What a run costs, and what stops it
|
|
673
689
|
|
package/package.json
CHANGED
package/src/commands.mjs
CHANGED
|
@@ -4742,7 +4742,8 @@ async function keysCmd(positional, flags) {
|
|
|
4742
4742
|
// A key `foldrun login` minted lasts 90 days and renews itself while
|
|
4743
4743
|
// that machine is in use; revoking it signs that machine out.
|
|
4744
4744
|
const login = k.origin === "cli-login" && !k.revokedAt ? " [CLI sign-in · renews itself]" : "";
|
|
4745
|
-
|
|
4745
|
+
const custReq = k.requireCustomer && !k.revokedAt ? ` ${c.yellow("[customer required]")}` : "";
|
|
4746
|
+
console.log(` ${state.padEnd(20)} ${k.id} ${k.prefix}… ${c.bold(k.label)} ${c.dim(what)}${k.createdBy ? c.dim(` by ${k.createdBy}`) : ""}${login}${custReq}`);
|
|
4746
4747
|
// A rotated key in its grace: still live, but not to be rotated again.
|
|
4747
4748
|
const next = k.replacedBy ? keys.find((n) => n.id === k.replacedBy) : null;
|
|
4748
4749
|
if (k.replacedBy) console.log(` ${" ".repeat(9)}${c.yellow(`rotated → ${k.replacedBy}${next ? ` (${next.prefix}…)` : ""}`)}${c.dim(" — rotate that one, not this")}`);
|
|
@@ -4755,6 +4756,9 @@ async function keysCmd(positional, flags) {
|
|
|
4755
4756
|
if (!arg) throw new Error("what is the key for? foldrun keys create <label>");
|
|
4756
4757
|
if (flags.a2a === true && flags.gateway === true) throw new Error("--a2a or --gateway, not both");
|
|
4757
4758
|
if (flags["claude-code"] === true && flags.gateway !== true) throw new Error("--claude-code goes with --gateway: only a gateway key runs Claude Code");
|
|
4759
|
+
// An A2A key's caller is one outside agent: requiring a customer is for
|
|
4760
|
+
// API and gateway keys (Codex review: never silently dropped).
|
|
4761
|
+
if (flags.a2a === true && flags["require-customer"] === true) throw new Error("--require-customer is for API and gateway keys, not --a2a");
|
|
4758
4762
|
if (flags.a2a === true) return keysCreateA2a(url, arg, flags);
|
|
4759
4763
|
if (flags.gateway === true) return keysCreateGateway(url, arg, flags);
|
|
4760
4764
|
const body = { label: arg };
|
|
@@ -4768,6 +4772,8 @@ async function keysCmd(positional, flags) {
|
|
|
4768
4772
|
// --workspaces a,b narrows the key to those; --workspaces all opens
|
|
4769
4773
|
// every one you can. Unsaid, the key inherits your own scope.
|
|
4770
4774
|
if (typeof flags.workspaces === "string") body.workspaces = flags.workspaces === "all" ? null : flags.workspaces.split(",").map((w) => w.trim()).filter(Boolean);
|
|
4775
|
+
// --require-customer (FOL-168): every run the key starts must name one.
|
|
4776
|
+
if (flags["require-customer"] === true) body.requireCustomer = true;
|
|
4771
4777
|
const made = await remoteCall(url, flags, "/api/keys", { method: "POST", body: JSON.stringify(body) });
|
|
4772
4778
|
console.log(`\n ${c.green("✓")} ${c.bold(arg)} ${c.dim(made.id)}${made.expiresAt ? c.dim(` expires ${made.expiresAt.slice(0, 10)}`) : ""}\n`);
|
|
4773
4779
|
if (made.key == null) return lostSecret(made.id);
|
|
@@ -4807,6 +4813,16 @@ async function keysCmd(positional, flags) {
|
|
|
4807
4813
|
console.log(` ${c.dim(`Shown once. The old key ${grace === "0" ? "is revoked" : `keeps working until ${String(ends).slice(0, 16).replace("T", " ")} UTC`}.`)}\n`);
|
|
4808
4814
|
return 0;
|
|
4809
4815
|
}
|
|
4816
|
+
if (verb === "set" && flags.customer !== undefined) {
|
|
4817
|
+
// `keys set <id> --customer required|optional` (FOL-168): whether its
|
|
4818
|
+
// runs and gateway calls must name an end customer.
|
|
4819
|
+
if (!arg) throw new Error("which key? foldrun keys set <id> --customer required|optional");
|
|
4820
|
+
if (["opus", "sonnet", "haiku"].some((t) => flags[t] !== undefined) || flags.clear === true) throw new Error("set the customer requirement and the model map in two commands: keys set <id> --customer …, then keys set <id> --sonnet …");
|
|
4821
|
+
if (flags.customer !== "required" && flags.customer !== "optional") throw new Error("--customer is required or optional");
|
|
4822
|
+
const r = await remoteCall(url, flags, `/api/keys/${encodeURIComponent(arg)}`, { method: "PATCH", body: JSON.stringify({ requireCustomer: flags.customer === "required" }) });
|
|
4823
|
+
console.log(`\n ${c.green("✓")} ${arg}: a customer is ${r.requireCustomer ? "required on every run and gateway call" : "no longer required"}\n`);
|
|
4824
|
+
return 0;
|
|
4825
|
+
}
|
|
4810
4826
|
if (verb === "set") return keysSetModels(url, arg, flags);
|
|
4811
4827
|
throw new Error(`keys: unknown verb "${verb}" — ls, create, set, rotate, revoke`);
|
|
4812
4828
|
}
|
|
@@ -4921,6 +4937,8 @@ async function keysCreateGateway(url, label, flags) {
|
|
|
4921
4937
|
const claude = flags["claude-code"] === true ? preflightClaudeSettings() : null;
|
|
4922
4938
|
const body = { label, purpose: "gateway" };
|
|
4923
4939
|
if (flags.login === true) body.credential = "login";
|
|
4940
|
+
// --require-customer (FOL-168): every call must send x-foldrun-customer.
|
|
4941
|
+
if (flags["require-customer"] === true) body.requireCustomer = true;
|
|
4924
4942
|
if (capUsd !== undefined) body.capUsd = capUsd;
|
|
4925
4943
|
if (dailyUsd !== undefined) body.dailyUsd = dailyUsd;
|
|
4926
4944
|
if (flags.forever === true && flags.expires !== undefined) throw new Error("--forever or --expires <span>, not both");
|
|
@@ -14391,6 +14409,12 @@ async function preferencesCmd(positional, flags) {
|
|
|
14391
14409
|
* [--reason "…"]`, `unblock <id>` (asks; --yes), `limits --starts-per-minute
|
|
14392
14410
|
* N --gateway-rpm N --gateway-concurrency N` (`default` puts one back).
|
|
14393
14411
|
*/
|
|
14412
|
+
/** The limits in force, in one line; a changed one marks its default. */
|
|
14413
|
+
function customerLimitsLine(L, D) {
|
|
14414
|
+
const mark = (k) => (D && L[k] !== D[k] ? c.dim(` (default ${D[k] ?? "none"})`) : "");
|
|
14415
|
+
return `${L.startsPerMinute} run starts a minute${mark("startsPerMinute")} · ${L.maxOpenRuns ?? "?"} open at once${mark("maxOpenRuns")} · ${L.gatewayRpm} gateway calls a minute${mark("gatewayRpm")} · ${L.gatewayConcurrency} at once${mark("gatewayConcurrency")} · model spend ${L.dailyModelUsd == null ? "no daily limit" : `$${L.dailyModelUsd} a day`}${mark("dailyModelUsd")}`;
|
|
14416
|
+
}
|
|
14417
|
+
|
|
14394
14418
|
async function customersCmd(positional, flags) {
|
|
14395
14419
|
const url = platformFor(flags, "customers");
|
|
14396
14420
|
const [verb, id] = positional;
|
|
@@ -14409,27 +14433,50 @@ async function customersCmd(positional, flags) {
|
|
|
14409
14433
|
}
|
|
14410
14434
|
if (verb === "limits") {
|
|
14411
14435
|
const patch = {};
|
|
14412
|
-
for (const [flag, key] of [["starts-per-minute", "startsPerMinute"], ["gateway-rpm", "gatewayRpm"], ["gateway-concurrency", "gatewayConcurrency"]]) {
|
|
14436
|
+
for (const [flag, key] of [["starts-per-minute", "startsPerMinute"], ["max-open-runs", "maxOpenRuns"], ["gateway-rpm", "gatewayRpm"], ["gateway-concurrency", "gatewayConcurrency"]]) {
|
|
14413
14437
|
if (flags[flag] === undefined) continue;
|
|
14414
14438
|
if (flags[flag] === "default") patch[key] = null;
|
|
14415
14439
|
else if (/^\d+$/.test(String(flags[flag]))) patch[key] = Number(flags[flag]);
|
|
14416
14440
|
else throw new Error(`--${flag} is a whole number, or default`);
|
|
14417
14441
|
}
|
|
14418
|
-
|
|
14442
|
+
// Dollars a day on foldrun's models; `none` (or default) takes the limit away.
|
|
14443
|
+
if (flags["daily-model-usd"] !== undefined) {
|
|
14444
|
+
const v = String(flags["daily-model-usd"]);
|
|
14445
|
+
if (v === "none" || v === "default") patch.dailyModelUsd = null;
|
|
14446
|
+
else if (/^\d+(\.\d{1,2})?$/.test(v) && Number(v) > 0) patch.dailyModelUsd = Number(v);
|
|
14447
|
+
else throw new Error("--daily-model-usd is dollars a day (e.g. 5 or 2.50), or none");
|
|
14448
|
+
}
|
|
14449
|
+
if (!Object.keys(patch).length) throw new Error("`foldrun customers limits --starts-per-minute N --max-open-runs N --gateway-rpm N --gateway-concurrency N --daily-model-usd D` (default / none puts one back)");
|
|
14419
14450
|
const r = await remoteCall(url, flags, "/api/customers", { method: "PATCH", body: JSON.stringify(patch) });
|
|
14420
14451
|
if (flags.json === true) console.log(JSON.stringify(r, null, 2));
|
|
14421
|
-
else console.log(`\n ${c.green("✓")} per customer: ${r.limits
|
|
14452
|
+
else console.log(`\n ${c.green("✓")} per customer: ${customerLimitsLine(r.limits)}\n`);
|
|
14453
|
+
return 0;
|
|
14454
|
+
}
|
|
14455
|
+
if (verb === "usage") {
|
|
14456
|
+
const days = flags.days === undefined ? 7 : Number(flags.days);
|
|
14457
|
+
if (!Number.isInteger(days) || days < 1 || days > 90) throw new Error("--days is 1 to 90");
|
|
14458
|
+
const r = await remoteCall(url, flags, `/api/customers/usage?days=${days}`);
|
|
14459
|
+
if (flags.json === true) {
|
|
14460
|
+
console.log(JSON.stringify(r, null, 2));
|
|
14461
|
+
return 0;
|
|
14462
|
+
}
|
|
14463
|
+
if (!r.customers.length) {
|
|
14464
|
+
console.log(`\n ${c.dim(`no model calls named a customer in the last ${r.days} day${r.days === 1 ? "" : "s"}`)}\n`);
|
|
14465
|
+
return 0;
|
|
14466
|
+
}
|
|
14467
|
+
const usd = (n) => `$${n < 1 ? n.toFixed(3) : n.toFixed(2)}`;
|
|
14468
|
+
console.log(`\n ${c.bold(`charged on foldrun's models · last ${r.days} day${r.days === 1 ? "" : "s"}`)}`);
|
|
14469
|
+
for (const x of r.customers.slice(0, Number(flags.limit) > 0 ? Number(flags.limit) : 20)) console.log(` ${usd(x.chargedUsd).padStart(9)} ${c.dim(`today ${usd(x.todayUsd)} · ${x.calls} calls`)} ${x.customer}`);
|
|
14470
|
+
console.log();
|
|
14422
14471
|
return 0;
|
|
14423
14472
|
}
|
|
14424
|
-
if (verb !== undefined && verb !== "ls") throw new Error("`foldrun customers` — ls, block <id>, unblock <id>, limits");
|
|
14473
|
+
if (verb !== undefined && verb !== "ls") throw new Error("`foldrun customers` — ls, usage, block <id>, unblock <id>, limits");
|
|
14425
14474
|
const r = await remoteCall(url, flags, "/api/customers");
|
|
14426
14475
|
if (flags.json === true) {
|
|
14427
14476
|
console.log(JSON.stringify(r, null, 2));
|
|
14428
14477
|
return 0;
|
|
14429
14478
|
}
|
|
14430
|
-
|
|
14431
|
-
const mark = (k) => (L[k] === D[k] ? "" : c.dim(` (default ${D[k]})`));
|
|
14432
|
-
console.log(`\n ${c.bold("per customer")} ${L.startsPerMinute} run starts a minute${mark("startsPerMinute")} · ${L.gatewayRpm} gateway calls a minute${mark("gatewayRpm")} · ${L.gatewayConcurrency} at once${mark("gatewayConcurrency")}`);
|
|
14479
|
+
console.log(`\n ${c.bold("per customer")} ${customerLimitsLine(r.limits, r.defaults)}`);
|
|
14433
14480
|
console.log(` ${c.dim("only for runs and gateway calls that name a customer")}`);
|
|
14434
14481
|
if (!r.blocked.length) console.log(`\n ${c.dim("no customer is blocked")}`);
|
|
14435
14482
|
else {
|