@mastra/platform-workspace 0.0.0 → 0.1.0

package/dist/index.js

@@ -0,0 +1,588 @@
+import { Buffer } from 'buffer';
+import nodePath from 'path';
+import { MastraFilesystem, FileNotFoundError, WorkspaceReadOnlyError, FileExistsError, MastraSandbox, SandboxNotReadyError, SandboxProcessManager, ProcessHandle } from '@mastra/core/workspace';
+
+// src/client.ts
+var DEFAULT_PROXY_URL = "https://workspaces.mastra.ai";
+var DEFAULT_REQUEST_TIMEOUT_MS = 6e4;
+function requireOption(value, name) {
+  if (!value) throw new Error(`${name} is required`);
+  return value;
+}
+function resolvePlatformOptions(options) {
+  return {
+    accessToken: requireOption(options.accessToken ?? process.env.MASTRA_PLATFORM_ACCESS_TOKEN, "accessToken"),
+    projectId: requireOption(options.projectId ?? process.env.MASTRA_PROJECT_ID, "projectId"),
+    proxyUrl: (process.env.MASTRA_WORKSPACE_PROXY_URL ?? DEFAULT_PROXY_URL).replace(/\/$/, ""),
+    fetch: options.fetch ?? fetch
+  };
+}
+function parseProxyError(body) {
+  if (!body) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    return void 0;
+  }
+  if (typeof parsed !== "object" || parsed === null) return void 0;
+  const err = parsed.error;
+  if (typeof err !== "object" || err === null) return void 0;
+  const { message, type } = err;
+  if (typeof message !== "string" || typeof type !== "string") return void 0;
+  return { message, type };
+}
+var PlatformApiError = class extends Error {
+  status;
+  body;
+  /** Machine-readable proxy error kind (e.g. `not_found`), when the response body matches `{ error: { message, type } }`. */
+  code;
+  /** Human-readable proxy error message, when the response body matches `{ error: { message, type } }`. */
+  proxyMessage;
+  constructor(status, body) {
+    const parsed = parseProxyError(body);
+    const summary = parsed ? `${parsed.type}: ${parsed.message}` : body;
+    super(`Platform proxy request failed with ${status}${summary ? `: ${summary}` : ""}`);
+    this.name = "PlatformApiError";
+    this.status = status;
+    this.body = body;
+    this.code = parsed?.type;
+    this.proxyMessage = parsed?.message;
+  }
+};
+var PlatformClient = class {
+  accessToken;
+  projectId;
+  proxyUrl;
+  fetch;
+  constructor(options) {
+    const resolved = resolvePlatformOptions(options);
+    this.accessToken = resolved.accessToken;
+    this.projectId = resolved.projectId;
+    this.proxyUrl = resolved.proxyUrl;
+    this.fetch = resolved.fetch;
+  }
+  async request(path, options = {}) {
+    const url = new URL(`${this.proxyUrl}/v1/projects/${encodeURIComponent(this.projectId)}${path}`);
+    for (const [key, value] of Object.entries(options.query ?? {})) {
+      if (value !== void 0) url.searchParams.set(key, String(value));
+    }
+    const headers = new Headers(options.headers);
+    headers.set("authorization", `Bearer ${this.accessToken}`);
+    const { query: _query, ...fetchOptions } = options;
+    const signal = fetchOptions.signal ?? AbortSignal.timeout(DEFAULT_REQUEST_TIMEOUT_MS);
+    const response = await this.fetch(url, { ...fetchOptions, headers, signal });
+    if (!response.ok) {
+      throw new PlatformApiError(response.status, await response.text());
+    }
+    return response;
+  }
+};
+function normalizePath(input) {
+  if (!input || input === ".") return "/";
+  let normalized = input.startsWith("/") ? input : `/${input}`;
+  normalized = nodePath.posix.normalize(normalized);
+  return normalized === "." ? "/" : normalized;
+}
+function keyFromPath(path) {
+  const normalized = normalizePath(path);
+  return normalized === "/" ? "" : normalized.slice(1);
+}
+function encodeKeyPath(key) {
+  return key.split("/").map(encodeURIComponent).join("/");
+}
+function nameFromPath(path) {
+  const normalized = normalizePath(path);
+  if (normalized === "/") return "";
+  return normalized.slice(normalized.lastIndexOf("/") + 1);
+}
+function contentToBody(content) {
+  if (typeof content === "string") return content;
+  return Buffer.from(content);
+}
+function headerDate(headers, name) {
+  const value = headers.get(name);
+  return value ? new Date(value) : /* @__PURE__ */ new Date(0);
+}
+function headerSize(headers) {
+  const value = headers.get("content-length");
+  return value ? Number(value) : 0;
+}
+function isNotFound(error) {
+  return typeof error === "object" && error !== null && "status" in error && error.status === 404;
+}
+var PlatformFilesystem = class extends MastraFilesystem {
+  id;
+  name = "PlatformFilesystem";
+  provider = "platform";
+  readOnly;
+  displayName;
+  icon;
+  description;
+  status = "pending";
+  _client;
+  _bucketName;
+  _instructionsOverride;
+  constructor(options = {}) {
+    super({ ...options, name: "PlatformFilesystem" });
+    this.id = options.id ?? this.generateId();
+    this._bucketName = options.bucketName ?? process.env.MASTRA_PLATFORM_BUCKET_NAME ?? "";
+    if (!this._bucketName) throw new Error("bucketName is required");
+    this.readOnly = options.readOnly;
+    this.displayName = options.displayName;
+    this.icon = options.icon ?? "cloud";
+    this.description = options.description;
+    this._instructionsOverride = options.instructions;
+    this._client = new PlatformClient(options);
+  }
+  generateId() {
+    return `platform-fs-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  }
+  async readFile(path, options) {
+    await this.ensureReady();
+    let response;
+    try {
+      response = await this._client.request(
+        `/fs/${encodeURIComponent(this._bucketName)}/${encodeKeyPath(keyFromPath(path))}`
+      );
+    } catch (error) {
+      if (isNotFound(error)) throw new FileNotFoundError(path);
+      throw error;
+    }
+    const buffer = Buffer.from(await response.arrayBuffer());
+    return options?.encoding ? buffer.toString(options.encoding) : buffer;
+  }
+  async writeFile(path, content, options) {
+    await this.ensureReady();
+    if (this.readOnly) throw new WorkspaceReadOnlyError("writeFile");
+    const headers = {};
+    if (options?.mimeType) headers["content-type"] = options.mimeType;
+    if (options?.overwrite === false) headers["if-none-match"] = "*";
+    try {
+      await this._client.request(`/fs/${encodeURIComponent(this._bucketName)}/${encodeKeyPath(keyFromPath(path))}`, {
+        method: "PUT",
+        headers,
+        body: contentToBody(content)
+      });
+    } catch (error) {
+      if (typeof error === "object" && error !== null && "status" in error && error.status === 412) {
+        throw new FileExistsError(path);
+      }
+      throw error;
+    }
+  }
+  /**
+   * Append bytes to a file.
+   *
+   * **Not atomic.** Object storage behind the workspace proxy has no native
+   * append or compare-and-swap primitive, so this implementation is a
+   * read-modify-write: it reads the current contents, concatenates the new
+   * bytes, and PUTs the whole object back. Concurrent `appendFile` calls to
+   * the same path can overwrite each other's writes ("last write wins").
+   * Use `writeFile` with distinct keys for concurrent writers.
+   */
+  async appendFile(path, content) {
+    const existing = await this.exists(path) ? await this.readFile(path) : Buffer.alloc(0);
+    await this.writeFile(
+      path,
+      Buffer.concat([Buffer.isBuffer(existing) ? existing : Buffer.from(existing), Buffer.from(content)])
+    );
+  }
+  async deleteFile(path, options) {
+    await this.ensureReady();
+    if (this.readOnly) throw new WorkspaceReadOnlyError("deleteFile");
+    try {
+      await this._client.request(`/fs/${encodeURIComponent(this._bucketName)}/${encodeKeyPath(keyFromPath(path))}`, {
+        method: "DELETE",
+        query: { recursive: options?.recursive }
+      });
+    } catch (error) {
+      if (isNotFound(error) && options?.force) return;
+      if (isNotFound(error)) throw new FileNotFoundError(path);
+      throw error;
+    }
+  }
+  async copyFile(src, dest, options) {
+    await this.ensureReady();
+    if (this.readOnly) throw new WorkspaceReadOnlyError("copyFile");
+    if (options?.overwrite === false) {
+      throw new Error("PlatformFilesystem.copyFile does not support overwrite: false \u2014 the proxy always overwrites.");
+    }
+    await this._client.request(`/fs/${encodeURIComponent(this._bucketName)}/${encodeKeyPath(keyFromPath(src))}`, {
+      method: "POST",
+      query: { op: "copy" },
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ destination: keyFromPath(dest) })
+    });
+  }
+  async moveFile(src, dest, options) {
+    await this.ensureReady();
+    if (this.readOnly) throw new WorkspaceReadOnlyError("moveFile");
+    if (options?.overwrite === false) {
+      throw new Error("PlatformFilesystem.moveFile does not support overwrite: false \u2014 the proxy always overwrites.");
+    }
+    await this._client.request(`/fs/${encodeURIComponent(this._bucketName)}/${encodeKeyPath(keyFromPath(src))}`, {
+      method: "POST",
+      query: { op: "rename" },
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ destination: keyFromPath(dest) })
+    });
+  }
+  async mkdir(path, _options) {
+    await this.ensureReady();
+    if (this.readOnly) throw new WorkspaceReadOnlyError("mkdir");
+    await this._client.request(`/fs/${encodeURIComponent(this._bucketName)}/${encodeKeyPath(keyFromPath(path))}`, {
+      method: "POST",
+      query: { op: "mkdir" }
+    });
+  }
+  async rmdir(path, options) {
+    await this.deleteFile(path.endsWith("/") ? path : `${path}/`, { recursive: true, force: options?.force });
+  }
+  async readdir(path, options) {
+    await this.ensureReady();
+    const prefix = keyFromPath(path);
+    const response = await this._client.request(
+      `/fs/${encodeURIComponent(this._bucketName)}/${encodeKeyPath(prefix)}`,
+      {
+        query: {
+          delimiter: options?.recursive ? void 0 : "/",
+          prefix: prefix ? `${prefix.replace(/\/$/, "")}/` : void 0
+        }
+      }
+    );
+    const json = await response.json();
+    return [
+      ...(json.commonPrefixes ?? []).map((prefix2) => ({
+        name: nameFromPath(prefix2.replace(/\/$/, "")),
+        type: "directory"
+      })),
+      ...(json.contents ?? []).filter((object) => object.key && !object.key.endsWith("/")).map((object) => ({
+        name: nameFromPath(object.key),
+        type: "file",
+        size: object.size
+      }))
+    ].filter(
+      (entry) => !options?.extension || entry.type === "directory" || matchesExtension(entry.name, options.extension)
+    );
+  }
+  async exists(path) {
+    try {
+      await this.stat(path);
+      return true;
+    } catch (error) {
+      if (isNotFound(error) || error instanceof FileNotFoundError) return false;
+      throw error;
+    }
+  }
+  async stat(path) {
+    await this.ensureReady();
+    const normalized = normalizePath(path);
+    if (normalized === "/") {
+      return { name: "", path: "/", type: "directory", size: 0, createdAt: /* @__PURE__ */ new Date(0), modifiedAt: /* @__PURE__ */ new Date(0) };
+    }
+    let response;
+    try {
+      response = await this._client.request(
+        `/fs/${encodeURIComponent(this._bucketName)}/${encodeKeyPath(keyFromPath(path))}`,
+        {
+          method: "HEAD"
+        }
+      );
+    } catch (error) {
+      if (isNotFound(error)) throw new FileNotFoundError(path);
+      throw error;
+    }
+    return {
+      name: nameFromPath(path),
+      path: normalized,
+      type: normalized.endsWith("/") ? "directory" : "file",
+      size: headerSize(response.headers),
+      createdAt: headerDate(response.headers, "last-modified"),
+      modifiedAt: headerDate(response.headers, "last-modified"),
+      mimeType: response.headers.get("content-type") ?? void 0
+    };
+  }
+  realpath(path) {
+    return Promise.resolve(normalizePath(path));
+  }
+  getInstructions(opts) {
+    const defaultInstructions = `Platform filesystem backed by Mastra Platform bucket ${this._bucketName}. Use absolute workspace paths.`;
+    if (typeof this._instructionsOverride === "function") {
+      return this._instructionsOverride({ defaultInstructions, requestContext: opts?.requestContext });
+    }
+    if (typeof this._instructionsOverride === "string") return this._instructionsOverride;
+    return defaultInstructions;
+  }
+  getInfo() {
+    return {
+      id: this.id,
+      name: this.name,
+      provider: this.provider,
+      status: this.status,
+      readOnly: this.readOnly,
+      icon: this.icon,
+      metadata: {
+        bucketName: this._bucketName,
+        ...this.displayName && { displayName: this.displayName },
+        ...this.description && { description: this.description }
+      }
+    };
+  }
+};
+function matchesExtension(name, extension) {
+  const extensions = Array.isArray(extension) ? extension : [extension];
+  return extensions.some((ext) => name.endsWith(ext));
+}
+function buildCommand(command, args) {
+  return args?.length ? `${command} ${args.map(shellQuote).join(" ")}` : command;
+}
+function shellQuote(arg) {
+  if (/^[a-zA-Z0-9._\-/=:@]+$/.test(arg)) return arg;
+  return `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+var PlatformProcessHandle = class extends ProcessHandle {
+  pid;
+  resultPromise;
+  exitCodeValue;
+  constructor(pid, resultPromise, options) {
+    super(options);
+    this.pid = pid;
+    this.resultPromise = resultPromise.then((result) => {
+      this.exitCodeValue = result.exitCode;
+      if (result.stdout) this.emitStdout(result.stdout);
+      if (result.stderr) this.emitStderr(result.stderr);
+      return result;
+    });
+  }
+  get exitCode() {
+    return this.exitCodeValue;
+  }
+  async wait() {
+    return this.resultPromise;
+  }
+  async kill() {
+    throw new Error("Platform sandbox command execution does not support killing individual processes");
+  }
+  async sendStdin() {
+    throw new Error("Platform sandbox command execution does not support stdin");
+  }
+};
+var PlatformProcessManager = class extends SandboxProcessManager {
+  spawnCounter = 0;
+  /**
+   * Spawn a process on the remote sandbox.
+   *
+   * `command` is interpreted as a shell string by the remote shell, matching
+   * the {@link MastraSandbox} contract. See {@link PlatformSandbox.executeCommand}
+   * for the untrusted-input caveat: never pass untrusted values as `command`.
+   */
+  async spawn(command, options = {}) {
+    const pid = `platform-proc-${Date.now().toString(36)}-${(this.spawnCounter++).toString(36)}`;
+    const resultPromise = this.sandbox.executeCommand(command, void 0, options);
+    const handle = new PlatformProcessHandle(pid, resultPromise, options);
+    this._tracked.set(handle.pid, handle);
+    return handle;
+  }
+  async list() {
+    return Array.from(this._tracked.values()).map((handle) => ({
+      pid: handle.pid,
+      command: handle.command,
+      running: handle.exitCode === void 0,
+      ...handle.exitCode !== void 0 && { exitCode: handle.exitCode }
+    }));
+  }
+};
+var PlatformSandbox = class extends MastraSandbox {
+  id;
+  name = "PlatformSandbox";
+  provider = "platform";
+  status = "pending";
+  _client;
+  _environmentId;
+  _sandboxId;
+  _idleTimeoutMinutes;
+  _networkIsolation;
+  _env;
+  _timeout;
+  _instructionsOverride;
+  _createdAt = null;
+  constructor(options = {}) {
+    super({ ...options, name: "PlatformSandbox", processes: new PlatformProcessManager() });
+    this.id = options.id ?? this.generateId();
+    this._client = new PlatformClient(options);
+    this._environmentId = options.environmentId ?? process.env.MASTRA_ENVIRONMENT_ID ?? "";
+    if (!this._environmentId && !options.sandboxId) throw new Error("environmentId is required");
+    this._sandboxId = options.sandboxId;
+    this._idleTimeoutMinutes = options.idleTimeoutMinutes;
+    this._networkIsolation = options.networkIsolation;
+    this._env = options.env ?? {};
+    this._timeout = options.timeout;
+    this._instructionsOverride = options.instructions;
+  }
+  generateId() {
+    return `platform-sandbox-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  }
+  async start() {
+    if (this._sandboxId) {
+      this._createdAt = /* @__PURE__ */ new Date();
+      return;
+    }
+    const response = await this._client.request("/sandbox", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        environmentId: this._environmentId,
+        idleTimeoutMinutes: this._idleTimeoutMinutes,
+        networkIsolation: this._networkIsolation,
+        env: this._env
+      })
+    });
+    const json = await response.json();
+    this._sandboxId = json.id;
+    this._createdAt = json.createdAt ? new Date(json.createdAt) : /* @__PURE__ */ new Date();
+  }
+  async stop() {
+    await this.destroy();
+  }
+  async destroy() {
+    if (!this._sandboxId) return;
+    await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}`, { method: "DELETE" });
+    this._sandboxId = void 0;
+    this._createdAt = null;
+  }
+  /**
+   * Execute a command on the remote sandbox.
+   *
+   * `command` is a **shell string**: it is concatenated verbatim into the
+   * command line sent to the remote shell, which lets callers use pipes,
+   * redirects, and chaining (`ls -la | grep foo`). This matches the contract
+   * of {@link MastraSandbox} and the local sandbox implementation.
+   *
+   * `args`, when provided, are always shell-quoted so they cannot inject
+   * additional shell syntax.
+   *
+   * Security: callers MUST NOT pass untrusted input as `command`. If any part
+   * of the invocation is derived from an untrusted source, pass it through
+   * `args` (which is safely quoted) or shell-quote it yourself before
+   * inclusion. Untrusted `command` values allow arbitrary shell syntax
+   * execution on the remote sandbox.
+   */
+  async executeCommand(command, args, options) {
+    await this.ensureRunning();
+    if (!this._sandboxId) throw new SandboxNotReadyError(this.id);
+    const started = Date.now();
+    const fullCommand = buildCommand(command, args);
+    const effectiveTimeout = options?.timeout ?? this._timeout;
+    const timeoutSec = effectiveTimeout != null ? Math.ceil(effectiveTimeout / 1e3) : void 0;
+    const clientSignal = effectiveTimeout != null && effectiveTimeout > 0 ? AbortSignal.timeout(effectiveTimeout + 3e4) : void 0;
+    const response = await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}/exec`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        command: fullCommand,
+        timeoutSec,
+        cwd: options?.cwd,
+        env: options?.env
+      }),
+      signal: clientSignal
+    });
+    const json = await response.json();
+    const exitCode = json.exitCode ?? (json.timedOut ? 124 : 1);
+    return {
+      success: exitCode === 0,
+      exitCode,
+      stdout: json.stdout,
+      stderr: json.stderr,
+      executionTimeMs: Date.now() - started,
+      timedOut: json.timedOut,
+      command: fullCommand
+    };
+  }
+  async getInfo() {
+    if (!this._sandboxId) {
+      return {
+        id: this.id,
+        name: this.name,
+        provider: this.provider,
+        status: this.status,
+        createdAt: this._createdAt ?? /* @__PURE__ */ new Date()
+      };
+    }
+    const response = await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}`);
+    const json = await response.json();
+    return {
+      id: json.id,
+      name: this.name,
+      provider: this.provider,
+      status: this.status,
+      createdAt: json.createdAt ? new Date(json.createdAt) : this._createdAt ?? /* @__PURE__ */ new Date(),
+      metadata: {
+        providerResourceId: json.providerResourceId ?? void 0,
+        platformStatus: json.status
+      }
+    };
+  }
+  getInstructions(opts) {
+    const defaultInstructions = `Platform sandbox${this._sandboxId ? ` ${this._sandboxId}` : ""}. Execute commands with the sandbox command APIs.`;
+    if (typeof this._instructionsOverride === "function") {
+      return this._instructionsOverride({ defaultInstructions, requestContext: opts?.requestContext });
+    }
+    if (typeof this._instructionsOverride === "string") return this._instructionsOverride;
+    return defaultInstructions;
+  }
+};
+
+// src/provider.ts
+var platformSandboxProvider = {
+  id: "platform",
+  name: "Mastra Platform Sandbox",
+  description: "Environment-scoped sandbox execution through Mastra Platform workspace proxy",
+  configSchema: {
+    type: "object",
+    properties: {
+      accessToken: {
+        type: "string",
+        description: "Mastra Platform access token (falls back to MASTRA_PLATFORM_ACCESS_TOKEN)"
+      },
+      projectId: { type: "string", description: "Platform project ID (falls back to MASTRA_PROJECT_ID)" },
+      environmentId: { type: "string", description: "Platform environment ID (falls back to MASTRA_ENVIRONMENT_ID)" },
+      sandboxId: { type: "string", description: "Reattach to an existing Platform sandbox by ID" },
+      idleTimeoutMinutes: { type: "number", description: "Minutes before the sandbox can be destroyed while idle" },
+      networkIsolation: {
+        type: "string",
+        description: "Network isolation mode",
+        enum: ["ISOLATED", "PRIVATE"],
+        default: "ISOLATED"
+      },
+      env: { type: "object", description: "Environment variables", additionalProperties: { type: "string" } },
+      timeout: { type: "number", description: "Default command timeout in ms" }
+    }
+  },
+  createSandbox: (config) => new PlatformSandbox(config)
+};
+var platformFilesystemProvider = {
+  id: "platform",
+  name: "Mastra Platform Filesystem",
+  description: "Bucket-backed filesystem access through Mastra Platform workspace proxy",
+  configSchema: {
+    type: "object",
+    properties: {
+      accessToken: {
+        type: "string",
+        description: "Mastra Platform access token (falls back to MASTRA_PLATFORM_ACCESS_TOKEN)"
+      },
+      projectId: { type: "string", description: "Platform project ID (falls back to MASTRA_PROJECT_ID)" },
+      bucketName: {
+        type: "string",
+        description: "Platform workspace bucket name (falls back to MASTRA_PLATFORM_BUCKET_NAME)"
+      },
+      readOnly: { type: "boolean", description: "Mount as read-only", default: false }
+    }
+  },
+  createFilesystem: (config) => new PlatformFilesystem(config)
+};
+
+export { PlatformApiError, PlatformClient, PlatformFilesystem, PlatformSandbox, platformFilesystemProvider, platformSandboxProvider };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map