@mastra/code-sdk 1.0.3-alpha.1 → 1.1.0-alpha.2

package/dist/index.js

@@ -1,765 +1,685 @@
-import { createHash } from "node:crypto";
-import { hostname } from "node:os";
-import path from "node:path";
-import { AgentController } from "@mastra/core/agent-controller";
-import { createCodingAgent } from "@mastra/core/coding-agent";
-import { PROVIDER_REGISTRY } from "@mastra/core/llm";
-import { Mastra } from "@mastra/core/mastra";
-import {
-  AgentsMDInjector,
-  isBadRequestError,
-  PrefillErrorHandler,
-  ProviderHistoryCompat,
-  StreamErrorRetryProcessor
-} from "@mastra/core/processors";
-import { RequestContext } from "@mastra/core/request-context";
-import { TaskSignalProvider } from "@mastra/core/signals";
-import { InMemoryHarness, MastraCompositeStore } from "@mastra/core/storage";
-import { DEFAULT_GOAL_JUDGE_PROMPT } from "@mastra/core/tools";
-import { DuckDBStore } from "@mastra/duckdb";
-import { GithubSignals } from "@mastra/github-signals";
-import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
-import {
-  Observability,
-  MastraStorageExporter,
-  MastraPlatformExporter,
-  SensitiveDataFilter
-} from "@mastra/observability";
-import { PostgresStore } from "@mastra/pg";
+import { validateConfigDirName } from "./constants.js";
+import { detectProject, getObservabilityDatabasePath, getResourceIdOverride, getStorageConfig } from "./utils/project.js";
+import { AuthStorage } from "./auth/storage.js";
+import { setAuthStorage } from "./providers/openai-codex.js";
+import { MASTRA_GATEWAY_PROVIDER, OBSERVABILITY_AUTH_PREFIX, loadSettings, resolveModelDefaults, resolveOmRoleModel, saveSettings } from "./onboarding/settings.js";
 import { hasCredentialStoreProvider } from "./agents/credential-resolver.js";
+import { getDynamicWorkspace, getGoalJudgeTools } from "./agents/workspace.js";
+import { getStaticallyLoadedInstructionPaths } from "./agents/prompts/agent-instructions.js";
 import { getDynamicInstructions } from "./agents/instructions.js";
-import { getDynamicMemory } from "./agents/memory.js";
+import { createAmazonBedrockGateway } from "./providers/amazon-bedrock-gateway.js";
+import { setAuthStorage as setAuthStorage$1 } from "./providers/claude-max.js";
+import { setAuthStorage as setAuthStorage$2 } from "./providers/github-copilot.js";
+import { setAuthStorage as setAuthStorage$3 } from "./providers/xai.js";
 import { createMastraCodeGateway, getDynamicModel, getGoalJudgeModel, resolveModel } from "./agents/model.js";
+import { getDynamicMemory } from "./agents/memory.js";
 import { buildMode } from "./agents/modes/build.js";
 import { fastMode } from "./agents/modes/explore.js";
 import { planMode } from "./agents/modes/plan.js";
-import { getStaticallyLoadedInstructionPaths } from "./agents/prompts/agent-instructions.js";
 import { attachOMThreadStatePersistence, restoreOMThreadStateForCurrentThread } from "./agents/thread-caveman-state.js";
 import { createDynamicTools, createToolHooks } from "./agents/tools.js";
-import { getDynamicWorkspace, getGoalJudgeTools } from "./agents/workspace.js";
-import { AuthStorage } from "./auth/storage.js";
-import { DEFAULT_CONFIG_DIR, validateConfigDirName } from "./constants.js";
-import { createOutcomeScorer, createEfficiencyScorer } from "./evals/scorers/index.js";
-import { HookManager } from "./hooks/index.js";
-import { createMcpManager } from "./mcp/index.js";
-import { getAvailableModePacks, getAvailableOmPacks } from "./onboarding/packs.js";
-import {
-  loadSettings,
-  MASTRA_GATEWAY_PROVIDER,
-  OBSERVABILITY_AUTH_PREFIX,
-  resolveModelDefaults,
-  resolveOmRoleModel,
-  saveSettings
-} from "./onboarding/settings.js";
+import { createOutcomeScorer } from "./evals/scorers/outcome.js";
+import { createEfficiencyScorer } from "./evals/scorers/efficiency.js";
+import "./evals/scorers/index.js";
+import { HookManager } from "./hooks/manager.js";
+import "./hooks/index.js";
+import { createMcpManager } from "./mcp/manager.js";
+import "./mcp/index.js";
+import { hasExplicitOMConfiguration } from "./onboarding/om-settings.js";
+import { getAvailableModePacks, getAvailableOmPacks, selectPreferredOMPack } from "./onboarding/packs.js";
 import { getToolCategory } from "./permissions.js";
 import { PluginManager } from "./plugins/manager.js";
 import { PlanRejectionAbortProcessor } from "./processors/plan-rejection-abort.js";
-import { createAmazonBedrockGateway } from "./providers/amazon-bedrock-gateway.js";
-import { setAuthStorage } from "./providers/claude-max.js";
-import { setAuthStorage as setGitHubCopilotAuthStorage } from "./providers/github-copilot.js";
-import { setAuthStorage as setOpenAIAuthStorage } from "./providers/openai-codex.js";
-import { setAuthStorage as setXAIAuthStorage } from "./providers/xai.js";
 import { stateSchema } from "./schema.js";
 import { mastraBrand } from "./theme-palette.js";
 import { syncGateways } from "./utils/gateway-sync.js";
-import {
-  detectProject,
-  getObservabilityDatabasePath,
-  getStorageConfig,
-  getResourceIdOverride
-} from "./utils/project.js";
 import { createSignalsPubSub } from "./utils/signals-pubsub.js";
+import { DEFAULT_RETENTION, createStorageMaintenance, resolveLocalDbFiles } from "./utils/storage-maintenance.js";
 import { createStorage, createVectorStore } from "./utils/storage-factory.js";
-import { createStorageMaintenance, DEFAULT_RETENTION, resolveLocalDbFiles } from "./utils/storage-maintenance.js";
 import { acquireThreadLock, releaseThreadLock } from "./utils/thread-lock.js";
+import { autoApprovePolicy, denyPolicy, permissionModeToPolicy } from "./headless/policy.js";
+import { runMC } from "./headless/run-mc.js";
+import { formatHuman, formatJsonl, renderJsonResult, renderTextResult } from "./headless/format.js";
+import { hasHeadlessFlag, runMCCli } from "./headless/cli.js";
+import "./headless/index.js";
+import { TaskSignalProvider } from "@mastra/core/signals";
+import { createHash } from "crypto";
+import { hostname } from "os";
+import path from "path";
+import { AgentController } from "@mastra/core/agent-controller";
+import { createCodingAgent } from "@mastra/core/coding-agent";
+import { PROVIDER_REGISTRY } from "@mastra/core/llm";
+import { Mastra } from "@mastra/core/mastra";
+import { AgentsMDInjector, PrefillErrorHandler, ProviderHistoryCompat, StreamErrorRetryProcessor, isBadRequestError } from "@mastra/core/processors";
+import { RequestContext } from "@mastra/core/request-context";
+import { InMemoryHarness, MastraCompositeStore } from "@mastra/core/storage";
+import { DEFAULT_GOAL_JUDGE_PROMPT } from "@mastra/core/tools";
+import { DuckDBStore } from "@mastra/duckdb";
+import { GithubSignals } from "@mastra/github-signals";
+import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
+import { MastraPlatformExporter, MastraStorageExporter, Observability, SensitiveDataFilter } from "@mastra/observability";
+import { PostgresStore } from "@mastra/pg";
+//#region src/index.ts
 const CODE_AGENT_ID = "code-agent";
 const MASTRACODE_TRANSIENT_CONNECTION_MAX_RETRIES = 2;
 const MASTRACODE_TRANSIENT_CONNECTION_RETRY_INITIAL_DELAY_MS = 1e3;
 const MASTRACODE_TRANSIENT_CONNECTION_RETRY_MAX_DELAY_MS = 3e4;
 const TRANSIENT_CONNECTION_ERROR_CODES = /* @__PURE__ */ new Set(["ECONNRESET", "EPIPE"]);
 const TRANSIENT_CONNECTION_MESSAGE_PATTERN = /econnreset|socket hang up|write epipe|other side closed/i;
