@mastra/code-sdk 0.0.0-esbuild-bundle-worker-20260807173433

package/dist/headless/flags.js

@@ -0,0 +1,190 @@
+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)"
+	},
+	{
+		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"
+	},
+	{
+		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)',\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":"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"}

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,EAAsC,MAAM,+BAA+B,CAAC;AAE9G,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvD;AAUD,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,CA4CjG;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,89 @@
+//#region src/headless/format.ts
+/** Truncate a string to `max` characters, appending "..." if truncated. */
+function truncate(s, max) {
+	return s.length > max ? s.slice(0, max) + "..." : s;
+}
+/** Concatenate the text of an assistant message's nested content parts. */
+function messageText(message) {
+	return message.content.parts.filter((p) => p.type === "text" && typeof p.text === "string").map((p) => p.text).join("");
+}
+function createHumanFormatState() {
+	return { lastTextLength: 0 };
+}
+/**
+* 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.
+*/
+function formatHuman(event, state) {
+	switch (event.type) {
+		case "agent_start":
+			state.lastTextLength = 0;
+			return {};
+		case "message_update": {
+			const fullText = messageText(event.message);
+			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 = messageText(event.message);
+			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}\n` };
+		case "tool_end": return event.isError ? { stderr: `[tool error] ${truncate(String(event.result), 200)}\n` } : {};
+		case "shell_output": return { stderr: event.output };
+		case "subagent_start": return { stderr: `[subagent:${event.forked ? "forked:" : ""}${event.agentType}] ${truncate(event.task, 100)}\n` };
+		case "subagent_end": return event.isError ? { stderr: `[subagent error] ${truncate(event.result, 200)}\n` } : {};
+		case "error": return { stderr: `[error] ${event.error.message}\n` };
+		default: return {};
+	}
+}
+/** Convert an `Error` instance into a JSON-serializable plain object. */
+function serializeError(err) {
+	return {
+		name: err.name,
+		message: err.message,
+		stack: err.stack
+	};
+}
+/**
+* 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 `{}`).
+*/
+function formatJsonl(event) {
+	const out = { ...event };
+	if ("error" in event && event.error instanceof Error) out.error = serializeError(event.error);
+	return out;
+}
+/** Render the final result for `--output text`: assistant text, newline-terminated. */
+function renderTextResult(result) {
+	return result.text.endsWith("\n") ? result.text : result.text + "\n";
+}
+/** Render the final result for `--output json`: one JSON object. */
+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";
+}
+//#endregion
+export { createHumanFormatState, formatHuman, formatJsonl, renderJsonResult, renderTextResult, truncate };
+
+//# sourceMappingURL=format.js.map

package/dist/headless/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","names":[],"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, MastraDBMessage, MastraMessagePart } 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/** Concatenate the text of an assistant message's nested content parts. */\nfunction messageText(message: MastraDBMessage): string {\n  return message.content.parts\n    .filter((p): p is MastraMessagePart & { text: string } => p.type === 'text' && typeof p.text === 'string')\n    .map(p => p.text)\n    .join('');\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 = messageText(event.message);\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 = messageText(event.message);\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":";;AAUA,SAAgB,SAAS,GAAW,KAAqB;CACvD,OAAO,EAAE,SAAS,MAAM,EAAE,MAAM,GAAG,GAAG,IAAI,QAAQ;AACpD;;AAGA,SAAS,YAAY,SAAkC;CACrD,OAAO,QAAQ,QAAQ,MACpB,QAAQ,MAAiD,EAAE,SAAS,UAAU,OAAO,EAAE,SAAS,QAAQ,CAAC,CACzG,KAAI,MAAK,EAAE,IAAI,CAAC,CAChB,KAAK,EAAE;AACZ;AAOA,SAAgB,yBAA2C;CACzD,OAAO,EAAE,gBAAgB,EAAE;AAC7B;;;;;;;AAcA,SAAgB,YAAY,OAA6B,OAA0C;CACjG,QAAQ,MAAM,MAAd;EACE,KAAK;GACH,MAAM,iBAAiB;GACvB,OAAO,CAAC;EACV,KAAK,kBAAkB;GACrB,MAAM,WAAW,YAAY,MAAM,OAAO;GAC1C,IAAI,SAAS,SAAS,MAAM,gBAAgB;IAC1C,MAAM,QAAQ,SAAS,MAAM,MAAM,cAAc;IACjD,MAAM,iBAAiB,SAAS;IAChC,OAAO,EAAE,QAAQ,MAAM;GACzB;GACA,OAAO,CAAC;EACV;EACA,KAAK,eAAe;GAIlB,IAAI,MAAM,QAAQ,SAAS,aAAa,OAAO,CAAC;GAIhD,MAAM,WAAW,YAAY,MAAM,OAAO;GAC1C,MAAM,QAAQ,SAAS,SAAS,MAAM,iBAAiB,SAAS,MAAM,MAAM,cAAc,IAAI;GAC9F,MAAM,iBAAiB;GACvB,OAAO,EAAE,QAAQ,QAAQ,KAAK;EAChC;EACA,KAAK,cACH,OAAO,EAAE,QAAQ,UAAU,MAAM,SAAS,IAAI;EAChD,KAAK,YACH,OAAO,MAAM,UAAU,EAAE,QAAQ,gBAAgB,SAAS,OAAO,MAAM,MAAM,GAAG,GAAG,EAAE,IAAI,IAAI,CAAC;EAChG,KAAK,gBACH,OAAO,EAAE,QAAQ,MAAM,OAAO;EAChC,KAAK,kBACH,OAAO,EACL,QAAQ,aAAa,MAAM,SAAS,YAAY,KAAK,MAAM,UAAU,IAAI,SAAS,MAAM,MAAM,GAAG,EAAE,IACrG;EACF,KAAK,gBACH,OAAO,MAAM,UAAU,EAAE,QAAQ,oBAAoB,SAAS,MAAM,QAAQ,GAAG,EAAE,IAAI,IAAI,CAAC;EAC5F,KAAK,SACH,OAAO,EAAE,QAAQ,WAAW,MAAM,MAAM,QAAQ,IAAI;EACtD,SACE,OAAO,CAAC;CACZ;AACF;;AAGA,SAAS,eAAe,KAA+D;CACrF,OAAO;EAAE,MAAM,IAAI;EAAM,SAAS,IAAI;EAAS,OAAO,IAAI;CAAM;AAClE;;;;;;;AAQA,SAAgB,YAAY,OAAsD;CAChF,MAAM,MAA+B,EAAE,GAAG,MAAM;CAChD,IAAI,WAAW,SAAS,MAAM,iBAAiB,OAC7C,IAAI,QAAQ,eAAe,MAAM,KAAK;CAExC,OAAO;AACT;;AAGA,SAAgB,iBAAiB,QAA6B;CAC5D,OAAO,OAAO,KAAK,SAAS,IAAI,IAAI,OAAO,OAAO,OAAO,OAAO;AAClE;;AAGA,SAAgB,iBAAiB,QAA6B;CAC5D,OACE,KAAK,UAAU;EACb,QAAQ,OAAO;EACf,MAAM,OAAO;EACb,cAAc,OAAO;EACrB,OAAO,OAAO;EACd,WAAW,OAAO;EAClB,aAAa,OAAO;EACpB,OAAO,OAAO;EACd,UAAU,OAAO;EACjB,UAAU,OAAO;CACnB,CAAC,IAAI;AAET"}

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, RunMCGoalOptions, 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,gBAAgB,EAChB,OAAO,EACP,aAAa,EACb,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC"}

package/dist/headless/index.js

@@ -0,0 +1,6 @@
+import { autoApprovePolicy, denyPolicy, permissionModeToPolicy } from "./policy.js";
+import { runMC } from "./run-mc.js";
+import { createHumanFormatState, formatHuman, formatJsonl, renderJsonResult, renderTextResult, truncate } from "./format.js";
+import { VALID_MODES, VALID_PERMISSION_MODES, VALID_THINKING_LEVELS } from "./types.js";
+import { hasHeadlessFlag, parseHeadlessArgs, printHeadlessUsage, runMCCli } from "./cli.js";
+export { VALID_MODES, VALID_PERMISSION_MODES, VALID_THINKING_LEVELS, autoApprovePolicy, createHumanFormatState, denyPolicy, formatHuman, formatJsonl, hasHeadlessFlag, parseHeadlessArgs, permissionModeToPolicy, printHeadlessUsage, renderJsonResult, renderTextResult, runMC, runMCCli, truncate };

package/dist/headless/policy.d.ts

@@ -0,0 +1,17 @@
+import type { PermissionMode, ResolutionPolicy } from './types.js';
+/**
+ * Default policy — reproduces the historical headless behavior:
+ *  - approve every tool approval request,
+ *  - auto-approve `request_access` / sandbox access suspensions ("Yes"),
+ *  - auto-approve `submit_plan` suspensions (`{ action: 'approved' }`),
+ *  - answer any other suspension with a "use your best judgment" instruction.
+ */
+export declare const autoApprovePolicy: ResolutionPolicy;
+/**
+ * Strict policy — refuses every tool approval and aborts on any suspension.
+ * Useful for CI gating where unattended tool execution must not happen.
+ */
+export declare const denyPolicy: ResolutionPolicy;
+/** Resolve a named {@link PermissionMode} to its built-in {@link ResolutionPolicy}. */
+export declare function permissionModeToPolicy(mode: PermissionMode): ResolutionPolicy;
+//# sourceMappingURL=policy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/headless/policy.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnE;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,gBAoB/B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAE,gBAUxB,CAAC;AAEF,uFAAuF;AACvF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,cAAc,GAAG,gBAAgB,CAQ7E"}

package/dist/headless/policy.js

@@ -0,0 +1,42 @@
+//#region src/headless/policy.ts
+/**
+* Default policy — reproduces the historical headless behavior:
+*  - approve every tool approval request,
+*  - auto-approve `request_access` / sandbox access suspensions ("Yes"),
+*  - auto-approve `submit_plan` suspensions (`{ action: 'approved' }`),
+*  - answer any other suspension with a "use your best judgment" instruction.
+*/
+const autoApprovePolicy = {
+	onToolApproval(_event) {
+		return "approve";
+	},
+	onSuspension(event) {
+		const payload = event.suspendPayload ?? {};
+		if (event.toolName === "request_access" || payload.kind === "sandbox_access_request") return { resumeData: "Yes" };
+		if (event.toolName === "submit_plan") return { resumeData: { action: "approved" } };
+		return { resumeData: "Proceed with your best judgment. Do not ask further questions." };
+	}
+};
+/**
+* Strict policy — refuses every tool approval and aborts on any suspension.
+* Useful for CI gating where unattended tool execution must not happen.
+*/
+const denyPolicy = {
+	onToolApproval(_event) {
+		return "deny";
+	},
+	onSuspension(_event) {
+		return { abort: true };
+	}
+};
+/** Resolve a named {@link PermissionMode} to its built-in {@link ResolutionPolicy}. */
+function permissionModeToPolicy(mode) {
+	switch (mode) {
+		case "deny": return denyPolicy;
+		default: return autoApprovePolicy;
+	}
+}
+//#endregion
+export { autoApprovePolicy, denyPolicy, permissionModeToPolicy };
+
+//# sourceMappingURL=policy.js.map

package/dist/headless/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","names":[],"sources":["../../src/headless/policy.ts"],"sourcesContent":["/**\n * Resolution policies decide how `runMC` resumes interactive events\n * (`tool_approval_required`, `tool_suspended`) without a human in the loop.\n *\n * Policies are pure decision objects: they inspect the event and return a\n * decision. The runner is responsible for applying the decision to the session\n * and for any side effects (emitting labels, etc.). This keeps policies testable\n * and lets CI swap in stricter behavior without touching the runner.\n */\nimport type { AgentControllerEvent } from '@mastra/core/agent-controller';\n\nimport type { PermissionMode, ResolutionPolicy } from './types.js';\n\n/**\n * Default policy — reproduces the historical headless behavior:\n *  - approve every tool approval request,\n *  - auto-approve `request_access` / sandbox access suspensions (\"Yes\"),\n *  - auto-approve `submit_plan` suspensions (`{ action: 'approved' }`),\n *  - answer any other suspension with a \"use your best judgment\" instruction.\n */\nexport const autoApprovePolicy: ResolutionPolicy = {\n  onToolApproval(_event: Extract<AgentControllerEvent, { type: 'tool_approval_required' }>): 'approve' | 'deny' {\n    return 'approve';\n  },\n\n  onSuspension(\n    event: Extract<AgentControllerEvent, { type: 'tool_suspended' }>,\n  ): { resumeData: unknown } | { abort: true } {\n    const payload = (event.suspendPayload ?? {}) as Record<string, unknown>;\n\n    if (event.toolName === 'request_access' || payload.kind === 'sandbox_access_request') {\n      return { resumeData: 'Yes' };\n    }\n\n    if (event.toolName === 'submit_plan') {\n      return { resumeData: { action: 'approved' } };\n    }\n\n    return { resumeData: 'Proceed with your best judgment. Do not ask further questions.' };\n  },\n};\n\n/**\n * Strict policy — refuses every tool approval and aborts on any suspension.\n * Useful for CI gating where unattended tool execution must not happen.\n */\nexport const denyPolicy: ResolutionPolicy = {\n  onToolApproval(_event: Extract<AgentControllerEvent, { type: 'tool_approval_required' }>): 'approve' | 'deny' {\n    return 'deny';\n  },\n\n  onSuspension(\n    _event: Extract<AgentControllerEvent, { type: 'tool_suspended' }>,\n  ): { resumeData: unknown } | { abort: true } {\n    return { abort: true };\n  },\n};\n\n/** Resolve a named {@link PermissionMode} to its built-in {@link ResolutionPolicy}. */\nexport function permissionModeToPolicy(mode: PermissionMode): ResolutionPolicy {\n  switch (mode) {\n    case 'deny':\n      return denyPolicy;\n    case 'auto':\n    default:\n      return autoApprovePolicy;\n  }\n}\n"],"mappings":";;;;;;;;AAoBA,MAAa,oBAAsC;CACjD,eAAe,QAA+F;EAC5G,OAAO;CACT;CAEA,aACE,OAC2C;EAC3C,MAAM,UAAW,MAAM,kBAAkB,CAAC;EAE1C,IAAI,MAAM,aAAa,oBAAoB,QAAQ,SAAS,0BAC1D,OAAO,EAAE,YAAY,MAAM;EAG7B,IAAI,MAAM,aAAa,eACrB,OAAO,EAAE,YAAY,EAAE,QAAQ,WAAW,EAAE;EAG9C,OAAO,EAAE,YAAY,iEAAiE;CACxF;AACF;;;;;AAMA,MAAa,aAA+B;CAC1C,eAAe,QAA+F;EAC5G,OAAO;CACT;CAEA,aACE,QAC2C;EAC3C,OAAO,EAAE,OAAO,KAAK;CACvB;AACF;;AAGA,SAAgB,uBAAuB,MAAwC;CAC7E,QAAQ,MAAR;EACE,KAAK,QACH,OAAO;EAET,SACE,OAAO;CACX;AACF"}

package/dist/headless/run-mc.d.ts

@@ -0,0 +1,7 @@
+import type { MCRun, RunMCOptions } from './types.js';
+/**
+ * Run a headless MastraCode turn. Returns an {@link MCRun} handle that is
+ * async-iterable over controller events and resolves to a {@link RunMCResult}.
+ */
+export declare function runMC<TState extends Record<string, unknown>>(options: RunMCOptions<TState>): MCRun;
+//# sourceMappingURL=run-mc.d.ts.map

package/dist/headless/run-mc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-mc.d.ts","sourceRoot":"","sources":["../../src/headless/run-mc.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,KAAK,EAAoB,YAAY,EAA4B,MAAM,YAAY,CAAC;AA0IlG;;;GAGG;AACH,wBAAgB,KAAK,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,KAAK,CA8RlG"}