@mastra/code-sdk 0.0.0-aggregate-trace-20261015182851

package/dist/agents/sandbox-filesystem.d.ts

@@ -0,0 +1,151 @@
+/**
+ * SandboxFilesystem
+ *
+ * A `WorkspaceFilesystem` that stores files inside a remote `MastraSandbox`
+ * (e.g. a Railway VM) rather than on the server host. File operations are
+ * implemented by shelling out through the sandbox's `executeCommand`, so the
+ * agent's file tools and command tools share one VM and one view of the repo.
+ *
+ * Paths are workspace-relative (`/src/foo.ts`) and resolve under the sandbox
+ * working directory (`basePath`). A traversal guard rejects any path that
+ * escapes the workdir, mirroring `LocalFilesystem`'s contained mode.
+ *
+ * Reads/writes use base64 over the wire so binary content survives the shell.
+ */
+import type { CopyOptions, FileContent, FileEntry, FileStat, FilesystemGrepOptions, FilesystemGrepResult, FilesystemInfo, ListOptions, ProviderStatus, ReadOptions, RemoveOptions, WalkEntry, WalkOptions, WorkspaceFilesystem, WriteOptions } from '@mastra/core/workspace';
+/** Minimal command result shape we depend on. */
+export interface SandboxCommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/** Minimal sandbox surface the filesystem needs. */
+export interface SandboxExec {
+    readonly id: string;
+    executeCommand(command: string, args?: string[], options?: {
+        timeout?: number;
+        maxRetainedBytes?: number;
+    }): Promise<SandboxCommandResult>;
+}
+export interface SandboxFilesystemOptions {
+    /** Live sandbox to run commands in. */
+    sandbox: SandboxExec;
+    /**
+     * Absolute path inside the sandbox that is the workspace root — or a lazy
+     * resolver for it. The resolver form exists for sandboxes whose workspace
+     * root is only knowable once the VM is running (e.g. `$HOME/<repo>` under
+     * a provider-chosen home dir): it is awaited on the first file operation
+     * (which itself may lazily start the VM) and the result is memoized.
+     */
+    workdir: string | (() => Promise<string> | string);
+    /** Optional stable id; defaults to a sandbox-derived id. */
+    id?: string;
+}
+export declare class SandboxFilesystem implements WorkspaceFilesystem {
+    readonly id: string;
+    readonly name = "SandboxFilesystem";
+    readonly provider = "sandbox";
+    status: ProviderStatus;
+    private readonly sandbox;
+    private readonly workdirSource;
+    private resolvedBase?;
+    private resolvingBase?;
+    constructor(options: SandboxFilesystemOptions);
+    /** The resolved workspace root; empty until a lazy workdir first resolves. */
+    get basePath(): string;
+    /** Await (and memoize) the workspace root, resolving a lazy workdir once. */
+    private base;
+    /**
+     * Resolve a workspace path to an absolute path inside the sandbox, enforcing
+     * that it stays within the workdir. Awaits the workspace root first, which
+     * for a lazy workdir may start the VM.
+     */
+    private resolveAsync;
+    /**
+     * Resolve a workspace path against a known base, enforcing that it stays
+     * within the workdir.
+     *
+     * Accepts both workspace-relative paths (`src/foo.ts`, `/src/foo.ts`) and
+     * absolute sandbox paths that already live under the workdir — the agent's
+     * prompt advertises the workdir as its working directory, so tools are
+     * routinely called with fully-qualified paths like `<workdir>/src/foo.ts`.
+     */
+    private resolveAgainst;
+    resolveAbsolutePath(inputPath: string): string | undefined;
+    private exec;
+    /**
+     * Lexical guard catches `..` traversal, but a symlink inside the workdir can
+     * still point outside it. After resolving a path that refers to an existing
+     * entry, verify its realpath is still contained in the workdir.
+     *
+     * Canonicalization tries `realpath`, then `readlink -f` (GNU/busybox), then
+     * `cd && pwd -P` for directories — covering GNU hosts, macOS/BSD, and
+     * busybox. If the path exists but cannot be canonicalized we fail CLOSED:
+     * returning without a check would let a symlink bypass containment.
+     */
+    private assertContainedRealpath;
+    /**
+     * Guard for write destinations. The lexical guard catches `..`, but a symlink
+     * inside the workdir can redirect a write outside it. For an existing target
+     * we check its realpath; for a not-yet-existing target we check the realpath
+     * of its nearest existing ancestor directory, since a symlinked parent is the
+     * escape vector (e.g. `link -> /etc` then writing `link/passwd`).
+     */
+    private assertContainedDest;
+    private execOk;
+    readFile(path: string, options?: ReadOptions): Promise<string | Buffer>;
+    writeFile(path: string, content: FileContent, options?: WriteOptions): Promise<void>;
+    appendFile(path: string, content: FileContent): Promise<void>;
+    deleteFile(path: string, options?: RemoveOptions): Promise<void>;
+    copyFile(src: string, dest: string, options?: CopyOptions): Promise<void>;
+    moveFile(src: string, dest: string, options?: CopyOptions): Promise<void>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    rmdir(path: string, options?: RemoveOptions): Promise<void>;
+    readdir(path: string, options?: ListOptions): Promise<FileEntry[]>;
+    private parseListOutput;
+    private parseFindOutput;
+    private matchesExtension;
+    /**
+     * Walk the tree in a single sandbox command instead of one readdir round
+     * trip per directory. Uses `find` with a portable classification loop
+     * (`find -printf` is GNU-only and fails on macOS/BSD hosts). `find` does
+     * not follow symlinked directories by default, matching the host-side
+     * walker's no-recursion-into-symlinks behavior.
+     */
+    walk(path: string, options?: WalkOptions): Promise<WalkEntry[]>;
+    /**
+     * Content search executed inside the sandbox in one command. Prefers
+     * ripgrep (`rg --json`) when installed; otherwise falls back to
+     * `grep -rnE`. Patterns the ERE fallback can't express (PCRE-style classes,
+     * word boundaries, lookarounds, non-greedy quantifiers) throw
+     * {@link UnsupportedGrepPatternError} so callers use their host-side walk.
+     *
+     * Callers are expected to apply their own gitignore/hidden/glob filtering
+     * to the returned paths; both engines run with ignore rules disabled so
+     * results are a superset of what any host-side filter would keep.
+     */
+    grep(options: FilesystemGrepOptions): Promise<FilesystemGrepResult[]>;
+    private rgCheck;
+    private hasRipgrep;
+    private grepWithRipgrep;
+    private parseRipgrepJson;
+    /**
+     * Patterns whose meaning differs between POSIX ERE and JS RegExp. The grep
+     * runs with ERE but match columns are recomputed with JS, so anything that
+     * only one side understands (PCRE classes, lookarounds, lazy quantifiers,
+     * POSIX bracket classes, GNU word anchors) must fall back to the host walk.
+     */
+    private static readonly ERE_UNSUPPORTED;
+    private grepWithPosixGrep;
+    private applyTotalCap;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileStat>;
+    init(): Promise<void>;
+    destroy(): Promise<void>;
+    isReady(): Promise<boolean>;
+    getInfo(): FilesystemInfo;
+    getInstructions(): string;
+}
+//# sourceMappingURL=sandbox-filesystem.d.ts.map

package/dist/agents/sandbox-filesystem.d.ts.map

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