foldrun 10.1.1 → 10.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/bin/foldrun.mjs CHANGED
@@ -16,6 +16,7 @@
16
16
  // foldrun report <run-id> one run, whole: every step, what it cost, what it wrote
17
17
  // foldrun approvals what is waiting for a person, anywhere in the account
18
18
  // foldrun inbox what is waiting on YOU — assigned, started by you, the team's (read, dismiss)
19
+ // foldrun mcp this account as MCP tools for an AI app (Claude, Cursor, Codex), over stdio
19
20
  // foldrun approve <run-id> release a waiting gate (asks first) — reject refuses it
20
21
  // foldrun stop <run-id> kill a run in flight
21
22
  // foldrun account the account's own defaults — timezone, notify, budget, concurrency, deploy_block, network_enforce
@@ -58,6 +59,7 @@
58
59
  // foldrun doctor what is between this terminal and the platform, checked
59
60
  // foldrun accounts every account signed in here; `use <name>` switches
60
61
  // foldrun keys <verb> ls / create / revoke — the account's API keys
62
+ // foldrun a2a <verb> ls / publish / unpublish / card / call / status / cancel — flows served to outside agents (A2A 1.0)
61
63
  // foldrun library <verb> ls / cat / put / new / rm — the account's shared shelf on the platform
62
64
  // foldrun find <words> search the account the way the dashboard's ⌘K does
63
65
  // foldrun changelog what each release of the platform changed
@@ -167,6 +169,7 @@ const HELP = `foldrun — agents are just folders
167
169
  foldrun insights recurring problems found in the runs, with what they cost and what to do (--days, --to, --json)
168
170
  foldrun inbox what waits on you: approvals, questions, issues, proposed fixes, your failed runs (--team, --all, --kind, --unread, --dismissed)
169
171
  foldrun inbox read|unread|dismiss|restore <id>… mark items in your own view (dismiss sets aside; it still waits where it lives)
172
+ foldrun mcp this account as MCP tools for an AI app, over stdio, with this machine's sign-in: \`claude mcp add foldrun -- foldrun mcp\` (--read-only: only the tools that read)
170
173
  foldrun issues what went wrong, grouped, open until resolved (--to <workspace>, --all, --status, --json)
171
174
  foldrun issues show|ack|snooze|resolve|reopen <id> one issue — snooze --for 1d or --times 5, --note "…"
172
175
  foldrun issues doctor <id> the run doctor on the issue's newest run, in its workspace: why, and the fix as diffs, saved on yes (--yes, --dry-run, --json)
@@ -259,6 +262,13 @@ Signing in
259
262
  foldrun accounts every account signed in on this machine, and which one is active
260
263
  foldrun use <name> act as one of them from here on
261
264
  foldrun keys ls the account's API keys: created, last used, expires, scope — also create <label> [--expires 90d], rotate <id> [--grace 1h], revoke <id>
265
+ 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
266
+ 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)
267
+ 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
268
+ foldrun a2a unpublish <flow> a2a: publish: false — no outside agent may call it; the rest of a2a: is kept (--to <ws>, --dry-run)
269
+ 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)
270
+ 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
271
+ foldrun a2a status <task-id> --card <url> the task as it stands now (--json) — cancel <task-id> --card <url> stops it (asks; --yes)
262
272
  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
273
  foldrun --version this CLI's version, offline (\`foldrun version\` also asks the platform)
264
274
  foldrun --help everything; \`foldrun <command> --help\`, \`-h\` or \`foldrun help <command>\` for one (never runs it)
@@ -297,6 +307,7 @@ Options
297
307
  --schedule "<cron>" flow trigger: the cron line a schedule fires on (5 fields, or @daily); --timezone <zone> the zone it is read in
298
308
  --team, --started, --mine, --all inbox: which bucket (default: assigned to you and started by you)
299
309
  --dismissed, --unread inbox: what you set aside; only what you have not read
310
+ --read-only mcp: offer the AI app only the tools that read — no run, approve, answer, message or stop
300
311
  --models <m[:effort],…> eval compare: two to four tiers or model ids to compare, each with an optional :effort
301
312
  --max-usd <n> eval compare: the spend limit — no run starts once the runs and judges have spent it (default 5)
302
313
  --payload <file|-|json> flow filter: the delivery to test — a file, - for stdin, or JSON inline
@@ -370,6 +381,9 @@ Options
370
381
  --role <r> keys create: viewer, editor (default) or admin
371
382
  --expires <span> keys create: when it stops working — 30d, 90d, 365d or never (default never)
372
383
  --grace <span> keys rotate: keep the old key working for 1h or 24h while you swap the new one in (default 0: revoked now)
384
+ --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)
385
+ --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
386
+ --card <url> a2a status, a2a cancel: the agent card of the agent that holds the task
373
387
 
374
388
  Platform options (deploy, invoke, secrets, logs, keys)
375
389
  --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 +424,9 @@ if (!command || command === "--help" || command === "-h") {
410
424
  // `--value` as the account's argument and stored an empty secret; `--force
411
425
  // ./dir` swallowed the directory. A flag followed by another flag is also
412
426
  // 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"]);
427
+ const BOOLEAN_FLAGS = new Set(["read-only", "account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear", "security", "changed", "write-baseline", "no-baseline", "rules", "calls", "tree", "tool-error", "stop", "last", "no-pkce", "export", "isolated", "no-wait", "dismissed", "unread", "team", "started", "mine", "none", "a2a", "public-card", "private-card", "return-immediately"]);
414
428
  // 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"]);
429
+ const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove", "rule", "authorize-param", "example"]);
416
430
  // `--wait` is a switch everywhere but `flow add <flow> wait`, where it takes
417
431
  // a span: `--wait 30m`, `--wait event`. Only a value that reads as one is
418
432
  // 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,38 @@ 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 |
528
+
529
+ ## MCP — AI apps connecting with a key
530
+
531
+ The platform as an [MCP server](mcp) for Claude Code, Claude Desktop,
532
+ Cursor, Codex and any other MCP client. An **API key** opens it
533
+ (`Authorization: Bearer mda_…`) — never a session cookie, never an A2A key —
534
+ and every tool is a call to one of the routes above, made with that key, so
535
+ it answers what the route would: the key's role, its workspaces and every
536
+ refusal hold. MCP's Streamable HTTP transport, stateless: one JSON-RPC 2.0
537
+ message per request, answered as JSON — no SSE stream, no session id, no
538
+ batches. Errors before a message is read (no key, a refused key, a foreign
539
+ `Origin`, an `MCP-Protocol-Version` it does not speak) are JSON-RPC error
540
+ objects with a real status; a tool whose route refused answers `isError: true`
541
+ with `HTTP <status>: <the route's error>`.
542
+
543
+ | Route | Methods | |
544
+ |---|---|---|
545
+ | `/api/mcp` | POST | one JSON-RPC message: `initialize` (revisions `2025-11-25`, `2025-06-18`, `2025-03-26`; an unknown one is answered with the newest), `ping`, `tools/list`, `tools/call`; a notification is `202` with no body. `?readonly=1` offers only the tools that read and refuses the rest (`-32602`). The tools: `whoami`, `list_workspaces`, `inbox`, `list_approvals`, `list_flows`, `list_runs`, `get_run`, `read_file`, `run_flow`, `decide_approval`, `answer_question`, `message_run`, `stop_run` — see [MCP](mcp#the-tools). `foldrun mcp` serves the same over stdio |
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: