foldrun 20.9.5 → 20.11.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)
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
@@ -163,10 +163,10 @@ const HELP = `foldrun — agents are just folders
163
163
  foldrun promote <run-id> keep a finished run as a regression case in evals/ (--eval <name>, --expect "contains: …" repeatable, --case <name>); a run that went wrong takes --should "what it should have done"
164
164
  foldrun probe <model> live check: can this model hold a tool loop here?
165
165
  foldrun logs [run-id] recent runs in one workspace, or one run's full event trail (--local: this machine's)
166
- foldrun runs what has run lately, across the account — --status, --verdict, --outcome (good, done, quiet, blocked, bad, failed, needs-you, …), --since, --to, --flow <name>, --q <words>, --limit; search with --tool, --tool-error, --agent, --model, --min-tokens 50k, --min-secs, or --view <name>; --limit is one page: --page <n>, --before <cursor> (printed when more match), --all, --json
166
+ foldrun runs what has run lately, across the account — --status, --verdict, --outcome (good, done, quiet, blocked, bad, failed, needs-you, …), --since, --to, --flow <name>, --q <words>, --limit; search with --tool, --tool-error, --agent, --model, --min-tokens 50k, --min-secs, --context <id>, or --view <name>; --limit is one page: --page <n>, --before <cursor> (printed when more match), --all, --json
167
167
  foldrun runs outputs <run-id> which files the run archived from its agents' outputs/, with their sizes (--to, --json); report <run-id> get downloads one
168
168
  foldrun runs views your saved run searches (--local prints exactly what logs --local prints)
169
- foldrun runs views save <name> [filters] save the runs filters given (--status, --flow, --to, --since, --q, --tool, --tool-error, --agent, --model, --min-tokens, --min-secs) as a view; a name taken is replaced
169
+ foldrun runs views save <name> [filters] save the runs filters given (--status, --flow, --to, --since, --q, --tool, --tool-error, --agent, --model, --min-tokens, --min-secs, --context) as a view; a name taken is replaced
170
170
  foldrun runs views rm <name> delete a saved view (asks; --yes)
171
171
  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 (--to, --yes, --dry-run, --json)
172
172
  foldrun runs rm <run-id> delete a run's record and archived outputs (an admin); a live one is stopped first — asks first, --yes means it
@@ -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,8 @@ 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)
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
334
337
  --follow logs: keep tailing a live run (with --url: on the platform)
335
338
  --status <s> runs, stop, rerun: only these statuses, comma-separated (failed, completed, awaiting-approval…)
336
339
  --since <span> runs, stop, rerun: only runs started within 24h, 7d, 90m, 2w, or today (the last 24h)
@@ -508,6 +511,8 @@ if (!command || command === "--help" || command === "-h") {
508
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"]);
509
512
  // Flags said more than once collect into a list: `--tag a --tag b`.
510
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"]);
511
516
  // `--wait` is a switch everywhere but `flow add <flow> wait`, where it takes
512
517
  // a span: `--wait 30m`, `--wait event`. Only a value that reads as one is
513
518
  // taken, so `invoke x --wait` and friends are as they were.
@@ -526,6 +531,9 @@ for (let i = 0; i < rest.length; i++) {
526
531
  else if (BOOLEAN_FLAGS.has(name) || next === undefined || next.startsWith("--")) value = true;
527
532
  else value = rest[++i];
528
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];
529
537
  else flags[name] = value;
530
538
  }
531
539
 
package/docs/a2a.md CHANGED
@@ -266,7 +266,11 @@ not taken: one request object per call.
266
266
 
267
267
  A task takes **one message**. A follow-up `SendMessage` with the task's
268
268
  `taskId` is refused (`-32004`); send a new message without `taskId`, with the
269
- `contextId` to keep the conversation together.
269
+ `contextId` to keep the conversation together. The flow's first step then
270
+ reads the earlier tasks of that `contextId` — what you sent and what you were
271
+ answered — before your message ([conversations](runs#conversations)). Your
272
+ contexts are your key's own: another caller's same `contextId` is a different
273
+ conversation, and you see only the answers you were given.
270
274
 
271
275
  ### Retries: `messageId`
272
276
 
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. 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; `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` |
@@ -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` — `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`, `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) |
@@ -572,7 +572,7 @@ with `HTTP <status>: <the route's error>`.
572
572
 
573
573
  | Route | Methods | |
574
574
  |---|---|---|
