foldrun 20.9.5 → 20.10.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>)
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
@@ -331,6 +331,7 @@ Options
331
331
  --no-task agent run: start it with no instruction — the agent works from its own prompt alone
332
332
  --task "<text>" flow inputs save: the task the saved set holds (--file <path> reads it from a file)
333
333
  --test run, invoke: a test run — nothing outward, state/ untouched, receipts on the run page
334
+ --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
335
  --follow logs: keep tailing a live run (with --url: on the platform)
335
336
  --status <s> runs, stop, rerun: only these statuses, comma-separated (failed, completed, awaiting-approval…)
336
337
  --since <span> runs, stop, rerun: only runs started within 24h, 7d, 90m, 2w, or today (the last 24h)
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. `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; `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,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
+ | `--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
237
  | `--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
238
  | `--follow` | `logs`: keep tailing a live run — locally, or on the platform with `--url` |
238
239
  | `--status <s>` | `runs`, and a bulk `stop` or `rerun`: only these statuses, comma-separated — `failed`, `completed`, `awaiting-approval`, `running`, `queued` |
@@ -279,7 +280,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
279
280
  | `--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
281
  | `--event-wait` | `reject`: refuse a step waiting on `wait: event` rather than a person's gate |
281
282
  | `--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` |
283
+ | `--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
284
  | `--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
285
  | `--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
286
  | `--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)) | `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
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/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,53 @@ 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
+
537
585
  ## What a run costs, and what stops it
538
586
 
539
587
  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.10.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,7 @@ 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>`");
3979
3980
  let body;
3980
3981
  try {
3981
3982
  body = await remoteCall(url, flags, `/api/workspaces/${ws}/flows/${target}/run${wait}`, {
@@ -3994,6 +3995,9 @@ async function invoke(target, flags) {
3994
3995
  ...(typeof flags.once === "string" && flags.once ? { idempotencyKey: flags.once } : {}),
3995
3996
  // --tag a --tag b: labels on the run, as the API's `tags`.
3996
3997
  ...(many(flags.tag).length ? { tags: many(flags.tag) } : {}),
3998
+ // --context <id> (FOL-162): a turn of that conversation — the first
3999
+ // step reads the earlier runs started with the same context.
4000
+ ...(typeof flags.context === "string" ? { context: flags.context } : {}),
3997
4001
  }),
3998
4002
  });
3999
4003
  } catch (err) {
@@ -7714,7 +7718,7 @@ async function runViewsCmd(flags) {
7714
7718
 
7715
7719
  /** The filter flags a saved view keeps, as the runs page's query names them
7716
7720
  * (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"]];
7721
+ 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
7722
 
7719
7723
  /**
7720
7724
  * `foldrun runs views save <name> [filters]` and `runs views rm <name>` — the
@@ -7732,13 +7736,13 @@ async function runViewsEditCmd([verb, ...rest], flags) {
7732
7736
  if (verb === "save") {
7733
7737
  if (name.length > 40) throw new Error("a view's name is 1 to 40 characters");
7734
7738
  // 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}`);
7739
+ 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
7740
  const query = new URLSearchParams();
7737
7741
  for (const [flag, key] of VIEW_FLAGS) if (flags[flag] !== undefined && flags[flag] !== true) query.set(key, String(flags[flag]));
7738
7742
  if (flags["tool-error"] === true) query.set("tool_error", "1");
7739
7743
  // The dashboard's windows are today, 7d and 30d; its Today is 24 hours.
7740
7744
  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");
7745
+ 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
7746
  list = [...runViews.filter((v) => v.name !== name), { name, query: query.toString() }];
7743
7747
  const since = query.get("since");
7744
7748
  const d = await remoteCall(url, flags, "/api/me/preferences", { method: "PATCH", body: JSON.stringify({ runViews: list }) });
