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

package/dist/hooks/types.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Type definitions for the hooks system.
+ * Hooks are user-configured shell commands that run at lifecycle events.
+ */
+export type HookEventName = 'PreToolUse' | 'PostToolUse' | 'Stop' | 'UserPromptSubmit' | 'SessionStart' | 'SessionEnd' | 'Notification' | 'AgentStart' | 'AgentEnd' | 'PermissionRequest' | 'PermissionResult' | 'Interrupt' | 'SubagentStart' | 'SubagentEnd';
+export type BlockingHookEvent = 'PreToolUse' | 'Stop' | 'UserPromptSubmit';
+/** Lifecycle hook events are non-blocking: they observe behavior without changing it. */
+export type LifecycleHookEvent = 'AgentStart' | 'AgentEnd' | 'PermissionRequest' | 'PermissionResult' | 'Interrupt' | 'SubagentStart' | 'SubagentEnd';
+export declare function isBlockingEvent(event: HookEventName): event is BlockingHookEvent;
+export interface HookMatcher {
+    /** Regex pattern matched against tool_name (PreToolUse/PostToolUse only). */
+    tool_name?: string;
+}
+export interface HookDefinition {
+    /** Hook type. Only "command" supported in phase 1. */
+    type: 'command';
+    /** Shell command to execute via /bin/sh -c. */
+    command: string;
+    /** Optional matcher to filter when this hook runs. */
+    matcher?: HookMatcher;
+    /** Timeout in ms. Default 10000. Process killed after timeout. */
+    timeout?: number;
+    /** Human-readable description for /hooks display. */
+    description?: string;
+}
+export interface HooksConfig {
+    PreToolUse?: HookDefinition[];
+    PostToolUse?: HookDefinition[];
+    Stop?: HookDefinition[];
+    UserPromptSubmit?: HookDefinition[];
+    SessionStart?: HookDefinition[];
+    SessionEnd?: HookDefinition[];
+    Notification?: HookDefinition[];
+    AgentStart?: HookDefinition[];
+    AgentEnd?: HookDefinition[];
+    PermissionRequest?: HookDefinition[];
+    PermissionResult?: HookDefinition[];
+    Interrupt?: HookDefinition[];
+    SubagentStart?: HookDefinition[];
+    SubagentEnd?: HookDefinition[];
+}
+export interface HookStdinBase {
+    session_id: string;
+    cwd: string;
+    hook_event_name: HookEventName;
+    /**
+     * Stable MastraCode-generated id for the active agent run. Present on events
+     * emitted while a run is active (AgentStart..AgentEnd, tool hooks, Stop).
+     * Absent outside a run (SessionStart, SessionEnd, Notification fired idle).
+     */
+    run_id?: string;
+}
+export interface HookStdinToolEvent extends HookStdinBase {
+    hook_event_name: 'PreToolUse' | 'PostToolUse';
+    tool_name: string;
+    tool_input: unknown;
+    tool_output?: unknown;
+    tool_error?: boolean;
+}
+export interface HookStdinUserPrompt extends HookStdinBase {
+    hook_event_name: 'UserPromptSubmit';
+    user_message: string;
+}
+export interface HookStdinStop extends HookStdinBase {
+    hook_event_name: 'Stop';
+    assistant_message?: string;
+    stop_reason: 'complete' | 'aborted' | 'error';
+}
+export interface HookStdinSession extends HookStdinBase {
+    hook_event_name: 'SessionStart' | 'SessionEnd';
+}
+export interface HookStdinNotification extends HookStdinBase {
+    hook_event_name: 'Notification';
+    /** Why the notification fired: agent_done, ask_question, tool_approval, plan_approval, sandbox_access */
+    reason: string;
+    /** Optional human-readable message for the notification. */
+    message?: string;
+}
+export interface HookStdinAgentStart extends HookStdinBase {
+    hook_event_name: 'AgentStart';
+    run_id: string;
+}
+export interface HookStdinAgentEnd extends HookStdinBase {
+    hook_event_name: 'AgentEnd';
+    run_id: string;
+    stop_reason: 'complete' | 'aborted' | 'error' | 'suspended';
+}
+export type PermissionKind = 'tool_approval' | 'sandbox_access' | 'plan_approval';
+export interface HookStdinPermissionRequest extends HookStdinBase {
+    hook_event_name: 'PermissionRequest';
+    run_id: string;
+    permission_kind: PermissionKind;
+    tool_call_id: string;
+    tool_name: string;
+    tool_input?: unknown;
+}
+export type PermissionDecision = 'approved' | 'declined' | 'dismissed' | 'auto_approved' | 'auto_declined';
+export interface HookStdinPermissionResult extends HookStdinBase {
+    hook_event_name: 'PermissionResult';
+    run_id: string;
+    permission_kind: PermissionKind;
+    tool_call_id: string;
+    tool_name: string;
+    tool_input?: unknown;
+    decision: PermissionDecision;
+}
+export type InterruptReason = 'user_interrupt' | 'goal_judge_interrupt' | 'process_sigint';
+export interface HookStdinInterrupt extends HookStdinBase {
+    hook_event_name: 'Interrupt';
+    run_id: string;
+    reason: InterruptReason;
+}
+export interface HookStdinSubagentStart extends HookStdinBase {
+    hook_event_name: 'SubagentStart';
+    run_id: string;
+    tool_call_id: string;
+    agent_type: string;
+    task: string;
+    model_id?: string;
+    forked?: boolean;
+}
+export interface HookStdinSubagentEnd extends HookStdinBase {
+    hook_event_name: 'SubagentEnd';
+    run_id: string;
+    tool_call_id: string;
+    agent_type: string;
+    result: unknown;
+    is_error: boolean;
+    duration_ms: number;
+}
+export type HookStdin = HookStdinToolEvent | HookStdinUserPrompt | HookStdinStop | HookStdinSession | HookStdinNotification | HookStdinAgentStart | HookStdinAgentEnd | HookStdinPermissionRequest | HookStdinPermissionResult | HookStdinInterrupt | HookStdinSubagentStart | HookStdinSubagentEnd;
+export interface HookStdout {
+    decision?: 'allow' | 'block';
+    reason?: string;
+    additionalContext?: string;
+}
+export interface HookResult {
+    hook: HookDefinition;
+    exitCode: number;
+    stdout?: HookStdout;
+    stderr?: string;
+    timedOut: boolean;
+    durationMs: number;
+}
+export interface HookEventResult {
+    allowed: boolean;
+    blockReason?: string;
+    additionalContext?: string;
+    results: HookResult[];
+    warnings: string[];
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/hooks/types.js

@@ -0,0 +1,7 @@
+function isBlockingEvent(event) {
+  return event === "PreToolUse" || event === "Stop" || event === "UserPromptSubmit";
+}
+export {
+  isBlockingEvent
+};
+//# sourceMappingURL=types.js.map

package/dist/hooks/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/hooks/types.ts"],"sourcesContent":["/**\n * Type definitions for the hooks system.\n * Hooks are user-configured shell commands that run at lifecycle events.\n */\n\n// =============================================================================\n// Hook Event Names\n// =============================================================================\nexport type HookEventName =\n  | 'PreToolUse'\n  | 'PostToolUse'\n  | 'Stop'\n  | 'UserPromptSubmit'\n  | 'SessionStart'\n  | 'SessionEnd'\n  | 'Notification'\n  | 'AgentStart'\n  | 'AgentEnd'\n  | 'PermissionRequest'\n  | 'PermissionResult'\n  | 'Interrupt'\n  | 'SubagentStart'\n  | 'SubagentEnd';\n\nexport type BlockingHookEvent = 'PreToolUse' | 'Stop' | 'UserPromptSubmit';\n\n/** Lifecycle hook events are non-blocking: they observe behavior without changing it. */\nexport type LifecycleHookEvent =\n  | 'AgentStart'\n  | 'AgentEnd'\n  | 'PermissionRequest'\n  | 'PermissionResult'\n  | 'Interrupt'\n  | 'SubagentStart'\n  | 'SubagentEnd';\n\nexport function isBlockingEvent(event: HookEventName): event is BlockingHookEvent {\n  return event === 'PreToolUse' || event === 'Stop' || event === 'UserPromptSubmit';\n}\n\n// =============================================================================\n// Hook Configuration\n// =============================================================================\n\nexport interface HookMatcher {\n  /** Regex pattern matched against tool_name (PreToolUse/PostToolUse only). */\n  tool_name?: string;\n}\n\nexport interface HookDefinition {\n  /** Hook type. Only \"command\" supported in phase 1. */\n  type: 'command';\n  /** Shell command to execute via /bin/sh -c. */\n  command: string;\n  /** Optional matcher to filter when this hook runs. */\n  matcher?: HookMatcher;\n  /** Timeout in ms. Default 10000. Process killed after timeout. */\n  timeout?: number;\n  /** Human-readable description for /hooks display. */\n  description?: string;\n}\nexport interface HooksConfig {\n  PreToolUse?: HookDefinition[];\n  PostToolUse?: HookDefinition[];\n  Stop?: HookDefinition[];\n  UserPromptSubmit?: HookDefinition[];\n  SessionStart?: HookDefinition[];\n  SessionEnd?: HookDefinition[];\n  Notification?: HookDefinition[];\n  AgentStart?: HookDefinition[];\n  AgentEnd?: HookDefinition[];\n  PermissionRequest?: HookDefinition[];\n  PermissionResult?: HookDefinition[];\n  Interrupt?: HookDefinition[];\n  SubagentStart?: HookDefinition[];\n  SubagentEnd?: HookDefinition[];\n}\n\n// =============================================================================\n// Stdin Protocol (JSON sent to hook process)\n// =============================================================================\n\nexport interface HookStdinBase {\n  session_id: string;\n  cwd: string;\n  hook_event_name: HookEventName;\n  /**\n   * Stable MastraCode-generated id for the active agent run. Present on events\n   * emitted while a run is active (AgentStart..AgentEnd, tool hooks, Stop).\n   * Absent outside a run (SessionStart, SessionEnd, Notification fired idle).\n   */\n  run_id?: string;\n}\n\nexport interface HookStdinToolEvent extends HookStdinBase {\n  hook_event_name: 'PreToolUse' | 'PostToolUse';\n  tool_name: string;\n  tool_input: unknown;\n  tool_output?: unknown;\n  tool_error?: boolean;\n}\n\nexport interface HookStdinUserPrompt extends HookStdinBase {\n  hook_event_name: 'UserPromptSubmit';\n  user_message: string;\n}\n\nexport interface HookStdinStop extends HookStdinBase {\n  hook_event_name: 'Stop';\n  assistant_message?: string;\n  stop_reason: 'complete' | 'aborted' | 'error';\n}\nexport interface HookStdinSession extends HookStdinBase {\n  hook_event_name: 'SessionStart' | 'SessionEnd';\n}\n\nexport interface HookStdinNotification extends HookStdinBase {\n  hook_event_name: 'Notification';\n  /** Why the notification fired: agent_done, ask_question, tool_approval, plan_approval, sandbox_access */\n  reason: string;\n  /** Optional human-readable message for the notification. */\n  message?: string;\n}\n\nexport interface HookStdinAgentStart extends HookStdinBase {\n  hook_event_name: 'AgentStart';\n  run_id: string;\n}\n\nexport interface HookStdinAgentEnd extends HookStdinBase {\n  hook_event_name: 'AgentEnd';\n  run_id: string;\n  stop_reason: 'complete' | 'aborted' | 'error' | 'suspended';\n}\n\nexport type PermissionKind = 'tool_approval' | 'sandbox_access' | 'plan_approval';\n\nexport interface HookStdinPermissionRequest extends HookStdinBase {\n  hook_event_name: 'PermissionRequest';\n  run_id: string;\n  permission_kind: PermissionKind;\n  tool_call_id: string;\n  tool_name: string;\n  tool_input?: unknown;\n}\n\nexport type PermissionDecision = 'approved' | 'declined' | 'dismissed' | 'auto_approved' | 'auto_declined';\n\nexport interface HookStdinPermissionResult extends HookStdinBase {\n  hook_event_name: 'PermissionResult';\n  run_id: string;\n  permission_kind: PermissionKind;\n  tool_call_id: string;\n  tool_name: string;\n  tool_input?: unknown;\n  decision: PermissionDecision;\n}\n\nexport type InterruptReason = 'user_interrupt' | 'goal_judge_interrupt' | 'process_sigint';\n\nexport interface HookStdinInterrupt extends HookStdinBase {\n  hook_event_name: 'Interrupt';\n  run_id: string;\n  reason: InterruptReason;\n}\n\nexport interface HookStdinSubagentStart extends HookStdinBase {\n  hook_event_name: 'SubagentStart';\n  run_id: string;\n  tool_call_id: string;\n  agent_type: string;\n  task: string;\n  model_id?: string;\n  forked?: boolean;\n}\n\nexport interface HookStdinSubagentEnd extends HookStdinBase {\n  hook_event_name: 'SubagentEnd';\n  run_id: string;\n  tool_call_id: string;\n  agent_type: string;\n  result: unknown;\n  is_error: boolean;\n  duration_ms: number;\n}\n\nexport type HookStdin =\n  | HookStdinToolEvent\n  | HookStdinUserPrompt\n  | HookStdinStop\n  | HookStdinSession\n  | HookStdinNotification\n  | HookStdinAgentStart\n  | HookStdinAgentEnd\n  | HookStdinPermissionRequest\n  | HookStdinPermissionResult\n  | HookStdinInterrupt\n  | HookStdinSubagentStart\n  | HookStdinSubagentEnd;\n\n// =============================================================================\n// Stdout Protocol (JSON read from hook process)\n// =============================================================================\n\nexport interface HookStdout {\n  decision?: 'allow' | 'block';\n  reason?: string;\n  additionalContext?: string;\n}\n\n// =============================================================================\n// Execution Results\n// =============================================================================\n\nexport interface HookResult {\n  hook: HookDefinition;\n  exitCode: number;\n  stdout?: HookStdout;\n  stderr?: string;\n  timedOut: boolean;\n  durationMs: number;\n}\n\nexport interface HookEventResult {\n  allowed: boolean;\n  blockReason?: string;\n  additionalContext?: string;\n  results: HookResult[];\n  warnings: string[];\n}\n"],"mappings":"AAoCO,SAAS,gBAAgB,OAAkD;AAChF,SAAO,UAAU,gBAAgB,UAAU,UAAU,UAAU;AACjE;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,241 @@
+import { AgentController } from '@mastra/core/agent-controller';
+import type { IntervalHandler, AgentControllerConfig, AgentControllerMode, AgentControllerSubagent, Session } from '@mastra/core/agent-controller';
+import type { PubSub } from '@mastra/core/events';
+import { Mastra } from '@mastra/core/mastra';
+import { RequestContext } from '@mastra/core/request-context';
+import type { ApiRoute } from '@mastra/core/server';
+import { MastraCompositeStore } from '@mastra/core/storage';
+import { GithubSignals } from '@mastra/github-signals';
+import { Observability } from '@mastra/observability';
+import { resolveModel } from './agents/model.js';
+import { AuthStorage } from './auth/storage.js';
+import { HookManager } from './hooks/index.js';
+import type { McpServerConfig } from './mcp/index.js';
+import { PluginManager } from './plugins/manager.js';
+import type { MastraCodeState } from './schema.js';
+import type { StorageConfig } from './utils/project.js';
+export interface MastraCodeConfig {
+    /** Working directory for project detection. Default: process.cwd() */
+    cwd?: string;
+    /** Home directory for global config discovery. Default: os.homedir() */
+    homeDir?: string;
+    /** Override modes (model IDs, colors, which modes exist). Default: build/plan/fast */
+    modes?: AgentControllerMode[];
+    /** Override or extend subagent definitions. Default: explore/plan/execute */
+    subagents?: AgentControllerSubagent[];
+    /** Extra tools merged into the dynamic tool set. Can be a static record or a function that receives requestContext. */
+    extraTools?: Record<string, {
+        execute?: (input: unknown, context?: unknown) => Promise<unknown> | unknown;
+        [key: string]: unknown;
+    }> | ((ctx: {
+        requestContext: RequestContext;
+    }) => Record<string, {
+        execute?: (input: unknown, context?: unknown) => Promise<unknown> | unknown;
+        [key: string]: unknown;
+    }>);
+    /** Tools removed from the dynamic tool set before exposure to the model */
+    disabledTools?: string[];
+    /** Custom storage config instead of auto-detected default */
+    storage?: StorageConfig;
+    /** Observational memory scope. Default: auto-detected from env/config files, falls back to 'thread' */
+    omScope?: 'thread' | 'resource';
+    /** Path to a custom settings.json file. Default: global settings */
+    settingsPath?: string;
+    /** Initial state overrides (yolo, thinkingLevel, etc.) */
+    initialState?: Partial<MastraCodeState>;
+    /** Override id generation for threads/messages. Primarily useful for deterministic tests. */
+    idGenerator?: AgentControllerConfig<MastraCodeState>['idGenerator'];
+    /** Override interval handlers. Default: gateway-sync */
+    intervalHandlers?: IntervalHandler[];
+    /** Override the workspace. Default: local filesystem + local sandbox based on detected project */
+    workspace?: AgentControllerConfig<MastraCodeState>['workspace'];
+    /** Override the config directory name. Default: '.mastracode'. Replaces '.mastracode' in all project-level and global config paths (MCP, hooks, commands, database, skills, agent instructions). */
+    configDir?: string;
+    /** Programmatic MCP server configurations, merged with (and overriding) file-based configs. */
+    mcpServers?: Record<string, McpServerConfig>;
+    /** Disable MCP server discovery. Default: false */
+    disableMcp?: boolean;
+    /** Disable hooks. Default: false */
+    disableHooks?: boolean;
+    /** Disable plugin discovery/loading. Default: false */
+    disablePlugins?: boolean;
+    /** Override the plugin manager. Primarily useful for tests or embedding. */
+    pluginManager?: PluginManager;
+    /**
+     * Override the memory instance (or dynamic factory) passed to the AgentController.
+     * When provided, this replaces the default `getDynamicMemory(storage, vectorStore)` which
+     * uses mastracode's built-in model gateway (Anthropic OAuth, OpenAI Codex,
+     * custom providers, and models.dev fallback).
+     *
+     * Use this when you need to override memory model behavior completely.
+     */
+    memory?: AgentControllerConfig<MastraCodeState>['memory'] | false;
+    /** Browser provider for browser automation tools. When set, the agent gains access to browser tools. */
+    browser?: AgentControllerConfig<MastraCodeState>['browser'];
+    /** PubSub for signal routing. When crossProcessPubSub is true, thread locks are disabled. */
+    pubsub?: PubSub;
+    /** Use Mastra Code's built-in Unix socket PubSub for local cross-process signal routing. */
+    unixSocketPubSub?: boolean;
+    /** Marks the configured PubSub as cross-process-safe, allowing Mastra Code to skip file thread locks. */
+    crossProcessPubSub?: boolean;
+}
+export declare function createAuthStorage(): AuthStorage;
+/**
+ * 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).
+ */
+export declare function createMastraCodeAgentController(config?: MastraCodeConfig): Promise<{
+    controller: AgentController<MastraCodeState>;
+    storage: MastraCompositeStore;
+    observability: Observability;
+    memory: import("@mastra/core/types").DynamicArgument<import("@mastra/core/memory").MastraMemory> | (({ requestContext }: {
+        requestContext: RequestContext;
+    }) => import("@mastra/memory").Memory) | undefined;
+    mcpManager: import("./mcp/manager.js").McpManager | undefined;
+    hookManager: HookManager | undefined;
+    pluginManager: PluginManager | undefined;
+    loadedPlugins: import("./plugins/types.js").LoadedPlugin[];
+    pluginTools: import("./plugin.js").MastraCodePluginTools;
+    signalsPubSub: PubSub | undefined;
+    authStorage: AuthStorage;
+    resolveModel: typeof resolveModel;
+    storageWarning: string | undefined;
+    observabilityWarning: string | undefined;
+    builtinPacks: import("./onboarding/packs.js").ModePack[];
+    builtinOmPacks: import("./onboarding/packs.js").OMPack[];
+    effectiveDefaults: Record<string, string>;
+    githubSignals: GithubSignals | undefined;
+    sessionId: string;
+    ownerId: string;
+    setActiveSession: (session: Session<MastraCodeState>) => void;
+}>;
+/**
+ * Result of {@link createMastraCodeAgentController}: every shared resource plus the
+ * inert AgentController, ready to be either booted locally or mounted on a server
+ * Mastra.
+ */
+export type MastraCodeAgentController = Awaited<ReturnType<typeof createMastraCodeAgentController>>;
+/**
+ * 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.
+ */
+export declare function wireSessionConcerns(base: Pick<MastraCodeAgentController, 'hookManager' | 'githubSignals' | 'setActiveSession'>, session: Session<MastraCodeState>): Promise<void>;
+/**
+ * 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.
+ */
+export declare function bootLocalAgentController(config?: MastraCodeConfig): Promise<{
+    session: Session<MastraCodeState>;
+    controller: AgentController<MastraCodeState>;
+    storage: MastraCompositeStore;
+    observability: Observability;
+    memory: import("@mastra/core/types").DynamicArgument<import("@mastra/core/memory").MastraMemory> | (({ requestContext }: {
+        requestContext: RequestContext;
+    }) => import("@mastra/memory").Memory) | undefined;
+    mcpManager: import("./mcp/manager.js").McpManager | undefined;
+    hookManager: HookManager | undefined;
+    pluginManager: PluginManager | undefined;
+    loadedPlugins: import("./plugins/types.js").LoadedPlugin[];
+    pluginTools: import("./plugin.js").MastraCodePluginTools;
+    signalsPubSub: PubSub | undefined;
+    authStorage: AuthStorage;
+    resolveModel: typeof resolveModel;
+    storageWarning: string | undefined;
+    observabilityWarning: string | undefined;
+    builtinPacks: import("./onboarding/packs.js").ModePack[];
+    builtinOmPacks: import("./onboarding/packs.js").OMPack[];
+    effectiveDefaults: Record<string, string>;
+    githubSignals: GithubSignals | undefined;
+    sessionId: string;
+    ownerId: string;
+    setActiveSession: (session: Session<MastraCodeState>) => void;
+}>;
+/** Result of {@link mountAgentControllerOnMastra}: shared handles plus the owning Mastra. */
+export type MountedMastraCode = MastraCodeAgentController & {
+    mastra: Mastra;
+};
+/**
+ * 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.
+ */
+export declare function mountAgentControllerOnMastra(config?: MastraCodeConfig & {
+    mastra?: Mastra;
+    controllerId?: string;
+    buildApiRoutes?: (deps: {
+        controller: MountedMastraCode['controller'];
+        authStorage: AuthStorage;
+    }) => ApiRoute[];
+    /**
+     * Additional `server` config to fold onto the constructed Mastra alongside
+     * the assembled `apiRoutes` (e.g. `middleware`, `cors`). Used by the
+     * platform entry (`src/mastra/index.ts`) to own the WorkOS gate + tenant
+     * dispatcher + CORS on the instance the deployer generates its server from.
+     * Ignored when `mastra` is provided (mounting onto a caller-owned instance).
+     */
+    buildServerConfig?: (deps: {
+        controller: MountedMastraCode['controller'];
+        authStorage: AuthStorage;
+    }) => Omit<NonNullable<ConstructorParameters<typeof Mastra>[0]>['server'], 'apiRoutes'>;
+}): Promise<MountedMastraCode>;
+/**
+ * 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.
+ */
+export declare function prepareAgentControllerMount(config?: MastraCodeConfig & {
+    mastra?: Mastra;
+    controllerId?: string;
+    buildApiRoutes?: (deps: {
+        controller: MountedMastraCode['controller'];
+        authStorage: AuthStorage;
+    }) => ApiRoute[];
+    buildServerConfig?: (deps: {
+        controller: MountedMastraCode['controller'];
+        authStorage: AuthStorage;
+    }) => Omit<NonNullable<ConstructorParameters<typeof Mastra>[0]>['server'], 'apiRoutes'>;
+}): Promise<{
+    base: Awaited<ReturnType<typeof createMastraCodeAgentController>>;
+    mastraArgs: NonNullable<ConstructorParameters<typeof Mastra>[0]>;
+    finalize: () => Promise<void>;
+}>;
+/**
+ * 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).
+ */
+export declare const createMastraCode: typeof bootLocalAgentController;
+/**
+ * Programmatic headless API. `runMC` runs an already-built controller/session
+ * (from {@link createMastraCode}) as an async-iterable run that also resolves to
+ * a typed result. Also available via the `mastracode/headless` subpath.
+ */
+export { runMC, runMCCli, hasHeadlessFlag, autoApprovePolicy, denyPolicy, permissionModeToPolicy, formatHuman, formatJsonl, renderTextResult, renderJsonResult, } from './headless/index.js';
+export type { RunMCOptions, RunMCResult, RunMCStatus, RunMCUsage, RunMCToolCall, RunMCToolResult, RunMCError, RunMCThreadOptions, MCRun, ResolutionPolicy, PermissionMode, } from './headless/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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