@iloveagents/foundry-web-graph 0.1.0

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

@@ -0,0 +1,31 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { cn } from "@iloveagents/foundry-web-primitives";
+import { primaryLabel, safeStringify } from "../model.js";
+function readString(source, key) {
+    if (typeof source !== "object" || source === null)
+        return null;
+    const value = source[key];
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+/**
+ * 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 function GraphProvenance({ payload, args, className }) {
+    const [showRaw, setShowRaw] = useState(false);
+    const query = readString(payload.meta, "query") ?? readString(args, "cypher") ?? readString(args, "query");
+    const elapsed = typeof payload.meta?.elapsedMs === "number" ? payload.meta.elapsedMs : null;
+    const database = readString(payload.meta, "database");
+    const rows = Array.isArray(payload.meta?.rows) ? payload.meta.rows : null;
+    const labelCounts = new Map();
+    for (const node of payload.nodes) {
+        const label = primaryLabel(node);
+        labelCounts.set(label, (labelCounts.get(label) ?? 0) + 1);
+    }
+    return (_jsxs("div", { className: cn("space-y-2 text-xs", className), children: [query && (_jsxs("section", { children: [_jsx("h4", { className: "text-muted-foreground mb-1 font-medium", children: "Query" }), _jsx("pre", { className: "border-border bg-muted/60 text-foreground max-h-40 overflow-auto rounded border p-2 font-mono text-[11px] leading-relaxed whitespace-pre-wrap", children: query })] })), _jsxs("section", { children: [_jsx("h4", { className: "text-muted-foreground mb-1 font-medium", children: "Result" }), _jsxs("div", { className: "flex flex-wrap items-center gap-x-3 gap-y-1", children: [_jsxs("span", { className: "text-foreground", children: [payload.nodes.length, " nodes \u00B7 ", payload.edges.length, " relationships"] }), [...labelCounts].map(([label, count]) => (_jsxs("span", { className: "text-muted-foreground", children: [label, " ", count] }, label))), payload.truncated && (_jsx("span", { className: "text-muted-foreground", children: "truncated at the server's cap" })), elapsed !== null && _jsxs("span", { className: "text-muted-foreground", children: [elapsed, " ms"] }), database && _jsxs("span", { className: "text-muted-foreground", children: ["db: ", database] })] })] }), rows && rows.length > 0 && (_jsxs("section", { children: [_jsx("h4", { className: "text-muted-foreground mb-1 font-medium", children: "Rows" }), _jsx("pre", { className: "border-border bg-muted/60 text-foreground max-h-40 overflow-auto rounded border p-2 font-mono text-[11px]", children: safeStringify(rows, 2) })] })), _jsx("button", { type: "button", onClick: () => setShowRaw((open) => !open), className: "text-muted-foreground hover:text-foreground focus-visible:ring-ring rounded underline-offset-2 hover:underline focus-visible:outline-none focus-visible:ring-1", children: showRaw ? "Hide raw result" : "Show raw result" }), showRaw && (_jsx("pre", { className: "border-border bg-muted/60 text-foreground max-h-64 overflow-auto rounded border p-2 font-mono text-[11px]", children: safeStringify(payload, 2) }))] }));
+}

package/dist/assistant-ui/graph-result-seeder.d.ts

@@ -0,0 +1,73 @@
+/**
+ * A graph result must reach the panel without anyone expanding anything.
+ *
+ * Folding a result into the open graph used to be a side effect of RENDERING
+ * the tool card — and that card lives inside the turn's collapsed
+ * "Worked · 3 tools" strip, which does not mount until the reader expands it.
+ * So the merge never ran: the agent narrated an expansion, described four new
+ * relationships by name, and the panel sat at three nodes with nothing
+ * reporting a failure anywhere.
+ *
+ * This is the same failure `@ltwlf/spaces-web-ui`'s `CitationSeeder` and
+ * `TaskSeeder` were written for, in the same strip, and it takes the same
+ * shape: a headless watcher over the thread's own parts, mounted once with the
+ * tool UIs, independent of what is expanded. The alternative — force-mounting
+ * the strip's contents — makes a disclosure's contents cost something in every
+ * transcript and replays every historical result on a reopened chat.
+ */
+import type { GraphPayload } from "../model.js";
+interface ToolishPart {
+    type?: string;
+    toolName?: string;
+    toolCallId?: string;
+    args?: unknown;
+    result?: unknown;
+}
+export interface SeedableGraphResult {
+    toolCallId: string;
+    toolName: string;
+    payload: GraphPayload;
+    args: unknown;
+    title: string;
+    autoOpenPanel: boolean;
+}
+/**
+ * Every graph-shaped tool result in the thread, oldest first.
+ *
+ * Keyed by `toolCallId` rather than by position, so a re-render that rebuilds
+ * the parts array does not look like new results.
+ */
+export declare function seedableGraphResults(messages: readonly {
+    parts?: readonly ToolishPart[];
+}[] | undefined, 
+/**
+ * Calls already dealt with. Checked BEFORE `extract` runs, which is the
+ * whole point of the parameter: `thread.messages` is a new array on every
+ * streamed token, so this walk happens per token, and extracting means
+ * validating every node and edge of every graph the conversation has ever
+ * produced — work that grows with the transcript and is thrown away every
+ * time.
+ */
+skip?: ReadonlySet<string>): SeedableGraphResult[];
+/**
+ * Headless. Acts on graph results that arrive while this thread is open.
+ *
+ * The baseline is what keeps a reopened conversation from replaying its whole
+ * history — opening a saved chat rehydrates every turn it ever had, and
+ * without this the last `show_graph` in it would throw a panel over whatever
+ * the user was doing. Two details, both learned the hard way downstream
+ * (ltwlf/lastspace#650):
+ *
+ * 1. **History arrives asynchronously.** A resumed thread mounts with NO
+ *    messages and fills them in later, so a baseline taken on the first effect
+ *    records an empty set and the entire history then looks new. It is taken
+ *    on the first NON-EMPTY view instead.
+ * 2. **The runtime can outlive the thread.** A host that switches threads
+ *    without remounting would carry thread A's ids into thread B, so the
+ *    baseline is re-taken whenever the thread identity changes.
+ *
+ * The card is untouched and still has its "Open in panel" action, so a result
+ * in a reopened thread stays reachable that way.
+ */
+export declare function GraphResultSeeder(): null;
+export {};

package/dist/assistant-ui/graph-result-seeder.js

@@ -0,0 +1,157 @@
+/**
+ * A graph result must reach the panel without anyone expanding anything.
+ *
+ * Folding a result into the open graph used to be a side effect of RENDERING
+ * the tool card — and that card lives inside the turn's collapsed
+ * "Worked · 3 tools" strip, which does not mount until the reader expands it.
+ * So the merge never ran: the agent narrated an expansion, described four new
+ * relationships by name, and the panel sat at three nodes with nothing
+ * reporting a failure anywhere.
+ *
+ * This is the same failure `@ltwlf/spaces-web-ui`'s `CitationSeeder` and
+ * `TaskSeeder` were written for, in the same strip, and it takes the same
+ * shape: a headless watcher over the thread's own parts, mounted once with the
+ * tool UIs, independent of what is expanded. The alternative — force-mounting
+ * the strip's contents — makes a disclosure's contents cost something in every
+ * transcript and replays every historical result on a reopened chat.
+ */
+import { useEffect, useRef } from "react";
+import { useAuiState } from "@assistant-ui/react";
+import { useToolPanelStore } from "@iloveagents/foundry-web-ui";
+import { graphToolBindings } from "./graph-tool-registry.js";
+import { GRAPH_PANEL_TYPE, graphPanelContent } from "./graph-panel-content.js";
+import { mergeIntoOpenGraph } from "./merge-into-panel.js";
+/**
+ * Every graph-shaped tool result in the thread, oldest first.
+ *
+ * Keyed by `toolCallId` rather than by position, so a re-render that rebuilds
+ * the parts array does not look like new results.
+ */
+export function seedableGraphResults(messages, 
+/**
+ * Calls already dealt with. Checked BEFORE `extract` runs, which is the
+ * whole point of the parameter: `thread.messages` is a new array on every
+ * streamed token, so this walk happens per token, and extracting means
+ * validating every node and edge of every graph the conversation has ever
+ * produced — work that grows with the transcript and is thrown away every
+ * time.
+ */
+skip = new Set()) {
+    const bindings = graphToolBindings();
+    const found = [];
+    const seen = new Set();
+    for (const message of messages ?? []) {
+        for (const part of message?.parts ?? []) {
+            const binding = part?.toolName ? bindings.get(part.toolName) : undefined;
+            if (!binding)
+                continue;
+            // A call still streaming has no result yet, and `undefined` is not a
+            // failure — it is simply not ready.
+            if (part.result === undefined || part.result === null)
+                continue;
+            const id = part.toolCallId;
+            if (!id || seen.has(id) || skip.has(id))
+                continue;
+            const payload = binding.extract(part.result, part.args);
+            if (!payload)
+                continue;
+            seen.add(id);
+            found.push({
+                toolCallId: id,
+                toolName: binding.toolName,
+                payload,
+                args: part.args,
+                title: binding.panelTitle?.(payload, part.args) ?? binding.title,
+                autoOpenPanel: binding.autoOpenPanel,
+            });
+        }
+    }
+    return found;
+}
+/**
+ * Headless. Acts on graph results that arrive while this thread is open.
+ *
+ * The baseline is what keeps a reopened conversation from replaying its whole
+ * history — opening a saved chat rehydrates every turn it ever had, and
+ * without this the last `show_graph` in it would throw a panel over whatever
+ * the user was doing. Two details, both learned the hard way downstream
+ * (ltwlf/lastspace#650):
+ *
+ * 1. **History arrives asynchronously.** A resumed thread mounts with NO
+ *    messages and fills them in later, so a baseline taken on the first effect
+ *    records an empty set and the entire history then looks new. It is taken
+ *    on the first NON-EMPTY view instead.
+ * 2. **The runtime can outlive the thread.** A host that switches threads
+ *    without remounting would carry thread A's ids into thread B, so the
+ *    baseline is re-taken whenever the thread identity changes.
+ *
+ * The card is untouched and still has its "Open in panel" action, so a result
+ * in a reopened thread stays reachable that way.
+ */
+export function GraphResultSeeder() {
+    const messages = useAuiState((s) => s.thread.messages);
+    const threadId = useAuiState((s) => s.thread.threadId);
+    // A GRAPH panel, not any panel. `isOpen` alone let a result be marked
+    // handled while a PDF was up: the merge rejected the non-graph content and
+    // the call was consumed anyway, so opening the graph later could never
+    // apply it — the same loss the closed-panel deferral was added to prevent.
+    const graphPanelOpen = useToolPanelStore((state) => state.isOpen && state.content?.type === GRAPH_PANEL_TYPE);
+    const baseline = useRef(null);
+    /** Seen, extracted, and waiting for a graph panel. Cleared with the baseline. */
+    const deferred = useRef(new Set());
+    useEffect(() => {
+        const current = baseline.current;
+        if (current === null || current.threadId !== threadId) {
+            // Nothing to anchor to yet — an empty thread may simply not have loaded.
+            if (!messages || messages.length === 0)
+                return;
+            deferred.current.clear();
+            baseline.current = {
+                threadId,
+                ids: new Set(seedableGraphResults(messages).map((result) => result.toolCallId)),
+            };
+            return;
+        }
+        // Everything already acted on is skipped before its payload is extracted,
+        // so a streaming turn re-walks the parts array without re-parsing the
+        // whole conversation's graphs on every token.
+        // Handled OR deferred: both are "do not extract this again". They stay
+        // separate sets because only `ids` means finished — a deferred call has to
+        // become extractable again the moment a graph panel is there for it.
+        const skip = graphPanelOpen ? current.ids : new Set([...current.ids, ...deferred.current]);
+        for (const result of seedableGraphResults(messages, skip)) {
+            if (result.autoOpenPanel) {
+                current.ids.add(result.toolCallId);
+                useToolPanelStore.getState().openPanel(graphPanelContent(result.title, result.payload));
+                continue;
+            }
+            // A result that arrives while the panel is CLOSED is not handled, it is
+            // early. Ask for an expansion, close the panel before the tool returns,
+            // reopen it: the merge had nothing to merge into, and marking the call
+            // done anyway meant the answer the user asked for was gone for good.
+            // Held back instead, and applied when a graph panel comes back — which
+            // is why `graphPanelOpen` is a dependency of this effect.
+            if (!graphPanelOpen) {
+                // Deferred, and REMEMBERED as deferred. Leaving it out of `deferred`
+                // as well as out of `ids` meant `seedableGraphResults` re-extracted it
+                // on every pass — and a pass happens per streamed token — so a graph
+                // held back while the panel was closed re-validated every node and
+                // edge of itself for the rest of the turn. That is the same cost the
+                // `skip` parameter exists to avoid; this set is the half of it the
+                // deferral had quietly opted out of.
+                deferred.current.add(result.toolCallId);
+                continue;
+            }
+            deferred.current.delete(result.toolCallId);
+            // Fold into the graph already open when it is about the same part of
+            // the graph. This is what makes expanding a node — and watching the
+            // agent write one — read as the workspace growing rather than as a
+            // series of unrelated pictures. A `false` here with the panel OPEN is a
+            // real decision — an unrelated result, or nothing new — so it counts as
+            // handled either way.
+            current.ids.add(result.toolCallId);
+            mergeIntoOpenGraph(result.payload);
+        }
+    }, [messages, threadId, graphPanelOpen]);
+    return null;
+}

package/dist/assistant-ui/graph-tool-registry.d.ts

@@ -0,0 +1,25 @@
+import type { GraphPayload } from "../model.js";
+/**
+ * What every graph-shaped tool in the app is called, and how to read it.
+ *
+ * `makeGraphToolUI` fills this in as a side effect of binding a card, so the
+ * headless `GraphResultSeeder` can act on a result without the card having
+ * rendered — which it may never do, since it lives inside a collapsed
+ * disclosure. Binding a card is therefore what makes a tool's result reach the
+ * panel; there is no second registration to forget.
+ */
+export interface GraphToolBinding {
+    toolName: string;
+    title: string;
+    extract: (result: unknown, args: unknown) => GraphPayload | null;
+    panelTitle?: (payload: GraphPayload, args: unknown) => string;
+    autoOpenPanel: boolean;
+}
+/**
+ * Idempotent by tool name: a module re-registering on a hot reload replaces
+ * its binding rather than stacking a second one.
+ */
+export declare function registerGraphTool(binding: GraphToolBinding): void;
+export declare function graphToolBindings(): ReadonlyMap<string, GraphToolBinding>;
+/** Test seam. Not exported from the package. */
+export declare function _resetGraphToolBindings(): void;

package/dist/assistant-ui/graph-tool-registry.js

@@ -0,0 +1,15 @@
+const bindings = new Map();
+/**
+ * Idempotent by tool name: a module re-registering on a hot reload replaces
+ * its binding rather than stacking a second one.
+ */
+export function registerGraphTool(binding) {
+    bindings.set(binding.toolName, binding);
+}
+export function graphToolBindings() {
+    return bindings;
+}
+/** Test seam. Not exported from the package. */
+export function _resetGraphToolBindings() {
+    bindings.clear();
+}

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

@@ -0,0 +1,54 @@
+import { type ReactNode } from "react";
+import { type GraphNode, type GraphPayload } from "../model.js";
+export interface MakeGraphToolUIOptions {
+    /** The agent tool whose result this card renders. */
+    toolName: string;
+    title?: string;
+    icon?: ReactNode;
+    /**
+     * Pull a payload out of the tool result. Defaults to {@link coerceGraphPayload},
+     * which accepts the payload itself, a JSON string, or one nested under
+     * `graph` / `result` / `data` / `payload`.
+     */
+    extract?: (result: unknown, args: unknown) => GraphPayload | null;
+    /** Panel heading. Defaults to the card title. */
+    panelTitle?: (payload: GraphPayload, args: unknown) => string;
+    /** Open the side panel as soon as a graph arrives. Off by default. */
+    autoOpenPanel?: boolean;
+    /**
+     * Expand the inline graph inside the card. Off by default.
+     *
+     * The card stays a compact summary and the full graph goes to the side
+     * panel, where it has the room to be readable — a 280px graph wedged into a
+     * chat column is a thumbnail, not an explorer. Turn this on for a surface
+     * with no panel.
+     */
+    defaultExpanded?: boolean;
+    inlineHeight?: number;
+    onExpandNode?: (node: GraphNode) => void;
+}
+/**
+ * Build a tool card that renders a graph-shaped result.
+ *
+ * A factory rather than a component because `makeAssistantToolUI` binds a
+ * literal tool name at construction time — and hard-coding one would tie this
+ * package to whatever the Neo4j starter happens to call its tools. Any agent
+ * that emits the payload contract gets the same card:
+ *
+ * ```ts
+ * const CypherToolUI = makeGraphToolUI({ toolName: "graph_read_cypher" });
+ * ```
+ *
+ * A result that is not graph-shaped is not an error — the card renders the
+ * usual summary and leaves the body empty rather than throwing inside a chat
+ * message.
+ */
+export declare function makeGraphToolUI(options: MakeGraphToolUIOptions): import("@assistant-ui/react").AssistantToolUI;
+/**
+ * The generic "show me this as a graph" card, bound to a `show_graph` tool.
+ *
+ * Mirrors `ShowDocumentToolUI` in `@iloveagents/foundry-web-ui`: an agent that
+ * wants to put a graph in front of the user calls `show_graph` with the payload
+ * and the panel opens itself.
+ */
+export declare const GraphToolUI: import("@assistant-ui/react").AssistantToolUI;

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

@@ -0,0 +1,77 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useState } from "react";
+import { makeAssistantToolUI } from "@assistant-ui/react";
+import { Share2 } from "lucide-react";
+import { ToolCallCard, useToolPanelStore } from "@iloveagents/foundry-web-ui";
+import { coerceGraphPayload } from "../model.js";
+import { GraphView } from "../graph-view.js";
+import { GraphProvenance } from "./graph-provenance.js";
+import { graphPanelContent } from "./graph-panel-content.js";
+import { registerGraphTool } from "./graph-tool-registry.js";
+const summarize = (payload) => {
+    const nodes = payload.nodes.length;
+    const edges = payload.edges.length;
+    return `${nodes} ${nodes === 1 ? "node" : "nodes"} · ${edges} ${edges === 1 ? "relationship" : "relationships"}`;
+};
+/**
+ * Build a tool card that renders a graph-shaped result.
+ *
+ * A factory rather than a component because `makeAssistantToolUI` binds a
+ * literal tool name at construction time — and hard-coding one would tie this
+ * package to whatever the Neo4j starter happens to call its tools. Any agent
+ * that emits the payload contract gets the same card:
+ *
+ * ```ts
+ * const CypherToolUI = makeGraphToolUI({ toolName: "graph_read_cypher" });
+ * ```
+ *
+ * A result that is not graph-shaped is not an error — the card renders the
+ * usual summary and leaves the body empty rather than throwing inside a chat
+ * message.
+ */
+export function makeGraphToolUI(options) {
+    const { toolName, title = "Graph", icon = _jsx(Share2, { className: "size-3.5" }), extract = (result) => coerceGraphPayload(result), panelTitle, autoOpenPanel = false, defaultExpanded = false, inlineHeight = 280, onExpandNode, } = options;
+    // Registering the BINDING, not just the card. `GraphResultSeeder` reads this
+    // to fold a result into the open graph, because the card itself may never
+    // mount — it lives inside the turn's collapsed activity strip. Binding a
+    // card is therefore all a new graph tool needs; there is no second
+    // registration to forget.
+    registerGraphTool({ toolName, title, extract, panelTitle, autoOpenPanel });
+    return makeAssistantToolUI({
+        toolName,
+        render: ({ args, result, status }) => {
+            const openPanel = useToolPanelStore((state) => state.openPanel);
+            const [expanded, setExpanded] = useState(defaultExpanded);
+            const payload = status.type === "complete" ? extract(result, args) : null;
+            const open = useCallback(() => {
+                if (!payload)
+                    return;
+                openPanel(graphPanelContent(panelTitle?.(payload, args) ?? title, payload));
+            }, [payload, openPanel, args]);
+            let description;
+            if (status.type === "running")
+                description = "Querying the graph…";
+            else if (status.type === "requires-action")
+                description = "Waiting for approval";
+            else if (payload)
+                description = summarize(payload);
+            else if (status.type === "complete")
+                description = "No graph in this result";
+            else
+                description = "Graph query did not complete";
+            return (_jsx(ToolCallCard, { icon: icon, title: title, description: description, status: status, className: "w-full", open: expanded, onOpenChange: setExpanded, action: payload ? { label: "Open in panel", onClick: open } : undefined, children: payload &&
+                    (defaultExpanded ? (_jsx(GraphView, { data: payload, variant: "inline", height: inlineHeight, onExpandNode: onExpandNode })) : (_jsx(GraphProvenance, { payload: payload, args: args }))) }));
+        },
+    });
+}
+/**
+ * The generic "show me this as a graph" card, bound to a `show_graph` tool.
+ *
+ * Mirrors `ShowDocumentToolUI` in `@iloveagents/foundry-web-ui`: an agent that
+ * wants to put a graph in front of the user calls `show_graph` with the payload
+ * and the panel opens itself.
+ */
+export const GraphToolUI = makeGraphToolUI({
+    toolName: "show_graph",
+    autoOpenPanel: true,
+});

