@mastra/code-sdk 0.0.0-livekit-beta-v3-20260709031728

package/dist/headless/cli.js

@@ -0,0 +1,196 @@
+import { existsSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { createMastraCode } from "../index.js";
+import { setupDebugLogging } from "../utils/debug-log.js";
+import { releaseAllThreadLocks } from "../utils/thread-lock.js";
+import { buildParseArgsOptions, FLAGS, renderFlagUsage } from "./flags.js";
+import { createHumanFormatState, formatHuman, formatJsonl, renderJsonResult } from "./format.js";
+import { permissionModeToPolicy } from "./policy.js";
+import { runMC } from "./run-mc.js";
+const parseArgsOptions = buildParseArgsOptions();
+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;
+  }
+}
+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 -
+`);
+}
+async function runMCCli(predrainedInput) {
+  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}
+`);
+    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}
+`);
+    process.exit(1);
+  }
+  const boot = await createMastraCode({ settingsPath: args.settings });
+  const { controller, session, mcpManager, effectiveDefaults } = boot;
+  if (mcpManager?.hasServers()) {
+    try {
+      await mcpManager.initInBackground();
+    } catch (err) {
+      process.stderr.write(`Warning: MCP server initialization failed: ${err.message ?? err}
+`);
+    }
+  }
+  setupDebugLogging();
+  let exitCode = 1;
+  try {
+    const humanState = createHumanFormatState();
+    const run = runMC({
+      controller,
+      session,
+      prompt,
+      model: args.model,
+      mode: args.mode,
+      modeDefaults: effectiveDefaults,
+      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(`
+Timeout elapsed. Aborted.
+`);
+    } else if (result.error && args.output === "human") {
+      process.stderr.write(`Error: ${result.error.message}
+`);
+    }
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message ?? err}
+`);
+    exitCode = 1;
+  } finally {
+    releaseAllThreadLocks();
+    const closeSignalsPubSub = boot.signalsPubSub?.close;
+    await Promise.allSettled([
+      mcpManager?.disconnect(),
+      controller.getMastra()?.stopWorkers(),
+      controller?.stopIntervals(),
+      closeSignalsPubSub?.()
+    ]);
+  }
+  process.exit(exitCode);
+}
+export {
+  hasHeadlessFlag,
+  parseHeadlessArgs,
+  printHeadlessUsage,
+  runMCCli
+};
+//# sourceMappingURL=cli.js.map

package/dist/headless/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"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 { 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  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();\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(predrainedInput?: string | null): 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  const boot = await createMastraCode({ settingsPath: args.settings });\n  const { controller, session, mcpManager, effectiveDefaults } = boot;\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  // 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    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      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    const closeSignalsPubSub = (boot.signalsPubSub as { close?: () => Promise<void> | void } | undefined)?.close;\n    await Promise.allSettled([\n      mcpManager?.disconnect(),\n      controller.getMastra()?.stopWorkers(),\n      controller?.stopIntervals(),\n      closeSignalsPubSub?.(),\n    ]);\n  }\n\n  process.exit(exitCode);\n}\n"],"mappings":"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","names":[]}

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,EAiI3B,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,188 @@
+import { VALID_MODES, VALID_PERMISSION_MODES, VALID_THINKING_LEVELS } from "./types.js";
+const VALID_OUTPUTS = ["human", "json", "jsonl"];
+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)"
+  },
+  {
+    key: "mode",
+    type: "string",
+    field: "mode",
+    coerce: validate.enum("--mode", VALID_MODES),
+    placeholder: "{build|plan|fast}",
+    help: 'Execution mode \u2014 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"
+  },
+  {
+    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"
+  }
+];
+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;
+}
+function renderFlagUsage() {
+  const left = (flag) => {
+    const long = `--${flag.key}`;
+    const short = flag.short ? `, -${flag.short}` : "";
+    const value = flag.placeholder ? ` ${flag.placeholder}` : "";
+    return `  ${long}${short}${value}`;
+  };
+  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];
+    const first = `${label.padEnd(width)}${lines[0]}`;
+    const rest = lines.slice(1).map((line) => `${" ".repeat(width)}${line}`);
+    return [first, ...rest].join("\n");
+  }).join("\n");
+}
+export {
+  FLAGS,
+  VALID_OUTPUTS,
+  buildParseArgsOptions,
+  renderFlagUsage
+};
+//# sourceMappingURL=flags.js.map

