@particle-academy/agent-integrations 0.8.0 → 0.9.1

package/README.md

@@ -1,5 +1,7 @@
 # @particle-academy/agent-integrations
 
+[![Fancified](art/fancified.svg)](https://particle.academy)
+
 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.
@@ -173,6 +175,12 @@ shuttles JSON-RPC frames — it doesn't run tools or hold state.
 - **`docs/relay-protocol.md`** — the on-the-wire JSON envelope, with notes on
   the three transports the protocol supports (Reverb, WebRTC, SSE+POST).
 
+The agent at the far end needs an MCP client. Beyond pasting the session URL
+into an existing one (Claude Code, Cursor, …), there's
+**[`mcp-relay-client`](https://github.com/Particle-Academy/mcp-relay-client)** —
+a single-file, zero-dependency client (bash / Python / TS / Go) built for these
+relay sessions: `curl -O …/connect.sh && bash connect.sh "<session-url>" tools`.
+
 Pattern (Reverb):
 
 ```ts

package/dist/bridges/artboard.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-CX3WFXgh.cjs';
-import { B as Bridge } from '../types-Cq5u8MJ8.cjs';
-import '../types-C2zdUpzn.cjs';
+import { T as ToolHost } from '../tool-host-BQuUygLF.cjs';
+import { B as Bridge } from '../types-CCSBGW9T.cjs';
+import '../types-aOQLTW0E.cjs';
 
 /**
  * Transport-level JSON shapes. These intentionally mirror fancy-artboard's

package/dist/bridges/artboard.d.ts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-DldwGNqR.js';
-import { B as Bridge } from '../types-DyaHnqNC.js';
-import '../types-C2zdUpzn.js';
+import { T as ToolHost } from '../tool-host-C8JMMGYq.js';
+import { B as Bridge } from '../types-DIVNcIQO.js';
+import '../types-aOQLTW0E.js';
 
 /**
  * Transport-level JSON shapes. These intentionally mirror fancy-artboard's

package/dist/bridges/charts.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-CX3WFXgh.cjs';
-import { B as Bridge } from '../types-Cq5u8MJ8.cjs';
-import '../types-C2zdUpzn.cjs';
+import { T as ToolHost } from '../tool-host-BQuUygLF.cjs';
+import { B as Bridge } from '../types-CCSBGW9T.cjs';
+import '../types-aOQLTW0E.cjs';
 
 /**
  * Adapter wires a single fancy-echarts chart to the bridge. Charts are

package/dist/bridges/charts.d.ts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-DldwGNqR.js';
-import { B as Bridge } from '../types-DyaHnqNC.js';
-import '../types-C2zdUpzn.js';
+import { T as ToolHost } from '../tool-host-C8JMMGYq.js';
+import { B as Bridge } from '../types-DIVNcIQO.js';
+import '../types-aOQLTW0E.js';
 
 /**
  * Adapter wires a single fancy-echarts chart to the bridge. Charts are

package/dist/bridges/code.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-CX3WFXgh.cjs';
-import { B as Bridge } from '../types-Cq5u8MJ8.cjs';
-import '../types-C2zdUpzn.cjs';
+import { T as ToolHost } from '../tool-host-BQuUygLF.cjs';
+import { B as Bridge } from '../types-CCSBGW9T.cjs';
+import '../types-aOQLTW0E.cjs';
 
 /**
  * Adapter the host wires to a fancy-code CodeEditor (typically via the

package/dist/bridges/code.d.ts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-DldwGNqR.js';
-import { B as Bridge } from '../types-DyaHnqNC.js';
-import '../types-C2zdUpzn.js';
+import { T as ToolHost } from '../tool-host-C8JMMGYq.js';
+import { B as Bridge } from '../types-DIVNcIQO.js';
+import '../types-aOQLTW0E.js';
 
 /**
  * Adapter the host wires to a fancy-code CodeEditor (typically via the

package/dist/bridges/flow.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-CX3WFXgh.cjs';
-import { B as Bridge } from '../types-Cq5u8MJ8.cjs';
-import '../types-C2zdUpzn.cjs';
+import { T as ToolHost } from '../tool-host-BQuUygLF.cjs';
+import { B as Bridge } from '../types-CCSBGW9T.cjs';
+import '../types-aOQLTW0E.cjs';
 
 type FlowNode = {
     id: string;

package/dist/bridges/flow.d.ts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-DldwGNqR.js';
-import { B as Bridge } from '../types-DyaHnqNC.js';
-import '../types-C2zdUpzn.js';
+import { T as ToolHost } from '../tool-host-C8JMMGYq.js';
+import { B as Bridge } from '../types-DIVNcIQO.js';
+import '../types-aOQLTW0E.js';
 
 type FlowNode = {
     id: string;

package/dist/bridges/forms.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-CX3WFXgh.cjs';
-import { B as Bridge } from '../types-Cq5u8MJ8.cjs';
-import '../types-C2zdUpzn.cjs';
+import { T as ToolHost } from '../tool-host-BQuUygLF.cjs';
+import { B as Bridge } from '../types-CCSBGW9T.cjs';
+import '../types-aOQLTW0E.cjs';
 
 /**
  * Field descriptor — what the host says about each form field. Mirrors the

package/dist/bridges/forms.d.ts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-DldwGNqR.js';
-import { B as Bridge } from '../types-DyaHnqNC.js';
-import '../types-C2zdUpzn.js';
+import { T as ToolHost } from '../tool-host-C8JMMGYq.js';
+import { B as Bridge } from '../types-DIVNcIQO.js';
+import '../types-aOQLTW0E.js';
 
 /**
  * Field descriptor — what the host says about each form field. Mirrors the

package/dist/bridges/scene.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-CX3WFXgh.cjs';
-import { B as Bridge } from '../types-Cq5u8MJ8.cjs';
-import '../types-C2zdUpzn.cjs';
+import { T as ToolHost } from '../tool-host-BQuUygLF.cjs';
+import { B as Bridge } from '../types-CCSBGW9T.cjs';
+import '../types-aOQLTW0E.cjs';
 
 /**
  * Loose Scene types — mirror the public surface of fancy-3d's Scene

package/dist/bridges/scene.d.ts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-DldwGNqR.js';
-import { B as Bridge } from '../types-DyaHnqNC.js';
-import '../types-C2zdUpzn.js';
+import { T as ToolHost } from '../tool-host-C8JMMGYq.js';
+import { B as Bridge } from '../types-DIVNcIQO.js';
+import '../types-aOQLTW0E.js';
 
 /**
  * Loose Scene types — mirror the public surface of fancy-3d's Scene

package/dist/bridges/screens.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-CX3WFXgh.cjs';
-import { B as Bridge } from '../types-Cq5u8MJ8.cjs';
-import '../types-C2zdUpzn.cjs';
+import { T as ToolHost } from '../tool-host-BQuUygLF.cjs';
+import { B as Bridge } from '../types-CCSBGW9T.cjs';
+import '../types-aOQLTW0E.cjs';
 
 /**
  * Loose snapshot of a screen — what's in fancy-screens' ScreenMeta plus

package/dist/bridges/screens.d.ts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-DldwGNqR.js';
-import { B as Bridge } from '../types-DyaHnqNC.js';
-import '../types-C2zdUpzn.js';
+import { T as ToolHost } from '../tool-host-C8JMMGYq.js';
+import { B as Bridge } from '../types-DIVNcIQO.js';
+import '../types-aOQLTW0E.js';
 
 /**
  * Loose snapshot of a screen — what's in fancy-screens' ScreenMeta plus

package/dist/bridges/sheets.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-CX3WFXgh.cjs';
-import { B as Bridge } from '../types-Cq5u8MJ8.cjs';
-import '../types-C2zdUpzn.cjs';
+import { T as ToolHost } from '../tool-host-BQuUygLF.cjs';
+import { B as Bridge } from '../types-CCSBGW9T.cjs';
+import '../types-aOQLTW0E.cjs';
 
 /**
  * Loose types — kept here so the bridge builds without a hard dep on

package/dist/bridges/sheets.d.ts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-DldwGNqR.js';
-import { B as Bridge } from '../types-DyaHnqNC.js';
-import '../types-C2zdUpzn.js';
+import { T as ToolHost } from '../tool-host-C8JMMGYq.js';
+import { B as Bridge } from '../types-DIVNcIQO.js';
+import '../types-aOQLTW0E.js';
 
 /**
  * Loose types — kept here so the bridge builds without a hard dep on

package/dist/bridges/slides.d.cts

@@ -1,8 +1,8 @@
 import { Deck, DeckOp } from '@particle-academy/fancy-slides';
 export { reduceDeck } from '@particle-academy/fancy-slides';
-import { T as ToolHost } from '../tool-host-CX3WFXgh.cjs';
-import { B as Bridge } from '../types-Cq5u8MJ8.cjs';
-import '../types-C2zdUpzn.cjs';
+import { T as ToolHost } from '../tool-host-BQuUygLF.cjs';
+import { B as Bridge } from '../types-CCSBGW9T.cjs';
+import '../types-aOQLTW0E.cjs';
 
 /**
  * Adapter — the bridge calls into these to read or change deck state. The

package/dist/bridges/slides.d.ts

@@ -1,8 +1,8 @@
 import { Deck, DeckOp } from '@particle-academy/fancy-slides';
 export { reduceDeck } from '@particle-academy/fancy-slides';
-import { T as ToolHost } from '../tool-host-DldwGNqR.js';
-import { B as Bridge } from '../types-DyaHnqNC.js';
-import '../types-C2zdUpzn.js';
+import { T as ToolHost } from '../tool-host-C8JMMGYq.js';
+import { B as Bridge } from '../types-DIVNcIQO.js';
+import '../types-aOQLTW0E.js';
 
 /**
  * Adapter — the bridge calls into these to read or change deck state. The

package/dist/bridges/whiteboard.d.cts

@@ -1,7 +1,7 @@
 import { StickyNoteItem, ShapeItem, ConnectorItem, Stroke, Viewport, RemoteCursor } from '@particle-academy/fancy-whiteboard';
-import { T as ToolHost } from '../tool-host-CX3WFXgh.cjs';
-import { B as Bridge } from '../types-Cq5u8MJ8.cjs';
-import '../types-C2zdUpzn.cjs';
+import { T as ToolHost } from '../tool-host-BQuUygLF.cjs';
+import { B as Bridge } from '../types-CCSBGW9T.cjs';
+import '../types-aOQLTW0E.cjs';
 
 /**
  * State accessors / mutators the bridge needs from the host. The host owns

package/dist/bridges/whiteboard.d.ts

@@ -1,7 +1,7 @@
 import { StickyNoteItem, ShapeItem, ConnectorItem, Stroke, Viewport, RemoteCursor } from '@particle-academy/fancy-whiteboard';
-import { T as ToolHost } from '../tool-host-DldwGNqR.js';
-import { B as Bridge } from '../types-DyaHnqNC.js';
-import '../types-C2zdUpzn.js';
+import { T as ToolHost } from '../tool-host-C8JMMGYq.js';
+import { B as Bridge } from '../types-DIVNcIQO.js';
+import '../types-aOQLTW0E.js';
 
 /**
  * State accessors / mutators the bridge needs from the host. The host owns

package/dist/bridges-artboard.cjs

@@ -1,5 +1,7 @@
 'use strict';
 
+var fancyAutoCommon = require('@particle-academy/fancy-auto-common');
+
 // src/mcp/server.ts
 function textResult(text, structured) {
   return {
@@ -10,10 +12,6 @@ function textResult(text, structured) {
 function errorResult(text) {
   return { content: [{ type: "text", text }], isError: true };
 }
-var listeners = /* @__PURE__ */ new Set();
-function emitActivity(event) {
-  for (const l of listeners) l(event);
-}
 
 // src/presence/wrap-tool-with-activity.ts
 function wrapToolWithActivity(handler, options) {
@@ -27,7 +25,7 @@ function wrapToolWithActivity(handler, options) {
       target = { kind: options.kind, screenId: options.screenId };
     }
     if (!target) return result;
-    emitActivity({
+    fancyAutoCommon.emitActivity({
       agentId: options.agent.id,
       agentName: options.agent.name,
       agentColor: options.agent.color,
@@ -48,43 +46,6 @@ function extractMeta(result) {
   return void 0;
 }
 
-// src/undo/undo-stack.ts
-var stacks = /* @__PURE__ */ new Map();
-var CAP = 200;
-function getStack(agentId) {
-  let s = stacks.get(agentId);
-  if (!s) {
-    s = { past: [], future: [] };
-    stacks.set(agentId, s);
-  }
-  return s;
-}
-function pushUndoEntry(agentId, entry) {
-  const s = getStack(agentId);
-  s.past.push(entry);
-  if (s.past.length > CAP) s.past.splice(0, s.past.length - CAP);
-  s.future.length = 0;
-}
-async function undoOne(agentId) {
-  const s = getStack(agentId);
-  const entry = s.past.pop();
-  if (!entry) return null;
-  await entry.undo();
-  s.future.push(entry);
-  return entry;
-}
-async function redoOne(agentId) {
-  const s = getStack(agentId);
-  const entry = s.future.pop();
-  if (!entry) return null;
-  await entry.redo();
-  s.past.push(entry);
-  return entry;
-}
-function readHistory(agentId) {
-  return getStack(agentId).past.slice();
-}
-
 // src/undo/undo-tools.ts
 var installedHosts = /* @__PURE__ */ new WeakSet();
 function ensureUndoToolsRegistered(host, options = {}) {
@@ -108,7 +69,7 @@ function registerUndoTools(host, options = {}) {
         }
       },
       async (args) => {
-        const entry = await undoOne(agentOf(args));
+        const entry = await fancyAutoCommon.undoOne(agentOf(args));
         if (!entry) return errorResult("Nothing to undo.");
         return textResult(`Undid: ${entry.label}`, { entry: serialize(entry) });
       }
@@ -126,7 +87,7 @@ function registerUndoTools(host, options = {}) {
         }
       },
       async (args) => {
-        const entry = await redoOne(agentOf(args));
+        const entry = await fancyAutoCommon.redoOne(agentOf(args));
         if (!entry) return errorResult("Nothing to redo.");
         return textResult(`Redid: ${entry.label}`, { entry: serialize(entry) });
       }
@@ -144,9 +105,9 @@ function registerUndoTools(host, options = {}) {
         }
       },
       async (args) => {
-        const history2 = readHistory(agentOf(args)).map(serialize);
-        const text = history2.map((e) => `${new Date(e.timestamp).toISOString()} ${e.bridgeId} ${e.action}: ${e.label}`).join("\n");
-        return textResult(text || "(empty)", history2);
+        const history = fancyAutoCommon.readHistory(agentOf(args)).map(serialize);
+        const text = history.map((e) => `${new Date(e.timestamp).toISOString()} ${e.bridgeId} ${e.action}: ${e.label}`).join("\n");
+        return textResult(text || "(empty)", history);
       }
     )
   );
@@ -272,7 +233,7 @@ function registerArtboardBridge(host, options) {
           (s) => s.id !== sectionId ? s : { ...s, pieces: [...s.pieces.slice(0, insertAt), piece, ...s.pieces.slice(insertAt)] }
         )
       }));
-      pushUndoEntry(agent.id, {
+      fancyAutoCommon.pushUndoEntry(agent.id, {
         timestamp: Date.now(),
         bridgeId: "artboard",
         action: "artboard_add_piece",
@@ -320,7 +281,7 @@ function registerArtboardBridge(host, options) {
           (s) => s.id !== sectionId ? s : { ...s, pieces: s.pieces.filter((p) => p.id !== pieceId) }
         )
       }));
-      pushUndoEntry(agent.id, {
+      fancyAutoCommon.pushUndoEntry(agent.id, {
         timestamp: Date.now(),
         bridgeId: "artboard",
         action: "artboard_remove_piece",
@@ -378,7 +339,7 @@ function registerArtboardBridge(host, options) {
           })
         };
       });
-      pushUndoEntry(agent.id, {
+      fancyAutoCommon.pushUndoEntry(agent.id, {
         timestamp: Date.now(),
         bridgeId: "artboard",
         action: "artboard_reorder_piece",
@@ -417,7 +378,7 @@ function registerArtboardBridge(host, options) {
         }))
       }));
       apply(label);
-      pushUndoEntry(agent.id, {
+      fancyAutoCommon.pushUndoEntry(agent.id, {
         timestamp: Date.now(),
         bridgeId: "artboard",
         action: "artboard_rename_piece",
@@ -447,7 +408,7 @@ function registerArtboardBridge(host, options) {
         }))
       }));
       apply(nextContent);
-      pushUndoEntry(agent.id, {
+      fancyAutoCommon.pushUndoEntry(agent.id, {
         timestamp: Date.now(),
         bridgeId: "artboard",
         action: "artboard_set_piece_content",
@@ -498,7 +459,7 @@ function registerArtboardBridge(host, options) {
       adapter.setValue((prev) => ({
         sections: [...prev.sections.slice(0, insertAt), section, ...prev.sections.slice(insertAt)]
       }));
-      pushUndoEntry(agent.id, {
+      fancyAutoCommon.pushUndoEntry(agent.id, {
         timestamp: Date.now(),
         bridgeId: "artboard",
         action: "artboard_add_section",
@@ -532,7 +493,7 @@ function registerArtboardBridge(host, options) {
         )
       }));
       apply(title, subtitle);
-      pushUndoEntry(agent.id, {
+      fancyAutoCommon.pushUndoEntry(agent.id, {
         timestamp: Date.now(),
         bridgeId: "artboard",
         action: "artboard_rename_section",