575
- | `/api/mcp` | POST | one JSON-RPC message: `initialize` (revisions `2025-11-25`, `2025-06-18`, `2025-03-26`; an unknown one is answered with the newest), `ping`, `tools/list`, `tools/call`; a notification is `202` with no body. `?readonly=1` offers only the tools that read and refuses the rest (`-32602`). The tools: `whoami`, `list_workspaces`, `inbox`, `list_approvals`, `list_flows`, `list_agents`, `list_runs`, `get_run`, `read_file`, `run_flow`, `run_agent`, `decide_approval`, `answer_question`, `message_run`, `stop_run` — see [MCP](mcp#the-tools). `foldrun mcp` serves the same over stdio |
575
+ | `/api/mcp` | POST | one JSON-RPC message: `initialize` (revisions `2025-11-25`, `2025-06-18`, `2025-03-26`; an unknown one is answered with the newest), `ping`, `tools/list`, `tools/call`; a notification is `202` with no body. `?readonly=1` offers only the tools that read and refuses the rest (`-32602`). The tools: `whoami`, `list_workspaces`, `inbox`, `list_approvals`, `list_flows`, `list_agents`, `list_runs`, `get_run`, `read_file`, `check_workspace`, `run_flow`, `run_agent`, `decide_approval`, `answer_question`, `message_run`, `stop_run`, `create_workspace`, `write_file`, `delete_file` — see [MCP](mcp#the-tools). `foldrun mcp` serves the same over stdio |
576
576
  | `/api/mcp/oauth/register` | POST | an AI app registers itself (RFC 7591), before anyone signs it in. Open, as the protocol needs — no key. `{ redirect_uris, client_name?, token_endpoint_auth_method?, grant_types?, response_types?, client_uri? }`: one to ten redirect URIs, each `https` or `http` to localhost, no fragment; `token_endpoint_auth_method` `none` (PKCE alone), `client_secret_post` or `client_secret_basic` (the default). Answers `201 { client_id, client_id_issued_at, client_name, redirect_uris, grant_types, response_types, token_endpoint_auth_method, client_secret?, client_secret_expires_at? }` — the secret only for the two secret methods, shown once. Errors are OAuth's `{ error, error_description }` (`invalid_redirect_uri`, `invalid_client_metadata`); `503` past 5,000 apps on the install An app may register `token_endpoint_auth_method: private_key_jwt` with `jwks` (`{ keys: [...] }`, public keys only) or an https `jwks_uri`; it gets no secret and signs a client assertion at the token and revocation endpoints (RFC 7523: `iss` = `sub` = its client id, `aud` the issuer or the endpoint, at most five minutes, each `jti` once).|
577
577
  | `/api/mcp/oauth/authorize` | GET, POST | the person's half of the sign-in, for the page at `/mcp/authorize` — a signed-in person only, never a key or a support view. GET `?request=<the app's query>` checks it and answers `{ client: { name, id, kind, uri }, redirectHost, loopback, scopes, account, person: { email, role }, workspaces, allWorkspaces }`; POST `{ request, decision: approve\|deny, access?: read\|write, workspaces?: [names] \| null }` answers `{ ok, redirect }` — the app's redirect URI with a one-time `code` (ten minutes), `state` and `iss`, or with `error=access_denied`. A request that names an unknown app or a redirect URI it did not register is `400` and never redirected; the rest of its faults (no PKCE `S256` challenge, a `resource` that is not this `/api/mcp`, an unknown scope) come back as `{ redirect }` with OAuth's error. `access: write` needs the app to have asked for `mcp:write`; `workspaces` must be ones the person may open (`403` otherwise) |
578
578
  | `/api/mcp/oauth/token` | POST | OAuth 2.1's token endpoint, form-encoded (JSON is read too), no key: `grant_type=authorization_code` with `code`, `redirect_uri`, `code_verifier` (PKCE S256) and `client_id` — or the app's secret, Basic or in the form —, or `grant_type=refresh_token` with `refresh_token`. `resource`, when sent, must be this `/api/mcp`. Answers `{ access_token, token_type: "Bearer", expires_in: 3600, refresh_token, scope }` with `Cache-Control: no-store`. A code is good once, right or wrong. A refresh token is rotated on use; one used twice revokes the whole connection. Errors: `400 invalid_grant` / `invalid_target` / `unsupported_grant_type`, `401 invalid_client` |
package/docs/cli.md CHANGED
@@ -90,9 +90,9 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
90
90
  | `foldrun promote <run-id>` | keep a finished run as a regression case: its task and what the next run must still say go into `evals/<target>-regressions.md` (or `--eval <name>`), appended when the file exists. `--expect "contains: $34"` — repeatable, eval syntax — replaces the default judge line that holds the next run to the recorded conclusion; `--case <name>` names the case. A run that went wrong (failed, BLOCKED, BAD) takes `--should "what it should have done"` — the judge's claim — or `--expect` |
91
91
  | `foldrun probe <model>` | can this model hold a tool loop here? A live check |
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
- | `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`, 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 |
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`; `--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 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 |
96
96
  | `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
97
  | `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
98
  | `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`) |
@@ -233,6 +233,8 @@ 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)) |
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 |
236
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) |
237
239
  | `--follow` | `logs`: keep tailing a live run — locally, or on the platform with `--url` |
238
240
  | `--status <s>` | `runs`, and a bulk `stop` or `rerun`: only these statuses, comma-separated — `failed`, `completed`, `awaiting-approval`, `running`, `queued` |
@@ -279,7 +281,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
279
281
  | `--payload <json\|text\|@file>` | `approve`: release a step waiting on `wait: event` with this body (`POST …/approve` `{ payload }`). JSON is sent as JSON, anything else as text; `@file` reads a file |
280
282
  | `--event-wait` | `reject`: refuse a step waiting on `wait: event` rather than a person's gate |
281
283
  | `--note "<text>"` | `approve`: guidance the approved step reads in its prompt — "approve, but skip the Sydney batch". `reject`: the reason, recorded on the trace |
282
- | `--read-only` | `mcp`: offer the AI app only the tools that read — no `run_flow`, `run_agent`, `decide_approval`, `answer_question`, `message_run` or `stop_run` |
284
+ | `--read-only` | `mcp`: offer the AI app only the tools that read — no `run_flow`, `run_agent`, `decide_approval`, `answer_question`, `message_run`, `stop_run`, `create_workspace`, `write_file` or `delete_file` |
283
285
  | `--yes` | skip the confirmation, deliberately: `approve`, `stop`, `deploy` (when it would delete files), and a bulk `stop` or `rerun`, `flow rotate-hook`, `flow draft`, `assistant`, `mcp disconnect`, `a2a cancel`, `history restore`, `restore`, `billing plan`, `repo deploy`/`merge`, `workspace set name`, and every delete — `runs rm`, `storage rm`, `storage unshare`, `source rm`, `secrets rm`, `keys revoke`, `workspaces rm`. Required when there is no terminal to ask; without it nothing is deleted |
284
286
  | `--json` | `report`: the raw run record instead of the report. `observe`, `usage`, `workspaces`, `workspaces show`, `agent ls`, `flow ls`, `agent import --list`, `assistant`, `backups requests`, `status --platform --history`, `signup status`, `team`, `secrets ls`, `triggers`, `storage ls --all`: the raw document |
285
287
  | `--events <a,b>` | `account set notify`: which events are notified on — `failed`, `awaiting-approval`, `completed` |
package/docs/mcp.md CHANGED
@@ -34,7 +34,8 @@ page says which app is asking, where the answer goes (`claude.ai`), and lets
34
34
  you choose:
35
35
 
36
36
  - **what it may do** — read only (inbox, runs, flows, files), or read and act
37
- (also start and stop runs, approve gates, answer and message agents);
37
+ (also start and stop runs, approve gates, answer and message agents, and
38
+ create workspaces and write or delete their files);
38
39
  - **which workspaces** — every one you may open, or the ones you tick.
39
40
 
40
41
  **Connect** sends you back to claude.ai, connected; **Deny** sends it a no.
@@ -134,17 +135,45 @@ and that automatic disconnect are in the audit log (`mcp.connected`,
134
135
  | `list_agents` | a workspace's agents: what each is for and when it last ran | `GET …/agents` |
135
136
  | `list_runs` | recent runs, with outcome, summary and failure (`limit` up to 100, default 20; `flow` keeps that flow's among the newest 500) | `GET …/runs` |
136
137
  | `get_run` | one run in full | `GET …/runs/<id>` |
137
- | `read_file` | one file of a workspace's source, or the tree | `GET …/source` |
138
- | `run_flow` | start a flow (`task`, `test: true` for a [test run](runs#test-runs)) | `POST …/flows/<flow>/run` |
139
- | `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)); answers a run id at once — read it with `get_run` | `POST …/agents/<agent>/run` |
138
+ | `read_file` | one file of a workspace's source (with its `sha256`), or the tree | `GET …/source` |
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), `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` |
140
142
  | `decide_approval` | approve or reject a gate (`note`, `step`) | `POST …/runs/<id>/approve` |
