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 +13 -2
- package/docs/a2a.md +330 -0
- package/docs/agents.md +77 -0
- package/docs/api.md +20 -2
- package/docs/checks.md +28 -5
- package/docs/cli.md +12 -2
- package/docs/flows.md +1 -0
- package/docs/glossary.md +5 -0
- package/docs/network.md +3 -2
- package/docs/team-and-access.md +10 -1
- package/docs/tools.md +2 -0
- package/package.json +3 -3
- package/src/commands.mjs +421 -1
- package/src/guide.mjs +1 -1
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>/
|
|
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,
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
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
|
-
|
|
28
|
-
|
|
27
|
+
the card of each outside agent in its `remotes:` (that card's own site — never
|
|
28
|
+
one the card names), and the sites its [secrets are bound to](secrets#bound-to-sites).
|
|
29
|
+
You never list those twice.
|
|
29
30
|
|
|
30
31
|
No level is ever a way into private space: the cluster, the LAN and the
|
|
31
32
|
cloud metadata endpoint are refused whatever `network:` says.
|
package/docs/team-and-access.md
CHANGED
|
@@ -28,7 +28,8 @@ A refused call answers `403` with the role that was needed.
|
|
|
28
28
|
The keys in a workspace's `AGENTS.md` that set policy for the whole
|
|
29
29
|
workspace — `budget`, `compute`, `notify`, `network_enforce`, `telemetry`,
|
|
30
30
|
`alerts`, `owner`, `judge` and `timezone` (also when written under a
|
|
31
|
-
`governance:`, `guardrail:`, `observability:` or `evaluation:` block) —
|
|
31
|
+
`governance:`, `guardrail:`, `observability:` or `evaluation:` block) — and a
|
|
32
|
+
flow's `a2a:`, which decides whether outside agents may call it ([A2A](a2a)) — need
|
|
32
33
|
the **admin** role to change, whichever way the file is written: the
|
|
33
34
|
workspace's settings, a save in the editor (`PUT …/source`), `foldrun deploy`,
|
|
34
35
|
an import, or a restore to an older point. An editor still edits the rest of
|
|
@@ -118,6 +119,14 @@ several accounts — an agency, a reseller — holds one key per account and
|
|
|
118
119
|
switches between them; the CLI stores each as a named profile. See
|
|
119
120
|
[More than one account](cli#more-than-one-account).
|
|
120
121
|
|
|
122
|
+
An **A2A key** is a key of its own kind, for an outside agent calling your
|
|
123
|
+
published flows over [A2A](a2a): one workspace, the flows it names, and how
|
|
124
|
+
many tasks it may have open (`foldrun keys create partner --a2a --to leads
|
|
125
|
+
--flows lead-finder`, or Settings → API keys). It opens only `/a2a/…` — every `/api`
|
|
126
|
+
route refuses it — so it can never read runs, change files, approve a step or
|
|
127
|
+
answer a question. It expires, is revoked and rotated like any key, and a
|
|
128
|
+
rotated one keeps the tasks its predecessor made.
|
|
129
|
+
|
|
121
130
|
### Expiry, last use and rotation
|
|
122
131
|
|
|
123
132
|
A key can be given an end when it is minted — 30, 90 or 365 days, or never
|
package/docs/tools.md
CHANGED
|
@@ -1770,6 +1770,8 @@ limits:
|
|
|
1770
1770
|
|---|---|
|
|
1771
1771
|
| `web.<action>` | one action of the `web` tool; a model provider's own search or fetch (`web: {search: zai}`) counts as `web.search` / `web.fetch` |
|
|
1772
1772
|
| `web` | every web action together |
|
|
1773
|
+
| `a2a` | messages to outside agents (`remotes:`) — `a2a_send` and `a2a_reply` together |
|
|
1774
|
+
| `a2a.<tool>` | one of `a2a.send`, `a2a.reply`, `a2a.status`, `a2a.cancel` — `a2a.status` caps polling apart from sending |
|
|
1773
1775
|
| an HTTP tool's name | every call to it — each operation of an `openapi:` tool, and its generic `call_`, all under the one name |
|
|
1774
1776
|
| a script tool's name | every run of it (`desk-email` and `desk_email` are the same key) |
|
|
1775
1777
|
| an MCP server's name | every tool the server exposes |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "foldrun",
|
|
3
|
-
"version": "10.
|
|
3
|
+
"version": "10.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.
|
|
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
|
|
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
|
|