@particle-academy/agent-integrations 0.46.0 → 0.47.0

package/dist/bridges/passkeys.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-LVBgCN5m.cjs';
-import { B as Bridge } from '../types-EcElKOlk.cjs';
-import '../types-C2DtnHIn.cjs';
+import { T as ToolHost } from '../tool-host-D67N2a2h.cjs';
+import { B as Bridge } from '../types-DP5yQZQU.cjs';
+import '../types-gzIpsUDE.cjs';
 
 /**
  * Bridge for `@particle-academy/fancy-passkeys-ui` — the **management** half of
@@ -150,7 +150,7 @@ type PasskeyBridgeOptions = {
      * Also route `passkey_rename` through {@link confirm}. Off by default: a
      * rename is cosmetic, reversible and pushed onto the undo stack. Worth turning
      * on where the label itself carries trust — a rogue credential relabelled
-     * "Glenn's iPhone" survives a human's audit of the list.
+     * "Avery's iPhone" survives a human's audit of the list.
      */
     confirmRename?: boolean;
     /**

package/dist/bridges/passkeys.d.ts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-Wo0pkY83.js';
-import { B as Bridge } from '../types-BxNRKSVd.js';
-import '../types-C2DtnHIn.js';
+import { T as ToolHost } from '../tool-host-LYfdPE8u.js';
+import { B as Bridge } from '../types-VX_9je7w.js';
+import '../types-gzIpsUDE.js';
 
 /**
  * Bridge for `@particle-academy/fancy-passkeys-ui` — the **management** half of
@@ -150,7 +150,7 @@ type PasskeyBridgeOptions = {
      * Also route `passkey_rename` through {@link confirm}. Off by default: a
      * rename is cosmetic, reversible and pushed onto the undo stack. Worth turning
      * on where the label itself carries trust — a rogue credential relabelled
-     * "Glenn's iPhone" survives a human's audit of the list.
+     * "Avery's iPhone" survives a human's audit of the list.
      */
     confirmRename?: boolean;
     /**

package/dist/bridges/scene.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-LVBgCN5m.cjs';
-import { B as Bridge } from '../types-EcElKOlk.cjs';
-import '../types-C2DtnHIn.cjs';
+import { T as ToolHost } from '../tool-host-D67N2a2h.cjs';
+import { B as Bridge } from '../types-DP5yQZQU.cjs';
+import '../types-gzIpsUDE.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-Wo0pkY83.js';
-import { B as Bridge } from '../types-BxNRKSVd.js';
-import '../types-C2DtnHIn.js';
+import { T as ToolHost } from '../tool-host-LYfdPE8u.js';
+import { B as Bridge } from '../types-VX_9je7w.js';
+import '../types-gzIpsUDE.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-LVBgCN5m.cjs';
-import { B as Bridge } from '../types-EcElKOlk.cjs';
-import '../types-C2DtnHIn.cjs';
+import { T as ToolHost } from '../tool-host-D67N2a2h.cjs';
+import { B as Bridge } from '../types-DP5yQZQU.cjs';
+import '../types-gzIpsUDE.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-Wo0pkY83.js';
-import { B as Bridge } from '../types-BxNRKSVd.js';
-import '../types-C2DtnHIn.js';
+import { T as ToolHost } from '../tool-host-LYfdPE8u.js';
+import { B as Bridge } from '../types-VX_9je7w.js';
+import '../types-gzIpsUDE.js';
 
 /**
  * Loose snapshot of a screen — what's in fancy-screens' ScreenMeta plus

package/dist/bridges/sheets.d.cts

@@ -1,7 +1,7 @@
-import { T as ToolHost } from '../tool-host-LVBgCN5m.cjs';
-import { B as Bridge } from '../types-EcElKOlk.cjs';
+import { T as ToolHost } from '../tool-host-D67N2a2h.cjs';
+import { B as Bridge } from '../types-DP5yQZQU.cjs';
 import { WorkbookData } from '@particle-academy/fancy-sheets';
-import '../types-C2DtnHIn.cjs';
+import '../types-gzIpsUDE.cjs';
 
 /**
  * Cell writes funnel through fancy-sheets' own `reduceWorkbook` + `SheetOp` —

package/dist/bridges/sheets.d.ts

@@ -1,7 +1,7 @@
-import { T as ToolHost } from '../tool-host-Wo0pkY83.js';
-import { B as Bridge } from '../types-BxNRKSVd.js';
+import { T as ToolHost } from '../tool-host-LYfdPE8u.js';
+import { B as Bridge } from '../types-VX_9je7w.js';
 import { WorkbookData } from '@particle-academy/fancy-sheets';
-import '../types-C2DtnHIn.js';
+import '../types-gzIpsUDE.js';
 
 /**
  * Cell writes funnel through fancy-sheets' own `reduceWorkbook` + `SheetOp` —

package/dist/bridges/slides.d.cts

@@ -1,7 +1,7 @@
 import { Deck, DeckOp } from '@particle-academy/fancy-slides';
-import { T as ToolHost } from '../tool-host-LVBgCN5m.cjs';
-import { B as Bridge } from '../types-EcElKOlk.cjs';
-import '../types-C2DtnHIn.cjs';
+import { T as ToolHost } from '../tool-host-D67N2a2h.cjs';
+import { B as Bridge } from '../types-DP5yQZQU.cjs';
+import '../types-gzIpsUDE.cjs';
 
 /**
  * Adapter — the bridge calls into these to read or change deck state. The

package/dist/bridges/slides.d.ts

@@ -1,7 +1,7 @@
 import { Deck, DeckOp } from '@particle-academy/fancy-slides';
-import { T as ToolHost } from '../tool-host-Wo0pkY83.js';
-import { B as Bridge } from '../types-BxNRKSVd.js';
-import '../types-C2DtnHIn.js';
+import { T as ToolHost } from '../tool-host-LYfdPE8u.js';
+import { B as Bridge } from '../types-VX_9je7w.js';
+import '../types-gzIpsUDE.js';
 
 /**
  * Adapter — the bridge calls into these to read or change deck state. The

package/dist/bridges/terminal.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-LVBgCN5m.cjs';
-import { B as Bridge } from '../types-EcElKOlk.cjs';
-import '../types-C2DtnHIn.cjs';
+import { T as ToolHost } from '../tool-host-D67N2a2h.cjs';
+import { B as Bridge } from '../types-DP5yQZQU.cjs';
+import '../types-gzIpsUDE.cjs';
 
 /**
  * A shell/profile an agent can switch a terminal to. Mirrors fancy-term's

package/dist/bridges/terminal.d.ts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-Wo0pkY83.js';
-import { B as Bridge } from '../types-BxNRKSVd.js';
-import '../types-C2DtnHIn.js';
+import { T as ToolHost } from '../tool-host-LYfdPE8u.js';
+import { B as Bridge } from '../types-VX_9je7w.js';
+import '../types-gzIpsUDE.js';
 
 /**
  * A shell/profile an agent can switch a terminal to. Mirrors fancy-term's

package/dist/bridges/tui.d.cts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-LVBgCN5m.cjs';
+import { T as ToolHost } from '../tool-host-D67N2a2h.cjs';
 import { HumanPlusEventStore, HumanPlusActor } from '../human-plus/index.cjs';
-import '../types-C2DtnHIn.cjs';
+import '../types-gzIpsUDE.cjs';
 
 type TuiActionPolicy = "observe" | "execute" | "propose" | "confirm" | "human-only";
 interface TuiSurfaceCommandLike {

package/dist/bridges/tui.d.ts

@@ -1,6 +1,6 @@
-import { T as ToolHost } from '../tool-host-Wo0pkY83.js';
+import { T as ToolHost } from '../tool-host-LYfdPE8u.js';
 import { HumanPlusEventStore, HumanPlusActor } from '../human-plus/index.js';
-import '../types-C2DtnHIn.js';
+import '../types-gzIpsUDE.js';
 
 type TuiActionPolicy = "observe" | "execute" | "propose" | "confirm" | "human-only";
 interface TuiSurfaceCommandLike {

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-LVBgCN5m.cjs';
-import { B as Bridge } from '../types-EcElKOlk.cjs';
-import '../types-C2DtnHIn.cjs';
+import { T as ToolHost } from '../tool-host-D67N2a2h.cjs';
+import { B as Bridge } from '../types-DP5yQZQU.cjs';
+import '../types-gzIpsUDE.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-Wo0pkY83.js';
-import { B as Bridge } from '../types-BxNRKSVd.js';
-import '../types-C2DtnHIn.js';
+import { T as ToolHost } from '../tool-host-LYfdPE8u.js';
+import { B as Bridge } from '../types-VX_9je7w.js';
+import '../types-gzIpsUDE.js';
 
 /**
  * State accessors / mutators the bridge needs from the host. The host owns

package/dist/bridges-navigation.cjs

@@ -0,0 +1,391 @@
+'use strict';
+
+var fancyAutoCommon = require('@particle-academy/fancy-auto-common');
+
+// 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 };
+}
+
+// src/presence/wrap-tool-with-activity.ts
+function wrapToolWithActivity(handler, options) {
+  return async (args) => {
+    const result = await handler(args);
+    if (result.isError) return result;
+    let target;
+    if (options.resolveTarget) {
+      target = options.resolveTarget({ toolName: options.toolName, args, result });
+    } else {
+      target = { kind: options.kind, screenId: options.screenId };
+    }
+    if (!target) return result;
+    fancyAutoCommon.emitActivity({
+      agentId: options.agent.id,
+      agentName: options.agent.name,
+      agentColor: options.agent.color,
+      target: { ...target, kind: target.kind ?? options.kind, screenId: target.screenId ?? options.screenId },
+      action: options.toolName,
+      timestamp: Date.now(),
+      meta: options.buildMeta ? options.buildMeta(result) : extractMeta(result),
+      ttlMs: options.ttlMs
+    });
+    return result;
+  };
+}
+function extractMeta(result) {
+  const sc = result.structuredContent;
+  if (sc && typeof sc === "object" && !Array.isArray(sc)) {
+    return sc;
+  }
+  return void 0;
+}
+
+// src/undo/undo-tools.ts
+var installedHosts = /* @__PURE__ */ new WeakSet();
+function ensureUndoToolsRegistered(host, options = {}) {
+  if (installedHosts.has(host)) return;
+  installedHosts.add(host);
+  registerUndoTools(host, options);
+}
+function registerUndoTools(host, options = {}) {
+  const defaultAgent = options.defaultAgentId ?? "agent";
+  const disposers = [];
+  const agentOf = (args) => typeof args?.agentId === "string" ? args.agentId : defaultAgent;
+  disposers.push(
+    host.registerTool(
+      {
+        name: "agent_undo",
+        description: "Undo the most recent action on the agent's stack. Optional agentId targets a specific agent.",
+        inputSchema: {
+          type: "object",
+          properties: { agentId: { type: "string" } },
+          additionalProperties: false
+        }
+      },
+      async (args) => {
+        const entry = await fancyAutoCommon.undoOne(agentOf(args));
+        if (!entry) return errorResult("Nothing to undo.");
+        return textResult(`Undid: ${entry.label}`, { entry: serialize(entry) });
+      }
+    )
+  );
+  disposers.push(
+    host.registerTool(
+      {
+        name: "agent_redo",
+        description: "Redo the most recently undone action.",
+        inputSchema: {
+          type: "object",
+          properties: { agentId: { type: "string" } },
+          additionalProperties: false
+        }
+      },
+      async (args) => {
+        const entry = await fancyAutoCommon.redoOne(agentOf(args));
+        if (!entry) return errorResult("Nothing to redo.");
+        return textResult(`Redid: ${entry.label}`, { entry: serialize(entry) });
+      }
+    )
+  );
+  disposers.push(
+    host.registerTool(
+      {
+        name: "agent_history",
+        description: "List the agent's undo stack (oldest first). Useful for understanding what's reversible.",
+        inputSchema: {
+          type: "object",
+          properties: { agentId: { type: "string" } },
+          additionalProperties: false
+        }
+      },
+      async (args) => {
+        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);
+      }
+    )
+  );
+  return () => disposers.forEach((d) => d());
+}
+function serialize(entry) {
+  return {
+    timestamp: entry.timestamp,
+    bridgeId: entry.bridgeId,
+    action: entry.action,
+    label: entry.label
+  };
+}
+
+// src/bridges/navigation.ts
+var DEFAULT_AGENT = { id: "agent", name: "Agent", color: "#a855f7" };
+function registerNavigationBridge(host, options) {
+  const { adapter } = options;
+  const agent = { ...DEFAULT_AGENT, ...options.agent ?? {} };
+  const pendingMode = options.pendingMode ?? true;
+  const disposers = [];
+  let groundedRevision = null;
+  const staleIntent = async () => {
+    const current = await adapter.getRevision?.();
+    if (current === void 0) return null;
+    if (groundedRevision === null || groundedRevision !== current) {
+      return errorResult(
+        `Human took control at page revision ${current}. This agent action was cancelled; call page_describe before acting again.`
+      );
+    }
+    return null;
+  };
+  ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });
+  const target = (label, elementId) => ({
+    kind: "navigation",
+    screenId: adapter.screenId,
+    elementId,
+    label
+  });
+  const reg = (name, description, properties, required, handler, activity) => {
+    const wrapped = async (args) => {
+      try {
+        return await handler(args);
+      } catch (e) {
+        return errorResult(e instanceof Error ? e.message : String(e));
+      }
+    };
+    const final = activity ? wrapToolWithActivity(wrapped, {
+      toolName: name,
+      agent: { id: agent.id, name: agent.name, color: agent.color },
+      kind: "navigation",
+      screenId: adapter.screenId,
+      resolveTarget: ({ args }) => activity(args)
+    }) : wrapped;
+    disposers.push(
+      host.registerTool(
+        {
+          name,
+          description,
+          inputSchema: { type: "object", properties, required, additionalProperties: false }
+        },
+        final
+      )
+    );
+  };
+  reg(
+    "page_describe",
+    "Describe the current page: its URL, title, and the interactive elements you can act on (each with a stable `handle`, role, and label). Call this first, and again after navigating.",
+    {},
+    [],
+    async () => {
+      const snap = await adapter.describe();
+      const revision = await adapter.getRevision?.();
+      if (revision !== void 0) {
+        snap.revision = revision;
+        groundedRevision = revision;
+      }
+      const text = [
+        `URL: ${snap.url}`,
+        `Title: ${snap.title}`,
+        "",
+        ...snap.actions.map((a) => `[${a.handle}] ${a.role}: ${a.label}${a.destructive ? " (destructive)" : ""}`)
+      ].join("\n");
+      return textResult(text, snap);
+    },
+    () => target("Inspect page")
+  );
+  reg(
+    "page_read",
+    "Read the page's visible text / heading outline for grounding.",
+    {},
+    [],
+    async () => textResult(adapter.read ? await adapter.read() : "(host did not provide page text)"),
+    () => target("Read page")
+  );
+  reg(
+    "page_focus",
+    "Move the agent's visible focus to an interactive element by stable handle without activating it.",
+    { handle: { type: "string" } },
+    ["handle"],
+    async (args) => {
+      const stale = await staleIntent();
+      if (stale) return stale;
+      const handle = String(args.handle ?? "");
+      const action = (await adapter.describe()).actions.find((candidate) => candidate.handle === handle);
+      if (!action) return errorResult(`No element for handle "${handle}"`);
+      return textResult(`Focused ${handle}`, {
+        handle,
+        rect: await adapter.rectFor?.(handle) ?? void 0
+      });
+    },
+    (args) => target(`Focus ${String(args.handle ?? "")}`, String(args.handle ?? ""))
+  );
+  reg(
+    "nav_visit",
+    "Navigate to a URL (same-site path or absolute). The human watches the page change.",
+    { url: { type: "string", description: "Path like /packages or an absolute URL." } },
+    ["url"],
+    async (args) => {
+      const stale = await staleIntent();
+      if (stale) return stale;
+      const url = String(args.url ?? "");
+      if (!url) return errorResult("url is required");
+      const scheme = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(url)?.[1]?.toLowerCase();
+      if (scheme && scheme !== "http" && scheme !== "https") {
+        return errorResult(
+          `Refusing to navigate to a '${scheme}:' URL. Only http(s) URLs or same-site paths are allowed.`
+        );
+      }
+      const from = (await adapter.getLocation()).url;
+      await adapter.visit(url);
+      fancyAutoCommon.pushUndoEntry(agent.id, {
+        timestamp: Date.now(),
+        bridgeId: "navigation",
+        action: "nav_visit",
+        label: `Navigate to ${url}`,
+        undo: () => {
+          adapter.visit(from);
+        },
+        redo: () => {
+          adapter.visit(url);
+        }
+      });
+      return textResult(`Navigated to ${url}`, { url });
+    },
+    (args) => target(`Navigate \u2192 ${String(args.url ?? "")}`)
+  );
+  reg(
+    "nav_back",
+    "Go back to the previous page.",
+    {},
+    [],
+    async () => {
+      const stale = await staleIntent();
+      if (stale) return stale;
+      if (!adapter.back) return errorResult("Host did not provide back navigation.");
+      await adapter.back();
+      return textResult("Went back");
+    },
+    () => target("Back")
+  );
+  reg(
+    "nav_forward",
+    "Go forward to the next page.",
+    {},
+    [],
+    async () => {
+      const stale = await staleIntent();
+      if (stale) return stale;
+      if (!adapter.forward) return errorResult("Host did not provide forward navigation.");
+      await adapter.forward();
+      return textResult("Went forward");
+    },
+    () => target("Forward")
+  );
+  reg(
+    "nav_scroll_to",
+    "Scroll the page to absolute coordinates, or to a specific element by its handle.",
+    {
+      handle: { type: "string", description: "Scroll this element into view." },
+      x: { type: "number" },
+      y: { type: "number" }
+    },
+    [],
+    async (args) => {
+      const stale = await staleIntent();
+      if (stale) return stale;
+      const handle = typeof args.handle === "string" ? args.handle : void 0;
+      await adapter.scrollTo({
+        handle,
+        x: typeof args.x === "number" ? args.x : void 0,
+        y: typeof args.y === "number" ? args.y : void 0
+      });
+      return textResult("Scrolled", handle ? { handle, rect: await adapter.rectFor?.(handle) ?? void 0 } : void 0);
+    },
+    () => target("Scroll")
+  );
+  reg(
+    "nav_scroll_by",
+    "Scroll the page by a vertical delta in pixels (negative scrolls up).",
+    { dy: { type: "number" } },
+    ["dy"],
+    async (args) => {
+      const stale = await staleIntent();
+      if (stale) return stale;
+      await adapter.scrollBy(Number(args.dy ?? 0));
+      return textResult(`Scrolled by ${Number(args.dy ?? 0)}px`);
+    },
+    () => target("Scroll")
+  );
+  reg(
+    "page_set_field",
+    "Set a form field's value by handle. The host updates the controlled input and the human sees it change.",
+    {
+      handle: { type: "string" },
+      value: { description: "Value to set; type matches the field." }
+    },
+    ["handle", "value"],
+    async (args) => {
+      const stale = await staleIntent();
+      if (stale) return stale;
+      const handle = String(args.handle ?? "");
+      const res = await adapter.setField(handle, args.value);
+      if (!res.ok) return errorResult(res.error ?? `Could not set ${handle}`);
+      return textResult(`${handle} \u2190 ${JSON.stringify(args.value)}`, { handle, value: args.value, rect: await adapter.rectFor?.(handle) ?? void 0 });
+    },
+    (args) => target(`Set ${String(args.handle ?? "")}`, String(args.handle ?? ""))
+  );
+  reg(
+    "page_click",
+    "Activate an element by handle (link, button, checkbox\u2026). Destructive elements are staged for the human to confirm.",
+    { handle: { type: "string" } },
+    ["handle"],
+    async (args) => {
+      const stale = await staleIntent();
+      if (stale) return stale;
+      const handle = String(args.handle ?? "");
+      const action = (await adapter.describe()).actions.find((a) => a.handle === handle);
+      const rect = await adapter.rectFor?.(handle) ?? void 0;
+      if (pendingMode && action?.destructive && adapter.confirm) {
+        const ok = await adapter.confirm({ action: "click", handle, label: action.label });
+        if (!ok) return errorResult("Declined by user");
+      }
+      const res = await adapter.click(handle);
+      if (!res.ok) return errorResult(res.error ?? `Could not click ${handle}`);
+      return textResult(`Clicked ${handle}`, { handle, rect });
+    },
+    (args) => target(`Click ${String(args.handle ?? "")}`, String(args.handle ?? ""))
+  );
+  reg(
+    "page_submit",
+    "Submit a form by handle. Always staged for the human to confirm when pendingMode is on.",
+    { handle: { type: "string" } },
+    ["handle"],
+    async (args) => {
+      const stale = await staleIntent();
+      if (stale) return stale;
+      const handle = String(args.handle ?? "");
+      const rect = await adapter.rectFor?.(handle) ?? void 0;
+      if (pendingMode && adapter.confirm) {
+        const ok = await adapter.confirm({ action: "submit", handle, label: handle });
+        if (!ok) return errorResult("Declined by user");
+      }
+      const res = await adapter.submit(handle);
+      if (!res.ok) return errorResult(res.error ?? "Submit failed");
+      return textResult(`Submitted ${handle}`, { handle, rect });
+    },
+    (args) => target(`Submit ${String(args.handle ?? "")}`, String(args.handle ?? ""))
+  );
+  return {
+    id: "navigation",
+    title: "Co-browsing",
+    dispose: () => {
+      for (const d of disposers) d();
+    }
+  };
+}
+
+exports.registerNavigationBridge = registerNavigationBridge;
+//# sourceMappingURL=bridges-navigation.cjs.map
+//# sourceMappingURL=bridges-navigation.cjs.map