agentfs-sdk 0.2.0-pre.1 → 0.2.0-pre.3

package/dist/filesystem.d.ts

@@ -17,10 +17,15 @@ export declare class Filesystem {
     private db;
     private initialized;
     private rootIno;
+    private chunkSize;
     constructor(db: Database);
+    /**
+     * Get the configured chunk size
+     */
+    getChunkSize(): number;
     private initialize;
     /**
-     * Ensure root directory exists
+     * Ensure config and root directory exist, returns the chunk_size
      */
     private ensureRoot;
     /**
@@ -57,7 +62,7 @@ export declare class Filesystem {
     private getLinkCount;
     writeFile(path: string, content: string | Buffer): Promise<void>;
     private updateFileContent;
-    readFile(path: string): Promise<string>;
+    readFile(path: string, encoding?: BufferEncoding): Promise<Buffer | string>;
     readdir(path: string): Promise<string[]>;
     deleteFile(path: string): Promise<void>;
     stat(path: string): Promise<Stats>;

package/dist/filesystem.js

@@ -9,12 +9,20 @@ const S_IFLNK = 0o120000; // Symbolic link
 // Default permissions
 const DEFAULT_FILE_MODE = S_IFREG | 0o644; // Regular file, rw-r--r--
 const DEFAULT_DIR_MODE = S_IFDIR | 0o755; // Directory, rwxr-xr-x
+const DEFAULT_CHUNK_SIZE = 4096;
 class Filesystem {
     constructor(db) {
         this.rootIno = 1;
+        this.chunkSize = DEFAULT_CHUNK_SIZE;
         this.db = db;
         this.initialized = this.initialize();
     }
+    /**
+     * Get the configured chunk size
+     */
+    getChunkSize() {
+        return this.chunkSize;
+    }
     async initialize() {
         // Ensure database is connected
         try {
@@ -26,6 +34,13 @@ class Filesystem {
                 throw error;
             }
         }
+        // Create the config table
+        await this.db.exec(`
+      CREATE TABLE IF NOT EXISTS fs_config (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      )
+    `);
         // Create the inode table
         await this.db.exec(`
       CREATE TABLE IF NOT EXISTS fs_inode (
@@ -54,20 +69,14 @@ class Filesystem {
       CREATE INDEX IF NOT EXISTS idx_fs_dentry_parent
       ON fs_dentry(parent_ino, name)
     `);
-        // Create the data blocks table
+        // Create the data chunks table
         await this.db.exec(`
       CREATE TABLE IF NOT EXISTS fs_data (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
         ino INTEGER NOT NULL,
-        offset INTEGER NOT NULL,
-        size INTEGER NOT NULL,
-        data BLOB NOT NULL
+        chunk_index INTEGER NOT NULL,
+        data BLOB NOT NULL,
+        PRIMARY KEY (ino, chunk_index)
       )
-    `);
-        // Create index for efficient data block lookups
-        await this.db.exec(`
-      CREATE INDEX IF NOT EXISTS idx_fs_data_ino_offset
-      ON fs_data(ino, offset)
     `);
         // Create the symlink table
         await this.db.exec(`
@@ -76,13 +85,28 @@ class Filesystem {
         target TEXT NOT NULL
       )
     `);
-        // Create root directory if it doesn't exist
-        await this.ensureRoot();
+        // Initialize config and root directory, and get chunk_size
+        this.chunkSize = await this.ensureRoot();
     }
     /**
-     * Ensure root directory exists
+     * Ensure config and root directory exist, returns the chunk_size
      */
     async ensureRoot() {
+        // Ensure chunk_size config exists and get its value
+        const configStmt = this.db.prepare("SELECT value FROM fs_config WHERE key = 'chunk_size'");
+        const config = await configStmt.get();
+        let chunkSize;
+        if (!config) {
+            const insertConfigStmt = this.db.prepare(`
+        INSERT INTO fs_config (key, value) VALUES ('chunk_size', ?)
+      `);
+            await insertConfigStmt.run(DEFAULT_CHUNK_SIZE.toString());
+            chunkSize = DEFAULT_CHUNK_SIZE;
+        }
+        else {
+            chunkSize = parseInt(config.value, 10) || DEFAULT_CHUNK_SIZE;
+        }
+        // Ensure root directory exists
         const stmt = this.db.prepare('SELECT ino FROM fs_inode WHERE ino = ?');
         const root = await stmt.get(this.rootIno);
         if (!root) {
@@ -93,6 +117,7 @@ class Filesystem {
       `);
             await insertStmt.run(this.rootIno, DEFAULT_DIR_MODE, now, now, now);
         }
+        return chunkSize;
     }
     /**
      * Normalize a path
@@ -240,15 +265,22 @@ class Filesystem {
     async updateFileContent(ino, content) {
         const buffer = typeof content === 'string' ? Buffer.from(content, 'utf-8') : content;
         const now = Math.floor(Date.now() / 1000);
-        // Delete existing data blocks
+        // Delete existing data chunks
         const deleteStmt = this.db.prepare('DELETE FROM fs_data WHERE ino = ?');
         await deleteStmt.run(ino);
-        // Write data in chunks (for now, single chunk, but can be extended)
-        const stmt = this.db.prepare(`
-      INSERT INTO fs_data (ino, offset, size, data)
-      VALUES (?, ?, ?, ?)
-    `);
-        await stmt.run(ino, 0, buffer.length, buffer);
+        // Write data in chunks
+        if (buffer.length > 0) {
+            const stmt = this.db.prepare(`
+        INSERT INTO fs_data (ino, chunk_index, data)
+        VALUES (?, ?, ?)
+      `);
+            let chunkIndex = 0;
+            for (let offset = 0; offset < buffer.length; offset += this.chunkSize) {
+                const chunk = buffer.subarray(offset, Math.min(offset + this.chunkSize, buffer.length));
+                await stmt.run(ino, chunkIndex, chunk);
+                chunkIndex++;
+            }
+        }
         // Update inode size and mtime
         const updateStmt = this.db.prepare(`
       UPDATE fs_inode
@@ -257,30 +289,36 @@ class Filesystem {
     `);
         await updateStmt.run(buffer.length, now, ino);
     }
-    async readFile(path) {
+    async readFile(path, encoding) {
         await this.initialized;
         const ino = await this.resolvePath(path);
         if (ino === null) {
             throw new Error(`ENOENT: no such file or directory, open '${path}'`);
         }
-        // Get all data blocks
+        // Get all data chunks
         const stmt = this.db.prepare(`
       SELECT data FROM fs_data
       WHERE ino = ?
-      ORDER BY offset ASC
+      ORDER BY chunk_index ASC
     `);
         const rows = await stmt.all(ino);
+        let combined;
         if (rows.length === 0) {
-            return '';
+            combined = Buffer.alloc(0);
+        }
+        else {
+            // Concatenate all chunks
+            const buffers = rows.map(row => row.data);
+            combined = Buffer.concat(buffers);
         }
-        // Concatenate all chunks
-        const buffers = rows.map(row => row.data);
-        const combined = Buffer.concat(buffers);
         // Update atime
         const now = Math.floor(Date.now() / 1000);
         const updateStmt = this.db.prepare('UPDATE fs_inode SET atime = ? WHERE ino = ?');
         await updateStmt.run(now, ino);
-        return combined.toString('utf-8');
+        if (encoding) {
+            return combined.toString(encoding);
+        }
+        return combined;
     }
     async readdir(path) {
         await this.initialized;
@@ -316,9 +354,12 @@ class Filesystem {
         // Check if this was the last link to the inode
         const linkCount = await this.getLinkCount(ino);
         if (linkCount === 0) {
-            // Delete the inode and all associated data (CASCADE will handle data blocks)
-            const deleteStmt = this.db.prepare('DELETE FROM fs_inode WHERE ino = ?');
-            await deleteStmt.run(ino);
+            // Delete the inode
+            const deleteInodeStmt = this.db.prepare('DELETE FROM fs_inode WHERE ino = ?');
+            await deleteInodeStmt.run(ino);
+            // Delete all data chunks
+            const deleteDataStmt = this.db.prepare('DELETE FROM fs_data WHERE ino = ?');
+            await deleteDataStmt.run(ino);
         }
     }
     async stat(path) {

package/dist/index.d.ts

@@ -7,11 +7,17 @@ import { ToolCalls } from './toolcalls';
  */
 export interface AgentFSOptions {
     /**
-     * Optional unique identifier for the agent.
-     * - If provided: Creates persistent storage at `.agentfs/{id}.db`
-     * - If omitted: Uses ephemeral in-memory database
+     * Unique identifier for the agent.
+     * - If provided without `path`: Creates storage at `.agentfs/{id}.db`
+     * - If provided with `path`: Uses the specified path
      */
     id?: string;
+    /**
+     * Explicit path to the database file.
+     * - If provided: Uses the specified path directly
+     * - Can be combined with `id`
+     */
+    path?: string;
 }
 export declare class AgentFS {
     private db;
@@ -24,19 +30,21 @@ export declare class AgentFS {
     private constructor();
     /**
      * Open an agent filesystem
-     * @param options Configuration options (optional id for persistent storage)
+     * @param options Configuration options (id and/or path required)
      * @returns Fully initialized AgentFS instance
      * @example
      * ```typescript
-     * // Persistent storage
+     * // Using id (creates .agentfs/my-agent.db)
      * const agent = await AgentFS.open({ id: 'my-agent' });
-     * // Creates: .agentfs/my-agent.db
      *
-     * // Ephemeral in-memory database
-     * const agent = await AgentFS.open();
+     * // Using id with custom path
+     * const agent = await AgentFS.open({ id: 'my-agent', path: './data/mydb.db' });
+     *
+     * // Using path only
+     * const agent = await AgentFS.open({ path: './data/mydb.db' });
      * ```
      */
-    static open(options?: AgentFSOptions): Promise<AgentFS>;
+    static open(options: AgentFSOptions): Promise<AgentFS>;
     /**
      * Get the underlying Database instance
      */

package/dist/index.js

@@ -18,38 +18,37 @@ class AgentFS {
     }
     /**
      * Open an agent filesystem
-     * @param options Configuration options (optional id for persistent storage)
+     * @param options Configuration options (id and/or path required)
      * @returns Fully initialized AgentFS instance
      * @example
      * ```typescript
-     * // Persistent storage
+     * // Using id (creates .agentfs/my-agent.db)
      * const agent = await AgentFS.open({ id: 'my-agent' });
-     * // Creates: .agentfs/my-agent.db
      *
-     * // Ephemeral in-memory database
-     * const agent = await AgentFS.open();
+     * // Using id with custom path
+     * const agent = await AgentFS.open({ id: 'my-agent', path: './data/mydb.db' });
+     *
+     * // Using path only
+     * const agent = await AgentFS.open({ path: './data/mydb.db' });
      * ```
      */
     static async open(options) {
-        // Error handling for old API usage
-        if (typeof options === 'string') {
-            throw new Error(`AgentFS.open() no longer accepts string paths. ` +
-                `Please use: AgentFS.open({ id: 'your-id' }) for persistent storage, ` +
-                `or AgentFS.open() for ephemeral in-memory database.`);
+        const { id, path } = options;
+        // Require at least id or path
+        if (!id && !path) {
+            throw new Error("AgentFS.open() requires at least 'id' or 'path'.");
+        }
+        // Validate agent ID if provided
+        if (id && !/^[a-zA-Z0-9_-]+$/.test(id)) {
+            throw new Error('Agent ID must contain only alphanumeric characters, hyphens, and underscores');
         }
-        const { id } = options || {};
-        // Determine database path based on id
+        // Determine database path: explicit path takes precedence, otherwise use id-based path
         let dbPath;
-        if (!id) {
-            // No id = ephemeral in-memory database
-            dbPath = ':memory:';
+        if (path) {
+            dbPath = path;
         }
         else {
-            // Validate agent ID to prevent path traversal attacks
-            if (!/^[a-zA-Z0-9_-]+$/.test(id)) {
-                throw new Error('Agent ID must contain only alphanumeric characters, hyphens, and underscores');
-            }
-            // Ensure .agentfs directory exists
+            // id is guaranteed to be defined here (we checked !id && !path above)
             const dir = '.agentfs';
             if (!(0, fs_1.existsSync)(dir)) {
                 (0, fs_1.mkdirSync)(dir, { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfs-sdk",
-  "version": "0.2.0-pre.1",
+  "version": "0.2.0-pre.3",
   "description": "AgentFS SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",