foldrun 10.1.0 → 10.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/bin/foldrun.mjs CHANGED
@@ -58,6 +58,7 @@
58
58
  // foldrun doctor what is between this terminal and the platform, checked
59
59
  // foldrun accounts every account signed in here; `use <name>` switches
60
60
  // foldrun keys <verb> ls / create / revoke — the account's API keys
61
+ // foldrun a2a <verb> ls / publish / unpublish / card / call / status / cancel — flows served to outside agents (A2A 1.0)
61
62
  // foldrun library <verb> ls / cat / put / new / rm — the account's shared shelf on the platform
62
63
  // foldrun find <words> search the account the way the dashboard's ⌘K does
63
64
  // foldrun changelog what each release of the platform changed
@@ -259,6 +260,13 @@ Signing in
259
260
  foldrun accounts every account signed in on this machine, and which one is active
260
261
  foldrun use <name> act as one of them from here on
261
262
  foldrun keys ls the account's API keys: created, last used, expires, scope — also create <label> [--expires 90d], rotate <id> [--grace 1h], revoke <id>
263
+ 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
264
+ 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)
265
+ 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
266
+ foldrun a2a unpublish <flow> a2a: publish: false — no outside agent may call it; the rest of a2a: is kept (--to <ws>, --dry-run)
267
+ foldrun a2a card <flow> --to <ws> the flow's agent card URL and endpoint, then the card (a private card needs an A2A key in $FOLDRUN_A2A_KEY or --key-env)
268
+ foldrun a2a call <card-url> "<text>" send one message to an A2A 1.0 agent — a published flow or anyone's — and wait for the task (--data <json|@file>, --context <id>, --no-wait, --max-wait <s>, --json); the A2A key comes from $FOLDRUN_A2A_KEY or --key-env NAME, never this CLI's API key
269
+ foldrun a2a status <task-id> --card <url> the task as it stands now (--json) — cancel <task-id> --card <url> stops it (asks; --yes)
262
270
  foldrun audit the account's audit log, newest first: sign-ins, keys, invites, secrets by name, deploys, support views (--since 7d, --action, --actor, --to, --all, --csv)
263
271
  foldrun --version this CLI's version, offline (\`foldrun version\` also asks the platform)
264
272
  foldrun --help everything; \`foldrun <command> --help\`, \`-h\` or \`foldrun help <command>\` for one (never runs it)
@@ -370,6 +378,9 @@ Options
370
378
  --role <r> keys create: viewer, editor (default) or admin
371
379
  --expires <span> keys create: when it stops working — 30d, 90d, 365d or never (default never)
372
380
  --grace <span> keys rotate: keep the old key working for 1h or 24h while you swap the new one in (default 0: revoked now)
381
+ --a2a keys create: an A2A key for an outside agent — with --to <workspace> and --flows a,b; --max-tasks <n> caps its open tasks (1–100, default 10)
382
+ --key-env <NAME> a2a call, a2a status, a2a cancel, a2a card: the environment variable holding the A2A key (default FOLDRUN_A2A_KEY) — a key is never taken on the command line
383
+ --card <url> a2a status, a2a cancel: the agent card of the agent that holds the task
373
384
 
374
385
  Platform options (deploy, invoke, secrets, logs, keys)
375
386
  --to <workspace> workspace on the platform (deploy default: folder name); flow add/show, agent link: edit or show the deployed copy instead of this folder; hook test: run the deployed hook on the platform; hook ls: list the deployed workspace's hooks and what they did lately; restore <ws>: the commit, date or age to put it back to (3d, 2026-09-28T14:00)
@@ -410,9 +421,9 @@ if (!command || command === "--help" || command === "-h") {
410
421
  // `--value` as the account's argument and stored an empty secret; `--force
411
422
  // ./dir` swallowed the directory. A flag followed by another flag is also
412
423
  // boolean, so an unlisted switch at least does not eat its neighbour.
413
- const BOOLEAN_FLAGS = new Set(["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", "export", "isolated", "no-wait", "dismissed", "unread", "team", "started", "mine", "none"]);
424
+ const BOOLEAN_FLAGS = new Set(["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", "export", "isolated", "no-wait", "dismissed", "unread", "team", "started", "mine", "none", "a2a", "public-card", "private-card", "return-immediately"]);
414
425
  // Flags said more than once collect into a list: `--tag a --tag b`.
415
- const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove", "rule", "authorize-param"]);
426
+ const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove", "rule", "authorize-param", "example"]);
416
427
  // `--wait` is a switch everywhere but `flow add <flow> wait`, where it takes
417
428
  // a span: `--wait 30m`, `--wait event`. Only a value that reads as one is
418
429
  // taken, so `invoke x --wait` and friends are as they were.
