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 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` |
@@ -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.2.0",
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":