Add support for syncing filesystem to Turso Cloud

Author: penberg

sdk/typescript/examples/turso-cloud/simple.ts

@@ -0,0 +1,71 @@
+import { AgentFS, tursoSync } from "agentfs-sdk";
+
+/**
+ * Simple Turso Cloud Sync Example
+ *
+ * This example demonstrates the minimal setup for syncing an AgentFS instance
+ * with Turso Cloud using environment variables.
+ *
+ * Prerequisites:
+ * - Set TURSO_API_TOKEN environment variable with your Turso API token
+ * - Optionally set TURSO_API_ORG (defaults to your primary org)
+ *
+ * The sync provider will automatically:
+ * 1. Create a database named 'simple-agent' if it doesn't exist
+ * 2. Generate an auth token for the database
+ * 3. Setup bidirectional sync
+ * 4. Enable auto-sync every 60 seconds
+ */
+async function main() {
+  console.log("=== Simple Turso Cloud Sync Example ===\n");
+
+  // Check for required environment variable
+  if (!process.env.TURSO_API_TOKEN) {
+    console.error("Error: TURSO_API_TOKEN environment variable is required");
+    console.error("Get your token from: https://turso.tech/app");
+    process.exit(1);
+  }
+
+  // Open AgentFS with Turso Cloud sync
+  // This will create a database named 'simple-agent' in Turso Cloud
+  console.log("Opening AgentFS with Turso Cloud sync...");
+  const agent = await AgentFS.open({
+    id: "simple-agent",
+    sync: tursoSync(), // Uses all defaults from environment variables
+  });
+
+  console.log("✓ Connected to Turso Cloud\n");
+
+  // Store some data
+  console.log("Storing data locally...");
+  await agent.kv.set("greeting", "Hello from AgentFS!");
+  await agent.kv.set("timestamp", new Date().toISOString());
+  await agent.kv.set("counter", 42);
+
+  console.log("✓ Data stored locally\n");
+
+  // Manual sync to cloud
+  console.log("Syncing to Turso Cloud...");
+  await agent.sync!.push();
+  console.log("✓ Data pushed to cloud\n");
+
+  // Check sync status
+  const status = agent.sync!.getStatus();
+  console.log("Sync status:", {
+    state: status.state,
+    lastSync: status.lastSync?.toISOString(),
+  });
+
+  console.log("\n=== Auto-sync is enabled ===");
+  console.log("Your data will automatically sync every 60 seconds.");
+  console.log("Try modifying the cloud database and run this again to see changes pulled down.\n");
+
+  // Cleanup
+  await agent.close();
+  console.log("✓ Connection closed");
+}
+
+main().catch((error) => {
+  console.error("Error:", error.message);
+  process.exit(1);
+});

sdk/typescript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfs-sdk",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "AgentFS SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,7 +20,9 @@
     "turso",
     "sqlite",
     "key-value",
-    "filesystem"
+    "filesystem",
+    "sync",
+    "cloud"
   ],
   "author": "",
   "license": "MIT",
@@ -33,6 +35,10 @@
   "dependencies": {
     "@tursodatabase/database": "^0.3.2"
   },
+  "optionalDependencies": {
+    "@tursodatabase/api": "^1.9.0",
+    "@tursodatabase/sync": "^0.3.2"
+  },
   "files": [
     "dist"
   ]

sdk/typescript/src/index.ts

@@ -3,6 +3,8 @@ import { existsSync, mkdirSync } from 'fs';
 import { KvStore } from './kvstore';
 import { Filesystem } from './filesystem';
 import { ToolCalls } from './toolcalls';
+import type { SyncProvider, TursoSyncFactory } from './sync';
+import { TursoSyncProvider } from './providers/turso';
 
 /**
  * Configuration options for opening an AgentFS instance
@@ -14,8 +16,13 @@ export interface AgentFSOptions {
    * - If omitted: Uses ephemeral in-memory database
    */
   id?: string;
-  // Future: sync configuration will be added here
-  // sync?: SyncConfig;
+
+  /**
+   * Optional sync configuration
+   * - Pass a TursoSyncFactory from tursoSync() for Turso Cloud sync
+   * - Pass a custom SyncProvider for other backends
+   */
+  sync?: TursoSyncFactory | SyncProvider;
 }
 
 export class AgentFS {
@@ -24,15 +31,23 @@ export class AgentFS {
   public readonly kv: KvStore;
   public readonly fs: Filesystem;
   public readonly tools: ToolCalls;
+  public readonly sync?: SyncProvider;
 
   /**
    * Private constructor - use AgentFS.open() instead
    */
-  private constructor(db: Database, kv: KvStore, fs: Filesystem, tools: ToolCalls) {
+  private constructor(
+    db: Database,
+    kv: KvStore,
+    fs: Filesystem,
+    tools: ToolCalls,
+    sync?: SyncProvider
+  ) {
     this.db = db;
     this.kv = kv;
     this.fs = fs;
     this.tools = tools;
+    this.sync = sync;
   }
 
   /**
@@ -47,6 +62,13 @@ export class AgentFS {
    *
    * // Ephemeral in-memory database
    * const agent = await AgentFS.open();
+   *
+   * // With Turso Cloud sync
+   * import { tursoSync } from 'agentfs-sdk';
+   * const agent = await AgentFS.open({
+   *   id: 'my-agent',
+   *   sync: tursoSync()
+   * });
    * ```
    */
   static async open(options?: AgentFSOptions): Promise<AgentFS> {
@@ -60,7 +82,7 @@ export class AgentFS {
       );
     }
 
-    const { id } = options || {};
+    const { id, sync } = options || {};
 
     // Determine database path based on id
     let dbPath: string;
@@ -91,8 +113,22 @@ export class AgentFS {
     await fs.ready();
     await tools.ready();
 
+    // Initialize sync if configured
+    let syncProvider: SyncProvider | undefined;
+    if (sync) {
+      if ('__type' in sync && sync.__type === 'turso-sync-factory') {
+        // Turso sync factory
+        syncProvider = new TursoSyncProvider(db, id || 'default', sync.config);
+      } else {
+        // Custom sync provider
+        syncProvider = sync as SyncProvider;
+      }
+
+      await syncProvider.initialize();
+    }
+
     // Return fully initialized instance
-    return new AgentFS(db, kv, fs, tools);
+    return new AgentFS(db, kv, fs, tools, syncProvider);
   }
 
   /**
@@ -103,9 +139,12 @@ export class AgentFS {
   }
 
   /**
-   * Close the database connection
+   * Close the database connection and cleanup sync
    */
   async close(): Promise<void> {
+    if (this.sync) {
+      await this.sync.cleanup();
+    }
     await this.db.close();
   }
 }
@@ -115,3 +154,5 @@ export { Filesystem } from './filesystem';
 export type { Stats } from './filesystem';
 export { ToolCalls } from './toolcalls';
 export type { ToolCall, ToolCallStats } from './toolcalls';
+export { tursoSync } from './sync';
+export type { SyncProvider, TursoSyncConfig, SyncStatus } from './sync';