@particle-academy/agent-integrations 0.25.0 → 0.27.0

package/dist/index.cjs

@@ -2,6 +2,7 @@
 
 var fancyAutoCommon = require('@particle-academy/fancy-auto-common');
 var react = require('react');
+var fancyDocCommons = require('@particle-academy/fancy-doc-commons');
 var jsxRuntime = require('react/jsx-runtime');
 var reactDom = require('react-dom');
 
@@ -285,12 +286,89 @@ function extractMeta(result) {
   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/forms.ts
 var DEFAULT_AGENT = { id: "agent", name: "Agent", color: "#a855f7" };
 function registerFormBridge(host, options) {
   const { adapter } = options;
   const agent = { ...DEFAULT_AGENT, ...options.agent ?? {} };
   const disposers = [];
+  ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });
   const formId = adapter.id;
   const target = (args) => ({
     kind: "form",
@@ -443,6 +521,7 @@ function registerSheetsBridge(host, options) {
   const { adapter } = options;
   const agent = { ...DEFAULT_AGENT2, ...options.agent ?? {} };
   const disposers = [];
+  ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });
   const target = (sheetId, address) => ({
     kind: "sheet",
     screenId: adapter.screenId,
@@ -789,6 +868,7 @@ function registerCodeBridge(host, options) {
   const { adapter } = options;
   const agent = { ...DEFAULT_AGENT3, ...options.agent ?? {} };
   const disposers = [];
+  ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });
   const target = {
     kind: "code",
     screenId: adapter.screenId,
@@ -955,6 +1035,7 @@ function registerChartsBridge(host, options) {
   const { adapter } = options;
   const agent = { ...DEFAULT_AGENT4, ...options.agent ?? {} };
   const disposers = [];
+  ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });
   const target = {
     kind: "chart",
     screenId: adapter.screenId,
@@ -1069,6 +1150,7 @@ function registerSceneBridge(host, options) {
   const { adapter } = options;
   const agent = { ...DEFAULT_AGENT5, ...options.agent ?? {} };
   const disposers = [];
+  ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });
   const target = (objectId) => ({
     kind: "scene",
     screenId: adapter.screenId,
@@ -1266,6 +1348,7 @@ function registerScreensBridge(host, options) {
   const { adapter } = options;
   const agent = { ...DEFAULT_AGENT6, ...options.agent ?? {} };
   const disposers = [];
+  ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });
   const target = (screenId) => ({
     kind: "screens",
     screenId,
@@ -1440,6 +1523,7 @@ function registerSlidesBridge(host, options) {
   const { adapter } = options;
   const agent = { ...DEFAULT_AGENT7, ...options.agent ?? {} };
   const disposers = [];
+  ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });
   const deckTarget = () => ({
     kind: "deck",
     screenId: adapter.screenId,
@@ -1876,84 +1960,8 @@ function firstTextContent(slide) {
   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/map.ts
-var DEFAULT_AGENT8 = { id: "agent", name: "Agent", color: "#7c3aed" };
+var DEFAULT_AGENT8 = { id: "agent", name: "Agent", color: "#a855f7" };
 var num2 = (v, fallback) => typeof v === "number" && Number.isFinite(v) ? v : 0;
 var str2 = (v, fallback = "") => typeof v === "string" ? v : fallback;
 var newId = (prefix) => `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 7)}`;
@@ -2280,7 +2288,7 @@ function registerMapBridge(host, options) {
 }
 
 // src/bridges/files.ts
-var DEFAULT_AGENT9 = { id: "agent", name: "Agent", color: "#0ea5e9" };
+var DEFAULT_AGENT9 = { id: "agent", name: "Agent", color: "#a855f7" };
 var str3 = (v, fallback = "") => typeof v === "string" ? v : fallback;
 var num3 = (v, fallback) => typeof v === "number" && Number.isFinite(v) ? v : 0;
 var asPaths = (v) => {
@@ -3479,6 +3487,314 @@ function registerFeaturesBridge(host, options) {
     }
   };
 }
+var DEFAULT_AGENT14 = { id: "agent", name: "Agent", color: "#a855f7" };
+function registerDocBridge(host, options) {
+  const { adapter, surface } = options;
+  const agent = { ...DEFAULT_AGENT14, ...options.agent ?? {} };
+  const reducer = options.reducer ?? fancyDocCommons.treeReducer();
+  const stage = options.stagePolicy ?? fancyDocCommons.autoApply;
+  const makeNode = options.makeNode ?? (({ id, type, parent, order }, props) => ({ id, type, parent, order, props }));
+  const describeNode = options.describeNode ?? ((n) => ({ id: n.id, type: n.type, parent: n.parent, props: Object.keys(n.props ?? {}) }));
+  const disposers = [];
+  ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });
+  let idSeq = 0;
+  const mintId = () => adapter.newId?.() ?? `${surface}-${idSeq += 1}`;
+  const target = (elementId) => ({ kind: surface, screenId: adapter.screenId, elementId });
+  const pending = /* @__PURE__ */ new Map();
+  function commit(op, label, targetId) {
+    const prev = adapter.get();
+    const next = reducer.reduce(prev, op);
+    adapter.set(next);
+    fancyAutoCommon.pushUndoEntry(agent.id, {
+      timestamp: Date.now(),
+      bridgeId: surface,
+      action: label,
+      label,
+      undo: () => adapter.set(prev),
+      redo: () => adapter.set(next)
+    });
+    return { ok: true, id: targetId };
+  }
+  function submit(op, label, targetId) {
+    if (stage(op) === "confirm") {
+      const id = `${surface}-pending-${idSeq += 1}`;
+      pending.set(id, { op, label, targetId });
+      options.onPending?.({ id, op, label });
+      return { staged: true, id };
+    }
+    commit(op, label, targetId);
+    return { staged: false, id: targetId };
+  }
+  const reg = (verb, description, properties, required, handler, isMutation, resolveTarget) => {
+    const name = `${surface}_${verb}`;
+    const wrapped = async (args) => {
+      try {
+        const { _text, ...structured } = await handler(args);
+        return textResult(typeof _text === "string" ? _text : name, structured);
+      } catch (e) {
+        return errorResult(e instanceof Error ? e.message : String(e));
+      }
+    };
+    const final = isMutation ? wrapToolWithActivity(wrapped, {
+      toolName: name,
+      agent,
+      kind: surface,
+      screenId: adapter.screenId,
+      resolveTarget: ({ args, result }) => {
+        if (result.structuredContent?.staged) return null;
+        return resolveTarget?.(args, result.structuredContent ?? {}) ?? target();
+      }
+    }) : wrapped;
+    disposers.push(
+      host.registerTool(
+        { name, description, inputSchema: { type: "object", properties, required, additionalProperties: false } },
+        final
+      )
+    );
+  };
+  reg(
+    "describe",
+    `Summarize the ${surface} document: node count, roots, and the active surface. Call before reading or writing.`,
+    {},
+    [],
+    () => {
+      const tree = adapter.get();
+      const ids = Object.keys(tree.nodes);
+      return { nodeCount: ids.length, roots: fancyDocCommons.childrenOf(tree, null).map((n) => n.id), _text: `${ids.length} nodes` };
+    },
+    false
+  );
+  reg(
+    "get",
+    `Get the whole ${surface} document tree as JSON.`,
+    {},
+    [],
+    () => ({ tree: adapter.get(), _text: "full tree" }),
+    false
+  );
+  reg(
+    "list",
+    "List nodes (optionally the children of `parent`), in order.",
+    { parent: { type: ["string", "null"], description: "Parent id, or null/omitted for roots." } },
+    [],
+    (args) => {
+      const tree = adapter.get();
+      const parent = typeof args.parent === "string" ? args.parent : null;
+      return { nodes: fancyDocCommons.childrenOf(tree, parent).map(describeNode), _text: `children of ${parent ?? "root"}` };
+    },
+    false
+  );
+  reg(
+    "get_node",
+    "Get one node by id.",
+    { id: { type: "string" } },
+    ["id"],
+    (args) => {
+      const node = adapter.get().nodes[String(args.id)];
+      if (!node) throw new Error(`No node ${args.id}`);
+      return { node, _text: `node ${node.id}` };
+    },
+    false
+  );
+  reg(
+    "add",
+    "Insert a node. Returns its id. Appends under `parent` (or roots) unless `order` is given.",
+    {
+      type: { type: "string", description: "Node type discriminant." },
+      parent: { type: ["string", "null"], description: "Parent id, or null for a root." },
+      props: { type: "object", description: "JSON props bag." },
+      order: { type: "string", description: "Fractional order key (default: append)." }
+    },
+    ["type"],
+    (args) => {
+      const tree = adapter.get();
+      const parent = typeof args.parent === "string" ? args.parent : null;
+      const id = mintId();
+      const order = typeof args.order === "string" ? args.order : fancyDocCommons.appendOrder(tree, parent);
+      const props = args.props && typeof args.props === "object" ? args.props : {};
+      const node = makeNode({ id, type: String(args.type), parent, order }, props);
+      const res = submit({ t: "insert", node }, `add ${args.type} ${id}`, id);
+      return { ...res, _text: res.staged ? `staged add ${id}` : `added ${id}` };
+    },
+    true,
+    (_args, result) => target(result.id)
+  );
+  reg(
+    "update",
+    "Merge a props patch into a node.",
+    { id: { type: "string" }, patch: { type: "object" } },
+    ["id", "patch"],
+    (args) => {
+      const id = String(args.id);
+      if (!adapter.get().nodes[id]) throw new Error(`No node ${id}`);
+      const patch = args.patch && typeof args.patch === "object" ? args.patch : {};
+      const res = submit({ t: "set_props", id, patch }, `update ${id}`, id);
+      return { ...res, id, _text: res.staged ? `staged update ${id}` : `updated ${id}` };
+    },
+    true,
+    (args) => target(String(args.id))
+  );
+  reg(
+    "remove",
+    "Remove a node and its subtree.",
+    { id: { type: "string" } },
+    ["id"],
+    (args) => {
+      const id = String(args.id);
+      const tree = adapter.get();
+      if (!tree.nodes[id]) throw new Error(`No node ${id}`);
+      const count = fancyDocCommons.descendantsOf(tree, id).length + 1;
+      const res = submit({ t: "remove", id }, `remove ${id} (${count} node${count === 1 ? "" : "s"})`, id);
+      return { ...res, id, removed: count, _text: res.staged ? `staged remove ${id}` : `removed ${id}` };
+    },
+    true,
+    (args) => target(String(args.id))
+  );
+  reg(
+    "move",
+    "Reparent + reorder a node.",
+    { id: { type: "string" }, parent: { type: ["string", "null"] }, order: { type: "string", description: "Fractional order key (default: append under the new parent)." } },
+    ["id"],
+    (args) => {
+      const id = String(args.id);
+      const tree = adapter.get();
+      if (!tree.nodes[id]) throw new Error(`No node ${id}`);
+      const parent = args.parent === null ? null : typeof args.parent === "string" ? args.parent : tree.nodes[id].parent;
+      const order = typeof args.order === "string" ? args.order : fancyDocCommons.appendOrder(tree, parent);
+      const res = submit({ t: "move", id, parent, order }, `move ${id}`, id);
+      return { ...res, id, _text: res.staged ? `staged move ${id}` : `moved ${id}` };
+    },
+    true,
+    (args) => target(String(args.id))
+  );
+  for (const t of options.opTools ?? []) {
+    reg(
+      t.verb,
+      t.description,
+      t.properties,
+      t.required,
+      (args) => {
+        const built = t.build(args, adapter.get());
+        if (built && typeof built === "object" && "error" in built) throw new Error(built.error);
+        const tid = t.targetId?.(args);
+        const res = submit(built, `${t.verb} ${tid ?? ""}`.trim(), tid);
+        return { ...res, id: tid, _text: res.staged ? `staged ${t.verb}` : t.verb };
+      },
+      true,
+      (args) => target(t.targetId?.(args))
+    );
+  }
+  reg(
+    "confirm",
+    "Apply a staged op by its pending id (from a staged mutation).",
+    { id: { type: "string" } },
+    ["id"],
+    (args) => {
+      const id = String(args.id);
+      const p = pending.get(id);
+      if (!p) throw new Error(`No pending op ${id}`);
+      pending.delete(id);
+      commit(p.op, p.label, p.targetId);
+      return { ok: true, applied: p.label, id: p.targetId, _text: `applied ${p.label}` };
+    },
+    true,
+    (_args, result) => target(result.id)
+  );
+  reg(
+    "reject",
+    "Discard a staged op by its pending id.",
+    { id: { type: "string" } },
+    ["id"],
+    (args) => {
+      const id = String(args.id);
+      const p = pending.get(id);
+      if (!p) throw new Error(`No pending op ${id}`);
+      pending.delete(id);
+      return { ok: true, rejected: p.label, _text: `rejected ${p.label}` };
+    },
+    false
+  );
+  return {
+    id: surface,
+    title: surface,
+    dispose: () => {
+      for (const d of disposers) d();
+      pending.clear();
+    }
+  };
+}
+function cmsReducer() {
+  const base = fancyDocCommons.treeReducer();
+  return {
+    reduce(doc, op) {
+      if (op.t === "set_style") {
+        const node = doc.nodes[op.id];
+        if (!node) return doc;
+        return { nodes: { ...doc.nodes, [op.id]: { ...node, style: { ...node.style, base: { ...node.style.base, ...op.patch } } } } };
+      }
+      if (op.t === "set_layout") {
+        const node = doc.nodes[op.id];
+        if (!node) return doc;
+        return { nodes: { ...doc.nodes, [op.id]: { ...node, layout: op.layout } } };
+      }
+      return base.reduce(doc, op);
+    },
+    invert(doc, op) {
+      if (op.t === "set_style") {
+        const node = doc.nodes[op.id];
+        if (!node) return [];
+        const prev = {};
+        for (const k in op.patch) prev[k] = node.style.base[k];
+        return [{ t: "set_style", id: op.id, patch: prev }];
+      }
+      if (op.t === "set_layout") {
+        const node = doc.nodes[op.id];
+        if (!node) return [];
+        return [{ t: "set_layout", id: op.id, layout: node.layout }];
+      }
+      return base.invert(doc, op);
+    }
+  };
+}
+function registerCmsBridge(host, options) {
+  return registerDocBridge(host, {
+    adapter: options.adapter,
+    surface: "cms",
+    agent: options.agent,
+    reducer: cmsReducer(),
+    stagePolicy: options.stagePolicy,
+    onPending: options.onPending,
+    // New nodes get an empty base style so they satisfy StyledNode.
+    makeNode: ({ id, type, parent, order }, props) => ({ id, type, parent, order, props, style: { base: {} } }),
+    describeNode: (n) => ({ id: n.id, type: n.type, parent: n.parent, layout: n.layout }),
+    opTools: [
+      {
+        verb: "set_style",
+        description: "Merge a StyleProps patch into a node's base style (color, background, padding, fontSize, gap, \u2026).",
+        properties: { id: { type: "string" }, patch: { type: "object", description: "Partial StyleProps." } },
+        required: ["id", "patch"],
+        build: (args, tree) => {
+          const id = String(args.id);
+          if (!tree.nodes[id]) return { error: `No node ${id}` };
+          return { t: "set_style", id, patch: args.patch && typeof args.patch === "object" ? args.patch : {} };
+        },
+        targetId: (args) => String(args.id)
+      },
+      {
+        verb: "set_layout",
+        description: "Set a container node's layout mode (free | stack | grid).",
+        properties: { id: { type: "string" }, layout: { type: "string", enum: ["free", "stack", "grid"] } },
+        required: ["id"],
+        build: (args, tree) => {
+          const id = String(args.id);
+          if (!tree.nodes[id]) return { error: `No node ${id}` };
+          return { t: "set_layout", id, layout: args.layout };
+        },
+        targetId: (args) => String(args.id)
+      }
+    ]
+  });
+}
 
 // src/sharing/token.ts
 var TOKEN_BYTES = 24;
@@ -3674,11 +3990,11 @@ function attachSseRelay(server, options) {
 
 // src/sharing/use-co-browse-session.ts
 init_registry();
-var DEFAULT_AGENT14 = { id: "agent", name: "Agent", color: "#a855f7" };
+var DEFAULT_AGENT15 = { id: "agent", name: "Agent", color: "#a855f7" };
 var USER = { id: "human", name: "You" };
 function useCoBrowseSession(options) {
   const { adapter, extraBridges } = options;
-  const agent = { ...DEFAULT_AGENT14, ...options.agent ?? {} };
+  const agent = { ...DEFAULT_AGENT15, ...options.agent ?? {} };
   const relayBaseUrl = options.relayBaseUrl ?? "/agent-relay";
   const serverRef = react.useRef(null);
   const relayRef = react.useRef(null);
@@ -4892,6 +5208,7 @@ exports.buildMcpbProxyStub = buildMcpbProxyStub;
 exports.buildShareConfig = buildShareConfig;
 exports.buildShareUrl = buildShareUrl;
 exports.buildVscodeDeeplink = buildVscodeDeeplink;
+exports.cmsReducer = cmsReducer;
 exports.connectorHref = connectorHref;
 exports.createSessionDescriptor = createSessionDescriptor;
 exports.describeSession = describeSession;
@@ -4902,7 +5219,9 @@ exports.mapActivityToHeuristicsEvent = mapActivityToEvent;
 exports.readSessionFromUrl = readSessionFromUrl;
 exports.registerCatalogBridge = registerCatalogBridge;
 exports.registerChartsBridge = registerChartsBridge;
+exports.registerCmsBridge = registerCmsBridge;
 exports.registerCodeBridge = registerCodeBridge;
+exports.registerDocBridge = registerDocBridge;
 exports.registerFeaturesBridge = registerFeaturesBridge;
 exports.registerFilesBridge = registerFilesBridge;
 exports.registerFormBridge = registerFormBridge;