@trustgraph/react-state 1.7.1 → 1.7.3

package/dist/index.esm.js

@@ -1,6 +1,6 @@
 import { useSocket, useConnectionState } from '@trustgraph/react-provider';
 export { ConnectionStateContext, SocketContext, SocketProvider } from '@trustgraph/react-provider';
-import { TG_EDGE, TG_REASONING, TG_EDGE_COUNT, TG_SELECTED_EDGE, TG_QUERY, PROV_STARTED_AT_TIME, TG_CONTENT, RDFS_LABEL as RDFS_LABEL$2, PROV_WAS_DERIVED_FROM, TG_REIFIES } from '@trustgraph/client';
+import { RDF_TYPE as RDF_TYPE$1, TG_EDGE, TG_REASONING, TG_EDGE_COUNT, TG_SELECTED_EDGE, TG_QUERY, PROV_STARTED_AT_TIME, TG_CONTENT, TG, PROV_WAS_DERIVED_FROM, RDFS_LABEL as RDFS_LABEL$2 } from '@trustgraph/client';
 export { PROV, PROV_ACTIVITY, PROV_ENTITY, PROV_STARTED_AT_TIME, PROV_WAS_DERIVED_FROM, PROV_WAS_GENERATED_BY, RDF, RDFS, RDF_TYPE, SCHEMA, SCHEMA_AUTHOR, SCHEMA_DESCRIPTION, SCHEMA_KEYWORDS, SCHEMA_NAME, SKOS, SKOS_DEFINITION, TG, TG_CONTENT, TG_DOCUMENT, TG_EDGE, TG_EDGE_COUNT, TG_QUERY, TG_REASONING, TG_REIFIES, TG_SELECTED_EDGE } from '@trustgraph/client';
 import { jsx } from 'react/jsx-runtime';
 import { createContext, useContext, useEffect, useState, useRef, useCallback, useMemo } from 'react';
