agents-library 0.1.0

package/dist/memory/arcadedb-adapter.js

@@ -0,0 +1,314 @@
+/**
+ * ArcadeDB Adapter
+ *
+ * Provides database operations for long-term memory storage using ArcadeDB.
+ * Supports vertex/edge operations and Cypher queries with connection pooling.
+ */
+import { ok, err } from '../common/result.js';
+import { DatabaseErrorType } from '../common/types.js';
+/**
+ * ArcadeDB Client
+ *
+ * Low-level HTTP client for ArcadeDB REST API
+ * Handles connection, authentication, and query execution
+ */
+export class ArcadeDBClient {
+    config;
+    connected = false;
+    baseUrl;
+    auth;
+    timeout;
+    /**
+     * Create ArcadeDB Client
+     *
+     * @param config - Client configuration
+     */
+    constructor(config) {
+        this.config = config;
+        this.baseUrl = `http://${config.host}:${config.port}`;
+        this.auth = Buffer.from(`${config.username}:${config.password}`).toString('base64');
+        this.timeout = config.timeout || 30000;
+    }
+    /**
+     * Connect to ArcadeDB
+     *
+     * Verifies connectivity by executing a test query
+     *
+     * @returns Result indicating connection success or error
+     */
+    async connect() {
+        try {
+            // Temporarily mark as connected to allow test query
+            this.connected = true;
+            // Test connection with simple query
+            const result = await this.query('SELECT 1 as test');
+            if (!result.success) {
+                this.connected = false;
+                return result;
+            }
+            return ok(undefined);
+        }
+        catch (error) {
+            this.connected = false;
+            return err({
+                type: DatabaseErrorType.CONNECTION_ERROR,
+                message: `Failed to connect to ArcadeDB: ${error.message}`,
+                originalError: error,
+            });
+        }
+    }
+    /**
+     * Disconnect from ArcadeDB
+     *
+     * Marks client as disconnected (no persistent connection to close)
+     *
+     * @returns Result indicating disconnect success
+     */
+    async disconnect() {
+        this.connected = false;
+        return ok(undefined);
+    }
+    /**
+     * Check if client is connected
+     *
+     * @returns True if connected
+     */
+    isConnected() {
+        return this.connected;
+    }
+    /**
+     * Execute query
+     *
+     * Supports both SQL and Cypher languages
+     *
+     * @param command - Query command
+     * @param params - Optional query parameters
+     * @param language - Query language ('sql' or 'cypher'), defaults to 'sql'
+     * @returns Result with query results or error
+     */
+    async query(command, params, language = 'sql') {
+        if (!this.connected) {
+            return err({
+                type: DatabaseErrorType.NOT_CONNECTED,
+                message: 'Client not connected. Call connect() first.',
+                query: command,
+            });
+        }
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+            const response = await fetch(`${this.baseUrl}/api/v1/query/${this.config.database}`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Basic ${this.auth}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    language,
+                    command,
+                    ...(params && { params }),
+                }),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                const errorText = await response.text();
+                return err({
+                    type: DatabaseErrorType.QUERY_ERROR,
+                    message: `Query failed with status ${response.status}: ${errorText}`,
+                    query: command,
+                });
+            }
+            const data = await response.json();
+            if (data.error) {
+                return err({
+                    type: DatabaseErrorType.QUERY_ERROR,
+                    message: `Query error: ${data.error}`,
+                    query: command,
+                });
+            }
+            return ok(data.result || []);
+        }
+        catch (error) {
+            if (error.name === 'AbortError') {
+                return err({
+                    type: DatabaseErrorType.TIMEOUT,
+                    message: `Query timeout after ${this.timeout}ms`,
+                    query: command,
+                    originalError: error,
+                });
+            }
+            return err({
+                type: DatabaseErrorType.QUERY_ERROR,
+                message: `Query execution failed: ${error.message}`,
+                query: command,
+                originalError: error,
+            });
+        }
+    }
+}
+/**
+ * ArcadeDB Adapter
+ *
+ * High-level adapter for graph database operations
+ * Provides vertex/edge operations using Cypher queries
+ */
+export class ArcadeDBAdapter {
+    dbUrl;
+    username;
+    password;
+    timeout;
+    client = null;
+    /**
+     * Create ArcadeDB Adapter
+     *
+     * @param dbUrl - Database connection URL (format: http://host:port/database)
+     * @param username - Database username
+     * @param password - Database password
+     * @param timeout - Query timeout in milliseconds
+     */
+    constructor(dbUrl, username = 'root', password = 'root', timeout = 30000) {
+        this.dbUrl = dbUrl;
+        this.username = username;
+        this.password = password;
+        this.timeout = timeout;
+    }
+    /**
+     * Parse database URL into config
+     *
+     * @returns Client configuration
+     */
+    parseDbUrl() {
+        const url = new URL(this.dbUrl);
+        const pathParts = url.pathname.split('/').filter(Boolean);
+        const database = pathParts[pathParts.length - 1];
+        return {
+            host: url.hostname,
+            port: parseInt(url.port) || 2480,
+            database,
+            username: this.username,
+            password: this.password,
+            timeout: this.timeout,
+        };
+    }
+    /**
+     * Connect to database
+     *
+     * Creates client instance and establishes connection
+     *
+     * @returns Result indicating success or error
+     */
+    async connect() {
+        if (this.client?.isConnected()) {
+            return ok(undefined); // Already connected, reuse connection
+        }
+        try {
+            const config = this.parseDbUrl();
+            this.client = new ArcadeDBClient(config);
+            return await this.client.connect();
+        }
+        catch (error) {
+            return err({
+                type: DatabaseErrorType.CONNECTION_ERROR,
+                message: `Failed to parse database URL or connect: ${error.message}`,
+                originalError: error,
+            });
+        }
+    }
+    /**
+     * Disconnect from database
+     *
+     * @returns Result indicating success or error
+     */
+    async disconnect() {
+        if (!this.client) {
+            return ok(undefined);
+        }
+        const result = await this.client.disconnect();
+        this.client = null;
+        return result;
+    }
+    /**
+     * Execute Cypher query
+     *
+     * @param cypher - Cypher query command
+     * @param params - Optional query parameters
+     * @returns Result with query results or error
+     */
+    async query(cypher, params) {
+        if (!this.client || !this.client.isConnected()) {
+            return err({
+                type: DatabaseErrorType.NOT_CONNECTED,
+                message: 'Not connected to database. Call connect() first.',
+                query: cypher,
+            });
+        }
+        return this.client.query(cypher, params, 'cypher');
+    }
+    /**
+     * Create vertex
+     *
+     * @param type - Vertex type (label)
+     * @param properties - Vertex properties
+     * @returns Result with vertex @rid or error
+     */
+    async createVertex(type, properties) {
+        // Build property map with parameterization for Cypher
+        const propKeys = Object.keys(properties);
+        const propAssignments = propKeys.map(key => `${key}: $${key}`).join(', ');
+        // Cypher syntax: CREATE (n:Type {prop1: value1, prop2: value2}) RETURN n
+        const cypher = `CREATE (n:${type} {${propAssignments}}) RETURN n`;
+        const params = { ...properties };
+        const result = await this.query(cypher, params);
+        if (!result.success) {
+            return result;
+        }
+        if (result.data.length === 0 || !result.data[0]['@rid']) {
+            return err({
+                type: DatabaseErrorType.QUERY_ERROR,
+                message: 'Vertex created but @rid not returned',
+                query: cypher,
+            });
+        }
+        return ok(result.data[0]['@rid']);
+    }
+    /**
+     * Create edge
+     *
+     * @param fromRid - Source vertex @rid
+     * @param toRid - Target vertex @rid
+     * @param type - Edge type (label)
+     * @param properties - Optional edge properties
+     * @returns Result with edge @rid or error
+     */
+    async createEdge(fromRid, toRid, type, properties) {
+        // Build Cypher query with parameterization
+        // Cypher syntax: MATCH (a), (b) WHERE id(a) = '@rid1' AND id(b) = '@rid2'
+        //                CREATE (a)-[r:TYPE {props}]->(b) RETURN r
+        let cypher;
+        let params;
+        if (properties && Object.keys(properties).length > 0) {
+            const propKeys = Object.keys(properties);
+            const propAssignments = propKeys.map(key => `${key}: $${key}`).join(', ');
+            cypher = `MATCH (a), (b) WHERE id(a) = $fromRid AND id(b) = $toRid CREATE (a)-[r:${type} {${propAssignments}}]->(b) RETURN r`;
+            params = { fromRid, toRid, ...properties };
+        }
+        else {
+            cypher = `MATCH (a), (b) WHERE id(a) = $fromRid AND id(b) = $toRid CREATE (a)-[r:${type}]->(b) RETURN r`;
+            params = { fromRid, toRid };
+        }
+        const result = await this.query(cypher, params);
+        if (!result.success) {
+            return result;
+        }
+        if (result.data.length === 0 || !result.data[0]['@rid']) {
+            return err({
+                type: DatabaseErrorType.QUERY_ERROR,
+                message: 'Edge created but @rid not returned',
+                query: cypher,
+            });
+        }
+        return ok(result.data[0]['@rid']);
+    }
+}
+//# sourceMappingURL=arcadedb-adapter.js.map

