@grackle-ai/plugin-knowledge 0.99.0

package/README.md

@@ -0,0 +1,40 @@
+# @grackle-ai/plugin-knowledge
+
+Knowledge graph plugin for Grackle. Provides Neo4j-backed semantic search, knowledge node management, and entity sync via the `GracklePlugin` interface.
+
+## Overview
+
+Loading this plugin opts the server into knowledge graph functionality. When enabled (`GRACKLE_KNOWLEDGE_ENABLED=true`), the plugin:
+
+- Connects to Neo4j and initializes the schema
+- Creates a local embedding model for semantic search
+- Registers gRPC handlers for knowledge operations
+- Syncs task and finding entities to the knowledge graph
+- Exposes `knowledge_search`, `knowledge_get_node`, and `knowledge_create_node` MCP tools
+- Monitors Neo4j health via a reconciliation phase
+
+## Usage
+
+```ts
+import { createKnowledgePlugin } from "@grackle-ai/plugin-knowledge";
+
+const plugins = [createCorePlugin()];
+if (config.knowledgeEnabled) {
+  plugins.push(createKnowledgePlugin());
+}
+const loaded = await loadPlugins(plugins, ctx);
+```
+
+## gRPC Handlers
+
+- `searchKnowledge` — Semantic similarity search
+- `getKnowledgeNode` — Retrieve a node by ID
+- `expandKnowledgeNode` — Expand a node's neighbors
+- `listRecentKnowledgeNodes` — List recently created nodes
+- `createKnowledgeNode` — Create a native node with embedding
+
+## MCP Tools
+
+- `knowledge_search` — Natural language search
+- `knowledge_get_node` — Retrieve a node by ID
+- `knowledge_create_node` — Create a knowledge entry

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createKnowledgePlugin } from "./knowledge-plugin.js";
+export { getKnowledgeReadinessCheck } from "./knowledge-health.js";
+export type { KnowledgeReadinessCheck } from "./knowledge-health.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AACnE,YAAY,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createKnowledgePlugin } from "./knowledge-plugin.js";
+export { getKnowledgeReadinessCheck } from "./knowledge-health.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/knowledge-handlers.d.ts

@@ -0,0 +1,12 @@
+import { grackle } from "@grackle-ai/common";
+/** Search the knowledge graph using semantic similarity. */
+export declare function searchKnowledge(req: grackle.SearchKnowledgeRequest): Promise<grackle.SearchKnowledgeResponse>;
+/** Get a knowledge node by ID. */
+export declare function getKnowledgeNode(req: grackle.GetKnowledgeNodeRequest): Promise<grackle.GetKnowledgeNodeResponse>;
+/** Expand a knowledge node to retrieve its neighbors. */
+export declare function expandKnowledgeNode(req: grackle.ExpandKnowledgeNodeRequest): Promise<grackle.ExpandKnowledgeNodeResponse>;
+/** List recently created knowledge nodes. */
+export declare function listRecentKnowledgeNodes(req: grackle.ListRecentKnowledgeNodesRequest): Promise<grackle.ListRecentKnowledgeNodesResponse>;
+/** Create a new native knowledge node with embedding. */
+export declare function createKnowledgeNode(req: grackle.CreateKnowledgeNodeRequest): Promise<grackle.CreateKnowledgeNodeResponse>;
+//# sourceMappingURL=knowledge-handlers.d.ts.map

package/dist/knowledge-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-handlers.d.ts","sourceRoot":"","sources":["../src/knowledge-handlers.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AA+D7C,4DAA4D;AAC5D,wBAAsB,eAAe,CAAC,GAAG,EAAE,OAAO,CAAC,sBAAsB,GAAG,OAAO,CAAC,OAAO,CAAC,uBAAuB,CAAC,CAqBnH;AAED,kCAAkC;AAClC,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,OAAO,CAAC,uBAAuB,GAAG,OAAO,CAAC,OAAO,CAAC,wBAAwB,CAAC,CAgBtH;AAED,yDAAyD;AACzD,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,OAAO,CAAC,0BAA0B,GAAG,OAAO,CAAC,OAAO,CAAC,2BAA2B,CAAC,CAgB/H;AAED,6CAA6C;AAC7C,wBAAsB,wBAAwB,CAAC,GAAG,EAAE,OAAO,CAAC,+BAA+B,GAAG,OAAO,CAAC,OAAO,CAAC,gCAAgC,CAAC,CAgB9I;AAED,yDAAyD;AACzD,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,OAAO,CAAC,0BAA0B,GAAG,OAAO,CAAC,OAAO,CAAC,2BAA2B,CAAC,CAuB/H"}

