openzoo 0.51.6 → 0.51.8

package/README.md

@@ -35,6 +35,8 @@ Configuration defaults to `~/.openzoo/chatgpt/config.toml`, with a separate desk
 
 `--model <id>` overrides `deepseek-v4-flash`; `--bearer` stores the non-secret placeholder token instead of requiring an environment variable. `--no-launch` writes config only (no download, install, proxy, or launch); `--no-proxy` skips proxy startup; `--print` previews without side effects. Pass app flags after `--`, for example `openzoo chatgpt -- --ozone-platform=wayland`. `OPENZOO_CHATGPT_BIN` selects an explicit executable. Failed downloads, installation, or launch commands return an error.
 
+The **savings pill** is enabled by default: an orange, draggable overlay shows spent and saved, with estimated direct cost in its expanded view. These are **all-time shared proxy totals**, not per-task ChatGPT billing; ordinary ChatGPT chats are excluded. Negative savings appear as extra cost, and unavailable totals are marked disconnected. The bridge reads `/v1/info` outside the renderer and updates only its own overlay, without modifying the signed app or its security policy. It uses a loopback-only, dynamically assigned Chromium debugging port on the OpenZoo desktop profile, exits after the app is gone for 60 seconds, and logs to `<CODEX_HOME>/desktop/openzoo-savings.log`. Use `--no-pill` to launch without the overlay/debugging flag. Run the command again to attach the pill after a separate app restart.
+
 Installer references: [ChatGPT downloads](https://chatgpt.com/download/), [Windows MSIX deployment](https://learn.chatgpt.com/docs/enterprise/windows-deployment), [Linux packages](https://learn.chatgpt.com/docs/linux/linux-app).
 
 

package/bin/openzoo.js

@@ -155,6 +155,8 @@ usage:
                          Choose "sign in with API key" (sk-openzoo) if prompted.
                          --deb <file> (Linux) --config /path/to/config.toml
                          --model <id> (deepseek-v4-flash) --wire responses|chat --bearer
+                         Savings pill: live shared proxy spend / direct estimate / saved
+                         --no-pill disables the overlay
                          --no-launch (config only) --no-proxy --tunnel --print
                          -- <app flags>
   npx openzoo openclaw   write the zoo into ~/.openclaw/openclaw.json as a model

package/lib/chatgpt-spend.js

@@ -0,0 +1,206 @@
+/** Read-only savings overlay for the OpenZoo ChatGPT profile. */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { cdpSession, listCdpPages } from './ozSpendChip.js';
+
+export function chatGptSpendState(info) {
+  if (info?.youAreTalkingTo !== 'openzoo proxy') throw new Error('not an OpenZoo proxy');
+  const amount = value => typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
+  const spent = amount(info.spendUsd), would = amount(info.directUsd);
+  const comparable = spent !== null && would !== null && (would > 0 || spent === 0);
+  // Do not use savedUsd: older proxies clamp negative savings to zero.
+  const saved = comparable ? would - spent : null;
+  return { spent, would: comparable ? would : null, saved,
+    pct: comparable && would > 0 ? 100 * saved / would : null,
+    scope: 'All-time · shared OpenZoo proxy', updatedAt: Date.now(), online: true };
+}
+
+/** Self-contained renderer. Only owns its shadow-root overlay, never chat content. */
+export function renderChatGptSpend(state) {
+  let host = document.getElementById('openzoo-chatgpt-spend');
+  if (!document.body) return false;
+  if (!host) {
+    host = document.createElement('div');
+    host.id = 'openzoo-chatgpt-spend';
+    host.style.cssText = 'position:fixed;right:20px;bottom:90px;z-index:2147483646;max-width:calc(100vw - 24px);-webkit-app-region:no-drag';
+    const root = host.attachShadow({ mode: 'open' });
+    root.innerHTML = `<style>
+      :host{font:12px/1.5 system-ui,sans-serif;color:#fafafa;color-scheme:dark}
+      details{max-width:min(470px,calc(100vw - 24px))}
+      summary{list-style:none;cursor:grab;touch-action:none;border-radius:999px;background:#e85d1c;color:white;padding:8px 14px;box-shadow:0 4px 18px #0006;font-weight:650;overflow-wrap:anywhere}
+      summary::-webkit-details-marker{display:none}summary:focus-visible{outline:2px solid white;outline-offset:3px}
+      section{margin-top:8px;padding:12px 14px;border:1px solid #ffffff24;border-radius:14px;background:#18181bef;box-shadow:0 4px 18px #0005}
+      dl{display:grid;grid-template-columns:1fr auto;gap:5px 24px;margin:10px 0}dd{margin:0;font-variant-numeric:tabular-nums}
+      small{display:block;color:#bfbfc7}p{margin:8px 0 0;color:#bfbfc7}button{margin-top:10px;border:1px solid #ffffff30;border-radius:8px;background:transparent;color:inherit;padding:4px 10px;cursor:pointer}
+    </style><details><summary role="button" aria-expanded="false" aria-label="OpenZoo costs and savings"></summary><section>
+      <small data-scope></small><dl><dt>Spent</dt><dd data-spent></dd><dt>Would’ve cost · estimate</dt><dd data-would></dd><dt data-saving-label>Saved</dt><dd data-saved></dd></dl>
+      <small data-status role="status"></small><p>Direct cost is the proxy’s counterfactual estimate. Totals include other apps using this proxy. Ordinary ChatGPT chats are not included.</p>
+      <button type="button">Reset position</button></section></details>`;
+    const summary = root.querySelector('summary');
+    let drag = null, moved = false;
+    const place = (left, top) => {
+      const r = host.getBoundingClientRect();
+      host.style.left = Math.max(8, Math.min(left, innerWidth - r.width - 8)) + 'px';
+      host.style.top = Math.max(8, Math.min(top, innerHeight - r.height - 8)) + 'px';
+      host.style.right = host.style.bottom = 'auto';
+    };
+    document.body.appendChild(host);
+    try { const p = JSON.parse(localStorage.getItem('openzoo-chatgpt-spend-position')); if (p && Number.isFinite(p.x) && Number.isFinite(p.y)) place(p.x, p.y); } catch { /* storage unavailable */ }
+    summary.addEventListener('pointerdown', e => {
+      if (e.button !== 0) return;
+      const r = host.getBoundingClientRect();
+      drag = { x: e.clientX, y: e.clientY, left: r.left, top: r.top }; moved = false;
+      summary.setPointerCapture(e.pointerId);
+    });
+    summary.addEventListener('pointermove', e => {
+      if (!drag) return;
+      const dx = e.clientX - drag.x, dy = e.clientY - drag.y;
+      if (Math.abs(dx) + Math.abs(dy) > 4) moved = true;
+      if (moved) place(drag.left + dx, drag.top + dy);
+    });
+    summary.addEventListener('pointerup', () => {
+      if (drag && moved) { const r = host.getBoundingClientRect(); try { localStorage.setItem('openzoo-chatgpt-spend-position', JSON.stringify({ x: r.left, y: r.top })); } catch {} }
+      drag = null;
+    });
+    summary.addEventListener('pointercancel', () => { drag = null; });
+    summary.addEventListener('click', e => { if (moved) { e.preventDefault(); moved = false; } });
+    root.querySelector('button').addEventListener('click', () => {
+      try { localStorage.removeItem('openzoo-chatgpt-spend-position'); } catch {}
+      host.style.left = host.style.top = 'auto'; host.style.right = '20px'; host.style.bottom = '90px';
+    });
+    root.querySelector('details').addEventListener('toggle', () => { summary.setAttribute('aria-expanded', String(root.querySelector('details').open)); if (host.style.left !== 'auto' && host.style.left) { const r = host.getBoundingClientRect(); place(r.left, r.top); } });
+    addEventListener('resize', () => { if (host.isConnected && host.style.left !== 'auto' && host.style.left) { const r = host.getBoundingClientRect(); place(r.left, r.top); } });
+    // A dead bridge must not leave apparently live numbers indefinitely.
+    const timer = setInterval(() => {
+      if (!host.isConnected) { clearInterval(timer); return; }
+      if (Date.now() - (host.__ozUpdate || 0) > 12000) {
+        root.querySelector('[data-status]').textContent = 'Disconnected · last known totals';
+        root.querySelector('summary').textContent = 'OpenZoo · disconnected';
+      }
+    }, 3000);
+  }
+  const root = host.shadowRoot;
+  if (!root) return false;
+  const usd = n => n === null || !Number.isFinite(n) ? '—' : '$' + Math.abs(n).toFixed(Math.abs(n) < 0.01 ? 4 : 2);
+  const more = state.saved !== null && state.saved < 0;
+  const savings = state.saved === null ? 'Savings —' : `${more ? 'Extra cost' : 'Saved'} ${usd(state.saved)}`;
+  root.querySelector('summary').textContent = state.online ? `OpenZoo · ${usd(state.spent)} spent · ${savings}` : 'OpenZoo · disconnected';
+  root.querySelector('[data-spent]').textContent = usd(state.spent);
+  root.querySelector('[data-would]').textContent = usd(state.would);
+  root.querySelector('[data-saving-label]').textContent = more ? 'Extra cost' : 'Saved';
+  root.querySelector('[data-saved]').textContent = usd(state.saved) + (state.pct === null ? '' : ` (${Math.abs(state.pct).toFixed(1)}%)`);
+  root.querySelector('[data-scope]').textContent = state.scope;
+  root.querySelector('[data-status]').textContent = state.online ? 'Updated ' + new Date(state.updatedAt).toLocaleTimeString() : 'Proxy unavailable · last known totals';
+  host.__ozUpdate = Date.now();
+  return true;
+}
+
+export function chatGptSpendSource(state) {
+  return `(${renderChatGptSpend.toString()})(${JSON.stringify(state).replace(/</g, '\\u003c')})`;
+}
+
+export function readChatGptDebugPort(profile) {
+  try {
+    const n = Number(fs.readFileSync(path.join(profile, 'DevToolsActivePort'), 'utf8').split(/\r?\n/)[0]);
+    return Number.isInteger(n) && n > 0 && n < 65536 ? n : null;
+  } catch { return null; }
+}
+
+export function isChatGptRenderer(target, port) {
+  try {
+    const ws = new URL(target.webSocketDebuggerUrl);
+    if (ws.protocol !== 'ws:' || ws.hostname !== '127.0.0.1' && ws.hostname !== 'localhost' || Number(ws.port) !== port) return false;
+    const url = new URL(target.url);
+    return target.type === 'page' && (url.protocol === 'file:' && /\/index\.html$/.test(url.pathname) || url.protocol === 'app:' && /codex|chatgpt/.test(url.hostname));
+  } catch { return false; }
+}
+
+/** Host-side polling avoids changing the signed app or relaxing renderer CSP. */
+export async function watchChatGptSpend({ profile, proxyPort, fetchImpl = fetch, connect = cdpSession,
+  sleep = ms => new Promise(r => setTimeout(r, ms)), stopped = () => false, log = console.error } = {}) {
+  const sessions = new Map();
+  let misses = 0;
+  let state = { spent: null, would: null, saved: null, pct: null, scope: 'All-time · shared OpenZoo proxy', online: false, updatedAt: 0 };
+  try {
+    while (!stopped() && misses < 20) {
+      const port = readChatGptDebugPort(profile);
+      const pages = port ? (await listCdpPages(port, fetchImpl)).filter(t => isChatGptRenderer(t, port)) : [];
+      misses = pages.length ? 0 : misses + 1;
+      const live = new Set(pages.map(t => t.webSocketDebuggerUrl));
+      for (const [id, session] of sessions) if (!live.has(id)) { session.close(); sessions.delete(id); }
+      try {
+        const r = await fetchImpl(`http://127.0.0.1:${proxyPort}/v1/info`, { signal: AbortSignal.timeout(2000) });
+        if (!r.ok) throw new Error(`proxy HTTP ${r.status}`);
+        state = chatGptSpendState(await r.json());
+      } catch { state = { ...state, online: false }; }
+      for (const page of pages) {
+        const id = page.webSocketDebuggerUrl;
+        try {
+          if (!sessions.has(id)) sessions.set(id, await connect(id, { timeoutMs: 2500, sendOrigin: false }));
+          const result = await sessions.get(id).send('Runtime.evaluate', { expression: chatGptSpendSource(state), returnByValue: true });
+          if (result.exceptionDetails) throw new Error('savings pill renderer evaluation failed');
+        } catch (e) { sessions.get(id)?.close(); sessions.delete(id); log(`openzoo: savings pill: ${e.message}`); }
+      }
+      await sleep(3000);
+    }
+    if (misses >= 20) log('openzoo: savings pill stopped: no ChatGPT renderer found for 60s');
+  } finally { for (const session of sessions.values()) session.close(); }
+}
+
+/** A current launcher supplies a native pill even when the chat app disables debugging. */
+export function nativeSavingsLauncher({ platform = process.platform, home = os.homedir(), env = process.env, exists = fs.existsSync } = {}) {
+  const roots = platform === 'darwin'
+    ? ['/Applications/OpenZoo Launcher.app/Contents', path.join(home, 'Applications/OpenZoo Launcher.app/Contents')]
+    : platform === 'win32' ? [path.join(env.LOCALAPPDATA || home, 'Programs/openzoo-launcher'), path.join(env.LOCALAPPDATA || home, 'Programs/OpenZoo Launcher')] : [];
+  for (const root of roots) {
+    const resources = path.join(root, platform === 'darwin' ? 'Resources' : 'resources');
+    const executable = platform === 'darwin' ? path.join(root, 'MacOS/OpenZoo Launcher') : path.join(root, 'OpenZoo Launcher.exe');
+    if (exists(path.join(resources, 'openzoo-overlay.json')) && exists(executable)) return executable;
+  }
+  return null;
+}
+
+export async function startChatGptSpend({ profile, proxyPort, spawnImpl = spawn } = {}) {
+  const native = nativeSavingsLauncher();
+  if (native && proxyPort === 8402) {
+    const child = spawnImpl(native, ['--savings-only'], { detached: true, stdio: 'ignore' });
+    await new Promise((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject); });
+    child.unref();
+    return;
+  }
+  fs.mkdirSync(profile, { recursive: true });
+  const fd = fs.openSync(path.join(profile, 'openzoo-savings.log'), 'a', 0o600);
+  try {
+    const child = spawnImpl(process.execPath, [fileURLToPath(import.meta.url), '--watch', profile, String(proxyPort)], { detached: true, stdio: ['ignore', fd, fd] });
+    await new Promise((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject); });
+    child.unref();
+  } finally { fs.closeSync(fd); }
+}
+
+/** One watcher per profile, including concurrent launcher invocations. */
+export function claimSpendWatcher(profile) {
+  const lock = path.join(profile, 'openzoo-savings.lock');
+  try {
+    const pid = Number(fs.readFileSync(lock, 'utf8'));
+    if (Number.isInteger(pid) && pid > 0) {
+      try { process.kill(pid, 0); return null; } catch (e) { if (e.code !== 'ESRCH') return null; }
+    } else if (Date.now() - fs.statSync(lock).mtimeMs < 60000) return null;
+    fs.unlinkSync(lock);
+  } catch (e) { if (e.code !== 'ENOENT') throw e; }
+  let fd;
+  try { fd = fs.openSync(lock, 'wx', 0o600); } catch (e) { if (e.code === 'EEXIST') return null; throw e; }
+  fs.writeFileSync(fd, String(process.pid)); fs.closeSync(fd);
+  return () => { try { if (fs.readFileSync(lock, 'utf8') === String(process.pid)) fs.unlinkSync(lock); } catch {} };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url) && process.argv[2] === '--watch') {
+  const release = claimSpendWatcher(process.argv[3]);
+  if (release) {
+    process.once('exit', release);
+    watchChatGptSpend({ profile: process.argv[3], proxyPort: Number(process.argv[4]) })
+      .catch(e => { console.error(e.message); process.exitCode = 1; }).finally(release);
+  }
+}

