@particle-academy/agent-integrations 0.46.0 → 0.47.1

package/dist/index.cjs

@@ -3416,14 +3416,30 @@ function registerTerminalBridge(host, options) {
 
 // src/bridges/navigation.ts
 var DEFAULT_AGENT12 = { id: "agent", name: "Agent", color: "#a855f7" };
+var isControl = (code) => code < 32 || code >= 127 && code <= 159 || code === 8232 || code === 8233;
+function oneLine(value, max) {
+  const raw = typeof value === "string" ? value : value == null ? "" : String(value);
+  const bounded = raw.length > max * 4 ? raw.slice(0, max * 4) : raw;
+  let out = "";
+  for (const c of bounded) out += isControl(c.charCodeAt(0)) ? " " : c;
+  out = out.replace(/\s+/g, " ").trim();
+  return out.length > max ? out.slice(0, max - 3) + "..." : out;
+}
+var SAFE_HANDLE = /^[A-Za-z0-9_.:#@/-]{1,80}$/;
+var CAP = { url: 500, title: 200, role: 40, label: 200, heading: 200, text: 4e3, error: 300, headings: 50 };
+function formatReadout(r) {
+  if (typeof r === "string") return oneLine(r, CAP.text);
+  const headings = (Array.isArray(r.headings) ? r.headings : []).slice(0, CAP.headings).map((h) => `H${Math.min(6, Math.max(1, Math.trunc(Number(h?.level)) || 1))}: ${oneLine(h?.text, CAP.heading)}`);
+  return [oneLine(r.title, CAP.title), ...headings, "", oneLine(r.text, CAP.text)].join("\n");
+}
 function registerNavigationBridge(host, options) {
   const { adapter } = options;
   const agent = { ...DEFAULT_AGENT12, ...options.agent ?? {} };
   const pendingMode = options.pendingMode ?? true;
   const disposers = [];
   let groundedRevision = null;
-  const staleIntent = () => {
-    const current = adapter.getRevision?.();
+  const staleIntent = async () => {
+    const current = await adapter.getRevision?.();
     if (current === void 0) return null;
     if (groundedRevision === null || groundedRevision !== current) {
       return errorResult(
@@ -3432,6 +3448,9 @@ function registerNavigationBridge(host, options) {
     }
     return null;
   };
+  let aliases = /* @__PURE__ */ new Map();
+  const pageHandle = (handle) => aliases.get(handle) ?? handle;
+  const failure = (message, fallback) => errorResult(oneLine(message ?? fallback, CAP.error) || fallback);
   ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });
   const target = (label, elementId) => ({
     kind: "navigation",
@@ -3444,7 +3463,7 @@ function registerNavigationBridge(host, options) {
       try {
         return await handler(args);
       } catch (e) {
-        return errorResult(e instanceof Error ? e.message : String(e));
+        return failure(e instanceof Error ? e.message : String(e), `${name} failed`);
       }
     };
     const final = activity ? wrapToolWithActivity(wrapped, {
@@ -3470,18 +3489,30 @@ function registerNavigationBridge(host, options) {
     "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.",
     {},
     [],
-    () => {
-      const snap = adapter.describe();
-      const revision = adapter.getRevision?.();
+    async () => {
+      const raw = await adapter.describe();
+      const next = /* @__PURE__ */ new Map();
+      const actions = (Array.isArray(raw.actions) ? raw.actions : []).map((a) => {
+        const handle = String(a.handle ?? "");
+        if (SAFE_HANDLE.test(handle)) return a;
+        const alias = `~${next.size}`;
+        next.set(alias, handle);
+        return { ...a, handle: alias };
+      });
+      aliases = next;
+      const snap = { ...raw, actions };
+      const revision = await adapter.getRevision?.();
       if (revision !== void 0) {
         snap.revision = revision;
         groundedRevision = revision;
       }
       const text = [
-        `URL: ${snap.url}`,
-        `Title: ${snap.title}`,
+        `URL: ${oneLine(snap.url, CAP.url)}`,
+        `Title: ${oneLine(snap.title, CAP.title)}`,
         "",
-        ...snap.actions.map((a) => `[${a.handle}] ${a.role}: ${a.label}${a.destructive ? " (destructive)" : ""}`)
+        ...actions.map(
+          (a) => `[${a.handle}] ${oneLine(a.role, CAP.role)}: ${oneLine(a.label, CAP.label)}${a.destructive ? " (destructive)" : ""}`
+        )
       ].join("\n");
       return textResult(text, snap);
     },
@@ -3492,7 +3523,10 @@ function registerNavigationBridge(host, options) {
     "Read the page's visible text / heading outline for grounding.",
     {},
     [],
-    () => textResult(adapter.read ? adapter.read() : "(host did not provide page text)"),
+    async () => {
+      const r = adapter.read ? await adapter.read() : void 0;
+      return textResult(r == null ? "(host did not provide page text)" : formatReadout(r));
+    },
     () => target("Read page")
   );
   reg(
@@ -3500,15 +3534,16 @@ function registerNavigationBridge(host, options) {
     "Move the agent's visible focus to an interactive element by stable handle without activating it.",
     { handle: { type: "string" } },
     ["handle"],
-    (args) => {
-      const stale = staleIntent();
+    async (args) => {
+      const stale = await 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}"`);
-      return textResult(`Focused ${handle}`, {
-        handle,
-        rect: adapter.rectFor?.(handle) ?? void 0
+      const shown = String(args.handle ?? "");
+      const handle = pageHandle(shown);
+      const action = (await adapter.describe()).actions.find((candidate) => candidate.handle === handle);
+      if (!action) return failure(`No element for handle "${shown}"`, "No element for that handle");
+      return textResult(`Focused ${oneLine(shown, CAP.label)}`, {
+        handle: shown,
+        rect: await adapter.rectFor?.(handle) ?? void 0
       });
     },
     (args) => target(`Focus ${String(args.handle ?? "")}`, String(args.handle ?? ""))
@@ -3519,7 +3554,7 @@ function registerNavigationBridge(host, options) {
     { url: { type: "string", description: "Path like /packages or an absolute URL." } },
     ["url"],
     async (args) => {
-      const stale = staleIntent();
+      const stale = await staleIntent();
       if (stale) return stale;
       const url = String(args.url ?? "");
       if (!url) return errorResult("url is required");
@@ -3529,7 +3564,7 @@ function registerNavigationBridge(host, options) {
           `Refusing to navigate to a '${scheme}:' URL. Only http(s) URLs or same-site paths are allowed.`
         );
       }
-      const from = adapter.getLocation().url;
+      const from = (await adapter.getLocation()).url;
       await adapter.visit(url);
       fancyAutoCommon.pushUndoEntry(agent.id, {
         timestamp: Date.now(),
@@ -3553,7 +3588,7 @@ function registerNavigationBridge(host, options) {
     {},
     [],
     async () => {
-      const stale = staleIntent();
+      const stale = await staleIntent();
       if (stale) return stale;
       if (!adapter.back) return errorResult("Host did not provide back navigation.");
       await adapter.back();
@@ -3567,7 +3602,7 @@ function registerNavigationBridge(host, options) {
     {},
     [],
     async () => {
-      const stale = staleIntent();
+      const stale = await staleIntent();
       if (stale) return stale;
       if (!adapter.forward) return errorResult("Host did not provide forward navigation.");
       await adapter.forward();
@@ -3584,16 +3619,20 @@ function registerNavigationBridge(host, options) {
       y: { type: "number" }
     },
     [],
-    (args) => {
-      const stale = staleIntent();
+    async (args) => {
+      const stale = await staleIntent();
       if (stale) return stale;
-      const handle = typeof args.handle === "string" ? args.handle : void 0;
-      adapter.scrollTo({
+      const shown = typeof args.handle === "string" ? args.handle : void 0;
+      const handle = shown === void 0 ? void 0 : pageHandle(shown);
+      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: adapter.rectFor?.(handle) ?? void 0 } : void 0);
+      return textResult(
+        "Scrolled",
+        handle ? { handle: shown, rect: await adapter.rectFor?.(handle) ?? void 0 } : void 0
+      );
     },
     () => target("Scroll")
   );
@@ -3602,10 +3641,10 @@ function registerNavigationBridge(host, options) {
     "Scroll the page by a vertical delta in pixels (negative scrolls up).",
     { dy: { type: "number" } },
     ["dy"],
-    (args) => {
-      const stale = staleIntent();
+    async (args) => {
+      const stale = await staleIntent();
       if (stale) return stale;
-      adapter.scrollBy(Number(args.dy ?? 0));
+      await adapter.scrollBy(Number(args.dy ?? 0));
       return textResult(`Scrolled by ${Number(args.dy ?? 0)}px`);
     },
     () => target("Scroll")
@@ -3618,13 +3657,18 @@ function registerNavigationBridge(host, options) {
       value: { description: "Value to set; type matches the field." }
     },
     ["handle", "value"],
-    (args) => {
-      const stale = staleIntent();
+    async (args) => {
+      const stale = await 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}`);
-      return textResult(`${handle} \u2190 ${JSON.stringify(args.value)}`, { handle, value: args.value, rect: adapter.rectFor?.(handle) ?? void 0 });
+      const shown = String(args.handle ?? "");
+      const handle = pageHandle(shown);
+      const res = await adapter.setField(handle, args.value);
+      if (!res.ok) return failure(res.error, `Could not set ${oneLine(shown, CAP.label)}`);
+      return textResult(`${oneLine(shown, CAP.label)} \u2190 ${JSON.stringify(args.value)}`, {
+        handle: shown,
+        value: args.value,
+        rect: await adapter.rectFor?.(handle) ?? void 0
+      });
     },
     (args) => target(`Set ${String(args.handle ?? "")}`, String(args.handle ?? ""))
   );
@@ -3634,18 +3678,19 @@ function registerNavigationBridge(host, options) {
     { handle: { type: "string" } },
     ["handle"],
     async (args) => {
-      const stale = staleIntent();
+      const stale = await 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;
+      const shown = String(args.handle ?? "");
+      const handle = pageHandle(shown);
+      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 = adapter.click(handle);
-      if (!res.ok) return errorResult(res.error ?? `Could not click ${handle}`);
-      return textResult(`Clicked ${handle}`, { handle, rect });
+      const res = await adapter.click(handle);
+      if (!res.ok) return failure(res.error, `Could not click ${oneLine(shown, CAP.label)}`);
+      return textResult(`Clicked ${oneLine(shown, CAP.label)}`, { handle: shown, rect });
     },
     (args) => target(`Click ${String(args.handle ?? "")}`, String(args.handle ?? ""))
   );
@@ -3655,17 +3700,18 @@ function registerNavigationBridge(host, options) {
     { handle: { type: "string" } },
     ["handle"],
     async (args) => {
-      const stale = staleIntent();
+      const stale = await staleIntent();
       if (stale) return stale;
-      const handle = String(args.handle ?? "");
-      const rect = adapter.rectFor?.(handle) ?? void 0;
+      const shown = String(args.handle ?? "");
+      const handle = pageHandle(shown);
+      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 });
+      if (!res.ok) return failure(res.error, "Submit failed");
+      return textResult(`Submitted ${oneLine(shown, CAP.label)}`, { handle: shown, rect });
     },
     (args) => target(`Submit ${String(args.handle ?? "")}`, String(args.handle ?? ""))
   );