package/dist/headless/flags.js.map

@@ -0,0 +1 @@
+{"version":3,"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)',\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',\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":"AAcA,SAAS,aAAa,wBAAwB,6BAA6B;AAEpE,MAAM,gBAAgB,CAAC,SAAS,QAAQ,OAAO;AAGtD,MAAM,WAAW;AAAA;AAAA,EAEf,KAAuB,MAAc,SAAuB;AAC1D,WAAO,CAAC,QAAmB;AACzB,UAAI,CAAE,QAA8B,SAAS,GAAG,GAAG;AACjD,cAAM,IAAI,MAAM,GAAG,IAAI,oBAAoB,QAAQ,KAAK,IAAI,CAAC,EAAE;AAAA,MACjE;AACA,aAAO;AAAA,IACT;AAAA,EACF;AAAA;AAAA,EAEA,YAAY,MAAc;AACxB,WAAO,CAAC,QAAwB;AAC9B,YAAM,SAAS,OAAO,GAAG;AACzB,UAAI,CAAC,OAAO,UAAU,MAAM,KAAK,UAAU,GAAG;AAC5C,cAAM,IAAI,MAAM,GAAG,IAAI,6BAA6B;AAAA,MACtD;AACA,aAAO;AAAA,IACT;AAAA,EACF;AAAA;AAAA,EAEA,OAAO,KAAqB;AAC1B,WAAO;AAAA,EACT;AACF;AAyBO,MAAM,QAAoB;AAAA,EAC/B;AAAA,IACE,KAAK;AAAA,IACL,OAAO;AAAA,IACP,MAAM;AAAA,IACN,OAAO;AAAA,IACP,QAAQ,SAAS;AAAA,IACjB,aAAa;AAAA,IACb,MAAM;AAAA,EACR;AAAA,EACA;AAAA,IACE,KAAK;AAAA,IACL,OAAO;AAAA,IACP,MAAM;AAAA,IACN,OAAO;AAAA,IACP,MAAM;AAAA,EACR;AAAA,EACA;AAAA,IACE,KAAK;AAAA,IACL,OAAO;AAAA,IACP,MAAM;AAAA,IACN,OAAO;AAAA,IACP,QAAQ,SAAS;AAAA,IACjB,aAAa;AAAA,IACb,MAAM;AAAA,EACR;AAAA,EACA;AAAA,IACE,KAAK;AAAA,IACL,MAAM;AAAA,IACN,OAAO;AAAA,IACP,QAAQ,SAAS;AAAA,IACjB,aAAa;AAAA,IACb,MAAM;AAAA,EACR;AAAA,EACA;AAAA,IACE,KAAK;AAAA,IACL,MAAM;AAAA,IACN,OAAO;AAAA,IACP,MAAM;AAAA,EACR;AAAA,EACA;AAAA,IACE,KAAK;AAAA,IACL,MAAM;AAAA,IACN,OAAO;AAAA,IACP,QAAQ,SAAS;AAAA,IACjB,aAAa;AAAA,IACb,MAAM;AAAA,EACR;AAAA,EACA;AAAA,IACE,KAAK;AAAA,IACL,MAAM;AAAA,IACN,OAAO;AAAA,IACP,QAAQ,SAAS,YAAY,WAAW;AAAA,IACxC,aAAa;AAAA,IACb,MAAM;AAAA,EACR;AAAA,EACA;AAAA,IACE,KAAK;AAAA,IACL,MAAM;AAAA,IACN,OAAO;AAAA,IACP,QAAQ,SAAS,YAAY,aAAa;AAAA,IAC1C,aAAa;AAAA,IACb,MAAM;AAAA,EACR;AAAA,EACA;AAAA,IACE,KAAK;AAAA,IACL,MAAM;AAAA,IACN,OAAO;AAAA,IACP,QAAQ,SAAS,KAAqB,qBAAqB,sBAAsB;AAAA,IACjF,aAAa;AAAA,IACb,MAAM;AAAA,MACJ;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAAA,EACA;AAAA,IACE,KAAK;AAAA,IACL,OAAO;AAAA,IACP,MAAM;AAAA,IACN,OAAO;AAAA,IACP,QAAQ,SAAS,KAAiB,YAAY,aAAa;AAAA,IAC3D,aAAa;AAAA,IACb,MAAM;AAAA,MACJ;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAAA,EACA;AAAA,IACE,KAAK;AAAA,IACL,OAAO;AAAA,IACP,MAAM;AAAA,IACN,OAAO;AAAA,IACP,QAAQ,SAAS;AAAA,IACjB,aAAa;AAAA,IACb,MAAM;AAAA,EACR;AAAA,EACA;AAAA,IACE,KAAK;AAAA,IACL,MAAM;AAAA,IACN,OAAO;AAAA,IACP,QAAQ,SAAS,KAAc,UAAU,WAAW;AAAA,IACpD,aAAa;AAAA,IACb,MAAM;AAAA,EACR;AAAA,EACA;AAAA,IACE,KAAK;AAAA,IACL,MAAM;AAAA,IACN,OAAO;AAAA,IACP,QAAQ,SAAS,KAAoB,oBAAoB,qBAAqB;AAAA,IAC9E,aAAa;AAAA,IACb,MAAM;AAAA,EACR;AAAA,EACA;AAAA,IACE,KAAK;AAAA,IACL,MAAM;AAAA,IACN,OAAO;AAAA,IACP,QAAQ,SAAS;AAAA,IACjB,aAAa;AAAA,IACb,MAAM;AAAA,EACR;AAAA,EACA;AAAA,IACE,KAAK;AAAA,IACL,OAAO;AAAA,IACP,MAAM;AAAA,IACN,MAAM;AAAA,EACR;AACF;AAGO,SAAS,wBAAwB;AACtC,QAAM,UAA6F,CAAC;AACpG,aAAW,QAAQ,OAAO;AACxB,YAAQ,KAAK,GAAG,IAAI,KAAK,SAAS,YAAY,EAAE,MAAM,WAAW,SAAS,MAAM,IAAI,EAAE,MAAM,SAAS;AACrG,QAAI,KAAK,MAAO,SAAQ,KAAK,GAAG,EAAG,QAAQ,KAAK;AAAA,EAClD;AACA,SAAO;AACT;AAGO,SAAS,kBAA0B;AACxC,QAAM,OAAO,CAAC,SAA2B;AACvC,UAAM,OAAO,KAAK,KAAK,GAAG;AAC1B,UAAM,QAAQ,KAAK,QAAQ,MAAM,KAAK,KAAK,KAAK;AAChD,UAAM,QAAQ,KAAK,cAAc,IAAI,KAAK,WAAW,KAAK;AAC1D,WAAO,KAAK,IAAI,GAAG,KAAK,GAAG,KAAK;AAAA,EAClC;AAEA,QAAM,OAAO,MAAM,IAAI,WAAS,EAAE,MAAM,OAAO,KAAK,IAAI,EAAE,EAAE;AAC5D,QAAM,QAAQ,KAAK,IAAI,GAAG,KAAK,IAAI,OAAK,EAAE,MAAM,MAAM,CAAC,IAAI;AAE3D,SAAO,KACJ,IAAI,CAAC,EAAE,MAAM,MAAM,MAAM;AACxB,UAAM,QAAQ,MAAM,QAAQ,KAAK,IAAI,IAAI,KAAK,OAAO,CAAC,KAAK,IAAI;AAC/D,UAAM,QAAQ,GAAG,MAAM,OAAO,KAAK,CAAC,GAAG,MAAM,CAAC,CAAC;AAC/C,UAAM,OAAO,MAAM,MAAM,CAAC,EAAE,IAAI,UAAQ,GAAG,IAAI,OAAO,KAAK,CAAC,GAAG,IAAI,EAAE;AACrE,WAAO,CAAC,OAAO,GAAG,IAAI,EAAE,KAAK,IAAI;AAAA,EACnC,CAAC,EACA,KAAK,IAAI;AACd;","names":[]}

