@particle-academy/agent-integrations 0.2.4

package/README.md

@@ -0,0 +1,131 @@
+# @particle-academy/agent-integrations
+
+MCP-driven agent presence in collab sessions. Each open session gets a **micro-MCP server** running in-page; agents (in-browser or external via relay) connect to it and act as participants — adding sticky notes, drawing, moving items, leaving cursor trails.
+
+Also ships the **agent UX surface**: a chat-and-tool-log panel, an on-canvas presence cursor, and a brief activity highlight for items the agent just touched.
+
+> v0.1 — focused on `@particle-academy/fancy-whiteboard` as the first bridged surface. The bridge layer is package-agnostic, so other fancy-* packages can register their own tool sets per session.
+
+## Install
+
+```bash
+npm install @particle-academy/agent-integrations
+```
+
+```ts
+import "@particle-academy/agent-integrations/styles.css";
+```
+
+## Architecture
+
+```
+┌─ Browser tab ───────────────────────────────────────┐
+│   Whiteboard UI ── controlled state ── Bridge       │
+│        ▲                                  │        │
+│        │ tool calls mutate state          ▼        │
+│        └────────── MicroMcpServer ◄─── Transport ◄─ │
+│                                          ▲          │
+└──────────────────────────────────────────┼──────────┘
+                                           │
+                                  ┌────────┴─────────┐
+                                  │                  │
+                           in-process            relay
+                       (in-page agent)      (external agent
+                                            via Reverb / WS)
+```
+
+- **`MicroMcpServer`** is a transport-agnostic JSON-RPC 2.0 / MCP protocol handler. Register tools, attach transports, done.
+- **`InProcessTransport`** wires an in-page agent (e.g. an embedded Claude widget) to the server with zero serialization.
+- **`RelayTransport`** wraps any JSON duplex channel (Reverb whisper, WebRTC data channel, SSE+POST tunnel) so external agents can reach the browser session.
+- **Bridges** install a cohesive set of MCP tools against a host's controlled state. v0.1 ships the whiteboard bridge with the full tool kit.
+- **UI components** (`AgentPanel`, `AgentCursor`, `AgentActivityHighlight`) make agent presence visible.
+
+## Quick start (in-page agent + whiteboard)
+
+```tsx
+import {
+  MicroMcpServer,
+  attachInProcess,
+  registerWhiteboardBridge,
+  AgentPanel,
+  AgentCursor,
+  type AgentActivity,
+} from "@particle-academy/agent-integrations";
+import "@particle-academy/agent-integrations/styles.css";
+
+function MyBoard() {
+  const [notes, setNotes] = useState([]);
+  const [shapes, setShapes] = useState([]);
+  const [connectors, setConnectors] = useState([]);
+  const [strokes, setStrokes] = useState([]);
+  const [viewport, setViewport] = useState({ x: 0, y: 0, zoom: 1 });
+  const [agentCursor, setAgentCursor] = useState(null);
+  const [activity, setActivity] = useState<AgentActivity[]>([]);
+
+  const serverRef = useRef<MicroMcpServer>();
+  const transportRef = useRef<InProcessTransport>();
+
+  useEffect(() => {
+    const server = new MicroMcpServer({
+      info: { name: "whiteboard-session", version: "0.1.0" },
+    });
+    const bridge = registerWhiteboardBridge(server, {
+      adapter: {
+        getNotes: () => notes, setNotes,
+        getShapes: () => shapes, setShapes,
+        getConnectors: () => connectors, setConnectors,
+        getStrokes: () => strokes, setStrokes,
+        getViewport: () => viewport, setViewport,
+        setAgentCursor,
+      },
+    });
+    const transport = attachInProcess(server);
+    serverRef.current = server;
+    transportRef.current = transport;
+    return () => bridge.dispose();
+  }, []);
+
+  // ... render board, AgentPanel, AgentCursor when agentCursor is non-null ...
+}
+```
+
+For an end-to-end runnable, see the sandbox demo at `/whiteboard-agent` (added in a follow-up PR).
+
+## External agent via relay
+
+The relay is host-implemented — this package only defines the JSON envelope. See `docs/relay-protocol.md`.
+
+Pattern (Reverb):
+
+```ts
+const channel = Echo.private(`agent.session.${id}`);
+const transport = attachRelay(server, {
+  sendToRemote: (frame) => channel.whisper("mcp", frame),
+});
+channel.listenForWhisper("mcp", (frame) => transport.deliverFromRemote(frame));
+```
+
+Agents (Claude Desktop, Cline, custom) connect to the same channel via your auth bridge.
+
+## Tools shipped (whiteboard bridge)
+
+| Tool | Purpose |
+|---|---|
+| `whiteboard_get_state` | Full snapshot |
+| `whiteboard_list_items` | Summary of every item |
+| `whiteboard_get_item` | Detail by id |
+| `whiteboard_add_sticky` / `_update_sticky` | Sticky CRUD |
+| `whiteboard_add_shape` / `_update_shape` | Full shape kit (rect, rounded-rect, ellipse, diamond, triangle, line, arrow, text) |
+| `whiteboard_add_connector` | Connect two items / points |
+| `whiteboard_add_stroke` | Pen layer |
+| `whiteboard_delete_item` | Generic delete |
+| `whiteboard_set_viewport` | Pan / zoom |
+| `whiteboard_set_agent_cursor` | Move presence |
+
+## Status
+
+`v0.1` — protocol + whiteboard bridge + UI. APIs will evolve before `v1`.
+
+## License
+
+MIT

