@particle-academy/agent-integrations 0.29.0 → 0.30.0

package/dist/components-shared-whiteboard.js

@@ -1,9 +1,9 @@
-import { ShareControls, AgentCursor, AgentActivityHighlight, AgentPanel } from './chunk-5KLUYF4D.js';
-import { createSessionDescriptor, attachSseRelay } from './chunk-KMSRG5KH.js';
+import { ShareControls, AgentCursor, AgentActivityHighlight, AgentPanel } from './chunk-HSI5RVF4.js';
+import { createSessionDescriptor, attachSseRelay } from './chunk-N6RLSLOF.js';
 import { attachInProcess } from './chunk-AFUULW5E.js';
-import { registerWhiteboardBridge } from './chunk-OFCR6JY3.js';
+import { registerWhiteboardBridge } from './chunk-2U5JB6ZA.js';
 import './chunk-CT3LRNH7.js';
-import './chunk-ULJL53DL.js';
+import './chunk-2VENWGLZ.js';
 import './chunk-C3TYI5TJ.js';
 import { MicroMcpServer } from './chunk-DF3PLL2E.js';
 import { useState, useRef, useEffect, useCallback, useMemo } from 'react';

package/dist/heuristics.js

@@ -1,6 +1,6 @@
 export { attachHeuristicsSink, mapActivityToEvent } from './chunk-7R6RMROL.js';
 import './chunk-UCKJAUBY.js';
-import './chunk-ULJL53DL.js';
+import './chunk-2VENWGLZ.js';
 import './chunk-C3TYI5TJ.js';
 //# sourceMappingURL=heuristics.js.map
 //# sourceMappingURL=heuristics.js.map

package/dist/index.cjs

@@ -321,7 +321,7 @@ function wrapToolWithActivity(handler, options) {
       target: { ...target, kind: target.kind ?? options.kind, screenId: target.screenId ?? options.screenId },
       action: options.toolName,
       timestamp: Date.now(),
-      meta: extractMeta(result),
+      meta: options.buildMeta ? options.buildMeta(result) : extractMeta(result),
       ttlMs: options.ttlMs
     });
     return result;
@@ -543,6 +543,7 @@ var DEFAULT_AGENT = { id: "agent", name: "Agent", color: "#a855f7" };
 function registerFormBridge(host, options) {
   const { adapter } = options;
   const agent = { ...DEFAULT_AGENT, ...options.agent ?? {} };
+  const pendingMode = options.pendingMode ?? true;
   const disposers = [];
   ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });
   const formId = adapter.id;