+/**
+* Matcher for transient connection failures. Cause-chain traversal is handled
+* by `StreamErrorRetryProcessor.isRetryableStreamError`, which calls each
+* matcher at every level of the cause chain.
+*/
 function isTransientConnectionError(error) {
-  if (!error) return false;
-  const code = typeof error === "object" && "code" in error ? error.code : void 0;
-  if (typeof code === "string" && TRANSIENT_CONNECTION_ERROR_CODES.has(code.toUpperCase())) return true;
-  const message = error instanceof Error ? error.message : void 0;
-  if (typeof message === "string" && TRANSIENT_CONNECTION_MESSAGE_PATTERN.test(message)) return true;
-  return false;
+	if (!error) return false;
+	const code = typeof error === "object" && "code" in error ? error.code : void 0;
+	if (typeof code === "string" && TRANSIENT_CONNECTION_ERROR_CODES.has(code.toUpperCase())) return true;
+	const message = error instanceof Error ? error.message : void 0;
+	if (typeof message === "string" && TRANSIENT_CONNECTION_MESSAGE_PATTERN.test(message)) return true;
+	return false;
 }
+/** Short deterministic hash (sha256, first 12 hex chars) matching project.ts shortHash style. */
 function shortHash(input) {
-  return createHash("sha256").update(input).digest("hex").slice(0, 12);
+	return createHash("sha256").update(input).digest("hex").slice(0, 12);
 }
 function applyEffectiveDefaultsToModes(modes, effectiveDefaults) {
-  return modes.map((mode) => {
-    const savedModel = effectiveDefaults[mode.id];
-    if (!savedModel) {
-      return mode;
-    }
-    return {
-      ...mode,
-      defaultModelId: savedModel
-    };
-  });
+	return modes.map((mode) => {
+		const savedModel = effectiveDefaults[mode.id];
+		if (!savedModel) return mode;
+		return {
+			...mode,
+			defaultModelId: savedModel
+		};
+	});
 }
 function addPluginToolsToModeAllowlists(modes, pluginToolNames) {
-  if (pluginToolNames.length === 0) return modes;
-  return modes.map((mode) => {
-    if (!mode.availableTools) return mode;
-    return {
-      ...mode,
-      availableTools: Array.from(/* @__PURE__ */ new Set([...mode.availableTools, ...pluginToolNames]))
-    };
-  });
+	if (pluginToolNames.length === 0) return modes;
+	return modes.map((mode) => {
+		if (!mode.availableTools) return mode;
+		return {
+			...mode,
+			availableTools: Array.from(/* @__PURE__ */ new Set([...mode.availableTools, ...pluginToolNames]))
+		};
+	});
 }
 function createAuthStorage() {
-  const authStorage = new AuthStorage();
-  setAuthStorage(authStorage);
-  setOpenAIAuthStorage(authStorage);
-  setGitHubCopilotAuthStorage(authStorage);
-  setXAIAuthStorage(authStorage);
-  return authStorage;
+	const authStorage = new AuthStorage();
+	setAuthStorage$1(authStorage);
+	setAuthStorage(authStorage);
+	setAuthStorage$2(authStorage);
+	setAuthStorage$3(authStorage);
+	return authStorage;
 }
+/**
+* Resolve cloud observability credentials for the MastraPlatformExporter.
+* Priority: per-resource settings > environment variables > disabled.
+*/
 function resolveCloudObservabilityConfig(settings, authStorage, resourceId) {
-  const resourceConfig = settings.observability.resources[resourceId];
-  if (resourceConfig) {
-    const token = authStorage.getStoredApiKey(`${OBSERVABILITY_AUTH_PREFIX}${resourceId}`);
-    if (token) {
-      return { accessToken: token, projectId: resourceConfig.projectId };
-    }
-  }
-  return {
-    accessToken: process.env.MASTRA_CLOUD_ACCESS_TOKEN,
-    projectId: process.env.MASTRA_PROJECT_ID
-  };
+	const resourceConfig = settings.observability.resources[resourceId];
+	if (resourceConfig) {
+		const token = authStorage.getStoredApiKey(`${OBSERVABILITY_AUTH_PREFIX}${resourceId}`);
+		if (token) return {
+			accessToken: token,
+			projectId: resourceConfig.projectId
+		};
+	}
+	return {
+		accessToken: process.env.MASTRA_CLOUD_ACCESS_TOKEN,
+		projectId: process.env.MASTRA_PROJECT_ID
+	};
 }
+/**
+* Base factory: builds every shared MastraCode resource (storage, observability,
+* memory, MCP, providers, gateways, agent, modes) and the {@link AgentController}, but
+* does NOT call `init()` or create a session. The controller is returned inert so
+* the composition layer can decide its Mastra ownership and session model.
+*
+* See {@link bootLocalAgentController} (Case 3) and `mountAgentControllerOnMastra` (Cases 1 & 2).
+*/
+/**
+* `instanceof` checks against Mastra classes are unreliable here: published
+* packages pin exact `@mastra/core` versions, so a user's dependency graph can
+* contain multiple copies of core (and peer-keyed copies of `@mastra/libsql` /
+* `@mastra/pg`). A store built against one copy fails `instanceof` against
+* another — the injected instance then silently fell through to the
+* StorageConfig path and crashed on `config.url`. These structural checks work
+* across duplicated copies.
+*/
 function isInjectedStorageInstance(storage) {
-  if (!storage) return false;
-  if (storage instanceof MastraCompositeStore) return true;
-  const candidate = storage;
-  return typeof candidate.init === "function" && typeof candidate.__registerMastra === "function";
+	if (!storage) return false;
+	if (storage instanceof MastraCompositeStore) return true;
+	const candidate = storage;
+	return typeof candidate.init === "function" && typeof candidate.__registerMastra === "function";
 }
