foldrun 21.0.0 → 21.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/bin/foldrun.mjs CHANGED
@@ -317,6 +317,7 @@ Signing in
317
317
  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)
318
318
  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
319
319
  foldrun a2a status <task-id> --card <url> the task as it stands now (--json) — cancel <task-id> --card <url> stops it (asks; --yes)
320
+ 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
320
321
  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)
321
322
  foldrun --version this CLI's version, offline (\`foldrun version\` also asks the platform)
322
323
  foldrun --help everything; \`foldrun <command> --help\`, \`-h\` or \`foldrun help <command>\` for one (never runs it)
@@ -333,6 +334,8 @@ Options
333
334
  --task "<text>" flow inputs save: the task the saved set holds (--file <path> reads it from a file)
334
335
  --test run, invoke: a test run — nothing outward, state/ untouched, receipts on the run page
335
336
  --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)
337
+ --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
338
+ --reason "<text>" customers block: why, kept on the block and the audit log
336
339
  --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
337
340
  --follow logs: keep tailing a live run (with --url: on the platform)
338
341
  --status <s> runs, stop, rerun: only these statuses, comma-separated (failed, completed, awaiting-approval…)
package/docs/api.md CHANGED
@@ -159,7 +159,7 @@ installer's `error`, its cause on the first line. `foldrun deploy` polls it afte
159
159
  | `/api/workspaces/<ws>/a2a` | GET | what this workspace serves to outside agents over A2A 1.0: `{ flows: [{ flow, published, publicCard, name, description, hasInputSchema, acceptRisk, card, url }], risks: [{ flow, agent, secrets, accepted }], keys, tasks: [{ id, flow, state, runId, contextId, key: { id, label, prefix, revoked }, createdAt, updatedAt }] }` — every flow whose frontmatter says `a2a:`; `risks`, every flow's agents (published or not) that hold a secret and can run code, with whether its `a2a: accept_risk` names them — a published flow with one not accepted takes no new task ([accept_risk](a2a.md#secret-and-code-accept_risk)); the URL of its agent card and of its JSON-RPC endpoint (`/a2a/<account>/<ws>/flows/<flow>`), the workspace's live A2A keys (`[{ id, label, prefix, flows, maxTasks, expiresAt }]`, or `null` unless you may manage keys), and the 50 newest A2A tasks (`state` a `TASK_STATE_*`) with the key that asked. Publishing is the flow's `a2a:` field, written like any other — changing it needs `workspace:manage`. `404` when the workspace does not exist |
160
160
  | `/api/workspaces/<ws>/flows/<flow>` | PATCH | edit a step (`step`, `instruction`, `options`, `target`, `subflow`), rearrange (`groups`), set `trigger`, set `compute` (`{ vcpu, memGiB, diskGiB }` or `null` — what one run may hold at once, merged over what the flow says), set `a2a` (`{ publish, name, description, examples, public_card, input, accept_risk }` merged over the flow's `a2a:` — a key sent replaces it, `null` removes it; `a2a: null` removes the block; refused `400` when the result would not read, `403` without the admin role, `400` `code: a2a_secret_code` when an agent of the published flow holds a secret and can run code and `accept_risk` does not name it — see [A2A](a2a.md)), a canvas edit (`edit`, or `edits` — at most 200 in one request, `400` past that; adding a step is `edit: { op: "insert", target, subflow?, instruction?, at: { rail } }`, removing one `edit: { op: "remove", step }`), undo (`restore` + `expect`). The older POST (a step at the end) and DELETE (`{ step }`) were removed on 5 Nov 2026 (deprecated and sunset the same day) — every client (the canvas, the list view's board, the CLI) sends PATCH `{ edit }`, one mechanism per change; `DELETE …/flows/draft` answers `410`. Every PATCH and DELETE takes `expect` — the text the step numbers were read from, or its sha256 — and is refused with `409` and the current `text`, nothing written, when the file no longer reads it (the canvas, the list view's board and step options, and the CLI's `flow add`/`rm-step`/`dup-step --to` send it; the dashboard shows the 409 as "this flow changed since you opened it — reload") |
161
161
  | `/api/workspaces/<ws>/flows/draft` | POST, PATCH, DELETE | POST draft a flow with a model: `{ description, flow? }` (`flow` redrafts that one). Returns `{ ok, files: [{ path, content, before, sha256 }], issues: [{ where, message, level }], repaired, notes }` — checked with the deploy's checks and the flow lint, repaired once. **Writes nothing**; save with the source PUT. Needs `workspace:write`; a description over 4,000 characters is `413`; a Chat-Completions `provider:` is `422`. On the platform's models the balance is checked first (`402`) and the call is charged as one ledger line, flow `ai-draft`. PATCH and DELETE, and a POST without `description`, are the edits of a flow that happens to be named `draft`, exactly as at `flows/<flow>` |
162
- | `/api/workspaces/<ws>/flows/<flow>/run` | POST | start it. `inputs` (storage paths) hands files to the first step at `inputs/` ([inputs](runs#inputs)); not with `from`. `context` (1–200 printable ASCII characters) makes the run a turn of that [conversation](runs#conversations): its first step reads the earlier runs of the same context before the task; not with `from` (`400`); the answer carries `context`. An `Idempotency-Key` header, or `idempotencyKey` in the body, makes a retried call safe: a dropped response, a proxy timeout or a CI step that ran twice is answered `started: false` with the `runId` it already started, rather than starting a second run and billing for it. Keys are remembered for 24 hours, per flow. While the account has its most runs waiting for their turn it answers 409 `{ error, code: "waiting_cap", limit, waiting }` and starts nothing ([how many runs may wait](budgets-and-billing#how-many-runs-may-wait)); so do the agent run and rerun routes (an A2A caller is told the agent is busy), and a webhook or inbound email gets the same as a 503 with `Retry-After: 60` |
162
+ | `/api/workspaces/<ws>/flows/<flow>/run` | POST | start it. `customer` names which of your own users it is for ([end customers](runs#end-customers)). `inputs` (storage paths) hands files to the first step at `inputs/` ([inputs](runs#inputs)); not with `from`. `context` (1–200 printable ASCII characters) makes the run a turn of that [conversation](runs#conversations): its first step reads the earlier runs of the same context before the task; not with `from` (`400`); the answer carries `context`. An `Idempotency-Key` header, or `idempotencyKey` in the body, makes a retried call safe: a dropped response, a proxy timeout or a CI step that ran twice is answered `started: false` with the `runId` it already started, rather than starting a second run and billing for it. Keys are remembered for 24 hours, per flow. While the account has its most runs waiting for their turn it answers 409 `{ error, code: "waiting_cap", limit, waiting }` and starts nothing ([how many runs may wait](budgets-and-billing#how-many-runs-may-wait)); so do the agent run and rerun routes (an A2A caller is told the agent is busy), and a webhook or inbound email gets the same as a 503 with `Retry-After: 60` |
163
163
  | `/api/workspaces/<ws>/flows/<flow>/filter` | POST | test the flow's `filter:` against a delivery without starting anything: `{ payload }` — a webhook's JSON body (or the body as a string, read as JSON), an email's `{ from, to, subject, text }`, a chained run's `{ run, flow, status, ending, verdict, summary }`, a storage event's `{ by, paths }`. Answers `{ flow, trigger, filter, applies, match, reason }` — `reason` names the first condition that failed; a flow with no filter matches everything. Reads the deployed flow; nothing is recorded or charged |
164
164
 
165
165
  `POST .../run` takes `task` (the input), `from` (start at step N — a rerun of
@@ -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; `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`); `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` |
@@ -224,7 +224,7 @@ paying for the steps around it.
224
224
 
225
225
  | Route | Methods | |
226
226
  |---|---|---|
227
- | `/api/workspaces/<ws>/runs?limit=&before=` | GET | `{ runs: [{ id, flow, status, verdict, outcome, startedAt, finishedAt, ... }], next }`, newest first; `next` is the cursor for the page after (`<startedAt>~<runId>`, null on the last page) — pass it back as `before`, which also takes a time (runs that started before it) or a run id of the workspace (runs older than it); a position, not an offset, so runs starting meanwhile shift nothing and one cursor pages every workspace (`foldrun runs --before`, `--page`, `--all`); a `before` that is none of these is a `400`; search (see [Runs](runs#searching-runs)) with `tool` (a step called a tool whose name contains it), `tool_error=1`, `agent`, `model` (contains), `min_tokens` (`50k`), `min_secs`, `context` (one [conversation](runs#conversations)'s runs, its id exactly; each run in it carries `context: { id, key, a2a? }`) — `limit` counts the matches — `verdict` is the word the summary leads with (`GOOD`, `QUIET`, `BLOCKED`, `BAD` or null) and `outcome` the one word every page shows (`running`, `queued`, `waiting`, `good`, `done`, `quiet`, `blocked`, `bad`, `failed`, `stopped`); `failure` is why a run failed (null otherwise) — `{ agent, reason, class, kind, message, fix }` and, for a limit, `used`, `allowed`, `unit` and `scope`, for a refused site `host` (see [Runs](runs#why-it-failed)), `chargedUsd` is what the account was charged for the run (one credit is one cent), null until the ledger settles it, while `costUsd` is the provider's token cost — off the run index (see [Runs](runs#the-runs-list)); a finished run's steps carry `agent`, `status`, `costUsd` and `tokens` (`{ input, output, cacheRead, cacheWrite }`, see [Runs](runs#the-record)), and the run its summed `tokens` — not their reply or trace |
227
+ | `/api/workspaces/<ws>/runs?limit=&before=` | GET | `{ runs: [{ id, flow, status, verdict, outcome, startedAt, finishedAt, ... }], next }`, newest first; `next` is the cursor for the page after (`<startedAt>~<runId>`, null on the last page) — pass it back as `before`, which also takes a time (runs that started before it) or a run id of the workspace (runs older than it); a position, not an offset, so runs starting meanwhile shift nothing and one cursor pages every workspace (`foldrun runs --before`, `--page`, `--all`); a `before` that is none of these is a `400`; search (see [Runs](runs#searching-runs)) with `tool` (a step called a tool whose name contains it), `tool_error=1`, `agent`, `model` (contains), `min_tokens` (`50k`), `min_secs`, `customer` (one end customer's runs, exactly), `context` (one [conversation](runs#conversations)'s runs, its id exactly; each run in it carries `context: { id, key, a2a? }`) — `limit` counts the matches — `verdict` is the word the summary leads with (`GOOD`, `QUIET`, `BLOCKED`, `BAD` or null) and `outcome` the one word every page shows (`running`, `queued`, `waiting`, `good`, `done`, `quiet`, `blocked`, `bad`, `failed`, `stopped`); `failure` is why a run failed (null otherwise) — `{ agent, reason, class, kind, message, fix }` and, for a limit, `used`, `allowed`, `unit` and `scope`, for a refused site `host` (see [Runs](runs#why-it-failed)), `chargedUsd` is what the account was charged for the run (one credit is one cent), null until the ledger settles it, while `costUsd` is the provider's token cost — off the run index (see [Runs](runs#the-runs-list)); a finished run's steps carry `agent`, `status`, `costUsd` and `tokens` (`{ input, output, cacheRead, cacheWrite }`, see [Runs](runs#the-record)), and the run its summed `tokens` — not their reply or trace |
228
228
  | `/api/workspaces/<ws>/runs/<id>/calls/<call>` | GET | one tool call's recorded content (see [Runs](runs#what-a-run-records)): `{ call: { id, tool, input, output, inputChars, outputChars, truncated, inputCut, outputCut } }` — what it was given and what it gave back, secrets masked, each at most 65,536 characters; `inputChars`/`outputChars` are the whole length, `inputCut`/`outputCut` say which part was cut (`truncated`: either). `<call>` is the tool event's `call`; an event with `captured: true` has content here. 404 when nothing was recorded: the workspace says `capture: metadata`, or the run is from before 19 Oct 2026. A run's steps also carry `calls`, each model call (`n`, `at`, `ms`, `model`, `stop`, `tokens`, `tools`, and `subagent` / `attempt` when a sub-agent or a later attempt made it); a step that handed jobs to `sandbox: own` sub-agents carries `delegations` (`id`, `agent`, `status`, `costUsd`, `ms`), and each job is a step of its own with `subagentOf` (the delegating agent), `delegation` (that `id`) and `wrote` (the workspace paths it changed — copied into the delegating step's sandbox too, up to 4 MiB a job); and the run its `revision` (the workspace's latest revision when a worker picked it up — a deploy's commit, or the id an edit through `/source` was saved as) and `drivenAt` (when that was) |
229
229
  | `/api/workspaces/<ws>/runs/<id>/trace` | GET | the run as one tree (see [Runs](runs#the-trace-tree)): `{ tree, failure }`. Each span is `{ id, kind, label, start, end, status, children, … }`, where `kind` is `run`, `step`, `model` (one model call: `model`, `stop`, `tokens`), `tool` (`call`, `captured` when its input and output were recorded) or `error` (`text`); `start`/`end` are epoch milliseconds and `status` is `ok`, `error`, `running`, `waiting`, `skipped` or `pending`. A tool call sits under the model call that asked for it. `failure` is the ids from the root to the first thing that went wrong, which the run page opens on; `[]` when nothing did |
230
230
  | `/api/workspaces/<ws>/runs/<id>/compare?with=` | GET | this run beside another of the same flow (see [Runs](runs#compare-with-the-last-good-run)): `{ comparison: { base, run, revisionChanged, changedFiles, steps }, chosen }`. Each step is `{ step, agent, base, run, changes }`: both sides' status, instruction, model, seconds, tokens, model calls, tool counts, tool errors, first errors and first line said, and `changes` in words (`status: completed → failed`, `new error: …`, `instruction changed`, `tools: +web ×3`, `took 12s → 48s`, …). `changedFiles` lists the files changed between the revisions the two ran (null when one is unknown). `with` names the other run; unasked it is the newest earlier run of the flow that finished well, else the run this one re-ran (`chosen` says which) |
@@ -396,6 +396,8 @@ Reads return which secrets exist, never their values.
396
396
  | `/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