@@ -671,11 +672,20 @@ function registerFormBridge(host, options) {
   );
   reg(
     "form_submit",
-    "Submit the form. Host returns ok + values (or an error).",
+    "Submit the form. Host returns ok + values (or an error). In pendingMode this is staged for the human to confirm first.",
     {},
     [],
     async () => {
       if (!adapter.submit) return errorResult("Host did not provide a submit implementation.");
+      if (pendingMode && adapter.confirm) {
+        const ok = await adapter.confirm({
+          action: "submit",
+          form: formId,
+          title: adapter.title,
+          values: adapter.getValues()
+        });
+        if (!ok) return errorResult("Declined by user");
+      }
       const result = await adapter.submit();
       if (!result.ok) return errorResult(result.error ?? "Submit failed");
       return textResult("Submitted", { values: result.values });
@@ -1039,6 +1049,7 @@ function useSheetsActivityHighlights(options = {}) {
 }
 
 // src/bridges/code.ts
+var MAX_STREAM_CHARS = 1e4;
 var DEFAULT_AGENT3 = { id: "agent", name: "Agent", color: "#a855f7" };
 function registerCodeBridge(host, options) {
   const { adapter } = options;
@@ -1051,6 +1062,16 @@ function registerCodeBridge(host, options) {
     elementId: adapter.id,
     label: adapter.title ?? adapter.id
   };
+  const recordUndo = (action, label, prevValue, nextValue) => {
+    fancyAutoCommon.pushUndoEntry(agent.id, {
+      timestamp: Date.now(),
+      bridgeId: "code",
+      action,
+      label,
+      undo: () => adapter.setValue(prevValue),
+      redo: () => adapter.setValue(nextValue)
+    });
+  };
   const reg = (name, description, properties, required, handler, isMutation) => {
     const wrapped = async (args) => {
       try {
@@ -1120,7 +1141,9 @@ function registerCodeBridge(host, options) {
     ["value"],
     (args) => {
       const value = String(args.value ?? "");
+      const prev = adapter.getValue();
       adapter.setValue(value);
+      recordUndo("code_set_value", "Replace document", prev, value);
       return textResult(`Replaced document (${value.length} chars)`, { length: value.length });
     },
     true
@@ -1132,8 +1155,10 @@ function registerCodeBridge(host, options) {
     ["text"],
     (args) => {
       const text = String(args.text ?? "");
-      const next = adapter.getValue() + text;
+      const prev = adapter.getValue();
+      const next = prev + text;
       adapter.setValue(next);
+      recordUndo("code_append", `Append ${text.length} chars`, prev, next);
       return textResult(`Appended ${text.length} chars`, { length: next.length });
     },
     true
@@ -1148,6 +1173,11 @@ function registerCodeBridge(host, options) {
     ["text"],
     async (args) => {
       const text = String(args.text ?? "");
+      if (text.length > MAX_STREAM_CHARS) {
+        return errorResult(
+          `Text too long to stream (${text.length} > ${MAX_STREAM_CHARS}). Use code_set_value / code_append for large content.`
+        );
+      }
       const cps = Math.max(1, Number(args.cps ?? 25));
       const interval = Math.max(8, Math.round(1e3 / cps));
       const start = adapter.getValue();
@@ -1155,6 +1185,7 @@ function registerCodeBridge(host, options) {
         adapter.setValue(start + text.slice(0, i));
         if (i < text.length) await new Promise((r) => setTimeout(r, interval));
       }
+      recordUndo("code_stream_append", `Append ${text.length} chars`, start, start + text);
       return textResult(`Streamed ${text.length} chars`, { length: text.length });
     },
     true
@@ -1166,7 +1197,9 @@ function registerCodeBridge(host, options) {
     ["text"],
     (args) => {
       if (!adapter.replaceSelection) return errorResult("Host did not provide replaceSelection.");
+      const prev = adapter.getValue();
       adapter.replaceSelection(String(args.text ?? ""));
+      recordUndo("code_replace_selection", "Replace selection", prev, adapter.getValue());
       return textResult("Selection replaced", {});
     },
     true
@@ -1179,7 +1212,18 @@ function registerCodeBridge(host, options) {
     (args) => {
       if (!adapter.setLanguage) return errorResult("Host did not provide setLanguage.");
       const lang = String(args.language ?? "");
+      const prevLang = adapter.getLanguage?.();
       adapter.setLanguage(lang);
+      if (prevLang !== void 0) {
+        fancyAutoCommon.pushUndoEntry(agent.id, {
+          timestamp: Date.now(),
+          bridgeId: "code",
+          action: "code_set_language",
+          label: `Language \u2192 ${lang}`,
+          undo: () => adapter.setLanguage?.(prevLang),
+          redo: () => adapter.setLanguage?.(lang)
+        });
+      }
       return textResult(`Language \u2192 ${lang}`, { language: lang });
     },
     true
@@ -1194,7 +1238,8 @@ function registerCodeBridge(host, options) {
       adapter.focus();
       return textResult("Focused", {});
     },
-    true
+    // Focus is not a document mutation — don't broadcast it as one or log undo.
+    false
   );
   return {
     id: `code:${adapter.id}`,
@@ -2465,6 +2510,22 @@ function registerMapBridge(host, options) {
 
 // src/bridges/files.ts
 var DEFAULT_AGENT9 = { id: "agent", name: "Agent", color: "#a855f7" };
+var MAX_SNAPSHOT_DEPTH = 8;
+function assertPathWithinRoot(root, path) {
+  const segments = path.replace(/[\\/]+/g, "/").split("/");
+  if (segments.includes("..")) {
+    throw new Error(`Path may not contain '..': ${path}`);
+  }
+  const isAbsolute = /^([A-Za-z]:)?[\\/]/.test(path) || /^[A-Za-z]:/.test(path);
+  if (isAbsolute) {
+    const norm = (p2) => p2.replace(/[\\/]+/g, "/").replace(/\/+$/, "").toLowerCase();
+    const r = norm(root);
+    const p = norm(path);
+    if (p !== r && !p.startsWith(r + "/")) {
+      throw new Error(`Path escapes the configured root: ${path}`);
+    }
+  }
+}
 var str3 = (v, fallback = "") => typeof v === "string" ? v : fallback;
 var num3 = (v, fallback) => typeof v === "number" && Number.isFinite(v) ? v : 0;
 var asPaths = (v) => {
@@ -2480,6 +2541,10 @@ function registerFilesBridge(host, options) {
   const { adapter } = options;
   const agent = { ...DEFAULT_AGENT9, ...options.agent ?? {} };
   const disposers = [];
+  const guard = (path) => {
+    if (options.root !== void 0) assertPathWithinRoot(options.root, path);
+    return path;
+  };
   ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });
   const fTarget = (args, _result) => ({
     kind: "files",
@@ -2535,7 +2600,7 @@ function registerFilesBridge(host, options) {
     { path: { type: "string", description: "Folder path to list; defaults to the current directory." } },
     [],
     async (args) => {
-      const path = args.path !== void 0 ? str3(args.path) : adapter.getPath();
+      const path = guard(args.path !== void 0 ? str3(args.path) : adapter.getPath());
       const entries = await adapter.listChildren(path);
       const summary = entries.map((e) => ({
         path: e.path,
@@ -2554,7 +2619,7 @@ function registerFilesBridge(host, options) {
     { path: { type: "string" } },
     ["path"],
     (args) => {
-      const path = str3(args.path);
+      const path = guard(str3(args.path));
       const prev = adapter.getPath();
       adapter.setPath(path);
       fancyAutoCommon.pushUndoEntry(agent.id, {
@@ -2575,7 +2640,7 @@ function registerFilesBridge(host, options) {
     { path: { type: "string" } },
     ["path"],
     (args) => {
-      const path = str3(args.path);
+      const path = guard(str3(args.path));
       if (adapter.getExpanded().includes(path)) {
         return textResult(`${path} already expanded`, { path, expanded: true });
       }
@@ -2598,7 +2663,7 @@ function registerFilesBridge(host, options) {
     { path: { type: "string" } },
     ["path"],
     (args) => {
-      const path = str3(args.path);
+      const path = guard(str3(args.path));
       if (!adapter.getExpanded().includes(path)) {
         return textResult(`${path} already collapsed`, { path, expanded: false });
       }
@@ -2624,7 +2689,7 @@ function registerFilesBridge(host, options) {
     },
     [],
     (args) => {
-      const next = args.paths !== void 0 ? asPaths(args.paths) : asPaths(args.path);
+      const next = (args.paths !== void 0 ? asPaths(args.paths) : asPaths(args.path)).map(guard);
       const prev = adapter.getSelection();
       adapter.setSelection(next);
       fancyAutoCommon.pushUndoEntry(agent.id, {
@@ -2653,8 +2718,8 @@ function registerFilesBridge(host, options) {
       if (!adapter.requestSnapshot) {
         return errorResult("Host did not wire requestSnapshot (snapshot mode not enabled).");
       }
-      const path = args.path !== void 0 ? str3(args.path) : adapter.getPath();
-      const depth = args.depth !== void 0 ? num3(args.depth) : void 0;
+      const path = guard(args.path !== void 0 ? str3(args.path) : adapter.getPath());
+      const depth = args.depth !== void 0 ? Math.max(0, Math.min(MAX_SNAPSHOT_DEPTH, num3(args.depth))) : void 0;
       const tree = await adapter.requestSnapshot(path, depth);
       const count = Array.isArray(tree) ? tree.length : 0;
       return textResult(`Snapshot of ${path}: ${count} top-level entr${count === 1 ? "y" : "ies"}.`, {
@@ -2678,16 +2743,15 @@ var DEFAULT_AGENT10 = { id: "agent", name: "Agent", color: "#a855f7" };
 var truncate = (s, n = 60) => s.length > n ? s.slice(0, n) + "\u2026" : s;
 function registerTerminalBridge(host, options) {
   const agent = { ...DEFAULT_AGENT10, ...options.agent ?? {} };
-  const pendingMode = options.pendingMode ?? false;
+  const pendingMode = options.pendingMode ?? true;
   const screenId = options.screenId ?? options.adapter?.screenId;
   const disposers = [];
   const staged = /* @__PURE__ */ new Map();
   let seq = 0;
   ensureUndoToolsRegistered(host);
   const listTerminals = () => {
-    if (options.terminals) return options.terminals();
-    if (options.adapter) return [{ id: "terminal", label: "Terminal", active: true, ...options.adapter }];
-    return [];
+    const all = options.terminals ? options.terminals() : options.adapter ? [{ id: "terminal", label: "Terminal", active: true, ...options.adapter }] : [];
+    return options.canAccess ? all.filter((t) => options.canAccess(t.id)) : all;
   };
   const resolve = (id) => {
     const list = listTerminals();
@@ -2704,6 +2768,17 @@ function registerTerminalBridge(host, options) {
     elementId: terminalId ?? screenId ?? "terminal",
     label: label ?? "terminal"
   });
+  const redactMeta = (result) => {
+    const sc = result.structuredContent;
+    if (!sc || typeof sc !== "object") return void 0;
+    return {
+      terminal: sc.terminal,
+      kind: sc.kind,
+      length: typeof sc.data === "string" ? sc.data.length : void 0,
+      executed: sc.executed,
+      pending: sc.pending
+    };
+  };
   const TERMINAL_ARG = {
     terminal: {
       type: "string",
@@ -2723,7 +2798,12 @@ function registerTerminalBridge(host, options) {
       agent,
       kind: "terminal",
       screenId,
-      resolveTarget: ({ args, result }) => resolveTarget?.(args, result) ?? target()
+      // A per-call resolver may return null to SKIP the broadcast (e.g. a
+      // merely-staged command); only fall back to the default target when no
+      // resolver was supplied.
+      resolveTarget: ({ args, result }) => resolveTarget ? resolveTarget(args, result) : target(),
+      // Never fan raw command/keystroke bytes to peers — broadcast shape only.
+      buildMeta: redactMeta
     }) : wrapped;
     disposers.push(
       host.registerTool(
@@ -2760,6 +2840,7 @@ function registerTerminalBridge(host, options) {
       return textResult(`${kind === "run" ? "ran" : "wrote"} on ${t.id}: ${truncate(data)}`, {
         kind,
         data,
+        length: data.length,
         terminal: t.id,
         executed: true
       });
@@ -2770,7 +2851,7 @@ function registerTerminalBridge(host, options) {
     options.onPending?.(entry);
     return textResult(
       `Staged ${kind} on ${t.id} (id ${id}) \u2014 awaiting human confirmation: ${truncate(data)}`,
-      { ...entry, pending: true }
+      { ...entry, length: data.length, pending: true }
     );
   }
   reg(
@@ -2815,12 +2896,13 @@ function registerTerminalBridge(host, options) {
   );
   reg(
     "terminal_write",
-    "Write raw data / keystrokes to a terminal (input, control chars, ANSI). Pass `terminal` to target a specific one. In pendingMode this stages instead of executing.",
+    "Write raw data / keystrokes to a terminal (input, control chars, ANSI). Pass `terminal` to target a specific one. In pendingMode this stages instead of executing. NOTE: bytes are written verbatim \u2014 an embedded CR runs a command, and ANSI/OSC sequences reach the terminal; treat this exactly like terminal_run for gating.",
     { ...TERMINAL_ARG, data: { type: "string", description: "Raw bytes to write." } },
     ["data"],
     (args) => stageOrExec(need(args), "write", String(args.data)),
     true,
-    (args) => target(`write:${String(args.terminal ?? "")}`, resolve(args.terminal)?.id)
+    // Skip the peer broadcast while only staged; emit once it actually executes.
+    (args, result) => result?.structuredContent?.pending ? null : target(`write:${String(args.terminal ?? "")}`, resolve(args.terminal)?.id)
   );
   reg(
     "terminal_run",
@@ -2829,41 +2911,47 @@ function registerTerminalBridge(host, options) {
     ["command"],
     (args) => stageOrExec(need(args), "run", String(args.command)),
     true,
-    (args) => target(truncate(String(args.command ?? "")), resolve(args.terminal)?.id)
-  );
-  reg(
-    "terminal_confirm",
-    "Confirm + execute a staged command by id (pendingMode).",
-    { id: { type: "string" } },
-    ["id"],
-    async (args) => {
-      const id = String(args.id);
-      const entry = staged.get(id);
-      if (!entry) return errorResult(`No staged command ${id}`);
-      const t = resolve(entry.terminalId);
-      if (!t) return errorResult(`Terminal '${entry.terminalId}' is gone \u2014 cannot run ${id}`);
-      staged.delete(id);
-      await exec(t, entry.kind, entry.data);
-      return textResult(`Confirmed ${id}: ${entry.kind} on ${t.id} ${truncate(entry.data)}`, { ...entry, executed: true });
-    },
-    true,
-    (args) => {
-      const e = staged.get(String(args.id));
-      return target(`confirm:${String(args.id ?? "")}`, e?.terminalId);
-    }
-  );
-  reg(
-    "terminal_reject",
-    "Drop a staged command by id without executing it.",
-    { id: { type: "string" } },
-    ["id"],
-    (args) => {
-      const id = String(args.id);
-      if (!staged.delete(id)) return errorResult(`No staged command ${id}`);
-      return textResult(`Rejected ${id}`, { id, rejected: true });
-    },
-    false
+    (args, result) => result?.structuredContent?.pending ? null : target(truncate(String(args.command ?? "")), resolve(args.terminal)?.id)
   );
+  if (options.allowAgentConfirm) {
+    reg(
+      "terminal_confirm",
+      "Confirm + execute a staged command by id (pendingMode).",
+      { id: { type: "string" } },
+      ["id"],
+      async (args) => {
+        const id = String(args.id);
+        const entry = staged.get(id);
+        if (!entry) return errorResult(`No staged command ${id}`);
+        const t = resolve(entry.terminalId);
+        if (!t) return errorResult(`Terminal '${entry.terminalId}' is gone \u2014 cannot run ${id}`);
+        staged.delete(id);
+        await exec(t, entry.kind, entry.data);
+        return textResult(`Confirmed ${id}: ${entry.kind} on ${t.id} ${truncate(entry.data)}`, {
+          ...entry,
+          length: entry.data.length,
+          executed: true
+        });
+      },
+      true,
+      (args) => {
+        const e = staged.get(String(args.id));
+        return target(`confirm:${String(args.id ?? "")}`, e?.terminalId);
+      }
+    );
+    reg(
+      "terminal_reject",
+      "Drop a staged command by id without executing it.",
+      { id: { type: "string" } },
+      ["id"],
+      (args) => {
+        const id = String(args.id);
+        if (!staged.delete(id)) return errorResult(`No staged command ${id}`);
+        return textResult(`Rejected ${id}`, { id, rejected: true });
+      },
+      false
+    );
+  }
   if (canClear) {
     reg(
       "terminal_clear",
@@ -2908,8 +2996,10 @@ function registerTerminalBridge(host, options) {
         if (!t.setShell) return errorResult(`Terminal '${t.id}' can't switch shells.`);
         const id = String(args.id);
         const shells = t.listShells?.();
-        if (shells && shells.length && !shells.some((s) => s.id === id)) {
-          return errorResult(`Unknown shell '${id}' for ${t.id}. Use terminal_list_shells for valid ids.`);
+        if (!shells || !shells.some((s) => s.id === id)) {
+          return errorResult(
+            `Unknown or unlisted shell '${id}' for ${t.id}. Call terminal_list_shells for valid ids.`
+          );
         }
         await t.setShell(id);
         return textResult(`Switched ${t.id} shell to ${id}`, { shell: id, terminal: t.id });
@@ -3050,6 +3140,12 @@ function registerNavigationBridge(host, options) {
       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 = adapter.getLocation().url;
       await adapter.visit(url);
       fancyAutoCommon.pushUndoEntry(agent.id, {
@@ -4034,8 +4130,7 @@ function describeSession(id, token) {
 }
 function buildShareUrl(descriptor, baseUrl = typeof window !== "undefined" ? window.location.href.split("?")[0] : "") {
   const u = new URL(baseUrl);
-  u.searchParams.set("session", descriptor.id);
-  u.searchParams.set("token", descriptor.token);
+  u.hash = new URLSearchParams({ session: descriptor.id, token: descriptor.token }).toString();
   return u.toString();
 }
 function buildShareConfig(descriptor, transport = "broadcast-channel") {
@@ -4050,9 +4145,10 @@ function buildShareConfig(descriptor, transport = "broadcast-channel") {
 }
 function readSessionFromUrl() {
   if (typeof window === "undefined") return null;
-  const params = new URL(window.location.href).searchParams;
-  const id = params.get("session");
-  const token = params.get("token");
+  const url = new URL(window.location.href);
+  const frag = new URLSearchParams(url.hash.replace(/^#/, ""));
+  const id = frag.get("session") ?? url.searchParams.get("session");
+  const token = frag.get("token") ?? url.searchParams.get("token");
   if (!id || !token) return null;
   return describeSession(id, token);
 }