agent-orcha 0.0.4 → 0.0.5

package/dist/lib/tools/built-in/knowledge-sql.tool.js

@@ -0,0 +1,127 @@
+import { tool } from "../../types/tool-factory.js";
+import { z } from 'zod';
+import { getPool, getDatabaseType } from "../../knowledge/utils/connection-pool.js";
+import { validateReadonlySql } from "./query-validators.js";
+/**
+ * Create a SQL query tool for a knowledge base backed by a database source.
+ */
+export function createKnowledgeSqlTool(name, config) {
+    const dbSource = config.source;
+    const dbType = getDatabaseType(dbSource.connectionString);
+    const exampleQueries = buildSqlExamples(dbSource, dbType);
+    return tool(async ({ query, limit }) => {
+        const validation = validateReadonlySql(query);
+        if (!validation.valid) {
+            return `Query rejected: ${validation.reason}`;
+        }
+        const effectiveLimit = Math.min(limit ?? 25, 100);
+        // Append LIMIT if not already present
+        const hasLimit = /\bLIMIT\b/i.test(query);
+        const finalQuery = hasLimit ? query : `${query.trimEnd()}\nLIMIT ${effectiveLimit}`;
+        try {
+            const pool = getPool(dbSource.connectionString);
+            if (dbType === 'sqlite') {
+                return executeSqliteReadonly(pool, finalQuery);
+            }
+            else if (dbType === 'postgresql') {
+                return await executePostgresReadonly(pool, finalQuery);
+            }
+            else {
+                return await executeMysqlReadonly(pool, finalQuery);
+            }
+        }
+        catch (error) {
+            return `SQL query error: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    }, {
+        name: `knowledge_sql_${name}`,
+        description: `Run a readonly SQL query against the "${name}" source database (${dbType}).
+
+SOURCE QUERY (shows available tables/columns):
+${dbSource.query.trim()}
+
+Content column: ${dbSource.contentColumn}
+${dbSource.metadataColumns ? `Metadata columns: ${dbSource.metadataColumns.join(', ')}` : ''}
+
+EXAMPLE QUERIES:
+${exampleQueries}
+
+RESTRICTIONS: Only SELECT queries allowed. No INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, CREATE, GRANT, or REVOKE.
+
+TIPS: Use this when you need precise filtering, aggregation, or joins that semantic search can't provide. The source query above shows the tables and columns available.`,
+        schema: z.object({
+            query: z.string().describe('A readonly SQL SELECT query'),
+            limit: z.number().optional().describe('Max rows to return (default 25, max 100). Ignored if query already has LIMIT.'),
+        }),
+    });
+}
+async function executePostgresReadonly(pool, query) {
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        await client.query('SET TRANSACTION READ ONLY');
+        const result = await client.query(query);
+        await client.query('COMMIT');
+        if (!result.rows || result.rows.length === 0) {
+            return 'Query returned no results.';
+        }
+        return JSON.stringify(result.rows, null, 2);
+    }
+    catch (error) {
+        await client.query('ROLLBACK').catch(() => { });
+        throw error;
+    }
+    finally {
+        client.release();
+    }
+}
+async function executeMysqlReadonly(pool, query) {
+    const connection = await pool.getConnection();
+    try {
+        await connection.query('START TRANSACTION READ ONLY');
+        const [rows] = await connection.query(query);
+        await connection.query('COMMIT');
+        if (!rows || (Array.isArray(rows) && rows.length === 0)) {
+            return 'Query returned no results.';
+        }
+        return JSON.stringify(rows, null, 2);
+    }
+    catch (error) {
+        await connection.query('ROLLBACK').catch(() => { });
+        throw error;
+    }
+    finally {
+        connection.release();
+    }
+}
+function executeSqliteReadonly(db, query) {
+    const rows = db.prepare(query).all();
+    if (!rows || rows.length === 0) {
+        return 'Query returned no results.';
+    }
+    return JSON.stringify(rows, null, 2);
+}
+function buildSqlExamples(dbSource, dbType) {
+    // Parse table names from the original query
+    const tableMatch = dbSource.query.match(/FROM\s+"?(\w+)"?/i);
+    const tableName = tableMatch ? tableMatch[1] : 'table';
+    const contentCol = dbSource.contentColumn;
+    const metaCols = dbSource.metadataColumns ?? [];
+    const examples = [];
+    // Count query
+    examples.push(`- SELECT COUNT(*) FROM "${tableName}"`);
+    // Simple select with content
+    if (metaCols.length > 0) {
+        const selectCols = metaCols.slice(0, 3).map((c) => `"${c}"`).join(', ');
+        examples.push(`- SELECT ${selectCols} FROM "${tableName}" LIMIT 10`);
+    }
+    // Content search — SQLite and MySQL don't support ILIKE
+    const likeOp = dbType === 'postgresql' ? 'ILIKE' : 'LIKE';
+    examples.push(`- SELECT "${contentCol}" FROM "${tableName}" WHERE "${contentCol}" ${likeOp} '%keyword%' LIMIT 10`);
+    // Aggregate if there's a useful column
+    if (metaCols.length > 1) {
+        examples.push(`- SELECT "${metaCols[0]}", COUNT(*) as cnt FROM "${tableName}" GROUP BY "${metaCols[0]}" ORDER BY cnt DESC LIMIT 10`);
+    }
+    return examples.join('\n');
+}
+//# sourceMappingURL=knowledge-sql.tool.js.map