+/** Cross-copy-safe class check: walks the prototype chain by constructor name. */
 function hasAncestorClassNamed(value, className) {
-  for (let proto = Object.getPrototypeOf(value); proto; proto = Object.getPrototypeOf(proto)) {
-    if (proto.constructor?.name === className) return true;
-  }
-  return false;
+	for (let proto = Object.getPrototypeOf(value); proto; proto = Object.getPrototypeOf(proto)) if (proto.constructor?.name === className) return true;
+	return false;
 }
 function resolveInjectedStorageBackend(storage, configuredBackend) {
-  if (configuredBackend) return configuredBackend;
-  if (storage instanceof LibSQLStore || hasAncestorClassNamed(storage, "LibSQLStore")) return "libsql";
-  if (storage instanceof PostgresStore || hasAncestorClassNamed(storage, "PostgresStore")) return "pg";
-  throw new Error("storageBackend is required when injecting a custom storage instance.");
+	if (configuredBackend) return configuredBackend;
+	if (storage instanceof LibSQLStore || hasAncestorClassNamed(storage, "LibSQLStore")) return "libsql";
+	if (storage instanceof PostgresStore || hasAncestorClassNamed(storage, "PostgresStore")) return "pg";
+	throw new Error("storageBackend is required when injecting a custom storage instance.");
 }
 async function createMastraCodeAgentController(config) {
-  const cwd = config?.cwd ?? process.cwd();
-  const homeDir = config?.homeDir ?? config?.initialState?.homeDir;
-  const configDir = config?.configDir ?? DEFAULT_CONFIG_DIR;
-  let activeSession;
-  if (configDir !== DEFAULT_CONFIG_DIR) {
-    validateConfigDirName(configDir);
-  }
-  try {
-    process.loadEnvFile(path.join(cwd, ".env"));
-  } catch {
-  }
-  const authStorage = createAuthStorage();
-  const globalSettings = loadSettings(config?.settingsPath);
-  const storedGatewayKey = authStorage.getStoredApiKey(MASTRA_GATEWAY_PROVIDER);
-  const storedGatewayUrl = globalSettings.memoryGateway?.baseUrl;
-  if (storedGatewayKey) {
-    process.env["MASTRA_GATEWAY_API_KEY"] ??= storedGatewayKey;
-  }
-  if (storedGatewayUrl) {
-    process.env["MASTRA_GATEWAY_URL"] ??= storedGatewayUrl;
-  }
-  if (!hasCredentialStoreProvider()) {
-    try {
-      const registry = PROVIDER_REGISTRY;
-      const providerEnvVars = {};
-      for (const [provider, cfg] of Object.entries(registry)) {
-        const envVars = cfg?.apiKeyEnvVar;
-        providerEnvVars[provider] = Array.isArray(envVars) ? envVars[0] : envVars;
-      }
-      providerEnvVars[MASTRA_GATEWAY_PROVIDER] ??= "MASTRA_GATEWAY_API_KEY";
-      authStorage.loadStoredApiKeysIntoEnv(providerEnvVars);
-    } catch {
-      authStorage.loadStoredApiKeysIntoEnv({
-        [MASTRA_GATEWAY_PROVIDER]: "MASTRA_GATEWAY_API_KEY",
-        anthropic: "ANTHROPIC_API_KEY",
-        openai: "OPENAI_API_KEY",
-        google: "GOOGLE_GENERATIVE_AI_API_KEY",
-        cerebras: "CEREBRAS_API_KEY",
-        deepseek: "DEEPSEEK_API_KEY"
-      });
-    }
-  }
-  const mgApiKey = process.env["MASTRA_GATEWAY_API_KEY"] ?? storedGatewayKey;
-  const mastraGatewayBaseUrl = (process.env["MASTRA_GATEWAY_URL"] ?? storedGatewayUrl ?? "https://gateway-api.mastra.ai").replace(/\/+$/, "").replace(/\/v1$/, "");
-  const mastraCodeGateway = createMastraCodeGateway({
-    mastraGatewayBaseUrl,
-    mastraGatewayApiKey: mgApiKey,
-    routeThroughMastraGateway: false,
-    settingsPath: config?.settingsPath
-  });
-  const amazonBedrockGateway = createAmazonBedrockGateway();
-  const project = detectProject(cwd);
-  const resourceIdOverride = getResourceIdOverride(project.rootPath, configDir);
-  if (resourceIdOverride) {
-    project.resourceId = resourceIdOverride;
-    project.resourceIdOverride = true;
-  }
-  const sessionId = `mastracode-session-${shortHash(project.resourceId)}`;
-  const ownerId = `mastracode-${shortHash(`${hostname()}\0${project.rootPath}`)}`;
-  const configuredPubSub = config?.pubsub;
-  const useUnixSocketPubSub = (config?.unixSocketPubSub ?? globalSettings.signals?.unixSocketPubSub ?? false) && process.platform !== "win32";
-  const signalsPubSub = configuredPubSub ?? (useUnixSocketPubSub ? createSignalsPubSub(project.resourceId) : void 0);
-  const crossProcessPubSub = config?.crossProcessPubSub ?? (!configuredPubSub && useUnixSocketPubSub);
-  if (crossProcessPubSub && !signalsPubSub) {
-    throw new Error("crossProcessPubSub requires a pubsub instance");
-  }
-  const injectedStorage = isInjectedStorageInstance(config?.storage) ? config.storage : void 0;
-  const storageConfig = injectedStorage ? void 0 : config?.storage ?? getStorageConfig(project.rootPath, globalSettings.storage, configDir);
-  const storageResult = injectedStorage ? { storage: injectedStorage, backend: resolveInjectedStorageBackend(injectedStorage, config?.storageBackend) } : await createStorage(storageConfig);
-  const storageWarning = storageResult.warning;
-  let observabilityDomain;
-  let observabilityWarning;
-  if (globalSettings.observability.localTracing) {
-    try {
-      const observabilityDuckDB = new DuckDBStore({
-        id: "mastra-code-observability",
-        path: getObservabilityDatabasePath()
-      });
-      await observabilityDuckDB.db.getConnection();
-      observabilityDomain = observabilityDuckDB.observability;
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      const isLockError = /lock|locked|busy/i.test(message);
-      if (isLockError) {
-        observabilityWarning = "Observability unavailable \u2014 another MastraCode instance holds the database lock. Traces, scores, and feedback will not be recorded in this session.";
-      } else {
-        observabilityWarning = `Observability unavailable \u2014 DuckDB initialization failed: ${message}`;
-      }
-    }
-  }
-  const harnessStorage = new InMemoryHarness();
-  const storage = new MastraCompositeStore({
-    id: "mastra-code-storage",
-    default: storageResult.storage,
-    domains: {
-      // When local tracing is off, disable the observability domain entirely so
-      // trace/score/feedback writes never fall through to the default libsql store.
-      observability: observabilityDomain ?? false,
-      harness: harnessStorage
-    }
-  });
-  const observability = new Observability({
-    configs: {
-      default: {
-        serviceName: "mastracode",
-        // Only these requestContext keys are stored on spans — prevents leaking
-        // large objects (controller state, workspace, env vars) into trace data.
-        // Use dot-notation because these are nested inside the 'controller' key.
-        //
-        // Session identifiers:
-        //   threadId, resourceId, session.modeId, agentControllerId
-        // Environment & project:
-        //   state.projectName, state.gitBranch
-        // Model configuration:
-        //   session.modelId, state.subagentModelId
-        // Agent settings:
-        //   state.yolo, state.thinkingLevel, state.smartEditing
-        // Observational memory settings:
-        //   state.omScope, state.observerModelId, state.reflectorModelId,
-        //   state.observationThreshold, state.reflectionThreshold
-        requestContextKeys: [
-          // Session identifiers
-          "controller.threadId",
-          "controller.resourceId",
-          "controller.session.modeId",
-          "controller.controllerId",
-          // Environment & project
-          "controller.state.projectName",
-          "controller.state.gitBranch",
-          // Model configuration
-          "controller.session.modelId",
-          "controller.state.subagentModelId",
-          // Agent settings
-          "controller.state.yolo",
-          "controller.state.thinkingLevel",
-          "controller.state.smartEditing",
-          // Observational memory settings
-          "controller.state.omScope",
-          "controller.state.observerModelId",
-          "controller.state.reflectorModelId",
-          "controller.state.observationThreshold",
-          "controller.state.reflectionThreshold"
-        ],
-        exporters: [
-          // Only persist traces locally when DuckDB observability is available
-          // (via `/observability local on`). Without this guard the storage
-          // exporter falls through to the default libsql backend and silently
-          // fills the main database with gigabytes of span data.
-          ...observabilityDomain ? [new MastraStorageExporter({ strategy: "event-sourced" })] : [],
-          new MastraPlatformExporter(resolveCloudObservabilityConfig(globalSettings, authStorage, project.resourceId))
-        ],
-        spanOutputProcessors: [new SensitiveDataFilter()]
-      }
-    }
-  });
-  const vector = config?.vector ?? (storageConfig ? await createVectorStore(storageConfig, storageResult.backend) : void 0);
-  const storageMaintenance = createStorageMaintenance({
-    storage: storageResult.storage,
-    backend: storageResult.backend,
-    retention: DEFAULT_RETENTION,
-    localDbFiles: storageConfig ? resolveLocalDbFiles(storageConfig, storageResult.backend) : [],
-    closeVector: vector instanceof LibSQLVector ? () => vector.close() : void 0
-  });
-  const memory = config?.memory === false ? void 0 : config?.memory ?? getDynamicMemory(storage, vector);
-  const mcpManager = config?.disableMcp ? void 0 : createMcpManager(project.rootPath, configDir, config?.mcpServers);
-  const hookManager = config?.disableHooks ? void 0 : new HookManager(project.rootPath, "session-init", configDir, homeDir);
-  const pluginManager = config?.disablePlugins ? void 0 : config?.pluginManager ?? new PluginManager({ projectRoot: project.rootPath, configDir, homeDir });
-  const loadedPlugins = pluginManager ? await pluginManager.reload() : [];
-  const pluginTools = pluginManager?.getPluginTools() ?? {};
-  const outcomeScorer = createOutcomeScorer();
-  const efficiencyScorer = createEfficiencyScorer();
-  const githubSignals = globalSettings.signals?.experimentalGithubSignals && !config?.disableGithubSignals ? new GithubSignals({
-    cwd: project.rootPath,
-    gitcrawlCommand: process.env.MASTRACODE_GITCRAWL_BIN ?? process.env.GITCRAWL_BIN ?? process.env.MASTRACODE_GITCRAWL_COMMAND ?? process.env.GITCRAWL_COMMAND,
-    getNotificationStreamOptions: async ({ resourceId, threadId }) => {
-      const session = await controller.getSessionByResource(resourceId) ?? activeSession;
-      const modeId = session.mode.get();
-      const defaultModeModelId = controller.listModes().find((mode) => mode.id === modeId)?.defaultModelId;
-      const modelId = session.model.get() || activeSession?.model.get() || defaultModeModelId || "";
-      const requestContext = new RequestContext();
-      const agentControllerContext = {
-        controllerId: controller.id,
-        state: session.state.get(),
-        getState: () => session.state.get(),
-        setState: (updates) => session.state.set(updates),
-        threadId,
-        resourceId,
-        session: {
-          id: session.identity.getId(),
-          ownerId: session.identity.getOwnerId(),
-          modeId,
-          modelId,
-          state: {
-            get: () => session.state.get(),
-            set: (updates) => session.state.set(updates),
-            update: (updater) => session.state.update(updater)
-          }
-        },
-        workspace: controller.getWorkspace(),
-        getSubagentModelId: (params) => session.subagents.model.get(params ?? {})
-      };
-      requestContext.set("controller", agentControllerContext);
-      return {
-        memory: { thread: threadId, resource: resourceId },
-        requestContext,
-        maxSteps: 1e3,
-        savePerStep: false,
-        requireToolApproval: session.state.get().yolo !== true,
-        modelSettings: { temperature: 1 }
-      };
-    }
-  }) : void 0;
-  const codeAgent = createCodingAgent({
-    id: CODE_AGENT_ID,
-    name: "Code Agent",
-    // Workspace is wired per-request at the AgentController level (see
-    // `config.workspace` below), so opt out of the factory's default local
-    // workspace. An explicit `undefined` is required: the factory only builds a
-    // default when the `workspace` key is absent.
-    workspace: void 0,
-    instructions: getDynamicInstructions,
-    model: getDynamicModel,
-    tools: createDynamicTools(mcpManager, config?.extraTools, config?.disabledTools, storage, pluginTools),
-    hooks: createToolHooks(hookManager, config?.postToolObserver),
-    scorers: {
-      outcome: {
-        scorer: outcomeScorer,
-        sampling: { type: "none" }
-      },
-      efficiency: {
-        scorer: efficiencyScorer,
-        sampling: { type: "ratio", rate: 0.3 }
-      }
-    },
-    // TaskSignalProvider bundles the task tools + TaskStateProcessor: it merges
-    // the tools into the toolset and registers the task state-signal processor,
-    // so the task list persists across turns and survives OM truncation.
-    signals: [new TaskSignalProvider(), ...githubSignals ? [githubSignals] : []],
-    // Native goal mechanism: the in-loop goal step judges the thread's active
-    // objective each qualifying iteration. The judge model is required for any
-    // gating to occur; when unset the goal step is a complete no-op. A6 auto-wires
-    // the GoalStateProcessor so the `<current-objective>` signal persists across
-    // turns. Per-thread overrides live in the ThreadState `goal` record and win
-    // over these defaults.
-    goal: {
-      // Resolve the judge model through mastracode's gateway (a model-resolver
-      // function) so provider credentials are injected; returns undefined when no
-      // judge model is configured, keeping the goal step a no-op. Bind the same
-      // `settingsPath` used above so the judge model and `maxRuns` come from one
-      // config (a custom settings file would otherwise diverge).
-      judge: (ctx) => getGoalJudgeModel(ctx, config?.settingsPath),
-      maxRuns: globalSettings.models.goalMaxTurns ?? 50,
-      maxSteps: 1e3,
-      prompt: DEFAULT_GOAL_JUDGE_PROMPT,
-      // Read-only workspace tools the default goal judge may call to verify the
-      // agent's work against the actual filesystem (view, search_content,
-      // find_files, file_stat, lsp_inspect) rather than grading prose alone —
-      // restoring the original MastraCode judge's verification ability. Resolved
-      // per-request from the active workspace (mirrors `judge`).
-      tools: getGoalJudgeTools
-    },
-    inputProcessors: [
-      ...config?.inputProcessors ?? [],
-      new PlanRejectionAbortProcessor(),
-      new AgentsMDInjector({
-        getIgnoredInstructionPaths: ({ requestContext }) => {
-          const agentControllerContext = requestContext?.get("controller");
-          const state = agentControllerContext?.getState();
-          return getStaticallyLoadedInstructionPaths(state?.projectPath ?? project.rootPath);
-        }
-      }),
-      new ProviderHistoryCompat()
-    ],
-    errorProcessors: [
-      // ProviderHistoryCompat must run before StreamErrorRetryProcessor: both react to
-      // HTTP 400s, but ProviderHistoryCompat repairs the incompatible history (e.g.
-      // sanitizing tool-call IDs) before retrying, while StreamErrorRetryProcessor's
-      // isBadRequestError matcher retries the identical request. Error processors
-      // short-circuit on the first `retry: true`, so a blind retry first would resend
-      // the broken history and fail again.
-      new ProviderHistoryCompat(),
-      new StreamErrorRetryProcessor({
-        matchers: [
-          { match: isBadRequestError, maxRetries: 1, delayMs: 2e3 },
-          {
-            match: isTransientConnectionError,
-            maxRetries: MASTRACODE_TRANSIENT_CONNECTION_MAX_RETRIES,
-            delayMs: ({ retryCount }) => Math.min(
-              MASTRACODE_TRANSIENT_CONNECTION_RETRY_INITIAL_DELAY_MS * Math.pow(2, retryCount),
-              MASTRACODE_TRANSIENT_CONNECTION_RETRY_MAX_DELAY_MS
-            )
-          }
-        ]
-      }),
-      new PrefillErrorHandler()
-    ]
-  });
-  const defaultModes = [
-    {
-      ...buildMode,
-      metadata: {
-        ...buildMode.metadata,
-        color: mastraBrand.green
-      }
-    },
-    {
-      ...planMode,
-      metadata: {
-        ...planMode.metadata,
-        color: mastraBrand.purple
-      }
-    },
-    {
-      ...fastMode,
-      metadata: {
-        ...fastMode.metadata,
-        color: mastraBrand.orange
-      }
-    }
-  ];
-  const defaultIntervalHandlers = [
-    {
-      id: "gateway-sync",
-      intervalMs: 5 * 60 * 1e3,
-      immediate: false,
-      handler: () => syncGateways()
-    }
-  ];
-  const intervalHandlers = config?.intervalHandlers ?? defaultIntervalHandlers;
-  const anthropicCred = authStorage.get("anthropic");
-  const openaiCred = authStorage.get("openai-codex");
-  const githubCopilotCred = authStorage.get("github-copilot");
-  const startupAccess = {
-    anthropic: anthropicCred?.type === "oauth" ? "oauth" : anthropicCred?.type === "api_key" && anthropicCred.key.trim().length > 0 ? "apikey" : false,
-    openai: openaiCred?.type === "oauth" ? "oauth" : openaiCred?.type === "api_key" && openaiCred.key.trim().length > 0 ? "apikey" : false,
-    cerebras: process.env.CEREBRAS_API_KEY ? "apikey" : false,
-    google: process.env.GOOGLE_GENERATIVE_AI_API_KEY ? "apikey" : false,
-    deepseek: process.env.DEEPSEEK_API_KEY ? "apikey" : false,
-    "github-copilot": githubCopilotCred?.type === "oauth" ? "oauth" : false
-  };
-  if (mgApiKey) {
-    if (!startupAccess.anthropic) startupAccess.anthropic = "apikey";
-    if (!startupAccess.openai) startupAccess.openai = "apikey";
-  }
-  try {
-    const registry = PROVIDER_REGISTRY;
-    for (const [provider, config2] of Object.entries(registry)) {
-      if (startupAccess[provider] === "oauth" || startupAccess[provider] === "apikey") continue;
-      if (provider === "anthropic" || provider === "openai") continue;
-      const envVars = config2?.apiKeyEnvVar;
-      const envVarList = Array.isArray(envVars) ? envVars : envVars ? [envVars] : [];
-      if (envVarList.some((envVar) => process.env[envVar])) {
-        startupAccess[provider] = "apikey";
-      }
-    }
-  } catch {
-  }
-  const builtinPacks = getAvailableModePacks(startupAccess);
-  const builtinOmPacks = getAvailableOmPacks(startupAccess);
-  const effectiveDefaults = resolveModelDefaults(globalSettings, builtinPacks);
-  const effectiveObserverModel = resolveOmRoleModel(globalSettings, "observer", builtinOmPacks);
-  const effectiveReflectorModel = resolveOmRoleModel(globalSettings, "reflector", builtinOmPacks);
-  const effectiveObservationThreshold = globalSettings.models.omObservationThreshold ?? void 0;
-  const effectiveReflectionThreshold = globalSettings.models.omReflectionThreshold ?? void 0;
-  const effectiveCavemanObservations = globalSettings.models.omCavemanObservations ?? void 0;
-  const effectiveObserveAttachments = globalSettings.models.omObserveAttachments ?? "auto";
-  const modes = addPluginToolsToModeAllowlists(
-    applyEffectiveDefaultsToModes(config?.modes ? config.modes : defaultModes, effectiveDefaults),
-    Object.keys(pluginTools)
-  );
-  const defaultModeId = modes.find((mode) => mode.metadata?.default === true)?.id ?? modes.find((mode) => mode.id === "build")?.id ?? modes[0]?.id;
-  if (!defaultModeId) {
-    throw new Error("MastraCode requires at least one mode");
-  }
-  const globalInitialState = {};
-  if (!config?.disableSettingsOmSeed) {
-    if (effectiveObserverModel) {
-      globalInitialState.observerModelId = effectiveObserverModel;
-    }
-    if (effectiveReflectorModel) {
-      globalInitialState.reflectorModelId = effectiveReflectorModel;
-    }
-    if (effectiveObservationThreshold !== void 0) {
-      globalInitialState.observationThreshold = effectiveObservationThreshold;
-    }
-    if (effectiveReflectionThreshold !== void 0) {
-      globalInitialState.reflectionThreshold = effectiveReflectionThreshold;
-    }
-    if (effectiveCavemanObservations !== void 0) {
-      globalInitialState.cavemanObservations = effectiveCavemanObservations;
-    }
-    if (effectiveObserveAttachments !== void 0) {
-      globalInitialState.observeAttachments = effectiveObserveAttachments;
-    }
-  }
-  if (globalSettings.preferences.yolo !== null) {
-    globalInitialState.yolo = globalSettings.preferences.yolo;
-  }
-  globalInitialState.thinkingLevel = globalSettings.preferences.thinkingLevel;
-  if (config?.omScope) {
-    globalInitialState.omScope = config.omScope;
-  }
-  for (const [key, modelId] of Object.entries(globalSettings.models.subagentModels)) {
-    if (key === "default" || key === "_default") {
-      globalInitialState.subagentModelId = modelId;
-    } else {
-      globalInitialState[`subagentModelId_${key}`] = modelId;
-    }
-  }
-  const typedStateSchema = stateSchema;
-  const controller = new AgentController({
-    id: "mastra-code",
-    resourceId: project.resourceId,
-    storage,
-    observability,
-    memory,
-    pubsub: signalsPubSub,
-    stateSchema: typedStateSchema,
-    agent: codeAgent,
-    subagents: config?.subagents ?? [],
-    gateways: [amazonBedrockGateway, mastraCodeGateway],
-    workspace: config?.workspace ?? ((args) => getDynamicWorkspace(args)),
-    browser: config?.browser,
-    idGenerator: config?.idGenerator,
-    toolCategoryResolver: getToolCategory,
-    initialState: {
-      projectPath: project.rootPath,
-      projectName: project.name,
-      gitBranch: project.gitBranch,
-      pluginSkillPaths: loadedPlugins.flatMap((plugin) => plugin.status === "active" ? plugin.skillPaths ?? [] : []),
-      pluginCommandPaths: loadedPlugins.flatMap(
-        (plugin) => plugin.status === "active" ? plugin.commandPaths ?? [] : []
-      ),
-      pluginInstructions: loadedPlugins.flatMap(
-        (plugin) => plugin.status === "active" && plugin.instructions ? [plugin.instructions] : []
-      ),
-      yolo: true,
-      ...globalInitialState,
-      ...config?.initialState,
-      // configDir must always win over initialState spreads to stay in sync
-      // with MCP/hooks/storage which were already initialized with this value.
-      configDir
-    },
-    modes,
-    intervalHandlers,
-    modelUseCountProvider: () => loadSettings().modelUseCounts,
-    modelUseCountTracker: (modelId) => {
-      try {
-        const settings = loadSettings();
-        settings.modelUseCounts[modelId] = (settings.modelUseCounts[modelId] ?? 0) + 1;
-        saveSettings(settings);
-      } catch (error) {
-        console.error("Failed to persist model usage count", error);
-      }
-    },
-    threadLock: crossProcessPubSub ? void 0 : {
-      acquire: acquireThreadLock,
-      release: releaseThreadLock
-    }
-  });
-  return {
-    controller,
-    storage,
-    storageMaintenance,
-    observability,
-    memory,
-    mcpManager,
-    hookManager,
-    pluginManager,
-    loadedPlugins,
-    pluginTools,
-    signalsPubSub,
-    authStorage,
-    resolveModel,
-    storageWarning,
-    observabilityWarning,
-    builtinPacks,
-    builtinOmPacks,
-    effectiveDefaults,
-    githubSignals,
-    // Identity for the single local session (Case 3). Servers ignore these and
-    // mint per-request sessions with client-supplied resourceIds instead.
-    sessionId,
-    ownerId,
-    // Lets the composition layer publish the created session back into the
-    // config closures (e.g. notification stream options read it lazily).
-    setActiveSession: (session) => {
-      activeSession = session;
-    }
-  };
+	const cwd = config?.cwd ?? process.cwd();
+	const homeDir = config?.homeDir ?? config?.initialState?.homeDir;
+	const configDir = config?.configDir ?? ".mastracode";
+	let activeSession;
+	if (configDir !== ".mastracode") validateConfigDirName(configDir);
+	try {
+		process.loadEnvFile(path.join(cwd, ".env"));
+	} catch {}
+	const authStorage = createAuthStorage();
+	const globalSettings = loadSettings(config?.settingsPath);
+	const storedGatewayKey = authStorage.getStoredApiKey(MASTRA_GATEWAY_PROVIDER);
+	const storedGatewayUrl = globalSettings.memoryGateway?.baseUrl;
+	if (storedGatewayKey) process.env["MASTRA_GATEWAY_API_KEY"] ??= storedGatewayKey;
+	if (storedGatewayUrl) process.env["MASTRA_GATEWAY_URL"] ??= storedGatewayUrl;
+	if (!hasCredentialStoreProvider()) try {
+		const registry = PROVIDER_REGISTRY;
+		const providerEnvVars = {};
+		for (const [provider, cfg] of Object.entries(registry)) {
+			const envVars = cfg?.apiKeyEnvVar;
+			providerEnvVars[provider] = Array.isArray(envVars) ? envVars[0] : envVars;
+		}
+		providerEnvVars[MASTRA_GATEWAY_PROVIDER] ??= "MASTRA_GATEWAY_API_KEY";
+		authStorage.loadStoredApiKeysIntoEnv(providerEnvVars);
+	} catch {
+		authStorage.loadStoredApiKeysIntoEnv({
+			[MASTRA_GATEWAY_PROVIDER]: "MASTRA_GATEWAY_API_KEY",
+			anthropic: "ANTHROPIC_API_KEY",
+			openai: "OPENAI_API_KEY",
+			google: "GOOGLE_GENERATIVE_AI_API_KEY",
+			cerebras: "CEREBRAS_API_KEY",
+			deepseek: "DEEPSEEK_API_KEY"
+		});
+	}
+	const mgApiKey = process.env["MASTRA_GATEWAY_API_KEY"] ?? storedGatewayKey;
+	const mastraCodeGateway = createMastraCodeGateway({
+		mastraGatewayBaseUrl: (process.env["MASTRA_GATEWAY_URL"] ?? storedGatewayUrl ?? "https://gateway-api.mastra.ai").replace(/\/+$/, "").replace(/\/v1$/, ""),
+		mastraGatewayApiKey: mgApiKey,
+		routeThroughMastraGateway: false,
+		settingsPath: config?.settingsPath
+	});
+	const amazonBedrockGateway = createAmazonBedrockGateway();
+	const project = detectProject(cwd);
+	const resourceIdOverride = getResourceIdOverride(project.rootPath, configDir);
+	if (resourceIdOverride) {
+		project.resourceId = resourceIdOverride;
+		project.resourceIdOverride = true;
+	}
+	const sessionId = `mastracode-session-${shortHash(project.resourceId)}`;
+	const ownerId = `mastracode-${shortHash(`${hostname()}\0${project.rootPath}`)}`;
+	const configuredPubSub = config?.pubsub;
+	const useUnixSocketPubSub = (config?.unixSocketPubSub ?? globalSettings.signals?.unixSocketPubSub ?? false) && process.platform !== "win32";
+	const signalsPubSub = configuredPubSub ?? (useUnixSocketPubSub ? createSignalsPubSub(project.resourceId) : void 0);
+	const crossProcessPubSub = config?.crossProcessPubSub ?? (!configuredPubSub && useUnixSocketPubSub);
+	if (crossProcessPubSub && !signalsPubSub) throw new Error("crossProcessPubSub requires a pubsub instance");
+	const injectedStorage = isInjectedStorageInstance(config?.storage) ? config.storage : void 0;
+	const storageConfig = injectedStorage ? void 0 : config?.storage ?? getStorageConfig(project.rootPath, globalSettings.storage, configDir);
+	const storageResult = injectedStorage ? {
+		storage: injectedStorage,
+		backend: resolveInjectedStorageBackend(injectedStorage, config?.storageBackend)
+	} : await createStorage(storageConfig);
+	const storageWarning = storageResult.warning;
+	let observabilityDomain;
+	let observabilityWarning;
+	if (globalSettings.observability.localTracing) try {
+		const observabilityDuckDB = new DuckDBStore({
+			id: "mastra-code-observability",
+			path: getObservabilityDatabasePath()
+		});
+		await observabilityDuckDB.db.getConnection();
+		observabilityDomain = observabilityDuckDB.observability;
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		if (/lock|locked|busy/i.test(message)) observabilityWarning = "Observability unavailable — another MastraCode instance holds the database lock. Traces, scores, and feedback will not be recorded in this session.";
+		else observabilityWarning = `Observability unavailable — DuckDB initialization failed: ${message}`;
+	}
+	const harnessStorage = new InMemoryHarness();
+	const storage = new MastraCompositeStore({
+		id: "mastra-code-storage",
+		default: storageResult.storage,
+		domains: {
+			observability: observabilityDomain ?? false,
+			harness: harnessStorage
+		}
+	});
+	const observability = new Observability({ configs: { default: {
+		serviceName: "mastracode",
+		requestContextKeys: [
+			"controller.threadId",
+			"controller.resourceId",
+			"controller.session.modeId",
+			"controller.controllerId",
+			"controller.state.projectName",
+			"controller.state.gitBranch",
+			"controller.session.modelId",
+			"controller.state.subagentModelId",
+			"controller.state.yolo",
+			"controller.state.thinkingLevel",
+			"controller.state.smartEditing",
+			"controller.state.omScope",
+			"controller.state.observerModelId",
+			"controller.state.reflectorModelId",
+			"controller.state.observationThreshold",
+			"controller.state.reflectionThreshold"
+		],
+		exporters: [...observabilityDomain ? [new MastraStorageExporter({ strategy: "event-sourced" })] : [], new MastraPlatformExporter(resolveCloudObservabilityConfig(globalSettings, authStorage, project.resourceId))],
+		spanOutputProcessors: [new SensitiveDataFilter()]
+	} } });
+	const vector = config?.vector ?? (storageConfig ? await createVectorStore(storageConfig, storageResult.backend) : void 0);
+	const storageMaintenance = createStorageMaintenance({
+		storage: storageResult.storage,
+		backend: storageResult.backend,
+		retention: DEFAULT_RETENTION,
+		localDbFiles: storageConfig ? resolveLocalDbFiles(storageConfig, storageResult.backend) : [],
+		closeVector: vector instanceof LibSQLVector ? () => vector.close() : void 0
+	});
+	const memory = config?.memory === false ? void 0 : config?.memory ?? getDynamicMemory(storage, vector);
+	const mcpManager = config?.disableMcp ? void 0 : createMcpManager(project.rootPath, configDir, config?.mcpServers);
+	const hookManager = config?.disableHooks ? void 0 : new HookManager(project.rootPath, "session-init", configDir, homeDir);
+	const pluginManager = config?.disablePlugins ? void 0 : config?.pluginManager ?? new PluginManager({
+		projectRoot: project.rootPath,
+		configDir,
+		homeDir
+	});
+	const loadedPlugins = pluginManager ? await pluginManager.reload() : [];
+	const pluginTools = pluginManager?.getPluginTools() ?? {};
+	const outcomeScorer = createOutcomeScorer();
+	const efficiencyScorer = createEfficiencyScorer();
+	const githubSignals = globalSettings.signals?.experimentalGithubSignals && !config?.disableGithubSignals ? new GithubSignals({
+		cwd: project.rootPath,
+		gitcrawlCommand: process.env.MASTRACODE_GITCRAWL_BIN ?? process.env.GITCRAWL_BIN ?? process.env.MASTRACODE_GITCRAWL_COMMAND ?? process.env.GITCRAWL_COMMAND,
+		getNotificationStreamOptions: async ({ resourceId, threadId }) => {
+			const session = await controller.getSessionByResource(resourceId) ?? activeSession;
+			const modeId = session.mode.get();
+			const defaultModeModelId = controller.listModes().find((mode) => mode.id === modeId)?.defaultModelId;
+			const modelId = session.model.get() || activeSession?.model.get() || defaultModeModelId || "";
+			const requestContext = new RequestContext();
+			const agentControllerContext = {
+				controllerId: controller.id,
+				state: session.state.get(),
+				getState: () => session.state.get(),
+				setState: (updates) => session.state.set(updates),
+				threadId,
+				resourceId,
+				session: {
+					id: session.identity.getId(),
+					ownerId: session.identity.getOwnerId(),
+					modeId,
+					modelId,
+					state: {
+						get: () => session.state.get(),
+						set: (updates) => session.state.set(updates),
+						update: (updater) => session.state.update(updater)
+					}
+				},
+				workspace: controller.getWorkspace(),
+				getSubagentModelId: (params) => session.subagents.model.get(params ?? {})
+			};
+			requestContext.set("controller", agentControllerContext);
+			return {
+				memory: {
+					thread: threadId,
+					resource: resourceId
+				},
+				requestContext,
+				maxSteps: 1e3,
+				savePerStep: false,
+				requireToolApproval: session.state.get().yolo !== true,
+				modelSettings: { temperature: 1 }
+			};
+		}
+	}) : void 0;
+	const codeAgent = createCodingAgent({
+		id: CODE_AGENT_ID,
+		name: "Code Agent",
+		workspace: void 0,
+		instructions: getDynamicInstructions,
+		model: getDynamicModel,
+		tools: createDynamicTools(mcpManager, config?.extraTools, config?.disabledTools, storage, pluginTools),
+		hooks: createToolHooks(hookManager, config?.postToolObserver),
+		scorers: {
+			outcome: {
+				scorer: outcomeScorer,
+				sampling: { type: "none" }
+			},
+			efficiency: {
+				scorer: efficiencyScorer,
+				sampling: {
+					type: "ratio",
+					rate: .3
+				}
+			}
+		},
+		signals: [new TaskSignalProvider(), ...githubSignals ? [githubSignals] : []],
+		goal: {
+			judge: (ctx) => getGoalJudgeModel(ctx, config?.settingsPath),
+			maxRuns: globalSettings.models.goalMaxTurns ?? 50,
+			maxSteps: 1e3,
+			prompt: DEFAULT_GOAL_JUDGE_PROMPT,
+			tools: getGoalJudgeTools
+		},
+		inputProcessors: [
+			...config?.inputProcessors ?? [],
+			new PlanRejectionAbortProcessor(),
+			new AgentsMDInjector({ getIgnoredInstructionPaths: ({ requestContext }) => {
+				const state = (requestContext?.get("controller"))?.getState();
+				return getStaticallyLoadedInstructionPaths(state?.projectPath ?? project.rootPath);
+			} }),
+			new ProviderHistoryCompat()
+		],
+		errorProcessors: [
+			new ProviderHistoryCompat(),
+			new StreamErrorRetryProcessor({ matchers: [{
+				match: isBadRequestError,
+				maxRetries: 1,
+				delayMs: 2e3
+			}, {
+				match: isTransientConnectionError,
+				maxRetries: MASTRACODE_TRANSIENT_CONNECTION_MAX_RETRIES,
+				delayMs: ({ retryCount }) => Math.min(MASTRACODE_TRANSIENT_CONNECTION_RETRY_INITIAL_DELAY_MS * Math.pow(2, retryCount), MASTRACODE_TRANSIENT_CONNECTION_RETRY_MAX_DELAY_MS)
+			}] }),
+			new PrefillErrorHandler()
+		]
+	});
+	const defaultModes = [
+		{
+			...buildMode,
+			metadata: {
+				...buildMode.metadata,
+				color: mastraBrand.green
+			}
+		},
+		{
+			...planMode,
+			metadata: {
+				...planMode.metadata,
+				color: mastraBrand.purple
+			}
+		},
+		{
+			...fastMode,
+			metadata: {
+				...fastMode.metadata,
+				color: mastraBrand.orange
+			}
+		}
+	];
+	const intervalHandlers = config?.intervalHandlers ?? [{
+		id: "gateway-sync",
+		intervalMs: 300 * 1e3,
+		immediate: false,
+		handler: () => syncGateways()
+	}];
+	const anthropicCred = authStorage.get("anthropic");
+	const openaiCred = authStorage.get("openai-codex");
+	const githubCopilotCred = authStorage.get("github-copilot");
+	const startupAccess = {
+		anthropic: anthropicCred?.type === "oauth" ? "oauth" : anthropicCred?.type === "api_key" && anthropicCred.key.trim().length > 0 ? "apikey" : false,
+		openai: openaiCred?.type === "oauth" ? "oauth" : openaiCred?.type === "api_key" && openaiCred.key.trim().length > 0 ? "apikey" : false,
+		cerebras: process.env.CEREBRAS_API_KEY ? "apikey" : false,
+		google: process.env.GOOGLE_GENERATIVE_AI_API_KEY ? "apikey" : false,
+		deepseek: process.env.DEEPSEEK_API_KEY ? "apikey" : false,
+		"github-copilot": githubCopilotCred?.type === "oauth" ? "oauth" : false
+	};
+	if (mgApiKey) {
+		if (!startupAccess.anthropic) startupAccess.anthropic = "apikey";
+		if (!startupAccess.openai) startupAccess.openai = "apikey";
+	}
+	try {
+		const registry = PROVIDER_REGISTRY;
+		for (const [provider, config] of Object.entries(registry)) {
+			if (startupAccess[provider] === "oauth" || startupAccess[provider] === "apikey") continue;
+			if (provider === "anthropic" || provider === "openai") continue;
+			const envVars = config?.apiKeyEnvVar;
+			if ((Array.isArray(envVars) ? envVars : envVars ? [envVars] : []).some((envVar) => process.env[envVar])) startupAccess[provider] = "apikey";
+		}
+	} catch {}
+	const builtinPacks = getAvailableModePacks(startupAccess);
+	const builtinOmPacks = getAvailableOmPacks(startupAccess);
+	const effectiveDefaults = resolveModelDefaults(globalSettings, builtinPacks);
+	const activeProviderId = effectiveDefaults.build?.split("/")[0];
+	const preferredOmModel = hasExplicitOMConfiguration(globalSettings) ? void 0 : selectPreferredOMPack(startupAccess, activeProviderId)?.modelId;
+	const effectiveObserverModel = resolveOmRoleModel(globalSettings, "observer", builtinOmPacks) || preferredOmModel;
+	const effectiveReflectorModel = resolveOmRoleModel(globalSettings, "reflector", builtinOmPacks) || preferredOmModel;
+	const effectiveObservationThreshold = globalSettings.models.omObservationThreshold ?? void 0;
+	const effectiveReflectionThreshold = globalSettings.models.omReflectionThreshold ?? void 0;
+	const effectiveCavemanObservations = globalSettings.models.omCavemanObservations ?? void 0;
+	const effectiveObserveAttachments = globalSettings.models.omObserveAttachments ?? "auto";
+	const modes = addPluginToolsToModeAllowlists(applyEffectiveDefaultsToModes(config?.modes ? config.modes : defaultModes, effectiveDefaults), Object.keys(pluginTools));
+	if (!(modes.find((mode) => mode.metadata?.default === true)?.id ?? modes.find((mode) => mode.id === "build")?.id ?? modes[0]?.id)) throw new Error("MastraCode requires at least one mode");
+	const globalInitialState = {};
+	if (!config?.disableSettingsOmSeed) {
+		if (effectiveObserverModel) globalInitialState.observerModelId = effectiveObserverModel;
+		if (effectiveReflectorModel) globalInitialState.reflectorModelId = effectiveReflectorModel;
+		if (effectiveObservationThreshold !== void 0) globalInitialState.observationThreshold = effectiveObservationThreshold;
+		if (effectiveReflectionThreshold !== void 0) globalInitialState.reflectionThreshold = effectiveReflectionThreshold;
+		if (effectiveCavemanObservations !== void 0) globalInitialState.cavemanObservations = effectiveCavemanObservations;
+		if (effectiveObserveAttachments !== void 0) globalInitialState.observeAttachments = effectiveObserveAttachments;
+	}
+	if (globalSettings.preferences.yolo !== null) globalInitialState.yolo = globalSettings.preferences.yolo;
+	globalInitialState.thinkingLevel = globalSettings.preferences.thinkingLevel;
+	if (config?.omScope) globalInitialState.omScope = config.omScope;
+	for (const [key, modelId] of Object.entries(globalSettings.models.subagentModels)) if (key === "default" || key === "_default") globalInitialState.subagentModelId = modelId;
+	else globalInitialState[`subagentModelId_${key}`] = modelId;
+	const typedStateSchema = stateSchema;
+	const controller = new AgentController({
+		id: "mastra-code",
+		resourceId: project.resourceId,
+		storage,
+		observability,
+		memory,
+		pubsub: signalsPubSub,
+		stateSchema: typedStateSchema,
+		agent: codeAgent,
+		subagents: config?.subagents ?? [],
+		gateways: [amazonBedrockGateway, mastraCodeGateway],
+		workspace: config?.workspace ?? ((args) => getDynamicWorkspace(args)),
+		browser: config?.browser,
+		idGenerator: config?.idGenerator,
+		toolCategoryResolver: getToolCategory,
+		initialState: {
+			projectPath: project.rootPath,
+			projectName: project.name,
+			gitBranch: project.gitBranch,
+			pluginSkillPaths: loadedPlugins.flatMap((plugin) => plugin.status === "active" ? plugin.skillPaths ?? [] : []),
+			pluginCommandPaths: loadedPlugins.flatMap((plugin) => plugin.status === "active" ? plugin.commandPaths ?? [] : []),
+			pluginInstructions: loadedPlugins.flatMap((plugin) => plugin.status === "active" && plugin.instructions ? [plugin.instructions] : []),
+			yolo: true,
+			...globalInitialState,
+			...config?.initialState,
+			configDir
+		},
+		modes,
+		intervalHandlers,
+		modelUseCountProvider: () => loadSettings().modelUseCounts,
+		modelUseCountTracker: (modelId) => {
+			try {
+				const settings = loadSettings();
+				settings.modelUseCounts[modelId] = (settings.modelUseCounts[modelId] ?? 0) + 1;
+				saveSettings(settings);
+			} catch (error) {
+				console.error("Failed to persist model usage count", error);
+			}
+		},
+		threadLock: crossProcessPubSub ? void 0 : {
+			acquire: acquireThreadLock,
+			release: releaseThreadLock
+		}
+	});
+	return {
+		controller,
+		storage,
+		storageMaintenance,
+		observability,
+		memory,
+		mcpManager,
+		hookManager,
+		pluginManager,
+		loadedPlugins,
+		pluginTools,
+		signalsPubSub,
+		authStorage,
+		resolveModel,
+		storageWarning,
+		observabilityWarning,
+		builtinPacks,
+		builtinOmPacks,
+		effectiveDefaults,
+		githubSignals,
+		sessionId,
+		ownerId,
+		setActiveSession: (session) => {
+			activeSession = session;
+		}
+	};
 }