package/dist/memory/arcadedb-adapter.js.map

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

package/dist/memory/file-storage-adapter.d.ts

@@ -0,0 +1,122 @@
+/**
+ * File Storage Adapter
+ *
+ * Provides low-level file operations for JSON and Markdown files with:
+ * - Atomic writes (write to temp → rename)
+ * - File locking with exponential backoff
+ * - Error handling with Result<T, FileError> pattern
+ * - Graceful ENOENT handling (returns null instead of error)
+ */
+import type { Result } from '../common/result.js';
+import type { FileError } from '../common/types.js';
+/**
+ * File Storage Adapter
+ *
+ * Manages low-level file operations with atomic writes and error handling
+ */
+export declare class FileStorageAdapter {
+    private readonly dataPath;
+    /**
+     * In-memory locks for file operations to prevent race conditions
+     */
+    private fileLocks;
+    /**
+     * Create File Storage Adapter
+     *
+     * @param dataPath - Base directory for file storage
+     */
+    constructor(dataPath: string);
+    /**
+     * Read JSON file
+     *
+     * @param filePath - Path to JSON file (relative to dataPath)
+     * @returns Result with parsed JSON data or null if file doesn't exist
+     */
+    readJSON<T>(filePath: string): Promise<Result<T | null, FileError>>;
+    /**
+     * Write JSON file with atomic write pattern
+     *
+     * Atomic pattern: write to temp file → rename to final file
+     * This prevents partial writes and corruption
+     *
+     * @param filePath - Path to JSON file (relative to dataPath)
+     * @param data - Data to serialize and write
+     * @returns Result indicating success or error
+     */
+    writeJSON<T>(filePath: string, data: T): Promise<Result<void, FileError>>;
+    /**
+     * Acquire lock for a file path and execute operation
+     *
+     * Ensures only one operation at a time per file path
+     *
+     * @param filePath - Path to lock
+     * @param operation - Async operation to execute while locked
+     * @returns Result of the operation
+     */
+    private withFileLock;
+    /**
+     * Append item to JSON array file
+     *
+     * Reads existing array, appends item, writes back atomically with file locking
+     *
+     * @param filePath - Path to JSON array file
+     * @param item - Item to append
+     * @returns Result indicating success or error
+     */
+    appendToJSONArray<T>(filePath: string, item: T): Promise<Result<void, FileError>>;
+    /**
+     * Trim JSON array to keep only last N items
+     *
+     * Reads array, keeps last N items, returns removed items
+     *
+     * @param filePath - Path to JSON array file
+     * @param keepLast - Number of items to keep
+     * @returns Result with removed items or error
+     */
+    trimJSONArray<T>(filePath: string, keepLast: number): Promise<Result<T[], FileError>>;
+    /**
+     * Ensure directory exists (create if needed)
+     *
+     * @param dirPath - Directory path (relative to dataPath)
+     * @returns Result indicating success or error
+     */
+    ensureDirectory(dirPath: string): Promise<Result<void, FileError>>;
+    /**
+     * List files in directory
+     *
+     * @param dirPath - Directory path (relative to dataPath)
+     * @returns Result with array of filenames or error
+     */
+    listFiles(dirPath: string): Promise<Result<string[], FileError>>;
+    /**
+     * Delete file
+     *
+     * @param filePath - File path (relative to dataPath)
+     * @returns Result indicating success or error
+     */
+    deleteFile(filePath: string): Promise<Result<void, FileError>>;
+    /**
+     * Read Markdown file
+     *
+     * @param filePath - Path to Markdown file (relative to dataPath)
+     * @returns Result with file content or null if file doesn't exist
+     */
+    readMarkdown(filePath: string): Promise<Result<string | null, FileError>>;
+    /**
+     * Write Markdown file with atomic write pattern
+     *
+     * @param filePath - Path to Markdown file (relative to dataPath)
+     * @param content - Markdown content to write
+     * @returns Result indicating success or error
+     */
+    writeMarkdown(filePath: string, content: string): Promise<Result<void, FileError>>;
+    /**
+     * Append content to Markdown file
+     *
+     * @param filePath - Path to Markdown file
+     * @param content - Content to append
+     * @returns Result indicating success or error
+     */
+    appendToMarkdown(filePath: string, content: string): Promise<Result<void, FileError>>;
+}
+//# sourceMappingURL=file-storage-adapter.d.ts.map

