@mastra/code-sdk 0.0.0-aggregate-trace-20261015182851

package/dist/headless/cli.js

@@ -0,0 +1,239 @@
+import { listBuiltinModePacks } from "../onboarding/packs.js";
+import { loadSettings, resolveModelDefaults, saveSettings } from "../onboarding/settings.js";
+import { releaseAllThreadLocks } from "../utils/thread-lock.js";
+import { permissionModeToPolicy } from "./policy.js";
+import { runMC } from "./run-mc.js";
+import { createHumanFormatState, formatHuman, formatJsonl, renderJsonResult } from "./format.js";
+import { activateModePackInSettings, resolveModePackArg, resolvePackSelection } from "../onboarding/pack-activation.js";
+import { createProcessMemoryDiagnosticsFromEnvironment, startConfiguredProcessMemoryDiagnostics, stopProcessMemoryDiagnosticsWithTimeout } from "../process-memory-diagnostics.js";
+import { setupDebugLogging } from "../utils/debug-log.js";
+import { FLAGS, buildParseArgsOptions, renderFlagUsage } from "./flags.js";
+import { createMastraCode } from "../index.js";
+import { existsSync } from "fs";
+import { parseArgs } from "util";
+//#region src/headless/cli.ts
+/**
+* CLI adapter for headless MastraCode runs.
+*
+* This is the only headless layer that touches the process: it parses argv,
+* reads stdin, bootstraps MastraCode via `createMastraCode`, drives `runMC`,
+* renders events/results to stdout/stderr through the pure formatters, maps the
+* result to an exit code, and owns teardown + `process.exit`.
+*/
+const parseArgsOptions = buildParseArgsOptions();
+const STOP_NOTIFICATION_DISPATCH_TIMEOUT_MS = 2e3;
+/**
+* Returns true if `argv` selects headless mode. This must agree with what
+* {@link parseHeadlessArgs} (and `runMCCli`) accept as a prompt: `--prompt`/`-p`
+* or a bare positional prompt (e.g. `mastracode "Fix the bug"`). Note that a
+* prompt piped via stdin without a flag is handled separately by the caller.
+*/
+function hasHeadlessFlag(argv) {
+	if (argv.some((a) => a === "--prompt" || a === "-p")) return true;
+	try {
+		const { values, positionals } = parseArgs({
+			args: argv.slice(2),
+			options: parseArgsOptions,
+			strict: false,
+			allowPositionals: true
+		});
+		return positionals.length > 0 && !values.help;
+	} catch {
+		return false;
+	}
+}
+/**
+* Parse CLI arguments for headless mode. The flag table in `flags.ts` is the
+* single source of truth: each flag carries its own coercion/validation, so this
+* function just walks {@link FLAGS} and assembles the typed {@link HeadlessArgs}.
+*/
+function parseHeadlessArgs(argv) {
+	const { values, positionals } = parseArgs({
+		args: argv.slice(2),
+		options: parseArgsOptions,
+		strict: false,
+		allowPositionals: true
+	});
+	const args = {
+		output: "human",
+		continue_: false,
+		cloneThread: false
+	};
+	const sink = args;
+	for (const flag of FLAGS) {
+		if (!flag.field) continue;
+		const raw = values[flag.key];
+		if (raw === void 0) continue;
+		if (flag.type === "boolean") sink[flag.field] = Boolean(raw);
+		else if (typeof raw === "string") sink[flag.field] = flag.coerce ? flag.coerce(raw) : raw;
+	}
+	if (args.prompt === void 0 && positionals[0] !== void 0) args.prompt = positionals[0];
+	if (args.continue_ && args.thread) throw new Error("--continue and --thread cannot be used together");
+	return args;
+}
+function printHeadlessUsage() {
+	process.stdout.write(`
+Usage: mastracode --prompt <text> [options]
+
+Headless (non-interactive) mode options:
+${renderFlagUsage()}
+
+Thread behavior:
+  By default, a new thread is created for each run.
+  Use --continue to resume the most recent thread, or --thread to target a specific one.
+  Use --clone-thread to branch off a copy before running.
+
+Settings file:
+  Uses the same settings.json as the interactive TUI. Pass --settings to use
+  a custom settings file (e.g., settings-ci.json for CI). All model, pack,
+  subagent, and OM configuration is resolved from settings at startup.
+
+Exit codes:
+  0  Agent completed successfully
+  1  Error, aborted, or max turns reached
+  2  Timeout
+
+Examples:
+  mastracode --prompt "Fix the bug in auth.ts"
+  mastracode --prompt "Add tests" --timeout 300 --output json
+  mastracode --prompt "Refactor" --output jsonl
+  mastracode --prompt "Review this PR" --permission-mode deny --max-turns 10
+  mastracode --settings ./settings-ci.json --prompt "Run tests"
+  mastracode -c --prompt "Continue where you left off"
+  echo "Summarize the repo" | mastracode --prompt -
+`);
+}
+/**
+* Headless CLI entry point: parse arguments, read stdin, initialize MastraCode,
+* run via `runMC`, render output, and exit with the mapped code.
+*/
+async function runMCCli(predrainedInput, options) {
+	if (process.argv.includes("--help") || process.argv.includes("-h")) {
+		printHeadlessUsage();
+		process.exit(0);
+	}
+	let args;
+	try {
+		args = parseHeadlessArgs(process.argv);
+	} catch (e) {
+		process.stderr.write(`Error: ${e.message}\n`);
+		process.exit(1);
+	}
+	let prompt = args.prompt;
+	if (predrainedInput !== void 0) prompt = predrainedInput ?? "";
+	else if (prompt === "-" || !prompt && !process.stdin.isTTY) {
+		const chunks = [];
+		for await (const chunk of process.stdin) chunks.push(chunk);
+		prompt = Buffer.concat(chunks).toString("utf-8").trim();
+	}
+	if (!prompt) {
+		printHeadlessUsage();
+		process.stderr.write("Error: --prompt is required (or pipe via stdin)\n");
+		process.exit(1);
+	}
+	if (args.settings && !existsSync(args.settings)) {
+		process.stderr.write(`Error: Settings file not found: ${args.settings}\n`);
+		process.exit(1);
+	}
+	const settings = loadSettings(args.settings);
+	let packId;
+	if (args.pack !== void 0) {
+		const resolved = resolveModePackArg(settings, args.pack);
+		if ("error" in resolved) {
+			process.stderr.write(`Error: ${resolved.error}\n`);
+			process.exit(1);
+		}
+		packId = resolved.packId;
+	}
+	const processMemoryDiagnostics = await startConfiguredProcessMemoryDiagnostics(createProcessMemoryDiagnosticsFromEnvironment(process.env), (warning) => {
+		process.stderr.write(`Warning: ${warning}\n`);
+	});
+	let boot;
+	let exitCode = 1;
+	try {
+		boot = await createMastraCode({
+			settingsPath: args.settings,
+			coAuthor: options?.coAuthor
+		});
+		const { controller, session, mcpManager } = boot;
+		const effectiveDefaults = resolveModelDefaults(settings, listBuiltinModePacks());
+		if (mcpManager?.hasServers()) try {
+			await mcpManager.initInBackground();
+		} catch (err) {
+			process.stderr.write(`Warning: MCP server initialization failed: ${err.message ?? err}\n`);
+		}
+		setupDebugLogging();
+		const humanState = createHumanFormatState();
+		const run = runMC({
+			controller,
+			session,
+			prompt,
+			model: args.model,
+			mode: args.mode,
+			modeDefaults: effectiveDefaults,
+			...packId ? { pack: {
+				id: packId,
+				resolve: (modeId) => resolvePackSelection(settings, packId, modeId),
+				onApplied: () => {
+					activateModePackInSettings(settings, packId);
+					saveSettings(settings, args.settings);
+				}
+			} } : {},
+			thinkingLevel: args.thinkingLevel,
+			thread: {
+				id: args.thread,
+				continueLatest: args.continue_,
+				clone: args.cloneThread
+			},
+			resourceId: args.resourceId,
+			title: args.title,
+			timeoutMs: args.timeout ? args.timeout * 1e3 : void 0,
+			maxTurns: args.maxTurns,
+			policy: args.permissionMode ? permissionModeToPolicy(args.permissionMode) : void 0
+		});
+		for await (const event of run) if (args.output === "human") {
+			const out = formatHuman(event, humanState);
+			if (out.stdout) process.stdout.write(out.stdout);
+			if (out.stderr) process.stderr.write(out.stderr);
+		} else if (args.output === "jsonl") process.stdout.write(JSON.stringify(formatJsonl(event)) + "\n");
+		const result = await run.result;
+		exitCode = result.exitCode;
+		if (args.output === "json") process.stdout.write(renderJsonResult(result));
+		else if (args.output === "jsonl") process.stdout.write(JSON.stringify({
+			type: "result",
+			...result
+		}) + "\n");
+		if (result.status === "timeout") process.stderr.write(`\nTimeout elapsed. Aborted.\n`);
+		else if (result.error && args.output === "human") process.stderr.write(`Error: ${result.error.message}\n`);
+	} catch (err) {
+		process.stderr.write(`Error: ${err.message ?? err}\n`);
+		exitCode = 1;
+	} finally {
+		releaseAllThreadLocks();
+		if (boot) {
+			try {
+				boot.releaseThreadClaims();
+			} catch {}
+			try {
+				boot.stopPluginSignalProviders();
+			} catch {}
+			const { controller, mcpManager } = boot;
+			await Promise.race([boot.stopNotificationDispatch?.().catch(() => {}), new Promise((resolve) => setTimeout(resolve, STOP_NOTIFICATION_DISPATCH_TIMEOUT_MS).unref())]);
+			await Promise.allSettled([
+				mcpManager?.disconnect(),
+				controller.getMastra()?.stopWorkers(),
+				controller.stopIntervals()
+			]);
+			const signalsPubSub = boot.signalsPubSub;
+			await Promise.allSettled([signalsPubSub?.close?.()]);
+		}
+		await stopProcessMemoryDiagnosticsWithTimeout(processMemoryDiagnostics, (warning) => {
+			process.stderr.write(`Warning: ${warning}\n`);
+		});
+	}
+	process.exit(exitCode);
+}
+//#endregion
+export { hasHeadlessFlag, parseHeadlessArgs, printHeadlessUsage, runMCCli };
+
+//# sourceMappingURL=cli.js.map