package/dist/knowledge-handlers.js

@@ -0,0 +1,140 @@
+import { ConnectError, Code } from "@connectrpc/connect";
+import { create } from "@bufbuild/protobuf";
+import { grackle } from "@grackle-ai/common";
+import { knowledgeSearch, getNode as getKnowledgeNodeById, expandNode, createNativeNode, ingest, createPassThroughChunker, listRecentNodes, } from "@grackle-ai/knowledge";
+import { getKnowledgeEmbedder } from "./knowledge-init.js";
+import { isNeo4jHealthy } from "./knowledge-health.js";
+import { knowledgeNodeToProto, knowledgeEdgeToProto } from "./proto-converters.js";
+import { logger } from "./logger.js";
+/** Error message returned when Neo4j is unreachable. */
+const NEO4J_UNAVAILABLE_MESSAGE = "Knowledge graph temporarily unavailable — Neo4j unreachable";
+/**
+ * Guard that checks Neo4j health status.
+ *
+ * @throws ConnectError with Code.Unavailable if Neo4j is unreachable.
+ */
+function requireKnowledgeReady() {
+    if (!isNeo4jHealthy()) {
+        throw new ConnectError(NEO4J_UNAVAILABLE_MESSAGE, Code.Unavailable);
+    }
+}
+/**
+ * Guard that checks embedder availability and Neo4j health, returning the embedder.
+ *
+ * @throws ConnectError with Code.Unavailable if knowledge is not ready.
+ */
+function requireEmbedder() {
+    const embedder = getKnowledgeEmbedder();
+    if (!embedder) {
+        throw new ConnectError("Knowledge graph not available", Code.Unavailable);
+    }
+    requireKnowledgeReady();
+    return embedder;
+}
+/**
+ * Wrap non-ConnectError exceptions as Code.Unavailable.
+ *
+ * ConnectErrors (e.g. NotFound, InvalidArgument) are re-thrown as-is so
+ * the handler's own error semantics are preserved.
+ */
+function wrapNeo4jError(err) {
+    if (err instanceof ConnectError) {
+        throw err;
+    }
+    // Log the full error server-side for debugging; return a generic message
+    // to clients to avoid leaking internal details (hostnames, ports, etc.)
+    logger.error({ err }, "Knowledge graph operation failed");
+    throw new ConnectError(NEO4J_UNAVAILABLE_MESSAGE, Code.Unavailable);
+}
+/** Search the knowledge graph using semantic similarity. */
+export async function searchKnowledge(req) {
+    const embedder = requireEmbedder();
+    try {
+        const results = await knowledgeSearch(req.query, embedder, {
+            limit: req.limit || 10,
+            workspaceId: req.workspaceId || undefined,
+        });
+        return create(grackle.SearchKnowledgeResponseSchema, {
+            results: results.map((r) => create(grackle.SearchKnowledgeResultSchema, {
+                score: r.score,
+                node: knowledgeNodeToProto(r.node),
+                edges: r.edges.map(knowledgeEdgeToProto),
+            })),
+        });
+    }
+    catch (err) {
+        wrapNeo4jError(err);
+    }
+}
+/** Get a knowledge node by ID. */
+export async function getKnowledgeNode(req) {
+    requireKnowledgeReady();
+    try {
+        const result = await getKnowledgeNodeById(req.id);
+        if (!result) {
+            throw new ConnectError(`Knowledge node not found: ${req.id}`, Code.NotFound);
+        }
+        return create(grackle.GetKnowledgeNodeResponseSchema, {
+            node: knowledgeNodeToProto(result.node),
+            edges: result.edges.map(knowledgeEdgeToProto),
+        });
+    }
+    catch (err) {
+        wrapNeo4jError(err);
+    }
+}
+/** Expand a knowledge node to retrieve its neighbors. */
+export async function expandKnowledgeNode(req) {
+    requireKnowledgeReady();
+    try {
+        const result = await expandNode(req.id, {
+            depth: req.depth || 1,
+            edgeTypes: req.edgeTypes.length > 0 ? req.edgeTypes : undefined,
+        });
+        return create(grackle.ExpandKnowledgeNodeResponseSchema, {
+            nodes: result.nodes.map(knowledgeNodeToProto),
+            edges: result.edges.map(knowledgeEdgeToProto),
+        });
+    }
+    catch (err) {
+        wrapNeo4jError(err);
+    }
+}
+/** List recently created knowledge nodes. */
+export async function listRecentKnowledgeNodes(req) {
+    requireKnowledgeReady();
+    try {
+        const result = await listRecentNodes(req.limit || 20, req.workspaceId || undefined);
+        return create(grackle.ListRecentKnowledgeNodesResponseSchema, {
+            nodes: result.nodes.map(knowledgeNodeToProto),
+            edges: result.edges.map(knowledgeEdgeToProto),
+        });
+    }
+    catch (err) {
+        wrapNeo4jError(err);
+    }
+}
+/** Create a new native knowledge node with embedding. */
+export async function createKnowledgeNode(req) {
+    const embedder = requireEmbedder();
+    try {
+        const chunker = createPassThroughChunker();
+        const embedded = await ingest(req.content, chunker, embedder);
+        if (embedded.length === 0) {
+            throw new ConnectError("Content produced no embeddings", Code.InvalidArgument);
+        }
+        const id = await createNativeNode({
+            category: (req.category || "insight"),
+            title: req.title,
+            content: req.content,
+            tags: [...req.tags],
+            embedding: embedded[0].vector,
+            workspaceId: req.workspaceId || "",
+        });
+        return create(grackle.CreateKnowledgeNodeResponseSchema, { id });
+    }
+    catch (err) {
+        wrapNeo4jError(err);
+    }
+}
+//# sourceMappingURL=knowledge-handlers.js.map

