foldrun 10.1.1 → 10.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/foldrun.mjs +16 -2
- package/docs/a2a.md +330 -0
- package/docs/agents.md +77 -0
- package/docs/api.md +38 -2
- package/docs/checks.md +28 -5
- package/docs/cli.md +14 -2
- package/docs/coding-agents.md +6 -0
- package/docs/flows.md +1 -0
- package/docs/glossary.md +5 -0
- package/docs/mcp.md +127 -0
- package/docs/network.md +3 -2
- package/docs/team-and-access.md +10 -1
- package/docs/tools.md +2 -0
- package/package.json +3 -3
- package/src/commands.mjs +539 -1
- package/src/guide.mjs +1 -1
package/bin/foldrun.mjs
CHANGED
|
@@ -16,6 +16,7 @@
|
|
|
16
16
|
// foldrun report <run-id> one run, whole: every step, what it cost, what it wrote
|
|
17
17
|
// foldrun approvals what is waiting for a person, anywhere in the account
|
|
18
18
|
// foldrun inbox what is waiting on YOU — assigned, started by you, the team's (read, dismiss)
|
|
19
|
+
// foldrun mcp this account as MCP tools for an AI app (Claude, Cursor, Codex), over stdio
|
|
19
20
|
// foldrun approve <run-id> release a waiting gate (asks first) — reject refuses it
|
|
20
21
|
// foldrun stop <run-id> kill a run in flight
|
|
21
22
|
// foldrun account the account's own defaults — timezone, notify, budget, concurrency, deploy_block, network_enforce
|
|
@@ -58,6 +59,7 @@
|
|
|
58
59
|
// foldrun doctor what is between this terminal and the platform, checked
|
|
59
60
|
// foldrun accounts every account signed in here; `use <name>` switches
|
|
60
61
|
// foldrun keys <verb> ls / create / revoke — the account's API keys
|
|
62
|
+
// foldrun a2a <verb> ls / publish / unpublish / card / call / status / cancel — flows served to outside agents (A2A 1.0)
|
|
61
63
|
// foldrun library <verb> ls / cat / put / new / rm — the account's shared shelf on the platform
|
|
62
64
|
// foldrun find <words> search the account the way the dashboard's ⌘K does
|
|
63
65
|
// foldrun changelog what each release of the platform changed
|
|
@@ -167,6 +169,7 @@ const HELP = `foldrun — agents are just folders
|
|
|
167
169
|
foldrun insights recurring problems found in the runs, with what they cost and what to do (--days, --to, --json)
|
|
168
170
|
foldrun inbox what waits on you: approvals, questions, issues, proposed fixes, your failed runs (--team, --all, --kind, --unread, --dismissed)
|
|
169
171
|
foldrun inbox read|unread|dismiss|restore <id>… mark items in your own view (dismiss sets aside; it still waits where it lives)
|
|
172
|
+
foldrun mcp this account as MCP tools for an AI app, over stdio, with this machine's sign-in: \`claude mcp add foldrun -- foldrun mcp\` (--read-only: only the tools that read)
|
|
170
173
|
foldrun issues what went wrong, grouped, open until resolved (--to <workspace>, --all, --status, --json)
|
|
171
174
|
foldrun issues show|ack|snooze|resolve|reopen <id> one issue — snooze --for 1d or --times 5, --note "…"
|
|
172
175
|
foldrun issues doctor <id> the run doctor on the issue's newest run, in its workspace: why, and the fix as diffs, saved on yes (--yes, --dry-run, --json)
|
|
@@ -259,6 +262,13 @@ Signing in
|
|
|
259
262
|
foldrun accounts every account signed in on this machine, and which one is active
|
|
260
263
|
foldrun use <name> act as one of them from here on
|
|
261
264
|
foldrun keys ls the account's API keys: created, last used, expires, scope — also create <label> [--expires 90d], rotate <id> [--grace 1h], revoke <id>
|
|
265
|
+
foldrun keys create <label> --a2a --to <ws> --flows a,b a key for an OUTSIDE agent: it opens /a2a for those published flows and no /api route (--max-tasks N open at once, default 10; --expires); shown once
|
|
266
|
+
foldrun a2a ls --to <ws> what a workspace serves over A2A: each flow's a2a:, card and endpoint URLs, its A2A keys (admins), recent tasks and the key that asked (--json)
|
|
267
|
+
foldrun a2a publish <flow> set a2a: publish: true in the flow (--to <ws>: the deployed copy, an admin's) — --name, --description, --example "…" (repeatable), --public-card | --private-card; diff, checked, --dry-run
|
|
268
|
+
foldrun a2a unpublish <flow> a2a: publish: false — no outside agent may call it; the rest of a2a: is kept (--to <ws>, --dry-run)
|
|
269
|
+
foldrun a2a card <flow> --to <ws> the flow's agent card URL and endpoint, then the card (a private card needs an A2A key in $FOLDRUN_A2A_KEY or --key-env)
|
|
270
|
+
foldrun a2a call <card-url> "<text>" send one message to an A2A 1.0 agent — a published flow or anyone's — and wait for the task (--data <json|@file>, --context <id>, --no-wait, --max-wait <s>, --json); the A2A key comes from $FOLDRUN_A2A_KEY or --key-env NAME, never this CLI's API key
|
|
271
|
+
foldrun a2a status <task-id> --card <url> the task as it stands now (--json) — cancel <task-id> --card <url> stops it (asks; --yes)
|
|
262
272
|
foldrun audit the account's audit log, newest first: sign-ins, keys, invites, secrets by name, deploys, support views (--since 7d, --action, --actor, --to, --all, --csv)
|
|
263
273
|
foldrun --version this CLI's version, offline (\`foldrun version\` also asks the platform)
|
|
264
274
|
foldrun --help everything; \`foldrun <command> --help\`, \`-h\` or \`foldrun help <command>\` for one (never runs it)
|
|
@@ -297,6 +307,7 @@ Options
|
|
|
297
307
|
--schedule "<cron>" flow trigger: the cron line a schedule fires on (5 fields, or @daily); --timezone <zone> the zone it is read in
|
|
298
308
|
--team, --started, --mine, --all inbox: which bucket (default: assigned to you and started by you)
|
|
299
309
|
--dismissed, --unread inbox: what you set aside; only what you have not read
|
|
310
|
+
--read-only mcp: offer the AI app only the tools that read — no run, approve, answer, message or stop
|
|
300
311
|
--models <m[:effort],…> eval compare: two to four tiers or model ids to compare, each with an optional :effort
|
|
301
312
|
--max-usd <n> eval compare: the spend limit — no run starts once the runs and judges have spent it (default 5)
|
|
302
313
|
--payload <file|-|json> flow filter: the delivery to test — a file, - for stdin, or JSON inline
|
|
@@ -370,6 +381,9 @@ Options
|
|
|
370
381
|
--role <r> keys create: viewer, editor (default) or admin
|
|
371
382
|
--expires <span> keys create: when it stops working — 30d, 90d, 365d or never (default never)
|
|
372
383
|
--grace <span> keys rotate: keep the old key working for 1h or 24h while you swap the new one in (default 0: revoked now)
|
|
384
|
+
--a2a keys create: an A2A key for an outside agent — with --to <workspace> and --flows a,b; --max-tasks <n> caps its open tasks (1–100, default 10)
|
|
385
|
+
--key-env <NAME> a2a call, a2a status, a2a cancel, a2a card: the environment variable holding the A2A key (default FOLDRUN_A2A_KEY) — a key is never taken on the command line
|
|
386
|
+
--card <url> a2a status, a2a cancel: the agent card of the agent that holds the task
|
|
373
387
|
|
|
374
388
|
Platform options (deploy, invoke, secrets, logs, keys)
|
|
375
389
|
--to <workspace> workspace on the platform (deploy default: folder name); flow add/show, agent link: edit or show the deployed copy instead of this folder; hook test: run the deployed hook on the platform; hook ls: list the deployed workspace's hooks and what they did lately; restore <ws>: the commit, date or age to put it back to (3d, 2026-09-28T14:00)
|
|
@@ -410,9 +424,9 @@ if (!command || command === "--help" || command === "-h") {
|
|
|
410
424
|
// `--value` as the account's argument and stored an empty secret; `--force
|
|
411
425
|
// ./dir` swallowed the directory. A flag followed by another flag is also
|
|
412
426
|
// boolean, so an unlisted switch at least does not eat its neighbour.
|
|
413
|
-
const BOOLEAN_FLAGS = new Set(["account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear", "security", "changed", "write-baseline", "no-baseline", "rules", "calls", "tree", "tool-error", "stop", "last", "no-pkce", "export", "isolated", "no-wait", "dismissed", "unread", "team", "started", "mine", "none"]);
|
|
427
|
+
const BOOLEAN_FLAGS = new Set(["read-only", "account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear", "security", "changed", "write-baseline", "no-baseline", "rules", "calls", "tree", "tool-error", "stop", "last", "no-pkce", "export", "isolated", "no-wait", "dismissed", "unread", "team", "started", "mine", "none", "a2a", "public-card", "private-card", "return-immediately"]);
|
|
414
428
|
// Flags said more than once collect into a list: `--tag a --tag b`.
|
|
415
|
-
const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove", "rule", "authorize-param"]);
|
|
429
|
+
const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove", "rule", "authorize-param", "example"]);
|
|
416
430
|
// `--wait` is a switch everywhere but `flow add <flow> wait`, where it takes
|
|
417
431
|
// a span: `--wait 30m`, `--wait event`. Only a value that reads as one is
|
|
418
432
|
// taken, so `invoke x --wait` and friends are as they were.
|
package/docs/a2a.md
ADDED
|
@@ -0,0 +1,330 @@
|
|
|
1
|
+
# A2A: outside agents
|
|
2
|
+
|
|
3
|
+
[A2A](https://a2a-protocol.org/v1.0.0/specification/) (Agent2Agent) is an
|
|
4
|
+
open protocol for one agent to hand a task to another agent run by somebody
|
|
5
|
+
else. foldrun speaks the released **1.0** version, over JSON-RPC 2.0 on HTTP,
|
|
6
|
+
in both directions:
|
|
7
|
+
|
|
8
|
+
- **Serving:** you publish a flow, and an outside agent holding an A2A key
|
|
9
|
+
sends it a request, follows the task, and reads the result.
|
|
10
|
+
- **Calling:** an agent of yours lists outside agents in `remotes:` and calls
|
|
11
|
+
them with four tools.
|
|
12
|
+
|
|
13
|
+
Your own files do not change shape for either. A2A is a door at the edge: a
|
|
14
|
+
published flow is the same flow, and a remote is reached the way an `apis:`
|
|
15
|
+
entry is.
|
|
16
|
+
|
|
17
|
+
## Publishing a flow
|
|
18
|
+
|
|
19
|
+
A flow is served over A2A when its frontmatter says so:
|
|
20
|
+
|
|
21
|
+
```markdown
|
|
22
|
+
---
|
|
23
|
+
trigger: manual
|
|
24
|
+
a2a:
|
|
25
|
+
publish: true
|
|
26
|
+
name: Lead researcher # the agent card's name; else the flow's
|
|
27
|
+
description: Finds three qualified leads for a business type and city.
|
|
28
|
+
examples: ["Dentists in Perth", "Accountants in Hobart"]
|
|
29
|
+
public_card: false # true: the card is readable without a key
|
|
30
|
+
input: # optional: a JSON Schema the request's data part must match
|
|
31
|
+
type: object
|
|
32
|
+
required: [city]
|
|
33
|
+
properties: { city: { type: string } }
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
1. [[researcher]] — Find three leads for the request.
|
|
37
|
+
2. [[writer]] — Write them up as a short list.
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
| key | |
|
|
41
|
+
|---|---|
|
|
42
|
+
| `publish` | required, `true` or `false`. `false` keeps the block and serves nothing |
|
|
43
|
+
| `name` | the card's (and its one skill's) name, up to 100 characters. Unset: the flow's name |
|
|
44
|
+
| `description` | what a caller reads about it, up to 2,000 characters. Unset: the flow's `description:` |
|
|
45
|
+
| `examples` | up to 10 example requests, 500 characters each |
|
|
46
|
+
| `public_card` | `true` lets anyone read the card without a key. Calling the flow always needs one. Default `false` |
|
|
47
|
+
| `input` | a JSON Schema (up to 16,000 bytes as JSON). With it, every request must carry a data part that matches it, and a request that does not is refused before anything starts |
|
|
48
|
+
|
|
49
|
+
A block `foldrun check` cannot read publishes nothing — a typo never opens a
|
|
50
|
+
flow nobody meant to open. Whether a flow is published is the workspace's
|
|
51
|
+
policy, so changing `a2a:` needs the **admin** role (`workspace:manage`) by
|
|
52
|
+
every door: the editor, a deploy, `PATCH /flows/<f>`, `PUT /source`. An
|
|
53
|
+
editor's change that leaves `a2a:` as it was goes through.
|
|
54
|
+
|
|
55
|
+
From the dashboard: **Flows**, the flow's card, **Publish over A2A…**
|
|
56
|
+
(admins only; others see it read-only) — it edits the block through
|
|
57
|
+
`PATCH /api/workspaces/<ws>/flows/<f>` `{ a2a: {…} }` (merged over what the
|
|
58
|
+
flow says: a key sent replaces it, `null` removes it, `a2a: null` removes the
|
|
59
|
+
block) and shows the card URL and a `curl` to try it. From the terminal:
|
|
60
|
+
|
|
61
|
+
```sh
|
|
62
|
+
foldrun a2a publish lead-finder --to sales --name "Lead researcher" --description "Finds three leads"
|
|
63
|
+
foldrun a2a card lead-finder --to sales # the card URL, and the card
|
|
64
|
+
foldrun a2a ls --to sales # what the workspace serves, and its recent tasks
|
|
65
|
+
foldrun a2a unpublish lead-finder --to sales
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
The workspace's **Triggers** page, section **Outside agents (A2A)** (and
|
|
69
|
+
`GET /api/workspaces/<ws>/a2a`), lists every
|
|
70
|
+
flow that says `a2a:`, its card and endpoint URLs, the workspace's A2A keys and
|
|
71
|
+
the newest tasks with the key that asked.
|
|
72
|
+
|
|
73
|
+
`foldrun check` warns on a published flow that is risky to open
|
|
74
|
+
([below](#security)).
|
|
75
|
+
|
|
76
|
+
## A2A keys
|
|
77
|
+
|
|
78
|
+
A caller needs an **A2A key**: a key of its own kind, minted by an admin of
|
|
79
|
+
the workspace, for one workspace and the flows it names.
|
|
80
|
+
|
|
81
|
+
```sh
|
|
82
|
+
foldrun keys create "Partner CRM" --a2a --to sales --flows lead-finder,quote --max-tasks 5
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
or **Settings → API keys**, kind **A2A key**: the workspace, the published
|
|
86
|
+
flows it may call, and how many tasks it may have open at once. The key is
|
|
87
|
+
shown once.
|
|
88
|
+
|
|
89
|
+
- It opens `/a2a/<account>/<workspace>/…` for its flows and nothing else.
|
|
90
|
+
Every `/api` route refuses it (`403`): not runs, not source, not approvals,
|
|
91
|
+
not storage, not secrets.
|
|
92
|
+
- A flow must be both **named by the key** and **published**. Both are read
|
|
93
|
+
on every call, so unpublishing a flow closes it to every key at once.
|
|
94
|
+
- `maxTasks` — its tasks open at once, 1 to 100, default 10. Past it,
|
|
95
|
+
`SendMessage` is refused with `TOO_MANY_TASKS` until one ends or is
|
|
96
|
+
canceled.
|
|
97
|
+
- It expires, is revoked and is rotated like any key (`expires`,
|
|
98
|
+
`foldrun keys rotate`). A task belongs to the key that made it; a rotated
|
|
99
|
+
key keeps its predecessor's tasks, so the caller can still read and cancel
|
|
100
|
+
them.
|
|
101
|
+
- It counts in its account's rate limit with its own bucket, like any key.
|
|
102
|
+
|
|
103
|
+
The API: `POST /api/keys { purpose: "a2a", workspace, flows, maxTasks?, label?, expires? }`
|
|
104
|
+
([api](api#account)).
|
|
105
|
+
|
|
106
|
+
## Calling a published flow
|
|
107
|
+
|
|
108
|
+
Each published flow has three addresses. `<account>` is your account's name;
|
|
109
|
+
the flow's page and `foldrun a2a card` show them whole.
|
|
110
|
+
|
|
111
|
+
| | |
|
|
112
|
+
|---|---|
|
|
113
|
+
| `GET /a2a/<account>/<ws>/flows/<flow>/.well-known/agent-card.json` | the agent card: name, description, examples, the endpoint, `streaming: false`, `pushNotifications: false`, and the bearer scheme. With a key that names the flow, or without one when `public_card: true` |
|
|
114
|
+
| `POST /a2a/<account>/<ws>/flows/<flow>` | the JSON-RPC endpoint |
|
|
115
|
+
| `GET /a2a/<account>/<ws>` | the flows this key may call here, each with its card and endpoint — a convenience index, not an A2A operation |
|
|
116
|
+
|
|
117
|
+
Every call sends the key as `Authorization: Bearer mda_…` and the protocol
|
|
118
|
+
version as `A2A-Version: 1.0` (or `?A2A-Version=1.0`). A request without the
|
|
119
|
+
header is A2A 0.3, which is not served: it is answered
|
|
120
|
+
`VersionNotSupportedError` (`-32009`). A session cookie never opens `/a2a`.
|
|
121
|
+
|
|
122
|
+
Send a request:
|
|
123
|
+
|
|
124
|
+
```sh
|
|
125
|
+
curl -sS https://foldrun.example.com/a2a/acme/sales/flows/lead-finder \
|
|
126
|
+
-H "authorization: Bearer $A2A_KEY" \
|
|
127
|
+
-H "a2a-version: 1.0" \
|
|
128
|
+
-H "content-type: application/json" \
|
|
129
|
+
-d '{
|
|
130
|
+
"jsonrpc": "2.0", "id": 1, "method": "SendMessage",
|
|
131
|
+
"params": {
|
|
132
|
+
"message": {
|
|
133
|
+
"messageId": "req-2026-11-01-001",
|
|
134
|
+
"role": "ROLE_USER",
|
|
135
|
+
"parts": [
|
|
136
|
+
{ "text": "Dentists, please." },
|
|
137
|
+
{ "data": { "city": "Perth" }, "mediaType": "application/json" }
|
|
138
|
+
]
|
|
139
|
+
},
|
|
140
|
+
"configuration": { "returnImmediately": true }
|
|
141
|
+
}
|
|
142
|
+
}'
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
The answer is the task:
|
|
146
|
+
|
|
147
|
+
```json
|
|
148
|
+
{ "jsonrpc": "2.0", "id": 1, "result": { "task": {
|
|
149
|
+
"id": "6f0c…", "contextId": "b41e…",
|
|
150
|
+
"status": { "state": "TASK_STATE_SUBMITTED", "timestamp": "2026-11-01T09:00:00.000Z" },
|
|
151
|
+
"history": [ { "messageId": "req-2026-11-01-001", "role": "ROLE_USER", "parts": [ … ] } ]
|
|
152
|
+
} } }
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Then poll it until it ends:
|
|
156
|
+
|
|
157
|
+
```sh
|
|
158
|
+
curl -sS https://foldrun.example.com/a2a/acme/sales/flows/lead-finder \
|
|
159
|
+
-H "authorization: Bearer $A2A_KEY" -H "a2a-version: 1.0" -H "content-type: application/json" \
|
|
160
|
+
-d '{"jsonrpc":"2.0","id":2,"method":"GetTask","params":{"id":"6f0c…"}}'
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
From the terminal, `foldrun a2a call <card-url> "<text>" [--data '{"city":"Perth"}'] [--key-env A2A_KEY]`
|
|
164
|
+
does the same against any A2A 1.0 agent, and `foldrun a2a status|cancel <task-id> --card <url>`
|
|
165
|
+
follows one.
|
|
166
|
+
|
|
167
|
+
### What is served
|
|
168
|
+
|
|
169
|
+
| method | |
|
|
170
|
+
|---|---|
|
|
171
|
+
| `SendMessage` | starts the flow. **Blocking by default**: it waits up to 25 seconds (`FOLDRUN_A2A_WAIT_MS`, at most 120) for the run to end, then answers the task as it stands — the caller polls `GetTask` from there. `configuration.returnImmediately: true` answers at once. `configuration.historyLength` trims the history. `acceptedOutputModes` must include `text/plain` or `application/json` (or a wildcard) |
|
|
172
|
+
| `GetTask` | the task by `id`, with `historyLength` |
|
|
173
|
+
| `ListTasks` | this key's tasks on this flow, newest state change first: `pageSize` (1–100, default 50), `pageToken`, `status` (a `TASK_STATE_*`), `contextId`, `statusTimestampAfter`, `includeArtifacts`, `historyLength`. Answers `tasks`, `nextPageToken` (empty on the last page), `pageSize`, `totalSize` |
|
|
174
|
+
| `CancelTask` | stops the run; its trail says "cancelled by A2A caller <key label>". Idempotent: a canceled task canceled again is answered as it is. A task that already ended otherwise is `TaskNotCancelableError` (`-32002`), and so is one still starting (try again in a moment) |
|
|
175
|
+
|
|
176
|
+
Not served, each answered with the error the spec names: `SendStreamingMessage`
|
|
177
|
+
and `SubscribeToTask` (`UnsupportedOperationError`, `-32004` — poll instead),
|
|
178
|
+
the four push-notification methods and a `taskPushNotificationConfig` on a
|
|
179
|
+
send (`PushNotificationNotSupportedError`, `-32003`), and
|
|
180
|
+
`GetExtendedAgentCard` (`-32004`). An unknown method is `-32601`. Batches are
|
|
181
|
+
not taken: one request object per call.
|
|
182
|
+
|
|
183
|
+
A task takes **one message**. A follow-up `SendMessage` with the task's
|
|
184
|
+
`taskId` is refused (`-32004`); send a new message without `taskId`, with the
|
|
185
|
+
`contextId` to keep the conversation together.
|
|
186
|
+
|
|
187
|
+
### Retries: `messageId`
|
|
188
|
+
|
|
189
|
+
`messageId` is the request's identity. Send the same message again with the
|
|
190
|
+
same `messageId` — after a timeout, a dropped connection — and you get the
|
|
191
|
+
task it already made; nothing starts twice. The same `messageId` with a
|
|
192
|
+
different message (other parts, context or metadata) is refused
|
|
193
|
+
(`-32602`, `InvalidParams`): a new message needs a new id. The JSON-RPC `id`
|
|
194
|
+
is only correlation and plays no part. A refused start (busy, paused, out of
|
|
195
|
+
funds) makes no task, so the same message may be sent again later as it is.
|
|
196
|
+
|
|
197
|
+
### What a request may carry
|
|
198
|
+
|
|
199
|
+
Text and JSON only. At most 16 parts; the text parts together at most 32,000
|
|
200
|
+
characters; one data part (`application/json`) of at most 64,000 bytes; a
|
|
201
|
+
request body at most 1 MiB. A `raw` or `url` part (a file) is refused with
|
|
202
|
+
`ContentTypeNotSupportedError` (`-32005`). With `input:`, the data part must
|
|
203
|
+
match the schema, and the refusal names each field that does not.
|
|
204
|
+
|
|
205
|
+
The request reaches the flow's first step fenced and marked as coming from an
|
|
206
|
+
outside agent — data to work on, not instructions that change the agent's
|
|
207
|
+
role, tools or limits.
|
|
208
|
+
|
|
209
|
+
### Task states
|
|
210
|
+
|
|
211
|
+
| the run | the task |
|
|
212
|
+
|---|---|
|
|
213
|
+
| queued, not started | `TASK_STATE_SUBMITTED` |
|
|
214
|
+
| running, waiting (`wait:`), parked for a person | `TASK_STATE_WORKING` |
|
|
215
|
+
| completed | `TASK_STATE_COMPLETED` |
|
|
216
|
+
| failed | `TASK_STATE_FAILED` |
|
|
217
|
+
| stopped (by `CancelTask` or a person) | `TASK_STATE_CANCELED` |
|
|
218
|
+
|
|
219
|
+
**A person's part stays with your people.** A step with an approval (`!`),
|
|
220
|
+
an `ask:`, or an agent asking a question (`tools: [ask]`) shows the caller
|
|
221
|
+
`TASK_STATE_WORKING` with the status message "waiting for a person" — never
|
|
222
|
+
who, never a link, never an address. No A2A call can approve, reject or
|
|
223
|
+
answer: those are your team's, in the dashboard, the inbox or the emailed
|
|
224
|
+
link, as for any run. A blocking `SendMessage` waits through a gate only as
|
|
225
|
+
long as its bound, then answers WORKING.
|
|
226
|
+
|
|
227
|
+
On `TASK_STATE_COMPLETED` the task carries one artifact, `result`: the
|
|
228
|
+
flow's final result as a text part (`text/plain`, at most 64,000 characters),
|
|
229
|
+
and a data part (`application/json`, at most 256,000 bytes) when the last
|
|
230
|
+
step answered `output: json`. Nothing else of the run is shown — no run id,
|
|
231
|
+
steps, agents, costs, approvers or files. No files go out, no stream, no push.
|
|
232
|
+
|
|
233
|
+
### Errors
|
|
234
|
+
|
|
235
|
+
Errors are JSON-RPC error objects with a `google.rpc.ErrorInfo` in `data`. A
|
|
236
|
+
request foldrun cannot take **now** is `-32000` with a foldrun reason:
|
|
237
|
+
|
|
238
|
+
| reason | |
|
|
239
|
+
|---|---|
|
|
240
|
+
| `BUSY` | the flow is `overlap: skip` and a run is live — send the same message later |
|
|
241
|
+
| `PAUSED` | the workspace or account is paused |
|
|
242
|
+
| `UNAVAILABLE` | out of budget or funds, or otherwise not taking work |
|
|
243
|
+
| `RATE_LIMITED` | the key's rate limit (`429` from the proxy carries `Retry-After`) |
|
|
244
|
+
| `TOO_MANY_TASKS` | the key has `maxTasks` open |
|
|
245
|
+
| `UNAUTHENTICATED` | no key, or a wrong, revoked or expired one (HTTP `401`) |
|
|
246
|
+
| `PERMISSION_DENIED` | a key that is not an A2A key (HTTP `403`) |
|
|
247
|
+
| `AGENT_NOT_FOUND` | the flow is not published, not named by the key, or not there — all alike (HTTP `404`) |
|
|
248
|
+
|
|
249
|
+
A task of another key, flow or workspace is `TaskNotFoundError` (`-32001`),
|
|
250
|
+
never "not yours".
|
|
251
|
+
|
|
252
|
+
A run started over A2A goes through the same admission as one started from
|
|
253
|
+
the dashboard: pause, money, `budget:`, plan limits and `overlap:` hold for an
|
|
254
|
+
outside agent exactly as for a person. In the runs list and on the run page
|
|
255
|
+
it shows **A2A · <key label>**.
|
|
256
|
+
|
|
257
|
+
## Calling outside agents: `remotes:`
|
|
258
|
+
|
|
259
|
+
An agent of yours may call A2A agents somebody else runs. You list them; the
|
|
260
|
+
agent calls them by name.
|
|
261
|
+
|
|
262
|
+
```yaml
|
|
263
|
+
---
|
|
264
|
+
name: buyer
|
|
265
|
+
remotes:
|
|
266
|
+
- name: invoice-checker
|
|
267
|
+
card: https://agents.example.com/.well-known/agent-card.json
|
|
268
|
+
secret: INVOICE_AGENT_TOKEN # optional: a vault NAME, sent as a bearer token
|
|
269
|
+
description: Checks an invoice against its purchase order.
|
|
270
|
+
limits: { a2a: 10 }
|
|
271
|
+
---
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
It gets four tools — `a2a_send`, `a2a_status`, `a2a_reply`, `a2a_cancel` —
|
|
275
|
+
that work by **handle**: a send answers a handle at once and waits a bounded
|
|
276
|
+
time (default 60 seconds, at most 300) for the answer; a wait that runs out
|
|
277
|
+
says "still running", and `a2a_status` picks it up. A slow remote is never
|
|
278
|
+
sent the request twice. The model never sees the card URL or the token.
|
|
279
|
+
|
|
280
|
+
- The card's own site joins the agent's [network](network), and nothing the
|
|
281
|
+
card says does: a card whose interface is at another origin is refused.
|
|
282
|
+
- The secret is bound to the card's origin and filled by the egress proxy on
|
|
283
|
+
the way out; it never enters the sandbox.
|
|
284
|
+
- What a remote answers is untrusted — fenced as data from someone else's
|
|
285
|
+
system.
|
|
286
|
+
- `limits: {a2a: N}` caps the messages a step sends; `a2a.status` caps
|
|
287
|
+
polling apart from sending.
|
|
288
|
+
- Test runs send nothing.
|
|
289
|
+
|
|
290
|
+
Every field and rule is in [agents](agents#calling-an-outside-agent-remotes).
|
|
291
|
+
|
|
292
|
+
## Limits
|
|
293
|
+
|
|
294
|
+
| | |
|
|
295
|
+
|---|---|
|
|
296
|
+
| card name / description | 100 / 2,000 characters |
|
|
297
|
+
| examples | 10, of 500 characters each |
|
|
298
|
+
| `input:` schema | 16,000 bytes as JSON |
|
|
299
|
+
| a request | 16 parts; 32,000 characters of text; one data part of 64,000 bytes; 1 MiB body |
|
|
300
|
+
| a result | 64,000 characters of text; 256,000 bytes of JSON |
|
|
301
|
+
| an A2A key | up to 50 flows; 1–100 tasks open (default 10) |
|
|
302
|
+
| a blocking `SendMessage` | 25 s by default, at most 120 s (`FOLDRUN_A2A_WAIT_MS`) |
|
|
303
|
+
| `ListTasks` | 100 a page |
|
|
304
|
+
| a calling step | 50 messages and 600 polls, whatever `limits:` says |
|
|
305
|
+
|
|
306
|
+
Ended tasks are kept 90 days.
|
|
307
|
+
|
|
308
|
+
## Security
|
|
309
|
+
|
|
310
|
+
- **Everything a caller sends is untrusted input.** It reaches the first step
|
|
311
|
+
as data, fenced; your tool grants, network, bound secrets and human gates
|
|
312
|
+
hold whatever it says. Publishing does not widen what an agent may do — it
|
|
313
|
+
widens who can ask.
|
|
314
|
+
- **`foldrun check` warns on two shapes** of published flow (warnings, not
|
|
315
|
+
errors): [`security/published-flow-trifecta`](checks#securitypublished-flow-trifecta)
|
|
316
|
+
— a step agent that holds something private and has a way out, which a
|
|
317
|
+
caller could steer into sending it; and
|
|
318
|
+
[`security/published-flow-ungated`](checks#securitypublished-flow-ungated)
|
|
319
|
+
— a step that acts outside the workspace with no approval or `ask:` before
|
|
320
|
+
it, which any key holder starts. Put a gate (`2!.`) on it, or take a leg
|
|
321
|
+
away.
|
|
322
|
+
- **A public card is metadata only**: the name, description and examples you
|
|
323
|
+
wrote, the endpoint and the auth scheme — never steps, agents or files.
|
|
324
|
+
It never lets anyone call the flow. Anonymous card reads are rate-limited.
|
|
325
|
+
Without a key, a private card and no card answer the same `401`.
|
|
326
|
+
- **Tokens never enter a sandbox**, in either direction: an A2A key is
|
|
327
|
+
checked at the edge and never reaches the run; a remote's secret is filled
|
|
328
|
+
by the egress proxy for that remote's origin alone.
|
|
329
|
+
- **Nothing a caller does reaches your people's decisions.** Approvals and
|
|
330
|
+
questions stay in foldrun; the caller sees only "waiting for a person".
|
package/docs/agents.md
CHANGED
|
@@ -96,6 +96,7 @@ the point of the week; a step that weighs two arguments and picks one is not.
|
|
|
96
96
|
| `hooks` | your own code at every tool call, step start and step end — refuse, rewrite, add context — the same on every model ([Hooks](hooks)). Also in a workspace's or the account's `AGENTS.md` for every agent under it |
|
|
97
97
|
| `apis` | an HTTP API declared inline, as one tool |
|
|
98
98
|
| `mcpServers` | an MCP server declared inline |
|
|
99
|
+
| `remotes` | outside agents it may call over A2A — `[{name, card, secret?, description?}]`: the four `a2a_*` tools, and each card's own site added to its network ([below](#calling-an-outside-agent-remotes)) |
|
|
99
100
|
| `secrets` | vault entries its tools may use — names only, never values. The names the step's own model call uses (`ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_CUSTOM_HEADERS`, the `ANTHROPIC_*_MODEL` tiers, `CLAUDE_CODE_OAUTH_TOKEN`, `FOLDRUN_MODEL_KEY`) never replace the model's own settings, and `foldrun check` warns: script and API tools and `verify:` get the declared value under that name, but the agent's own shell sees the model's — give it another name (`MY_ANTHROPIC_KEY`), or run the model on it with `provider:` |
|
|
100
101
|
| `limits` | the most calls one step may make — per tool, per web action, or in all: `limits: {web.search: 40, crm: 20, calls: 300, repeat: 5}` (`repeat`: the same call with the same input). A call past a limit is refused, never run ([Tools](tools#limits--how-many-calls-a-step-may-make)) |
|
|
101
102
|
| `network` | which sites its sandbox may reach: `open`, `trusted` or `none`, or a list of sites added to the trusted list — `network: [api.hubapi.com]`. Unset, an agent that may fetch or browse the web is `open` and every other `trusted`. Also in a workspace's or the account's `AGENTS.md` ([Network](network)) |
|
|
@@ -209,6 +210,82 @@ tools:
|
|
|
209
210
|
`{bash: ask}` is accepted for per-call approval in Claude Code; platform runs
|
|
210
211
|
disable ask-mode and log that they did.
|
|
211
212
|
|
|
213
|
+
## Calling an outside agent: `remotes:`
|
|
214
|
+
|
|
215
|
+
An agent can hand a request to an agent somebody else runs, over the
|
|
216
|
+
Agent2Agent protocol (A2A 1.0, JSON-RPC). You name the remote; the agent
|
|
217
|
+
calls it by that name and never sees a URL or a token.
|
|
218
|
+
|
|
219
|
+
```yaml
|
|
220
|
+
remotes:
|
|
221
|
+
- name: invoice-checker
|
|
222
|
+
card: https://agents.example.com/.well-known/agent-card.json
|
|
223
|
+
secret: INVOICE_AGENT_TOKEN # optional: a vault NAME, sent as a bearer token
|
|
224
|
+
description: Checks an invoice against its purchase order.
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
| key | |
|
|
228
|
+
|---|---|
|
|
229
|
+
| `name` | kebab-case — what the agent calls it by |
|
|
230
|
+
| `card` | the https URL of the remote's agent card. Plain http, to `localhost` only, is for a laptop (or an install whose operator set `FOLDRUN_EGRESS_ALLOW_PRIVATE=1`); a hosted install calls https cards only, and never a private or internal address |
|
|
231
|
+
| `secret` | optional — the NAME of a vault secret, sent as `Authorization: Bearer …` to the card's origin and nowhere else |
|
|
232
|
+
| `description` | your words for it, the only text about the remote in the agent's prompt (the card's own text is the remote's, and is not trusted) |
|
|
233
|
+
|
|
234
|
+
It gives the agent four tools:
|
|
235
|
+
|
|
236
|
+
| tool | |
|
|
237
|
+
|---|---|
|
|
238
|
+
| `a2a_send(remote, text, data?, wait_seconds?)` | sends one request (text, and JSON as a data part) and waits, at most `wait_seconds` (default 60, at most 300), for the answer. Returns a handle with the answer or where the remote got to |
|
|
239
|
+
| `a2a_status(handle, wait_seconds?)` | where it got to, and the answer once it is done |
|
|
240
|
+
| `a2a_reply(handle, text, data?)` | answers a remote that asked for more (`input-required`) |
|
|
241
|
+
| `a2a_cancel(handle)` | asks the remote to stop; safe to repeat |
|
|
242
|
+
|
|
243
|
+
A slow remote is never sent the request twice. The remote's task id is kept
|
|
244
|
+
(in `workspace/state/a2a/<agent>/`) before any waiting starts, so a wait that
|
|
245
|
+
runs out says "still running" with the handle, and `a2a_status` picks it up —
|
|
246
|
+
in the same step, a retry of it, or a later step of the same run. The same
|
|
247
|
+
request asked again in a step returns its handle. A request that ended without
|
|
248
|
+
success may be sent again on purpose.
|
|
249
|
+
|
|
250
|
+
What it may reach and send:
|
|
251
|
+
|
|
252
|
+
- **Network.** Each card's own site joins the agent's [network](network), and
|
|
253
|
+
nothing the card says does: a card whose JSON-RPC interface is at another
|
|
254
|
+
origin is refused, and a redirect is never followed.
|
|
255
|
+
- **The secret** is granted to the card's origin at the egress proxy, which
|
|
256
|
+
fills it on the way out; it never enters the sandbox, even for a step whose
|
|
257
|
+
scripts get their secrets as values. On a laptop (`foldrun run`) it reaches
|
|
258
|
+
the four tools alone: no script, shell or consulted colleague sees it. Name
|
|
259
|
+
it under the agent's own `secrets:` too only if a script really needs it. A secret the vault binds to other sites
|
|
260
|
+
is not sent to a remote outside them — that remote is not called.
|
|
261
|
+
- **Size.** A card is read to 64 KiB and an answer to 1 MiB. Text and JSON
|
|
262
|
+
only: a file part in an answer is named, never fetched.
|
|
263
|
+
- **Untrusted.** What a remote answers reaches the model fenced as data from
|
|
264
|
+
another organisation's system, with invisible characters removed. An agent
|
|
265
|
+
with `remotes:` counts as reading untrusted content in the
|
|
266
|
+
[lethal-trifecta check](checks#securitylethal-trifecta).
|
|
267
|
+
- **Limits.** `limits: {a2a: 10}` caps the messages a step sends (`a2a_send`
|
|
268
|
+
and `a2a_reply`); `a2a.status`, `a2a.send`, `a2a.reply` and `a2a.cancel` cap
|
|
269
|
+
each tool alone, so polling is capped apart from sending. A step sends at
|
|
270
|
+
most 50 messages and polls at most 600 times whatever `limits:` says.
|
|
271
|
+
- **Test runs** send nothing: `a2a_send`, `a2a_reply` and `a2a_cancel` say
|
|
272
|
+
what they would have sent.
|
|
273
|
+
- **Retries.** An agent with `remotes:` acts outside the workspace, like one
|
|
274
|
+
holding an `outward: true` tool: a step that called a tool and then failed
|
|
275
|
+
its `verify:` or `output:` check is not run again on its own, so the work is
|
|
276
|
+
not asked for twice in other words.
|
|
277
|
+
|
|
278
|
+
`permissionMode: plan` withholds the four tools.
|
|
279
|
+
|
|
280
|
+
remotes: are not available to shared-sandbox sub-agents yet; give the
|
|
281
|
+
sub-agent `sandbox: own` or call the remote from the parent. A sub-agent
|
|
282
|
+
delegated to inside its parent's step (the default, `sandbox: parent`) never
|
|
283
|
+
gets the `a2a_*` tools — they are the parent's, with the parent's remotes and
|
|
284
|
+
credentials — and a call to one is refused; the step's trace and the
|
|
285
|
+
sub-agent's prompt say so when it declares `remotes:`. A `sandbox: own`
|
|
286
|
+
sub-agent runs each job as a step of its own and gets its own `remotes:`, from
|
|
287
|
+
its own file, with its own secrets and network.
|
|
288
|
+
|
|
212
289
|
## Consulting colleagues
|
|
213
290
|
|
|
214
291
|
```yaml
|
package/docs/api.md
CHANGED
|
@@ -143,7 +143,8 @@ installer's `error`, its cause on the first line. `foldrun deploy` polls it afte
|
|
|
143
143
|
| Route | Methods | |
|
|
144
144
|
|---|---|---|
|
|
145
145
|
| `/api/workspaces/<ws>/flows` | GET, POST | list; create (`name`, `pattern`) |
|
|
146
|
-
| `/api/workspaces/<ws>/
|
|
146
|
+
| `/api/workspaces/<ws>/a2a` | GET | what this workspace serves to outside agents over A2A 1.0: `{ flows: [{ flow, published, publicCard, name, description, hasInputSchema, card, url }], keys, tasks: [{ id, flow, state, runId, contextId, key: { id, label, prefix, revoked }, createdAt, updatedAt }] }` — every flow whose frontmatter says `a2a:`, the URL of its agent card and of its JSON-RPC endpoint (`/a2a/<account>/<ws>/flows/<flow>`), the workspace's live A2A keys (`[{ id, label, prefix, flows, maxTasks, expiresAt }]`, or `null` unless you may manage keys), and the 50 newest A2A tasks (`state` a `TASK_STATE_*`) with the key that asked. Publishing is the flow's `a2a:` field, written like any other — changing it needs `workspace:manage`. `404` when the workspace does not exist |
|
|
147
|
+
| `/api/workspaces/<ws>/flows/<flow>` | POST, PATCH, DELETE | edit a step (`step`, `instruction`, `options`, `target`, `subflow`), rearrange (`groups`), set `trigger`, set `compute` (`{ vcpu, memGiB, diskGiB }` or `null` — what one run may hold at once, merged over what the flow says), set `a2a` (`{ publish, name, description, examples, public_card, input }` merged over the flow's `a2a:` — a key sent replaces it, `null` removes it; `a2a: null` removes the block; refused `400` when the result would not read, `403` without the admin role — see [A2A](a2a.md)), a canvas edit (`edit`, or `edits` — at most 200 in one request, `400` past that), undo (`restore` + `expect`); delete. Every PATCH and DELETE takes `expect` — the text the step numbers were read from, or its sha256 — and is refused with `409` and the current `text`, nothing written, when the file no longer reads it (the canvas, the list view's board and step options, and the CLI's `flow add`/`rm-step`/`dup-step --to` send it; the dashboard shows the 409 as "this flow changed since you opened it — reload") |
|
|
147
148
|
| `/api/workspaces/<ws>/flows/draft` | POST, PATCH, DELETE | POST draft a flow with a model: `{ description, flow? }` (`flow` redrafts that one). Returns `{ ok, files: [{ path, content, before, sha256 }], issues: [{ where, message, level }], repaired, notes }` — checked with the deploy's checks and the flow lint, repaired once. **Writes nothing**; save with the source PUT. Needs `workspace:write`; a description over 4,000 characters is `413`; a Chat-Completions `provider:` is `422`. On the platform's models the balance is checked first (`402`) and the call is charged as one ledger line, flow `ai-draft`. PATCH and DELETE, and a POST without `description`, are the edits of a flow that happens to be named `draft`, exactly as at `flows/<flow>` |
|
|
148
149
|
| `/api/workspaces/<ws>/flows/<flow>/run` | POST | start it. An `Idempotency-Key` header, or `idempotencyKey` in the body, makes a retried call safe: a dropped response, a proxy timeout or a CI step that ran twice is answered `started: false` with the `runId` it already started, rather than starting a second run and billing for it. Keys are remembered for 24 hours, per flow |
|
|
149
150
|
| `/api/workspaces/<ws>/flows/<flow>/filter` | POST | test the flow's `filter:` against a delivery without starting anything: `{ payload }` — a webhook's JSON body (or the body as a string, read as JSON), an email's `{ from, to, subject, text }`, a chained run's `{ run, flow, status, ending, verdict, summary }`, a storage event's `{ by, paths }`. Answers `{ flow, trigger, filter, applies, match, reason }` — `reason` names the first condition that failed; a flow with no filter matches everything. Reads the deployed flow; nothing is recorded or charged |
|
|
@@ -350,7 +351,7 @@ Reads return which secrets exist, never their values.
|
|
|
350
351
|
|
|
351
352
|
| Route | Methods | |
|
|
352
353
|
|---|---|---|
|
|
353
|
-
| `/api/keys` | GET, POST, DELETE | API keys — an admin's (`keys:manage`) to list, mint and revoke; any key may revoke itself (DELETE with its own `id`, audited as self — what `foldrun logout` does). POST `label`, `role` (viewer \| editor \| admin, never above your own, default editor), `workspaces` (names, or `null` for all — never wider than your own scope); `expires` (`30d`, `90d`, `365d`, any number of days up to 3650, or `never` — the default; anything else is a 400, never a key that lives forever); returns `{ ok, key, id, prefix, role, workspaces, expiresAt }`, and the key is shown once. GET lists each key with `createdAt`, `createdBy`, `expiresAt`, `lastUsedAt`, `lastIp` and `replacedBy` (the id of the key a rotation replaced it with; `null` until then) — the last-use pair written at most once a minute per key, the address cut to its /24 (IPv4) or /48 (IPv6). A key past its `expiresAt` is refused with 401 `API key expired on <date>`; the owner is emailed seven days before. Mint, revoke and rotate are written to the audit log. POST with `workspace` or `access` is refused (400): those minted deploy keys for the platform's own git, which went on 17 Oct 2026 — a deploy key minted before is refused everywhere (403). A key for one workspace is `workspaces: ["<ws>"]`. DELETE `id`. `?tenant=` / body `tenant` is read only on an install with no users yet (first-run bootstrap), and there, when the install has a setup token (`FOLDRUN_SETUP_TOKEN`, written by the self-hosting installer), only with that token in `X-Foldrun-Setup-Token` |
|
|
354
|
+
| `/api/keys` | GET, POST, DELETE | API keys — an admin's (`keys:manage`) to list, mint and revoke; any key may revoke itself (DELETE with its own `id`, audited as self — what `foldrun logout` does). POST `label`, `role` (viewer \| editor \| admin, never above your own, default editor), `workspaces` (names, or `null` for all — never wider than your own scope); `expires` (`30d`, `90d`, `365d`, any number of days up to 3650, or `never` — the default; anything else is a 400, never a key that lives forever); returns `{ ok, key, id, prefix, role, workspaces, expiresAt }`. POST `{ purpose: "a2a", workspace, flows, maxTasks?, label?, expires? }` mints an A2A key instead: for an outside agent, it opens `/a2a/<account>/<workspace>/…` for the named flows (each must also say `a2a: { publish: true }`) and every `/api` route refuses it (403); `maxTasks` (1–100, default 10) caps its tasks open at once; it answers `{ ok, key, id, prefix, purpose, workspace, flows, maxTasks, role, workspaces, expiresAt }`, and rotating one keeps the tasks it made, and the key is shown once. GET lists each key with `createdAt`, `createdBy`, `expiresAt`, `lastUsedAt`, `lastIp` and `replacedBy` (the id of the key a rotation replaced it with; `null` until then) — the last-use pair written at most once a minute per key, the address cut to its /24 (IPv4) or /48 (IPv6). A key past its `expiresAt` is refused with 401 `API key expired on <date>`; the owner is emailed seven days before. Mint, revoke and rotate are written to the audit log. POST with `workspace` or `access` is refused (400): those minted deploy keys for the platform's own git, which went on 17 Oct 2026 — a deploy key minted before is refused everywhere (403). A key for one workspace is `workspaces: ["<ws>"]`. DELETE `id`. `?tenant=` / body `tenant` is read only on an install with no users yet (first-run bootstrap), and there, when the install has a setup token (`FOLDRUN_SETUP_TOKEN`, written by the self-hosting installer), only with that token in `X-Foldrun-Setup-Token` |
|
|
354
355
|
| `/api/keys/<id>/rotate` | POST | a new key with the old one's label, role, workspaces and deploy scope — and, when it had an end, the same lifetime from today — returned once like a mint (`{ ok, key, id, prefix, role, workspaces, expiresAt, replaced: { id, endsAt } }`). `grace`: `0` (default — the old key is revoked at once), or a duration up to `7d` such as `1h` or `24h`, during which the old key still works and after which it is refused as expired. A key is rotated once: rotating a key already replaced is 409 `this key was already rotated to <prefix>…; rotate that one` — and someone who lost the new key's secret rotates the NEW key, which mints another and ends the lost one (rotating the old one again would leave the lost key working). Two rotations of one key at once mint one key. `keys:manage`; a key outside the caller's scope is 404 — except that a key `foldrun login` minted may rotate **itself**, whatever its role: same label, role, workspaces and 90-day lifetime from today, the old key ending 10 minutes later (`grace` is not read). A retry with the old key inside those 10 minutes — the CLI lost the answer, or could not store it — rotates that replacement instead, when nobody has used it and it is at least 30 seconds old (a younger one is a 409: another command may have just stored it). That is how the CLI renews its sign-in; any other key rotating itself still needs `keys:manage`. Audited as `apikey.rotated` (`self: true` for a self-rotation) |
|
|
355
356
|
| `/api/team` | GET, POST | members with their roles and workspace scope; mint an invite — `role` (viewer \| editor \| admin, default editor), `workspaces` (names, or omit for all), `email` (only that address can accept it; sent through the account's `RESEND_API_KEY` unless `send: false`). An invite works **once**, for seven days, and a newer invite to the same address revokes the older ones still pending. Returns `id`, `path` (the invite's relative URL, shown only here), `expires`, `sent` and any `sendError` either way; the full link is in the mail. Links made before 29 Oct 2026 (`inv1`–`inv3`) are refused |
|
|
356
357
|
| `/api/team/invites?all=1` | GET | the account's invites, newest first — pending ones unless `all=1` (then accepted, revoked and expired too): `{ invites: [{ id, email, role, workspaces, invitedBy, createdAt, expiresAt, status }] }`, `email` `null` for a link anyone may use, `workspaces` `null` for all, `status` `pending` \| `accepted` \| `revoked` \| `expired`. Never the link. `team:manage` — an admin key included; a caller scoped to some workspaces sees only the invites inside its scope |
|
|
@@ -507,3 +508,38 @@ signed-in person, never by a key — mints an ordinary API key at their role.
|
|
|
507
508
|
| `/api/approve/<tenant>/<ws>/<id>?token=` | GET, POST | decide a run parked on a human, from the link in its notification. GET shows what is waiting and two buttons — it never decides, because inbox link-checkers follow GETs. POST `decision` (`approve` or `reject`) and an optional `note`, form-encoded or JSON; answers JSON when `Accept` prefers it. The token is derived from the run id under the install key, not stored, so a key rotation kills every link. Needs `FOLDRUN_PUBLIC_URL` to be minted at all |
|
|
508
509
|
| `/api/workspaces/<ws>/hooks/<flow>` | GET | read the flow's webhook URL without changing it: `{ ok, flow, path, url }` — `path` carries the token, `url` is it made absolute with `FOLDRUN_PUBLIC_URL` (null when that is unset). `workspace:manage`, as rotate and the settings page that shows it, since the URL is a credential. `404` for no such flow, `409` for a flow that is not `trigger: webhook` |
|
|
509
510
|
| `/api/workspaces/<ws>/hooks/<flow>/rotate` | POST | new token, old URLs stop working. `404` for no such flow, `409` for a flow that is not `trigger: webhook`, as GET `…/hooks/<flow>` answers |
|
|
511
|
+
|
|
512
|
+
## A2A — outside agents calling a published flow
|
|
513
|
+
|
|
514
|
+
Outside `/api`, and opened only by an **A2A key** (`Authorization: Bearer mda_…`,
|
|
515
|
+
minted with `POST /api/keys { purpose: "a2a", … }`) — never a session, never an
|
|
516
|
+
API key. They speak [A2A 1.0](a2a) over JSON-RPC 2.0, not this API: no
|
|
517
|
+
`Foldrun-Version` (the route answers `A2A-Version: 1.0` instead, and a call
|
|
518
|
+
without it is refused as 0.3), errors are JSON-RPC error objects, and the
|
|
519
|
+
proxy holds the same raw-path check, body limit (1 MiB), rate limit and
|
|
520
|
+
cross-site rule as for `/api`. A flow the key does not name, or that is not
|
|
521
|
+
published, is `404` like one that does not exist.
|
|
522
|
+
|
|
523
|
+
| Route | Methods | |
|
|
524
|
+
|---|---|---|
|
|
525
|
+
| `/a2a/<account>/<ws>/flows/<flow>/.well-known/agent-card.json` | GET | the flow's agent card — with an A2A key naming the flow, or with none when the flow says `a2a: { public_card: true }` (`Cache-Control: public, max-age=300` then; `private, max-age=60` otherwise; an `ETag`, so `If-None-Match` answers `304`). Without a key every other card is the same `401` |
|
|
526
|
+
| `/a2a/<account>/<ws>/flows/<flow>` | POST | one JSON-RPC call: `SendMessage`, `GetTask`, `ListTasks`, `CancelTask`. Streaming, push notifications and the extended card are answered with the spec's unsupported errors ([what is served](a2a#what-is-served)) |
|
|
527
|
+
| `/a2a/<account>/<ws>` | GET | `{ agents: [{ flow, name, description, card, url }] }` — the published flows this key may call here. A convenience index, not an A2A operation |
|
|
528
|
+
|
|
529
|
+
## MCP — AI apps connecting with a key
|
|
530
|
+
|
|
531
|
+
The platform as an [MCP server](mcp) for Claude Code, Claude Desktop,
|
|
532
|
+
Cursor, Codex and any other MCP client. An **API key** opens it
|
|
533
|
+
(`Authorization: Bearer mda_…`) — never a session cookie, never an A2A key —
|
|
534
|
+
and every tool is a call to one of the routes above, made with that key, so
|
|
535
|
+
it answers what the route would: the key's role, its workspaces and every
|
|
536
|
+
refusal hold. MCP's Streamable HTTP transport, stateless: one JSON-RPC 2.0
|
|
537
|
+
message per request, answered as JSON — no SSE stream, no session id, no
|
|
538
|
+
batches. Errors before a message is read (no key, a refused key, a foreign
|
|
539
|
+
`Origin`, an `MCP-Protocol-Version` it does not speak) are JSON-RPC error
|
|
540
|
+
objects with a real status; a tool whose route refused answers `isError: true`
|
|
541
|
+
with `HTTP <status>: <the route's error>`.
|
|
542
|
+
|
|
543
|
+
| Route | Methods | |
|
|
544
|
+
|---|---|---|
|
|
545
|
+
| `/api/mcp` | POST | one JSON-RPC message: `initialize` (revisions `2025-11-25`, `2025-06-18`, `2025-03-26`; an unknown one is answered with the newest), `ping`, `tools/list`, `tools/call`; a notification is `202` with no body. `?readonly=1` offers only the tools that read and refuses the rest (`-32602`). The tools: `whoami`, `list_workspaces`, `inbox`, `list_approvals`, `list_flows`, `list_runs`, `get_run`, `read_file`, `run_flow`, `decide_approval`, `answer_question`, `message_run`, `stop_run` — see [MCP](mcp#the-tools). `foldrun mcp` serves the same over stdio |
|
package/docs/checks.md
CHANGED
|
@@ -254,11 +254,14 @@ and is not flagged.
|
|
|
254
254
|
### security/lethal-trifecta
|
|
255
255
|
|
|
256
256
|
*warn · ASI01, ASI02, ASI03.* One agent that **reads untrusted content** (the
|
|
257
|
-
`web` tool,
|
|
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:
|