@grafema/mcp 0.3.28 → 0.3.29

package/dist/handlers/enox-handlers.js

@@ -0,0 +1,869 @@
+/**
+ * Enox Handlers — RFDB-backed knowledge graph for Grafema MCP server.
+ *
+ * Replaces the file-based knowledge-handlers.ts with a proper graph database.
+ * All knowledge lives in a separate RFDB database called "knowledge",
+ * sharing the same server socket as the code graph.
+ */
+import { createHash } from 'crypto';
+import { join, dirname } from 'path';
+import { RFDBClient } from '@grafema/util';
+import { textResult, errorResult, log } from '../utils.js';
+import { getProjectPath, getSocketPathOverride } from '../state.js';
+import { loadConfig } from '../config.js';
+// ---------------------------------------------------------------------------
+// Key normalization
+// ---------------------------------------------------------------------------
+function normalizeKey(name) {
+    return name
+        .toLowerCase()
+        .replace(/\s*\(.*?\)\s*/g, '')
+        .replace(/[_\-]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+// ---------------------------------------------------------------------------
+// Fact ID computation
+// ---------------------------------------------------------------------------
+function computeFactId(from, rel, to) {
+    return createHash('sha256').update(`${from}|${rel}|${to}`).digest('hex');
+}
+// ---------------------------------------------------------------------------
+// Knowledge client singleton
+// ---------------------------------------------------------------------------
+let knowledgeClient = null;
+let knowledgeDbReady = false;
+/**
+ * Derive the socket path using the same logic as RFDBServerBackend.
+ * Priority: --socket CLI override > config rfdb_socket > auto-derive from dbPath.
+ */
+function deriveSocketPath() {
+    const projectPath = getProjectPath();
+    const config = loadConfig(projectPath);
+    const override = getSocketPathOverride();
+    if (override)
+        return override;
+    if (config.rfdb_socket)
+        return config.rfdb_socket;
+    const dbPath = join(projectPath, '.grafema', 'graph.rfdb');
+    const localSocket = join(dirname(dbPath), 'rfdb.sock');
+    const SUN_LEN = process.platform === 'darwin' ? 104 : 108;
+    if (Buffer.byteLength(localSocket) < SUN_LEN) {
+        return localSocket;
+    }
+    const hash = createHash('md5').update(dirname(dbPath)).digest('hex').slice(0, 12);
+    return join('/tmp', `grafema-${hash}.sock`);
+}
+/**
+ * Get or create the knowledge RFDB client.
+ * Connects to the same RFDB server socket as the code graph,
+ * but opens/creates a separate "knowledge" database.
+ */
+async function getKnowledgeClient() {
+    if (knowledgeClient?.connected && knowledgeDbReady) {
+        return knowledgeClient;
+    }
+    // Connection died or never existed — (re)create
+    if (knowledgeClient) {
+        try {
+            await knowledgeClient.close();
+        }
+        catch { /* ignore */ }
+    }
+    const socketPath = deriveSocketPath();
+    log(`[Enox] Connecting to RFDB at ${socketPath}`);
+    knowledgeClient = new RFDBClient(socketPath, 'enox-knowledge');
+    await knowledgeClient.connect();
+    await knowledgeClient.hello();
+    // Create or open the "knowledge" database
+    try {
+        await knowledgeClient.createDatabase('knowledge');
+        log('[Enox] Created "knowledge" database');
+    }
+    catch {
+        // Already exists — that's fine
+    }
+    await knowledgeClient.openDatabase('knowledge', 'rw');
+    knowledgeDbReady = true;
+    log('[Enox] Opened "knowledge" database');
+    return knowledgeClient;
+}
+// ---------------------------------------------------------------------------
+// Metadata helpers
+// ---------------------------------------------------------------------------
+function parseMeta(node) {
+    try {
+        return node.metadata ? JSON.parse(node.metadata) : {};
+    }
+    catch {
+        return {};
+    }
+}
+function parseEdgeMeta(edge) {
+    try {
+        return edge.metadata ? JSON.parse(edge.metadata) : {};
+    }
+    catch {
+        return {};
+    }
+}
+function nowISO() {
+    return new Date().toISOString();
+}
+// ---------------------------------------------------------------------------
+// Node/edge collection helpers
+// ---------------------------------------------------------------------------
+async function collectNodes(client, query) {
+    const nodes = [];
+    for await (const node of client.queryNodes(query)) {
+        nodes.push(node);
+    }
+    return nodes;
+}
+async function findNodeByName(client, name) {
+    const key = normalizeKey(name);
+    // Try exact match on normalized key
+    const exact = await collectNodes(client, { name: key });
+    if (exact.length > 0)
+        return exact[0];
+    // Try original name (might have dashes/underscores)
+    if (name !== key) {
+        const orig = await collectNodes(client, { name: name.toLowerCase() });
+        if (orig.length > 0)
+            return orig[0];
+    }
+    // Substring fallback — try each word
+    const words = key.split(' ').filter(w => w.length > 2);
+    for (const word of words) {
+        const matches = await collectNodes(client, { name: word, substringMatch: true });
+        if (matches.length > 0) {
+            // Pick the best match (shortest name = most specific)
+            matches.sort((a, b) => a.name.length - b.name.length);
+            return matches[0];
+        }
+    }
+    return null;
+}
+/**
+ * Ensure a node exists for the given entity name.
+ * Returns the node ID (normalized key).
+ */
+async function ensureEntity(client, name, nodeType = 'ENTITY', domain = 'general') {
+    const id = normalizeKey(name);
+    const existing = await client.getNode(id);
+    if (existing)
+        return id;
+    await client.addNodes([{
+            id,
+            nodeType: nodeType,
+            name: id,
+            file: domain,
+            exported: false,
+            metadata: JSON.stringify({ created_at: nowISO(), domain }),
+        }]);
+    return id;
+}
+export async function handleRemember(args) {
+    try {
+        const client = await getKnowledgeClient();
+        const domain = args.domain || 'general';
+        const relation = args.relation || 'HAS_FACT';
+        // Ensure subject node
+        const subjectId = await ensureEntity(client, args.subject, 'ENTITY', domain);
+        // Create fact node
+        const factId = createHash('sha256')
+            .update(`${subjectId}|${args.fact}|${Date.now()}`)
+            .digest('hex')
+            .slice(0, 16);
+        const factNodeId = `fact:${factId}`;
+        await client.addNodes([{
+                id: factNodeId,
+                nodeType: 'FACT',
+                name: args.fact.slice(0, 120),
+                file: domain,
+                exported: false,
+                metadata: JSON.stringify({
+                    content: args.fact,
+                    domain,
+                    created_at: nowISO(),
+                }),
+            }]);
+        // Create edge from subject to fact
+        await client.addEdges([{
+                src: subjectId,
+                dst: factNodeId,
+                edgeType: relation,
+                metadata: JSON.stringify({ created_at: nowISO() }),
+            }]);
+        await client.flush();
+        return textResult(`Remembered:\n` +
+            `  Subject: ${subjectId}\n` +
+            `  Fact: ${factNodeId}\n` +
+            `  Relation: ${relation}\n` +
+            `  Domain: ${domain}`);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return errorResult(`Failed to remember: ${msg}`);
+    }
+}
+export async function handleRecall(args) {
+    try {
+        const client = await getKnowledgeClient();
+        const depth = args.depth ?? 2;
+        // Find entities: try full query first, then individual words
+        let nodes = await collectNodes(client, {
+            name: args.query.toLowerCase(),
+            substringMatch: true,
+        });
+        if (nodes.length === 0) {
+            const words = args.query.toLowerCase().split(/\s+/).filter(w => w.length > 3);
+            const seen = new Set();
+            for (const word of words.sort((a, b) => b.length - a.length)) {
+                const matches = await collectNodes(client, { name: word, substringMatch: true });
+                for (const m of matches) {
+                    if (!seen.has(m.id) && m.nodeType !== 'NPM_SYMBOL' && m.nodeType !== 'NPM_PACKAGE') {
+                        seen.add(m.id);
+                        nodes.push(m);
+                    }
+                }
+                if (nodes.length >= 10)
+                    break;
+            }
+        }
+        if (nodes.length === 0) {
+            return textResult(`No knowledge found for "${args.query}".`);
+        }
+        const lines = [];
+        for (const node of nodes.slice(0, 10)) {
+            const meta = parseMeta(node);
+            lines.push(`## ${node.name} [${node.nodeType}]`);
+            if (meta.domain)
+                lines.push(`Domain: ${meta.domain}`);
+            if (meta.content)
+                lines.push(`Content: ${String(meta.content)}`);
+            if (meta.description)
+                lines.push(`Description: ${String(meta.description)}`);
+            lines.push('');
+            // Traverse neighborhood
+            if (depth > 0) {
+                const outgoing = await client.getOutgoingEdges(node.id);
+                const incoming = await client.getIncomingEdges(node.id);
+                if (outgoing.length > 0) {
+                    lines.push('### Outgoing:');
+                    for (const edge of outgoing.slice(0, 20)) {
+                        const target = await client.getNode(edge.dst);
+                        const eMeta = parseEdgeMeta(edge);
+                        const targetName = target?.name || edge.dst;
+                        lines.push(`  -[${edge.edgeType}]-> ${targetName}${eMeta.confidence ? ` (confidence: ${eMeta.confidence})` : ''}`);
+                    }
+                    lines.push('');
+                }
+                if (incoming.length > 0) {
+                    lines.push('### Incoming:');
+                    for (const edge of incoming.slice(0, 20)) {
+                        const source = await client.getNode(edge.src);
+                        const eMeta = parseEdgeMeta(edge);
+                        const sourceName = source?.name || edge.src;
+                        lines.push(`  ${sourceName} -[${edge.edgeType}]->  this${eMeta.confidence ? ` (confidence: ${eMeta.confidence})` : ''}`);
+                    }
+                    lines.push('');
+                }
+            }
+        }
+        return textResult(lines.join('\n'));
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return errorResult(`Failed to recall: ${msg}`);
+    }
+}
+export async function handleSemanticSearch(args) {
+    try {
+        const client = await getKnowledgeClient();
+        const limit = args.limit ?? 20;
+        // TODO: Wire to RFDB embedding engine when enabled.
+        // For now, fall back to substring search via queryNodes.
+        const querySpec = {
+            name: args.query.toLowerCase(),
+            substringMatch: true,
+        };
+        if (args.domain) {
+            querySpec.file = args.domain; // domain stored in file field
+        }
+        const nodes = await collectNodes(client, querySpec);
+        const results = nodes.slice(0, limit);
+        if (results.length === 0) {
+            return textResult(`No results for semantic search: "${args.query}".`);
+        }
+        const lines = [`Found ${results.length} result(s) for "${args.query}":\n`];
+        for (let i = 0; i < results.length; i++) {
+            const node = results[i];
+            const meta = parseMeta(node);
+            // Pseudo-similarity score based on match quality (placeholder until embeddings)
+            const similarity = (1.0 - (i * 0.05)).toFixed(2);
+            lines.push(`${i + 1}. [${similarity}] ${node.name} (${node.nodeType})`);
+            if (meta.domain)
+                lines.push(`   Domain: ${meta.domain}`);
+            if (meta.content)
+                lines.push(`   ${String(meta.content).slice(0, 200)}`);
+            lines.push('');
+        }
+        return textResult(lines.join('\n'));
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return errorResult(`Failed to search: ${msg}`);
+    }
+}
+export async function handleExploreEntity(args) {
+    try {
+        const client = await getKnowledgeClient();
+        const node = await findNodeByName(client, args.name);
+        if (!node) {
+            return errorResult(`Entity "${args.name}" not found. Use semantic_search to find similar entities.`);
+        }
+        const meta = parseMeta(node);
+        const lines = [
+            `# ${node.name}`,
+            `Type: ${node.nodeType}`,
+            `ID: ${node.id}`,
+        ];
+        if (meta.domain)
+            lines.push(`Domain: ${meta.domain}`);
+        if (meta.description)
+            lines.push(`Description: ${meta.description}`);
+        if (meta.content)
+            lines.push(`Content: ${String(meta.content).slice(0, 500)}`);
+        if (meta.created_at)
+            lines.push(`Created: ${meta.created_at}`);
+        lines.push('');
+        // Outgoing edges
+        const outgoing = await client.getOutgoingEdges(node.id);
+        if (outgoing.length > 0) {
+            lines.push(`## Outgoing (${outgoing.length}):`);
+            for (const edge of outgoing) {
+                const target = await client.getNode(edge.dst);
+                const eMeta = parseEdgeMeta(edge);
+                const targetName = target?.name || edge.dst;
+                let detail = `  -[${edge.edgeType}]-> ${targetName}`;
+                if (eMeta.confidence)
+                    detail += ` | confidence: ${eMeta.confidence}`;
+                if (eMeta.condition)
+                    detail += ` | condition: ${eMeta.condition}`;
+                if (eMeta.note)
+                    detail += ` | note: ${eMeta.note}`;
+                lines.push(detail);
+            }
+            lines.push('');
+        }
+        // Incoming edges
+        const incoming = await client.getIncomingEdges(node.id);
+        if (incoming.length > 0) {
+            lines.push(`## Incoming (${incoming.length}):`);
+            for (const edge of incoming) {
+                const source = await client.getNode(edge.src);
+                const eMeta = parseEdgeMeta(edge);
+                const sourceName = source?.name || edge.src;
+                let detail = `  ${sourceName} -[${edge.edgeType}]->`;
+                if (eMeta.confidence)
+                    detail += ` | confidence: ${eMeta.confidence}`;
+                if (eMeta.condition)
+                    detail += ` | condition: ${eMeta.condition}`;
+                if (eMeta.note)
+                    detail += ` | note: ${eMeta.note}`;
+                lines.push(detail);
+            }
+            lines.push('');
+        }
+        if (outgoing.length === 0 && incoming.length === 0) {
+            lines.push('No edges found (isolated node).');
+        }
+        return textResult(lines.join('\n'));
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return errorResult(`Failed to explore: ${msg}`);
+    }
+}
+export async function handleAddAssertion(args) {
+    try {
+        const client = await getKnowledgeClient();
+        const domain = args.domain || 'general';
+        // Ensure from and to nodes exist
+        const fromId = await ensureEntity(client, args.from, 'ENTITY', domain);
+        const toId = await ensureEntity(client, args.to, 'ENTITY', domain);
+        const factId = computeFactId(fromId, args.relation, toId);
+        const edgeMeta = {
+            fact_id: factId,
+            domain,
+            created_at: nowISO(),
+        };
+        if (args.context)
+            edgeMeta.context = args.context;
+        if (args.confidence !== undefined)
+            edgeMeta.confidence = args.confidence;
+        if (args.note)
+            edgeMeta.note = args.note;
+        if (args.condition)
+            edgeMeta.condition = args.condition;
+        await client.addEdges([{
+                src: fromId,
+                dst: toId,
+                edgeType: args.relation,
+                metadata: JSON.stringify(edgeMeta),
+            }]);
+        await client.flush();
+        return textResult(`Assertion added:\n` +
+            `  ${fromId} -[${args.relation}]-> ${toId}\n` +
+            `  fact_id: ${factId}\n` +
+            `  domain: ${domain}` +
+            (args.confidence !== undefined ? `\n  confidence: ${args.confidence}` : ''));
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return errorResult(`Failed to add assertion: ${msg}`);
+    }
+}
+export async function handleUpdateAssertion(args) {
+    try {
+        const client = await getKnowledgeClient();
+        // Scan all edges to find the one with matching fact_id.
+        // This is expensive but necessary because RFDB doesn't index edge metadata.
+        const allEdges = await client.getAllEdges();
+        let found = null;
+        for (const edge of allEdges) {
+            const meta = parseEdgeMeta(edge);
+            if (meta.fact_id === args.fact_id) {
+                found = edge;
+                break;
+            }
+        }
+        if (!found) {
+            return errorResult(`Assertion with fact_id "${args.fact_id}" not found.`);
+        }
+        // Delete old edge, create new one with updated metadata
+        const oldMeta = parseEdgeMeta(found);
+        const newMeta = { ...oldMeta, updated_at: nowISO() };
+        if (args.confidence !== undefined)
+            newMeta.confidence = args.confidence;
+        if (args.context !== undefined)
+            newMeta.context = args.context;
+        if (args.note !== undefined)
+            newMeta.note = args.note;
+        if (args.condition !== undefined)
+            newMeta.condition = args.condition;
+        if (args.domain !== undefined)
+            newMeta.domain = args.domain;
+        await client.deleteEdge(found.src, found.dst, found.edgeType);
+        await client.addEdges([{
+                src: found.src,
+                dst: found.dst,
+                edgeType: found.edgeType,
+                metadata: JSON.stringify(newMeta),
+            }]);
+        await client.flush();
+        return textResult(`Assertion updated:\n` +
+            `  fact_id: ${args.fact_id}\n` +
+            `  ${found.src} -[${found.edgeType}]-> ${found.dst}`);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return errorResult(`Failed to update assertion: ${msg}`);
+    }
+}
+export async function handleDeleteAssertion(args) {
+    try {
+        const client = await getKnowledgeClient();
+        const allEdges = await client.getAllEdges();
+        let found = null;
+        for (const edge of allEdges) {
+            const meta = parseEdgeMeta(edge);
+            if (meta.fact_id === args.fact_id) {
+                found = edge;
+                break;
+            }
+        }
+        if (!found) {
+            return errorResult(`Assertion with fact_id "${args.fact_id}" not found.`);
+        }
+        await client.deleteEdge(found.src, found.dst, found.edgeType);
+        await client.flush();
+        return textResult(`Assertion deleted:\n` +
+            `  fact_id: ${args.fact_id}\n` +
+            `  ${found.src} -[${found.edgeType}]-> ${found.dst}`);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return errorResult(`Failed to delete assertion: ${msg}`);
+    }
+}
+export async function handleEnoxQuery(args) {
+    try {
+        const client = await getKnowledgeClient();
+        const limit = args.limit ?? 50;
+        const querySpec = {};
+        if (args.type)
+            querySpec.nodeType = args.type;
+        if (args.name) {
+            querySpec.name = args.name.toLowerCase();
+            querySpec.substringMatch = true;
+        }
+        if (args.domain) {
+            querySpec.file = args.domain; // domain stored in file field
+        }
+        const nodes = await collectNodes(client, querySpec);
+        const results = nodes.slice(0, limit);
+        if (results.length === 0) {
+            return textResult('No matching nodes in knowledge graph.');
+        }
+        const lines = [`Found ${results.length} node(s):\n`];
+        for (const node of results) {
+            const meta = parseMeta(node);
+            lines.push(`- ${node.id} | ${node.nodeType} | ${node.name}`);
+            if (meta.domain)
+                lines.push(`  domain: ${meta.domain}`);
+            if (meta.created_at)
+                lines.push(`  created: ${meta.created_at}`);
+        }
+        return textResult(lines.join('\n'));
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return errorResult(`Failed to query knowledge graph: ${msg}`);
+    }
+}
+export async function handleEnoxTraverse(args) {
+    try {
+        const client = await getKnowledgeClient();
+        const direction = args.direction ?? 'outgoing';
+        const maxDepth = args.max_depth ?? 3;
+        // Resolve entity to node ID
+        const node = await findNodeByName(client, args.entity);
+        if (!node) {
+            return errorResult(`Entity "${args.entity}" not found.`);
+        }
+        const edgeFilter = args.edge_types?.length
+            ? args.edge_types
+            : undefined;
+        // BFS traversal
+        const visited = new Map(); // id -> depth
+        const queue = [{ id: node.id, depth: 0 }];
+        visited.set(node.id, 0);
+        while (queue.length > 0) {
+            const current = queue.shift();
+            if (current.depth >= maxDepth)
+                continue;
+            const edges = [];
+            if (direction === 'outgoing' || direction === 'both') {
+                const out = await client.getOutgoingEdges(current.id, edgeFilter ?? null);
+                edges.push(...out);
+            }
+            if (direction === 'incoming' || direction === 'both') {
+                const inc = await client.getIncomingEdges(current.id, edgeFilter ?? null);
+                edges.push(...inc);
+            }
+            for (const edge of edges) {
+                const neighborId = direction === 'incoming' ? edge.src : edge.dst;
+                // For 'both', pick the other end
+                const otherId = edge.src === current.id ? edge.dst : edge.src;
+                const nextId = direction === 'both' ? otherId : neighborId;
+                if (!visited.has(nextId)) {
+                    visited.set(nextId, current.depth + 1);
+                    queue.push({ id: nextId, depth: current.depth + 1 });
+                }
+            }
+        }
+        // Format results
+        const lines = [`Traversal from "${node.name}" (${direction}, max_depth=${maxDepth}):\n`];
+        lines.push(`Visited ${visited.size} node(s):\n`);
+        for (const [id, depth] of Array.from(visited.entries())) {
+            const n = await client.getNode(id);
+            const name = n?.name || id;
+            const type = n?.nodeType || 'UNKNOWN';
+            const indent = '  '.repeat(depth);
+            lines.push(`${indent}[depth=${depth}] ${name} (${type})`);
+        }
+        return textResult(lines.join('\n'));
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return errorResult(`Failed to traverse: ${msg}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// 10. handleEnoxStats
+// ---------------------------------------------------------------------------
+export async function handleEnoxStats() {
+    try {
+        const client = await getKnowledgeClient();
+        const [stats, nodesByType, edgesByType] = await Promise.all([
+            client.getStats(),
+            client.countNodesByType(),
+            client.countEdgesByType(),
+        ]);
+        const lines = [
+            '## Knowledge Graph Stats\n',
+            `Node count: ${stats.nodeCount}`,
+            `Edge count: ${stats.edgeCount}`,
+        ];
+        const nodeTypeEntries = Object.entries(nodesByType);
+        if (nodeTypeEntries.length > 0) {
+            lines.push('\n### Nodes by Type');
+            for (const [type, count] of nodeTypeEntries) {
+                lines.push(`  ${type}: ${count}`);
+            }
+        }
+        const edgeTypeEntries = Object.entries(edgesByType);
+        if (edgeTypeEntries.length > 0) {
+            lines.push('\n### Edges by Type');
+            for (const [type, count] of edgeTypeEntries) {
+                lines.push(`  ${type}: ${count}`);
+            }
+        }
+        return textResult(lines.join('\n'));
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return errorResult(`Failed to get graph stats: ${msg}`);
+    }
+}
+export async function handleRecentActivity(args) {
+    try {
+        const client = await getKnowledgeClient();
+        const limit = args.limit ?? 30;
+        // Get all nodes and sort by created_at from metadata
+        const allNodes = await client.getAllNodes();
+        // Parse created_at from metadata and sort descending
+        const withDates = allNodes
+            .map(node => {
+            const meta = parseMeta(node);
+            const createdAt = meta.created_at;
+            return { node, createdAt, meta };
+        })
+            .filter(item => item.createdAt !== undefined);
+        withDates.sort((a, b) => {
+            const da = new Date(a.createdAt).getTime();
+            const db = new Date(b.createdAt).getTime();
+            return db - da; // newest first
+        });
+        // Filter by since date if provided
+        let results = withDates;
+        if (args.since) {
+            const sinceTime = new Date(args.since).getTime();
+            results = withDates.filter(item => new Date(item.createdAt).getTime() >= sinceTime);
+        }
+        results = results.slice(0, limit);
+        if (results.length === 0) {
+            return textResult('No recent activity found.');
+        }
+        const lines = [`Recent activity (${results.length} entries):\n`];
+        for (const { node, createdAt, meta } of results) {
+            lines.push(`- [${createdAt}] ${node.nodeType}: ${node.name}`);
+            if (meta.domain)
+                lines.push(`  domain: ${meta.domain}`);
+        }
+        return textResult(lines.join('\n'));
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return errorResult(`Failed to get recent activity: ${msg}`);
+    }
+}
+export async function handleUpdateNode(args) {
+    try {
+        const client = await getKnowledgeClient();
+        const existing = await client.getNode(args.id);
+        if (!existing) {
+            return errorResult(`Node "${args.id}" not found.`);
+        }
+        const meta = parseMeta(existing);
+        meta.updated_at = nowISO();
+        if (args.description !== undefined)
+            meta.description = args.description;
+        if (args.domain !== undefined)
+            meta.domain = args.domain;
+        const updatedNode = {
+            id: existing.id,
+            nodeType: args.nodeType || existing.nodeType,
+            name: args.name ?? existing.name,
+            file: args.domain ?? existing.file,
+            exported: existing.exported,
+            metadata: JSON.stringify(meta),
+        };
+        // Re-add node (addNodes upserts in RFDB)
+        await client.addNodes([updatedNode]);
+        await client.flush();
+        return textResult(`Node updated:\n` +
+            `  ID: ${updatedNode.id}\n` +
+            `  Name: ${updatedNode.name}\n` +
+            `  Type: ${updatedNode.nodeType}\n` +
+            `  Domain: ${meta.domain || existing.file}`);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return errorResult(`Failed to update node: ${msg}`);
+    }
+}
+/**
+ * Lightweight ontological crawl: query the code graph for an entity,
+ * generate graph-derived facts, and record them in the knowledge DB.
+ *
+ * No LLM, no child processes — pure graph introspection.
+ */
+export async function handleCrawlEntity(args) {
+    try {
+        const knowledgeClient = await getKnowledgeClient();
+        const depth = args.depth ?? 3;
+        // 1. Recall: check knowledge DB for existing facts
+        const existingNodes = await collectNodes(knowledgeClient, {
+            name: args.entity.toLowerCase(),
+            substringMatch: true,
+        });
+        const existingFacts = [];
+        for (const node of existingNodes.slice(0, 10)) {
+            const meta = parseMeta(node);
+            if (meta.content)
+                existingFacts.push(String(meta.content));
+        }
+        // 2. Code graph scan: connect to default DB and find the entity
+        const socketPath = deriveSocketPath();
+        const codeClient = new RFDBClient(socketPath, 'crawl-entity');
+        await codeClient.connect();
+        await codeClient.hello();
+        const codeNodes = await collectNodes(codeClient, { name: args.entity, substringMatch: true });
+        if (codeNodes.length === 0) {
+            await codeClient.close();
+            return textResult(`No code entity found matching "${args.entity}".\n` +
+                (existingFacts.length > 0
+                    ? `\nExisting knowledge (${existingFacts.length} facts):\n${existingFacts.map(f => `  - ${f}`).join('\n')}`
+                    : 'No existing knowledge either.'));
+        }
+        // 3. Generate graph-derived facts for each matched node
+        const facts = [];
+        const processedNodes = codeNodes.slice(0, depth);
+        for (const node of processedNodes) {
+            const outgoing = await codeClient.getOutgoingEdges(node.id);
+            const incoming = await codeClient.getIncomingEdges(node.id);
+            facts.push(`${node.name} is a ${node.nodeType} in file ${node.file}`);
+            if (outgoing.length > 0 || incoming.length > 0) {
+                facts.push(`${node.name} has ${outgoing.length} outgoing and ${incoming.length} incoming edges`);
+            }
+            // Callers (incoming CALLS edges)
+            const callers = [];
+            for (const edge of incoming) {
+                if (edge.edgeType === 'CALLS' || edge.edgeType === 'INVOKES') {
+                    const src = await codeClient.getNode(edge.src);
+                    if (src)
+                        callers.push(src.name);
+                }
+            }
+            if (callers.length > 0) {
+                facts.push(`${node.name} is called by: ${callers.slice(0, 10).join(', ')}${callers.length > 10 ? ` (+${callers.length - 10} more)` : ''}`);
+            }
+            // Children (outgoing CONTAINS edges)
+            const children = [];
+            for (const edge of outgoing) {
+                if (edge.edgeType === 'CONTAINS' || edge.edgeType === 'HAS_MEMBER') {
+                    const dst = await codeClient.getNode(edge.dst);
+                    if (dst)
+                        children.push(`${dst.name} (${dst.nodeType})`);
+                }
+            }
+            if (children.length > 0) {
+                facts.push(`${node.name} contains ${children.length} members: ${children.slice(0, 10).join(', ')}${children.length > 10 ? ` (+${children.length - 10} more)` : ''}`);
+            }
+            // Callees (outgoing CALLS edges)
+            const callees = [];
+            for (const edge of outgoing) {
+                if (edge.edgeType === 'CALLS' || edge.edgeType === 'INVOKES') {
+                    const dst = await codeClient.getNode(edge.dst);
+                    if (dst)
+                        callees.push(dst.name);
+                }
+            }
+            if (callees.length > 0) {
+                facts.push(`${node.name} calls: ${callees.slice(0, 10).join(', ')}${callees.length > 10 ? ` (+${callees.length - 10} more)` : ''}`);
+            }
+        }
+        await codeClient.close();
+        // 4. Return facts as context (NOT recorded — graph-derived data
+        //    is already in code graph, recording duplicates it)
+        //    Use remember() or add_assertion() to record interpretations.
+        const lines = [
+            `## Crawl: ${args.entity}`,
+            `Code graph matches: ${codeNodes.length}`,
+            `Facts generated: ${facts.length}`,
+            `Existing knowledge: ${existingFacts.length} fact(s)`,
+            '',
+            '### Graph-derived facts:',
+            ...facts.map(f => `  - ${f}`),
+        ];
+        if (existingFacts.length > 0) {
+            lines.push('', '### Prior knowledge:');
+            for (const f of existingFacts.slice(0, 10)) {
+                lines.push(`  - ${f}`);
+            }
+        }
+        return textResult(lines.join('\n'));
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return errorResult(`Failed to crawl entity: ${msg}`);
+    }
+}
+export async function handleSaveDocument(args) {
+    try {
+        const client = await getKnowledgeClient();
+        const domain = args.domain || 'general';
+        const docId = `doc:${createHash('sha256')
+            .update(`${args.title}|${Date.now()}`)
+            .digest('hex')
+            .slice(0, 16)}`;
+        await client.addNodes([{
+                id: docId,
+                nodeType: 'DOCUMENT',
+                name: args.title,
+                file: domain,
+                exported: false,
+                metadata: JSON.stringify({
+                    content: args.content,
+                    domain,
+                    created_at: nowISO(),
+                }),
+            }]);
+        // Create REFERENCES edges if relates_to is provided
+        const relatedEdges = [];
+        if (args.relates_to?.length) {
+            for (const targetName of args.relates_to) {
+                const targetId = await ensureEntity(client, targetName, 'ENTITY', domain);
+                relatedEdges.push({
+                    src: docId,
+                    dst: targetId,
+                    edgeType: 'REFERENCES',
+                    metadata: JSON.stringify({ created_at: nowISO() }),
+                });
+            }
+            if (relatedEdges.length > 0) {
+                await client.addEdges(relatedEdges);
+            }
+        }
+        await client.flush();
+        const lines = [
+            `Document saved:`,
+            `  ID: ${docId}`,
+            `  Title: ${args.title}`,
+            `  Domain: ${domain}`,
+            `  Content: ${args.content.length} chars`,
+        ];
+        if (relatedEdges.length > 0) {
+            lines.push(`  References: ${relatedEdges.map(e => e.dst).join(', ')}`);
+        }
+        return textResult(lines.join('\n'));
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return errorResult(`Failed to save document: ${msg}`);
+    }
+}
+//# sourceMappingURL=enox-handlers.js.map