@mastra/core/dist/workspace/sandbox/mount-manager.d.ts

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

/**
 * Mount Manager
 *
 * Encapsulates all mount-related state and operations for sandboxes.
 * Used by BaseSandbox to manage filesystem mounts.
 */
import type { IMastraLogger } from '../../logger/index.js';
import type { WorkspaceFilesystem } from '../filesystem/filesystem.js';
import type { FilesystemMountConfig, MountResult } from '../filesystem/mount.js';
import type { Workspace } from '../workspace.js';
import type { WorkspaceSandbox } from './sandbox.js';
import type { MountEntry, MountState } from './types.js';
/**
 * Mount function signature.
 */
export type MountFn = (filesystem: WorkspaceFilesystem, mountPath: string) => Promise<MountResult>;
/**
 * onMount hook result.
 * - false: skip mount
 * - { success, error? }: hook handled it
 * - void: use default mount
 */
export type OnMountResult = false | {
    success: boolean;
    error?: string;
} | void;
/**
 * Arguments passed to the onMount hook.
 */
export interface OnMountArgs {
    /** The filesystem being mounted */
    filesystem: WorkspaceFilesystem;
    /** The mount path in the sandbox */
    mountPath: string;
    /** The mount configuration from filesystem.getMountConfig() (undefined if not supported) */
    config: FilesystemMountConfig | undefined;
    /** The sandbox instance for custom mount implementations */
    sandbox: WorkspaceSandbox;
    /** The workspace instance */
    workspace: Workspace;
}
/**
 * onMount hook function.
 *
 * Called for each filesystem before mounting into sandbox.
 * Return value controls mounting behavior (see {@link OnMountResult}).
 *
 * @example Skip local filesystems
 * ```typescript
 * onMount: ({ filesystem }) => {
 *   if (filesystem.provider === 'local') return false;
 * }
 * ```
 *
 * @example Custom mount implementation
 * ```typescript
 * onMount: async ({ filesystem, mountPath, sandbox }) => {
 *   if (mountPath === '/custom') {
 *     await sandbox.executeCommand?.('my-mount-script', [mountPath]);
 *     return { success: true };
 *   }
 * }
 * ```
 */
export type OnMountHook = (args: OnMountArgs) => Promise<OnMountResult> | OnMountResult;
/**
 * MountManager configuration.
 */
export interface MountManagerConfig {
    /** The mount implementation from the sandbox */
    mount: MountFn;
    /** Logger instance */
    logger: IMastraLogger;
}
/**
 * Manages filesystem mounts for a sandbox.
 *
 * Provides methods for tracking mount state, updating entries,
 * and processing pending mounts.
 */
export declare class MountManager {
    private _entries;
    private _mountFn;
    private _onMount?;
    private _sandbox?;
    private _workspace?;
    private logger;
    constructor(config: MountManagerConfig);
    /**
     * Set the sandbox and workspace references for onMount hook args.
     * Called by Workspace during construction.
     */
    setContext(context: {
        sandbox: WorkspaceSandbox;
        workspace: Workspace;
    }): void;
    /**
     * Set the onMount hook for custom mount handling.
     * Called before each mount - can skip, handle, or defer to default.
     */
    setOnMount(hook: OnMountHook | undefined): void;
    /**
     * Update the logger instance.
     * Called when the sandbox receives a logger from Mastra.
     * @internal
     */
    __setLogger(logger: IMastraLogger): void;
    /**
     * Get all mount entries.
     */
    get entries(): ReadonlyMap<string, MountEntry>;
    /**
     * Get a mount entry by path.
     */
    get(path: string): MountEntry | undefined;
    /**
     * Check if a mount exists at the given path.
     */
    has(path: string): boolean;
    /**
     * Add pending mounts from workspace config.
     * These will be processed when `processPending()` is called.
     */
    add(mounts: Record<string, WorkspaceFilesystem>): void;
    /**
     * Update a mount entry's state.
     * Creates the entry if it doesn't exist.
     */
    set(path: string, updates: {
        filesystem?: WorkspaceFilesystem;
        state: MountState;
        config?: FilesystemMountConfig;
        error?: string;
    }): void;
    /**
     * Delete a mount entry.
     */
    delete(path: string): boolean;
    /**
     * Clear all mount entries.
     */
    clear(): void;
    /**
     * Process all pending mounts.
     * Call this after sandbox is ready (in start()).
     */
    processPending(): Promise<void>;
    /**
     * Generate a marker filename for a mount path.
     * Used by sandboxes to store mount metadata for reconnection detection.
     *
     * @param mountPath - The mount path to generate a filename for
     * @returns A safe filename like "mount-abc123"
     */
    markerFilename(mountPath: string): string;
    /**
     * Generate marker file content for a mount path.
     * Format: "path|configHash" - used for detecting config changes on reconnect.
     *
     * @param mountPath - The mount path
     * @returns Marker content string, or null if no config hash available
     */
    getMarkerContent(mountPath: string): string | null;
    /**
     * Parse marker file content.
     *
     * @param content - The marker file content (format: "path|configHash")
     * @returns Parsed path and configHash, or null if invalid format
     */
    parseMarkerContent(content: string): {
        path: string;
        configHash: string;
    } | null;
    /**
     * Check if a config hash matches the expected hash for a mount path.
     *
     * @param mountPath - The mount path to check
     * @param storedHash - The hash from the marker file
     * @returns true if the hashes match
     */
    isConfigMatching(mountPath: string, storedHash: string): boolean;
    /**
     * Compute a hash for a mount config. Used for comparing configs across mounts.
     *
     * @param config - The config to hash
     * @returns A hash string suitable for comparison
     */
    computeConfigHash(config: FilesystemMountConfig): string;
    /**
     * Hash a mount config for comparison.
     */
    private hashConfig;
    private sortKeysDeep;
}
//# sourceMappingURL=mount-manager.d.ts.map