package/dist/headless/format.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 {
+    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,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,CAkDjG;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"}

package/dist/headless/format.js

@@ -0,0 +1,85 @@
+function truncate(s, max) {
+  return s.length > max ? s.slice(0, max) + "..." : s;
+}
+function createHumanFormatState() {
+  return { lastTextLength: 0 };
+}
+function formatHuman(event, state) {
+  switch (event.type) {
+    case "agent_start":
+      state.lastTextLength = 0;
+      return {};
+    case "message_update": {
+      const fullText = event.message.content.filter((c) => c.type === "text").map((p) => p.text).join("");
+      if (fullText.length > state.lastTextLength) {
+        const delta = fullText.slice(state.lastTextLength);
+        state.lastTextLength = fullText.length;
+        return { stdout: delta };
+      }
+      return {};
+    }
+    case "message_end": {
+      if (event.message.role !== "assistant") return {};
+      const fullText = event.message.content.filter((c) => c.type === "text").map((p) => p.text).join("");
+      const delta = fullText.length > state.lastTextLength ? fullText.slice(state.lastTextLength) : "";
+      state.lastTextLength = 0;
+      return { stdout: delta + "\n" };
+    }
+    case "tool_start":
+      return { stderr: `[tool] ${event.toolName}
+` };
+    case "tool_end":
+      return event.isError ? { stderr: `[tool error] ${truncate(String(event.result), 200)}
+` } : {};
+    case "shell_output":
+      return { stderr: event.output };
+    case "subagent_start":
+      return {
+        stderr: `[subagent:${event.forked ? "forked:" : ""}${event.agentType}] ${truncate(event.task, 100)}
+`
+      };
+    case "subagent_end":
+      return event.isError ? { stderr: `[subagent error] ${truncate(event.result, 200)}
+` } : {};
+    case "error":
+      return { stderr: `[error] ${event.error.message}
+` };
+    default:
+      return {};
+  }
+}
+function serializeError(err) {
+  return { name: err.name, message: err.message, stack: err.stack };
+}
+function formatJsonl(event) {
+  const out = { ...event };
+  if ("error" in event && event.error instanceof Error) {
+    out.error = serializeError(event.error);
+  }
+  return out;
+}
+function renderTextResult(result) {
+  return result.text.endsWith("\n") ? result.text : result.text + "\n";
+}
+function renderJsonResult(result) {
+  return JSON.stringify({
+    status: result.status,
+    text: result.text,
+    finishReason: result.finishReason,
+    usage: result.usage,
+    toolCalls: result.toolCalls,
+    toolResults: result.toolResults,
+    error: result.error,
+    threadId: result.threadId,
+    exitCode: result.exitCode
+  }) + "\n";
+}
+export {
+  createHumanFormatState,
+  formatHuman,
+  formatJsonl,
+  renderJsonResult,
+  renderTextResult,
+  truncate
+};
+//# sourceMappingURL=format.js.map

package/dist/headless/format.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/headless/format.ts"],"sourcesContent":["/**\n * Output formatters for headless runs. All functions here are pure — they take\n * an event (or a final result) and return strings / plain objects. They never\n * touch `process.*`; the CLI adapter owns the sinks.\n */\nimport type { AgentControllerEvent } from '@mastra/core/agent-controller';\n\nimport type { RunMCResult } from './types.js';\n\n/** Truncate a string to `max` characters, appending \"...\" if truncated. */\nexport function truncate(s: string, max: number): string {\n  return s.length > max ? s.slice(0, max) + '...' : s;\n}\n\n/** Mutable per-stream cursor used by {@link formatHuman} to stream assistant text. */\nexport interface HumanFormatState {\n  lastTextLength: number;\n}\n\nexport function createHumanFormatState(): HumanFormatState {\n  return { lastTextLength: 0 };\n}\n\n/** A chunk of formatted output destined for stdout and/or stderr. */\nexport interface FormattedOutput {\n  stdout?: string;\n  stderr?: string;\n}\n\n/**\n * Human-readable streaming formatter (the historical default). Assistant text\n * streams to stdout; tool/subagent/shell/error activity goes to stderr. The\n * `state` cursor is mutated so repeated `message_update` events only emit the\n * newly-appended text.\n */\nexport function formatHuman(event: AgentControllerEvent, state: HumanFormatState): FormattedOutput {\n  switch (event.type) {\n    case 'agent_start':\n      state.lastTextLength = 0;\n      return {};\n    case 'message_update': {\n      const fullText = event.message.content\n        .filter((c): c is { type: 'text'; text: string } => c.type === 'text')\n        .map(p => p.text)\n        .join('');\n      if (fullText.length > state.lastTextLength) {\n        const delta = fullText.slice(state.lastTextLength);\n        state.lastTextLength = fullText.length;\n        return { stdout: delta };\n      }\n      return {};\n    }\n    case 'message_end': {\n      // Only assistant messages produce stdout. The controller also emits\n      // message_end for the echoed user prompt (and system messages); emitting\n      // those here would duplicate the prompt to stdout and corrupt the stream.\n      if (event.message.role !== 'assistant') return {};\n      // Emit any assistant text the message_update stream didn't already cover\n      // (e.g. a run that only delivered the final text on message_end), then\n      // terminate the line.\n      const fullText = event.message.content\n        .filter((c): c is { type: 'text'; text: string } => c.type === 'text')\n        .map(p => p.text)\n        .join('');\n      const delta = fullText.length > state.lastTextLength ? fullText.slice(state.lastTextLength) : '';\n      state.lastTextLength = 0;\n      return { stdout: delta + '\\n' };\n    }\n    case 'tool_start':\n      return { stderr: `[tool] ${event.toolName}\\n` };\n    case 'tool_end':\n      return event.isError ? { stderr: `[tool error] ${truncate(String(event.result), 200)}\\n` } : {};\n    case 'shell_output':\n      return { stderr: event.output };\n    case 'subagent_start':\n      return {\n        stderr: `[subagent:${event.forked ? 'forked:' : ''}${event.agentType}] ${truncate(event.task, 100)}\\n`,\n      };\n    case 'subagent_end':\n      return event.isError ? { stderr: `[subagent error] ${truncate(event.result, 200)}\\n` } : {};\n    case 'error':\n      return { stderr: `[error] ${event.error.message}\\n` };\n    default:\n      return {};\n  }\n}\n\n/** Convert an `Error` instance into a JSON-serializable plain object. */\nfunction serializeError(err: Error): { name: string; message: string; stack?: string } {\n  return { name: err.name, message: err.message, stack: err.stack };\n}\n\n/**\n * JSONL (stream-json) formatter — returns a plain object to be `JSON.stringify`'d\n * as one line per event by the sink. `Error` instances are normalized so their\n * `name`/`message`/`stack` survive serialization (`JSON.stringify` turns a raw\n * `Error` into `{}`).\n */\nexport function formatJsonl(event: AgentControllerEvent): Record<string, unknown> {\n  const out: Record<string, unknown> = { ...event };\n  if ('error' in event && event.error instanceof Error) {\n    out.error = serializeError(event.error);\n  }\n  return out;\n}\n\n/** Render the final result for `--output text`: assistant text, newline-terminated. */\nexport function renderTextResult(result: RunMCResult): string {\n  return result.text.endsWith('\\n') ? result.text : result.text + '\\n';\n}\n\n/** Render the final result for `--output json`: one JSON object. */\nexport function renderJsonResult(result: RunMCResult): string {\n  return (\n    JSON.stringify({\n      status: result.status,\n      text: result.text,\n      finishReason: result.finishReason,\n      usage: result.usage,\n      toolCalls: result.toolCalls,\n      toolResults: result.toolResults,\n      error: result.error,\n      threadId: result.threadId,\n      exitCode: result.exitCode,\n    }) + '\\n'\n  );\n}\n"],"mappings":"AAUO,SAAS,SAAS,GAAW,KAAqB;AACvD,SAAO,EAAE,SAAS,MAAM,EAAE,MAAM,GAAG,GAAG,IAAI,QAAQ;AACpD;AAOO,SAAS,yBAA2C;AACzD,SAAO,EAAE,gBAAgB,EAAE;AAC7B;AAcO,SAAS,YAAY,OAA6B,OAA0C;AACjG,UAAQ,MAAM,MAAM;AAAA,IAClB,KAAK;AACH,YAAM,iBAAiB;AACvB,aAAO,CAAC;AAAA,IACV,KAAK,kBAAkB;AACrB,YAAM,WAAW,MAAM,QAAQ,QAC5B,OAAO,CAAC,MAA2C,EAAE,SAAS,MAAM,EACpE,IAAI,OAAK,EAAE,IAAI,EACf,KAAK,EAAE;AACV,UAAI,SAAS,SAAS,MAAM,gBAAgB;AAC1C,cAAM,QAAQ,SAAS,MAAM,MAAM,cAAc;AACjD,cAAM,iBAAiB,SAAS;AAChC,eAAO,EAAE,QAAQ,MAAM;AAAA,MACzB;AACA,aAAO,CAAC;AAAA,IACV;AAAA,IACA,KAAK,eAAe;AAIlB,UAAI,MAAM,QAAQ,SAAS,YAAa,QAAO,CAAC;AAIhD,YAAM,WAAW,MAAM,QAAQ,QAC5B,OAAO,CAAC,MAA2C,EAAE,SAAS,MAAM,EACpE,IAAI,OAAK,EAAE,IAAI,EACf,KAAK,EAAE;AACV,YAAM,QAAQ,SAAS,SAAS,MAAM,iBAAiB,SAAS,MAAM,MAAM,cAAc,IAAI;AAC9F,YAAM,iBAAiB;AACvB,aAAO,EAAE,QAAQ,QAAQ,KAAK;AAAA,IAChC;AAAA,IACA,KAAK;AACH,aAAO,EAAE,QAAQ,UAAU,MAAM,QAAQ;AAAA,EAAK;AAAA,IAChD,KAAK;AACH,aAAO,MAAM,UAAU,EAAE,QAAQ,gBAAgB,SAAS,OAAO,MAAM,MAAM,GAAG,GAAG,CAAC;AAAA,EAAK,IAAI,CAAC;AAAA,IAChG,KAAK;AACH,aAAO,EAAE,QAAQ,MAAM,OAAO;AAAA,IAChC,KAAK;AACH,aAAO;AAAA,QACL,QAAQ,aAAa,MAAM,SAAS,YAAY,EAAE,GAAG,MAAM,SAAS,KAAK,SAAS,MAAM,MAAM,GAAG,CAAC;AAAA;AAAA,MACpG;AAAA,IACF,KAAK;AACH,aAAO,MAAM,UAAU,EAAE,QAAQ,oBAAoB,SAAS,MAAM,QAAQ,GAAG,CAAC;AAAA,EAAK,IAAI,CAAC;AAAA,IAC5F,KAAK;AACH,aAAO,EAAE,QAAQ,WAAW,MAAM,MAAM,OAAO;AAAA,EAAK;AAAA,IACtD;AACE,aAAO,CAAC;AAAA,EACZ;AACF;AAGA,SAAS,eAAe,KAA+D;AACrF,SAAO,EAAE,MAAM,IAAI,MAAM,SAAS,IAAI,SAAS,OAAO,IAAI,MAAM;AAClE;AAQO,SAAS,YAAY,OAAsD;AAChF,QAAM,MAA+B,EAAE,GAAG,MAAM;AAChD,MAAI,WAAW,SAAS,MAAM,iBAAiB,OAAO;AACpD,QAAI,QAAQ,eAAe,MAAM,KAAK;AAAA,EACxC;AACA,SAAO;AACT;AAGO,SAAS,iBAAiB,QAA6B;AAC5D,SAAO,OAAO,KAAK,SAAS,IAAI,IAAI,OAAO,OAAO,OAAO,OAAO;AAClE;AAGO,SAAS,iBAAiB,QAA6B;AAC5D,SACE,KAAK,UAAU;AAAA,IACb,QAAQ,OAAO;AAAA,IACf,MAAM,OAAO;AAAA,IACb,cAAc,OAAO;AAAA,IACrB,OAAO,OAAO;AAAA,IACd,WAAW,OAAO;AAAA,IAClB,aAAa,OAAO;AAAA,IACpB,OAAO,OAAO;AAAA,IACd,UAAU,OAAO;AAAA,IACjB,UAAU,OAAO;AAAA,EACnB,CAAC,IAAI;AAET;","names":[]}

package/dist/headless/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Public headless / programmatic API for MastraCode.
+ *
+ * Programmatic (CI / Node) usage:
+ * ```ts
+ * import { createMastraCode } from 'mastracode';
+ * import { runMC } from 'mastracode/headless';
+ *
+ * const { controller, session } = await createMastraCode({ settingsPath });
+ * const run = runMC({ controller, session, prompt: 'Fix the bug' });
+ * for await (const event of run) { ... } // optional live events
+ * const result = await run.result;        // typed RunMCResult
+ * ```
+ *
+ * The CLI adapter (`runMCCli`) wraps the same `createMastraCode` → `runMC` flow.
+ */
+export { runMC } from './run-mc.js';
+export { autoApprovePolicy, denyPolicy, permissionModeToPolicy } from './policy.js';
+export { formatHuman, formatJsonl, renderTextResult, renderJsonResult, createHumanFormatState, truncate, } from './format.js';
+export type { FormattedOutput, HumanFormatState } from './format.js';
+export { runMCCli, hasHeadlessFlag, parseHeadlessArgs, printHeadlessUsage } from './cli.js';
+export type { HeadlessArgs, OutputMode } from './cli.js';
+export type { RunMCOptions, RunMCResult, RunMCStatus, RunMCUsage, RunMCToolCall, RunMCToolResult, RunMCError, RunMCThreadOptions, MCRun, ResolutionPolicy, RunMode, ThinkingLevel, PermissionMode, } from './types.js';
+export { VALID_MODES, VALID_THINKING_LEVELS, VALID_PERMISSION_MODES } from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/headless/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGpC,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAGpF,OAAO,EACL,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,QAAQ,GACT,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGrE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC5F,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAGzD,YAAY,EACV,YAAY,EACZ,WAAW,EACX,WAAW,EACX,UAAU,EACV,aAAa,EACb,eAAe,EACf,UAAU,EACV,kBAAkB,EAClB,KAAK,EACL,gBAAgB,EAChB,OAAO,EACP,aAAa,EACb,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC"}