package/dist/lib/tools/built-in/knowledge-sql.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-sql.tool.js","sourceRoot":"","sources":["../../../../lib/tools/built-in/knowledge-sql.tool.ts"],"names":[],"mappings":"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"}

package/dist/lib/tools/built-in/knowledge-tools-factory.d.ts

@@ -0,0 +1,17 @@
+import type { StructuredTool } from '../../types/llm-types.ts';
+import type { KnowledgeStoreInstance, KnowledgeConfig } from '../../knowledge/types.ts';
+import type { SqliteStore } from '../../knowledge/sqlite-store.ts';
+/**
+ * Create the full toolset for a knowledge base based on its type.
+ *
+ * - All KBs get: search
+ * - KBs with entities get: search + traverse + entity_lookup + graph_schema
+ * - Database-sourced KBs additionally get: sql
+ */
+export declare function createKnowledgeTools(name: string, store: KnowledgeStoreInstance, sqliteStore?: SqliteStore): StructuredTool[];
+/**
+ * Build a human-readable schema description from a knowledge config with graph.
+ * Used in tool descriptions to help LLMs understand the graph structure.
+ */
+export declare function buildGraphSchemaDescription(config: KnowledgeConfig): string;
+//# sourceMappingURL=knowledge-tools-factory.d.ts.map

package/dist/lib/tools/built-in/knowledge-tools-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-tools-factory.d.ts","sourceRoot":"","sources":["../../../../lib/tools/built-in/knowledge-tools-factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AACxF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAUnE;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,sBAAsB,EAC7B,WAAW,CAAC,EAAE,WAAW,GACxB,cAAc,EAAE,CAsBlB;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAyB3E"}

package/dist/lib/tools/built-in/knowledge-tools-factory.js