package/dist/assistant-ui/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Chat glue: the assistant-ui tool card and the tool-panel renderer.
+ *
+ * Split into its own entry point so the root export stays free of
+ * `@assistant-ui/react` — a host that only wants to draw a graph (a dashboard,
+ * a report page) imports `@iloveagents/foundry-web-graph` and never loads the
+ * chat runtime.
+ */
+export { GraphToolUI, makeGraphToolUI, type MakeGraphToolUIOptions } from "./graph-tool-ui.js";
+export { GraphProvenance } from "./graph-provenance.js";
+export { GraphResultSeeder, seedableGraphResults } from "./graph-result-seeder.js";
+export { graphToolBindings, type GraphToolBinding } from "./graph-tool-registry.js";
+export { registerGraphPanelRenderer } from "./register-graph-panel.js";
+export { mergeIntoOpenGraph } from "./merge-into-panel.js";
+export { GRAPH_SELECTION_CONTEXT_KEY, GraphContextPinButton, syncGraphSelectionContext, } from "./graph-context.js";
+export { GRAPH_CLIENT_TOOLS, registerGraphClientTools } from "./graph-client-tools.js";
+export { GRAPH_PANEL_TYPE, graphPanelContent, graphPanelPayload, type GraphPanelContent, type GraphPanelContentLike, } from "./graph-panel-content.js";

