@mastra/vercel 0.1.0 → 0.2.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @mastra/vercel
 
+## 0.2.0-alpha.0
+
+### Minor Changes
+
+- Added `VercelMicroVMSandbox`, a new workspace sandbox provider backed by the [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) ephemeral Firecracker MicroVM product (`@vercel/sandbox`). It provides a persistent in-session filesystem, `sudo` access, exposed ports, command execution, and background processes via the process manager. This is distinct from the existing `VercelSandbox`, which runs commands as stateless Vercel serverless Functions and is unchanged. Also exports `VercelMicroVMProcessManager` and the `vercelMicroVMSandboxProvider` editor descriptor (provider id `vercel-microvm`). Closes #16704. ([#17332](https://github.com/mastra-ai/mastra/pull/17332))
+
+  ```typescript
+  import { Workspace } from '@mastra/core/workspace';
+  import { VercelMicroVMSandbox } from '@mastra/vercel';
+
+  const workspace = new Workspace({
+    sandbox: new VercelMicroVMSandbox({
+      runtime: 'node24',
+      timeout: 600_000,
+      ports: [3000],
+    }),
+  });
+
+  await workspace.init();
+  const result = await workspace.sandbox.executeCommand('node', ['--version']);
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`8ace89d`](https://github.com/mastra-ai/mastra/commit/8ace89df77f762e622d3b9f7f65ad7524350d050), [`fa63872`](https://github.com/mastra-ai/mastra/commit/fa6387280954e6b667bec5714b55ba082bc627ff), [`f07b646`](https://github.com/mastra-ai/mastra/commit/f07b64604ab7d25391179790b7fd4823df9e2dff), [`d8838ae`](https://github.com/mastra-ai/mastra/commit/d8838ae80b69780361693d27098f7f6684af12fe), [`40f9297`](https://github.com/mastra-ai/mastra/commit/40f9297003b921c62373d3e8d3a4bda76c9f6de3), [`0f0d1ba`](https://github.com/mastra-ai/mastra/commit/0f0d1ba67bfcb2204e571401662f1eceefc03357), [`8c31bcd`](https://github.com/mastra-ai/mastra/commit/8c31bcdb00e597880d5939b1b7d7566fbe5dacae), [`95b14cd`](https://github.com/mastra-ai/mastra/commit/95b14cdd820e86d97ac05fe568424c513a252e31), [`aa36be2`](https://github.com/mastra-ai/mastra/commit/aa36be23aa513b7dc53cb8ca16b7fab8f20e43ad), [`212c635`](https://github.com/mastra-ai/mastra/commit/212c635203e61d036ab41db8ff86c3893dc795b3), [`d8838ae`](https://github.com/mastra-ai/mastra/commit/d8838ae80b69780361693d27098f7f6684af12fe), [`9aa5a73`](https://github.com/mastra-ai/mastra/commit/9aa5a73e7e110f6e9365eec69364a33d5f03bb56), [`f73c789`](https://github.com/mastra-ai/mastra/commit/f73c789e8ef21561580395d2c410119cab5848c8), [`8bd16da`](https://github.com/mastra-ai/mastra/commit/8bd16da73a4cb874d739373643dbd6a6e7f88684), [`c8630f8`](https://github.com/mastra-ai/mastra/commit/c8630f80d4f40cb5d22e60ab162b618b1907167a), [`47f71dc`](https://github.com/mastra-ai/mastra/commit/47f71dc6fbcbd12d71e21a979e676e20a02bd77d), [`50ceae2`](https://github.com/mastra-ai/mastra/commit/50ceae270878e2f8fb2b2c6c2faab09df0007c8a), [`8cdde58`](https://github.com/mastra-ai/mastra/commit/8cdde5875bbba6702d9df226f2b20232b8d75d6c), [`847ff1e`](https://github.com/mastra-ai/mastra/commit/847ff1e0d94368d94b2e173e4e0908e115568ef3), [`259d409`](https://github.com/mastra-ai/mastra/commit/259d409a514174299dbde1ff5e1121209b3ba850), [`9e16c68`](https://github.com/mastra-ai/mastra/commit/9e16c6818b6485ccb43df28aba6f3a2219d28662), [`cefca33`](https://github.com/mastra-ai/mastra/commit/cefca33ae666e69810c935fedf95a929c173d1d7), [`d00e8c5`](https://github.com/mastra-ai/mastra/commit/d00e8c50daebe5bce5bf2f48bde39c86fc3d2fe4), [`36fa7e2`](https://github.com/mastra-ai/mastra/commit/36fa7e24d14e58a1eb46147097b32f583e5b8775), [`87e9774`](https://github.com/mastra-ai/mastra/commit/87e97741c1e493cd6d62f478eb810b49bda4d57c), [`65a72e7`](https://github.com/mastra-ai/mastra/commit/65a72e70c25eedea8ff985a6624b96be2850236b), [`0f77241`](https://github.com/mastra-ai/mastra/commit/0f7724108806703799a8ba80ad0f09414afd5066), [`92ff509`](https://github.com/mastra-ai/mastra/commit/92ff5098ef8a990438ca038077021a5f7541ec1d), [`3fce5e7`](https://github.com/mastra-ai/mastra/commit/3fce5e70d011d289043e75003ef3336ed4aa43c3), [`a763592`](https://github.com/mastra-ai/mastra/commit/a763592c3db46963ef1011cfe16fe372816e775e), [`80c7737`](https://github.com/mastra-ai/mastra/commit/80c7737e32d7917b5f356957d67c169d01744fd3), [`3f1cf47`](https://github.com/mastra-ai/mastra/commit/3f1cf476f74c1e4cc2df908837e05853a5347e31)]:
+  - @mastra/core@1.38.0-alpha.3
+
 ## 0.1.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 var workspace = require('@mastra/core/workspace');
+var sandbox = require('@vercel/sandbox');
 
 // src/sandbox/index.ts
 
@@ -446,8 +447,391 @@ var vercelSandboxProvider = {
   },
   createSandbox: (config) => new VercelSandbox(config)
 };
+var VercelMicroVMProcessHandle = class extends workspace.ProcessHandle {
+  pid;
+  _command;
+  _startTime;
+  _timeout;
+  _exitCode;
+  _waitPromise = null;
+  _streamingPromise = null;
+  _killed = false;
+  constructor(command, startTime, options) {
+    super(options);
+    this.pid = command.cmdId;
+    this._command = command;
+    this._startTime = startTime;
+    this._timeout = options?.timeout;
+  }
+  get exitCode() {
+    return this._exitCode;
+  }
+  /** @internal Set by the process manager after streaming starts. */
+  set streamingPromise(p) {
+    this._streamingPromise = p;
+  }
+  async wait() {
+    if (!this._waitPromise) {
+      this._waitPromise = this._doWait();
+    }
+    return this._waitPromise;
+  }
+  async _doWait() {
+    const finishedPromise = this._command.wait().then((finished) => {
+      if (this._exitCode === void 0) this._exitCode = finished.exitCode;
+    }).catch(() => {
+      if (this._exitCode === void 0) this._exitCode = 1;
+    });
+    if (this._timeout) {
+      let timeoutId;
+      const timeoutPromise = new Promise((resolve) => {
+        timeoutId = setTimeout(() => resolve("timeout"), this._timeout);
+      });
+      const outcome = await Promise.race([finishedPromise.then(() => "done"), timeoutPromise]);
+      clearTimeout(timeoutId);
+      if (outcome === "timeout") {
+        await this.kill();
+        this._exitCode = 124;
+        await this._streamingPromise?.catch(() => {
+        });
+        return {
+          success: false,
+          exitCode: 124,
+          stdout: this.stdout,
+          stderr: this.stderr || `Command timed out after ${this._timeout}ms`,
+          executionTimeMs: Date.now() - this._startTime,
+          killed: true,
+          timedOut: true
+        };
+      }
+    } else {
+      await finishedPromise;
+    }
+    await this._streamingPromise?.catch(() => {
+    });
+    if (this._killed) {
+      return {
+        success: false,
+        exitCode: this._exitCode ?? 137,
+        stdout: this.stdout,
+        stderr: this.stderr,
+        executionTimeMs: Date.now() - this._startTime,
+        killed: true,
+        timedOut: false
+      };
+    }
+    return {
+      success: this._exitCode === 0,
+      exitCode: this._exitCode ?? 1,
+      stdout: this.stdout,
+      stderr: this.stderr,
+      executionTimeMs: Date.now() - this._startTime
+    };
+  }
+  async kill() {
+    if (this._exitCode !== void 0 && !this._killed) return false;
+    this._killed = true;
+    if (this._exitCode === void 0) this._exitCode = 137;
+    try {
+      await this._command.kill();
+    } catch {
+    }
+    return true;
+  }
+  async sendStdin(_data) {
+    throw new Error("VercelMicroVMSandbox does not support sending stdin to running processes.");
+  }
+};
+var VercelMicroVMProcessManager = class extends workspace.SandboxProcessManager {
+  async spawn(command, options = {}) {
+    const mergedEnv = { ...this.env, ...options.env };
+    const env = Object.fromEntries(
+      Object.entries(mergedEnv).filter((entry) => entry[1] !== void 0)
+    );
+    const cmd = await this.sandbox.sandbox.runCommand({
+      cmd: "sh",
+      args: ["-c", command],
+      ...options.cwd ? { cwd: options.cwd } : {},
+      ...Object.keys(env).length ? { env } : {},
+      detached: true
+    });
+    const handle = new VercelMicroVMProcessHandle(cmd, Date.now(), options);
+    const streamingPromise = (async () => {
+      for await (const log of cmd.logs()) {
+        if (log.stream === "stdout") handle.emitStdout(log.data);
+        else handle.emitStderr(log.data);
+      }
+    })().catch(() => {
+    });
+    handle.streamingPromise = streamingPromise;
+    this._tracked.set(handle.pid, handle);
+    return handle;
+  }
+  async list() {
+    const result = [];
+    for (const [pid, handle] of this._tracked) {
+      result.push({
+        pid,
+        command: handle.command,
+        running: handle.exitCode === void 0,
+        exitCode: handle.exitCode
+      });
+    }
+    return result;
+  }
+};
+
+// src/microvm/index.ts
+var LOG_PREFIX2 = "[VercelMicroVMSandbox]";
+var VercelMicroVMSandbox = class extends workspace.MastraSandbox {
+  id;
+  name = "VercelMicroVMSandbox";
+  provider = "vercel-microvm";
+  status = "pending";
+  _sandbox = null;
+  _createdAt = null;
+  _sandboxName;
+  _token;
+  _teamId;
+  _projectId;
+  _runtime;
+  _timeout;
+  _vcpus;
+  _ports;
+  _env;
+  _metadata;
+  _instructionsOverride;
+  constructor(options = {}) {
+    super({
+      ...options,
+      name: "VercelMicroVMSandbox",
+      processes: new VercelMicroVMProcessManager({ env: options.env ?? {} })
+    });
+    this.id = options.id ?? `vercel-microvm-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+    this._sandboxName = options.sandboxName;
+    this._token = options.token ?? process.env.VERCEL_TOKEN;
+    this._teamId = options.teamId ?? process.env.VERCEL_TEAM_ID;
+    this._projectId = options.projectId ?? process.env.VERCEL_PROJECT_ID;
+    this._runtime = options.runtime ?? "node24";
+    this._timeout = options.timeout ?? 3e5;
+    this._vcpus = options.resources?.vcpus;
+    this._ports = options.ports;
+    this._env = options.env ?? {};
+    this._metadata = options.metadata ?? {};
+    this._instructionsOverride = options.instructions;
+  }
+  /**
+   * The underlying `@vercel/sandbox` instance.
+   * Throws if the sandbox has not been started yet.
+   */
+  get sandbox() {
+    if (!this._sandbox) {
+      throw new workspace.SandboxNotReadyError(this.id);
+    }
+    return this._sandbox;
+  }
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+  async start() {
+    if (this._sandbox) {
+      return;
+    }
+    const hasExplicitCreds = Boolean(this._token || this._teamId || this._projectId);
+    if (hasExplicitCreds && !(this._token && this._teamId && this._projectId)) {
+      throw new Error(
+        `${LOG_PREFIX2} Incomplete credentials. Provide token, teamId, and projectId together (or the VERCEL_TOKEN, VERCEL_TEAM_ID, and VERCEL_PROJECT_ID env vars), or omit all three to use the VERCEL_OIDC_TOKEN.`
+      );
+    }
+    this.logger.debug(`${LOG_PREFIX2} Creating sandbox...`, { runtime: this._runtime, timeout: this._timeout });
+    this._sandbox = await sandbox.Sandbox.create({
+      ...this._sandboxName ? { name: this._sandboxName } : {},
+      runtime: this._runtime,
+      timeout: this._timeout,
+      ...this._vcpus ? { resources: { vcpus: this._vcpus } } : {},
+      ...this._ports?.length ? { ports: this._ports } : {},
+      ...Object.keys(this._env).length ? { env: this._env } : {},
+      ...hasExplicitCreds ? { token: this._token, teamId: this._teamId, projectId: this._projectId } : {}
+    });
+    this._createdAt = /* @__PURE__ */ new Date();
+    this.logger.debug(`${LOG_PREFIX2} Sandbox ready: ${this._sandbox.name}`);
+  }
+  async stop() {
+    await this._teardown();
+  }
+  async destroy() {
+    await this._teardown();
+  }
+  async _teardown() {
+    if (!this._sandbox) {
+      return;
+    }
+    try {
+      await this._sandbox.stop();
+    } catch (error) {
+      this.logger.warn(`${LOG_PREFIX2} Error stopping sandbox:`, error);
+    }
+    this._sandbox = null;
+  }
+  // ---------------------------------------------------------------------------
+  // Command Execution
+  // ---------------------------------------------------------------------------
+  async executeCommand(command, args, options) {
+    await this.ensureRunning();
+    const startTime = Date.now();
+    const fullCommand = args?.length ? `${command} ${args.join(" ")}` : command;
+    this.logger.debug(`${LOG_PREFIX2} Executing: ${fullCommand}`, { cwd: options?.cwd });
+    const mergedEnv = { ...this._env, ...options?.env };
+    const env = Object.fromEntries(
+      Object.entries(mergedEnv).filter((entry) => entry[1] !== void 0)
+    );
+    let timeoutId;
+    const abortController = new AbortController();
+    const forwardAbort = () => abortController.abort();
+    if (options?.abortSignal) {
+      if (options.abortSignal.aborted) abortController.abort();
+      else options.abortSignal.addEventListener("abort", forwardAbort, { once: true });
+    }
+    const signal = abortController.signal;
+    const timeoutPromise = options?.timeout ? new Promise((resolve) => {
+      timeoutId = setTimeout(() => resolve("timeout"), options.timeout);
+    }) : null;
+    try {
+      const commandPromise = this.sandbox.runCommand({
+        cmd: command,
+        args: args ?? [],
+        ...options?.cwd ? { cwd: options.cwd } : {},
+        ...Object.keys(env).length ? { env } : {},
+        signal
+      });
+      const finished = timeoutPromise ? await Promise.race([commandPromise, timeoutPromise]) : await commandPromise;
+      if (finished === "timeout") {
+        abortController.abort();
+        return {
+          command: fullCommand,
+          args,
+          success: false,
+          exitCode: 124,
+          stdout: "",
+          stderr: `Command timed out after ${options.timeout}ms`,
+          executionTimeMs: Date.now() - startTime,
+          timedOut: true
+        };
+      }
+      const [stdout, stderr] = await Promise.all([finished.stdout(), finished.stderr()]);
+      if (options?.onStdout && stdout) options.onStdout(stdout);
+      if (options?.onStderr && stderr) options.onStderr(stderr);
+      return {
+        command: fullCommand,
+        args,
+        success: finished.exitCode === 0,
+        exitCode: finished.exitCode,
+        stdout,
+        stderr,
+        executionTimeMs: Date.now() - startTime
+      };
+    } finally {
+      if (timeoutId) clearTimeout(timeoutId);
+      options?.abortSignal?.removeEventListener("abort", forwardAbort);
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Info & Instructions
+  // ---------------------------------------------------------------------------
+  getInfo() {
+    const domains = {};
+    if (this._sandbox && this._ports?.length) {
+      for (const port of this._ports) {
+        try {
+          domains[port] = this._sandbox.domain(port);
+        } catch {
+        }
+      }
+    }
+    return {
+      id: this.id,
+      name: this.name,
+      provider: this.provider,
+      status: this.status,
+      createdAt: this._createdAt ?? /* @__PURE__ */ new Date(),
+      metadata: {
+        ...this._metadata,
+        sandboxName: this._sandbox?.name,
+        runtime: this._runtime,
+        timeout: this._timeout,
+        ...this._vcpus ? { vcpus: this._vcpus } : {},
+        ...this._ports?.length ? { ports: this._ports, domains } : {}
+      }
+    };
+  }
+  // Matches the resolveInstructions pattern in @mastra/core/workspace.
+  getInstructions(opts) {
+    if (this._instructionsOverride === void 0) return this._getDefaultInstructions();
+    if (typeof this._instructionsOverride === "string") return this._instructionsOverride;
+    const defaultInstructions = this._getDefaultInstructions();
+    return this._instructionsOverride({ defaultInstructions, requestContext: opts?.requestContext });
+  }
+  _getDefaultInstructions() {
+    return [
+      "Vercel Sandbox: an ephemeral Firecracker MicroVM running Amazon Linux 2023.",
+      `- Runtime: ${this._runtime}. Working directory defaults to /vercel/sandbox.`,
+      "- Persistent filesystem within the session; state is lost when the sandbox stops.",
+      "- Runs as the vercel-sandbox user with sudo access (install packages via dnf).",
+      `- The sandbox auto-terminates after ${Math.round(this._timeout / 1e3)} seconds.`,
+      ...this._ports?.length ? [`- Exposed ports: ${this._ports.join(", ")} (reachable via public HTTPS domains).`] : [],
+      "- Background/long-running processes are supported via the process tools.",
+      "- Filesystem mounting (FUSE) is not supported."
+    ].join("\n");
+  }
+};
+
+// src/microvm-provider.ts
+var vercelMicroVMSandboxProvider = {
+  id: "vercel-microvm",
+  name: "Vercel Sandbox (MicroVM)",
+  description: "Ephemeral Firecracker MicroVM sandbox powered by Vercel Sandbox",
+  configSchema: {
+    type: "object",
+    properties: {
+      token: { type: "string", description: "Vercel API token (falls back to VERCEL_TOKEN; omit to use OIDC)" },
+      teamId: { type: "string", description: "Vercel team ID (falls back to VERCEL_TEAM_ID)" },
+      projectId: { type: "string", description: "Vercel project ID (falls back to VERCEL_PROJECT_ID)" },
+      runtime: {
+        type: "string",
+        description: "Sandbox runtime",
+        enum: ["node24", "node22", "node26", "python3.13"],
+        default: "node24"
+      },
+      timeout: { type: "number", description: "Auto-terminate timeout in milliseconds", default: 3e5 },
+      vcpus: { type: "number", description: "Number of vCPUs (2048 MB memory per vCPU)" },
+      ports: {
+        type: "array",
+        description: "Ports to expose (up to 4)",
+        items: { type: "number" }
+      },
+      env: {
+        type: "object",
+        description: "Environment variables",
+        additionalProperties: { type: "string" }
+      }
+    }
+  },
+  createSandbox: (config) => new VercelMicroVMSandbox({
+    token: config.token,
+    teamId: config.teamId,
+    projectId: config.projectId,
+    runtime: config.runtime,
+    timeout: config.timeout,
+    ...config.vcpus ? { resources: { vcpus: config.vcpus } } : {},
+    ports: config.ports,
+    env: config.env
+  })
+};
 
+exports.VercelMicroVMProcessManager = VercelMicroVMProcessManager;
+exports.VercelMicroVMSandbox = VercelMicroVMSandbox;
 exports.VercelSandbox = VercelSandbox;
+exports.vercelMicroVMSandboxProvider = vercelMicroVMSandboxProvider;
 exports.vercelSandboxProvider = vercelSandboxProvider;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map