package/dist/headless/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","names":[],"sources":["../../src/headless/cli.ts"],"sourcesContent":["/**\n * CLI adapter for headless MastraCode runs.\n *\n * This is the only headless layer that touches the process: it parses argv,\n * reads stdin, bootstraps MastraCode via `createMastraCode`, drives `runMC`,\n * renders events/results to stdout/stderr through the pure formatters, maps the\n * result to an exit code, and owns teardown + `process.exit`.\n */\nimport { existsSync } from 'node:fs';\nimport { parseArgs } from 'node:util';\n\nimport { createMastraCode } from '../index.js';\nimport { activateModePackInSettings, resolveModePackArg, resolvePackSelection } from '../onboarding/pack-activation.js';\nimport { listBuiltinModePacks } from '../onboarding/packs.js';\nimport { loadSettings, resolveModelDefaults, saveSettings } from '../onboarding/settings.js';\nimport {\n  createProcessMemoryDiagnosticsFromEnvironment,\n  startConfiguredProcessMemoryDiagnostics,\n  stopProcessMemoryDiagnosticsWithTimeout,\n} from '../process-memory-diagnostics.js';\nimport { setupDebugLogging } from '../utils/debug-log.js';\nimport { releaseAllThreadLocks } from '../utils/thread-lock.js';\n\nimport { buildParseArgsOptions, FLAGS, renderFlagUsage } from './flags.js';\nimport { createHumanFormatState, formatHuman, formatJsonl, renderJsonResult } from './format.js';\nimport { permissionModeToPolicy } from './policy.js';\nimport { runMC } from './run-mc.js';\nimport type { PermissionMode, RunMode, ThinkingLevel } from './types.js';\n\n/** Consolidated output mode (replaces the old `--format` + `--output-format`). */\nexport type OutputMode = 'human' | 'json' | 'jsonl';\n\nexport interface HeadlessArgs {\n  prompt?: string;\n  /** Timeout in seconds (CLI surface); converted to ms before `runMC`. */\n  timeout?: number;\n  output: OutputMode;\n  continue_: boolean;\n  model?: string;\n  pack?: string;\n  mode?: RunMode;\n  thinkingLevel?: ThinkingLevel;\n  settings?: string;\n  thread?: string;\n  title?: string;\n  cloneThread: boolean;\n  resourceId?: string;\n  /** Max agentic turns before the run aborts with exit code 1. */\n  maxTurns?: number;\n  /** Named permission mode resolving to a built-in policy. Defaults to `auto`. */\n  permissionMode?: PermissionMode;\n}\n\nconst parseArgsOptions = buildParseArgsOptions();\nconst STOP_NOTIFICATION_DISPATCH_TIMEOUT_MS = 2_000;\n\n/**\n * Returns true if `argv` selects headless mode. This must agree with what\n * {@link parseHeadlessArgs} (and `runMCCli`) accept as a prompt: `--prompt`/`-p`\n * or a bare positional prompt (e.g. `mastracode \"Fix the bug\"`). Note that a\n * prompt piped via stdin without a flag is handled separately by the caller.\n */\nexport function hasHeadlessFlag(argv: string[]): boolean {\n  if (argv.some(a => a === '--prompt' || a === '-p')) return true;\n  try {\n    const { values, positionals } = parseArgs({\n      args: argv.slice(2),\n      options: parseArgsOptions,\n      strict: false,\n      allowPositionals: true,\n    });\n    // A positional prompt only counts when not asking for help.\n    return positionals.length > 0 && !values.help;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Parse CLI arguments for headless mode. The flag table in `flags.ts` is the\n * single source of truth: each flag carries its own coercion/validation, so this\n * function just walks {@link FLAGS} and assembles the typed {@link HeadlessArgs}.\n */\nexport function parseHeadlessArgs(argv: string[]): HeadlessArgs {\n  const { values, positionals } = parseArgs({\n    args: argv.slice(2),\n    options: parseArgsOptions,\n    strict: false,\n    allowPositionals: true,\n  });\n\n  // Seed defaults; per-flag values below override these.\n  const args: HeadlessArgs = {\n    output: 'human',\n    continue_: false,\n    cloneThread: false,\n  };\n  const sink = args as unknown as Record<string, unknown>;\n\n  for (const flag of FLAGS) {\n    if (!flag.field) continue; // e.g. --help, handled by the caller\n    const raw = values[flag.key];\n    if (raw === undefined) continue;\n\n    if (flag.type === 'boolean') {\n      sink[flag.field] = Boolean(raw);\n    } else if (typeof raw === 'string') {\n      sink[flag.field] = flag.coerce ? flag.coerce(raw) : raw;\n    }\n  }\n\n  // A bare positional acts as the prompt when --prompt/-p is absent.\n  if (args.prompt === undefined && positionals[0] !== undefined) {\n    args.prompt = positionals[0];\n  }\n\n  if (args.continue_ && args.thread) {\n    throw new Error('--continue and --thread cannot be used together');\n  }\n\n  return args;\n}\n\nexport function printHeadlessUsage(): void {\n  process.stdout.write(`\nUsage: mastracode --prompt <text> [options]\n\nHeadless (non-interactive) mode options:\n${renderFlagUsage()}\n\nThread behavior:\n  By default, a new thread is created for each run.\n  Use --continue to resume the most recent thread, or --thread to target a specific one.\n  Use --clone-thread to branch off a copy before running.\n\nSettings file:\n  Uses the same settings.json as the interactive TUI. Pass --settings to use\n  a custom settings file (e.g., settings-ci.json for CI). All model, pack,\n  subagent, and OM configuration is resolved from settings at startup.\n\nExit codes:\n  0  Agent completed successfully\n  1  Error, aborted, or max turns reached\n  2  Timeout\n\nExamples:\n  mastracode --prompt \"Fix the bug in auth.ts\"\n  mastracode --prompt \"Add tests\" --timeout 300 --output json\n  mastracode --prompt \"Refactor\" --output jsonl\n  mastracode --prompt \"Review this PR\" --permission-mode deny --max-turns 10\n  mastracode --settings ./settings-ci.json --prompt \"Run tests\"\n  mastracode -c --prompt \"Continue where you left off\"\n  echo \"Summarize the repo\" | mastracode --prompt -\n`);\n}\n\n/**\n * Headless CLI entry point: parse arguments, read stdin, initialize MastraCode,\n * run via `runMC`, render output, and exit with the mapped code.\n */\nexport async function runMCCli(\n  predrainedInput?: string | null,\n  options?: { coAuthor?: { name?: string; email?: string } },\n): Promise<never> {\n  if (process.argv.includes('--help') || process.argv.includes('-h')) {\n    printHeadlessUsage();\n    process.exit(0);\n  }\n\n  let args: HeadlessArgs;\n  try {\n    args = parseHeadlessArgs(process.argv);\n  } catch (e) {\n    process.stderr.write(`Error: ${(e as Error).message}\\n`);\n    process.exit(1);\n  }\n\n  let prompt = args.prompt;\n  if (predrainedInput !== undefined) {\n    prompt = predrainedInput ?? '';\n  } else if (prompt === '-' || (!prompt && !process.stdin.isTTY)) {\n    const chunks: Buffer[] = [];\n    for await (const chunk of process.stdin) {\n      chunks.push(chunk as Buffer);\n    }\n    prompt = Buffer.concat(chunks).toString('utf-8').trim();\n  }\n\n  if (!prompt) {\n    printHeadlessUsage();\n    process.stderr.write('Error: --prompt is required (or pipe via stdin)\\n');\n    process.exit(1);\n  }\n\n  if (args.settings && !existsSync(args.settings)) {\n    process.stderr.write(`Error: Settings file not found: ${args.settings}\\n`);\n    process.exit(1);\n  }\n\n  // Resolve --pack up front: an unknown pack fails fast with the valid list,\n  // before MastraCode boots. The selection itself is resolved inside runMC\n  // after thread selection, because a resumed thread restores its persisted\n  // mode — the mode that decides whether the pack has a model for this run.\n  // Activation (which mirrors /models → Activate and becomes the global\n  // default pack in settings) is saved via onApplied only once the pack has\n  // actually been applied to the session — a rejected pack must not change\n  // the persisted default on its way out.\n  const settings = loadSettings(args.settings);\n  let packId: string | undefined;\n  if (args.pack !== undefined) {\n    const resolved = resolveModePackArg(settings, args.pack);\n    if ('error' in resolved) {\n      process.stderr.write(`Error: ${resolved.error}\\n`);\n      process.exit(1);\n    }\n    packId = resolved.packId;\n  }\n\n  const diagnosticsSetup = createProcessMemoryDiagnosticsFromEnvironment(process.env);\n  const processMemoryDiagnostics = await startConfiguredProcessMemoryDiagnostics(diagnosticsSetup, warning => {\n    process.stderr.write(`Warning: ${warning}\\n`);\n  });\n\n  let boot: Awaited<ReturnType<typeof createMastraCode>> | undefined;\n  // Default to a non-zero exit so an unexpected throw before the run resolves\n  // still surfaces as a failure to the caller / CI.\n  let exitCode = 1;\n  try {\n    boot = await createMastraCode({ settingsPath: args.settings, coAuthor: options?.coAuthor });\n    const { controller, session, mcpManager } = boot;\n\n    const effectiveDefaults = resolveModelDefaults(settings, listBuiltinModePacks());\n\n    if (mcpManager?.hasServers()) {\n      try {\n        await mcpManager.initInBackground();\n      } catch (err) {\n        process.stderr.write(`Warning: MCP server initialization failed: ${(err as Error).message ?? err}\\n`);\n      }\n    }\n\n    setupDebugLogging();\n\n    const humanState = createHumanFormatState();\n    const run = runMC({\n      controller,\n      session,\n      prompt,\n      model: args.model,\n      mode: args.mode,\n      modeDefaults: effectiveDefaults,\n      ...(packId\n        ? {\n            pack: {\n              id: packId,\n              resolve: (modeId: string) => resolvePackSelection(settings, packId, modeId),\n              onApplied: () => {\n                activateModePackInSettings(settings, packId);\n                saveSettings(settings, args.settings);\n              },\n            },\n          }\n        : {}),\n      thinkingLevel: args.thinkingLevel,\n      thread: { id: args.thread, continueLatest: args.continue_, clone: args.cloneThread },\n      resourceId: args.resourceId,\n      title: args.title,\n      timeoutMs: args.timeout ? args.timeout * 1000 : undefined,\n      maxTurns: args.maxTurns,\n      policy: args.permissionMode ? permissionModeToPolicy(args.permissionMode) : undefined,\n    });\n\n    // Stream live events for human + jsonl modes. (json mode prints only the final object.)\n    for await (const event of run) {\n      if (args.output === 'human') {\n        const out = formatHuman(event, humanState);\n        if (out.stdout) process.stdout.write(out.stdout);\n        if (out.stderr) process.stderr.write(out.stderr);\n      } else if (args.output === 'jsonl') {\n        process.stdout.write(JSON.stringify(formatJsonl(event)) + '\\n');\n      }\n    }\n\n    const result = await run.result;\n    exitCode = result.exitCode;\n\n    if (args.output === 'json') {\n      process.stdout.write(renderJsonResult(result));\n    } else if (args.output === 'jsonl') {\n      process.stdout.write(JSON.stringify({ type: 'result', ...result }) + '\\n');\n    }\n\n    if (result.status === 'timeout') {\n      process.stderr.write(`\\nTimeout elapsed. Aborted.\\n`);\n    } else if (result.error && args.output === 'human') {\n      process.stderr.write(`Error: ${result.error.message}\\n`);\n    }\n  } catch (err) {\n    process.stderr.write(`Error: ${(err as Error).message ?? err}\\n`);\n    exitCode = 1;\n  } finally {\n    // --- Teardown (always runs, even on a thrown error) ---\n    releaseAllThreadLocks();\n    if (boot) {\n      // Stop plugin-contributed signal providers (and the plugin reload listener)\n      // before quiescing workers: a provider that keeps polling past this point\n      // could dispatch into a controller that is shutting down. Release thread\n      // claims first so a restarted process need not wait out this teardown.\n      try {\n        boot.releaseThreadClaims();\n      } catch {\n        // Best-effort — the process is exiting.\n      }\n      try {\n        boot.stopPluginSignalProviders();\n      } catch {\n        // Best-effort — the process is exiting.\n      }\n      const { controller, mcpManager } = boot;\n      // Release notification dispatch leases before the pubsub that holds them\n      // closes. Headless has no shutdown deadline, so don't let a stalled\n      // in-flight dispatch hold up exit.\n      await Promise.race([\n        boot.stopNotificationDispatch?.().catch(() => {}),\n        new Promise<void>(resolve => setTimeout(resolve, STOP_NOTIFICATION_DISPATCH_TIMEOUT_MS).unref()),\n      ]);\n      await Promise.allSettled([\n        mcpManager?.disconnect(),\n        controller.getMastra()?.stopWorkers(),\n        controller.stopIntervals(),\n      ]);\n      // The signals pubsub is Mastra's event bus, so close it after the workers\n      // stop. Call close() on the object; a detached method loses `this` and\n      // rejects silently, leaving socket files behind.\n      const signalsPubSub = boot.signalsPubSub as { close?: () => Promise<void> | void } | undefined;\n      await Promise.allSettled([signalsPubSub?.close?.()]);\n    }\n    await stopProcessMemoryDiagnosticsWithTimeout(processMemoryDiagnostics, warning => {\n      process.stderr.write(`Warning: ${warning}\\n`);\n    });\n  }\n\n  process.exit(exitCode);\n}\n"],"mappings":"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"}

package/dist/headless/flags.d.ts

@@ -0,0 +1,33 @@
+export declare const VALID_OUTPUTS: readonly ["human", "json", "jsonl"];
+/**
+ * One CLI flag. `key` is the long name (e.g. `output`); `field` is the
+ * {@link import('./cli.js').HeadlessArgs} property it populates. `coerce`
+ * converts the raw string and validates it. Boolean flags omit `coerce` and set
+ * `field` to `true` when present.
+ */
+export interface FlagSpec {
+    /** Long flag name without the leading `--`. */
+    key: string;
+    /** Single-character alias (without the leading `-`), if any. */
+    short?: string;
+    /** Whether the flag takes a value (`string`) or is a switch (`boolean`). */
+    type: 'string' | 'boolean';
+    /** Target field on `HeadlessArgs`. Omit for flags handled out-of-band (e.g. help). */
+    field?: string;
+    /** Coerce/validate a string value. Required for `type: 'string'` flags that map to a field. */
+    coerce?: (raw: string) => unknown;
+    /** `<...>` value placeholder shown in usage, e.g. `<text>`. */
+    placeholder?: string;
+    /** One-line (or multi-line) help description shown in usage. */
+    help: string | string[];
+}
+export declare const FLAGS: FlagSpec[];
+/** `parseArgs` option config derived from {@link FLAGS}. */
+export declare function buildParseArgsOptions(): Record<string, {
+    type: "string" | "boolean";
+    short?: string;
+    default?: boolean;
+}>;
+/** Render the aligned `--flag  description` block of the usage text from {@link FLAGS}. */
+export declare function renderFlagUsage(): string;
+//# sourceMappingURL=flags.d.ts.map

package/dist/headless/flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../../src/headless/flags.ts"],"names":[],"mappings":"AAgBA,eAAO,MAAM,aAAa,qCAAsC,CAAC;AA6BjE;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC3B,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+FAA+F;IAC/F,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAClC,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACzB;AAED,eAAO,MAAM,KAAK,EAAE,QAAQ,EA8I3B,CAAC;AAEF,4DAA4D;AAC5D,wBAAgB,qBAAqB;UACG,QAAQ,GAAG,SAAS;YAAU,MAAM;cAAY,OAAO;GAM9F;AAED,2FAA2F;AAC3F,wBAAgB,eAAe,IAAI,MAAM,CAmBxC"}

package/dist/headless/flags.js

@@ -0,0 +1,203 @@
+import { VALID_MODES, VALID_PERMISSION_MODES, VALID_THINKING_LEVELS } from "./types.js";
+//#region src/headless/flags.ts
+const VALID_OUTPUTS = [
+	"human",
+	"json",
+	"jsonl"
+];
+/** Reusable validators. Each throws a descriptive Error or returns the typed value. */
+const validate = {
+	/** Restrict to a fixed set of string literals. */
+	enum(flag, allowed) {
+		return (raw) => {
+			if (!allowed.includes(raw)) throw new Error(`${flag} must be one of: ${allowed.join(", ")}`);
+			return raw;
+		};
+	},
+	/** Require a positive (>0) integer. */
+	positiveInt(flag) {
+		return (raw) => {
+			const parsed = Number(raw);
+			if (!Number.isInteger(parsed) || parsed <= 0) throw new Error(`${flag} must be a positive integer`);
+			return parsed;
+		};
+	},
+	/** Pass a string through unchanged. */
+	string(raw) {
+		return raw;
+	}
+};
+const FLAGS = [
+	{
+		key: "prompt",
+		short: "p",
+		type: "string",
+		field: "prompt",
+		coerce: validate.string,
+		placeholder: "<text>",
+		help: "The task to execute (required, or pipe via stdin)"
+	},
+	{
+		key: "continue",
+		short: "c",
+		type: "boolean",
+		field: "continue_",
+		help: "Resume the most recent thread instead of creating a new one"
+	},
+	{
+		key: "thread",
+		short: "t",
+		type: "string",
+		field: "thread",
+		coerce: validate.string,
+		placeholder: "<id>",
+		help: "Resume a specific thread by ID"
+	},
+	{
+		key: "title",
+		type: "string",
+		field: "title",
+		coerce: validate.string,
+		placeholder: "<title>",
+		help: "Set or rename the thread title"
+	},
+	{
+		key: "clone-thread",
+		type: "boolean",
+		field: "cloneThread",
+		help: "Clone the current thread before running (work on a copy)"
+	},
+	{
+		key: "resource-id",
+		type: "string",
+		field: "resourceId",
+		coerce: validate.string,
+		placeholder: "<id>",
+		help: "Set the resource ID for thread scoping"
+	},
+	{
+		key: "timeout",
+		type: "string",
+		field: "timeout",
+		coerce: validate.positiveInt("--timeout"),
+		placeholder: "<seconds>",
+		help: "Exit with code 2 if not complete within timeout"
+	},
+	{
+		key: "max-turns",
+		type: "string",
+		field: "maxTurns",
+		coerce: validate.positiveInt("--max-turns"),
+		placeholder: "<n>",
+		help: "Abort after N agentic turns (exit code 1)"
+	},
+	{
+		key: "permission-mode",
+		type: "string",
+		field: "permissionMode",
+		coerce: validate.enum("--permission-mode", VALID_PERMISSION_MODES),
+		placeholder: "<mode>",
+		help: [
+			"How tool approvals/suspensions resolve:",
+			"  auto   approve everything (default)",
+			"  deny   refuse approvals, abort on suspension"
+		]
+	},
+	{
+		key: "output",
+		short: "o",
+		type: "string",
+		field: "output",
+		coerce: validate.enum("--output", VALID_OUTPUTS),
+		placeholder: "<mode>",
+		help: [
+			"Output mode: \"human\" (default), \"json\", or \"jsonl\"",
+			"  human  streaming text to stdout, activity to stderr",
+			"  json   single final JSON object (text, usage, tools)",
+			"  jsonl  newline-delimited JSON event stream"
+		]
+	},
+	{
+		key: "model",
+		short: "m",
+		type: "string",
+		field: "model",
+		coerce: validate.string,
+		placeholder: "<id>",
+		help: "Model override (e.g., a provider/model id); wins over --pack for the active mode"
+	},
+	{
+		key: "pack",
+		type: "string",
+		field: "pack",
+		coerce: validate.string,
+		placeholder: "<id>",
+		help: [
+			"Model pack to activate (like /models → Activate): a builtin pack id",
+			"(anthropic, openai, github-copilot) or a saved custom pack, by",
+			"\"custom:<name>\" or its bare name. Sets the pack for every mode and",
+			"becomes the global default pack. --model overrides it for the active mode."
+		]
+	},
+	{
+		key: "mode",
+		type: "string",
+		field: "mode",
+		coerce: validate.enum("--mode", VALID_MODES),
+		placeholder: "{build|plan|fast}",
+		help: "Execution mode — defaults to \"build\" if omitted"
+	},
+	{
+		key: "thinking-level",
+		type: "string",
+		field: "thinkingLevel",
+		coerce: validate.enum("--thinking-level", VALID_THINKING_LEVELS),
+		placeholder: "<level>",
+		help: "Thinking level: off, low, medium, high, xhigh, max"
+	},
+	{
+		key: "settings",
+		type: "string",
+		field: "settings",
+		coerce: validate.string,
+		placeholder: "<path>",
+		help: "Path to settings.json file (default: global settings)"
+	},
+	{
+		key: "help",
+		short: "h",
+		type: "boolean",
+		help: "Show this help and exit"
+	}
+];
+/** `parseArgs` option config derived from {@link FLAGS}. */
+function buildParseArgsOptions() {
+	const options = {};
+	for (const flag of FLAGS) {
+		options[flag.key] = flag.type === "boolean" ? {
+			type: "boolean",
+			default: false
+		} : { type: "string" };
+		if (flag.short) options[flag.key].short = flag.short;
+	}
+	return options;
+}
+/** Render the aligned `--flag  description` block of the usage text from {@link FLAGS}. */
+function renderFlagUsage() {
+	const left = (flag) => {
+		return `  ${`--${flag.key}`}${flag.short ? `, -${flag.short}` : ""}${flag.placeholder ? ` ${flag.placeholder}` : ""}`;
+	};
+	const rows = FLAGS.map((flag) => ({
+		flag,
+		label: left(flag)
+	}));
+	const width = Math.max(...rows.map((r) => r.label.length)) + 2;
+	return rows.map(({ flag, label }) => {
+		const lines = Array.isArray(flag.help) ? flag.help : [flag.help];
+		return [`${label.padEnd(width)}${lines[0]}`, ...lines.slice(1).map((line) => `${" ".repeat(width)}${line}`)].join("\n");
+	}).join("\n");
+}
+//#endregion
+export { FLAGS, VALID_OUTPUTS, buildParseArgsOptions, renderFlagUsage };
+
+//# sourceMappingURL=flags.js.map

package/dist/headless/flags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags.js","names":[],"sources":["../../src/headless/flags.ts"],"sourcesContent":["/**\n * Declarative flag specification for the headless CLI.\n *\n * A single table is the source of truth for three things that previously drifted\n * apart in `cli.ts`:\n *   1. the `node:util` `parseArgs` option config,\n *   2. per-flag value coercion + validation, and\n *   3. the `--help` usage text.\n *\n * Adding a flag means adding one row here; parsing, validation, and the usage\n * listing all follow automatically.\n */\nimport type { OutputMode } from './cli.js';\nimport type { PermissionMode, RunMode, ThinkingLevel } from './types.js';\nimport { VALID_MODES, VALID_PERMISSION_MODES, VALID_THINKING_LEVELS } from './types.js';\n\nexport const VALID_OUTPUTS = ['human', 'json', 'jsonl'] as const;\n\n/** Reusable validators. Each throws a descriptive Error or returns the typed value. */\nconst validate = {\n  /** Restrict to a fixed set of string literals. */\n  enum<T extends string>(flag: string, allowed: readonly T[]) {\n    return (raw: string): T => {\n      if (!(allowed as readonly string[]).includes(raw)) {\n        throw new Error(`${flag} must be one of: ${allowed.join(', ')}`);\n      }\n      return raw as T;\n    };\n  },\n  /** Require a positive (>0) integer. */\n  positiveInt(flag: string) {\n    return (raw: string): number => {\n      const parsed = Number(raw);\n      if (!Number.isInteger(parsed) || parsed <= 0) {\n        throw new Error(`${flag} must be a positive integer`);\n      }\n      return parsed;\n    };\n  },\n  /** Pass a string through unchanged. */\n  string(raw: string): string {\n    return raw;\n  },\n};\n\n/**\n * One CLI flag. `key` is the long name (e.g. `output`); `field` is the\n * {@link import('./cli.js').HeadlessArgs} property it populates. `coerce`\n * converts the raw string and validates it. Boolean flags omit `coerce` and set\n * `field` to `true` when present.\n */\nexport interface FlagSpec {\n  /** Long flag name without the leading `--`. */\n  key: string;\n  /** Single-character alias (without the leading `-`), if any. */\n  short?: string;\n  /** Whether the flag takes a value (`string`) or is a switch (`boolean`). */\n  type: 'string' | 'boolean';\n  /** Target field on `HeadlessArgs`. Omit for flags handled out-of-band (e.g. help). */\n  field?: string;\n  /** Coerce/validate a string value. Required for `type: 'string'` flags that map to a field. */\n  coerce?: (raw: string) => unknown;\n  /** `<...>` value placeholder shown in usage, e.g. `<text>`. */\n  placeholder?: string;\n  /** One-line (or multi-line) help description shown in usage. */\n  help: string | string[];\n}\n\nexport const FLAGS: FlagSpec[] = [\n  {\n    key: 'prompt',\n    short: 'p',\n    type: 'string',\n    field: 'prompt',\n    coerce: validate.string,\n    placeholder: '<text>',\n    help: 'The task to execute (required, or pipe via stdin)',\n  },\n  {\n    key: 'continue',\n    short: 'c',\n    type: 'boolean',\n    field: 'continue_',\n    help: 'Resume the most recent thread instead of creating a new one',\n  },\n  {\n    key: 'thread',\n    short: 't',\n    type: 'string',\n    field: 'thread',\n    coerce: validate.string,\n    placeholder: '<id>',\n    help: 'Resume a specific thread by ID',\n  },\n  {\n    key: 'title',\n    type: 'string',\n    field: 'title',\n    coerce: validate.string,\n    placeholder: '<title>',\n    help: 'Set or rename the thread title',\n  },\n  {\n    key: 'clone-thread',\n    type: 'boolean',\n    field: 'cloneThread',\n    help: 'Clone the current thread before running (work on a copy)',\n  },\n  {\n    key: 'resource-id',\n    type: 'string',\n    field: 'resourceId',\n    coerce: validate.string,\n    placeholder: '<id>',\n    help: 'Set the resource ID for thread scoping',\n  },\n  {\n    key: 'timeout',\n    type: 'string',\n    field: 'timeout',\n    coerce: validate.positiveInt('--timeout'),\n    placeholder: '<seconds>',\n    help: 'Exit with code 2 if not complete within timeout',\n  },\n  {\n    key: 'max-turns',\n    type: 'string',\n    field: 'maxTurns',\n    coerce: validate.positiveInt('--max-turns'),\n    placeholder: '<n>',\n    help: 'Abort after N agentic turns (exit code 1)',\n  },\n  {\n    key: 'permission-mode',\n    type: 'string',\n    field: 'permissionMode',\n    coerce: validate.enum<PermissionMode>('--permission-mode', VALID_PERMISSION_MODES),\n    placeholder: '<mode>',\n    help: [\n      'How tool approvals/suspensions resolve:',\n      '  auto   approve everything (default)',\n      '  deny   refuse approvals, abort on suspension',\n    ],\n  },\n  {\n    key: 'output',\n    short: 'o',\n    type: 'string',\n    field: 'output',\n    coerce: validate.enum<OutputMode>('--output', VALID_OUTPUTS),\n    placeholder: '<mode>',\n    help: [\n      'Output mode: \"human\" (default), \"json\", or \"jsonl\"',\n      '  human  streaming text to stdout, activity to stderr',\n      '  json   single final JSON object (text, usage, tools)',\n      '  jsonl  newline-delimited JSON event stream',\n    ],\n  },\n  {\n    key: 'model',\n    short: 'm',\n    type: 'string',\n    field: 'model',\n    coerce: validate.string,\n    placeholder: '<id>',\n    help: 'Model override (e.g., a provider/model id); wins over --pack for the active mode',\n  },\n  {\n    key: 'pack',\n    type: 'string',\n    field: 'pack',\n    coerce: validate.string,\n    placeholder: '<id>',\n    help: [\n      'Model pack to activate (like /models → Activate): a builtin pack id',\n      '(anthropic, openai, github-copilot) or a saved custom pack, by',\n      '\"custom:<name>\" or its bare name. Sets the pack for every mode and',\n      'becomes the global default pack. --model overrides it for the active mode.',\n    ],\n  },\n  {\n    key: 'mode',\n    type: 'string',\n    field: 'mode',\n    coerce: validate.enum<RunMode>('--mode', VALID_MODES),\n    placeholder: '{build|plan|fast}',\n    help: 'Execution mode — defaults to \"build\" if omitted',\n  },\n  {\n    key: 'thinking-level',\n    type: 'string',\n    field: 'thinkingLevel',\n    coerce: validate.enum<ThinkingLevel>('--thinking-level', VALID_THINKING_LEVELS),\n    placeholder: '<level>',\n    help: 'Thinking level: off, low, medium, high, xhigh, max',\n  },\n  {\n    key: 'settings',\n    type: 'string',\n    field: 'settings',\n    coerce: validate.string,\n    placeholder: '<path>',\n    help: 'Path to settings.json file (default: global settings)',\n  },\n  {\n    key: 'help',\n    short: 'h',\n    type: 'boolean',\n    help: 'Show this help and exit',\n  },\n];\n\n/** `parseArgs` option config derived from {@link FLAGS}. */\nexport function buildParseArgsOptions() {\n  const options: Record<string, { type: 'string' | 'boolean'; short?: string; default?: boolean }> = {};\n  for (const flag of FLAGS) {\n    options[flag.key] = flag.type === 'boolean' ? { type: 'boolean', default: false } : { type: 'string' };\n    if (flag.short) options[flag.key]!.short = flag.short;\n  }\n  return options;\n}\n\n/** Render the aligned `--flag  description` block of the usage text from {@link FLAGS}. */\nexport function renderFlagUsage(): string {\n  const left = (flag: FlagSpec): string => {\n    const long = `--${flag.key}`;\n    const short = flag.short ? `, -${flag.short}` : '';\n    const value = flag.placeholder ? ` ${flag.placeholder}` : '';\n    return `  ${long}${short}${value}`;\n  };\n\n  const rows = FLAGS.map(flag => ({ flag, label: left(flag) }));\n  const width = Math.max(...rows.map(r => r.label.length)) + 2;\n\n  return rows\n    .map(({ flag, label }) => {\n      const lines = Array.isArray(flag.help) ? flag.help : [flag.help];\n      const first = `${label.padEnd(width)}${lines[0]}`;\n      const rest = lines.slice(1).map(line => `${' '.repeat(width)}${line}`);\n      return [first, ...rest].join('\\n');\n    })\n    .join('\\n');\n}\n"],"mappings":";;AAgBA,MAAa,gBAAgB;CAAC;CAAS;CAAQ;AAAO;;AAGtD,MAAM,WAAW;;CAEf,KAAuB,MAAc,SAAuB;EAC1D,QAAQ,QAAmB;GACzB,IAAI,CAAE,QAA8B,SAAS,GAAG,GAC9C,MAAM,IAAI,MAAM,GAAG,KAAK,mBAAmB,QAAQ,KAAK,IAAI,GAAG;GAEjE,OAAO;EACT;CACF;;CAEA,YAAY,MAAc;EACxB,QAAQ,QAAwB;GAC9B,MAAM,SAAS,OAAO,GAAG;GACzB,IAAI,CAAC,OAAO,UAAU,MAAM,KAAK,UAAU,GACzC,MAAM,IAAI,MAAM,GAAG,KAAK,4BAA4B;GAEtD,OAAO;EACT;CACF;;CAEA,OAAO,KAAqB;EAC1B,OAAO;CACT;AACF;AAyBA,MAAa,QAAoB;CAC/B;EACE,KAAK;EACL,OAAO;EACP,MAAM;EACN,OAAO;EACP,QAAQ,SAAS;EACjB,aAAa;EACb,MAAM;CACR;CACA;EACE,KAAK;EACL,OAAO;EACP,MAAM;EACN,OAAO;EACP,MAAM;CACR;CACA;EACE,KAAK;EACL,OAAO;EACP,MAAM;EACN,OAAO;EACP,QAAQ,SAAS;EACjB,aAAa;EACb,MAAM;CACR;CACA;EACE,KAAK;EACL,MAAM;EACN,OAAO;EACP,QAAQ,SAAS;EACjB,aAAa;EACb,MAAM;CACR;CACA;EACE,KAAK;EACL,MAAM;EACN,OAAO;EACP,MAAM;CACR;CACA;EACE,KAAK;EACL,MAAM;EACN,OAAO;EACP,QAAQ,SAAS;EACjB,aAAa;EACb,MAAM;CACR;CACA;EACE,KAAK;EACL,MAAM;EACN,OAAO;EACP,QAAQ,SAAS,YAAY,WAAW;EACxC,aAAa;EACb,MAAM;CACR;CACA;EACE,KAAK;EACL,MAAM;EACN,OAAO;EACP,QAAQ,SAAS,YAAY,aAAa;EAC1C,aAAa;EACb,MAAM;CACR;CACA;EACE,KAAK;EACL,MAAM;EACN,OAAO;EACP,QAAQ,SAAS,KAAqB,qBAAqB,sBAAsB;EACjF,aAAa;EACb,MAAM;GACJ;GACA;GACA;EACF;CACF;CACA;EACE,KAAK;EACL,OAAO;EACP,MAAM;EACN,OAAO;EACP,QAAQ,SAAS,KAAiB,YAAY,aAAa;EAC3D,aAAa;EACb,MAAM;GACJ;GACA;GACA;GACA;EACF;CACF;CACA;EACE,KAAK;EACL,OAAO;EACP,MAAM;EACN,OAAO;EACP,QAAQ,SAAS;EACjB,aAAa;EACb,MAAM;CACR;CACA;EACE,KAAK;EACL,MAAM;EACN,OAAO;EACP,QAAQ,SAAS;EACjB,aAAa;EACb,MAAM;GACJ;GACA;GACA;GACA;EACF;CACF;CACA;EACE,KAAK;EACL,MAAM;EACN,OAAO;EACP,QAAQ,SAAS,KAAc,UAAU,WAAW;EACpD,aAAa;EACb,MAAM;CACR;CACA;EACE,KAAK;EACL,MAAM;EACN,OAAO;EACP,QAAQ,SAAS,KAAoB,oBAAoB,qBAAqB;EAC9E,aAAa;EACb,MAAM;CACR;CACA;EACE,KAAK;EACL,MAAM;EACN,OAAO;EACP,QAAQ,SAAS;EACjB,aAAa;EACb,MAAM;CACR;CACA;EACE,KAAK;EACL,OAAO;EACP,MAAM;EACN,MAAM;CACR;AACF;;AAGA,SAAgB,wBAAwB;CACtC,MAAM,UAA6F,CAAC;CACpG,KAAK,MAAM,QAAQ,OAAO;EACxB,QAAQ,KAAK,OAAO,KAAK,SAAS,YAAY;GAAE,MAAM;GAAW,SAAS;EAAM,IAAI,EAAE,MAAM,SAAS;EACrG,IAAI,KAAK,OAAO,QAAQ,KAAK,IAAI,CAAE,QAAQ,KAAK;CAClD;CACA,OAAO;AACT;;AAGA,SAAgB,kBAA0B;CACxC,MAAM,QAAQ,SAA2B;EAIvC,OAAO,KAAK,KAHM,KAAK,QACT,KAAK,QAAQ,MAAM,KAAK,UAAU,KAClC,KAAK,cAAc,IAAI,KAAK,gBAAgB;CAE5D;CAEA,MAAM,OAAO,MAAM,KAAI,UAAS;EAAE;EAAM,OAAO,KAAK,IAAI;CAAE,EAAE;CAC5D,MAAM,QAAQ,KAAK,IAAI,GAAG,KAAK,KAAI,MAAK,EAAE,MAAM,MAAM,CAAC,IAAI;CAE3D,OAAO,KACJ,KAAK,EAAE,MAAM,YAAY;EACxB,MAAM,QAAQ,MAAM,QAAQ,KAAK,IAAI,IAAI,KAAK,OAAO,CAAC,KAAK,IAAI;EAG/D,OAAO,CAAC,GAFS,MAAM,OAAO,KAAK,IAAI,MAAM,MAE9B,GADF,MAAM,MAAM,CAAC,CAAC,CAAC,KAAI,SAAQ,GAAG,IAAI,OAAO,KAAK,IAAI,MAC1C,CAAC,CAAC,CAAC,KAAK,IAAI;CACnC,CAAC,CAAC,CACD,KAAK,IAAI;AACd"}

package/dist/headless/format.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Output formatters for headless runs. All functions here are pure — they take
+ * an event (or a final result) and return strings / plain objects. They never
+ * touch `process.*`; the CLI adapter owns the sinks.
+ */
+import type { AgentControllerEvent } from '@mastra/core/agent-controller';
+import type { RunMCResult } from './types.js';
+/** Truncate a string to `max` characters, appending "..." if truncated. */
+export declare function truncate(s: string, max: number): string;
+/** Mutable per-stream cursor used by {@link formatHuman} to stream assistant text. */
+export interface HumanFormatState {
+    activeAssistantMessageId?: string;
+    lastTextLength: number;
+}
+export declare function createHumanFormatState(): HumanFormatState;
+/** A chunk of formatted output destined for stdout and/or stderr. */
+export interface FormattedOutput {
+    stdout?: string;
+    stderr?: string;
+}
+/**
+ * Human-readable streaming formatter (the historical default). Assistant text
+ * streams to stdout; tool/subagent/shell/error activity goes to stderr. The
+ * `state` cursor is mutated so repeated `message_update` events only emit the
+ * newly-appended text.
+ */
+export declare function formatHuman(event: AgentControllerEvent, state: HumanFormatState): FormattedOutput;
+/**
+ * JSONL (stream-json) formatter — returns a plain object to be `JSON.stringify`'d
+ * as one line per event by the sink. `Error` instances are normalized so their
+ * `name`/`message`/`stack` survive serialization (`JSON.stringify` turns a raw
+ * `Error` into `{}`).
+ */
+export declare function formatJsonl(event: AgentControllerEvent): Record<string, unknown>;
+/** Render the final result for `--output text`: assistant text, newline-terminated. */
+export declare function renderTextResult(result: RunMCResult): string;
+/** Render the final result for `--output json`: one JSON object. */
+export declare function renderJsonResult(result: RunMCResult): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/headless/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/headless/format.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAE1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,sFAAsF;AACtF,MAAM,WAAW,gBAAgB;IAC/B,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,sBAAsB,IAAI,gBAAgB,CAEzD;AAED,qEAAqE;AACrE,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,oBAAoB,EAAE,KAAK,EAAE,gBAAgB,GAAG,eAAe,CAuCjG;AAOD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMhF;AAED,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAE5D;AAED,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAc5D"}