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

mason/forge:mason/12521-a-small-forge-loads-less-at-boot-the-tui → main 1 commit fork

  • Merged. mason/12521-a-small-forge-loads-less-at-boot-the-tui was merged into main as 2bd9d30.

Review

Sign in to review this change.
10 files changed +173 −16
AGENTS.md +2
@@ -28,6 +28,8 @@ State shared between modules through process memory, not the database, is named
2828
2929 `src/core/transfer.ts`: the old owner/name pairs a transfer left behind (`repo_redirect`), held per database after the first request reads them and dropped by `transferRepo`, so a request under a path nothing moved from costs no statement (#569).
3030
31 `src/http/mcp/load.ts`: `loading`, the one import of the MCP server and its tool index (#12521), started by the first request that needs the tools; when it settles it hands the list to /llms.txt (`setMcpTools`) and the cards (`setCardTools`), so a reader of those lists awaits `loadMcp()` first. A failed import is dropped and tried again; gone on restart.
32
3133 `src/spawn/funding.ts`: `askedAt`, when a run last asked the host for the lent credit (`refreshFundingOnce`, 15 s per data directory); gone on restart.
3234 `src/system/footing.ts`: `footing`, the last reading of what the forge stands on from the kube API (#11685), held 60 s so /system, its terminal screen (`src/tui/screens/footing.ts`, palette entry for admins) and the MCP `system` tool (`kind: footing`) share one read; a probe that throws is not retried for 60 s; one reading, gone on restart.
3335 `src/system/largest_dirs.ts`: `largestDirs`, the last measurement of the five largest directories under the forge's data (#11800), held 60 s so /system, its terminal screen (`src/tui/screens/system.ts`, `largestLines`) and the MCP `system` tool share one asynchronous walk; a walk that fails is not retried for 60 s; one reading, gone on restart.
docs/features/footprint.md +6
@@ -15,6 +15,12 @@ Reading the disk figure walks the whole data directory (`treeBytes`), once per r
1515
1616 This is the measurement step. The work that cuts the footprint is tracked in its own issues, each blocking #12092: the cell ceiling on a small pod (#12346), reading the pod's limit in `/system` and health (#12347), a launcher-free start (#12348), lazy-loading what a small forge never uses (#12349), an ARM image (#12350), and the serve/work split only on machines with cores (#12351).
1717
18 ## What loads on first use (#12349, #12521)
19
20 The boot's static imports reach neither the terminal UI nor the MCP server and its tool index (`test/boot-lazy.test.ts` walks them). The terminal loads when `FORGE_SSH_PORT` is set; the MCP modules load on the first request that needs the tools (`/mcp`, `/llms.txt`, `/agents`, `/.well-known/mcp.json`, `/.well-known/agent-card.json`, a held confirm said yes to) through `src/http/mcp/load.ts`. The route table names `/mcp` from boot (`lazyRoutes` in `src/http/lazy_routes.ts`), so matching, gates and 405s are unchanged; the first such request waits for one import (0.1 s on a dev machine; every later one does not). A load that fails answers that request with an error naming the MCP tools, and the next request tries again.
21
22 The boot graph went from 2,653 modules to 2,433; RSS at rest on a fresh forge (`FORGE_SSH_PORT=0 FORGE_APPS=0`, 20 s after `/healthz` answers, source run on a dev machine) went from 313–333 MiB (three runs) to 265–271 MiB. The next largest family, the OpenAPI contract's route descriptions (443 modules), is still loaded at boot: the admin gate and the cursor guard read it on every request.
23
1824 ## Measured sizes (2026-11-13, release image, same first-hour journey)
1925
2026 | limit | boot to first page | RSS at rest / after | result |
src/actions/conversation_confirms.ts +3 −1
@@ -18,7 +18,7 @@ import { answerHeld, countWaiting, HELD_TTL_MS, waitingFor, type YesRefusal } fr
1818 import type { User } from "../core/users.ts";
1919 import { argumentsShown, confirmSentence, keptOf, undoOf } from "../crew/conversation_confirm.ts";
2020 import type { Ctx } from "../http/context.ts";
21 import { TOOLS } from "../http/mcp/tools.ts";
21 import { loadMcp } from "../http/mcp/load.ts";
2222
2323 /** A confirm as the person reads it before saying yes. */
2424 export interface Waiting {
@@ -72,6 +72,8 @@ const kept = (value: unknown): unknown => {
7272 /** Say yes to `confirmId` as `user`, whose own session asked. */
7373 export async function sayYes(ctx: Ctx, user: User, confirmId: string): Promise<Yes> {
7474 if (!CONFIRM_ID.test(confirmId)) return { ok: false, error: "not_found" };
75 // Loaded before the confirm is claimed, so a load that fails leaves it waiting.
76 const { TOOLS } = await loadMcp();
7577 const answered = answerHeld(ctx.app.db, confirmId, user.id);
7678 if (!answered.ok) return answered;
7779 const held = answered.value;
src/http/lazy_routes.ts added +43
@@ -0,0 +1,43 @@
1 /**
2 * Routes whose module loads on first use (#12521). The route table holds
3 * each method and pattern from boot, so matching, the admin gate, 405s and
4 * HEAD answer exactly as they did; the handler behind them imports its
5 * module on the first request, registers it on a table of its own, and
6 * hands the request to the handler it added for the same method and pattern.
7 *
8 * A load that fails is not kept, so the next request tries again; a route the
9 * module no longer adds is named in the error (and caught by its test first).
10 */
11
12 import type { Handler } from "./context.ts";
13 import { Router } from "./router.ts";
14
15 /** A module's own registration, as its `…Routes(router)` export. */
16 export type Register = (router: Router<Handler>) => void;
17
18 export function lazyRoutes(
19 table: Router<Handler>,
20 family: string,
21 routes: readonly (readonly [method: string, pattern: string])[],
22 load: () => Promise<Register>,
23 ): void {
24 let own: Promise<Router<Handler>> | undefined;
25 const loaded = (): Promise<Router<Handler>> =>
26 (own ??= load().then(
27 (register) => {
28 const registered = new Router<Handler>();
29 register(registered);
30 return registered;
31 },
32 (error: unknown) => {
33 own = undefined;
34 throw error;
35 },
36 ));
37 for (const [method, pattern] of routes)
38 table.add(method, pattern, async (ctx) => {
39 const handler = (await loaded()).handlerOf(method, pattern);
40 if (handler === undefined) throw new Error(`the ${family} module does not add ${method} ${pattern}`);
41 return handler(ctx);
42 });
43 }
src/http/mcp/load.ts added +43
@@ -0,0 +1,43 @@
1 /**
2 * The MCP server and its tools, loaded on first use (#12521): the tool index
3 * is some two hundred modules a forge nobody steers by MCP never needs, so
4 * the boot imports none of them (test/boot-lazy.test.ts). The first request
5 * that needs the tools (`/mcp`, `/llms.txt`, `/agents`, the server and agent
6 * cards, a held confirm said yes to) waits for this one import; every later
7 * one finds it done.
8 *
9 * Loading also hands the list to /llms.txt (`setMcpTools`) and the cards
10 * (`setCardTools`), as the boot used to, so a page cannot be drawn from an
11 * empty list. A load that fails is not kept: the next request tries again,
12 * and the error names what failed.
13 */
14
15 import { setCardTools } from "../../core/mcp_card.ts";
16 import { setMcpTools } from "../../web/llms_tools.ts";
17
18 /** The routes `mcpRoutes` adds, registered at boot in front of the module (`lazyRoutes`). */
19 export const MCP_ROUTES = [
20 ["POST", "/mcp"],
21 ["GET", "/mcp"],
22 ["DELETE", "/mcp"],
23 ] as const;
24
25 export type Mcp = typeof import("../mcp.ts") & typeof import("./tools.ts");
26
27 let loading: Promise<Mcp> | undefined;
28
29 /** The MCP module and the tool index, imported once. */
30 export function loadMcp(): Promise<Mcp> {
31 loading ??= Promise.all([import("../mcp.ts"), import("./tools.ts")]).then(
32 ([mcp, tools]) => {
33 setMcpTools(tools.TOOLS, [mcp.REPORT_TOOL, mcp.START_TOOL]);
34 setCardTools([...tools.TOOLS, mcp.REPORT_TOOL, mcp.START_TOOL]);
35 return { ...mcp, ...tools };
36 },
37 (error: unknown) => {
38 loading = undefined;
39 throw new Error(`the MCP tools failed to load: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
40 },
41 );
42 return loading;
43 }
src/http/router.ts +5
@@ -78,6 +78,11 @@ export class Router<H> {
7878 return this.routes_.map(({ method, pattern }) => ({ method, pattern }));
7979 }
8080
81 /** The handler added for exactly this method and pattern, the first if added twice. */
82 handlerOf(method: string, pattern: string): H | undefined {
83 return this.routes_.find((r) => r.method === method && r.pattern === pattern)?.handler;
84 }
85
8186 add(method: string, pattern: string, handler: H): this {
8287 this.routes_.push({ method, pattern, segments: compile(pattern), handler });
8388 return this;
src/http/server.ts +4 −7
@@ -534,10 +534,8 @@ import { viaGate } from "./via_gate.ts";
534534 import { checksRecheckRoutes } from "./checks_recheck.ts";
535535 import { feedRoutes } from "./feed.ts";
536536 import type { Database } from "bun:sqlite";
537 import { mcpRoutes, REPORT_TOOL, START_TOOL } from "./mcp.ts";
538 import { TOOLS } from "./mcp/tools.ts";
539 import { setCardTools } from "../core/mcp_card.ts";
540 import { setMcpTools } from "../web/llms_tools.ts";
537 import { loadMcp, MCP_ROUTES } from "./mcp/load.ts";
538 import { lazyRoutes } from "./lazy_routes.ts";
541539 import { resourcePolicy } from "./corp.ts";
542540 import { agentsPage } from "../web/pages/agents.ts";
543541 import { openapiRoute } from "../contract/served.ts";
@@ -1293,9 +1291,8 @@ export function buildRouter(): Router<Handler> {
12931291 // below) — never here, so a `/:owner`-shaped studio route can never
12941292 // reclaim a path under `/api/`.
12951293 // The forge as an MCP server: the studio's verbs for an assistant.
1296 mcpRoutes(router);
1297 setMcpTools(TOOLS, [REPORT_TOOL, START_TOOL]);
1298 setCardTools([...TOOLS, REPORT_TOOL, START_TOOL]);
1294 // Its modules load on the first request that needs them (`mcp/load.ts`, #12521).
1295 lazyRoutes(router, "MCP", MCP_ROUTES, async () => (await loadMcp()).mcpRoutes);
12991296 // The public API as OpenAPI, for any client that reads it.
13001297 openapiRoute(router);
13011298 oauthRoutes(router);
src/web/pages/agents.ts +3 −1
@@ -15,6 +15,7 @@ import { page } from "../layout.ts";
1515 import { renderMarkdown } from "../markdown.ts";
1616 import { START_BUTTON, SITE_PATH } from "../site_line.ts";
1717 import { llmsBody } from "../standards.ts";
18 import { loadMcp } from "../../http/mcp/load.ts";
1819
1920 /** An address in prose, outside code, made a link; a template (`{owner}`) stays words. */
2021 const URL = /https?:\/\/[A-Za-z0-9][^\s<>`"()\]]*/g;
@@ -62,8 +63,9 @@ export function guideHtml(body: string): Html {
6263 return renderMarkdown(linkAddresses(withoutTitle(body)));
6364 }
6465
65 export function agentsPage(ctx: Ctx): Response {
66 export async function agentsPage(ctx: Ctx): Promise<Response> {
6667 notePhase(ctx.request, "session", takeSessionTime(ctx.request));
68 await loadMcp();
6769 const { body } = llmsBody(ctx);
6870 return timePhase(ctx.request, "render", () => page({
6971 ctx,
src/web/standards.ts +12 −4
@@ -53,6 +53,7 @@ import { agentCard, toolsKey, apiCatalog, cardsLine, DISCOVERY, mcpCard, offered
5353 import { forgeDocument } from "../core/standards_index.ts";
5454 import { TAGS } from "../contract/served.ts";
5555 import { running } from "../kernel/version.ts";
56 import { loadMcp } from "../http/mcp/load.ts";
5657 import { timePhase, timePhaseAsync } from "../core/route_timing.ts";
5758 import { shippedReleases, type Shipped } from "../release/shipped.ts";
5859
@@ -143,7 +144,8 @@ function discovery(ctx: Ctx, kind: string, inputs: string, make: () => unknown,
143144 }
144145
145146 /** GET /.well-known/mcp.json — the MCP server card (a draft format; see docs/MCP.md). */
146 export function mcpJson(ctx: Ctx): Response {
147 export async function mcpJson(ctx: Ctx): Promise<Response> {
148 await loadMcp();
147149 const repo = offeredPluginRepo(ctx.app.db, ctx.app.config.forgeRepo, UPSTREAM_REPO);
148150 const now = running();
149151 return discovery(ctx, "mcp", JSON.stringify([repo, now.version, now.commit, toolsKey()]), () => mcpCard(ctx.url.origin, repo, now), "application/json", "public, max-age=3600", true);
@@ -153,7 +155,8 @@ export function mcpJson(ctx: Ctx): Response {
153155 * GET /.well-known/agent-card.json — the A2A agent card, its skills the MCP
154156 * tool names the server card lists.
155157 */
156 export function agentCardJson(ctx: Ctx): Response {
158 export async function agentCardJson(ctx: Ctx): Promise<Response> {
159 await loadMcp();
157160 const now = running();
158161 return discovery(ctx, "agent-card", JSON.stringify([now.version, toolsKey()]), () => agentCard(ctx.url.origin, now), "application/json", "public, max-age=3600", true);
159162 }
@@ -407,7 +410,8 @@ const llmsBodies = new Map<string, { repos: LlmsListing; running: string; tell:
407410 * where the API and the MCP are, and the public repositories. Facts only,
408411 * each with the method and URL that does it.
409412 */
410 export function llmsTxt(ctx: Ctx): Response {
413 export async function llmsTxt(ctx: Ctx): Promise<Response> {
414 await loadMcp();
411415 const kept = llmsBody(ctx);
412416 // The third line names the running commit: a client revalidates (one small 304)
413417 // rather than keep an old build for an hour.
@@ -424,7 +428,11 @@ export function llmsTxt(ctx: Ctx): Response {
424428 return res;
425429 }
426430
427 /** The llms.txt text for this request and its ETag: /llms.txt sends it as is, /agents draws it as a page. */
431 /**
432 * The llms.txt text for this request and its ETag: /llms.txt sends it as is, /agents draws it
433 * as a page. Its callers wait for `loadMcp` first, so the tools section is never drawn from an
434 * empty list.
435 */
428436 export function llmsBody(ctx: Ctx): { body: string; etag: string } {
429437 const o = ctx.url.origin;
430438 const tell = sshTellCommand(ctx.app);
test/boot-lazy.test.ts +52 −3
@@ -1,10 +1,14 @@
11 /**
2 * A small forge loads only what it uses (#12349): the terminal UI is imported
3 * when a shell opens, not by the boot's static imports.
2 * A small forge loads only what it uses (#12349, #12521): the terminal UI is
3 * imported when a shell opens, and the MCP server with its tools on the first
4 * request that needs them, not by the boot's static imports.
45 */
5 import { expect, test } from "bun:test";
6 import { describe, expect, test } from "bun:test";
67 import { existsSync, readFileSync } from "node:fs";
78 import { dirname, resolve } from "node:path";
9 import type { Ctx, Handler } from "../src/http/context.ts";
10 import { lazyRoutes } from "../src/http/lazy_routes.ts";
11 import { Router } from "../src/http/router.ts";
812
913 const FROM = /(?:^|\n)\s*(?:import|export)\s+(?!type\b)[^;]*?from\s+"(\.[^"]+)"|(?:^|\n)\s*import\s+"(\.[^"]+)"/g;
1014
@@ -32,3 +36,48 @@ test("the boot's static imports do not reach the terminal UI", () => {
3236 test("the terminal's server is imported dynamically by the boot", () => {
3337 expect(readFileSync(resolve("src/main.ts"), "utf8")).toContain('import("./tui/ssh.ts")');
3438 });
39
40 // #12521: the MCP server and its tool index (some two hundred modules) load on first use.
41 test("the boot's static imports do not reach the MCP server or its tools", () => {
42 const closure = [...staticClosure(resolve("src/main.ts"))];
43 const mcp = closure.filter((f) => f.endsWith("/src/http/mcp.ts") || f.endsWith("/src/http/mcp/tools.ts") || f.includes("/src/http/mcp/tools/"));
44 expect(mcp).toEqual([]);
45 });
46
47 test("the routes registered in front of the MCP module are the ones it adds", async () => {
48 const { MCP_ROUTES } = await import("../src/http/mcp/load.ts");
49 const { mcpRoutes } = await import("../src/http/mcp.ts");
50 const own = new Router<Handler>();
51 mcpRoutes(own);
52 expect(MCP_ROUTES.map(([method, pattern]): { method: string; pattern: string } => ({ method, pattern }))).toEqual(own.routes());
53 });
54
55 describe("lazyRoutes", () => {
56 const ctx = {} as Ctx;
57 test("loads its module once, on the first request, and answers with the handler it adds", async () => {
58 let loads = 0;
59 const router = new Router<Handler>();
60 lazyRoutes(router, "test", [["GET", "/x"]], async () => {
61 loads++;
62 return (r) => void r.add("GET", "/x", () => new Response("from the module"));
63 });
64 expect(loads).toBe(0);
65 const handler = router.match("GET", "/x")!.handler;
66 expect(await (await handler(ctx)).text()).toBe("from the module");
67 await handler(ctx);
68 expect(loads).toBe(1);
69 });
70
71 test("a load that fails is tried again, and a route the module does not add is named", async () => {
72 let loads = 0;
73 const router = new Router<Handler>();
74 lazyRoutes(router, "test", [["POST", "/y"]], async () => {
75 if (++loads === 1) throw new Error("boom");
76 return () => {};
77 });
78 const handler = router.match("POST", "/y")!.handler;
79 await expect(Promise.resolve(handler(ctx))).rejects.toThrow("boom");
80 await expect(Promise.resolve(handler(ctx))).rejects.toThrow("the test module does not add POST /y");
81 expect(loads).toBe(2);
82 });
83 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs