@buoy-gg/shared-ui 7.0.35 → 7.0.38

package/lib/commonjs/sync/keyedArrays.js

@@ -0,0 +1,209 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.expandKeyedArrays = expandKeyedArrays;
+exports.identityField = identityField;
+/**
+ * Id-addressed list edits — one implementation, shared by every adapter that
+ * takes a merge patch.
+ *
+ * WHY. Resending a whole array is correct only when the caller has SEEN the
+ * whole array, and reads are capped. Measured with a 20-item list truncated to
+ * 5 (`pnpm ai:array --truncate=5`): the whole-array form scored 0/9 across three
+ * models — two refused outright, and one silently sent back only the 5 items it
+ * had been shown, destroying the other 15. Addressed edits scored 9/9.
+ *
+ * It also makes mass deletion impossible BY OMISSION: an addressed edit can only
+ * remove ids it names. Sending a real array still replaces the list, which is
+ * how a caller deliberately empties one.
+ *
+ * This lives here rather than in one adapter because react-query, zustand and
+ * network all take merge patches, and a second copy of a data-destroying safety
+ * rule is a copy that drifts.
+ */
+const isPlainObject = v => typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** Fields we will treat as an item's stable identity, best first. */
+const ID_FIELDS = ["id", "lineId", "key", "uuid", "_id", "slug", "name"];
+
+/**
+ * The field that identifies items in this list, or undefined if there isn't one.
+ *
+ * Every item must carry it, and every value must be a distinct string/number —
+ * a duplicated id would make an addressed edit ambiguous, and silently picking
+ * the first match is exactly the kind of "helpful" guess that loses data.
+ */
+function identityField(items) {
+  if (!items.length || !items.every(isPlainObject)) return undefined;
+  const first = items[0];
+  for (const f of ID_FIELDS) {
+    if (!(f in first)) continue;
+    const values = items.map(it => it[f]);
+    const usable = values.every(v => typeof v === "string" || typeof v === "number");
+    if (!usable) continue;
+    if (new Set(values.map(String)).size !== values.length) continue;
+    return f;
+  }
+  return undefined;
+}
+
+/**
+ * The identity an ADDED item should carry.
+ *
+ * `Object.entries` hands back STRING keys, so `{"9901": {id: 9901, …}}` was
+ * written as `{id: "9901"}` — the caller's own numeric id replaced by text, and
+ * then refused by the typed-edit guard as `[2].id: number → string`. The caller
+ * recovers by resending the WHOLE array, which is exactly the truncation-unsafe
+ * move this module exists to prevent. Measured on a live QA run: one added
+ * offer cost a refusal, a full-list retransmission and 35 seconds.
+ *
+ * So the id the caller WROTE wins. With no id in the body, the key is coerced
+ * to the type the existing items use, and only when the text round-trips
+ * exactly: "007" is not 7, and inventing that identity is worse than a refusal
+ * the caller can read.
+ */
+function identityForAdd(current, idField, key, edit) {
+  const supplied = edit[idField];
+  if (typeof supplied === "string" || typeof supplied === "number") {
+    // An item whose id disagrees with the address it was sent under is
+    // ambiguous — either could be the one the caller meant. Say so rather than
+    // silently picking one and writing an item nobody asked for.
+    if (String(supplied) !== key) {
+      return {
+        ok: false,
+        error: `The new item is addressed as \`${key}\` but carries \`${idField}\`: ${JSON.stringify(supplied)}. Use the same value for both — address it by the id it carries.`
+      };
+    }
+    return {
+      ok: true,
+      value: supplied
+    };
+  }
+  const numericList = current.every(it => typeof it[idField] === "number");
+  if (numericList && key.trim() !== "" && String(Number(key)) === key) {
+    return {
+      ok: true,
+      value: Number(key)
+    };
+  }
+  return {
+    ok: true,
+    value: key
+  };
+}
+
+/**
+ * Let a caller address list items by their own id instead of resending the list.
+ *
+ *   { lines: { "seed-1": { qty: 5 } } }   change one field of one item
+ *   { lines: { "seed-2": null } }         remove that item
+ *   { lines: { "new-1": { …all fields… } } }  append (id not already present)
+ *
+ * WHY THIS EXISTS. Resending the whole array is correct only when the caller has
+ * SEEN the whole array, and reads are capped — so on a long list the honest
+ * agents refuse and the careless ones send back only the items they were shown,
+ * silently destroying the rest. Measured: with a 20-item bag truncated to 5, the
+ * whole-array form scored 0/9 across three models and one of them deleted 15
+ * lines without a word. Addressed edits scored 9/9. (`pnpm ai:array`.)
+ *
+ * It also makes mass deletion impossible BY OMISSION: `lines: []` empties a bag,
+ * but a keyed edit can only remove ids it names.
+ *
+ * Returns the patch with keyed objects expanded into real arrays, so everything
+ * downstream — the typed-edit guard, the receipt, the store write — is unchanged
+ * and keeps all of its protections.
+ */
+function expandKeyedArrays(current, patch, path = "", notes = []) {
+  if (Array.isArray(current) && isPlainObject(patch)) {
+    const idField = identityField(current);
+    if (!idField) {
+      // No stable identity: leave it alone and let the normal guard report the
+      // object-vs-array type change, which says something truer than we could.
+      return {
+        patch,
+        notes
+      };
+    }
+    const byId = new Map(current.map(it => [String(it[idField]), it]));
+    const next = current.slice();
+    let removed = 0;
+    let changed = 0;
+    let added = 0;
+    for (const [id, edit] of Object.entries(patch)) {
+      const i = next.findIndex(it => String(it[idField]) === id);
+      if (edit === null) {
+        if (i === -1) return {
+          patch,
+          notes
+        };
+        next.splice(i, 1);
+        removed++;
+      } else if (i === -1) {
+        if (!isPlainObject(edit)) return {
+          patch,
+          notes
+        };
+        const identity = identityForAdd(current, idField, id, edit);
+        if (!identity.ok) {
+          return {
+            patch,
+            notes,
+            error: identity.error
+          };
+        }
+        next.push({
+          ...edit,
+          [idField]: identity.value
+        });
+        added++;
+      } else {
+        const merged = expandKeyedArrays(byId.get(id), edit, `${path}[${id}]`, notes);
+        if (merged.error) return {
+          patch,
+          notes,
+          error: merged.error
+        };
+        const base = next[i];
+        next[i] = isPlainObject(base) && isPlainObject(merged.patch) ? {
+          ...base,
+          ...merged.patch
+        } : merged.patch;
+        changed++;
+      }
+    }
+    notes.push(`${path || "(root)"}: addressed by \`${idField}\` — ${changed} changed, ${added} added, ${removed} removed, ${next.length} item(s) remain`);
+    return {
+      patch: next,
+      notes
+    };
+  }
+  if (isPlainObject(current) && isPlainObject(patch)) {
+    const outPatch = {};
+    for (const [k, v] of Object.entries(patch)) {
+      const p = path ? `${path}.${k}` : k;
+      if (!(k in current)) {
+        outPatch[k] = v;
+        continue;
+      }
+      const inner = expandKeyedArrays(current[k], v, p, notes);
+      // A refusal deep in the tree is the whole patch's refusal: writing the
+      // rest of it would apply half of what the caller asked for.
+      if (inner.error) return {
+        patch,
+        notes,
+        error: inner.error
+      };
+      outPatch[k] = inner.patch;
+    }
+    return {
+      patch: outPatch,
+      notes
+    };
+  }
+  return {
+    patch,
+    notes
+  };
+}

