@particle-academy/agent-integrations 0.35.0 → 0.36.0

package/dist/index.cjs

@@ -4093,7 +4093,15 @@ function registerDocBridge(host, options) {
   const disposers = [];
   ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });
   let idSeq = 0;
-  const mintId = () => adapter.newId?.() ?? `${surface}-${idSeq += 1}`;
+  const mintId = () => {
+    if (adapter.newId) return adapter.newId();
+    const taken = adapter.get().nodes;
+    let id;
+    do
+      id = `${surface}-${idSeq += 1}`;
+    while (taken[id]);
+    return id;
+  };
   const target = (elementId) => ({ kind: surface, screenId: adapter.screenId, elementId });
   const pending = /* @__PURE__ */ new Map();
   function commit(op, label, targetId) {
@@ -4112,10 +4120,10 @@ function registerDocBridge(host, options) {
   }
   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 };
+      const pendingId = `${surface}-pending-${idSeq += 1}`;
+      pending.set(pendingId, { op, label, targetId });
+      options.onPending?.({ id: pendingId, op, label });
+      return { staged: true, id: targetId, pendingId };
     }
     commit(op, label, targetId);
     return { staged: false, id: targetId };
@@ -4198,18 +4206,26 @@ function registerDocBridge(host, options) {
       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)." }
+      order: { type: "string", description: "Fractional order key (default: append)." },
+      id: {
+        type: "string",
+        description: "Id for the new node. Supply a meaningful one if you intend to address this node later; omitted means one is minted for you. Must not already exist."
+      }
     },
     ["type"],
     (args) => {
       const tree = adapter.get();
       const parent = typeof args.parent === "string" ? args.parent : null;
-      const id = mintId();
+      const requested = typeof args.id === "string" ? args.id : void 0;
+      if (requested !== void 0 && tree.nodes[requested]) {
+        throw new Error(`Node ${requested} already exists \u2014 pick a different id or update it instead`);
+      }
+      const id = requested ?? 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}` };
+      return { ...res, _text: res.staged ? `staged add ${id} \u2014 confirm ${res.pendingId}` : `added ${id}` };
     },
     true,
     (_args, result) => target(result.id)
@@ -4224,7 +4240,7 @@ function registerDocBridge(host, options) {
       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}` };
+      return { ...res, id, _text: res.staged ? `staged update ${id} \u2014 confirm ${res.pendingId}` : `updated ${id}` };
     },
     true,
     (args) => target(String(args.id))
@@ -4240,7 +4256,7 @@ function registerDocBridge(host, options) {
       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}` };
+      return { ...res, id, removed: count, _text: res.staged ? `staged remove ${id} \u2014 confirm ${res.pendingId}` : `removed ${id}` };
     },
     true,
     (args) => target(String(args.id))
@@ -4257,7 +4273,7 @@ function registerDocBridge(host, options) {
       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}` };
+      return { ...res, id, _text: res.staged ? `staged move ${id} \u2014 confirm ${res.pendingId}` : `moved ${id}` };
     },
     true,
     (args) => target(String(args.id))
@@ -4273,7 +4289,7 @@ function registerDocBridge(host, options) {
         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 };
+        return { ...res, id: tid, _text: res.staged ? `staged ${t.verb} \u2014 confirm ${res.pendingId}` : t.verb };
       },
       true,
       (args) => target(t.targetId?.(args))