+/**
+* Wires the session-scoped concerns MastraCode layers on top of a Session:
+* hookManager thread-id sync, GitHub PR polling for the current thread, and
+* per-thread persistence of the mastracode-only `/om` settings.
+*
+* Used by {@link bootLocalAgentController} for the single local session. A server can
+* call this for any session it mints if it wants the same background wiring.
+*/
 async function wireSessionConcerns(base, session) {
-  const { hookManager, githubSignals } = base;
-  base.setActiveSession(session);
-  if (hookManager) {
-    session.subscribe((event) => {
-      if (event.type === "thread_changed") {
-        hookManager.setSessionId(event.threadId);
-      } else if (event.type === "thread_created") {
-        hookManager.setSessionId(event.thread.id);
-      }
-    });
-  }
-  if (githubSignals) {
-    const startGithubPollingForCurrentThread = async (threadId) => {
-      if (!threadId) return;
-      githubSignals.stopAllPolling();
-      try {
-        const threads = await session.thread.list({ allResources: true });
-        const thread = threads.find((item) => item.id === threadId);
-        await githubSignals.startPollingForThread(
-          {
-            threadId,
-            resourceId: thread?.resourceId ?? session.identity.getResourceId()
-          },
-          { pollImmediately: true }
-        );
-      } catch (error) {
-        console.warn("Failed to start GitHub PR polling:", error);
-      }
-    };
-    session.subscribe((event) => {
-      if (event.type === "thread_changed") void startGithubPollingForCurrentThread(event.threadId);
-      else if (event.type === "thread_created") void startGithubPollingForCurrentThread(event.thread.id);
-    });
-    void startGithubPollingForCurrentThread(session.thread.getId());
-  }
-  const omThreadStateSession = session;
-  attachOMThreadStatePersistence(omThreadStateSession);
-  await restoreOMThreadStateForCurrentThread(omThreadStateSession).catch(() => {
-  });
+	const { hookManager, githubSignals } = base;
+	base.setActiveSession(session);
+	if (hookManager) session.subscribe((event) => {
+		if (event.type === "thread_changed") hookManager.setSessionId(event.threadId);
+		else if (event.type === "thread_created") hookManager.setSessionId(event.thread.id);
+	});
+	if (githubSignals) {
+		const startGithubPollingForCurrentThread = async (threadId) => {
+			if (!threadId) return;
+			githubSignals.stopAllPolling();
+			try {
+				const thread = (await session.thread.list({ allResources: true })).find((item) => item.id === threadId);
+				await githubSignals.startPollingForThread({
+					threadId,
+					resourceId: thread?.resourceId ?? session.identity.getResourceId()
+				}, { pollImmediately: true });
+			} catch (error) {
+				console.warn("Failed to start GitHub PR polling:", error);
+			}
+		};
+		session.subscribe((event) => {
+			if (event.type === "thread_changed") startGithubPollingForCurrentThread(event.threadId);
+			else if (event.type === "thread_created") startGithubPollingForCurrentThread(event.thread.id);
+		});
+		startGithubPollingForCurrentThread(session.thread.getId());
+	}
+	const omThreadStateSession = session;
+	attachOMThreadStatePersistence(omThreadStateSession);
+	await restoreOMThreadStateForCurrentThread(omThreadStateSession).catch(() => {});
 }
