TypeScript
perf(server): background service launcher uses 75% less memory (#29284)
Theo Browne6577c6b61851
diff --git a/apps/server/scripts/cli.ts b/apps/server/scripts/cli.tsindex 5bb8b74474b..c4fa5013579 100644--- a/apps/server/scripts/cli.ts+++ b/apps/server/scripts/cli.ts@@ -16,6 +16,7 @@ import rootPackageJson from "../../../package.json" with { type: "json" };import * as HostProcess from "@t3tools/shared/HostProcess";import { resolveSpawnCommand } from "@t3tools/shared/shell";import {+ ServerCliBootstrapTooLargeError,ServerCliBuildAssetMissingError,ServerCliCommandExitError,ServerCliDevelopmentIconSourceMissingError,@@ -127,30 +128,48 @@ const buildExeCmd = Command.make((yield* HostProcess.Platform) === "linux" &&(yield* HostProcess.Architecture) === "arm64";const spawnCommand = yield* resolveSpawnCommand("vp", ["pack"]);- yield* runCommand(- ChildProcess.make(spawnCommand.command, spawnCommand.args, {- cwd: serverDir,- env: {- ...process.env,- T3CODE_PACK_EXE: linuxArm64 ? "bundle" : "1",- T3CODE_PACK_EXE_TARGET: target ?? "",- },- stdout: config.verbose ? "inherit" : "ignore",- stderr: "inherit",- shell: spawnCommand.shell,- }),- );+ const cliAssetDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-cli-asset-" });+ const pack = (packMode: "bundle" | "bootstrap" | "1") =>+ runCommand(+ ChildProcess.make(spawnCommand.command, spawnCommand.args, {+ cwd: serverDir,+ env: {+ ...process.env,+ T3CODE_PACK_EXE: packMode,+ T3CODE_CLI_ASSET_DIR: cliAssetDir,+ T3CODE_PACK_EXE_TARGET: target ?? "",+ },+ stdout: config.verbose ? "inherit" : "ignore",+ stderr: "inherit",+ shell: spawnCommand.shell,+ }),+ );++ yield* pack("bundle");+ const cliMainPath = path.join(cliAssetDir, "binMain.mjs");+ yield* pack(linuxArm64 ? "bootstrap" : "1");// Executables reject non-builtin imports even when bundling succeeds; inspect the emitted graph.- const bundlePath = path.join(serverDir, "dist-exe/bin.mjs");- const specifiers = findEsmImportsOfExternalPackages(yield* fs.readFileString(bundlePath));- if (specifiers.length > 0) {- return yield* new ServerCliExecutableImportError({ bundlePath, specifiers });+ const bootstrapPath = path.join(serverDir, "dist-exe/bin.mjs");+ for (const bundlePath of [bootstrapPath, cliMainPath]) {+ const specifiers = findEsmImportsOfExternalPackages(yield* fs.readFileString(bundlePath));+ if (specifiers.length > 0) {+ return yield* new ServerCliExecutableImportError({ bundlePath, specifiers });+ }+ }+ // The service launcher's memory win depends on the CLI staying out of the bootstrap.+ const bootstrapBytes = (yield* fs.stat(bootstrapPath)).size;+ if (bootstrapBytes > 1024 * 1024) {+ return yield* new ServerCliBootstrapTooLargeError({+ bootstrapPath,+ bytes: Number(bootstrapBytes),+ });}// TEMPORARY one-time Node fix. Remove when fixed: https://github.com/nodejs/node/issues/67048if (linuxArm64) {yield* injectLinuxArm64Sea({- bundlePath,+ bundlePath: bootstrapPath,+ cliAssetPath: cliMainPath,outputPath: path.join(serverDir, "dist-exe/t3"),nodeVersion: rootPackageJson.engines.node,verbose: config.verbose,diff --git a/apps/server/scripts/cliErrors.ts b/apps/server/scripts/cliErrors.tsindex 5c02281aabb..6c3a954809c 100644--- a/apps/server/scripts/cliErrors.ts+++ b/apps/server/scripts/cliErrors.ts@@ -58,3 +58,15 @@ export class ServerCliExecutableImportError extends Schema.TaggedError<ServerClireturn `${this.bundlePath} imports file-backed packages that a single-executable cannot resolve: ${this.specifiers.join(", ")}. Load them through createRequire instead.`;}}++export class ServerCliBootstrapTooLargeError extends Schema.TaggedError<ServerCliBootstrapTooLargeError>()(+ "ServerCliBootstrapTooLargeError",+ {+ bootstrapPath: Schema.String,+ bytes: Schema.Number,+ },+) {+ override get message(): string {+ return `${this.bootstrapPath} is ${this.bytes} bytes. The CLI was bundled into the executable bootstrap; keep ./binMain.ts external.`;+ }+}diff --git a/apps/server/src/bin.ts b/apps/server/src/bin.tsindex 8cd59674ef6..b69fa6e4bb2 100644--- a/apps/server/src/bin.ts+++ b/apps/server/src/bin.ts@@ -1,11 +1,34 @@-/**- * Every ACP agent spawns `t3 acp-mcp-bridge` while opening its session, and terminal-fallback- * agents run `t3 acp-mcp-call` per tool call, so their startup sits on first-message latency.- * They and Codex's managed-token helper dispatch before the full CLI module graph (seconds- * of evaluation) loads; everything else defers to the real CLI in ./binCli.ts.- */+// @effect-diagnostics nodeBuiltinImport:off -- The service launcher starts before the CLI runtime.+import * as NodeModule from "node:module";+import * as NodeSea from "node:sea";+import * as NodeURL from "node:url";+import { isEntrypoint } from "./entrypoint.ts";-import { enableCliCompileCache } from "./cliCompileCache.ts";++// Loads the CLI outside the launcher's module graph. Packaged builds embed it as a raw asset.+async function loadCliMain(): Promise<typeof import("./binMain.ts")> {+ if (!NodeSea.isSea()) return import("./binMain.ts");++ // Keep the executable's module URL so the CLI finds the web client and native packages beside it.+ const require = NodeModule.createRequire(import.meta.url);+ // require() resolves links in the executable path, such as a Windows junction.+ const cliUrl = NodeURL.pathToFileURL(require.resolve(process.execPath)).href;+ const hook = NodeModule.registerHooks({+ load(url, context, next) {+ if (url !== cliUrl) return next(url, context);+ return {+ format: "module",+ source: new Uint8Array(NodeSea.getRawAsset("binMain.mjs")),+ shortCircuit: true,+ };+ },+ });+ try {+ return require(process.execPath) as typeof import("./binMain.ts");+ } finally {+ hook.deregister();+ }+}if (isEntrypoint({@@ -14,42 +37,13 @@ if (runtimeMain: import.meta.main,})) {- const command = process.argv[2];- // Guard sockets before either dispatch path can load outbound-capable modules.- const { ignoreMacosTypeOfServiceEinval } = await import("./outboundHttp.ts");- ignoreMacosTypeOfServiceEinval();- if (command === "__document-text") {- const { extractDocumentText } = await import("./provider/documentTextWorker.ts");- try {- process.stdout.write(await extractDocumentText(process.argv[3]!, process.argv[4]!));- } catch (error) {- if (error instanceof Error && "code" in error && /^E[A-Z0-9]+$/.test(String(error.code))) {- throw error;- }- // Exit 2 identifies document rejections; OS and process failures remain retryable.- process.exitCode = 2;- }- } else if (command === "__managed-chatgpt-token") {- const { runManagedChatGptTokenCli } = await import("./cli/managedChatGptToken.ts");- await runManagedChatGptTokenCli(process.argv.slice(3));- } else if (command === "acp-mcp-bridge" || command === "acp-mcp-call") {- const { runAcpMcpCliFastPath } = await import("./mcp/AcpMcpStdioBridge.ts");- await runAcpMcpCliFastPath(command, process.argv.slice(3));- } else if (command === "__speech-worker") {- const mode = process.argv[3];- if (mode !== "discover" && mode !== "model") throw new Error("Unknown speech worker mode.");- const { runNativeSpeechWorker } = await import("./speech/native.ts");- await runNativeSpeechWorker(mode, process.argv[4]);+ // The launcher owns shutdown until its child exits, so it bypasses the Effect CLI runtime.+ // The service unit passes no arguments; flags and help go through the full CLI.+ if (process.argv[2] === "__service-launcher" && process.argv.length === 3) {+ const { runServiceLauncherCli } = await import("./cli/serviceLauncher.ts");+ await runServiceLauncherCli();} else {- enableCliCompileCache();- // Windows desktop launches without stdin; attach before reading, except on fast paths using pipes.- const { attachConsoleStdin } = await import("./cli/consoleStdin.ts");- attachConsoleStdin();- const importStart = performance.now();- const { runCli } = await import("./binCli.ts");- if (process.env.T3CODE_STARTUP_PROFILE_DIR) {- performance.measure("server.import.binCli", { start: importStart });- }- runCli();+ const { runCliCommand } = await loadCliMain();+ await runCliCommand();}}diff --git a/apps/server/src/binCli.ts b/apps/server/src/binCli.tsindex 5ea04dfff18..ee3ef9402f8 100644--- a/apps/server/src/binCli.ts+++ b/apps/server/src/binCli.ts@@ -24,7 +24,7 @@ import { threadCommand } from "./cli/thread.ts";import { runDefaultServerCommand, serveCommand, startCommand } from "./cli/server.ts";import { updateCommand } from "./cli/update.ts";import { uninstallCommand } from "./cli/uninstall.ts";-import { serviceLauncherCommand } from "./cli/serviceLauncher.ts";+import { runServiceLauncherCli } from "./cli/serviceLauncher.ts";import { speechWorkerCommand } from "./cli/speechWorker.ts";import { claudeHistoryCommand } from "./cli/claudeHistory.ts";import { sshHelperCommand } from "./cli/sshHelper.ts";@@ -90,7 +90,12 @@ export const makeCli = ({ cloudEnabled = hasCloudPublicConfig } = {}) =>serviceCommand,updateCommand,uninstallCommand,- serviceLauncherCommand,+ // bin.ts runs the bare service invocation; this keeps flags and help working like other commands.+ Command.make("__service-launcher").pipe(+ Command.unlisted,+ // The launcher owns shutdown until its child exits; `runMain` would interrupt that shutdown.+ Command.withHandler(() => Effect.sync(() => void runServiceLauncherCli())),+ ),claudeHistoryCommand,speechWorkerCommand,sshHelperCommand,diff --git a/apps/server/src/binMain.ts b/apps/server/src/binMain.tsnew file mode 100644index 00000000000..0dabd738734--- /dev/null+++ b/apps/server/src/binMain.ts@@ -0,0 +1,45 @@+import { enableCliCompileCache } from "./cliCompileCache.ts";++// Packaged builds load this graph with require(esm): top-level await anywhere in it breaks them.+// ACP agents spawn `acp-mcp-bridge` per session and `acp-mcp-call` per tool call, so those fast+// paths dispatch before the full CLI module graph (seconds of evaluation) loads.+export async function runCliCommand() {+ const command = process.argv[2];+ // Install the socket guard before importing code that can open outbound connections.+ const { ignoreMacosTypeOfServiceEinval } = await import("./outboundHttp.ts");+ ignoreMacosTypeOfServiceEinval();+ if (command === "__document-text") {+ const { extractDocumentText } = await import("./provider/documentTextWorker.ts");+ try {+ process.stdout.write(await extractDocumentText(process.argv[3]!, process.argv[4]!));+ } catch (error) {+ if (error instanceof Error && "code" in error && /^E[A-Z0-9]+$/.test(String(error.code))) {+ throw error;+ }+ // Exit 2 identifies document rejections; OS and process failures remain retryable.+ process.exitCode = 2;+ }+ } else if (command === "__managed-chatgpt-token") {+ const { runManagedChatGptTokenCli } = await import("./cli/managedChatGptToken.ts");+ await runManagedChatGptTokenCli(process.argv.slice(3));+ } else if (command === "acp-mcp-bridge" || command === "acp-mcp-call") {+ const { runAcpMcpCliFastPath } = await import("./mcp/AcpMcpStdioBridge.ts");+ await runAcpMcpCliFastPath(command, process.argv.slice(3));+ } else if (command === "__speech-worker") {+ const mode = process.argv[3];+ if (mode !== "discover" && mode !== "model") throw new Error("Unknown speech worker mode.");+ const { runNativeSpeechWorker } = await import("./speech/native.ts");+ await runNativeSpeechWorker(mode, process.argv[4]);+ } else {+ enableCliCompileCache();+ // Windows desktop launches without stdin; attach before reading, except on fast paths using pipes.+ const { attachConsoleStdin } = await import("./cli/consoleStdin.ts");+ attachConsoleStdin();+ const importStart = performance.now();+ const { runCli } = await import("./binCli.ts");+ if (process.env.T3CODE_STARTUP_PROFILE_DIR) {+ performance.measure("server.import.binCli", { start: importStart });+ }+ runCli();+ }+}diff --git a/apps/server/src/cli/serviceLauncher.ts b/apps/server/src/cli/serviceLauncher.tsindex a1af566d0c7..252659fd254 100644--- a/apps/server/src/cli/serviceLauncher.ts+++ b/apps/server/src/cli/serviceLauncher.ts@@ -1,18 +1,11 @@-import * as Effect from "effect/Effect";-import { Command } from "effect/cli";-import { main as runServiceLauncher } from "../serviceLauncher.ts";-/** The launcher must stop its child before exiting; `runMain` would interrupt that shutdown. */-export const serviceLauncherCommand = Command.make("__service-launcher").pipe(- Command.unlisted,- Command.withHandler(() =>- Effect.sync(() => {- runServiceLauncher().catch((cause: unknown) => {- const error = cause instanceof Error ? cause : new Error(String(cause));- process.stderr.write(`[service-launcher] ${error.message}\n`);- process.exitCode = 1;- });- }),- ),-);+export async function runServiceLauncherCli(): Promise<void> {+ try {+ await runServiceLauncher();+ } catch (cause) {+ const message = cause instanceof Error ? cause.message : String(cause);+ process.stderr.write(`[service-launcher] ${message}\n`);+ process.exitCode = 1;+ }+}diff --git a/apps/server/src/cliCompileCache.test.ts b/apps/server/src/cliCompileCache.test.tsindex 0603ce51786..b58e7969999 100644--- a/apps/server/src/cliCompileCache.test.ts+++ b/apps/server/src/cliCompileCache.test.ts@@ -7,13 +7,23 @@ import * as FileSystem from "effect/FileSystem";import * as Stream from "effect/Stream";import { ChildProcess, ChildProcessSpawner } from "effect/process";-it.live("enables CLI caching while respecting overrides and unavailable storage", () =>+it.live("loads the CLI with its cache settings only when the command needs it", () =>Effect.gen(function* () {const fs = yield* FileSystem.FileSystem;const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-cli-cache-test-" });- const report = `import { getCompileCacheDir, registerHooks } from 'node:module'; registerHooks({ resolve(specifier, context, nextResolve) { if (specifier === './binCli.ts') console.error('CACHE=' + (getCompileCacheDir() ?? 'disabled')); return nextResolve(specifier, context); } });`;- const run = Effect.fn("cliCompileCache.test.run")(function* (env: Record<string, string>) {+ const report = `+ import { getCompileCacheDir, registerHooks } from 'node:module';+ registerHooks({ resolve(specifier, context, nextResolve) {+ if (specifier === './binMain.ts') console.error('LOADED_CLI_MAIN');+ if (specifier === './binCli.ts') console.error('CACHE=' + (getCompileCacheDir() ?? 'disabled'));+ return nextResolve(specifier, context);+ } });+ `;+ const run = Effect.fn("cliCompileCache.test.run")(function* (+ env: Record<string, string>,+ args: ReadonlyArray<string> = ["--help"],+ ) {const child = yield* spawner.spawn(ChildProcess.make(process.execPath,@@ -22,7 +32,7 @@ it.live("enables CLI caching while respecting overrides and unavailable storage""--import",`data:text/javascript,${encodeURIComponent(report)}`,NodeURL.fileURLToPath(new URL("./bin.ts", import.meta.url)),- "--help",+ ...args,],{env: {@@ -47,9 +57,26 @@ it.live("enables CLI caching while respecting overrides and unavailable storage"}, Effect.scoped);const normal = yield* run({});expect(normal.exitCode).toBe(0);+ expect(normal.stderr).toContain("LOADED_CLI_MAIN");expect(normal.stderr.replaceAll("\\", "/")).toContain(`CACHE=${root}/cache/t3code/compile-cache`.replaceAll("\\", "/"),);+ const launcher = yield* run({ T3CODE_HOME: "" }, ["__service-launcher"]);+ expect(launcher.exitCode).toBe(1);+ expect(launcher.stderr).toContain("[service-launcher] T3CODE_HOME is required");+ expect(launcher.stderr).not.toMatch(/LOADED_CLI_MAIN|CACHE=/);+ const launcherHelp = yield* run({ T3CODE_HOME: "" }, ["__service-launcher", "--help"]);+ expect(launcherHelp.exitCode).toBe(0);+ expect(launcherHelp.stderr).toContain("LOADED_CLI_MAIN");+ expect(launcherHelp.stdout).toContain("t3 __service-launcher [flags]");+ const launcherFlags = yield* run({ T3CODE_HOME: "" }, [+ "__service-launcher",+ "--log-level",+ "debug",+ ]);+ expect(launcherFlags.exitCode).toBe(1);+ expect(launcherFlags.stderr).toContain("LOADED_CLI_MAIN");+ expect(launcherFlags.stderr).toContain("[service-launcher] T3CODE_HOME is required");const appImage = yield* run({ APPIMAGE: `${root}/T3Code.AppImage` });expect(appImage.exitCode).toBe(0);expect(appImage.stderr).toContain("CACHE=disabled");diff --git a/apps/server/vite.config.ts b/apps/server/vite.config.tsindex cb77ab545c6..02fe582953a 100644--- a/apps/server/vite.config.ts+++ b/apps/server/vite.config.ts@@ -1,4 +1,6 @@import "vite-plus/test/config";+// @effect-diagnostics-next-line nodeBuiltinImport:off -- tsdown needs the asset path when it reads this config.+import * as NodePath from "node:path";import { defineConfig, mergeConfig } from "vite-plus";import baseConfig from "../../vite.config.ts";@@ -29,10 +31,14 @@ if (!TELEMETRY_CHANNELS.includes(telemetryChannel)) {}// tsdown SEA needs one chunk (sourcemaps count) and Node >=25.7, so package separately.+// "bundle" emits the embedded CLI. "1" builds dist-exe/t3 from the bootstrap.// TEMPORARY one-time Node fix. Remove when fixed: https://github.com/nodejs/node/issues/67048-// "1" builds dist-exe/t3 here; "bundle" stops at bin.mjs for scripts/cli.ts to inject (linux-arm64).+// "bootstrap" stops at bin.mjs for scripts/cli.ts to inject (linux-arm64).const packMode = process.env.T3CODE_PACK_EXE;-const packExecutable = packMode === "1" || packMode === "bundle";+const packBootstrap = packMode === "1" || packMode === "bootstrap";+const packExecutable = packBootstrap || packMode === "bundle";+const cliAssetDir = process.env.T3CODE_CLI_ASSET_DIR ?? "";+if (packExecutable && !cliAssetDir) throw new Error("Build the executable with build:exe.");// TEMPORARY one-time Node fix. Remove when fixed: https://github.com/nodejs/node/issues/67048// No linux-arm64: --build-sea output cannot load on 16/64 KiB page kernels, so it builds natively.const SEA_TARGETS = {@@ -83,12 +89,15 @@ export default mergeConfig(},pack: {// SEA embeds one entry; expose the history worker as a hidden subcommand.- entry: packExecutable ? ["src/bin.ts"] : ["src/bin.ts", "src/claude-history-worker.ts"],- outDir: packExecutable ? "dist-exe" : "dist",+ entry: packBootstrap+ ? ["src/bin.ts"]+ : packExecutable+ ? ["src/binMain.ts"]+ : ["src/bin.ts", "src/claude-history-worker.ts"],+ outDir: packBootstrap ? "dist-exe" : packExecutable ? cliAssetDir : "dist",sourcemap: !packExecutable,clean: true,- // TEMPORARY one-time Node fix. Remove when fixed: https://github.com/nodejs/node/issues/67048- // SEA can only resolve built-ins; keep dynamic imports inside its one module.+ // SEA can only resolve built-ins; keep dynamic imports inside each emitted module....(packExecutable ? { outputOptions: { codeSplitting: false } } : {}),...(packMode === "1"? {@@ -97,14 +106,20 @@ export default mergeConfig(outDir: "dist-exe",...(packExecutableTargets ? { targets: packExecutableTargets } : {}),// Node SEA useCodeCache breaks import(), which the server needs.- seaConfig: { useCodeCache: false },+ seaConfig: {+ useCodeCache: false,+ // The bootstrap loads the embedded CLI with require(esm).+ execArgv: ["--require-module"],+ assets: { "binMain.mjs": NodePath.join(cliAssetDir, "binMain.mjs") },+ },},}: {}),deps: {// alwaysBundle=false has no opinion; neverBundle must retain transitive native acceleration.alwaysBundle: shouldBundleCliDependency,- neverBundle: (id: string) => isExternalCliDependency(id),+ neverBundle: (id: string) =>+ (packBootstrap && id === "./binMain.ts") || isExternalCliDependency(id),onlyBundle: false,},banner: {diff --git a/scripts/lib/linux-arm64-sea.ts b/scripts/lib/linux-arm64-sea.tsindex 0071f59c200..8851e125e9c 100644--- a/scripts/lib/linux-arm64-sea.ts+++ b/scripts/lib/linux-arm64-sea.ts@@ -32,6 +32,7 @@ const run = Effect.fn("LinuxArm64Sea.run")(function* (args: Array<string>, verbo// Builds the SEA blob with this Node and injects it into a copy of this Node with postject.export const injectLinuxArm64Sea = Effect.fn("LinuxArm64Sea.inject")(function* (input: {bundlePath: string;+ cliAssetPath: string;outputPath: string;nodeVersion: string;verbose: boolean;@@ -51,11 +52,14 @@ export const injectLinuxArm64Sea = Effect.fn("LinuxArm64Sea.inject")(function* (configPath,yield* encodeJson({main: input.bundlePath,+ assets: { "binMain.mjs": input.cliAssetPath },output: blobPath,mainFormat: "module",disableExperimentalSEAWarning: true,// Node SEA useCodeCache breaks import(), which the server needs.useCodeCache: false,+ // The bootstrap loads the embedded CLI with require(esm).+ execArgv: ["--require-module"],}),);yield* run(["--experimental-sea-config", configPath], input.verbose);diff --git a/scripts/smoke-cli-archive.ts b/scripts/smoke-cli-archive.tsindex 1318aa3c0c6..e11d63c3081 100644--- a/scripts/smoke-cli-archive.ts+++ b/scripts/smoke-cli-archive.ts@@ -135,6 +135,15 @@ const smokeCliArchive = Effect.fn("smokeCliArchive")(function* (input: {});}+ // The service launcher loads outside the embedded CLI; without T3CODE_HOME it exits right away.+ const launcher = yield* runExecutable(executable, ["__service-launcher"], contentDir);+ if (launcher.exitCode !== 1 || !launcher.stderr.includes("T3CODE_HOME is required")) {+ return yield* new CliArchiveSmokeError({+ step: "running __service-launcher",+ detail: `exit ${String(launcher.exitCode)}\n${launcher.stdout}${launcher.stderr}`,+ });+ }+const net = yield* NetService.NetService;const port = yield* net.findAvailablePort(47700);const home = path.join(scratch, "home");@@ -191,7 +200,9 @@ const smokeCliArchive = Effect.fn("smokeCliArchive")(function* (input: {detail: `no 200 from / within 30s\n${stdout}${stderr}`,});}- yield* Effect.log(`[cli-smoke] ${root}: --version passed and serve answered on ${String(port)}.`);+ yield* Effect.log(+ `[cli-smoke] ${root}: --version and __service-launcher passed, and serve answered on ${String(port)}.`,+ );});const command = Command.make(