foldrun 20.5.1 → 20.5.3
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 +2 -1
- package/docs/cli.md +1 -1
- package/docs/mcp.md +3 -1
- package/package.json +2 -2
package/docs/api.md
CHANGED
|
@@ -205,6 +205,7 @@ history with each message.
|
|
|
205
205
|
| `/api/workspaces/<ws>/proposals/<id>` | GET, POST | one proposal. `POST { action: "apply" }` writes its files, each a revision by the caller, only when every one still reads what it was drawn against (`409` naming the file that changed) and can be written (`422`; a check error the deploy would refuse is `422` too); `POST { action: "dismiss" }` sets it aside — its failures stay looked at. Only agents, flows and skills are ever in one. Needs `workspace:write` |
|
|
206
206
|
| `/api/workspaces/<ws>/export` | GET | this workspace, one flow or one agent as a `.zip` — `?kind=flow&name=<flow>` (the flow, every flow it runs as a step, every agent those steps and their colleagues name, and the workspace tools, skills and scripts they grant), `?kind=agent&name=<agent>` (its folder and what it grants), or neither for the whole authored tree. Never memory/, state/, outputs/, storage, runs or a secret's value; `foldrun-package.json` inside says what it is. Any role that can read the workspace |
|
|
207
207
|
| `/api/workspaces/<ws>/import` | POST | take a package in; the body is the `.zip` (`content-type: application/zip`, at most 20 MB). `?dryRun=1` answers `{ kind, name, from, creates, added, overwritten, unchanged, needs: { secrets, tools, skills, scripts, agents, flows } }` plus `skipped` (entries it will not write: memory, state, anything outside the authored folders) and writes nothing. Without it, applies as one revision; 409 when it would replace a file with different text unless `?overwrite=1`, or when a file cannot be written there (all or nothing). Never deletes. A `Content-Length` is required (411 without). A workspace package into a name that does not exist makes that workspace (`workspace:manage`, the plan's workspace count). 400 for anything not a package, or one holding memory/, state/ or outputs/. A change to a policy key of the workspace's `AGENTS.md` (`budget`, `compute`, `notify`, `network_enforce`, `telemetry`, `alerts`, `owner`, `judge`, `timezone`) needs `workspace:manage` — `403` naming the key, nothing written ([Team and access](team-and-access#a-workspaces-policy-is-an-admins)). Idempotent |
|
|
208
|
+
| `/api/workspaces/<ws>/snapshots` | POST | send a folder for an agent on foldrun to work on (a snapshot). The body is the folder as a `.tar.gz` (`content-type: application/gzip`, at most 50 MB compressed; a `Content-Length` is required, 411 without) — what `foldrun snapshot push` makes. Checked on the server whatever the client did: plain files and folders only (no links, devices or extended headers), no path that leaves the folder or differs from another only by case, at most 20,000 entries, 10 MB a file and 200 MB unpacked, and no secret — `422` naming the file and line, never the value. Answers `{ snapshotId, files, bytes, compressedBytes, expiresAt, reused }`: `201`, or `200` when this workspace already had this exact folder (`reused`; stored once by its hash). Usable only in this workspace; kept 7 days from the last send, and as long as a run that uses it is kept. An account holds at most 50 snapshots and 2 GB (`422` past either). Needs `snapshot:write` (editor). Idempotent |
|
|
208
209
|
| `/api/workspaces/<ws>/evals` | GET, POST | list; create (`name`) |
|
|
209
210
|
| `/api/workspaces/<ws>/evals/trends` | GET | evals by change, the workspace Observe page's table: `{ workspace, trends: [{ eval, latest, previous, delta }] }`, biggest drop first. `latest` is the eval's newest run and `previous` the most recent run on a DIFFERENT commit (`null` when every run so far was on one) — each `{ eval, at, commit, passed, failed, costUsd }`, `commit` a git sha or a revision id (`r-…`), `null` when no change is on record; `delta` is passed now minus passed then, `null` without a previous. Not windowed: two runs on one commit differ only by the model, so the comparison is always against another commit |
|
|
210
211
|
| `/api/workspaces/<ws>/evals/<eval>/run` | GET, POST | POST runs one eval and answers with its result; with `{ async: true }` it answers `202 { started, eval, runId, startedAt }` at once and the eval runs on — an eval of slow cases outlives a proxy's read timeout (Cloudflare's is 125 s by default). One run of an eval at a time: a second is `409` naming the run that holds it. `GET ?run=<runId>` is what to poll — that run alone, whatever else runs or writes the eval's latest result meanwhile: `{ runId, state, running }` where `state` is `running`, `done` (with its `result`), `failed` (with `error`), `lost` (it stopped reporting before saving a result, e.g. a restart) or `unavailable` (an id not on record — the last 20 runs are kept). Plain `GET` answers who holds the eval now (`running`, `runId`, `startedAt`) and the latest `result`. The dashboard and `foldrun eval --to` start async and poll by run id |
|
|
@@ -571,7 +572,7 @@ with `HTTP <status>: <the route's error>`.
|
|
|
571
572
|
|
|
572
573
|
| Route | Methods | |
|
|
573
574
|
|---|---|---|
|
|
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 |
|
|
575
|
+
| `/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
576
|
| `/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
577
|
| `/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
578
|
| `/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
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "foldrun",
|
|
3
|
-
"version": "20.5.
|
|
3
|
+
"version": "20.5.3",
|
|
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": "^18.
|
|
14
|
+
"@foldrun/core": "^18.2.0"
|
|
15
15
|
},
|
|
16
16
|
"files": [
|
|
17
17
|
"bin",
|