foldrun 10.1.1 → 10.3.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 +16 -2
- package/docs/a2a.md +330 -0
- package/docs/agents.md +77 -0
- package/docs/api.md +38 -2
- package/docs/checks.md +28 -5
- package/docs/cli.md +14 -2
- package/docs/coding-agents.md +6 -0
- package/docs/flows.md +1 -0
- package/docs/glossary.md +5 -0
- package/docs/mcp.md +127 -0
- package/docs/network.md +3 -2
- package/docs/team-and-access.md +10 -1
- package/docs/tools.md +2 -0
- package/package.json +3 -3
- package/src/commands.mjs +539 -1
- package/src/guide.mjs +1 -1
package/docs/cli.md
CHANGED
|
@@ -95,6 +95,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
95
95
|
| `foldrun insights` | recurring [problems](runs#insights) found in the last week of runs — a prompt mostly uncached, a big tool result sent again, a retry loop, steps near their timeout — each with why, what to do, about what it cost and the runs it was seen in. `--days <1-30>`, `--to <workspace>`, `--json` |
|
|
96
96
|
| `foldrun inbox` | what waits on you across your workspaces ([your inbox](runs#your-inbox)): gates, questions agents ask, open issues, proposed fixes, your runs that went wrong this week — assigned to you and started by you by default; `--team`, `--started`, `--mine`, `--all`, `--dismissed`, `--kind approval\|question\|issue\|proposal\|run`, `--unread`, `--json`. Each item shows its id; exits 1 when something assigned to you is unread |
|
|
97
97
|
| `foldrun inbox read\|unread\|dismiss\|restore <id>…` | mark items in your own view: `dismiss` sets one aside (it still waits where it lives), `restore` puts it back |
|
|
98
|
+
| `foldrun mcp` | this account as an [MCP server](mcp) on stdin/stdout, for an AI app to start: `claude mcp add foldrun -- foldrun mcp`, `codex mcp add foldrun -- foldrun mcp`. Each line is one JSON-RPC message, forwarded to the platform's `POST /api/mcp` with this machine's sign-in (`--profile`, `--url`, `--token` as for any platform command); stdout carries nothing but protocol. `--read-only` offers only the tools that read. Typed into a terminal it prints how to connect and exits 2 |
|
|
98
99
|
| `foldrun issues` | the account's [issues](runs#issues): what went wrong, grouped, open until someone resolves it — kind, desk and flow (or the platform cause and every desk it hit), how many times since when, the newest reason and what to do. `--to <workspace>` narrows it, `--all` adds resolved ones (`--status open\|acknowledged\|snoozed\|resolved\|all`), `--json` |
|
|
99
100
|
| `foldrun issues show\|ack\|snooze\|resolve\|reopen <id>` | one issue: `show` adds its runs and history; `ack` says you have seen it, `snooze --for 30m\|4h\|1d\|1w` (or `--until <ISO>`, or `--times <n>`: until it happens n more times) hides it for a while, `resolve` closes it until it happens again, `reopen` undoes that. `--note "…"` is kept in its history |
|
|
100
101
|
| `foldrun issues doctor <id>` | the run doctor on an issue's newest run, in that run's workspace — the issue card's **Doctor** button: why (platform, check, work or outside), and the fix as diffs, saved on yes (`--yes`, `--dry-run`, `--json`). A missed schedule has no run and is refused |
|
|
@@ -173,6 +174,13 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
173
174
|
| `foldrun use <name>` | act as one of them from here on. `foldrun switch <name>` is the same command |
|
|
174
175
|
| `foldrun keys ls` | the account's API keys, each with its role and scope, when it was created, when it was last used and from where (a /24 or /48), and when it expires — also `create <label>` (`--expires 30d\|90d\|365d\|never`), `rotate <id>` and `revoke <id>` |
|
|
175
176
|
| `foldrun keys rotate <id>` | a new key with the old one's label, role, workspaces and deploy scope, printed once; the old key is revoked at once (asks first; `--yes` on a pipe), or keeps working for `--grace 1h` / `24h` while you swap the new one in. A key already rotated is refused (409) and the command names the key that replaced it — rotate that one, also if its secret was lost; `keys ls` shows `rotated → <id>`. The owner is emailed a week before any key expires |
|
|
177
|
+
| `foldrun keys create <label> --a2a --to <ws> --flows a,b` | a key for an outside agent ([A2A](a2a.md)): it opens `/a2a/<account>/<ws>/…` — the agent card and JSON-RPC endpoint of those flows, each also published with `a2a:` — and no `/api` route. `--max-tasks <n>` caps the tasks it may have open at once (1–100, default 10); `--expires` as for any key. Printed once; `keys ls` shows it as `A2A · <ws> · <flows>`. `POST /api/keys { purpose: "a2a", workspace, flows, maxTasks }`, an admin's |
|
|
178
|
+
| `foldrun a2a ls --to <ws>` | what a workspace serves over A2A (`GET /api/workspaces/<ws>/a2a`): every flow that says `a2a:`, published or not, with its public/private card and its card and endpoint URLs; the workspace's A2A keys (an admin's view; `null` otherwise); and the newest tasks — state, flow, run, and `A2A · <key label>`. `--json` prints the answer as it came |
|
|
179
|
+
| `foldrun a2a publish <flow>` | sets `a2a: { publish: true }` in the flow, keeping the rest of its block: `--name`, `--description`, `--example "…"` (repeatable — the card's examples), `--public-card` (the card is readable without a key; calling never is) or `--private-card`. Checked with core's `a2a:` rules before anything is written; shows the diff, `--dry-run` writes nothing. Without `--to` it edits this folder (`deploy` ships it); `--to <workspace>` sends the flow page's `PATCH …/flows/<flow> { a2a, expect }` — an admin's, the platform refuses an editor — and prints the card URL. A caller also needs an A2A key that names the flow |
|
|
180
|
+
| `foldrun a2a unpublish <flow>` | `a2a: publish: false` — no outside agent may call it, whatever keys name it; the rest of `a2a:` stays for the next publish. `--to`, `--dry-run` as for `publish` |
|
|
181
|
+
| `foldrun a2a card <flow> --to <ws>` | the flow's card URL and JSON-RPC endpoint, then the card itself. A private card is read with an A2A key from `$FOLDRUN_A2A_KEY` (or `--key-env NAME`); without one the URLs are printed and the card is not |
|
|
182
|
+
| `foldrun a2a call <card-url> "<text>"` | a small A2A 1.0 client (core's `a2a-client`), to try a published flow or any A2A agent: reads the card (its JSON-RPC interface must be at the card's own origin; redirects are never followed), sends `SendMessage` with the text and `--data <json\|@file>` as a data part (`--context <id>` continues a conversation), prints the task id, then polls `GetTask` until the task ends or `--max-wait <s>` (default 300) runs out — `--no-wait` returns at once. Prints the state and the answer (`--json` the task). The key is an A2A key from `$FOLDRUN_A2A_KEY` or `--key-env NAME`, never this CLI's API key and never a command-line value. Exit 0 when completed or still open, 1 when failed, canceled or rejected |
|
|
183
|
+
| `foldrun a2a status <task-id> --card <url>` | `GetTask`: the task as it stands, and its answer once it has one (`--json`). `foldrun a2a cancel <task-id> --card <url>` sends `CancelTask` (asks first; `--yes` on a pipe) — on a foldrun flow that stops its run; exit 0 when it reads canceled. The exit code is the same with or without `--json`: `status` exits 1 for a failed, rejected or canceled task. An agent's text and ids are printed with terminal control characters removed |
|
|
176
184
|
| `foldrun audit` | the account's audit log, newest first — sign-ins and refusals, sessions, MFA, keys minted, rotated and revoked, invites and role changes, secrets set and deleted (by name), deploys, workspace deletes, plan and billing changes, and every time support viewed the account, with the reason. `--since 7d` (default) or a date, `--until`, `--action apikey` (a family or one action), `--actor <email\|key:label\|support:email>`, `--to <workspace>`, `--limit`, `--all` to follow every page, `--json`, `--csv [--file audit.csv]`. The owner's and unscoped admins'. There is no `audit` for support's view-as: that is a person's act in the browser, never a key's |
|
|
177
185
|
|
|
178
186
|
## Options
|
|
@@ -222,7 +230,8 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
222
230
|
| `--step <n>` | `approve`, `reject`: decide one gate, numbered as `report` prints it. Without it, every step of that run which is waiting |
|
|
223
231
|
| `--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 |
|
|
224
232
|
| `--note "<text>"` | `approve`: guidance the approved step reads in its prompt — "approve, but skip the Sydney batch". `reject`: the reason, recorded on the trace |
|
|
225
|
-
| `--
|
|
233
|
+
| `--read-only` | `mcp`: offer the AI app only the tools that read — no `run_flow`, `decide_approval`, `answer_question`, `message_run` or `stop_run` |
|
|
234
|
+
| `--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`, `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 |
|
|
226
235
|
| `--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`, `team`: the raw document |
|
|
227
236
|
| `--events <a,b>` | `account set notify`: which events are notified on — `failed`, `awaiting-approval`, `completed` |
|
|
228
237
|
| `--watch` | `invoke`: follow the run's trace here as it happens; the exit code is the run's |
|
|
@@ -243,6 +252,9 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
243
252
|
| `--role <r>` | `keys create`: `viewer`, `editor` (default) or `admin` |
|
|
244
253
|
| `--expires <span>` | `keys create`: when it stops working — `30d`, `90d`, `365d` or `never` (default) |
|
|
245
254
|
| `--grace <span>` | `keys rotate`: keep the old key working for `1h` or `24h` (default `0`: revoked now) |
|
|
255
|
+
| `--a2a` | `keys create`: an A2A key for an outside agent, with `--to <workspace>`, `--flows a,b` and optionally `--max-tasks <n>` |
|
|
256
|
+
| `--key-env <NAME>` | `a2a call`, `a2a status`, `a2a cancel`, `a2a card`: the environment variable that holds the A2A key (default `FOLDRUN_A2A_KEY`) |
|
|
257
|
+
| `--card <url>` | `a2a status`, `a2a cancel`: the agent card of the agent that holds the task |
|
|
246
258
|
| `--force` | `deploy`: deploy while runs are in flight. `pull`, `storage get`: overwrite local files |
|
|
247
259
|
| `--no-runtimes` | `deploy`: do not wait for the workspace's environments to be built, or print them |
|
|
248
260
|
| `--platform` / `--yes` | `workspaces rm`: delete it on the platform, said twice because it cannot be undone |
|
|
@@ -257,7 +269,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
257
269
|
| `--timeout <s>` | how many seconds one request to the platform may take — or `FOLDRUN_TIMEOUT`. Default 30, and 300 for `tool test`, where the tool itself is the thing being waited on |
|
|
258
270
|
| `--local` | `deploy`, `secrets`, `logs`: the installation on this machine, even when signed in |
|
|
259
271
|
| `--quiet` | leave out the dim "acting as …" line a platform command prints on stderr |
|
|
260
|
-
| `--dry-run` | `extract`: list what would move, change nothing. `flow add`, `flow rm-step`, `flow dup-step`, `flow set`, `flow trigger`, `flow move-step`, `flow paste`, `flow draft`, `assistant`, `history restore`, `agent link`/`unlink`, `agent network`: show the diff, write nothing. `restore`: the diff only, restore nothing. A bulk `stop`/`rerun`: list what matches, touch nothing |
|
|
272
|
+
| `--dry-run` | `extract`: list what would move, change nothing. `flow add`, `flow rm-step`, `flow dup-step`, `flow set`, `flow trigger`, `flow move-step`, `flow paste`, `flow draft`, `assistant`, `history restore`, `agent link`/`unlink`, `agent network`, `a2a publish`/`unpublish`: show the diff, write nothing. `restore`: the diff only, restore nothing. A bulk `stop`/`rerun`: list what matches, touch nothing |
|
|
261
273
|
| `--out <file>` | `api spec`: where to write the OpenAPI document (default stdout) |
|
|
262
274
|
| `--file <path>` | `source put`: the file to send. `storage get`, `report get`, `account export`, `billing statement --csv`: where to write — `-` for stdout |
|
|
263
275
|
|
package/docs/coding-agents.md
CHANGED
|
@@ -107,6 +107,12 @@ report <id>` to read which step failed and what it cost, fix the markdown,
|
|
|
107
107
|
`foldrun deploy`, then `foldrun rerun <id> --from <step>`. `foldrun triggers`
|
|
108
108
|
answers "why did nothing run".
|
|
109
109
|
|
|
110
|
+
An app that cannot run a terminal — Claude Desktop, Cursor's chat — or one
|
|
111
|
+
that would rather call tools than commands reaches the same account through
|
|
112
|
+
[MCP](mcp): `claude mcp add foldrun -- foldrun mcp` gives it the inbox, the
|
|
113
|
+
waiting gates and questions, runs, flows and files, and approve, answer,
|
|
114
|
+
message, start and stop, each as the key could do it.
|
|
115
|
+
|
|
110
116
|
## Writing a flow
|
|
111
117
|
|
|
112
118
|
A numbered list of steps. The number is the GROUP: same number means those
|
package/docs/flows.md
CHANGED
|
@@ -346,6 +346,7 @@ normal outcome, recorded as one.
|
|
|
346
346
|
| `approvers` | who may decide this flow's gates — addresses, or `admins` |
|
|
347
347
|
| `approve_within` | how long a gate waits before the run is rejected |
|
|
348
348
|
| `live` | `true` to make this flow's runs real where the platform would otherwise make them [test runs](runs#test-runs): as an eval's subject. Only ever an opt-out of the safe default |
|
|
349
|
+
| `a2a` | serve this flow to outside agents over A2A 1.0 — `{ publish: true, name?, description?, examples?, public_card?, input? }`: the agent card's name, description and example requests (else the flow's own), `public_card: true` to let the card be read without a key, and `input` a JSON Schema the request's data part must match. A caller still needs an A2A key that names the flow; a block `foldrun check` cannot read publishes nothing. Changing it needs `workspace:manage`. See [A2A](a2a) |
|
|
349
350
|
|
|
350
351
|
Every duration here is written the way `wait:` is — `45s`, `10m`, `2h`, `3d`,
|
|
351
352
|
or bare seconds — and capped at thirty days.
|
package/docs/glossary.md
CHANGED
|
@@ -1,5 +1,10 @@
|
|
|
1
1
|
# Glossary
|
|
2
2
|
|
|
3
|
+
**A2A** — Agent2Agent, an open protocol for one agent to hand a task to
|
|
4
|
+
another run by somebody else. A flow with `a2a: { publish: true }` is served
|
|
5
|
+
to outside agents holding an **A2A key**; an agent's `remotes:` are the
|
|
6
|
+
outside agents it may call. See [A2A](a2a).
|
|
7
|
+
|
|
3
8
|
**account** — the top level: people, keys, the library, the wallet, and the
|
|
4
9
|
workspaces under it. Has one owner.
|
|
5
10
|
|
package/docs/mcp.md
ADDED
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
# MCP: AI apps
|
|
2
|
+
|
|
3
|
+
foldrun is an [MCP](https://modelcontextprotocol.io) server. An AI app that
|
|
4
|
+
speaks MCP — Claude Code, Claude Desktop, Cursor, Codex — connects to your
|
|
5
|
+
account and gets tools for what you would otherwise open the dashboard for:
|
|
6
|
+
what waits on you, the gates and questions, the runs and flows, a file, and
|
|
7
|
+
the decisions — approve, answer, message, start, stop.
|
|
8
|
+
|
|
9
|
+
Ask it "what is waiting on me in foldrun?", "why did last night's run of
|
|
10
|
+
`weekly` fail?" or "approve the draft in run r-…, and say why".
|
|
11
|
+
|
|
12
|
+
There are two ways in, and they serve the same tools:
|
|
13
|
+
|
|
14
|
+
| | needs | for |
|
|
15
|
+
|---|---|---|
|
|
16
|
+
| `foldrun mcp` | the CLI, signed in (`foldrun login`) | an app on the same machine — nothing to paste |
|
|
17
|
+
| `POST /api/mcp` | an API key | an app that connects over HTTP, or a machine without the CLI |
|
|
18
|
+
|
|
19
|
+
## Connecting
|
|
20
|
+
|
|
21
|
+
With the CLI, on a machine that is signed in:
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
claude mcp add foldrun -- foldrun mcp # Claude Code
|
|
25
|
+
codex mcp add foldrun -- foldrun mcp # Codex
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Claude Desktop, Cursor and other apps that take a JSON config:
|
|
29
|
+
|
|
30
|
+
```json
|
|
31
|
+
{ "mcpServers": { "foldrun": { "command": "foldrun", "args": ["mcp"] } } }
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
`foldrun mcp` forwards each message to the platform the CLI is signed in to,
|
|
35
|
+
as the account `foldrun whoami` names — `--profile <name>` picks another
|
|
36
|
+
signed-in account, `--url` and `--token` (or `FOLDRUN_URL`, `FOLDRUN_TOKEN`)
|
|
37
|
+
another platform or key. It renews this machine's sign-in once when it starts,
|
|
38
|
+
the way every platform command does. Typed into a terminal it prints how to
|
|
39
|
+
connect and exits: it is for an app to start.
|
|
40
|
+
|
|
41
|
+
Over HTTP, with a key from Settings → API keys:
|
|
42
|
+
|
|
43
|
+
```sh
|
|
44
|
+
claude mcp add --transport http foldrun https://<your platform>/api/mcp \
|
|
45
|
+
--header "Authorization: Bearer mda_..."
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Settings → API keys → **Connecting an AI app (MCP)** shows this install's
|
|
49
|
+
address and the same lines. claude.ai's connectors sign in with OAuth, which
|
|
50
|
+
this endpoint does not offer; connect through Claude Desktop or Claude Code.
|
|
51
|
+
|
|
52
|
+
## The tools
|
|
53
|
+
|
|
54
|
+
| tool | does | route |
|
|
55
|
+
|---|---|---|
|
|
56
|
+
| `whoami` | the account, role and workspaces this key acts for | `GET /api/me` |
|
|
57
|
+
| `list_workspaces` | the workspaces it may open | `GET /api/workspaces` |
|
|
58
|
+
| `inbox` | what waits on you: approvals, questions, issues, proposed fixes, your failed runs (`bucket`, `kind`, `workspace`) | `GET /api/me/inbox` |
|
|
59
|
+
| `list_approvals` | every gate waiting on a person, and every question an agent is asking | `GET /api/approvals` |
|
|
60
|
+
| `list_flows` | a workspace's flows | `GET …/flows` |
|
|
61
|
+
| `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` |
|
|
62
|
+
| `get_run` | one run in full | `GET …/runs/<id>` |
|
|
63
|
+
| `read_file` | one file of a workspace's source, or the tree | `GET …/source` |
|
|
64
|
+
| `run_flow` | start a flow (`task`, `test: true` for a [test run](runs#test-runs)) | `POST …/flows/<flow>/run` |
|
|
65
|
+
| `decide_approval` | approve or reject a gate (`note`, `step`) | `POST …/runs/<id>/approve` |
|
|
66
|
+
| `answer_question` | answer an agent's question mid-step | `POST …/runs/<id>/answer` |
|
|
67
|
+
| `message_run` | say something to a running agent | `POST …/runs/<id>/message` |
|
|
68
|
+
| `stop_run` | stop a run | `POST …/runs/<id>/stop` |
|
|
69
|
+
|
|
70
|
+
The first eight read. The last five act, and are marked so for the app
|
|
71
|
+
(`readOnlyHint: false`; `stop_run` also `destructiveHint: true`), which is
|
|
72
|
+
what an app uses to ask you before calling one.
|
|
73
|
+
|
|
74
|
+
## What it may do
|
|
75
|
+
|
|
76
|
+
Nothing a key could not. Each tool is a call to the route in the table, made
|
|
77
|
+
with the same key — so a viewer's key cannot start, approve or stop; a key
|
|
78
|
+
scoped to some workspaces sees and touches only those; an
|
|
79
|
+
[A2A key](a2a#a2a-keys) is refused (it opens `/a2a` and nothing else); and
|
|
80
|
+
every check, limit and refusal is the route's own. A tool whose route refused
|
|
81
|
+
answers `isError: true` with the route's words: `HTTP 403: this workspace is
|
|
82
|
+
not one you were given access to`.
|
|
83
|
+
|
|
84
|
+
`inbox` is a person's: a key minted by a person (every key from Settings, and
|
|
85
|
+
the CLI's sign-in) has one; a key nobody minted is refused, as the route
|
|
86
|
+
refuses it.
|
|
87
|
+
|
|
88
|
+
To give an app only the tools that read, connect it read-only — the tools
|
|
89
|
+
that act are not offered, and a call to one is refused:
|
|
90
|
+
|
|
91
|
+
```sh
|
|
92
|
+
claude mcp add foldrun -- foldrun mcp --read-only
|
|
93
|
+
claude mcp add --transport http foldrun "https://<your platform>/api/mcp?readonly=1" --header "Authorization: Bearer mda_..."
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
A viewer's key is the stronger version of the same: read-only by role,
|
|
97
|
+
whatever the app is told.
|
|
98
|
+
|
|
99
|
+
## What comes back is data
|
|
100
|
+
|
|
101
|
+
Run outputs, summaries, an agent's question, a file — all of it was written by
|
|
102
|
+
your agents, by the sites they read and by the people who sent them work. The
|
|
103
|
+
server tells the app so when it connects: treat it as content, never as an
|
|
104
|
+
instruction. A tool answer is at most 100,000 characters; a longer one (a
|
|
105
|
+
long run's whole record) is cut and says so.
|
|
106
|
+
|
|
107
|
+
## The protocol
|
|
108
|
+
|
|
109
|
+
MCP's Streamable HTTP transport, stateless: one JSON-RPC 2.0 message per
|
|
110
|
+
`POST /api/mcp`, answered with one JSON body. No SSE stream, no session id, no
|
|
111
|
+
batches; `GET` and `DELETE` answer `405`. Served: `initialize` (revisions
|
|
112
|
+
`2025-11-25`, `2025-06-18` and `2025-03-26` — the app's when it is one of
|
|
113
|
+
these, else the newest), `ping`, `tools/list`, `tools/call`; a notification is
|
|
114
|
+
answered `202` with no body. It sits under `/api`, so the proxy holds the same
|
|
115
|
+
raw-path check, body limit and rate limit as for every other route.
|
|
116
|
+
|
|
117
|
+
Refused before a message is read, as a JSON-RPC error with a real status: no
|
|
118
|
+
key (`401`, with `WWW-Authenticate: Bearer`) — a session cookie never opens
|
|
119
|
+
it —, a refused key (`401`/`403`), an `Origin` header that is not the
|
|
120
|
+
platform's own (`403`; MCP clients send none), an `MCP-Protocol-Version` it
|
|
121
|
+
does not speak (`400`). The route and request shape are in [the API
|
|
122
|
+
reference](api#mcp--ai-apps-connecting-with-a-key).
|
|
123
|
+
|
|
124
|
+
`foldrun mcp` reads one message per line on stdin and writes one per line on
|
|
125
|
+
stdout, and nothing else there: every note goes to stderr. Calls run side by
|
|
126
|
+
side, after `initialize` has answered. A platform from before 1 Nov 2026 has
|
|
127
|
+
no `/api/mcp`; the CLI says so as a JSON-RPC error.
|
package/docs/network.md
CHANGED
|
@@ -24,8 +24,9 @@ network: [api.hubapi.com] # the trusted list, plus this
|
|
|
24
24
|
|
|
25
25
|
**What the step declares** is always allowed, at every level: the hosts of
|
|
26
26
|
its `apis:`, its remote MCP servers, its web providers (`web: {search: brave}`),
|
|
27
|
-
|
|
28
|
-
|
|
27
|
+
the card of each outside agent in its `remotes:` (that card's own site — never
|
|
28
|
+
one the card names), and the sites its [secrets are bound to](secrets#bound-to-sites).
|
|
29
|
+
You never list those twice.
|
|
29
30
|
|
|
30
31
|
No level is ever a way into private space: the cluster, the LAN and the
|
|
31
32
|
cloud metadata endpoint are refused whatever `network:` says.
|
package/docs/team-and-access.md
CHANGED
|
@@ -28,7 +28,8 @@ A refused call answers `403` with the role that was needed.
|
|
|
28
28
|
The keys in a workspace's `AGENTS.md` that set policy for the whole
|
|
29
29
|
workspace — `budget`, `compute`, `notify`, `network_enforce`, `telemetry`,
|
|
30
30
|
`alerts`, `owner`, `judge` and `timezone` (also when written under a
|
|
31
|
-
`governance:`, `guardrail:`, `observability:` or `evaluation:` block) —
|
|
31
|
+
`governance:`, `guardrail:`, `observability:` or `evaluation:` block) — and a
|
|
32
|
+
flow's `a2a:`, which decides whether outside agents may call it ([A2A](a2a)) — need
|
|
32
33
|
the **admin** role to change, whichever way the file is written: the
|
|
33
34
|
workspace's settings, a save in the editor (`PUT …/source`), `foldrun deploy`,
|
|
34
35
|
an import, or a restore to an older point. An editor still edits the rest of
|
|
@@ -118,6 +119,14 @@ several accounts — an agency, a reseller — holds one key per account and
|
|
|
118
119
|
switches between them; the CLI stores each as a named profile. See
|
|
119
120
|
[More than one account](cli#more-than-one-account).
|
|
120
121
|
|
|
122
|
+
An **A2A key** is a key of its own kind, for an outside agent calling your
|
|
123
|
+
published flows over [A2A](a2a): one workspace, the flows it names, and how
|
|
124
|
+
many tasks it may have open (`foldrun keys create partner --a2a --to leads
|
|
125
|
+
--flows lead-finder`, or Settings → API keys). It opens only `/a2a/…` — every `/api`
|
|
126
|
+
route refuses it — so it can never read runs, change files, approve a step or
|
|
127
|
+
answer a question. It expires, is revoked and rotated like any key, and a
|
|
128
|
+
rotated one keeps the tasks its predecessor made.
|
|
129
|
+
|
|
121
130
|
### Expiry, last use and rotation
|
|
122
131
|
|
|
123
132
|
A key can be given an end when it is minted — 30, 90 or 365 days, or never
|
package/docs/tools.md
CHANGED
|
@@ -1770,6 +1770,8 @@ limits:
|
|
|
1770
1770
|
|---|---|
|
|
1771
1771
|
| `web.<action>` | one action of the `web` tool; a model provider's own search or fetch (`web: {search: zai}`) counts as `web.search` / `web.fetch` |
|
|
1772
1772
|
| `web` | every web action together |
|
|
1773
|
+
| `a2a` | messages to outside agents (`remotes:`) — `a2a_send` and `a2a_reply` together |
|
|
1774
|
+
| `a2a.<tool>` | one of `a2a.send`, `a2a.reply`, `a2a.status`, `a2a.cancel` — `a2a.status` caps polling apart from sending |
|
|
1773
1775
|
| an HTTP tool's name | every call to it — each operation of an `openapi:` tool, and its generic `call_`, all under the one name |
|
|
1774
1776
|
| a script tool's name | every run of it (`desk-email` and `desk_email` are the same key) |
|
|
1775
1777
|
| an MCP server's name | every tool the server exposes |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "foldrun",
|
|
3
|
-
"version": "10.
|
|
3
|
+
"version": "10.3.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": "^9.
|
|
14
|
+
"@foldrun/core": "^9.2.0"
|
|
15
15
|
},
|
|
16
16
|
"files": [
|
|
17
17
|
"bin",
|
|
@@ -22,7 +22,7 @@
|
|
|
22
22
|
],
|
|
23
23
|
"scripts": {
|
|
24
24
|
"e2e": "FOLDRUN_E2E=1 FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-e2e-XXXXXX) node --test --test-timeout=300000 tests/e2e.test.ts",
|
|
25
|
-
"test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-issues.test.ts tests/cli-capture.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-agent-link-isolated.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-report-cache.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts tests/cli-check-scan.test.ts tests/cli-published.test.ts tests/cli-init-target.test.ts tests/cli-flow-filter.test.ts tests/cli-eval-grades.test.ts tests/cli-eval-compare.test.ts tests/cli-proposals.test.ts tests/cli-inbox.test.ts tests/cli-usage-compute.test.ts tests/cli-fol105.test.ts tests/cli-key-renew.test.ts tests/cli-wait-failed.test.ts",
|
|
25
|
+
"test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-issues.test.ts tests/cli-capture.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-agent-link-isolated.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-report-cache.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts tests/cli-check-scan.test.ts tests/cli-published.test.ts tests/cli-init-target.test.ts tests/cli-flow-filter.test.ts tests/cli-eval-grades.test.ts tests/cli-eval-compare.test.ts tests/cli-proposals.test.ts tests/cli-inbox.test.ts tests/cli-usage-compute.test.ts tests/cli-fol105.test.ts tests/cli-key-renew.test.ts tests/cli-wait-failed.test.ts tests/cli-mcp.test.ts tests/cli-a2a.test.ts",
|
|
26
26
|
"release": "node scripts/release.mjs",
|
|
27
27
|
"typecheck": "tsc -p tsconfig.json",
|
|
28
28
|
"docs:sync": "node scripts/sync-docs.mjs",
|