@particle-academy/agent-integrations 0.34.0 → 0.36.0

package/dist/components-shared-whiteboard.js

@@ -1,5 +1,5 @@
-import { ShareControls, AgentCursor, AgentActivityHighlight, AgentPanel } from './chunk-SJTLTITO.js';
-import { createSessionDescriptor, attachSseRelay } from './chunk-N6RLSLOF.js';
+import { ShareControls, AgentCursor, AgentActivityHighlight, AgentPanel } from './chunk-ABP2THQV.js';
+import { createSessionDescriptor, attachSseRelay } from './chunk-JDCB2NMM.js';
 import { attachInProcess } from './chunk-AFUULW5E.js';
 import { registerWhiteboardBridge } from './chunk-2U5JB6ZA.js';
 import './chunk-CT3LRNH7.js';

package/dist/index.cjs

@@ -4093,7 +4093,15 @@ function registerDocBridge(host, options) {
   const disposers = [];
   ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });
   let idSeq = 0;
-  const mintId = () => adapter.newId?.() ?? `${surface}-${idSeq += 1}`;
+  const mintId = () => {
+    if (adapter.newId) return adapter.newId();
+    const taken = adapter.get().nodes;
+    let id;
+    do
+      id = `${surface}-${idSeq += 1}`;
+    while (taken[id]);
+    return id;
+  };
   const target = (elementId) => ({ kind: surface, screenId: adapter.screenId, elementId });
   const pending = /* @__PURE__ */ new Map();
   function commit(op, label, targetId) {
@@ -4112,10 +4120,10 @@ function registerDocBridge(host, options) {
   }
   function submit(op, label, targetId) {
     if (stage(op) === "confirm") {
-      const id = `${surface}-pending-${idSeq += 1}`;
-      pending.set(id, { op, label, targetId });
-      options.onPending?.({ id, op, label });
-      return { staged: true, id };
+      const pendingId = `${surface}-pending-${idSeq += 1}`;
+      pending.set(pendingId, { op, label, targetId });
+      options.onPending?.({ id: pendingId, op, label });
+      return { staged: true, id: targetId, pendingId };
     }
     commit(op, label, targetId);
     return { staged: false, id: targetId };
@@ -4198,18 +4206,26 @@ function registerDocBridge(host, options) {
       type: { type: "string", description: "Node type discriminant." },
       parent: { type: ["string", "null"], description: "Parent id, or null for a root." },
       props: { type: "object", description: "JSON props bag." },
-      order: { type: "string", description: "Fractional order key (default: append)." }
+      order: { type: "string", description: "Fractional order key (default: append)." },
+      id: {
+        type: "string",
+        description: "Id for the new node. Supply a meaningful one if you intend to address this node later; omitted means one is minted for you. Must not already exist."
+      }
     },
     ["type"],
     (args) => {
       const tree = adapter.get();
       const parent = typeof args.parent === "string" ? args.parent : null;
-      const id = mintId();
+      const requested = typeof args.id === "string" ? args.id : void 0;
+      if (requested !== void 0 && tree.nodes[requested]) {
+        throw new Error(`Node ${requested} already exists \u2014 pick a different id or update it instead`);
+      }
+      const id = requested ?? mintId();
       const order = typeof args.order === "string" ? args.order : fancyDocCommons.appendOrder(tree, parent);
       const props = args.props && typeof args.props === "object" ? args.props : {};
       const node = makeNode({ id, type: String(args.type), parent, order }, props);
       const res = submit({ t: "insert", node }, `add ${args.type} ${id}`, id);
-      return { ...res, _text: res.staged ? `staged add ${id}` : `added ${id}` };
+      return { ...res, _text: res.staged ? `staged add ${id} \u2014 confirm ${res.pendingId}` : `added ${id}` };
     },
     true,
     (_args, result) => target(result.id)
@@ -4224,7 +4240,7 @@ function registerDocBridge(host, options) {
       if (!adapter.get().nodes[id]) throw new Error(`No node ${id}`);
       const patch = args.patch && typeof args.patch === "object" ? args.patch : {};
       const res = submit({ t: "set_props", id, patch }, `update ${id}`, id);
-      return { ...res, id, _text: res.staged ? `staged update ${id}` : `updated ${id}` };
+      return { ...res, id, _text: res.staged ? `staged update ${id} \u2014 confirm ${res.pendingId}` : `updated ${id}` };
     },
     true,
     (args) => target(String(args.id))
@@ -4240,7 +4256,7 @@ function registerDocBridge(host, options) {
       if (!tree.nodes[id]) throw new Error(`No node ${id}`);
       const count = fancyDocCommons.descendantsOf(tree, id).length + 1;
       const res = submit({ t: "remove", id }, `remove ${id} (${count} node${count === 1 ? "" : "s"})`, id);
-      return { ...res, id, removed: count, _text: res.staged ? `staged remove ${id}` : `removed ${id}` };
+      return { ...res, id, removed: count, _text: res.staged ? `staged remove ${id} \u2014 confirm ${res.pendingId}` : `removed ${id}` };
     },
     true,
     (args) => target(String(args.id))
@@ -4257,7 +4273,7 @@ function registerDocBridge(host, options) {
       const parent = args.parent === null ? null : typeof args.parent === "string" ? args.parent : tree.nodes[id].parent;
       const order = typeof args.order === "string" ? args.order : fancyDocCommons.appendOrder(tree, parent);
       const res = submit({ t: "move", id, parent, order }, `move ${id}`, id);
-      return { ...res, id, _text: res.staged ? `staged move ${id}` : `moved ${id}` };
+      return { ...res, id, _text: res.staged ? `staged move ${id} \u2014 confirm ${res.pendingId}` : `moved ${id}` };
     },
     true,
     (args) => target(String(args.id))
@@ -4273,7 +4289,7 @@ function registerDocBridge(host, options) {
         if (built && typeof built === "object" && "error" in built) throw new Error(built.error);
         const tid = t.targetId?.(args);
         const res = submit(built, `${t.verb} ${tid ?? ""}`.trim(), tid);
-        return { ...res, id: tid, _text: res.staged ? `staged ${t.verb}` : t.verb };
+        return { ...res, id: tid, _text: res.staged ? `staged ${t.verb} \u2014 confirm ${res.pendingId}` : t.verb };
       },
       true,
       (args) => target(t.targetId?.(args))
@@ -4281,8 +4297,8 @@ function registerDocBridge(host, options) {
   }
   reg(
     "confirm",
-    "Apply a staged op by its pending id (from a staged mutation).",
-    { id: { type: "string" } },
+    "Apply a staged op. Pass the `pendingId` a staged mutation returned \u2014 not the node `id` it also returns.",
+    { id: { type: "string", description: "The `pendingId` from a staged mutation." } },
     ["id"],
     (args) => {
       const id = String(args.id);
@@ -4297,8 +4313,8 @@ function registerDocBridge(host, options) {
   );
   reg(
     "reject",
-    "Discard a staged op by its pending id.",
-    { id: { type: "string" } },
+    "Discard a staged op. Pass the `pendingId` a staged mutation returned \u2014 not the node `id` it also returns.",
+    { id: { type: "string", description: "The `pendingId` from a staged mutation." } },
     ["id"],
     (args) => {
       const id = String(args.id);
@@ -4390,6 +4406,90 @@ function registerCmsBridge(host, options) {
     ]
   });
 }
+var SCREEN_TEXT_NODE_TYPE = "#text";
+function registerScreenDocBridge(host, options) {
+  const { adapter } = options;
+  const surface = options.surface ?? "screen";
+  const setText = {
+    verb: "set_text",
+    description: "Replace the literal text of an element node \u2014 the natural way to change a label, heading or paragraph. Pass the ELEMENT's id, not the text node's.",
+    properties: {
+      id: { type: "string", description: "Id of the element whose text to set." },
+      text: { type: "string" }
+    },
+    required: ["id", "text"],
+    build: (args, tree) => {
+      const id = String(args.id);
+      const node = tree.nodes[id];
+      if (!node) return { error: `No node ${id}` };
+      if (node.type === SCREEN_TEXT_NODE_TYPE) {
+        return { t: "set_props", id, patch: { value: String(args.text) } };
+      }
+      const texts = fancyDocCommons.childrenOf(tree, id).filter((c) => c.type === SCREEN_TEXT_NODE_TYPE);
+      if (texts.length === 1) {
+        return { t: "set_props", id: texts[0].id, patch: { value: String(args.text) } };
+      }
+      if (texts.length === 0) {
+        return {
+          t: "insert",
+          node: {
+            id: `${id}-text`,
+            type: SCREEN_TEXT_NODE_TYPE,
+            parent: id,
+            order: fancyDocCommons.appendOrder(tree, id),
+            props: { value: String(args.text) }
+          }
+        };
+      }
+      return {
+        error: `Node ${id} has ${texts.length} text children (${texts.map((t) => t.id).join(", ")}) \u2014 set_text on the one you mean`
+      };
+    },
+    targetId: (args) => String(args.id)
+  };
+  const bridge = registerDocBridge(host, {
+    adapter,
+    surface,
+    agent: options.agent,
+    stagePolicy: options.stagePolicy,
+    onPending: options.onPending,
+    // Anything the AGENT adds is authored by definition — it chose or was given
+    // the id — so it must not inherit the synthetic flag from its neighbours.
+    makeNode: ({ id, type, parent, order }, props) => ({ id, type, parent, order, props }),
+    describeNode: (n) => ({
+      id: n.id,
+      type: n.type,
+      parent: n.parent,
+      ...n.synthetic ? { synthetic: true } : {},
+      ...n.type === SCREEN_TEXT_NODE_TYPE ? { text: String(n.props?.value ?? "") } : { props: Object.keys(n.props ?? {}) }
+    }),
+    opTools: [setText]
+  });
+  const disposeAddressable = host.registerTool(
+    {
+      name: `${surface}_addressable`,
+      description: "List the node ids that are safe to remember and use later. Ids NOT listed here were minted from a node's position: they resolve today and silently point at a different node once a sibling is inserted above them. Address those in the same turn you read them, and never store one.",
+      inputSchema: { type: "object", properties: {}, required: [], additionalProperties: false }
+    },
+    (async () => {
+      const nodes = Object.values(adapter.get().nodes);
+      const authored = nodes.filter((n) => !n.synthetic).map((n) => ({ id: n.id, type: n.type }));
+      const syntheticCount = nodes.length - authored.length;
+      return textResult(
+        authored.length ? `${authored.length} addressable, ${syntheticCount} positional` : `no addressable ids \u2014 all ${syntheticCount} nodes are positional`,
+        { addressable: authored, syntheticCount }
+      );
+    })
+  );
+  return {
+    id: surface,
+    title: "Screen content",
+    dispose: () => {
+      disposeAddressable();
+      bridge.dispose();
+    }
+  };
+}
 
 // src/sharing/token.ts
 var TOKEN_BYTES = 24;
@@ -4457,6 +4557,7 @@ var SseRelayTransport = class {
     this.listeners = /* @__PURE__ */ new Set();
     this.state = "idle";
     this.peers = /* @__PURE__ */ new Set();
+    this.peerListeners = /* @__PURE__ */ new Set();
     this.opts = options;
     this.expectedToken = options.token;
   }
@@ -4517,6 +4618,8 @@ var SseRelayTransport = class {
     this.es?.close();
     this.es = void 0;
     this.connected = false;
+    this.peers.clear();
+    this.notifyPeers();
     this.setState("closed");
   }
   onStateChange(listener) {
@@ -4524,6 +4627,28 @@ var SseRelayTransport = class {
     listener(this.state);
     return () => this.listeners.delete(listener);
   }
+  /** How many remote peers (agents) are currently attached to this session. */
+  peerCount() {
+    return this.peers.size;
+  }
+  /**
+   * Subscribe to peer arrivals/departures. Fires immediately with the current
+   * count.
+   *
+   * This is the ONLY honest answer to "is an agent actually here?".
+   * `onStateChange` reports the BROWSER's own channel to the relay, which opens
+   * the instant sharing starts — so a UI keyed on it announces "Agent is
+   * driving" to a human who has not yet handed the link to anybody, and can
+   * never tell them when one really arrives.
+   */
+  onPeersChange(listener) {
+    this.peerListeners.add(listener);
+    listener(this.peers.size);
+    return () => this.peerListeners.delete(listener);
+  }
+  notifyPeers() {
+    for (const l of this.peerListeners) l(this.peers.size);
+  }
   /**
    * For relays that wrap each frame with auth metadata: hosts can call this
    * directly when a frame arrives via a non-SSE path. The transport will
@@ -4558,6 +4683,7 @@ var SseRelayTransport = class {
     if ("method" in message && message.method === "notifications/peer_joined") {
       const subscriberId = String(message.params?.subscriberId ?? "peer");
       this.peers.add(subscriberId);
+      this.notifyPeers();
       fancyAutoCommon.emitActivity({
         agentId: "agent",
         agentName: "Agent",
@@ -4572,6 +4698,7 @@ var SseRelayTransport = class {
     if ("method" in message && message.method === "notifications/peer_left") {
       const subscriberId = String(message.params?.subscriberId ?? "peer");
       this.peers.delete(subscriberId);
+      this.notifyPeers();
       if (this.peers.size === 0) {
         fancyAutoCommon.emitActivity({
           agentId: "agent",
@@ -4629,6 +4756,7 @@ function useCoBrowseSession(options) {
   const disposeBridge = react.useRef(null);
   const [session, setSession] = react.useState(null);
   const [relayState, setRelayState] = react.useState("idle");
+  const [agentCount, setAgentCount] = react.useState(0);
   react.useEffect(() => {
     const server = new MicroMcpServer({
       info: options.info ?? { name: "fancy-co-browse", version: "0.1.0" },
@@ -4663,6 +4791,7 @@ function useCoBrowseSession(options) {
     }
     const relay = attachSseRelay(server, { baseUrl: relayBaseUrl, sessionId: descriptor.id, token: descriptor.token });
     relay.onStateChange(setRelayState);
+    relay.onPeersChange(setAgentCount);
     relayRef.current = relay;
     setSession(descriptor);
   }, [relayBaseUrl, options]);
@@ -4671,6 +4800,7 @@ function useCoBrowseSession(options) {
     relayRef.current?.close();
     relayRef.current = null;
     setRelayState("idle");
+    setAgentCount(0);
     setSession(null);
     if (current) {
       const csrf = options.csrfToken?.() ?? "";
@@ -4693,7 +4823,16 @@ function useCoBrowseSession(options) {
       meta: event
     });
   }, []);
-  return { server: serverRef.current, session, relayState, startShare, stopShare, observeUser };
+  return {
+    server: serverRef.current,
+    session,
+    relayState,
+    agentConnected: agentCount > 0,
+    agentCount,
+    startShare,
+    stopShare,
+    observeUser
+  };
 }
 function AgentPanel({ agent, activity, onSubmit, busy, actions, className, style }) {
   const scrollRef = react.useRef(null);
@@ -5416,10 +5555,12 @@ function ManualPopover({
     /* @__PURE__ */ jsxRuntime.jsx("button", { type: "button", className: "fai-connect__copy-btn", onClick: onCopy, children: copied ? "Copied" : "Copy snippet" })
   ] });
 }
