@mastra/code-sdk 0.0.0-mastracode-cloud-20260706153555

package/dist/headless/index.js

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

package/dist/headless/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/headless/index.ts"],"sourcesContent":["/**\n * Public headless / programmatic API for MastraCode.\n *\n * Programmatic (CI / Node) usage:\n * ```ts\n * import { createMastraCode } from 'mastracode';\n * import { runMC } from 'mastracode/headless';\n *\n * const { controller, session } = await createMastraCode({ settingsPath });\n * const run = runMC({ controller, session, prompt: 'Fix the bug' });\n * for await (const event of run) { ... } // optional live events\n * const result = await run.result;        // typed RunMCResult\n * ```\n *\n * The CLI adapter (`runMCCli`) wraps the same `createMastraCode` → `runMC` flow.\n */\n\n// Core runner\nexport { runMC } from './run-mc.js';\n\n// Resolution policy\nexport { autoApprovePolicy, denyPolicy, permissionModeToPolicy } from './policy.js';\n\n// Formatters (pure, sink-agnostic)\nexport {\n  formatHuman,\n  formatJsonl,\n  renderTextResult,\n  renderJsonResult,\n  createHumanFormatState,\n  truncate,\n} from './format.js';\nexport type { FormattedOutput, HumanFormatState } from './format.js';\n\n// CLI adapter\nexport { runMCCli, hasHeadlessFlag, parseHeadlessArgs, printHeadlessUsage } from './cli.js';\nexport type { HeadlessArgs, OutputMode } from './cli.js';\n\n// Shared types\nexport type {\n  RunMCOptions,\n  RunMCResult,\n  RunMCStatus,\n  RunMCUsage,\n  RunMCToolCall,\n  RunMCToolResult,\n  RunMCError,\n  RunMCThreadOptions,\n  MCRun,\n  ResolutionPolicy,\n  RunMode,\n  ThinkingLevel,\n  PermissionMode,\n} from './types.js';\nexport { VALID_MODES, VALID_THINKING_LEVELS, VALID_PERMISSION_MODES } from './types.js';\n"],"mappings":"AAkBA,SAAS,aAAa;AAGtB,SAAS,mBAAmB,YAAY,8BAA8B;AAGtE;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAIP,SAAS,UAAU,iBAAiB,mBAAmB,0BAA0B;AAmBjF,SAAS,aAAa,uBAAuB,8BAA8B;","names":[]}

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,38 @@
+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." };
+  }
+};
+const denyPolicy = {
+  onToolApproval(_event) {
+    return "deny";
+  },
+  onSuspension(_event) {
+    return { abort: true };
+  }
+};
+function permissionModeToPolicy(mode) {
+  switch (mode) {
+    case "deny":
+      return denyPolicy;
+    case "auto":
+    default:
+      return autoApprovePolicy;
+  }
+}
+export {
+  autoApprovePolicy,
+  denyPolicy,
+  permissionModeToPolicy
+};
+//# sourceMappingURL=policy.js.map

package/dist/headless/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"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":"AAoBO,MAAM,oBAAsC;AAAA,EACjD,eAAe,QAA+F;AAC5G,WAAO;AAAA,EACT;AAAA,EAEA,aACE,OAC2C;AAC3C,UAAM,UAAW,MAAM,kBAAkB,CAAC;AAE1C,QAAI,MAAM,aAAa,oBAAoB,QAAQ,SAAS,0BAA0B;AACpF,aAAO,EAAE,YAAY,MAAM;AAAA,IAC7B;AAEA,QAAI,MAAM,aAAa,eAAe;AACpC,aAAO,EAAE,YAAY,EAAE,QAAQ,WAAW,EAAE;AAAA,IAC9C;AAEA,WAAO,EAAE,YAAY,iEAAiE;AAAA,EACxF;AACF;AAMO,MAAM,aAA+B;AAAA,EAC1C,eAAe,QAA+F;AAC5G,WAAO;AAAA,EACT;AAAA,EAEA,aACE,QAC2C;AAC3C,WAAO,EAAE,OAAO,KAAK;AAAA,EACvB;AACF;AAGO,SAAS,uBAAuB,MAAwC;AAC7E,UAAQ,MAAM;AAAA,IACZ,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AAAA,IACL;AACE,aAAO;AAAA,EACX;AACF;","names":[]}

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":"AAeA,OAAO,KAAK,EAAE,KAAK,EAAoB,YAAY,EAA4B,MAAM,YAAY,CAAC;AAyIlG;;;GAGG;AACH,wBAAgB,KAAK,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,KAAK,CAqOlG"}

package/dist/headless/run-mc.js