141
143
  | `answer_question` | answer an agent's question mid-step | `POST …/runs/<id>/answer` |
142
144
  | `message_run` | say something to a running agent | `POST …/runs/<id>/message` |
143
145
  | `stop_run` | stop a run | `POST …/runs/<id>/stop` |
144
-
145
- The first nine read. The last six act, and are marked so for the app
146
- (`readOnlyHint: false`; `stop_run` also `destructiveHint: true`), which is
147
- what an app uses to ask you before calling one.
146
+ | `create_workspace` | a new, blank workspace — an `AGENTS.md` and nothing else; refused when the name is taken | `POST /api/workspaces` |
147
+ | `write_file` | create or replace one file — an agent, a flow, knowledge, a skill, `AGENTS.md` (`message` for the revision, `if_match` below) | `PUT …/source` |
148
+ | `delete_file` | delete one file or folder | `DELETE …/source` |
149
+
150
+ The first ten read. The other nine act, and are marked so for the app
151
+ (`readOnlyHint: false`; `stop_run` and `delete_file` also
152
+ `destructiveHint: true`), which is what an app uses to ask you before
153
+ calling one.
154
+
155
+ ## Building with it
156
+
157
+ The last three tools let an app with no shell, such as Claude Desktop,
158
+ build an automation, not only drive one: `create_workspace`, then
159
+ `write_file` for each agent (`agents/<name>/agent.md`) and flow
160
+ (`flows/<name>.md`), then `check_workspace`, then `run_flow` with
161
+ `test: true`.
162
+
163
+ - **A file written is live at once.** The next run reads it; there is no
164
+ separate deploy. Each write is a revision in the workspace's
165
+ [History](deploying#history-and-rollback), so a mistake is undone from there.
166
+ - **It is checked as a deploy checks it.** A file with an error (a flow
167
+ naming an agent that is not there, frontmatter YAML cannot read) is
168
+ refused with `HTTP 422` and its issues, and nothing is written. Warnings
169
+ come back as `issues` on a save that went through.
170
+ - **A change never overwrites someone else's.** Pass the `sha256` that
171
+ `read_file` gave as `if_match`: a file changed since is refused with
172
+ `HTTP 409`. `if_match: "absent"` creates only, and is refused when a file
173
+ is already there.
174
+
175
+ A key with a CLI and a shell (Claude Code, Codex) can also work on a local
176
+ folder and `foldrun deploy` it ([CLI](cli)); both reach the same files.
148
177
 
149
178
  ## What it may do
150
179
 
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
@@ -277,12 +277,13 @@ never holds a run up: a failed send is logged on the platform, not retried.
277
277
  The runs pages search by what happened inside a run, not only its status:
278
278
  **tool** (a step called a tool whose name contains it — `web`, `crm`), **a
279
279
  tool errored**, **agent**, **model** (contains — `haiku`), **≥ tokens** (input
280
- read by all its steps, `50k`) and **≥ secs**. A search can be kept as a named
280
+ read by all its steps, `50k`), **≥ secs** and **conversation** (a
281
+ [context](#conversations), exactly). A search can be kept as a named
281
282
  **view** (save view), yours on every browser; the views sit beside the search.
282
283
  `foldrun runs --tool web --tool-error`, `--agent`, `--model`, `--min-tokens`,
283
- `--min-secs` and `--view <name>` do the same (`foldrun runs views` lists
284
+ `--min-secs`, `--context` and `--view <name>` do the same (`foldrun runs views` lists
284
285
  yours), and `GET …/runs` takes `tool`, `tool_error`, `agent`, `model`,
285
- `min_tokens`, `min_secs`. Tools and models are searchable on runs from
286
+ `min_tokens`, `min_secs`, `context`. Tools and models are searchable on runs from
286
287
  19 Oct 2026; tokens and time on every run.
287
288
 
288
289
  ## Insights
@@ -534,6 +535,91 @@ it to `storage/` — a tool that takes an `out=` path and tees its own output
534
535
  is the reliable way, because a model asked to copy a long report by hand
535
536
  shortens it.
536
537
 
538
+ ## Conversations
539
+
540
+ A run may name a **context**: any id you choose, 1–200 printable ASCII
541
+ characters with no spaces (`order-42`, `ticket:8812`). A run in the same
542
+ context is given the earlier runs of that context before its task — what
543
+ each was asked and what it answered — so a follow-up like "and the same for
544
+ April" means something. It is not a chat screen: the chat stays in your app,
545
+ and foldrun keeps the turns.
546
+
547
+ ```sh
548
+ foldrun agent run analyst --to sales --task "how many orders in March?" --context order-42
549
+ foldrun agent run analyst --to sales --task "and April?" --context order-42
550
+ ```
551
+
552
+ The API takes the same field: `context` on `POST …/agents/<agent>/run` and
553
+ `POST …/flows/<flow>/run` (not with `from`), and on MCP's `run_agent` and
554
+ `run_flow`. Over [A2A](a2a), a task's `contextId` is its context.
555
+
556
+ **What counts as an earlier turn:** a run of the same workspace and context,
557
+ completed or failed, that had finished before this run was started. A test
558
+ run reads only test runs, and a real run only real ones. The cutoff is fixed
559
+ when the run is made, so a retry, a park at a gate or a rescue reads the same
560
+ turns. A failed turn is shown as failed, with the one-line reason.
561
+
562
+ **What the model reads:** each turn's question as it was asked (the task, not
563
+ the flow's own instruction around it) and its answer — the last step's final
564
+ reply. They go in the user message of the step the task reaches, before the
565
+ task, marked as a record of past turns: data, not instructions. Later steps
566
+ get the usual [handoff](#handoffs) from the steps before them. A re-run stays
567
+ in the conversation, and the first step it runs reads it.
568
+
569
+ **How much:** the newest turns first, up to 20 runs and 32,000 characters in
570
+ all; a question is cut at 2,000 characters and an answer at 6,000. Older turns
571
+ that do not fit are left out. The step's trail says what it was given:
572
+ `conversation order-42: given 3 earlier runs (4,210 characters)`.
573
+
574
+ **Who shares a context:** runs started through the API, the dashboard, the
575
+ CLI or MCP share the workspace's contexts, so anyone who can start runs there
576
+ can continue one — and could read those runs anyway. A context is a way to
577
+ group runs, not a lock. Each outside caller over A2A has its own: two A2A keys
578
+ that send the same `contextId` never see each other's turns, and an A2A
579
+ caller's history holds only what that caller was answered.
580
+
581
+ The run page shows a run's **Conversation**, linked to the runs list filtered
582
+ to it; `foldrun runs --context order-42` and `GET …/runs?context=order-42`
583
+ list them.
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
+
537
623
  ## What a run costs, and what stops it
538
624
 
539
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.9.5",
3
+ "version": "20.11.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.4.0"
14
+ "@foldrun/core": "^18.5.0"
15
15
  },
16
16
  "files": [
17
17
  "bin",
package/src/commands.mjs CHANGED
@@ -3976,6 +3976,8 @@ async function invoke(target, flags) {
3976
3976
  // "Run with…" reads and writes, as the platform has it.
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
+ if (flags.context !== undefined && typeof flags.context !== "string") throw new Error("which conversation? `--context <id>`");
3980
+ const files = await runInputs(url, flags, ws);
3979
3981
  let body;
3980
3982
  try {
3981
3983
  body = await remoteCall(url, flags, `/api/workspaces/${ws}/flows/${target}/run${wait}`, {
@@ -3994,6 +3996,11 @@ async function invoke(target, flags) {
3994
3996
  ...(typeof flags.once === "string" && flags.once ? { idempotencyKey: flags.once } : {}),
3995
3997
  // --tag a --tag b: labels on the run, as the API's `tags`.
3996
3998
  ...(many(flags.tag).length ? { tags: many(flags.tag) } : {}),
3999
+ // --context <id> (FOL-162): a turn of that conversation — the first
4000
+ // step reads the earlier runs started with the same context.
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 } : {}),
3997
4004
  }),
3998
4005
  });
3999
4006
  } catch (err) {
@@ -4697,7 +4704,7 @@ async function doctor(flags) {
4697
4704
  * keys create <label> --a2a --to <ws> --flows a,b [--max-tasks N] a key for an outside agent: /a2a only
4698
4705
  * keys create <label> --gateway --cap <usd> [--daily <usd>] a coding agent's key (Claude Code): the gateway only
4699
4706
  * keys create <label> --gateway --login on the operator's Claude login (its own accounts): not metered
4700
- * 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)
4701
4708
  * keys set <id> --opus|--sonnet|--haiku <provider/model> which model each Claude Code tier runs on (a gateway key; `-` clears one, --clear all)
4702
4709
  * keys rotate <id> [--grace 1h] a new key, same label/role/scope; the old
4703
4710
  * one ends now, or when the grace runs out.
@@ -4926,7 +4933,7 @@ async function keysCreateGateway(url, label, flags) {
4926
4933
  // Written from the file as it is NOW, not as it was before the request,
4927
4934
  // so a change made meanwhile is kept. A write that fails after the key
4928
4935
  // exists says so and falls back to the lines to copy.
4929
- /** @type {{ file: string, dropped: string[], backup: string | null } | null} */
4936
+ /** @type {{ file: string, dropped: string[], backup: string | null, statusLine: "added" | "kept" | "theirs" } | null} */
4930
4937
  let done = null;
4931
4938
  if (claude && made.gatewayUrl) {
4932
4939
  try { done = writeClaudeSettings(readClaudeSettings(), made.gatewayUrl, made.key); }
@@ -4937,12 +4944,18 @@ async function keysCreateGateway(url, label, flags) {
4937
4944
  console.log(` ${c.dim(`env: ANTHROPIC_BASE_URL=${made.gatewayUrl}, ANTHROPIC_AUTH_TOKEN=<this key>`)}`);
4938
4945
  if (done.dropped.length) console.log(` ${c.dim(`removed from that env block: ${done.dropped.join(", ")} (it would have competed with the key)`)}`);
4939
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`)}`);
4940
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`);
4941
4950
  } else {
4942
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`);
4943
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.
4944
4955
  console.log(` export ANTHROPIC_BASE_URL=${base}`);
4945
- 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`);
4946
4959
  }
4947
4960
  // A login key is not metered: there is no spend for `keys ls` to show.
4948
4961
  const after = made.credential === "login"
@@ -5007,6 +5020,11 @@ function writeClaudeSettings({ file, text, settings }, baseUrl, key) {
5007
5020
  env.ANTHROPIC_BASE_URL = baseUrl;
5008
5021
  env.ANTHROPIC_AUTH_TOKEN = key;
5009
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 };
5010
5028
  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
5011
5029
  /** @type {string | null} */
5012
5030
  let backup = null;
@@ -5019,7 +5037,66 @@ function writeClaudeSettings({ file, text, settings }, baseUrl, key) {
5019
5037
  fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
5020
5038
  fs.renameSync(tmp, file);
5021
5039
  try { fs.chmodSync(file, 0o600); } catch { /* Windows: no modes */ }
5022
- 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;
5023
5100
  }
5024
5101
 
5025
5102
  /** A retried mint or rotate is answered from the first call, and the server
@@ -6399,11 +6476,6 @@ async function storageCmd(positional, flags, layout) {
6399
6476
  jobs[0].rel = flags.as;
6400
6477
  }
6401
6478
  const token = await renewedToken(url, flags);
6402
- const base = `/api/workspaces/${encodeURIComponent(ws)}/storage`;
6403
- const said = async (res) => {
6404
- const text = await res.text();
6405
- try { return JSON.parse(text).error ?? text.slice(0, 200); } catch { return text.slice(0, 200); }
6406
- };
6407
6479
  let ok = 0, skipped = 0, bytesSent = 0;
6408
6480
  const failed = [];
6409
6481
  console.log();
@@ -6416,23 +6488,7 @@ async function storageCmd(positional, flags, layout) {
6416
6488
  continue;
6417
6489
  }
6418
6490
  try {
6419
- const sha = crypto.createHash("sha256").update(bytes).digest("hex");
6420
- // The length too: the platform checks the limits on it and signs it
6421
- // into the URL, so the bucket takes exactly these bytes (30 Oct 2026).
6422
- 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 });
6423
- // A platform older than presigned uploads answers 404 here: it
6424
- // takes the bytes itself, the way one with no bucket does.
6425
- if (!ask.ok && ask.status !== 404) throw new HttpError(await said(ask), ask.status, {});
6426
- const { url: direct } = /** @type {{ url?: string | null }} */ (ask.ok ? await ask.json() : { url: null });
6427
- if (direct) {
6428
- const put = await fetch(direct, { method: "PUT", body: bytes, signal: AbortSignal.timeout(Math.max(120, bytes.length / 200_000) * 1000) });
6429
- if (!put.ok) throw new Error(`the storage service refused it (${put.status})`);
6430
- const done = await remoteFetch(url, base, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ path: rel, sha, size: bytes.length }) }, { token });
6431
- if (!done.ok) throw new HttpError(await said(done), done.status, {});
6432
- } else {
6433
- const put = await remoteFetch(url, `${base}?path=${encodeURIComponent(rel)}`, { method: "PUT", body: bytes, headers: { "content-type": "application/octet-stream" } }, { token });
6434
- if (!put.ok) throw new HttpError(await said(put), put.status, {});
6435
- }
6491
+ await uploadToStorage(url, token, ws, rel, bytes);
6436
6492
  ok++;
6437
6493
  bytesSent += bytes.length;
6438
6494
  console.log(` ${c.green("✓")} ${ws}/storage/${rel} ${c.dim(humanBytes(bytes.length))}`);
@@ -7714,7 +7770,7 @@ async function runViewsCmd(flags) {
7714
7770
 
7715
7771
  /** The filter flags a saved view keeps, as the runs page's query names them
7716
7772
  * (run-views-model.ts VIEW_KEYS) — the reverse of what --view reads. */
7717
- 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"]];
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"]];
7718
7774
 
7719
7775
  /**
7720
7776
  * `foldrun runs views save <name> [filters]` and `runs views rm <name>` — the
@@ -7732,13 +7788,13 @@ async function runViewsEditCmd([verb, ...rest], flags) {
7732
7788
  if (verb === "save") {
7733
7789
  if (name.length > 40) throw new Error("a view's name is 1 to 40 characters");
7734
7790
  // Said, not dropped: the route would keep only the keys it knows.
7735
- for (const f of ["verdict", "outcome"]) if (flags[f] !== undefined) throw new Error(`a saved view keeps --status, --flow, --to, --since, --q, --tool, --tool-error, --agent, --model, --min-tokens and --min-secs — not --${f}`);
7791
+ for (const f of ["verdict", "outcome"]) if (flags[f] !== undefined) throw new Error(`a saved view keeps --status, --flow, --to, --since, --q, --tool, --tool-error, --agent, --model, --min-tokens, --min-secs and --context — not --${f}`);
7736
7792
  const query = new URLSearchParams();
7737
7793
  for (const [flag, key] of VIEW_FLAGS) if (flags[flag] !== undefined && flags[flag] !== true) query.set(key, String(flags[flag]));
7738
7794
  if (flags["tool-error"] === true) query.set("tool_error", "1");
7739
7795
  // The dashboard's windows are today, 7d and 30d; its Today is 24 hours.
7740
7796
  if (["24h", "1d"].includes(String(query.get("since")).trim().toLowerCase())) query.set("since", "today");
7741
- if (!query.size) throw new Error("a view needs at least one filter — --status, --flow, --to, --since, --q, --tool, --tool-error, --agent, --model, --min-tokens or --min-secs");
7797
+ if (!query.size) throw new Error("a view needs at least one filter — --status, --flow, --to, --since, --q, --tool, --tool-error, --agent, --model, --min-tokens, --min-secs or --context");
7742
7798
  list = [...runViews.filter((v) => v.name !== name), { name, query: query.toString() }];
7743
7799
  const since = query.get("since");
7744
7800
  const d = await remoteCall(url, flags, "/api/me/preferences", { method: "PATCH", body: JSON.stringify({ runViews: list }) });
@@ -8352,6 +8408,68 @@ async function stopCmd(runId, flags, layout) {
8352
8408
  * carries each run's one-line summary — the sentence that says what it
8353
8409
  * found, not merely that it finished.
8354
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
+
8355
8473
  async function runsCmd(flags, layout) {
8356
8474
  const url = platformFor(flags, "runs");
8357
8475
  // --view <name>: a saved search (the dashboard's) read first, so every
@@ -8404,11 +8522,11 @@ async function runsCmd(flags, layout) {
8404
8522
  // Search (FOL-72 step 9): by what happened inside a run, filtered by the
8405
8523
  // platform; --view <name> starts from a saved search (the dashboard's).
8406
8524
  const search = new URLSearchParams();
8407
- for (const [flag, key] of [["tool", "tool"], ["agent", "agent"], ["model", "model"], ["min-tokens", "min_tokens"], ["min-secs", "min_secs"]]) {
8525
+ for (const [flag, key] of [["tool", "tool"], ["agent", "agent"], ["model", "model"], ["min-tokens", "min_tokens"], ["min-secs", "min_secs"], ["context", "context"]]) {
8408
8526
  if (flags[flag] !== undefined && flags[flag] !== true) search.set(key, String(flags[flag]));
8409
8527
  }
8410
8528
  if (flags["tool-error"] === true) search.set("tool_error", "1");
8411
- const searching = [...search.keys()].some((k) => ["tool", "tool_error", "agent", "model", "min_tokens", "min_secs"].includes(k));
8529
+ const searching = [...search.keys()].some((k) => ["tool", "tool_error", "agent", "model", "min_tokens", "min_secs", "context"].includes(k));
8412
8530
  // A view's flow or text filters here, after the fetch: ask for the ceiling
8413
8531
  // as for a status, or matches past the newest few go missing (Codex review).
8414
8532
  const localText = typeof flags.flow === "string" || typeof flags.q === "string";
@@ -8432,6 +8550,9 @@ async function runsCmd(flags, layout) {
8432
8550
  if (wanted && !wanted.has(r.outcome === "stopped" ? "stopped" : r.status)) return false;
8433
8551
  if (verdicts && !(r.status === "completed" && verdicts.has(verdictOf(r)))) return false;
8434
8552
  if (outcomes && !(typeof r.outcome === "string" && outcomes.has(r.outcome))) return false;
8553
+ // --context (FOL-162): one conversation's runs. The platform filters too;
8554
+ // checked here as well, so a platform from before it lists none, not all.
8555
+ if (typeof flags.context === "string" && r.context?.id !== flags.context) return false;
8435
8556
  // A view's flow and free text (the runs page's): "agent: x" is a direct run.
8436
8557
  // The dashboard names a run by what ran (whatRan): a direct agent run's
8437
8558
  // or an eval's own name, without adhoc:/eval: (Codex review).
@@ -8455,7 +8576,7 @@ async function runsCmd(flags, layout) {
8455
8576
  for (let round = 0; ; round++) {
8456
8577
  const answers = await pool(names, 8, async (ws) => {
8457
8578
  try {
8458
- const forApi = new URLSearchParams([...search].filter(([k]) => ["tool", "tool_error", "agent", "model", "min_tokens", "min_secs"].includes(k)));
8579
+ const forApi = new URLSearchParams([...search].filter(([k]) => ["tool", "tool_error", "agent", "model", "min_tokens", "min_secs", "context"].includes(k)));
8459
8580
  forApi.set("limit", String(perWorkspace));
8460
8581
  if (cursor) forApi.set("before", cursor);
8461
8582
  const answer = await remoteCall(url, flags, `/api/workspaces/${ws}/runs?${forApi}`);
@@ -9093,6 +9214,8 @@ async function agentRunCmd(positional, flags, layout) {
9093
9214
  const WAIT_PIECE_S = 25;
9094
9215
  const wait = flags.wait === true ? `?wait=true&timeout=${WAIT_PIECE_S}` : "";
9095
9216
  const base = `/api/workspaces/${encodeURIComponent(ws)}/agents/${encodeURIComponent(name)}`;
9217
+ if (flags.context !== undefined && typeof flags.context !== "string") throw new Error("which conversation? `--context <id>`");
9218
+ const files = await runInputs(url, flags, ws);
9096
9219
 
9097
9220
  // A waited run that FAILS is the answer to the question, not a fault in
9098
9221
  // the call: 200 with its status since FOL-106, 500 with the same record
@@ -9112,7 +9235,9 @@ async function agentRunCmd(positional, flags, layout) {
9112
9235
  method: "POST",
9113
9236
  // --test: the platform marks the run a test run — sends refused or sunk
9114
9237
  // at the proxy, send-capable secrets withheld, state/ kept.
9115
- body: JSON.stringify({ ...(task ? { task } : {}), ...(flags.test === true ? { test: true } : {}) }),
9238
+ // --context <id> (FOL-162): a turn of that conversation — the agent
9239
+ // 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 } : {}) }),
9116
9241
  }),
9117
9242
  );
9118
9243
  const runId = body?.runId;
@@ -15118,6 +15243,8 @@ export async function run(command, positional, flags, workspace, layout) {
15118
15243
  return apiCmd(positional, flags);
15119
15244
  case "keys":
15120
15245
  return keysCmd(positional, flags);
15246
+ case "gateway":
15247
+ return gatewayCmd(positional, flags);
15121
15248
  case "a2a":
15122
15249
  return a2aCmd(positional, flags, layout);
15123
15250
  case "audit":