openzoo 0.50.37 → 0.50.39

package/lib/grokcli.js

@@ -22,6 +22,11 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { config } from './config.js';
+import {
+  GROKBOT_CDP_PORT,
+  grokBotChromiumArgs,
+  injectSpendChipInBackground,
+} from './ozSpendChip.js';
 
 const GROK_HOME = process.env.GROK_HOME || join(homedir(), '.grok');
 const CONFIG_PATH = join(GROK_HOME, 'config.toml');
@@ -134,12 +139,14 @@ function somethingTalksToPort(port, run = execSync) {
 }
 
 /** Is the running Grok Bot already pointed at our aiserver? */
-export function inspectGrokBotHijack(url, port = 8443, run = execSync) {
+export function inspectGrokBotHijack(url, port = 8443, run = execSync, cdpPort = GROKBOT_CDP_PORT) {
   const pids = grokBotPids(run);
   const needle = `CURSOR_API_BASE_URL=${url}`;
   const envHit = pids.some((pid) => pidHasNeedle(pid, needle, run));
   const tcpHit = somethingTalksToPort(port, run);
-  return { running: pids.length > 0, pids, hijacked: envHit || tcpHit };
+  const cdpNeedle = `--remote-debugging-port=${Number(cdpPort)}`;
+  const chipDebug = pids.some((pid) => pidHasNeedle(pid, cdpNeedle, run));
+  return { running: pids.length > 0, pids, hijacked: envHit || tcpHit, chipDebug };
 }
 
 /**
@@ -147,7 +154,13 @@ export function inspectGrokBotHijack(url, port = 8443, run = execSync) {
  * forceQuit = --quit / OZ_NO_QUIT=0
  * neverQuit = --no-quit / OZ_NO_QUIT=1
  */
-export function grokBotQuitPlan({ forceQuit = false, neverQuit = false, running = false, hijacked = false } = {}) {
+export function grokBotQuitPlan({
+  forceQuit = false,
+  neverQuit = false,
+  running = false,
+  hijacked = false,
+  chipDebug,
+} = {}) {
   if (forceQuit) return { quit: true, spawn: true, reason: 'forced --quit' };
   if (neverQuit) {
     return {
@@ -159,6 +172,13 @@ export function grokBotQuitPlan({ forceQuit = false, neverQuit = false, running
     };
   }
   if (!running) return { quit: false, spawn: true, reason: 'Grok Bot not running' };
+  if (hijacked && chipDebug === false) {
+    return {
+      quit: true,
+      spawn: true,
+      reason: 'hijacked but no spend-chip debug port — bouncing so the ⓘ bubble can inject',
+    };
+  }
   if (hijacked) return { quit: false, spawn: false, reason: 'already hijacked — leaving the session' };
   return {
     quit: true,
@@ -181,6 +201,10 @@ export function grokBotQuitPlan({ forceQuit = false, neverQuit = false, running
  * stubs oauth if it is the unpatched npx copy — do not point the app there.
  */
 export async function runBot(argv = []) {
+  if (argv.includes('--web')) {
+    const { runGrokBotWeb } = await import('./grokbotweb.js');
+    return runGrokBotWeb(argv);
+  }
   const port = 8443;
   const url = `https://127.0.0.1:${port}`;
   const bin = `${APP}/Contents/MacOS/Grok Bot`;
@@ -190,13 +214,9 @@ export async function runBot(argv = []) {
   }
 
   const proxyBase = `http://localhost:${config.port}/v1`;
-  let up = false;
-  try { up = (await fetch(`${proxyBase}/models`, { signal: AbortSignal.timeout(2000) })).ok; } catch { up = false; }
-  if (!up) {
-    console.error('openzoo: starting proxy on', proxyBase);
-    const { startProxy } = await import('./proxy.js');
-    await startProxy({ silent: true, autoTunnel: process.env.OPENZOO_NO_TUNNEL === '1' ? false : true });
-  }
+  console.error('openzoo: starting proxy on', proxyBase);
+  const { startProxy } = await import('./proxy.js');
+  await startProxy({ silent: true, autoTunnel: process.env.OPENZOO_NO_TUNNEL === '1' ? false : true });
 
   process.env.OPENZOO_BYOK = '1';
   const sniff = argv.includes('--sniff') || argv.includes('--passthru');
@@ -264,6 +284,7 @@ export async function runBot(argv = []) {
     neverQuit: argv.includes('--no-quit') || process.env.OZ_NO_QUIT === '1',
     running: state.running,
     hijacked: state.hijacked,
+    chipDebug: state.chipDebug,
   });
   console.error(`openzoo: grokbot ${plan.reason}`);
   if (plan.quit) {
@@ -274,7 +295,7 @@ export async function runBot(argv = []) {
   if (plan.spawn) {
     console.error('openzoo: launching Grok Bot');
     console.error(`         CURSOR_API_BASE_URL=${url}`);
-    spawn(bin, ['--ignore-certificate-errors'], {
+    spawn(bin, grokBotChromiumArgs(), {
       stdio: 'ignore',
       detached: true,
       env: {
@@ -294,6 +315,12 @@ export async function runBot(argv = []) {
     console.error('openzoo: Grok Bot already hijacked — not spawning another copy');
   }
 
+  injectSpendChipInBackground({
+    port: GROKBOT_CDP_PORT,
+    log: (m) => console.error(m),
+    delayMs: plan.spawn ? 500 : 200,
+  });
+
   console.error('openzoo: leave this running. ctrl-c stops the backend.');
   if (argv.includes('--once')) return;
   await new Promise(() => {});
@@ -303,19 +330,17 @@ export async function setupGrokBot(argv = []) {
   const base = `http://localhost:${config.port}/v1`;
   const launch = !argv.includes('--no-launch');
 
-  // 1. proxy up, or nothing can pay
+  // 1. proxy up, or nothing can pay. Always startProxy: it kills a stale
+  // listener on the port instead of reusing a PayClient that still thinks $0.
+  console.error('openzoo: starting the proxy...');
+  const { startProxy } = await import('./proxy.js');
+  await startProxy({ silent: true, autoTunnel: true });
   let up = false;
-  try { up = (await fetch(`${base}/models`, { signal: AbortSignal.timeout(3000) })).ok; } catch { up = false; }
-  if (!up) {
-    console.error('openzoo: starting the proxy...');
-    const { startProxy } = await import('./proxy.js');
-    await startProxy({ silent: true, autoTunnel: true });
-    for (let i = 0; i < 25 && !up; i++) {
-      await new Promise((r) => setTimeout(r, 300));
-      try { up = (await fetch(`${base}/models`, { signal: AbortSignal.timeout(2000) })).ok; } catch { /* wait */ }
-    }
-    if (!up) { console.error(`openzoo: proxy did not come up on ${base}`); process.exit(1); }
+  for (let i = 0; i < 25 && !up; i++) {
+    await new Promise((r) => setTimeout(r, 300));
+    try { up = (await fetch(`${base}/models`, { signal: AbortSignal.timeout(2000) })).ok; } catch { /* wait */ }
   }
+  if (!up) { console.error(`openzoo: proxy did not come up on ${base}`); process.exit(1); }
 
   const models = await grokModels(base);
 

package/lib/ozSpendChip.js

@@ -0,0 +1,482 @@
+/**
+ * Cafe spend chip — the ⓘ $N <details> that folds formatSpendFooter.
+ *
+ * Cafe injects this via grokbotweb-shim concatenation. Grok Bot.app cannot
+ * be patched (asar integrity), so `openzoo bot` launches Chromium with a
+ * localhost CDP port and evaluates the same IIFE in the renderer.
+ */
+import net from 'node:net';
+import crypto from 'node:crypto';
+
+export const GROKBOT_CDP_PORT = Number(process.env.OZ_GROKBOT_CDP_PORT || 9444);
+
+export function grokBotChromiumArgs(port = GROKBOT_CDP_PORT) {
+  return [
+    '--ignore-certificate-errors',
+    `--remote-debugging-port=${Number(port)}`,
+    '--remote-allow-origins=*',
+  ];
+}
+
+/** Pure. Same split the renderer IIFE uses. */
+export function splitSpendText(text) {
+  const s = String(text || '');
+  let m = s.match(/::oz-spend::(\$[0-9.]+|[^\n]*)\s*([\s\S]*)$/);
+  if (m && (m[2] || '').length > 8) {
+    let summary = (m[1] || '').trim();
+    const body = m[2].trim();
+    if (!/^\$[0-9.]+$/.test(summary) || summary === '$0.0000') {
+      const spent = body.match(/spent \$([0-9.]+)/i);
+      const call = body.match(/this call \$([0-9.]+)/i);
+      const n = Number((call && Number(call[1]) > 0.00005 ? call[1] : null) || (spent && spent[1]) || 0);
+      if (n > 0) summary = `$${n.toFixed(4)}`;
+    }
+    return { head: s.slice(0, m.index), summary: summary || 'spend', body };
+  }
+  m = s.match(/(?:this call \$|spent \$)[\s\S]*$/i);
+  if (m) {
+    const body = m[0].trim();
+    const call = body.match(/this call \$([0-9.]+)/i);
+    const spent = body.match(/spent \$([0-9.]+)/i);
+    const n = Number((call && Number(call[1]) > 0.00005 ? call[1] : null) || (spent && spent[1]) || 0);
+    return { head: s.slice(0, m.index), summary: n > 0 ? `$${n.toFixed(4)}` : 'spend', body };
+  }
+  return null;
+}
+
+export function spendOnlyText(t) {
+  const s = String(t || '').replace(/\u00a0/g, ' ').trim();
+  if (!s) return false;
+  if (!/::oz-spend::|this call \$|spent \$[0-9.]+[\s\S]*OpenRouter/i.test(s)) return false;
+  const rest = s
+    .replace(/::oz-spend::\$?[0-9.]*/gi, ' ')
+    .replace(/this call \$[0-9.]+/gi, ' ')
+    .replace(/OpenRouter(?: would)? \$[0-9.]+/gi, ' ')
+    .replace(/spent \$[0-9.]+/gi, ' ')
+    .replace(/saved \$[0-9.]+/gi, ' ')
+    .replace(/balance \$[0-9.]+/gi, ' ')
+    .replace(/\(\s*\d+%\s*\)/g, ' ')
+    .replace(/\b(?:tx|memo|proves)\b[^\n]*/gi, ' ')
+    .replace(/https?:\/\/\S+/gi, ' ')
+    .replace(/[·•.,;:/$%\d\s()[\]+\-]/g, '');
+  return rest.length < 4;
+}
+
+function ozEnsureSpendCss() {
+  if (document.getElementById('oz-spend-css')) return;
+  const s = document.createElement('style');
+  s.id = 'oz-spend-css';
+  s.textContent = [
+    '.oz-spend{margin:.55rem 0 0;font-size:12px;color:inherit;opacity:.82;max-width:36em}',
+    '.oz-spend>summary{cursor:help;list-style:none;display:inline-flex;align-items:center;gap:.35rem;',
+    'padding:3px 9px;border-radius:999px;border:1px solid rgba(255,255,255,.18)}',
+    '.oz-spend>summary::-webkit-details-marker{display:none}',
+    '.oz-spend-body{white-space:pre-wrap;margin:.55rem 0 0;font-size:11px;line-height:1.45;opacity:.88;overflow-wrap:anywhere}',
+    '[data-oz-spend-hide]{display:none!important}',
+  ].join('');
+  (document.head || document.documentElement).appendChild(s);
+}
+
+function ozSpendHost(el) {
+  let cur = el;
+  let found = el;
+  let card = null;
+  for (let i = 0; i < 16 && cur && cur !== document.body && cur.id !== 'root'; i += 1) {
+    const t = cur.textContent || '';
+    if (/::oz-spend::|this call \$|spent \$/i.test(t)) found = cur;
+    const cls = cur.className && String(cur.className);
+    if (cls && /sand-message-card|sand-message-block/.test(cls)) {
+      card = cur;
+      return cur;
+    }
+    if (cls && /(^|\s)sand-message(\s|$)/.test(cls)) card = cur;
+    cur = cur.parentElement;
+  }
+  if (card) return card;
+  if (found && found !== document.body && found.id !== 'root' && (found.textContent || '').length < 12000) {
+    return found;
+  }
+  return null;
+}
+
+function ozVisibleSpendText(root) {
+  let s = '';
+  const w = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, null);
+  while (w.nextNode()) {
+    const tn = w.currentNode;
+    if (tn.parentElement && tn.parentElement.closest && tn.parentElement.closest('.oz-spend')) continue;
+    s += tn.nodeValue || '';
+  }
+  return s;
+}
+
+function ozBlankAfter(root, keepLen) {
+  let off = 0;
+  const w = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, null);
+  const tns = [];
+  while (w.nextNode()) tns.push(w.currentNode);
+  for (let i = 0; i < tns.length; i += 1) {
+    const tn = tns[i];
+    if (tn.parentElement && tn.parentElement.closest && tn.parentElement.closest('.oz-spend')) continue;
+    const s = tn.nodeValue || '';
+    const start = off;
+    off += s.length;
+    if (off <= keepLen) continue;
+    if (start >= keepLen) tn.nodeValue = '';
+    else tn.nodeValue = s.slice(0, keepLen - start);
+  }
+}
+
+function ozHideSpendLeftovers() {
+  const nodes = document.body.querySelectorAll('div, p, span, li');
+  for (let i = 0; i < nodes.length; i += 1) {
+    const el = nodes[i];
+    if (el.closest && el.closest('.oz-spend')) continue;
+    if (el.querySelector && el.querySelector('.oz-spend')) continue;
+    const vis = ozVisibleSpendText(el);
+    if (!spendOnlyText(vis)) continue;
+    if (vis.length > 4000) continue;
+    if (el.children && el.children.length > 8) continue;
+    el.setAttribute('data-oz-spend-hide', '1');
+  }
+}
+
+function ozPreviousMessageCard(el) {
+  let cur = el;
+  for (let i = 0; i < 8 && cur && cur !== document.body; i += 1) {
+    let sib = cur.previousElementSibling;
+    while (sib) {
+      if (sib === el) {
+        sib = sib.previousElementSibling;
+        continue;
+      }
+      const cls = String(sib.className || '');
+      if (/sand-message-card|sand-message-block/.test(cls) || /(^|\s)sand-message(\s|$)/.test(cls)) {
+        return sib;
+      }
+      const inner = sib.querySelector && sib.querySelector('.sand-message-card, .sand-message-block');
+      if (inner) return inner;
+      sib = sib.previousElementSibling;
+    }
+    cur = cur.parentElement;
+  }
+  return null;
+}
+
+function ozAttachSpendChip(host, split) {
+  if (!host || !split) return;
+  if (host.querySelector && host.querySelector('.oz-spend')) return;
+  const d = document.createElement('details');
+  d.className = 'oz-spend';
+  const sum = document.createElement('summary');
+  sum.textContent = 'ⓘ ' + split.summary;
+  sum.title = split.body;
+  const body = document.createElement('div');
+  body.className = 'oz-spend-body';
+  body.textContent = split.body;
+  d.appendChild(sum);
+  d.appendChild(body);
+  try { host.appendChild(d); } catch { /* react owns some nodes */ }
+}
+
+function ozCollapseSpend() {
+  if (!document.body) return;
+  const hosts = [];
+  const seen = new Set();
+  const nodes = document.body.querySelectorAll('div, p, span, li');
+  for (let i = 0; i < nodes.length; i += 1) {
+    const el = nodes[i];
+    if (el.closest && el.closest('.oz-spend')) continue;
+    const t = ozVisibleSpendText(el);
+    if (!/::oz-spend::|this call \$|spent \$/i.test(t)) continue;
+    const host = ozSpendHost(el);
+    if (!host || seen.has(host)) continue;
+    seen.add(host);
+    hosts.push(host);
+  }
+  for (let h = 0; h < hosts.length; h += 1) {
+    const host = hosts[h];
+    const vis = ozVisibleSpendText(host);
+    const split = splitSpendText(vis);
+    if (!split || !split.body || split.body.length < 12) continue;
+    ozEnsureSpendCss();
+    if (spendOnlyText(vis)) {
+      const prev = ozPreviousMessageCard(host);
+      if (prev && prev !== host) {
+        ozAttachSpendChip(prev, split);
+        host.setAttribute('data-oz-spend-hide', '1');
+        ozBlankAfter(host, 0);
+        continue;
+      }
+    }
+    ozBlankAfter(host, split.head.length);
+    ozAttachSpendChip(host, split);
+  }
+  ozHideSpendLeftovers();
+}
+
+function ozWatchSpend() {
+  const run = () => { try { ozCollapseSpend(); } catch { /* */ } };
+  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', run);
+  else run();
+  try {
+    const mo = new MutationObserver(run);
+    const start = () => { if (document.body) mo.observe(document.body, { childList: true, subtree: true }); };
+    if (document.body) start();
+    else document.addEventListener('DOMContentLoaded', start);
+  } catch { /* */ }
+  setInterval(run, 1500);
+}
+
+export function spendChipSource() {
+  return [
+    '(function ozSpendChip(){',
+    "'use strict';",
+    'if (window.__OZ_SPEND_CHIP__) return;',
+    'window.__OZ_SPEND_CHIP__ = 1;',
+    splitSpendText.toString(),
+    spendOnlyText.toString(),
+    ozEnsureSpendCss.toString(),
+    ozSpendHost.toString(),
+    ozVisibleSpendText.toString(),
+    ozBlankAfter.toString(),
+    ozHideSpendLeftovers.toString(),
+    ozPreviousMessageCard.toString(),
+    ozAttachSpendChip.toString(),
+    ozCollapseSpend.toString(),
+    ozWatchSpend.toString(),
+    'ozWatchSpend();',
+    '})();',
+  ].join('\n');
+}
+
+function wsMaskFrame(payload, opcode = 0x1) {
+  const data = Buffer.isBuffer(payload) ? payload : Buffer.from(String(payload));
+  const mask = crypto.randomBytes(4);
+  const len = data.length;
+  let header;
+  if (len < 126) {
+    header = Buffer.alloc(6);
+    header[0] = 0x80 | opcode;
+    header[1] = 0x80 | len;
+    mask.copy(header, 2);
+  } else if (len < 65536) {
+    header = Buffer.alloc(8);
+    header[0] = 0x80 | opcode;
+    header[1] = 0x80 | 126;
+    header.writeUInt16BE(len, 2);
+    mask.copy(header, 4);
+  } else {
+    header = Buffer.alloc(14);
+    header[0] = 0x80 | opcode;
+    header[1] = 0x80 | 127;
+    header.writeBigUInt64BE(BigInt(len), 2);
+    mask.copy(header, 10);
+  }
+  const masked = Buffer.alloc(len);
+  for (let i = 0; i < len; i += 1) masked[i] = data[i] ^ mask[i % 4];
+  return Buffer.concat([header, masked]);
+}
+
+function decodeWsFrames(buf) {
+  const frames = [];
+  let rest = buf;
+  while (rest.length >= 2) {
+    const opcode = rest[0] & 0x0f;
+    const masked = (rest[1] & 0x80) !== 0;
+    let len = rest[1] & 0x7f;
+    let offset = 2;
+    if (len === 126) {
+      if (rest.length < 4) break;
+      len = rest.readUInt16BE(2);
+      offset = 4;
+    } else if (len === 127) {
+      if (rest.length < 10) break;
+      len = Number(rest.readBigUInt64BE(2));
+      offset = 10;
+    }
+    const maskLen = masked ? 4 : 0;
+    if (rest.length < offset + maskLen + len) break;
+    let payload = rest.subarray(offset + maskLen, offset + maskLen + len);
+    if (masked) {
+      const mask = rest.subarray(offset, offset + 4);
+      const decoded = Buffer.alloc(len);
+      for (let i = 0; i < len; i += 1) decoded[i] = payload[i] ^ mask[i % 4];
+      payload = decoded;
+    }
+    frames.push({ opcode, payload });
+    rest = rest.subarray(offset + maskLen + len);
+  }
+  return { frames, rest };
+}
+
+export function cdpSession(wsUrl, { timeoutMs = 8000 } = {}) {
+  return new Promise((resolve, reject) => {
+    let u;
+    try { u = new URL(wsUrl); } catch (e) { reject(e); return; }
+    const key = crypto.randomBytes(16).toString('base64');
+    const sock = net.connect({ host: u.hostname, port: Number(u.port || 80) });
+    let buf = Buffer.alloc(0);
+    let upgraded = false;
+    let settled = false;
+    let nextId = 0;
+    const pending = new Map();
+    const timer = setTimeout(() => {
+      if (!upgraded) fail(new Error('cdp timeout'));
+    }, timeoutMs);
+
+    function fail(err) {
+      if (settled) {
+        sock.destroy();
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      sock.destroy();
+      reject(err);
+    }
+
+    sock.on('error', fail);
+    sock.on('connect', () => {
+      sock.write(
+        `GET ${u.pathname}${u.search} HTTP/1.1\r\n`
+        + `Host: ${u.host}\r\n`
+        + 'Upgrade: websocket\r\n'
+        + 'Connection: Upgrade\r\n'
+        + 'Sec-WebSocket-Version: 13\r\n'
+        + `Sec-WebSocket-Key: ${key}\r\n`
+        + `Origin: http://${u.host}\r\n`
+        + '\r\n',
+      );
+    });
+    sock.on('data', (chunk) => {
+      buf = Buffer.concat([buf, chunk]);
+      if (!upgraded) {
+        const idx = buf.indexOf('\r\n\r\n');
+        if (idx < 0) return;
+        const head = buf.subarray(0, idx).toString('utf8');
+        buf = buf.subarray(idx + 4);
+        if (!/^HTTP\/1\.1 101/i.test(head)) {
+          fail(new Error(`cdp upgrade ${head.split('\r\n')[0] || 'failed'}`));
+          return;
+        }
+        upgraded = true;
+        settled = true;
+        clearTimeout(timer);
+        resolve({
+          send(method, params) {
+            const id = ++nextId;
+            return new Promise((res, rej) => {
+              const t = setTimeout(() => {
+                pending.delete(id);
+                rej(new Error(`cdp ${method} timeout`));
+              }, Math.max(1000, timeoutMs));
+              pending.set(id, {
+                res: (v) => { clearTimeout(t); res(v); },
+                rej: (e) => { clearTimeout(t); rej(e); },
+              });
+              try { sock.write(wsMaskFrame(JSON.stringify({ id, method, params }))); } catch (e) {
+                clearTimeout(t);
+                pending.delete(id);
+                rej(e);
+              }
+            });
+          },
+          close() {
+            clearTimeout(timer);
+            try { sock.destroy(); } catch { /* */ }
+          },
+        });
+      }
+      const decoded = decodeWsFrames(buf);
+      buf = decoded.rest;
+      for (const f of decoded.frames) {
+        if (f.opcode === 0x9) {
+          try { sock.write(wsMaskFrame(f.payload, 0xa)); } catch { /* */ }
+          continue;
+        }
+        if (f.opcode === 0x8) {
+          sock.destroy();
+          continue;
+        }
+        if (f.opcode !== 0x1 && f.opcode !== 0x0) continue;
+        let msg;
+        try { msg = JSON.parse(f.payload.toString('utf8')); } catch { continue; }
+        if (msg && msg.id != null && pending.has(msg.id)) {
+          const { res, rej } = pending.get(msg.id);
+          pending.delete(msg.id);
+          if (msg.error) rej(new Error(msg.error.message || JSON.stringify(msg.error)));
+          else res(msg.result);
+        }
+      }
+    });
+  });
+}
+
+export async function listCdpPages(port, fetchImpl = fetch) {
+  for (const path of ['/json/list', '/json']) {
+    try {
+      const r = await fetchImpl(`http://127.0.0.1:${Number(port)}${path}`, {
+        signal: AbortSignal.timeout(1500),
+      });
+      if (!r.ok) continue;
+      const j = await r.json();
+      const arr = Array.isArray(j) ? j : [];
+      return arr.filter((t) => t && t.webSocketDebuggerUrl && t.type !== 'service_worker' && t.type !== 'worker');
+    } catch { /* try next */ }
+  }
+  return [];
+}
+
+async function injectTarget(target, source, connect) {
+  const session = await connect(target.webSocketDebuggerUrl);
+  try {
+    await session.send('Page.enable').catch(() => {});
+    await session.send('Runtime.enable').catch(() => {});
+    await session.send('Page.addScriptToEvaluateOnNewDocument', { source }).catch(() => {});
+    await session.send('Runtime.evaluate', { expression: source, awaitPromise: false });
+  } finally {
+    session.close();
+  }
+}
+
+export async function injectSpendChip({
+  port = GROKBOT_CDP_PORT,
+  source = spendChipSource(),
+  log = () => {},
+  fetchImpl = fetch,
+  connect = cdpSession,
+  tries = 40,
+  delayMs = 400,
+} = {}) {
+  let targets = [];
+  for (let i = 0; i < Math.max(1, tries); i += 1) {
+    targets = await listCdpPages(port, fetchImpl);
+    if (targets.length) break;
+    if (i + 1 < tries && delayMs) await new Promise((r) => setTimeout(r, delayMs));
+  }
+  if (!targets.length) {
+    log(`openzoo: spend chip CDP :${port} has no pages yet`);
+    return { ok: false, injected: 0 };
+  }
+  let injected = 0;
+  for (const t of targets) {
+    try {
+      await injectTarget(t, source, connect);
+      injected += 1;
+    } catch (e) {
+      log(`openzoo: spend chip inject ${e.message}`);
+    }
+  }
+  if (injected) log(`openzoo: spend chip folded into ${injected} renderer(s)`);
+  return { ok: injected > 0, injected };
+}
+
+/** Fire-and-forget wrapper used by `openzoo bot`. */
+export function injectSpendChipInBackground(opts = {}) {
+  const log = opts.log || ((m) => console.error(m));
+  injectSpendChip({ ...opts, log }).catch((e) => {
+    log(`openzoo: spend chip inject failed ${e.message}`);
+  });
+}
+