package/dist/knowledge-handlers.js.map

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

package/dist/knowledge-health.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Knowledge graph health monitoring.
+ *
+ * Provides a {@link ReconciliationPhase} that periodically checks Neo4j
+ * connectivity and tracks state transitions. Exposes the current health
+ * state for use by gRPC handlers, the event sync circuit breaker, and
+ * the `/readyz` endpoint.
+ *
+ * @module
+ */
+import type { ReconciliationPhase } from "@grackle-ai/plugin-sdk";
+/** Dependencies injected into the knowledge health phase for testability. */
+export interface KnowledgeHealthPhaseDeps {
+    /** Check Neo4j connectivity. Returns `true` if reachable. */
+    healthCheck: () => Promise<boolean>;
+}
+/** Readiness check result compatible with the web-server ReadinessCheck type. */
+export interface KnowledgeReadinessCheck {
+    /** Whether Neo4j is reachable. */
+    ok: boolean;
+    /** Human-readable detail when unhealthy. */
+    message?: string;
+}
+/**
+ * Create a reconciliation phase that monitors Neo4j health.
+ *
+ * Calls `healthCheck()` on every tick and updates the module-level state.
+ * Logs only on state transitions (healthy to unhealthy or vice versa) to
+ * avoid log flooding during sustained outages.
+ */
+export declare function createKnowledgeHealthPhase(deps: KnowledgeHealthPhaseDeps): ReconciliationPhase;
+/**
+ * Whether Neo4j is currently considered healthy.
+ *
+ * Returns `true` before the first health check has completed (optimistic
+ * default — `initKnowledge()` verifies connectivity at startup).
+ */
+export declare function isNeo4jHealthy(): boolean;
+/**
+ * Get a readiness check result for the `/readyz` endpoint.
+ *
+ * Returns `{ ok: true }` when Neo4j is reachable (or before the first check
+ * completes, using the optimistic default), or `{ ok: false, message }` when
+ * Neo4j has been observed unreachable.
+ */
+export declare function getKnowledgeReadinessCheck(): KnowledgeReadinessCheck;
+/**
+ * Mark the knowledge subsystem as unhealthy immediately.
+ *
+ * Called when plugin initialization fails (e.g. Neo4j unreachable at startup)
+ * so that `/readyz` returns an accurate status instead of the optimistic default.
+ */
+export declare function markKnowledgeInitFailed(): void;
+/**
+ * Reset health state for testing.
+ *
+ * @internal
+ */
+export declare function resetKnowledgeHealthState(): void;
+//# sourceMappingURL=knowledge-health.d.ts.map

