@intella/sdk 0.0.1

package/src/filesystem/agentfs-provider.ts

@@ -0,0 +1,328 @@
+// Note: agentfs-sdk needs to be installed separately
+// npm install agentfs-sdk
+import { AgentFS } from 'agentfs-sdk';
+import type {
+  FilesystemConfig,
+  FileStats,
+  DirectoryEntry,
+  ToolCallMetadata,
+} from '../types.js';
+import { BaseFilesystemProvider } from './base-provider.js';
+
+/**
+ * AgentFS filesystem provider
+ * Uses Turso's AgentFS SDK for SQLite-based agent filesystem
+ */
+export class AgentFSProvider extends BaseFilesystemProvider {
+  private agentFS: any = null; // AgentFS instance (typed as any due to SDK)
+
+  constructor() {
+    super('agentfs');
+  }
+
+  /**
+   * Initialize AgentFS filesystem
+   */
+  async initialize(config?: FilesystemConfig): Promise<void> {
+    this.config = { ...this.config, ...config };
+
+    try {
+      // Initialize AgentFS based on configuration
+      if (this.config.dbPath) {
+        // Use explicit database path
+        this.agentFS = await AgentFS.open({ path: this.config.dbPath });
+      } else if (this.config.agentId) {
+        // Use agent ID (creates .agentfs/{agentId}.db)
+        this.agentFS = await AgentFS.open({ id: this.config.agentId });
+      } else {
+        throw new Error('No agent ID or database path provided');
+      }
+
+      this.initialized = true;
+    } catch (error) {
+      throw new Error(`Failed to initialize AgentFS: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Close AgentFS filesystem
+   */
+  async close(): Promise<void> {
+    if (this.agentFS) {
+      // AgentFS doesn't expose a close method in the SDK,
+      // but we can clear the reference
+      this.agentFS = null;
+      this.initialized = false;
+    }
+  }
+
+  // Filesystem operations
+  async readFile(path: string): Promise<Buffer | string> {
+    this.ensureInitialized();
+    const normalizedPath = this.normalizePath(path);
+    try {
+      const content = await this.agentFS.fs.readFile(normalizedPath);
+      // AgentFS may return string or Buffer, return as-is
+      return content;
+    } catch (error) {
+      throw new Error(`Failed to read file ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  async writeFile(path: string, data: Buffer | string): Promise<void> {
+    this.ensureInitialized();
+    const normalizedPath = this.normalizePath(path);
+    try {
+      await this.agentFS.fs.writeFile(normalizedPath, data);
+    } catch (error) {
+      throw new Error(`Failed to write file ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  async appendFile(path: string, data: Buffer | string): Promise<void> {
+    this.ensureInitialized();
+    const normalizedPath = this.normalizePath(path);
+    try {
+      // Read existing content
+      let existingContent = '';
+      try {
+        const existing = await this.agentFS.fs.readFile(normalizedPath);
+        existingContent = existing instanceof Buffer ? existing.toString() : existing;
+      } catch {
+        // File doesn't exist, start with empty string
+      }
+
+      // Write combined content
+      const newContent = existingContent + (data instanceof Buffer ? data.toString() : data);
+      await this.agentFS.fs.writeFile(normalizedPath, newContent);
+    } catch (error) {
+      throw new Error(`Failed to append to file ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  async exists(path: string): Promise<boolean> {
+    this.ensureInitialized();
+    const normalizedPath = this.normalizePath(path);
+    try {
+      await this.agentFS.fs.stat(normalizedPath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async stat(path: string): Promise<FileStats> {
+    this.ensureInitialized();
+    const normalizedPath = this.normalizePath(path);
+    try {
+      const stats = await this.agentFS.fs.stat(normalizedPath);
+      return {
+        size: stats.size || 0,
+        isDirectory: stats.isDirectory || false,
+        isFile: stats.isFile || false,
+        createdAt: stats.createdAt,
+        modifiedAt: stats.modifiedAt,
+      };
+    } catch (error) {
+      throw new Error(`Failed to stat ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  async readdir(path: string): Promise<DirectoryEntry[]> {
+    this.ensureInitialized();
+    const normalizedPath = this.normalizePath(path);
+    try {
+      const entries = await this.agentFS.fs.readdir(normalizedPath);
+      const result: DirectoryEntry[] = [];
+
+      for (const entry of entries) {
+        const entryPath = normalizedPath === '' ? entry : `${normalizedPath}/${entry}`;
+        const stats = await this.stat(entryPath);
+        result.push({
+          name: entry,
+          path: entryPath,
+          stats,
+        });
+      }
+
+      return result;
+    } catch (error) {
+      throw new Error(`Failed to read directory ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  async mkdir(path: string, recursive = false): Promise<void> {
+    this.ensureInitialized();
+    const normalizedPath = this.normalizePath(path);
+    try {
+      // AgentFS may support recursive mkdir through the SDK
+      // If not, we'll create parent directories manually if recursive is true
+      if (recursive) {
+        const parts = normalizedPath.split('/');
+        let currentPath = '';
+        for (const part of parts) {
+          currentPath = currentPath ? `${currentPath}/${part}` : part;
+          try {
+            await this.agentFS.fs.mkdir(currentPath);
+          } catch (err: any) {
+            // Ignore if directory already exists
+            if (!err?.message?.includes('exists')) {
+              throw err;
+            }
+          }
+        }
+      } else {
+        await this.agentFS.fs.mkdir(normalizedPath);
+      }
+    } catch (error) {
+      throw new Error(`Failed to create directory ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  async unlink(path: string, recursive = false): Promise<void> {
+    this.ensureInitialized();
+    const normalizedPath = this.normalizePath(path);
+    try {
+      const stats = await this.stat(normalizedPath);
+      if (stats.isDirectory) {
+        if (recursive) {
+          const entries = await this.readdir(normalizedPath);
+          for (const entry of entries) {
+            await this.unlink(entry.path, true);
+          }
+        }
+        await this.agentFS.fs.rmdir(normalizedPath);
+      } else {
+        await this.agentFS.fs.unlink(normalizedPath);
+      }
+    } catch (error) {
+      throw new Error(`Failed to delete ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  async copy(src: string, dest: string): Promise<void> {
+    this.ensureInitialized();
+    const normalizedSrc = this.normalizePath(src);
+    const normalizedDest = this.normalizePath(dest);
+    try {
+      const content = await this.readFile(normalizedSrc);
+      await this.writeFile(normalizedDest, content);
+    } catch (error) {
+      throw new Error(`Failed to copy ${src} to ${dest}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  async move(src: string, dest: string): Promise<void> {
+    this.ensureInitialized();
+    const normalizedSrc = this.normalizePath(src);
+    const normalizedDest = this.normalizePath(dest);
+    try {
+      await this.copy(normalizedSrc, normalizedDest);
+      await this.unlink(normalizedSrc);
+    } catch (error) {
+      throw new Error(`Failed to move ${src} to ${dest}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  // Key-value operations
+  async get(key: string): Promise<unknown> {
+    this.ensureInitialized();
+    try {
+      return await this.agentFS.kv.get(key);
+    } catch (error) {
+      throw new Error(`Failed to get key ${key}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  async set(key: string, value: unknown): Promise<void> {
+    this.ensureInitialized();
+    try {
+      await this.agentFS.kv.set(key, value);
+    } catch (error) {
+      throw new Error(`Failed to set key ${key}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    this.ensureInitialized();
+    try {
+      await this.agentFS.kv.delete(key);
+    } catch (error) {
+      throw new Error(`Failed to delete key ${key}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  async listKeys(prefix?: string): Promise<string[]> {
+    this.ensureInitialized();
+    try {
+      // AgentFS may have a list method or we need to query directly
+      // For now, we'll use a method that might exist or throw a not implemented error
+      if (this.agentFS.kv.list) {
+        return await this.agentFS.kv.list(prefix);
+      }
+      // If list method doesn't exist, we'll need to implement it differently
+      // This might require direct SQLite access which isn't exposed by the SDK
+      throw new Error('listKeys is not directly supported by AgentFS SDK. Consider using SQL queries directly.');
+    } catch (error) {
+      throw new Error(`Failed to list keys: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  async hasKey(key: string): Promise<boolean> {
+    this.ensureInitialized();
+    try {
+      const value = await this.get(key);
+      return value !== null && value !== undefined;
+    } catch {
+      return false;
+    }
+  }
+
+  // Tool call tracking
+  async recordToolCall(metadata: ToolCallMetadata): Promise<void> {
+    this.ensureInitialized();
+    try {
+      await this.agentFS.tools.record(
+        metadata.tool,
+        metadata.startedAt,
+        metadata.endedAt,
+        metadata.input || {},
+        metadata.output || {}
+      );
+    } catch (error) {
+      throw new Error(`Failed to record tool call: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  async getToolCallHistory(filter?: {
+    tool?: string;
+    status?: ToolCallMetadata['status'];
+    since?: number;
+    until?: number;
+    limit?: number;
+  }): Promise<ToolCallMetadata[]> {
+    this.ensureInitialized();
+    try {
+      // AgentFS tools API might have a query method
+      // If not, we'll need to query the SQLite database directly
+      if (this.agentFS.tools.query) {
+        const results = await this.agentFS.tools.query(filter);
+        return results.map((r: any) => ({
+          tool: r.tool,
+          startedAt: r.startedAt,
+          endedAt: r.endedAt,
+          input: r.input,
+          output: r.output,
+          status: r.status,
+          error: r.error,
+        }));
+      }
+      // If query method doesn't exist, return empty array for now
+      // In a real implementation, you might want to access the database directly
+      throw new Error('getToolCallHistory is not directly supported by AgentFS SDK. Consider using SQL queries directly.');
+    } catch (error) {
+      throw new Error(`Failed to get tool call history: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+}
+

package/src/filesystem/base-provider.ts

@@ -0,0 +1,98 @@
+import type {
+  FilesystemProviderType,
+  FilesystemConfig,
+  FileStats,
+  DirectoryEntry,
+  ToolCallMetadata,
+  IFilesystemProvider,
+} from '../types.js';
+
+/**
+ * Base filesystem provider
+ * Abstract implementation that provides common functionality
+ */
+export abstract class BaseFilesystemProvider implements IFilesystemProvider {
+  protected initialized = false;
+  protected config: FilesystemConfig = {};
+  public readonly type: FilesystemProviderType;
+
+  constructor(type: FilesystemProviderType) {
+    this.type = type;
+  }
+
+  /**
+   * Initialize the filesystem
+   */
+  abstract initialize(config?: FilesystemConfig): Promise<void>;
+
+  /**
+   * Check if filesystem is initialized
+   */
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  /**
+   * Close/cleanup the filesystem
+   */
+  abstract close(): Promise<void>;
+
+  // Filesystem operations
+  abstract readFile(path: string): Promise<Buffer | string>;
+  abstract writeFile(path: string, data: Buffer | string): Promise<void>;
+  abstract appendFile(path: string, data: Buffer | string): Promise<void>;
+  abstract exists(path: string): Promise<boolean>;
+  abstract stat(path: string): Promise<FileStats>;
+  abstract readdir(path: string): Promise<DirectoryEntry[]>;
+  abstract mkdir(path: string, recursive?: boolean): Promise<void>;
+  abstract unlink(path: string, recursive?: boolean): Promise<void>;
+  abstract copy(src: string, dest: string): Promise<void>;
+  abstract move(src: string, dest: string): Promise<void>;
+
+  // Key-value operations
+  abstract get(key: string): Promise<unknown>;
+  abstract set(key: string, value: unknown): Promise<void>;
+  abstract delete(key: string): Promise<void>;
+  abstract listKeys(prefix?: string): Promise<string[]>;
+  abstract hasKey(key: string): Promise<boolean>;
+
+  // Tool call tracking
+  abstract recordToolCall(metadata: ToolCallMetadata): Promise<void>;
+  abstract getToolCallHistory(filter?: {
+    tool?: string;
+    status?: ToolCallMetadata['status'];
+    since?: number;
+    until?: number;
+    limit?: number;
+  }): Promise<ToolCallMetadata[]>;
+
+  /**
+   * Normalize path (remove leading/trailing slashes, handle ..)
+   */
+  protected normalizePath(path: string): string {
+    return path
+      .split('/')
+      .filter((segment) => segment !== '' && segment !== '.')
+      .reduce((acc, segment) => {
+        if (segment === '..') {
+          acc.pop();
+        } else {
+          acc.push(segment);
+        }
+        return acc;
+      }, [] as string[])
+      .join('/');
+  }
+
+  /**
+   * Ensure filesystem is initialized before operation
+   */
+  protected ensureInitialized(): void {
+    if (!this.initialized) {
+      throw new Error(
+        `Filesystem provider ${this.type} is not initialized. Call initialize() first.`
+      );
+    }
+  }
+}
+

package/src/filesystem/index.ts

@@ -0,0 +1,5 @@
+// Provider exports
+export { BaseFilesystemProvider } from './base-provider.js';
+export { AgentFSProvider } from './agentfs-provider.js';
+export { MemoryFilesystemProvider } from './memory-provider.js';
+

package/src/filesystem/memory-provider.ts

@@ -0,0 +1,267 @@
+import type {
+  FilesystemConfig,
+  FileStats,
+  DirectoryEntry,
+  ToolCallMetadata,
+} from '../types.js';
+import { BaseFilesystemProvider } from './base-provider.js';
+
+/**
+ * In-memory filesystem provider
+ * Useful for testing and ephemeral operations
+ */
+export class MemoryFilesystemProvider extends BaseFilesystemProvider {
+  private fs: Map<string, Buffer | string> = new Map();
+  private kv: Map<string, unknown> = new Map();
+  private toolCalls: ToolCallMetadata[] = [];
+
+  constructor() {
+    super('memory');
+  }
+
+  /**
+   * Initialize memory filesystem (no-op for memory provider)
+   */
+  async initialize(config?: FilesystemConfig): Promise<void> {
+    this.config = { ...this.config, ...config };
+    this.initialized = true;
+  }
+
+  /**
+   * Close memory filesystem (clears all data)
+   */
+  async close(): Promise<void> {
+    this.fs.clear();
+    this.kv.clear();
+    this.toolCalls = [];
+    this.initialized = false;
+  }
+
+  // Filesystem operations
+  async readFile(path: string): Promise<Buffer | string> {
+    this.ensureInitialized();
+    const normalizedPath = this.normalizePath(path);
+    const content = this.fs.get(normalizedPath);
+    if (content === undefined) {
+      throw new Error(`File not found: ${path}`);
+    }
+    return content;
+  }
+
+  async writeFile(path: string, data: Buffer | string): Promise<void> {
+    this.ensureInitialized();
+    const normalizedPath = this.normalizePath(path);
+    // Ensure parent directory exists
+    const parentDir = normalizedPath.split('/').slice(0, -1).join('/');
+    if (parentDir && !this.fs.has(parentDir)) {
+      this.fs.set(parentDir, Buffer.from('')); // Mark as directory
+    }
+    this.fs.set(normalizedPath, typeof data === 'string' ? data : data);
+  }
+
+  async appendFile(path: string, data: Buffer | string): Promise<void> {
+    this.ensureInitialized();
+    const normalizedPath = this.normalizePath(path);
+    const existing = this.fs.get(normalizedPath);
+    const existingContent: string = existing instanceof Buffer 
+      ? existing.toString() 
+      : (typeof existing === 'string' ? existing : '');
+    const newData: string = data instanceof Buffer ? data.toString() : (typeof data === 'string' ? data : '');
+    this.fs.set(normalizedPath, existingContent + newData);
+  }
+
+  async exists(path: string): Promise<boolean> {
+    this.ensureInitialized();
+    const normalizedPath = this.normalizePath(path);
+    return this.fs.has(normalizedPath);
+  }
+
+  async stat(path: string): Promise<FileStats> {
+    this.ensureInitialized();
+    const normalizedPath = this.normalizePath(path);
+    const content = this.fs.get(normalizedPath);
+    if (content === undefined) {
+      throw new Error(`Path not found: ${path}`);
+    }
+
+    const isDirectory = typeof content === 'string' && content === '';
+    const isFile = !isDirectory;
+
+    return {
+      size: isFile ? (content instanceof Buffer ? content.length : content.length) : 0,
+      isDirectory,
+      isFile,
+      createdAt: Date.now() / 1000,
+      modifiedAt: Date.now() / 1000,
+    };
+  }
+
+  async readdir(path: string): Promise<DirectoryEntry[]> {
+    this.ensureInitialized();
+    const normalizedPath = this.normalizePath(path);
+    const prefix = normalizedPath === '' ? '' : `${normalizedPath}/`;
+    const entries: DirectoryEntry[] = [];
+    const seen = new Set<string>();
+
+    for (const [filePath] of this.fs.entries()) {
+      if (filePath.startsWith(prefix) || (prefix === '' && !filePath.includes('/'))) {
+        const relativePath = filePath.startsWith(prefix) ? filePath.slice(prefix.length) : filePath;
+        const parts = relativePath.split('/');
+        const name = parts[0];
+        const entryPath = prefix === '' ? name : `${prefix}${name}`;
+
+        if (name && !seen.has(entryPath)) {
+          seen.add(entryPath);
+          try {
+            const stats = await this.stat(entryPath);
+            entries.push({
+              name,
+              path: entryPath,
+              stats,
+            });
+          } catch {
+            // Skip if stat fails
+          }
+        }
+      }
+    }
+
+    return entries;
+  }
+
+  async mkdir(path: string, recursive = false): Promise<void> {
+    this.ensureInitialized();
+    const normalizedPath = this.normalizePath(path);
+    
+    if (recursive) {
+      const parts = normalizedPath.split('/');
+      let currentPath = '';
+      for (const part of parts) {
+        currentPath = currentPath ? `${currentPath}/${part}` : part;
+        if (!this.fs.has(currentPath)) {
+          this.fs.set(currentPath, Buffer.from('')); // Mark as directory
+        }
+      }
+    } else {
+      if (this.fs.has(normalizedPath)) {
+        throw new Error(`Directory already exists: ${path}`);
+      }
+      this.fs.set(normalizedPath, Buffer.from('')); // Mark as directory
+    }
+  }
+
+  async unlink(path: string, recursive = false): Promise<void> {
+    this.ensureInitialized();
+    const normalizedPath = this.normalizePath(path);
+    
+    if (!this.fs.has(normalizedPath)) {
+      throw new Error(`Path not found: ${path}`);
+    }
+
+    const stats = await this.stat(normalizedPath);
+    const prefix = `${normalizedPath}/`;
+
+    if (stats.isDirectory) {
+      if (recursive) {
+        // Remove all files/directories under this path
+        for (const [filePath] of this.fs.entries()) {
+          if (filePath.startsWith(prefix) || filePath === normalizedPath) {
+            this.fs.delete(filePath);
+          }
+        }
+      } else {
+        // Check if directory is empty
+        const entries = await this.readdir(normalizedPath);
+        if (entries.length > 0) {
+          throw new Error(`Directory not empty: ${path}`);
+        }
+        this.fs.delete(normalizedPath);
+      }
+    } else {
+      this.fs.delete(normalizedPath);
+    }
+  }
+
+  async copy(src: string, dest: string): Promise<void> {
+    this.ensureInitialized();
+    const normalizedSrc = this.normalizePath(src);
+    const normalizedDest = this.normalizePath(dest);
+    const content = this.fs.get(normalizedSrc);
+    if (content === undefined) {
+      throw new Error(`Source not found: ${src}`);
+    }
+    this.fs.set(normalizedDest, content);
+  }
+
+  async move(src: string, dest: string): Promise<void> {
+    await this.copy(src, dest);
+    await this.unlink(src);
+  }
+
+  // Key-value operations
+  async get(key: string): Promise<unknown> {
+    this.ensureInitialized();
+    return this.kv.get(key);
+  }
+
+  async set(key: string, value: unknown): Promise<void> {
+    this.ensureInitialized();
+    this.kv.set(key, value);
+  }
+
+  async delete(key: string): Promise<void> {
+    this.ensureInitialized();
+    this.kv.delete(key);
+  }
+
+  async listKeys(prefix?: string): Promise<string[]> {
+    this.ensureInitialized();
+    if (!prefix) {
+      return Array.from(this.kv.keys());
+    }
+    return Array.from(this.kv.keys()).filter((key) => key.startsWith(prefix));
+  }
+
+  async hasKey(key: string): Promise<boolean> {
+    this.ensureInitialized();
+    return this.kv.has(key);
+  }
+
+  // Tool call tracking
+  async recordToolCall(metadata: ToolCallMetadata): Promise<void> {
+    this.ensureInitialized();
+    this.toolCalls.push(metadata);
+  }
+
+  async getToolCallHistory(filter?: {
+    tool?: string;
+    status?: ToolCallMetadata['status'];
+    since?: number;
+    until?: number;
+    limit?: number;
+  }): Promise<ToolCallMetadata[]> {
+    this.ensureInitialized();
+    let results = [...this.toolCalls];
+
+    if (filter) {
+      if (filter.tool) {
+        results = results.filter((tc) => tc.tool === filter.tool);
+      }
+      if (filter.status) {
+        results = results.filter((tc) => tc.status === filter.status);
+      }
+      if (filter.since !== undefined) {
+        results = results.filter((tc) => tc.startedAt >= filter.since!);
+      }
+      if (filter.until !== undefined) {
+        results = results.filter((tc) => tc.startedAt <= filter.until!);
+      }
+      if (filter.limit !== undefined) {
+        results = results.slice(0, filter.limit);
+      }
+    }
+
+    return results.reverse(); // Most recent first
+  }
+}
+