pilotswarm-sdk 0.2.0 → 0.2.2

package/dist/graph-tools.js

@@ -0,0 +1,554 @@
+import { defineTool } from "@github/copilot-sdk";
+// Roles that may run the privileged crawl work queue (`facts_read_uncrawled` /
+// `facts_mark_crawled`, which read facts across ALL scopes). The app assigns the
+// harvester role to its own agent; the facts-manager holds the queue too but is
+// dormant by default (07 §1.5). agent-tuner is read-only and never harvests.
+// NOTE: graph write/delete is NOT gated by this role — it is open to every
+// non-tuner session (the knowledge graph is shared).
+const TUNER_AGENT_ID = "agent-tuner";
+const FACTS_MANAGER_AGENT_ID = "facts-manager";
+const DEFAULT_GRAPH_NAMESPACE = "default";
+function namespaceKey(namespace) {
+    const clean = String(namespace ?? "").trim().replace(/\/+$/g, "");
+    return clean.length === 0 ? DEFAULT_GRAPH_NAMESPACE : clean;
+}
+function isDefaultNamespace(namespace) {
+    return namespaceKey(namespace).toLowerCase() === DEFAULT_GRAPH_NAMESPACE;
+}
+function normalizeNamespace(value) {
+    const clean = typeof value === "string" ? value.trim().replace(/\/+$/g, "") : "";
+    return clean.length > 0 && clean.toLowerCase() !== DEFAULT_GRAPH_NAMESPACE ? clean : null;
+}
+function boundedPreview(value, max = 80) {
+    const text = typeof value === "string" ? value.trim() : "";
+    if (!text)
+        return undefined;
+    return text.length > max ? text.slice(0, max) : text;
+}
+function isFactSeed(seed) {
+    return /^(shared|session):/.test(seed);
+}
+function isLikelyNodeKey(seed) {
+    return !isFactSeed(seed) && /^[a-z][a-z0-9_-]*:/i.test(seed);
+}
+/**
+ * Build the graph + crawl-queue tools (enhancedfactstore 07 P4). Registered
+ * ONLY when a `graphStore` is present. Reader tools (search/neighbourhood) go to
+ * every session; graph write/delete (`graph_upsert_*` / `graph_merge_nodes` /
+ * `graph_delete_*`) go to EVERY session EXCEPT the read-only agent-tuner, so any
+ * agent can incorporate into the SHARED graph; the crawl work queue
+ * (`facts_read_uncrawled` / `facts_mark_crawled`) stays harvester-role +
+ * facts-manager only (it reads facts across ALL scopes, bypassing per-session
+ * ACL); `graph_stats` (read-only) goes to facts-manager + agent-tuner.
+ * agent-tuner never gets a mutating tool.
+ */
+export function createGraphTools(opts) {
+    const { graphStore, factStore, agentIdentity, isHarvester, recordEvent } = opts;
+    const agentId = opts.agentId ?? agentIdentity ?? "harvester";
+    const isTuner = agentIdentity === TUNER_AGENT_ID;
+    const isFactsManager = agentIdentity === FACTS_MANAGER_AGENT_ID;
+    // ACL resolver. FAIL CLOSED: with no resolver, restrict reads to the
+    // caller's own session (readerSessionId only) — never unrestricted. The
+    // tuner is always unrestricted (privileged read-only investigator), matching
+    // the read_facts model.
+    const resolveAccess = async (sessionId) => {
+        if (isTuner)
+            return { unrestricted: true };
+        if (opts.resolveAccess)
+            return opts.resolveAccess(sessionId);
+        return { readerSessionId: sessionId ?? null, grantedSessionIds: [] };
+    };
+    // Harvester powers (the crawl work queue): the app-assigned harvester role OR
+    // the facts-manager (which holds them dormant). Never the tuner.
+    const canHarvest = !isTuner && (isHarvester === true || isFactsManager);
+    // Graph write/delete is open to EVERY session that can run tools, so any
+    // agent can incorporate into the SHARED knowledge graph. The only exception
+    // is the read-only agent-tuner, which never receives a mutating tool.
+    const canWriteGraph = !isTuner;
+    // Namespace registry tools are optional: older/third-party GraphStore
+    // providers may implement graph search but not the registry sidecar.
+    const canReadNamespaces = typeof graphStore.listGraphNamespaces === "function"
+        && typeof graphStore.getGraphNamespace === "function";
+    const canUpsertNamespace = typeof graphStore.upsertGraphNamespace === "function";
+    const canArchiveNamespace = typeof graphStore.archiveGraphNamespace === "function";
+    const canDeleteNamespace = typeof graphStore.deleteGraphNamespace === "function";
+    const tools = [];
+    // Record a graph search for tuner forensics — best-effort, never blocks.
+    const recordSearch = (sessionId, eventType, data) => {
+        if (!recordEvent || !sessionId)
+            return;
+        recordEvent(sessionId, eventType, { ...data, callerAgentId: agentId }).catch(() => { });
+    };
+    const recordNamespaceMutation = (sessionId, action, namespace, data = {}) => {
+        if (!recordEvent || !sessionId)
+            return;
+        recordEvent(sessionId, "graph.namespace_mutated", {
+            action,
+            namespace,
+            ...((data && typeof data === "object") ? data : {}),
+            at: new Date().toISOString(),
+        }).catch(() => { });
+    };
+    // ── Reader tools (every session) ─────────────────────────────────────────
+    if (canReadNamespaces) {
+        tools.push(defineTool("graph_list_namespaces", {
+            description: "List registered graph knowledge-base namespaces. Use this FIRST when a task may benefit from " +
+                "graph/domain enrichment: inspect each row's compact frontmatter (name + description) to decide " +
+                "which corpus is relevant before deeper graph traversal. Compact by default; set includeDetails " +
+                "only when frontmatter is insufficient.",
+            parameters: {
+                type: "object",
+                properties: {
+                    prefix: { type: "string", description: "Optional string-prefix filter over registered namespace keys." },
+                    includeArchived: { type: "boolean", description: "Include archived namespaces. Default false." },
+                    includeDetails: { type: "boolean", description: "Include source/schema/harvest details. Default false." },
+                },
+            },
+            handler: (a = {}) => graphStore.listGraphNamespaces({
+                prefix: a.prefix,
+                includeArchived: a.includeArchived === true,
+                includeDetails: a.includeDetails === true,
+            }),
+        }));
+        tools.push(defineTool("graph_get_namespace", {
+            description: "Get the full descriptor for one graph namespace after graph_list_namespaces frontmatter suggests it is relevant. " +
+                "Do not call this for every namespace by default; use it lazily when details are needed.",
+            parameters: {
+                type: "object",
+                properties: {
+                    namespace: { type: "string", description: "Registered graph namespace key, e.g. 'default' or 'corpus/acme'." },
+                },
+                required: ["namespace"],
+            },
+            handler: (a) => graphStore.getGraphNamespace(a.namespace),
+        }));
+    }
+    tools.push(defineTool("graph_search_nodes", {
+        description: "Find / expand knowledge-graph nodes. RESOLVE (does this entity exist? — pass kind + nameLike before " +
+            "creating anything) and PIVOT (seeds = fact scopeKeys from facts_search, expanded via EVIDENCED_BY; node " +
+            "keys expand directly; depth bounds the hops). Each hit carries its evidence fact scopeKeys — feed those " +
+            "into read_facts({ scopeKeys }) to get the underlying facts.",
+        parameters: {
+            type: "object",
+            properties: {
+                kind: { type: "string", description: "Free-text node kind filter (person, patch, file, …)." },
+                nameLike: { type: "string", description: "Lexical match on node name or any alias. The resolve key." },
+                namespace: {
+                    type: "string",
+                    description: "Optional graph namespace subtree. Matches this exact namespace and descendants, e.g. 'corpus/acme' includes 'corpus/acme/services'.",
+                },
+                seeds: { type: "array", items: { type: "string" }, description: "Fact scopeKeys OR node keys to anchor from." },
+                depth: { type: "number", description: "Hops to expand from seeds (1..5)." },
+                limit: { type: "number" },
+            },
+        },
+        handler: async (a, ctx) => {
+            const startedAt = Date.now();
+            const access = await resolveAccess(ctx?.sessionId);
+            const hits = await graphStore.searchGraphNodes({ kind: a.kind, nameLike: a.nameLike, namespace: a.namespace, seeds: a.seeds, depth: a.depth, limit: a.limit }, access);
+            const seeds = Array.isArray(a.seeds) ? a.seeds.filter((seed) => typeof seed === "string" && seed.trim().length > 0) : [];
+            const nodeKeySeeds = seeds.filter(isLikelyNodeKey);
+            recordSearch(ctx?.sessionId, "graph.searched", {
+                operation: "graph_search_nodes",
+                kind: a.kind ?? null,
+                nameLikePreview: boundedPreview(a.nameLike),
+                namespace: normalizeNamespace(a.namespace),
+                seedCount: seeds.length,
+                nodeKeySeedCount: nodeKeySeeds.length,
+                depth: a.depth ?? null,
+                limit: a.limit ?? 50,
+                resultCount: hits.length,
+                durationMs: Date.now() - startedAt,
+            });
+            for (const nodeKey of nodeKeySeeds) {
+                recordSearch(ctx?.sessionId, "graph.node_searched", {
+                    operation: "graph_search_nodes",
+                    nodeKey,
+                    namespace: normalizeNamespace(a.namespace),
+                    durationMs: Date.now() - startedAt,
+                });
+            }
+            return hits;
+        },
+    }));
+    tools.push(defineTool("graph_search_edges", {
+        description: "Find graph edges, two ways: anchor-and-explore (set fromKey and/or toKey) or exact-predicate " +
+            "(predicate / predicateKey — exact equality, no fuzzy match).",
+        parameters: {
+            type: "object",
+            properties: {
+                predicate: { type: "string", description: "EXACT predicate text." },
+                predicateKey: { type: "string", description: "EXACT normalized key (preferred)." },
+                fromKey: { type: "string" },
+                toKey: { type: "string" },
+                namespace: {
+                    type: "string",
+                    description: "Optional graph namespace subtree. An edge matches when the edge itself or either endpoint is in the namespace subtree.",
+                },
+                minConfidence: { type: "number" },
+                limit: { type: "number" },
+            },
+        },
+        handler: async (a, ctx) => {
+            const startedAt = Date.now();
+            const access = await resolveAccess(ctx?.sessionId);
+            const hits = await graphStore.searchGraphEdges(a, access);
+            const normalizedPredicateKey = a.predicateKey
+                ?? (typeof a.predicate === "string" && typeof graphStore.normalizePredicateKey === "function"
+                    ? graphStore.normalizePredicateKey(a.predicate)
+                    : null);
+            recordSearch(ctx?.sessionId, "graph.searched", {
+                operation: "graph_search_edges",
+                predicateKey: normalizedPredicateKey,
+                fromKey: a.fromKey ?? null,
+                toKey: a.toKey ?? null,
+                namespace: normalizeNamespace(a.namespace),
+                minConfidence: a.minConfidence ?? null,
+                limit: a.limit ?? 50,
+                resultCount: hits.length,
+                durationMs: Date.now() - startedAt,
+            });
+            return hits;
+        },
+    }));
+    tools.push(defineTool("graph_neighbourhood", {
+        description: "Bounded subgraph around a node — 'show me everything connected to X'.",
+        parameters: {
+            type: "object",
+            properties: {
+                nodeKey: { type: "string" },
+                depth: { type: "number", description: "Hops (clamped 1..5)." },
+                namespace: {
+                    type: "string",
+                    description: "Optional graph namespace subtree for returned nodes/edges. Matches exact namespace and descendants.",
+                },
+            },
+            required: ["nodeKey", "depth"],
+        },
+        handler: async (a, ctx) => {
+            const startedAt = Date.now();
+            const access = await resolveAccess(ctx?.sessionId);
+            const sub = await graphStore.graphNeighbourhood(a.nodeKey, a.depth, access, { namespace: a.namespace });
+            const durationMs = Date.now() - startedAt;
+            recordSearch(ctx?.sessionId, "graph.searched", {
+                operation: "graph_neighbourhood",
+                nodeKey: a.nodeKey,
+                namespace: normalizeNamespace(a.namespace),
+                depth: a.depth,
+                resultCount: sub.nodes.length + sub.edges.length,
+                nodeCount: sub.nodes.length,
+                edgeCount: sub.edges.length,
+                durationMs,
+            });
+            recordSearch(ctx?.sessionId, "graph.node_loaded", {
+                operation: "graph_neighbourhood",
+                nodeKey: a.nodeKey,
+                namespace: normalizeNamespace(a.namespace),
+                durationMs,
+            });
+            return sub;
+        },
+    }));
+    // ── graph_stats (read-only) — facts-manager + agent-tuner reporting ──────
+    if (isFactsManager || isTuner) {
+        tools.push(defineTool("graph_stats", {
+            description: "Read-only graph report: node + edge counts and crawl-queue status (how many facts remain " +
+                "uncrawled, reported up to a bounded probe). Use for status/health reporting — it never mutates the graph.",
+            parameters: {
+                type: "object",
+                properties: {
+                    namespace: {
+                        type: "string",
+                        description: "Optional graph namespace subtree for node/edge counts and crawl backlog. Matches exact namespace and descendants.",
+                    },
+                },
+            },
+            handler: async (a = {}) => {
+                // Prefer a provider aggregate (single cheap query). If the store
+                // does not implement graphStats(), fall back to a BOUNDED count —
+                // never a fan-out traversal (that would be a multi-minute DoS on a
+                // large graph).
+                //
+                // Crawl backlog: read a BOUNDED probe of the pending queue and
+                // report its size. readUncrawledFacts returns `count = rows
+                // returned` (capped by `limit`), so a limit:1 read would always
+                // report 0 or 1 — useless as a backlog signal. We probe up to
+                // BACKLOG_PROBE and flag `uncrawledFactsCapped` when the queue is
+                // at least that deep ("harvester is well behind"); the exact depth
+                // beyond the probe is not needed for a health report.
+                const BACKLOG_PROBE = 500;
+                const statsFn = graphStore.graphStats;
+                const uncrawled = await factStore.readUncrawledFacts({ namespace: a.namespace, limit: BACKLOG_PROBE });
+                const uncrawledFacts = uncrawled.count;
+                const uncrawledFactsCapped = uncrawled.count >= BACKLOG_PROBE;
+                if (typeof statsFn === "function") {
+                    const s = await statsFn.call(graphStore, { namespace: a.namespace });
+                    return {
+                        nodeCount: s.nodeCount,
+                        edgeCount: s.edgeCount,
+                        uncrawledFacts: s.uncrawledFacts ?? uncrawledFacts,
+                        uncrawledFactsCapped: s.uncrawledFacts != null ? undefined : uncrawledFactsCapped,
+                    };
+                }
+                // Bounded fallback: report whether the graph is non-empty + the
+                // crawl backlog, without an O(N) traversal. nodeCount is a lower
+                // bound (capped sample) so callers know it is approximate.
+                const SAMPLE = 1000;
+                const sample = await graphStore.searchGraphNodes({ namespace: a.namespace, limit: SAMPLE }, { unrestricted: true });
+                return {
+                    nodeCountAtLeast: sample.length,
+                    nodeCountExact: sample.length < SAMPLE ? sample.length : undefined,
+                    uncrawledFacts,
+                    uncrawledFactsCapped,
+                    note: typeof statsFn !== "function"
+                        ? "Provider has no graphStats(); nodeCount is a bounded sample. Edge count omitted to avoid fan-out."
+                        : undefined,
+                };
+            },
+        }));
+    }
+    // ── Crawl-queue tools (HARVESTER / facts-manager — privileged, all scopes) ─
+    // The crawl work queue reads facts across ALL scopes (bypassing per-session
+    // ACL), so it stays restricted to the harvester role and the (dormant)
+    // facts-manager — it is NOT opened up to every session.
+    if (canHarvest) {
+        tools.push(defineTool("facts_read_uncrawled", {
+            description: "PRIVILEGED harvester work queue: facts not yet incorporated into the graph (new or edited since the " +
+                "last crawl), across ALL scopes. Keep each fact's scopeKey and etag — both are the receipt facts_mark_crawled needs.",
+            parameters: {
+                type: "object",
+                properties: {
+                    namespace: { type: "string", description: "Restrict the queue to a literal key prefix." },
+                    limit: { type: "number", description: "Max facts this batch (default 20)." },
+                },
+            },
+            handler: (a) => factStore.readUncrawledFacts({ namespace: a.namespace, limit: a.limit }),
+        }));
+        tools.push(defineTool("facts_mark_crawled", {
+            description: "Stamp facts as incorporated so they leave the queue. Pass each fact's scopeKey and etag from facts_read_uncrawled. " +
+                "A skipped stamp means the fact was already marked, changed since your read, or no longer exists; re-read if needed.",
+            parameters: {
+                type: "object",
+                properties: {
+                    stamps: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                scopeKey: { type: "string" },
+                                etag: { type: "number" },
+                            },
+                            required: ["scopeKey", "etag"],
+                        },
+                    },
+                },
+                required: ["stamps"],
+            },
+            handler: (a) => factStore.markFactsCrawled(a.stamps),
+        }));
+        tools.push(defineTool("graph_remove_evidence", {
+            description: "Reconcile a soft-deleted fact with the graph: remove this fact scopeKey from node EVIDENCED_BY anchors " +
+                "and edge evidence arrays, deleting graph nodes/edges that become evidence-less. Call this for " +
+                "facts_read_uncrawled rows where deletedAt/deleted_at is set, then mark the fact crawled with its scopeKey and etag.",
+            parameters: {
+                type: "object",
+                properties: {
+                    scopeKey: { type: "string", description: "Deleted fact scopeKey from facts_read_uncrawled." },
+                    namespace: { type: "string", description: "Optional graph namespace guard, e.g. corpus/northwind." },
+                },
+                required: ["scopeKey"],
+            },
+            handler: (a) => graphStore.removeGraphEvidence(a.scopeKey, { namespace: a.namespace }),
+        }));
+    }
+    // ── Namespace registry writes. Upsert follows normal graph-write policy so
+    // ordinary graph-aware agents can register corpora they just incorporated.
+    // Archive remains harvester/facts-manager only; delete is facts-manager only.
+    if (canWriteGraph && canUpsertNamespace) {
+        tools.push(defineTool("graph_upsert_namespace", {
+            description: "Register or update a graph namespace/corpus descriptor. Available to graph-writing sessions. " +
+                "Use when a corpus starts, before first crawl, or when static source/schema/harvest details change. " +
+                "frontmatter must be compact name/description discovery text; do not write per-crawl stats or secrets.",
+            parameters: {
+                type: "object",
+                properties: {
+                    namespace: { type: "string", description: "Namespace key. Use 'default' only for the unscoped/NULL partition." },
+                    frontmatter: {
+                        type: "object",
+                        properties: {
+                            name: { type: "string", description: "Short display label. Defaults to namespace if omitted." },
+                            description: { type: "string", description: "Compact when-to-use-this-corpus hint. Required." },
+                        },
+                        required: ["description"],
+                    },
+                    source: { type: "string", description: "How source fact keys map/link to this graph namespace. No secrets." },
+                    nodeSchema: { type: "object", description: "Expected node kinds/properties/examples. Details only." },
+                    edgeSchema: { type: "object", description: "Expected predicates/direction/semantics. Details only." },
+                    harvestConfig: { type: "object", description: "Static, non-secret harvest shape/config handles. No per-crawl stats." },
+                    archived: { type: "boolean", description: "Set archived state. Upsert normally clears archived to false." },
+                },
+                required: ["namespace", "frontmatter"],
+            },
+            handler: async (a, ctx) => {
+                const result = await graphStore.upsertGraphNamespace({
+                    namespace: a.namespace,
+                    frontmatter: a.frontmatter,
+                    source: a.source,
+                    nodeSchema: a.nodeSchema,
+                    edgeSchema: a.edgeSchema,
+                    harvestConfig: a.harvestConfig,
+                    archived: a.archived,
+                });
+                recordNamespaceMutation(ctx?.sessionId, "upsert", result.namespace, { archived: result.archived });
+                return result;
+            },
+        }));
+    }
+    if (canHarvest && canArchiveNamespace) {
+        tools.push(defineTool("graph_archive_namespace", {
+            description: "Archive a graph namespace so it disappears from ordinary discovery. Non-destructive: graph data remains searchable when directly targeted. Harvester/facts-manager only. 'default' cannot be archived.",
+            parameters: {
+                type: "object",
+                properties: {
+                    namespace: { type: "string", description: "Registered namespace key to archive." },
+                },
+                required: ["namespace"],
+            },
+            handler: async (a, ctx) => {
+                if (isDefaultNamespace(a.namespace)) {
+                    throw new Error("graph_archive_namespace: the 'default' namespace cannot be archived");
+                }
+                const key = namespaceKey(a.namespace);
+                const archived = await graphStore.archiveGraphNamespace(key);
+                recordNamespaceMutation(ctx?.sessionId, "archive", key, { archived });
+                return { archived };
+            },
+        }));
+    }
+    if (isFactsManager && canDeleteNamespace) {
+        tools.push(defineTool("graph_delete_namespace", {
+            description: "DESTRUCTIVE facts-manager-only deletion. Deletes graph data for the exact namespace and then the registry row. " +
+                "Does not delete source facts and does not delete child namespaces. Use only on explicit user request. 'default' cannot be deleted.",
+            parameters: {
+                type: "object",
+                properties: {
+                    namespace: { type: "string", description: "Exact namespace key to delete. Child namespaces are not deleted." },
+                    confirmDestructiveDelete: { type: "boolean", description: "Must be true to confirm the destructive delete was explicitly requested by the user." },
+                    reason: { type: "string", description: "Short reason / user request summary for auditability." },
+                },
+                required: ["namespace", "confirmDestructiveDelete", "reason"],
+            },
+            handler: async (a, ctx) => {
+                const key = namespaceKey(a.namespace);
+                if (key.toLowerCase() === DEFAULT_GRAPH_NAMESPACE) {
+                    throw new Error("graph_delete_namespace: the 'default' namespace cannot be deleted");
+                }
+                if (a.confirmDestructiveDelete !== true) {
+                    throw new Error("graph_delete_namespace requires confirmDestructiveDelete=true");
+                }
+                if (!String(a.reason ?? "").trim()) {
+                    throw new Error("graph_delete_namespace requires a non-empty reason");
+                }
+                const result = await graphStore.deleteGraphNamespace(key);
+                recordNamespaceMutation(ctx?.sessionId, "delete", key, { reason: String(a.reason).trim(), result });
+                return result;
+            },
+        }));
+    }
+    // ── Graph write / delete — every session EXCEPT the read-only agent-tuner ─
+    // The shared knowledge graph is writable by any agent that can run tools;
+    // graph population is app-owned and is not a facts-manager-only job.
+    if (!canWriteGraph)
+        return tools;
+    tools.push(defineTool("graph_upsert_node", {
+        description: "Create a node, or merge into an existing one (idempotent; aliases + evidence union in). RESOLVE BEFORE " +
+            "YOU CREATE: graph_search_nodes by nameLike first. Pass the source fact's scopeKey as evidence — it is " +
+            "the provenance and what makes reinforcement dedup work. The graph is SHARED: anything you incorporate " +
+            "is visible to every reader.",
+        parameters: {
+            type: "object",
+            properties: {
+                kind: { type: "string", description: "Free text: person, patch, code_file, thread…" },
+                name: { type: "string", description: "Canonical surface form." },
+                namespace: {
+                    type: "string",
+                    description: "Optional graph namespace, aligned with fact key prefixes (e.g. 'corpus/acme' or 'corpus/acme/services').",
+                },
+                aliases: { type: "array", items: { type: "string" }, description: "Other observed surface forms." },
+                evidence: { type: "array", items: { type: "string" }, description: "Fact scopeKeys justifying this node." },
+            },
+            required: ["kind", "name"],
+        },
+        handler: (a) => graphStore.upsertGraphNode({ ...a, agentId }),
+    }));
+    tools.push(defineTool("graph_upsert_edge", {
+        description: "Assert a free-text relationship, or reinforce an existing one. Re-stating the same (fromKey, predicate, " +
+            "toKey) does not duplicate — it bumps observations and combines confidence (noisy-OR) ONLY when you bring " +
+            "new evidence; same-evidence replays are harmless no-ops. Pass RESOLVED nodeKeys, not raw names.",
+        parameters: {
+            type: "object",
+            properties: {
+                fromKey: { type: "string", description: "Source node key." },
+                toKey: { type: "string", description: "Target node key." },
+                predicate: { type: "string", description: "Free-text verb, e.g. 'revives argument from'." },
+                namespace: {
+                    type: "string",
+                    description: "Optional graph namespace for this edge assertion. Use the same namespace as the source evidence/domain when known.",
+                },
+                confidence: { type: "number", description: "0..1 for THIS observation (default 1.0)." },
+                evidence: { type: "array", items: { type: "string" }, description: "Fact scopeKeys justifying the edge." },
+            },
+            required: ["fromKey", "toKey", "predicate"],
+        },
+        handler: (a) => graphStore.upsertGraphEdge({ ...a, agentId }),
+    }));
+    tools.push(defineTool("graph_merge_nodes", {
+        description: "Entity resolution: fold a duplicate node into the survivor (union aliases, repoint edges, delete the " +
+            "duplicate). Use when you discover two nodes are the same entity after the fact.",
+        parameters: {
+            type: "object",
+            properties: {
+                fromKey: { type: "string", description: "Duplicate to remove." },
+                intoKey: { type: "string", description: "Survivor to keep." },
+                namespace: {
+                    type: "string",
+                    description: "Optional namespace guard. Merge only when both duplicate and survivor are in this namespace subtree.",
+                },
+                reason: { type: "string", description: "Why they're the same (audit)." },
+            },
+            required: ["fromKey", "intoKey", "reason"],
+        },
+        handler: async (a) => { await graphStore.mergeGraphNodes(a.fromKey, a.intoKey, a.reason, { namespace: a.namespace }); return { merged: true }; },
+    }));
+    tools.push(defineTool("graph_delete_node", {
+        description: "Remove a node and all its edges (DETACH DELETE). No cascade to facts.",
+        parameters: {
+            type: "object",
+            properties: {
+                nodeKey: { type: "string" },
+                namespace: { type: "string", description: "Optional namespace guard. Delete only when the node is in this namespace subtree." },
+            },
+            required: ["nodeKey"],
+        },
+        handler: async (a) => ({ deleted: await graphStore.deleteGraphNode(a.nodeKey, { namespace: a.namespace }) }),
+    }));
+    tools.push(defineTool("graph_delete_edge", {
+        description: "Remove one exact edge triple. Returns whether something matched.",
+        parameters: {
+            type: "object",
+            properties: {
+                fromKey: { type: "string" },
+                toKey: { type: "string" },
+                predicateKey: { type: "string" },
+                namespace: {
+                    type: "string",
+                    description: "Optional namespace guard. Delete only when the edge itself or either endpoint is in this namespace subtree.",
+                },
+            },
+            required: ["fromKey", "toKey", "predicateKey"],
+        },
+        handler: async (a) => ({ deleted: await graphStore.deleteGraphEdge(a.fromKey, a.toKey, a.predicateKey, { namespace: a.namespace }) }),
+    }));
+    return tools;
+}
+//# sourceMappingURL=graph-tools.js.map