package/dist/assistant-ui/index.js

@@ -0,0 +1,17 @@
+/**
+ * Chat glue: the assistant-ui tool card and the tool-panel renderer.
+ *
+ * Split into its own entry point so the root export stays free of
+ * `@assistant-ui/react` — a host that only wants to draw a graph (a dashboard,
+ * a report page) imports `@iloveagents/foundry-web-graph` and never loads the
+ * chat runtime.
+ */
+export { GraphToolUI, makeGraphToolUI } from "./graph-tool-ui.js";
+export { GraphProvenance } from "./graph-provenance.js";
+export { GraphResultSeeder, seedableGraphResults } from "./graph-result-seeder.js";
+export { graphToolBindings } from "./graph-tool-registry.js";
+export { registerGraphPanelRenderer } from "./register-graph-panel.js";
+export { mergeIntoOpenGraph } from "./merge-into-panel.js";
+export { GRAPH_SELECTION_CONTEXT_KEY, GraphContextPinButton, syncGraphSelectionContext, } from "./graph-context.js";
+export { GRAPH_CLIENT_TOOLS, registerGraphClientTools } from "./graph-client-tools.js";
+export { GRAPH_PANEL_TYPE, graphPanelContent, graphPanelPayload, } from "./graph-panel-content.js";

package/dist/assistant-ui/merge-into-panel.d.ts