package/dist/bridges/flow.d.cts

@@ -0,0 +1,72 @@
+import { M as MicroMcpServer } from '../server-Bv985us3.cjs';
+import { B as Bridge } from '../types-DR5AS6Rd.cjs';
+
+type FlowNode = {
+    id: string;
+    type?: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    data: {
+        kind?: string;
+        label?: string;
+        description?: string;
+        status?: string;
+        statusText?: string;
+        config?: Record<string, unknown>;
+        [k: string]: unknown;
+    };
+};
+type FlowEdge = {
+    id: string;
+    source: string;
+    target: string;
+    sourceHandle?: string;
+    targetHandle?: string;
+    label?: string;
+    [k: string]: unknown;
+};
+type NodeRunStatus = "idle" | "queued" | "running" | "done" | "error";
+type ExecutorRegistry = Record<string, unknown>;
+type RunResult = {
+    ok: boolean;
+    outputs: Record<string, unknown>;
+    error?: string;
+};
+
+/**
+ * Adapter the host provides — same shape as the editor's local state plus
+ * an optional `run`/`cancel` pair so agents can trigger executions.
+ */
+type FlowBridgeAdapter = {
+    getNodes: () => FlowNode[];
+    setNodes: (next: FlowNode[] | ((prev: FlowNode[]) => FlowNode[])) => void;
+    getEdges: () => FlowEdge[];
+    setEdges: (next: FlowEdge[] | ((prev: FlowEdge[]) => FlowEdge[])) => void;
+    /** Optional: invoke runFlow with the host's executor registry. */
+    run?: (executors?: ExecutorRegistry) => Promise<RunResult>;
+    /** Optional: cancel the in-flight run. */
+    cancel?: () => void;
+    /** Optional: set per-node status text without going through the runner
+     *  (useful for agents narrating). */
+    setNodeStatus?: (id: string, status: NodeRunStatus, text?: string) => void;
+};
+type FlowBridgeOptions = {
+    adapter: FlowBridgeAdapter;
+    /** Identity tagged onto agent-authored nodes. */
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+};
+/**
+ * registerFlowBridge — wires an MCP tool set against a fancy-flow editor's
+ * controlled state. Mirrors the whiteboard bridge in shape: read tools,
+ * mutation tools (add / update / delete nodes + edges), and optional
+ * run/cancel if the host provides those callbacks.
+ */
+declare function registerFlowBridge(server: MicroMcpServer, options: FlowBridgeOptions): Bridge;
+
+export { type FlowBridgeAdapter, type FlowBridgeOptions, registerFlowBridge };