+var LIFECYCLE_ACTIONS = /* @__PURE__ */ new Set(["agent_connected", "agent_disconnected"]);
 function CoBrowsePresence({ session, connectUrl, shareBaseUrl, className }) {
   const { events } = useAgentActivity(void 0, { capacity: 40 });
-  const lastAgentAction = [...events].reverse().find((e) => (e.source ?? "agent") !== "user");
-  const connected = session.relayState === "open";
+  const lastAgentAction = [...events].reverse().find((e) => (e.source ?? "agent") !== "user" && !LIFECYCLE_ACTIONS.has(e.action));
+  const connected = session.agentConnected;
+  const activity = react.useMemo(() => events.map(toPanelActivity), [events]);
   if (!session.session) {
     return /* @__PURE__ */ jsxRuntime.jsx("div", { className, "data-co-browse-presence": "idle", children: /* @__PURE__ */ jsxRuntime.jsx("button", { type: "button", onClick: () => void session.startShare(), "data-co-browse-start": true, children: "Let an agent drive" }) });
   }
@@ -5437,12 +5578,25 @@ function CoBrowsePresence({ session, connectUrl, shareBaseUrl, className }) {
         onStart: () => void session.startShare(),
         onStop: session.stopShare,
         status: session.relayState,
+        agentConnected: connected,
+        activity,
         shareBaseUrl
       }
     ),
     connectUrl && /* @__PURE__ */ jsxRuntime.jsx(ConnectorButtons, { serverName: "Fancy UI co-browse", mcpUrl: connectUrl })
   ] });
 }
