@particle-academy/agent-integrations 0.28.0 → 0.28.2

package/dist/index.cjs

@@ -2772,6 +2772,17 @@ function registerNavigationBridge(host, options) {
   const agent = { ...DEFAULT_AGENT11, ...options.agent ?? {} };
   const pendingMode = options.pendingMode ?? true;
   const disposers = [];
+  let groundedRevision = null;
+  const staleIntent = () => {
+    const current = 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",
@@ -2812,6 +2823,11 @@ function registerNavigationBridge(host, options) {
     [],
     () => {
       const snap = adapter.describe();
+      const revision = adapter.getRevision?.();
+      if (revision !== void 0) {
+        snap.revision = revision;
+        groundedRevision = revision;
+      }
       const text = [
         `URL: ${snap.url}`,
         `Title: ${snap.title}`,
@@ -2836,6 +2852,8 @@ function registerNavigationBridge(host, options) {
     { handle: { type: "string" } },
     ["handle"],
     (args) => {
+      const stale = staleIntent();
+      if (stale) return stale;
       const handle = String(args.handle ?? "");
       const action = adapter.describe().actions.find((candidate) => candidate.handle === handle);
       if (!action) return errorResult(`No element for handle "${handle}"`);
@@ -2852,6 +2870,8 @@ function registerNavigationBridge(host, options) {
     { url: { type: "string", description: "Path like /packages or an absolute URL." } },
     ["url"],
     async (args) => {
+      const stale = staleIntent();
+      if (stale) return stale;
       const url = String(args.url ?? "");
       if (!url) return errorResult("url is required");
       const from = adapter.getLocation().url;
@@ -2878,6 +2898,8 @@ function registerNavigationBridge(host, options) {
     {},
     [],
     async () => {
+      const stale = staleIntent();
+      if (stale) return stale;
       if (!adapter.back) return errorResult("Host did not provide back navigation.");
       await adapter.back();
       return textResult("Went back");
@@ -2890,6 +2912,8 @@ function registerNavigationBridge(host, options) {
     {},
     [],
     async () => {
+      const stale = staleIntent();
+      if (stale) return stale;
       if (!adapter.forward) return errorResult("Host did not provide forward navigation.");
       await adapter.forward();
       return textResult("Went forward");
@@ -2906,6 +2930,8 @@ function registerNavigationBridge(host, options) {
     },
     [],
     (args) => {
+      const stale = staleIntent();
+      if (stale) return stale;
       const handle = typeof args.handle === "string" ? args.handle : void 0;
       adapter.scrollTo({
         handle,
@@ -2922,6 +2948,8 @@ function registerNavigationBridge(host, options) {
     { dy: { type: "number" } },
     ["dy"],
     (args) => {
+      const stale = staleIntent();
+      if (stale) return stale;
       adapter.scrollBy(Number(args.dy ?? 0));
       return textResult(`Scrolled by ${Number(args.dy ?? 0)}px`);
     },
@@ -2936,6 +2964,8 @@ function registerNavigationBridge(host, options) {
     },
     ["handle", "value"],
     (args) => {
+      const stale = staleIntent();
+      if (stale) return stale;
       const handle = String(args.handle ?? "");
       const res = adapter.setField(handle, args.value);
       if (!res.ok) return errorResult(res.error ?? `Could not set ${handle}`);
@@ -2949,6 +2979,8 @@ function registerNavigationBridge(host, options) {
     { handle: { type: "string" } },
     ["handle"],
     async (args) => {
+      const stale = staleIntent();
+      if (stale) return stale;
       const handle = String(args.handle ?? "");
       const action = adapter.describe().actions.find((a) => a.handle === handle);
       const rect = adapter.rectFor?.(handle) ?? void 0;
@@ -2968,6 +3000,8 @@ function registerNavigationBridge(host, options) {
     { handle: { type: "string" } },
     ["handle"],
     async (args) => {
+      const stale = staleIntent();
+      if (stale) return stale;
       const handle = String(args.handle ?? "");
       const rect = adapter.rectFor?.(handle) ?? void 0;
       if (pendingMode && adapter.confirm) {
@@ -4871,6 +4905,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(
@@ -4880,7 +4931,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;
     }
@@ -4889,11 +4940,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]);
@@ -4919,7 +4978,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"
+          }
         }
       )
     ] }),