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
Check · Review · Land · Live done — Landed and live in production.
mason/forge:mason/12521-a-small-forge-loads-less-at-boot-the-tui → main 1 commit fork
10 files
changed +173
−16
AGENTS.md +2
| @@ -28,6 +28,8 @@ State shared between modules through process memory, not the database, is named | ||
| 28 | 28 | |
| 29 | 29 | `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). |
| 30 | 30 | |
| 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 | ||
| 31 | 33 | `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. |
| 32 | 34 | `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. |
| 33 | 35 | `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 | ||
| 15 | 15 | |
| 16 | 16 | 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). |
| 17 | 17 | |
| 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 | ||
| 18 | 24 | ## Measured sizes (2026-11-13, release image, same first-hour journey) |
| 19 | 25 | |
| 20 | 26 | | 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 | ||
| 18 | 18 | import type { User } from "../core/users.ts"; |
| 19 | 19 | import { argumentsShown, confirmSentence, keptOf, undoOf } from "../crew/conversation_confirm.ts"; |
| 20 | 20 | import type { Ctx } from "../http/context.ts"; |
| 21 | import { TOOLS } from "../http/mcp/tools.ts"; | |
| 21 | import { loadMcp } from "../http/mcp/load.ts"; | |
| 22 | 22 | |
| 23 | 23 | /** A confirm as the person reads it before saying yes. */ |
| 24 | 24 | export interface Waiting { |
| @@ -72,6 +72,8 @@ const kept = (value: unknown): unknown => { | ||
| 72 | 72 | /** Say yes to `confirmId` as `user`, whose own session asked. */ |
| 73 | 73 | export async function sayYes(ctx: Ctx, user: User, confirmId: string): Promise<Yes> { |
| 74 | 74 | 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(); | |
| 75 | 77 | const answered = answerHeld(ctx.app.db, confirmId, user.id); |
| 76 | 78 | if (!answered.ok) return answered; |
| 77 | 79 | 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> { | ||
| 78 | 78 | return this.routes_.map(({ method, pattern }) => ({ method, pattern })); |
| 79 | 79 | } |
| 80 | 80 | |
| 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 | ||
| 81 | 86 | add(method: string, pattern: string, handler: H): this { |
| 82 | 87 | this.routes_.push({ method, pattern, segments: compile(pattern), handler }); |
| 83 | 88 | return this; |
src/http/server.ts +4 −7
| @@ -534,10 +534,8 @@ import { viaGate } from "./via_gate.ts"; | ||
| 534 | 534 | import { checksRecheckRoutes } from "./checks_recheck.ts"; |
| 535 | 535 | import { feedRoutes } from "./feed.ts"; |
| 536 | 536 | 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"; | |
| 541 | 539 | import { resourcePolicy } from "./corp.ts"; |
| 542 | 540 | import { agentsPage } from "../web/pages/agents.ts"; |
| 543 | 541 | import { openapiRoute } from "../contract/served.ts"; |
| @@ -1293,9 +1291,8 @@ export function buildRouter(): Router<Handler> { | ||
| 1293 | 1291 | // below) — never here, so a `/:owner`-shaped studio route can never |
| 1294 | 1292 | // reclaim a path under `/api/`. |
| 1295 | 1293 | // 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); | |
| 1299 | 1296 | // The public API as OpenAPI, for any client that reads it. |
| 1300 | 1297 | openapiRoute(router); |
| 1301 | 1298 | oauthRoutes(router); |
src/web/pages/agents.ts +3 −1
| @@ -15,6 +15,7 @@ import { page } from "../layout.ts"; | ||
| 15 | 15 | import { renderMarkdown } from "../markdown.ts"; |
| 16 | 16 | import { START_BUTTON, SITE_PATH } from "../site_line.ts"; |
| 17 | 17 | import { llmsBody } from "../standards.ts"; |
| 18 | import { loadMcp } from "../../http/mcp/load.ts"; | |
| 18 | 19 | |
| 19 | 20 | /** An address in prose, outside code, made a link; a template (`{owner}`) stays words. */ |
| 20 | 21 | const URL = /https?:\/\/[A-Za-z0-9][^\s<>`"()\]]*/g; |
| @@ -62,8 +63,9 @@ export function guideHtml(body: string): Html { | ||
| 62 | 63 | return renderMarkdown(linkAddresses(withoutTitle(body))); |
| 63 | 64 | } |
| 64 | 65 | |
| 65 | export function agentsPage(ctx: Ctx): Response { | |
| 66 | export async function agentsPage(ctx: Ctx): Promise<Response> { | |
| 66 | 67 | notePhase(ctx.request, "session", takeSessionTime(ctx.request)); |
| 68 | await loadMcp(); | |
| 67 | 69 | const { body } = llmsBody(ctx); |
| 68 | 70 | return timePhase(ctx.request, "render", () => page({ |
| 69 | 71 | ctx, |
src/web/standards.ts +12 −4
| @@ -53,6 +53,7 @@ import { agentCard, toolsKey, apiCatalog, cardsLine, DISCOVERY, mcpCard, offered | ||
| 53 | 53 | import { forgeDocument } from "../core/standards_index.ts"; |
| 54 | 54 | import { TAGS } from "../contract/served.ts"; |
| 55 | 55 | import { running } from "../kernel/version.ts"; |
| 56 | import { loadMcp } from "../http/mcp/load.ts"; | |
| 56 | 57 | import { timePhase, timePhaseAsync } from "../core/route_timing.ts"; |
| 57 | 58 | import { shippedReleases, type Shipped } from "../release/shipped.ts"; |
| 58 | 59 | |
| @@ -143,7 +144,8 @@ function discovery(ctx: Ctx, kind: string, inputs: string, make: () => unknown, | ||
| 143 | 144 | } |
| 144 | 145 | |
| 145 | 146 | /** 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(); | |
| 147 | 149 | const repo = offeredPluginRepo(ctx.app.db, ctx.app.config.forgeRepo, UPSTREAM_REPO); |
| 148 | 150 | const now = running(); |
| 149 | 151 | 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 { | ||
| 153 | 155 | * GET /.well-known/agent-card.json — the A2A agent card, its skills the MCP |
| 154 | 156 | * tool names the server card lists. |
| 155 | 157 | */ |
| 156 | export function agentCardJson(ctx: Ctx): Response { | |
| 158 | export async function agentCardJson(ctx: Ctx): Promise<Response> { | |
| 159 | await loadMcp(); | |
| 157 | 160 | const now = running(); |
| 158 | 161 | return discovery(ctx, "agent-card", JSON.stringify([now.version, toolsKey()]), () => agentCard(ctx.url.origin, now), "application/json", "public, max-age=3600", true); |
| 159 | 162 | } |
| @@ -407,7 +410,8 @@ const llmsBodies = new Map<string, { repos: LlmsListing; running: string; tell: | ||
| 407 | 410 | * where the API and the MCP are, and the public repositories. Facts only, |
| 408 | 411 | * each with the method and URL that does it. |
| 409 | 412 | */ |
| 410 | export function llmsTxt(ctx: Ctx): Response { | |
| 413 | export async function llmsTxt(ctx: Ctx): Promise<Response> { | |
| 414 | await loadMcp(); | |
| 411 | 415 | const kept = llmsBody(ctx); |
| 412 | 416 | // The third line names the running commit: a client revalidates (one small 304) |
| 413 | 417 | // rather than keep an old build for an hour. |
| @@ -424,7 +428,11 @@ export function llmsTxt(ctx: Ctx): Response { | ||
| 424 | 428 | return res; |
| 425 | 429 | } |
| 426 | 430 | |
| 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 | */ | |
| 428 | 436 | export function llmsBody(ctx: Ctx): { body: string; etag: string } { |
| 429 | 437 | const o = ctx.url.origin; |
| 430 | 438 | const tell = sshTellCommand(ctx.app); |
test/boot-lazy.test.ts +52 −3
| @@ -1,10 +1,14 @@ | ||
| 1 | 1 | /** |
| 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. | |
| 4 | 5 | */ |
| 5 | import { expect, test } from "bun:test"; | |
| 6 | import { describe, expect, test } from "bun:test"; | |
| 6 | 7 | import { existsSync, readFileSync } from "node:fs"; |
| 7 | 8 | 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"; | |
| 8 | 12 | |
| 9 | 13 | const FROM = /(?:^|\n)\s*(?:import|export)\s+(?!type\b)[^;]*?from\s+"(\.[^"]+)"|(?:^|\n)\s*import\s+"(\.[^"]+)"/g; |
| 10 | 14 | |
| @@ -32,3 +36,48 @@ test("the boot's static imports do not reach the terminal UI", () => { | ||
| 32 | 36 | test("the terminal's server is imported dynamically by the boot", () => { |
| 33 | 37 | expect(readFileSync(resolve("src/main.ts"), "utf8")).toContain('import("./tui/ssh.ts")'); |
| 34 | 38 | }); |
| 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 | }); |
new above
offline