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

package/dist/headless/run-mc.js

@@ -0,0 +1,346 @@
+import { GoalManager } from "../goal-manager.js";
+import { createGoalReminderSignal } from "../goal-signal.js";
+import { autoApprovePolicy } from "./policy.js";
+//#region src/headless/run-mc.ts
+function extractAssistantText(message) {
+	return message.content.parts.filter((p) => p.type === "text" && typeof p.text === "string").map((p) => p.text).join("");
+}
+function exitCodeForStatus(status) {
+	switch (status) {
+		case "completed":
+		case "done": return 0;
+		case "timeout": return 2;
+		default: return 1;
+	}
+}
+function aggregate(event, acc) {
+	switch (event.type) {
+		case "message_end":
+			if (event.message.role === "assistant") acc.text += extractAssistantText(event.message);
+			break;
+		case "tool_start":
+			acc.toolCalls.push({
+				id: event.toolCallId,
+				name: event.toolName,
+				args: event.args
+			});
+			break;
+		case "tool_end": {
+			const matching = acc.toolCalls.find((c) => c.id === event.toolCallId);
+			acc.toolResults.push({
+				id: event.toolCallId,
+				name: matching?.name ?? "",
+				result: event.result,
+				isError: event.isError
+			});
+			break;
+		}
+		case "usage_update":
+			acc.usage = {
+				inputTokens: event.usage.promptTokens,
+				outputTokens: event.usage.completionTokens,
+				totalTokens: event.usage.totalTokens
+			};
+			break;
+		case "error":
+			acc.error = {
+				name: event.error.name,
+				message: event.error.message,
+				stack: event.error.stack
+			};
+			break;
+	}
+}
+/** Resolve a thread by its exact ID. Titles are not unique, so we don't match on them. */
+async function resolveThread(session, threadId) {
+	const byId = (await session.thread.list()).find((t) => t.id === threadId);
+	if (byId) return { threadId: byId.id };
+	return { error: `No thread found with ID "${threadId}"` };
+}
+/**
+* A simple back-pressured async queue. Events are pushed in; consumers pull via
+* the async iterator. `close()` ends iteration after draining buffered events.
+*
+* Buffered events are bounded by `maxBuffer`: if a consumer never iterates (the
+* result-only path, `await run.result` without `for await (...)`) — or simply
+* falls far behind — the oldest buffered events are dropped instead of growing
+* without limit. The aggregated {@link RunMCResult} is built independently of
+* this queue, so dropping buffered events never affects the final result.
+*/
+var EventQueue = class {
+	#buffer = [];
+	#resolvers = [];
+	#closed = false;
+	#maxBuffer;
+	constructor(maxBuffer = 1e4) {
+		this.#maxBuffer = maxBuffer;
+	}
+	push(value) {
+		if (this.#closed) return;
+		const resolve = this.#resolvers.shift();
+		if (resolve) {
+			resolve({
+				value,
+				done: false
+			});
+			return;
+		}
+		this.#buffer.push(value);
+		if (this.#buffer.length > this.#maxBuffer) this.#buffer.shift();
+	}
+	close() {
+		if (this.#closed) return;
+		this.#closed = true;
+		for (const resolve of this.#resolvers.splice(0)) resolve({
+			value: void 0,
+			done: true
+		});
+	}
+	[Symbol.asyncIterator]() {
+		return { next: () => {
+			if (this.#buffer.length > 0) return Promise.resolve({
+				value: this.#buffer.shift(),
+				done: false
+			});
+			if (this.#closed) return Promise.resolve({
+				value: void 0,
+				done: true
+			});
+			return new Promise((resolve) => this.#resolvers.push(resolve));
+		} };
+	}
+};
+/**
+* Run a headless MastraCode turn. Returns an {@link MCRun} handle that is
+* async-iterable over controller events and resolves to a {@link RunMCResult}.
+*/
+function runMC(options) {
+	const { controller, session } = options;
+	const goal = options.goal;
+	const policy = options.policy ?? autoApprovePolicy;
+	const queue = new EventQueue();
+	const acc = {
+		text: "",
+		toolCalls: [],
+		toolResults: []
+	};
+	let timeoutId;
+	let timedOut = false;
+	let aborted = false;
+	let maxTurnsExceeded = false;
+	let assistantTurns = 0;
+	let settled = false;
+	let unsubscribe;
+	let resolveResult;
+	const result = new Promise((resolve) => {
+		resolveResult = resolve;
+	});
+	function finish(status, data = {}) {
+		if (settled) return;
+		settled = true;
+		if (timeoutId) clearTimeout(timeoutId);
+		unsubscribe?.();
+		queue.close();
+		resolveResult({
+			status,
+			text: acc.text,
+			finishReason: acc.finishReason,
+			usage: acc.usage,
+			toolCalls: acc.toolCalls,
+			toolResults: acc.toolResults,
+			threadId: acc.threadId ?? session.thread.getId() ?? void 0,
+			error: acc.error,
+			exitCode: exitCodeForStatus(status),
+			...data
+		});
+	}
+	function fail(message, name = "Error") {
+		if (!acc.error) acc.error = {
+			name,
+			message
+		};
+		finish("error");
+	}
+	function abort() {
+		if (settled) return;
+		aborted = true;
+		session.abort();
+	}
+	if (options.signal) if (options.signal.aborted) queueMicrotask(() => abort());
+	else options.signal.addEventListener("abort", () => abort(), { once: true });
+	function armTimeout() {
+		if (!options.timeoutMs || settled) return;
+		if (timeoutId) clearTimeout(timeoutId);
+		timeoutId = setTimeout(() => {
+			timedOut = true;
+			session.abort();
+			if (goal) finish("timeout");
+		}, options.timeoutMs);
+	}
+	(async () => {
+		armTimeout();
+		try {
+			if (options.model) {
+				const match = (await controller.listAvailableModels()).find((m) => m.id === options.model);
+				if (!match) return fail(`Unknown model: "${options.model}"`);
+				if (!match.hasApiKey) {
+					const keyHint = match.apiKeyEnvVar ? ` Set ${match.apiKeyEnvVar} to use this model.` : "";
+					return fail(`Model "${options.model}" has no API key configured.${keyHint}`);
+				}
+				await session.model.switch({ modelId: options.model });
+			} else if (options.mode) {
+				const modelId = options.modeDefaults?.[options.mode];
+				if (modelId) {
+					const match = (await controller.listAvailableModels()).find((m) => m.id === modelId);
+					if (!match) return fail(`Unknown model "${modelId}" configured for mode "${options.mode}"`);
+					if (!match.hasApiKey) {
+						const keyHint = match.apiKeyEnvVar ? ` Set ${match.apiKeyEnvVar} to use this model.` : "";
+						return fail(`Model "${modelId}" (mode: ${options.mode}) has no API key configured.${keyHint}`);
+					}
+					await session.model.switch({ modelId });
+				}
+			}
+			if (options.thinkingLevel) await session.state.set({ thinkingLevel: options.thinkingLevel });
+		} catch (err) {
+			return fail(`Failed to resolve run config: ${err.message}`);
+		}
+		unsubscribe = session.subscribe((event) => {
+			if (settled) return;
+			if (goal) armTimeout();
+			if (event.type === "tool_approval_required") {
+				let decision;
+				try {
+					decision = policy.onToolApproval(event);
+				} catch (err) {
+					fail(`Resolution policy failed: ${err.message}`);
+					return;
+				}
+				session.respondToToolApproval({
+					decision: decision === "approve" ? "approve" : "decline",
+					toolCallId: event.toolCallId
+				});
+				queue.push(event);
+				return;
+			}
+			if (event.type === "tool_suspended") {
+				let outcome;
+				try {
+					outcome = policy.onSuspension(event);
+				} catch (err) {
+					fail(`Resolution policy failed: ${err.message}`);
+					return;
+				}
+				if ("abort" in outcome) {
+					queue.push(event);
+					abort();
+					return;
+				}
+				session.respondToToolSuspension({
+					toolCallId: event.toolCallId,
+					resumeData: outcome.resumeData
+				});
+				queue.push(event);
+				return;
+			}
+			aggregate(event, acc);
+			queue.push(event);
+			if (event.type === "error" && goal) {
+				finish("error");
+				return;
+			}
+			if (event.type === "message_end" && event.message.role === "assistant" && options.maxTurns !== void 0) {
+				assistantTurns += 1;
+				if (assistantTurns >= options.maxTurns && !maxTurnsExceeded) {
+					maxTurnsExceeded = true;
+					abort();
+				}
+			}
+			if (event.type === "goal_evaluation" && goal && !event.payload.pending) {
+				if (event.payload.status === "done" || event.payload.status === "paused") finish(event.payload.status, {
+					objective: goal.objective,
+					goalEvent: event,
+					reason: event.payload.reason ?? event.payload.results?.[0]?.reason,
+					iterations: event.payload.iteration,
+					maxRuns: event.payload.maxRuns
+				});
+				return;
+			}
+			if (event.type === "agent_end") {
+				acc.finishReason = event.reason;
+				if (goal) return;
+				if (timedOut) finish("timeout");
+				else if (event.reason === "error") finish("error");
+				else if (maxTurnsExceeded && event.reason !== "complete") finish("max_turns");
+				else if ((event.reason === "aborted" || aborted) && !maxTurnsExceeded) finish("aborted");
+				else finish("completed");
+			}
+		});
+		try {
+			if (options.resourceId) await controller.setResourceId(session, { resourceId: options.resourceId });
+		} catch (err) {
+			return fail(`Failed to set resource id: ${err.message}`);
+		}
+		try {
+			const thread = options.thread;
+			if (thread?.id) {
+				const resolved = await resolveThread(session, thread.id);
+				if ("error" in resolved) return fail(resolved.error);
+				await session.thread.switch({ threadId: resolved.threadId });
+			} else if (thread?.continueLatest) {
+				const threads = await session.thread.list();
+				if (threads.length > 0) {
+					const sorted = [...threads].sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());
+					await session.thread.switch({ threadId: sorted[0].id });
+				}
+			}
+		} catch (err) {
+			return fail(`Failed to select thread: ${err.message}`);
+		}
+		if (options.thread?.clone) try {
+			await session.thread.clone();
+		} catch (err) {
+			return fail(`Failed to clone thread: ${err.message}`);
+		}
+		if (options.title) try {
+			await session.thread.rename({ title: options.title });
+		} catch (err) {
+			return fail(`Failed to set thread title: ${err.message}`);
+		}
+		try {
+			if (goal) {
+				const threadId = session.thread.getId();
+				if (!threadId || !await session.thread.getById({ threadId })) await session.thread.create();
+				const goalManager = goal.goalManager ?? new GoalManager();
+				const state = {
+					controller,
+					session,
+					goalManager,
+					pendingNewThread: false,
+					planStartedGoalId: void 0
+				};
+				const objective = await goalManager.setGoal(state, goal.objective, goal.judgeModelId, goal.maxRuns);
+				if (!objective) return fail("Failed to set goal.");
+				const persisted = await controller.getCurrentAgent(session).getObjective({ threadId: session.thread.getId() });
+				if (!persisted || persisted.id !== objective.id) return fail("Failed to persist goal objective before sending goal signal.");
+				await goalManager.saveToThread(state);
+				if (!settled) await session.sendSignal(createGoalReminderSignal(objective)).accepted;
+			} else {
+				if (!options.prompt) return fail("A prompt or goal is required.");
+				await session.sendMessage({ content: options.prompt });
+			}
+		} catch (err) {
+			return fail(`Failed to start run: ${err.message}`);
+		}
+	})();
+	return {
+		result,
+		abort,
+		[Symbol.asyncIterator]() {
+			return queue[Symbol.asyncIterator]();
+		}
+	};
+}
+//#endregion
+export { runMC };
+
+//# sourceMappingURL=run-mc.js.map

