@mastra/agentfs 0.1.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# @mastra/agentfs
+
+## 0.1.0-alpha.0
+
+### Minor Changes
+
+- Added AgentFSFilesystem workspace provider — a Turso/SQLite-backed filesystem via the agentfs-sdk that gives agents persistent, database-backed file storage across sessions. ([#13450](https://github.com/mastra-ai/mastra/pull/13450))
+
+  **Basic usage**
+
+  ```ts
+  import { Workspace } from '@mastra/core/workspace';
+  import { AgentFSFilesystem } from '@mastra/agentfs';
+
+  const workspace = new Workspace({
+    filesystem: new AgentFSFilesystem({
+      agentId: 'my-agent',
+    }),
+  });
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`ea86967`](https://github.com/mastra-ai/mastra/commit/ea86967449426e0a3673253bd1c2c052a99d970d), [`db21c21`](https://github.com/mastra-ai/mastra/commit/db21c21a6ae5f33539262cc535342fa8757eb359), [`11f5dbe`](https://github.com/mastra-ai/mastra/commit/11f5dbe9a1e7ad8ef3b1ea34fb4a9fa3631d1587), [`6751354`](https://github.com/mastra-ai/mastra/commit/67513544d1a64be891d9de7624d40aadc895d56e), [`c958cd3`](https://github.com/mastra-ai/mastra/commit/c958cd36627c1eea122ec241b2b15492977a263a), [`86f2426`](https://github.com/mastra-ai/mastra/commit/86f242631d252a172d2f9f9a2ea0feb8647a76b0), [`950eb07`](https://github.com/mastra-ai/mastra/commit/950eb07b7e7354629630e218d49550fdd299c452)]:
+  - @mastra/core@1.13.0-alpha.0

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/README.md

@@ -0,0 +1,58 @@
+# @mastra/agentfs
+
+AgentFS (Turso/SQLite-backed) filesystem provider for Mastra workspaces. Stores files in a local SQLite database via the agentfs-sdk, giving agents persistent storage that survives across sessions.
+
+## Installation
+
+```bash
+npm install @mastra/agentfs
+```
+
+## Usage
+
+```typescript
+import { Agent } from '@mastra/core/agent';
+import { Workspace } from '@mastra/core/workspace';
+import { AgentFSFilesystem } from '@mastra/agentfs';
+
+const workspace = new Workspace({
+  filesystem: new AgentFSFilesystem({
+    agentId: 'my-agent', // stores at .agentfs/my-agent.db
+  }),
+});
+
+const agent = new Agent({
+  name: 'my-agent',
+  model: 'anthropic/claude-opus-4-5',
+  workspace,
+});
+```
+
+### Using an explicit database path
+
+```typescript
+const workspace = new Workspace({
+  filesystem: new AgentFSFilesystem({
+    path: '/data/my-agent.db',
+  }),
+});
+```
+
+### Using a pre-opened AgentFS instance
+
+```typescript
+import { AgentFS } from 'agentfs-sdk';
+import { AgentFSFilesystem } from '@mastra/agentfs';
+
+const agent = await AgentFS.open({ id: 'my-agent' });
+
+const workspace = new Workspace({
+  filesystem: new AgentFSFilesystem({
+    agent, // caller manages open/close
+  }),
+});
+```
+
+## Documentation
+
+For more information, see the [Mastra Workspaces documentation](https://mastra.ai/docs/workspace/overview).

package/dist/filesystem/index.d.ts

@@ -0,0 +1,109 @@
+/**
+ * AgentFS Filesystem Provider
+ *
+ * Implements WorkspaceFilesystem backed by AgentFS (Turso/SQLite).
+ * Follows the same pattern as S3Filesystem.
+ */
+import type { FileContent, FileStat, FileEntry, ReadOptions, WriteOptions, ListOptions, RemoveOptions, CopyOptions, FilesystemIcon, FilesystemInfo, ProviderStatus, MastraFilesystemOptions } from '@mastra/core/workspace';
+import { MastraFilesystem } from '@mastra/core/workspace';
+import { AgentFS } from 'agentfs-sdk';
+/**
+ * AgentFS filesystem provider configuration.
+ */
+export interface AgentFSFilesystemOptions extends MastraFilesystemOptions {
+    /** Unique identifier for this filesystem instance */
+    id?: string;
+    /** Agent ID — creates database at `.agentfs/<agentId>.db` */
+    agentId?: string;
+    /** Explicit database file path */
+    path?: string;
+    /** Pre-opened AgentFS instance (skips open/close — caller manages lifecycle) */
+    agent?: AgentFS;
+    /** Block write operations (default: false) */
+    readOnly?: boolean;
+    /** Human-friendly display name for the UI */
+    displayName?: string;
+    /** Icon identifier for the UI (default: 'database') */
+    icon?: FilesystemIcon;
+    /** Description shown in tooltips */
+    description?: string;
+}
+/**
+ * AgentFS filesystem implementation.
+ *
+ * Stores files in a Turso/SQLite database via the AgentFS SDK.
+ *
+ * @example Using agentId
+ * ```typescript
+ * import { AgentFSFilesystem } from '@mastra/agentfs';
+ *
+ * const fs = new AgentFSFilesystem({ agentId: 'my-agent' });
+ * ```
+ *
+ * @example Using a pre-opened instance
+ * ```typescript
+ * import { AgentFS } from 'agentfs-sdk';
+ * import { AgentFSFilesystem } from '@mastra/agentfs';
+ *
+ * const agent = await AgentFS.open({ id: 'my-agent' });
+ * const fs = new AgentFSFilesystem({ agent });
+ * ```
+ */
+export declare class AgentFSFilesystem extends MastraFilesystem {
+    readonly id: string;
+    readonly name = "AgentFSFilesystem";
+    readonly provider = "agentfs";
+    readonly readOnly?: boolean;
+    status: ProviderStatus;
+    readonly displayName?: string;
+    readonly icon: FilesystemIcon;
+    readonly description?: string;
+    private _agent;
+    private readonly _ownsAgent;
+    private readonly _agentId?;
+    private readonly _path?;
+    constructor(options: AgentFSFilesystemOptions);
+    /** The underlying AgentFS instance, or null if not yet initialized. */
+    get agent(): AgentFS | null;
+    getInfo(): FilesystemInfo<{
+        agentId?: string;
+        dbPath?: string;
+    }>;
+    getInstructions(): string;
+    init(): Promise<void>;
+    destroy(): Promise<void>;
+    private getAgent;
+    private assertWritable;
+    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[]>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileStat>;
+    /**
+     * Check if the path points to a file.
+     * Returns `false` if the path doesn't exist.
+     */
+    isFile(path: string): Promise<boolean>;
+    /**
+     * Check if the path points to a directory.
+     * Returns `false` if the path doesn't exist.
+     */
+    isDirectory(path: string): Promise<boolean>;
+    /**
+     * Recursively create directories, ignoring EEXIST errors.
+     */
+    private mkdirRecursive;
+    /**
+     * Recursively copy a directory tree.
+     */
+    private copyDirRecursive;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/filesystem/index.d.ts.map

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