@@ -8404,11 +8408,11 @@ async function runsCmd(flags, layout) {
8404
8408
  // Search (FOL-72 step 9): by what happened inside a run, filtered by the
8405
8409
  // platform; --view <name> starts from a saved search (the dashboard's).
8406
8410
  const search = new URLSearchParams();
8407
- for (const [flag, key] of [["tool", "tool"], ["agent", "agent"], ["model", "model"], ["min-tokens", "min_tokens"], ["min-secs", "min_secs"]]) {
8411
+ for (const [flag, key] of [["tool", "tool"], ["agent", "agent"], ["model", "model"], ["min-tokens", "min_tokens"], ["min-secs", "min_secs"], ["context", "context"]]) {
8408
8412
  if (flags[flag] !== undefined && flags[flag] !== true) search.set(key, String(flags[flag]));
8409
8413
  }
8410
8414
  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));
8415
+ const searching = [...search.keys()].some((k) => ["tool", "tool_error", "agent", "model", "min_tokens", "min_secs", "context"].includes(k));
8412
8416
  // A view's flow or text filters here, after the fetch: ask for the ceiling
8413
8417
  // as for a status, or matches past the newest few go missing (Codex review).
8414
8418
  const localText = typeof flags.flow === "string" || typeof flags.q === "string";
@@ -8432,6 +8436,9 @@ async function runsCmd(flags, layout) {
8432
8436
  if (wanted && !wanted.has(r.outcome === "stopped" ? "stopped" : r.status)) return false;
8433
8437
  if (verdicts && !(r.status === "completed" && verdicts.has(verdictOf(r)))) return false;
8434
8438
  if (outcomes && !(typeof r.outcome === "string" && outcomes.has(r.outcome))) return false;
8439
+ // --context (FOL-162): one conversation's runs. The platform filters too;
8440
+ // checked here as well, so a platform from before it lists none, not all.
8441
+ if (typeof flags.context === "string" && r.context?.id !== flags.context) return false;
8435
8442
  // A view's flow and free text (the runs page's): "agent: x" is a direct run.
8436
8443
  // The dashboard names a run by what ran (whatRan): a direct agent run's
8437
8444
  // or an eval's own name, without adhoc:/eval: (Codex review).
@@ -8455,7 +8462,7 @@ async function runsCmd(flags, layout) {
8455
8462
  for (let round = 0; ; round++) {
8456
8463
  const answers = await pool(names, 8, async (ws) => {
8457
8464
  try {
8458
- const forApi = new URLSearchParams([...search].filter(([k]) => ["tool", "tool_error", "agent", "model", "min_tokens", "min_secs"].includes(k)));
8465
+ const forApi = new URLSearchParams([...search].filter(([k]) => ["tool", "tool_error", "agent", "model", "min_tokens", "min_secs", "context"].includes(k)));
8459
8466
  forApi.set("limit", String(perWorkspace));
8460
8467
  if (cursor) forApi.set("before", cursor);
8461
8468
  const answer = await remoteCall(url, flags, `/api/workspaces/${ws}/runs?${forApi}`);
@@ -9093,6 +9100,7 @@ async function agentRunCmd(positional, flags, layout) {
9093
9100
  const WAIT_PIECE_S = 25;
9094
9101
  const wait = flags.wait === true ? `?wait=true&timeout=${WAIT_PIECE_S}` : "";
9095
9102
  const base = `/api/workspaces/${encodeURIComponent(ws)}/agents/${encodeURIComponent(name)}`;
9103
+ if (flags.context !== undefined && typeof flags.context !== "string") throw new Error("which conversation? `--context <id>`");
9096
9104
 
9097
9105
  // A waited run that FAILS is the answer to the question, not a fault in
9098
9106
  // the call: 200 with its status since FOL-106, 500 with the same record
@@ -9112,7 +9120,9 @@ async function agentRunCmd(positional, flags, layout) {
9112
9120
  method: "POST",
9113
9121
  // --test: the platform marks the run a test run — sends refused or sunk
9114
9122
  // at the proxy, send-capable secrets withheld, state/ kept.
9115
- body: JSON.stringify({ ...(task ? { task } : {}), ...(flags.test === true ? { test: true } : {}) }),
9123
+ // --context <id> (FOL-162): a turn of that conversation — the agent
9124
+ // 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 } : {}) }),
9116
9126
  }),
9117
9127
  );
9118
9128
  const runId = body?.runId;