package/dist/headless/run-mc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-mc.js","names":["#maxBuffer","#closed","#resolvers","#buffer"],"sources":["../../src/headless/run-mc.ts"],"sourcesContent":["/**\n * Core programmatic runner for MastraCode headless runs.\n *\n * `runMC` is a pure async runner: it takes an already-built `controller` +\n * `session` (from `createMastraCode(...)`), resolves run config, subscribes to\n * the session, applies a {@link ResolutionPolicy} for approvals/suspensions,\n * sends the prompt, and aggregates events into a {@link RunMCResult}.\n *\n * It never touches `process.*` and never calls `process.exit`. The returned\n * {@link MCRun} is async-iterable over controller events and also resolves to a\n * final result via `result`.\n */\nimport type { AgentControllerEvent, MastraDBMessage, MastraMessagePart, Session } from '@mastra/core/agent-controller';\n\nimport { GoalManager } from '../goal-manager.js';\nimport { createGoalReminderSignal } from '../goal-signal.js';\n\nimport { autoApprovePolicy } from './policy.js';\nimport type { MCRun, ResolutionPolicy, RunMCOptions, RunMCResult, RunMCStatus } from './types.js';\n\nfunction extractAssistantText(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\nfunction exitCodeForStatus(status: RunMCStatus): number {\n  switch (status) {\n    case 'completed':\n    case 'done':\n      return 0;\n    case 'timeout':\n      return 2;\n    default:\n      return 1;\n  }\n}\n\ninterface MutableResult {\n  text: string;\n  finishReason?: string;\n  usage?: RunMCResult['usage'];\n  toolCalls: RunMCResult['toolCalls'];\n  toolResults: RunMCResult['toolResults'];\n  error?: RunMCResult['error'];\n  threadId?: string;\n}\n\nfunction aggregate(event: AgentControllerEvent, acc: MutableResult): void {\n  switch (event.type) {\n    case 'message_end':\n      if (event.message.role === 'assistant') {\n        acc.text += extractAssistantText(event.message);\n      }\n      break;\n    case 'tool_start':\n      acc.toolCalls.push({ id: event.toolCallId, name: event.toolName, args: event.args });\n      break;\n    case 'tool_end': {\n      const matching = acc.toolCalls.find(c => c.id === event.toolCallId);\n      acc.toolResults.push({\n        id: event.toolCallId,\n        name: matching?.name ?? '',\n        result: event.result,\n        isError: event.isError,\n      });\n      break;\n    }\n    case 'usage_update':\n      acc.usage = {\n        inputTokens: event.usage.promptTokens,\n        outputTokens: event.usage.completionTokens,\n        totalTokens: event.usage.totalTokens,\n      };\n      break;\n    case 'error':\n      acc.error = {\n        name: event.error.name,\n        message: event.error.message,\n        stack: event.error.stack,\n      };\n      break;\n  }\n}\n\n/** Resolve a thread by its exact ID. Titles are not unique, so we don't match on them. */\nasync function resolveThread<TState extends Record<string, unknown>>(\n  session: Session<TState>,\n  threadId: string,\n): Promise<{ threadId: string } | { error: string }> {\n  const threads = await session.thread.list();\n\n  const byId = threads.find(t => t.id === threadId);\n  if (byId) return { threadId: byId.id };\n\n  return { error: `No thread found with ID \"${threadId}\"` };\n}\n\n/**\n * A simple back-pressured async queue. Events are pushed in; consumers pull via\n * the async iterator. `close()` ends iteration after draining buffered events.\n *\n * Buffered events are bounded by `maxBuffer`: if a consumer never iterates (the\n * result-only path, `await run.result` without `for await (...)`) — or simply\n * falls far behind — the oldest buffered events are dropped instead of growing\n * without limit. The aggregated {@link RunMCResult} is built independently of\n * this queue, so dropping buffered events never affects the final result.\n */\nclass EventQueue<T> {\n  #buffer: T[] = [];\n  #resolvers: Array<(r: IteratorResult<T>) => void> = [];\n  #closed = false;\n  readonly #maxBuffer: number;\n\n  constructor(maxBuffer = 10_000) {\n    this.#maxBuffer = maxBuffer;\n  }\n\n  push(value: T): void {\n    if (this.#closed) return;\n    const resolve = this.#resolvers.shift();\n    if (resolve) {\n      resolve({ value, done: false });\n      return;\n    }\n    this.#buffer.push(value);\n    if (this.#buffer.length > this.#maxBuffer) {\n      // Bound memory: drop the oldest event once over the cap.\n      this.#buffer.shift();\n    }\n  }\n\n  close(): void {\n    if (this.#closed) return;\n    this.#closed = true;\n    for (const resolve of this.#resolvers.splice(0)) {\n      resolve({ value: undefined as unknown as T, done: true });\n    }\n  }\n\n  [Symbol.asyncIterator](): AsyncIterator<T> {\n    return {\n      next: (): Promise<IteratorResult<T>> => {\n        if (this.#buffer.length > 0) {\n          return Promise.resolve({ value: this.#buffer.shift()!, done: false });\n        }\n        if (this.#closed) {\n          return Promise.resolve({ value: undefined as unknown as T, done: true });\n        }\n        return new Promise<IteratorResult<T>>(resolve => this.#resolvers.push(resolve));\n      },\n    };\n  }\n}\n\n/**\n * Run a headless MastraCode turn. Returns an {@link MCRun} handle that is\n * async-iterable over controller events and resolves to a {@link RunMCResult}.\n */\nexport function runMC<TState extends Record<string, unknown>>(options: RunMCOptions<TState>): MCRun {\n  const { controller, session } = options;\n  const goal = options.goal;\n  const policy: ResolutionPolicy = options.policy ?? autoApprovePolicy;\n\n  const queue = new EventQueue<AgentControllerEvent>();\n  const acc: MutableResult = { text: '', toolCalls: [], toolResults: [] };\n\n  let timeoutId: ReturnType<typeof setTimeout> | undefined;\n  let timedOut = false;\n  let aborted = false;\n  let maxTurnsExceeded = false;\n  let assistantTurns = 0;\n  let settled = false;\n  let unsubscribe: (() => void) | undefined;\n  let resolveResult!: (r: RunMCResult) => void;\n\n  const result = new Promise<RunMCResult>(resolve => {\n    resolveResult = resolve;\n  });\n\n  function finish(status: RunMCStatus, data: Partial<RunMCResult> = {}): void {\n    if (settled) return;\n    settled = true;\n    if (timeoutId) clearTimeout(timeoutId);\n    unsubscribe?.();\n    queue.close();\n    resolveResult({\n      status,\n      text: acc.text,\n      finishReason: acc.finishReason,\n      usage: acc.usage,\n      toolCalls: acc.toolCalls,\n      toolResults: acc.toolResults,\n      threadId: acc.threadId ?? session.thread.getId() ?? undefined,\n      error: acc.error,\n      exitCode: exitCodeForStatus(status),\n      ...data,\n    });\n  }\n\n  function fail(message: string, name = 'Error'): void {\n    if (!acc.error) acc.error = { name, message };\n    finish('error');\n  }\n\n  function abort(): void {\n    if (settled) return;\n    aborted = true;\n    session.abort();\n  }\n\n  if (options.signal) {\n    if (options.signal.aborted) {\n      // Defer so the caller can attach iteration / result handlers first.\n      queueMicrotask(() => abort());\n    } else {\n      options.signal.addEventListener('abort', () => abort(), { once: true });\n    }\n  }\n\n  function armTimeout(): void {\n    if (!options.timeoutMs || settled) return;\n    if (timeoutId) clearTimeout(timeoutId);\n    timeoutId = setTimeout(() => {\n      timedOut = true;\n      session.abort();\n      if (goal) finish('timeout');\n    }, options.timeoutMs);\n  }\n\n  // Kick off the run asynchronously so the MCRun handle is returned synchronously.\n  void (async () => {\n    armTimeout();\n\n    // --- Config resolution (model / mode / thinking) ---\n    try {\n      if (options.model) {\n        const available = await controller.listAvailableModels();\n        const match = available.find(m => m.id === options.model);\n        if (!match) return fail(`Unknown model: \"${options.model}\"`);\n        if (!match.hasApiKey) {\n          const keyHint = match.apiKeyEnvVar ? ` Set ${match.apiKeyEnvVar} to use this model.` : '';\n          return fail(`Model \"${options.model}\" has no API key configured.${keyHint}`);\n        }\n        await session.model.switch({ modelId: options.model });\n      } else if (options.mode) {\n        const modelId = options.modeDefaults?.[options.mode];\n        if (modelId) {\n          const available = await controller.listAvailableModels();\n          const match = available.find(m => m.id === modelId);\n          if (!match) return fail(`Unknown model \"${modelId}\" configured for mode \"${options.mode}\"`);\n          if (!match.hasApiKey) {\n            const keyHint = match.apiKeyEnvVar ? ` Set ${match.apiKeyEnvVar} to use this model.` : '';\n            return fail(`Model \"${modelId}\" (mode: ${options.mode}) has no API key configured.${keyHint}`);\n          }\n          await session.model.switch({ modelId });\n        }\n        // No configured model for mode → fall through to default (no failure).\n      }\n\n      if (options.thinkingLevel) {\n        await session.state.set({ thinkingLevel: options.thinkingLevel } as unknown as Partial<TState>);\n      }\n    } catch (err) {\n      return fail(`Failed to resolve run config: ${(err as Error).message}`);\n    }\n\n    // --- Subscribe ---\n    unsubscribe = session.subscribe(event => {\n      if (settled) return;\n      if (goal) armTimeout();\n\n      if (event.type === 'tool_approval_required') {\n        let decision: 'approve' | 'deny';\n        try {\n          decision = policy.onToolApproval(event);\n        } catch (err) {\n          fail(`Resolution policy failed: ${(err as Error).message}`);\n          return;\n        }\n        session.respondToToolApproval({\n          decision: decision === 'approve' ? 'approve' : 'decline',\n          toolCallId: event.toolCallId,\n        });\n        queue.push(event);\n        return;\n      }\n\n      if (event.type === 'tool_suspended') {\n        let outcome: ReturnType<ResolutionPolicy['onSuspension']>;\n        try {\n          outcome = policy.onSuspension(event);\n        } catch (err) {\n          fail(`Resolution policy failed: ${(err as Error).message}`);\n          return;\n        }\n        if ('abort' in outcome) {\n          queue.push(event);\n          abort();\n          return;\n        }\n        void session.respondToToolSuspension({ toolCallId: event.toolCallId, resumeData: outcome.resumeData });\n        queue.push(event);\n        return;\n      }\n\n      aggregate(event, acc);\n      queue.push(event);\n\n      if (event.type === 'error' && goal) {\n        finish('error');\n        return;\n      }\n\n      // Count agentic turns (one assistant response = one turn). When the cap is\n      // reached, abort the run; agent_end then resolves as 'max_turns'.\n      if (event.type === 'message_end' && event.message.role === 'assistant' && options.maxTurns !== undefined) {\n        assistantTurns += 1;\n        if (assistantTurns >= options.maxTurns && !maxTurnsExceeded) {\n          maxTurnsExceeded = true;\n          abort();\n        }\n      }\n\n      if (event.type === 'goal_evaluation' && goal && !event.payload.pending) {\n        if (event.payload.status === 'done' || event.payload.status === 'paused') {\n          finish(event.payload.status, {\n            objective: goal.objective,\n            goalEvent: event,\n            reason: event.payload.reason ?? event.payload.results?.[0]?.reason,\n            iterations: event.payload.iteration,\n            maxRuns: event.payload.maxRuns,\n          });\n        }\n        return;\n      }\n\n      if (event.type === 'agent_end') {\n        acc.finishReason = event.reason;\n        // Goal evaluations can arrive after the agent stream ends, so goal runs\n        // remain active until a terminal goal_evaluation is emitted.\n        if (goal) return;\n        if (timedOut) {\n          finish('timeout');\n        } else if (event.reason === 'error') {\n          finish('error');\n        } else if (maxTurnsExceeded && event.reason !== 'complete') {\n          // The cap forced an abort while the agent still had work to do.\n          finish('max_turns');\n        } else if ((event.reason === 'aborted' || aborted) && !maxTurnsExceeded) {\n          finish('aborted');\n        } else {\n          finish('completed');\n        }\n      }\n    });\n\n    // --- Resource id ---\n    try {\n      if (options.resourceId) {\n        await controller.setResourceId(session, { resourceId: options.resourceId });\n      }\n    } catch (err) {\n      return fail(`Failed to set resource id: ${(err as Error).message}`);\n    }\n\n    // --- Thread selection ---\n    try {\n      const thread = options.thread;\n      if (thread?.id) {\n        const resolved = await resolveThread(session, thread.id);\n        if ('error' in resolved) return fail(resolved.error);\n        await session.thread.switch({ threadId: resolved.threadId });\n      } else if (thread?.continueLatest) {\n        const threads = await session.thread.list();\n        if (threads.length > 0) {\n          const sorted = [...threads].sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());\n          await session.thread.switch({ threadId: sorted[0]!.id });\n        }\n      }\n    } catch (err) {\n      return fail(`Failed to select thread: ${(err as Error).message}`);\n    }\n\n    // --- Clone ---\n    if (options.thread?.clone) {\n      try {\n        await session.thread.clone();\n      } catch (err) {\n        return fail(`Failed to clone thread: ${(err as Error).message}`);\n      }\n    }\n\n    // --- Title ---\n    if (options.title) {\n      try {\n        await session.thread.rename({ title: options.title });\n      } catch (err) {\n        return fail(`Failed to set thread title: ${(err as Error).message}`);\n      }\n    }\n\n    // --- Start ---\n    try {\n      if (goal) {\n        const threadId = session.thread.getId();\n        if (!threadId || !(await session.thread.getById({ threadId }))) {\n          await session.thread.create();\n        }\n\n        const goalManager = goal.goalManager ?? new GoalManager();\n        const state = {\n          controller,\n          session,\n          goalManager,\n          pendingNewThread: false,\n          planStartedGoalId: undefined,\n        } as any;\n        const objective = await goalManager.setGoal(state, goal.objective, goal.judgeModelId, goal.maxRuns);\n        if (!objective) return fail('Failed to set goal.');\n\n        const agent = controller.getCurrentAgent(session);\n        const persisted = await agent.getObjective({ threadId: session.thread.getId()! });\n        if (!persisted || persisted.id !== objective.id) {\n          return fail('Failed to persist goal objective before sending goal signal.');\n        }\n\n        await goalManager.saveToThread(state);\n        if (!settled) await session.sendSignal(createGoalReminderSignal(objective)).accepted;\n      } else {\n        if (!options.prompt) return fail('A prompt or goal is required.');\n        await session.sendMessage({ content: options.prompt });\n      }\n    } catch (err) {\n      return fail(`Failed to start run: ${(err as Error).message}`);\n    }\n  })();\n\n  return {\n    result,\n    abort,\n    [Symbol.asyncIterator](): AsyncIterator<AgentControllerEvent> {\n      return queue[Symbol.asyncIterator]();\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/headless/types.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Shared types for the headless / programmatic MastraCode API.
+ *
+ * These types are consumed by the core runner (`runMC`), the resolution policy,
+ * the output formatters, and the CLI adapter. They are intentionally free of any
+ * `process.*` access so the core API is usable from CI / Node code.
+ */
+import type { AgentController, AgentControllerEvent, Session } from '@mastra/core/agent-controller';
+import type { GoalManager } from '../goal-manager.js';
+export type RunMode = 'build' | 'plan' | 'fast';
+export type ThinkingLevel = 'off' | 'low' | 'medium' | 'high' | 'xhigh';
+export declare const VALID_MODES: readonly ["build", "plan", "fast"];
+export declare const VALID_THINKING_LEVELS: readonly ["off", "low", "medium", "high", "xhigh"];
+/**
+ * Named permission modes for non-interactive runs. Maps to a built-in
+ * {@link ResolutionPolicy}:
+ *  - `auto`   — approve every tool and auto-resolve suspensions (the default).
+ *  - `deny`   — refuse every tool approval and abort on any suspension.
+ */
+export type PermissionMode = 'auto' | 'deny';
+export declare const VALID_PERMISSION_MODES: readonly ["auto", "deny"];
+/** How `runMC` should resume `tool_approval_required` and `tool_suspended` events. */
+export interface ResolutionPolicy {
+    /**
+     * Called for every `tool_approval_required` event. Return the decision; the
+     * runner forwards it to `session.respondToToolApproval`.
+     */
+    onToolApproval(event: Extract<AgentControllerEvent, {
+        type: 'tool_approval_required';
+    }>): 'approve' | 'deny';
+    /**
+     * Called for every `tool_suspended` event. Return `resumeData` to resume the
+     * tool, or `{ abort: true }` to abort the run.
+     */
+    onSuspension(event: Extract<AgentControllerEvent, {
+        type: 'tool_suspended';
+    }>): {
+        resumeData: unknown;
+    } | {
+        abort: true;
+    };
+}
+/** Thread selection / mutation options resolved up front by `runMC`. */
+export interface RunMCThreadOptions {
+    /** Resume a specific thread by its exact id. */
+    id?: string;
+    /** Resume the most recently updated thread instead of creating a new one. */
+    continueLatest?: boolean;
+    /** Clone the resolved (or current) thread before running — work on a copy. */
+    clone?: boolean;
+}
+interface RunMCBaseOptions<TState extends Record<string, unknown> = Record<string, unknown>> {
+    /** Controller built via `createMastraCode(...)`. */
+    controller: AgentController<TState>;
+    /** Session built via `createMastraCode(...)`. */
+    session: Session<TState>;
+    /** Explicit model id override. Takes precedence over `mode`. */
+    model?: string;
+    /** Execution mode; resolves a model from `modeDefaults` when `model` is absent. */
+    mode?: RunMode;
+    /** Per-mode default model ids (resolved from settings at startup). */
+    modeDefaults?: Record<string, string>;
+    /** Thinking-effort level. */
+    thinkingLevel?: ThinkingLevel;
+    /** Thread selection / mutation. */
+    thread?: RunMCThreadOptions;
+    /** Resource id for thread scoping. */
+    resourceId?: string;
+    /** Set or rename the thread title before running. */
+    title?: string;
+    /** Abort with `status: 'timeout'` (exit code 2) after this many ms without an event. */
+    timeoutMs?: number;
+    /**
+     * Maximum number of agentic turns (assistant responses). When the limit is
+     * reached the run aborts with `status: 'max_turns'` (exit code 1). No limit
+     * by default.
+     */
+    maxTurns?: number;
+    /** How approvals / suspensions are resolved. Defaults to {@link autoApprovePolicy}. */
+    policy?: ResolutionPolicy;
+    /** External abort signal; aborting it aborts the run. */
+    signal?: AbortSignal;
+}
+export interface RunMCGoalOptions {
+    objective: string;
+    judgeModelId: string;
+    maxRuns: number;
+    goalManager?: GoalManager;
+}
+export type RunMCOptions<TState extends Record<string, unknown> = Record<string, unknown>> = RunMCBaseOptions<TState> & ({
+    /** The task to run as a regular headless turn. */
+    prompt: string;
+    goal?: never;
+} | {
+    prompt?: never;
+    /** Run a persisted goal instead of a regular prompt. */
+    goal: RunMCGoalOptions;
+});
+export type RunMCStatus = 'completed' | 'done' | 'paused' | 'error' | 'aborted' | 'timeout' | 'max_turns';
+export interface RunMCUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+}
+export interface RunMCToolCall {
+    id: string;
+    name: string;
+    args: unknown;
+}
+export interface RunMCToolResult {
+    id: string;
+    name: string;
+    result: unknown;
+    isError: boolean;
+}
+export interface RunMCError {
+    name: string;
+    message: string;
+    stack?: string;
+}
+export interface RunMCResult {
+    status: RunMCStatus;
+    /** Aggregated assistant text across all message_end events. */
+    text: string;
+    /** Goal objective when this was a goal run. */
+    objective?: string;
+    /** Terminal goal evaluation when this was a goal run. */
+    goalEvent?: Extract<AgentControllerEvent, {
+        type: 'goal_evaluation';
+    }>;
+    reason?: string;
+    iterations?: number;
+    maxRuns?: number;
+    /** Underlying finish reason from `agent_end`, when the run finished normally. */
+    finishReason?: string;
+    usage?: RunMCUsage;
+    toolCalls: RunMCToolCall[];
+    toolResults: RunMCToolResult[];
+    threadId?: string;
+    error?: RunMCError;
+    /** 0 success, 1 error/aborted/max_turns, 2 timeout. */
+    exitCode: number;
+}
+/**
+ * A handle to an in-flight `runMC` run. It is async-iterable over controller
+ * events and also resolves to a final {@link RunMCResult} via `result`.
+ *
+ * Both `for await (const e of run)` and `await run.result` work on the same run;
+ * awaiting `result` without iterating still drains events internally.
+ */
+export interface MCRun extends AsyncIterable<AgentControllerEvent> {
+    /** Resolves once the run completes, times out, errors, or is aborted. */
+    result: Promise<RunMCResult>;
+    /** Abort the in-flight run. */
+    abort(): void;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/headless/types.ts"],"names":[],"mappings":"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"}

package/dist/headless/types.js

@@ -0,0 +1,18 @@
+//#region src/headless/types.ts
+const VALID_MODES = [
+	"build",
+	"plan",
+	"fast"
+];
+const VALID_THINKING_LEVELS = [
+	"off",
+	"low",
+	"medium",
+	"high",
+	"xhigh"
+];
+const VALID_PERMISSION_MODES = ["auto", "deny"];
+//#endregion
+export { VALID_MODES, VALID_PERMISSION_MODES, VALID_THINKING_LEVELS };
+
+//# sourceMappingURL=types.js.map

package/dist/headless/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":[],"sources":["../../src/headless/types.ts"],"sourcesContent":["/**\n * Shared types for the headless / programmatic MastraCode API.\n *\n * These types are consumed by the core runner (`runMC`), the resolution policy,\n * the output formatters, and the CLI adapter. They are intentionally free of any\n * `process.*` access so the core API is usable from CI / Node code.\n */\nimport type { AgentController, AgentControllerEvent, Session } from '@mastra/core/agent-controller';\n\nimport type { GoalManager } from '../goal-manager.js';\n\nexport type RunMode = 'build' | 'plan' | 'fast';\nexport type ThinkingLevel = 'off' | 'low' | 'medium' | 'high' | 'xhigh';\n\nexport const VALID_MODES = ['build', 'plan', 'fast'] as const;\nexport const VALID_THINKING_LEVELS = ['off', 'low', 'medium', 'high', 'xhigh'] as const;\n\n/**\n * Named permission modes for non-interactive runs. Maps to a built-in\n * {@link ResolutionPolicy}:\n *  - `auto`   — approve every tool and auto-resolve suspensions (the default).\n *  - `deny`   — refuse every tool approval and abort on any suspension.\n */\nexport type PermissionMode = 'auto' | 'deny';\nexport const VALID_PERMISSION_MODES = ['auto', 'deny'] as const;\n\n/** How `runMC` should resume `tool_approval_required` and `tool_suspended` events. */\nexport interface ResolutionPolicy {\n  /**\n   * Called for every `tool_approval_required` event. Return the decision; the\n   * runner forwards it to `session.respondToToolApproval`.\n   */\n  onToolApproval(event: Extract<AgentControllerEvent, { type: 'tool_approval_required' }>): 'approve' | 'deny';\n  /**\n   * Called for every `tool_suspended` event. Return `resumeData` to resume the\n   * tool, or `{ abort: true }` to abort the run.\n   */\n  onSuspension(\n    event: Extract<AgentControllerEvent, { type: 'tool_suspended' }>,\n  ): { resumeData: unknown } | { abort: true };\n}\n\n/** Thread selection / mutation options resolved up front by `runMC`. */\nexport interface RunMCThreadOptions {\n  /** Resume a specific thread by its exact id. */\n  id?: string;\n  /** Resume the most recently updated thread instead of creating a new one. */\n  continueLatest?: boolean;\n  /** Clone the resolved (or current) thread before running — work on a copy. */\n  clone?: boolean;\n}\n\ninterface RunMCBaseOptions<TState extends Record<string, unknown> = Record<string, unknown>> {\n  /** Controller built via `createMastraCode(...)`. */\n  controller: AgentController<TState>;\n  /** Session built via `createMastraCode(...)`. */\n  session: Session<TState>;\n\n  /** Explicit model id override. Takes precedence over `mode`. */\n  model?: string;\n  /** Execution mode; resolves a model from `modeDefaults` when `model` is absent. */\n  mode?: RunMode;\n  /** Per-mode default model ids (resolved from settings at startup). */\n  modeDefaults?: Record<string, string>;\n  /** Thinking-effort level. */\n  thinkingLevel?: ThinkingLevel;\n  /** Thread selection / mutation. */\n  thread?: RunMCThreadOptions;\n  /** Resource id for thread scoping. */\n  resourceId?: string;\n  /** Set or rename the thread title before running. */\n  title?: string;\n  /** Abort with `status: 'timeout'` (exit code 2) after this many ms without an event. */\n  timeoutMs?: number;\n  /**\n   * Maximum number of agentic turns (assistant responses). When the limit is\n   * reached the run aborts with `status: 'max_turns'` (exit code 1). No limit\n   * by default.\n   */\n  maxTurns?: number;\n  /** How approvals / suspensions are resolved. Defaults to {@link autoApprovePolicy}. */\n  policy?: ResolutionPolicy;\n  /** External abort signal; aborting it aborts the run. */\n  signal?: AbortSignal;\n}\n\nexport interface RunMCGoalOptions {\n  objective: string;\n  judgeModelId: string;\n  maxRuns: number;\n  goalManager?: GoalManager;\n}\n\nexport type RunMCOptions<TState extends Record<string, unknown> = Record<string, unknown>> = RunMCBaseOptions<TState> &\n  (\n    | {\n        /** The task to run as a regular headless turn. */\n        prompt: string;\n        goal?: never;\n      }\n    | {\n        prompt?: never;\n        /** Run a persisted goal instead of a regular prompt. */\n        goal: RunMCGoalOptions;\n      }\n  );\n\nexport type RunMCStatus = 'completed' | 'done' | 'paused' | 'error' | 'aborted' | 'timeout' | 'max_turns';\n\nexport interface RunMCUsage {\n  inputTokens?: number;\n  outputTokens?: number;\n  totalTokens?: number;\n}\n\nexport interface RunMCToolCall {\n  id: string;\n  name: string;\n  args: unknown;\n}\n\nexport interface RunMCToolResult {\n  id: string;\n  name: string;\n  result: unknown;\n  isError: boolean;\n}\n\nexport interface RunMCError {\n  name: string;\n  message: string;\n  stack?: string;\n}\n\nexport interface RunMCResult {\n  status: RunMCStatus;\n  /** Aggregated assistant text across all message_end events. */\n  text: string;\n  /** Goal objective when this was a goal run. */\n  objective?: string;\n  /** Terminal goal evaluation when this was a goal run. */\n  goalEvent?: Extract<AgentControllerEvent, { type: 'goal_evaluation' }>;\n  reason?: string;\n  iterations?: number;\n  maxRuns?: number;\n  /** Underlying finish reason from `agent_end`, when the run finished normally. */\n  finishReason?: string;\n  usage?: RunMCUsage;\n  toolCalls: RunMCToolCall[];\n  toolResults: RunMCToolResult[];\n  threadId?: string;\n  error?: RunMCError;\n  /** 0 success, 1 error/aborted/max_turns, 2 timeout. */\n  exitCode: number;\n}\n\n/**\n * A handle to an in-flight `runMC` run. It is async-iterable over controller\n * events and also resolves to a final {@link RunMCResult} via `result`.\n *\n * Both `for await (const e of run)` and `await run.result` work on the same run;\n * awaiting `result` without iterating still drains events internally.\n */\nexport interface MCRun extends AsyncIterable<AgentControllerEvent> {\n  /** Resolves once the run completes, times out, errors, or is aborted. */\n  result: Promise<RunMCResult>;\n  /** Abort the in-flight run. */\n  abort(): void;\n}\n"],"mappings":";AAcA,MAAa,cAAc;CAAC;CAAS;CAAQ;AAAM;AACnD,MAAa,wBAAwB;CAAC;CAAO;CAAO;CAAU;CAAQ;AAAO;AAS7E,MAAa,yBAAyB,CAAC,QAAQ,MAAM"}

package/dist/hooks/config.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Hook configuration loading from filesystem.
+ * Loads from global (~/.mastracode/hooks.json) and project (.mastracode/hooks.json).
+ * Global hooks run first, project hooks append.
+ */
+import type { HooksConfig, HookEventName } from './types.js';
+export declare const VALID_EVENTS: HookEventName[];
+export declare function loadHooksConfig(projectDir: string, configDirName?: string, homeDir?: string): HooksConfig;
+export declare function getProjectHooksPath(projectDir: string, configDirName?: string): string;
+export declare function getGlobalHooksPath(configDirName?: string, homeDir?: string): string;
+//# sourceMappingURL=config.d.ts.map

package/dist/hooks/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/hooks/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,KAAK,EAAE,WAAW,EAAkB,aAAa,EAAE,MAAM,YAAY,CAAC;AAE7E,eAAO,MAAM,YAAY,EAAE,aAAa,EAevC,CAAC;AAEF,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,SAAqB,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,CAQrH;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,SAAqB,GAAG,MAAM,CAElG;AAED,wBAAgB,kBAAkB,CAAC,aAAa,SAAqB,EAAE,OAAO,SAAe,GAAG,MAAM,CAErG"}