+function toPanelActivity(event) {
+  const who = (event.source ?? "agent") === "user" ? "You" : event.agentName ?? "Agent";
+  return {
+    id: `${event.timestamp}-${event.action}-${event.target?.elementId ?? event.target?.label ?? ""}`,
+    at: event.timestamp,
+    kind: LIFECYCLE_ACTIONS.has(event.action) ? "info" : "tool",
+    source: who,
+    text: event.target?.label ?? event.action,
+    detail: event.meta
+  };
+}
 CoBrowsePresence.displayName = "CoBrowsePresence";
 var CURSOR_EDGE_INSET = 24;
 var FLUID_CURSOR_SPEED_PX_PER_SECOND = 1050;
@@ -5461,19 +5615,26 @@ function fluidGlideDuration(from, to) {
   const distance = Math.hypot(to.x - from.x, to.y - from.y);
   return Math.round(Math.min(MAX_GLIDE_MS, Math.max(MIN_GLIDE_MS, distance / FLUID_CURSOR_SPEED_PX_PER_SECOND * 1e3)));
 }
-function CoBrowseCursorLayer({ active = true, zIndex = 2147483e3 }) {
+var LIFECYCLE_ACTIONS2 = /* @__PURE__ */ new Set(["agent_connected", "agent_disconnected"]);
+function CoBrowseCursorLayer({
+  active = true,
+  zIndex = 2147483e3,
+  idleAfterMs = 15e3
+}) {
   const { latest } = useAgentActivity(void 0, { capacity: 12 });
   const [cursor, setCursor] = react.useState(
     null
   );
   const [pulse, setPulse] = react.useState(null);
+  const [lastActionAt, setLastActionAt] = react.useState(0);
   react.useEffect(() => {
     if (!latest || (latest.source ?? "agent") === "user") return;
-    if (latest.action === "agent_disconnected") {
-      setCursor((prev) => prev ? { ...prev, status: "Standing by", glideMs: 0 } : prev);
+    if (LIFECYCLE_ACTIONS2.has(latest.action)) {
+      setCursor((prev) => prev ? { ...prev, status: "Standing by", glideMs: 0 } : null);
       setPulse(null);
       return;
     }
+    setLastActionAt(latest.timestamp);
     const color = latest.agentColor ?? "#a855f7";
     const name = latest.agentName ?? "Agent";
     const status = latest.target?.label ?? latest.action;
@@ -5495,6 +5656,14 @@ function CoBrowseCursorLayer({ active = true, zIndex = 2147483e3 }) {
       );
     }
   }, [latest?.timestamp]);
+  react.useEffect(() => {
+    if (!idleAfterMs || !lastActionAt) return;
+    const timer = setTimeout(() => {
+      setCursor(null);
+      setPulse(null);
+    }, idleAfterMs);
+    return () => clearTimeout(timer);
+  }, [lastActionAt, idleAfterMs]);
   if (!active || !cursor || typeof document === "undefined") return null;
   return reactDom.createPortal(
     /* @__PURE__ */ jsxRuntime.jsxs("div", { "data-co-browse-cursor-layer": "", style: { position: "fixed", inset: 0, pointerEvents: "none", zIndex }, children: [
@@ -5842,6 +6011,7 @@ exports.MemoryHumanPlusEventStore = MemoryHumanPlusEventStore;
 exports.MicroMcpServer = MicroMcpServer;
 exports.PASSKEY_BRIDGE_TOOLS = PASSKEY_BRIDGE_TOOLS;
 exports.RelayTransport = RelayTransport;
+exports.SCREEN_TEXT_NODE_TYPE = SCREEN_TEXT_NODE_TYPE;
 exports.ScreensActivityBridge = ScreensActivityBridge;
 exports.ShareControls = ShareControls;
 exports.SimulateUsersButton = SimulateUsersButton;
@@ -5884,6 +6054,7 @@ exports.registerMapBridge = registerMapBridge;
 exports.registerNavigationBridge = registerNavigationBridge;
 exports.registerPasskeyBridge = registerPasskeyBridge;
 exports.registerSceneBridge = registerSceneBridge;
+exports.registerScreenDocBridge = registerScreenDocBridge;
 exports.registerScreensBridge = registerScreensBridge;
 exports.registerSheetsBridge = registerSheetsBridge;
 exports.registerSlidesBridge = registerSlidesBridge;