package/lib/commonjs/sync/toolActionRegistry.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.dispatchToolAction = dispatchToolAction;
 exports.getToolAdapters = getToolAdapters;
+exports.guardToolAdapter = guardToolAdapter;
 exports.isToolRegistryReady = isToolRegistryReady;
 exports.listSnapshotToolIds = listSnapshotToolIds;
 exports.listToolActions = listToolActions;
@@ -12,6 +13,7 @@ exports.listToolIds = listToolIds;
 exports.readToolSnapshot = readToolSnapshot;
 exports.registerToolAdapters = registerToolAdapters;
 exports.waitForToolRegistry = waitForToolRegistry;
+var _licenseModule = require("../license/licenseModule.js");
 /**
  * toolActionRegistry — the on-device twin of the broker's action dispatch.
  *
@@ -68,13 +70,45 @@ function sources() {
 function registerToolAdapters(getTools) {
   const set = sources();
   set.add(getTools);
+  let disposed = false;
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    const raw = getTools();
+    // Private inverse operations only. No credential bypass reaches public dispatch.
+    const cleanup = async (toolId, action, params) => {
+      if (!(toolId === "network" && action === "deleteOverrideRule" || toolId === "impersonate" && action === "stopImpersonation")) {
+        throw new Error("Unsupported account-lock cleanup operation");
+      }
+      if (toolId === "impersonate") return raw[toolId]?.dispose?.(cleanup);
+      const fn = raw[toolId]?.actions?.[action];
+      if (!fn) throw new Error(`Cleanup unavailable for ${toolId}`);
+      return fn(params);
+    };
+    for (const adapter of Object.values(raw)) {
+      try {
+        Promise.resolve(adapter.dispose?.(cleanup)).catch(error => console.warn("[Buoy] Tool cleanup failed", error));
+      } catch (error) {
+        console.warn("[Buoy] Tool cleanup failed", error);
+      }
+    }
+  };
+  const off = (0, _licenseModule.subscribeAccountAccess)(() => {
+    if (!(0, _licenseModule.hasAccountAccess)()) dispose();else disposed = false;
+  });
   return () => {
+    off();
     set.delete(getTools);
+    // A second provider still owns these adapters during Strict Mode/remount.
+    Promise.resolve().then(() => {
+      if (set.size === 0) dispose();
+    });
   };
 }
 
 /** The merged adapter map across every live source. */
 function getToolAdapters() {
+  if (!(0, _licenseModule.hasAccountAccess)()) return {};
   const merged = {};
   for (const get of sources()) {
     try {
@@ -83,7 +117,7 @@ function getToolAdapters() {
       // A source that throws must not take the whole registry down.
     }
   }
-  return merged;
+  return Object.fromEntries(Object.entries(merged).map(([id, adapter]) => [id, guardToolAdapter(adapter)]));
 }
 
 /** Tool ids currently dispatchable. */
@@ -123,6 +157,7 @@ function listSnapshotToolIds() {
  * an adapter is free to make this a promise later without breaking them.
  */
 async function readToolSnapshot(toolId) {
+  (0, _licenseModule.assertAccountAccess)();
   const tools = getToolAdapters();
   const adapter = tools[toolId];
   if (!adapter) throw new Error(`Unknown tool "${toolId}"`);
@@ -132,7 +167,7 @@ async function readToolSnapshot(toolId) {
   return await adapter.getSnapshot();
 }
 function isToolRegistryReady() {
-  return sources().size > 0;
+  return (0, _licenseModule.hasAccountAccess)() && sources().size > 0;
 }
 
 /**
@@ -141,6 +176,7 @@ function isToolRegistryReady() {
  * surface as plain messages rather than objects nobody can read on a phone.
  */
 async function dispatchToolAction(toolId, action, params) {
+  (0, _licenseModule.assertAccountAccess)();
   const tools = getToolAdapters();
   const tool = tools[toolId];
   const fn = tool?.actions?.[action];
@@ -163,4 +199,51 @@ async function waitForToolRegistry(timeoutMs = 2000) {
     if (isToolRegistryReady()) return true;
   }
   return false;
+}
+
+/** Guard retained references too, and discard results completed after revocation. */
+function guardToolAdapter(adapter) {
+  const guard = fn => (...args) => {
+    (0, _licenseModule.assertAccountAccess)();
+    let revoked = false;
+    const off = (0, _licenseModule.subscribeAccountAccess)(() => {
+      if (!(0, _licenseModule.hasAccountAccess)()) revoked = true;
+    });
+    const check = () => {
+      if (revoked) throw new Error("Buoy account access ended while the operation was pending.");
+      (0, _licenseModule.assertAccountAccess)();
+    };
+    try {
+      const result = fn.apply(adapter, args);
+      if (result && typeof result.then === "function") {
+        return Promise.resolve(result).then(value => {
+          check();
+          return value;
+        }).finally(off);
+      }
+      check();
+      off();
+      return result;
+    } catch (error) {
+      off();
+      throw error;
+    }
+  };
+  return {
+    ...adapter,
+    ...(adapter.getSnapshot ? {
+      getSnapshot: guard(adapter.getSnapshot)
+    } : {}),
+    ...(adapter.actions ? {
+      actions: Object.fromEntries(Object.entries(adapter.actions).map(([name, action]) => [name, guard(action)]))
+    } : {}),
+    ...(adapter.subscribe ? {
+      subscribe: listener => {
+        (0, _licenseModule.assertAccountAccess)();
+        return adapter.subscribe(() => {
+          if ((0, _licenseModule.hasAccountAccess)()) listener();
+        });
+      }
+    } : {})
+  };
 }

package/lib/commonjs/sync/toolAttention.test.js

@@ -0,0 +1,51 @@
+"use strict";
+
+var _vitest = require("vitest");
+var _toolUiBridge = require("./toolUiBridge.js");
+/**
+ * The attention badge seam: a tool says "I need you" and the rail hears it.
+ */
+
+(0, _vitest.describe)("toolAttention", () => {
+  (0, _vitest.it)("stores, replaces and clears a badge, notifying once per change", () => {
+    const fn = _vitest.vi.fn();
+    const off = (0, _toolUiBridge.subscribeToolAttention)(fn);
+    (0, _toolUiBridge.setToolAttention)("ask-buoy", {
+      kind: "needsInput",
+      label: "Needs your approval"
+    });
+    (0, _vitest.expect)((0, _toolUiBridge.getToolAttention)("ask-buoy")).toEqual({
+      kind: "needsInput",
+      label: "Needs your approval"
+    });
+    (0, _vitest.expect)(fn).toHaveBeenCalledTimes(1);
+    // Same value again is not a change.
+    (0, _toolUiBridge.setToolAttention)("ask-buoy", {
+      kind: "needsInput",
+      label: "Needs your approval"
+    });
+    (0, _vitest.expect)(fn).toHaveBeenCalledTimes(1);
+    (0, _toolUiBridge.setToolAttention)("ask-buoy", {
+      kind: "done",
+      label: "Finished"
+    });
+    (0, _vitest.expect)(fn).toHaveBeenCalledTimes(2);
+    (0, _toolUiBridge.setToolAttention)("ask-buoy", null);
+    (0, _vitest.expect)((0, _toolUiBridge.getToolAttention)("ask-buoy")).toBeNull();
+    (0, _vitest.expect)(fn).toHaveBeenCalledTimes(3);
+    // Clearing what is already clear is silent.
+    (0, _toolUiBridge.setToolAttention)("ask-buoy", null);
+    (0, _vitest.expect)(fn).toHaveBeenCalledTimes(3);
+    off();
+  });
+  (0, _vitest.it)("keeps tools apart", () => {
+    (0, _toolUiBridge.setToolAttention)("a", {
+      kind: "failed",
+      label: "x"
+    });
+    (0, _toolUiBridge.setToolAttention)("b", null);
+    (0, _vitest.expect)((0, _toolUiBridge.getToolAttention)("a")?.kind).toBe("failed");
+    (0, _vitest.expect)((0, _toolUiBridge.getToolAttention)("b")).toBeNull();
+    (0, _toolUiBridge.setToolAttention)("a", null);
+  });
+});

package/lib/commonjs/sync/toolUiBridge.js

@@ -4,8 +4,11 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.canOpenBuoyTools = canOpenBuoyTools;
+exports.getToolAttention = getToolAttention;
 exports.openBuoyTool = openBuoyTool;
 exports.registerToolOpener = registerToolOpener;
+exports.setToolAttention = setToolAttention;
+exports.subscribeToolAttention = subscribeToolAttention;
 /**
  * toolUiBridge — let a tool ask the host to bring another tool back on screen.
  *
@@ -71,4 +74,59 @@ function openBuoyTool(toolId) {
 /** True when some host is listening — for deciding whether to offer the button. */
 function canOpenBuoyTools() {
   return openers().size > 0;
+}
+
+// ─── Attention ───────────────────────────────────────────────────────────────
+
+/**
+ * "This tool needs you" — shown as a badge on its chip in the minimized rail.
+ *
+ * The case: Ask Buoy is minimized so a tester can watch the app, and the
+ * agent hits a step that needs a tap. Nobody can see the card. The sheet used
+ * to fail safe by DECLINING the change and ending the turn — which made
+ * minimize mean "stop", the opposite of what it is for. Now the approval
+ * holds, the chip gets a badge, and tapping the chip (the existing restore
+ * path) brings the card back. Same seam shape as the opener above: the rail
+ * lives inside the host, the tool cannot import the host, so it publishes
+ * through a global.
+ *
+ * `done` and `failed` cover the other thing a hidden tool cannot say — that
+ * the work you minimized it to wait for has finished.
+ */
+
+const ATTENTION_KEY = "__buoyToolAttention";
+function attention() {
+  const g = globalThis;
+  if (!g[ATTENTION_KEY]) g[ATTENTION_KEY] = {
+    byTool: new Map(),
+    listeners: new Set()
+  };
+  return g[ATTENTION_KEY];
+}
+
+/** Set, replace or (with null) clear a tool's badge. No-op when nothing changed. */
+function setToolAttention(toolId, next) {
+  const store = attention();
+  const prev = store.byTool.get(toolId) ?? null;
+  if (prev === next || prev && next && prev.kind === next.kind && prev.label === next.label) return;
+  if (next) store.byTool.set(toolId, next);else store.byTool.delete(toolId);
+  for (const fn of store.listeners) {
+    try {
+      fn();
+    } catch {
+      // A throwing subscriber must not stop the others from hearing.
+    }
+  }
+}
+function getToolAttention(toolId) {
+  return attention().byTool.get(toolId) ?? null;
+}
+
+/** For `useSyncExternalStore` in the rail. */
+function subscribeToolAttention(fn) {
+  const store = attention();
+  store.listeners.add(fn);
+  return () => {
+    store.listeners.delete(fn);
+  };
 }