@@ -0,0 +1,296 @@
+import { autoApprovePolicy } from "./policy.js";
+function extractAssistantText(message) {
+  return message.content.filter((c) => c.type === "text").map((c) => c.text).join("");
+}
+function exitCodeForStatus(status) {
+  switch (status) {
+    case "completed":
+      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;
+  }
+}
+async function resolveThread(session, threadId) {
+  const threads = await session.thread.list();
+  const byId = threads.find((t) => t.id === threadId);
+  if (byId) return { threadId: byId.id };
+  return { error: `No thread found with ID "${threadId}"` };
+}
+class EventQueue {
+  #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));
+      }
+    };
+  }
+}
+function runMC(options) {
+  const { controller, session, prompt } = options;
+  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) {
+    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)
+    });
+  }
+  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 });
+    }
+  }
+  void (async () => {
+    if (options.timeoutMs) {
+      timeoutId = setTimeout(() => {
+        timedOut = true;
+        session.abort();
+      }, options.timeoutMs);
+    }
+    try {
+      if (options.model) {
+        const available = await controller.listAvailableModels();
+        const match = available.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 available = await controller.listAvailableModels();
+          const match = available.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 (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;
+        }
+        void session.respondToToolSuspension({ toolCallId: event.toolCallId, resumeData: outcome.resumeData });
+        queue.push(event);
+        return;
+      }
+      aggregate(event, acc);
+      queue.push(event);
+      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 === "agent_end") {
+        acc.finishReason = event.reason;
+        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 {
+      await session.sendMessage({ content: prompt });
+    } catch (err) {
+      return fail(`Failed to send message: ${err.message}`);
+    }
+  })();
+  return {
+    result,
+    abort,
+    [Symbol.asyncIterator]() {
+      return queue[Symbol.asyncIterator]();
+    }
+  };
+}
+export {
+  runMC
+};
+//# sourceMappingURL=run-mc.js.map

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

@@ -0,0 +1 @@
+{"version":3,"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, AgentControllerMessage, Session } from '@mastra/core/agent-controller';\n\nimport { autoApprovePolicy } from './policy.js';\nimport type { MCRun, ResolutionPolicy, RunMCOptions, RunMCResult, RunMCStatus } from './types.js';\n\nfunction extractAssistantText(message: AgentControllerMessage): string {\n  return message.content\n    .filter((c): c is { type: 'text'; text: string } => c.type === 'text')\n    .map(c => c.text)\n    .join('');\n}\n\nfunction exitCodeForStatus(status: RunMCStatus): number {\n  switch (status) {\n    case 'completed':\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, prompt } = options;\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): 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    });\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  // Kick off the run asynchronously so the MCRun handle is returned synchronously.\n  void (async () => {\n    if (options.timeoutMs) {\n      timeoutId = setTimeout(() => {\n        timedOut = true;\n        session.abort();\n      }, options.timeoutMs);\n    }\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\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      // 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 === 'agent_end') {\n        acc.finishReason = event.reason;\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    // --- Send ---\n    try {\n      await session.sendMessage({ content: prompt });\n    } catch (err) {\n      return fail(`Failed to send message: ${(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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","names":[]}

package/dist/headless/types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * 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';
+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;
+}
+export interface RunMCOptions<TState extends Record<string, unknown> = Record<string, unknown>> {
+    /** Controller built via `createMastraCode(...)`. */
+    controller: AgentController<TState>;
+    /** Session built via `createMastraCode(...)`. */
+    session: Session<TState>;
+    /** The task to run. */
+    prompt: string;
+    /** 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) if not complete within this many ms. */
+    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 type RunMCStatus = 'completed' | '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;
+    /** 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;
+}
+//# 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,9 @@
+const VALID_MODES = ["build", "plan", "fast"];
+const VALID_THINKING_LEVELS = ["off", "low", "medium", "high", "xhigh"];
+const VALID_PERMISSION_MODES = ["auto", "deny"];
+export {
+  VALID_MODES,
+  VALID_PERMISSION_MODES,
+  VALID_THINKING_LEVELS
+};
+//# sourceMappingURL=types.js.map

package/dist/headless/types.js.map

@@ -0,0 +1 @@
+{"version":3,"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\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\nexport interface RunMCOptions<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  /** The task to run. */\n  prompt: string;\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) if not complete within this many ms. */\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 type RunMCStatus = 'completed' | '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  /** 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":"AAYO,MAAM,cAAc,CAAC,SAAS,QAAQ,MAAM;AAC5C,MAAM,wBAAwB,CAAC,OAAO,OAAO,UAAU,QAAQ,OAAO;AAStE,MAAM,yBAAyB,CAAC,QAAQ,MAAM;","names":[]}

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"}