package/docs/a2a.md ADDED
@@ -0,0 +1,330 @@
1
+ # A2A: outside agents
2
+
3
+ [A2A](https://a2a-protocol.org/v1.0.0/specification/) (Agent2Agent) is an
4
+ open protocol for one agent to hand a task to another agent run by somebody
5
+ else. foldrun speaks the released **1.0** version, over JSON-RPC 2.0 on HTTP,
6
+ in both directions:
7
+
8
+ - **Serving:** you publish a flow, and an outside agent holding an A2A key
9
+ sends it a request, follows the task, and reads the result.
10
+ - **Calling:** an agent of yours lists outside agents in `remotes:` and calls
11
+ them with four tools.
12
+
13
+ Your own files do not change shape for either. A2A is a door at the edge: a
14
+ published flow is the same flow, and a remote is reached the way an `apis:`
15
+ entry is.
16
+
17
+ ## Publishing a flow
18
+
19
+ A flow is served over A2A when its frontmatter says so:
20
+
21
+ ```markdown
22
+ ---
23
+ trigger: manual
24
+ a2a:
25
+ publish: true
26
+ name: Lead researcher # the agent card's name; else the flow's
27
+ description: Finds three qualified leads for a business type and city.
28
+ examples: ["Dentists in Perth", "Accountants in Hobart"]
29
+ public_card: false # true: the card is readable without a key
30
+ input: # optional: a JSON Schema the request's data part must match
31
+ type: object
32
+ required: [city]
33
+ properties: { city: { type: string } }
34
+ ---
35
+
36
+ 1. [[researcher]] — Find three leads for the request.
37
+ 2. [[writer]] — Write them up as a short list.
38
+ ```
39
+
40
+ | key | |
41
+ |---|---|
42
+ | `publish` | required, `true` or `false`. `false` keeps the block and serves nothing |
43
+ | `name` | the card's (and its one skill's) name, up to 100 characters. Unset: the flow's name |
44
+ | `description` | what a caller reads about it, up to 2,000 characters. Unset: the flow's `description:` |
45
+ | `examples` | up to 10 example requests, 500 characters each |
46
+ | `public_card` | `true` lets anyone read the card without a key. Calling the flow always needs one. Default `false` |
47
+ | `input` | a JSON Schema (up to 16,000 bytes as JSON). With it, every request must carry a data part that matches it, and a request that does not is refused before anything starts |
48
+
49
+ A block `foldrun check` cannot read publishes nothing — a typo never opens a
50
+ flow nobody meant to open. Whether a flow is published is the workspace's
51
+ policy, so changing `a2a:` needs the **admin** role (`workspace:manage`) by
52
+ every door: the editor, a deploy, `PATCH /flows/<f>`, `PUT /source`. An
53
+ editor's change that leaves `a2a:` as it was goes through.
54
+
55
+ From the dashboard: **Flows**, the flow's card, **Publish over A2A…**
56
+ (admins only; others see it read-only) — it edits the block through
57
+ `PATCH /api/workspaces/<ws>/flows/<f>` `{ a2a: {…} }` (merged over what the
58
+ flow says: a key sent replaces it, `null` removes it, `a2a: null` removes the
59
+ block) and shows the card URL and a `curl` to try it. From the terminal:
60
+
61
+ ```sh
62
+ foldrun a2a publish lead-finder --to sales --name "Lead researcher" --description "Finds three leads"
63
+ foldrun a2a card lead-finder --to sales # the card URL, and the card
64
+ foldrun a2a ls --to sales # what the workspace serves, and its recent tasks
65
+ foldrun a2a unpublish lead-finder --to sales
66
+ ```
67
+
68
+ The workspace's **Triggers** page, section **Outside agents (A2A)** (and
69
+ `GET /api/workspaces/<ws>/a2a`), lists every
70
+ flow that says `a2a:`, its card and endpoint URLs, the workspace's A2A keys and
71
+ the newest tasks with the key that asked.
72
+
73
+ `foldrun check` warns on a published flow that is risky to open
74
+ ([below](#security)).
75
+
76
+ ## A2A keys
77
+
78
+ A caller needs an **A2A key**: a key of its own kind, minted by an admin of
79
+ the workspace, for one workspace and the flows it names.
80
+
81
+ ```sh
82
+ foldrun keys create "Partner CRM" --a2a --to sales --flows lead-finder,quote --max-tasks 5
83
+ ```
84
+
85
+ or **Settings → API keys**, kind **A2A key**: the workspace, the published
86
+ flows it may call, and how many tasks it may have open at once. The key is
87
+ shown once.
88
+
89
+ - It opens `/a2a/<account>/<workspace>/…` for its flows and nothing else.
90
+ Every `/api` route refuses it (`403`): not runs, not source, not approvals,
91
+ not storage, not secrets.
92
+ - A flow must be both **named by the key** and **published**. Both are read
93
+ on every call, so unpublishing a flow closes it to every key at once.
94
+ - `maxTasks` — its tasks open at once, 1 to 100, default 10. Past it,
95
+ `SendMessage` is refused with `TOO_MANY_TASKS` until one ends or is
96
+ canceled.
97
+ - It expires, is revoked and is rotated like any key (`expires`,
98
+ `foldrun keys rotate`). A task belongs to the key that made it; a rotated
99
+ key keeps its predecessor's tasks, so the caller can still read and cancel
100
+ them.
101
+ - It counts in its account's rate limit with its own bucket, like any key.
102
+
103
+ The API: `POST /api/keys { purpose: "a2a", workspace, flows, maxTasks?, label?, expires? }`
104
+ ([api](api#account)).
105
+
106
+ ## Calling a published flow
107
+
108
+ Each published flow has three addresses. `<account>` is your account's name;
109
+ the flow's page and `foldrun a2a card` show them whole.
110
+
111
+ | | |
112
+ |---|---|
113
+ | `GET /a2a/<account>/<ws>/flows/<flow>/.well-known/agent-card.json` | the agent card: name, description, examples, the endpoint, `streaming: false`, `pushNotifications: false`, and the bearer scheme. With a key that names the flow, or without one when `public_card: true` |
114
+ | `POST /a2a/<account>/<ws>/flows/<flow>` | the JSON-RPC endpoint |
115
+ | `GET /a2a/<account>/<ws>` | the flows this key may call here, each with its card and endpoint — a convenience index, not an A2A operation |
116
+
117
+ Every call sends the key as `Authorization: Bearer mda_…` and the protocol
118
+ version as `A2A-Version: 1.0` (or `?A2A-Version=1.0`). A request without the
119
+ header is A2A 0.3, which is not served: it is answered
120
+ `VersionNotSupportedError` (`-32009`). A session cookie never opens `/a2a`.
121
+
122
+ Send a request:
123
+
124
+ ```sh
125
+ curl -sS https://foldrun.example.com/a2a/acme/sales/flows/lead-finder \
126
+ -H "authorization: Bearer $A2A_KEY" \
127
+ -H "a2a-version: 1.0" \
128
+ -H "content-type: application/json" \
129
+ -d '{
130
+ "jsonrpc": "2.0", "id": 1, "method": "SendMessage",
131
+ "params": {
132
+ "message": {
133
+ "messageId": "req-2026-11-01-001",
134
+ "role": "ROLE_USER",
135
+ "parts": [
136
+ { "text": "Dentists, please." },
137
+ { "data": { "city": "Perth" }, "mediaType": "application/json" }
138
+ ]
139
+ },
140
+ "configuration": { "returnImmediately": true }
141
+ }
142
+ }'
143
+ ```
144
+
145
+ The answer is the task:
146
+
147
+ ```json
148
+ { "jsonrpc": "2.0", "id": 1, "result": { "task": {
149
+ "id": "6f0c…", "contextId": "b41e…",
150
+ "status": { "state": "TASK_STATE_SUBMITTED", "timestamp": "2026-11-01T09:00:00.000Z" },
151
+ "history": [ { "messageId": "req-2026-11-01-001", "role": "ROLE_USER", "parts": [ … ] } ]
152
+ } } }
153
+ ```
154
+
155
+ Then poll it until it ends:
156
+
157
+ ```sh
158
+ curl -sS https://foldrun.example.com/a2a/acme/sales/flows/lead-finder \
159
+ -H "authorization: Bearer $A2A_KEY" -H "a2a-version: 1.0" -H "content-type: application/json" \
160
+ -d '{"jsonrpc":"2.0","id":2,"method":"GetTask","params":{"id":"6f0c…"}}'
161
+ ```
162
+
163
+ From the terminal, `foldrun a2a call <card-url> "<text>" [--data '{"city":"Perth"}'] [--key-env A2A_KEY]`
164
+ does the same against any A2A 1.0 agent, and `foldrun a2a status|cancel <task-id> --card <url>`
165
+ follows one.
166
+
167
+ ### What is served
168
+
169
+ | method | |
170
+ |---|---|
171
+ | `SendMessage` | starts the flow. **Blocking by default**: it waits up to 25 seconds (`FOLDRUN_A2A_WAIT_MS`, at most 120) for the run to end, then answers the task as it stands — the caller polls `GetTask` from there. `configuration.returnImmediately: true` answers at once. `configuration.historyLength` trims the history. `acceptedOutputModes` must include `text/plain` or `application/json` (or a wildcard) |
172
+ | `GetTask` | the task by `id`, with `historyLength` |
173
+ | `ListTasks` | this key's tasks on this flow, newest state change first: `pageSize` (1–100, default 50), `pageToken`, `status` (a `TASK_STATE_*`), `contextId`, `statusTimestampAfter`, `includeArtifacts`, `historyLength`. Answers `tasks`, `nextPageToken` (empty on the last page), `pageSize`, `totalSize` |
174
+ | `CancelTask` | stops the run; its trail says "cancelled by A2A caller <key label>". Idempotent: a canceled task canceled again is answered as it is. A task that already ended otherwise is `TaskNotCancelableError` (`-32002`), and so is one still starting (try again in a moment) |
175
+
176
+ Not served, each answered with the error the spec names: `SendStreamingMessage`
177
+ and `SubscribeToTask` (`UnsupportedOperationError`, `-32004` — poll instead),
178
+ the four push-notification methods and a `taskPushNotificationConfig` on a
179
+ send (`PushNotificationNotSupportedError`, `-32003`), and
180
+ `GetExtendedAgentCard` (`-32004`). An unknown method is `-32601`. Batches are
181
+ not taken: one request object per call.
182
+
183
+ A task takes **one message**. A follow-up `SendMessage` with the task's
184
+ `taskId` is refused (`-32004`); send a new message without `taskId`, with the
185
+ `contextId` to keep the conversation together.
186
+
187
+ ### Retries: `messageId`
188
+
189
+ `messageId` is the request's identity. Send the same message again with the
190
+ same `messageId` — after a timeout, a dropped connection — and you get the
191
+ task it already made; nothing starts twice. The same `messageId` with a
192
+ different message (other parts, context or metadata) is refused
193
+ (`-32602`, `InvalidParams`): a new message needs a new id. The JSON-RPC `id`
194
+ is only correlation and plays no part. A refused start (busy, paused, out of
195
+ funds) makes no task, so the same message may be sent again later as it is.
196
+
197
+ ### What a request may carry
198
+
199
+ Text and JSON only. At most 16 parts; the text parts together at most 32,000
200
+ characters; one data part (`application/json`) of at most 64,000 bytes; a
201
+ request body at most 1 MiB. A `raw` or `url` part (a file) is refused with
202
+ `ContentTypeNotSupportedError` (`-32005`). With `input:`, the data part must
203
+ match the schema, and the refusal names each field that does not.
204
+
205
+ The request reaches the flow's first step fenced and marked as coming from an
206
+ outside agent — data to work on, not instructions that change the agent's
207
+ role, tools or limits.
208
+
209
+ ### Task states
210
+
211
+ | the run | the task |
212
+ |---|---|
213
+ | queued, not started | `TASK_STATE_SUBMITTED` |
214
+ | running, waiting (`wait:`), parked for a person | `TASK_STATE_WORKING` |
215
+ | completed | `TASK_STATE_COMPLETED` |
216
+ | failed | `TASK_STATE_FAILED` |
217
+ | stopped (by `CancelTask` or a person) | `TASK_STATE_CANCELED` |
218
+
219
+ **A person's part stays with your people.** A step with an approval (`!`),
220
+ an `ask:`, or an agent asking a question (`tools: [ask]`) shows the caller
221
+ `TASK_STATE_WORKING` with the status message "waiting for a person" — never
222
+ who, never a link, never an address. No A2A call can approve, reject or
223
+ answer: those are your team's, in the dashboard, the inbox or the emailed
224
+ link, as for any run. A blocking `SendMessage` waits through a gate only as
225
+ long as its bound, then answers WORKING.
226
+
227
+ On `TASK_STATE_COMPLETED` the task carries one artifact, `result`: the
228
+ flow's final result as a text part (`text/plain`, at most 64,000 characters),
229
+ and a data part (`application/json`, at most 256,000 bytes) when the last
230
+ step answered `output: json`. Nothing else of the run is shown — no run id,
231
+ steps, agents, costs, approvers or files. No files go out, no stream, no push.
232
+
233
+ ### Errors
234
+
235
+ Errors are JSON-RPC error objects with a `google.rpc.ErrorInfo` in `data`. A
236
+ request foldrun cannot take **now** is `-32000` with a foldrun reason:
237
+
238
+ | reason | |
239
+ |---|---|
240
+ | `BUSY` | the flow is `overlap: skip` and a run is live — send the same message later |
241
+ | `PAUSED` | the workspace or account is paused |
242
+ | `UNAVAILABLE` | out of budget or funds, or otherwise not taking work |
243
+ | `RATE_LIMITED` | the key's rate limit (`429` from the proxy carries `Retry-After`) |
244
+ | `TOO_MANY_TASKS` | the key has `maxTasks` open |
245
+ | `UNAUTHENTICATED` | no key, or a wrong, revoked or expired one (HTTP `401`) |
246
+ | `PERMISSION_DENIED` | a key that is not an A2A key (HTTP `403`) |
247
+ | `AGENT_NOT_FOUND` | the flow is not published, not named by the key, or not there — all alike (HTTP `404`) |
248
+
249
+ A task of another key, flow or workspace is `TaskNotFoundError` (`-32001`),
250
+ never "not yours".
251
+
252
+ A run started over A2A goes through the same admission as one started from
253
+ the dashboard: pause, money, `budget:`, plan limits and `overlap:` hold for an
254
+ outside agent exactly as for a person. In the runs list and on the run page
255
+ it shows **A2A · <key label>**.
256
+
257
+ ## Calling outside agents: `remotes:`
258
+
259
+ An agent of yours may call A2A agents somebody else runs. You list them; the
260
+ agent calls them by name.
261
+
262
+ ```yaml
263
+ ---
264
+ name: buyer
265
+ remotes:
266
+ - name: invoice-checker
267
+ card: https://agents.example.com/.well-known/agent-card.json
268
+ secret: INVOICE_AGENT_TOKEN # optional: a vault NAME, sent as a bearer token
269
+ description: Checks an invoice against its purchase order.
270
+ limits: { a2a: 10 }
271
+ ---
272
+ ```
273
+
274
+ It gets four tools — `a2a_send`, `a2a_status`, `a2a_reply`, `a2a_cancel` —
275
+ that work by **handle**: a send answers a handle at once and waits a bounded
276
+ time (default 60 seconds, at most 300) for the answer; a wait that runs out
277
+ says "still running", and `a2a_status` picks it up. A slow remote is never
278
+ sent the request twice. The model never sees the card URL or the token.
279
+
280
+ - The card's own site joins the agent's [network](network), and nothing the
281
+ card says does: a card whose interface is at another origin is refused.
282
+ - The secret is bound to the card's origin and filled by the egress proxy on
283
+ the way out; it never enters the sandbox.
284
+ - What a remote answers is untrusted — fenced as data from someone else's
285
+ system.
286
+ - `limits: {a2a: N}` caps the messages a step sends; `a2a.status` caps
287
+ polling apart from sending.
288
+ - Test runs send nothing.
289
+
290
+ Every field and rule is in [agents](agents#calling-an-outside-agent-remotes).
291
+
292
+ ## Limits
293
+
294
+ | | |
295
+ |---|---|
296
+ | card name / description | 100 / 2,000 characters |
297
+ | examples | 10, of 500 characters each |
298
+ | `input:` schema | 16,000 bytes as JSON |
299
+ | a request | 16 parts; 32,000 characters of text; one data part of 64,000 bytes; 1 MiB body |
300
+ | a result | 64,000 characters of text; 256,000 bytes of JSON |
301
+ | an A2A key | up to 50 flows; 1–100 tasks open (default 10) |
302
+ | a blocking `SendMessage` | 25 s by default, at most 120 s (`FOLDRUN_A2A_WAIT_MS`) |
303
+ | `ListTasks` | 100 a page |
304
+ | a calling step | 50 messages and 600 polls, whatever `limits:` says |
305
+
306
+ Ended tasks are kept 90 days.
307
+
308
+ ## Security
309
+
310
+ - **Everything a caller sends is untrusted input.** It reaches the first step
311
+ as data, fenced; your tool grants, network, bound secrets and human gates
312
+ hold whatever it says. Publishing does not widen what an agent may do — it
313
+ widens who can ask.
314
+ - **`foldrun check` warns on two shapes** of published flow (warnings, not
315
+ errors): [`security/published-flow-trifecta`](checks#securitypublished-flow-trifecta)
316
+ — a step agent that holds something private and has a way out, which a
317
+ caller could steer into sending it; and
318
+ [`security/published-flow-ungated`](checks#securitypublished-flow-ungated)
319
+ — a step that acts outside the workspace with no approval or `ask:` before
320
+ it, which any key holder starts. Put a gate (`2!.`) on it, or take a leg
321
+ away.
322
+ - **A public card is metadata only**: the name, description and examples you
323
+ wrote, the endpoint and the auth scheme — never steps, agents or files.
324
+ It never lets anyone call the flow. Anonymous card reads are rate-limited.
325
+ Without a key, a private card and no card answer the same `401`.
326
+ - **Tokens never enter a sandbox**, in either direction: an A2A key is
327
+ checked at the edge and never reaches the run; a remote's secret is filled
328
+ by the egress proxy for that remote's origin alone.
329
+ - **Nothing a caller does reaches your people's decisions.** Approvals and
330
+ questions stay in foldrun; the caller sees only "waiting for a person".
package/docs/agents.md CHANGED
@@ -96,6 +96,7 @@ the point of the week; a step that weighs two arguments and picks one is not.
96
96
  | `hooks` | your own code at every tool call, step start and step end — refuse, rewrite, add context — the same on every model ([Hooks](hooks)). Also in a workspace's or the account's `AGENTS.md` for every agent under it |
97
97
  | `apis` | an HTTP API declared inline, as one tool |
98
98
  | `mcpServers` | an MCP server declared inline |
99
+ | `remotes` | outside agents it may call over A2A — `[{name, card, secret?, description?}]`: the four `a2a_*` tools, and each card's own site added to its network ([below](#calling-an-outside-agent-remotes)) |
99
100
  | `secrets` | vault entries its tools may use — names only, never values. The names the step's own model call uses (`ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_CUSTOM_HEADERS`, the `ANTHROPIC_*_MODEL` tiers, `CLAUDE_CODE_OAUTH_TOKEN`, `FOLDRUN_MODEL_KEY`) never replace the model's own settings, and `foldrun check` warns: script and API tools and `verify:` get the declared value under that name, but the agent's own shell sees the model's — give it another name (`MY_ANTHROPIC_KEY`), or run the model on it with `provider:` |
100
101
  | `limits` | the most calls one step may make — per tool, per web action, or in all: `limits: {web.search: 40, crm: 20, calls: 300, repeat: 5}` (`repeat`: the same call with the same input). A call past a limit is refused, never run ([Tools](tools#limits--how-many-calls-a-step-may-make)) |
101
102
  | `network` | which sites its sandbox may reach: `open`, `trusted` or `none`, or a list of sites added to the trusted list — `network: [api.hubapi.com]`. Unset, an agent that may fetch or browse the web is `open` and every other `trusted`. Also in a workspace's or the account's `AGENTS.md` ([Network](network)) |
@@ -209,6 +210,82 @@ tools:
209
210
  `{bash: ask}` is accepted for per-call approval in Claude Code; platform runs
210
211
  disable ask-mode and log that they did.
211
212
 
213
+ ## Calling an outside agent: `remotes:`
214
+
215
+ An agent can hand a request to an agent somebody else runs, over the
216
+ Agent2Agent protocol (A2A 1.0, JSON-RPC). You name the remote; the agent
217
+ calls it by that name and never sees a URL or a token.
218
+
219
+ ```yaml
220
+ remotes:
221
+ - name: invoice-checker
222
+ card: https://agents.example.com/.well-known/agent-card.json
223
+ secret: INVOICE_AGENT_TOKEN # optional: a vault NAME, sent as a bearer token
224
+ description: Checks an invoice against its purchase order.
225
+ ```
226
+
227
+ | key | |
228
+ |---|---|
229
+ | `name` | kebab-case — what the agent calls it by |
230
+ | `card` | the https URL of the remote's agent card. Plain http, to `localhost` only, is for a laptop (or an install whose operator set `FOLDRUN_EGRESS_ALLOW_PRIVATE=1`); a hosted install calls https cards only, and never a private or internal address |
231
+ | `secret` | optional — the NAME of a vault secret, sent as `Authorization: Bearer …` to the card's origin and nowhere else |
232
+ | `description` | your words for it, the only text about the remote in the agent's prompt (the card's own text is the remote's, and is not trusted) |
233
+
234
+ It gives the agent four tools:
235
+
236
+ | tool | |
237
+ |---|---|
238
+ | `a2a_send(remote, text, data?, wait_seconds?)` | sends one request (text, and JSON as a data part) and waits, at most `wait_seconds` (default 60, at most 300), for the answer. Returns a handle with the answer or where the remote got to |
239
+ | `a2a_status(handle, wait_seconds?)` | where it got to, and the answer once it is done |
240
+ | `a2a_reply(handle, text, data?)` | answers a remote that asked for more (`input-required`) |
241
+ | `a2a_cancel(handle)` | asks the remote to stop; safe to repeat |
242
+
243
+ A slow remote is never sent the request twice. The remote's task id is kept
244
+ (in `workspace/state/a2a/<agent>/`) before any waiting starts, so a wait that
245
+ runs out says "still running" with the handle, and `a2a_status` picks it up —
246
+ in the same step, a retry of it, or a later step of the same run. The same
247
+ request asked again in a step returns its handle. A request that ended without
248
+ success may be sent again on purpose.
249
+
250
+ What it may reach and send:
251
+
252
+ - **Network.** Each card's own site joins the agent's [network](network), and
253
+ nothing the card says does: a card whose JSON-RPC interface is at another
254
+ origin is refused, and a redirect is never followed.
255
+ - **The secret** is granted to the card's origin at the egress proxy, which
256
+ fills it on the way out; it never enters the sandbox, even for a step whose
257
+ scripts get their secrets as values. On a laptop (`foldrun run`) it reaches
258
+ the four tools alone: no script, shell or consulted colleague sees it. Name
259
+ it under the agent's own `secrets:` too only if a script really needs it. A secret the vault binds to other sites
260
+ is not sent to a remote outside them — that remote is not called.
261
+ - **Size.** A card is read to 64 KiB and an answer to 1 MiB. Text and JSON
262
+ only: a file part in an answer is named, never fetched.
263
+ - **Untrusted.** What a remote answers reaches the model fenced as data from
264
+ another organisation's system, with invisible characters removed. An agent
265
+ with `remotes:` counts as reading untrusted content in the
266
+ [lethal-trifecta check](checks#securitylethal-trifecta).
267
+ - **Limits.** `limits: {a2a: 10}` caps the messages a step sends (`a2a_send`
268
+ and `a2a_reply`); `a2a.status`, `a2a.send`, `a2a.reply` and `a2a.cancel` cap
269
+ each tool alone, so polling is capped apart from sending. A step sends at
270
+ most 50 messages and polls at most 600 times whatever `limits:` says.
271
+ - **Test runs** send nothing: `a2a_send`, `a2a_reply` and `a2a_cancel` say
272
+ what they would have sent.
273
+ - **Retries.** An agent with `remotes:` acts outside the workspace, like one
274
+ holding an `outward: true` tool: a step that called a tool and then failed
275
+ its `verify:` or `output:` check is not run again on its own, so the work is
276
+ not asked for twice in other words.
277
+
278
+ `permissionMode: plan` withholds the four tools.
279
+
280
+ remotes: are not available to shared-sandbox sub-agents yet; give the
281
+ sub-agent `sandbox: own` or call the remote from the parent. A sub-agent
282
+ delegated to inside its parent's step (the default, `sandbox: parent`) never
283
+ gets the `a2a_*` tools — they are the parent's, with the parent's remotes and
284
+ credentials — and a call to one is refused; the step's trace and the
285
+ sub-agent's prompt say so when it declares `remotes:`. A `sandbox: own`
286
+ sub-agent runs each job as a step of its own and gets its own `remotes:`, from
287
+ its own file, with its own secrets and network.
288
+
212
289
  ## Consulting colleagues
213
290
 
214
291
  ```yaml
package/docs/api.md CHANGED
@@ -143,7 +143,8 @@ installer's `error`, its cause on the first line. `foldrun deploy` polls it afte
143
143
  | Route | Methods | |
144
144
  |---|---|---|
145
145
  | `/api/workspaces/<ws>/flows` | GET, POST | list; create (`name`, `pattern`) |
146
- | `/api/workspaces/<ws>/flows/<flow>` | POST, PATCH, DELETE | 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), a canvas edit (`edit`, or `edits` — at most 200 in one request, `400` past that), undo (`restore` + `expect`); delete. 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") |
146
+ | `/api/workspaces/<ws>/a2a` | GET | what this workspace serves to outside agents over A2A 1.0: `{ flows: [{ flow, published, publicCard, name, description, hasInputSchema, card, url }], keys, tasks: [{ id, flow, state, runId, contextId, key: { id, label, prefix, revoked }, createdAt, updatedAt }] }` — every flow whose frontmatter says `a2a:`, 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 |
147
+ | `/api/workspaces/<ws>/flows/<flow>` | POST, PATCH, DELETE | 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 }` 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 — see [A2A](a2a.md)), a canvas edit (`edit`, or `edits` — at most 200 in one request, `400` past that), undo (`restore` + `expect`); delete. 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") |
147
148
  | `/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>` |
148
149
  | `/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 |
149
150
  | `/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 |
@@ -350,7 +351,7 @@ Reads return which secrets exist, never their values.
350
351
 
351
352
  | Route | Methods | |
352
353
  |---|---|---|
353
- | `/api/keys` | GET, POST, DELETE | API keys — an admin's (`keys:manage`) to list, mint and revoke; any key may revoke itself (DELETE with its own `id`, audited as self — what `foldrun logout` does). POST `label`, `role` (viewer \| editor \| admin, never above your own, default editor), `workspaces` (names, or `null` for all — never wider than your own scope); `expires` (`30d`, `90d`, `365d`, any number of days up to 3650, or `never` — the default; anything else is a 400, never a key that lives forever); returns `{ ok, key, id, prefix, role, workspaces, expiresAt }`, and the key is shown once. GET lists each key with `createdAt`, `createdBy`, `expiresAt`, `lastUsedAt`, `lastIp` and `replacedBy` (the id of the key a rotation replaced it with; `null` until then) — the last-use pair written at most once a minute per key, the address cut to its /24 (IPv4) or /48 (IPv6). A key past its `expiresAt` is refused with 401 `API key expired on <date>`; the owner is emailed seven days before. Mint, revoke and rotate are written to the audit log. POST with `workspace` or `access` is refused (400): those minted deploy keys for the platform's own git, which went on 17 Oct 2026 — a deploy key minted before is refused everywhere (403). A key for one workspace is `workspaces: ["<ws>"]`. DELETE `id`. `?tenant=` / body `tenant` is read only on an install with no users yet (first-run bootstrap), and there, when the install has a setup token (`FOLDRUN_SETUP_TOKEN`, written by the self-hosting installer), only with that token in `X-Foldrun-Setup-Token` |
354
+ | `/api/keys` | GET, POST, DELETE | API keys — an admin's (`keys:manage`) to list, mint and revoke; any key may revoke itself (DELETE with its own `id`, audited as self — what `foldrun logout` does). POST `label`, `role` (viewer \| editor \| admin, never above your own, default editor), `workspaces` (names, or `null` for all — never wider than your own scope); `expires` (`30d`, `90d`, `365d`, any number of days up to 3650, or `never` — the default; anything else is a 400, never a key that lives forever); returns `{ ok, key, id, prefix, role, workspaces, expiresAt }`. POST `{ purpose: "a2a", workspace, flows, maxTasks?, label?, expires? }` mints an A2A key instead: for an outside agent, it opens `/a2a/<account>/<workspace>/…` for the named flows (each must also say `a2a: { publish: true }`) and every `/api` route refuses it (403); `maxTasks` (1–100, default 10) caps its tasks open at once; it answers `{ ok, key, id, prefix, purpose, workspace, flows, maxTasks, role, workspaces, expiresAt }`, and rotating one keeps the tasks it made, and the key is shown once. GET lists each key with `createdAt`, `createdBy`, `expiresAt`, `lastUsedAt`, `lastIp` and `replacedBy` (the id of the key a rotation replaced it with; `null` until then) — the last-use pair written at most once a minute per key, the address cut to its /24 (IPv4) or /48 (IPv6). A key past its `expiresAt` is refused with 401 `API key expired on <date>`; the owner is emailed seven days before. Mint, revoke and rotate are written to the audit log. POST with `workspace` or `access` is refused (400): those minted deploy keys for the platform's own git, which went on 17 Oct 2026 — a deploy key minted before is refused everywhere (403). A key for one workspace is `workspaces: ["<ws>"]`. DELETE `id`. `?tenant=` / body `tenant` is read only on an install with no users yet (first-run bootstrap), and there, when the install has a setup token (`FOLDRUN_SETUP_TOKEN`, written by the self-hosting installer), only with that token in `X-Foldrun-Setup-Token` |
354
355
  | `/api/keys/<id>/rotate` | POST | a new key with the old one's label, role, workspaces and deploy scope — and, when it had an end, the same lifetime from today — returned once like a mint (`{ ok, key, id, prefix, role, workspaces, expiresAt, replaced: { id, endsAt } }`). `grace`: `0` (default — the old key is revoked at once), or a duration up to `7d` such as `1h` or `24h`, during which the old key still works and after which it is refused as expired. A key is rotated once: rotating a key already replaced is 409 `this key was already rotated to <prefix>…; rotate that one` — and someone who lost the new key's secret rotates the NEW key, which mints another and ends the lost one (rotating the old one again would leave the lost key working). Two rotations of one key at once mint one key. `keys:manage`; a key outside the caller's scope is 404 — except that a key `foldrun login` minted may rotate **itself**, whatever its role: same label, role, workspaces and 90-day lifetime from today, the old key ending 10 minutes later (`grace` is not read). A retry with the old key inside those 10 minutes — the CLI lost the answer, or could not store it — rotates that replacement instead, when nobody has used it and it is at least 30 seconds old (a younger one is a 409: another command may have just stored it). That is how the CLI renews its sign-in; any other key rotating itself still needs `keys:manage`. Audited as `apikey.rotated` (`self: true` for a self-rotation) |
355
356
  | `/api/team` | GET, POST | members with their roles and workspace scope; mint an invite — `role` (viewer \| editor \| admin, default editor), `workspaces` (names, or omit for all), `email` (only that address can accept it; sent through the account's `RESEND_API_KEY` unless `send: false`). An invite works **once**, for seven days, and a newer invite to the same address revokes the older ones still pending. Returns `id`, `path` (the invite's relative URL, shown only here), `expires`, `sent` and any `sendError` either way; the full link is in the mail. Links made before 29 Oct 2026 (`inv1`–`inv3`) are refused |
356
357
  | `/api/team/invites?all=1` | GET | the account's invites, newest first — pending ones unless `all=1` (then accepted, revoked and expired too): `{ invites: [{ id, email, role, workspaces, invitedBy, createdAt, expiresAt, status }] }`, `email` `null` for a link anyone may use, `workspaces` `null` for all, `status` `pending` \| `accepted` \| `revoked` \| `expired`. Never the link. `team:manage` — an admin key included; a caller scoped to some workspaces sees only the invites inside its scope |
@@ -507,3 +508,20 @@ signed-in person, never by a key — mints an ordinary API key at their role.
507
508
  | `/api/approve/<tenant>/<ws>/<id>?token=` | GET, POST | decide a run parked on a human, from the link in its notification. GET shows what is waiting and two buttons — it never decides, because inbox link-checkers follow GETs. POST `decision` (`approve` or `reject`) and an optional `note`, form-encoded or JSON; answers JSON when `Accept` prefers it. The token is derived from the run id under the install key, not stored, so a key rotation kills every link. Needs `FOLDRUN_PUBLIC_URL` to be minted at all |
508
509
  | `/api/workspaces/<ws>/hooks/<flow>` | GET | read the flow's webhook URL without changing it: `{ ok, flow, path, url }` — `path` carries the token, `url` is it made absolute with `FOLDRUN_PUBLIC_URL` (null when that is unset). `workspace:manage`, as rotate and the settings page that shows it, since the URL is a credential. `404` for no such flow, `409` for a flow that is not `trigger: webhook` |
509
510
  | `/api/workspaces/<ws>/hooks/<flow>/rotate` | POST | new token, old URLs stop working. `404` for no such flow, `409` for a flow that is not `trigger: webhook`, as GET `…/hooks/<flow>` answers |
511
+
512
+ ## A2A — outside agents calling a published flow
513
+
514
+ Outside `/api`, and opened only by an **A2A key** (`Authorization: Bearer mda_…`,
515
+ minted with `POST /api/keys { purpose: "a2a", … }`) — never a session, never an
516
+ API key. They speak [A2A 1.0](a2a) over JSON-RPC 2.0, not this API: no
517
+ `Foldrun-Version` (the route answers `A2A-Version: 1.0` instead, and a call
518
+ without it is refused as 0.3), errors are JSON-RPC error objects, and the
519
+ proxy holds the same raw-path check, body limit (1 MiB), rate limit and
520
+ cross-site rule as for `/api`. A flow the key does not name, or that is not
521
+ published, is `404` like one that does not exist.
522
+
523
+ | Route | Methods | |
524
+ |---|---|---|
525
+ | `/a2a/<account>/<ws>/flows/<flow>/.well-known/agent-card.json` | GET | the flow's agent card — with an A2A key naming the flow, or with none when the flow says `a2a: { public_card: true }` (`Cache-Control: public, max-age=300` then; `private, max-age=60` otherwise; an `ETag`, so `If-None-Match` answers `304`). Without a key every other card is the same `401` |
526
+ | `/a2a/<account>/<ws>/flows/<flow>` | POST | one JSON-RPC call: `SendMessage`, `GetTask`, `ListTasks`, `CancelTask`. Streaming, push notifications and the extended card are answered with the spec's unsupported errors ([what is served](a2a#what-is-served)) |
527
+ | `/a2a/<account>/<ws>` | GET | `{ agents: [{ flow, name, description, card, url }] }` — the published flows this key may call here. A convenience index, not an A2A operation |
package/docs/checks.md CHANGED
@@ -254,11 +254,14 @@ and is not flagged.
254
254
  ### security/lethal-trifecta
255
255
 
256
256
  *warn · ASI01, ASI02, ASI03.* One agent that **reads untrusted content** (the
257
- `web` tool, or a browse/fetch/scrape tool), **holds something private** (a
258
- secret, an `apis:` entry, an MCP server) and **has a way out** (an open
259
- network, which is the default for an agent that reads the web, a tool marked
260
- `outward: true`, or an API it may POST, PUT, PATCH or DELETE to). Any page it
261
- reads can tell it to send what it holds anywhere it can reach.
257
+ `web` tool, a browse/fetch/scrape tool, or the replies of outside agents it
258
+ calls through `remotes:`), **holds something private** (a secret, an `apis:`
259
+ entry, an MCP server) and **has a way out** (an open network, which is the
260
+ default for an agent that reads the web, a tool marked `outward: true`, an
261
+ API it may POST, PUT, PATCH or DELETE to, or an outside agent it may send to).
262
+ Any page or reply it reads can tell it to send what it holds anywhere it can
263
+ reach. A remote's own secret is not counted as private: the egress proxy
264
+ fills it for that remote's origin alone, and the agent never holds it.
262
265
 
263
266
  Take a leg away:
264
267
  - take it off the open network: `network: { level: trusted, allow:
@@ -289,6 +292,26 @@ sandbox of its own, with its own tools, secrets and network, and only its
289
292
  reply reaches the parent. The finding says what it holds, so the choice
290
293
  stays visible ([agents](agents#isolated-sub-agents-sandbox-own)).
291
294
 
295
+ ### security/published-flow-trifecta
296
+
297
+ *warn · ASI01, ASI02, ASI03.* A flow published over A2A (`a2a: {publish:
298
+ true}`) runs a step whose agent holds something private and has a way out —
299
+ the trifecta above, with the outside caller as the untrusted content: what a
300
+ caller sends reaches every step. Take a leg away from that agent (the same
301
+ three ways as above), or do not publish the flow. A warning, like every new
302
+ rule; `deploy_block: security` makes it refuse a deploy.
303
+
304
+ ### security/published-flow-ungated
305
+
306
+ *warn · ASI02, ASI09.* A flow published over A2A has a step that acts outside
307
+ the workspace — an `outward: true` tool, an API it may write to, or a message
308
+ to an outside agent (`remotes:`) — with no approval (`!`) and no `ask:` on it,
309
+ on a step beside it in its group (a gate there holds the whole group), or on a
310
+ step before it. Anyone holding a key for the flow can start it as
311
+ often as the key allows, so put a person in the way: a `!` on the first such
312
+ step, or on one before it. A `verify:` does not count here; it checks the step
313
+ after it acted.
314
+
292
315
  ### flow/outward-ungated
293
316
 
294
317
  *the step's level · ASI02, ASI09.* A step whose agent holds an `outward:
package/docs/cli.md CHANGED
@@ -173,6 +173,13 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
173
173
  | `foldrun use <name>` | act as one of them from here on. `foldrun switch <name>` is the same command |
174
174
  | `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
175
  | `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 |
176
+ | `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 |
177
+ | `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 |
178
+ | `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 |
179
+ | `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` |
180
+ | `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 |
181
+ | `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 |
182
+ | `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
183
  | `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
184
 
178
185
  ## Options
@@ -222,7 +229,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
222
229
  | `--step <n>` | `approve`, `reject`: decide one gate, numbered as `report` prints it. Without it, every step of that run which is waiting |
223
230
  | `--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
231
  | `--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
- | `--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`, `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 |
232
+ | `--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
233
  | `--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
234
  | `--events <a,b>` | `account set notify`: which events are notified on — `failed`, `awaiting-approval`, `completed` |
228
235
  | `--watch` | `invoke`: follow the run's trace here as it happens; the exit code is the run's |
@@ -243,6 +250,9 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
243
250
  | `--role <r>` | `keys create`: `viewer`, `editor` (default) or `admin` |
244
251
  | `--expires <span>` | `keys create`: when it stops working — `30d`, `90d`, `365d` or `never` (default) |
245
252
  | `--grace <span>` | `keys rotate`: keep the old key working for `1h` or `24h` (default `0`: revoked now) |
253
+ | `--a2a` | `keys create`: an A2A key for an outside agent, with `--to <workspace>`, `--flows a,b` and optionally `--max-tasks <n>` |
254
+ | `--key-env <NAME>` | `a2a call`, `a2a status`, `a2a cancel`, `a2a card`: the environment variable that holds the A2A key (default `FOLDRUN_A2A_KEY`) |
255
+ | `--card <url>` | `a2a status`, `a2a cancel`: the agent card of the agent that holds the task |
246
256
  | `--force` | `deploy`: deploy while runs are in flight. `pull`, `storage get`: overwrite local files |
247
257
  | `--no-runtimes` | `deploy`: do not wait for the workspace's environments to be built, or print them |
248
258
  | `--platform` / `--yes` | `workspaces rm`: delete it on the platform, said twice because it cannot be undone |
@@ -257,7 +267,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
257
267
  | `--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
268
  | `--local` | `deploy`, `secrets`, `logs`: the installation on this machine, even when signed in |
259
269
  | `--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 |
270
+ | `--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
271
  | `--out <file>` | `api spec`: where to write the OpenAPI document (default stdout) |
262
272
  | `--file <path>` | `source put`: the file to send. `storage get`, `report get`, `account export`, `billing statement --csv`: where to write — `-` for stdout |
263
273
 
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/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
- and the sites its [secrets are bound to](secrets#bound-to-sites). You never list
28
- those twice.
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.
@@ -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) — need
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.1.0",
3
+ "version": "10.2.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.0.0"
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-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",
package/src/commands.mjs CHANGED
@@ -4278,6 +4278,7 @@ async function doctor(flags) {
4278
4278
  * keys create <label> --workspaces <ws> one that opens that workspace alone
4279
4279
  * keys revoke <id>
4280
4280
  * keys create <label> --expires 90d it stops working in 90 days (30d, 365d, never)
4281
+ * keys create <label> --a2a --to <ws> --flows a,b [--max-tasks N] a key for an outside agent: /a2a only
4281
4282
  * keys rotate <id> [--grace 1h] a new key, same label/role/scope; the old
4282
4283
  * one ends now, or when the grace runs out.
4283
4284
  * A key already rotated is refused (409):
@@ -4300,7 +4301,11 @@ async function keysCmd(positional, flags) {
4300
4301
  const day = (iso) => (iso ? iso.slice(0, 10) : "");
4301
4302
  for (const k of keys) {
4302
4303
  // A deploy key opened the platform's own git, gone since 17 Oct 2026.
4303
- const what = k.scope ? "deploy key · opens nothing since the platform's git went — revoke it" : `${k.role ?? "admin"} · ${k.workspaces ? k.workspaces.join(",") || "no workspaces" : "all workspaces"}`;
4304
+ const what = k.scope
4305
+ ? "deploy key · opens nothing since the platform's git went — revoke it"
4306
+ : k.purpose === "a2a"
4307
+ ? `A2A · ${k.a2a?.workspace ?? "?"} · ${(k.a2a?.flows ?? []).join(",")}${k.a2a?.maxTasks ? ` · up to ${k.a2a.maxTasks} open` : ""}`
4308
+ : `${k.role ?? "admin"} · ${k.workspaces ? k.workspaces.join(",") || "no workspaces" : "all workspaces"}`;
4304
4309
  const expired = !k.revokedAt && k.expiresAt && Date.parse(k.expiresAt) <= Date.now();
4305
4310
  const state = k.revokedAt ? c.red("revoked") : expired ? c.red("expired") : c.green("live");
4306
4311
  console.log(` ${state.padEnd(20)} ${k.id} ${k.prefix}… ${c.bold(k.label)} ${c.dim(what)}${k.createdBy ? c.dim(` by ${k.createdBy}`) : ""}`);
@@ -4314,6 +4319,7 @@ async function keysCmd(positional, flags) {
4314
4319
  }
4315
4320
  if (verb === "create" || verb === "new") {
4316
4321
  if (!arg) throw new Error("what is the key for? foldrun keys create <label>");
4322
+ if (flags.a2a === true) return keysCreateA2a(url, arg, flags);
4317
4323
  const body = { label: arg };
4318
4324
  if (typeof flags.role === "string") body.role = flags.role;
4319
4325
  // --expires 30d|90d|365d|never; unsaid, the key never expires.
@@ -4363,6 +4369,35 @@ async function keysCmd(positional, flags) {
4363
4369
  throw new Error(`keys: unknown verb "${verb}" — ls, create, rotate, revoke`);
4364
4370
  }
4365
4371
 
4372
+ /**
4373
+ * `foldrun keys create <label> --a2a --to <ws> --flows a,b [--max-tasks N]` —
4374
+ * a key for an OUTSIDE agent: it opens /a2a/<account>/<ws>/… for those
4375
+ * flows (each also published with a2a:) and no /api route.
4376
+ */
4377
+ async function keysCreateA2a(url, label, flags) {
4378
+ if (flags.role !== undefined || flags.workspaces !== undefined) {
4379
+ throw new Error("an A2A key takes --to <workspace> and --flows, not --role or --workspaces — it opens /a2a only, for that workspace's flows");
4380
+ }
4381
+ if (typeof flags.to !== "string" || !flags.to) throw new Error("which workspace? `foldrun keys create <label> --a2a --to <workspace> --flows <flow,…>`");
4382
+ const flows = typeof flags.flows === "string" ? [...new Set(flags.flows.split(",").map((f) => f.trim()).filter(Boolean))] : [];
4383
+ if (!flows.length) throw new Error(`which flows may it call? --flows <flow,…> — \`foldrun a2a ls --to ${flags.to}\` lists what ${flags.to} publishes`);
4384
+ const body = { label, purpose: "a2a", workspace: flags.to, flows };
4385
+ if (flags["max-tasks"] !== undefined) {
4386
+ const n = Number(flags["max-tasks"]);
4387
+ if (!Number.isInteger(n) || n < 1 || n > 100) throw new Error("--max-tasks takes a whole number from 1 to 100 — how many tasks the key may have open at once (default 10)");
4388
+ body.maxTasks = n;
4389
+ }
4390
+ if (typeof flags.expires === "string") body.expires = flags.expires;
4391
+ const made = await remoteCall(url, flags, "/api/keys", { method: "POST", body: JSON.stringify(body) });
4392
+ console.log(
4393
+ `\n ${c.green("✓")} ${c.bold(label)} ${c.dim(made.id)} ${c.dim(`A2A · ${made.workspace ?? flags.to} · ${(made.flows ?? flows).join(", ")} · up to ${made.maxTasks ?? body.maxTasks ?? 10} open`)}${made.expiresAt ? c.dim(` expires ${made.expiresAt.slice(0, 10)}`) : ""}\n`,
4394
+ );
4395
+ if (made.key == null) return lostSecret(made.id);
4396
+ console.log(` ${made.key}\n`);
4397
+ console.log(` ${c.dim(`Shown once. The outside agent sends it as its bearer token; it opens /a2a only. Try it: ${A2A_KEY_ENV}=<key> foldrun a2a call <card-url> "…" — \`foldrun a2a ls --to ${flags.to}\` has the card URLs. \`foldrun keys revoke ${made.id}\` ends it.`)}\n`);
4398
+ return 0;
4399
+ }
4400
+
4366
4401
  /** A retried mint or rotate is answered from the first call, and the server
4367
4402
  * never stores a key's secret — so a retry after a lost answer has none. */
4368
4403
  function lostSecret(id) {
@@ -12139,6 +12174,389 @@ function printPreview(p, rel) {
12139
12174
  }
12140
12175
  }
12141
12176
 
12177
+ // ------------------------------------------------------------------- a2a
12178
+
12179
+ /**
12180
+ * `foldrun a2a …` — A2A (Agent2Agent 1.0): outside agents calling this
12181
+ * account's published flows, and this terminal calling any A2A agent.
12182
+ *
12183
+ * a2a ls --to <ws> what the workspace serves: flows, cards, keys, recent tasks
12184
+ * a2a publish <flow> [--to <ws>] [--name --description --example … --public-card|--private-card]
12185
+ * a2a unpublish <flow> [--to <ws>] publish: false, the rest of a2a: kept
12186
+ * a2a card <flow> --to <ws> the card's URL, then the card
12187
+ * a2a call <card-url> "<text>" [--data <json|@file>] [--context <id>] [--no-wait] [--max-wait <s>]
12188
+ * a2a status <task-id> --card <url>
12189
+ * a2a cancel <task-id> --card <url> [--yes]
12190
+ *
12191
+ * Publishing is an edit of the flow's `a2a:` frontmatter — here, or with
12192
+ * --to on the platform through the flow route's PATCH { a2a } (an admin's:
12193
+ * the platform refuses an editor). The /a2a endpoints take an A2A key and nothing else:
12194
+ * call, status, cancel and a private card read it from $FOLDRUN_A2A_KEY
12195
+ * (or the variable --key-env names), never from the command line, and never
12196
+ * send this terminal's own API key to a card's address.
12197
+ */
12198
+ const A2A_KEY_ENV = "FOLDRUN_A2A_KEY";
12199
+ // Core's A2A modules, named in variables: the installed core may predate
12200
+ // them, and a literal would fail the typecheck against it. Both are in
12201
+ // core's foldrun.publicApi (tests/cli-release.test.ts reads these strings).
12202
+ /** @type {string} */
12203
+ const A2A_CLIENT_MODULE = "@foldrun/core/a2a-client";
12204
+ /** @type {string} */
12205
+ const A2A_PUBLISH_MODULE = "@foldrun/core/a2a-publish";
12206
+ const A2A_POLL_MS = 2_000;
12207
+ const A2A_CARD_BYTES = 64 * 1024;
12208
+
12209
+ async function a2aCmd(positional, flags, layout) {
12210
+ const verb = positional[0];
12211
+ switch (verb) {
12212
+ case "ls":
12213
+ case "list":
12214
+ case undefined:
12215
+ return a2aLsCmd(flags, layout);
12216
+ case "publish":
12217
+ case "unpublish":
12218
+ return a2aPublishCmd(verb, positional[1], flags, layout);
12219
+ case "card":
12220
+ return a2aCardCmd(positional[1], flags, layout);
12221
+ case "call":
12222
+ return a2aCallCmd(positional[1], positional.slice(2).join(" "), flags);
12223
+ case "status":
12224
+ case "cancel":
12225
+ return a2aTaskCmd(verb, positional[1], flags);
12226
+ }
12227
+ throw new Error(`a2a: unknown verb "${verb}" — ls, publish, unpublish, card, call, status, cancel`);
12228
+ }
12229
+
12230
+ /** GET /api/workspaces/<ws>/a2a — what a workspace serves over A2A. */
12231
+ async function a2aView(flags, layout, what) {
12232
+ const url = platformFor(flags, what);
12233
+ const ws = platformWorkspace(flags, layout, what);
12234
+ return { url, ws, view: await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/a2a`) };
12235
+ }
12236
+
12237
+ const a2aStateWord = (s) => printable(s).replace(/^TASK_STATE_/, "").toLowerCase().replace(/_/g, "-");
12238
+ const a2aStateMark = (s) =>
12239
+ s === "TASK_STATE_COMPLETED" ? c.green("✓") : s === "TASK_STATE_FAILED" || s === "TASK_STATE_REJECTED" ? c.red("✗") : s === "TASK_STATE_CANCELED" ? c.dim("■") : c.amber("…");
12240
+
12241
+ async function a2aLsCmd(flags, layout) {
12242
+ const { ws, view } = await a2aView(flags, layout, "a2a ls");
12243
+ if (flags.json === true) {
12244
+ console.log(JSON.stringify(view, null, 2));
12245
+ return 0;
12246
+ }
12247
+ const flows = view.flows ?? [];
12248
+ console.log(`\n ${c.bold(ws)} ${c.dim("· over A2A")}\n`);
12249
+ if (!flows.length) console.log(` ${c.dim(`no flow says a2a: — \`foldrun a2a publish <flow> --to ${ws}\` publishes one`)}`);
12250
+ for (const f of flows) {
12251
+ const state = f.published ? c.green("published".padEnd(13)) : c.dim("not published");
12252
+ const extra = [f.publicCard ? "public card" : "private card", f.hasInputSchema ? "input schema" : null].filter(Boolean).join(" · ");
12253
+ console.log(` ${state} ${c.bold(printable(f.flow))}${f.name && f.name !== f.flow ? ` ${printable(f.name)}` : ""} ${c.dim(extra)}`);
12254
+ if (f.published) {
12255
+ console.log(` ${" ".repeat(10)}${c.dim("card")} ${printable(f.card)}`);
12256
+ console.log(` ${" ".repeat(10)}${c.dim("url ")} ${printable(f.url)}`);
12257
+ }
12258
+ }
12259
+ if (Array.isArray(view.keys)) {
12260
+ console.log(`\n ${c.bold("A2A keys")}`);
12261
+ if (!view.keys.length) console.log(` ${c.dim(`none — \`foldrun keys create <label> --a2a --to ${ws} --flows <flow>\` mints one`)}`);
12262
+ for (const k of view.keys) {
12263
+ console.log(` ${printable(k.id)} ${printable(k.prefix)}… ${c.bold(printable(k.label) || "(no label)")} ${c.dim(printable(`${(k.flows ?? []).join(", ")}${k.maxTasks ? ` · up to ${k.maxTasks} open` : ""}${k.expiresAt ? ` · expires ${String(k.expiresAt).slice(0, 10)}` : ""}`))}`);
12264
+ }
12265
+ }
12266
+ const tasks = view.tasks ?? [];
12267
+ console.log(`\n ${c.bold("Recent tasks")}`);
12268
+ if (!tasks.length) console.log(` ${c.dim("none yet")}`);
12269
+ for (const t of tasks) {
12270
+ const who = t.key?.label || t.key?.prefix ? `A2A · ${t.key.label || `${t.key.prefix}…`}${t.key.revoked ? " (revoked)" : ""}` : "A2A · a key since removed";
12271
+ console.log(` ${a2aStateMark(t.state)} ${a2aStateWord(t.state).padEnd(14)} ${c.bold(printable(t.flow))} ${c.dim(printable(`${who} · ${when(t.updatedAt)}${t.runId ? ` · run ${t.runId}` : ""}`))}`);
12272
+ }
12273
+ console.log("");
12274
+ return 0;
12275
+ }
12276
+
12277
+ /** What a publish or unpublish changes in `a2a:` — the body of the flow
12278
+ * route's PATCH { a2a }, merged there over the flow's block (a key given
12279
+ * replaces it, a key given as null removes it). */
12280
+ export function a2aPatchFor(verb, flags) {
12281
+ if (verb !== "publish") return { publish: false };
12282
+ const patch = { publish: true };
12283
+ if (typeof flags.name === "string") patch.name = flags.name;
12284
+ if (typeof flags.description === "string") patch.description = flags.description;
12285
+ const examples = many(flags.example);
12286
+ if (examples.length) patch.examples = examples;
12287
+ if (flags["public-card"] === true && flags["private-card"] === true) throw new Error("--public-card or --private-card, not both");
12288
+ if (flags["public-card"] === true) patch.public_card = true;
12289
+ if (flags["private-card"] === true) patch.public_card = null;
12290
+ return patch;
12291
+ }
12292
+
12293
+ /** The `a2a:` the flow will say after `patch`, merged as the platform
12294
+ * merges it: its other keys kept, `publish` first. */
12295
+ export function a2aBlockFor(current, patch) {
12296
+ const base = current && typeof current === "object" && !Array.isArray(current) ? { ...current } : {};
12297
+ delete base.publish;
12298
+ const block = { publish: patch.publish, ...base };
12299
+ for (const [k, v] of Object.entries(patch)) {
12300
+ if (k === "publish") continue;
12301
+ if (v === null) delete block[k];
12302
+ else block[k] = v;
12303
+ }
12304
+ return block;
12305
+ }
12306
+
12307
+ async function a2aPublishCmd(verb, flow, flags, layout) {
12308
+ if (!flow) throw new Error(`which flow? \`foldrun a2a ${verb} <flow> --to <workspace>\``);
12309
+ // The block's own rules are core's (a2a-publish.ts): the same sentences
12310
+ // check and the platform say. A core without them would call a2a: an
12311
+ // unknown field and refuse the edit for a reason that is not one.
12312
+ const pub = /** @type {any} */ (await import(A2A_PUBLISH_MODULE).catch(() => null));
12313
+ if (!pub || typeof pub.a2aPublishProblems !== "function") {
12314
+ throw new Error(`\`foldrun a2a ${verb}\` needs an @foldrun/core that knows a2a: (@foldrun/core/a2a-publish) — this install's is older; update foldrun (npm i -g foldrun@latest)`);
12315
+ }
12316
+ const matter = (await import("gray-matter")).default;
12317
+ const { patchFrontmatter } = await import("@foldrun/core/agents-md");
12318
+ const patch = a2aPatchFor(verb, flags);
12319
+ const code = await flowEditCmd(flags, layout, {
12320
+ flow,
12321
+ what: `a2a ${verb}`,
12322
+ label: verb === "publish" ? "a2a: publish — outside agents with an A2A key naming it may call it" : "a2a: publish: false — no outside agent may call it",
12323
+ compute: (raw) => {
12324
+ let current;
12325
+ try {
12326
+ current = matter(raw, {}).data?.a2a;
12327
+ } catch {
12328
+ current = undefined;
12329
+ }
12330
+ // Nothing to take back from a flow that never said a2a:.
12331
+ if (verb === "unpublish" && (current === undefined || current === null)) return { next: raw, meta: null };
12332
+ const block = a2aBlockFor(current, patch);
12333
+ const problems = pub.a2aPublishProblems(block);
12334
+ if (problems.length) throw new Error(`a2a: ${problems.join("; ")}`);
12335
+ return { next: patchFrontmatter(raw, { a2a: block }), meta: null };
12336
+ },
12337
+ // The flow page's Publish over A2A control sends the same PATCH { a2a }
12338
+ // (an admin's: the platform refuses an editor with 403).
12339
+ bodies: (raw) => [{ body: { a2a: patch }, after: raw }],
12340
+ });
12341
+ if (code !== 0 || flags["dry-run"] === true) return code;
12342
+ if (!namesPlatform(flags)) {
12343
+ if (verb === "publish") console.log(` ${c.dim("Once deployed, an outside agent calls it with an A2A key: `foldrun keys create <label> --a2a --to <workspace> --flows " + flow + "`")}\n`);
12344
+ return 0;
12345
+ }
12346
+ if (verb === "unpublish") return 0;
12347
+ // Where it is served now, and how a caller gets in.
12348
+ const { ws, view } = await a2aView(flags, layout, `a2a ${verb}`).catch(() => ({ ws: flags.to, view: null }));
12349
+ const f = (view?.flows ?? []).find((x) => x.flow === flow);
12350
+ if (f?.published) {
12351
+ console.log(` ${c.dim("card")} ${printable(f.card)}`);
12352
+ console.log(` ${c.dim("url ")} ${printable(f.url)}\n`);
12353
+ }
12354
+ console.log(` ${c.dim(`A caller needs an A2A key that names it: \`foldrun keys create <label> --a2a --to ${ws} --flows ${flow}\``)}\n`);
12355
+ return 0;
12356
+ }
12357
+
12358
+ /** The A2A key this terminal sends to an /a2a address: from $FOLDRUN_A2A_KEY
12359
+ * or the variable --key-env names — never this CLI's own API key. */
12360
+ function a2aKey(flags) {
12361
+ const named = typeof flags["key-env"] === "string";
12362
+ const name = named ? flags["key-env"] : A2A_KEY_ENV;
12363
+ if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new Error(`--key-env takes the NAME of an environment variable that holds the A2A key — got "${name}"`);
12364
+ const token = process.env[name]?.trim() || undefined;
12365
+ if (named && !token) throw new Error(`--key-env ${name}: $${name} is not set — export the A2A key in it (a key is never read from the command line)`);
12366
+ return { name, token };
12367
+ }
12368
+
12369
+ /** A card address, checked: http(s), no user:password in it. */
12370
+ function a2aCardUrl(value, what) {
12371
+ if (typeof value !== "string" || !value) throw new Error(`which agent? \`foldrun a2a ${what}\` takes the agent card's URL (…/.well-known/agent-card.json)`);
12372
+ let u;
12373
+ try {
12374
+ u = new URL(value);
12375
+ } catch {
12376
+ throw new Error(`"${value}" is not a URL — \`foldrun a2a ${what}\` takes the agent card's address (…/.well-known/agent-card.json)`);
12377
+ }
12378
+ if (u.protocol !== "https:" && u.protocol !== "http:") throw new Error(`${u.protocol} is not a web address — an A2A card is at https://…`);
12379
+ if (u.username || u.password) throw new Error("the card URL holds a user name or password — the key goes in $FOLDRUN_A2A_KEY, never in a URL");
12380
+ return u;
12381
+ }
12382
+
12383
+ const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
12384
+
12385
+ /** Core's A2A client, or a clear refusal from an older core. */
12386
+ async function a2aClient(what) {
12387
+ const m = /** @type {any} */ (await import(A2A_CLIENT_MODULE).catch(() => null));
12388
+ if (!m || ["fetchCard", "sendMessage", "getTask", "cancelTask", "replyText"].some((f) => typeof m[f] !== "function")) {
12389
+ throw new Error(`\`foldrun a2a ${what}\` needs an @foldrun/core with the A2A client (@foldrun/core/a2a-client) — this install's is older; update foldrun (npm i -g foldrun@latest)`);
12390
+ }
12391
+ return m;
12392
+ }
12393
+
12394
+ /** The connection core's client takes, for one card. */
12395
+ function a2aConnection(u, flags) {
12396
+ const key = a2aKey(flags);
12397
+ if (key.token && u.protocol === "http:" && !LOOPBACK.has(u.hostname)) {
12398
+ console.error(` ${c.amber("!")} ${c.dim(`sending the A2A key to ${u.host} over plain http — anyone on the way can read it`)}`);
12399
+ }
12400
+ return { key, conn: { remote: u.host, card: u.href, origin: u.origin, ...(key.token ? { token: key.token } : {}), timeoutMs: timeoutSeconds(flags) * 1000 } };
12401
+ }
12402
+
12403
+ /** An A2A refusal, said with what to do about it here. */
12404
+ function a2aExplain(err, key) {
12405
+ // The remote's own words can be in the message: printed, so made safe.
12406
+ const msg = printable(err instanceof Error ? err.message : String(err));
12407
+ if (/refused the credential/.test(msg)) {
12408
+ return new Error(key.token ? `${msg} — is $${key.name} an A2A key for this flow? (POST /api/keys { purpose: "a2a" } mints one; an API key never opens /a2a)` : `${msg.replace(/ — this remote has no secret: set one$/, "")} — no A2A key was sent: export it in $${key.name} (or name the variable with --key-env)`);
12409
+ }
12410
+ return new Error(msg);
12411
+ }
12412
+
12413
+ /**
12414
+ * The exit code a task means, whatever the output format: 0 for a task
12415
+ * that completed or is still open (call, status), 1 for one that failed,
12416
+ * was rejected or canceled — and for cancel, 0 only when the agent says
12417
+ * the task IS canceled now.
12418
+ */
12419
+ export function a2aExitCode(verb, task, terminal) {
12420
+ const state = task?.status?.state;
12421
+ if (verb === "cancel") return state === "TASK_STATE_CANCELED" ? 0 : 1;
12422
+ return state === "TASK_STATE_COMPLETED" || !terminal?.has?.(state) ? 0 : 1;
12423
+ }
12424
+
12425
+ /** An outside agent's text, indented, made safe to print: it cannot move the
12426
+ * cursor, retitle the terminal or write the clipboard (printable). */
12427
+ const a2aIndented = (text) => printable(text).split("\n").map((l) => ` ${l}`).join("\n");
12428
+
12429
+ function a2aPrintTask(task, A, cardUrl) {
12430
+ const state = task.status?.state;
12431
+ const id = printable(task.id);
12432
+ console.log(`\n ${a2aStateMark(state)} ${c.bold(a2aStateWord(state))} ${c.dim(`task ${id}${task.contextId ? ` · context ${printable(task.contextId)}` : ""}`)}`);
12433
+ const text = A.replyText({ task });
12434
+ if (text) console.log(`\n${a2aIndented(text)}`);
12435
+ if (!A.TERMINAL_STATES?.has?.(state)) {
12436
+ console.log(`\n ${c.dim(`still open — \`foldrun a2a status ${id} --card ${cardUrl}\` asks again, \`foldrun a2a cancel ${id} --card ${cardUrl}\` stops it`)}`);
12437
+ }
12438
+ console.log("");
12439
+ return a2aExitCode("status", task, A.TERMINAL_STATES);
12440
+ }
12441
+
12442
+ /** --data: one JSON value, inline or @file — the request's data part. */
12443
+ function a2aData(value) {
12444
+ if (value === undefined) return undefined;
12445
+ if (value === true) throw new Error("--data needs a value — JSON, or @file");
12446
+ const text = String(value).startsWith("@") ? fs.readFileSync(path.resolve(String(value).slice(1)), "utf8") : String(value);
12447
+ try {
12448
+ return JSON.parse(text);
12449
+ } catch (err) {
12450
+ throw new Error(`--data is not JSON (${err instanceof Error ? err.message : err}) — it is sent as the message's data part`);
12451
+ }
12452
+ }
12453
+
12454
+ async function a2aCallCmd(cardArg, text, flags) {
12455
+ const u = a2aCardUrl(cardArg, "call <card-url> \"<text>\"");
12456
+ if (!text.trim()) throw new Error("what should it do? `foldrun a2a call <card-url> \"<text>\"` — the text is the message");
12457
+ const data = a2aData(flags.data);
12458
+ const A = await a2aClient("call");
12459
+ const { key, conn } = a2aConnection(u, flags);
12460
+ const maxWait = flags["max-wait"] === undefined ? 300 : Number(flags["max-wait"]);
12461
+ if (!Number.isFinite(maxWait) || maxWait < 0) throw new Error("--max-wait takes seconds, 0 or more");
12462
+ const wait = flags["no-wait"] !== true && flags["return-immediately"] !== true && maxWait > 0;
12463
+ let task;
12464
+ try {
12465
+ const endpoint = await A.fetchCard(conn);
12466
+ const sent = await A.sendMessage(conn, endpoint, {
12467
+ messageId: crypto.randomUUID(),
12468
+ text,
12469
+ ...(data !== undefined ? { data } : {}),
12470
+ ...(typeof flags.context === "string" ? { contextId: flags.context } : {}),
12471
+ });
12472
+ if (sent.message) {
12473
+ if (flags.json === true) console.log(JSON.stringify(sent, null, 2));
12474
+ else console.log(`\n${a2aIndented(A.replyText(sent))}\n`);
12475
+ return 0;
12476
+ }
12477
+ task = sent.task;
12478
+ // The id is printed before any waiting, so an interrupted wait still
12479
+ // leaves the task in hand.
12480
+ if (wait && flags.json !== true) console.error(` ${c.dim(`task ${printable(task.id)} — waiting up to ${maxWait}s for it to end (Ctrl-C leaves it running)`)}`);
12481
+ const until = Date.now() + maxWait * 1000;
12482
+ while (wait && !A.TERMINAL_STATES.has(task.status.state) && !A.INTERRUPTED_STATES?.has?.(task.status.state) && Date.now() < until) {
12483
+ await new Promise((r) => setTimeout(r, Math.min(A2A_POLL_MS, Math.max(0, until - Date.now()))));
12484
+ task = await A.getTask(conn, endpoint, task.id);
12485
+ }
12486
+ } catch (err) {
12487
+ throw a2aExplain(err, key);
12488
+ }
12489
+ if (flags.json === true) console.log(JSON.stringify(task, null, 2));
12490
+ else a2aPrintTask(task, A, u.href);
12491
+ return a2aExitCode("call", task, A.TERMINAL_STATES);
12492
+ }
12493
+
12494
+ async function a2aTaskCmd(verb, taskId, flags) {
12495
+ if (!taskId) throw new Error(`which task? \`foldrun a2a ${verb} <task-id> --card <url>\` — \`foldrun a2a call\` prints the id`);
12496
+ const u = a2aCardUrl(flags.card, `${verb} <task-id> --card <url>`);
12497
+ const A = await a2aClient(verb);
12498
+ const { key, conn } = a2aConnection(u, flags);
12499
+ if (verb === "cancel" && !(await confirmed(flags, "a2a cancel", `Cancel task ${taskId} at ${u.host} (its run is stopped)? [y/N] `))) {
12500
+ console.log(`\n ${c.dim("nothing cancelled")}\n`);
12501
+ return 1;
12502
+ }
12503
+ let task;
12504
+ try {
12505
+ const endpoint = await A.fetchCard(conn);
12506
+ task = verb === "cancel" ? await A.cancelTask(conn, endpoint, taskId) : await A.getTask(conn, endpoint, taskId);
12507
+ } catch (err) {
12508
+ throw a2aExplain(err, key);
12509
+ }
12510
+ // JSON or words, the same exit code: a script reading --json must still
12511
+ // see a failed task, or a cancel the agent did not carry out, as a failure.
12512
+ if (flags.json === true) console.log(JSON.stringify(task, null, 2));
12513
+ else a2aPrintTask(task, A, u.href);
12514
+ return a2aExitCode(verb, task, A.TERMINAL_STATES);
12515
+ }
12516
+
12517
+ async function a2aCardCmd(flow, flags, layout) {
12518
+ if (!flow) throw new Error("which flow? `foldrun a2a card <flow> --to <workspace>`");
12519
+ const { ws, view } = await a2aView(flags, layout, "a2a card");
12520
+ const f = (view.flows ?? []).find((x) => x.flow === flow);
12521
+ if (!f) throw new Error(`${flow} in ${ws} says no a2a: — \`foldrun a2a publish ${flow} --to ${ws}\` publishes it`);
12522
+ if (!f.published) throw new Error(`${flow} in ${ws} is not published (a2a: publish: false) — it has no card; \`foldrun a2a publish ${flow} --to ${ws}\``);
12523
+ console.log(`\n ${c.dim("card")} ${printable(f.card)}`);
12524
+ console.log(` ${c.dim("url ")} ${printable(f.url)}\n`);
12525
+ const u = new URL(f.card);
12526
+ const key = a2aKey(flags);
12527
+ if (!f.publicCard && !key.token) {
12528
+ console.log(` ${c.dim(`a private card — reading it takes an A2A key that names ${flow}: export it in $${key.name} (or --key-env NAME), or make it public with \`foldrun a2a publish ${flow} --to ${ws} --public-card\``)}\n`);
12529
+ return 0;
12530
+ }
12531
+ // Only the A2A key goes to the card's address — never this terminal's API key.
12532
+ const res = await fetch(u, {
12533
+ headers: { accept: "application/json", "A2A-Version": "1.0", ...(key.token && !f.publicCard ? { authorization: `Bearer ${key.token}` } : {}) },
12534
+ redirect: "manual",
12535
+ signal: AbortSignal.timeout(timeoutSeconds(flags) * 1000),
12536
+ });
12537
+ const body = await res.text();
12538
+ if (res.status !== 200) {
12539
+ const said = (() => {
12540
+ try {
12541
+ return JSON.parse(body)?.error?.message;
12542
+ } catch {
12543
+ return null;
12544
+ }
12545
+ })();
12546
+ throw new Error(`the card answered HTTP ${res.status}${said ? `: ${printable(said)}` : ""}${res.status === 401 || res.status === 403 ? ` — is $${key.name} an A2A key that names ${flow}?` : ""}`);
12547
+ }
12548
+ if (Buffer.byteLength(body, "utf8") > A2A_CARD_BYTES) throw new Error(`the card is over ${A2A_CARD_BYTES / 1024} KiB — not printed`);
12549
+ let card;
12550
+ try {
12551
+ card = JSON.parse(body);
12552
+ } catch {
12553
+ throw new Error("the card's address did not answer JSON");
12554
+ }
12555
+ console.log(JSON.stringify(card, null, 2).split("\n").map((l) => ` ${l}`).join("\n"));
12556
+ console.log("");
12557
+ return 0;
12558
+ }
12559
+
12142
12560
  export async function run(command, positional, flags, workspace, layout) {
12143
12561
  // Nothing outside the CLI's own entry point passes a layout — the tests
12144
12562
  // that call run() directly, an embedder. A lone workspace is the safe
@@ -12164,6 +12582,8 @@ export async function run(command, positional, flags, workspace, layout) {
12164
12582
  return apiCmd(positional, flags);
12165
12583
  case "keys":
12166
12584
  return keysCmd(positional, flags);
12585
+ case "a2a":
12586
+ return a2aCmd(positional, flags, layout);
12167
12587
  case "audit":
12168
12588
  return auditCmd(positional, flags);
12169
12589
  case "accounts":
package/src/guide.mjs CHANGED
@@ -30,7 +30,7 @@ export function agentRulesBlock() {
30
30
 
31
31
  # Read foldrun's docs before you edit this folder
32
32
 
33
- This is a foldrun account: agents, flows, tools and knowledge as markdown, run by foldrun. Its formats — frontmatter fields, step options, \`verify:\` prefixes, which folder a file goes in — are foldrun's own and may differ from your training data. Before you write or change an agent, flow, tool or skill, read the relevant guide: \`foldrun docs\` lists them and \`foldrun docs <page>\` prints one (start with \`foldrun docs coding-agents\`). They ship with the CLI, so they match the version you are driving. Check every edit with \`foldrun check\` — offline, no model calls; it is also the security scanner (a key written into a file, hidden text, an agent that can leak), and \`foldrun check --security\` fails on what it finds. Never paste a credential into a file: \`foldrun secrets set NAME\` and write \`\${NAME}\`. For a flow's shape, \`foldrun flow show <flow>\` draws it, and \`foldrun flow add\`, \`foldrun flow rm-step\`, \`foldrun flow dup-step\` and \`foldrun agent link\` make the same edits as the dashboard canvas (patterns, sub-agents, consults, \`ask\`). An agent with \`tools: [peers]\` can message the steps running beside it in its parallel group (\`peers_message\`) and ask for what they have instead of guessing or failing (\`foldrun docs agents\`). A sub-agent that reads untrusted content (web pages, mail, uploads) gets \`sandbox: own\` in its own file: each job then runs in a sandbox of its own with its own tools, secrets and network, and only its reply and the files it wrote reach the agent that delegated (\`foldrun agent link <agent> --subagent <worker> --isolated\`). A script tool's own \`secrets: [NAMES]\` are granted with the tool; list on an agent only the secrets it uses directly. A hook (\`hooks/<name>/hook.md\` + \`run.mjs\`, turned on with \`hooks: [name]\`) is code at every tool call, step start and step end — \`foldrun hook add\`/\`test\` and \`foldrun docs hooks\`. Paths to the workspace's own folders are written \`workspace/storage/…\` and \`workspace/state/…\` — in an agent's prose, a flow's options and a script's arguments — not \`../../\`, which still works but is the older spelling. Which sites a step's sandbox may reach is \`network:\` — open for an agent that may fetch or browse the web, the trusted list plus what it declares for every other; add a site with \`foldrun agent network <agent> --add <site>\` (\`foldrun docs network\`). Bind a secret to the sites it is for (\`foldrun secrets sites NAME <site>\`) and no sandbox ever holds its value. What a step's sandbox may use is \`size:\` (\`small\` 1 core/1Gi, \`large\`, \`heavy\` 4 cores/8Gi — hard limits and the billed figures); \`resources: {cpu, memory, disk}\` sets the numbers yourself, key by key over the class (\`foldrun docs agents\`). What steps may hold together is capped at four levels, each only narrowing the one above: the account's and a workspace's \`compute: {vcpu, memory, disk}\` in AGENTS.md, a flow's \`compute:\` for each of its runs, and the plan's most for one step; a step past a cap waits its turn, one bigger than a whole cap fails (\`foldrun usage compute\`, \`foldrun docs budgets-and-billing\`). A webhook, email, chained or storage flow says which deliveries start it with \`filter:\` (\`foldrun flow filter <flow> --payload body.json\` tries one); an eval with \`trigger: runs\` grades a \`sample:\` of real finished runs instead of running cases, \`foldrun eval compare\` runs an eval's cases under several models side by side, and \`improve: true\` turns repeated failures into a proposed fix a person applies (\`foldrun docs evals\`).
33
+ This is a foldrun account: agents, flows, tools and knowledge as markdown, run by foldrun. Its formats — frontmatter fields, step options, \`verify:\` prefixes, which folder a file goes in — are foldrun's own and may differ from your training data. Before you write or change an agent, flow, tool or skill, read the relevant guide: \`foldrun docs\` lists them and \`foldrun docs <page>\` prints one (start with \`foldrun docs coding-agents\`). They ship with the CLI, so they match the version you are driving. Check every edit with \`foldrun check\` — offline, no model calls; it is also the security scanner (a key written into a file, hidden text, an agent that can leak), and \`foldrun check --security\` fails on what it finds. Never paste a credential into a file: \`foldrun secrets set NAME\` and write \`\${NAME}\`. For a flow's shape, \`foldrun flow show <flow>\` draws it, and \`foldrun flow add\`, \`foldrun flow rm-step\`, \`foldrun flow dup-step\` and \`foldrun agent link\` make the same edits as the dashboard canvas (patterns, sub-agents, consults, \`ask\`). An agent with \`tools: [peers]\` can message the steps running beside it in its parallel group (\`peers_message\`) and ask for what they have instead of guessing or failing (\`foldrun docs agents\`). A sub-agent that reads untrusted content (web pages, mail, uploads) gets \`sandbox: own\` in its own file: each job then runs in a sandbox of its own with its own tools, secrets and network, and only its reply and the files it wrote reach the agent that delegated (\`foldrun agent link <agent> --subagent <worker> --isolated\`). A script tool's own \`secrets: [NAMES]\` are granted with the tool; list on an agent only the secrets it uses directly. A hook (\`hooks/<name>/hook.md\` + \`run.mjs\`, turned on with \`hooks: [name]\`) is code at every tool call, step start and step end — \`foldrun hook add\`/\`test\` and \`foldrun docs hooks\`. Paths to the workspace's own folders are written \`workspace/storage/…\` and \`workspace/state/…\` — in an agent's prose, a flow's options and a script's arguments — not \`../../\`, which still works but is the older spelling. Which sites a step's sandbox may reach is \`network:\` — open for an agent that may fetch or browse the web, the trusted list plus what it declares for every other; add a site with \`foldrun agent network <agent> --add <site>\` (\`foldrun docs network\`). Bind a secret to the sites it is for (\`foldrun secrets sites NAME <site>\`) and no sandbox ever holds its value. What a step's sandbox may use is \`size:\` (\`small\` 1 core/1Gi, \`large\`, \`heavy\` 4 cores/8Gi — hard limits and the billed figures); \`resources: {cpu, memory, disk}\` sets the numbers yourself, key by key over the class (\`foldrun docs agents\`). What steps may hold together is capped at four levels, each only narrowing the one above: the account's and a workspace's \`compute: {vcpu, memory, disk}\` in AGENTS.md, a flow's \`compute:\` for each of its runs, and the plan's most for one step; a step past a cap waits its turn, one bigger than a whole cap fails (\`foldrun usage compute\`, \`foldrun docs budgets-and-billing\`). A webhook, email, chained or storage flow says which deliveries start it with \`filter:\` (\`foldrun flow filter <flow> --payload body.json\` tries one); an eval with \`trigger: runs\` grades a \`sample:\` of real finished runs instead of running cases, \`foldrun eval compare\` runs an eval's cases under several models side by side, and \`improve: true\` turns repeated failures into a proposed fix a person applies (\`foldrun docs evals\`). A flow is served to outside agents over A2A 1.0 when its frontmatter says \`a2a: { publish: true }\` (an admin's change; callers need an A2A key naming the flow — \`foldrun a2a publish\`, \`foldrun keys create --a2a\`), and an agent calls outside A2A agents listed in \`remotes: [{name, card, secret?}]\` with the \`a2a_send\`/\`a2a_status\` tools — never send a request twice to retry, poll its handle (\`foldrun docs a2a\`).
34
34
 
35
35
  This block is for coding tools. It is written and re-added by the foldrun CLI, and the runtime strips it, so the agents that run here never see it; the rest of this file is the account's own context, which they do read. Committing the block with your work keeps the tree clean.
36
36