@particle-academy/agent-integrations 0.28.1 → 0.29.0

package/dist/index.cjs

@@ -112,7 +112,7 @@ var MicroMcpServer = class extends ToolRegistry {
     }
     const request = message;
     try {
-      const result = await this.handle(request);
+      const result = await this.handle(request, transport);
       transport.send({ jsonrpc: "2.0", id: request.id, result });
     } catch (err) {
       transport.send({
@@ -122,7 +122,7 @@ var MicroMcpServer = class extends ToolRegistry {
       });
     }
   }
-  async handle(request) {
+  async handle(request, transport) {
     const { method, params } = request;
     switch (method) {
       case "initialize":
@@ -144,7 +144,7 @@ var MicroMcpServer = class extends ToolRegistry {
         if (!tool) {
           throw rpcError(JSONRPC_METHOD_NOT_FOUND, `Unknown tool: ${name}`);
         }
-        const result = await tool.handler(args);
+        const result = await tool.handler(args, { transport });
         return result;
       }
       case "ping":
@@ -161,6 +161,11 @@ var MicroMcpServer = class extends ToolRegistry {
       this.broadcast({ jsonrpc: "2.0", method: "notifications/tools/list_changed" });
     });
   }
+  /** Send an application notification to every client, or one attached transport. */
+  notify(message, transport) {
+    if (transport) transport.send(message);
+    else this.broadcast(message);
+  }
   broadcast(message) {
     for (const t of this.transports) t.send(message);
   }
@@ -252,6 +257,50 @@ function attachRelay(server, channel) {
   return transport;
 }
 
+// src/human-plus/events.ts
+var MemoryHumanPlusEventStore = class {
+  constructor() {
+    this.events = [];
+    this.acknowledgements = /* @__PURE__ */ new Map();
+    this.listeners = /* @__PURE__ */ new Set();
+    this.nextSequence = 1;
+  }
+  async append(input) {
+    const event = { ...input, id: input.id ?? globalThis.crypto.randomUUID(), timestamp: input.timestamp ?? Date.now(), sequence: this.nextSequence++ };
+    this.events.push(event);
+    this.listeners.forEach((listener) => listener(event));
+    return event;
+  }
+  async list(query) {
+    const acknowledged = this.acknowledgements.get(query.consumerId);
+    const events = this.events.filter((event) => event.sequence > (query.after ?? 0) && (!query.unacknowledgedOnly || !acknowledged?.has(event.id)) && (!query.types?.length || query.types.includes(event.type)) && (!query.surfaces?.length || query.surfaces.includes(event.surfaceId))).slice(0, Math.max(1, Math.min(500, query.limit ?? 50)));
+    return { events, nextCursor: events.at(-1)?.sequence ?? query.after ?? 0 };
+  }
+  async acknowledge(consumerId, eventIds, disposition) {
+    let values = this.acknowledgements.get(consumerId);
+    if (!values) {
+      values = /* @__PURE__ */ new Map();
+      this.acknowledgements.set(consumerId, values);
+    }
+    eventIds.forEach((id) => values.set(id, disposition));
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  async compact(options = {}) {
+    const cutoff = options.before ?? Number.POSITIVE_INFINITY;
+    const keep = options.keepLast ?? 1e3;
+    const removable = Math.max(0, this.events.length - keep);
+    this.events = this.events.filter((event, index) => index >= removable || event.timestamp >= cutoff);
+    const ids = new Set(this.events.map((event) => event.id));
+    for (const values of this.acknowledgements.values()) for (const id of values.keys()) if (!ids.has(id)) values.delete(id);
+  }
+};
+
+// src/presence/index.ts
+init_registry();
+
 // src/presence/wrap-tool-with-activity.ts
 init_registry();
 function wrapToolWithActivity(handler, options) {
@@ -286,6 +335,133 @@ function extractMeta(result) {
   return void 0;
 }
 
+// src/presence/use-agent-activity.ts
+init_registry();
+function useAgentActivity(filter, options = {}) {
+  const cap = options.capacity ?? 50;
+  const [events, setEvents] = react.useState(() => fancyAutoCommon.readActivityHistory(filter).slice(-cap));
+  react.useEffect(() => {
+    setEvents(fancyAutoCommon.readActivityHistory(filter).slice(-cap));
+    return fancyAutoCommon.onActivity((event) => {
+      setEvents((prev) => {
+        const next = prev.length >= cap ? prev.slice(prev.length - cap + 1) : prev.slice();
+        next.push(event);
+        return next;
+      });
+    }, filter);
+  }, [filter?.agentId, filter?.screenId, filter?.kind, cap]);
+  return { events, latest: events.length > 0 ? events[events.length - 1] : null };
+}
+function useAgentActivityForScreen(screenId, options = {}) {
+  const { events, latest } = useAgentActivity({ screenId }, options);
+  const fadeAfter = latest?.ttlMs ?? 1500;
+  const [isAgentActive, setActive] = react.useState(false);
+  react.useEffect(() => {
+    if (!latest) {
+      setActive(false);
+      return;
+    }
+    setActive(true);
+    const timer = setTimeout(() => setActive(false), fadeAfter);
+    return () => clearTimeout(timer);
+  }, [latest, fadeAfter]);
+  return { events, latest, isAgentActive };
+}
+
+// src/bridges/tui.ts
+function registerTuiBridge(host, options) {
+  const disposers = [];
+  const subscriptions = /* @__PURE__ */ new Map();
+  const pending = /* @__PURE__ */ new Map();
+  const defaultActor = options.actor ?? { kind: "agent", id: "agent", name: "Agent" };
+  const serverCapabilities = host.capabilities;
+  if (serverCapabilities) serverCapabilities.experimental = { ...serverCapabilities.experimental, "io.particle-academy/human-plus": { version: "1", push: true, durableCursor: true, stagedActions: true, wakesAgent: false } };
+  const register = (name, description, properties, required, handler) => {
+    disposers.push(host.registerTool({ name, description, inputSchema: { type: "object", properties, required } }, async (args, context) => {
+      try {
+        const result = await handler(args, context);
+        return textResult(typeof result === "string" ? result : JSON.stringify(result), result);
+      } catch (error) {
+        return errorResult(error instanceof Error ? error.message : String(error));
+      }
+    }));
+  };
+  const publish = async (surfaceId, type, payload, actor = defaultActor, priority = "normal") => options.eventStore.append({ appId: options.appId, sessionId: options.sessionId, surfaceId, type, payload, actor, priority });
+  register("tui_surfaces_list", "List addressable Fancy TUI surfaces and commands.", {}, [], () => options.registry.list().map((surface) => ({ id: surface.id, kind: surface.kind, label: surface.label, commands: surface.commands?.map((command) => ({ name: command.name, description: command.description, policy: command.policy ?? "execute", inputSchema: command.inputSchema })) ?? [] })));
+  register("tui_surface_read", "Read a Fancy TUI surface by stable id.", { id: { type: "string" } }, ["id"], (args) => {
+    const surface = options.registry.get(String(args.id));
+    if (!surface) throw new Error(`Unknown TUI surface: ${String(args.id)}`);
+    return { id: surface.id, kind: surface.kind, state: surface.read() };
+  });
+  register("tui_action_invoke", "Invoke or propose an action on a Fancy TUI surface.", { surfaceId: { type: "string" }, command: { type: "string" }, input: { type: "object" } }, ["surfaceId", "command"], async (args) => {
+    const surfaceId = String(args.surfaceId);
+    const commandName = String(args.command);
+    const surface = options.registry.get(surfaceId);
+    if (!surface) throw new Error(`Unknown TUI surface: ${surfaceId}`);
+    const command = surface.commands?.find((value) => value.name === commandName);
+    if (!command) throw new Error(`Unknown command '${commandName}' on ${surfaceId}`);
+    const policy = command.policy ?? "execute";
+    if (policy === "observe" || policy === "human-only") throw new Error(`Action ${surfaceId}.${commandName} is ${policy}`);
+    const input = args.input && typeof args.input === "object" && !Array.isArray(args.input) ? args.input : {};
+    if (policy === "propose" || policy === "confirm") {
+      const id = globalThis.crypto.randomUUID();
+      pending.set(id, { id, surfaceId, command: commandName, input, actor: defaultActor });
+      await publish(surfaceId, "action.proposed", { id, command: commandName, input }, defaultActor, "attention");
+      return { pending: true, id };
+    }
+    const result = await command.invoke(input);
+    await publish(surfaceId, "action.executed", { command: commandName, input, result });
+    fancyAutoCommon.emitActivity({ agentId: defaultActor.id, agentName: defaultActor.name, target: { kind: "custom", elementId: surfaceId }, action: `tui_${commandName}`, timestamp: Date.now(), meta: { surfaceId } });
+    return { executed: true, result };
+  });
+  register("tui_action_confirm", "Confirm and execute a pending TUI action.", { id: { type: "string" } }, ["id"], async (args) => {
+    const id = String(args.id);
+    const value = pending.get(id);
+    if (!value) throw new Error(`Unknown pending action: ${id}`);
+    const surface = options.registry.get(value.surfaceId);
+    const command = surface?.commands?.find((x) => x.name === value.command);
+    if (!command) throw new Error("Pending action target is no longer available");
+    pending.delete(id);
+    const result = await command.invoke(value.input);
+    await publish(value.surfaceId, "action.confirmed", { id, command: value.command, result }, { kind: "human", id: "human" });
+    return { executed: true, result };
+  });
+  register("tui_action_reject", "Reject a pending TUI action.", { id: { type: "string" } }, ["id"], async (args) => {
+    const id = String(args.id);
+    const value = pending.get(id);
+    if (!value) throw new Error(`Unknown pending action: ${id}`);
+    pending.delete(id);
+    await publish(value.surfaceId, "action.rejected", { id, command: value.command }, { kind: "human", id: "human" });
+    return { rejected: true };
+  });
+  register("human_plus_events_list", "Pull durable Human+ events for a consumer.", { consumerId: { type: "string" }, after: { type: "number" }, limit: { type: "number" }, unacknowledgedOnly: { type: "boolean" } }, ["consumerId"], (args) => options.eventStore.list({ consumerId: String(args.consumerId), after: typeof args.after === "number" ? args.after : void 0, limit: typeof args.limit === "number" ? args.limit : void 0, unacknowledgedOnly: args.unacknowledgedOnly === true }));
+  register("human_plus_events_ack", "Acknowledge durable Human+ events.", { consumerId: { type: "string" }, eventIds: { type: "array", items: { type: "string" } }, disposition: { type: "string" } }, ["consumerId", "eventIds"], async (args) => {
+    const ids = Array.isArray(args.eventIds) ? args.eventIds.map(String) : [];
+    await options.eventStore.acknowledge(String(args.consumerId), ids, ["seen", "handled", "rejected", "ignored"].includes(String(args.disposition)) ? String(args.disposition) : "handled");
+    return { acknowledged: ids.length };
+  });
+  register("human_plus_events_subscribe", "Push matching Human+ events on this MCP transport while retaining them in the inbox.", { consumerId: { type: "string" }, types: { type: "array" }, surfaces: { type: "array" } }, ["consumerId"], (args, context) => {
+    if (!context?.transport) throw new Error("Subscriptions require an attached MCP transport");
+    subscriptions.set(context.transport, { consumerId: String(args.consumerId), types: Array.isArray(args.types) ? args.types.map(String) : void 0, surfaces: Array.isArray(args.surfaces) ? args.surfaces.map(String) : void 0 });
+    return { subscribed: true, delivery: "at-least-once", wakesAgent: false };
+  });
+  const unsubscribeStore = options.eventStore.subscribe((event) => {
+    const server = host;
+    if (typeof server.notify !== "function") return;
+    for (const [transport, subscription] of subscriptions) {
+      if (subscription.types?.length && !subscription.types.includes(event.type)) continue;
+      if (subscription.surfaces?.length && !subscription.surfaces.includes(event.surfaceId)) continue;
+      server.notify({ jsonrpc: "2.0", method: "notifications/human_plus/event", params: event }, transport);
+    }
+  });
+  return { id: "tui", title: "Fancy TUI", pending: () => [...pending.values()], dispose: () => {
+    disposers.forEach((dispose) => dispose());
+    unsubscribeStore();
+    subscriptions.clear();
+    pending.clear();
+  } };
+}
+
 // src/undo/undo-tools.ts
 var installedHosts = /* @__PURE__ */ new WeakSet();
 function ensureUndoToolsRegistered(host, options = {}) {
@@ -4568,39 +4744,6 @@ function buildCurlRecipe(session) {
   ].join("\n");
 }
 
-// src/presence/use-agent-activity.ts
-init_registry();
-function useAgentActivity(filter, options = {}) {
-  const cap = options.capacity ?? 50;
-  const [events, setEvents] = react.useState(() => fancyAutoCommon.readActivityHistory(filter).slice(-cap));
-  react.useEffect(() => {
-    setEvents(fancyAutoCommon.readActivityHistory(filter).slice(-cap));
-    return fancyAutoCommon.onActivity((event) => {
-      setEvents((prev) => {
-        const next = prev.length >= cap ? prev.slice(prev.length - cap + 1) : prev.slice();
-        next.push(event);
-        return next;
-      });
-    }, filter);
-  }, [filter?.agentId, filter?.screenId, filter?.kind, cap]);
-  return { events, latest: events.length > 0 ? events[events.length - 1] : null };
-}
-function useAgentActivityForScreen(screenId, options = {}) {
-  const { events, latest } = useAgentActivity({ screenId }, options);
-  const fadeAfter = latest?.ttlMs ?? 1500;
-  const [isAgentActive, setActive] = react.useState(false);
-  react.useEffect(() => {
-    if (!latest) {
-      setActive(false);
-      return;
-    }
-    setActive(true);
-    const timer = setTimeout(() => setActive(false), fadeAfter);
-    return () => clearTimeout(timer);
-  }, [latest, fadeAfter]);
-  return { events, latest, isAgentActive };
-}
-
 // src/connectors/targets.ts
 var CLAUDE_CONNECTORS_URL = "https://claude.ai/settings/connectors";
 function encodeBase64Json(value) {
@@ -4905,6 +5048,23 @@ function CoBrowsePresence({ session, connectUrl, shareBaseUrl, className }) {
   ] });
 }
 CoBrowsePresence.displayName = "CoBrowsePresence";
+var CURSOR_EDGE_INSET = 24;
+var FLUID_CURSOR_SPEED_PX_PER_SECOND = 1050;
+var MIN_GLIDE_MS = 240;
+var MAX_GLIDE_MS = 1200;
+function visibleCursorPoint(rect, viewport) {
+  const x = rect.x + rect.width / 2;
+  const y = rect.y + rect.height / 2;
+  return {
+    x: Math.min(Math.max(x, CURSOR_EDGE_INSET), Math.max(CURSOR_EDGE_INSET, viewport.width - CURSOR_EDGE_INSET)),
+    y: Math.min(Math.max(y, CURSOR_EDGE_INSET), Math.max(CURSOR_EDGE_INSET, viewport.height - CURSOR_EDGE_INSET))
+  };
+}
+function fluidGlideDuration(from, to) {
+  if (!from) return 0;
+  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 }) {
   const { latest } = useAgentActivity(void 0, { capacity: 12 });
   const [cursor, setCursor] = react.useState(
@@ -4914,7 +5074,7 @@ function CoBrowseCursorLayer({ active = true, zIndex = 2147483e3 }) {
   react.useEffect(() => {
     if (!latest || (latest.source ?? "agent") === "user") return;
     if (latest.action === "agent_disconnected") {
-      setCursor(null);
+      setCursor((prev) => prev ? { ...prev, status: "Standing by", glideMs: 0 } : prev);
       setPulse(null);
       return;
     }
@@ -4923,11 +5083,19 @@ function CoBrowseCursorLayer({ active = true, zIndex = 2147483e3 }) {
     const status = latest.target?.label ?? latest.action;
     const rect = latest.meta?.rect;
     if (rect) {
-      setCursor({ x: rect.x + rect.width / 2, y: rect.y + rect.height / 2, name, color, status });
+      const target = visibleCursorPoint(rect, { width: window.innerWidth, height: window.innerHeight });
+      const reduceMotion = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false;
+      setCursor((prev) => ({
+        ...target,
+        name,
+        color,
+        status,
+        glideMs: reduceMotion ? 0 : fluidGlideDuration(prev, target)
+      }));
       setPulse({ rect, color, key: latest.timestamp });
     } else {
       setCursor(
-        (prev) => prev ? { ...prev, status, name, color } : { x: window.innerWidth / 2, y: window.innerHeight / 2, name, color, status }
+        (prev) => prev ? { ...prev, status, name, color } : { x: window.innerWidth / 2, y: window.innerHeight / 2, name, color, status, glideMs: 0 }
       );
     }
   }, [latest?.timestamp]);
@@ -4953,7 +5121,9 @@ function CoBrowseCursorLayer({ active = true, zIndex = 2147483e3 }) {
           name: cursor.name,
           color: cursor.color,
           status: cursor.status,
-          style: { transition: "left .35s cubic-bezier(.22,.61,.36,1), top .35s cubic-bezier(.22,.61,.36,1)" }
+          style: {
+            transition: cursor.glideMs ? `left ${cursor.glideMs}ms cubic-bezier(.22,.61,.36,1), top ${cursor.glideMs}ms cubic-bezier(.22,.61,.36,1)` : "none"
+          }
         }
       )
     ] }),