package/dist/knowledge-health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-health.d.ts","sourceRoot":"","sources":["../src/knowledge-health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAuBlE,6EAA6E;AAC7E,MAAM,WAAW,wBAAwB;IACvC,6DAA6D;IAC7D,WAAW,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACrC;AAED,iFAAiF;AACjF,MAAM,WAAW,uBAAuB;IACtC,kCAAkC;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,wBAAwB,GAC7B,mBAAmB,CAwBrB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,IAAI,uBAAuB,CAQpE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAG9C;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAGhD"}

package/dist/knowledge-health.js

@@ -0,0 +1,102 @@
+/**
+ * Knowledge graph health monitoring.
+ *
+ * Provides a {@link ReconciliationPhase} that periodically checks Neo4j
+ * connectivity and tracks state transitions. Exposes the current health
+ * state for use by gRPC handlers, the event sync circuit breaker, and
+ * the `/readyz` endpoint.
+ *
+ * @module
+ */
+import { logger } from "./logger.js";
+// ---------------------------------------------------------------------------
+// Module-level state
+// ---------------------------------------------------------------------------
+/**
+ * Whether Neo4j was healthy on the last check.
+ *
+ * Defaults to `true` (optimistic) because `initKnowledge()` verifies
+ * connectivity via `openNeo4j()` before subscribing to events. This
+ * avoids a startup gap where events would be dropped before the first
+ * reconciliation tick (~10s).
+ */
+let healthy = true;
+/** Whether at least one health check has completed. */
+let initialized = false;
+/**
+ * Create a reconciliation phase that monitors Neo4j health.
+ *
+ * Calls `healthCheck()` on every tick and updates the module-level state.
+ * Logs only on state transitions (healthy to unhealthy or vice versa) to
+ * avoid log flooding during sustained outages.
+ */
+export function createKnowledgeHealthPhase(deps) {
+    return {
+        name: "knowledge-health",
+        execute: async () => {
+            let result;
+            try {
+                result = await deps.healthCheck();
+            }
+            catch {
+                result = false;
+            }
+            const previous = healthy;
+            const wasInitialized = initialized;
+            healthy = result;
+            initialized = true;
+            // Log on state transitions and on first-check failures
+            if (previous && !result) {
+                logger.warn("Neo4j became unreachable — knowledge graph operations will be skipped");
+            }
+            else if (wasInitialized && !previous && result) {
+                logger.info("Neo4j recovered — knowledge graph operations resumed");
+            }
+        },
+    };
+}
+/**
+ * Whether Neo4j is currently considered healthy.
+ *
+ * Returns `true` before the first health check has completed (optimistic
+ * default — `initKnowledge()` verifies connectivity at startup).
+ */
+export function isNeo4jHealthy() {
+    return healthy;
+}
+/**
+ * Get a readiness check result for the `/readyz` endpoint.
+ *
+ * Returns `{ ok: true }` when Neo4j is reachable (or before the first check
+ * completes, using the optimistic default), or `{ ok: false, message }` when
+ * Neo4j has been observed unreachable.
+ */
+export function getKnowledgeReadinessCheck() {
+    if (!initialized) {
+        return { ok: true, message: "Neo4j health check has not run yet" };
+    }
+    if (!healthy) {
+        return { ok: false, message: "Neo4j is unreachable" };
+    }
+    return { ok: true };
+}
+/**
+ * Mark the knowledge subsystem as unhealthy immediately.
+ *
+ * Called when plugin initialization fails (e.g. Neo4j unreachable at startup)
+ * so that `/readyz` returns an accurate status instead of the optimistic default.
+ */
+export function markKnowledgeInitFailed() {
+    healthy = false;
+    initialized = true;
+}
+/**
+ * Reset health state for testing.
+ *
+ * @internal
+ */
+export function resetKnowledgeHealthState() {
+    healthy = true;
+    initialized = false;
+}
+//# sourceMappingURL=knowledge-health.js.map