@@ -0,0 +1,54 @@
+import { createKnowledgeSearchTool } from "./knowledge-search.tool.js";
+import { createKnowledgeTraverseTool } from "./knowledge-traverse.tool.js";
+import { createKnowledgeEntityLookupTool } from "./knowledge-entity-lookup.tool.js";
+import { createKnowledgeGraphSchemaTool } from "./knowledge-graph-schema.tool.js";
+import { createKnowledgeSqlTool } from "./knowledge-sql.tool.js";
+import { createLogger } from "../../logger.js";
+const logger = createLogger('KnowledgeToolsFactory');
+/**
+ * Create the full toolset for a knowledge base based on its type.
+ *
+ * - All KBs get: search
+ * - KBs with entities get: search + traverse + entity_lookup + graph_schema
+ * - Database-sourced KBs additionally get: sql
+ */
+export function createKnowledgeTools(name, store, sqliteStore) {
+    const config = store.config;
+    const tools = [];
+    // 1. Always create search tool
+    tools.push(createKnowledgeSearchTool(name, store));
+    // 2. Graph tools — if entities exist in the SQLite store
+    if (sqliteStore && sqliteStore.getEntityCount() > 0) {
+        tools.push(createKnowledgeTraverseTool(name, config, sqliteStore));
+        tools.push(createKnowledgeEntityLookupTool(name, config, sqliteStore));
+        tools.push(createKnowledgeGraphSchemaTool(name, config, sqliteStore));
+    }
+    // 3. SQL tool — if backed by a database source
+    if (config.source.type === 'database') {
+        tools.push(createKnowledgeSqlTool(name, config));
+    }
+    logger.info(`Created ${tools.length} knowledge tool(s) for "${name}": ${tools.map((t) => t.name).join(', ')}`);
+    return tools;
+}
+/**
+ * Build a human-readable schema description from a knowledge config with graph.
+ * Used in tool descriptions to help LLMs understand the graph structure.
+ */
+export function buildGraphSchemaDescription(config) {
+    const sections = [];
+    sections.push(`Knowledge base: "${config.name}" — ${config.description ?? ''}`);
+    if (!config.graph?.directMapping)
+        return sections.join('\n');
+    const mapping = config.graph.directMapping;
+    const entityLines = mapping.entities.map((e) => {
+        const props = e.properties.map((p) => typeof p === 'string' ? p : Object.values(p)[0]);
+        return `  ${e.type}: ${props.join(', ')}`;
+    });
+    sections.push(`ENTITY TYPES:\n${entityLines.join('\n')}`);
+    if (mapping.relationships && mapping.relationships.length > 0) {
+        const relLines = mapping.relationships.map((r) => `  (${r.source}) -[${r.type}]-> (${r.target})`);
+        sections.push(`RELATIONSHIPS:\n${relLines.join('\n')}`);
+    }
+    return sections.join('\n');
+}
+//# sourceMappingURL=knowledge-tools-factory.js.map

package/dist/lib/tools/built-in/knowledge-tools-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-tools-factory.js","sourceRoot":"","sources":["../../../../lib/tools/built-in/knowledge-tools-factory.ts"],"names":[],"mappings":"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"}

package/dist/lib/tools/built-in/knowledge-traverse.tool.d.ts

@@ -0,0 +1,9 @@
+import type { StructuredTool } from '../../types/llm-types.ts';
+import type { SqliteStore } from '../../knowledge/sqlite-store.ts';
+import type { KnowledgeConfig } from '../../knowledge/types.ts';
+/**
+ * Create a graph traversal tool for a knowledge base with entities.
+ * Gets the neighborhood around an entity (N hops).
+ */
+export declare function createKnowledgeTraverseTool(name: string, config: KnowledgeConfig, sqliteStore: SqliteStore): StructuredTool;
+//# sourceMappingURL=knowledge-traverse.tool.d.ts.map

package/dist/lib/tools/built-in/knowledge-traverse.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-traverse.tool.d.ts","sourceRoot":"","sources":["../../../../lib/tools/built-in/knowledge-traverse.tool.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAA8B,MAAM,iCAAiC,CAAC;AAC/F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAKhE;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,eAAe,EACvB,WAAW,EAAE,WAAW,GACvB,cAAc,CA0DhB"}

package/dist/lib/tools/built-in/knowledge-traverse.tool.js

