@particle-academy/agent-integrations 0.46.0 → 0.47.1

package/dist/bridges/navigation.d.ts

@@ -0,0 +1,140 @@
+import { T as ToolHost } from '../tool-host-LYfdPE8u.js';
+import { B as Bridge } from '../types-VX_9je7w.js';
+import '../types-gzIpsUDE.js';
+
+/**
+ * One interactive element the agent can act on, addressed by a STABLE handle
+ * (not a CSS selector) so the agent drives the page the Human+ way — never DOM
+ * scraping. The host builds these in `describe()` (data-co-handle → name/id →
+ * ARIA role + accessible name).
+ */
+type PageAction = {
+    /** Stable, opaque handle the agent passes back to act on this element. */
+    handle: string;
+    /** ARIA-ish role: "link" | "button" | "textbox" | "checkbox" | "select" | … */
+    role: string;
+    /** Accessible name / label. */
+    label: string;
+    /** Current value for inputs (omitted/masked for sensitive fields). */
+    value?: unknown;
+    /** True when activating this is destructive / submits (agent should stage). */
+    destructive?: boolean;
+};
+/** The page as the agent sees it: where it is + what it can do. */
+type PageSnapshot = {
+    url: string;
+    title: string;
+    actions: PageAction[];
+    /** Monotonic host revision. Human input advances it and invalidates stale agent intent. */
+    revision?: number;
+};
+/**
+ * Structured page text. Preferred over a plain string from `read()`: the bridge
+ * can then put every page-supplied string on its own single line and keep the
+ * outline. A plain string is untrusted as a whole and is rendered as ONE line.
+ */
+type PageReadout = {
+    title: string;
+    headings: Array<{
+        level: number;
+        text: string;
+    }>;
+    text: string;
+};
+/** A write the host may want the human to confirm (trust-but-verify). */
+type NavigationConfirmRequest = {
+    action: "submit" | "click";
+    handle: string;
+    label: string;
+};
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Host-provided adapter. In the sandbox this is backed by Inertia's `router` +
+ * the DOM walker from `@particle-academy/agent-integrations/dom-navigation`.
+ * Every method works on stable handles, never raw selectors.
+ *
+ * Any method may return a Promise: a host driving a page it does not run in
+ * (an Electron WebContentsView, via `createRemoteNavigationAdapter`) can only
+ * answer asynchronously. The bridge awaits every call.
+ */
+type NavigationBridgeAdapter = {
+    /** Optional fancy-screens screen id for presence targeting. */
+    screenId?: string;
+    /** Current location. */
+    getLocation: () => MaybePromise<{
+        url: string;
+        title: string;
+    }>;
+    /** Current human-control revision. Omit to disable stale-intent protection. */
+    getRevision?: () => MaybePromise<number>;
+    /** Snapshot of the page's actionable elements (stable handles + labels). */
+    describe: () => MaybePromise<PageSnapshot>;
+    /** Visible text / heading outline for grounding (optional). Prefer a {@link PageReadout}. */
+    read?: () => MaybePromise<string | PageReadout>;
+    /** Navigate to a URL (host wires to router.visit). */
+    visit: (url: string) => void | Promise<void>;
+    back?: () => void | Promise<void>;
+    forward?: () => void | Promise<void>;
+    /** Scroll to coords or to a handle's element. */
+    scrollTo: (opts: {
+        x?: number;
+        y?: number;
+        handle?: string;
+    }) => void | Promise<void>;
+    scrollBy: (dy: number) => void | Promise<void>;
+    /** Set a field's value by handle (host dispatches input/change for React). */
+    setField: (handle: string, value: unknown) => MaybePromise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /** Activate an element by handle. */
+    click: (handle: string) => MaybePromise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /** Submit a form by handle. */
+    submit: (handle: string) => Promise<{
+        ok: boolean;
+        error?: string;
+    }> | {
+        ok: boolean;
+        error?: string;
+    };
+    /**
+     * Viewport rect of a handle's element, for agent-presence rendering (cursor +
+     * highlight). Returned in tool `meta.rect` so `<CoBrowseCursorLayer>` can show
+     * the agent acting on the page. Optional — omit and there's just no cursor.
+     */
+    rectFor?: (handle: string) => MaybePromise<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null>;
+    /**
+     * Trust-but-verify hook. When `pendingMode` is on, `page_submit` and
+     * destructive `page_click` route through this; the host shows a prompt and
+     * resolves true (proceed) / false (declined).
+     */
+    confirm?: (req: NavigationConfirmRequest) => Promise<boolean>;
+};
+type NavigationBridgeOptions = {
+    adapter: NavigationBridgeAdapter;
+    /** Identity tagged into activity events (so the human sees who's driving). */
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+    /** Route submit + destructive clicks through `adapter.confirm`. Default true. */
+    pendingMode?: boolean;
+};
+/**
+ * registerNavigationBridge — site-wide co-browsing. Lets a connected agent
+ * navigate, scroll, and (with staged confirm) fill + click any page, addressed
+ * by stable handles. Pairs with `useCoBrowseSession` (server + relay) and
+ * `<CoBrowsePresence>` (the human's view of the agent). The 12th Fancy bridge.
+ */
+declare function registerNavigationBridge(host: ToolHost, options: NavigationBridgeOptions): Bridge;
+
+export { type NavigationBridgeAdapter, type NavigationBridgeOptions, type NavigationConfirmRequest, type PageAction, type PageReadout, type PageSnapshot, registerNavigationBridge };

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