package/dist/knowledge-health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-health.js","sourceRoot":"","sources":["../src/knowledge-health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,8EAA8E;AAC9E,qBAAqB;AACrB,8EAA8E;AAE9E;;;;;;;GAOG;AACH,IAAI,OAAO,GAAY,IAAI,CAAC;AAE5B,uDAAuD;AACvD,IAAI,WAAW,GAAY,KAAK,CAAC;AAoBjC;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CACxC,IAA8B;IAE9B,OAAO;QACL,IAAI,EAAE,kBAAkB;QACxB,OAAO,EAAE,KAAK,IAAmB,EAAE;YACjC,IAAI,MAAe,CAAC;YACpB,IAAI,CAAC;gBACH,MAAM,GAAG,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;YACpC,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,GAAG,KAAK,CAAC;YACjB,CAAC;YAED,MAAM,QAAQ,GAAY,OAAO,CAAC;YAClC,MAAM,cAAc,GAAY,WAAW,CAAC;YAC5C,OAAO,GAAG,MAAM,CAAC;YACjB,WAAW,GAAG,IAAI,CAAC;YAEnB,uDAAuD;YACvD,IAAI,QAAQ,IAAI,CAAC,MAAM,EAAE,CAAC;gBACxB,MAAM,CAAC,IAAI,CAAC,uEAAuE,CAAC,CAAC;YACvF,CAAC;iBAAM,IAAI,cAAc,IAAI,CAAC,QAAQ,IAAI,MAAM,EAAE,CAAC;gBACjD,MAAM,CAAC,IAAI,CAAC,sDAAsD,CAAC,CAAC;YACtE,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B;IACxC,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,oCAAoC,EAAE,CAAC;IACrE,CAAC;IACD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,sBAAsB,EAAE,CAAC;IACxD,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,GAAG,KAAK,CAAC;IAChB,WAAW,GAAG,IAAI,CAAC;AACrB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB;IACvC,OAAO,GAAG,IAAI,CAAC;IACf,WAAW,GAAG,KAAK,CAAC;AACtB,CAAC"}

package/dist/knowledge-init.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Knowledge graph subsystem initialization and lifecycle management.
+ *
+ * Wires Neo4j, the local embedder, and event-driven reference node sync
+ * into the Grackle server. Opt-in by loading the plugin.
+ *
+ * @module
+ */
+import { healthCheck as neo4jHealthCheck, type Embedder } from "@grackle-ai/knowledge";
+import type { PluginContext, Disposable } from "@grackle-ai/plugin-sdk";
+/** Re-export Neo4j health check for use by the reconciliation health phase. */
+export { neo4jHealthCheck };
+/** Get the knowledge embedder. Returns undefined if knowledge is not initialized. */
+export declare function getKnowledgeEmbedder(): Embedder | undefined;
+/**
+ * Initialize the knowledge graph subsystem.
+ *
+ * Opens Neo4j, initializes the schema, and creates the local embedder.
+ * If any step after Neo4j connection fails, cleans up the connection
+ * before re-throwing.
+ *
+ * @returns A cleanup function that closes Neo4j.
+ */
+export declare function initKnowledge(ctx: PluginContext): Promise<() => Promise<void>>;
+/**
+ * Create an entity sync subscriber that listens for task/finding events
+ * and keeps the knowledge graph in sync.
+ *
+ * @returns A Disposable that unsubscribes when disposed.
+ */
+export declare function createEntitySyncSubscriber(ctx: PluginContext): Disposable;
+//# sourceMappingURL=knowledge-init.d.ts.map

package/dist/knowledge-init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-init.d.ts","sourceRoot":"","sources":["../src/knowledge-init.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAIL,WAAW,IAAI,gBAAgB,EAS/B,KAAK,QAAQ,EACd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAgB,aAAa,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAKtF,+EAA+E;AAC/E,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAK5B,qFAAqF;AACrF,wBAAgB,oBAAoB,IAAI,QAAQ,GAAG,SAAS,CAE3D;AAsLD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CA0BpF;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,aAAa,GAAG,UAAU,CAazE"}

package/dist/knowledge-init.js