+/**
+* Case 3 (AgentController local + TUI/headless): build the controller, let it stand up its
+* own internal Mastra via `init()`, and mint the single eager session that all
+* work in this process runs through. The AgentController owns no session of its own.
+*/
 async function bootLocalAgentController(config) {
-  const base = await createMastraCodeAgentController(config);
-  const { controller, sessionId, ownerId } = base;
-  await controller.init();
-  await controller.getMastra()?.startWorkers();
-  const session = await controller.createSession({ id: sessionId, ownerId });
-  await wireSessionConcerns(base, session);
-  return { ...base, session };
+	const base = await createMastraCodeAgentController(config);
+	const { controller, sessionId, ownerId } = base;
+	await controller.init();
+	await controller.getMastra()?.startWorkers();
+	const session = await controller.createSession({
+		id: sessionId,
+		ownerId
+	});
+	await wireSessionConcerns(base, session);
+	return {
+		...base,
+		session
+	};
 }
+/**
+* Cases 1 & 2 (AgentController in Server + Web/TUI): build the controller, register it on a
+* server-owned Mastra, THEN init it. Registering before `init()` is what makes
+* the controller inherit the server's Mastra (storage, agents, gateways) instead of
+* spinning up its own internal one — there is a single shared Mastra.
+*
+* No eager session is minted: each client (browser or terminal) creates/resumes
+* its own isolated session via `controller.createSession({ resourceId })`, so one
+* server can drive many concurrent users.
+*
+* Pass an existing `mastra` to mount onto a Mastra that already hosts other
+* primitives; otherwise a Mastra is created that owns the controller's storage so
+* durability is configured in one place.
+*/
 async function mountAgentControllerOnMastra(config) {
-  const prepared = await prepareAgentControllerMount(config);
-  if (config?.mastra) {
-    prepared.base.controller.__registerMastra(config.mastra);
-    await prepared.finalize();
-    return { ...prepared.base, mastra: config.mastra };
-  }
-  const mastra = new Mastra(prepared.mastraArgs);
-  await prepared.finalize();
-  return { ...prepared.base, mastra };
+	const prepared = await prepareAgentControllerMount(config);
+	if (config?.mastra) {
+		prepared.base.controller.__registerMastra(config.mastra);
+		await prepared.finalize();
+		return {
+			...prepared.base,
+			mastra: config.mastra
+		};
+	}
+	const mastra = new Mastra(prepared.mastraArgs);
+	await prepared.finalize();
+	return {
+		...prepared.base,
+		mastra
+	};
 }
