foldrun 20.5.1 → 20.5.2
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/docs/api.md +1 -1
- package/docs/cli.md +1 -1
- package/docs/mcp.md +3 -1
- package/package.json +1 -1
package/docs/api.md
CHANGED
|
@@ -571,7 +571,7 @@ with `HTTP <status>: <the route's error>`.
|
|
|
571
571
|
|
|
572
572
|
| Route | Methods | |
|
|
573
573
|
|---|---|---|
|
|
574
|
-
| `/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 |
|
|
574
|
+
| `/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_agents`, `list_runs`, `get_run`, `read_file`, `run_flow`, `run_agent`, `decide_approval`, `answer_question`, `message_run`, `stop_run` — see [MCP](mcp#the-tools). `foldrun mcp` serves the same over stdio |
|
|
575
575
|
| `/api/mcp/oauth/register` | POST | an AI app registers itself (RFC 7591), before anyone signs it in. Open, as the protocol needs — no key. `{ redirect_uris, client_name?, token_endpoint_auth_method?, grant_types?, response_types?, client_uri? }`: one to ten redirect URIs, each `https` or `http` to localhost, no fragment; `token_endpoint_auth_method` `none` (PKCE alone), `client_secret_post` or `client_secret_basic` (the default). Answers `201 { client_id, client_id_issued_at, client_name, redirect_uris, grant_types, response_types, token_endpoint_auth_method, client_secret?, client_secret_expires_at? }` — the secret only for the two secret methods, shown once. Errors are OAuth's `{ error, error_description }` (`invalid_redirect_uri`, `invalid_client_metadata`); `503` past 5,000 apps on the install An app may register `token_endpoint_auth_method: private_key_jwt` with `jwks` (`{ keys: [...] }`, public keys only) or an https `jwks_uri`; it gets no secret and signs a client assertion at the token and revocation endpoints (RFC 7523: `iss` = `sub` = its client id, `aud` the issuer or the endpoint, at most five minutes, each `jti` once).|
|
|
576
576
|
| `/api/mcp/oauth/authorize` | GET, POST | the person's half of the sign-in, for the page at `/mcp/authorize` — a signed-in person only, never a key or a support view. GET `?request=<the app's query>` checks it and answers `{ client: { name, id, kind, uri }, redirectHost, loopback, scopes, account, person: { email, role }, workspaces, allWorkspaces }`; POST `{ request, decision: approve\|deny, access?: read\|write, workspaces?: [names] \| null }` answers `{ ok, redirect }` — the app's redirect URI with a one-time `code` (ten minutes), `state` and `iss`, or with `error=access_denied`. A request that names an unknown app or a redirect URI it did not register is `400` and never redirected; the rest of its faults (no PKCE `S256` challenge, a `resource` that is not this `/api/mcp`, an unknown scope) come back as `{ redirect }` with OAuth's error. `access: write` needs the app to have asked for `mcp:write`; `workspaces` must be ones the person may open (`403` otherwise) |
|
|
577
577
|
| `/api/mcp/oauth/token` | POST | OAuth 2.1's token endpoint, form-encoded (JSON is read too), no key: `grant_type=authorization_code` with `code`, `redirect_uri`, `code_verifier` (PKCE S256) and `client_id` — or the app's secret, Basic or in the form —, or `grant_type=refresh_token` with `refresh_token`. `resource`, when sent, must be this `/api/mcp`. Answers `{ access_token, token_type: "Bearer", expires_in: 3600, refresh_token, scope }` with `Cache-Control: no-store`. A code is good once, right or wrong. A refresh token is rotated on use; one used twice revokes the whole connection. Errors: `400 invalid_grant` / `invalid_target` / `unsupported_grant_type`, `401 invalid_client` |
|
package/docs/cli.md
CHANGED
|
@@ -280,7 +280,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
280
280
|
| `--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 |
|
|
281
281
|
| `--event-wait` | `reject`: refuse a step waiting on `wait: event` rather than a person's gate |
|
|
282
282
|
| `--note "<text>"` | `approve`: guidance the approved step reads in its prompt — "approve, but skip the Sydney batch". `reject`: the reason, recorded on the trace |
|
|
283
|
-
| `--read-only` | `mcp`: offer the AI app only the tools that read — no `run_flow`, `decide_approval`, `answer_question`, `message_run` or `stop_run` |
|
|
283
|
+
| `--read-only` | `mcp`: offer the AI app only the tools that read — no `run_flow`, `run_agent`, `decide_approval`, `answer_question`, `message_run` or `stop_run` |
|
|
284
284
|
| `--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`, `mcp disconnect`, `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 |
|
|
285
285
|
| `--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`, `signup status`, `team`, `secrets ls`, `triggers`, `storage ls --all`: the raw document |
|
|
286
286
|
| `--events <a,b>` | `account set notify`: which events are notified on — `failed`, `awaiting-approval`, `completed` |
|
package/docs/mcp.md
CHANGED
|
@@ -131,16 +131,18 @@ and that automatic disconnect are in the audit log (`mcp.connected`,
|
|
|
131
131
|
| `inbox` | what waits on you: approvals, questions, issues, proposed fixes, your failed runs (`bucket`, `kind`, `workspace`) | `GET /api/me/inbox` |
|
|
132
132
|
| `list_approvals` | every gate waiting on a person, and every question an agent is asking | `GET /api/approvals` |
|
|
133
133
|
| `list_flows` | a workspace's flows | `GET …/flows` |
|
|
134
|
+
| `list_agents` | a workspace's agents: what each is for and when it last ran | `GET …/agents` |
|
|
134
135
|
| `list_runs` | recent runs, with outcome, summary and failure (`limit` up to 100, default 20; `flow` keeps that flow's among the newest 500) | `GET …/runs` |
|
|
135
136
|
| `get_run` | one run in full | `GET …/runs/<id>` |
|
|
136
137
|
| `read_file` | one file of a workspace's source, or the tree | `GET …/source` |
|
|
137
138
|
| `run_flow` | start a flow (`task`, `test: true` for a [test run](runs#test-runs)) | `POST …/flows/<flow>/run` |
|
|
139
|
+
| `run_agent` | run one agent on a task of your own, in its own sandbox, no flow needed (`task`, `test: true` for a [test run](runs#test-runs)); answers a run id at once — read it with `get_run` | `POST …/agents/<agent>/run` |
|
|
138
140
|
| `decide_approval` | approve or reject a gate (`note`, `step`) | `POST …/runs/<id>/approve` |
|
|
139
141
|
| `answer_question` | answer an agent's question mid-step | `POST …/runs/<id>/answer` |
|
|
140
142
|
| `message_run` | say something to a running agent | `POST …/runs/<id>/message` |
|
|
141
143
|
| `stop_run` | stop a run | `POST …/runs/<id>/stop` |
|
|
142
144
|
|
|
143
|
-
The first
|
|
145
|
+
The first nine read. The last six act, and are marked so for the app
|
|
144
146
|
(`readOnlyHint: false`; `stop_run` also `destructiveHint: true`), which is
|
|
145
147
|
what an app uses to ask you before calling one.
|
|
146
148
|
|