package/dist/bridges/flow.d.ts

@@ -0,0 +1,72 @@
+import { M as MicroMcpServer } from '../server-Bv985us3.js';
+import { B as Bridge } from '../types-CRPA_D0z.js';
+
+type FlowNode = {
+    id: string;
+    type?: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    data: {
+        kind?: string;
+        label?: string;
+        description?: string;
+        status?: string;
+        statusText?: string;
+        config?: Record<string, unknown>;
+        [k: string]: unknown;
+    };
+};
+type FlowEdge = {
+    id: string;
+    source: string;
+    target: string;
+    sourceHandle?: string;
+    targetHandle?: string;
+    label?: string;
+    [k: string]: unknown;
+};
+type NodeRunStatus = "idle" | "queued" | "running" | "done" | "error";
+type ExecutorRegistry = Record<string, unknown>;
+type RunResult = {
+    ok: boolean;
+    outputs: Record<string, unknown>;
+    error?: string;
+};
+
+/**
+ * Adapter the host provides — same shape as the editor's local state plus
+ * an optional `run`/`cancel` pair so agents can trigger executions.
+ */
+type FlowBridgeAdapter = {
+    getNodes: () => FlowNode[];
+    setNodes: (next: FlowNode[] | ((prev: FlowNode[]) => FlowNode[])) => void;
+    getEdges: () => FlowEdge[];
+    setEdges: (next: FlowEdge[] | ((prev: FlowEdge[]) => FlowEdge[])) => void;
+    /** Optional: invoke runFlow with the host's executor registry. */
+    run?: (executors?: ExecutorRegistry) => Promise<RunResult>;
+    /** Optional: cancel the in-flight run. */
+    cancel?: () => void;
+    /** Optional: set per-node status text without going through the runner
+     *  (useful for agents narrating). */
+    setNodeStatus?: (id: string, status: NodeRunStatus, text?: string) => void;
+};
+type FlowBridgeOptions = {
+    adapter: FlowBridgeAdapter;
+    /** Identity tagged onto agent-authored nodes. */
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+};
+/**
+ * registerFlowBridge — wires an MCP tool set against a fancy-flow editor's
+ * controlled state. Mirrors the whiteboard bridge in shape: read tools,
+ * mutation tools (add / update / delete nodes + edges), and optional
+ * run/cancel if the host provides those callbacks.
+ */
+declare function registerFlowBridge(server: MicroMcpServer, options: FlowBridgeOptions): Bridge;
+
+export { type FlowBridgeAdapter, type FlowBridgeOptions, registerFlowBridge };

package/dist/bridges/whiteboard.d.cts

@@ -0,0 +1,40 @@
+import { StickyNoteItem, ShapeItem, ConnectorItem, Stroke, Viewport, RemoteCursor } from '@particle-academy/fancy-whiteboard';
+import { M as MicroMcpServer } from '../server-Bv985us3.cjs';
+import { B as Bridge } from '../types-DR5AS6Rd.cjs';
+
+/**
+ * State accessors / mutators the bridge needs from the host. The host owns
+ * whiteboard state (controlled props on fancy-whiteboard components); the
+ * bridge calls into these to read or change it.
+ */
+type WhiteboardBridgeAdapter = {
+    getNotes: () => StickyNoteItem[];
+    setNotes: (next: StickyNoteItem[] | ((prev: StickyNoteItem[]) => StickyNoteItem[])) => void;
+    getShapes: () => ShapeItem[];
+    setShapes: (next: ShapeItem[] | ((prev: ShapeItem[]) => ShapeItem[])) => void;
+    getConnectors: () => ConnectorItem[];
+    setConnectors: (next: ConnectorItem[] | ((prev: ConnectorItem[]) => ConnectorItem[])) => void;
+    getStrokes: () => Stroke[];
+    setStrokes: (next: Stroke[] | ((prev: Stroke[]) => Stroke[])) => void;
+    getViewport: () => Viewport;
+    setViewport: (next: Viewport) => void;
+    /** Optional: agent presence cursor (for the visualizer). */
+    setAgentCursor?: (cursor: RemoteCursor | null) => void;
+};
+type WhiteboardBridgeOptions = {
+    adapter: WhiteboardBridgeAdapter;
+    /** Identity used when the agent stamps authorId on items / cursor. */
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+};
+/**
+ * registerWhiteboardBridge — wires a full MCP tool set against a fancy-
+ * whiteboard session controlled by the host. Returns a Bridge handle the
+ * host can dispose to tear everything down.
+ */
+declare function registerWhiteboardBridge(server: MicroMcpServer, options: WhiteboardBridgeOptions): Bridge;
+
+export { type WhiteboardBridgeAdapter, type WhiteboardBridgeOptions, registerWhiteboardBridge };