@@ -0,0 +1,21 @@
+import { type GraphPayload } from "../model.js";
+/**
+ * Fold a fresh result into the graph the user already has open.
+ *
+ * The panel is a workspace, not a slideshow. When the agent expands a node or
+ * writes one, the answer is about the graph on screen — so it belongs in that
+ * graph, appearing beside what it connects to, rather than arriving as a
+ * separate picture the user has to open and mentally join up.
+ *
+ * Doing it here rather than asking the model to call `graph_show` afterwards
+ * also keeps the turn to a single tool call. Two calls in one turn is where
+ * the AG-UI client-tool replay gets into trouble, and "the agent remembered to
+ * call the second tool" is not a foundation to build the main interaction on.
+ *
+ * Merges only when the new payload SHARES a node with what is on screen. That
+ * overlap is the evidence the two results are about the same thing; without
+ * it, an unrelated query would quietly graft itself onto someone's workspace.
+ *
+ * @returns whether the open graph was updated.
+ */
+export declare function mergeIntoOpenGraph(payload: GraphPayload): boolean;

package/dist/assistant-ui/merge-into-panel.js

@@ -0,0 +1,72 @@
+import { useToolPanelStore } from "@iloveagents/foundry-web-ui";
+import { deepEqual, mergeGraphPayloads, } from "../model.js";
+import { graphWorkspaceStore } from "../graph-workspace.js";
+import { GRAPH_PANEL_TYPE, graphPanelContent, graphPanelPayload, } from "./graph-panel-content.js";
+/**
+ * Fold a fresh result into the graph the user already has open.
+ *
+ * The panel is a workspace, not a slideshow. When the agent expands a node or
+ * writes one, the answer is about the graph on screen — so it belongs in that
+ * graph, appearing beside what it connects to, rather than arriving as a
+ * separate picture the user has to open and mentally join up.
+ *
+ * Doing it here rather than asking the model to call `graph_show` afterwards
+ * also keeps the turn to a single tool call. Two calls in one turn is where
+ * the AG-UI client-tool replay gets into trouble, and "the agent remembered to
+ * call the second tool" is not a foundation to build the main interaction on.
+ *
+ * Merges only when the new payload SHARES a node with what is on screen. That
+ * overlap is the evidence the two results are about the same thing; without
+ * it, an unrelated query would quietly graft itself onto someone's workspace.
+ *
+ * @returns whether the open graph was updated.
+ */
+export function mergeIntoOpenGraph(payload) {
+    const panel = useToolPanelStore.getState();
+    const content = panel.content;
+    if (!panel.isOpen || content?.type !== GRAPH_PANEL_TYPE)
+        return false;
+    // The base is what the PANEL holds, not what the workspace published.
+    // `setContent` below updates the panel synchronously; the workspace only
+    // catches up when `GraphPanel`'s effect re-runs. Two results handled in one
+    // pass — an expansion and a write in the same turn, which is the ordinary
+    // case here — would otherwise both read the same stale base, and the second
+    // would either reject an addition overlapping only the first or overwrite
+    // it with `old + second`, silently losing a merge already on screen. The
+    // workspace is the fallback for a panel opened by something that only knows
+    // how to set strings.
+    const current = graphPanelPayload(content) ?? graphWorkspaceStore.getState().payload;
+    // An empty payload is not a merge. It is usually a write that DELETED
+    // something, and merging cannot express a removal — there is no row for a
+    // node that no longer exists, and nothing here can know which ids went. The
+    // write tool therefore marks its own result `view_stale` and tells the agent
+    // to re-read; silently treating this as "no change" is what would leave the
+    // panel drawing a node the database no longer has.
+    if (!current || payload.nodes.length === 0)
+        return false;
+    const onScreen = new Set(current.nodes.map((node) => node.id));
+    if (!payload.nodes.some((node) => onScreen.has(node.id)))
+        return false;
+    // Nothing new AND nothing changed: re-setting identical content would churn
+    // the store and re-run the panel's effects for no visible difference.
+    //
+    // "New" is not enough on its own. `MATCH (n) SET n.status = $status RETURN n`
+    // is an ordinary write whose result carries only ids the graph already has,
+    // and an id-only test threw it away — leaving the details drawer showing the
+    // property the user just changed, at its old value. `mergeGraphPayloads`
+    // already lets the fresher entity win; this test only decides whether to ask
+    // it to.
+    const byId = new Map();
+    for (const node of current.nodes)
+        byId.set(node.id, node);
+    for (const edge of current.edges)
+        byId.set(edge.id, edge);
+    const differs = (entity) => {
+        const existing = byId.get(entity.id);
+        return existing === undefined || !deepEqual(existing, entity);
+    };
+    if (!payload.nodes.some(differs) && !payload.edges.some(differs))
+        return false;
+    panel.setContent(graphPanelContent(content.title, mergeGraphPayloads(current, payload)));
+    return true;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Teach the tool panel to render graphs.
+ *
+ * Call once at app start, or from a `ChatModule`'s `useInit`. Idempotent: the
+ * entry carries a stable id, and the store replaces a same-id entry rather than
+ * appending, so a StrictMode double-render or a hot reload cannot stack copies.
+ */
+export declare function registerGraphPanelRenderer(): void;

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

@@ -0,0 +1,18 @@
+import { lazy } from "react";
+import { useToolPanelStore } from "@iloveagents/foundry-web-ui";
+import { GRAPH_PANEL_TYPE, graphPanelPayload } from "./graph-panel-content.js";
+const GraphPanelRenderer = lazy(() => import("./graph-panel.js"));
+/**
+ * Teach the tool panel to render graphs.
+ *
+ * Call once at app start, or from a `ChatModule`'s `useInit`. Idempotent: the
+ * entry carries a stable id, and the store replaces a same-id entry rather than
+ * appending, so a StrictMode double-render or a hot reload cannot stack copies.
+ */
+export function registerGraphPanelRenderer() {
+    useToolPanelStore.getState().registerRenderer({
+        id: "foundry.graph",
+        match: (content) => content.type === GRAPH_PANEL_TYPE && graphPanelPayload(content) !== null,
+        component: GraphPanelRenderer,
+    });
+}