@@ -0,0 +1,225 @@
+/**
+ * Knowledge graph subsystem initialization and lifecycle management.
+ *
+ * Wires Neo4j, the local embedder, and event-driven reference node sync
+ * into the Grackle server. Opt-in by loading the plugin.
+ *
+ * @module
+ */
+import { openNeo4j, initSchema, closeNeo4j, healthCheck as neo4jHealthCheck, createLocalEmbedder, syncReferenceNode, deleteReferenceNodeBySource, findReferenceNodeBySource, createEdge, deriveTaskText, deriveFindingText, EDGE_TYPE, } from "@grackle-ai/knowledge";
+import { taskStore, findingStore, safeParseJsonArray } from "@grackle-ai/database";
+import { logger } from "./logger.js";
+import { isNeo4jHealthy } from "./knowledge-health.js";
+/** Re-export Neo4j health check for use by the reconciliation health phase. */
+export { neo4jHealthCheck };
+/** Module-level embedder, available after initKnowledge() completes. */
+let knowledgeEmbedder;
+/** Get the knowledge embedder. Returns undefined if knowledge is not initialized. */
+export function getKnowledgeEmbedder() {
+    return knowledgeEmbedder;
+}
+// ---------------------------------------------------------------------------
+// Event handler
+// ---------------------------------------------------------------------------
+/**
+ * Create an event bus subscriber that syncs reference nodes.
+ *
+ * Sync is fire-and-forget — errors are logged but never propagated.
+ */
+function createEntitySyncHandler(embedder) {
+    return (event) => {
+        // Fire-and-forget async — errors handled inside handleEvent
+        handleEvent(embedder, event).catch(() => { });
+    };
+}
+/**
+ * Ensure a task's reference node exists in the knowledge graph.
+ *
+ * If the node already exists, returns its ID. Otherwise syncs it from
+ * the task store and returns the new ID. Returns `undefined` if the
+ * task is not found in the store.
+ */
+async function ensureTaskReferenceNode(embedder, taskId) {
+    const existing = await findReferenceNodeBySource("task", taskId);
+    if (existing) {
+        return existing.id;
+    }
+    const task = taskStore.getTask(taskId);
+    if (!task) {
+        return undefined;
+    }
+    return syncReferenceNode(embedder, {
+        sourceType: "task",
+        sourceId: taskId,
+        label: task.title,
+        text: deriveTaskText(task.title, task.description),
+        workspaceId: task.workspaceId ?? "",
+    });
+}
+/**
+ * Create edges from a task reference node to its parent and dependencies.
+ *
+ * Best-effort — edge creation failures are logged but don't block sync.
+ */
+async function syncTaskEdges(embedder, taskNodeId, task) {
+    // Parent task → PART_OF edge
+    if (task.parentTaskId) {
+        try {
+            const parentNodeId = await ensureTaskReferenceNode(embedder, task.parentTaskId);
+            if (parentNodeId) {
+                await createEdge(taskNodeId, parentNodeId, EDGE_TYPE.PART_OF);
+            }
+        }
+        catch (err) {
+            logger.warn({ taskNodeId, parentTaskId: task.parentTaskId, err }, "Failed to create PART_OF edge");
+        }
+    }
+    // Dependencies → DEPENDS_ON edges
+    const deps = safeParseJsonArray(task.dependsOn);
+    for (const depId of deps) {
+        try {
+            const depNodeId = await ensureTaskReferenceNode(embedder, depId);
+            if (depNodeId) {
+                await createEdge(taskNodeId, depNodeId, EDGE_TYPE.DEPENDS_ON);
+            }
+        }
+        catch (err) {
+            logger.warn({ taskNodeId, depId, err }, "Failed to create DEPENDS_ON edge");
+        }
+    }
+}
+/** Handle a single entity event. */
+async function handleEvent(embedder, event) {
+    // Circuit breaker: skip sync when Neo4j is known-unreachable
+    if (!isNeo4jHealthy()) {
+        logger.debug({ eventType: event.type }, "Knowledge sync skipped — Neo4j unhealthy");
+        return;
+    }
+    try {
+        const payload = event.payload;
+        switch (event.type) {
+            case "task.created":
+            case "task.updated": {
+                const taskId = payload.taskId;
+                if (typeof taskId !== "string" || !taskId) {
+                    return;
+                }
+                const task = taskStore.getTask(taskId);
+                if (!task) {
+                    logger.warn({ taskId }, "Knowledge sync: task not found, skipping");
+                    return;
+                }
+                const taskNodeId = await syncReferenceNode(embedder, {
+                    sourceType: "task",
+                    sourceId: taskId,
+                    label: task.title,
+                    text: deriveTaskText(task.title, task.description),
+                    workspaceId: task.workspaceId ?? "",
+                });
+                await syncTaskEdges(embedder, taskNodeId, task);
+                break;
+            }
+            case "task.deleted": {
+                const taskId = payload.taskId;
+                if (typeof taskId !== "string" || !taskId) {
+                    return;
+                }
+                await deleteReferenceNodeBySource("task", taskId);
+                break;
+            }
+            case "finding.posted": {
+                const findingId = payload.findingId;
+                if (typeof findingId !== "string" || !findingId) {
+                    return;
+                }
+                const workspaceId = typeof payload.workspaceId === "string" ? payload.workspaceId : "";
+                const findings = findingStore.queryFindings(workspaceId);
+                const finding = findings.find((f) => f.id === findingId);
+                if (!finding) {
+                    logger.warn({ findingId }, "Knowledge sync: finding not found, skipping");
+                    return;
+                }
+                const tags = safeParseJsonArray(typeof finding.tags === "string" ? finding.tags : null);
+                const findingNodeId = await syncReferenceNode(embedder, {
+                    sourceType: "finding",
+                    sourceId: findingId,
+                    label: finding.title,
+                    text: deriveFindingText(finding.title, finding.content, tags),
+                    workspaceId,
+                });
+                // Link finding to its task
+                if (finding.taskId) {
+                    try {
+                        const taskNodeId = await ensureTaskReferenceNode(embedder, finding.taskId);
+                        if (taskNodeId) {
+                            await createEdge(findingNodeId, taskNodeId, EDGE_TYPE.DERIVED_FROM);
+                        }
+                    }
+                    catch (err) {
+                        logger.warn({ findingNodeId, taskId: finding.taskId, err }, "Failed to create DERIVED_FROM edge");
+                    }
+                }
+                break;
+            }
+            default:
+                // Ignore events we don't handle
+                break;
+        }
+    }
+    catch (err) {
+        logger.error({ err, eventType: event.type, eventId: event.id }, "Knowledge sync failed for entity event");
+    }
+}
+// ---------------------------------------------------------------------------
+// Lifecycle
+// ---------------------------------------------------------------------------
+/**
+ * Initialize the knowledge graph subsystem.
+ *
+ * Opens Neo4j, initializes the schema, and creates the local embedder.
+ * If any step after Neo4j connection fails, cleans up the connection
+ * before re-throwing.
+ *
+ * @returns A cleanup function that closes Neo4j.
+ */
+export async function initKnowledge(ctx) {
+    ctx.logger.info("Initializing knowledge graph subsystem");
+    const embedder = createLocalEmbedder();
+    await openNeo4j();
+    try {
+        await initSchema(embedder.dimensions);
+        knowledgeEmbedder = embedder;
+        ctx.logger.info("Knowledge graph subsystem ready");
+        return async () => {
+            ctx.logger.info("Shutting down knowledge graph subsystem");
+            knowledgeEmbedder = undefined;
+            await closeNeo4j();
+            ctx.logger.info("Knowledge graph subsystem stopped");
+        };
+    }
+    catch (err) {
+        // Clean up Neo4j if a later step fails
+        knowledgeEmbedder = undefined;
+        await closeNeo4j().catch(() => { });
+        throw err;
+    }
+}
+/**
+ * Create an entity sync subscriber that listens for task/finding events
+ * and keeps the knowledge graph in sync.
+ *
+ * @returns A Disposable that unsubscribes when disposed.
+ */
+export function createEntitySyncSubscriber(ctx) {
+    const embedder = knowledgeEmbedder;
+    if (!embedder) {
+        return { dispose: () => { } };
+    }
+    const unsubscribe = ctx.subscribe(createEntitySyncHandler(embedder));
+    return {
+        dispose: () => {
+            unsubscribe();
+        },
+    };
+}
+//# sourceMappingURL=knowledge-init.js.map