package/dist/bridges/whiteboard.d.ts

@@ -0,0 +1,40 @@
+import { StickyNoteItem, ShapeItem, ConnectorItem, Stroke, Viewport, RemoteCursor } from '@particle-academy/fancy-whiteboard';
+import { M as MicroMcpServer } from '../server-Bv985us3.js';
+import { B as Bridge } from '../types-CRPA_D0z.js';
+
+/**
+ * State accessors / mutators the bridge needs from the host. The host owns
+ * whiteboard state (controlled props on fancy-whiteboard components); the
+ * bridge calls into these to read or change it.
+ */
+type WhiteboardBridgeAdapter = {
+    getNotes: () => StickyNoteItem[];
+    setNotes: (next: StickyNoteItem[] | ((prev: StickyNoteItem[]) => StickyNoteItem[])) => void;
+    getShapes: () => ShapeItem[];
+    setShapes: (next: ShapeItem[] | ((prev: ShapeItem[]) => ShapeItem[])) => void;
+    getConnectors: () => ConnectorItem[];
+    setConnectors: (next: ConnectorItem[] | ((prev: ConnectorItem[]) => ConnectorItem[])) => void;
+    getStrokes: () => Stroke[];
+    setStrokes: (next: Stroke[] | ((prev: Stroke[]) => Stroke[])) => void;
+    getViewport: () => Viewport;
+    setViewport: (next: Viewport) => void;
+    /** Optional: agent presence cursor (for the visualizer). */
+    setAgentCursor?: (cursor: RemoteCursor | null) => void;
+};
+type WhiteboardBridgeOptions = {
+    adapter: WhiteboardBridgeAdapter;
+    /** Identity used when the agent stamps authorId on items / cursor. */
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+};
+/**
+ * registerWhiteboardBridge — wires a full MCP tool set against a fancy-
+ * whiteboard session controlled by the host. Returns a Bridge handle the
+ * host can dispose to tear everything down.
+ */
+declare function registerWhiteboardBridge(server: MicroMcpServer, options: WhiteboardBridgeOptions): Bridge;
+
+export { type WhiteboardBridgeAdapter, type WhiteboardBridgeOptions, registerWhiteboardBridge };

package/dist/bridges-flow.cjs

