@particle-academy/agent-integrations 0.3.4 → 0.4.0

package/dist/index.cjs

@@ -63,10 +63,43 @@ var JSONRPC_INVALID_PARAMS = -32602;
 var JSONRPC_INTERNAL_ERROR = -32603;
 var MCP_PROTOCOL_VERSION = "2025-06-18";
 
+// src/mcp/tool-host.ts
+var ToolRegistry = class {
+  constructor() {
+    this.tools = /* @__PURE__ */ new Map();
+  }
+  registerTool(definition, handler) {
+    this.tools.set(definition.name, { definition, handler });
+    this.onToolsChanged();
+    return () => {
+      if (this.tools.delete(definition.name)) this.onToolsChanged();
+    };
+  }
+  getTool(name) {
+    return this.tools.get(name) ?? null;
+  }
+  listTools() {
+    return Array.from(this.tools.values()).map((t) => t.definition);
+  }
+  async callTool(name, args = {}) {
+    const tool = this.tools.get(name);
+    if (!tool) {
+      throw new Error(`Unknown tool: ${name}`);
+    }
+    return tool.handler(args);
+  }
+  /**
+   * Hook for subclasses (e.g. MicroMcpServer) to notify subscribers
+   * when the tool catalog changes. Default no-op.
+   */
+  onToolsChanged() {
+  }
+};
+
 // src/mcp/server.ts