397
  | `/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
398
  | `/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/<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` |
399
401
  | `/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 |
400
402
  | `/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 |
401
403
  | `/api/avatars/<kind>/<id>` | GET, PUT, DELETE | a picture for a `user` (their own id), a `workspace` (its name) or the `account` (the tenant). PUT the bytes of a PNG, JPEG or WebP under 1 MB; a person sets their own, an admin a workspace's or the account's. GET needs a signed-in tenant — a workspace's picture, a caller who may open that workspace (403 otherwise) — and is privately cached for a year — the URL's `?v=` changes with the picture |
package/docs/cli.md CHANGED
@@ -92,7 +92,8 @@ 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 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`; `--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 |
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` |
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 |
96
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 |
97
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 |
98
99
  | `foldrun runs rm --until <30d\|date>` | delete every **finished** run that started before then — its record, captured calls and archived outputs — in every workspace, or one with `--to` ([how long a run is kept](runs#how-long-a-run-is-kept)). Counts what would go, asks once (`--yes` with no terminal; `--dry-run` only counts), then deletes 100 at a time until none match (`POST …/runs/bulk { action: "delete", until }`). Runs still going are left alone; the ledger lines stay. Needs an admin (`workspace:manage`) |
@@ -234,6 +235,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
234
235
  | `--no-task` | `agent run`: start it with no instruction — the agent works from its own prompt alone |
235
236
  | `--task "<text>"` | `flow inputs save`: the task the saved set holds |
236
237
  | `--file <path>` | `invoke`, `agent run`: a file handed to the run — repeatable; a storage path, or a local one (`./`, `../`, `/`, `~`) uploaded to `storage/inputs/<upload id>/` first. The first step finds them in `inputs/` ([inputs](runs#inputs)) |
238
+ | `--customer <id>` | `invoke`, `agent run`: which of your own users the run is for ([end customers](runs#end-customers)); `runs`: only that customer's runs |
237
239
  | `--context <id>` | `invoke`, `agent run`: a turn of that [conversation](runs#conversations) — the first step reads the earlier runs started with the same context (any id you choose, 1–200 printable characters, no spaces); `runs`: only that conversation's runs |
238
240
  | `--test` | `run`, `invoke`, `agent run`: a test run — every step runs, nothing outward happens, `state/` and `storage/` are left alone, and the run page lists what would have happened. See [Test runs](runs#test-runs) |
239
241
  | `--follow` | `logs`: keep tailing a live run — locally, or on the platform with `--url` |
package/docs/providers.md CHANGED
@@ -215,6 +215,11 @@ model on Chat Completions a PDF's text, read it with a script. Whether a given
215
215
  model can see images at all is the provider's; one that cannot refuses or
216
216
  ignores the image.
217
217
 
218
+ Audio and video are never model input: no endpoint above is sent a sound or
219
+ a video, whatever its provider supports. A voice note stays a file in the
220
+ sandbox; to use it, transcribe it with a script (`runtime:` packages, or an
221
+ API the agent declares in `apis:`) and give the model the text.
222
+
218
223
  ### Persian prompts, by tier (checked 11 Nov 2026)
219
224
 
220
225
  An eval of eight Persian tasks, compared on the three tiers with **Compare
package/docs/runs.md CHANGED
@@ -283,7 +283,7 @@ read by all its steps, `50k`), **≥ secs** and **conversation** (a
283
283
  `foldrun runs --tool web --tool-error`, `--agent`, `--model`, `--min-tokens`,
284
284
  `--min-secs`, `--context` and `--view <name>` do the same (`foldrun runs views` lists
285
285
  yours), and `GET …/runs` takes `tool`, `tool_error`, `agent`, `model`,
286
- `min_tokens`, `min_secs`, `context`. Tools and models are searchable on runs from
286
+ `min_tokens`, `min_secs`, `context`, `customer`. Tools and models are searchable on runs from
287
287
  19 Oct 2026; tokens and time on every run.
288
288
 
289
289
  ## Insights
@@ -592,6 +592,13 @@ the model as they are, where the model can be shown them (see
592
592
  [images and PDFs](providers#images-and-pdfs-an-agent-reads)). Scripts can read
593
593
  every file.
594
594
 
595
+ Which model is shown an image or a PDF is the one the step runs on — Claude
596
+ only when the step's provider is Anthropic (your key, or foldrun's models
597
+ set to Anthropic); OpenAI, Gemini or another provider otherwise. Audio and
598
+ video (a voice note, an `.mp3`, an `.mp4`) are never sent to a model: they
599
+ stay files in the sandbox, for a script or tool to work on. A script that
600
+ transcribes one with an outside API sends it to that API, and nowhere else.
601
+
595
602
  ```sh
596
603
  foldrun storage put brief.pdf --to sales --into briefs/
597
604
  foldrun agent run analyst --to sales --task "summarise the brief" --file briefs/brief.pdf
@@ -620,6 +627,48 @@ takes `inputs: ["briefs/brief.pdf"]` on `POST …/agents/<agent>/run` and
620
627
  - **Released with the run.** Deleting a run, or the retention window
621
628
  pruning it, lets its held copies go.
622
629
 
630
+ ## End customers
631
+
632
+ When your account serves people of your own — a product built on foldrun,
633
+ with many users behind one account — say which of them a run is for:
634
+ **`customer`**, an id you choose (1–128 of letters, digits and `. _ : @ -`).
635
+ It is opaque: you map it to a person, foldrun never does, and it must not be
636
+ personal data (an email, a name).
637
+
638
+ ```sh
639
+ foldrun agent run support --to helpdesk --task "summarise the ticket" --customer c-8812
640
+ ```
641
+
642
+ The API takes `customer` on `POST …/agents/<agent>/run` and
643
+ `POST …/flows/<flow>/run`, and so do MCP's `run_agent` and `run_flow`. A
644
+ re-run is for the same customer.
645
+
646
+ What follows from it:
647
+
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**. One customer past its
650
+ limit is refused (`429`, with `Retry-After` and code `customer_rate`) while
651
+ your other customers carry on. Runs that name no customer are held to the
652
+ account's limits alone, as before.
653
+ - **Blocked.** An admin with every workspace can block a customer
654
+ (Settings → API keys → Customers, `foldrun customers block <id>`, or
655
+ `PUT /api/customers/<id>/block`). Its runs are refused at start (`403`,
656
+ code `customer_blocked`), and a run of it already going stops at its next
657
+ model call. Unblocking lets it through again.
658
+ - **Told to the model provider.** On foldrun's models, the provider is sent
659
+ the customer as its end-user id — hashed with your account, so your id never
660
+ leaves foldrun and two accounts' `user-1` are never one identity there. A
661
+ provider that acts on abuse acts on that customer, not on everyone. Runs on
662
+ your own model keys are not changed.
663
+ - **Found.** The run page shows **Customer**, linked to the runs list filtered
664
+ to it; `foldrun runs --customer c-8812` and `GET …/runs?customer=c-8812` list
665
+ them.
666
+
667
+ The limits are the account's to change: `PATCH /api/customers` or
668
+ `foldrun customers limits --starts-per-minute 60` (`default` puts one back).
669
+ 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.
671
+
623
672
  ## What a run costs, and what stops it
624
673
 
625
674
  Every step records what it cost. A flow's `budget:` is checked between
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "foldrun",
3
- "version": "21.0.0",
3
+ "version": "21.1.1",
4
4
  "description": "Agents are just folders. Write them, check them, run them — on your machine.",
5
5
  "license": "FSL-1.1-ALv2",
6
6
  "type": "module",
package/src/commands.mjs CHANGED
@@ -4001,6 +4001,8 @@ async function invoke(target, flags) {
4001
4001
  ...(typeof flags.context === "string" ? { context: flags.context } : {}),
4002
4002
  // --file (FOL-163): storage paths handed to the first step, in inputs/.
4003
4003
  ...(files.length ? { inputs: files } : {}),
4004
+ // --customer (FOL-168): which of your own users this run is for.
4005
+ ...(typeof flags.customer === "string" ? { customer: flags.customer } : {}),
4004
4006
  }),
4005
4007
  });
4006
4008
  } catch (err) {
@@ -7770,7 +7772,7 @@ async function runViewsCmd(flags) {
7770
7772
 
7771
7773
  /** The filter flags a saved view keeps, as the runs page's query names them
7772
7774
  * (run-views-model.ts VIEW_KEYS) — the reverse of what --view reads. */
7773
- const VIEW_FLAGS = [["status", "status"], ["flow", "flow"], ["to", "workspace"], ["since", "since"], ["q", "q"], ["tool", "tool"], ["agent", "agent"], ["model", "model"], ["min-tokens", "min_tokens"], ["min-secs", "min_secs"], ["context", "context"]];
7775
+ const VIEW_FLAGS = [["status", "status"], ["flow", "flow"], ["to", "workspace"], ["since", "since"], ["q", "q"], ["tool", "tool"], ["agent", "agent"], ["model", "model"], ["min-tokens", "min_tokens"], ["min-secs", "min_secs"], ["context", "context"], ["customer", "customer"]];
7774
7776
 
7775
7777
  /**
7776
7778
  * `foldrun runs views save <name> [filters]` and `runs views rm <name>` — the
@@ -8522,11 +8524,11 @@ async function runsCmd(flags, layout) {
8522
8524
  // Search (FOL-72 step 9): by what happened inside a run, filtered by the
8523
8525
  // platform; --view <name> starts from a saved search (the dashboard's).
8524
8526
  const search = new URLSearchParams();
8525
- for (const [flag, key] of [["tool", "tool"], ["agent", "agent"], ["model", "model"], ["min-tokens", "min_tokens"], ["min-secs", "min_secs"], ["context", "context"]]) {
8527
+ for (const [flag, key] of [["tool", "tool"], ["agent", "agent"], ["model", "model"], ["min-tokens", "min_tokens"], ["min-secs", "min_secs"], ["context", "context"], ["customer", "customer"]]) {
8526
8528
  if (flags[flag] !== undefined && flags[flag] !== true) search.set(key, String(flags[flag]));
8527
8529
  }
8528
8530
  if (flags["tool-error"] === true) search.set("tool_error", "1");
8529
- const searching = [...search.keys()].some((k) => ["tool", "tool_error", "agent", "model", "min_tokens", "min_secs", "context"].includes(k));
8531
+ const searching = [...search.keys()].some((k) => ["tool", "tool_error", "agent", "model", "min_tokens", "min_secs", "context", "customer"].includes(k));
8530
8532
  // A view's flow or text filters here, after the fetch: ask for the ceiling
8531
8533
  // as for a status, or matches past the newest few go missing (Codex review).
8532
8534
  const localText = typeof flags.flow === "string" || typeof flags.q === "string";
@@ -8553,6 +8555,7 @@ async function runsCmd(flags, layout) {
8553
8555
  // --context (FOL-162): one conversation's runs. The platform filters too;
8554
8556
  // checked here as well, so a platform from before it lists none, not all.
8555
8557
  if (typeof flags.context === "string" && r.context?.id !== flags.context) return false;
8558
+ if (typeof flags.customer === "string" && r.customer !== flags.customer) return false;
8556
8559
  // A view's flow and free text (the runs page's): "agent: x" is a direct run.
8557
8560
  // The dashboard names a run by what ran (whatRan): a direct agent run's
8558
8561
  // or an eval's own name, without adhoc:/eval: (Codex review).
@@ -8576,7 +8579,7 @@ async function runsCmd(flags, layout) {
8576
8579
  for (let round = 0; ; round++) {
8577
8580
  const answers = await pool(names, 8, async (ws) => {
8578
8581
  try {
8579
- const forApi = new URLSearchParams([...search].filter(([k]) => ["tool", "tool_error", "agent", "model", "min_tokens", "min_secs", "context"].includes(k)));
8582
+ const forApi = new URLSearchParams([...search].filter(([k]) => ["tool", "tool_error", "agent", "model", "min_tokens", "min_secs", "context", "customer"].includes(k)));
8580
8583
  forApi.set("limit", String(perWorkspace));
8581
8584
  if (cursor) forApi.set("before", cursor);
8582
8585
  const answer = await remoteCall(url, flags, `/api/workspaces/${ws}/runs?${forApi}`);
@@ -9237,7 +9240,7 @@ async function agentRunCmd(positional, flags, layout) {
9237
9240
  // at the proxy, send-capable secrets withheld, state/ kept.
9238
9241
  // --context <id> (FOL-162): a turn of that conversation — the agent
9239
9242
  // reads the earlier runs started with the same context first.
9240
- body: JSON.stringify({ ...(task ? { task } : {}), ...(flags.test === true ? { test: true } : {}), ...(typeof flags.context === "string" ? { context: flags.context } : {}), ...(files.length ? { inputs: files } : {}) }),
9243
+ body: JSON.stringify({ ...(task ? { task } : {}), ...(flags.test === true ? { test: true } : {}), ...(typeof flags.context === "string" ? { context: flags.context } : {}), ...(files.length ? { inputs: files } : {}), ...(typeof flags.customer === "string" ? { customer: flags.customer } : {}) }),
9241
9244
  }),
9242
9245
  );
9243
9246
  const runId = body?.runId;
@@ -14152,6 +14155,62 @@ async function preferencesCmd(positional, flags) {
14152
14155
  return 0;
14153
14156
  }
14154
14157
 
14158
+ /**
14159
+ * `foldrun customers` (FOL-168) — your own users, by the id you put on runs
14160
+ * (`--customer`) and gateway calls (x-foldrun-customer): the limits each is
14161
+ * held to, and the block list. `ls` (or nothing) shows them; `block <id>
14162
+ * [--reason "…"]`, `unblock <id>` (asks; --yes), `limits --starts-per-minute
14163
+ * N --gateway-rpm N --gateway-concurrency N` (`default` puts one back).
14164
+ */
14165
+ async function customersCmd(positional, flags) {
14166
+ const url = platformFor(flags, "customers");
14167
+ const [verb, id] = positional;
14168
+ const enc = encodeURIComponent;
14169
+ if (verb === "block" || verb === "unblock") {
14170
+ if (!id) throw new Error(`\`foldrun customers ${verb} <customer-id>\` — the id you put on its runs`);
14171
+ if (verb === "block") {
14172
+ await remoteCall(url, flags, `/api/customers/${enc(id)}/block`, { method: "PUT", body: JSON.stringify(typeof flags.reason === "string" ? { reason: flags.reason } : {}) });
14173
+ console.log(`\n ${c.green("✓")} ${id} blocked ${c.dim("— its runs stop at their next model call, its gateway calls are refused")}\n`);
14174
+ return 0;
14175
+ }
14176
+ if (!(await sureToDelete(flags, "customers unblock", `the block on ${id}`))) return 1;
14177
+ await remoteCall(url, flags, `/api/customers/${enc(id)}/block`, { method: "DELETE" });
14178
+ console.log(`\n ${c.green("✓")} ${id} unblocked\n`);
14179
+ return 0;
14180
+ }
14181
+ if (verb === "limits") {
14182
+ const patch = {};
14183
+ for (const [flag, key] of [["starts-per-minute", "startsPerMinute"], ["gateway-rpm", "gatewayRpm"], ["gateway-concurrency", "gatewayConcurrency"]]) {
14184
+ if (flags[flag] === undefined) continue;
14185
+ if (flags[flag] === "default") patch[key] = null;
14186
+ else if (/^\d+$/.test(String(flags[flag]))) patch[key] = Number(flags[flag]);
14187
+ else throw new Error(`--${flag} is a whole number, or default`);
14188
+ }
14189
+ if (!Object.keys(patch).length) throw new Error("`foldrun customers limits --starts-per-minute N --gateway-rpm N --gateway-concurrency N` (default puts one back)");
14190
+ const r = await remoteCall(url, flags, "/api/customers", { method: "PATCH", body: JSON.stringify(patch) });
14191
+ if (flags.json === true) console.log(JSON.stringify(r, null, 2));
14192
+ else console.log(`\n ${c.green("✓")} per customer: ${r.limits.startsPerMinute} run starts a minute · ${r.limits.gatewayRpm} gateway calls a minute · ${r.limits.gatewayConcurrency} at once\n`);
14193
+ return 0;
14194
+ }
14195
+ if (verb !== undefined && verb !== "ls") throw new Error("`foldrun customers` — ls, block <id>, unblock <id>, limits");
14196
+ const r = await remoteCall(url, flags, "/api/customers");
14197
+ if (flags.json === true) {
14198
+ console.log(JSON.stringify(r, null, 2));
14199
+ return 0;
14200
+ }
14201
+ const L = r.limits, D = r.defaults;
14202
+ const mark = (k) => (L[k] === D[k] ? "" : c.dim(` (default ${D[k]})`));
14203
+ 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")}`);
14204
+ console.log(` ${c.dim("only for runs and gateway calls that name a customer")}`);
14205
+ if (!r.blocked.length) console.log(`\n ${c.dim("no customer is blocked")}`);
14206
+ else {
14207
+ console.log(`\n ${c.bold("blocked")}`);
14208
+ for (const b of r.blocked) console.log(` ${c.red("■")} ${b.customer}${b.reason ? ` ${b.reason}` : ""} ${c.dim(`${b.by} · ${when(b.at)}`)}`);
14209
+ }
14210
+ console.log(`\n ${c.dim("foldrun customers block <id> --reason \"…\" · unblock <id> · limits --gateway-rpm N")}\n`);
14211
+ return 0;
14212
+ }
14213
+
14155
14214
  /** `foldrun changelog [--limit n]` — What's new: the API's versions, what each
14156
14215
  * broke and what is deprecated, then each release and what it changed. */
14157
14216
  async function changelogCmd(flags) {
@@ -15249,6 +15308,8 @@ export async function run(command, positional, flags, workspace, layout) {
15249
15308
  return a2aCmd(positional, flags, layout);
15250
15309
  case "audit":
15251
15310
  return auditCmd(positional, flags);
15311
+ case "customers":
15312
+ return customersCmd(positional, flags);
15252
15313
  case "accounts":
15253
15314
  case "profiles":
15254
15315
  return accountsCmd(positional, flags);