foldrun 10.2.0 → 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 +4 -1
- package/docs/api.md +18 -0
- package/docs/cli.md +2 -0
- package/docs/coding-agents.md +6 -0
- package/docs/mcp.md +127 -0
- package/package.json +2 -2
- package/src/commands.mjs +118 -0
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
|
|
@@ -168,6 +169,7 @@ const HELP = `foldrun — agents are just folders
|
|
|
168
169
|
foldrun insights recurring problems found in the runs, with what they cost and what to do (--days, --to, --json)
|
|
169
170
|
foldrun inbox what waits on you: approvals, questions, issues, proposed fixes, your failed runs (--team, --all, --kind, --unread, --dismissed)
|
|
170
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)
|
|
171
173
|
foldrun issues what went wrong, grouped, open until resolved (--to <workspace>, --all, --status, --json)
|
|
172
174
|
foldrun issues show|ack|snooze|resolve|reopen <id> one issue — snooze --for 1d or --times 5, --note "…"
|
|
173
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)
|
|
@@ -305,6 +307,7 @@ Options
|
|
|
305
307
|
--schedule "<cron>" flow trigger: the cron line a schedule fires on (5 fields, or @daily); --timezone <zone> the zone it is read in
|
|
306
308
|
--team, --started, --mine, --all inbox: which bucket (default: assigned to you and started by you)
|
|
307
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
|
|
308
311
|
--models <m[:effort],…> eval compare: two to four tiers or model ids to compare, each with an optional :effort
|
|
309
312
|
--max-usd <n> eval compare: the spend limit — no run starts once the runs and judges have spent it (default 5)
|
|
310
313
|
--payload <file|-|json> flow filter: the delivery to test — a file, - for stdin, or JSON inline
|
|
@@ -421,7 +424,7 @@ if (!command || command === "--help" || command === "-h") {
|
|
|
421
424
|
// `--value` as the account's argument and stored an empty secret; `--force
|
|
422
425
|
// ./dir` swallowed the directory. A flag followed by another flag is also
|
|
423
426
|
// boolean, so an unlisted switch at least does not eat its neighbour.
|
|
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"]);
|
|
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"]);
|
|
425
428
|
// Flags said more than once collect into a list: `--tag a --tag b`.
|
|
426
429
|
const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove", "rule", "authorize-param", "example"]);
|
|
427
430
|
// `--wait` is a switch everywhere but `flow add <flow> wait`, where it takes
|
package/docs/api.md
CHANGED
|
@@ -525,3 +525,21 @@ published, is `404` like one that does not exist.
|
|
|
525
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
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
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/cli.md
CHANGED
|
@@ -95,6 +95,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
95
95
|
| `foldrun insights` | recurring [problems](runs#insights) found in the last week of runs — a prompt mostly uncached, a big tool result sent again, a retry loop, steps near their timeout — each with why, what to do, about what it cost and the runs it was seen in. `--days <1-30>`, `--to <workspace>`, `--json` |
|
|
96
96
|
| `foldrun inbox` | what waits on you across your workspaces ([your inbox](runs#your-inbox)): gates, questions agents ask, open issues, proposed fixes, your runs that went wrong this week — assigned to you and started by you by default; `--team`, `--started`, `--mine`, `--all`, `--dismissed`, `--kind approval\|question\|issue\|proposal\|run`, `--unread`, `--json`. Each item shows its id; exits 1 when something assigned to you is unread |
|
|
97
97
|
| `foldrun inbox read\|unread\|dismiss\|restore <id>…` | mark items in your own view: `dismiss` sets one aside (it still waits where it lives), `restore` puts it back |
|
|
98
|
+
| `foldrun mcp` | this account as an [MCP server](mcp) on stdin/stdout, for an AI app to start: `claude mcp add foldrun -- foldrun mcp`, `codex mcp add foldrun -- foldrun mcp`. Each line is one JSON-RPC message, forwarded to the platform's `POST /api/mcp` with this machine's sign-in (`--profile`, `--url`, `--token` as for any platform command); stdout carries nothing but protocol. `--read-only` offers only the tools that read. Typed into a terminal it prints how to connect and exits 2 |
|
|
98
99
|
| `foldrun issues` | the account's [issues](runs#issues): what went wrong, grouped, open until someone resolves it — kind, desk and flow (or the platform cause and every desk it hit), how many times since when, the newest reason and what to do. `--to <workspace>` narrows it, `--all` adds resolved ones (`--status open\|acknowledged\|snoozed\|resolved\|all`), `--json` |
|
|
99
100
|
| `foldrun issues show\|ack\|snooze\|resolve\|reopen <id>` | one issue: `show` adds its runs and history; `ack` says you have seen it, `snooze --for 30m\|4h\|1d\|1w` (or `--until <ISO>`, or `--times <n>`: until it happens n more times) hides it for a while, `resolve` closes it until it happens again, `reopen` undoes that. `--note "…"` is kept in its history |
|
|
100
101
|
| `foldrun issues doctor <id>` | the run doctor on an issue's newest run, in that run's workspace — the issue card's **Doctor** button: why (platform, check, work or outside), and the fix as diffs, saved on yes (`--yes`, `--dry-run`, `--json`). A missed schedule has no run and is refused |
|
|
@@ -229,6 +230,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
229
230
|
| `--step <n>` | `approve`, `reject`: decide one gate, numbered as `report` prints it. Without it, every step of that run which is waiting |
|
|
230
231
|
| `--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 |
|
|
231
232
|
| `--note "<text>"` | `approve`: guidance the approved step reads in its prompt — "approve, but skip the Sydney batch". `reject`: the reason, recorded on the trace |
|
|
233
|
+
| `--read-only` | `mcp`: offer the AI app only the tools that read — no `run_flow`, `decide_approval`, `answer_question`, `message_run` or `stop_run` |
|
|
232
234
|
| `--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 |
|
|
233
235
|
| `--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 |
|
|
234
236
|
| `--events <a,b>` | `account set notify`: which events are notified on — `failed`, `awaiting-approval`, `completed` |
|
package/docs/coding-agents.md
CHANGED
|
@@ -107,6 +107,12 @@ report <id>` to read which step failed and what it cost, fix the markdown,
|
|
|
107
107
|
`foldrun deploy`, then `foldrun rerun <id> --from <step>`. `foldrun triggers`
|
|
108
108
|
answers "why did nothing run".
|
|
109
109
|
|
|
110
|
+
An app that cannot run a terminal — Claude Desktop, Cursor's chat — or one
|
|
111
|
+
that would rather call tools than commands reaches the same account through
|
|
112
|
+
[MCP](mcp): `claude mcp add foldrun -- foldrun mcp` gives it the inbox, the
|
|
113
|
+
waiting gates and questions, runs, flows and files, and approve, answer,
|
|
114
|
+
message, start and stop, each as the key could do it.
|
|
115
|
+
|
|
110
116
|
## Writing a flow
|
|
111
117
|
|
|
112
118
|
A numbered list of steps. The number is the GROUP: same number means those
|
package/docs/mcp.md
ADDED
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
# MCP: AI apps
|
|
2
|
+
|
|
3
|
+
foldrun is an [MCP](https://modelcontextprotocol.io) server. An AI app that
|
|
4
|
+
speaks MCP — Claude Code, Claude Desktop, Cursor, Codex — connects to your
|
|
5
|
+
account and gets tools for what you would otherwise open the dashboard for:
|
|
6
|
+
what waits on you, the gates and questions, the runs and flows, a file, and
|
|
7
|
+
the decisions — approve, answer, message, start, stop.
|
|
8
|
+
|
|
9
|
+
Ask it "what is waiting on me in foldrun?", "why did last night's run of
|
|
10
|
+
`weekly` fail?" or "approve the draft in run r-…, and say why".
|
|
11
|
+
|
|
12
|
+
There are two ways in, and they serve the same tools:
|
|
13
|
+
|
|
14
|
+
| | needs | for |
|
|
15
|
+
|---|---|---|
|
|
16
|
+
| `foldrun mcp` | the CLI, signed in (`foldrun login`) | an app on the same machine — nothing to paste |
|
|
17
|
+
| `POST /api/mcp` | an API key | an app that connects over HTTP, or a machine without the CLI |
|
|
18
|
+
|
|
19
|
+
## Connecting
|
|
20
|
+
|
|
21
|
+
With the CLI, on a machine that is signed in:
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
claude mcp add foldrun -- foldrun mcp # Claude Code
|
|
25
|
+
codex mcp add foldrun -- foldrun mcp # Codex
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Claude Desktop, Cursor and other apps that take a JSON config:
|
|
29
|
+
|
|
30
|
+
```json
|
|
31
|
+
{ "mcpServers": { "foldrun": { "command": "foldrun", "args": ["mcp"] } } }
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
`foldrun mcp` forwards each message to the platform the CLI is signed in to,
|
|
35
|
+
as the account `foldrun whoami` names — `--profile <name>` picks another
|
|
36
|
+
signed-in account, `--url` and `--token` (or `FOLDRUN_URL`, `FOLDRUN_TOKEN`)
|
|
37
|
+
another platform or key. It renews this machine's sign-in once when it starts,
|
|
38
|
+
the way every platform command does. Typed into a terminal it prints how to
|
|
39
|
+
connect and exits: it is for an app to start.
|
|
40
|
+
|
|
41
|
+
Over HTTP, with a key from Settings → API keys:
|
|
42
|
+
|
|
43
|
+
```sh
|
|
44
|
+
claude mcp add --transport http foldrun https://<your platform>/api/mcp \
|
|
45
|
+
--header "Authorization: Bearer mda_..."
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Settings → API keys → **Connecting an AI app (MCP)** shows this install's
|
|
49
|
+
address and the same lines. claude.ai's connectors sign in with OAuth, which
|
|
50
|
+
this endpoint does not offer; connect through Claude Desktop or Claude Code.
|
|
51
|
+
|
|
52
|
+
## The tools
|
|
53
|
+
|
|
54
|
+
| tool | does | route |
|
|
55
|
+
|---|---|---|
|
|
56
|
+
| `whoami` | the account, role and workspaces this key acts for | `GET /api/me` |
|
|
57
|
+
| `list_workspaces` | the workspaces it may open | `GET /api/workspaces` |
|
|
58
|
+
| `inbox` | what waits on you: approvals, questions, issues, proposed fixes, your failed runs (`bucket`, `kind`, `workspace`) | `GET /api/me/inbox` |
|
|
59
|
+
| `list_approvals` | every gate waiting on a person, and every question an agent is asking | `GET /api/approvals` |
|
|
60
|
+
| `list_flows` | a workspace's flows | `GET …/flows` |
|
|
61
|
+
| `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` |
|
|
62
|
+
| `get_run` | one run in full | `GET …/runs/<id>` |
|
|
63
|
+
| `read_file` | one file of a workspace's source, or the tree | `GET …/source` |
|
|
64
|
+
| `run_flow` | start a flow (`task`, `test: true` for a [test run](runs#test-runs)) | `POST …/flows/<flow>/run` |
|
|
65
|
+
| `decide_approval` | approve or reject a gate (`note`, `step`) | `POST …/runs/<id>/approve` |
|
|
66
|
+
| `answer_question` | answer an agent's question mid-step | `POST …/runs/<id>/answer` |
|
|
67
|
+
| `message_run` | say something to a running agent | `POST …/runs/<id>/message` |
|
|
68
|
+
| `stop_run` | stop a run | `POST …/runs/<id>/stop` |
|
|
69
|
+
|
|
70
|
+
The first eight read. The last five act, and are marked so for the app
|
|
71
|
+
(`readOnlyHint: false`; `stop_run` also `destructiveHint: true`), which is
|
|
72
|
+
what an app uses to ask you before calling one.
|
|
73
|
+
|
|
74
|
+
## What it may do
|
|
75
|
+
|
|
76
|
+
Nothing a key could not. Each tool is a call to the route in the table, made
|
|
77
|
+
with the same key — so a viewer's key cannot start, approve or stop; a key
|
|
78
|
+
scoped to some workspaces sees and touches only those; an
|
|
79
|
+
[A2A key](a2a#a2a-keys) is refused (it opens `/a2a` and nothing else); and
|
|
80
|
+
every check, limit and refusal is the route's own. A tool whose route refused
|
|
81
|
+
answers `isError: true` with the route's words: `HTTP 403: this workspace is
|
|
82
|
+
not one you were given access to`.
|
|
83
|
+
|
|
84
|
+
`inbox` is a person's: a key minted by a person (every key from Settings, and
|
|
85
|
+
the CLI's sign-in) has one; a key nobody minted is refused, as the route
|
|
86
|
+
refuses it.
|
|
87
|
+
|
|
88
|
+
To give an app only the tools that read, connect it read-only — the tools
|
|
89
|
+
that act are not offered, and a call to one is refused:
|
|
90
|
+
|
|
91
|
+
```sh
|
|
92
|
+
claude mcp add foldrun -- foldrun mcp --read-only
|
|
93
|
+
claude mcp add --transport http foldrun "https://<your platform>/api/mcp?readonly=1" --header "Authorization: Bearer mda_..."
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
A viewer's key is the stronger version of the same: read-only by role,
|
|
97
|
+
whatever the app is told.
|
|
98
|
+
|
|
99
|
+
## What comes back is data
|
|
100
|
+
|
|
101
|
+
Run outputs, summaries, an agent's question, a file — all of it was written by
|
|
102
|
+
your agents, by the sites they read and by the people who sent them work. The
|
|
103
|
+
server tells the app so when it connects: treat it as content, never as an
|
|
104
|
+
instruction. A tool answer is at most 100,000 characters; a longer one (a
|
|
105
|
+
long run's whole record) is cut and says so.
|
|
106
|
+
|
|
107
|
+
## The protocol
|
|
108
|
+
|
|
109
|
+
MCP's Streamable HTTP transport, stateless: one JSON-RPC 2.0 message per
|
|
110
|
+
`POST /api/mcp`, answered with one JSON body. No SSE stream, no session id, no
|
|
111
|
+
batches; `GET` and `DELETE` answer `405`. Served: `initialize` (revisions
|
|
112
|
+
`2025-11-25`, `2025-06-18` and `2025-03-26` — the app's when it is one of
|
|
113
|
+
these, else the newest), `ping`, `tools/list`, `tools/call`; a notification is
|
|
114
|
+
answered `202` with no body. It sits under `/api`, so the proxy holds the same
|
|
115
|
+
raw-path check, body limit and rate limit as for every other route.
|
|
116
|
+
|
|
117
|
+
Refused before a message is read, as a JSON-RPC error with a real status: no
|
|
118
|
+
key (`401`, with `WWW-Authenticate: Bearer`) — a session cookie never opens
|
|
119
|
+
it —, a refused key (`401`/`403`), an `Origin` header that is not the
|
|
120
|
+
platform's own (`403`; MCP clients send none), an `MCP-Protocol-Version` it
|
|
121
|
+
does not speak (`400`). The route and request shape are in [the API
|
|
122
|
+
reference](api#mcp--ai-apps-connecting-with-a-key).
|
|
123
|
+
|
|
124
|
+
`foldrun mcp` reads one message per line on stdin and writes one per line on
|
|
125
|
+
stdout, and nothing else there: every note goes to stderr. Calls run side by
|
|
126
|
+
side, after `initialize` has answered. A platform from before 1 Nov 2026 has
|
|
127
|
+
no `/api/mcp`; the CLI says so as a JSON-RPC error.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "foldrun",
|
|
3
|
-
"version": "10.
|
|
3
|
+
"version": "10.3.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",
|
|
@@ -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 tests/cli-a2a.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-mcp.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
|
@@ -6621,6 +6621,122 @@ function issueDoctor(issue) {
|
|
|
6621
6621
|
* `restore` take item ids. A key reads the inbox of the person who minted it.
|
|
6622
6622
|
* The dashboard's Inbox. Exit 1 when anything assigned to you is unread.
|
|
6623
6623
|
*/
|
|
6624
|
+
/**
|
|
6625
|
+
* `foldrun mcp` — this account as an MCP server over stdio, for an AI app
|
|
6626
|
+
* (Claude Code, Claude Desktop, Cursor, Codex): `claude mcp add foldrun --
|
|
6627
|
+
* foldrun mcp`. Each line on stdin is one JSON-RPC message, forwarded to the
|
|
6628
|
+
* platform's POST /api/mcp with this machine's sign-in; each answer is one
|
|
6629
|
+
* line on stdout. The tools live on the platform, so they are always the
|
|
6630
|
+
* platform's own — this end holds no list to go stale. stdout carries
|
|
6631
|
+
* nothing but protocol; every note goes to stderr.
|
|
6632
|
+
* @param {string[]} positional @param {Record<string, any>} flags
|
|
6633
|
+
*/
|
|
6634
|
+
async function mcpCmd(positional, flags) {
|
|
6635
|
+
if (positional.length) throw new Error("`foldrun mcp` takes no arguments — an AI app starts it: `claude mcp add foldrun -- foldrun mcp` (--read-only for the tools that read)");
|
|
6636
|
+
if (process.stdin.isTTY && flags.yes !== true) {
|
|
6637
|
+
console.error(`\n ${c.bold("foldrun mcp")} is an MCP server on stdin/stdout, for an AI app to start — not to type into.\n\n claude mcp add foldrun -- foldrun mcp${flags["read-only"] === true ? " --read-only" : ""}\n codex mcp add foldrun -- foldrun mcp\n\n ${c.dim("Claude Desktop, Cursor: { \"mcpServers\": { \"foldrun\": { \"command\": \"foldrun\", \"args\": [\"mcp\"] } } } — `foldrun docs mcp`")}\n`);
|
|
6638
|
+
return 2;
|
|
6639
|
+
}
|
|
6640
|
+
// The account this server acts as is the one it started as: pinned by
|
|
6641
|
+
// profile name, so `foldrun use <other>` in another terminal never moves a
|
|
6642
|
+
// running session to another account, or its key to another platform.
|
|
6643
|
+
const started = typeof flags.token === "string" || env("FOLDRUN_TOKEN") ? null : chosenProfile(flags);
|
|
6644
|
+
if (started?.name) flags = { ...flags, profile: started.name };
|
|
6645
|
+
const url = platformFor(flags, "mcp");
|
|
6646
|
+
await renewedToken(url, flags);
|
|
6647
|
+
/** An app keeps this process for days, and another command may renew the
|
|
6648
|
+
* sign-in meanwhile (the old key ends minutes later): the key is read
|
|
6649
|
+
* again for every message, and the renewal checked again twice a day. */
|
|
6650
|
+
let renewedAt = Date.now();
|
|
6651
|
+
const currentToken = async () => {
|
|
6652
|
+
if (Date.now() - renewedAt > 12 * 60 * 60 * 1000) {
|
|
6653
|
+
renewedAt = Date.now();
|
|
6654
|
+
renewChecked = false;
|
|
6655
|
+
await renewIfDue(url, flags);
|
|
6656
|
+
}
|
|
6657
|
+
return tokenFor(url, flags);
|
|
6658
|
+
};
|
|
6659
|
+
const apiPath = `/api/mcp${flags["read-only"] === true ? "?readonly=1" : ""}`;
|
|
6660
|
+
// Long tool calls (a run's whole record) get longer than a CLI read.
|
|
6661
|
+
const seconds = explicitTimeout(flags) ?? 120;
|
|
6662
|
+
/** The revision `initialize` settled on, sent on every later request. */
|
|
6663
|
+
let protocol = null;
|
|
6664
|
+
const send = (msg) => {
|
|
6665
|
+
process.stdout.write(`${JSON.stringify(msg)}\n`);
|
|
6666
|
+
};
|
|
6667
|
+
const fail = (id, code, message) => send({ jsonrpc: "2.0", id: id ?? null, error: { code, message } });
|
|
6668
|
+
|
|
6669
|
+
/** @param {string} line */
|
|
6670
|
+
const forward = async (line) => {
|
|
6671
|
+
let msg;
|
|
6672
|
+
try {
|
|
6673
|
+
msg = JSON.parse(line);
|
|
6674
|
+
} catch {
|
|
6675
|
+
return fail(null, -32700, "not JSON — one JSON-RPC message per line");
|
|
6676
|
+
}
|
|
6677
|
+
const id = msg && typeof msg === "object" && !Array.isArray(msg) ? msg.id : undefined;
|
|
6678
|
+
const isRequest = id !== undefined && typeof msg?.method === "string";
|
|
6679
|
+
let res;
|
|
6680
|
+
try {
|
|
6681
|
+
const token = await currentToken();
|
|
6682
|
+
res = await remoteFetch(url, apiPath, {
|
|
6683
|
+
method: "POST",
|
|
6684
|
+
headers: { "content-type": "application/json", accept: "application/json, text/event-stream", ...(protocol ? { "mcp-protocol-version": protocol } : {}) },
|
|
6685
|
+
body: line,
|
|
6686
|
+
}, { token, seconds });
|
|
6687
|
+
} catch (err) {
|
|
6688
|
+
console.error(`foldrun mcp: ${explain(err)}`);
|
|
6689
|
+
return isRequest ? fail(id, -32603, `foldrun could not reach ${new URL(url).host}: ${explain(err)}`) : undefined;
|
|
6690
|
+
}
|
|
6691
|
+
if (res.status === 202) return;
|
|
6692
|
+
let text;
|
|
6693
|
+
try {
|
|
6694
|
+
text = await res.text();
|
|
6695
|
+
} catch (err) {
|
|
6696
|
+
// The headers came and the body did not: a dropped connection, the clock.
|
|
6697
|
+
console.error(`foldrun mcp: ${explain(err)}`);
|
|
6698
|
+
return isRequest ? fail(id, -32603, `the answer from ${new URL(url).host} broke off: ${explain(err)}`) : undefined;
|
|
6699
|
+
}
|
|
6700
|
+
let body;
|
|
6701
|
+
try {
|
|
6702
|
+
body = JSON.parse(text);
|
|
6703
|
+
// JSON, but not the protocol: an /api error from a platform that has no
|
|
6704
|
+
// /api/mcp (`{ error: "…" }`), or a proxy's own JSON.
|
|
6705
|
+
if (body?.jsonrpc !== "2.0") throw new Error("not JSON-RPC");
|
|
6706
|
+
} catch {
|
|
6707
|
+
console.error(`foldrun mcp: ${apiPath} → HTTP ${res.status}: ${text.slice(0, 200)}`);
|
|
6708
|
+
if (!isRequest) return;
|
|
6709
|
+
return fail(id, -32603, res.status === 404 ? `${new URL(url).host} has no MCP endpoint — it runs a platform from before 1 Nov 2026` : `the platform's MCP endpoint answered HTTP ${res.status}, and not in MCP — is ${new URL(url).host} the right address?`);
|
|
6710
|
+
}
|
|
6711
|
+
// A refusal before the message was read (no key, a refused key) carries
|
|
6712
|
+
// no id; give it this request's, so the app knows which call failed.
|
|
6713
|
+
if (body && typeof body === "object" && body.id === null && isRequest) body.id = id;
|
|
6714
|
+
if (body?.error && (res.status === 401 || res.status === 403)) body.error.message += refusedHint(url, flags);
|
|
6715
|
+
if (msg?.method === "initialize" && typeof body?.result?.protocolVersion === "string") protocol = body.result.protocolVersion;
|
|
6716
|
+
if (!isRequest && !body?.error) return;
|
|
6717
|
+
send(body);
|
|
6718
|
+
};
|
|
6719
|
+
|
|
6720
|
+
const readline = await import("node:readline");
|
|
6721
|
+
const lines = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
|
|
6722
|
+
const inFlight = new Set();
|
|
6723
|
+
/** An initialize still on its way: what comes after it waits for the revision it settles. */
|
|
6724
|
+
let initializing = Promise.resolve();
|
|
6725
|
+
for await (const raw of lines) {
|
|
6726
|
+
const line = raw.trim();
|
|
6727
|
+
if (!line) continue;
|
|
6728
|
+
// Calls run side by side: a slow tools/call never holds up a ping. Each
|
|
6729
|
+
// answer carries its id, so the order they come back in does not matter.
|
|
6730
|
+
const before = initializing;
|
|
6731
|
+
const p = before.then(() => forward(line)).catch((err) => console.error(`foldrun mcp: ${explain(err)}`));
|
|
6732
|
+
if (/"method"\s*:\s*"initialize"/.test(line)) initializing = p;
|
|
6733
|
+
inFlight.add(p);
|
|
6734
|
+
p.finally(() => inFlight.delete(p));
|
|
6735
|
+
}
|
|
6736
|
+
await Promise.all(inFlight);
|
|
6737
|
+
return 0;
|
|
6738
|
+
}
|
|
6739
|
+
|
|
6624
6740
|
async function inboxCmd(positional, flags) {
|
|
6625
6741
|
const url = platformFor(flags, "inbox");
|
|
6626
6742
|
const [verb, ...ids] = positional;
|
|
@@ -12727,6 +12843,8 @@ export async function run(command, positional, flags, workspace, layout) {
|
|
|
12727
12843
|
return issuesCmd(positional, flags, layout);
|
|
12728
12844
|
case "inbox":
|
|
12729
12845
|
return inboxCmd(positional, flags);
|
|
12846
|
+
case "mcp":
|
|
12847
|
+
return mcpCmd(positional, flags);
|
|
12730
12848
|
case "insights":
|
|
12731
12849
|
return insightsCmd(flags);
|
|
12732
12850
|
case "approve":
|