package/dist/graph-tools.js.map

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

package/dist/horizon-env.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Convenience: build the optional EnhancedFactStore + knowledge-graph worker
+ * config from the canonical `HORIZON_*` environment variables.
+ *
+ * The `PilotSwarmWorker` intentionally does NOT read `process.env` itself — app
+ * entrypoints own env parsing and pass explicit config. This helper exists so the
+ * shipped CLI/portal embedded worker, the standalone K8s worker, and the examples
+ * all map the same env vars to the same worker fields, with no drift.
+ *
+ * Returns an EMPTY object when none of the `HORIZON_*` vars are set (the default —
+ * plain `PgFactStore`, no enhanced provider, no graph). The enhanced facts store and
+ * the knowledge graph are INDEPENDENT axes: setting only `HORIZON_GRAPH_DATABASE_URL`
+ * yields a graph over the base fact store (graph tools, no search). Spread the result
+ * into the worker options:
+ *
+ * ```ts
+ * const worker = new PilotSwarmWorker({
+ *     store: process.env.DATABASE_URL,
+ *     githubToken: process.env.GITHUB_TOKEN,
+ *     ...horizonConfigFromEnv(),
+ * });
+ * ```
+ *
+ * Env vars (all optional except the database URL):
+ *   HORIZON_DATABASE_URL        → enhancedFactsDatabaseUrl (enables the enhanced
+ *                                 provider; worker infers factsProvider="horizon")
+ *   HORIZON_FACTS_SCHEMA        → enhancedFactsSchema (default "horizon_facts")
+ *   HORIZON_GRAPH_DATABASE_URL  → graphDatabaseUrl (opt-in graph; unset ⇒ no graph)
+ *   HORIZON_GRAPH_SCHEMA        → graphSchema (default "horizon_graph")
+ *   HORIZON_GRAPH_REGISTRY_SCHEMA → graphRegistrySchema (default
+ *                                 `${graphSchema}_registry`; MUST differ from graphSchema)
+ *   HORIZON_NAMESPACE_CACHE_TTL_MS → graphNamespaceCacheTtlMs (default 60000; 0 disables cache)
+ *   HORIZON_EMBED_URL/MODEL/DIM → horizonEmbed (durable embedder; all three
+ *                                 required, else the embedder is omitted and
+ *                                 search runs lexical-only)
+ *   HORIZON_EMBED_API_KEY       → horizonEmbed.apiKey
+ *   HORIZON_EMBED_API_KEY_HEADER→ horizonEmbed.apiKeyHeader (default "api-key")
+ *   HORIZON_EMBED_BEARER        → horizonEmbed.bearer (sends "Bearer <key>");
+ *                                 inferred true when the header is "Authorization"
+ *
+ * @module
+ */
+import type { EmbeddingEndpointConfig } from "./facts-store.js";
+/** The subset of `PilotSwarmWorkerOptions` that the `HORIZON_*` env vars map to. */
+export interface HorizonEnvConfig {
+    enhancedFactsDatabaseUrl?: string;
+    enhancedFactsSchema?: string;
+    horizonEmbed?: EmbeddingEndpointConfig;
+    graphDatabaseUrl?: string;
+    graphSchema?: string;
+    graphRegistrySchema?: string;
+    graphNamespaceCacheTtlMs?: number;
+}
+/**
+ * Map the `HORIZON_*` environment variables to the worker's enhanced-facts /
+ * knowledge-graph config. Pure and side-effect-free; safe to call at startup.
+ *
+ * @param env - Environment source (defaults to `process.env`).
+ */
+export declare function horizonConfigFromEnv(env?: Record<string, string | undefined>): HorizonEnvConfig;
+//# sourceMappingURL=horizon-env.d.ts.map