foldrun 20.10.0 → 21.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/bin/foldrun.mjs CHANGED
@@ -116,7 +116,7 @@ const HELP = `foldrun — agents are just folders
116
116
  foldrun check --security only the security rules: hard-coded secrets, hidden text, agents that can leak, unpinned code — fails on a warning
117
117
  foldrun check --rules every rule check knows: id, level, what it guards against (--json)
118
118
  foldrun check --to <ws> --online also the network checks, run by the platform: known vulnerabilities for exact runtime pins (OSV) and remote MCP servers' tool text — and what could not be checked
119
- foldrun agent run <name> run one agent once on the platform (--task "…", --to, --wait, --test, --context <id>)
119
+ foldrun agent run <name> run one agent once on the platform (--task "…", --to, --wait, --test, --context <id>, --file <path> repeatable)
120
120
  foldrun agent run <name> --no-task run it with no instruction, on its own prompt alone — the dashboard's Run (--to, --wait, --test)
121
121
  foldrun agent link <agent> add to its team, in its frontmatter: --subagent <worker> (--isolated: sandbox: own on the worker), --consult <agent> or --can-ask (--description for a worker with none)
122
122
  foldrun agent unlink <agent> take one away: --subagent <name>, --consult <name> or --can-ask
@@ -307,7 +307,8 @@ Signing in
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
309
  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
- 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
310
+ 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
+ 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>)
311
312
  foldrun a2a ls --to <ws> what a workspace serves over A2A: each flow's a2a:, card and endpoint URLs, its A2A keys (admins), recent tasks and the key that asked (--json)
312
313
  foldrun a2a publish <flow> set a2a: publish: true in the flow (--to <ws>: the deployed copy, an admin's) — --name, --description, --example "…" (repeatable), --public-card | --private-card; diff, checked, --dry-run
313
314
  foldrun a2a publish <flow> --clear-name | --clear-description | --clear-examples drop the card's name, description or examples (also on unpublish)
@@ -331,6 +332,7 @@ Options
331
332
  --no-task agent run: start it with no instruction — the agent works from its own prompt alone
332
333
  --task "<text>" flow inputs save: the task the saved set holds (--file <path> reads it from a file)
333
334
  --test run, invoke: a test run — nothing outward, state/ untouched, receipts on the run page
335
+ --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)
334
336
  --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
335
337
  --follow logs: keep tailing a live run (with --url: on the platform)
336
338
  --status <s> runs, stop, rerun: only these statuses, comma-separated (failed, completed, awaiting-approval…)
@@ -509,6 +511,8 @@ if (!command || command === "--help" || command === "-h") {
509
511
  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"]);
510
512
  // Flags said more than once collect into a list: `--tag a --tag b`.
511
513
  const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove", "rule", "authorize-param", "example", "accept-risk"]);
514
+ /** Flags that become a list only when given more than once (FOL-163 `--file`). */
515
+ const LIST_WHEN_REPEATED = new Set(["file"]);
512
516
  // `--wait` is a switch everywhere but `flow add <flow> wait`, where it takes
513
517
  // a span: `--wait 30m`, `--wait event`. Only a value that reads as one is
514
518
  // taken, so `invoke x --wait` and friends are as they were.
@@ -527,6 +531,9 @@ for (let i = 0; i < rest.length; i++) {
527
531
  else if (BOOLEAN_FLAGS.has(name) || next === undefined || next.startsWith("--")) value = true;
528
532
  else value = rest[++i];
529
533
  if (REPEATABLE.has(name) && typeof value === "string") flags[name] = [...(Array.isArray(flags[name]) ? flags[name] : []), value];
534
+ // Given twice, a list; once, a string as ever — so `--file` stays one path
535
+ // for the commands that read one, and invoke / agent run take several.
536
+ else if (LIST_WHEN_REPEATED.has(name) && typeof value === "string" && flags[name] !== undefined && flags[name] !== true) flags[name] = [...(Array.isArray(flags[name]) ? flags[name] : [flags[name]]), value];
530
537
  else flags[name] = value;
531
538
  }
532
539
 
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. `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. `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; `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; `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` |
package/docs/cli.md CHANGED
@@ -233,6 +233,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
233
233
  | `--task "<text>"` | the instruction for a manual run |
