openzoo 0.48.68 → 0.48.70

package/lib/anthropic.js

@@ -87,6 +87,28 @@ export function anthropicToOpenAI(body) {
   delete out.system;
   delete out.anthropic_version;
   delete out.metadata;
+  // A SERVER-SIDE web_search TOOL IS A PLUGIN, NOT A FUNCTION — TRANSLATE IT.
+  //
+  // Claude Code's Web Search arrives as an Anthropic server tool (type
+  // "web_search_20250305", name "web_search") with NO input_schema, because
+  // Anthropic runs it itself. Routed to OpenRouter->some other provider, nobody
+  // runs it, and the old code simply DROPPED it (no schema) — so the model got
+  // no search capability and every Web Search came back "0 results". Silent,
+  // and worse than the 400 it replaced: the agent believes it searched.
+  //
+  // OpenRouter's `web` plugin is the cross-model equivalent — search-then-inject
+  // middleware that works on every model. Detect the server tool and switch it
+  // on, mapping max_uses -> max_results, rather than discarding the intent.
+  const webTool = (Array.isArray(body.tools) ? body.tools : [])
+    .find((t) => t?.type?.startsWith?.('web_search') || t?.name === 'web_search');
+  if (webTool) {
+    const existing = Array.isArray(body.plugins) ? body.plugins : [];
+    if (!existing.some((p) => p?.id === 'web')) {
+      const web = { id: 'web' };
+      if (Number.isFinite(webTool.max_uses)) web.max_results = webTool.max_uses;
+      out.plugins = [...existing, web];
+    }
+  }
   if (Array.isArray(body.tools) && body.tools.length) {
     out.tools = body.tools
       .filter((t) => t?.name && t?.input_schema)

package/lib/launch.js

@@ -230,7 +230,13 @@ export async function launchClaude(argv) {
         + 'const sp=j.spilled||{};'
         + 'const tk=Number(sp.tokensApprox)||0;'
         + 'const ht=tk>=1e6?(tk/1e6).toFixed(1)+"M":tk>=1e3?Math.round(tk/1e3)+"k":String(tk);'
-        + 'const spill=tk?("  \\u00b7 "+ht+" tok offloaded"):"";'
+        + 'const sc=Number(sp.calls)||0;'
+        + 'const fb=Number(sp.fileBinds)||0;'
+        + 'const bits=[];'
+        + 'if(sc||j.paidCalls)bits.push(sc+" spilled");'
+        + 'if(fb||sc)bits.push(fb+" filebind");'
+        + 'if(tk)bits.push(ht+" tok offloaded");'
+        + 'const spill=bits.length?("  \\u00b7 "+bits.join("  \\u00b7 ")):"";'
         // "how can I easily see what credit i'm left" — asked by a user who
         // could not tell whether x402 had charged them at all.
         + 'const cr=(j.creditUsd==null)?"":("  \\u00b7 $"+Number(j.creditUsd).toFixed(2)+" credit");'

package/lib/proxy.js

@@ -12,6 +12,9 @@ import { PayClient, QuoteTooHighError, UnderfundedError } from './pay.js';
 import { tokenBalance } from './x402.js';
 import { evmTokenBalance } from './evm.js';
 import { bindCorpus, contextCacheDisabled, BIND_MIN_CHARS } from './hrr.js';
+import {
+  loadBoundChars, noteCorpusLedger, filesForCorpus, createSpillStats,
+} from './spill.js';
 import { maybeRewriteModel, rewritablePath, augmentModelList, ALIAS_IDS } from './models.js';
 import { forgetContext } from './contexts.js';
 import { injectBrief } from './brief.js';
@@ -122,6 +125,10 @@ const boundFiles = new Set();
 // context_id -> total chars BOUND (turns + files appended). The counterfactual
 // basis must reflect what the corpus actually holds, not just this turn's slice.
 const boundChars = new Map();
+// sessionKey -> { contextId, chars } so a sidecar restart can keep appending
+// to the same context and still send the accumulated x-hrr-corpus-chars.
+const sessionLedger = new Map();
+loadBoundChars(boundChars, { sessions: sessionLedger, boundFiles });
 
 // THIS MAP SURVIVES A RESTART, OR THE COUNTERFACTUAL DOES NOT.
 //
@@ -363,9 +370,53 @@ function msgText(m) {
  * severed at a plain `user` message — everything before one is self-contained.
  * A system message is never spilled: it is the operating contract, not history.
  */
-async function spillTranscript(body, log, req) {
+async function spillTranscript(body, log, req, stats) {
   const msgs = Array.isArray(body?.messages) ? body.messages : null;
-  if (!msgs || msgs.length < 6) return null;
+  if (!msgs?.length) return null;
+
+  // FILES FIRST. The cut/length gates below used to run before filesForCorpus,
+  // so a short agent turn that Read a file never bound it � and when the
+  // extract itself returned empty, nothing logged. Extract + log unconditionally.
+  const fileResult = filesForCorpus(msgs, { boundFiles, log });
+  const files = fileResult.text;
+  const sessionId = req?.headers?.['x-claude-code-session-id']
+    || req?.headers?.['x-session-id']
+    || req?.headers?.['x-claude-session-id']
+    || (typeof body?.metadata?.user_id === 'string' ? body.metadata.user_id : null);
+  let sessionKey = sessionId ? `sid:${sessionId}` : null;
+
+  const ledgerOpts = () => ({ sessionKey, sessions: sessionLedger, boundFiles });
+  const bindFilesInBackground = (label) => {
+    if (!files) return;
+    const known = (sessionKey && spillMemo.get(sessionKey))
+      || (sessionKey && sessionLedger.get(sessionKey))
+      || null;
+    const appendTo = known?.contextId || null;
+    void bindCorpus(files, {
+      appendTo,
+      onStage: (stage, info) => {
+        if (stage === 'binding') log(`binding ${mb(info.bytes)}MB of FILES (${label})`);
+      },
+    }).then((b) => {
+      if (!b?.contextId) return;
+      noteCorpusLedger(boundChars, {
+        contextId: b.contextId,
+        reused: Boolean(appendTo),
+        corpusChars: 0,
+        fileChars: files.length,
+        ...ledgerOpts(),
+      });
+      stats?.noteFileBind(fileResult.files, fileResult.bytes);
+      if (sessionKey && !spillMemo.has(sessionKey)) {
+        spillMemo.set(sessionKey, { corpus: '', contextId: b.contextId, hash: b.hash });
+      }
+    }).catch((e) => log(`file bind failed: ${e.message}`));
+  };
+
+  if (msgs.length < 6) {
+    bindFilesInBackground('conversation under 6 messages, background');
+    return null;
+  }
 
   // Keep the recent tail, but never more than half the transcript: a fixed 8 on
   // a 10-message body left only index 2 to search, which is rarely a user turn,
@@ -415,7 +466,10 @@ async function spillTranscript(body, log, req) {
       if (severable(i)) { cut = i; break; }
     }
   }
-  if (cut <= firstSpillable) return null;         // nothing safely severable
+  if (cut <= firstSpillable) {
+    bindFilesInBackground('no severable cut, files only');
+    return null;                                  // nothing safely severable
+  }
 
   // TRIM THE TAIL BY BYTES, NOT MESSAGE COUNT.
   //
@@ -529,93 +583,40 @@ async function spillTranscript(body, log, req) {
   // sitting on this machine. Binding it makes the corpus large immediately
   // instead of eventually, and makes the truncated read whole again.
   //
-  // Read-only, bounded, deduped by path+mtime, and failures are silent: this
-  // runs on the request path and must never be the reason a turn does not go.
-  const filesForCorpus = () => {
-    if (process.env.OPENZOO_BIND_FILES === '0') return '';
-    const cap = Number(process.env.OPENZOO_BIND_FILE_MAX || 400_000);
-    const out = [];
-    const seen = new Set();
-    for (const m of msgs) {
-      const blocks = Array.isArray(m?.content) ? m.content : [];
-      const calls = Array.isArray(m?.tool_calls) ? m.tool_calls : [];
-      const paths = [];
-      for (const b of blocks) {
-        const p = b?.input?.file_path || b?.input?.path;
-        if (typeof p === 'string') paths.push(p);
-      }
-      for (const c of calls) {
-        try {
-          const a = JSON.parse(c?.function?.arguments || '{}');
-          if (typeof a.file_path === 'string') paths.push(a.file_path);
-          else if (typeof a.path === 'string') paths.push(a.path);
-        } catch { /* not json args */ }
-      }
-      for (const p of paths) {
-        if (seen.has(p) || !path.isAbsolute(p)) continue;
-        seen.add(p);
-        try {
-          const st = fs.statSync(p);
-          if (!st.isFile() || st.size > cap) continue;
-          const key = `${p}:${st.mtimeMs}`;
-          if (boundFiles.has(key)) continue;
-          boundFiles.add(key);
-          out.push(`FILE ${p}\n${fs.readFileSync(p, 'utf8')}`);
-        } catch { /* unreadable, gone, or binary — simply not corpus */ }
-      }
-    }
-    return out.join('\n\n');
-  };
-
+  // Read-only, bounded, deduped by path+mtime. Path extraction + the file-bind
+  // log already ran at the top of this function (files / fileResult).
+  //
   // FILES RIDE THE BACKGROUND, NEVER THE CRITICAL PATH.
   //
-  // The FIRST bind of a session is necessarily synchronous — the request cannot
+  // The FIRST bind of a session is necessarily synchronous � the request cannot
   // go until the context_id exists, because it travels as x-hrr-context. Folding
   // file bytes into that bind put a 400KB upload in front of the caller's turn,
   // which is the cold-bind stall this whole exercise was meant to remove: the
   // bind endpoint measures 0.34-0.48s on a 613KB corpus, and that is 0.34-0.48s
   // the user waits before a single token appears.
   //
-  // Nothing recalls a file during the turn that read it — the model already has
+  // Nothing recalls a file during the turn that read it � the model already has
   // the tool result in its window. Files are only worth having bound for the
   // NEXT ask. So the conversation binds inline and the files are appended after
   // the fact, off the clock.
   const turns = msgs.slice(firstSpillable, cut).map(msgText).filter(Boolean).join('\n\n');
-  const files = filesForCorpus();
   const corpus = turns;
+  if (!sessionKey) sessionKey = corpus.slice(0, 2048);
 
   // FILES BIND EVEN WHEN THE CONVERSATION IS TOO SMALL TO SPILL.
   //
-  // The threshold exists to stop us binding a two-line chat — it was never
+  // The threshold exists to stop us binding a two-line chat � it was never
   // meant to gate FILES. But bailing here skipped them entirely, so a fresh
   // session that reads a 200KB file bound nothing and scored 1.00x forever:
   // OBSERVED on a live session that read files all turn and never produced a
   // corpus, because its conversation stayed under the threshold the whole time.
   //
   // A file is worth binding on its own merit. So when the turns are too small
-  // to spill but files exist, bind the files anyway — in the background,
-  // against this session's context — and let this turn go unspilled. The corpus
+  // to spill but files exist, bind the files anyway � in the background,
+  // against this session's context � and let this turn go unspilled. The corpus
   // is then waiting for the next ask.
-  const sessionId = req?.headers?.['x-claude-code-session-id']
-    || req?.headers?.['x-session-id']
-    || req?.headers?.['x-claude-session-id']
-    || (typeof body?.metadata?.user_id === 'string' ? body.metadata.user_id : null);
-  const sessionKey = sessionId ? `sid:${sessionId}` : corpus.slice(0, 2048);
   if (corpus.length <= BIND_MIN_CHARS) {
-    if (files) {
-      const known = spillMemo.get(sessionKey);
-      void bindCorpus(files, {
-        appendTo: known?.contextId || null,
-        onStage: (stage, info) => {
-          if (stage === 'binding') log(`binding ${mb(info.bytes)}MB of FILES (conversation under spill threshold, background)`);
-        },
-      }).then((b) => {
-        if (!b?.contextId) return;
-        boundChars.set(b.contextId, (boundChars.get(b.contextId) || 0) + files.length);
-        persistBoundChars();
-        if (!known) spillMemo.set(sessionKey, { corpus, contextId: b.contextId, hash: b.hash });
-      }).catch((e) => log(`file bind failed: ${e.message}`));
-    }
+    bindFilesInBackground('conversation under spill threshold, background');
     return null;
   }
 
@@ -650,11 +651,30 @@ async function spillTranscript(body, log, req) {
   //   anthropic-beta, anthropic-version, x-app, x-claude-code-session-id,
   //   x-stainless-*
   const anchor = sessionKey;
-  const prior = spillMemo.get(anchor);
+  const persisted = sessionKey ? sessionLedger.get(sessionKey) : null;
+  const prior = spillMemo.get(anchor) || (persisted?.contextId
+    ? { contextId: persisted.contextId, hash: persisted.hash || '', corpus: null, restored: true }
+    : null);
   let bind;
-  if (prior && corpus.startsWith(prior.corpus) && corpus.length > prior.corpus.length) {
+  let deltaChars = 0;
+  let appended = false;
+  if (prior?.restored && prior.contextId) {
+    // Sidecar came back up: we still know the context_id and the accumulated
+    // char count, but not the prior prefix string, so we cannot slice a delta.
+    // Re-append the current prefix (some overlap is harmless) and keep the
+    // restored ledger � do not add corpus.length again.
+    void bindCorpus(corpus, {
+      appendTo: prior.contextId,
+      onStage: (stage, info) => {
+        if (stage === 'binding') log(`appending ${mb(info.bytes)}MB to ${prior.contextId} (restored session, background)`);
+      },
+    }).catch((e) => log(`append failed (history may lag one turn): ${e.message}`));
+    appended = true;
+    bind = { contextId: prior.contextId, hash: prior.hash, reused: true, bytes: 0 };
+  } else if (prior && typeof prior.corpus === 'string' && corpus.startsWith(prior.corpus) && corpus.length > prior.corpus.length) {
     const delta = corpus.slice(prior.corpus.length);
-    // FIRE AND FORGET. This delta is history for FUTURE turns — the answer
+    deltaChars = delta.length;
+    // FIRE AND FORGET. This delta is history for FUTURE turns � the answer
     // being generated right now is served from the tail plus what is already
     // bound, so waiting on the upload buys nothing and costs the user the
     // round trip on every single turn. The context id is already known, so
@@ -662,7 +682,7 @@ async function spillTranscript(body, log, req) {
     //
     // The FIRST bind is deliberately NOT async: the request must carry
     // x-hrr-context, and that id does not exist until the bind returns. Firing
-    // that one off would send the opening turn with no context at all — a
+    // that one off would send the opening turn with no context at all � a
     // silently worse answer traded for a shorter pause, which is the wrong way
     // round.
     void bindCorpus(delta, {
@@ -671,6 +691,7 @@ async function spillTranscript(body, log, req) {
         if (stage === 'binding') log(`appending ${mb(info.bytes)}MB to ${prior.contextId} (delta, background)`);
       },
     }).catch((e) => log(`append failed (history may lag one turn): ${e.message}`));
+    appended = true;
     bind = { contextId: prior.contextId, hash: prior.hash, reused: true, bytes: delta.length };
   } else {
     bind = await bindCorpus(corpus, {
@@ -679,13 +700,24 @@ async function spillTranscript(body, log, req) {
       },
     });
   }
+  // CONVERSATION LEDGER � every successful bind AND append, not only when
+  // files exist. First bind initializes to the bound corpus size; each append
+  // adds the delta; file bytes ride on top. This is what makes x-hrr-corpus-chars
+  // the accumulated bound corpus instead of this-turn's prefix.
+  noteCorpusLedger(boundChars, {
+    contextId: bind.contextId,
+    reused: appended,
+    corpusChars: corpus.length,
+    deltaChars,
+    fileChars: files.length,
+    ...ledgerOpts(),
+  });
   // APPEND THE FILES AFTER, off the clock. Fire-and-forget against the context
   // we just secured: this turn is already answerable without them, and the next
   // ask gets them for free. `boundFiles` already deduped by path:mtime, so this
   // uploads each version exactly once no matter how often the agent re-reads it.
   if (files) {
-    boundChars.set(bind.contextId, (boundChars.get(bind.contextId) || corpus.length) + files.length);
-    persistBoundChars();
+    stats?.noteFileBind(fileResult.files, fileResult.bytes);
     void bindCorpus(files, {
       appendTo: bind.contextId,
       onStage: (stage, info) => {
@@ -747,11 +779,21 @@ async function spillTranscript(body, log, req) {
   };
 }
 
-async function maybeCacheCorpus(req, bodyBuf, log) {
+async function maybeCacheCorpus(req, bodyBuf, log, stats) {
   if (contextCacheDisabled()) return null;
   if (req.method !== 'POST' || !(req.url || '').includes('/chat/completions')) return null;
   if (req.headers['x-hrr-context']) return null; // harness manages its own context
-  if (bodyBuf.length <= BIND_MIN_CHARS) return null;
+  if (bodyBuf.length <= BIND_MIN_CHARS) {
+    // Still walk the transcript: a short agent turn that Read a file should
+    // bind it even when there is nothing large enough to spill.
+    try {
+      const body = JSON.parse(bodyBuf.toString('utf8'));
+      if (Array.isArray(body?.messages) && body.messages.length) {
+        return spillTranscript(body, log, req, stats);
+      }
+    } catch { /* not json */ }
+    return null;
+  }
   let body;
   try { body = JSON.parse(bodyBuf.toString('utf8')); } catch { return null; }
   const msgs = Array.isArray(body?.messages) ? body.messages : null;
@@ -764,17 +806,24 @@ async function maybeCacheCorpus(req, bodyBuf, log) {
   const oneShot = typeof last?.content === 'string'
     && last.content.length > BIND_MIN_CHARS
     && last.content.lastIndexOf('\n\n') >= BIND_MIN_CHARS;
-  if (!oneShot) return spillTranscript(body, log, req);
+  if (!oneShot) return spillTranscript(body, log, req, stats);
   const cut = last.content.lastIndexOf('\n\n');
   const corpus = last.content.slice(0, cut);
   const ask = last.content.slice(cut + 2).trim();
-  if (!ask || ask.length > 8000) return spillTranscript(body, log, req);
+  if (!ask || ask.length > 8000) return spillTranscript(body, log, req, stats);
 
   const bind = await bindCorpus(corpus, {
     onStage: (stage, info) => {
       if (stage === 'binding') log(`binding ${mb(info.bytes)}MB corpus to holographic memory (one-time)...`);
     },
   });
+  noteCorpusLedger(boundChars, {
+    contextId: bind.contextId,
+    reused: false,
+    corpusChars: corpus.length,
+    sessions: sessionLedger,
+    boundFiles,
+  });
   if (bind.reused) {
     log(`corpus already bound (${bind.hash.slice(0, 12)}… → ${bind.contextId}) — skipped ${mb(bind.bytes)}MB upload`);
   } else {
@@ -850,16 +899,13 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
   // SPILL ACCOUNTING. The product's whole claim is that context is offloaded
   // instead of re-sent, and nothing measured it — the status line showed spend
   // and call count, which is the cost side with none of the benefit.
-  let spillCalls = 0;
-  let spilledChars = 0;
-  let spillReuses = 0;
+  const spill = createSpillStats();
   // Spend/direct for ONLY the calls that spilled. The session-wide savingX
   // averages these with every small turn that had nothing to offload, so it
   // slides toward 1.0 as a conversation grows — which reads as the mechanism
   // degrading when it is just the mix changing. OBSERVED: 1.3166 -> 1.1823
   // while spilled calls and offloaded tokens both sat completely still.
-  let spillSpend = 0;
-  let spillDirect = 0;
+  // spillSpend / spillDirect live on `spill` (createSpillStats).
   // ACTUAL UPSTREAM SPEND, FROM THE PROVIDER — not our estimate of it.
   //
   // Every other dollar figure here is derived from OpenRouter's CATALOG price
@@ -999,17 +1045,11 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
           publicTunnel: tunnelGate?.publicUrl ? `${tunnelGate.publicUrl}/v1` : null,
           servedRequests,
           spilled: {
-            calls: spillCalls,
-            chars: spilledChars,
+            ...spill.snapshot(),
             // ~4 chars/token is the usual rough rule; this is the context that
             // did NOT ride upstream on those calls, which is the number the
             // saving is actually made of.
-            tokensApprox: Math.round(spilledChars / 4),
-            reusedBinds: spillReuses,
-            spend: spillSpend,
-            direct: spillDirect,
-            savedUsd: Math.max(0, spillDirect - spillSpend),
-            savingX: spillSpend > 0 ? Number((spillDirect / spillSpend).toFixed(4)) : null,
+            boundChars: [...boundChars.values()].reduce((a, b) => a + b, 0),
           },
           spendUsd: sessionSpent,
           creditUsd,
@@ -1433,7 +1473,7 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
     try {
       let cached = null;
       try {
-        cached = await maybeCacheCorpus(req, bodyBuf, log);
+        cached = await maybeCacheCorpus(req, bodyBuf, log, spill);
       } catch (err) {
         log(`context cache skipped for this call: ${err.message}`);
       }
@@ -1462,10 +1502,8 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
       let didSpill = false;
       let result;
       if (cached) {
-        spillCalls += 1;
+        spill.noteSpill({ corpusChars: cached.corpus?.length || 0, reused: cached.reused });
         didSpill = true;
-        spilledChars += cached.corpus?.length || 0;
-        if (cached.reused) spillReuses += 1;
         result = await send(cached.body, cached.contextId, cached.topK, boundChars.get(cached.contextId) || cached.corpus?.length);
         // Sidecar wiped between runs: the gateway 404s BEFORE the 402 (nothing
         // paid). Never fail on a stale manifest — re-bind once and retry.
@@ -1506,8 +1544,8 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
           // orders of magnitude above what was billed. directUsd is exact and
           // always present; savesVsDirect is the same number as a ratio.
           if (didSpill) {
-            spillSpend += receipt.billedUsd || 0;
-            spillDirect += typeof receipt.directUsd === 'number' ? receipt.directUsd : (receipt.billedUsd || 0);
+            spill.spillSpend += receipt.billedUsd || 0;
+            spill.spillDirect += typeof receipt.directUsd === 'number' ? receipt.directUsd : (receipt.billedUsd || 0);
           }
           sessionDirect += typeof receipt.directUsd === 'number'
             ? receipt.directUsd
@@ -1527,10 +1565,10 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
         // the receipt lines go to a file (they corrupt a TUI). But the running
         // total should still be visible — so write it to the terminal TITLE via
         // an OSC escape, which updates the window/tab title without touching the
-        // TUI's content. `openzoo ● $0.0042 · 12 calls` in the title bar, live.
+        // TUI's content. `openzoo ◝ $0.0042 · 12 calls` in the title bar, live.
         if (receipt.ok && typeof receipt.billedUsd === 'number') { paidCalls += 1; }
         if (sayFile) {
-          try { process.stderr.write(`]0;openzoo ● $${sessionSpent.toFixed(4)} · ${paidCalls} call${paidCalls === 1 ? '' : 's'}`); } catch { /* no tty */ }
+          try { process.stderr.write(`]0;openzoo ◝ $${sessionSpent.toFixed(4)} · ${paidCalls} call${paidCalls === 1 ? '' : 's'}`); } catch { /* no tty */ }
         }
         scheduleRefresh(4000); // settlement lands on-chain in a few seconds
       }
@@ -1583,8 +1621,8 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
             // night's debugging after a number that was never the input.
             const basis = x.counterfactualTokensUsed ?? lc.corpusTokens;
             log(`spill priced: ${x.pricing} · basis ${basis ?? '?'} tok vs sent ${lc.tokensBefore ?? '?'} -> ${lc.tokensAfter ?? '?'} · billed ${(x.billedUsd ?? 0).toFixed(5)} direct ${(x.directUsd ?? 0).toFixed(5)}`);
-            spillSpend += x.billedUsd;
-            spillDirect += typeof x.directUsd === 'number' ? x.directUsd : x.billedUsd;
+            spill.spillSpend += x.billedUsd;
+            spill.spillDirect += typeof x.directUsd === 'number' ? x.directUsd : x.billedUsd;
           }
           paidCalls += 1;
           if (viaTunnel) tunnelSpent += x.billedUsd;
@@ -1639,8 +1677,8 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
         if (didSpill) {
           const lc = x.lecore || {};
           log(`spill priced (streamed): ${x.pricing} · basis ${x.counterfactualTokensUsed ?? '?'} tok vs sent ${lc.tokensBefore ?? '?'} -> ${lc.tokensAfter ?? '?'} · billed ${(x.billedUsd ?? 0).toFixed(5)} direct ${(x.directUsd ?? 0).toFixed(5)}`);
-          spillSpend += x.billedUsd;
-          spillDirect += typeof x.directUsd === 'number' ? x.directUsd : x.billedUsd;
+          spill.spillSpend += x.billedUsd;
+          spill.spillDirect += typeof x.directUsd === 'number' ? x.directUsd : x.billedUsd;
         }
         paidCalls += 1;
         if (viaTunnel) tunnelSpent += x.billedUsd;

package/lib/spill.js

@@ -0,0 +1,327 @@
+/**
+ * Spill-side bookkeeping that used to live (and die) inside proxy.js.
+ *
+ * Three things the status line needs, and that a live session was not getting:
+ *   1. A corpus ledger that accumulates bind + append + file bytes, persisted
+ *      so a sidecar restart still knows how big the bound context is.
+ *   2. File-path extraction that matches Claude Code / Anthropic tool_use
+ *      (and the OpenAI shape those requests are translated into).
+ *   3. Counters for spilled calls, file-bind events, and offloaded chars —
+ *      incremented on the spill path, never on a pass-through.
+ *
+ * Kept as pure-enough helpers so test/spill.test.js can cover them without
+ * standing up the proxy or the gateway.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const PATH_KEYS = new Set([
+  'file_path', 'path', 'target_file', 'filePath', 'filename', 'file',
+  'targetFile', 'filepath',
+]);
+const PATH_ARRAY_KEYS = new Set(['files', 'file_paths', 'paths', 'filePaths']);
+
+export function boundCharsFile(home = os.homedir()) {
+  return process.env.OPENZOO_BOUND_CHARS_PATH
+    || path.join(home, '.openzoo', 'bound-chars.json');
+}
+
+/**
+ * Load ~/.openzoo/bound-chars.json into the maps the proxy holds.
+ * Missing / corrupt file is a cold start, not an error.
+ */
+export function loadBoundChars(boundChars, extra = {}) {
+  const file = extra.file || boundCharsFile(extra.home);
+  let raw;
+  try { raw = fs.readFileSync(file, 'utf8'); } catch { return { ok: false, reason: 'missing' }; }
+  let data;
+  try { data = JSON.parse(raw); } catch { return { ok: false, reason: 'corrupt' }; }
+  const chars = data?.chars && typeof data.chars === 'object' ? data.chars
+    : (data && typeof data === 'object' && !data.sessions && !data.files ? data : {});
+  for (const [id, n] of Object.entries(chars)) {
+    const v = Number(n);
+    if (id && Number.isFinite(v) && v > 0) boundChars.set(id, v);
+  }
+  if (extra.sessions && data?.sessions && typeof data.sessions === 'object') {
+    for (const [k, v] of Object.entries(data.sessions)) {
+      if (k && v && typeof v.contextId === 'string') extra.sessions.set(k, v);
+    }
+  }
+  if (extra.boundFiles && Array.isArray(data?.files)) {
+    for (const key of data.files) {
+      if (typeof key === 'string') extra.boundFiles.add(key);
+    }
+  }
+  return { ok: true, contexts: boundChars.size };
+}
+
+export function persistBoundChars(boundChars, extra = {}) {
+  const file = extra.file || boundCharsFile(extra.home);
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const payload = {
+      chars: Object.fromEntries(boundChars),
+    };
+    if (extra.sessions) payload.sessions = Object.fromEntries(extra.sessions);
+    if (extra.boundFiles) payload.files = [...extra.boundFiles];
+    const tmp = `${file}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(payload));
+    fs.renameSync(tmp, file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Accumulate bound bytes for a context.
+ *
+ *   init  — first bind: ledger becomes `chars` (the bound corpus size)
+ *   add   — append / file: ledger += chars
+ *
+ * Persist after every successful update so a crash mid-session keeps the count.
+ */
+export function accumulateBoundChars(boundChars, contextId, chars, opts = {}) {
+  if (!contextId || !Number.isFinite(chars) || chars < 0) return boundChars.get(contextId) || 0;
+  const next = opts.init ? chars : (boundChars.get(contextId) || 0) + chars;
+  boundChars.set(contextId, next);
+  if (opts.sessionKey && opts.sessions) {
+    opts.sessions.set(opts.sessionKey, { contextId, chars: next });
+  }
+  if (opts.persist !== false) persistBoundChars(boundChars, opts);
+  return next;
+}
+
+/**
+ * Apply the bind/append/file rule in one place so spillTranscript and the
+ * tests cannot drift.
+ *
+ * First bind initializes to the conversation corpus; each append adds the
+ * delta; file bytes are added on top either way.
+ */
+export function noteCorpusLedger(boundChars, {
+  contextId, reused, corpusChars = 0, deltaChars = 0, fileChars = 0, ...opts
+} = {}) {
+  if (!contextId) return 0;
+  if (reused) {
+    if (deltaChars) accumulateBoundChars(boundChars, contextId, deltaChars, { ...opts, persist: false });
+  } else {
+    accumulateBoundChars(boundChars, contextId, corpusChars, { ...opts, init: true, persist: false });
+  }
+  if (fileChars) accumulateBoundChars(boundChars, contextId, fileChars, { ...opts, persist: false });
+  persistBoundChars(boundChars, opts);
+  return boundChars.get(contextId) || 0;
+}
+
+/** Expand ~ and resolve relative paths against cwd. Returns null if unusable. */
+export function resolveReadablePath(p, cwd = process.cwd()) {
+  if (typeof p !== 'string') return null;
+  let s = p.trim();
+  if (!s || s.length > 1024 || /[\n\r]/.test(s)) return null;
+  if (/^https?:\/\//i.test(s)) return null;
+  if (s.startsWith('~/') || s === '~') s = path.join(os.homedir(), s.slice(1).replace(/^\//, '') || '');
+  if (!path.isAbsolute(s)) s = path.resolve(cwd, s);
+  return s;
+}
+
+function looksLikePath(s) {
+  if (typeof s !== 'string') return false;
+  const t = s.trim();
+  if (t.length < 2 || t.length > 1024 || /[\n\r]/.test(t)) return false;
+  if (/^https?:\/\//i.test(t)) return false;
+  return /[\\/]/.test(t) || /\.\w{1,10}$/.test(t) || t.startsWith('~') || t.startsWith('.');
+}
+
+function parseArgs(args) {
+  if (args == null) return {};
+  if (typeof args === 'object' && !Array.isArray(args)) return args;
+  if (typeof args === 'string') {
+    const t = args.trim();
+    if (!t) return {};
+    try { return JSON.parse(t); } catch { return {}; }
+  }
+  return {};
+}
+
+function collectFromValue(value, out, depth) {
+  if (depth > 6 || value == null) return;
+  if (typeof value === 'string') {
+    if (looksLikePath(value)) out.push(value);
+    const t = value.trim();
+    if ((t.startsWith('{') || t.startsWith('[')) && t.length < 100_000) {
+      try { collectFromValue(JSON.parse(t), out, depth + 1); } catch { /* not json */ }
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const x of value) collectFromValue(x, out, depth + 1);
+    return;
+  }
+  if (typeof value !== 'object') return;
+  for (const [k, v] of Object.entries(value)) {
+    if (PATH_KEYS.has(k) && typeof v === 'string' && v) out.push(v);
+    else if (PATH_ARRAY_KEYS.has(k) && Array.isArray(v)) {
+      for (const x of v) {
+        if (typeof x === 'string') out.push(x);
+        else collectFromValue(x, out, depth + 1);
+      }
+    } else if (k === 'input' || k === 'arguments' || k === 'params' || k === 'parameters') {
+      collectFromValue(typeof v === 'string' ? parseArgs(v) : v, out, depth + 1);
+    }
+  }
+}
+
+/**
+ * Pull file paths out of a transcript that may still be Anthropic-shaped,
+ * already translated to OpenAI tool_calls, or a mix (Responses → chat).
+ *
+ * Structured fields only — never walks tool_result *bodies*, which are file
+ * contents and would harvest every import path in the source.
+ */
+export function extractFilePaths(msgs) {
+  const raw = [];
+  if (!Array.isArray(msgs)) return [];
+  for (const m of msgs) {
+    if (!m || typeof m !== 'object') continue;
+    const blocks = Array.isArray(m.content) ? m.content : [];
+    for (const b of blocks) {
+      if (!b || typeof b !== 'object') continue;
+      if (b.input) collectFromValue(b.input, raw, 0);
+      for (const k of PATH_KEYS) {
+        if (typeof b[k] === 'string') raw.push(b[k]);
+      }
+      // tool_result: only structured content, never a long body string
+      if (b.type === 'tool_result' && b.content && typeof b.content === 'object') {
+        collectFromValue(b.content, raw, 0);
+      } else if (b.type === 'tool_result' && typeof b.content === 'string' && b.content.length < 512 && looksLikePath(b.content)) {
+        raw.push(b.content.trim());
+      }
+    }
+    const calls = [
+      ...(Array.isArray(m.tool_calls) ? m.tool_calls : []),
+      ...(m.function_call ? [m.function_call] : []),
+    ];
+    for (const c of calls) {
+      collectFromValue(parseArgs(c?.function?.arguments ?? c?.arguments), raw, 0);
+      if (c?.input) collectFromValue(c.input, raw, 0);
+      if (typeof c?.function?.name === 'string' && c.function.arguments == null && typeof c.name === 'string') {
+        collectFromValue(c, raw, 0);
+      }
+    }
+  }
+  const seen = new Set();
+  const out = [];
+  for (const p of raw) {
+    if (typeof p !== 'string') continue;
+    const t = p.trim();
+    if (!t || seen.has(t)) continue;
+    seen.add(t);
+    out.push(t);
+  }
+  return out;
+}
+
+/**
+ * Read every new file the agent touched and return the corpus slice to bind.
+ *
+ * Read-only, size-capped, path+mtime deduped. Failures never throw — this
+ * runs on the request path.
+ *
+ * Always reports `file-bind N files / X bytes` or `file-bind 0 because …`
+ * so a silent empty extract cannot hide again.
+ */
+export function filesForCorpus(msgs, {
+  boundFiles,
+  cwd = process.cwd(),
+  cap = Number(process.env.OPENZOO_BIND_FILE_MAX || 400_000),
+  disabled = process.env.OPENZOO_BIND_FILES === '0',
+  log = () => {},
+  statSync = (p) => fs.statSync(p),
+  readFileSync = (p) => fs.readFileSync(p, 'utf8'),
+} = {}) {
+  if (disabled) {
+    log('file-bind 0 because OPENZOO_BIND_FILES=0');
+    return { text: '', files: 0, bytes: 0, reason: 'disabled' };
+  }
+  const paths = extractFilePaths(msgs);
+  if (!paths.length) {
+    log('file-bind 0 because no file paths in tool_use / tool_calls');
+    return { text: '', files: 0, bytes: 0, reason: 'no-paths' };
+  }
+  const seen = new Set();
+  const chunks = [];
+  let skippedCap = 0;
+  let skippedBound = 0;
+  let skippedMissing = 0;
+  let skippedRelative = 0;
+  for (const raw of paths) {
+    const p = resolveReadablePath(raw, cwd);
+    if (!p) { skippedRelative += 1; continue; }
+    if (seen.has(p)) continue;
+    seen.add(p);
+    try {
+      const st = statSync(p);
+      if (!st.isFile()) { skippedMissing += 1; continue; }
+      if (st.size > cap) { skippedCap += 1; continue; }
+      const key = `${p}:${st.mtimeMs}`;
+      if (boundFiles?.has(key)) { skippedBound += 1; continue; }
+      boundFiles?.add(key);
+      chunks.push(`FILE ${p}\n${readFileSync(p)}`);
+    } catch {
+      skippedMissing += 1;
+    }
+  }
+  if (!chunks.length) {
+    const why = skippedBound && !skippedMissing && !skippedCap
+      ? 'already bound'
+      : skippedCap && !skippedMissing
+        ? `over OPENZOO_BIND_FILE_MAX (${cap})`
+        : skippedMissing
+          ? 'unreadable or not a file'
+          : 'paths did not resolve';
+    log(`file-bind 0 because ${why}`);
+    return { text: '', files: 0, bytes: 0, reason: why };
+  }
+  const text = chunks.join('\n\n');
+  log(`file-bind ${chunks.length} files / ${text.length} bytes`);
+  return { text, files: chunks.length, bytes: text.length, reason: null };
+}
+
+/** Session counters the HUD reads off /v1/info. */
+export function createSpillStats() {
+  return {
+    spillCalls: 0,
+    spilledChars: 0,
+    spillReuses: 0,
+    fileBinds: 0,
+    fileBindBytes: 0,
+    spillSpend: 0,
+    spillDirect: 0,
+    noteSpill({ corpusChars = 0, reused = false } = {}) {
+      this.spillCalls += 1;
+      this.spilledChars += corpusChars;
+      if (reused) this.spillReuses += 1;
+    },
+    noteFileBind(n, bytes = 0) {
+      if (!n) return;
+      this.fileBinds += n;
+      this.fileBindBytes += bytes;
+      this.spilledChars += bytes;
+    },
+    snapshot() {
+      return {
+        calls: this.spillCalls,
+        chars: this.spilledChars,
+        tokensApprox: Math.round(this.spilledChars / 4),
+        reusedBinds: this.spillReuses,
+        fileBinds: this.fileBinds,
+        fileBindBytes: this.fileBindBytes,
+        spend: this.spillSpend,
+        direct: this.spillDirect,
+        savedUsd: Math.max(0, this.spillDirect - this.spillSpend),
+        savingX: this.spillSpend > 0 ? Number((this.spillDirect / this.spillSpend).toFixed(4)) : null,
+      };
+    },
+  };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openzoo",
-  "version": "0.48.68",
-  "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.",
+  "version": "0.48.70",
+  "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.",
   "license": "MIT",
   "type": "module",
   "bin": {