foldrun 20.9.5 → 20.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/foldrun.mjs +12 -4
- package/docs/a2a.md +5 -1
- package/docs/api.md +4 -4
- package/docs/cli.md +5 -3
- package/docs/mcp.md +37 -8
- package/docs/providers.md +20 -0
- package/docs/runs.md +89 -3
- package/package.json +2 -2
- package/src/commands.mjs +160 -33
package/bin/foldrun.mjs
CHANGED
|
@@ -116,7 +116,7 @@ const HELP = `foldrun — agents are just folders
|
|
|
116
116
|
foldrun check --security only the security rules: hard-coded secrets, hidden text, agents that can leak, unpinned code — fails on a warning
|
|
117
117
|
foldrun check --rules every rule check knows: id, level, what it guards against (--json)
|
|
118
118
|
foldrun check --to <ws> --online also the network checks, run by the platform: known vulnerabilities for exact runtime pins (OSV) and remote MCP servers' tool text — and what could not be checked
|
|
119
|
-
foldrun agent run <name> run one agent once on the platform (--task "…", --to, --wait, --test)
|
|
119
|
+
foldrun agent run <name> run one agent once on the platform (--task "…", --to, --wait, --test, --context <id>, --file <path> repeatable)
|
|
120
120
|
foldrun agent run <name> --no-task run it with no instruction, on its own prompt alone — the dashboard's Run (--to, --wait, --test)
|
|
121
121
|
foldrun agent link <agent> add to its team, in its frontmatter: --subagent <worker> (--isolated: sandbox: own on the worker), --consult <agent> or --can-ask (--description for a worker with none)
|
|
122
122
|
foldrun agent unlink <agent> take one away: --subagent <name>, --consult <name> or --can-ask
|
|
@@ -163,10 +163,10 @@ const HELP = `foldrun — agents are just folders
|
|
|
163
163
|
foldrun promote <run-id> keep a finished run as a regression case in evals/ (--eval <name>, --expect "contains: …" repeatable, --case <name>); a run that went wrong takes --should "what it should have done"
|
|
164
164
|
foldrun probe <model> live check: can this model hold a tool loop here?
|
|
165
165
|
foldrun logs [run-id] recent runs in one workspace, or one run's full event trail (--local: this machine's)
|
|
166
|
-
foldrun runs what has run lately, across the account — --status, --verdict, --outcome (good, done, quiet, blocked, bad, failed, needs-you, …), --since, --to, --flow <name>, --q <words>, --limit; search with --tool, --tool-error, --agent, --model, --min-tokens 50k, --min-secs, or --view <name>; --limit is one page: --page <n>, --before <cursor> (printed when more match), --all, --json
|
|
166
|
+
foldrun runs what has run lately, across the account — --status, --verdict, --outcome (good, done, quiet, blocked, bad, failed, needs-you, …), --since, --to, --flow <name>, --q <words>, --limit; search with --tool, --tool-error, --agent, --model, --min-tokens 50k, --min-secs, --context <id>, or --view <name>; --limit is one page: --page <n>, --before <cursor> (printed when more match), --all, --json
|
|
167
167
|
foldrun runs outputs <run-id> which files the run archived from its agents' outputs/, with their sizes (--to, --json); report <run-id> get downloads one
|
|
168
168
|
foldrun runs views your saved run searches (--local prints exactly what logs --local prints)
|
|
169
|
-
foldrun runs views save <name> [filters] save the runs filters given (--status, --flow, --to, --since, --q, --tool, --tool-error, --agent, --model, --min-tokens, --min-secs) as a view; a name taken is replaced
|
|
169
|
+
foldrun runs views save <name> [filters] save the runs filters given (--status, --flow, --to, --since, --q, --tool, --tool-error, --agent, --model, --min-tokens, --min-secs, --context) as a view; a name taken is replaced
|
|
170
170
|
foldrun runs views rm <name> delete a saved view (asks; --yes)
|
|
171
171
|
foldrun runs doctor <run-id> the run doctor: the assistant reads a failed run and the files it names, says why (platform, check, work or outside) and proposes the fix as diffs, saved on yes (--to, --yes, --dry-run, --json)
|
|
172
172
|
foldrun runs rm <run-id> delete a run's record and archived outputs (an admin); a live one is stopped first — asks first, --yes means it
|
|
@@ -307,7 +307,8 @@ Signing in
|
|
|
307
307
|
foldrun keys create <label> --a2a --to <ws> --flows a,b a key for an OUTSIDE agent: it opens /a2a for those published flows and no /api route (--max-tasks N open at once, default 10; --expires); shown once
|
|
308
308
|
foldrun keys set <id> --sonnet openai/gpt-6 which model a gateway key runs each Claude Code tier on (--opus, --haiku; - clears one, --clear all)
|
|
309
309
|
foldrun keys create <label> --gateway --cap <usd> [--daily <usd>] a key for a CODING agent (Claude Code: ANTHROPIC_BASE_URL + this key) — it spends the account's credits on foldrun's models through the gateway, up to its own limits, and opens no /api route; an admin of every workspace; shown once
|
|
310
|
-
foldrun keys create laptop --gateway --cap 20 --claude-code the same, and Claude Code is set up on this machine: the URL and key go into its settings
|
|
310
|
+
foldrun keys create laptop --gateway --cap 20 --claude-code the same, and Claude Code is set up on this machine: the URL and key go into its settings, and its status line shows the key's spend
|
|
311
|
+
foldrun gateway status-line one line for Claude Code's status line: what the gateway key in ANTHROPIC_AUTH_TOKEN has spent, of its limits (asks the gateway; kept 10 s, --cache <s>)
|
|
311
312
|
foldrun a2a ls --to <ws> what a workspace serves over A2A: each flow's a2a:, card and endpoint URLs, its A2A keys (admins), recent tasks and the key that asked (--json)
|
|
312
313
|
foldrun a2a publish <flow> set a2a: publish: true in the flow (--to <ws>: the deployed copy, an admin's) — --name, --description, --example "…" (repeatable), --public-card | --private-card; diff, checked, --dry-run
|
|
313
314
|
foldrun a2a publish <flow> --clear-name | --clear-description | --clear-examples drop the card's name, description or examples (also on unpublish)
|
|
@@ -331,6 +332,8 @@ Options
|
|
|
331
332
|
--no-task agent run: start it with no instruction — the agent works from its own prompt alone
|
|
332
333
|
--task "<text>" flow inputs save: the task the saved set holds (--file <path> reads it from a file)
|
|
333
334
|
--test run, invoke: a test run — nothing outward, state/ untouched, receipts on the run page
|
|
335
|
+
--file <path> invoke, agent run: a file handed to the run (repeatable) — a storage path, or ./local-file uploaded to storage/inputs/ first; the first step finds them in inputs/ and can read images and PDFs (FOL-163)
|
|
336
|
+
--context <id> invoke, agent run: a turn of that conversation — the first step reads the earlier runs started with the same context (any id you choose, 1–200 printable characters); runs: only that conversation's runs
|
|
334
337
|
--follow logs: keep tailing a live run (with --url: on the platform)
|
|
335
338
|
--status <s> runs, stop, rerun: only these statuses, comma-separated (failed, completed, awaiting-approval…)
|
|
336
339
|
--since <span> runs, stop, rerun: only runs started within 24h, 7d, 90m, 2w, or today (the last 24h)
|
|
@@ -508,6 +511,8 @@ if (!command || command === "--help" || command === "-h") {
|
|
|
508
511
|
const BOOLEAN_FLAGS = new Set(["read-only", "account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear", "security", "changed", "write-baseline", "no-baseline", "rules", "calls", "tree", "tool-error", "stop", "last", "no-pkce", "generate-key", "device", "write", "dpop", "export", "isolated", "no-wait", "dismissed", "unread", "team", "started", "mine", "none", "a2a", "gateway", "claude-code", "login", "unreachable", "public-card", "private-card", "return-immediately", "online", "overwrite", "no-send", "event-wait", "with-client", "use", "clear-name", "clear-description", "clear-examples", "clear-accept-risk", "clear-address", "clear-email", "clear-abn", "no-task", "empty"]);
|
|
509
512
|
// Flags said more than once collect into a list: `--tag a --tag b`.
|
|
510
513
|
const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove", "rule", "authorize-param", "example", "accept-risk"]);
|
|
514
|
+
/** Flags that become a list only when given more than once (FOL-163 `--file`). */
|
|
515
|
+
const LIST_WHEN_REPEATED = new Set(["file"]);
|
|
511
516
|
// `--wait` is a switch everywhere but `flow add <flow> wait`, where it takes
|
|
512
517
|
// a span: `--wait 30m`, `--wait event`. Only a value that reads as one is
|
|
513
518
|
// taken, so `invoke x --wait` and friends are as they were.
|
|
@@ -526,6 +531,9 @@ for (let i = 0; i < rest.length; i++) {
|
|
|
526
531
|
else if (BOOLEAN_FLAGS.has(name) || next === undefined || next.startsWith("--")) value = true;
|
|
527
532
|
else value = rest[++i];
|
|
528
533
|
if (REPEATABLE.has(name) && typeof value === "string") flags[name] = [...(Array.isArray(flags[name]) ? flags[name] : []), value];
|
|
534
|
+
// Given twice, a list; once, a string as ever — so `--file` stays one path
|
|
535
|
+
// for the commands that read one, and invoke / agent run take several.
|
|
536
|
+
else if (LIST_WHEN_REPEATED.has(name) && typeof value === "string" && flags[name] !== undefined && flags[name] !== true) flags[name] = [...(Array.isArray(flags[name]) ? flags[name] : [flags[name]]), value];
|
|
529
537
|
else flags[name] = value;
|
|
530
538
|
}
|
|
531
539
|
|
package/docs/a2a.md
CHANGED
|
@@ -266,7 +266,11 @@ not taken: one request object per call.
|
|
|
266
266
|
|
|
267
267
|
A task takes **one message**. A follow-up `SendMessage` with the task's
|
|
268
268
|
`taskId` is refused (`-32004`); send a new message without `taskId`, with the
|
|
269
|
-
`contextId` to keep the conversation together.
|
|
269
|
+
`contextId` to keep the conversation together. The flow's first step then
|
|
270
|
+
reads the earlier tasks of that `contextId` — what you sent and what you were
|
|
271
|
+
answered — before your message ([conversations](runs#conversations)). Your
|
|
272
|
+
contexts are your key's own: another caller's same `contextId` is a different
|
|
273
|
+
conversation, and you see only the answers you were given.
|
|
270
274
|
|
|
271
275
|
### Retries: `messageId`
|
|
272
276
|
|
package/docs/api.md
CHANGED
|
@@ -159,7 +159,7 @@ installer's `error`, its cause on the first line. `foldrun deploy` polls it afte
|
|
|
159
159
|
| `/api/workspaces/<ws>/a2a` | GET | what this workspace serves to outside agents over A2A 1.0: `{ flows: [{ flow, published, publicCard, name, description, hasInputSchema, acceptRisk, card, url }], risks: [{ flow, agent, secrets, accepted }], keys, tasks: [{ id, flow, state, runId, contextId, key: { id, label, prefix, revoked }, createdAt, updatedAt }] }` — every flow whose frontmatter says `a2a:`; `risks`, every flow's agents (published or not) that hold a secret and can run code, with whether its `a2a: accept_risk` names them — a published flow with one not accepted takes no new task ([accept_risk](a2a.md#secret-and-code-accept_risk)); the URL of its agent card and of its JSON-RPC endpoint (`/a2a/<account>/<ws>/flows/<flow>`), the workspace's live A2A keys (`[{ id, label, prefix, flows, maxTasks, expiresAt }]`, or `null` unless you may manage keys), and the 50 newest A2A tasks (`state` a `TASK_STATE_*`) with the key that asked. Publishing is the flow's `a2a:` field, written like any other — changing it needs `workspace:manage`. `404` when the workspace does not exist |
|
|
160
160
|
| `/api/workspaces/<ws>/flows/<flow>` | PATCH | edit a step (`step`, `instruction`, `options`, `target`, `subflow`), rearrange (`groups`), set `trigger`, set `compute` (`{ vcpu, memGiB, diskGiB }` or `null` — what one run may hold at once, merged over what the flow says), set `a2a` (`{ publish, name, description, examples, public_card, input, accept_risk }` merged over the flow's `a2a:` — a key sent replaces it, `null` removes it; `a2a: null` removes the block; refused `400` when the result would not read, `403` without the admin role, `400` `code: a2a_secret_code` when an agent of the published flow holds a secret and can run code and `accept_risk` does not name it — see [A2A](a2a.md)), a canvas edit (`edit`, or `edits` — at most 200 in one request, `400` past that; adding a step is `edit: { op: "insert", target, subflow?, instruction?, at: { rail } }`, removing one `edit: { op: "remove", step }`), undo (`restore` + `expect`). The older POST (a step at the end) and DELETE (`{ step }`) were removed on 5 Nov 2026 (deprecated and sunset the same day) — every client (the canvas, the list view's board, the CLI) sends PATCH `{ edit }`, one mechanism per change; `DELETE …/flows/draft` answers `410`. Every PATCH and DELETE takes `expect` — the text the step numbers were read from, or its sha256 — and is refused with `409` and the current `text`, nothing written, when the file no longer reads it (the canvas, the list view's board and step options, and the CLI's `flow add`/`rm-step`/`dup-step --to` send it; the dashboard shows the 409 as "this flow changed since you opened it — reload") |
|
|
161
161
|
| `/api/workspaces/<ws>/flows/draft` | POST, PATCH, DELETE | POST draft a flow with a model: `{ description, flow? }` (`flow` redrafts that one). Returns `{ ok, files: [{ path, content, before, sha256 }], issues: [{ where, message, level }], repaired, notes }` — checked with the deploy's checks and the flow lint, repaired once. **Writes nothing**; save with the source PUT. Needs `workspace:write`; a description over 4,000 characters is `413`; a Chat-Completions `provider:` is `422`. On the platform's models the balance is checked first (`402`) and the call is charged as one ledger line, flow `ai-draft`. PATCH and DELETE, and a POST without `description`, are the edits of a flow that happens to be named `draft`, exactly as at `flows/<flow>` |
|
|
162
|
-
| `/api/workspaces/<ws>/flows/<flow>/run` | POST | start it. An `Idempotency-Key` header, or `idempotencyKey` in the body, makes a retried call safe: a dropped response, a proxy timeout or a CI step that ran twice is answered `started: false` with the `runId` it already started, rather than starting a second run and billing for it. Keys are remembered for 24 hours, per flow. While the account has its most runs waiting for their turn it answers 409 `{ error, code: "waiting_cap", limit, waiting }` and starts nothing ([how many runs may wait](budgets-and-billing#how-many-runs-may-wait)); so do the agent run and rerun routes (an A2A caller is told the agent is busy), and a webhook or inbound email gets the same as a 503 with `Retry-After: 60` |
|
|
162
|
+
| `/api/workspaces/<ws>/flows/<flow>/run` | POST | start it. `inputs` (storage paths) hands files to the first step at `inputs/` ([inputs](runs#inputs)); not with `from`. `context` (1–200 printable ASCII characters) makes the run a turn of that [conversation](runs#conversations): its first step reads the earlier runs of the same context before the task; not with `from` (`400`); the answer carries `context`. An `Idempotency-Key` header, or `idempotencyKey` in the body, makes a retried call safe: a dropped response, a proxy timeout or a CI step that ran twice is answered `started: false` with the `runId` it already started, rather than starting a second run and billing for it. Keys are remembered for 24 hours, per flow. While the account has its most runs waiting for their turn it answers 409 `{ error, code: "waiting_cap", limit, waiting }` and starts nothing ([how many runs may wait](budgets-and-billing#how-many-runs-may-wait)); so do the agent run and rerun routes (an A2A caller is told the agent is busy), and a webhook or inbound email gets the same as a 503 with `Retry-After: 60` |
|
|
163
163
|
| `/api/workspaces/<ws>/flows/<flow>/filter` | POST | test the flow's `filter:` against a delivery without starting anything: `{ payload }` — a webhook's JSON body (or the body as a string, read as JSON), an email's `{ from, to, subject, text }`, a chained run's `{ run, flow, status, ending, verdict, summary }`, a storage event's `{ by, paths }`. Answers `{ flow, trigger, filter, applies, match, reason }` — `reason` names the first condition that failed; a flow with no filter matches everything. Reads the deployed flow; nothing is recorded or charged |
|
|
164
164
|
|
|
165
165
|
`POST .../run` takes `task` (the input), `from` (start at step N — a rerun of
|
|
@@ -199,7 +199,7 @@ history with each message.
|
|
|
199
199
|
|---|---|---|
|
|
200
200
|
| `/api/workspaces/<ws>/agents` | GET, POST | list — each agent's frontmatter as read, `owner` and `ownerFrom` (its own `owner:`, else the workspace's, else the account's), `lastRunAt` (when its latest step that ran started, from the runs kept; null for none) and `stale` (past `alerts: stale_days`); create (`name`) |
|
|
201
201
|
| `/api/workspaces/<ws>/agents/<agent>` | PATCH | edit one line of an agent's frontmatter in place, as the flow canvas does: `{ list: { key, name, action } }` — `key` one of `subagents`, `agents`, `tools`; `action` `add` or `remove` — or `{ set: { key: "description" | "sandbox", value } }` (`sandbox` takes `own` or `parent`, else 400), or `{ network }` — the sites its sandbox may reach: `"open"`, `"trusted"`, `"none"`, a list of sites, or `{ level, allow, defaults }`; `null` removes the line so it inherits ([Network](network)). A `network` nobody could read is a 400 that says why. Only that key's lines change — comments, key order and prose stay. Answers `{ ok, changed }`; 404 for an unknown agent. `workspace:write` |
|
|
202
|
-
| `/api/workspaces/<ws>/agents/<agent>/run` | POST | run one agent alone (`task`; `test: true` for a test run; `snapshot`: a folder to work on, the id `POST …/snapshots` answered — the step finds it in `snapshot/`, only its `outputs/` come back to the workspace, and the run's outputs hold `snapshot.patch`, the change as a git patch, with `snapshot.json` saying what it touched or why there is none. Needs the k8s sandbox: `409` on an install without it, `404` for a snapshot not in this workspace) |
|
|
202
|
+
| `/api/workspaces/<ws>/agents/<agent>/run` | POST | run one agent alone (`task`; `test: true` for a test run; `inputs`: storage paths handed to the step at `inputs/` ([inputs](runs#inputs): at most 20 and 100 MiB, held as they are when the run is made; `404` names a path with no stored file, `409` where the install has no sandbox to stage them; the answer lists them); `context`: a [conversation](runs#conversations) the run is a turn of — the agent reads the earlier runs of the same context before the task, and the answer carries `context`; `snapshot`: a folder to work on, the id `POST …/snapshots` answered — the step finds it in `snapshot/`, only its `outputs/` come back to the workspace, and the run's outputs hold `snapshot.patch`, the change as a git patch, with `snapshot.json` saying what it touched or why there is none. Needs the k8s sandbox: `409` on an install without it, `404` for a snapshot not in this workspace) |
|
|
203
203
|
| `/api/workspaces/<ws>/agents/import` | GET, POST | copy an agent in from another workspace of the account. GET lists what could be imported (every other workspace you can read, with its agents). POST `{ from, agent, as? }` copies `agents/<agent>/` — its agent.md and own skills/, scripts/, knowledge/; never memory/, outputs/, state/ — and answers `{ name, files, warnings }`; `warnings` names tools, skills, scripts and secrets the copy uses that this workspace lacks. 409 on a name clash (pass `as`), 404 for an unknown workspace or agent, 403 when `from` is outside your key's scope. Idempotent |
|
|
204
204
|
| `/api/workspaces/<ws>/proposals` | GET | the workspace's proposed fixes, newest first (`404` when the workspace does not exist): `{ proposals: [{ id, workspace, eval, by (auto, or who asked), createdAt, updatedAt, status, failures: [{ runId?, case?, check, detail, at }], jobId, reply (the assistant's reasoning), files: [{ path, content, before, sha256 }], issues: [{ where, message, level }], error?, notes?, decidedBy?, decidedAt?, applied? }] }`. `status` is `drafting`, `ready`, `failed`, `applying`, `applied`, `partial` (a write failed part-way; `applied` names what was written) or `dismissed`. `?status=`, `?eval=`. A drafting one is settled as it is read |
|
|
205
205
|
| `/api/workspaces/<ws>/proposals/<id>` | GET, POST | one proposal. `POST { action: "apply" }` writes its files, each a revision by the caller, only when every one still reads what it was drawn against (`409` naming the file that changed) and can be written (`422`; a check error the deploy would refuse is `422` too); `POST { action: "dismiss" }` sets it aside — its failures stay looked at. Only agents, flows and skills are ever in one. Needs `workspace:write` |
|
|
@@ -224,7 +224,7 @@ paying for the steps around it.
|
|
|
224
224
|
|
|
225
225
|
| Route | Methods | |
|
|
226
226
|
|---|---|---|
|
|
227
|
-
| `/api/workspaces/<ws>/runs?limit=&before=` | GET | `{ runs: [{ id, flow, status, verdict, outcome, startedAt, finishedAt, ... }], next }`, newest first; `next` is the cursor for the page after (`<startedAt>~<runId>`, null on the last page) — pass it back as `before`, which also takes a time (runs that started before it) or a run id of the workspace (runs older than it); a position, not an offset, so runs starting meanwhile shift nothing and one cursor pages every workspace (`foldrun runs --before`, `--page`, `--all`); a `before` that is none of these is a `400`; search (see [Runs](runs#searching-runs)) with `tool` (a step called a tool whose name contains it), `tool_error=1`, `agent`, `model` (contains), `min_tokens` (`50k`), `min_secs` — `limit` counts the matches — `verdict` is the word the summary leads with (`GOOD`, `QUIET`, `BLOCKED`, `BAD` or null) and `outcome` the one word every page shows (`running`, `queued`, `waiting`, `good`, `done`, `quiet`, `blocked`, `bad`, `failed`, `stopped`); `failure` is why a run failed (null otherwise) — `{ agent, reason, class, kind, message, fix }` and, for a limit, `used`, `allowed`, `unit` and `scope`, for a refused site `host` (see [Runs](runs#why-it-failed)), `chargedUsd` is what the account was charged for the run (one credit is one cent), null until the ledger settles it, while `costUsd` is the provider's token cost — off the run index (see [Runs](runs#the-runs-list)); a finished run's steps carry `agent`, `status`, `costUsd` and `tokens` (`{ input, output, cacheRead, cacheWrite }`, see [Runs](runs#the-record)), and the run its summed `tokens` — not their reply or trace |
|
|
227
|
+
| `/api/workspaces/<ws>/runs?limit=&before=` | GET | `{ runs: [{ id, flow, status, verdict, outcome, startedAt, finishedAt, ... }], next }`, newest first; `next` is the cursor for the page after (`<startedAt>~<runId>`, null on the last page) — pass it back as `before`, which also takes a time (runs that started before it) or a run id of the workspace (runs older than it); a position, not an offset, so runs starting meanwhile shift nothing and one cursor pages every workspace (`foldrun runs --before`, `--page`, `--all`); a `before` that is none of these is a `400`; search (see [Runs](runs#searching-runs)) with `tool` (a step called a tool whose name contains it), `tool_error=1`, `agent`, `model` (contains), `min_tokens` (`50k`), `min_secs`, `context` (one [conversation](runs#conversations)'s runs, its id exactly; each run in it carries `context: { id, key, a2a? }`) — `limit` counts the matches — `verdict` is the word the summary leads with (`GOOD`, `QUIET`, `BLOCKED`, `BAD` or null) and `outcome` the one word every page shows (`running`, `queued`, `waiting`, `good`, `done`, `quiet`, `blocked`, `bad`, `failed`, `stopped`); `failure` is why a run failed (null otherwise) — `{ agent, reason, class, kind, message, fix }` and, for a limit, `used`, `allowed`, `unit` and `scope`, for a refused site `host` (see [Runs](runs#why-it-failed)), `chargedUsd` is what the account was charged for the run (one credit is one cent), null until the ledger settles it, while `costUsd` is the provider's token cost — off the run index (see [Runs](runs#the-runs-list)); a finished run's steps carry `agent`, `status`, `costUsd` and `tokens` (`{ input, output, cacheRead, cacheWrite }`, see [Runs](runs#the-record)), and the run its summed `tokens` — not their reply or trace |
|
|
228
228
|
| `/api/workspaces/<ws>/runs/<id>/calls/<call>` | GET | one tool call's recorded content (see [Runs](runs#what-a-run-records)): `{ call: { id, tool, input, output, inputChars, outputChars, truncated, inputCut, outputCut } }` — what it was given and what it gave back, secrets masked, each at most 65,536 characters; `inputChars`/`outputChars` are the whole length, `inputCut`/`outputCut` say which part was cut (`truncated`: either). `<call>` is the tool event's `call`; an event with `captured: true` has content here. 404 when nothing was recorded: the workspace says `capture: metadata`, or the run is from before 19 Oct 2026. A run's steps also carry `calls`, each model call (`n`, `at`, `ms`, `model`, `stop`, `tokens`, `tools`, and `subagent` / `attempt` when a sub-agent or a later attempt made it); a step that handed jobs to `sandbox: own` sub-agents carries `delegations` (`id`, `agent`, `status`, `costUsd`, `ms`), and each job is a step of its own with `subagentOf` (the delegating agent), `delegation` (that `id`) and `wrote` (the workspace paths it changed — copied into the delegating step's sandbox too, up to 4 MiB a job); and the run its `revision` (the workspace's latest revision when a worker picked it up — a deploy's commit, or the id an edit through `/source` was saved as) and `drivenAt` (when that was) |
|
|
229
229
|
| `/api/workspaces/<ws>/runs/<id>/trace` | GET | the run as one tree (see [Runs](runs#the-trace-tree)): `{ tree, failure }`. Each span is `{ id, kind, label, start, end, status, children, … }`, where `kind` is `run`, `step`, `model` (one model call: `model`, `stop`, `tokens`), `tool` (`call`, `captured` when its input and output were recorded) or `error` (`text`); `start`/`end` are epoch milliseconds and `status` is `ok`, `error`, `running`, `waiting`, `skipped` or `pending`. A tool call sits under the model call that asked for it. `failure` is the ids from the root to the first thing that went wrong, which the run page opens on; `[]` when nothing did |
|
|
230
230
|
| `/api/workspaces/<ws>/runs/<id>/compare?with=` | GET | this run beside another of the same flow (see [Runs](runs#compare-with-the-last-good-run)): `{ comparison: { base, run, revisionChanged, changedFiles, steps }, chosen }`. Each step is `{ step, agent, base, run, changes }`: both sides' status, instruction, model, seconds, tokens, model calls, tool counts, tool errors, first errors and first line said, and `changes` in words (`status: completed → failed`, `new error: …`, `instruction changed`, `tools: +web ×3`, `took 12s → 48s`, …). `changedFiles` lists the files changed between the revisions the two ran (null when one is unknown). `with` names the other run; unasked it is the newest earlier run of the flow that finished well, else the run this one re-ran (`chosen` says which) |
|
|
@@ -572,7 +572,7 @@ with `HTTP <status>: <the route's error>`.
|
|
|
572
572
|
|
|
573
573
|
| Route | Methods | |
|
|
574
574
|
|---|---|---|
|
|
575
|
-
| `/api/mcp` | POST | one JSON-RPC message: `initialize` (revisions `2025-11-25`, `2025-06-18`, `2025-03-26`; an unknown one is answered with the newest), `ping`, `tools/list`, `tools/call`; a notification is `202` with no body. `?readonly=1` offers only the tools that read and refuses the rest (`-32602`). The tools: `whoami`, `list_workspaces`, `inbox`, `list_approvals`, `list_flows`, `list_agents`, `list_runs`, `get_run`, `read_file`, `run_flow`, `run_agent`, `decide_approval`, `answer_question`, `message_run`, `stop_run` — see [MCP](mcp#the-tools). `foldrun mcp` serves the same over stdio |
|
|
575
|
+
| `/api/mcp` | POST | one JSON-RPC message: `initialize` (revisions `2025-11-25`, `2025-06-18`, `2025-03-26`; an unknown one is answered with the newest), `ping`, `tools/list`, `tools/call`; a notification is `202` with no body. `?readonly=1` offers only the tools that read and refuses the rest (`-32602`). The tools: `whoami`, `list_workspaces`, `inbox`, `list_approvals`, `list_flows`, `list_agents`, `list_runs`, `get_run`, `read_file`, `check_workspace`, `run_flow`, `run_agent`, `decide_approval`, `answer_question`, `message_run`, `stop_run`, `create_workspace`, `write_file`, `delete_file` — see [MCP](mcp#the-tools). `foldrun mcp` serves the same over stdio |
|
|
576
576
|
| `/api/mcp/oauth/register` | POST | an AI app registers itself (RFC 7591), before anyone signs it in. Open, as the protocol needs — no key. `{ redirect_uris, client_name?, token_endpoint_auth_method?, grant_types?, response_types?, client_uri? }`: one to ten redirect URIs, each `https` or `http` to localhost, no fragment; `token_endpoint_auth_method` `none` (PKCE alone), `client_secret_post` or `client_secret_basic` (the default). Answers `201 { client_id, client_id_issued_at, client_name, redirect_uris, grant_types, response_types, token_endpoint_auth_method, client_secret?, client_secret_expires_at? }` — the secret only for the two secret methods, shown once. Errors are OAuth's `{ error, error_description }` (`invalid_redirect_uri`, `invalid_client_metadata`); `503` past 5,000 apps on the install An app may register `token_endpoint_auth_method: private_key_jwt` with `jwks` (`{ keys: [...] }`, public keys only) or an https `jwks_uri`; it gets no secret and signs a client assertion at the token and revocation endpoints (RFC 7523: `iss` = `sub` = its client id, `aud` the issuer or the endpoint, at most five minutes, each `jti` once).|
|
|
577
577
|
| `/api/mcp/oauth/authorize` | GET, POST | the person's half of the sign-in, for the page at `/mcp/authorize` — a signed-in person only, never a key or a support view. GET `?request=<the app's query>` checks it and answers `{ client: { name, id, kind, uri }, redirectHost, loopback, scopes, account, person: { email, role }, workspaces, allWorkspaces }`; POST `{ request, decision: approve\|deny, access?: read\|write, workspaces?: [names] \| null }` answers `{ ok, redirect }` — the app's redirect URI with a one-time `code` (ten minutes), `state` and `iss`, or with `error=access_denied`. A request that names an unknown app or a redirect URI it did not register is `400` and never redirected; the rest of its faults (no PKCE `S256` challenge, a `resource` that is not this `/api/mcp`, an unknown scope) come back as `{ redirect }` with OAuth's error. `access: write` needs the app to have asked for `mcp:write`; `workspaces` must be ones the person may open (`403` otherwise) |
|
|
578
578
|
| `/api/mcp/oauth/token` | POST | OAuth 2.1's token endpoint, form-encoded (JSON is read too), no key: `grant_type=authorization_code` with `code`, `redirect_uri`, `code_verifier` (PKCE S256) and `client_id` — or the app's secret, Basic or in the form —, or `grant_type=refresh_token` with `refresh_token`. `resource`, when sent, must be this `/api/mcp`. Answers `{ access_token, token_type: "Bearer", expires_in: 3600, refresh_token, scope }` with `Cache-Control: no-store`. A code is good once, right or wrong. A refresh token is rotated on use; one used twice revokes the whole connection. Errors: `400 invalid_grant` / `invalid_target` / `unsupported_grant_type`, `401 invalid_client` |
|
package/docs/cli.md
CHANGED
|
@@ -90,9 +90,9 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
90
90
|
| `foldrun promote <run-id>` | keep a finished run as a regression case: its task and what the next run must still say go into `evals/<target>-regressions.md` (or `--eval <name>`), appended when the file exists. `--expect "contains: $34"` — repeatable, eval syntax — replaces the default judge line that holds the next run to the recorded conclusion; `--case <name>` names the case. A run that went wrong (failed, BLOCKED, BAD) takes `--should "what it should have done"` — the judge's claim — or `--expect` |
|
|
91
91
|
| `foldrun probe <model>` | can this model hold a tool loop here? A live check |
|
|
92
92
|
| `foldrun logs [run-id]` | recent runs in one workspace, or one run's whole event trail. `--follow` tails a live run: on a platform it reads the run's server-sent events (`GET …/runs/<id>/stream`, what the dashboard's run page reads — `invoke --watch` and `agent run --wait` too), reconnecting up to three times if the stream goes quiet; a run on this machine is read from its file. `--local` reads this machine's store even when signed in; `foldrun runs --local` is the same command and prints the same thing |
|
|
93
|
-
| `foldrun runs` | what has run lately across the whole account: when, workspace, flow, status, steps done, how long, the credits it was charged (its token cost in dollars until the ledger settles it) and the run's own one-line summary — or, for a failed run, why it failed: `✗ agent: ` and the sentence every surface gives ([why it failed](runs#why-it-failed)). A completed run shows its verdict beside the status — `GOOD`, `BAD`, `QUIET`, or `BLOCKED` in red with a ⛔ mark. `--status failed`, `--verdict blocked`, search by what happened inside (`--tool web`, `--tool-error`, `--agent`, `--model haiku`, `--min-tokens 50k`, `--min-secs 120`, or `--view <name>` for a saved one — `foldrun runs views` lists yours), `--outcome blocked,failed` (the dashboard's word; `needs-you` is `waiting`), `--since 24h`, `--to <workspace>`, `--flow <name>` (that flow's runs, or a direct agent run's or an eval's name), `--q <words>` (the runs page's text search: every word, any order, across id, flow, workspace, status, verdict, summary and failure), `--limit <n>` (20 by default) is one page: when more match it prints the next page's cursor — `--before <cursor>` shows that page (a time or a run id works too), `--page <n>` the nth page of `--limit`, `--all` every run that matches; `--json` prints `{ runs, next }`. `--local` prints exactly what `logs --local` prints — this machine's runs, one workspace |
|
|
93
|
+
| `foldrun runs` | what has run lately across the whole account: when, workspace, flow, status, steps done, how long, the credits it was charged (its token cost in dollars until the ledger settles it) and the run's own one-line summary — or, for a failed run, why it failed: `✗ agent: ` and the sentence every surface gives ([why it failed](runs#why-it-failed)). A completed run shows its verdict beside the status — `GOOD`, `BAD`, `QUIET`, or `BLOCKED` in red with a ⛔ mark. `--status failed`, `--verdict blocked`, search by what happened inside (`--tool web`, `--tool-error`, `--agent`, `--model haiku`, `--min-tokens 50k`, `--min-secs 120`, `--context <id>` (one [conversation](runs#conversations)'s runs), or `--view <name>` for a saved one — `foldrun runs views` lists yours), `--outcome blocked,failed` (the dashboard's word; `needs-you` is `waiting`), `--since 24h`, `--to <workspace>`, `--flow <name>` (that flow's runs, or a direct agent run's or an eval's name), `--q <words>` (the runs page's text search: every word, any order, across id, flow, workspace, status, verdict, summary and failure), `--limit <n>` (20 by default) is one page: when more match it prints the next page's cursor — `--before <cursor>` shows that page (a time or a run id works too), `--page <n>` the nth page of `--limit`, `--all` every run that matches; `--json` prints `{ runs, next }`. `--local` prints exactly what `logs --local` prints — this machine's runs, one workspace |
|
|
94
94
|
| `foldrun runs outputs <run-id>` | which files the run archived from its agents' `outputs/` — the run page's **Out** column: each agent's files with their sizes, and the `foldrun report <run-id> get <agent>/<path>` that downloads one. `--to <workspace>` names the run's workspace (else it is found); `--json` prints `{ runId, files: [{ agent, path, bytes, href }], totalBytes }`. `GET /api/workspaces/<ws>/runs/<id>/files` |
|
|
95
|
-
| `foldrun runs views save <name>` · `foldrun runs views rm <name>` | the runs page's **save view**: `save` keeps the filters given (`--status`, `--flow`, `--to`, `--since`, `--q`, `--tool`, `--tool-error`, `--agent`, `--model`, `--min-tokens`, `--min-secs`; `--since 24h` is kept as the dashboard's `today`) under that name, replacing a view of the same name; `rm` deletes one (asks; `--yes`). `PATCH /api/me/preferences` `{ runViews }` — the whole list, at most 20. `--json` prints the list after |
|
|
95
|
+
| `foldrun runs views save <name>` · `foldrun runs views rm <name>` | the runs page's **save view**: `save` keeps the filters given (`--status`, `--flow`, `--to`, `--since`, `--q`, `--tool`, `--tool-error`, `--agent`, `--model`, `--min-tokens`, `--min-secs`, `--context`; `--since 24h` is kept as the dashboard's `today`) under that name, replacing a view of the same name; `rm` deletes one (asks; `--yes`). `PATCH /api/me/preferences` `{ runViews }` — the whole list, at most 20. `--json` prints the list after |
|
|
96
96
|
| `foldrun runs doctor <run-id>` | the run doctor: the assistant reads a failed run and the files it names, says why (platform, check, work or outside), and proposes the fix as diffs, saved on yes — the run page's **Doctor** (`--to`, `--yes`, `--dry-run`, `--json`). Charged like one assistant reply |
|
|
97
97
|
| `foldrun runs rm <run-id>` | erase a run from history: its record and its archived outputs. A run still in flight is stopped first. The ledger line stays — money is not deleted because a trace was. Needs an admin (`workspace:manage`). Asks first; `--yes` with no terminal. Several ids (`runs rm <id> <id>…`) are the runs list's **Delete** on a selection, through the same route (`POST …/runs/bulk` `{ action: "delete" }`, one call per workspace): it lists them, asks once, then deletes them — each run its own outcome, so one refused does not stop the rest, and it exits 1 |
|
|
98
98
|
| `foldrun runs rm --until <30d\|date>` | delete every **finished** run that started before then — its record, captured calls and archived outputs — in every workspace, or one with `--to` ([how long a run is kept](runs#how-long-a-run-is-kept)). Counts what would go, asks once (`--yes` with no terminal; `--dry-run` only counts), then deletes 100 at a time until none match (`POST …/runs/bulk { action: "delete", until }`). Runs still going are left alone; the ledger lines stay. Needs an admin (`workspace:manage`) |
|
|
@@ -233,6 +233,8 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
233
233
|
| `--task "<text>"` | the instruction for a manual run |
|
|
234
234
|
| `--no-task` | `agent run`: start it with no instruction — the agent works from its own prompt alone |
|
|
235
235
|
| `--task "<text>"` | `flow inputs save`: the task the saved set holds |
|
|
236
|
+
| `--file <path>` | `invoke`, `agent run`: a file handed to the run — repeatable; a storage path, or a local one (`./`, `../`, `/`, `~`) uploaded to `storage/inputs/<upload id>/` first. The first step finds them in `inputs/` ([inputs](runs#inputs)) |
|
|
237
|
+
| `--context <id>` | `invoke`, `agent run`: a turn of that [conversation](runs#conversations) — the first step reads the earlier runs started with the same context (any id you choose, 1–200 printable characters, no spaces); `runs`: only that conversation's runs |
|
|
236
238
|
| `--test` | `run`, `invoke`, `agent run`: a test run — every step runs, nothing outward happens, `state/` and `storage/` are left alone, and the run page lists what would have happened. See [Test runs](runs#test-runs) |
|
|
237
239
|
| `--follow` | `logs`: keep tailing a live run — locally, or on the platform with `--url` |
|
|
238
240
|
| `--status <s>` | `runs`, and a bulk `stop` or `rerun`: only these statuses, comma-separated — `failed`, `completed`, `awaiting-approval`, `running`, `queued` |
|
|
@@ -279,7 +281,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
279
281
|
| `--payload <json\|text\|@file>` | `approve`: release a step waiting on `wait: event` with this body (`POST …/approve` `{ payload }`). JSON is sent as JSON, anything else as text; `@file` reads a file |
|
|
280
282
|
| `--event-wait` | `reject`: refuse a step waiting on `wait: event` rather than a person's gate |
|
|
281
283
|
| `--note "<text>"` | `approve`: guidance the approved step reads in its prompt — "approve, but skip the Sydney batch". `reject`: the reason, recorded on the trace |
|
|
282
|
-
| `--read-only` | `mcp`: offer the AI app only the tools that read — no `run_flow`, `run_agent`, `decide_approval`, `answer_question`, `message_run` or `
|
|
284
|
+
| `--read-only` | `mcp`: offer the AI app only the tools that read — no `run_flow`, `run_agent`, `decide_approval`, `answer_question`, `message_run`, `stop_run`, `create_workspace`, `write_file` or `delete_file` |
|
|
283
285
|
| `--yes` | skip the confirmation, deliberately: `approve`, `stop`, `deploy` (when it would delete files), and a bulk `stop` or `rerun`, `flow rotate-hook`, `flow draft`, `assistant`, `mcp disconnect`, `a2a cancel`, `history restore`, `restore`, `billing plan`, `repo deploy`/`merge`, `workspace set name`, and every delete — `runs rm`, `storage rm`, `storage unshare`, `source rm`, `secrets rm`, `keys revoke`, `workspaces rm`. Required when there is no terminal to ask; without it nothing is deleted |
|
|
284
286
|
| `--json` | `report`: the raw run record instead of the report. `observe`, `usage`, `workspaces`, `workspaces show`, `agent ls`, `flow ls`, `agent import --list`, `assistant`, `backups requests`, `status --platform --history`, `signup status`, `team`, `secrets ls`, `triggers`, `storage ls --all`: the raw document |
|
|
285
287
|
| `--events <a,b>` | `account set notify`: which events are notified on — `failed`, `awaiting-approval`, `completed` |
|
package/docs/mcp.md
CHANGED
|
@@ -34,7 +34,8 @@ page says which app is asking, where the answer goes (`claude.ai`), and lets
|
|
|
34
34
|
you choose:
|
|
35
35
|
|
|
36
36
|
- **what it may do** — read only (inbox, runs, flows, files), or read and act
|
|
37
|
-
(also start and stop runs, approve gates, answer and message agents
|
|
37
|
+
(also start and stop runs, approve gates, answer and message agents, and
|
|
38
|
+
create workspaces and write or delete their files);
|
|
38
39
|
- **which workspaces** — every one you may open, or the ones you tick.
|
|
39
40
|
|
|
40
41
|
**Connect** sends you back to claude.ai, connected; **Deny** sends it a no.
|
|
@@ -134,17 +135,45 @@ and that automatic disconnect are in the audit log (`mcp.connected`,
|
|
|
134
135
|
| `list_agents` | a workspace's agents: what each is for and when it last ran | `GET …/agents` |
|
|
135
136
|
| `list_runs` | recent runs, with outcome, summary and failure (`limit` up to 100, default 20; `flow` keeps that flow's among the newest 500) | `GET …/runs` |
|
|
136
137
|
| `get_run` | one run in full | `GET …/runs/<id>` |
|
|
137
|
-
| `read_file` | one file of a workspace's source, or the tree | `GET …/source` |
|
|
138
|
-
| `
|
|
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), `inputs` for [files](runs#inputs)) | `POST …/flows/<flow>/run` |
|
|
141
|
+
| `run_agent` | run one agent on a task of your own, in its own sandbox, no flow needed (`task`, `test: true` for a [test run](runs#test-runs), `context` for a turn of a [conversation](runs#conversations), `inputs` for [files](runs#inputs)); answers a run id at once — read it with `get_run` | `POST …/agents/<agent>/run` |
|
|
140
142
|
| `decide_approval` | approve or reject a gate (`note`, `step`) | `POST …/runs/<id>/approve` |
|
|
141
143
|
| `answer_question` | answer an agent's question mid-step | `POST …/runs/<id>/answer` |
|
|
142
144
|
| `message_run` | say something to a running agent | `POST …/runs/<id>/message` |
|
|
143
145
|
| `stop_run` | stop a run | `POST …/runs/<id>/stop` |
|
|
144
|
-
|
|
145
|
-
|
|
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/providers.md
CHANGED
|
@@ -195,6 +195,26 @@ those families on both wires and says so in the drop line. Every other id
|
|
|
195
195
|
keeps it, because a gateway ignores a field it cannot use and an o-series,
|
|
196
196
|
gpt-5, grok or deepseek-r model wants it.
|
|
197
197
|
|
|
198
|
+
### Images and PDFs an agent reads
|
|
199
|
+
|
|
200
|
+
An agent that reads an image or a PDF with its Read tool — a run's
|
|
201
|
+
[inputs](runs#inputs), a screenshot it took — gets it back as an image or a
|
|
202
|
+
document block. On an Anthropic endpoint the model sees it as it is. Through
|
|
203
|
+
the translator:
|
|
204
|
+
|
|
205
|
+
| | Chat Completions (`format: openai`) | Responses (`format: responses`) |
|
|
206
|
+
|---|---|---|
|
|
207
|
+
| an image a tool returned | sent in a user message right after the tool results, labelled with the call it came from (a tool message carries text alone) | carried in the tool output |
|
|
208
|
+
| a PDF a tool returned | not sent — no portable Chat part takes one | carried as an `input_file` |
|
|
209
|
+
| an image or PDF in the message itself | images sent; PDFs not | both sent |
|
|
210
|
+
|
|
211
|
+
Wherever a file is not sent, the model is told so in its place — "a PDF was
|
|
212
|
+
here, but this model endpoint cannot be shown PDFs" — so it never answers as
|
|
213
|
+
though it had seen it, and the run trace says what was left out. To give a
|
|
214
|
+
model on Chat Completions a PDF's text, read it with a script. Whether a given
|
|
215
|
+
model can see images at all is the provider's; one that cannot refuses or
|
|
216
|
+
ignores the image.
|
|
217
|
+
|
|
198
218
|
### Persian prompts, by tier (checked 11 Nov 2026)
|
|
199
219
|
|
|
200
220
|
An eval of eight Persian tasks, compared on the three tiers with **Compare
|
package/docs/runs.md
CHANGED
|
@@ -277,12 +277,13 @@ never holds a run up: a failed send is logged on the platform, not retried.
|
|
|
277
277
|
The runs pages search by what happened inside a run, not only its status:
|
|
278
278
|
**tool** (a step called a tool whose name contains it — `web`, `crm`), **a
|
|
279
279
|
tool errored**, **agent**, **model** (contains — `haiku`), **≥ tokens** (input
|
|
280
|
-
read by all its steps, `50k`)
|
|
280
|
+
read by all its steps, `50k`), **≥ secs** and **conversation** (a
|
|
281
|
+
[context](#conversations), exactly). A search can be kept as a named
|
|
281
282
|
**view** (save view), yours on every browser; the views sit beside the search.
|
|
282
283
|
`foldrun runs --tool web --tool-error`, `--agent`, `--model`, `--min-tokens`,
|
|
283
|
-
`--min-secs` and `--view <name>` do the same (`foldrun runs views` lists
|
|
284
|
+
`--min-secs`, `--context` and `--view <name>` do the same (`foldrun runs views` lists
|
|
284
285
|
yours), and `GET …/runs` takes `tool`, `tool_error`, `agent`, `model`,
|
|
285
|
-
`min_tokens`, `min_secs`. Tools and models are searchable on runs from
|
|
286
|
+
`min_tokens`, `min_secs`, `context`. Tools and models are searchable on runs from
|
|
286
287
|
19 Oct 2026; tokens and time on every run.
|
|
287
288
|
|
|
288
289
|
## Insights
|
|
@@ -534,6 +535,91 @@ it to `storage/` — a tool that takes an `out=` path and tees its own output
|
|
|
534
535
|
is the reliable way, because a model asked to copy a long report by hand
|
|
535
536
|
shortens it.
|
|
536
537
|
|
|
538
|
+
## Conversations
|
|
539
|
+
|
|
540
|
+
A run may name a **context**: any id you choose, 1–200 printable ASCII
|
|
541
|
+
characters with no spaces (`order-42`, `ticket:8812`). A run in the same
|
|
542
|
+
context is given the earlier runs of that context before its task — what
|
|
543
|
+
each was asked and what it answered — so a follow-up like "and the same for
|
|
544
|
+
April" means something. It is not a chat screen: the chat stays in your app,
|
|
545
|
+
and foldrun keeps the turns.
|
|
546
|
+
|
|
547
|
+
```sh
|
|
548
|
+
foldrun agent run analyst --to sales --task "how many orders in March?" --context order-42
|
|
549
|
+
foldrun agent run analyst --to sales --task "and April?" --context order-42
|
|
550
|
+
```
|
|
551
|
+
|
|
552
|
+
The API takes the same field: `context` on `POST …/agents/<agent>/run` and
|
|
553
|
+
`POST …/flows/<flow>/run` (not with `from`), and on MCP's `run_agent` and
|
|
554
|
+
`run_flow`. Over [A2A](a2a), a task's `contextId` is its context.
|
|
555
|
+
|
|
556
|
+
**What counts as an earlier turn:** a run of the same workspace and context,
|
|
557
|
+
completed or failed, that had finished before this run was started. A test
|
|
558
|
+
run reads only test runs, and a real run only real ones. The cutoff is fixed
|
|
559
|
+
when the run is made, so a retry, a park at a gate or a rescue reads the same
|
|
560
|
+
turns. A failed turn is shown as failed, with the one-line reason.
|
|
561
|
+
|
|
562
|
+
**What the model reads:** each turn's question as it was asked (the task, not
|
|
563
|
+
the flow's own instruction around it) and its answer — the last step's final
|
|
564
|
+
reply. They go in the user message of the step the task reaches, before the
|
|
565
|
+
task, marked as a record of past turns: data, not instructions. Later steps
|
|
566
|
+
get the usual [handoff](#handoffs) from the steps before them. A re-run stays
|
|
567
|
+
in the conversation, and the first step it runs reads it.
|
|
568
|
+
|
|
569
|
+
**How much:** the newest turns first, up to 20 runs and 32,000 characters in
|
|
570
|
+
all; a question is cut at 2,000 characters and an answer at 6,000. Older turns
|
|
571
|
+
that do not fit are left out. The step's trail says what it was given:
|
|
572
|
+
`conversation order-42: given 3 earlier runs (4,210 characters)`.
|
|
573
|
+
|
|
574
|
+
**Who shares a context:** runs started through the API, the dashboard, the
|
|
575
|
+
CLI or MCP share the workspace's contexts, so anyone who can start runs there
|
|
576
|
+
can continue one — and could read those runs anyway. A context is a way to
|
|
577
|
+
group runs, not a lock. Each outside caller over A2A has its own: two A2A keys
|
|
578
|
+
that send the same `contextId` never see each other's turns, and an A2A
|
|
579
|
+
caller's history holds only what that caller was answered.
|
|
580
|
+
|
|
581
|
+
The run page shows a run's **Conversation**, linked to the runs list filtered
|
|
582
|
+
to it; `foldrun runs --context order-42` and `GET …/runs?context=order-42`
|
|
583
|
+
list them.
|
|
584
|
+
|
|
585
|
+
## Inputs
|
|
586
|
+
|
|
587
|
+
A run may be handed **files**: storage paths, as the workspace's storage lists
|
|
588
|
+
them. The step the task reaches finds them at `inputs/` in its working
|
|
589
|
+
directory, under the same paths (`inputs/reports/q4.pdf`), and is told which
|
|
590
|
+
they are. An agent reads them with its Read tool; images and PDFs are shown to
|
|
591
|
+
the model as they are, where the model can be shown them (see
|
|
592
|
+
[images and PDFs](providers#images-and-pdfs-an-agent-reads)). Scripts can read
|
|
593
|
+
every file.
|
|
594
|
+
|
|
595
|
+
```sh
|
|
596
|
+
foldrun storage put brief.pdf --to sales --into briefs/
|
|
597
|
+
foldrun agent run analyst --to sales --task "summarise the brief" --file briefs/brief.pdf
|
|
598
|
+
foldrun agent run analyst --to sales --task "what changed?" --file ./local/v2.pdf
|
|
599
|
+
```
|
|
600
|
+
|
|
601
|
+
A `--file` written as a local path (`./`, `../`, `/` or `~`) is uploaded to
|
|
602
|
+
`storage/inputs/<upload id>/` first; anything else is a storage path. The API
|
|
603
|
+
takes `inputs: ["briefs/brief.pdf"]` on `POST …/agents/<agent>/run` and
|
|
604
|
+
`POST …/flows/<flow>/run` (not with `from`), and so do MCP's `run_agent` and
|
|
605
|
+
`run_flow`. In the dashboard, **Run with…** on a flow has a **Files** list.
|
|
606
|
+
|
|
607
|
+
- **Fixed when the run is made.** The run holds the bytes each path named
|
|
608
|
+
then. Overwriting or deleting the storage file afterwards changes nothing
|
|
609
|
+
it reads, and a re-run reads the same files. The run page's **Inputs**
|
|
610
|
+
panel links to the copy the run held. Holding costs no extra space: the
|
|
611
|
+
same bytes are stored once.
|
|
612
|
+
- **Never copied back.** Whatever the step writes inside `inputs/` stays in
|
|
613
|
+
its sandbox. Put results in `outputs/` or `workspace/storage/`.
|
|
614
|
+
- **Limits:** at most 20 files and 100 MiB on one run — foldrun's limits.
|
|
615
|
+
What a model can be shown at once is the provider's: an image or a PDF
|
|
616
|
+
past its limits is still staged for scripts to read.
|
|
617
|
+
- **Where:** the sandboxed executors stage inputs (k8s and `container`). An
|
|
618
|
+
install that runs steps in-process answers `409`, as it does for a
|
|
619
|
+
snapshot.
|
|
620
|
+
- **Released with the run.** Deleting a run, or the retention window
|
|
621
|
+
pruning it, lets its held copies go.
|
|
622
|
+
|
|
537
623
|
## What a run costs, and what stops it
|
|
538
624
|
|
|
539
625
|
Every step records what it cost. A flow's `budget:` is checked between
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "foldrun",
|
|
3
|
-
"version": "20.
|
|
3
|
+
"version": "20.11.0",
|
|
4
4
|
"description": "Agents are just folders. Write them, check them, run them — on your machine.",
|
|
5
5
|
"license": "FSL-1.1-ALv2",
|
|
6
6
|
"type": "module",
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
"node": ">=22"
|
|
12
12
|
},
|
|
13
13
|
"dependencies": {
|
|
14
|
-
"@foldrun/core": "^18.
|
|
14
|
+
"@foldrun/core": "^18.5.0"
|
|
15
15
|
},
|
|
16
16
|
"files": [
|
|
17
17
|
"bin",
|
package/src/commands.mjs
CHANGED
|
@@ -3976,6 +3976,8 @@ async function invoke(target, flags) {
|
|
|
3976
3976
|
// "Run with…" reads and writes, as the platform has it.
|
|
3977
3977
|
const task = typeof flags.inputs === "string" ? await savedInputs(url, flags, ws, target, flags.inputs) : typeof flags.task === "string" ? flags.task : "";
|
|
3978
3978
|
if (flags.inputs !== undefined && typeof flags.inputs !== "string") throw new Error("which input set? `--inputs <name>`");
|
|
3979
|
+
if (flags.context !== undefined && typeof flags.context !== "string") throw new Error("which conversation? `--context <id>`");
|
|
3980
|
+
const files = await runInputs(url, flags, ws);
|
|
3979
3981
|
let body;
|
|
3980
3982
|
try {
|
|
3981
3983
|
body = await remoteCall(url, flags, `/api/workspaces/${ws}/flows/${target}/run${wait}`, {
|
|
@@ -3994,6 +3996,11 @@ async function invoke(target, flags) {
|
|
|
3994
3996
|
...(typeof flags.once === "string" && flags.once ? { idempotencyKey: flags.once } : {}),
|
|
3995
3997
|
// --tag a --tag b: labels on the run, as the API's `tags`.
|
|
3996
3998
|
...(many(flags.tag).length ? { tags: many(flags.tag) } : {}),
|
|
3999
|
+
// --context <id> (FOL-162): a turn of that conversation — the first
|
|
4000
|
+
// step reads the earlier runs started with the same context.
|
|
4001
|
+
...(typeof flags.context === "string" ? { context: flags.context } : {}),
|
|
4002
|
+
// --file (FOL-163): storage paths handed to the first step, in inputs/.
|
|
4003
|
+
...(files.length ? { inputs: files } : {}),
|
|
3997
4004
|
}),
|
|
3998
4005
|
});
|
|
3999
4006
|
} catch (err) {
|
|
@@ -4697,7 +4704,7 @@ async function doctor(flags) {
|
|
|
4697
4704
|
* keys create <label> --a2a --to <ws> --flows a,b [--max-tasks N] a key for an outside agent: /a2a only
|
|
4698
4705
|
* keys create <label> --gateway --cap <usd> [--daily <usd>] a coding agent's key (Claude Code): the gateway only
|
|
4699
4706
|
* keys create <label> --gateway --login on the operator's Claude login (its own accounts): not metered
|
|
4700
|
-
* keys create <label> --gateway --cap <usd> --claude-code …and write it into Claude Code's settings
|
|
4707
|
+
* keys create <label> --gateway --cap <usd> --claude-code …and write it into Claude Code's settings (its status line too)
|
|
4701
4708
|
* keys set <id> --opus|--sonnet|--haiku <provider/model> which model each Claude Code tier runs on (a gateway key; `-` clears one, --clear all)
|
|
4702
4709
|
* keys rotate <id> [--grace 1h] a new key, same label/role/scope; the old
|
|
4703
4710
|
* one ends now, or when the grace runs out.
|
|
@@ -4926,7 +4933,7 @@ async function keysCreateGateway(url, label, flags) {
|
|
|
4926
4933
|
// Written from the file as it is NOW, not as it was before the request,
|
|
4927
4934
|
// so a change made meanwhile is kept. A write that fails after the key
|
|
4928
4935
|
// exists says so and falls back to the lines to copy.
|
|
4929
|
-
/** @type {{ file: string, dropped: string[], backup: string | null } | null} */
|
|
4936
|
+
/** @type {{ file: string, dropped: string[], backup: string | null, statusLine: "added" | "kept" | "theirs" } | null} */
|
|
4930
4937
|
let done = null;
|
|
4931
4938
|
if (claude && made.gatewayUrl) {
|
|
4932
4939
|
try { done = writeClaudeSettings(readClaudeSettings(), made.gatewayUrl, made.key); }
|
|
@@ -4937,12 +4944,18 @@ async function keysCreateGateway(url, label, flags) {
|
|
|
4937
4944
|
console.log(` ${c.dim(`env: ANTHROPIC_BASE_URL=${made.gatewayUrl}, ANTHROPIC_AUTH_TOKEN=<this key>`)}`);
|
|
4938
4945
|
if (done.dropped.length) console.log(` ${c.dim(`removed from that env block: ${done.dropped.join(", ")} (it would have competed with the key)`)}`);
|
|
4939
4946
|
if (done.backup) console.log(` ${c.dim(`the file as it was: ${done.backup}`)}`);
|
|
4947
|
+
if (done.statusLine === "theirs") console.log(` ${c.dim(`your own statusLine was kept; for the key's spend there, run \`${STATUS_LINE_COMMAND}\` from it`)}`);
|
|
4948
|
+
else console.log(` ${c.dim(`statusLine: ${STATUS_LINE_COMMAND} — the key's spend under Claude Code's input box`)}`);
|
|
4940
4949
|
console.log(` ${c.dim("Start a new claude session; /status shows the gateway. Claude Desktop is set in its own Developer → Configure Third-Party Inference.")}\n`);
|
|
4941
4950
|
} else {
|
|
4942
4951
|
if (claude && !made.gatewayUrl) console.log(` ${c.yellow("This platform has no gateway URL yet, so Claude Code's settings were not written.")}\n`);
|
|
4943
4952
|
console.log(` ${c.dim("Shown once. Point Claude Code at it:")}\n`);
|
|
4953
|
+
// ANTHROPIC_AUTH_TOKEN, not ANTHROPIC_API_KEY: Claude Code asks about a
|
|
4954
|
+
// "custom API key" with No preselected, and No leaves the gateway unused.
|
|
4944
4955
|
console.log(` export ANTHROPIC_BASE_URL=${base}`);
|
|
4945
|
-
console.log(` export
|
|
4956
|
+
console.log(` export ANTHROPIC_AUTH_TOKEN=<key>\n`);
|
|
4957
|
+
console.log(` ${c.dim(`The key's spend under Claude Code's input box: add to ~/.claude/settings.json`)}`);
|
|
4958
|
+
console.log(` "statusLine": { "type": "command", "command": "${STATUS_LINE_COMMAND}" }\n`);
|
|
4946
4959
|
}
|
|
4947
4960
|
// A login key is not metered: there is no spend for `keys ls` to show.
|
|
4948
4961
|
const after = made.credential === "login"
|
|
@@ -5007,6 +5020,11 @@ function writeClaudeSettings({ file, text, settings }, baseUrl, key) {
|
|
|
5007
5020
|
env.ANTHROPIC_BASE_URL = baseUrl;
|
|
5008
5021
|
env.ANTHROPIC_AUTH_TOKEN = key;
|
|
5009
5022
|
const next = { ...settings, env };
|
|
5023
|
+
// The key's spend under Claude Code's input box — unless a status line of
|
|
5024
|
+
// the person's own is set, which is theirs and stays.
|
|
5025
|
+
/** @type {"added" | "kept" | "theirs"} */
|
|
5026
|
+
const statusLine = settings.statusLine === undefined ? "added" : settings.statusLine?.command === STATUS_LINE_COMMAND ? "kept" : "theirs";
|
|
5027
|
+
if (statusLine === "added") next.statusLine = { type: "command", command: STATUS_LINE_COMMAND };
|
|
5010
5028
|
fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
|
|
5011
5029
|
/** @type {string | null} */
|
|
5012
5030
|
let backup = null;
|
|
@@ -5019,7 +5037,66 @@ function writeClaudeSettings({ file, text, settings }, baseUrl, key) {
|
|
|
5019
5037
|
fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
|
|
5020
5038
|
fs.renameSync(tmp, file);
|
|
5021
5039
|
try { fs.chmodSync(file, 0o600); } catch { /* Windows: no modes */ }
|
|
5022
|
-
return { file, dropped, backup };
|
|
5040
|
+
return { file, dropped, backup, statusLine };
|
|
5041
|
+
}
|
|
5042
|
+
|
|
5043
|
+
/** Claude Code's status line, as `keys create --gateway --claude-code`
|
|
5044
|
+
* writes it: the key's spend, read from the gateway itself. */
|
|
5045
|
+
const STATUS_LINE_COMMAND = "foldrun gateway status-line";
|
|
5046
|
+
|
|
5047
|
+
/**
|
|
5048
|
+
* `foldrun gateway status-line` — one line for Claude Code's status line:
|
|
5049
|
+
* what the gateway key in this environment has spent against its limits,
|
|
5050
|
+
*
|
|
5051
|
+
* foldrun · $3.12 of $20.00 · today $1.10 of $5.00
|
|
5052
|
+
*
|
|
5053
|
+
* It reads ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN (or ANTHROPIC_API_KEY)
|
|
5054
|
+
* — the env Claude Code hands the status line — and asks the gateway's
|
|
5055
|
+
* GET /v1/usage, never the platform's API. Claude Code redraws the line
|
|
5056
|
+
* after every message, so an answer is kept 10 s on this machine. It always
|
|
5057
|
+
* prints one line and exits 0: a status line has no place for an error.
|
|
5058
|
+
*/
|
|
5059
|
+
async function gatewayCmd(positional, flags) {
|
|
5060
|
+
const sub = positional[0];
|
|
5061
|
+
if (sub !== "status-line") throw new Error("foldrun gateway status-line — the one line Claude Code's status line shows: the gateway key's spend and limits");
|
|
5062
|
+
// Claude Code sends the session as JSON on stdin; it is not needed here.
|
|
5063
|
+
if (!process.stdin.isTTY) process.stdin.resume().on("error", () => {});
|
|
5064
|
+
console.log(await gatewayStatusLine(process.env, flags));
|
|
5065
|
+
if (!process.stdin.isTTY) process.stdin.destroy();
|
|
5066
|
+
return 0;
|
|
5067
|
+
}
|
|
5068
|
+
|
|
5069
|
+
/** The line itself; exported for tests. */
|
|
5070
|
+
export async function gatewayStatusLine(env = process.env, flags = {}, now = Date.now()) {
|
|
5071
|
+
const base = (env.ANTHROPIC_BASE_URL ?? "").trim().replace(/\/+$/, "");
|
|
5072
|
+
const key = (env.ANTHROPIC_AUTH_TOKEN || env.ANTHROPIC_API_KEY || "").trim();
|
|
5073
|
+
if (!base) return "foldrun · no gateway set (ANTHROPIC_BASE_URL)";
|
|
5074
|
+
if (!key) return "foldrun · no key set (ANTHROPIC_AUTH_TOKEN)";
|
|
5075
|
+
// Kept per gateway and key, under a name that shows neither.
|
|
5076
|
+
const cacheFile = path.join(os.tmpdir(), `foldrun-status-${crypto.createHash("sha256").update(`${base}\n${key}`).digest("hex").slice(0, 24)}`);
|
|
5077
|
+
const ttl = typeof flags.cache === "string" && /^\d+$/.test(flags.cache) ? Number(flags.cache) * 1000 : 10_000;
|
|
5078
|
+
try {
|
|
5079
|
+
const st = fs.statSync(cacheFile);
|
|
5080
|
+
if (now - st.mtimeMs < ttl) return fs.readFileSync(cacheFile, "utf8");
|
|
5081
|
+
} catch { /* none yet */ }
|
|
5082
|
+
let line;
|
|
5083
|
+
try {
|
|
5084
|
+
const res = await fetch(`${base}/v1/usage?format=line`, { headers: { authorization: `Bearer ${key}` }, signal: AbortSignal.timeout(3000) });
|
|
5085
|
+
const text = await res.text();
|
|
5086
|
+
// The gateway's own line; anything else (a proxy's page, Anthropic's own
|
|
5087
|
+
// API) is not shown as if it were.
|
|
5088
|
+
const first = text.split("\n")[0] ?? "";
|
|
5089
|
+
line = /^foldrun · /.test(first) ? first : res.status === 404 ? "foldrun · this base URL is not a foldrun gateway" : `foldrun · usage not available (${res.status})`;
|
|
5090
|
+
} catch {
|
|
5091
|
+
line = "foldrun · gateway not reachable";
|
|
5092
|
+
}
|
|
5093
|
+
// Only printable text reaches the terminal, and not much of it.
|
|
5094
|
+
line = line.replace(/[\u0000-\u001f\u007f-\u009f]/g, "").slice(0, 160);
|
|
5095
|
+
try {
|
|
5096
|
+
fs.writeFileSync(`${cacheFile}.${process.pid}`, line, { mode: 0o600 });
|
|
5097
|
+
fs.renameSync(`${cacheFile}.${process.pid}`, cacheFile);
|
|
5098
|
+
} catch { /* the next draw asks again */ }
|
|
5099
|
+
return line;
|
|
5023
5100
|
}
|
|
5024
5101
|
|
|
5025
5102
|
/** A retried mint or rotate is answered from the first call, and the server
|
|
@@ -6399,11 +6476,6 @@ async function storageCmd(positional, flags, layout) {
|
|
|
6399
6476
|
jobs[0].rel = flags.as;
|
|
6400
6477
|
}
|
|
6401
6478
|
const token = await renewedToken(url, flags);
|
|
6402
|
-
const base = `/api/workspaces/${encodeURIComponent(ws)}/storage`;
|
|
6403
|
-
const said = async (res) => {
|
|
6404
|
-
const text = await res.text();
|
|
6405
|
-
try { return JSON.parse(text).error ?? text.slice(0, 200); } catch { return text.slice(0, 200); }
|
|
6406
|
-
};
|
|
6407
6479
|
let ok = 0, skipped = 0, bytesSent = 0;
|
|
6408
6480
|
const failed = [];
|
|
6409
6481
|
console.log();
|
|
@@ -6416,23 +6488,7 @@ async function storageCmd(positional, flags, layout) {
|
|
|
6416
6488
|
continue;
|
|
6417
6489
|
}
|
|
6418
6490
|
try {
|
|
6419
|
-
|
|
6420
|
-
// The length too: the platform checks the limits on it and signs it
|
|
6421
|
-
// into the URL, so the bucket takes exactly these bytes (30 Oct 2026).
|
|
6422
|
-
const ask = await remoteFetch(url, `${base}/upload-url`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ path: rel, sha, size: bytes.length }) }, { token });
|
|
6423
|
-
// A platform older than presigned uploads answers 404 here: it
|
|
6424
|
-
// takes the bytes itself, the way one with no bucket does.
|
|
6425
|
-
if (!ask.ok && ask.status !== 404) throw new HttpError(await said(ask), ask.status, {});
|
|
6426
|
-
const { url: direct } = /** @type {{ url?: string | null }} */ (ask.ok ? await ask.json() : { url: null });
|
|
6427
|
-
if (direct) {
|
|
6428
|
-
const put = await fetch(direct, { method: "PUT", body: bytes, signal: AbortSignal.timeout(Math.max(120, bytes.length / 200_000) * 1000) });
|
|
6429
|
-
if (!put.ok) throw new Error(`the storage service refused it (${put.status})`);
|
|
6430
|
-
const done = await remoteFetch(url, base, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ path: rel, sha, size: bytes.length }) }, { token });
|
|
6431
|
-
if (!done.ok) throw new HttpError(await said(done), done.status, {});
|
|
6432
|
-
} else {
|
|
6433
|
-
const put = await remoteFetch(url, `${base}?path=${encodeURIComponent(rel)}`, { method: "PUT", body: bytes, headers: { "content-type": "application/octet-stream" } }, { token });
|
|
6434
|
-
if (!put.ok) throw new HttpError(await said(put), put.status, {});
|
|
6435
|
-
}
|
|
6491
|
+
await uploadToStorage(url, token, ws, rel, bytes);
|
|
6436
6492
|
ok++;
|
|
6437
6493
|
bytesSent += bytes.length;
|
|
6438
6494
|
console.log(` ${c.green("✓")} ${ws}/storage/${rel} ${c.dim(humanBytes(bytes.length))}`);
|
|
@@ -7714,7 +7770,7 @@ async function runViewsCmd(flags) {
|
|
|
7714
7770
|
|
|
7715
7771
|
/** The filter flags a saved view keeps, as the runs page's query names them
|
|
7716
7772
|
* (run-views-model.ts VIEW_KEYS) — the reverse of what --view reads. */
|
|
7717
|
-
const VIEW_FLAGS = [["status", "status"], ["flow", "flow"], ["to", "workspace"], ["since", "since"], ["q", "q"], ["tool", "tool"], ["agent", "agent"], ["model", "model"], ["min-tokens", "min_tokens"], ["min-secs", "min_secs"]];
|
|
7773
|
+
const VIEW_FLAGS = [["status", "status"], ["flow", "flow"], ["to", "workspace"], ["since", "since"], ["q", "q"], ["tool", "tool"], ["agent", "agent"], ["model", "model"], ["min-tokens", "min_tokens"], ["min-secs", "min_secs"], ["context", "context"]];
|
|
7718
7774
|
|
|
7719
7775
|
/**
|
|
7720
7776
|
* `foldrun runs views save <name> [filters]` and `runs views rm <name>` — the
|
|
@@ -7732,13 +7788,13 @@ async function runViewsEditCmd([verb, ...rest], flags) {
|
|
|
7732
7788
|
if (verb === "save") {
|
|
7733
7789
|
if (name.length > 40) throw new Error("a view's name is 1 to 40 characters");
|
|
7734
7790
|
// Said, not dropped: the route would keep only the keys it knows.
|
|
7735
|
-
for (const f of ["verdict", "outcome"]) if (flags[f] !== undefined) throw new Error(`a saved view keeps --status, --flow, --to, --since, --q, --tool, --tool-error, --agent, --model, --min-tokens
|
|
7791
|
+
for (const f of ["verdict", "outcome"]) if (flags[f] !== undefined) throw new Error(`a saved view keeps --status, --flow, --to, --since, --q, --tool, --tool-error, --agent, --model, --min-tokens, --min-secs and --context — not --${f}`);
|
|
7736
7792
|
const query = new URLSearchParams();
|
|
7737
7793
|
for (const [flag, key] of VIEW_FLAGS) if (flags[flag] !== undefined && flags[flag] !== true) query.set(key, String(flags[flag]));
|
|
7738
7794
|
if (flags["tool-error"] === true) query.set("tool_error", "1");
|
|
7739
7795
|
// The dashboard's windows are today, 7d and 30d; its Today is 24 hours.
|
|
7740
7796
|
if (["24h", "1d"].includes(String(query.get("since")).trim().toLowerCase())) query.set("since", "today");
|
|
7741
|
-
if (!query.size) throw new Error("a view needs at least one filter — --status, --flow, --to, --since, --q, --tool, --tool-error, --agent, --model, --min-tokens
|
|
7797
|
+
if (!query.size) throw new Error("a view needs at least one filter — --status, --flow, --to, --since, --q, --tool, --tool-error, --agent, --model, --min-tokens, --min-secs or --context");
|
|
7742
7798
|
list = [...runViews.filter((v) => v.name !== name), { name, query: query.toString() }];
|
|
7743
7799
|
const since = query.get("since");
|
|
7744
7800
|
const d = await remoteCall(url, flags, "/api/me/preferences", { method: "PATCH", body: JSON.stringify({ runViews: list }) });
|
|
@@ -8352,6 +8408,68 @@ async function stopCmd(runId, flags, layout) {
|
|
|
8352
8408
|
* carries each run's one-line summary — the sentence that says what it
|
|
8353
8409
|
* found, not merely that it finished.
|
|
8354
8410
|
*/
|
|
8411
|
+
/**
|
|
8412
|
+
* Put one file's bytes into a workspace's storage at `rel`: straight to the
|
|
8413
|
+
* bucket when the platform hands out an upload URL (then registered), else
|
|
8414
|
+
* through the platform — what `storage put` and `--input ./file` both do.
|
|
8415
|
+
*/
|
|
8416
|
+
async function uploadToStorage(url, token, ws, rel, bytes) {
|
|
8417
|
+
const base = `/api/workspaces/${encodeURIComponent(ws)}/storage`;
|
|
8418
|
+
const said = async (res) => {
|
|
8419
|
+
const text = await res.text();
|
|
8420
|
+
try { return JSON.parse(text).error ?? text.slice(0, 200); } catch { return text.slice(0, 200); }
|
|
8421
|
+
};
|
|
8422
|
+
const sha = crypto.createHash("sha256").update(bytes).digest("hex");
|
|
8423
|
+
// The length too: the platform checks the limits on it and signs it
|
|
8424
|
+
// into the URL, so the bucket takes exactly these bytes (30 Oct 2026).
|
|
8425
|
+
const ask = await remoteFetch(url, `${base}/upload-url`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ path: rel, sha, size: bytes.length }) }, { token });
|
|
8426
|
+
// A platform older than presigned uploads answers 404 here: it
|
|
8427
|
+
// takes the bytes itself, the way one with no bucket does.
|
|
8428
|
+
if (!ask.ok && ask.status !== 404) throw new HttpError(await said(ask), ask.status, {});
|
|
8429
|
+
const { url: direct } = /** @type {{ url?: string | null }} */ (ask.ok ? await ask.json() : { url: null });
|
|
8430
|
+
if (direct) {
|
|
8431
|
+
const put = await fetch(direct, { method: "PUT", body: bytes, signal: AbortSignal.timeout(Math.max(120, bytes.length / 200_000) * 1000) });
|
|
8432
|
+
if (!put.ok) throw new Error(`the storage service refused it (${put.status})`);
|
|
8433
|
+
const done = await remoteFetch(url, base, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ path: rel, sha, size: bytes.length }) }, { token });
|
|
8434
|
+
if (!done.ok) throw new HttpError(await said(done), done.status, {});
|
|
8435
|
+
} else {
|
|
8436
|
+
const put = await remoteFetch(url, `${base}?path=${encodeURIComponent(rel)}`, { method: "PUT", body: bytes, headers: { "content-type": "application/octet-stream" } }, { token });
|
|
8437
|
+
if (!put.ok) throw new HttpError(await said(put), put.status, {});
|
|
8438
|
+
}
|
|
8439
|
+
}
|
|
8440
|
+
|
|
8441
|
+
/**
|
|
8442
|
+
* `--file` (FOL-163, repeatable): the files a run is handed — the API's
|
|
8443
|
+
* `inputs` (`--inputs <set>` is invoke's saved input set, a different thing). A path that
|
|
8444
|
+
* starts with ./, ../, / or ~ is a file on this machine — uploaded first to
|
|
8445
|
+
* storage/inputs/<upload id>/<name>; anything else is a storage path as
|
|
8446
|
+
* `foldrun storage ls` prints it. Decided by how it is written, never by
|
|
8447
|
+
* whether a local file happens to exist. Returns the storage paths.
|
|
8448
|
+
*/
|
|
8449
|
+
async function runInputs(url, flags, ws) {
|
|
8450
|
+
if (flags.file !== undefined && typeof flags.file !== "string" && !Array.isArray(flags.file)) throw new Error("which file? `--file <storage path>` or `--file ./local-file`");
|
|
8451
|
+
const given = many(flags.file);
|
|
8452
|
+
if (!given.length) return [];
|
|
8453
|
+
const local = (p) => /^(\.{1,2}\/|\/|~)/.test(p);
|
|
8454
|
+
const out = [];
|
|
8455
|
+
let token = null;
|
|
8456
|
+
const id = `${new Date().toISOString().slice(0, 10)}-${crypto.randomBytes(4).toString("hex")}`;
|
|
8457
|
+
for (const p of given) {
|
|
8458
|
+
if (!local(p)) {
|
|
8459
|
+
out.push(p.replace(/^storage\//, ""));
|
|
8460
|
+
continue;
|
|
8461
|
+
}
|
|
8462
|
+
const abs = path.resolve(p.startsWith("~") ? path.join(os.homedir(), p.slice(1)) : p);
|
|
8463
|
+
if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) throw new Error(`--file ${p}: no such file here`);
|
|
8464
|
+
token ??= await renewedToken(url, flags);
|
|
8465
|
+
const rel = `inputs/${id}/${path.basename(abs)}`;
|
|
8466
|
+
await uploadToStorage(url, token, ws, rel, fs.readFileSync(abs));
|
|
8467
|
+
console.log(` ${c.green("↑")} ${p} ${c.dim(`→ storage/${rel}`)}`);
|
|
8468
|
+
out.push(rel);
|
|
8469
|
+
}
|
|
8470
|
+
return out;
|
|
8471
|
+
}
|
|
8472
|
+
|
|
8355
8473
|
async function runsCmd(flags, layout) {
|
|
8356
8474
|
const url = platformFor(flags, "runs");
|
|
8357
8475
|
// --view <name>: a saved search (the dashboard's) read first, so every
|
|
@@ -8404,11 +8522,11 @@ async function runsCmd(flags, layout) {
|
|
|
8404
8522
|
// Search (FOL-72 step 9): by what happened inside a run, filtered by the
|
|
8405
8523
|
// platform; --view <name> starts from a saved search (the dashboard's).
|
|
8406
8524
|
const search = new URLSearchParams();
|
|
8407
|
-
for (const [flag, key] of [["tool", "tool"], ["agent", "agent"], ["model", "model"], ["min-tokens", "min_tokens"], ["min-secs", "min_secs"]]) {
|
|
8525
|
+
for (const [flag, key] of [["tool", "tool"], ["agent", "agent"], ["model", "model"], ["min-tokens", "min_tokens"], ["min-secs", "min_secs"], ["context", "context"]]) {
|
|
8408
8526
|
if (flags[flag] !== undefined && flags[flag] !== true) search.set(key, String(flags[flag]));
|
|
8409
8527
|
}
|
|
8410
8528
|
if (flags["tool-error"] === true) search.set("tool_error", "1");
|
|
8411
|
-
const searching = [...search.keys()].some((k) => ["tool", "tool_error", "agent", "model", "min_tokens", "min_secs"].includes(k));
|
|
8529
|
+
const searching = [...search.keys()].some((k) => ["tool", "tool_error", "agent", "model", "min_tokens", "min_secs", "context"].includes(k));
|
|
8412
8530
|
// A view's flow or text filters here, after the fetch: ask for the ceiling
|
|
8413
8531
|
// as for a status, or matches past the newest few go missing (Codex review).
|
|
8414
8532
|
const localText = typeof flags.flow === "string" || typeof flags.q === "string";
|
|
@@ -8432,6 +8550,9 @@ async function runsCmd(flags, layout) {
|
|
|
8432
8550
|
if (wanted && !wanted.has(r.outcome === "stopped" ? "stopped" : r.status)) return false;
|
|
8433
8551
|
if (verdicts && !(r.status === "completed" && verdicts.has(verdictOf(r)))) return false;
|
|
8434
8552
|
if (outcomes && !(typeof r.outcome === "string" && outcomes.has(r.outcome))) return false;
|
|
8553
|
+
// --context (FOL-162): one conversation's runs. The platform filters too;
|
|
8554
|
+
// checked here as well, so a platform from before it lists none, not all.
|
|
8555
|
+
if (typeof flags.context === "string" && r.context?.id !== flags.context) return false;
|
|
8435
8556
|
// A view's flow and free text (the runs page's): "agent: x" is a direct run.
|
|
8436
8557
|
// The dashboard names a run by what ran (whatRan): a direct agent run's
|
|
8437
8558
|
// or an eval's own name, without adhoc:/eval: (Codex review).
|
|
@@ -8455,7 +8576,7 @@ async function runsCmd(flags, layout) {
|
|
|
8455
8576
|
for (let round = 0; ; round++) {
|
|
8456
8577
|
const answers = await pool(names, 8, async (ws) => {
|
|
8457
8578
|
try {
|
|
8458
|
-
const forApi = new URLSearchParams([...search].filter(([k]) => ["tool", "tool_error", "agent", "model", "min_tokens", "min_secs"].includes(k)));
|
|
8579
|
+
const forApi = new URLSearchParams([...search].filter(([k]) => ["tool", "tool_error", "agent", "model", "min_tokens", "min_secs", "context"].includes(k)));
|
|
8459
8580
|
forApi.set("limit", String(perWorkspace));
|
|
8460
8581
|
if (cursor) forApi.set("before", cursor);
|
|
8461
8582
|
const answer = await remoteCall(url, flags, `/api/workspaces/${ws}/runs?${forApi}`);
|
|
@@ -9093,6 +9214,8 @@ async function agentRunCmd(positional, flags, layout) {
|
|
|
9093
9214
|
const WAIT_PIECE_S = 25;
|
|
9094
9215
|
const wait = flags.wait === true ? `?wait=true&timeout=${WAIT_PIECE_S}` : "";
|
|
9095
9216
|
const base = `/api/workspaces/${encodeURIComponent(ws)}/agents/${encodeURIComponent(name)}`;
|
|
9217
|
+
if (flags.context !== undefined && typeof flags.context !== "string") throw new Error("which conversation? `--context <id>`");
|
|
9218
|
+
const files = await runInputs(url, flags, ws);
|
|
9096
9219
|
|
|
9097
9220
|
// A waited run that FAILS is the answer to the question, not a fault in
|
|
9098
9221
|
// the call: 200 with its status since FOL-106, 500 with the same record
|
|
@@ -9112,7 +9235,9 @@ async function agentRunCmd(positional, flags, layout) {
|
|
|
9112
9235
|
method: "POST",
|
|
9113
9236
|
// --test: the platform marks the run a test run — sends refused or sunk
|
|
9114
9237
|
// at the proxy, send-capable secrets withheld, state/ kept.
|
|
9115
|
-
|
|
9238
|
+
// --context <id> (FOL-162): a turn of that conversation — the agent
|
|
9239
|
+
// reads the earlier runs started with the same context first.
|
|
9240
|
+
body: JSON.stringify({ ...(task ? { task } : {}), ...(flags.test === true ? { test: true } : {}), ...(typeof flags.context === "string" ? { context: flags.context } : {}), ...(files.length ? { inputs: files } : {}) }),
|
|
9116
9241
|
}),
|
|
9117
9242
|
);
|
|
9118
9243
|
const runId = body?.runId;
|
|
@@ -15118,6 +15243,8 @@ export async function run(command, positional, flags, workspace, layout) {
|
|
|
15118
15243
|
return apiCmd(positional, flags);
|
|
15119
15244
|
case "keys":
|
|
15120
15245
|
return keysCmd(positional, flags);
|
|
15246
|
+
case "gateway":
|
|
15247
|
+
return gatewayCmd(positional, flags);
|
|
15121
15248
|
case "a2a":
|
|
15122
15249
|
return a2aCmd(positional, flags, layout);
|
|
15123
15250
|
case "audit":
|