@@ -0,0 +1,330 @@
+'use strict';
+
+// src/mcp/server.ts
+function textResult(text, structured) {
+  return {
+    content: [{ type: "text", text }],
+    ...structured !== void 0 ? { structuredContent: structured } : {}
+  };
+}
+function errorResult(text) {
+  return { content: [{ type: "text", text }], isError: true };
+}
+var num = (v, fallback) => typeof v === "number" && Number.isFinite(v) ? v : 0;
+var str = (v, fallback = "") => typeof v === "string" ? v : fallback;
+var newId = (prefix) => `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 7)}`;
+function registerFlowBridge(server, options) {
+  const { adapter } = options;
+  ({ ...options.agent ?? {} });
+  const disposers = [];
+  const reg = (name, description, properties, required, handler) => {
+    disposers.push(
+      server.registerTool(
+        {
+          name,
+          description,
+          inputSchema: { type: "object", properties, required, additionalProperties: false }
+        },
+        async (args) => {
+          try {
+            return await handler(args);
+          } catch (e) {
+            return errorResult(e instanceof Error ? e.message : String(e));
+          }
+        }
+      )
+    );
+  };
+  reg("flow_get_state", "Get the full graph: nodes + edges.", {}, [], () => {
+    const state = { nodes: adapter.getNodes(), edges: adapter.getEdges() };
+    return textResult(JSON.stringify(state, null, 2), state);
+  });
+  reg("flow_list_nodes", "Summarise every node: id, kind, label, position, status.", {}, [], () => {
+    const items = adapter.getNodes().map((n) => ({
+      id: n.id,
+      kind: n.type,
+      label: n.data?.label,
+      x: Math.round(n.position.x),
+      y: Math.round(n.position.y),
+      status: n.data?.status ?? "idle"
+    }));
+    const text = items.map((i) => `${i.kind} ${i.id}: "${i.label}" @(${i.x},${i.y}) [${i.status}]`).join("\n") || "(empty graph)";
+    return textResult(text, items);
+  });
+  reg(
+    "flow_get_node",
+    "Get a single node's full record by id.",
+    { id: { type: "string" } },
+    ["id"],
+    (args) => {
+      const id = str(args.id);
+      const node = adapter.getNodes().find((n) => n.id === id);
+      if (!node) return errorResult(`No node with id ${id}`);
+      return textResult(JSON.stringify(node, null, 2), node);
+    }
+  );
+  reg(
+    "flow_list_node_kinds",
+    "List every node kind registered in fancy-flow's registry. Use this to discover what's authorable before adding nodes.",
+    { category: { type: "string", description: "Optional category filter: trigger | logic | data | ai | io | human | output | custom." } },
+    [],
+    async () => {
+      try {
+        const { listNodeKinds } = await import('@particle-academy/fancy-flow');
+        const cat = adapter ? void 0 : void 0;
+        const all = (cat ? listNodeKinds(cat) : listNodeKinds()).map((k) => ({
+          name: k.name,
+          category: k.category,
+          label: k.label,
+          description: k.description,
+          icon: k.icon,
+          accent: k.accent,
+          inputs: k.inputs ?? [],
+          outputs: k.outputs ?? [],
+          configFields: (k.configSchema ?? []).map((f) => ({ key: f.key, type: f.type, label: f.label, required: !!f.required }))
+        }));
+        const text = all.map((k) => `${k.category}/${k.name}: ${k.label}${k.description ? " \u2014 " + k.description : ""}`).join("\n");
+        return textResult(text || "(no kinds registered)", all);
+      } catch (e) {
+        return errorResult(`fancy-flow registry not available: ${e instanceof Error ? e.message : String(e)}`);
+      }
+    }
+  );
+  reg(
+    "flow_get_node_schema",
+    "Get the full configSchema + ports for a node kind. Use to know exactly what fields a kind accepts before calling flow_add_node.",
+    { name: { type: "string" } },
+    ["name"],
+    async (args) => {
+      try {
+        const { getNodeKind } = await import('@particle-academy/fancy-flow');
+        const k = getNodeKind(str(args.name));
+        if (!k) return errorResult(`No kind registered: ${args.name}`);
+        const summary = {
+          name: k.name,
+          category: k.category,
+          label: k.label,
+          description: k.description,
+          inputs: k.inputs ?? [],
+          outputs: k.outputs ?? [],
+          configSchema: k.configSchema ?? [],
+          defaultConfig: k.defaultConfig ?? null
+        };
+        return textResult(JSON.stringify(summary, null, 2), summary);
+      } catch (e) {
+        return errorResult(`fancy-flow registry not available: ${e instanceof Error ? e.message : String(e)}`);
+      }
+    }
+  );
+  reg("flow_list_edges", "Summarise every edge.", {}, [], () => {
+    const items = adapter.getEdges().map((e) => ({
+      id: e.id,
+      from: `${e.source}${e.sourceHandle ? `:${e.sourceHandle}` : ""}`,
+      to: `${e.target}${e.targetHandle ? `:${e.targetHandle}` : ""}`
+    }));
+    return textResult(items.map((i) => `${i.id}: ${i.from} \u2192 ${i.to}`).join("\n") || "(no edges)", items);
+  });
+  reg(
+    "flow_add_node",
+    "Add a node of any kind registered in fancy-flow's registry. Call flow_list_node_kinds first to discover what's available.",
+    {
+      kind: { type: "string", description: "Registry kind name (e.g. memory_store, llm_call, branch)." },
+      label: { type: "string" },
+      x: { type: "number" },
+      y: { type: "number" },
+      description: { type: "string" },
+      config: { type: "object", description: "Config fields per the kind's configSchema." },
+      body: { type: "string", description: "Note kinds only \u2014 body text." }
+    },
+    ["kind", "label", "x", "y"],
+    async (args) => {
+      const kindName = str(args.kind);
+      let kindDef = null;
+      try {
+        const { getNodeKind, defaultConfigFor } = await import('@particle-academy/fancy-flow');
+        kindDef = getNodeKind(kindName);
+        var defaults = kindDef ? defaultConfigFor(kindDef) : {};
+      } catch {
+        var defaults = {};
+      }
+      const isLegacy = ["trigger", "action", "decision", "output", "note", "subgraph"].includes(kindName);
+      if (!kindDef && !isLegacy) {
+        return errorResult(`Unknown kind: ${kindName} \u2014 call flow_list_node_kinds for the registry.`);
+      }
+      const id = newId("n");
+      const config = { ...defaults, ...args.config && typeof args.config === "object" ? args.config : {} };
+      const node = {
+        id,
+        type: kindName,
+        position: { x: num(args.x), y: num(args.y) },
+        data: {
+          kind: kindName,
+          label: str(args.label),
+          ...args.description ? { description: str(args.description) } : {},
+          config,
+          ...kindName === "note" && args.body ? { body: str(args.body) } : {}
+        }
+      };
+      adapter.setNodes((all) => [...all, node]);
+      return textResult(`Added ${kindName} ${id} ("${str(args.label)}")`, node);
+    }
+  );
+  reg(
+    "flow_update_node",
+    "Update fields on a node. Only provided fields change.",
+    {
+      id: { type: "string" },
+      label: { type: "string" },
+      x: { type: "number" },
+      y: { type: "number" },
+      description: { type: "string" },
+      config: { type: "object" }
+    },
+    ["id"],
+    (args) => {
+      const id = str(args.id);
+      let updated = null;
+      adapter.setNodes(
+        (all) => all.map((n) => {
+          if (n.id !== id) return n;
+          updated = {
+            ...n,
+            position: {
+              x: args.x !== void 0 ? num(args.x) : n.position.x,
+              y: args.y !== void 0 ? num(args.y) : n.position.y
+            },
+            data: {
+              ...n.data,
+              ...args.label !== void 0 ? { label: str(args.label) } : {},
+              ...args.description !== void 0 ? { description: str(args.description) } : {},
+              ...args.config && typeof args.config === "object" ? { config: { ...n.data.config ?? {}, ...args.config } } : {}
+            }
+          };
+          return updated;
+        })
+      );
+      if (!updated) return errorResult(`No node with id ${id}`);
+      return textResult(`Updated node ${id}`, updated);
+    }
+  );
+  reg(
+    "flow_delete_node",
+    "Remove a node by id (also removes any connected edges).",
+    { id: { type: "string" } },
+    ["id"],
+    (args) => {
+      const id = str(args.id);
+      if (!adapter.getNodes().some((n) => n.id === id)) {
+        return errorResult(`No node with id ${id}`);
+      }
+      adapter.setNodes((all) => all.filter((n) => n.id !== id));
+      adapter.setEdges((all) => all.filter((e) => e.source !== id && e.target !== id));
+      return textResult(`Deleted node ${id}`);
+    }
+  );
+  reg(
+    "flow_connect",
+    "Create an edge between two nodes (optionally specifying handle ids).",
+    {
+      source: { type: "string" },
+      target: { type: "string" },
+      sourceHandle: { type: "string" },
+      targetHandle: { type: "string" },
+      label: { type: "string" }
+    },
+    ["source", "target"],
+    (args) => {
+      const source = str(args.source);
+      const target = str(args.target);
+      const all = adapter.getNodes();
+      if (!all.find((n) => n.id === source)) return errorResult(`No source node ${source}`);
+      if (!all.find((n) => n.id === target)) return errorResult(`No target node ${target}`);
+      const edge = {
+        id: newId("e"),
+        source,
+        target,
+        ...args.sourceHandle ? { sourceHandle: str(args.sourceHandle) } : {},
+        ...args.targetHandle ? { targetHandle: str(args.targetHandle) } : {},
+        ...args.label ? { label: str(args.label) } : {}
+      };
+      adapter.setEdges((existing) => [...existing, edge]);
+      return textResult(`Connected ${source}${edge.sourceHandle ? `:${edge.sourceHandle}` : ""} \u2192 ${target}${edge.targetHandle ? `:${edge.targetHandle}` : ""}`, edge);
+    }
+  );
+  reg(
+    "flow_disconnect",
+    "Remove an edge by id.",
+    { id: { type: "string" } },
+    ["id"],
+    (args) => {
+      const id = str(args.id);
+      if (!adapter.getEdges().some((e) => e.id === id)) {
+        return errorResult(`No edge ${id}`);
+      }
+      adapter.setEdges((all) => all.filter((e) => e.id !== id));
+      return textResult(`Disconnected ${id}`);
+    }
+  );
+  reg(
+    "flow_set_node_status",
+    "Manually set a node's status badge (idle | queued | running | done | error) and optional text. Useful for narration outside a run.",
+    {
+      id: { type: "string" },
+      status: { type: "string", enum: ["idle", "queued", "running", "done", "error"] },
+      text: { type: "string" }
+    },
+    ["id", "status"],
+    (args) => {
+      const id = str(args.id);
+      const status = str(args.status);
+      const text = args.text !== void 0 ? str(args.text) : void 0;
+      if (adapter.setNodeStatus) {
+        adapter.setNodeStatus(id, status, text);
+      } else {
+        let found = false;
+        adapter.setNodes(
+          (all) => all.map((n) => {
+            if (n.id !== id) return n;
+            found = true;
+            return { ...n, data: { ...n.data, status, statusText: text } };
+          })
+        );
+        if (!found) return errorResult(`No node with id ${id}`);
+      }
+      return textResult(`${id} \u2192 ${status}${text ? ` (${text})` : ""}`);
+    }
+  );
+  reg(
+    "flow_run",
+    "Trigger a run of the current graph. Returns the topological result. Requires the host to have wired `run` into the adapter.",
+    {},
+    [],
+    async () => {
+      if (!adapter.run) return errorResult("Host did not provide a run handler.");
+      const result = await adapter.run();
+      return textResult(result.ok ? "Run complete" : `Run failed: ${result.error ?? "unknown"}`, result);
+    }
+  );
+  reg(
+    "flow_cancel",
+    "Cancel an in-flight run.",
+    {},
+    [],
+    () => {
+      if (!adapter.cancel) return errorResult("Host did not provide a cancel handler.");
+      adapter.cancel();
+      return textResult("Run cancelled");
+    }
+  );
+  return {
+    id: "flow",
+    title: "Flow",
+    dispose: () => {
+      for (const d of disposers) d();
+    }
+  };
+}
+
+exports.registerFlowBridge = registerFlowBridge;
+//# sourceMappingURL=bridges-flow.cjs.map
+//# sourceMappingURL=bridges-flow.cjs.map