@@ -0,0 +1,91 @@
+import { tool } from "../../types/tool-factory.js";
+import { z } from 'zod';
+import { buildGraphSchemaDescription } from "./knowledge-tools-factory.js";
+const MAX_NODES = 50;
+/**
+ * Create a graph traversal tool for a knowledge base with entities.
+ * Gets the neighborhood around an entity (N hops).
+ */
+export function createKnowledgeTraverseTool(name, config, sqliteStore) {
+    const schemaInfo = buildGraphSchemaDescription(config);
+    return tool(async ({ entityName, entityId, depth }) => {
+        const effectiveDepth = Math.min(Math.max(depth ?? 1, 1), 3);
+        let targetId = entityId;
+        // If name given but no ID, search for a matching entity
+        if (!targetId && entityName) {
+            try {
+                const allEntities = sqliteStore.getAllEntities();
+                const nameLower = entityName.toLowerCase();
+                const match = allEntities.find((e) => e.name.toLowerCase() === nameLower || e.name.toLowerCase().includes(nameLower));
+                if (!match) {
+                    return `No entity found matching name "${entityName}". Try a different name or use knowledge_entity_lookup_${name} to search.`;
+                }
+                targetId = match.id;
+            }
+            catch (error) {
+                return `Error searching for entity: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        }
+        if (!targetId) {
+            return 'Provide either entityName or entityId to traverse from.';
+        }
+        try {
+            const { entities, relationships } = sqliteStore.getNeighborhood(targetId, effectiveDepth);
+            if (entities.length === 0) {
+                return `No neighbors found for entity "${targetId}" at depth ${effectiveDepth}.`;
+            }
+            const truncated = entities.length > MAX_NODES;
+            const displayEntities = entities.slice(0, MAX_NODES);
+            return formatTraversalResult(displayEntities, relationships, effectiveDepth, truncated, entities.length);
+        }
+        catch (error) {
+            return `Traversal error: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    }, {
+        name: `knowledge_traverse_${name}`,
+        description: `Explore the neighborhood around an entity in the "${name}" knowledge graph. Returns connected nodes and relationships within N hops.
+
+${schemaInfo}
+
+TIPS: Use this to understand how an entity relates to others. Start with depth=1 for immediate connections. Use knowledge_entity_lookup_${name} first if you need to find the entity's ID or name.`,
+        schema: z.object({
+            entityName: z.string().optional().describe('Name of the entity to start from (case-insensitive partial match)'),
+            entityId: z.string().optional().describe('ID of the entity to start from (exact match, takes precedence over entityName)'),
+            depth: z.number().optional().describe('How many hops to traverse (1-3, default 1)'),
+        }),
+    });
+}
+function formatTraversalResult(entities, relationships, depth, truncated, totalNodes) {
+    const sections = [];
+    // Group entities by type
+    const byType = new Map();
+    for (const entity of entities) {
+        const list = byType.get(entity.type) ?? [];
+        list.push(entity);
+        byType.set(entity.type, list);
+    }
+    sections.push(`NEIGHBORHOOD (depth=${depth}, ${entities.length} nodes, ${relationships.length} edges)${truncated ? ` [truncated from ${totalNodes}]` : ''}`);
+    sections.push('\nNODES:');
+    for (const [type, typeEntities] of byType) {
+        sections.push(`  [${type}] (${typeEntities.length})`);
+        for (const entity of typeEntities.slice(0, 20)) {
+            const desc = entity.description ? ` — ${entity.description.substring(0, 100)}` : '';
+            sections.push(`    - ${entity.name} (id: ${entity.id})${desc}`);
+        }
+        if (typeEntities.length > 20) {
+            sections.push(`    ... and ${typeEntities.length - 20} more`);
+        }
+    }
+    if (relationships.length > 0) {
+        sections.push('\nEDGES:');
+        const displayEdges = relationships.slice(0, 30);
+        for (const edge of displayEdges) {
+            sections.push(`  (${edge.source_id}) -[${edge.type}]-> (${edge.target_id})`);
+        }
+        if (relationships.length > 30) {
+            sections.push(`  ... and ${relationships.length - 30} more edges`);
+        }
+    }
+    return sections.join('\n');
+}
+//# sourceMappingURL=knowledge-traverse.tool.js.map

package/dist/lib/tools/built-in/knowledge-traverse.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-traverse.tool.js","sourceRoot":"","sources":["../../../../lib/tools/built-in/knowledge-traverse.tool.ts"],"names":[],"mappings":"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"}

package/dist/lib/tools/built-in/memory-save.tool.d.ts

@@ -0,0 +1,4 @@
+import type { StructuredTool } from '../../types/llm-types.ts';
+import type { MemoryManager } from '../../memory/memory-manager.ts';
+export declare function createMemorySaveTool(memoryManager: MemoryManager, agentName: string, maxLines: number): StructuredTool;
+//# sourceMappingURL=memory-save.tool.d.ts.map

package/dist/lib/tools/built-in/memory-save.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-save.tool.d.ts","sourceRoot":"","sources":["../../../../lib/tools/built-in/memory-save.tool.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAEpE,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,aAAa,EAC5B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,cAAc,CAuBhB"}

package/dist/lib/tools/built-in/memory-save.tool.js

@@ -0,0 +1,21 @@
+import { tool } from "../../types/tool-factory.js";
+import { z } from 'zod';
+export function createMemorySaveTool(memoryManager, agentName, maxLines) {
+    return tool(async ({ content }) => {
+        await memoryManager.save(agentName, content, maxLines);
+        const lineCount = content.split('\n').length;
+        return `Memory saved successfully (${lineCount} lines).`;
+    }, {
+        name: 'save_memory',
+        description: 'Save or update your long-term memory. Provide the COMPLETE memory content ' +
+            'that should be persisted. This replaces the entire memory file. ' +
+            'Use this to remember important facts, user preferences, and key context across conversations.',
+        schema: z.object({
+            content: z
+                .string()
+                .describe('The full memory content to save. This replaces any existing memory. ' +
+                'Use markdown formatting with bullet points for clarity.'),
+        }),
+    });
+}
+//# sourceMappingURL=memory-save.tool.js.map

package/dist/lib/tools/built-in/memory-save.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-save.tool.js","sourceRoot":"","sources":["../../../../lib/tools/built-in/memory-save.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AACnD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,MAAM,UAAU,oBAAoB,CAClC,aAA4B,EAC5B,SAAiB,EACjB,QAAgB;IAEhB,OAAO,IAAI,CACT,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;QACpB,MAAM,aAAa,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;QACvD,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;QAC7C,OAAO,8BAA8B,SAAS,UAAU,CAAC;IAC3D,CAAC,EACD;QACE,IAAI,EAAE,aAAa;QACnB,WAAW,EACT,4EAA4E;YAC5E,kEAAkE;YAClE,+FAA+F;QACjG,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;YACf,OAAO,EAAE,CAAC;iBACP,MAAM,EAAE;iBACR,QAAQ,CACP,sEAAsE;gBACtE,yDAAyD,CAC1D;SACJ,CAAC;KACH,CACF,CAAC;AACJ,CAAC"}

package/dist/lib/tools/built-in/query-validators.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared readonly validation for Cypher and SQL queries.
+ * Strips comments and string literals before checking for write keywords.
+ */
+interface ValidationResult {
+    valid: boolean;
+    reason?: string;
+}
+/**
+ * Validate that a Cypher query is readonly (no mutations).
+ */
+export declare function validateReadonlyCypher(query: string): ValidationResult;
+/**
+ * Validate that a SQL query is readonly (no mutations).
+ */
+export declare function validateReadonlySql(query: string): ValidationResult;
+export {};
+//# sourceMappingURL=query-validators.d.ts.map

package/dist/lib/tools/built-in/query-validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-validators.d.ts","sourceRoot":"","sources":["../../../../lib/tools/built-in/query-validators.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,UAAU,gBAAgB;IACxB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA+CD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAoBtE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAkBnE"}

package/dist/lib/tools/built-in/query-validators.js

@@ -0,0 +1,87 @@
+/**
+ * Shared readonly validation for Cypher and SQL queries.
+ * Strips comments and string literals before checking for write keywords.
+ */
+/**
+ * Strip single-line comments, multi-line comments, and string literals
+ * so keyword detection doesn't get tricked by values inside strings/comments.
+ */
+function stripCommentsAndStrings(query) {
+    return query
+        // Remove single-line comments (// or --)
+        .replace(/\/\/.*$/gm, '')
+        .replace(/--.*$/gm, '')
+        // Remove multi-line comments
+        .replace(/\/\*[\s\S]*?\*\//g, '')
+        // Remove double-quoted strings
+        .replace(/"(?:[^"\\]|\\.)*"/g, '""')
+        // Remove single-quoted strings
+        .replace(/'(?:[^'\\]|\\.)*'/g, "''")
+        // Remove backtick-quoted identifiers
+        .replace(/`(?:[^`\\]|\\.)*`/g, '``');
+}
+const CYPHER_WRITE_KEYWORDS = [
+    'CREATE',
+    'DELETE',
+    'MERGE',
+    'SET',
+    'REMOVE',
+    'DROP',
+    'DETACH',
+    'CALL\\s+\\{', // CALL { ... } subqueries that could write
+    'FOREACH',
+];
+const SQL_WRITE_KEYWORDS = [
+    'INSERT',
+    'UPDATE',
+    'DELETE',
+    'DROP',
+    'ALTER',
+    'TRUNCATE',
+    'CREATE',
+    'GRANT',
+    'REVOKE',
+    'EXEC',
+    'EXECUTE',
+];
+/**
+ * Validate that a Cypher query is readonly (no mutations).
+ */
+export function validateReadonlyCypher(query) {
+    if (!query.trim()) {
+        return { valid: false, reason: 'Query cannot be empty.' };
+    }
+    const stripped = stripCommentsAndStrings(query);
+    for (const keyword of CYPHER_WRITE_KEYWORDS) {
+        // Match keyword as whole word (word boundary), case-insensitive
+        const regex = new RegExp(`\\b${keyword}\\b`, 'i');
+        if (regex.test(stripped)) {
+            const cleanKeyword = keyword.replace(/\\s\+/, ' ').replace(/\\/, '');
+            return {
+                valid: false,
+                reason: `Write operation "${cleanKeyword}" is not allowed. Only read queries (MATCH, RETURN, WITH, WHERE, ORDER BY, etc.) are permitted.`,
+            };
+        }
+    }
+    return { valid: true };
+}
+/**
+ * Validate that a SQL query is readonly (no mutations).
+ */
+export function validateReadonlySql(query) {
+    if (!query.trim()) {
+        return { valid: false, reason: 'Query cannot be empty.' };
+    }
+    const stripped = stripCommentsAndStrings(query);
+    for (const keyword of SQL_WRITE_KEYWORDS) {
+        const regex = new RegExp(`\\b${keyword}\\b`, 'i');
+        if (regex.test(stripped)) {
+            return {
+                valid: false,
+                reason: `Write operation "${keyword}" is not allowed. Only SELECT queries are permitted.`,
+            };
+        }
+    }
+    return { valid: true };
+}
+//# sourceMappingURL=query-validators.js.map

package/dist/lib/tools/built-in/query-validators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-validators.js","sourceRoot":"","sources":["../../../../lib/tools/built-in/query-validators.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH;;;GAGG;AACH,SAAS,uBAAuB,CAAC,KAAa;IAC5C,OAAO,KAAK;QACV,yCAAyC;SACxC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;SACxB,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC;QACvB,6BAA6B;SAC5B,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC;QACjC,+BAA+B;SAC9B,OAAO,CAAC,oBAAoB,EAAE,IAAI,CAAC;QACpC,+BAA+B;SAC9B,OAAO,CAAC,oBAAoB,EAAE,IAAI,CAAC;QACpC,qCAAqC;SACpC,OAAO,CAAC,oBAAoB,EAAE,IAAI,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,qBAAqB,GAAG;IAC5B,QAAQ;IACR,QAAQ;IACR,OAAO;IACP,KAAK;IACL,QAAQ;IACR,MAAM;IACN,QAAQ;IACR,aAAa,EAAE,2CAA2C;IAC1D,SAAS;CACV,CAAC;AAEF,MAAM,kBAAkB,GAAG;IACzB,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,MAAM;IACN,OAAO;IACP,UAAU;IACV,QAAQ;IACR,OAAO;IACP,QAAQ;IACR,MAAM;IACN,SAAS;CACV,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAa;IAClD,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAClB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;IAC5D,CAAC;IAED,MAAM,QAAQ,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAC;IAEhD,KAAK,MAAM,OAAO,IAAI,qBAAqB,EAAE,CAAC;QAC5C,gEAAgE;QAChE,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,MAAM,OAAO,KAAK,EAAE,GAAG,CAAC,CAAC;QAClD,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzB,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACrE,OAAO;gBACL,KAAK,EAAE,KAAK;gBACZ,MAAM,EAAE,oBAAoB,YAAY,iGAAiG;aAC1I,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAClB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;IAC5D,CAAC;IAED,MAAM,QAAQ,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAC;IAEhD,KAAK,MAAM,OAAO,IAAI,kBAAkB,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,MAAM,OAAO,KAAK,EAAE,GAAG,CAAC,CAAC;QAClD,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzB,OAAO;gBACL,KAAK,EAAE,KAAK;gBACZ,MAAM,EAAE,oBAAoB,OAAO,sDAAsD;aAC1F,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzB,CAAC"}

package/dist/lib/tools/index.d.ts

@@ -1,5 +1,5 @@
-export { ToolRegistry } from './tool-registry.js';
-export { ToolDiscovery } from './tool-discovery.js';
-export { AgentToolWrapper } from './agent-tool-wrapper.js';
-export { createKnowledgeSearchTool, createAskUserTool } from './built-in/index.js';
+export { ToolRegistry } from './tool-registry.ts';
+export { ToolDiscovery } from './tool-discovery.ts';
+export { AgentToolWrapper } from './agent-tool-wrapper.ts';
+export { createKnowledgeSearchTool, createAskUserTool } from './built-in/index.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/tools/index.js

@@ -1,5 +1,5 @@
-export { ToolRegistry } from './tool-registry.js';
-export { ToolDiscovery } from './tool-discovery.js';
-export { AgentToolWrapper } from './agent-tool-wrapper.js';
-export { createKnowledgeSearchTool, createAskUserTool } from './built-in/index.js';
+export { ToolRegistry } from "./tool-registry.js";
+export { ToolDiscovery } from "./tool-discovery.js";
+export { AgentToolWrapper } from "./agent-tool-wrapper.js";
+export { createKnowledgeSearchTool, createAskUserTool } from "./built-in/index.js";
 //# sourceMappingURL=index.js.map

package/dist/lib/tools/tool-discovery.d.ts

@@ -1,50 +1,28 @@
-import type { StructuredTool } from '@langchain/core/tools';
-import type { ToolRegistry } from './tool-registry.js';
-import type { MCPClientManager } from '../mcp/mcp-client.js';
-import type { KnowledgeStoreManager } from '../knowledge/knowledge-store-manager.js';
-import type { FunctionLoader } from '../functions/function-loader.js';
-import type { GraphToolConfig, GraphAgentConfig } from '../workflows/types.js';
-import type { AgentLoader } from '../agents/agent-loader.js';
-import type { AgentExecutor } from '../agents/agent-executor.js';
+import type { StructuredTool } from '../types/llm-types.ts';
+import type { ToolRegistry } from './tool-registry.ts';
+import type { MCPClientManager } from '../mcp/mcp-client.ts';
+import type { KnowledgeStore } from '../knowledge/knowledge-store.ts';
+import type { FunctionLoader } from '../functions/function-loader.ts';
+import type { GraphToolConfig, GraphAgentConfig } from '../workflows/types.ts';
+import type { AgentLoader } from '../agents/agent-loader.ts';
+import type { AgentExecutor } from '../agents/agent-executor.ts';
 /**
- * Centralized tool discovery for LangGraph workflows.
+ * Centralized tool discovery for ReAct workflows.
  * Discovers tools from all configured sources and applies filtering.
  */
 export declare class ToolDiscovery {
     private mcpClient;
-    private knowledgeStoreManager;
+    private knowledgeStores;
     private functionLoader;
     private agentLoader;
     private agentExecutor;
-    constructor(_toolRegistry: ToolRegistry, // Unused but kept for future use
-    mcpClient: MCPClientManager, knowledgeStoreManager: KnowledgeStoreManager, functionLoader: FunctionLoader, agentLoader: AgentLoader, agentExecutor: AgentExecutor);
-    /**
-     * Discovers all tools based on configuration.
-     */
+    constructor(_toolRegistry: ToolRegistry, mcpClient: MCPClientManager, knowledgeStores: KnowledgeStore, functionLoader: FunctionLoader, agentLoader: AgentLoader, agentExecutor: AgentExecutor);
     discoverAll(config: GraphToolConfig): Promise<StructuredTool[]>;
-    /**
-     * Discovers agent tools based on configuration.
-     */
     discoverAgents(config: GraphAgentConfig): Promise<StructuredTool[]>;
-    /**
-     * Filters tools based on mode and include/exclude lists.
-     */
     private filterTools;
-    /**
-     * Discovers MCP tools from all servers.
-     */
     private discoverMCP;
-    /**
-     * Discovers knowledge search tools for all knowledge stores.
-     */
     private discoverKnowledge;
-    /**
-     * Discovers custom function tools.
-     */
     private discoverFunction;
-    /**
-     * Discovers built-in tools (ask_user is always included).
-     */
     private discoverBuiltin;
 }
 //# sourceMappingURL=tool-discovery.d.ts.map

package/dist/lib/tools/tool-discovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-discovery.d.ts","sourceRoot":"","sources":["../../../lib/tools/tool-discovery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AACrF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAMjE;;;GAGG;AACH,qBAAa,aAAa;IAGtB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,qBAAqB;IAC7B,OAAO,CAAC,cAAc;IACtB,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,aAAa;gBALrB,aAAa,EAAE,YAAY,EAAE,iCAAiC;IACtD,SAAS,EAAE,gBAAgB,EAC3B,qBAAqB,EAAE,qBAAqB,EAC5C,cAAc,EAAE,cAAc,EAC9B,WAAW,EAAE,WAAW,EACxB,aAAa,EAAE,aAAa;IAGtC;;OAEG;IACG,WAAW,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAwBrE;;OAEG;IACG,cAAc,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IA2BzE;;OAEG;IACH,OAAO,CAAC,WAAW;IA2BnB;;OAEG;YACW,WAAW;IAsBzB;;OAEG;YACW,iBAAiB;IA6B/B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAYxB;;OAEG;IACH,OAAO,CAAC,eAAe;CASxB"}
+{"version":3,"file":"tool-discovery.d.ts","sourceRoot":"","sources":["../../../lib/tools/tool-discovery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAMjE;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,SAAS,CAAmB;IACpC,OAAO,CAAC,eAAe,CAAiB;IACxC,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,aAAa,CAAgB;gBAGnC,aAAa,EAAE,YAAY,EAC3B,SAAS,EAAE,gBAAgB,EAC3B,eAAe,EAAE,cAAc,EAC/B,cAAc,EAAE,cAAc,EAC9B,WAAW,EAAE,WAAW,EACxB,aAAa,EAAE,aAAa;IASxB,WAAW,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAuB/D,cAAc,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IA0BzE,OAAO,CAAC,WAAW;YA0BL,WAAW;YAsBX,iBAAiB;IA4B/B,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,eAAe;CAMxB"}