+/**
+* Assemble everything needed to construct the server-owned Mastra WITHOUT
+* constructing it, so a caller (the platform entry `src/mastra/index.ts`) can
+* run the `new Mastra(...)` literal in its own module. The deployer's
+* `checkConfigExport` Babel plugin only marks the config valid when it finds a
+* top-level `new Mastra(...)` exported as `mastra` in the ENTRY file; hiding the
+* construction inside this helper would trip the "Invalid Mastra config" warning.
+*
+* Returns the constructor args plus a `finalize()` that runs the post-construct
+* boot (`controller.init()` + `startWorkers()`). The controller is registered on
+* the Mastra via the `agentControllers` arg at construction time.
+*/
 async function prepareAgentControllerMount(config) {
-  const base = await createMastraCodeAgentController(config);
-  const { controller, storage, authStorage } = base;
-  const controllerId = config?.controllerId ?? controller.id;
-  const apiRoutes = config?.buildApiRoutes?.({ controller, authStorage });
-  const extraServerConfig = config?.buildServerConfig?.({ controller, authStorage });
-  const serverConfig = {
-    ...extraServerConfig,
-    ...apiRoutes?.length ? { apiRoutes } : {}
-  };
-  const mastraArgs = {
-    agentControllers: { [controllerId]: controller },
-    storage,
-    // Mirror the controller's internal-Mastra construction (which passes
-    // `config.pubsub` through): the server-owned Mastra must run its event
-    // bus on the same transport so streams/workflows/signals stay
-    // cross-process when a distributed PubSub (e.g. Redis Streams) is
-    // configured.
-    ...base.signalsPubSub ? { pubsub: base.signalsPubSub } : {},
-    ...Object.keys(serverConfig).length ? { server: serverConfig } : {}
-  };
-  const finalize = async () => {
-    await controller.init();
-    await controller.getMastra()?.startWorkers();
-  };
-  return { base, mastraArgs, finalize };
+	const base = await createMastraCodeAgentController(config);
+	const { controller, storage, authStorage } = base;
+	const controllerId = config?.controllerId ?? controller.id;
+	const apiRoutes = config?.buildApiRoutes?.({
+		controller,
+		authStorage
+	});
+	const serverConfig = {
+		...config?.buildServerConfig?.({
+			controller,
+			authStorage
+		}),
+		...apiRoutes?.length ? { apiRoutes } : {}
+	};
+	const mastraArgs = {
+		agentControllers: { [controllerId]: controller },
+		storage,
+		...base.signalsPubSub ? { pubsub: base.signalsPubSub } : {},
+		...Object.keys(serverConfig).length ? { server: serverConfig } : {}
+	};
+	const finalize = async () => {
+		await controller.init();
+		await controller.getMastra()?.startWorkers();
+	};
+	return {
+		base,
+		mastraArgs,
+		finalize
+	};
 }