package/dist/memory/file-storage-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-storage-adapter.d.ts","sourceRoot":"","sources":["../../src/memory/file-storage-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAGpD;;;;GAIG;AACH,qBAAa,kBAAkB;IAWjB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAVrC;;OAEG;IACH,OAAO,CAAC,SAAS,CAAyC;IAE1D;;;;OAIG;gBAC0B,QAAQ,EAAE,MAAM;IAE7C;;;;;OAKG;IACG,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,EAAE,SAAS,CAAC,CAAC;IA+BzE;;;;;;;;;OASG;IACG,SAAS,CAAC,CAAC,EACf,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,CAAC,GACN,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAqCnC;;;;;;;;OAQG;YACW,YAAY;IA6B1B;;;;;;;;OAQG;IACG,iBAAiB,CAAC,CAAC,EACvB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,CAAC,GACN,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAmBnC;;;;;;;;OAQG;IACG,aAAa,CAAC,CAAC,EACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IAmClC;;;;;OAKG;IACG,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAexE;;;;;OAKG;IACG,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,SAAS,CAAC,CAAC;IAoBtE;;;;;OAKG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAoBpE;;;;;OAKG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,EAAE,SAAS,CAAC,CAAC;IAoB/E;;;;;;OAMG;IACG,aAAa,CACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAkCnC;;;;;;OAMG;IACG,gBAAgB,CACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;CAcpC"}