@iloveagents/foundry-web-graph 0.1.0

package/dist/assistant-ui/graph-client-tools.js

@@ -0,0 +1,261 @@
+import { clientToolRegistry } from "@iloveagents/foundry-agent";
+import { useToolPanelStore } from "@iloveagents/foundry-web-ui";
+import { coerceGraphPayload, hasOwn, mergeGraphPayloads, primaryLabel, resolveCaption, safeStringify, } from "../model.js";
+import { findWorkspaceNode, graphWorkspaceStore, isAmbiguous } from "../graph-workspace.js";
+import { GRAPH_PANEL_TYPE, graphPanelContent } from "./graph-panel-content.js";
+/**
+ * Client tools that let the agent work IN the open graph, not just hand one
+ * over.
+ *
+ * These execute in the browser, so they act on what the user is actually
+ * looking at — the live panel, its current selection, its current search.
+ * That is the difference between an agent that can produce a picture and one
+ * you can have a conversation with about the picture.
+ */
+/**
+ * A node as the AGENT should see it — captioned the way the canvas paints it.
+ *
+ * The payload\'s `legend.captionKey` is a supported part of the contract, and
+ * where a producer sets one, resolving without it names the node something
+ * that appears nowhere on screen. `findWorkspaceNode` already matches with the
+ * legend key, so without this the tool could find a node by the caption the
+ * user can see and then report a different name back.
+ */
+const describe = (node, legend) => {
+    const label = primaryLabel(node);
+    const captionKey = legend && hasOwn(legend, label) ? legend[label]?.captionKey : undefined;
+    return {
+        id: node.id,
+        labels: node.labels ?? [],
+        caption: resolveCaption(node, captionKey),
+        properties: node.properties ?? {},
+    };
+};
+// Not `JSON.stringify`: every one of these results carries node properties
+// straight out of the database, and a `bigint` there would throw inside the
+// tool rather than answering it.
+const ok = (value) => safeStringify(value);
+const fail = (message) => JSON.stringify({ error: message });
+function parseArgs(argsJson) {
+    try {
+        const parsed = JSON.parse(argsJson || "{}");
+        return typeof parsed === "object" && parsed !== null ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+const showGraph = {
+    name: "graph_show",
+    description: "Show a graph in the side panel. Updates the graph already open rather than opening a " +
+        "second one, and keeps the positions of nodes that were already on screen, so a new " +
+        "result reads as a change rather than a new picture. Set merge: true to ADD to what is " +
+        "on screen — always do that for an expansion or a write, so the new part appears beside " +
+        "what it connects to. Pass the payload a graph tool returned.",
+    parameters: {
+        type: "object",
+        properties: {
+            title: { type: "string", description: "Panel heading, e.g. the question this answers." },
+            graph: { type: "object", description: "A graph payload (kind: 'foundry.graph')." },
+            merge: {
+                type: "boolean",
+                description: "Add to the graph on screen instead of replacing it. Use for expansions and writes.",
+            },
+        },
+        required: ["graph"],
+    },
+    execute: async (argsJson) => {
+        const args = parseArgs(argsJson);
+        const payload = coerceGraphPayload(args.graph);
+        if (!payload)
+            return fail("That is not a graph payload (expected kind: 'foundry.graph').");
+        const workspace = graphWorkspaceStore.getState();
+        const merging = args.merge === true && workspace.payload !== null;
+        const next = merging ? mergeGraphPayloads(workspace.payload, payload) : payload;
+        const title = typeof args.title === "string" && args.title
+            ? args.title
+            : ((merging ? workspace.title : null) ?? "Graph");
+        // Update in place when a graph is already up. `openPanel` would do the
+        // same to the store, but going through `setContent` says what is meant:
+        // this is the same workspace changing, not a new one — which is also how
+        // it behaves on screen, since the renderer instance is reused and the
+        // layout reconciles by node id.
+        const panel = useToolPanelStore.getState();
+        const content = graphPanelContent(title, next);
+        if (panel.isOpen && panel.content?.type === GRAPH_PANEL_TYPE)
+            panel.setContent(content);
+        else
+            panel.openPanel(content);
+        return ok({
+            shown: true,
+            merged: merging,
+            nodes: next.nodes.length,
+            edges: next.edges.length,
+            added: merging ? next.nodes.length - workspace.payload.nodes.length : next.nodes.length,
+        });
+    },
+};
+const selectNode = {
+    name: "graph_select_node",
+    description: "Select a node in the open graph and centre the view on it, as if the user had clicked it. " +
+        "Accepts a node id or a caption such as a name or title. Returns the node's properties.",
+    parameters: {
+        type: "object",
+        properties: {
+            node: { type: "string", description: "Node id, or its caption (name/title)." },
+        },
+        required: ["node"],
+    },
+    execute: async (argsJson) => {
+        const args = parseArgs(argsJson);
+        const needle = typeof args.node === "string" ? args.node : "";
+        const { handle, payload: openPayload } = graphWorkspaceStore.getState();
+        if (!handle)
+            return fail("No graph is open. Call graph_show first.");
+        const legend = openPayload?.legend;
+        const captionOf = (node) => describe(node, legend).caption;
+        const match = findWorkspaceNode(needle);
+        if (!match)
+            return fail(`No node matching "${needle}" is in the open graph.`);
+        // Several nodes answer to that text. Picking one would be a confident
+        // wrong answer the user cannot see — duplicate captions are ordinary — so
+        // hand back the candidates WITH their ids, which is what the agent needs
+        // to ask a real question or select precisely.
+        if (isAmbiguous(match)) {
+            const options = match.ambiguous
+                .slice(0, 10)
+                .map((n) => `${describe(n, openPayload?.legend).caption} (id ${n.id})`)
+                .join(", ");
+            return fail(`"${needle}" matches ${match.ambiguous.length} nodes in the open graph: ${options}. ` +
+                `Select by id, or ask the user which one they mean.`);
+        }
+        const node = match;
+        // A node can be in the workspace payload and still not be RENDERED — the
+        // view caps a large graph to its connected core — and reporting a
+        // selection that did not happen sends the agent on to describe something
+        // the user cannot see.
+        if (!handle.select(node.id)) {
+            // Two different reasons a node is not drawn, and they need opposite
+            // advice. A legend filter is undone by turning the label back on;
+            // narrowing the query cannot bring back something the USER switched off,
+            // so telling the agent to narrow sends it somewhere that cannot work.
+            const hidden = handle.getViewState().hiddenLabels;
+            const label = primaryLabel(node);
+            if (hidden.includes(label)) {
+                return fail(`"${captionOf(node)}" is in this result but hidden: the "${label}" filter is ` +
+                    `switched off in the legend. Ask the user to turn it back on to see this node.`);
+            }
+            return fail(`"${captionOf(node)}" is in this result but not drawn — the view is showing the ` +
+                `most connected part of a graph too large for one screen. Narrow the query to bring ` +
+                `it in.`);
+        }
+        // Reveal, not centre: the user framed this graph, and a tool that
+        // re-centres on every mention throws that away. Move only if the node is
+        // off-screen or behind the details drawer.
+        handle.reveal(node.id);
+        return ok({ selected: describe(node, legend) });
+    },
+};
+const searchGraph = {
+    name: "graph_search",
+    description: "Highlight nodes in the open graph matching a term, dimming the rest. Searches captions, " +
+        "labels and property values. Pass an empty string to clear.",
+    parameters: {
+        type: "object",
+        properties: { query: { type: "string", description: "Text to highlight. Empty clears." } },
+        required: ["query"],
+    },
+    execute: async (argsJson) => {
+        const args = parseArgs(argsJson);
+        const query = typeof args.query === "string" ? args.query : "";
+        const { handle, payload } = graphWorkspaceStore.getState();
+        if (!handle || !payload)
+            return fail("No graph is open. Call graph_show first.");
+        handle.search(query);
+        return ok({ query, of: payload.nodes.length });
+    },
+};
+const getView = {
+    name: "graph_get_view",
+    description: "Read what the user is currently looking at: the open graph's title, its node and " +
+        "relationship counts, the types present, the selected node, and any active search. Call " +
+        "this before answering a question about 'this' node or 'the graph' on screen.",
+    parameters: { type: "object", properties: {} },
+    execute: async () => {
+        const { payload, title, handle } = graphWorkspaceStore.getState();
+        if (!payload || !handle)
+            return ok({ open: false });
+        // Read the VIEW, not the payload. Two different things were being lost by
+        // counting the payload: the render cap keeps only the connected core of a
+        // graph too big for one screen, and a label switched off in the legend
+        // takes its nodes and their relationships off the canvas. Either way the
+        // agent was describing a graph the user was not looking at — and could
+        // name a node that is not drawn.
+        const view = handle.getViewState();
+        // Counted into a `Map`, not `{}`. Labels and relationship types come from
+        // the payload, which is source-neutral and untrusted — a graph is free to
+        // have a label called `constructor` or `toString`, and reading those off
+        // an object literal finds an inherited function instead of "not counted
+        // yet". The count then either throws or lands in the result as something
+        // that is not a number.
+        const labels = new Map();
+        for (const node of view.nodes) {
+            const label = primaryLabel(node);
+            labels.set(label, (labels.get(label) ?? 0) + 1);
+        }
+        const types = new Map();
+        for (const edge of view.edges) {
+            const type = edge.type ?? "RELATED";
+            types.set(type, (types.get(type) ?? 0) + 1);
+        }
+        return ok({
+            open: true,
+            title,
+            nodeCount: view.nodes.length,
+            edgeCount: view.edges.length,
+            // The producer's own truncation OR the render cap. Reporting only the
+            // former said `false` while the UI was showing a loss notice.
+            truncated: (payload.truncated ?? false) || view.lossy,
+            labels: Object.fromEntries(labels),
+            relationshipTypes: Object.fromEntries(types),
+            // Named, so the agent can say "Person is hidden" rather than silently
+            // reporting a smaller graph than the query returned.
+            hiddenLabels: view.hiddenLabels,
+            hiddenNodeCount: payload.nodes.length - view.nodes.length,
+            selectedNode: view.selection ? describe(view.selection, payload.legend) : null,
+            // A selected node whose label the legend hides stays selected — the
+            // drawer is still open and its properties are still what the user is
+            // reading — but it is NOT in `nodeCount` or among the drawn nodes. Said
+            // plainly here, so the agent can answer "selected, though its label is
+            // currently hidden" instead of describing a node this same result says
+            // is not on screen.
+            selectedNodeHidden: view.selection ? !view.selectionDrawn : false,
+            // A relationship can be selected too, and the drawer shows it. Reporting
+            // only nodes said "nothing is selected" with an edge plainly selected.
+            selectedRelationship: view.selectedEdge
+                ? {
+                    id: view.selectedEdge.id,
+                    type: view.selectedEdge.type ?? "RELATED",
+                    source: view.selectedEdge.source,
+                    target: view.selectedEdge.target,
+                    properties: view.selectedEdge.properties ?? {},
+                }
+                : null,
+            search: view.query || null,
+        });
+    },
+};
+export const GRAPH_CLIENT_TOOLS = [showGraph, selectNode, searchGraph, getView];
+/**
+ * Register the graph client tools globally.
+ *
+ * Global rather than page-scoped: the panel is available from every route, so
+ * scoping them to one page would make the agent's ability to drive the graph
+ * depend on where the user happens to be standing. Re-registering by the same
+ * name replaces the entry, so this is safe to call from a `useInit`.
+ */
+export function registerGraphClientTools() {
+    const { registerGlobal } = clientToolRegistry.getState();
+    for (const tool of GRAPH_CLIENT_TOOLS)
+        registerGlobal(tool);
+}

package/dist/assistant-ui/graph-context.d.ts

@@ -0,0 +1,38 @@
+import { type GraphNode } from "../model.js";
+/**
+ * The context key the graph's selection occupies.
+ *
+ * One key means one item: selecting a different node replaces the previous
+ * one rather than stacking, and deselecting clears it. That is exactly what
+ * `setContextItem` is for — "context that tracks a piece of UI rather than a
+ * user's pin".
+ */
+export declare const GRAPH_SELECTION_CONTEXT_KEY = "graph.selection";
+/**
+ * Keep the graph's selected node in the chat's context.
+ *
+ * Without this, "tell me about this node" means the agent has to guess, or
+ * the user has to retype what they are already looking at. With it, whatever
+ * is selected is simply part of the conversation — and because it is keyed,
+ * selecting something else swaps it instead of piling up.
+ */
+export declare function syncGraphSelectionContext(node: GraphNode | null, sourcePage: string, captionKey?: string): void;
+/**
+ * Pin the selected node so it outlives the selection.
+ *
+ * Uses the shell's own pin vocabulary — same icons, same `text-primary` when
+ * active — because it is the same idea: this stays in the conversation until
+ * I remove it. `promoteContextItem` is what turns the keyed, selection-tracking
+ * item into a persistent pin (it drops the key), so pinning and then selecting
+ * elsewhere leaves the pin standing.
+ */
+export declare function GraphContextPinButton({ node, captionKey, }: {
+    node: GraphNode;
+    /**
+     * The payload's caption key for this node's label — the same one the canvas
+     * paints with. Unpinning rebuilds the tracking item, and without it the chip
+     * the user reads (and the `preview` the agent reads) reverts to a default
+     * caption that may appear nowhere on screen.
+     */
+    captionKey?: string;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/assistant-ui/graph-context.js

@@ -0,0 +1,113 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback } from "react";
+import { Pin, PinOff } from "lucide-react";
+import { cn } from "@iloveagents/foundry-web-primitives";
+import { useAppStore } from "@iloveagents/foundry-web-ui";
+import { jsonSafe, primaryLabel, resolveCaption } from "../model.js";
+/**
+ * The context key the graph's selection occupies.
+ *
+ * One key means one item: selecting a different node replaces the previous
+ * one rather than stacking, and deselecting clears it. That is exactly what
+ * `setContextItem` is for — "context that tracks a piece of UI rather than a
+ * user's pin".
+ */
+export const GRAPH_SELECTION_CONTEXT_KEY = "graph.selection";
+function contextItemFor(node, sourcePage, captionKey) {
+    // Captioned with the payload\'s own `legend.captionKey`, like the canvas,
+    // the expansion prompt and the client tools. Without it the chip the user
+    // reads — and the `preview` the agent reads — can name the selected node
+    // something that appears nowhere on screen.
+    const caption = resolveCaption(node, captionKey);
+    return {
+        key: GRAPH_SELECTION_CONTEXT_KEY,
+        type: "ref",
+        label: `${primaryLabel(node)} · ${caption}`,
+        payload: {
+            kind: "ref",
+            refType: "graph-node",
+            refId: node.id,
+            preview: caption,
+            // The agent gets the node's own data, so it can answer about "this
+            // node" without a round trip back through a tool.
+            //
+            // A JSON-SAFE copy, not the live object. This item is attached to every
+            // subsequent turn and serialized by the HTTP agent, so a single native
+            // `bigint` in `properties` — which is what the Neo4j driver returns
+            // under `useBigInt` — throws inside someone else's `JSON.stringify`.
+            // That does not lose a property, it stops the user sending any message
+            // at all for as long as the node stays selected. Copying also detaches
+            // it from a node object the simulation keeps mutating.
+            meta: jsonSafe({ labels: node.labels ?? [], properties: node.properties ?? {} }),
+        },
+        sourcePage,
+        // Ephemeral: it follows the selection. Pinning promotes it, which drops
+        // the key and makes it persist.
+        persistence: "ephemeral",
+    };
+}
+/**
+ * Keep the graph's selected node in the chat's context.
+ *
+ * Without this, "tell me about this node" means the agent has to guess, or
+ * the user has to retype what they are already looking at. With it, whatever
+ * is selected is simply part of the conversation — and because it is keyed,
+ * selecting something else swaps it instead of piling up.
+ */
+export function syncGraphSelectionContext(node, sourcePage, captionKey) {
+    const { setContextItem, contextItems } = useAppStore.getState();
+    if (!node) {
+        setContextItem(GRAPH_SELECTION_CONTEXT_KEY, null);
+        return;
+    }
+    // Already pinned? Then the node is in the conversation once, deliberately,
+    // and the tracking item would make it twice. `promoteContextItem` drops the
+    // key to pin, so nothing stops this from re-adding a keyed copy on the next
+    // republish — a route change or a merge — and the agent would be handed the
+    // same node under two entries whose properties can disagree after a merge.
+    if (contextItems.some((item) => isPinnedGraphNode(item, node.id))) {
+        setContextItem(GRAPH_SELECTION_CONTEXT_KEY, null);
+        return;
+    }
+    setContextItem(GRAPH_SELECTION_CONTEXT_KEY, contextItemFor(node, sourcePage, captionKey));
+}
+/** A user\'s pin of this exact node: promoted, so it carries no key. */
+function isPinnedGraphNode(item, nodeId) {
+    const payload = item.payload;
+    return (item.key === undefined &&
+        payload?.kind === "ref" &&
+        payload.refType === "graph-node" &&
+        payload.refId === nodeId);
+}
+/**
+ * Pin the selected node so it outlives the selection.
+ *
+ * Uses the shell's own pin vocabulary — same icons, same `text-primary` when
+ * active — because it is the same idea: this stays in the conversation until
+ * I remove it. `promoteContextItem` is what turns the keyed, selection-tracking
+ * item into a persistent pin (it drops the key), so pinning and then selecting
+ * elsewhere leaves the pin standing.
+ */
+export function GraphContextPinButton({ node, captionKey, }) {
+    const items = useAppStore((s) => s.contextItems);
+    const promoteContextItem = useAppStore((s) => s.promoteContextItem);
+    const removeContextItem = useAppStore((s) => s.removeContextItem);
+    const tracked = items.find((item) => item.key === GRAPH_SELECTION_CONTEXT_KEY);
+    const pinned = items.find((item) => isPinnedGraphNode(item, node.id));
+    const toggle = useCallback(() => {
+        if (pinned) {
+            removeContextItem(pinned.id);
+            // Pinning PROMOTED the keyed item, which is how it survives selecting
+            // elsewhere — so removing the pin removes the only copy, and the node
+            // the user is still looking at drops out of the conversation entirely
+            // until they select something else. Unpinning means "stop keeping this
+            // one", not "forget what I have selected", so the tracking item comes
+            // back.
+            syncGraphSelectionContext(node, pinned.sourcePage ?? "", captionKey);
+            return;
+        }
+        if (tracked)
+            promoteContextItem(tracked.id);
+    }, [node, captionKey, pinned, tracked, promoteContextItem, removeContextItem]);
+    return (_jsxs("button", { type: "button", onClick: toggle, title: pinned ? "Unpin from chat" : "Pin to chat", "aria-pressed": !!pinned, className: cn("border-border hover:bg-muted focus-visible:ring-ring inline-flex items-center gap-1.5 rounded-lg border px-2.5 py-1.5 text-xs transition-colors focus-visible:outline-none focus-visible:ring-1", pinned ? "text-primary" : "text-muted-foreground"), children: [pinned ? _jsx(PinOff, { className: "size-3.5" }) : _jsx(Pin, { className: "size-3.5" }), pinned ? "Pinned" : "Pin"] }));
+}

package/dist/assistant-ui/graph-panel-content.d.ts

@@ -0,0 +1,45 @@
+import { type GraphPayload } from "../model.js";
+/** The `ToolPanelContent.type` a graph panel matches on. */
+export declare const GRAPH_PANEL_TYPE = "graph";
+/**
+ * ANY panel content, for the renderer that has to decide whether it is a graph.
+ *
+ * Declared structurally so this module does not import the store's type — it
+ * only ever reads these fields, and a structural shape keeps the dependency
+ * one-way. `type` is deliberately wide here: the whole job of
+ * `graphPanelPayload` is to be handed something that might not be a graph.
+ */
+export interface GraphPanelContentLike {
+    title: string;
+    content: string;
+    type: string;
+    data?: unknown;
+}
+/**
+ * Content this module BUILT, which is a graph by construction.
+ *
+ * Separate from the wide shape above so `type` can be the literal, which is
+ * what makes it assignable to the host's `ToolPanelContent` union. One type
+ * serving both directions forced an `as never` at every `openPanel` and
+ * `setContent` call — casts that switch checking off exactly where a shape
+ * mismatch with the host would otherwise be caught.
+ */
+export interface GraphPanelContent extends GraphPanelContentLike {
+    type: typeof GRAPH_PANEL_TYPE;
+}
+/**
+ * Build the panel payload for a graph.
+ *
+ * `data` carries the parsed payload so the renderer never re-parses, and
+ * `content` carries the serialization so the panel header's Copy button and the
+ * built-in text fallback still do something useful if no renderer matched.
+ */
+export declare function graphPanelContent(title: string, payload: GraphPayload): GraphPanelContent;
+/**
+ * Recover the payload from panel content.
+ *
+ * Prefers `data`; falls back to parsing `content` so a panel opened by a
+ * generic client tool (`ui_open_panel`, which only knows how to set strings)
+ * still renders as a graph.
+ */
+export declare function graphPanelPayload(content: GraphPanelContentLike): GraphPayload | null;

package/dist/assistant-ui/graph-panel-content.js

@@ -0,0 +1,28 @@
+import { coerceGraphPayload, safeStringify } from "../model.js";
+/** The `ToolPanelContent.type` a graph panel matches on. */
+export const GRAPH_PANEL_TYPE = "graph";
+/**
+ * Build the panel payload for a graph.
+ *
+ * `data` carries the parsed payload so the renderer never re-parses, and
+ * `content` carries the serialization so the panel header's Copy button and the
+ * built-in text fallback still do something useful if no renderer matched.
+ */
+export function graphPanelContent(title, payload) {
+    return {
+        title,
+        type: GRAPH_PANEL_TYPE,
+        content: safeStringify(payload, 2),
+        data: payload,
+    };
+}
+/**
+ * Recover the payload from panel content.
+ *
+ * Prefers `data`; falls back to parsing `content` so a panel opened by a
+ * generic client tool (`ui_open_panel`, which only knows how to set strings)
+ * still renders as a graph.
+ */
+export function graphPanelPayload(content) {
+    return coerceGraphPayload(content.data) ?? coerceGraphPayload(content.content);
+}

package/dist/assistant-ui/graph-panel.d.ts

@@ -0,0 +1,11 @@
+import { type GraphPanelContentLike } from "./graph-panel-content.js";
+/**
+ * Full-size graph for the tool panel, connected to the shared workspace.
+ *
+ * Default-exported and loaded through `React.lazy` from
+ * `registerGraphPanelRenderer`, so neither this nor the force engine is in the
+ * bundle until a graph panel is actually opened.
+ */
+export default function GraphPanel({ content }: {
+    content: GraphPanelContentLike;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/assistant-ui/graph-panel.js

@@ -0,0 +1,121 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import { GraphView } from "../graph-view.js";
+import { hasOwn, primaryLabel, resolveCaption } from "../model.js";
+import { GraphEmptyState } from "../graph-notice.js";
+import { graphWorkspaceStore } from "../graph-workspace.js";
+import { submitComposerText, useAppStore, useToolPanelStore } from "@iloveagents/foundry-web-ui";
+import { graphPanelPayload } from "./graph-panel-content.js";
+import { GraphContextPinButton, syncGraphSelectionContext } from "./graph-context.js";
+/**
+ * Full-size graph for the tool panel, connected to the shared workspace.
+ *
+ * Default-exported and loaded through `React.lazy` from
+ * `registerGraphPanelRenderer`, so neither this nor the force engine is in the
+ * bundle until a graph panel is actually opened.
+ */
+export default function GraphPanel({ content }) {
+    const handleRef = useRef(null);
+    // Memoised on the panel's own content, so an unrelated re-render does not
+    // hand `GraphView` a new payload object and re-run the workspace effect.
+    const payload = useMemo(() => graphPanelPayload(content), [content]);
+    const isOpen = useToolPanelStore((state) => state.isOpen);
+    const currentPage = useAppStore((state) => state.currentPage);
+    /**
+     * Expand through the conversation, not behind it.
+     *
+     * The panel cannot query the graph — the Cypher tools live on the server, as
+     * they must. So a double-click asks the agent, in the chat, the way the user
+     * would: the turn is visible, the agent picks the traversal, and the answer
+     * merges into the graph on screen. The expansion becomes part of the
+     * conversation rather than a side effect nobody can refer back to.
+     */
+    /**
+     * The payload's caption key for this node's label.
+     *
+     * Every path that NAMES a node — the expansion prompt, the chat-context
+     * chip, the client tools — resolves through the same rule the canvas paints
+     * by, or the same node ends up with two names and the agent discusses one
+     * the user cannot see.
+     */
+    const captionKeyFor = useCallback((node) => {
+        const legend = payload?.legend;
+        const label = primaryLabel(node);
+        return legend && hasOwn(legend, label) ? legend[label]?.captionKey : undefined;
+    }, [payload]);
+    const expandNode = useCallback((node) => {
+        submitComposerText(`Expand "${resolveCaption(node, captionKeyFor(node))}" (${primaryLabel(node)}) in the graph — node id ${node.id}.`);
+    }, [captionKeyFor]);
+    // Publish this panel as THE live graph, so the agent's client tools can read
+    // what is on screen and drive it. Registering the handle is what lets
+    // `graph_select_node` and `graph_search` reach into a mounted view.
+    //
+    // Gated on `isOpen`, because closing the panel does not unmount it — the
+    // tool panel slides off-screen with `translate-x-full` and stays in the
+    // tree. Without this the workspace stayed connected to a graph nobody could
+    // see, and `graph_get_view` went on describing it.
+    useEffect(() => {
+        const handle = handleRef.current;
+        if (!handle || !payload || !isOpen)
+            return;
+        const workspace = graphWorkspaceStore.getState();
+        workspace.connect(handle, content.title, payload);
+        // Republish what the view is already showing. `disconnect` cleared the
+        // workspace when the panel closed, but the view was never unmounted — so
+        // reopening it leaves the drawer and the search box exactly as they were
+        // while `graph_get_view` reports neither, and the selected node is missing
+        // from the chat context. The callbacks cannot help: they fire on CHANGE,
+        // and from the view's side nothing changed.
+        const view = handle.getViewState();
+        workspace.setSelection(view.selection);
+        workspace.setQuery(view.query);
+        workspace.setHiddenLabels(view.hiddenLabels);
+        syncGraphSelectionContext(view.selection, `graph:${content.title}`, view.selection ? captionKeyFor(view.selection) : undefined);
+        return () => graphWorkspaceStore.getState().disconnect(handle);
+        // `currentPage` is a dependency for the same reason `isOpen` is, and it is
+        // easy to miss because the panel does not move: `setCurrentPage` clears
+        // every keyed and ephemeral context item on navigation, on the reasonable
+        // assumption that a keyed item tracks UI the navigation just unmounted.
+        // The tool panel is the exception — it belongs to the shell, so the graph
+        // and its open drawer survive a route change while the selected node
+        // silently drops out of the conversation. Nothing fires to put it back:
+        // the selection did not change. Re-running this republishes it, which is
+        // the same job it already does for reopening a closed panel.
+    }, [content.title, payload, isOpen, currentPage]);
+    /**
+     * The selected node leaves the conversation when the graph does — and not
+     * before.
+     *
+     * This used to ride in the cleanup above, which made it fire on every
+     * payload change: an in-place merge, the thing this panel is built around,
+     * dropped the user's selected node out of the chat context even though it
+     * was still on screen and still selected. Visibility is its own lifetime.
+     */
+    useEffect(() => {
+        if (isOpen)
+            return;
+        syncGraphSelectionContext(null, "");
+    }, [isOpen]);
+    useEffect(() => () => syncGraphSelectionContext(null, ""), []);
+    if (!payload) {
+        return _jsx(GraphEmptyState, { message: "This panel does not contain a readable graph." });
+    }
+    // `absolute inset-0`, not `h-full`.
+    //
+    // The tool panel's content wrapper is `relative flex-1 overflow-y-auto` — a
+    // scroll container. A percentage height inside one resolves against the
+    // CONTENT box, so `h-full` lets the canvas grow past the visible area: the
+    // graph gets correctly fitted into a canvas taller than the panel, and the
+    // bottom half is simply below the fold. Pinning to the positioned ancestor
+    // makes the canvas exactly the size of what the user can see, which is also
+    // what the ResizeObserver needs to re-fit on drag-resize and fullscreen.
+    return (_jsx("div", { className: "absolute inset-0 p-3", children: _jsx(GraphView, { data: payload, variant: "full", height: "100%", handleRef: handleRef, onExpandNode: expandNode, 
+            // The user's clicks and the agent's reads share one piece of state, so
+            // "tell me about this node" needs no restating on either side.
+            onSelectionChange: (node) => {
+                graphWorkspaceStore.getState().setSelection(node);
+                // The selected node joins the conversation automatically, so
+                // "tell me about this" needs no restating on either side.
+                syncGraphSelectionContext(node, `graph:${content.title}`, node ? captionKeyFor(node) : undefined);
+            }, inspectorActions: (node) => (_jsx(GraphContextPinButton, { node: node, captionKey: captionKeyFor(node) })), onQueryChange: (query) => graphWorkspaceStore.getState().setQuery(query), onFilterChange: (labels) => graphWorkspaceStore.getState().setHiddenLabels(labels) }) }));
+}

package/dist/assistant-ui/graph-provenance.d.ts

@@ -0,0 +1,17 @@
+import { type GraphPayload } from "../model.js";
+interface GraphProvenanceProps {
+    payload: GraphPayload;
+    /** Arguments the agent called the tool with — usually where the query lives. */
+    args?: unknown;
+    className?: string;
+}
+/**
+ * What the card shows when expanded: the query that ran, and the result.
+ *
+ * The card is provenance, not a viewport — the graph belongs in the panel,
+ * where it has room. What someone opens a tool card for is "what did it
+ * actually do, and do I believe it": the statement, the shape of what came
+ * back, and a way to see the data itself.
+ */
+export declare function GraphProvenance({ payload, args, className }: GraphProvenanceProps): import("react/jsx-runtime").JSX.Element;
+export {};