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 +4 -3
- package/docs/a2a.md +5 -1
- package/docs/api.md +4 -4
- package/docs/cli.md +4 -3
- package/docs/mcp.md +37 -8
- package/docs/runs.md +51 -3
- package/package.json +2 -2
- package/src/commands.mjs +17 -7
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 `
|
|
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
|
-
| `
|
|
139
|
-
| `
|
|
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
|
-
|
|
146
|
-
|
|
147
|
-
|
|
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`)
|
|
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.
|
|
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.
|
|
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
|
|
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
|
|
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
|
-
|
|
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;
|