@mastra/platform-workspace 0.0.0 → 0.1.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @mastra/platform
 
+## 0.1.0-alpha.0
+
+### Minor Changes
+
+- Added Mastra Platform workspace providers for connecting agents to Platform sandboxes and bucket-backed filesystems. ([#18908](https://github.com/mastra-ai/mastra/pull/18908))
+
+  `PlatformFilesystem` and `PlatformSandbox` extend `MastraFilesystem` / `MastraSandbox` from `@mastra/core/workspace` and speak the workspace-proxy wire format (`Authorization: Bearer sk_*`, project-scoped routes at `/v1/projects/:projectId/...`). Both accept config directly and fall back to env vars (`MASTRA_PLATFORM_ACCESS_TOKEN`, `MASTRA_PROJECT_ID`, `MASTRA_ENVIRONMENT_ID`, `MASTRA_PLATFORM_BUCKET_NAME`, `MASTRA_WORKSPACE_PROXY_URL`).
+
+  ```ts
+  import { Workspace } from '@mastra/core/workspace';
+  import { PlatformFilesystem, PlatformSandbox } from '@mastra/platform-workspace';
+
+  const workspace = new Workspace({
+    filesystem: new PlatformFilesystem({ bucketName: 'dev-bucket' }),
+    sandbox: new PlatformSandbox({
+      environmentId: 'env_123',
+      idleTimeoutMinutes: 30,
+      networkIsolation: 'ISOLATED',
+    }),
+  });
+  ```
+
+  Also exports `platformFilesystemProvider` and `platformSandboxProvider` descriptors for hosts that register providers dynamically through the editor's `FilesystemProvider` / `SandboxProvider` registries:
+
+  ```ts
+  import { platformFilesystemProvider, platformSandboxProvider } from '@mastra/platform-workspace';
+
+  registry.registerFilesystem(platformFilesystemProvider);
+  registry.registerSandbox(platformSandboxProvider);
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`45a8e65`](https://github.com/mastra-ai/mastra/commit/45a8e65e1556d1362cb3f25187023c36de26661d), [`c8ed116`](https://github.com/mastra-ai/mastra/commit/c8ed11699f62bcac70102ab4ec84d80d20541da6), [`33f2b88`](https://github.com/mastra-ai/mastra/commit/33f2b88842c09a567f906fac4cb61cd5277ced59)]:
+  - @mastra/core@1.51.0-alpha.11
+
 ## 0.0.1-alpha.0
 
 ### Patch Changes

package/LICENSE.md

@@ -0,0 +1,30 @@
+Portions of this software are licensed as follows:
+
+- All content that resides under any directory named "ee/" within this
+  repository, including but not limited to:
+  - `packages/core/src/auth/ee/`
+  - `packages/server/src/server/auth/ee/`
+    is licensed under the license defined in `ee/LICENSE`.
+
+- All third-party components incorporated into the Mastra Software are
+  licensed under the original license provided by the owner of the
+  applicable component.
+
+- Content outside of the above-mentioned directories or restrictions is
+  available under the "Apache License 2.0" as defined below.
+
+# Apache License 2.0
+
+Copyright (c) 2025 Kepler Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/dist/client.d.ts

@@ -0,0 +1,44 @@
+export interface PlatformClientOptions {
+    accessToken?: string;
+    projectId?: string;
+    fetch?: typeof fetch;
+}
+export interface PlatformRequestOptions extends RequestInit {
+    query?: Record<string, string | number | boolean | undefined>;
+}
+export declare function requireOption(value: string | undefined, name: string): string;
+export declare function resolvePlatformOptions(options: PlatformClientOptions): {
+    accessToken: string;
+    projectId: string;
+    proxyUrl: string;
+    fetch: typeof fetch;
+};
+/**
+ * Structured error shape returned by the workspace proxy. All routes emit
+ * `{ error: { message, type } }` on failure — see servers/workspace-proxy in
+ * the Platform repo. Kept as a wire-level type so callers can switch on
+ * `error.code` without re-parsing `error.body`.
+ */
+export interface PlatformProxyError {
+    message: string;
+    /** Machine-readable error kind, e.g. `not_found`, `invalid_request`, `authentication_error`. */
+    type: string;
+}
+export declare class PlatformApiError extends Error {
+    readonly status: number;
+    readonly body: string;
+    /** Machine-readable proxy error kind (e.g. `not_found`), when the response body matches `{ error: { message, type } }`. */
+    readonly code: string | undefined;
+    /** Human-readable proxy error message, when the response body matches `{ error: { message, type } }`. */
+    readonly proxyMessage: string | undefined;
+    constructor(status: number, body: string);
+}
+export declare class PlatformClient {
+    readonly accessToken: string;
+    readonly projectId: string;
+    readonly proxyUrl: string;
+    readonly fetch: typeof fetch;
+    constructor(options: PlatformClientOptions);
+    request(path: string, options?: PlatformRequestOptions): Promise<Response>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,MAAM,WAAW,sBAAuB,SAAQ,WAAW;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;CAC/D;AAWD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG7E;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,qBAAqB;;;;;EAOpE;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,gGAAgG;IAChG,IAAI,EAAE,MAAM,CAAC;CACd;AAkBD,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2HAA2H;IAC3H,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,yGAAyG;IACzG,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE9B,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAUzC;AAED,qBAAa,cAAc;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC;gBAEjB,OAAO,EAAE,qBAAqB;IAQpC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,QAAQ,CAAC;CAoBrF"}

package/dist/filesystem.d.ts

@@ -0,0 +1,62 @@
+import { Buffer } from 'node:buffer';
+import type { RequestContext } from '@mastra/core/request-context';
+import type { CopyOptions, FileContent, FileEntry, FileStat, FilesystemIcon, FilesystemInfo, InstructionsOption, ListOptions, MastraFilesystemOptions, ProviderStatus, ReadOptions, RemoveOptions, WriteOptions } from '@mastra/core/workspace';
+import { MastraFilesystem } from '@mastra/core/workspace';
+import type { PlatformClientOptions } from './client.js';
+export interface PlatformFilesystemOptions extends PlatformClientOptions, MastraFilesystemOptions {
+    id?: string;
+    bucketName?: string;
+    readOnly?: boolean;
+    displayName?: string;
+    icon?: FilesystemIcon;
+    description?: string;
+    instructions?: InstructionsOption;
+}
+export declare class PlatformFilesystem extends MastraFilesystem {
+    readonly id: string;
+    readonly name = "PlatformFilesystem";
+    readonly provider = "platform";
+    readonly readOnly?: boolean;
+    readonly displayName?: string;
+    readonly icon: FilesystemIcon;
+    readonly description?: string;
+    status: ProviderStatus;
+    private readonly _client;
+    private readonly _bucketName;
+    private readonly _instructionsOverride?;
+    constructor(options?: PlatformFilesystemOptions);
+    private generateId;
+    readFile(path: string, options?: ReadOptions): Promise<string | Buffer>;
+    writeFile(path: string, content: FileContent, options?: WriteOptions): Promise<void>;
+    /**
+     * 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.
+     */
+    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[]>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileStat>;
+    realpath(path: string): Promise<string>;
+    getInstructions(opts?: {
+        requestContext?: RequestContext;
+    }): string;
+    getInfo(): FilesystemInfo<{
+        bucketName: string;
+        displayName?: string;
+        description?: string;
+    }>;
+}
+//# sourceMappingURL=filesystem.d.ts.map

package/dist/filesystem.d.ts.map

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