[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_266":267,"_268":269},"routes/_app.x.$handle.$name",{"_105":104,"_33":51,"_113":95,"_28":114,"_13":14,"_115":-5,"_11":116,"_117":118,"_119":120,"_121":122,"_123":124,"_21":-5,"_125":-5,"_126":-5,"_127":55,"_128":129,"_130":26,"_131":-5,"_132":-5,"_133":134},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_49":50,"_33":51,"_38":52,"_53":-5,"_54":55,"_56":57,"_58":57,"_59":60,"_61":-5,"_18":62,"_63":-5,"_64":55,"_65":-5,"_66":-5,"_67":68,"_69":70,"_71":72,"_73":74,"_75":76,"_77":-5,"_78":79,"_80":79,"_81":82,"_83":82,"_84":82,"_85":79,"_86":79,"_87":88,"_89":90,"_91":92,"_93":55},"version",39,"changes",[19,20],"aiChatInfo","userId",{"_21":43,"_23":44,"_25":26,"_27":26,"_28":45,"_30":45},{"_21":22,"_23":24,"_25":26,"_27":26,"_28":29,"_30":29},"file",{"_31":32,"_33":34,"_35":21,"_36":37,"_38":39,"_40":14,"_41":42,"_25":26},"previous",{"_31":32,"_33":34,"_35":21,"_36":37},"deleted",true,"deletedHere","path","docs/spec.md","latestPath","fileId","0e73bc02-2ff2-11f1-bb6d-42dde27851f2","name","spec.md","fileType","content","# Agent Filesystem Specification\n\n**Version:** 0.4\n\n## Introduction\n\nThe Agent Filesystem Specification defines a SQLite schema for representing\nagent filesystem state. The specification consists of three main components:\n\n1. **Tool Call Audit Trail**: Captures tool invocations, parameters, and results\n for debugging, auditing, and performance analysis\n2. **Virtual Filesystem**: Stores agent artifacts (files, documents, outputs)\n using a Unix-like inode design with support for hard links, proper metadata,\n and efficient file operations\n3. **Key-Value Store**: Provides simple get/set operations for agent context,\n preferences, and structured state that doesn't fit into the filesystem model\n\nAll timestamps in this specification use Unix epoch format (seconds since\n1970-01-01 00:00:00 UTC) with optional nanosecond precision via separate `_nsec`\ncolumns.\n\n## Tool Calls\n\nThe tool call tracking schema captures tool invocations for debugging, auditing,\nand analysis.\n\n### Schema\n\n#### Table: `tool_calls`\n\nStores individual tool invocations with parameters and results. This is an\ninsert-only audit log.\n\n```sql\nCREATE TABLE tool_calls (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n name TEXT NOT NULL,\n parameters TEXT,\n result TEXT,\n error TEXT,\n started_at INTEGER NOT NULL,\n completed_at INTEGER NOT NULL,\n duration_ms INTEGER NOT NULL\n)\n\nCREATE INDEX idx_tool_calls_name ON tool_calls(name)\nCREATE INDEX idx_tool_calls_started_at ON tool_calls(started_at)\n```\n\n**Fields:**\n\n- `id` - Unique tool call identifier\n- `name` - Tool name (e.g., 'read_file', 'web_search', 'execute_code')\n- `parameters` - JSON-serialized input parameters (NULL if no parameters)\n- `result` - JSON-serialized result (NULL if error)\n- `error` - Error message (NULL if success)\n- `started_at` - Invocation timestamp (Unix timestamp, seconds)\n- `completed_at` - Completion timestamp (Unix timestamp, seconds)\n- `duration_ms` - Execution duration in milliseconds\n\n### Operations\n\n#### Record Tool Call\n\n```sql\nINSERT INTO tool_calls (name, parameters, result, error, started_at, completed_at, duration_ms)\nVALUES (?, ?, ?, ?, ?, ?, ?)\n```\n\n**Note:** Insert once when the tool call completes. Either `result` or `error`\nshould be set, not both.\n\n#### Query Tool Calls by Name\n\n```sql\nSELECT * FROM tool_calls\nWHERE name = ?\nORDER BY started_at DESC\n```\n\n#### Query Recent Tool Calls\n\n```sql\nSELECT * FROM tool_calls\nWHERE started_at > ?\nORDER BY started_at DESC\n```\n\n#### Analyze Tool Performance\n\n```sql\nSELECT\n name,\n COUNT(*) as total_calls,\n SUM(CASE WHEN error IS NULL THEN 1 ELSE 0 END) as successful,\n SUM(CASE WHEN error IS NOT NULL THEN 1 ELSE 0 END) as failed,\n AVG(duration_ms) as avg_duration_ms\nFROM tool_calls\nGROUP BY name\nORDER BY total_calls DESC\n```\n\n### Consistency Rules\n\n1. Exactly one of `result` or `error` SHOULD be non-NULL (mutual exclusion)\n2. `completed_at` MUST always be set (no NULL values)\n3. `duration_ms` MUST always be set and equal to\n `(completed_at - started_at) * 1000`\n4. Parameters and results MUST be valid JSON strings when present\n5. Records MUST NOT be updated or deleted (insert-only audit log)\n\n### Implementation Notes\n\n- This is an insert-only audit log - no updates or deletes\n- Insert the record once when the tool call completes\n- Set either `result` (on success) or `error` (on failure), but not both\n- `parameters`, `result`, and `error` are stored as JSON-serialized strings\n- `duration_ms` should be computed as `(completed_at - started_at) * 1000`\n- Use indexes for efficient queries by name or time\n- Consider periodic archival of old tool call records to a separate table\n\n### Extension Points\n\nImplementations MAY extend the tool call schema with additional functionality:\n\n- Session/conversation grouping (add `session_id` field)\n- User attribution (add `user_id` field)\n- Cost tracking (add `cost` field for API calls)\n- Parent/child relationships for nested tool calls\n- Token usage tracking\n- Input/output size metrics\n\nSuch extensions SHOULD use separate tables to maintain referential integrity.\n\n## Virtual Filesystem\n\nThe virtual filesystem provides POSIX-like file operations for agent artifacts.\nThe filesystem separates namespace (paths and names) from data (file content and\nmetadata) using a Unix-like inode design. This enables hard links (multiple\npaths to the same file), efficient file operations, proper file metadata\n(permissions, timestamps), and chunked content storage.\n\n### Schema\n\n#### Table: `fs_config`\n\nStores filesystem-level configuration. This table is initialized once when the\nfilesystem is created and MUST NOT be modified afterward.\n\n```sql\nCREATE TABLE fs_config (\n key TEXT PRIMARY KEY,\n value TEXT NOT NULL\n)\n```\n\n**Fields:**\n\n- `key` - Configuration key\n- `value` - Configuration value (stored as text)\n\n**Required Configuration:**\n\n| Key | Description | Default |\n| ------------ | ---------------------------- | ------- |\n| `chunk_size` | Size of data chunks in bytes | `4096` |\n\n**Notes:**\n\n- `chunk_size` determines the fixed size of data chunks in `fs_data`\n- All chunks except the last chunk of a file are exactly `chunk_size` bytes\n- Configuration is immutable after filesystem initialization\n- Implementations MAY define additional configuration keys\n\n#### Table: `fs_inode`\n\nStores file and directory metadata.\n\n```sql\nCREATE TABLE fs_inode (\n ino INTEGER PRIMARY KEY AUTOINCREMENT,\n mode INTEGER NOT NULL,\n nlink INTEGER NOT NULL DEFAULT 0,\n uid INTEGER NOT NULL DEFAULT 0,\n gid INTEGER NOT NULL DEFAULT 0,\n size INTEGER NOT NULL DEFAULT 0,\n atime INTEGER NOT NULL,\n mtime INTEGER NOT NULL,\n ctime INTEGER NOT NULL,\n rdev INTEGER NOT NULL DEFAULT 0,\n atime_nsec INTEGER NOT NULL DEFAULT 0,\n mtime_nsec INTEGER NOT NULL DEFAULT 0,\n ctime_nsec INTEGER NOT NULL DEFAULT 0\n)\n```\n\n**Fields:**\n\n- `ino` - Inode number (unique identifier)\n- `mode` - File type and permissions (Unix mode bits)\n- `nlink` - Number of hard links pointing to this inode\n- `uid` - Owner user ID\n- `gid` - Owner group ID\n- `size` - Total file size in bytes\n- `atime` - Last access time (Unix timestamp, seconds)\n- `mtime` - Last modification time (Unix timestamp, seconds)\n- `ctime` - Creation/change time (Unix timestamp, seconds)\n- `rdev` - Device number for character and block devices (major/minor encoded)\n- `atime_nsec` - Nanosecond component of last access time (0–999999999)\n- `mtime_nsec` - Nanosecond component of last modification time (0–999999999)\n- `ctime_nsec` - Nanosecond component of creation/change time (0–999999999)\n\n**Mode Encoding:**\n\nThe `mode` field combines file type and permissions:\n\n```\nFile type (upper bits):\n 0o170000 - File type mask (S_IFMT)\n 0o100000 - Regular file (S_IFREG)\n 0o040000 - Directory (S_IFDIR)\n 0o120000 - Symbolic link (S_IFLNK)\n 0o010000 - FIFO/named pipe (S_IFIFO)\n 0o020000 - Character device (S_IFCHR)\n 0o060000 - Block device (S_IFBLK)\n 0o140000 - Socket (S_IFSOCK)\n\nPermissions (lower 12 bits):\n 0o000777 - Permission bits (rwxrwxrwx)\n\nExample:\n 0o100644 - Regular file, rw-r--r--\n 0o040755 - Directory, rwxr-xr-x\n```\n\n**Special Inodes:**\n\n- Inode 1 MUST be the root directory\n\n#### Table: `fs_dentry`\n\nMaps names to inodes (directory entries).\n\n```sql\nCREATE TABLE fs_dentry (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n name TEXT NOT NULL,\n parent_ino INTEGER NOT NULL,\n ino INTEGER NOT NULL,\n UNIQUE(parent_ino, name)\n)\n\nCREATE INDEX idx_fs_dentry_parent ON fs_dentry(parent_ino, name)\n```\n\n**Fields:**\n\n- `id` - Internal entry ID\n- `name` - Basename (filename or directory name)\n- `parent_ino` - Parent directory inode number\n- `ino` - Inode this entry points to\n\n**Constraints:**\n\n- `UNIQUE(parent_ino, name)` - No duplicate names in a directory\n\n**Notes:**\n\n- Root directory (ino=1) has no dentry (no parent)\n- Multiple dentries MAY point to the same inode (hard links)\n- Link count is stored in `fs_inode.nlink` and must be incremented/decremented\n when dentries are added/removed\n\n#### Table: `fs_data`\n\nStores file content in fixed-size chunks. Chunk size is configured at filesystem\nlevel via `fs_config`.\n\n```sql\nCREATE TABLE fs_data (\n ino INTEGER NOT NULL,\n chunk_index INTEGER NOT NULL,\n data BLOB NOT NULL,\n PRIMARY KEY (ino, chunk_index)\n)\n```\n\n**Fields:**\n\n- `ino` - Inode number\n- `chunk_index` - Zero-based chunk index (chunk 0 contains bytes 0 to\n chunk_size-1)\n- `data` - Binary content (BLOB), exactly `chunk_size` bytes except for the last\n chunk\n\n**Notes:**\n\n- Directories MUST NOT have data chunks\n- Chunk size is determined by the `chunk_size` value in `fs_config`\n- All chunks except the last chunk of a file MUST be exactly `chunk_size` bytes\n- The last chunk MAY be smaller than `chunk_size`\n- Byte offset for a chunk = `chunk_index * chunk_size`\n- To read at byte offset `N`: `chunk_index = N / chunk_size`,\n `offset_in_chunk = N % chunk_size`\n\n#### Table: `fs_symlink`\n\nStores symbolic link targets.\n\n```sql\nCREATE TABLE fs_symlink (\n ino INTEGER PRIMARY KEY,\n target TEXT NOT NULL\n)\n```\n\n**Fields:**\n\n- `ino` - Inode number of the symlink\n- `target` - Target path (may be absolute or relative)\n\n### Operations\n\n#### Path Resolution\n\nTo resolve a path to an inode:\n\n1. Start at root inode (ino=1)\n2. Split path by `/` and filter empty components\n3. For each component:\n ```sql\n SELECT ino FROM fs_dentry WHERE parent_ino = ? AND name = ?\n ```\n4. Return final inode or NULL if any component not found\n\n#### Creating a File\n\n1. Resolve parent directory path to inode\n2. Get chunk size from config:\n ```sql\n SELECT value FROM fs_config WHERE key = 'chunk_size'\n ```\n3. Insert inode:\n ```sql\n INSERT INTO fs_inode (mode, uid, gid, size, atime, mtime, ctime)\n VALUES (?, ?, ?, 0, ?, ?, ?)\n RETURNING ino\n ```\n4. Insert directory entry:\n ```sql\n INSERT INTO fs_dentry (name, parent_ino, ino)\n VALUES (?, ?, ?)\n ```\n5. Increment link count:\n ```sql\n UPDATE fs_inode SET nlink = nlink + 1 WHERE ino = ?\n ```\n6. Split data into chunks and insert each:\n ```sql\n INSERT INTO fs_data (ino, chunk_index, data)\n VALUES (?, ?, ?)\n ```\n Where `chunk_index` starts at 0 and increments for each chunk.\n7. Update inode size:\n ```sql\n UPDATE fs_inode SET size = ?, mtime = ? WHERE ino = ?\n ```\n\n#### Reading a File\n\n1. Resolve path to inode\n2. Fetch all chunks in order:\n ```sql\n SELECT data FROM fs_data WHERE ino = ? ORDER BY chunk_index ASC\n ```\n3. Concatenate chunks in order\n4. Update access time:\n ```sql\n UPDATE fs_inode SET atime = ? WHERE ino = ?\n ```\n\n#### Reading a File at Offset\n\nTo read `length` bytes starting at byte offset `offset`:\n\n1. Resolve path to inode\n2. Get chunk size from config:\n ```sql\n SELECT value FROM fs_config WHERE key = 'chunk_size'\n ```\n3. Calculate chunk range:\n - `start_chunk = offset / chunk_size`\n - `end_chunk = (offset + length - 1) / chunk_size`\n4. Fetch required chunks:\n ```sql\n SELECT chunk_index, data FROM fs_data\n WHERE ino = ? AND chunk_index >= ? AND chunk_index <= ?\n ORDER BY chunk_index ASC\n ```\n5. Extract the requested byte range from the chunks:\n - `offset_in_first_chunk = offset % chunk_size`\n - Skip first `offset_in_first_chunk` bytes of first chunk\n - Take `length` total bytes across chunks\n\n#### Listing a Directory\n\n1. Resolve directory path to inode\n2. Query entries:\n ```sql\n SELECT name FROM fs_dentry WHERE parent_ino = ? ORDER BY name ASC\n ```\n\n#### Deleting a File\n\n1. Resolve path to get inode and parent\n2. Delete directory entry:\n ```sql\n DELETE FROM fs_dentry WHERE parent_ino = ? AND name = ?\n ```\n3. Decrement link count:\n ```sql\n UPDATE fs_inode SET nlink = nlink - 1 WHERE ino = ?\n ```\n4. Check if last link:\n ```sql\n SELECT nlink FROM fs_inode WHERE ino = ?\n ```\n5. If nlink = 0, delete inode and data:\n ```sql\n DELETE FROM fs_inode WHERE ino = ?\n DELETE FROM fs_data WHERE ino = ?\n ```\n\n#### Creating a Hard Link\n\n1. Resolve source path to get inode\n2. Resolve destination parent to get parent_ino\n3. Insert new directory entry:\n ```sql\n INSERT INTO fs_dentry (name, parent_ino, ino)\n VALUES (?, ?, ?)\n ```\n4. Increment link count:\n ```sql\n UPDATE fs_inode SET nlink = nlink + 1 WHERE ino = ?\n ```\n\n#### Reading File Metadata (stat)\n\n1. Resolve path to inode\n2. Query inode (includes link count):\n ```sql\n SELECT ino, mode, nlink, uid, gid, size, atime, mtime, ctime, rdev,\n atime_nsec, mtime_nsec, ctime_nsec\n FROM fs_inode WHERE ino = ?\n ```\n\n### Initialization\n\nWhen creating a new agent database, initialize the filesystem configuration and\nroot directory:\n\n```sql\n-- Initialize filesystem configuration\nINSERT INTO fs_config (key, value) VALUES ('chunk_size', '4096');\n\n-- Initialize root directory\nINSERT INTO fs_inode (ino, mode, nlink, uid, gid, size, atime, mtime, ctime)\nVALUES (1, 16877, 1, 0, 0, 0, unixepoch(), unixepoch(), unixepoch());\n```\n\nWhere `16877` = `0o040755` (directory with rwxr-xr-x permissions)\n\n**Note:** The `chunk_size` value can be customized at filesystem creation time\nbut MUST NOT be changed afterward. The root directory has `nlink=1` as it has no\nparent directory entry.\n\n### Consistency Rules\n\n1. Root inode (ino=1) MUST always exist\n2. Every dentry MUST reference a valid inode\n3. Every dentry MUST reference a valid parent inode\n4. No directory MAY contain duplicate names\n5. Directories MUST have mode with S_IFDIR bit set\n6. Regular files MUST have mode with S_IFREG bit set\n7. File size MUST match total size of all data chunks\n8. Every inode MUST have at least one dentry (except root)\n\n### Implementation Notes\n\n- Use `RETURNING` clause to safely get auto-generated inode numbers\n- Parent directories are created implicitly as needed\n- Empty files have an inode but no data chunks\n- Symlink resolution is implementation-defined (not part of schema)\n- Use transactions for multi-step operations to maintain consistency\n\n### Extension Points\n\nImplementations MAY extend the filesystem schema with additional functionality:\n\n- Extended attributes table\n- File ACLs and advanced permissions\n- Quota tracking per user/group\n- Version history and snapshots\n- Content deduplication\n- Compression metadata\n- File checksums/hashes\n\nSuch extensions SHOULD use separate tables to maintain referential integrity.\n\n## Overlay Filesystem\n\nThe overlay filesystem provides copy-on-write semantics by layering a writable\ndelta filesystem on top of a read-only base filesystem. Changes are written to\nthe delta layer while the base layer remains unmodified. This enables sandboxed\nexecution where modifications can be discarded or committed independently.\n\n### Whiteouts\n\nWhen a file is deleted from an overlay filesystem, the deletion must be recorded\nso that lookups do not fall through to the base layer. This is accomplished\nusing \"whiteouts\" - markers that indicate a path has been explicitly deleted.\n\n#### Table: `fs_whiteout`\n\nTracks deleted paths in the overlay to prevent base layer visibility.\n\n```sql\nCREATE TABLE fs_whiteout (\n path TEXT PRIMARY KEY,\n parent_path TEXT NOT NULL,\n created_at INTEGER NOT NULL\n)\n\nCREATE INDEX idx_fs_whiteout_parent ON fs_whiteout(parent_path)\n```\n\n**Fields:**\n\n- `path` - Normalized absolute path that has been deleted\n- `parent_path` - Parent directory path (for efficient child lookups)\n- `created_at` - Deletion timestamp (Unix timestamp, seconds)\n\n**Notes:**\n\n- The `parent_path` column enables O(1) lookups of whiteouts within a directory,\n avoiding expensive `LIKE` pattern matching\n- For the root directory `/`, `parent_path` is `/`\n- For other paths, `parent_path` is the path with the final component removed\n (e.g., `/foo/bar` has parent `/foo`)\n\n### Operations\n\n#### Create Whiteout\n\nWhen deleting a file that exists in the base layer:\n\n```sql\nINSERT INTO fs_whiteout (path, parent_path, created_at)\nVALUES (?, ?, ?)\nON CONFLICT(path) DO UPDATE SET created_at = excluded.created_at\n```\n\n#### Check for Whiteout\n\nBefore falling through to the base layer during lookup:\n\n```sql\nSELECT 1 FROM fs_whiteout WHERE path = ?\n```\n\n#### Remove Whiteout\n\nWhen creating a file at a previously deleted path:\n\n```sql\nDELETE FROM fs_whiteout WHERE path = ?\n```\n\n#### List Child Whiteouts\n\nWhen listing a directory, get whiteouts to exclude from base layer results:\n\n```sql\nSELECT path FROM fs_whiteout WHERE parent_path = ?\n```\n\n### Overlay Lookup Semantics\n\n1. Check if path exists in delta layer → return delta entry\n2. Check if path has a whiteout → return \"not found\"\n3. Check if path exists in base layer → return base entry\n4. Return \"not found\"\n\n### Inode Origin Tracking\n\nWhen a file is copied from the base layer to the delta layer during a copy-up\noperation (e.g., when creating a hard link to a base file), the original base\ninode number must be preserved. This is necessary because the kernel caches\ninode numbers, and returning a different inode after copy-up causes ENOENT\nerrors or cache inconsistencies.\n\nThis mechanism is similar to Linux overlayfs's `trusted.overlay.origin` extended\nattribute, which stores a file handle to the lower inode.\n\n#### Table: `fs_origin`\n\nMaps delta layer inodes to their original base layer inodes.\n\n```sql\nCREATE TABLE fs_origin (\n delta_ino INTEGER PRIMARY KEY,\n base_ino INTEGER NOT NULL\n)\n```\n\n**Fields:**\n\n- `delta_ino` - Inode number in the delta layer\n- `base_ino` - Original inode number from the base layer\n\n#### Operations\n\n##### Store Origin Mapping\n\nWhen copying a file from base to delta during copy-up:\n\n```sql\nINSERT OR REPLACE INTO fs_origin (delta_ino, base_ino)\nVALUES (?, ?)\n```\n\n##### Get Origin Inode\n\nWhen stat'ing a file that exists in delta, check if it has an origin:\n\n```sql\nSELECT base_ino FROM fs_origin WHERE delta_ino = ?\n```\n\nIf a mapping exists, return `base_ino` instead of `delta_ino` in stat results.\n\n### Consistency Rules\n\n1. A whiteout MUST be removed when a new file is created at that path\n2. A whiteout MUST be created when deleting a file that exists in the base layer\n3. The `parent_path` MUST be correctly derived from `path`\n4. Whiteouts only affect overlay lookups, not the underlying base filesystem\n5. When copying a file from base to delta, the origin mapping MUST be stored\n6. When stat'ing a delta file with an origin mapping, the base inode MUST be\n returned\n\n## Key-Value Data\n\nThe key-value store provides simple get/set operations for agent context and\nstate.\n\n### Schema\n\n#### Table: `kv_store`\n\nStores arbitrary key-value pairs with automatic timestamping.\n\n```sql\nCREATE TABLE kv_store (\n key TEXT PRIMARY KEY,\n value TEXT NOT NULL,\n created_at INTEGER DEFAULT (unixepoch()),\n updated_at INTEGER DEFAULT (unixepoch())\n)\n\nCREATE INDEX idx_kv_store_created_at ON kv_store(created_at)\n```\n\n**Fields:**\n\n- `key` - Unique key identifier\n- `value` - JSON-serialized value\n- `created_at` - Creation timestamp (Unix timestamp, seconds)\n- `updated_at` - Last update timestamp (Unix timestamp, seconds)\n\n### Operations\n\n#### Set a Value\n\n```sql\nINSERT INTO kv_store (key, value, updated_at)\nVALUES (?, ?, unixepoch())\nON CONFLICT(key) DO UPDATE SET\n value = excluded.value,\n updated_at = unixepoch()\n```\n\n#### Get a Value\n\n```sql\nSELECT value FROM kv_store WHERE key = ?\n```\n\n#### Delete a Value\n\n```sql\nDELETE FROM kv_store WHERE key = ?\n```\n\n#### List All Keys\n\n```sql\nSELECT key, created_at, updated_at FROM kv_store ORDER BY key ASC\n```\n\n### Consistency Rules\n\n1. Keys MUST be unique (enforced by PRIMARY KEY)\n2. Values MUST be valid JSON strings\n3. Timestamps MUST use Unix epoch format (seconds)\n\n### Implementation Notes\n\n- Values are stored as JSON strings; serialize before storing, deserialize after\n retrieving\n- Use `ON CONFLICT` clause for upsert operations\n- Indexes on `created_at` support temporal queries\n- Updates automatically refresh the `updated_at` timestamp\n- Keys can use any naming convention (e.g., namespaced: `user:preferences`,\n `session:state`)\n\n### Extension Points\n\nImplementations MAY extend the key-value store schema with additional\nfunctionality:\n\n- Namespaced keys with hierarchy support\n- Value versioning/history\n- TTL (time-to-live) for automatic expiration\n- Value size limits and quotas\n\nSuch extensions SHOULD use separate tables to maintain referential integrity.\n\n## Revision History\n\n### Version 0.4\n\n- Added nanosecond timestamp precision for `atime`, `mtime`, and `ctime`\n- Added `atime_nsec`, `mtime_nsec`, `ctime_nsec` columns to `fs_inode` table\n (DEFAULT 0 for backward compatibility)\n- Nanosecond precision enables correct NFS `wcc_data` cache invalidation when\n multiple operations occur within the same second\n- Added POSIX special file support (FIFOs, character devices, block devices,\n sockets)\n- Added `rdev` column to `fs_inode` table for device major/minor numbers\n- Added `S_IFIFO`, `S_IFCHR`, `S_IFBLK`, `S_IFSOCK` file type constants to Mode\n Encoding\n- Updated stat query to include `rdev` field\n\n### Version 0.3\n\n- Added `fs_origin` table to Overlay Filesystem for tracking copy-up origin\n inodes\n- Origin tracking ensures consistent inode numbers after copy-up (similar to\n Linux overlayfs `trusted.overlay.origin`)\n\n### Version 0.2\n\n- Added Overlay Filesystem section with `fs_whiteout` table for copy-on-write\n semantics\n- Whiteout table includes `parent_path` column with index for efficient O(1)\n child lookups\n- Added `nlink` column to `fs_inode` table to store link count directly\n- Link count is now maintained in the inode rather than computed via COUNT(*) on\n `fs_dentry`\n\n### Version 0.1\n\n- Added `fs_config` table for filesystem-level configuration\n- Changed `fs_data` table to use fixed-size chunks with `chunk_index` instead of\n variable-size chunks with `offset` and `size`\n- Added `chunk_size` configuration option (default: 4096 bytes)\n- Added \"Reading a File at Offset\" operation for efficient partial reads\n- Chunk-based storage enables efficient random access reads without loading\n entire files\n\n### Version 0.0\n\n- Initial specification\n- Tool call audit trail (`tool_calls` table)\n- Virtual filesystem (`fs_inode`, `fs_dentry`, `fs_data`, `fs_symlink` tables)\n- Key-value store (`kv_store` table)","createdAt",["D",1775322440068],"branchVersion","branchId","0efb5874-2fed-11f1-ad2f-42dde27851f2",{"_31":46,"_33":45,"_35":47,"_36":-5,"_38":48,"_40":14,"_41":42,"_25":26},{"_31":46,"_33":45,"_35":47,"_36":-5},"docs","06992c10-2ff2-11f1-832b-42dde27851f2","directory",["D",1775322440068],"id","0efaa3f2-2fed-11f1-ad2f-42dde27851f2","agentfs",["D",1775283063025],"deletedAt","legacyEnvVars",false,"privacy","public","httpPrivacy","description","A virtual filesystem for AI agents, backed by SQLite.","imageUrl","5d1042a9-7b0b-499d-8a72-3a8ac7a4e185","pinnedFileId","pinPreview","pinMigrated","screenshotVersion","likeCount",1,"orgId","5f80108f-7ca4-4327-b77b-089dbe4b5a82","tursoName","0efaa3f22fed11f1ad2f42dde27851f2","tursoHostname","0efaa3f22fed11f1ad2f42dde27851f2-val-town.aws-us-east-2.turso.io","tursoMeasuredAt",["D",1789470042795],"pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_105":104,"_112":108},"org",{"_105":104,"_106":-5,"_107":108,"_18":62,"_109":110,"_111":55},"branch",{"_13":94,"_33":95,"_49":42,"_96":50,"_97":-5,"_98":-5,"_99":-5,"_100":-5,"_101":-5,"_102":51,"_103":104},"isOwned",55,"main","projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","nbbaier","handle","displayName","avatar","https://secure.gravatar.com/avatar/0129a541b7b3574e92c4afd06c5e32da&d=identicon","tier","pro","canRestrictVals","profileImageUrl","branchName","","adoptOrgId",{"_49":50,"_33":51,"_38":261,"_53":-5,"_54":55,"_56":57,"_58":57,"_59":60,"_61":-5,"_18":62,"_63":-5,"_64":55,"_65":-5,"_66":-5,"_67":68,"_69":70,"_71":72,"_73":74,"_75":262,"_77":-5,"_78":79,"_80":79,"_81":82,"_83":82,"_84":82,"_85":79,"_86":79,"_87":263,"_89":264,"_91":265,"_93":55},"tree",[224,225,226,227,228,229,230,231,232],"files",[224,225,226,227,228,229,230,231,232],"counts",{"_214":151,"_215":68,"_216":151,"_217":218,"_219":220},"contents",[135,136,137,138,139,140,141,142,143],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},{"_49":207,"_33":208,"_31":209,"_147":-5,"_41":42,"_40":210,"_149":55,"_38":211,"_13":151,"_35":21,"_36":212,"_25":55,"_153":-5,"_28":213},{"_49":200,"_33":201,"_31":202,"_147":-5,"_41":42,"_40":203,"_149":26,"_38":204,"_13":68,"_35":21,"_36":205,"_25":55,"_153":-5,"_28":206},{"_49":193,"_33":194,"_31":195,"_147":-5,"_41":42,"_40":196,"_149":26,"_38":197,"_13":151,"_35":21,"_36":198,"_25":55,"_153":-5,"_28":199},{"_49":185,"_33":186,"_31":187,"_147":-5,"_41":42,"_40":188,"_149":55,"_38":189,"_13":148,"_35":190,"_36":191,"_25":55,"_153":-5,"_28":192},{"_49":178,"_33":179,"_31":180,"_147":-5,"_41":42,"_40":181,"_149":26,"_38":182,"_13":151,"_35":21,"_36":183,"_25":55,"_153":-5,"_28":184},{"_49":171,"_33":172,"_31":173,"_147":-5,"_41":42,"_40":174,"_149":26,"_38":175,"_13":151,"_35":21,"_36":176,"_25":55,"_153":-5,"_28":177},{"_49":162,"_33":163,"_31":164,"_147":-5,"_41":42,"_40":165,"_149":55,"_38":166,"_13":167,"_35":168,"_36":169,"_25":55,"_153":-5,"_28":170},{"_49":155,"_33":156,"_31":157,"_147":-5,"_41":42,"_40":158,"_149":26,"_38":159,"_13":151,"_35":21,"_36":160,"_25":55,"_153":-5,"_28":161},{"_49":144,"_33":145,"_31":146,"_147":-5,"_41":42,"_40":148,"_149":26,"_38":150,"_13":151,"_35":21,"_36":152,"_25":55,"_153":-5,"_28":154},"19f9a47c-2fef-11f1-8163-42dde27851f2","types.ts","19f9a54e-2fef-11f1-8163-42dde27851f2","parentId",6,"latest",["D",1775283940460],0,"/**\n * AgentFS type definitions — mirrors the v0.4 spec.\n */\n\n// ─── Tool Calls ──────────────────────────────────────────────────────\n\nexport interface ToolCall {\n id: number;\n name: string;\n parameters: string | null;\n result: string | null;\n error: string | null;\n started_at: number;\n completed_at: number;\n duration_ms: number;\n}\n\nexport interface ToolPerformance {\n name: string;\n total_calls: number;\n successful: number;\n failed: number;\n avg_duration_ms: number;\n}\n\n// ─── Virtual Filesystem ──────────────────────────────────────────────\n\n/** Unix mode constants */\nexport const S_IFMT = 0o170000;\nexport const S_IFREG = 0o100000;\nexport const S_IFDIR = 0o040000;\nexport const S_IFLNK = 0o120000;\nexport const S_IFIFO = 0o010000;\nexport const S_IFCHR = 0o020000;\nexport const S_IFBLK = 0o060000;\nexport const S_IFSOCK = 0o140000;\n\n/** Default modes */\nexport const DEFAULT_FILE_MODE = 0o100644; // rw-r--r--\nexport const DEFAULT_DIR_MODE = 0o040755; // rwxr-xr-x\n\n/** Root inode number */\nexport const ROOT_INO = 1;\n\n/** Default chunk size in bytes */\nexport const DEFAULT_CHUNK_SIZE = 4096;\n\nexport interface Inode {\n ino: number;\n mode: number;\n nlink: number;\n uid: number;\n gid: number;\n size: number;\n atime: number;\n mtime: number;\n ctime: number;\n rdev: number;\n atime_nsec: number;\n mtime_nsec: number;\n ctime_nsec: number;\n}\n\nexport interface DirEntry {\n id: number;\n name: string;\n parent_ino: number;\n ino: number;\n}\n\nexport interface StatResult {\n ino: number;\n mode: number;\n nlink: number;\n uid: number;\n gid: number;\n size: number;\n atime: number;\n mtime: number;\n ctime: number;\n rdev: number;\n atime_nsec: number;\n mtime_nsec: number;\n ctime_nsec: number;\n}\n\n// ─── Key-Value Store ─────────────────────────────────────────────────\n\nexport interface KVEntry {\n key: string;\n value: string;\n created_at: number;\n updated_at: number;\n}\n\n// ─── Helpers ─────────────────────────────────────────────────────────\n\n/** Checks whether a mode value represents a directory */\nexport function isDir(mode: number): boolean {\n return (mode & S_IFMT) === S_IFDIR;\n}\n\n/** Checks whether a mode value represents a regular file */\nexport function isFile(mode: number): boolean {\n return (mode & S_IFMT) === S_IFREG;\n}\n\n/** Checks whether a mode value represents a symlink */\nexport function isSymlink(mode: number): boolean {\n return (mode & S_IFMT) === S_IFLNK;\n}\n","label",[145],"4b76572a-2fef-11f1-8c6e-42dde27851f2","tool-calls.ts","4b7657c0-2fef-11f1-8c6e-42dde27851f2",9,["D",1775284023483],"/**\n * AgentFS Tool Call Audit Log\n *\n * Insert-only audit trail for tool invocations.\n * Records are never updated or deleted.\n */\n\nimport { sqlite } from \"https://esm.town/v/std/sqlite/main.ts\";\nimport type { ToolCall, ToolPerformance } from \"./types.ts\";\n\n/**\n * Record a completed tool call.\n *\n * Provide either `result` (on success) or `error` (on failure), not both.\n * Timestamps are Unix epoch seconds; duration is computed automatically.\n */\nexport async function record(opts: {\n name: string;\n parameters?: unknown;\n result?: unknown;\n error?: string;\n started_at: number;\n completed_at: number;\n}): Promise {\n const duration_ms = Math.round((opts.completed_at - opts.started_at) * 1000);\n const res = await sqlite.execute({\n sql: `INSERT INTO tool_calls (name, parameters, result, error, started_at, completed_at, duration_ms)\n VALUES (?, ?, ?, ?, ?, ?, ?)`,\n args: [\n opts.name,\n opts.parameters != null ? JSON.stringify(opts.parameters) : null,\n opts.result != null ? JSON.stringify(opts.result) : null,\n opts.error ?? null,\n opts.started_at,\n opts.completed_at,\n duration_ms,\n ],\n });\n return Number(res.lastInsertRowid ?? 0);\n}\n\n/**\n * Convenience wrapper: execute a function and automatically record\n * the tool call with timing, result, and error capture.\n */\nexport async function trace(\n name: string,\n parameters: unknown,\n fn: () => Promise,\n): Promise {\n const started_at = Date.now() / 1000;\n try {\n const result = await fn();\n const completed_at = Date.now() / 1000;\n await record({ name, parameters, result, started_at, completed_at });\n return result;\n } catch (err) {\n const completed_at = Date.now() / 1000;\n const error = err instanceof Error ? err.message : String(err);\n await record({ name, parameters, error, started_at, completed_at });\n throw err;\n }\n}\n\n/** Get a single tool call by ID. */\nexport async function get(id: number): Promise {\n const res = await sqlite.execute({\n sql: `SELECT * FROM tool_calls WHERE id = ?`,\n args: [id],\n });\n return (res.rows[0] as unknown as ToolCall) ?? undefined;\n}\n\n/** Query tool calls by name, most recent first. */\nexport async function queryByName(\n name: string,\n limit = 100,\n): Promise {\n const res = await sqlite.execute({\n sql: `SELECT * FROM tool_calls WHERE name = ? ORDER BY started_at DESC LIMIT ?`,\n args: [name, limit],\n });\n return res.rows as unknown as ToolCall[];\n}\n\n/** Query tool calls after a given timestamp, most recent first. */\nexport async function queryRecent(\n since: number,\n limit = 100,\n): Promise {\n const res = await sqlite.execute({\n sql: `SELECT * FROM tool_calls WHERE started_at > ? ORDER BY started_at DESC LIMIT ?`,\n args: [since, limit],\n });\n return res.rows as unknown as ToolCall[];\n}\n\n/** Aggregate performance stats grouped by tool name. */\nexport async function analyzePerformance(): Promise {\n const res = await sqlite.execute({\n sql: `SELECT\n name,\n COUNT(*) as total_calls,\n SUM(CASE WHEN error IS NULL THEN 1 ELSE 0 END) as successful,\n SUM(CASE WHEN error IS NOT NULL THEN 1 ELSE 0 END) as failed,\n AVG(duration_ms) as avg_duration_ms\n FROM tool_calls\n GROUP BY name\n ORDER BY total_calls DESC`,\n args: [],\n });\n return res.rows as unknown as ToolPerformance[];\n}\n",[156],"4c90f74c-3048-11f1-92b2-42dde27851f2","test.ts","3aba72b2-2ff0-11f1-b843-42dde27851f2",38,["D",1775322250542],2,"script","/**\n * Quick smoke test — run as a script to verify AgentFS works.\n */\n\nimport { fs, init, isFile, kv, tools } from \"./mod.ts\";\n\n// Initialize\nawait init();\nconsole.log(\"init: OK\");\n\n// KV\nawait kv.set(\"test:x\", { a: 1 });\nconst val = await kv.get(\"test:x\");\nconsole.log(\"kv.set/get:\", JSON.stringify(val));\nawait kv.del(\"test:x\");\nconsole.log(\"kv.del: OK\");\n\n// Tool calls\nconst t = Date.now() / 1000;\nconst id = await tools.record({\n name: \"test_tool\",\n parameters: { q: \"hello\" },\n result: { ok: true },\n started_at: t,\n completed_at: t + 0.1,\n});\nconst tc = await tools.get(id);\nconsole.log(\"tools.record/get:\", tc?.name, tc?.duration_ms + \"ms\");\n\n// Filesystem\nawait fs.writeFile(\"/test.txt\", \"hello world\");\nconst content = await fs.readFile(\"/test.txt\", \"utf-8\");\nconsole.log(\"fs.writeFile/readFile:\", content);\n\nconst st = await fs.stat(\"/test.txt\");\nconsole.log(\"fs.stat: size=\" + st.size, \"isFile=\" + isFile(st.mode));\n\nawait fs.writeFile(\"/sub/dir/deep.txt\", \"nested\");\nconst dirs = await fs.readdir(\"/\");\nconsole.log(\"readdir /:\", dirs);\n\nconst subDirs = await fs.readdir(\"/sub\");\nconsole.log(\"readdir /sub:\", subDirs);\n\n// Cleanup\nawait fs.deleteFile(\"/test.txt\");\nawait fs.deleteFile(\"/sub/dir/deep.txt\");\nawait fs.rmdir(\"/sub/dir\");\nawait fs.rmdir(\"/sub\");\nconsole.log(\"cleanup: OK\");\n\nconsole.log(\"\\nAll tests passed.\");",[163],"256f77dc-2fef-11f1-acbc-42dde27851f2","schema.ts","256f78a4-2fef-11f1-acbc-42dde27851f2",7,["D",1775283959685],"/**\n * AgentFS schema definitions and initialization.\n *\n * All DDL is idempotent (CREATE TABLE IF NOT EXISTS / CREATE INDEX IF NOT EXISTS)\n * so init() can be called safely on every startup.\n */\n\nimport { sqlite } from \"https://esm.town/v/std/sqlite/main.ts\";\nimport { DEFAULT_CHUNK_SIZE, DEFAULT_DIR_MODE, ROOT_INO } from \"./types.ts\";\n\n// ─── DDL Statements ──────────────────────────────────────────────────\n\nconst TOOL_CALLS_DDL = `\nCREATE TABLE IF NOT EXISTS tool_calls (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n name TEXT NOT NULL,\n parameters TEXT,\n result TEXT,\n error TEXT,\n started_at INTEGER NOT NULL,\n completed_at INTEGER NOT NULL,\n duration_ms INTEGER NOT NULL\n)`;\n\nconst TOOL_CALLS_INDEXES = [\n `CREATE INDEX IF NOT EXISTS idx_tool_calls_name ON tool_calls(name)`,\n `CREATE INDEX IF NOT EXISTS idx_tool_calls_started_at ON tool_calls(started_at)`,\n];\n\nconst FS_CONFIG_DDL = `\nCREATE TABLE IF NOT EXISTS fs_config (\n key TEXT PRIMARY KEY,\n value TEXT NOT NULL\n)`;\n\nconst FS_INODE_DDL = `\nCREATE TABLE IF NOT EXISTS fs_inode (\n ino INTEGER PRIMARY KEY AUTOINCREMENT,\n mode INTEGER NOT NULL,\n nlink INTEGER NOT NULL DEFAULT 0,\n uid INTEGER NOT NULL DEFAULT 0,\n gid INTEGER NOT NULL DEFAULT 0,\n size INTEGER NOT NULL DEFAULT 0,\n atime INTEGER NOT NULL,\n mtime INTEGER NOT NULL,\n ctime INTEGER NOT NULL,\n rdev INTEGER NOT NULL DEFAULT 0,\n atime_nsec INTEGER NOT NULL DEFAULT 0,\n mtime_nsec INTEGER NOT NULL DEFAULT 0,\n ctime_nsec INTEGER NOT NULL DEFAULT 0\n)`;\n\nconst FS_DENTRY_DDL = `\nCREATE TABLE IF NOT EXISTS fs_dentry (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n name TEXT NOT NULL,\n parent_ino INTEGER NOT NULL,\n ino INTEGER NOT NULL,\n UNIQUE(parent_ino, name)\n)`;\n\nconst FS_DENTRY_INDEXES = [\n `CREATE INDEX IF NOT EXISTS idx_fs_dentry_parent ON fs_dentry(parent_ino, name)`,\n];\n\nconst FS_DATA_DDL = `\nCREATE TABLE IF NOT EXISTS fs_data (\n ino INTEGER NOT NULL,\n chunk_index INTEGER NOT NULL,\n data BLOB NOT NULL,\n PRIMARY KEY (ino, chunk_index)\n)`;\n\nconst FS_SYMLINK_DDL = `\nCREATE TABLE IF NOT EXISTS fs_symlink (\n ino INTEGER PRIMARY KEY,\n target TEXT NOT NULL\n)`;\n\nconst KV_STORE_DDL = `\nCREATE TABLE IF NOT EXISTS kv_store (\n key TEXT PRIMARY KEY,\n value TEXT NOT NULL,\n created_at INTEGER DEFAULT (unixepoch()),\n updated_at INTEGER DEFAULT (unixepoch())\n)`;\n\nconst KV_STORE_INDEXES = [\n `CREATE INDEX IF NOT EXISTS idx_kv_store_created_at ON kv_store(created_at)`,\n];\n\n// ─── Initialization ──────────────────────────────────────────────────\n\n/**\n * Initialize all AgentFS tables and seed required data.\n *\n * Safe to call multiple times — uses IF NOT EXISTS throughout and\n * only inserts seed data when it's absent.\n */\nexport async function init(): Promise {\n // Create all tables\n await sqlite.batch([\n { sql: TOOL_CALLS_DDL, args: [] },\n ...TOOL_CALLS_INDEXES.map((sql) => ({ sql, args: [] as any[] })),\n { sql: FS_CONFIG_DDL, args: [] },\n { sql: FS_INODE_DDL, args: [] },\n { sql: FS_DENTRY_DDL, args: [] },\n ...FS_DENTRY_INDEXES.map((sql) => ({ sql, args: [] as any[] })),\n { sql: FS_DATA_DDL, args: [] },\n { sql: FS_SYMLINK_DDL, args: [] },\n { sql: KV_STORE_DDL, args: [] },\n ...KV_STORE_INDEXES.map((sql) => ({ sql, args: [] as any[] })),\n ]);\n\n // Seed fs_config (chunk_size) if not present\n await sqlite.execute({\n sql: `INSERT OR IGNORE INTO fs_config (key, value) VALUES ('chunk_size', ?)`,\n args: [String(DEFAULT_CHUNK_SIZE)],\n });\n\n // Seed root directory inode if not present\n const root = await sqlite.execute({\n sql: `SELECT ino FROM fs_inode WHERE ino = ?`,\n args: [ROOT_INO],\n });\n\n if (root.rows.length === 0) {\n const now = Math.floor(Date.now() / 1000);\n await sqlite.execute({\n sql: `INSERT INTO fs_inode (ino, mode, nlink, uid, gid, size, atime, mtime, ctime)\n VALUES (?, ?, 1, 0, 0, 0, ?, ?, ?)`,\n args: [ROOT_INO, DEFAULT_DIR_MODE, now, now, now],\n });\n }\n}\n",[172],"7ad46fac-2fef-11f1-a11c-42dde27851f2","mod.ts","7ad4706a-2fef-11f1-a11c-42dde27851f2",11,["D",1775284102955],"/**\n * AgentFS — A virtual filesystem for AI agents.\n *\n * Implements the Agent Filesystem Specification v0.4 using Val Town SQLite.\n * https://www.agentfs.ai/\n *\n * Usage:\n * import { init, kv, tools, fs } from \"https://esm.town/v/nbbaier/agentfs/mod.ts\";\n *\n * await init();\n * await kv.set(\"greeting\", \"hello\");\n * await fs.writeFile(\"/notes.md\", \"# My Notes\");\n */\n\nexport { init } from \"./schema.ts\";\n\n// Re-export modules as namespaces\nexport * as kv from \"./kv.ts\";\nexport * as tools from \"./tool-calls.ts\";\nexport * as fs from \"./fs.ts\";\n\n// Re-export types\nexport type {\n DirEntry,\n Inode,\n KVEntry,\n StatResult,\n ToolCall,\n ToolPerformance,\n} from \"./types.ts\";\n\nexport {\n DEFAULT_CHUNK_SIZE,\n DEFAULT_DIR_MODE,\n DEFAULT_FILE_MODE,\n isDir,\n isFile,\n isSymlink,\n ROOT_INO,\n S_IFBLK,\n S_IFCHR,\n S_IFDIR,\n S_IFIFO,\n S_IFLNK,\n S_IFMT,\n S_IFREG,\n S_IFSOCK,\n} from \"./types.ts\";\n",[179],"a9a6157e-2fef-11f1-b8d6-42dde27851f2","main.ts","0efdef3a-2fed-11f1-ad2f-42dde27851f2",13,["D",1775284181484],"http","/**\n * AgentFS test handler — exercises all modules against the scoped SQLite database.\n *\n * Hit the endpoint to run the test suite.\n */\n\nimport { init, kv, tools, fs } from \"./mod.ts\";\n\ntype TestResult = { name: string; ok: boolean; detail?: string };\n\nasync function runTest(\n name: string,\n fn: () => Promise,\n): Promise {\n try {\n const detail = (await fn()) ?? \"ok\";\n return { name, ok: true, detail };\n } catch (err) {\n const msg = err instanceof Error ? err.message : String(err);\n return { name, ok: false, detail: msg };\n }\n}\n\nexport default async function handler(_req: Request): Promise {\n const results: TestResult[] = [];\n\n // ── Schema init ──────────────────────────────────────────────────\n results.push(\n await runTest(\"init\", async () => {\n await init();\n }),\n );\n\n // ── KV store ─────────────────────────────────────────────────────\n results.push(\n await runTest(\"kv.set + kv.get (object)\", async () => {\n await kv.set(\"test:obj\", { hello: \"world\" });\n const val = await kv.get<{ hello: string }>(\"test:obj\");\n if (val?.hello !== \"world\") throw new Error(`Expected \"world\", got ${JSON.stringify(val)}`);\n return JSON.stringify(val);\n }),\n );\n\n results.push(\n await runTest(\"kv.set + kv.get (number)\", async () => {\n await kv.set(\"test:num\", 42);\n const val = await kv.get(\"test:num\");\n if (val !== 42) throw new Error(`Expected 42, got ${val}`);\n return String(val);\n }),\n );\n\n results.push(\n await runTest(\"kv.has\", async () => {\n const yes = await kv.has(\"test:num\");\n const no = await kv.has(\"test:nonexistent\");\n if (!yes) throw new Error(\"Expected true for existing key\");\n if (no) throw new Error(\"Expected false for missing key\");\n return `exists=${yes}, missing=${no}`;\n }),\n );\n\n results.push(\n await runTest(\"kv.list\", async () => {\n const entries = await kv.list(\"test:\");\n if (entries.length < 2) throw new Error(`Expected >= 2 entries, got ${entries.length}`);\n return `${entries.length} entries`;\n }),\n );\n\n results.push(\n await runTest(\"kv.del\", async () => {\n await kv.del(\"test:obj\");\n await kv.del(\"test:num\");\n const val = await kv.get(\"test:obj\");\n if (val !== undefined) throw new Error(\"Expected undefined after delete\");\n }),\n );\n\n // ── Tool calls ───────────────────────────────────────────────────\n results.push(\n await runTest(\"tools.record\", async () => {\n const now = Date.now() / 1000;\n const id = await tools.record({\n name: \"test_tool\",\n parameters: { query: \"hello\" },\n result: { answer: 42 },\n started_at: now,\n completed_at: now + 0.150,\n });\n if (!id || id <= 0) throw new Error(`Expected positive id, got ${id}`);\n return `id=${id}`;\n }),\n );\n\n results.push(\n await runTest(\"tools.trace\", async () => {\n const result = await tools.trace(\"traced_tool\", { input: \"x\" }, async () => {\n await new Promise((r) => setTimeout(r, 10));\n return \"done\";\n });\n if (result !== \"done\") throw new Error(`Expected \"done\", got ${result}`);\n }),\n );\n\n results.push(\n await runTest(\"tools.queryByName\", async () => {\n const calls = await tools.queryByName(\"test_tool\");\n if (calls.length === 0) throw new Error(\"Expected at least 1 call\");\n return `${calls.length} call(s)`;\n }),\n );\n\n results.push(\n await runTest(\"tools.analyzePerformance\", async () => {\n const perf = await tools.analyzePerformance();\n if (perf.length === 0) throw new Error(\"Expected performance data\");\n return perf.map((p) => `${p.name}: ${p.total_calls} calls`).join(\", \");\n }),\n );\n\n // ── Filesystem ───────────────────────────────────────────────────\n results.push(\n await runTest(\"fs.writeFile + fs.readFile (string)\", async () => {\n await fs.writeFile(\"/test.txt\", \"hello agentfs\");\n const content = await fs.readFile(\"/test.txt\", \"utf-8\");\n if (content !== \"hello agentfs\") {\n throw new Error(`Expected \"hello agentfs\", got \"${content}\"`);\n }\n return `\"${content}\"`;\n }),\n );\n\n results.push(\n await runTest(\"fs.writeFile (auto-mkdir)\", async () => {\n await fs.writeFile(\"/deep/nested/dir/file.md\", \"# Nested\");\n const content = await fs.readFile(\"/deep/nested/dir/file.md\", \"utf-8\");\n if (!content.startsWith(\"# Nested\")) throw new Error(\"Content mismatch\");\n return `\"${content}\"`;\n }),\n );\n\n results.push(\n await runTest(\"fs.writeFile (overwrite)\", async () => {\n await fs.writeFile(\"/test.txt\", \"version 1\");\n await fs.writeFile(\"/test.txt\", \"version 2\");\n const content = await fs.readFile(\"/test.txt\", \"utf-8\");\n if (content !== \"version 2\") throw new Error(`Expected \"version 2\", got \"${content}\"`);\n }),\n );\n\n results.push(\n await runTest(\"fs.exists\", async () => {\n const yes = await fs.exists(\"/test.txt\");\n const no = await fs.exists(\"/nonexistent.txt\");\n if (!yes) throw new Error(\"Expected true for existing file\");\n if (no) throw new Error(\"Expected false for missing file\");\n return `exists=${yes}, missing=${no}`;\n }),\n );\n\n results.push(\n await runTest(\"fs.stat\", async () => {\n const st = await fs.stat(\"/test.txt\");\n if (!st.ino || st.size <= 0) throw new Error(`Bad stat: ${JSON.stringify(st)}`);\n return `ino=${st.ino}, size=${st.size}, mode=${st.mode.toString(8)}`;\n }),\n );\n\n results.push(\n await runTest(\"fs.readdir\", async () => {\n const entries = await fs.readdir(\"/\");\n if (!entries.includes(\"test.txt\")) throw new Error(\"Missing test.txt in readdir\");\n return entries.join(\", \");\n }),\n );\n\n results.push(\n await runTest(\"fs.mkdir + fs.readdir\", async () => {\n if (!(await fs.exists(\"/mydir\"))) {\n await fs.mkdir(\"/mydir\");\n }\n await fs.writeFile(\"/mydir/a.txt\", \"aaa\");\n await fs.writeFile(\"/mydir/b.txt\", \"bbb\");\n const entries = await fs.readdir(\"/mydir\");\n if (entries.length < 2) throw new Error(`Expected >= 2 entries, got ${entries.length}`);\n return entries.join(\", \");\n }),\n );\n\n results.push(\n await runTest(\"fs.link (hard link)\", async () => {\n await fs.link(\"/test.txt\", \"/test-link.txt\");\n const content = await fs.readFile(\"/test-link.txt\", \"utf-8\");\n if (content !== \"version 2\") throw new Error(\"Hard link content mismatch\");\n const st = await fs.stat(\"/test.txt\");\n if (st.nlink < 2) throw new Error(`Expected nlink >= 2, got ${st.nlink}`);\n return `nlink=${st.nlink}`;\n }),\n );\n\n results.push(\n await runTest(\"fs.symlink + fs.readlink\", async () => {\n if (await fs.exists(\"/test-sym.txt\")) {\n await fs.deleteFile(\"/test-sym.txt\");\n }\n await fs.symlink(\"/test.txt\", \"/test-sym.txt\");\n const target = await fs.readlink(\"/test-sym.txt\");\n if (target !== \"/test.txt\") throw new Error(`Expected \"/test.txt\", got \"${target}\"`);\n return `target=\"${target}\"`;\n }),\n );\n\n results.push(\n await runTest(\"fs.rename\", async () => {\n await fs.writeFile(\"/rename-me.txt\", \"moving\");\n await fs.rename(\"/rename-me.txt\", \"/renamed.txt\");\n const gone = await fs.exists(\"/rename-me.txt\");\n const there = await fs.exists(\"/renamed.txt\");\n if (gone) throw new Error(\"Old path still exists\");\n if (!there) throw new Error(\"New path doesn't exist\");\n const content = await fs.readFile(\"/renamed.txt\", \"utf-8\");\n if (content !== \"moving\") throw new Error(\"Content lost during rename\");\n }),\n );\n\n results.push(\n await runTest(\"fs.readFileAt (partial read)\", async () => {\n await fs.writeFile(\"/partial.txt\", \"abcdefghijklmnop\");\n const chunk = await fs.readFileAt(\"/partial.txt\", 4, 4);\n const text = new TextDecoder().decode(chunk);\n if (text !== \"efgh\") throw new Error(`Expected \"efgh\", got \"${text}\"`);\n return `\"${text}\"`;\n }),\n );\n\n // ── Cleanup ──────────────────────────────────────────────────────\n results.push(\n await runTest(\"cleanup\", async () => {\n for (const p of [\"/test.txt\", \"/test-link.txt\", \"/test-sym.txt\", \"/renamed.txt\", \"/partial.txt\"]) {\n if (await fs.exists(p)) await fs.deleteFile(p);\n }\n for (const p of [\"/mydir/a.txt\", \"/mydir/b.txt\"]) {\n if (await fs.exists(p)) await fs.deleteFile(p);\n }\n if (await fs.exists(\"/mydir\")) await fs.rmdir(\"/mydir\");\n for (const p of [\"/deep/nested/dir/file.md\"]) {\n if (await fs.exists(p)) await fs.deleteFile(p);\n }\n // Clean nested dirs\n for (const d of [\"/deep/nested/dir\", \"/deep/nested\", \"/deep\"]) {\n if (await fs.exists(d)) await fs.rmdir(d);\n }\n }),\n );\n\n // ── Format output ────────────────────────────────────────────────\n const passed = results.filter((r) => r.ok).length;\n const failed = results.filter((r) => !r.ok).length;\n\n const lines = results.map((r) => {\n const icon = r.ok ? \"PASS\" : \"FAIL\";\n return `[${icon}] ${r.name}${r.detail ? ` — ${r.detail}` : \"\"}`;\n });\n\n lines.push(\"\");\n lines.push(`${passed} passed, ${failed} failed, ${results.length} total`);\n\n return new Response(lines.join(\"\\n\"), {\n status: failed > 0 ? 500 : 200,\n headers: { \"content-type\": \"text/plain; charset=utf-8\" },\n });\n}\n",[186],"2d9c2c3e-2fef-11f1-8aaf-42dde27851f2","kv.ts","2d9c2cfc-2fef-11f1-8aaf-42dde27851f2",8,["D",1775283973401],"/**\n * AgentFS Key-Value Store\n *\n * Simple get/set/delete/list for agent context and structured state.\n * Values are JSON-serialized on write and deserialized on read.\n */\n\nimport { sqlite } from \"https://esm.town/v/std/sqlite/main.ts\";\nimport type { KVEntry } from \"./types.ts\";\n\n/**\n * Set a key-value pair. Upserts — creates if new, updates if existing.\n * The value is JSON-serialized before storage.\n */\nexport async function set(key: string, value: unknown): Promise {\n const serialized = JSON.stringify(value);\n await sqlite.execute({\n sql: `INSERT INTO kv_store (key, value, updated_at)\n VALUES (?, ?, unixepoch())\n ON CONFLICT(key) DO UPDATE SET\n value = excluded.value,\n updated_at = unixepoch()`,\n args: [key, serialized],\n });\n}\n\n/**\n * Get a value by key. Returns the deserialized value, or undefined if not found.\n */\nexport async function get(key: string): Promise {\n const result = await sqlite.execute({\n sql: `SELECT value FROM kv_store WHERE key = ?`,\n args: [key],\n });\n if (result.rows.length === 0) return undefined;\n return JSON.parse(result.rows[0].value as string) as T;\n}\n\n/**\n * Delete a key-value pair. No-op if the key doesn't exist.\n */\nexport async function del(key: string): Promise {\n await sqlite.execute({\n sql: `DELETE FROM kv_store WHERE key = ?`,\n args: [key],\n });\n}\n\n/**\n * Check if a key exists.\n */\nexport async function has(key: string): Promise {\n const result = await sqlite.execute({\n sql: `SELECT 1 FROM kv_store WHERE key = ?`,\n args: [key],\n });\n return result.rows.length > 0;\n}\n\n/**\n * List all keys, optionally filtered by prefix.\n * Returns metadata (key, timestamps) without values for efficiency.\n */\nexport async function list(\n prefix?: string,\n): Promise> {\n if (prefix) {\n const result = await sqlite.execute({\n sql: `SELECT key, created_at, updated_at FROM kv_store\n WHERE key LIKE ? ORDER BY key ASC`,\n args: [prefix + \"%\"],\n });\n return result.rows as Array<{\n key: string;\n created_at: number;\n updated_at: number;\n }>;\n }\n\n const result = await sqlite.execute({\n sql: `SELECT key, created_at, updated_at FROM kv_store ORDER BY key ASC`,\n args: [],\n });\n return result.rows as Array<{\n key: string;\n created_at: number;\n updated_at: number;\n }>;\n}\n\n/**\n * Get the full KV entry including metadata.\n */\nexport async function getEntry(key: string): Promise {\n const result = await sqlite.execute({\n sql: `SELECT key, value, created_at, updated_at FROM kv_store WHERE key = ?`,\n args: [key],\n });\n if (result.rows.length === 0) return undefined;\n return result.rows[0] as unknown as KVEntry;\n}\n",[194],"ffb84396-2ff0-11f1-8cb7-42dde27851f2","fs.ts","74970d2a-2fef-11f1-b8d6-42dde27851f2",16,["D",1775284755396],"/**\n * AgentFS Virtual Filesystem\n *\n * POSIX-like file operations backed by Val Town SQLite.\n * Uses an inode-based design with chunked content storage.\n */\n\nimport { sqlite } from \"https://esm.town/v/std/sqlite/main.ts\";\nimport {\n DEFAULT_DIR_MODE,\n DEFAULT_FILE_MODE,\n isDir,\n ROOT_INO,\n S_IFDIR,\n S_IFLNK,\n S_IFMT,\n} from \"./types.ts\";\nimport type { Inode, StatResult } from \"./types.ts\";\n\n// ─── Internal helpers ────────────────────────────────────────────────\n\nfunction now(): number {\n return Math.floor(Date.now() / 1000);\n}\n\n/** Split a path into components, filtering empties. */\nfunction splitPath(path: string): string[] {\n return path.split(\"/\").filter((c) => c.length > 0);\n}\n\n/** Get parent path and basename from a full path. */\nfunction parsePath(path: string): { parent: string; name: string } {\n const components = splitPath(path);\n if (components.length === 0) {\n throw new Error(\"Cannot parse root path\");\n }\n const name = components.pop()!;\n const parent = \"/\" + components.join(\"/\");\n return { parent, name };\n}\n\n/** Retrieve the configured chunk size. */\nasync function getChunkSize(): Promise {\n const res = await sqlite.execute({\n sql: `SELECT value FROM fs_config WHERE key = 'chunk_size'`,\n args: [],\n });\n if (res.rows.length === 0) throw new Error(\"fs_config missing chunk_size\");\n return Number((res.rows[0] as any).value);\n}\n\n/**\n * Normalize blob data from SQLite into a Uint8Array.\n *\n * Val Town's scoped SQLite (Turso) returns BLOB columns as ArrayBuffer.\n * This helper handles that plus other potential representations.\n */\nfunction toBytes(d: unknown): Uint8Array {\n if (d instanceof Uint8Array) return d;\n if (d instanceof ArrayBuffer) return new Uint8Array(d);\n if (ArrayBuffer.isView(d)) return new Uint8Array(d.buffer, d.byteOffset, d.byteLength);\n if (typeof d === \"string\") return new TextEncoder().encode(d);\n return new Uint8Array(0);\n}\n\n/** Concatenate an array of Uint8Arrays into a single Uint8Array. */\nfunction concatBytes(chunks: Uint8Array[]): Uint8Array {\n const totalLen = chunks.reduce((sum, c) => sum + c.length, 0);\n const combined = new Uint8Array(totalLen);\n let offset = 0;\n for (const chunk of chunks) {\n combined.set(chunk, offset);\n offset += chunk.length;\n }\n return combined;\n}\n\n// ─── Path Resolution ─────────────────────────────────────────────────\n\n/**\n * Resolve an absolute path to its inode number.\n * Returns undefined if any component along the path doesn't exist.\n */\nexport async function resolve(path: string): Promise {\n const components = splitPath(path);\n if (components.length === 0) return ROOT_INO;\n\n let currentIno = ROOT_INO;\n for (const name of components) {\n const res = await sqlite.execute({\n sql: `SELECT ino FROM fs_dentry WHERE parent_ino = ? AND name = ?`,\n args: [currentIno, name],\n });\n if (res.rows.length === 0) return undefined;\n currentIno = (res.rows[0] as any).ino as number;\n }\n return currentIno;\n}\n\n/**\n * Resolve a path, throwing if it doesn't exist.\n */\nasync function resolveOrThrow(path: string): Promise {\n const ino = await resolve(path);\n if (ino === undefined) throw new Error(`ENOENT: ${path}`);\n return ino;\n}\n\n// ─── Stat ────────────────────────────────────────────────────────────\n\n/** Get file/directory metadata. */\nexport async function stat(path: string): Promise {\n const ino = await resolveOrThrow(path);\n const res = await sqlite.execute({\n sql: `SELECT ino, mode, nlink, uid, gid, size, atime, mtime, ctime, rdev,\n atime_nsec, mtime_nsec, ctime_nsec\n FROM fs_inode WHERE ino = ?`,\n args: [ino],\n });\n if (res.rows.length === 0) throw new Error(`Inode ${ino} not found`);\n return res.rows[0] as unknown as StatResult;\n}\n\n/** Check whether a path exists. */\nexport async function exists(path: string): Promise {\n return (await resolve(path)) !== undefined;\n}\n\n// ─── Directory Operations ────────────────────────────────────────────\n\n/**\n * Create a directory. Throws if it already exists or the parent doesn't exist.\n */\nexport async function mkdir(path: string): Promise {\n const { parent, name } = parsePath(path);\n const parentIno = await resolveOrThrow(parent);\n\n const ts = now();\n const res = await sqlite.execute({\n sql: `INSERT INTO fs_inode (mode, nlink, uid, gid, size, atime, mtime, ctime)\n VALUES (?, 0, 0, 0, 0, ?, ?, ?) RETURNING ino`,\n args: [DEFAULT_DIR_MODE, ts, ts, ts],\n });\n const ino = (res.rows[0] as any).ino as number;\n\n await sqlite.execute({\n sql: `INSERT INTO fs_dentry (name, parent_ino, ino) VALUES (?, ?, ?)`,\n args: [name, parentIno, ino],\n });\n\n await sqlite.execute({\n sql: `UPDATE fs_inode SET nlink = nlink + 1 WHERE ino = ?`,\n args: [ino],\n });\n\n return ino;\n}\n\n/**\n * Create a directory and all missing parents (like mkdir -p).\n */\nexport async function mkdirp(path: string): Promise {\n const components = splitPath(path);\n let currentIno = ROOT_INO;\n\n for (const name of components) {\n const res = await sqlite.execute({\n sql: `SELECT ino FROM fs_dentry WHERE parent_ino = ? AND name = ?`,\n args: [currentIno, name],\n });\n\n if (res.rows.length > 0) {\n currentIno = (res.rows[0] as any).ino as number;\n } else {\n const ts = now();\n const newInode = await sqlite.execute({\n sql: `INSERT INTO fs_inode (mode, nlink, uid, gid, size, atime, mtime, ctime)\n VALUES (?, 0, 0, 0, 0, ?, ?, ?) RETURNING ino`,\n args: [DEFAULT_DIR_MODE, ts, ts, ts],\n });\n const newIno = (newInode.rows[0] as any).ino as number;\n\n await sqlite.execute({\n sql: `INSERT INTO fs_dentry (name, parent_ino, ino) VALUES (?, ?, ?)`,\n args: [name, currentIno, newIno],\n });\n await sqlite.execute({\n sql: `UPDATE fs_inode SET nlink = nlink + 1 WHERE ino = ?`,\n args: [newIno],\n });\n\n currentIno = newIno;\n }\n }\n\n return currentIno;\n}\n\n/** List the names in a directory. */\nexport async function readdir(path: string): Promise {\n const ino = await resolveOrThrow(path);\n const res = await sqlite.execute({\n sql: `SELECT name FROM fs_dentry WHERE parent_ino = ? ORDER BY name ASC`,\n args: [ino],\n });\n return res.rows.map((r: any) => r.name as string);\n}\n\n/**\n * Remove an empty directory. Throws if not empty or not a directory.\n */\nexport async function rmdir(path: string): Promise {\n if (path === \"/\") throw new Error(\"Cannot remove root directory\");\n\n const { parent, name } = parsePath(path);\n const ino = await resolveOrThrow(path);\n\n // Check it's a directory\n const inodeRes = await sqlite.execute({\n sql: `SELECT mode FROM fs_inode WHERE ino = ?`,\n args: [ino],\n });\n if (inodeRes.rows.length === 0) throw new Error(`Inode ${ino} not found`);\n if (!isDir((inodeRes.rows[0] as any).mode as number)) {\n throw new Error(`ENOTDIR: ${path}`);\n }\n\n // Check it's empty\n const children = await sqlite.execute({\n sql: `SELECT 1 FROM fs_dentry WHERE parent_ino = ? LIMIT 1`,\n args: [ino],\n });\n if (children.rows.length > 0) throw new Error(`ENOTEMPTY: ${path}`);\n\n const parentIno = await resolveOrThrow(parent);\n\n await sqlite.execute({\n sql: `DELETE FROM fs_dentry WHERE parent_ino = ? AND name = ?`,\n args: [parentIno, name],\n });\n await sqlite.execute({\n sql: `UPDATE fs_inode SET nlink = nlink - 1 WHERE ino = ?`,\n args: [ino],\n });\n\n // If no more links, delete the inode\n const linkCheck = await sqlite.execute({\n sql: `SELECT nlink FROM fs_inode WHERE ino = ?`,\n args: [ino],\n });\n if (linkCheck.rows.length > 0 && (linkCheck.rows[0] as any).nlink <= 0) {\n await sqlite.execute({\n sql: `DELETE FROM fs_inode WHERE ino = ?`,\n args: [ino],\n });\n }\n}\n\n// ─── File Operations ─────────────────────────────────────────────────\n\n/**\n * Write a file at the given path. Creates parent directories as needed.\n * If the file already exists, its content is replaced.\n *\n * Accepts string or Uint8Array content.\n */\nexport async function writeFile(\n path: string,\n content: string | Uint8Array,\n): Promise {\n const { parent, name } = parsePath(path);\n const data =\n typeof content === \"string\" ? new TextEncoder().encode(content) : content;\n const chunkSize = await getChunkSize();\n\n // Ensure parent directories exist\n const parentIno = await mkdirp(parent);\n\n // Check if file already exists\n const existing = await sqlite.execute({\n sql: `SELECT ino FROM fs_dentry WHERE parent_ino = ? AND name = ?`,\n args: [parentIno, name],\n });\n\n let ino: number;\n\n if (existing.rows.length > 0) {\n // Overwrite: delete old chunks, rewrite\n ino = (existing.rows[0] as any).ino as number;\n await sqlite.execute({\n sql: `DELETE FROM fs_data WHERE ino = ?`,\n args: [ino],\n });\n } else {\n // Create new inode + dentry\n const ts = now();\n const res = await sqlite.execute({\n sql: `INSERT INTO fs_inode (mode, nlink, uid, gid, size, atime, mtime, ctime)\n VALUES (?, 0, 0, 0, 0, ?, ?, ?) RETURNING ino`,\n args: [DEFAULT_FILE_MODE, ts, ts, ts],\n });\n ino = (res.rows[0] as any).ino as number;\n\n await sqlite.execute({\n sql: `INSERT INTO fs_dentry (name, parent_ino, ino) VALUES (?, ?, ?)`,\n args: [name, parentIno, ino],\n });\n await sqlite.execute({\n sql: `UPDATE fs_inode SET nlink = nlink + 1 WHERE ino = ?`,\n args: [ino],\n });\n }\n\n // Write chunks\n const totalChunks = data.length === 0 ? 0 : Math.ceil(data.length / chunkSize);\n for (let i = 0; i < totalChunks; i++) {\n const start = i * chunkSize;\n const end = Math.min(start + chunkSize, data.length);\n const chunk = data.slice(start, end);\n\n await sqlite.execute({\n sql: `INSERT INTO fs_data (ino, chunk_index, data) VALUES (?, ?, ?)`,\n args: [ino, i, chunk],\n });\n }\n\n // Update size + mtime\n await sqlite.execute({\n sql: `UPDATE fs_inode SET size = ?, mtime = ? WHERE ino = ?`,\n args: [data.length, now(), ino],\n });\n\n return ino;\n}\n\n/**\n * Read an entire file. Returns a Uint8Array by default.\n * Pass encoding = \"utf-8\" to get a string.\n */\nexport async function readFile(\n path: string,\n encoding?: \"utf-8\",\n): Promise {\n const ino = await resolveOrThrow(path);\n\n const res = await sqlite.execute({\n sql: `SELECT data FROM fs_data WHERE ino = ? ORDER BY chunk_index ASC`,\n args: [ino],\n });\n\n // Update atime\n await sqlite.execute({\n sql: `UPDATE fs_inode SET atime = ? WHERE ino = ?`,\n args: [now(), ino],\n });\n\n if (res.rows.length === 0) {\n return encoding === \"utf-8\" ? \"\" : new Uint8Array(0);\n }\n\n const combined = concatBytes(res.rows.map((r: any) => toBytes(r.data)));\n\n if (encoding === \"utf-8\") {\n return new TextDecoder().decode(combined);\n }\n return combined;\n}\n\n/**\n * Read a portion of a file at a given byte offset.\n */\nexport async function readFileAt(\n path: string,\n offset: number,\n length: number,\n): Promise {\n const ino = await resolveOrThrow(path);\n const chunkSize = await getChunkSize();\n\n const startChunk = Math.floor(offset / chunkSize);\n const endChunk = Math.floor((offset + length - 1) / chunkSize);\n\n const res = await sqlite.execute({\n sql: `SELECT chunk_index, data FROM fs_data\n WHERE ino = ? AND chunk_index >= ? AND chunk_index <= ?\n ORDER BY chunk_index ASC`,\n args: [ino, startChunk, endChunk],\n });\n\n if (res.rows.length === 0) return new Uint8Array(0);\n\n const combined = concatBytes(res.rows.map((r: any) => toBytes(r.data)));\n\n // Extract the requested window\n const offsetInFirst = offset % chunkSize;\n return combined.slice(offsetInFirst, offsetInFirst + length);\n}\n\n/**\n * Delete (unlink) a file. If this is the last link, the inode and data are removed.\n */\nexport async function deleteFile(path: string): Promise {\n const { parent, name } = parsePath(path);\n const parentIno = await resolveOrThrow(parent);\n const ino = await resolveOrThrow(path);\n\n // Remove dentry\n await sqlite.execute({\n sql: `DELETE FROM fs_dentry WHERE parent_ino = ? AND name = ?`,\n args: [parentIno, name],\n });\n\n // Decrement nlink\n await sqlite.execute({\n sql: `UPDATE fs_inode SET nlink = nlink - 1 WHERE ino = ?`,\n args: [ino],\n });\n\n // If last link, clean up inode + data + symlink\n const linkCheck = await sqlite.execute({\n sql: `SELECT nlink FROM fs_inode WHERE ino = ?`,\n args: [ino],\n });\n\n if (linkCheck.rows.length > 0 && (linkCheck.rows[0] as any).nlink <= 0) {\n await sqlite.execute({ sql: `DELETE FROM fs_data WHERE ino = ?`, args: [ino] });\n await sqlite.execute({ sql: `DELETE FROM fs_symlink WHERE ino = ?`, args: [ino] });\n await sqlite.execute({ sql: `DELETE FROM fs_inode WHERE ino = ?`, args: [ino] });\n }\n}\n\n// ─── Links ───────────────────────────────────────────────────────────\n\n/**\n * Create a hard link: a new name pointing to an existing inode.\n */\nexport async function link(srcPath: string, destPath: string): Promise {\n const srcIno = await resolveOrThrow(srcPath);\n const { parent, name } = parsePath(destPath);\n const destParentIno = await resolveOrThrow(parent);\n\n await sqlite.execute({\n sql: `INSERT INTO fs_dentry (name, parent_ino, ino) VALUES (?, ?, ?)`,\n args: [name, destParentIno, srcIno],\n });\n await sqlite.execute({\n sql: `UPDATE fs_inode SET nlink = nlink + 1 WHERE ino = ?`,\n args: [srcIno],\n });\n}\n\n/**\n * Create a symbolic link at `linkPath` pointing to `target`.\n */\nexport async function symlink(target: string, linkPath: string): Promise {\n const { parent, name } = parsePath(linkPath);\n const parentIno = await resolveOrThrow(parent);\n\n const ts = now();\n // Mode: symlink + 0777\n const mode = S_IFLNK | 0o777;\n const res = await sqlite.execute({\n sql: `INSERT INTO fs_inode (mode, nlink, uid, gid, size, atime, mtime, ctime)\n VALUES (?, 0, 0, 0, ?, ?, ?, ?) RETURNING ino`,\n args: [mode, target.length, ts, ts, ts],\n });\n const ino = (res.rows[0] as any).ino as number;\n\n await sqlite.execute({\n sql: `INSERT INTO fs_dentry (name, parent_ino, ino) VALUES (?, ?, ?)`,\n args: [name, parentIno, ino],\n });\n await sqlite.execute({\n sql: `UPDATE fs_inode SET nlink = nlink + 1 WHERE ino = ?`,\n args: [ino],\n });\n await sqlite.execute({\n sql: `INSERT INTO fs_symlink (ino, target) VALUES (?, ?)`,\n args: [ino, target],\n });\n\n return ino;\n}\n\n/**\n * Read the target of a symbolic link.\n */\nexport async function readlink(path: string): Promise {\n const ino = await resolveOrThrow(path);\n const res = await sqlite.execute({\n sql: `SELECT target FROM fs_symlink WHERE ino = ?`,\n args: [ino],\n });\n if (res.rows.length === 0) throw new Error(`Not a symlink: ${path}`);\n return (res.rows[0] as any).target as string;\n}\n\n// ─── Rename / Move ───────────────────────────────────────────────────\n\n/**\n * Rename or move a file/directory from oldPath to newPath.\n */\nexport async function rename(oldPath: string, newPath: string): Promise {\n const { parent: oldParent, name: oldName } = parsePath(oldPath);\n const { parent: newParent, name: newName } = parsePath(newPath);\n\n const oldParentIno = await resolveOrThrow(oldParent);\n const ino = await resolveOrThrow(oldPath);\n\n // Ensure new parent exists\n const newParentIno = await mkdirp(newParent);\n\n // Remove old dentry\n await sqlite.execute({\n sql: `DELETE FROM fs_dentry WHERE parent_ino = ? AND name = ?`,\n args: [oldParentIno, oldName],\n });\n\n // Check if destination exists and remove it\n const destExisting = await sqlite.execute({\n sql: `SELECT ino FROM fs_dentry WHERE parent_ino = ? AND name = ?`,\n args: [newParentIno, newName],\n });\n if (destExisting.rows.length > 0) {\n const destIno = (destExisting.rows[0] as any).ino as number;\n await sqlite.execute({\n sql: `DELETE FROM fs_dentry WHERE parent_ino = ? AND name = ?`,\n args: [newParentIno, newName],\n });\n await sqlite.execute({\n sql: `UPDATE fs_inode SET nlink = nlink - 1 WHERE ino = ?`,\n args: [destIno],\n });\n }\n\n // Insert new dentry\n await sqlite.execute({\n sql: `INSERT INTO fs_dentry (name, parent_ino, ino) VALUES (?, ?, ?)`,\n args: [newName, newParentIno, ino],\n });\n\n // Update ctime\n await sqlite.execute({\n sql: `UPDATE fs_inode SET ctime = ? WHERE ino = ?`,\n args: [now(), ino],\n });\n}\n",[201],"d0442114-2ff2-11f1-ad77-42dde27851f2","README.md","d04421c8-2ff2-11f1-ad77-42dde27851f2",24,["D",1775285534784],"# AgentFS\n\nA virtual filesystem for AI agents, backed by SQLite. Implements the [Agent Filesystem Specification v0.4](https://www.agentfs.ai/) on Val Town.\n\nAgentFS gives agents persistent, structured storage through three primitives:\n\n- **Virtual Filesystem** — POSIX-like file operations (read, write, mkdir, link, symlink, rename) using a Unix inode design with chunked content storage\n- **Key-Value Store** — Simple typed get/set for agent context, preferences, and structured state\n- **Tool Call Audit Log** — Insert-only trail of tool invocations with timing, parameters, results, and performance analytics\n\n## Quick Start\n\n```ts\nimport { init, fs, kv, tools } from \"https://esm.town/v/nbbaier/agentfs/mod.ts\";\n\n// Initialize tables (idempotent — safe to call on every run)\nawait init();\n\n// Write and read files\nawait fs.writeFile(\"/notes/today.md\", \"# Meeting Notes\\n- Ship v2\");\nconst content = await fs.readFile(\"/notes/today.md\", \"utf-8\");\n\n// Key-value store (auto JSON serialization)\nawait kv.set(\"agent:config\", { model: \"gpt-4\", temperature: 0.7 });\nconst config = await kv.get<{ model: string }>(\"agent:config\");\n\n// Tool call tracking\nconst result = await tools.trace(\"web_search\", { query: \"Val Town\" }, async () => {\n // ... your tool implementation\n return { results: [\"...\"] };\n});\n```\n\n## Architecture\n\n```mermaid\ngraph TD\n A[mod.ts] --> B[schema.ts]\n A --> C[fs.ts]\n A --> D[kv.ts]\n A --> E[tool-calls.ts]\n A --> F[types.ts]\n C --> F\n D --> F\n E --> F\n B --> F\n B --> G[(SQLite)]\n C --> G\n D --> G\n E --> G\n```\n\nAll modules import from Val Town's scoped SQLite (`std/sqlite/main.ts`) so each val gets its own isolated database.\n\n## API Reference\n\n### `init()`\n\nCreates all tables and seeds the root directory. Uses `CREATE TABLE IF NOT EXISTS` — safe to call on every startup.\n\n```ts\nawait init();\n```\n\n### Filesystem (`fs`)\n\n| Function | Description |\n|----------|-------------|\n| `writeFile(path, content)` | Write a string or `Uint8Array`. Auto-creates parent dirs. Overwrites if exists. |\n| `readFile(path, encoding?)` | Read a file. Pass `\"utf-8\"` for string, omit for `Uint8Array`. |\n| `readFileAt(path, offset, length)` | Partial read at a byte offset. |\n| `exists(path)` | Check if a path exists. |\n| `stat(path)` | Get inode metadata (size, mode, timestamps, nlink). |\n| `mkdir(path)` | Create a directory. |\n| `mkdirp(path)` | Create a directory and all missing parents. |\n| `readdir(path)` | List names in a directory. |\n| `rmdir(path)` | Remove an empty directory. |\n| `deleteFile(path)` | Unlink a file. Cleans up inode/data when last link is removed. |\n| `link(src, dest)` | Create a hard link. |\n| `symlink(target, linkPath)` | Create a symbolic link. |\n| `readlink(path)` | Read a symlink's target. |\n| `rename(oldPath, newPath)` | Move/rename a file or directory. |\n| `resolve(path)` | Resolve a path to its inode number (or `undefined`). |\n\n### Key-Value Store (`kv`)\n\nValues are automatically JSON-serialized on write and deserialized on read.\n\n| Function | Description |\n|----------|-------------|\n| `set(key, value)` | Upsert a key-value pair. |\n| `get(key)` | Get a value (or `undefined`). |\n| `del(key)` | Delete a key. |\n| `has(key)` | Check if a key exists. |\n| `list(prefix?)` | List keys with optional prefix filter. Returns metadata without values. |\n| `getEntry(key)` | Get the full entry including `created_at` and `updated_at` timestamps. |\n\n### Tool Call Audit Log (`tools`)\n\nAn insert-only audit trail — records are never updated or deleted.\n\n| Function | Description |\n|----------|-------------|\n| `record(opts)` | Record a completed tool call with name, parameters, result/error, and timestamps. |\n| `trace(name, params, fn)` | Execute a function and auto-record timing, result, and errors. |\n| `get(id)` | Get a tool call by ID. |\n| `queryByName(name, limit?)` | Query calls by tool name, most recent first. |\n| `queryRecent(since, limit?)` | Query calls after a Unix timestamp. |\n| `analyzePerformance()` | Aggregate stats (call count, success/fail, avg duration) by tool name. |\n\n### Types & Constants\n\n```ts\nimport {\n // Types\n type Inode, type StatResult, type DirEntry,\n type KVEntry, type ToolCall, type ToolPerformance,\n\n // Mode helpers\n isFile, isDir, isSymlink,\n\n // Constants\n ROOT_INO, // 1\n DEFAULT_CHUNK_SIZE, // 4096\n DEFAULT_FILE_MODE, // 0o100644\n DEFAULT_DIR_MODE, // 0o040755\n S_IFREG, S_IFDIR, S_IFLNK, S_IFIFO, S_IFCHR, S_IFBLK, S_IFSOCK, S_IFMT,\n} from \"https://esm.town/v/nbbaier/agentfs/mod.ts\";\n```\n\n## Files\n\n| File | Purpose |\n|------|---------|\n| `mod.ts` | Public entry point — re-exports all modules |\n| `schema.ts` | DDL definitions and `init()` |\n| `fs.ts` | Virtual filesystem operations |\n| `kv.ts` | Key-value store operations |\n| `tool-calls.ts` | Tool call audit log operations |\n| `types.ts` | Type definitions and constants |\n| `main.ts` | HTTP test handler — hit the endpoint to run the test suite |\n| `test.ts` | Quick smoke test script |\n| `docs/spec.md` | Full Agent Filesystem Specification v0.4 |\n",[208],"pulls","branches","forks","envVars",{"_221":151,"_223":151},"connections",{"_221":151,"_222":151},"count","unfilledCount","emptyCount",{"_49":207,"_33":208,"_31":209,"_147":-5,"_41":42,"_40":210,"_149":55,"_38":258,"_13":151,"_35":21,"_36":212,"_25":55,"_153":-5,"_234":259,"_28":260},{"_49":200,"_33":201,"_31":202,"_147":-5,"_41":42,"_40":203,"_149":26,"_38":255,"_13":68,"_35":21,"_36":205,"_25":55,"_153":-5,"_234":256,"_28":257},{"_49":193,"_33":194,"_31":195,"_147":-5,"_41":42,"_40":196,"_149":26,"_38":252,"_13":151,"_35":21,"_36":198,"_25":55,"_153":-5,"_234":253,"_28":254},{"_49":185,"_33":186,"_31":187,"_147":-5,"_41":42,"_40":188,"_149":55,"_38":249,"_13":148,"_35":190,"_36":191,"_25":55,"_153":-5,"_234":250,"_28":251},{"_49":178,"_33":179,"_31":180,"_147":-5,"_41":42,"_40":181,"_149":26,"_38":246,"_13":151,"_35":21,"_36":183,"_25":55,"_153":-5,"_234":247,"_28":248},{"_49":171,"_33":172,"_31":173,"_147":-5,"_41":42,"_40":174,"_149":26,"_38":243,"_13":151,"_35":21,"_36":176,"_25":55,"_153":-5,"_234":244,"_28":245},{"_49":162,"_33":163,"_31":164,"_147":-5,"_41":42,"_40":165,"_149":55,"_38":240,"_13":167,"_35":168,"_36":169,"_25":55,"_153":-5,"_234":241,"_28":242},{"_49":155,"_33":156,"_31":157,"_147":-5,"_41":42,"_40":158,"_149":26,"_38":237,"_13":151,"_35":21,"_36":160,"_25":55,"_153":-5,"_234":238,"_28":239},{"_49":144,"_33":145,"_31":146,"_147":-5,"_41":42,"_40":148,"_149":26,"_38":233,"_13":151,"_35":21,"_36":152,"_25":55,"_153":-5,"_234":235,"_28":236},["D",1775283940460],"children",[],[145],["D",1775284023483],[],[156],["D",1775322250542],[],[163],["D",1775283959685],[],[172],["D",1775284102955],[],[179],["D",1775284181484],[],[186],["D",1775283973401],[],[194],["D",1775284755396],[],[201],["D",1775285534784],[],[208],["D",1775283063025],["D",1789470042795],{"_105":104,"_112":108},{"_105":104,"_106":-5,"_107":108,"_18":62,"_109":110,"_111":55},{"_13":94,"_33":95,"_49":42,"_96":50,"_97":-5,"_98":-5,"_99":-5,"_100":-5,"_101":-5,"_102":51,"_103":104},"ctx",{"_87":-5,"_132":299,"_300":301,"_302":303,"_304":55,"_305":55,"_306":55,"_307":26,"_308":-5,"_309":-7,"_310":-7,"_311":151,"_312":55,"_313":55,"_314":-5,"_315":55,"_316":55,"_317":55,"_318":-5},"ENV",{"_270":271,"_272":273,"_274":95,"_275":276,"_277":278,"_279":280,"_281":282,"_283":284,"_285":286,"_287":288,"_289":290,"_291":292,"_293":294,"_295":296,"_297":298},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

Diff · v39