+/**
+* Back-compat alias. Historically `createMastraCode` built and booted a local
+* controller with a single session; that behavior now lives in
+* {@link bootLocalAgentController}. New code should call the explicit factory for its
+* case: `bootLocalAgentController` (local) or {@link mountAgentControllerOnMastra} (server).
+*/
 const createMastraCode = bootLocalAgentController;
-import {
-  runMC,
-  runMCCli,
-  hasHeadlessFlag,
-  autoApprovePolicy,
-  denyPolicy,
-  permissionModeToPolicy,
-  formatHuman,
-  formatJsonl,
-  renderTextResult,
-  renderJsonResult
-} from "./headless/index.js";
-export {
-  autoApprovePolicy,
-  bootLocalAgentController,
-  createAuthStorage,
-  createMastraCode,
-  createMastraCodeAgentController,
-  denyPolicy,
-  formatHuman,
-  formatJsonl,
-  hasHeadlessFlag,
-  mountAgentControllerOnMastra,
-  permissionModeToPolicy,
-  prepareAgentControllerMount,
-  renderJsonResult,
-  renderTextResult,
-  runMC,
-  runMCCli,
-  wireSessionConcerns
-};
+//#endregion
+export { autoApprovePolicy, bootLocalAgentController, createAuthStorage, createMastraCode, createMastraCodeAgentController, denyPolicy, formatHuman, formatJsonl, hasHeadlessFlag, mountAgentControllerOnMastra, permissionModeToPolicy, prepareAgentControllerMount, renderJsonResult, renderTextResult, runMC, runMCCli, wireSessionConcerns };
+
 //# sourceMappingURL=index.js.map