package/lib/chatgpt.js

@@ -11,6 +11,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { config } from './config.js';
+import { startChatGptSpend } from './chatgpt-spend.js';
 import { installChatGpt, windowsChatGptApp, runCommand } from './chatgpt-install.js';
 
 export const PROVIDER_ID = 'openzoo';
@@ -245,9 +246,9 @@ async function ensureProxy({ tunnel }) {
 export async function setupChatGpt(argv = [], dependencies = {}) {
   const { platform = process.platform, home = os.homedir(), env: sourceEnv = process.env,
     resolve = resolveChatGptApp, install = installChatGpt, proxy = ensureProxy,
-    launch = launchChatGpt, findWindows = windowsChatGptApp } = dependencies;
+    launch = launchChatGpt, findWindows = windowsChatGptApp, overlay = startChatGptSpend } = dependencies;
   const args = [...argv];
-  const opt = { model: null, deb: null, wireApi: 'responses', bearer: false, launch: true, proxy: true, tunnel: false, print: false, configPath: null, rest: [] };
+  const opt = { model: null, deb: null, wireApi: 'responses', bearer: false, launch: true, proxy: true, pill: true, tunnel: false, print: false, configPath: null, rest: [] };
   while (args.length) {
     const a = args.shift();
     if (a === '--') { opt.rest.push(...args); break; }
@@ -261,6 +262,7 @@ export async function setupChatGpt(argv = [], dependencies = {}) {
     else if (a === '--config') opt.configPath = value();
     else if (a === '--bearer') opt.bearer = true;
     else if (a === '--no-launch') opt.launch = false;
+    else if (a === '--no-pill') opt.pill = false;
     else if (a === '--no-proxy') opt.proxy = false;
     else if (a === '--tunnel') opt.tunnel = true;
     else if (a === '--print') opt.print = true;
@@ -319,7 +321,14 @@ export async function setupChatGpt(argv = [], dependencies = {}) {
   console.log(`launching ${app}`);
   console.log(`  Codex / agent mode → the zoo, paid per turn by x402. Choose "sign in with API key" (any key).`);
   console.log('  the plain ChatGPT chat tab still talks to chatgpt.com — that half is not API-shaped.');
-  await launch(app, opt.rest, { env, platform });
+  const appArgs = opt.pill ? ['--remote-debugging-address=127.0.0.1', '--remote-debugging-port=0', ...opt.rest] : opt.rest;
+  await launch(app, appArgs, { env, platform });
+  if (opt.pill) {
+    try {
+      await overlay({ profile: env.CODEX_ELECTRON_USER_DATA_PATH, proxyPort: config.port });
+      console.log('savings pill enabled · spent / estimated direct cost / saved · shared proxy totals');
+    } catch (e) { console.error(`openzoo: savings pill unavailable: ${e.message}`); }
+  }
   return { file, model, app, launched: true };
 }
 

package/lib/evm.js

@@ -9,7 +9,7 @@ const ERC20_ABI = [
 
 const evmClients = new Map();
 function clientFor(rpcUrl) {
-  if (!evmClients.has(rpcUrl)) evmClients.set(rpcUrl, createPublicClient({ transport: http(rpcUrl) }));
+  if (!evmClients.has(rpcUrl)) evmClients.set(rpcUrl, createPublicClient({ transport: http(rpcUrl, { timeout: 4000, retryCount: 0 }) }));
   return evmClients.get(rpcUrl);
 }
 

package/lib/funding-status.js

@@ -0,0 +1,17 @@
+/** Coalesce live reads, retain unknowns, and never cache an empty balance for a minute. */
+export function liveBalance(read, { ttlMs = 3000, now = Date.now } = {}) {
+  let value = null, at = 0, inflight;
+  return {
+    get value() { return value; },
+    get checkedAt() { return at || null; },
+    async refresh(force = false) {
+      if (inflight) return inflight;
+      if (!force && at && now() - at < ttlMs) return value;
+      inflight = Promise.resolve().then(read).then(next => {
+        if (typeof next !== 'number' || !Number.isFinite(next) || next < 0) throw new Error('Balance unavailable');
+        value = next; at = now(); return value;
+      }).catch(() => value).finally(() => { inflight = null; });
+      return inflight;
+    },
+  };
+}

package/lib/info.js

@@ -259,14 +259,12 @@ export { CREDIT_TIMEOUT_MS };
 
 export async function creditBalance() {
   const { withNamespace } = await import('./namespace.js');
-  try {
-    const r = await fetch(`${config.apiBase}/v1/credits`, {
-      headers: withNamespace({}),
-      signal: AbortSignal.timeout(CREDIT_TIMEOUT_MS),
-    });
-    const j = await r.json();
-    return Number(j.balanceUsd) || 0;
-  } catch {
-    return 0;
-  }
+  const r = await fetch(`${config.apiBase}/v1/credits`, {
+    headers: withNamespace({}), cache: 'no-store',
+    signal: AbortSignal.timeout(CREDIT_TIMEOUT_MS),
+  });
+  if (!r.ok) throw new Error('Credit balance is temporarily unavailable');
+  const j = await r.json();
+  if (typeof j.balanceUsd !== 'number' || !Number.isFinite(j.balanceUsd) || j.balanceUsd < 0) throw new Error('Credit balance is temporarily unavailable');
+  return j.balanceUsd;
 }

package/lib/ozSpendChip.js

@@ -758,7 +758,7 @@ function decodeWsFrames(buf) {
   return { frames, rest };
 }
 
-export function cdpSession(wsUrl, { timeoutMs = 8000 } = {}) {
+export function cdpSession(wsUrl, { timeoutMs = 8000, sendOrigin = true } = {}) {
   return new Promise((resolve, reject) => {
     let u;
     try { u = new URL(wsUrl); } catch (e) { reject(e); return; }
@@ -793,7 +793,7 @@ export function cdpSession(wsUrl, { timeoutMs = 8000 } = {}) {
         + 'Connection: Upgrade\r\n'
         + 'Sec-WebSocket-Version: 13\r\n'
         + `Sec-WebSocket-Key: ${key}\r\n`
-        + `Origin: http://${u.host}\r\n`
+        + (sendOrigin ? `Origin: http://${u.host}\r\n` : '')
         + '\r\n',
       );
     });

package/lib/pay.js

@@ -27,6 +27,10 @@ export class QuoteTooHighError extends Error {
   }
 }
 
+export class BalanceUnavailableError extends Error {
+  constructor() { super('We couldn’t check your balance right now. Please try again. You don’t need to add funds again.'); }
+}
+
 export class UnderfundedError extends Error {
   constructor(accept, usdcUi, address, { line } = {}) {
     const usd = Number(accept?.extra?.billedUsd);
@@ -149,14 +153,10 @@ export function chainName(network) {
 
 const memoKey = (a) => `${a?.network || ''}|${a?.asset || ''}`;
 
-/** lastGood first, known-underfunded last (never dropped — only deprioritised). */
-export function orderCandidatesByMemory(cands, now = Date.now()) {
-  const skip = (c) => (underfundedUntil.get(memoKey(c)) ?? 0) > now;
+/** Prefer a confirmed successful payer; recheck other balances on every request. */
+export function orderCandidatesByMemory(cands) {
   const good = (c) => lastGoodAsset && memoKey(c) === lastGoodAsset;
-  // Stable partition: proven payer, then untried, then recently-underfunded. The
-  // last group is KEPT so a wallet funded seconds ago is still reachable in the
-  // same call if nothing else works.
-  return [...cands].sort((a, b) => (good(b) - good(a)) || (skip(a) - skip(b)));
+  return [...cands].sort((a, b) => good(b) - good(a));
 }
 
 /** Test seam: forget everything the rail memory learned. */
@@ -259,7 +259,7 @@ export class PayClient {
     const rail = railOf(accept);
     if (rail === 'solana') {
       const need = BigInt(accept.maxAmountRequired);
-      const bal = await cachedTokenBalance(this.connection, this.keypair.publicKey, accept.asset, { force: true });
+      const bal = await cachedTokenBalance(this.connection, this.keypair.publicKey, accept.asset, { force: true }).catch(() => { throw new BalanceUnavailableError(); });
       // SHORT IS SHORT. The 402 quotes the raw native mint, so there is nothing
       // to convert and no pool to walk: the wallet either holds the asset or it
       // does not. This branch used to run resolvePool + poolState + a wrap
@@ -302,7 +302,7 @@ export class PayClient {
         });
       }
       if (owner) {
-        const bal = await evmTokenBalance({ rpcUrl, token: accept.asset, owner }).catch(() => null);
+        const bal = await evmTokenBalance({ rpcUrl, token: accept.asset, owner }).catch(() => { throw new BalanceUnavailableError(); });
         if (bal !== null && bal < BigInt(accept.maxAmountRequired)) {
           // Robinhood used to quote an ERC-4626 vault twin here and the shim
           // ran approve+deposit to mint it. The gateway now quotes canonical
@@ -377,6 +377,7 @@ export class PayClient {
     let accept = null;
     let payment = null;
     const fundErrs = [];
+    let balanceError = null;
     let tooHigh = null;
     for (const cand of candidates) {
       const billedUsd = Number(cand?.extra?.billedUsd ?? NaN);
@@ -388,13 +389,13 @@ export class PayClient {
         payment = await this.buildPaymentFor(cand, onStage, quote);
         if (fundErrs.length) railNote(`paying on ${railLabel(cand)}`);
         accept = cand;
-        lastGoodAsset = memoKey(cand);
         underfundedUntil.delete(memoKey(cand));
         if (railOf(cand) === 'solana') {
           try { debitCachedBalance(this.keypair.publicKey, cand.asset, BigInt(cand.maxAmountRequired)); } catch { /* advisory */ }
         }
         break;
       } catch (e) {
+        if (e instanceof BalanceUnavailableError) { balanceError = e; continue; }
         if (!(e instanceof UnderfundedError)) throw e;
         // Remember it so the next call does not re-pay the discovery cost.
         underfundedUntil.set(memoKey(cand), Date.now() + RAIL_MEMO_MS);
@@ -411,6 +412,7 @@ export class PayClient {
       }
     }
     if (!payment) {
+      if (balanceError) throw balanceError;
       if (!fundErrs.length && tooHigh) throw tooHigh;
       if (fundErrs.length === 1) throw fundErrs[0].err;
       throw new UnderfundedError(candidates[0], null, this.address, {
@@ -452,11 +454,11 @@ export class PayClient {
           });
           if (again.status !== 402) {
             accept = cand; payment = retry; response = again;
-            lastGoodAsset = memoKey(cand);
+            if (again.ok) lastGoodAsset = memoKey(cand);
             break;
           }
         } catch (e) {
-          if (!(e instanceof UnderfundedError)) throw e;
+          if (!(e instanceof UnderfundedError) && !(e instanceof BalanceUnavailableError)) throw e;
         }
       }
     }
@@ -513,6 +515,9 @@ export class PayClient {
         this._rebuilt = false;
       }
     }
+    if (response.ok) lastGoodAsset = memoKey(accept);
+    else if (lastGoodAsset === memoKey(accept)) lastGoodAsset = null;
+
     // NEVER PRESENT OUR OWN SIGNATURE AS THE TRANSACTION.
     //
     // This fell back to `{ signature: payment.ownerSignature }`, and on Solana

package/lib/payment-error.js

@@ -0,0 +1,15 @@
+import { randomUUID } from 'node:crypto';
+/** Report a failed turn through the client's response stream, not transport-error prose. */
+export function paymentError(res, req, init, status, message) {
+  let body = {};
+  try { body = JSON.parse(String(init?.body || '{}')); } catch {}
+  if (/\/responses(?:\?|$)/.test(req.url || '') && body.stream === true) {
+    const response = { id: `resp_${randomUUID()}`, object: 'response', created_at: Math.floor(Date.now()/1000), status: 'failed',
+      error: { code: 'server_error', message }, output: [], usage: null, model: body.model || '', incomplete_details: null };
+    res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' });
+    res.end(`event: response.failed\ndata: ${JSON.stringify({ type: 'response.failed', sequence_number: 0, response })}\n\n`);
+    return;
+  }
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(JSON.stringify({ error: { message } }));
+}

package/lib/proxy.js

@@ -1,3 +1,5 @@
+import { liveBalance } from './funding-status.js';
+import { paymentError } from './payment-error.js';
 import { readFileSync, appendFileSync, mkdirSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -8,8 +10,8 @@ import {
   config, FUNDING_ASSETS, EVM_FUNDING_ASSETS, evmRpcFor, fundingLine, liveRails, railFundingHint, railFundingAddresses, unfundableRails, RAIL_FUNDING,
 } from './config.js';
 import { execSync } from 'node:child_process';
-import { PayClient, QuoteTooHighError, UnderfundedError } from './pay.js';
-import { withOnrampLink, settleFailCopy } from './stripeOnramp.js';
+import { PayClient, QuoteTooHighError, UnderfundedError, BalanceUnavailableError, resetBalanceCache, resetRailMemory } from './pay.js';
+import { withOnrampLink, settleFailCopy, whopFundBlurb } from './stripeOnramp.js';
 import { tokenBalance } from './x402.js';
 import { evmTokenBalance } from './evm.js';
 import { autoContext } from './autobind.js';
@@ -451,7 +453,7 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
   let refreshBalances = async () => {};
   let refreshPending = false;
   const scheduleRefresh = (ms) => {
-    if (silent || refreshPending) return;
+    if (refreshPending) return;
     refreshPending = true;
     const t = setTimeout(async () => { refreshPending = false; await refreshBalances(); }, ms);
     t.unref?.();
@@ -471,11 +473,10 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
   // billed for ONLY those calls whose real cost we learned — the honest
   // numerator for markupX.
   let billedWithActual = 0;
-  // CREDIT, CACHED. Refreshed at most every 20s and served stale in between —
+  // CREDIT, CACHED. Refreshed every few seconds and served stale in between —
   // a status line must never add latency to the thing it is describing.
   let creditUsd = null;
   let creditAt = 0;
-  let creditInflight = null;
   let lastPrices = {};
   let pricesAt = 0;
   // WALLET BALANCE, CACHED LIKE CREDIT.
@@ -490,40 +491,38 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
   // behind it — the same contract refreshCredit() keeps.
   let walletUsd = null;
   let walletAt = 0;
-  let walletInflight = null;
+  const walletStatus = liveBalance(async () => {
+    const snap = await snapshotBalances(client);
+    if (!snap.length) throw new Error('Balances unavailable');
+    const previous = new Map((lastSnap || []).map(b => [`${b.chain}:${b.symbol}`, b]));
+    for (const b of snap) {
+      const old = previous.get(`${b.chain}:${b.symbol}`);
+      if (b.ui > (old?.ui ?? 0)) { resetBalanceCache(); resetRailMemory(); }
+      previous.set(`${b.chain}:${b.symbol}`, b);
+    }
+    lastSnap = [...previous.values()];
+    return priceHoldings(lastSnap, lastPrices).chainUsd;
+  });
+  const creditStatus = liveBalance(creditBalance);
   const refreshWallet = async (force = false) => {
-    if (!force && Date.now() - walletAt < 60000 && walletUsd != null) return walletUsd;
-    if (walletInflight) return walletInflight;
-    walletInflight = (async () => {
-      try {
-        const { affordableUsd } = await import('./info.js');
-        const v = await affordableUsd();
-        if (Number.isFinite(v)) { walletUsd = v; walletAt = Date.now(); }
-      } catch { /* keep last known */ }
-      walletInflight = null;
-      return walletUsd;
-    })();
-    return walletInflight;
+    walletUsd = await walletStatus.refresh(force);
+    walletAt = walletStatus.checkedAt;
+    return walletUsd;
   };
   const refreshCredit = async (force = false) => {
-    if (!force && Date.now() - creditAt < 20000 && creditUsd != null) return creditUsd;
-    if (creditInflight) return creditInflight;
-    creditInflight = (async () => {
-      try {
-        creditUsd = await creditBalance();
-        creditAt = Date.now();
-      } catch { /* keep last known */ }
-      creditInflight = null;
-      return creditUsd;
-    })();
-    return creditInflight;
+    creditUsd = await creditStatus.refresh(force);
+    creditAt = creditStatus.checkedAt;
+    return creditUsd;
   };
+  let pricesInflight = null;
   const refreshPrices = async () => {
-    if (Date.now() - pricesAt < 60000 && Object.keys(lastPrices).length) return lastPrices;
-    try {
-      lastPrices = await quotedPrices();
+    if (Date.now() - pricesAt < 60000) return lastPrices;
+    if (!pricesInflight) {
       pricesAt = Date.now();
-    } catch { /* keep last */ }
+      pricesInflight = quotedPrices().then(prices => { lastPrices = prices; })
+        .catch(() => {}).finally(() => { pricesInflight = null; });
+    }
+    await pricesInflight;
     return lastPrices;
   };
   const walletMoney = () => priceHoldings(lastSnap || [], lastPrices);
@@ -570,6 +569,13 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
       return;
     }
 
+    if (req.method === 'GET' && (req.url || '').split('?')[0] === '/v1/funding') {
+      await Promise.all([refreshCredit(true), refreshWallet(true), refreshBalances()]);
+      res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+      res.end(JSON.stringify({ creditUsd, walletUsd, creditCheckedAt: creditAt || null, walletCheckedAt: walletAt || null }));
+      return;
+    }
+
     if ((req.url || '').split('?')[0] === '/mcp') {
       try {
         const { handleMcpRequest } = await import('./mcphttp.js');
@@ -1068,21 +1074,24 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
         // USDC on Base — so every 402 after a payment carries all three, not
         // only the ones the gateway managed to classify as insufficient funds.
         msg = await withOnrampLink(msg, { solana: client.address, evm: client.evmAddress, usd, code: copy.code, force: true });
-        log(/ties to your account/i.test(msg) ? 'onramp: whop + copy-paste solana' : `402: ${msg.slice(0, 140)}`);
-        jsonErr(res, paid ? copy.status : 402, msg);
+        log(/At checkout/i.test(msg) ? 'onramp: whop + copy-paste solana' : `402: ${msg.slice(0, 140)}`);
+        log(`payment diagnostic: ${copy.reason}`);
+        paymentError(res, req, init, paid ? copy.status : 402, msg);
         return;
       }
       await relay(res, response, meterStreamed);
     } catch (err) {
       if (err instanceof QuoteTooHighError) {
         log(err.message);
-        jsonErr(res, 402, err.message, { quote: err.quote });
+        paymentError(res, req, init, 400, 'This request exceeds your spending limit. Try a shorter request or change your limit.');
       } else if (err instanceof UnderfundedError) {
         const msg = await withOnrampLink(err.message, {
           solana: client.address, evm: client.evmAddress, usd: Number(err.accept?.extra?.billedUsd),
         });
         log(msg);
-        jsonErr(res, 402, msg);
+        paymentError(res, req, init, 402, `Your available balance does not cover this request yet.\n\n${whopFundBlurb(client.address, client.evmAddress)}`);
+      } else if (err instanceof BalanceUnavailableError) {
+        paymentError(res, req, init, 503, `${err.message}\n\n${whopFundBlurb(client.address, client.evmAddress)}`);
       } else {
         // "fetch failed" alone is undiagnosable — undici hides the real
         // network error in `cause`. Surface it or every transport hiccup looks
@@ -1092,7 +1101,7 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
         const detail = raw;
         log(`proxy error: ${detail}`);
         if (process.env.OPENZOO_DEBUG) console.error(err.stack);
-        jsonErr(res, 502, `openzoo proxy error: ${detail}`);
+        paymentError(res, req, init, 502, 'OpenZoo couldn’t connect right now. Please try again.');
       }
     }
   });
@@ -1130,6 +1139,13 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
     }
   }
 
+  // Funding checks run for desktop/background launches as well as terminal sessions.
+  refreshBalances = () => refreshWallet(true);
+  refreshWallet(); refreshCredit(); refreshPrices();
+  const fundingTimer = setInterval(() => { refreshCredit(); refreshWallet(); refreshPrices(); }, 3000);
+  fundingTimer.unref?.();
+  server.on('close', () => clearInterval(fundingTimer));
+
   // AUTO-PREPAY. Paying on-chain per call is where the latency lives: credit
   // is applied automatically server-side whenever a balance covers the quote,
   // so buying it once makes every later call skip verify+settle entirely.
@@ -1183,31 +1199,6 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
     } catch { /* RPC hiccup: balance is advisory */ }
     refreshCredit();
     refreshPrices();
-    // LIVE REFRESH: poll on an interval (and shortly after each paid call),
-    // print ONLY on change, and call out arrivals explicitly.
-    refreshBalances = async () => {
-      try {
-        const snap = await snapshotBalances(client);
-        if (!snap.length) return;
-        const prev = new Map((lastSnap || []).map((b) => [`${b.chain}:${b.symbol}`, b.ui]));
-        const changed = snap.some((b) => Math.abs((prev.get(`${b.chain}:${b.symbol}`) ?? 0) - b.ui) > 1e-9)
-          || snap.length !== (lastSnap || []).length;
-        if (!changed) return;
-        if (lastSnap) {
-          for (const b of snap) {
-            const gain = b.ui - (prev.get(`${b.chain}:${b.symbol}`) ?? 0);
-            if (gain > 1e-9) console.log(`funding arrived: +${gain.toFixed(6)} ${b.symbol}${b.chain !== 'solana' ? ` (${b.chain})` : ''}`);
-          }
-        }
-        lastSnap = snap;
-        console.log(`balance: ${balanceLine(snap)}`);
-      } catch { /* advisory — never noisy on RPC trouble */ }
-    };
-    const pollSecs = Number(process.env.OPENZOO_BALANCE_POLL_SECS ?? 45);
-    if (pollSecs > 0) {
-      const timer = setInterval(refreshBalances, pollSecs * 1000);
-      timer.unref?.();
-    }
     // Which rails the zoo will actually settle right now, straight off a live
     // 402 — so nobody funds a lane the resource is not currently offering.
     try {

package/lib/stripeOnramp.js

@@ -97,15 +97,12 @@ export function whopFundBlurb(solana, evm) {
   const url = whopBuyUrl();
   const base = String(evm || '').trim();
   return [
-    `Hey — buy this: ${url}`,
-    '',
-    'Copy-paste THIS Solana address into "what is your Solana address?" so it ties to your account:',
-    addr,
-    // OR FUND THE WALLET DIRECTLY. Every failed payment ends here: card via
-    // Whop, or USDC to either address — those are the only three moves a
-    // stuck caller has, so they are the whole message.
-    '',
-    `Or send USDC directly — Solana: ${addr}${base ? `  ·  Base: ${base}` : ''}`,
+    'Funding options:',
+    `Card: ${url}`,
+    `At checkout, use this Solana wallet address to link your purchase: ${addr}`,
+    `Solana (USDC): ${addr}`,
+    ...(base ? [`Base (USDC): ${base}`] : []),
+    'Your balance refreshes automatically once the payment is confirmed.',
   ].join('\n');
 }
 
@@ -151,11 +148,10 @@ export function settleFailCopy(q402) {
   const reason = gatewayReason(q402);
   const code = q402?.advice?.code || q402?.error?.code || '';
   const fund = isFundInstruction(reason, { code, advice: q402?.advice });
-  const message = reason
-    ? `openzoo payment did not settle: ${reason}`
-    : 'openzoo payment did not settle';
-  const upstreamish = /upstream|facilitator|internal(?: server)? error|settle(?:ment)? (?:failed|error)/i.test(reason) && !fund;
-  return { message, status: upstreamish ? 502 : 402, fund, reason, code: String(code || '') };
+  const message = fund
+    ? 'Your available balance does not cover this request yet. If you just added funds, wait for confirmation and try again.'
+    : 'We couldn’t complete the payment for this request. Please try again. If you already added funds, you don’t need to add them again.';
+  return { message, status: fund ? 402 : 503, fund, reason, code: String(code || '') };
 }
 
 export async function withOnrampLink(text, dest) {
@@ -164,5 +160,5 @@ export async function withOnrampLink(text, dest) {
   const blurb = whopFundBlurb(dest?.solana, dest?.evm);
   if (!blurb) return body;
   if (/ties to your account/i.test(body) && body.includes(String(dest.solana))) return body;
-  return `${blurb}\n\n${body}`;
+  return `${body}\n\n${blurb}`;
 }

package/lib/x402.js

@@ -422,8 +422,9 @@ export async function tokenBalance(connection, owner, mintStr) {
     const ata = getAssociatedTokenAddressSync(new PublicKey(mintStr), owner, false, programId);
     const bal = await connection.getTokenAccountBalance(ata);
     return { raw: BigInt(bal.value.amount), ui: bal.value.uiAmount };
-  } catch {
-    return { raw: 0n, ui: 0 };
+  } catch (error) {
+    if (/could not find account|account.*(?:does not exist|not found)/i.test(error.message)) return { raw: 0n, ui: 0 };
+    throw error;
   }
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openzoo",
-  "version": "0.51.6",
-  "description": "Local x402-paying proxy + MCP server for openzoo.fun \u2014 point any OpenAI-compatible harness (Cursor, Claude Code, aider, SDKs) at localhost and it pays per call from a local burner wallet. Solana and Base rails live; Robinhood experimental.",
+  "version": "0.51.8",
+  "description": "Local x402-paying proxy + MCP server for openzoo.fun — point any OpenAI-compatible harness (Cursor, Claude Code, aider, SDKs) at localhost and it pays per call from a local burner wallet. Solana and Base rails live; Robinhood experimental.",
   "license": "MIT",
   "type": "module",
   "bin": {