234
234
  | `--no-task` | `agent run`: start it with no instruction — the agent works from its own prompt alone |
235
235
  | `--task "<text>"` | `flow inputs save`: the task the saved set holds |
236
+ | `--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)) |
236
237
  | `--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 |
237
238
  | `--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) |
238
239
  | `--follow` | `logs`: keep tailing a live run — locally, or on the platform with `--url` |
package/docs/mcp.md CHANGED
@@ -137,8 +137,8 @@ and that automatic disconnect are in the audit log (`mcp.connected`,
137
137
  | `get_run` | one run in full | `GET …/runs/<id>` |
138
138
  | `read_file` | one file of a workspace's source (with its `sha256`), or the tree | `GET …/source` |
139
139
  | `check_workspace` | what `foldrun check` says about a workspace: findings with rule ids (`security: true` for the security rules alone) | `GET …/check` |
140
- | `run_flow` | start a flow (`task`, `test: true` for a [test run](runs#test-runs), `context` for a turn of a [conversation](runs#conversations)) | `POST …/flows/<flow>/run` |
141
- | `run_agent` | run one agent on a task of your own, in its own sandbox, no flow needed (`task`, `test: true` for a [test run](runs#test-runs), `context` for a turn of a [conversation](runs#conversations)); answers a run id at once — read it with `get_run` | `POST …/agents/<agent>/run` |
140
+ | `run_flow` | start a flow (`task`, `test: true` for a [test run](runs#test-runs), `context` for a turn of a [conversation](runs#conversations), `inputs` for [files](runs#inputs)) | `POST …/flows/<flow>/run` |
141
+ | `run_agent` | run one agent on a task of your own, in its own sandbox, no flow needed (`task`, `test: true` for a [test run](runs#test-runs), `context` for a turn of a [conversation](runs#conversations), `inputs` for [files](runs#inputs)); answers a run id at once — read it with `get_run` | `POST …/agents/<agent>/run` |
142
142
  | `decide_approval` | approve or reject a gate (`note`, `step`) | `POST …/runs/<id>/approve` |
143
143
  | `answer_question` | answer an agent's question mid-step | `POST …/runs/<id>/answer` |
144
144
  | `message_run` | say something to a running agent | `POST …/runs/<id>/message` |
package/docs/providers.md CHANGED
@@ -195,6 +195,26 @@ those families on both wires and says so in the drop line. Every other id
195
195
  keeps it, because a gateway ignores a field it cannot use and an o-series,
196
196
  gpt-5, grok or deepseek-r model wants it.
197
197
 
198
+ ### Images and PDFs an agent reads
199
+
200
+ An agent that reads an image or a PDF with its Read tool — a run's
201
+ [inputs](runs#inputs), a screenshot it took — gets it back as an image or a
202
+ document block. On an Anthropic endpoint the model sees it as it is. Through
203
+ the translator:
204
+
205
+ | | Chat Completions (`format: openai`) | Responses (`format: responses`) |
206
+ |---|---|---|
207
+ | an image a tool returned | sent in a user message right after the tool results, labelled with the call it came from (a tool message carries text alone) | carried in the tool output |
208
+ | a PDF a tool returned | not sent — no portable Chat part takes one | carried as an `input_file` |
209
+ | an image or PDF in the message itself | images sent; PDFs not | both sent |
210
+
211
+ Wherever a file is not sent, the model is told so in its place — "a PDF was
212
+ here, but this model endpoint cannot be shown PDFs" — so it never answers as
213
+ though it had seen it, and the run trace says what was left out. To give a
214
+ model on Chat Completions a PDF's text, read it with a script. Whether a given
215
+ model can see images at all is the provider's; one that cannot refuses or
216
+ ignores the image.
217
+
198
218
  ### Persian prompts, by tier (checked 11 Nov 2026)
199
219
 
200
220
  An eval of eight Persian tasks, compared on the three tiers with **Compare
package/docs/runs.md CHANGED
@@ -582,6 +582,44 @@ The run page shows a run's **Conversation**, linked to the runs list filtered
582
582
  to it; `foldrun runs --context order-42` and `GET …/runs?context=order-42`
583
583
  list them.
584
584
 
585
+ ## Inputs
586
+
587
+ A run may be handed **files**: storage paths, as the workspace's storage lists
588
+ them. The step the task reaches finds them at `inputs/` in its working
589
+ directory, under the same paths (`inputs/reports/q4.pdf`), and is told which
590
+ they are. An agent reads them with its Read tool; images and PDFs are shown to
591
+ the model as they are, where the model can be shown them (see
592
+ [images and PDFs](providers#images-and-pdfs-an-agent-reads)). Scripts can read
593
+ every file.
594
+
595
+ ```sh
596
+ foldrun storage put brief.pdf --to sales --into briefs/
597
+ foldrun agent run analyst --to sales --task "summarise the brief" --file briefs/brief.pdf
598
+ foldrun agent run analyst --to sales --task "what changed?" --file ./local/v2.pdf
599
+ ```
600
+
601
+ A `--file` written as a local path (`./`, `../`, `/` or `~`) is uploaded to
602
+ `storage/inputs/<upload id>/` first; anything else is a storage path. The API
603
+ takes `inputs: ["briefs/brief.pdf"]` on `POST …/agents/<agent>/run` and
604
+ `POST …/flows/<flow>/run` (not with `from`), and so do MCP's `run_agent` and
605
+ `run_flow`. In the dashboard, **Run with…** on a flow has a **Files** list.
606
+
607
+ - **Fixed when the run is made.** The run holds the bytes each path named
608
+ then. Overwriting or deleting the storage file afterwards changes nothing
609
+ it reads, and a re-run reads the same files. The run page's **Inputs**
610
+ panel links to the copy the run held. Holding costs no extra space: the
611
+ same bytes are stored once.
612
+ - **Never copied back.** Whatever the step writes inside `inputs/` stays in
613
+ its sandbox. Put results in `outputs/` or `workspace/storage/`.
614
+ - **Limits:** at most 20 files and 100 MiB on one run — foldrun's limits.
615
+ What a model can be shown at once is the provider's: an image or a PDF
616
+ past its limits is still staged for scripts to read.
617
+ - **Where:** the sandboxed executors stage inputs (k8s and `container`). An
618
+ install that runs steps in-process answers `409`, as it does for a
619
+ snapshot.
620
+ - **Released with the run.** Deleting a run, or the retention window
621
+ pruning it, lets its held copies go.
622
+
585
623
  ## What a run costs, and what stops it
586
624
 
587
625
  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": "20.10.0",
3
+ "version": "21.0.0",
4
4
  "description": "Agents are just folders. Write them, check them, run them — on your machine.",
5
5
  "license": "FSL-1.1-ALv2",
6
6
  "type": "module",
@@ -11,7 +11,7 @@
11
11
  "node": ">=22"
12
12
  },
13
13
  "dependencies": {
14
- "@foldrun/core": "^18.5.0"
14
+ "@foldrun/core": "^19.0.0"
15
15
  },
16
16
  "files": [
17
17
  "bin",
package/src/commands.mjs CHANGED
@@ -3977,6 +3977,7 @@ async function invoke(target, flags) {
3977
3977
  const task = typeof flags.inputs === "string" ? await savedInputs(url, flags, ws, target, flags.inputs) : typeof flags.task === "string" ? flags.task : "";
3978
3978
  if (flags.inputs !== undefined && typeof flags.inputs !== "string") throw new Error("which input set? `--inputs <name>`");
3979
3979
  if (flags.context !== undefined && typeof flags.context !== "string") throw new Error("which conversation? `--context <id>`");
3980
+ const files = await runInputs(url, flags, ws);
3980
3981
  let body;
3981
3982
  try {
3982
3983
  body = await remoteCall(url, flags, `/api/workspaces/${ws}/flows/${target}/run${wait}`, {
@@ -3998,6 +3999,8 @@ async function invoke(target, flags) {
3998
3999
  // --context <id> (FOL-162): a turn of that conversation — the first
3999
4000
  // step reads the earlier runs started with the same context.
4000
4001
  ...(typeof flags.context === "string" ? { context: flags.context } : {}),
4002
+ // --file (FOL-163): storage paths handed to the first step, in inputs/.
4003
+ ...(files.length ? { inputs: files } : {}),
4001
4004
  }),
4002
4005
  });
4003
4006
  } catch (err) {
@@ -4701,7 +4704,7 @@ async function doctor(flags) {
4701
4704
  * keys create <label> --a2a --to <ws> --flows a,b [--max-tasks N] a key for an outside agent: /a2a only
4702
4705
  * keys create <label> --gateway --cap <usd> [--daily <usd>] a coding agent's key (Claude Code): the gateway only
4703
4706
  * keys create <label> --gateway --login on the operator's Claude login (its own accounts): not metered
4704
- * keys create <label> --gateway --cap <usd> --claude-code …and write it into Claude Code's settings
4707
+ * keys create <label> --gateway --cap <usd> --claude-code …and write it into Claude Code's settings (its status line too)
4705
4708
  * keys set <id> --opus|--sonnet|--haiku <provider/model> which model each Claude Code tier runs on (a gateway key; `-` clears one, --clear all)
4706
4709
  * keys rotate <id> [--grace 1h] a new key, same label/role/scope; the old
4707
4710
  * one ends now, or when the grace runs out.
@@ -4930,7 +4933,7 @@ async function keysCreateGateway(url, label, flags) {
4930
4933
  // Written from the file as it is NOW, not as it was before the request,
4931
4934
  // so a change made meanwhile is kept. A write that fails after the key
4932
4935
  // exists says so and falls back to the lines to copy.
4933
- /** @type {{ file: string, dropped: string[], backup: string | null } | null} */
4936
+ /** @type {{ file: string, dropped: string[], backup: string | null, statusLine: "added" | "kept" | "theirs" } | null} */
4934
4937
  let done = null;
4935
4938
  if (claude && made.gatewayUrl) {
4936
4939
  try { done = writeClaudeSettings(readClaudeSettings(), made.gatewayUrl, made.key); }
@@ -4941,12 +4944,18 @@ async function keysCreateGateway(url, label, flags) {
4941
4944
  console.log(` ${c.dim(`env: ANTHROPIC_BASE_URL=${made.gatewayUrl}, ANTHROPIC_AUTH_TOKEN=<this key>`)}`);
4942
4945
  if (done.dropped.length) console.log(` ${c.dim(`removed from that env block: ${done.dropped.join(", ")} (it would have competed with the key)`)}`);
4943
4946
  if (done.backup) console.log(` ${c.dim(`the file as it was: ${done.backup}`)}`);
4947
+ if (done.statusLine === "theirs") console.log(` ${c.dim(`your own statusLine was kept; for the key's spend there, run \`${STATUS_LINE_COMMAND}\` from it`)}`);
4948
+ else console.log(` ${c.dim(`statusLine: ${STATUS_LINE_COMMAND} — the key's spend under Claude Code's input box`)}`);
4944
4949
  console.log(` ${c.dim("Start a new claude session; /status shows the gateway. Claude Desktop is set in its own Developer → Configure Third-Party Inference.")}\n`);
4945
4950
  } else {
4946
4951
  if (claude && !made.gatewayUrl) console.log(` ${c.yellow("This platform has no gateway URL yet, so Claude Code's settings were not written.")}\n`);
4947
4952
  console.log(` ${c.dim("Shown once. Point Claude Code at it:")}\n`);
4953
+ // ANTHROPIC_AUTH_TOKEN, not ANTHROPIC_API_KEY: Claude Code asks about a
4954
+ // "custom API key" with No preselected, and No leaves the gateway unused.
4948
4955
  console.log(` export ANTHROPIC_BASE_URL=${base}`);
4949
- console.log(` export ANTHROPIC_API_KEY=<key>\n`);
4956
+ console.log(` export ANTHROPIC_AUTH_TOKEN=<key>\n`);
4957
+ console.log(` ${c.dim(`The key's spend under Claude Code's input box: add to ~/.claude/settings.json`)}`);
4958
+ console.log(` "statusLine": { "type": "command", "command": "${STATUS_LINE_COMMAND}" }\n`);
4950
4959
  }
4951
4960
  // A login key is not metered: there is no spend for `keys ls` to show.
4952
4961
  const after = made.credential === "login"
@@ -5011,6 +5020,11 @@ function writeClaudeSettings({ file, text, settings }, baseUrl, key) {
5011
5020
  env.ANTHROPIC_BASE_URL = baseUrl;
5012
5021
  env.ANTHROPIC_AUTH_TOKEN = key;
5013
5022
  const next = { ...settings, env };
5023
+ // The key's spend under Claude Code's input box — unless a status line of
5024
+ // the person's own is set, which is theirs and stays.
5025
+ /** @type {"added" | "kept" | "theirs"} */
5026
+ const statusLine = settings.statusLine === undefined ? "added" : settings.statusLine?.command === STATUS_LINE_COMMAND ? "kept" : "theirs";
5027
+ if (statusLine === "added") next.statusLine = { type: "command", command: STATUS_LINE_COMMAND };
5014
5028
  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
5015
5029
  /** @type {string | null} */
5016
5030
  let backup = null;
@@ -5023,7 +5037,66 @@ function writeClaudeSettings({ file, text, settings }, baseUrl, key) {
5023
5037
  fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
5024
5038
  fs.renameSync(tmp, file);
5025
5039
  try { fs.chmodSync(file, 0o600); } catch { /* Windows: no modes */ }
5026
- return { file, dropped, backup };
5040
+ return { file, dropped, backup, statusLine };
5041
+ }
5042
+
5043
+ /** Claude Code's status line, as `keys create --gateway --claude-code`
5044
+ * writes it: the key's spend, read from the gateway itself. */
5045
+ const STATUS_LINE_COMMAND = "foldrun gateway status-line";
5046
+
5047
+ /**
5048
+ * `foldrun gateway status-line` — one line for Claude Code's status line:
5049
+ * what the gateway key in this environment has spent against its limits,
5050
+ *
5051
+ * foldrun · $3.12 of $20.00 · today $1.10 of $5.00
5052
+ *
5053
+ * It reads ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN (or ANTHROPIC_API_KEY)
5054
+ * — the env Claude Code hands the status line — and asks the gateway's
5055
+ * GET /v1/usage, never the platform's API. Claude Code redraws the line
5056
+ * after every message, so an answer is kept 10 s on this machine. It always
5057
+ * prints one line and exits 0: a status line has no place for an error.
5058
+ */
5059
+ async function gatewayCmd(positional, flags) {
5060
+ const sub = positional[0];
5061
+ if (sub !== "status-line") throw new Error("foldrun gateway status-line — the one line Claude Code's status line shows: the gateway key's spend and limits");
5062
+ // Claude Code sends the session as JSON on stdin; it is not needed here.
5063
+ if (!process.stdin.isTTY) process.stdin.resume().on("error", () => {});
5064
+ console.log(await gatewayStatusLine(process.env, flags));
5065
+ if (!process.stdin.isTTY) process.stdin.destroy();
5066
+ return 0;
5067
+ }
5068
+
5069
+ /** The line itself; exported for tests. */
5070
+ export async function gatewayStatusLine(env = process.env, flags = {}, now = Date.now()) {
5071
+ const base = (env.ANTHROPIC_BASE_URL ?? "").trim().replace(/\/+$/, "");
5072
+ const key = (env.ANTHROPIC_AUTH_TOKEN || env.ANTHROPIC_API_KEY || "").trim();
5073
+ if (!base) return "foldrun · no gateway set (ANTHROPIC_BASE_URL)";
5074
+ if (!key) return "foldrun · no key set (ANTHROPIC_AUTH_TOKEN)";
5075
+ // Kept per gateway and key, under a name that shows neither.
5076
+ const cacheFile = path.join(os.tmpdir(), `foldrun-status-${crypto.createHash("sha256").update(`${base}\n${key}`).digest("hex").slice(0, 24)}`);
5077
+ const ttl = typeof flags.cache === "string" && /^\d+$/.test(flags.cache) ? Number(flags.cache) * 1000 : 10_000;
5078
+ try {
5079
+ const st = fs.statSync(cacheFile);
5080
+ if (now - st.mtimeMs < ttl) return fs.readFileSync(cacheFile, "utf8");
5081
+ } catch { /* none yet */ }
5082
+ let line;
5083
+ try {
5084
+ const res = await fetch(`${base}/v1/usage?format=line`, { headers: { authorization: `Bearer ${key}` }, signal: AbortSignal.timeout(3000) });
5085
+ const text = await res.text();
5086
+ // The gateway's own line; anything else (a proxy's page, Anthropic's own
5087
+ // API) is not shown as if it were.
5088
+ const first = text.split("\n")[0] ?? "";
5089
+ line = /^foldrun · /.test(first) ? first : res.status === 404 ? "foldrun · this base URL is not a foldrun gateway" : `foldrun · usage not available (${res.status})`;
5090
+ } catch {
5091
+ line = "foldrun · gateway not reachable";
5092
+ }
5093
+ // Only printable text reaches the terminal, and not much of it.
5094
+ line = line.replace(/[\u0000-\u001f\u007f-\u009f]/g, "").slice(0, 160);
5095
+ try {
5096
+ fs.writeFileSync(`${cacheFile}.${process.pid}`, line, { mode: 0o600 });
5097
+ fs.renameSync(`${cacheFile}.${process.pid}`, cacheFile);
5098
+ } catch { /* the next draw asks again */ }
5099
+ return line;
5027
5100
  }
5028
5101
 
5029
5102
  /** A retried mint or rotate is answered from the first call, and the server
@@ -6403,11 +6476,6 @@ async function storageCmd(positional, flags, layout) {
6403
6476
  jobs[0].rel = flags.as;
6404
6477
  }
6405
6478
  const token = await renewedToken(url, flags);
6406
- const base = `/api/workspaces/${encodeURIComponent(ws)}/storage`;
6407
- const said = async (res) => {
6408
- const text = await res.text();
6409
- try { return JSON.parse(text).error ?? text.slice(0, 200); } catch { return text.slice(0, 200); }
6410
- };
6411
6479
  let ok = 0, skipped = 0, bytesSent = 0;
6412
6480
  const failed = [];
6413
6481
  console.log();
@@ -6420,23 +6488,7 @@ async function storageCmd(positional, flags, layout) {
6420
6488
  continue;
6421
6489
  }
6422
6490
  try {
6423
- const sha = crypto.createHash("sha256").update(bytes).digest("hex");
6424
- // The length too: the platform checks the limits on it and signs it
6425
- // into the URL, so the bucket takes exactly these bytes (30 Oct 2026).
6426
- const ask = await remoteFetch(url, `${base}/upload-url`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ path: rel, sha, size: bytes.length }) }, { token });
6427
- // A platform older than presigned uploads answers 404 here: it
6428
- // takes the bytes itself, the way one with no bucket does.
6429
- if (!ask.ok && ask.status !== 404) throw new HttpError(await said(ask), ask.status, {});
6430
- const { url: direct } = /** @type {{ url?: string | null }} */ (ask.ok ? await ask.json() : { url: null });
6431
- if (direct) {
6432
- const put = await fetch(direct, { method: "PUT", body: bytes, signal: AbortSignal.timeout(Math.max(120, bytes.length / 200_000) * 1000) });
6433
- if (!put.ok) throw new Error(`the storage service refused it (${put.status})`);
6434
- const done = await remoteFetch(url, base, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ path: rel, sha, size: bytes.length }) }, { token });
6435
- if (!done.ok) throw new HttpError(await said(done), done.status, {});
6436
- } else {
6437
- const put = await remoteFetch(url, `${base}?path=${encodeURIComponent(rel)}`, { method: "PUT", body: bytes, headers: { "content-type": "application/octet-stream" } }, { token });
6438
- if (!put.ok) throw new HttpError(await said(put), put.status, {});
6439
- }
6491
+ await uploadToStorage(url, token, ws, rel, bytes);
6440
6492
  ok++;
6441
6493
  bytesSent += bytes.length;
6442
6494
  console.log(` ${c.green("✓")} ${ws}/storage/${rel} ${c.dim(humanBytes(bytes.length))}`);
@@ -8356,6 +8408,68 @@ async function stopCmd(runId, flags, layout) {
8356
8408
  * carries each run's one-line summary — the sentence that says what it
8357
8409
  * found, not merely that it finished.
8358
8410
  */
8411
+ /**
8412
+ * Put one file's bytes into a workspace's storage at `rel`: straight to the
8413
+ * bucket when the platform hands out an upload URL (then registered), else
8414
+ * through the platform — what `storage put` and `--input ./file` both do.
8415
+ */
8416
+ async function uploadToStorage(url, token, ws, rel, bytes) {
8417
+ const base = `/api/workspaces/${encodeURIComponent(ws)}/storage`;
8418
+ const said = async (res) => {
8419
+ const text = await res.text();
8420
+ try { return JSON.parse(text).error ?? text.slice(0, 200); } catch { return text.slice(0, 200); }
8421
+ };
8422
+ const sha = crypto.createHash("sha256").update(bytes).digest("hex");
8423
+ // The length too: the platform checks the limits on it and signs it
8424
+ // into the URL, so the bucket takes exactly these bytes (30 Oct 2026).
8425
+ const ask = await remoteFetch(url, `${base}/upload-url`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ path: rel, sha, size: bytes.length }) }, { token });
8426
+ // A platform older than presigned uploads answers 404 here: it
8427
+ // takes the bytes itself, the way one with no bucket does.
8428
+ if (!ask.ok && ask.status !== 404) throw new HttpError(await said(ask), ask.status, {});
8429
+ const { url: direct } = /** @type {{ url?: string | null }} */ (ask.ok ? await ask.json() : { url: null });
8430
+ if (direct) {
8431
+ const put = await fetch(direct, { method: "PUT", body: bytes, signal: AbortSignal.timeout(Math.max(120, bytes.length / 200_000) * 1000) });
8432
+ if (!put.ok) throw new Error(`the storage service refused it (${put.status})`);
8433
+ const done = await remoteFetch(url, base, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ path: rel, sha, size: bytes.length }) }, { token });
8434
+ if (!done.ok) throw new HttpError(await said(done), done.status, {});
8435
+ } else {
8436
+ const put = await remoteFetch(url, `${base}?path=${encodeURIComponent(rel)}`, { method: "PUT", body: bytes, headers: { "content-type": "application/octet-stream" } }, { token });
8437
+ if (!put.ok) throw new HttpError(await said(put), put.status, {});
8438
+ }
8439
+ }
8440
+
8441
+ /**
8442
+ * `--file` (FOL-163, repeatable): the files a run is handed — the API's
8443
+ * `inputs` (`--inputs <set>` is invoke's saved input set, a different thing). A path that
8444
+ * starts with ./, ../, / or ~ is a file on this machine — uploaded first to
8445
+ * storage/inputs/<upload id>/<name>; anything else is a storage path as
8446
+ * `foldrun storage ls` prints it. Decided by how it is written, never by
8447
+ * whether a local file happens to exist. Returns the storage paths.
8448
+ */
8449
+ async function runInputs(url, flags, ws) {
8450
+ if (flags.file !== undefined && typeof flags.file !== "string" && !Array.isArray(flags.file)) throw new Error("which file? `--file <storage path>` or `--file ./local-file`");
8451
+ const given = many(flags.file);
8452
+ if (!given.length) return [];
8453
+ const local = (p) => /^(\.{1,2}\/|\/|~)/.test(p);
8454
+ const out = [];
8455
+ let token = null;
8456
+ const id = `${new Date().toISOString().slice(0, 10)}-${crypto.randomBytes(4).toString("hex")}`;
8457
+ for (const p of given) {
8458
+ if (!local(p)) {
8459
+ out.push(p.replace(/^storage\//, ""));
8460
+ continue;
8461
+ }
8462
+ const abs = path.resolve(p.startsWith("~") ? path.join(os.homedir(), p.slice(1)) : p);
8463
+ if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) throw new Error(`--file ${p}: no such file here`);
8464
+ token ??= await renewedToken(url, flags);
8465
+ const rel = `inputs/${id}/${path.basename(abs)}`;
8466
+ await uploadToStorage(url, token, ws, rel, fs.readFileSync(abs));
8467
+ console.log(` ${c.green("↑")} ${p} ${c.dim(`→ storage/${rel}`)}`);
8468
+ out.push(rel);
8469
+ }
8470
+ return out;
8471
+ }
8472
+
8359
8473
  async function runsCmd(flags, layout) {
8360
8474
  const url = platformFor(flags, "runs");
8361
8475
  // --view <name>: a saved search (the dashboard's) read first, so every
@@ -9101,6 +9215,7 @@ async function agentRunCmd(positional, flags, layout) {
9101
9215
  const wait = flags.wait === true ? `?wait=true&timeout=${WAIT_PIECE_S}` : "";
9102
9216
  const base = `/api/workspaces/${encodeURIComponent(ws)}/agents/${encodeURIComponent(name)}`;
9103
9217
  if (flags.context !== undefined && typeof flags.context !== "string") throw new Error("which conversation? `--context <id>`");
9218
+ const files = await runInputs(url, flags, ws);
9104
9219
 
9105
9220
  // A waited run that FAILS is the answer to the question, not a fault in
9106
9221
  // the call: 200 with its status since FOL-106, 500 with the same record
@@ -9122,7 +9237,7 @@ async function agentRunCmd(positional, flags, layout) {
9122
9237
  // at the proxy, send-capable secrets withheld, state/ kept.
9123
9238
  // --context <id> (FOL-162): a turn of that conversation — the agent
9124
9239
  // reads the earlier runs started with the same context first.
9125
- body: JSON.stringify({ ...(task ? { task } : {}), ...(flags.test === true ? { test: true } : {}), ...(typeof flags.context === "string" ? { context: flags.context } : {}) }),
9240
+ body: JSON.stringify({ ...(task ? { task } : {}), ...(flags.test === true ? { test: true } : {}), ...(typeof flags.context === "string" ? { context: flags.context } : {}), ...(files.length ? { inputs: files } : {}) }),
9126
9241
  }),
9127
9242
  );
9128
9243
  const runId = body?.runId;
@@ -15128,6 +15243,8 @@ export async function run(command, positional, flags, workspace, layout) {
15128
15243
  return apiCmd(positional, flags);
15129
15244
  case "keys":
15130
15245
  return keysCmd(positional, flags);
15246
+ case "gateway":
15247
+ return gatewayCmd(positional, flags);
15131
15248
  case "a2a":
15132
15249
  return a2aCmd(positional, flags, layout);
15133
15250
  case "audit":