perf(cli): load the Maestro engine only when a replay entry is a flow

The command registry evaluates every command family on CLI startup, so the replay script-source builder's static @agent-device/maestro import put the YAML parser on the --help path. It now loads on demand behind the format check, and the startup import-closure guard covers the engine the way it already covers node:http.

Author: thymikee

src/__tests__/cli-startup-import-closure.test.ts

@@ -12,6 +12,12 @@ import { parseSync } from 'oxc-parser';
  * socket). The HTTP daemon transport, remote-artifact upload and download all
  * load these modules on demand instead.
  *
+ * `@agent-device/maestro` is held to the same line for the same reason. The command registry
+ * evaluates every command family's module on startup -- `--help` included -- so a replay-side
+ * static import of the Maestro engine (and the YAML parser behind it) put a 131 kB chunk and
+ * ~28ms on every warm command, for a format most invocations never touch (#1802). The replay
+ * script-source builder loads it on demand, only once an entry actually resolves to a flow.
+ *
  * "On demand" is a claim about SCOPE, not about syntax, which is why this reads
  * the AST rather than matching import forms. Two shapes evaluate the module
  * during module evaluation while looking lazy or looking like nothing at all:
@@ -29,6 +35,8 @@ import { parseSync } from 'oxc-parser';
 
 const srcRoot = path.resolve(import.meta.dirname, '..');
 const LAZY_HTTP_MODULES = new Set(['node:http', 'node:https']);
+/** Engines heavy enough that evaluating them on startup is a measurable regression. */
+const LAZY_ENGINE_MODULES = new Set(['@agent-device/maestro']);
 const FUNCTION_NODES = new Set([
   'FunctionDeclaration',
   'FunctionExpression',
@@ -259,6 +267,24 @@ test('the CLI startup import closure never evaluates node:http or node:https', (
   ).toEqual([]);
 });
 
+test('the CLI startup import closure never evaluates the Maestro engine', () => {
+  const offenders: string[] = [];
+  for (const file of eagerClosureOfCli()) {
+    for (const specifier of eagerlyEvaluatedModules(file, fs.readFileSync(file, 'utf8'))) {
+      if (LAZY_ENGINE_MODULES.has(specifier)) {
+        offenders.push(`${path.relative(srcRoot, file)} -> ${specifier}`);
+      }
+    }
+  }
+
+  expect(
+    offenders,
+    'Load @agent-device/maestro on demand instead: the command registry evaluates every command ' +
+      'family on startup, so importing the engine here costs every warm CLI command ~28ms of ' +
+      'YAML-parser evaluation and a 131 kB startup chunk, for a format most runs never use.',
+  ).toEqual([]);
+});
+
 test('the CLI startup import closure is reachable and crosses the package boundary', () => {
   // Guards the test above from silently passing because the walk found nothing:
   // a resolver that returned null for everything would leave both the src side

src/__tests__/test-utils/replay-script-source.ts

@@ -1,22 +1,30 @@
 import type { ReplayScriptSourceBundle } from '@agent-device/contracts/replay';
 import type { MaestroSourceReader } from '@agent-device/maestro';
 import type { DaemonRequest } from '../../daemon/types.ts';
-import { buildReplayScriptSourceBundle } from '../../replay/script-source-bundle.ts';
+import {
+  loadReplayScriptSourceBundle,
+  readAdScriptSourceBundle,
+} from '../../replay/script-source-bundle.ts';
 import { discoverReplaySourcePaths } from '../../replay/source-discovery.ts';
 
 /**
- * Builds a replay script source bundle from a file on disk the way a real
- * caller does (#1802) — through the client's own builder, so a test never
- * hand-rolls a bundle shape the CLI would not actually send.
+ * A native `.ad` script's bundle, built from a file on disk through the client's own reader
+ * (#1802) so a test never hand-rolls a shape the CLI would not actually send. Synchronous
+ * because an `.ad` script has no include grammar and needs no engine; use
+ * `maestroScriptSourceBundleFor` for a flow.
  */
-export function replayScriptSourceBundleFor(
+export function replayScriptSourceBundleFor(filePath: string): ReplayScriptSourceBundle {
+  return readAdScriptSourceBundle({ inputPath: filePath, cwd: process.cwd() });
+}
+
+/** A Maestro flow's bundle — async because the engine that walks its includes loads on demand. */
+export async function maestroScriptSourceBundleFor(
   filePath: string,
-  options: { replayBackend?: string } = {},
-): ReplayScriptSourceBundle {
-  return buildReplayScriptSourceBundle({
+): Promise<ReplayScriptSourceBundle> {
+  return await loadReplayScriptSourceBundle({
     inputPath: filePath,
     cwd: process.cwd(),
-    replayBackend: options.replayBackend,
+    replayBackend: 'maestro',
   });
 }
 
@@ -41,7 +49,7 @@ export const noMaestroIncludeSources: MaestroSourceReader = (resolvedPath) => {
  * the CLI boundary (pinned in `cli-client-commands.test.ts`), and a daemon-level harness must
  * still deliver the request so the daemon's own response is what the case observes.
  */
-export function withClientReplayScriptSources(req: DaemonRequest): DaemonRequest {
+export async function withClientReplayScriptSources(req: DaemonRequest): Promise<DaemonRequest> {
   if (req.command !== 'replay' && req.command !== 'test') return req;
   const inputs = req.positionals ?? [];
   const entryPath = inputs[0];
@@ -52,7 +60,7 @@ export function withClientReplayScriptSources(req: DaemonRequest): DaemonRequest
     if (req.command === 'replay') {
       if (req.flags?.replayScriptSource) return req;
       return withFlags(req, {
-        replayScriptSource: buildReplayScriptSourceBundle({
+        replayScriptSource: await loadReplayScriptSourceBundle({
           inputPath: entryPath,
           cwd,
           replayBackend,
@@ -61,8 +69,11 @@ export function withClientReplayScriptSources(req: DaemonRequest): DaemonRequest
     }
     if (req.flags?.replayScriptSources) return req;
     return withFlags(req, {
-      replayScriptSources: discoverReplaySourcePaths({ inputs, cwd, replayBackend }).map(
-        (inputPath) => buildReplayScriptSourceBundle({ inputPath, cwd, replayBackend }),
+      replayScriptSources: await Promise.all(
+        discoverReplaySourcePaths({ inputs, cwd, replayBackend }).map(
+          async (inputPath) =>
+            await loadReplayScriptSourceBundle({ inputPath, cwd, replayBackend }),
+        ),
       ),
     });
   } catch {

src/agent-device-client.ts

@@ -131,7 +131,7 @@ export function createAgentDeviceClient(
     command: DaemonCommandName,
     options: InternalRequestOptions = {},
   ): Promise<T> => {
-    const request = prepareDaemonCommandRequest(command, options);
+    const request = await prepareDaemonCommandRequest(command, options);
     return (await execute(
       request.command,
       request.positionals,

src/commands/batch/projection.ts

@@ -11,7 +11,11 @@ import {
 } from '@agent-device/contracts/command';
 import { AppError } from '@agent-device/kernel/errors';
 import { request } from '../cli-grammar/common.ts';
-import type { CommandInput, DaemonCommandRequest, DaemonWriter } from '../cli-grammar/types.ts';
+import type {
+  AsyncDaemonWriter,
+  CommandInput,
+  DaemonCommandRequest,
+} from '../cli-grammar/types.ts';
 import { buildRequestFlags } from '../command-flags.ts';
 import type { DaemonCommandName } from '../command-projection.ts';
 
@@ -23,42 +27,46 @@ type PrepareDaemonCommandRequest = (
   command: string,
   input: CommandInput,
   stepNumber: number,
-) => DaemonCommandRequest;
+) => Promise<DaemonCommandRequest>;
 
 export function createBatchDaemonWriter(
   prepareDaemonCommandRequest: PrepareDaemonCommandRequest,
-): DaemonWriter {
-  return (input) =>
+): AsyncDaemonWriter {
+  return async (input) =>
     request(PUBLIC_COMMANDS.batch, [], {
       ...input,
-      batchSteps: readBatchDaemonSteps(input.steps, prepareDaemonCommandRequest),
+      batchSteps: await readBatchDaemonSteps(input.steps, prepareDaemonCommandRequest),
       batchOnError: input.onError,
       batchMaxSteps: input.maxSteps,
     });
 }
 
-function readBatchDaemonSteps(
+async function readBatchDaemonSteps(
   steps: unknown,
   prepareDaemonCommandRequest: PrepareDaemonCommandRequest,
-): DaemonBatchStep[] {
+): Promise<DaemonBatchStep[]> {
   if (!Array.isArray(steps) || steps.length === 0) {
     throw new AppError('INVALID_ARGS', 'batch requires a non-empty steps array.');
   }
-  return steps.map((step, index) =>
-    readBatchDaemonStep(step, index + 1, prepareDaemonCommandRequest),
-  );
+  // Sequential, not `Promise.all`: a step's rejection is reported with its own step number, and
+  // preparing step N+1 after N keeps that number the first failure a caller sees.
+  const prepared: DaemonBatchStep[] = [];
+  for (const [index, step] of steps.entries()) {
+    prepared.push(await readBatchDaemonStep(step, index + 1, prepareDaemonCommandRequest));
+  }
+  return prepared;
 }
 
-function readBatchDaemonStep(
+async function readBatchDaemonStep(
   step: unknown,
   stepNumber: number,
   prepareDaemonCommandRequest: PrepareDaemonCommandRequest,
-): DaemonBatchStep {
+): Promise<DaemonBatchStep> {
   const record = readBatchStepRecord(step, stepNumber);
   const command = readBatchStepCommand(record, stepNumber);
   const input = readBatchStepInputObject(record, stepNumber) as CommandInput;
   const runtime = parseBatchStepRuntime(record.runtime, stepNumber);
-  const prepared = prepareDaemonCommandRequest(command, input, stepNumber);
+  const prepared = await prepareDaemonCommandRequest(command, input, stepNumber);
   return {
     command: prepared.command,
     positionals: prepared.positionals,

src/commands/cli-grammar/types.ts

@@ -85,4 +85,15 @@ export type SelectionOptions = {
 
 export type CliInput = Record<string, unknown>;
 export type CliReader = (positionals: string[], flags: CliFlags) => CliInput;
+/** Builds the daemon request for one command. Most writers are pure projections of their input. */
 export type DaemonWriter = (input: CommandInput) => DaemonCommandRequest;
+
+/**
+ * A writer that has caller-side work to do before the request exists: reading the replay script
+ * files the request carries (#1802), which for a Maestro flow also loads the engine that walks its
+ * `runFlow` includes on demand. The registry awaits whichever kind a command declares, so the
+ * asynchrony stays inside the one writer that needs it.
+ */
+export type AsyncDaemonWriter = (input: CommandInput) => Promise<DaemonCommandRequest>;
+
+export type AnyDaemonWriter = DaemonWriter | AsyncDaemonWriter;

src/commands/command-projection.ts

@@ -1,23 +1,23 @@
 import { createBatchDaemonWriter } from './batch/index.ts';
-import type { CommandInput, DaemonCommandRequest, DaemonWriter } from './cli-grammar/types.ts';
+import type { AnyDaemonWriter, CommandInput, DaemonCommandRequest } from './cli-grammar/types.ts';
 import { findCommandMetadata } from './command-metadata.ts';
 import { readMetadataCommandFlags } from './command-flags.ts';
 import { listCommandFamilyDaemonWriters } from './family/registry.ts';
 import { AppError } from '@agent-device/kernel/errors';
 
-const daemonWriters: Record<string, DaemonWriter> = {
+const daemonWriters: Record<string, AnyDaemonWriter> = {
   ...listCommandFamilyDaemonWriters(),
   batch: createBatchDaemonWriter(prepareBatchDaemonCommandRequest),
 };
 
 export type DaemonCommandName = keyof typeof daemonWriters;
 
-function prepareBatchDaemonCommandRequest(
+async function prepareBatchDaemonCommandRequest(
   command: string,
   input: CommandInput,
   stepNumber: number,
-): DaemonCommandRequest {
-  const writer = (daemonWriters as Readonly<Record<string, DaemonWriter>>)[command];
+): Promise<DaemonCommandRequest> {
+  const writer = (daemonWriters as Readonly<Record<string, AnyDaemonWriter>>)[command];
   if (!writer) {
     throw new Error(`Missing daemon writer for batch command: ${command}`);
   }
@@ -26,7 +26,7 @@ function prepareBatchDaemonCommandRequest(
     throw new Error(`Missing command metadata for batch command: ${command}`);
   }
   try {
-    return prepareRequestWithMetadataFlags(
+    return await prepareRequestWithMetadataFlags(
       writer,
       metadata,
       metadata.readInput(input) as CommandInput,
@@ -42,24 +42,24 @@ function prepareBatchDaemonCommandRequest(
   }
 }
 
-export function prepareDaemonCommandRequest(
+export async function prepareDaemonCommandRequest(
   command: DaemonCommandName,
   input: CommandInput,
-): DaemonCommandRequest {
+): Promise<DaemonCommandRequest> {
   const writer = daemonWriters[command];
   if (!writer) {
     throw new Error(`Missing daemon writer for command: ${command}`);
   }
   const metadata = findCommandMetadata(command);
-  return prepareRequestWithMetadataFlags(writer, metadata, input);
+  return await prepareRequestWithMetadataFlags(writer, metadata, input);
 }
 
-function prepareRequestWithMetadataFlags(
-  writer: DaemonWriter,
+async function prepareRequestWithMetadataFlags(
+  writer: AnyDaemonWriter,
   metadata: ReturnType<typeof findCommandMetadata>,
   input: CommandInput,
-): DaemonCommandRequest {
-  const request = writer(input);
+): Promise<DaemonCommandRequest> {
+  const request = await writer(input);
   return {
     ...request,
     ...(metadata ? { metadataFlags: readMetadataCommandFlags(metadata, request.options) } : {}),

src/commands/family/registry.ts

@@ -1,6 +1,6 @@
 import { batchCommandFamily } from '../batch/index.ts';
 import { captureCommandFamily } from '../capture/index.ts';
-import type { CliReader, DaemonWriter } from '../cli-grammar/types.ts';
+import type { AnyDaemonWriter, CliReader } from '../cli-grammar/types.ts';
 import { debuggingCommandFamily } from '../debugging/index.ts';
 import { interactionCommandFamily } from '../interaction/index.ts';
 import { managementCommandFamily } from '../management/index.ts';
@@ -18,7 +18,7 @@ import { type CommandFamilyFacet } from './types.ts';
 type CommandFamilyRecordMap = {
   cliSchemas: CommandSchema;
   cliReaders: CliReader;
-  daemonWriters: DaemonWriter;
+  daemonWriters: AnyDaemonWriter;
   cliOutputFormatters: CliOutputFormatter;
 };
 
@@ -57,7 +57,7 @@ export function listCommandFamilyCliReaders(): Record<CommandFamilyCommandName,
   return mergeFamilyRecords('cliReaders') as Record<CommandFamilyCommandName, CliReader>;
 }
 
-export function listCommandFamilyDaemonWriters(): Record<string, DaemonWriter> {
+export function listCommandFamilyDaemonWriters(): Record<string, AnyDaemonWriter> {
   return mergeFamilyRecords('daemonWriters');
 }
 

src/commands/family/types.ts

@@ -1,6 +1,6 @@
 import type { AgentDeviceClient } from '../../client/client-types.ts';
 import type { CommandSchema, CommandSchemaOverride } from '../../cli-schema/types.ts';
-import type { CliReader, DaemonWriter } from '../cli-grammar/types.ts';
+import type { AnyDaemonWriter, CliReader } from '../cli-grammar/types.ts';
 import type {
   CommandMetadata,
   ExecutableCommandProjection,
@@ -28,7 +28,7 @@ export type CommandFamilyFacet<TCommandName extends string = string> = {
   clientCommandMethods?: Readonly<Record<string, TCommandName>>;
   cliSchemas?: Readonly<Partial<Record<TCommandName, CommandSchema>>>;
   cliReaders: Readonly<Record<TCommandName, CliReader>>;
-  daemonWriters?: Readonly<Record<string, DaemonWriter>>;
+  daemonWriters?: Readonly<Record<string, AnyDaemonWriter>>;
   cliOutputFormatters?: Readonly<Partial<Record<TCommandName, CliOutputFormatter>>>;
 };
 
@@ -43,7 +43,7 @@ export type CommandFacetInput<TCommandName extends string = string> = {
   cliSchema?: CommandSchemaOverride;
   clientMethod?: string;
   cliReader: CliReader;
-  daemonWriter?: DaemonWriter;
+  daemonWriter?: AnyDaemonWriter;
   cliOutputFormatter?: CliOutputFormatter;
   text: FacetCommandText;
 };
@@ -96,7 +96,7 @@ export function defineCommandFamilyFromFacets<
   const cliSchemas: Record<string, CommandSchema> = {};
   const clientCommandMethods: Record<string, string> = {};
   const cliReaders: Record<string, CliReader> = {};
-  const daemonWriters: Record<string, DaemonWriter> = {};
+  const daemonWriters: Record<string, AnyDaemonWriter> = {};
   const cliOutputFormatters: Record<string, CliOutputFormatter> = {};
 
   for (const command of family.commands) {