@@ -4281,8 +4297,8 @@ function registerDocBridge(host, options) {
   }
   reg(
     "confirm",
-    "Apply a staged op by its pending id (from a staged mutation).",
-    { id: { type: "string" } },
+    "Apply a staged op. Pass the `pendingId` a staged mutation returned \u2014 not the node `id` it also returns.",
+    { id: { type: "string", description: "The `pendingId` from a staged mutation." } },
     ["id"],
     (args) => {
       const id = String(args.id);
@@ -4297,8 +4313,8 @@ function registerDocBridge(host, options) {
   );
   reg(
     "reject",
-    "Discard a staged op by its pending id.",
-    { id: { type: "string" } },
+    "Discard a staged op. Pass the `pendingId` a staged mutation returned \u2014 not the node `id` it also returns.",
+    { id: { type: "string", description: "The `pendingId` from a staged mutation." } },
     ["id"],
     (args) => {
       const id = String(args.id);
@@ -4390,6 +4406,90 @@ function registerCmsBridge(host, options) {
     ]
   });
 }
+var SCREEN_TEXT_NODE_TYPE = "#text";
+function registerScreenDocBridge(host, options) {
+  const { adapter } = options;
+  const surface = options.surface ?? "screen";
+  const setText = {
+    verb: "set_text",
+    description: "Replace the literal text of an element node \u2014 the natural way to change a label, heading or paragraph. Pass the ELEMENT's id, not the text node's.",
+    properties: {
+      id: { type: "string", description: "Id of the element whose text to set." },
+      text: { type: "string" }
+    },
+    required: ["id", "text"],
+    build: (args, tree) => {
+      const id = String(args.id);
+      const node = tree.nodes[id];
+      if (!node) return { error: `No node ${id}` };
+      if (node.type === SCREEN_TEXT_NODE_TYPE) {
+        return { t: "set_props", id, patch: { value: String(args.text) } };
+      }
+      const texts = fancyDocCommons.childrenOf(tree, id).filter((c) => c.type === SCREEN_TEXT_NODE_TYPE);
+      if (texts.length === 1) {
+        return { t: "set_props", id: texts[0].id, patch: { value: String(args.text) } };
+      }
+      if (texts.length === 0) {
+        return {
+          t: "insert",
+          node: {
+            id: `${id}-text`,
+            type: SCREEN_TEXT_NODE_TYPE,
+            parent: id,
+            order: fancyDocCommons.appendOrder(tree, id),
+            props: { value: String(args.text) }
+          }
+        };
+      }
+      return {
+        error: `Node ${id} has ${texts.length} text children (${texts.map((t) => t.id).join(", ")}) \u2014 set_text on the one you mean`
+      };
+    },
+    targetId: (args) => String(args.id)
+  };
+  const bridge = registerDocBridge(host, {
+    adapter,
+    surface,
+    agent: options.agent,
+    stagePolicy: options.stagePolicy,
+    onPending: options.onPending,
+    // Anything the AGENT adds is authored by definition — it chose or was given
+    // the id — so it must not inherit the synthetic flag from its neighbours.
+    makeNode: ({ id, type, parent, order }, props) => ({ id, type, parent, order, props }),
+    describeNode: (n) => ({
+      id: n.id,
+      type: n.type,
+      parent: n.parent,
+      ...n.synthetic ? { synthetic: true } : {},
+      ...n.type === SCREEN_TEXT_NODE_TYPE ? { text: String(n.props?.value ?? "") } : { props: Object.keys(n.props ?? {}) }
+    }),
+    opTools: [setText]
+  });
+  const disposeAddressable = host.registerTool(
+    {
+      name: `${surface}_addressable`,
+      description: "List the node ids that are safe to remember and use later. Ids NOT listed here were minted from a node's position: they resolve today and silently point at a different node once a sibling is inserted above them. Address those in the same turn you read them, and never store one.",
+      inputSchema: { type: "object", properties: {}, required: [], additionalProperties: false }
+    },
+    (async () => {
+      const nodes = Object.values(adapter.get().nodes);
+      const authored = nodes.filter((n) => !n.synthetic).map((n) => ({ id: n.id, type: n.type }));
+      const syntheticCount = nodes.length - authored.length;
+      return textResult(
+        authored.length ? `${authored.length} addressable, ${syntheticCount} positional` : `no addressable ids \u2014 all ${syntheticCount} nodes are positional`,
+        { addressable: authored, syntheticCount }
+      );
+    })
+  );
+  return {
+    id: surface,
+    title: "Screen content",
+    dispose: () => {
+      disposeAddressable();
+      bridge.dispose();
+    }
+  };
+}
 
 // src/sharing/token.ts
 var TOKEN_BYTES = 24;
@@ -5911,6 +6011,7 @@ exports.MemoryHumanPlusEventStore = MemoryHumanPlusEventStore;
 exports.MicroMcpServer = MicroMcpServer;
 exports.PASSKEY_BRIDGE_TOOLS = PASSKEY_BRIDGE_TOOLS;
 exports.RelayTransport = RelayTransport;
+exports.SCREEN_TEXT_NODE_TYPE = SCREEN_TEXT_NODE_TYPE;
 exports.ScreensActivityBridge = ScreensActivityBridge;
 exports.ShareControls = ShareControls;
 exports.SimulateUsersButton = SimulateUsersButton;
@@ -5953,6 +6054,7 @@ exports.registerMapBridge = registerMapBridge;
 exports.registerNavigationBridge = registerNavigationBridge;
 exports.registerPasskeyBridge = registerPasskeyBridge;
 exports.registerSceneBridge = registerSceneBridge;
+exports.registerScreenDocBridge = registerScreenDocBridge;
 exports.registerScreensBridge = registerScreensBridge;
 exports.registerSheetsBridge = registerSheetsBridge;
 exports.registerSlidesBridge = registerSlidesBridge;