-var MicroMcpServer = class {
+var MicroMcpServer = class extends ToolRegistry {
   constructor(options) {
-    this.tools = /* @__PURE__ */ new Map();
+    super();
     this.transports = /* @__PURE__ */ new Set();
     this.notifyListChangedScheduled = false;
     this.info = options.info;
@@ -82,18 +115,13 @@ var MicroMcpServer = class {
       transport.close?.();
     }
   }
-  registerTool(definition, handler) {
-    this.tools.set(definition.name, { definition, handler });
-    this.scheduleListChangedNotification();
-    return () => this.unregisterTool(definition.name);
-  }
   unregisterTool(name) {
     if (this.tools.delete(name)) {
       this.scheduleListChangedNotification();
     }
   }
-  listTools() {
-    return Array.from(this.tools.values()).map((t) => t.definition);
+  onToolsChanged() {
+    this.scheduleListChangedNotification();
   }
   /**
    * Receive a JSON-RPC frame from a client (called by the transport).
@@ -325,18 +353,18 @@ function resetAllUndoStacks() {
 }
 
 // src/undo/undo-tools.ts
-var installedServers = /* @__PURE__ */ new WeakSet();
-function ensureUndoToolsRegistered(server, options = {}) {
-  if (installedServers.has(server)) return;
-  installedServers.add(server);
-  registerUndoTools(server, options);
+var installedHosts = /* @__PURE__ */ new WeakSet();
+function ensureUndoToolsRegistered(host, options = {}) {
+  if (installedHosts.has(host)) return;
+  installedHosts.add(host);
+  registerUndoTools(host, options);
 }
-function registerUndoTools(server, options = {}) {
+function registerUndoTools(host, options = {}) {
   const defaultAgent = options.defaultAgentId ?? "agent";
   const disposers = [];
   const agentOf = (args) => typeof args?.agentId === "string" ? args.agentId : defaultAgent;
   disposers.push(
-    server.registerTool(
+    host.registerTool(
       {
         name: "agent_undo",
         description: "Undo the most recent action on the agent's stack. Optional agentId targets a specific agent.",
@@ -354,7 +382,7 @@ function registerUndoTools(server, options = {}) {
     )
   );
   disposers.push(
-    server.registerTool(
+    host.registerTool(
       {
         name: "agent_redo",
         description: "Redo the most recently undone action.",
@@ -372,7 +400,7 @@ function registerUndoTools(server, options = {}) {
     )
   );
   disposers.push(
-    server.registerTool(
+    host.registerTool(
       {
         name: "agent_history",
         description: "List the agent's undo stack (oldest first). Useful for understanding what's reversible.",
@@ -407,11 +435,11 @@ var num = (v, fallback) => typeof v === "number" && Number.isFinite(v) ? v : fal
 var str = (v, fallback = "") => typeof v === "string" ? v : fallback;
 var bool = (v, fallback = false) => typeof v === "boolean" ? v : fallback;
 var newId = (prefix) => `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 7)}`;
-function registerWhiteboardBridge(server, options) {
+function registerWhiteboardBridge(host, options) {
   const { adapter } = options;
   const agent = { ...DEFAULT_AGENT, ...options.agent ?? {} };
   const disposers = [];
-  ensureUndoToolsRegistered(server, { defaultAgentId: agent.id });
+  ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });
   const wbTarget = (args, result) => ({
     kind: "whiteboard",
     elementId: result?.structuredContent?.id ?? args?.id
@@ -431,7 +459,7 @@ function registerWhiteboardBridge(server, options) {
       resolveTarget: ({ args, result }) => resolveTarget(args, result)
     }) : wrapped;
     disposers.push(
-      server.registerTool(
+      host.registerTool(
         {
           name,
           description,
@@ -834,7 +862,7 @@ var DEFAULT_AGENT2 = { id: "agent", name: "Agent", color: "#a855f7" };
 var num2 = (v, fallback) => typeof v === "number" && Number.isFinite(v) ? v : 0;
 var str2 = (v, fallback = "") => typeof v === "string" ? v : fallback;
 var newId2 = (prefix) => `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 7)}`;
-function registerFlowBridge(server, options) {
+function registerFlowBridge(host, options) {
   const { adapter } = options;
   const agent = { ...DEFAULT_AGENT2, ...options.agent ?? {} };
   const disposers = [];
@@ -857,7 +885,7 @@ function registerFlowBridge(server, options) {
       resolveTarget: ({ args, result }) => resolveTarget(args, result)
     }) : wrapped;
     disposers.push(
-      server.registerTool(
+      host.registerTool(
         {
           name,
           description,
@@ -1167,7 +1195,7 @@ function registerFlowBridge(server, options) {
 
 // src/bridges/forms.ts
 var DEFAULT_AGENT3 = { id: "agent", name: "Agent", color: "#a855f7" };
-function registerFormBridge(server, options) {
+function registerFormBridge(host, options) {
   const { adapter } = options;
   const agent = { ...DEFAULT_AGENT3, ...options.agent ?? {} };
   const disposers = [];
@@ -1194,7 +1222,7 @@ function registerFormBridge(server, options) {
       resolveTarget: ({ args }) => target(args)
     }) : wrapped;
     disposers.push(
-      server.registerTool(
+      host.registerTool(
         {
           name,
           description,
@@ -1319,7 +1347,7 @@ function registerFormBridge(server, options) {
 
 // src/bridges/sheets.ts
 var DEFAULT_AGENT4 = { id: "agent", name: "Agent", color: "#a855f7" };
-function registerSheetsBridge(server, options) {
+function registerSheetsBridge(host, options) {
   const { adapter } = options;
   const agent = { ...DEFAULT_AGENT4, ...options.agent ?? {} };
   const disposers = [];
@@ -1345,7 +1373,7 @@ function registerSheetsBridge(server, options) {
       resolveTarget: ({ args, result }) => resolveTarget?.(args, result) ?? target(getSheetId(args))
     }) : wrapped;
     disposers.push(
-      server.registerTool(
+      host.registerTool(
         {
           name,
           description,
@@ -1591,9 +1619,88 @@ function readRange(sheet, startAddr, endAddr) {
   return grid;
 }
 
+// src/sheets-adapter.ts
+init_registry();
+function useSheetsAdapter(initial, options = {}) {
+  const [workbook, setWorkbook] = react.useState(initial);
+  const [activeCell, setActiveCellState] = react.useState(null);
+  const workbookRef = react.useRef(workbook);
+  workbookRef.current = workbook;
+  const setActiveCell = react.useCallback((sheetId, address) => {
+    setWorkbook((cur) => cur.activeSheetId === sheetId ? cur : { ...cur, activeSheetId: sheetId });
+    setActiveCellState(address);
+  }, []);
+  const onActiveCellChange = react.useCallback((address) => {
+    setActiveCellState(address);
+  }, []);
+  const setWorkbookRef = react.useRef(setWorkbook);
+  setWorkbookRef.current = setWorkbook;
+  const adapter = react.useMemo(
+    () => ({
+      screenId: options.screenId,
+      getWorkbook: () => workbookRef.current,
+      setWorkbook: (next) => setWorkbookRef.current(next),
+      setActiveCell
+    }),
+    [options.screenId, setActiveCell]
+  );
+  return {
+    workbook,
+    setWorkbook,
+    onActiveCellChange,
+    adapter,
+    setActiveCell,
+    activeCell
+  };
+}
+function useSheetsActivityHighlights(options = {}) {
+  const ttlMs = options.ttlMs ?? 2200;
+  const screenId = options.screenId;
+  const [, force] = react.useState(0);
+  const hitsRef = react.useRef(/* @__PURE__ */ new Map());
+  react.useEffect(() => {
+    const off = onActivity((event) => {
+      if (event.target?.kind !== "sheet") return;
+      if (screenId && event.target.screenId && event.target.screenId !== screenId) return;
+      const elementId = event.target.elementId;
+      if (!elementId || !elementId.includes("!")) return;
+      hitsRef.current.set(elementId, { event, expiresAt: Date.now() + ttlMs });
+      force((n) => n + 1);
+    });
+    return off;
+  }, [screenId, ttlMs]);
+  react.useEffect(() => {
+    const t = window.setInterval(() => {
+      const now = Date.now();
+      let dirty = false;
+      for (const [k, v] of hitsRef.current) {
+        if (v.expiresAt < now) {
+          hitsRef.current.delete(k);
+          dirty = true;
+        }
+      }
+      if (dirty) force((n) => n + 1);
+    }, 500);
+    return () => window.clearInterval(t);
+  }, []);
+  const out = {};
+  for (const [elementId, { event }] of hitsRef.current) {
+    const idx = elementId.indexOf("!");
+    const address = elementId.slice(idx + 1);
+    if (!address) continue;
+    const color = event.agentColor ?? "#a855f7";
+    out[address] = {
+      color,
+      background: color + "33",
+      label: event.agentName ?? event.agentId ?? "agent"
+    };
+  }
+  return out;
+}
+
 // src/bridges/code.ts
 var DEFAULT_AGENT5 = { id: "agent", name: "Agent", color: "#a855f7" };
-function registerCodeBridge(server, options) {
+function registerCodeBridge(host, options) {
   const { adapter } = options;
   const agent = { ...DEFAULT_AGENT5, ...options.agent ?? {} };
   const disposers = [];
@@ -1619,7 +1726,7 @@ function registerCodeBridge(server, options) {
       resolveTarget: () => target
     }) : wrapped;
     disposers.push(
-      server.registerTool(
+      host.registerTool(
         {
           name,
           description,
@@ -1759,7 +1866,7 @@ function registerCodeBridge(server, options) {
 
 // src/bridges/charts.ts
 var DEFAULT_AGENT6 = { id: "agent", name: "Agent", color: "#a855f7" };
-function registerChartsBridge(server, options) {
+function registerChartsBridge(host, options) {
   const { adapter } = options;
   const agent = { ...DEFAULT_AGENT6, ...options.agent ?? {} };
   const disposers = [];
@@ -1785,7 +1892,7 @@ function registerChartsBridge(server, options) {
       resolveTarget: () => target
     }) : wrapped;
     disposers.push(
-      server.registerTool(
+      host.registerTool(
         { name, description, inputSchema: { type: "object", properties, required, additionalProperties: false } },
         final
       )
@@ -1873,7 +1980,7 @@ function registerChartsBridge(server, options) {
 
 // src/bridges/scene.ts
 var DEFAULT_AGENT7 = { id: "agent", name: "Agent", color: "#a855f7" };
-function registerSceneBridge(server, options) {
+function registerSceneBridge(host, options) {
   const { adapter } = options;
   const agent = { ...DEFAULT_AGENT7, ...options.agent ?? {} };
   const disposers = [];
@@ -1899,7 +2006,7 @@ function registerSceneBridge(server, options) {
       resolveTarget: ({ args }) => target(objectIdFromArgs?.(args))
     }) : wrapped;
     disposers.push(
-      server.registerTool(
+      host.registerTool(
         { name, description, inputSchema: { type: "object", properties, required, additionalProperties: false } },
         final
       )
@@ -2067,6 +2174,180 @@ function parseTriple(v) {
   if (out.some((x) => !Number.isFinite(x))) return void 0;
   return out;
 }
+
+// src/bridges/screens.ts
+var DEFAULT_AGENT8 = { id: "agent", name: "Agent", color: "#a855f7" };
+function registerScreensBridge(host, options) {
+  const { adapter } = options;
+  const agent = { ...DEFAULT_AGENT8, ...options.agent ?? {} };
+  const disposers = [];
+  const target = (screenId) => ({
+    kind: "screens",
+    screenId,
+    label: `Screen ${screenId}`
+  });
+  const reg = (name, description, properties, required, handler, isMutation, targetFromArgs) => {
+    const wrapped = async (args) => {
+      try {
+        return await handler(args);
+      } catch (e) {
+        return errorResult(e instanceof Error ? e.message : String(e));
+      }
+    };
+    const final = isMutation ? wrapToolWithActivity(wrapped, {
+      toolName: name,
+      agent,
+      kind: "screens",
+      resolveTarget: ({ args }) => targetFromArgs?.(args) ?? null
+    }) : wrapped;
+    disposers.push(
+      host.registerTool(
+        { name, description, inputSchema: { type: "object", properties, required, additionalProperties: false } },
+        final
+      )
+    );
+  };
+  reg(
+    "screens_list",
+    "List every screen the host has registered. Returns id, title, active flag, and optional kind.",
+    {},
+    [],
+    () => {
+      const screens = adapter.listScreens();
+      const text = screens.map((s) => `${s.active ? "\u25B8" : " "} ${s.id}${s.title ? ` \u2014 ${s.title}` : ""}${s.kind ? ` [${s.kind}]` : ""}`).join("\n");
+      return textResult(text || "(no screens)", { screens, active: adapter.getActive() });
+    },
+    false
+  );
+  reg(
+    "screens_describe_active",
+    "Get the currently-active screen id (or null).",
+    {},
+    [],
+    () => {
+      const active = adapter.getActive();
+      return textResult(active ?? "(none)", { active });
+    },
+    false
+  );
+  reg(
+    "screens_list_kinds",
+    "List the screen kinds (templates) the host knows how to instantiate. Use this before screens_create to know what's available.",
+    {},
+    [],
+    () => {
+      if (!adapter.listKinds) return errorResult("Host did not register a kind catalog. Cannot create screens dynamically.");
+      const kinds = adapter.listKinds();
+      const text = kinds.map((k) => `${k.kind}${k.label ? ` \u2014 ${k.label}` : ""}${k.description ? ` (${k.description})` : ""}`).join("\n");
+      return textResult(text || "(no kinds registered)", kinds);
+    },
+    false
+  );
+  reg(
+    "screens_create",
+    "Instantiate a new screen from a template kind + config. Switches the active view to the new screen.",
+    {
+      id: { type: "string", description: "Stable screen id. Must be unique." },
+      title: { type: "string" },
+      kind: { type: "string", description: "Template kind \u2014 call screens_list_kinds for the catalog." },
+      config: { type: "object", description: "Template-specific config (e.g. { fields: [...] } for a form)." }
+    },
+    ["id", "kind"],
+    (args) => {
+      if (!adapter.createScreen) return errorResult("Host did not provide createScreen.");
+      const id = String(args.id);
+      const kind = String(args.kind);
+      if (adapter.listScreens().find((s) => s.id === id)) {
+        return errorResult(`Screen ${id} already exists. Use screens_destroy first or pick a fresh id.`);
+      }
+      adapter.createScreen({
+        id,
+        title: typeof args.title === "string" ? args.title : void 0,
+        kind,
+        config: args.config && typeof args.config === "object" ? args.config : void 0
+      });
+      adapter.setActive(id);
+      return textResult(`Created ${kind} screen "${id}"`, { id, kind });
+    },
+    true,
+    (args) => target(String(args.id ?? ""))
+  );
+  reg(
+    "screens_destroy",
+    "Remove a previously-created screen. Active screen falls back to the first remaining one (or null).",
+    { id: { type: "string" } },
+    ["id"],
+    (args) => {
+      if (!adapter.destroyScreen) return errorResult("Host did not provide destroyScreen.");
+      const id = String(args.id);
+      if (!adapter.listScreens().find((s) => s.id === id)) {
+        return errorResult(`No screen with id ${id}`);
+      }
+      adapter.destroyScreen(id);
+      return textResult(`Destroyed screen ${id}`, { id });
+    },
+    true,
+    (args) => target(String(args.id ?? ""))
+  );
+  reg(
+    "screens_set_layout",
+    "Change the layout of an existing composite screen. Layouts: 'single', 'split-h' (left/right), 'split-v' (top/bottom), 'grid-2x2', 'stack' (tabs).",
+    {
+      id: { type: "string" },
+      layout: { type: "string", enum: ["single", "split-h", "split-v", "grid-2x2", "stack"] }
+    },
+    ["id", "layout"],
+    (args) => {
+      if (!adapter.updateScreenContent) return errorResult("Host did not provide updateScreenContent.");
+      adapter.updateScreenContent(String(args.id), { layout: String(args.layout) });
+      return textResult(`Layout of ${args.id} \u2192 ${args.layout}`, { id: args.id, layout: args.layout });
+    },
+    true,
+    (args) => target(String(args.id ?? ""))
+  );
+  reg(
+    "screens_update_content",
+    "Merge new config into an existing screen (e.g. add a field to a form, append a sheet column, change chart series).",
+    {
+      id: { type: "string" },
+      partial: { type: "object", description: "Shallow-merged into the screen's config." }
+    },
+    ["id", "partial"],
+    (args) => {
+      if (!adapter.updateScreenContent) return errorResult("Host did not provide updateScreenContent.");
+      const id = String(args.id);
+      const partial = args.partial && typeof args.partial === "object" ? args.partial : {};
+      adapter.updateScreenContent(id, partial);
+      return textResult(`Updated content of ${id}`, { id });
+    },
+    true,
+    (args) => target(String(args.id ?? ""))
+  );
+  reg(
+    "screens_navigate",
+    "Switch the human's view to a different screen. The host updates its router / tab state and re-renders.",
+    { screen: { type: "string", description: "Screen id to activate." } },
+    ["screen"],
+    (args) => {
+      const screenId = String(args.screen ?? "");
+      const screens = adapter.listScreens();
+      if (!screens.find((s) => s.id === screenId)) {
+        return errorResult(`No screen registered with id "${screenId}". Call screens_list first.`);
+      }
+      adapter.setActive(screenId);
+      return textResult(`Navigated to ${screenId}`, { screen: screenId });
+    },
+    true,
+    (args) => target(String(args.screen ?? ""))
+  );
+  return {
+    id: "screens",
+    title: "Screens",
+    dispose: () => {
+      for (const d of disposers) d();
+    }
+  };
+}
 function AgentPanel({ agent, activity, onSubmit, busy, actions, className, style }) {
   const scrollRef = react.useRef(null);
   const inputRef = react.useRef(null);
@@ -2612,14 +2893,14 @@ function attachSseRelay(server, options) {
   });
   return transport;
 }
-var DEFAULT_AGENT8 = { id: "agent", name: "Agent", color: "#a855f7" };
+var DEFAULT_AGENT9 = { id: "agent", name: "Agent", color: "#a855f7" };
 function SharedWhiteboard({
   initialNotes = [],
   initialShapes = [],
   initialConnectors = [],
   initialStrokes = [],
   initialViewport = { x: 0, y: 0, zoom: 1 },
-  agent = DEFAULT_AGENT8,
+  agent = DEFAULT_AGENT9,
   shareBaseUrl = "/whiteboard-share",
   onRegisterSession,
   showAgentPanel = true,
@@ -2948,6 +3229,7 @@ exports.ScreensActivityBridge = ScreensActivityBridge;
 exports.ShareControls = ShareControls;
 exports.SharedWhiteboard = SharedWhiteboard;
 exports.SseRelayTransport = SseRelayTransport;
+exports.ToolRegistry = ToolRegistry;
 exports.attachInProcess = attachInProcess;
 exports.attachRelay = attachRelay;
 exports.attachSseRelay = attachSseRelay;
@@ -2970,6 +3252,7 @@ exports.registerCodeBridge = registerCodeBridge;
 exports.registerFlowBridge = registerFlowBridge;
 exports.registerFormBridge = registerFormBridge;
 exports.registerSceneBridge = registerSceneBridge;
+exports.registerScreensBridge = registerScreensBridge;
 exports.registerSheetsBridge = registerSheetsBridge;
 exports.registerUndoTools = registerUndoTools;
 exports.registerWhiteboardBridge = registerWhiteboardBridge;
@@ -2980,6 +3263,8 @@ exports.textResult = textResult;
 exports.undoOne = undoOne;
 exports.useAgentActivity = useAgentActivity;
 exports.useAgentActivityForScreen = useAgentActivityForScreen;
+exports.useSheetsActivityHighlights = useSheetsActivityHighlights;
+exports.useSheetsAdapter = useSheetsAdapter;
 exports.useUndoStack = useUndoStack;
 exports.wrapToolWithActivity = wrapToolWithActivity;
 //# sourceMappingURL=index.cjs.map