@@ -1922,9 +1922,28 @@ const useExplainabilityStore = create()((set, get) => ({
 /**
  * Explainability utilities for parsing and structuring explain events
  */
+// Predicates not yet in client library
+const TG_ACTION = TG + "action";
+const TG_ARGUMENTS = TG + "arguments";
+const TG_SUBAGENT_GOAL = TG + "subagentGoal";
+const TG_CONCEPT = TG + "concept";
+const TG_ENTITY = TG + "entity";
+// RDF type URIs
+const TG_AGENT_QUESTION = TG + "AgentQuestion";
+const TG_ANALYSIS = TG + "Analysis";
+const TG_TOOL_USE = TG + "ToolUse";
+const TG_OBSERVATION = TG + "Observation";
+const TG_THOUGHT_TYPE = TG + "Thought";
+const TG_REFLECTION_TYPE = TG + "Reflection";
+const TG_CONCLUSION = TG + "Conclusion";
+const TG_FINDING = TG + "Finding";
+const TG_DECOMPOSITION = TG + "Decomposition";
+const TG_GROUNDING = TG + "Grounding";
+const TG_EXPLORATION_TYPE = TG + "Exploration";
+const TG_FOCUS_TYPE = TG + "Focus";
+// ── Helpers ─────────────────────────────────────────────────────────
 /**
- * Extract event type from explainId URI
- * e.g., "urn:trustgraph:question:abc123" → "question"
+ * Extract event type from explainId URI (graph-rag fallback)
  */
 function getEventType(explainId) {
     if (explainId.includes("question"))
@@ -1937,9 +1956,6 @@ function getEventType(explainId) {
         return "synthesis";
     return "unknown";
 }
-/**
- * Get term value from a Term object
- */
 function getTermValue$1(term) {
     if (!term)
         return "";
@@ -1948,7 +1964,6 @@ function getTermValue$1(term) {
     if (term.t === "l")
         return term.v || "";
     if (term.t === "t" && term.tr) {
-        // Quoted triple - return a serialized form
         const s = getTermValue$1(term.tr.s);
         const p = getTermValue$1(term.tr.p);
         const o = getTermValue$1(term.tr.o);
@@ -1956,9 +1971,6 @@ function getTermValue$1(term) {
     }
     return "";
 }
-/**
- * Extract quoted triple from a Term
- */
 function extractQuotedTriple(term) {
     if (term.t === "t" && term.tr) {
         return {
@@ -1969,48 +1981,102 @@ function extractQuotedTriple(term) {
     }
     return null;
 }
+// ── RDF type detection ──────────────────────────────────────────────
+/**
+ * Map RDF type URI → event type (first match wins).
+ * Agent-specific types only — shared types like tg:Synthesis and
+ * tg:Answer are excluded to avoid catching graph-rag events.
+ * Grounding, Exploration, Focus are included since they now carry
+ * embedded triples with their RDF type.
+ */
+const RDF_TYPE_CHECKS = [
+    [TG_AGENT_QUESTION, "agent-question"],
+    [TG_DECOMPOSITION, "decomposition"],
+    [TG_ANALYSIS, "analysis"],
+    [TG_TOOL_USE, "analysis"],
+    [TG_OBSERVATION, "reflection"],
+    [TG_THOUGHT_TYPE, "reflection"],
+    [TG_REFLECTION_TYPE, "reflection"],
+    [TG_CONCLUSION, "conclusion"],
+    [TG_FINDING, "conclusion"],
+    [TG_GROUNDING, "grounding"],
+    [TG_EXPLORATION_TYPE, "exploration"],
+    [TG_FOCUS_TYPE, "focus"],
+];
+/**
+ * Detect event type from RDF types in embedded triples.
+ */
+function getEventTypeFromTriples(triples) {
+    const types = new Set();
+    for (const t of triples) {
+        if (getTermValue$1(t.p) === RDF_TYPE$1) {
+            types.add(getTermValue$1(t.o));
+        }
+    }
+    for (const [typeUri, eventType] of RDF_TYPE_CHECKS) {
+        if (types.has(typeUri))
+            return eventType;
+    }
+    return "unknown";
+}
+/** Extract common fields (label, derivedFrom) from triples */
+function extractCommonFields(triples) {
+    const derivedFrom = [];
+    let label;
+    for (const t of triples) {
+        const p = getTermValue$1(t.p);
+        const o = getTermValue$1(t.o);
+        if (p === RDFS_LABEL$2 && o)
+            label = o;
+        if (p === PROV_WAS_DERIVED_FROM && o)
+            derivedFrom.push(o);
+    }
+    return { label, derivedFrom };
+}
 /**
- * Parse triples for a question event
+ * Extract inline edges from triples (tg:edge quoted triples).
+ * Returns SelectedEdge objects with URIs — labels resolved later.
  */
+function extractInlineEdges(triples) {
+    const edges = [];
+    for (const t of triples) {
+        if (getTermValue$1(t.p) === TG_EDGE && t.o.t === "t" && t.o.tr) {
+            const edge = extractQuotedTriple(t.o);
+            if (edge) {
+                edges.push({ edge });
+            }
+        }
+    }
+    return edges;
+}
+// ── Parsers ─────────────────────────────────────────────────────────
 function parseQuestionTriples(explainId, explainGraph, triples) {
-    const event = {
-        type: "question",
-        explainId,
-        explainGraph,
-    };
-    for (const triple of triples) {
-        const p = getTermValue$1(triple.p);
-        const o = getTermValue$1(triple.o);
-        if (p === TG_QUERY) {
+    const event = { type: "question", explainId, explainGraph };
+    for (const t of triples) {
+        const p = getTermValue$1(t.p);
+        const o = getTermValue$1(t.o);
+        if (p === TG_QUERY)
             event.query = o;
-        }
-        else if (p === PROV_STARTED_AT_TIME) {
+        else if (p === PROV_STARTED_AT_TIME)
             event.timestamp = o;
-        }
     }
     return event;
 }
-/**
- * Parse triples for an exploration event
- */
 function parseExplorationTriples(explainId, explainGraph, triples) {
-    const event = {
-        type: "exploration",
-        explainId,
-        explainGraph,
-    };
-    for (const triple of triples) {
-        const p = getTermValue$1(triple.p);
-        const o = getTermValue$1(triple.o);
-        if (p === TG_EDGE_COUNT) {
+    const event = { type: "exploration", explainId, explainGraph };
+    const entities = [];
+    for (const t of triples) {
+        const p = getTermValue$1(t.p);
+        const o = getTermValue$1(t.o);
+        if (p === TG_EDGE_COUNT)
             event.edgeCount = parseInt(o, 10);
-        }
+        if (p === TG_ENTITY && o)
+            entities.push(o);
     }
+    if (entities.length > 0)
+        event.entities = entities;
     return event;
 }
-/**
- * Parse triples for a focus event
- */
 function parseFocusTriples(explainId, explainGraph, triples) {
     const event = {
         type: "focus",
@@ -2018,54 +2084,135 @@ function parseFocusTriples(explainId, explainGraph, triples) {
         explainGraph,
         edgeSelectionUris: [],
     };
-    for (const triple of triples) {
-        const p = getTermValue$1(triple.p);
-        const o = getTermValue$1(triple.o);
+    // Collect edge selection URIs (old format)
+    for (const t of triples) {
+        const p = getTermValue$1(t.p);
+        const o = getTermValue$1(t.o);
         if (p === TG_SELECTED_EDGE && typeof o === "string") {
             event.edgeSelectionUris.push(o);
         }
     }
+    // Extract inline edges (new format: tg:edge with quoted triples)
+    const inlineEdges = extractInlineEdges(triples);
+    if (inlineEdges.length > 0) {
+        event.selectedEdges = inlineEdges;
+    }
     return event;
 }
-/**
- * Parse triples for a synthesis event
- */
 function parseSynthesisTriples(explainId, explainGraph, triples) {
-    const event = {
-        type: "synthesis",
-        explainId,
-        explainGraph,
-    };
-    for (const triple of triples) {
-        const p = getTermValue$1(triple.p);
-        const o = getTermValue$1(triple.o);
-        if (p === TG_CONTENT) {
+    const event = { type: "synthesis", explainId, explainGraph };
+    for (const t of triples) {
+        const p = getTermValue$1(t.p);
+        const o = getTermValue$1(t.o);
+        if (p === TG_CONTENT)
             event.contentLength = o.length;
-        }
     }
     return event;
 }
-/**
- * Parse triples for an edge selection entity
- */
 function parseEdgeSelectionTriples(triples) {
     let edge = null;
     let reasoning = null;
     for (const triple of triples) {
         const p = getTermValue$1(triple.p);
-        if (p === TG_EDGE) {
+        if (p === TG_EDGE)
             edge = extractQuotedTriple(triple.o);
-        }
-        else if (p === TG_REASONING) {
+        else if (p === TG_REASONING)
             reasoning = getTermValue$1(triple.o);
-        }
     }
     return { edge, reasoning };
 }
+function parseGroundingTriples(explainId, explainGraph, triples) {
+    const { label, derivedFrom } = extractCommonFields(triples);
+    const concepts = [];
+    for (const t of triples) {
+        const p = getTermValue$1(t.p);
+        const o = getTermValue$1(t.o);
+        if (p === TG_CONCEPT && o)
+            concepts.push(o);
+    }
+    return { type: "grounding", explainId, explainGraph, label, concepts, derivedFrom };
+}
+function parseAgentQuestionTriples(explainId, explainGraph, triples) {
+    const { label, derivedFrom } = extractCommonFields(triples);
+    const event = {
+        type: "agent-question", explainId, explainGraph, label, derivedFrom,
+    };
+    for (const t of triples) {
+        const p = getTermValue$1(t.p);
+        const o = getTermValue$1(t.o);
+        if (p === TG_QUERY)
+            event.query = o;
+        if (p === PROV_STARTED_AT_TIME)
+            event.timestamp = o;
+    }
+    return event;
+}
+function parseDecompositionTriples(explainId, explainGraph, triples) {
+    const { label, derivedFrom } = extractCommonFields(triples);
+    const goals = [];
+    for (const t of triples) {
+        const p = getTermValue$1(t.p);
+        const o = getTermValue$1(t.o);
+        if (p === TG_SUBAGENT_GOAL && o)
+            goals.push(o);
+    }
+    return { type: "decomposition", explainId, explainGraph, label, goals, derivedFrom };
+}
+function parseAnalysisTriples(explainId, explainGraph, triples) {
+    const { label, derivedFrom } = extractCommonFields(triples);
+    const event = {
+        type: "analysis", explainId, explainGraph, label, derivedFrom,
+    };
+    for (const t of triples) {
+        const p = getTermValue$1(t.p);
+        const o = getTermValue$1(t.o);
+        if (p === TG_ACTION)
+            event.action = o;
+        if (p === TG_ARGUMENTS)
+            event.arguments = o;
+    }
+    return event;
+}
+function parseReflectionTriples(explainId, explainGraph, triples) {
+    const { label, derivedFrom } = extractCommonFields(triples);
+    return { type: "reflection", explainId, explainGraph, label, derivedFrom };
+}
+function parseConclusionTriples(explainId, explainGraph, triples) {
+    const { label, derivedFrom } = extractCommonFields(triples);
+    return { type: "conclusion", explainId, explainGraph, label, derivedFrom };
+}
+// ── Unified parser ──────────────────────────────────────────────────
 /**
- * Parse triples based on event type
+ * Parse triples into a structured event.
+ * Tries RDF type detection first, then URI patterns as fallback.
+ * Returns null for events with no triples.
  */
 function parseExplainTriples(explainId, explainGraph, triples) {
+    if (triples.length === 0)
+        return null;
+    // Try RDF type detection first
+    const rdfEventType = getEventTypeFromTriples(triples);
+    if (rdfEventType !== "unknown") {
+        switch (rdfEventType) {
+            case "agent-question":
+                return parseAgentQuestionTriples(explainId, explainGraph, triples);
+            case "decomposition":
+                return parseDecompositionTriples(explainId, explainGraph, triples);
+            case "analysis":
+                return parseAnalysisTriples(explainId, explainGraph, triples);
+            case "reflection":
+                return parseReflectionTriples(explainId, explainGraph, triples);
+            case "conclusion":
+                return parseConclusionTriples(explainId, explainGraph, triples);
+            case "grounding":
+                return parseGroundingTriples(explainId, explainGraph, triples);
+            case "exploration":
+                return parseExplorationTriples(explainId, explainGraph, triples);
+            case "focus":
+                return parseFocusTriples(explainId, explainGraph, triples);
+        }
+    }
+    // Fall back to URI pattern detection (graph-rag events)
     const eventType = getEventType(explainId);
     switch (eventType) {
         case "question":
@@ -2083,8 +2230,10 @@ function parseExplainTriples(explainId, explainGraph, triples) {
 
 /**
  * Hook for tracing provenance chains in the knowledge graph
- * Follows prov:wasDerivedFrom relationships from any entity to its source documents
+ * Follows tg:contains to find subgraphs, then prov:wasDerivedFrom
+ * to trace chunk → page → document chains
  */
+const TG_CONTAINS = TG + "contains";
 /**
  * Hook for tracing provenance chains
  */
@@ -2181,13 +2330,13 @@ const useProvenance = (options = {}) => {
         }
     }, [maxDepth, resolveLabel, queryDerivedFrom]);
     /**
-     * Query for statements that reify an edge via tg:reifies
+     * Find subgraphs that contain an edge via tg:contains with a quoted triple
      */
-    const queryReifyingStatements = useCallback(async (s, p, o) => {
+    const queryContainingSubgraphs = useCallback(async (s, p, o) => {
         if (!isConnected())
             return [];
         try {
-            // Build the quoted triple term
+            // Build the quoted triple term for the edge
             const quotedTriple = {
                 t: "t",
                 tr: {
@@ -2200,7 +2349,7 @@ const useProvenance = (options = {}) => {
             };
             const triples = await socket
                 .flow(effectiveFlow)
-                .triplesQuery(undefined, { t: "i", i: TG_REIFIES }, quotedTriple, 10, collection);
+                .triplesQuery(undefined, { t: "i", i: TG_CONTAINS }, quotedTriple, 10, collection);
             return triples.map((t) => getTermValue$1(t.s));
         }
         catch {
@@ -2208,20 +2357,21 @@ const useProvenance = (options = {}) => {
         }
     }, [socket, effectiveFlow, collection, isConnected]);
     /**
-     * Trace provenance for an edge - finds reifying statements and traces each
+     * Trace provenance for an edge — find containing subgraph, then follow
+     * wasDerivedFrom chain: subgraph → chunk → page → document
      */
     const traceEdgeProvenance = useCallback(async (s, p, o) => {
         setIsTracing(true);
         try {
-            // Find statements that reify this edge
-            const stmtUris = await queryReifyingStatements(s, p, o);
-            // For each reifying statement, trace its provenance chain
+            // Find subgraphs containing this edge
+            const subgraphUris = await queryContainingSubgraphs(s, p, o);
             const chains = [];
-            for (const stmtUri of stmtUris) {
-                // Get the wasDerivedFrom source for this statement
-                const sourceUri = await queryDerivedFrom(stmtUri);
-                if (sourceUri) {
-                    const chain = await traceChain(sourceUri);
+            for (const subgraphUri of subgraphUris) {
+                // Follow wasDerivedFrom from the subgraph to the chunk
+                const chunkUri = await queryDerivedFrom(subgraphUri);
+                if (chunkUri) {
+                    // Trace the full chain from chunk upward
+                    const chain = await traceChain(chunkUri);
                     chains.push(chain);
                 }
             }
@@ -2230,7 +2380,7 @@ const useProvenance = (options = {}) => {
         finally {
             setIsTracing(false);
         }
-    }, [queryReifyingStatements, queryDerivedFrom, traceChain]);
+    }, [queryContainingSubgraphs, queryDerivedFrom, traceChain]);
     /**
      * Clear the label cache
      */
@@ -2252,24 +2402,26 @@ const useProvenance = (options = {}) => {
  *
  * Processing strategy:
  * - Events are processed immediately as they arrive
- * - Main event nodes (question, exploration, focus, synthesis) use
- *   stability-based retry: fetch until count > 0 AND stable
- * - Edge sub-objects use simple retry-until-non-empty (fast)
- * - All edge fetching + label resolution + provenance runs in parallel
+ * - Explain triples are embedded directly in events (no store lookups)
+ * - Edge labels are resolved via triple store queries
+ * - Edge label resolution + provenance runs in parallel
+ * - onUpdate callback fires on every session state change, allowing
+ *   callers to sync to external stores (e.g. Zustand)
  */
 /**
  * Hook for managing explainability during inference
  */
 const useExplainability = (options = {}) => {
     const { flow, collection = "default", traceProvenance = true, } = options;
-    const socket = useSocket();
-    const connectionState = useConnectionState();
     const sessionFlowId = useSessionStore((state) => state.flowId);
     const effectiveFlow = flow ?? sessionFlowId;
     const { traceEdgeProvenance, resolveLabel } = useProvenance({
         flow: effectiveFlow,
         collection,
     });
+    // Keep onUpdate in a ref so it doesn't break memoisation
+    const onUpdateRef = useRef(options.onUpdate);
+    onUpdateRef.current = options.onUpdate;
     const [events, setEvents] = useState([]);
     const [session, setSession] = useState({});
     const [isUnpacking, setIsUnpacking] = useState(false);
@@ -2280,98 +2432,19 @@ const useExplainability = (options = {}) => {
     const unpackQueueRef = useRef([]);
     const isProcessingRef = useRef(false);
     /**
-     * Check if connected
-     */
-    const isConnected = useCallback(() => {
-        return (connectionState?.status === "authenticated" ||
-            connectionState?.status === "unauthenticated");
-    }, [connectionState]);
-    /**
-     * Single triple query (no retry)
-     */
-    const fetchTriples = useCallback(async (explainId, explainGraph) => {
-        return socket
-            .flow(effectiveFlow)
-            .triplesQuery({ t: "i", i: explainId }, undefined, undefined, 100, collection, explainGraph);
-    }, [socket, effectiveFlow, collection]);
-    /**
-     * Stability-based retry for main event nodes.
-     * Retries until: count > 0 AND count matches previous fetch.
-     * Used for question, exploration, focus, synthesis nodes where the
-     * backend may write multiple triples incrementally.
-     */
-    const queryWithStabilityRetry = useCallback(async (explainId, explainGraph, timeoutMs = 5000) => {
-        if (!isConnected())
-            return [];
-        const retryDelay = 500;
-        const maxAttempts = Math.ceil(timeoutMs / retryDelay) + 1;
-        let prevCount = -1;
-        for (let attempt = 0; attempt < maxAttempts; attempt++) {
-            try {
-                const triples = await fetchTriples(explainId, explainGraph);
-                const count = triples.length;
-                if (count > 0 && count === prevCount) {
-                    return triples;
-                }
-                prevCount = count;
-                if (attempt < maxAttempts - 1) {
-                    await new Promise((r) => setTimeout(r, retryDelay));
-                }
-            }
-            catch (err) {
-                console.error("[explain] triple query failed:", explainId, err);
-                return [];
-            }
-        }
-        // Return last fetch if we got anything
-        if (prevCount > 0) {
-            try {
-                return await fetchTriples(explainId, explainGraph);
-            }
-            catch {
-                return [];
-            }
-        }
-        return [];
-    }, [fetchTriples, isConnected]);
-    /**
-     * Simple retry-until-non-empty for sub-objects (edge selections).
-     * These are small atomic writes — either fully there or not yet.
+     * Resolve a single edge: extract from embedded triples, resolve labels
      */
-    const queryWithSimpleRetry = useCallback(async (explainId, explainGraph, timeoutMs = 5000) => {
-        if (!isConnected())
-            return [];
-        const retryDelay = 300;
-        const maxAttempts = Math.ceil(timeoutMs / retryDelay) + 1;
-        for (let attempt = 0; attempt < maxAttempts; attempt++) {
-            try {
-                const triples = await fetchTriples(explainId, explainGraph);
-                if (triples.length > 0)
-                    return triples;
-                if (attempt < maxAttempts - 1) {
-                    await new Promise((r) => setTimeout(r, retryDelay));
-                }
-            }
-            catch (err) {
-                console.error("[explain] triple query failed:", explainId, err);
-                return [];
-            }
-        }
-        return [];
-    }, [fetchTriples, isConnected]);
-    /**
-     * Resolve a single edge: fetch triples, labels, and provenance in parallel
-     */
-    const resolveEdge = useCallback(async (edgeSelUri, explainGraph) => {
-        const triples = await queryWithSimpleRetry(edgeSelUri, explainGraph);
-        const { edge, reasoning } = parseEdgeSelectionTriples(triples);
+    const resolveEdge = useCallback(async (edgeSelUri, allTriples) => {
+        // Filter embedded triples for this edge selection URI
+        const edgeTriples = allTriples.filter((t) => getTermValue$1(t.s) === edgeSelUri);
+        const { edge, reasoning } = parseEdgeSelectionTriples(edgeTriples);
         if (!edge)
             return null;
         const selectedEdge = {
             edge,
             reasoning: reasoning || undefined,
         };
-        // Kick off labels and provenance in parallel
+        // Kick off label resolution and provenance in parallel
         const [labels, provenanceChains] = await Promise.all([
             // Labels — all 3 in parallel
             Promise.all([
@@ -2389,13 +2462,13 @@ const useExplainability = (options = {}) => {
             selectedEdge.sources = provenanceChains.map((c) => c.chain).flat();
         }
         return selectedEdge;
-    }, [queryWithSimpleRetry, resolveLabel, traceProvenance, traceEdgeProvenance]);
+    }, [resolveLabel, traceProvenance, traceEdgeProvenance]);
     /**
      * Unpack a focus event — resolve ALL edges in parallel
      */
-    const unpackFocusEvent = useCallback(async (focusEvent) => {
+    const unpackFocusEvent = useCallback(async (focusEvent, allTriples) => {
         // Fire off all edge resolutions concurrently
-        const edgePromises = focusEvent.edgeSelectionUris.map((uri) => resolveEdge(uri, focusEvent.explainGraph));
+        const edgePromises = focusEvent.edgeSelectionUris.map((uri) => resolveEdge(uri, allTriples));
         const results = await Promise.all(edgePromises);
         const selectedEdges = results.filter((e) => e !== null);
         return {
@@ -2403,50 +2476,88 @@ const useExplainability = (options = {}) => {
             selectedEdges,
         };
     }, [resolveEdge]);
-    /** Helper to update both state and ref together */
+    /** Helper to update state, ref, and notify caller together */
     const updateSession = useCallback((updater) => {
         sessionRef.current = updater(sessionRef.current);
         setSession(updater);
+        onUpdateRef.current?.(sessionRef.current);
     }, []);
+    const AGENT_STEP_TYPES = new Set([
+        "agent-question", "decomposition", "analysis", "reflection", "conclusion",
+        "grounding",
+    ]);
+    /**
+     * Resolve labels for inline edges (edges already extracted, just need labels)
+     */
+    const resolveEdgeLabels = useCallback(async (focusEvent) => {
+        if (!focusEvent.selectedEdges || focusEvent.selectedEdges.length === 0) {
+            return focusEvent;
+        }
+        const resolved = await Promise.all(focusEvent.selectedEdges.map(async (se) => {
+            const [sLabel, pLabel, oLabel] = await Promise.all([
+                resolveLabel(se.edge.s),
+                resolveLabel(se.edge.p),
+                resolveLabel(se.edge.o),
+            ]);
+            let sources;
+            if (traceProvenance) {
+                const chains = await traceEdgeProvenance(se.edge.s, se.edge.p, se.edge.o);
+                if (chains.length > 0) {
+                    sources = chains.map((c) => c.chain).flat();
+                }
+            }
+            return {
+                ...se,
+                labels: { s: sLabel, p: pLabel, o: oLabel },
+                sources,
+            };
+        }));
+        return { ...focusEvent, selectedEdges: resolved };
+    }, [resolveLabel, traceProvenance, traceEdgeProvenance]);
     /**
      * Process a single explain event
      */
     const processEvent = useCallback(async (event) => {
-        // Query triples for main event node (stability retry)
-        const triples = await queryWithStabilityRetry(event.explainId, event.explainGraph);
-        // Parse into structured data
+        const triples = event.explainTriples ?? [];
         const parsed = parseExplainTriples(event.explainId, event.explainGraph, triples);
         if (!parsed)
             return;
-        // Update session based on event type
-        updateSession((prev) => {
-            const next = { ...prev };
-            switch (parsed.type) {
-                case "question":
-                    next.question = parsed;
-                    break;
-                case "exploration":
-                    next.exploration = parsed;
-                    break;
-                case "focus":
-                    // Will be updated again after unpacking
-                    next.focus = parsed;
-                    break;
-                case "synthesis":
-                    next.synthesis = parsed;
-                    break;
-            }
-            return next;
-        });
-        // For focus events, unpack edges in parallel
-        if (parsed.type === "focus") {
-            const unpackedFocus = await unpackFocusEvent(parsed);
+        if (AGENT_STEP_TYPES.has(parsed.type)) {
+            // Agent step — append to timeline
             updateSession((prev) => ({
                 ...prev,
-                focus: unpackedFocus,
+                agentSteps: [...(prev.agentSteps || []), parsed],
             }));
         }
-    }, [queryWithStabilityRetry, unpackFocusEvent, updateSession]);
+        // Graph-RAG fields — populate regardless (agent produces these too)
+        switch (parsed.type) {
+            case "question":
+                updateSession((prev) => ({ ...prev, question: parsed }));
+                break;
+            case "exploration":
+                updateSession((prev) => ({ ...prev, exploration: parsed }));
+                break;
+            case "focus": {
+                updateSession((prev) => ({ ...prev, focus: parsed }));
+                // Resolve labels for inline edges, or unpack old-format edges
+                const focusEvent = parsed;
+                if (focusEvent.selectedEdges && focusEvent.selectedEdges.length > 0) {
+                    // New format: edges already extracted, resolve labels
+                    const resolved = await resolveEdgeLabels(focusEvent);
+                    updateSession((prev) => ({ ...prev, focus: resolved }));
+                }
+                else if (focusEvent.edgeSelectionUris.length > 0) {
+                    // Old format: unpack edge selection URIs
+                    const unpacked = await unpackFocusEvent(focusEvent, triples);
+                    updateSession((prev) => ({ ...prev, focus: unpacked }));
+                }
+                break;
+            }
+            case "synthesis":
+                updateSession((prev) => ({ ...prev, synthesis: parsed }));
+                break;
+        }
+    }, [unpackFocusEvent, resolveEdgeLabels, updateSession]);
     /**
      * Process the unpack queue
      */
@@ -2529,10 +2640,18 @@ const useChatSession = ({ flow } = {}) => {
     const { settings } = useSettings();
     // Explainability store for persisting sessions
     const addExplainSession = useExplainabilityStore((state) => state.addSession);
-    // Explainability hook for processing events (processes each event immediately)
+    // Track the current explain session ID so onUpdate can target the right store key
+    const explainSessionIdRef = useRef(undefined);
+    // Explainability hook — onUpdate syncs every state change to the Zustand store
     const explainability = useExplainability({
         flow: effectiveFlow,
         collection: settings.collection,
+        onUpdate: (session) => {
+            const id = explainSessionIdRef.current;
+            if (id) {
+                addExplainSession(id, session);
+            }
+        },
     });
     const explainabilityRef = useRef(explainability);
     explainabilityRef.current = explainability;
@@ -2551,13 +2670,9 @@ const useChatSession = ({ flow } = {}) => {
         addActivity(ragActivity);
         let accumulated = "";
         let messageAdded = false;
-        // Check if explainability is enabled
-        const explainabilityEnabled = settings.featureSwitches.explainability;
-        const sessionId = explainabilityEnabled ? generateSessionId() : undefined;
-        // Reset explainability state for new query
-        if (explainabilityEnabled) {
-            explainabilityRef.current.reset();
-        }
+        const sessionId = generateSessionId();
+        explainabilityRef.current.reset();
+        explainSessionIdRef.current = sessionId;
         try {
             // Execute Graph RAG with streaming and entity discovery
             const result = await inference.graphRag({
@@ -2573,41 +2688,20 @@ const useChatSession = ({ flow } = {}) => {
                     onChunk: (chunk, complete) => {
                         accumulated += chunk;
                         if (!messageAdded) {
-                            // Add empty message on first chunk (with session ID if enabled)
                             addMessage("ai", accumulated, undefined, sessionId);
                             messageAdded = true;
                         }
                         else {
-                            // Update existing message with accumulated text
                             updateLastMessage(accumulated);
                         }
                     },
-                    // Wire up explainability callback if feature is enabled
-                    ...(explainabilityEnabled && {
-                        onExplain: (event) => {
-                            console.log("[explain] event received:", event.explainId);
-                            explainabilityRef.current.addEvent(event);
-                        },
-                    }),
+                    onExplain: (event) => {
+                        console.log("[explain] event received:", event.explainId);
+                        explainabilityRef.current.addEvent(event);
+                    },
                 },
             });
             removeActivity(ragActivity);
-            // Store explainability session progressively — events are already being
-            // processed as they arrive. Wait for processing to finish, then snapshot.
-            if (explainabilityEnabled && sessionId) {
-                const waitAndStore = async () => {
-                    // Poll until processing completes (events are processed as they arrive)
-                    const maxWait = 30000;
-                    let elapsed = 0;
-                    while (explainabilityRef.current.isProcessingRef.current && elapsed < maxWait) {
-                        await new Promise((r) => setTimeout(r, 500));
-                        elapsed += 500;
-                    }
-                    const sess = explainabilityRef.current.sessionRef.current;
-                    addExplainSession(sessionId, sess);
-                };
-                waitAndStore();
-            }
             // Start embeddings activity
             addActivity(embActivity);
             // Get labels for each entity
@@ -2695,9 +2789,13 @@ const useChatSession = ({ flow } = {}) => {
         let observationMessageAdded = false;
         let answerAccumulated = "";
         let answerMessageAdded = false;
+        const sessionId = generateSessionId();
+        explainabilityRef.current.reset();
+        explainSessionIdRef.current = sessionId;
         try {
             const response = await inference.agent({
                 input,
+                collection: settings.collection,
                 callbacks: {
                     onThink: (thought, complete) => {
                         thinkingAccumulated += thought;
@@ -2730,13 +2828,17 @@ const useChatSession = ({ flow } = {}) => {
                     onAnswer: (answer, complete) => {
                         answerAccumulated += answer;
                         if (!answerMessageAdded) {
-                            addMessage("ai", answerAccumulated, "answer");
+                            addMessage("ai", answerAccumulated, "answer", sessionId);
                             answerMessageAdded = true;
                         }
                         else {
                             updateLastMessage(answerAccumulated);
                         }
                     },
+                    onExplain: (event) => {
+                        console.log("[explain] agent event received:", event.explainId);
+                        explainabilityRef.current.addEvent(event);
+                    },
                 },
             });
             removeActivity(activity);
@@ -5972,5 +6074,5 @@ const useDocumentsMetadata = (documentIds = []) => {
     };
 };
 
-export { DEFAULT_SETTINGS, NotificationProvider, RDFS_LABEL, SETTINGS_STORAGE_KEY, createDocId, extractQuotedTriple, fileToBase64, generateFlowBlueprintId, getEventType, getTermValue$1 as getExplainTermValue, getTermValue$3 as getTermValue, getTriples, parseEdgeSelectionTriples, parseExplainTriples, parseExplorationTriples, parseFocusTriples, parseQuestionTriples, parseSynthesisTriples, prepareMetadata, textToBase64, useActivity, useAgentTools, useChat, useChatSession, useChunkedDownload, useChunkedUpload, useCollections, useConversation, useDocumentEmbeddingsQuery, useDocumentMetadata, useDocumentsMetadata, useEmbeddings, useEntityDetail, useExplainability, useExplainabilityStore, useFlowBlueprints, useFlowParameters, useFlows, useGraphEmbeddings, useGraphSubgraph, useInference, useKnowledgeCores, useLLMModels, useLibrary, useLoadStateStore, useMcpTools, useNlpQuery, useNodeDetails, useNotification, useOntologies, useParameterValidation, useProcessing, useProgressStateStore, usePrompts, useProvenance, useRowEmbeddingsQuery, useRowsQuery, useSchemas, useSearchStateStore, useSessionStore, useSettings, useStructuredQuery, useTokenCosts, useTriples, useVectorSearch, useWorkbenchStateStore, vectorSearch };
+export { DEFAULT_SETTINGS, NotificationProvider, RDFS_LABEL, SETTINGS_STORAGE_KEY, createDocId, extractQuotedTriple, fileToBase64, generateFlowBlueprintId, getEventType, getEventTypeFromTriples, getTermValue$1 as getExplainTermValue, getTermValue$3 as getTermValue, getTriples, parseEdgeSelectionTriples, parseExplainTriples, parseExplorationTriples, parseFocusTriples, parseQuestionTriples, parseSynthesisTriples, prepareMetadata, textToBase64, useActivity, useAgentTools, useChat, useChatSession, useChunkedDownload, useChunkedUpload, useCollections, useConversation, useDocumentEmbeddingsQuery, useDocumentMetadata, useDocumentsMetadata, useEmbeddings, useEntityDetail, useExplainability, useExplainabilityStore, useFlowBlueprints, useFlowParameters, useFlows, useGraphEmbeddings, useGraphSubgraph, useInference, useKnowledgeCores, useLLMModels, useLibrary, useLoadStateStore, useMcpTools, useNlpQuery, useNodeDetails, useNotification, useOntologies, useParameterValidation, useProcessing, useProgressStateStore, usePrompts, useProvenance, useRowEmbeddingsQuery, useRowsQuery, useSchemas, useSearchStateStore, useSessionStore, useSettings, useStructuredQuery, useTokenCosts, useTriples, useVectorSearch, useWorkbenchStateStore, vectorSearch };
 //# sourceMappingURL=index.esm.js.map