@@ -5032,9 +5202,6 @@ function SimulateUsersButton({
   );
 }
 
-// src/presence/index.ts
-init_registry();
-
 // src/heuristics/sink.ts
 function numericMeta(meta, key) {
   const v = meta?.[key];
@@ -5275,6 +5442,7 @@ exports.InProcessTransport = InProcessTransport;
 exports.MCPB_MANIFEST_VERSION = MCPB_MANIFEST_VERSION;
 exports.MCPB_MIN_NODE = MCPB_MIN_NODE;
 exports.MCP_PROTOCOL_VERSION = MCP_PROTOCOL_VERSION;
+exports.MemoryHumanPlusEventStore = MemoryHumanPlusEventStore;
 exports.MicroMcpServer = MicroMcpServer;
 exports.RelayTransport = RelayTransport;
 exports.ScreensActivityBridge = ScreensActivityBridge;
@@ -5321,6 +5489,7 @@ exports.registerScreensBridge = registerScreensBridge;
 exports.registerSheetsBridge = registerSheetsBridge;
 exports.registerSlidesBridge = registerSlidesBridge;
 exports.registerTerminalBridge = registerTerminalBridge;
+exports.registerTuiBridge = registerTuiBridge;
 exports.registerUndoTools = registerUndoTools;
 exports.rpcError = rpcError;
 exports.slugifyServerName = slugifyServerName;