Public: anyone can read this; the crew can change it.

A small forge loads less at boot: the TUI, boards and studio modules load on first use #12549

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

The MCP server and its tool index now load on the first request that needs them, not at boot. The boot import graph drops from 2,653 modules to 2,433, and resting memory drops by about 55 MiB. The terminal UI already loaded lazily on main (#12349), so this pull adds the second family the issue asks for.

Notes

shipped production is serving it deploy 7612a18

opened this

The MCP server and its tool index now load on the first request that needs them, not at boot. The boot import graph drops from 2,653 modules to 2,433, and resting memory drops by about 55 MiB. The terminal UI already loaded lazily on main (#12349), so this pull adds the second family the issue asks for.

Measured on this machine (fresh forge with FORGE_SSH_PORT=0 FORGE_APPS=0, run from source, VmRSS read 20 s after /healthz answers):

RSS at rest
Before313, 326, 333 MiB
After269, 271, 265 MiB

The first request that loads the tools takes about 0.1 s; later requests don't wait. / takes about 30 ms before and after.

What moved

  • src/http/mcp/load.ts (loadMcp): imports mcp.ts and the tool index once. It also hands the tool list to /llms.txt (setMcpTools) and to the cards (setCardTools); before, server.ts did that at boot. If the import fails, the request gets an error that says the MCP tools failed to load, and the next request tries again.
  • src/http/lazy_routes.ts (lazyRoutes): registers POST/GET/DELETE /mcp in the route table at boot. The handler behind them loads the module on the first request and hands it on to the handler the module adds, so route matching, the admin gate, 405s and HEAD behave as before. Router gains handlerOf(method, pattern).
  • Readers of the tool list wait for the load first:

- /llms.txt, /.well-known/mcp.json and /.well-known/agent-card.json in standards.ts - /agents - sayYes in actions/conversation_confirms.ts, which loads before it claims the confirm, so a failed load leaves the confirm waiting instead of using it up.

  • Docs: AGENTS.md names the new shared in-memory state, and docs/features/footprint.md says what loads on first use and gives the numbers above.

Tests (test/boot-lazy.test.ts):

  • The boot's static imports reach none of http/mcp.ts, http/mcp/tools.ts or http/mcp/tools/*.
  • MCP_ROUTES matches what mcpRoutes adds, so the two can't drift.
  • lazyRoutes loads once, retries after a failed load, and names a route the module no longer adds.

What to look at:

  • One existing test fails on this branch and on the base commit alike, so it isn't caused by this change: test/mcp-refusal-hints.test.ts "a stranger calling every listed tool…" (expects 401, gets 200).
  • The parameter in lazy_routes.ts is named table, not router, because test/helpers/registered_routes.ts counts router.add( calls in the source text.

Not done:

  • The OpenAPI contract's route descriptions (443 modules) are the largest family still loaded at boot. The admin gate (admin_gate.ts) and the cursor guard (cursor_lists.ts) read them on every request. Deferring them would mean getting those two facts without loading the document, which is a riskier change than this issue allows.
  • Boards and the studio are small (boards saves 14 modules) or imported from all over, so lazy loading them would barely help.
  • I didn't keep a plan with keep_plan or record an estimate: neither tool was available in this run.

Checks run: bun scripts/gate.ts, bun x tsc --noEmit and bun scripts/design-lint.ts pass. I ran the 437 test files that reach /mcp, /llms.txt, the cards, /agents or the confirms. The two other failures from that run, in test/capacity.test.ts and test/holds.test.ts, came from a run disturbed by a stash I made while it was going, and both pass on a clean re-run. fast.ts named 2,183 test files, too many to run here, so the forge's check runs the full suite.

Try it: on the preview, open /llms.txt and /.well-known/mcp.json, then POST /mcp with tools/list and a token. Each should list the same tools as production.

🤖 Generated with Claude Code

Closes #12521

commented

The MCP server and its tool index now load on the first request that needs them, not at boot. The boot import graph drops from 2,653 modules to 2,433, and resting memory drops by about 55 MiB. The terminal UI already loaded lazily on main (#12349), so this pull adds the second family the issue asks for.

Measured on this machine (fresh forge with FORGE_SSH_PORT=0 FORGE_APPS=0, run from source, VmRSS read 20 s after /healthz answers):

RSS at rest
Before313, 326, 333 MiB
After269, 271, 265 MiB

The first request that loads the tools takes about 0.1 s; later requests don't wait. / takes about 30 ms before and after.

What moved

  • src/http/mcp/load.ts (loadMcp): imports mcp.ts and the tool index once. It also hands the tool list to /llms.txt (setMcpTools) and to the cards (setCardTools); before, server.ts did that at boot. If the import fails, the request gets an error that says the MCP tools failed to load, and the next request tries again.
  • src/http/lazy_routes.ts (lazyRoutes): registers POST/GET/DELETE /mcp in the route table at boot. The handler behind them loads the module on the first request and hands it on to the handler the module adds, so route matching, the admin gate, 405s and HEAD behave as before. Router gains handlerOf(method, pattern).
  • Readers of the tool list wait for the load first:

- /llms.txt, /.well-known/mcp.json and /.well-known/agent-card.json in standards.ts - /agents - sayYes in actions/conversation_confirms.ts, which loads before it claims the confirm, so a failed load leaves the confirm waiting instead of using it up.

  • Docs: AGENTS.md names the new shared in-memory state, and docs/features/footprint.md says what loads on first use and gives the numbers above.

Tests (test/boot-lazy.test.ts):

  • The boot's static imports reach none of http/mcp.ts, http/mcp/tools.ts or http/mcp/tools/*.
  • MCP_ROUTES matches what mcpRoutes adds, so the two can't drift.
  • lazyRoutes loads once, retries after a failed load, and names a route the module no longer adds.

What to look at:

  • One existing test fails on this branch and on the base commit alike, so it isn't caused by this change: test/mcp-refusal-hints.test.ts "a stranger calling every listed tool…" (expects 401, gets 200).
  • The parameter in lazy_routes.ts is named table, not router, because test/helpers/registered_routes.ts counts router.add( calls in the source text.

Not done:

  • The OpenAPI contract's route descriptions (443 modules) are the largest family still loaded at boot. The admin gate (admin_gate.ts) and the cursor guard (cursor_lists.ts) read them on every request. Deferring them would mean getting those two facts without loading the document, which is a riskier change than this issue allows.
  • Boards and the studio are small (boards saves 14 modules) or imported from all over, so lazy loading them would barely help.
  • I didn't keep a plan with keep_plan or record an estimate: neither tool was available in this run.

Checks run: bun scripts/gate.ts, bun x tsc --noEmit and bun scripts/design-lint.ts pass. I ran the 437 test files that reach /mcp, /llms.txt, the cards, /agents or the confirms. The two other failures from that run, in test/capacity.test.ts and test/holds.test.ts, came from a run disturbed by a stash I made while it was going, and both pass on a clean re-run. fast.ts named 2,183 test files, too many to run here, so the forge's check runs the full suite.

Try it: on the preview, open /llms.txt and /.well-known/mcp.json, then POST /mcp with tools/list and a token. Each should list the same tools as production.

🤖 Generated with Claude Code

Approved

Clean. The MCP server and tool index load on first use behind route-table entries registered at boot, so matching, the admin gate and 405s are unchanged. Every reader of the tool list (/llms.txt, /agents, both cards, sayYes) awaits loadMcp first. sayYes loads before it claims the confirm, so a failed load leaves the confirm waiting. A failed load is retried. Tests cover the boot graph, MCP_ROUTES against mcpRoutes, and lazyRoutes. AGENTS.md and docs/features/footprint.md are updated, and README is untouched. Preview: /llms.txt, /.well-known/mcp.json and /agents answer 200 and list tools; /mcp answers 401 to a forge token, as expected. No new dependency, and src/web changes are logic only, with no markup or design change.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs