openzoo 0.48.18 → 0.48.23

package/lib/launch.js

@@ -49,21 +49,54 @@ function resolveClaudeCli() {
  * Both get ANTHROPIC_BASE_URL so inference pays x402.
  */
 export async function launchClaude(argv) {
-  const base = `http://localhost:${config.port}/v1`;
+  // let, not const: startProxy can heal onto a different port and every URL
+  // below must follow the port we actually bound.
+  let base = `http://localhost:${config.port}/v1`;
   // AUTO-START THE PROXY. One command should just work — if nothing is listening,
   // boot the proxy in THIS process (it stays alive because claude runs in the
   // foreground below), rather than making the user run `npx openzoo` first.
   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 in the background...');
-    const { startProxy } = await import('./proxy.js');
-    await startProxy({ silent: true, autoTunnel: true });
+    // NEVER GO SILENT DURING STARTUP. silent:true routes the proxy's own lines
+    // to ~/.openzoo/proxy.log so payment receipts cannot corrupt Claude Code's
+    // stdio — correct DURING the session, wrong BEFORE it, because it made a
+    // slow step and a dead step look identical. Reported from the wild as
+    // "always gets stuck at 'starting the proxy in the background...'": there
+    // was nothing on screen for up to 46s and then, at worst, one terse line.
+    // A ticking elapsed counter is the difference between "hung" and "working".
+    process.stderr.write('openzoo: starting the proxy...');
+    const t0 = Date.now();
+    const tick = setInterval(() => {
+      process.stderr.write(`\ropenzoo: starting the proxy... ${((Date.now() - t0) / 1000).toFixed(0)}s`);
+    }, 1000);
+    tick.unref?.();
+    const done = (msg) => { clearInterval(tick); process.stderr.write(`\r\x1b[2Kopenzoo: ${msg}\n`); };
+    try {
+      const { startProxy } = await import('./proxy.js');
+      await startProxy({ silent: true, autoTunnel: true });
+    } catch (err) {
+      // An exception here used to surface as an eternal spinner. Say what broke.
+      done(`proxy failed to start: ${err?.message || err}`);
+      console.error('  full log: ~/.openzoo/proxy.log');
+      console.error('  try: OPENZOO_NO_TUNNEL=1 npx openzoo claude   (skips the cloudflared download)');
+      process.exit(1);
+    }
+    // The proxy may have healed onto a different port (8402 busy). config.port
+    // is the one it ACTUALLY bound, so re-derive every URL from it — the old
+    // code kept polling the port it wished for and timed out on a live proxy.
+    base = `http://localhost:${config.port}/v1`;
     for (let i = 0; i < 20 && !up; i++) {
       await new Promise((r) => setTimeout(r, 300));
       try { up = (await fetch(`${base}/models`, { signal: AbortSignal.timeout(2000) })).ok; } catch { /* keep waiting */ }
     }
-    if (!up) { console.error(`openzoo: proxy did not come up on ${base}`); process.exit(1); }
+    if (!up) {
+      done(`proxy did not answer on ${base}`);
+      console.error('  full log: ~/.openzoo/proxy.log');
+      console.error('  try: OPENZOO_NO_TUNNEL=1 npx openzoo claude   (skips the cloudflared download)');
+      process.exit(1);
+    }
+    done(`proxy up on :${config.port} (${((Date.now() - t0) / 1000).toFixed(1)}s)`);
   }
   // TERMINAL (Claude Code CLI) IS THE DEFAULT — it is the guaranteed-x402 path
   // and honours ANTHROPIC_BASE_URL. --desktop explicitly opens the desktop app

package/lib/namespace.js

@@ -36,19 +36,45 @@ import { loadOrCreateWallet } from './wallet.js';
  * BREAKING: corpora bound before this lived in the shared tenant and are not
  * reachable from a signed request. Re-bind them.
  */
-let cached = null;
+/**
+ * ONE NAMESPACE ACROSS EVERY STACC APP (2026-08-18).
+ *
+ * This used to be sha256("openzoo-ns:" + pubkey) — stable, per-user, and
+ * DIFFERENT from what every other stacc app sent. openzoo brain sent
+ * HMAC(OPENZOO_TENANT_SECRET, pubkey); the open-webui wallet sent a literal
+ * app name. Since the gateway keys a tenant on sha256(chain:signer:namespace),
+ * one wallet therefore landed in THREE tenants: three separate leCore
+ * memories and three separate credit balances, for the same person. Bind a
+ * corpus in the CLI and it was invisible from the browser.
+ *
+ * The constant is safe because the reason for the per-user hash is gone. It
+ * existed to stop someone addressing your tenant by guessing your namespace —
+ * but the gateway now folds the VERIFIED SIGNER into the tenant hash (see
+ * nsauth.ts / tenantFor), so the namespace string is no longer the
+ * access-control boundary. Signing is what proves ownership; this string only
+ * chooses WHICH of your namespaces you mean.
+ *
+ * A constant is in fact MORE private than what it replaces. A per-user hash is
+ * stable and unique, i.e. a tracking identifier that correlates one user's
+ * requests across time. A value every caller sends identically discloses
+ * nothing at all.
+ *
+ * BREAKING: corpora bound under the old per-wallet namespace live in a
+ * different tenant and will not be found. The gateway's tenantsToTry fallback
+ * reaches pre-existing context ids by id, but anything relying on the old
+ * namespace should be re-bound.
+ */
+export const STACC_NAMESPACE = 'stacc';
 
 export function namespaceHeaderValue() {
-  if (cached) return cached;
   try {
-    const w = loadOrCreateWallet();
-    cached = crypto.createHash('sha256')
-      .update(`openzoo-ns:${w.keypair.publicKey.toBase58()}`)
-      .digest('hex');
+    // Still require a wallet: the namespace is meaningless without a signer to
+    // prove it, and sending one unsigned drops you into the SHARED tenant.
+    loadOrCreateWallet();
+    return STACC_NAMESPACE;
   } catch {
-    cached = ''; // no wallet (read-only use): fall back to the shared tenant
+    return ''; // no wallet (read-only use): fall back to the shared tenant
   }
-  return cached;
 }
 
 /**

package/lib/podagent.mjs

@@ -249,13 +249,40 @@ async function httpErrorNote(status) {
 // same rail, second call pays fine). Surfacing that as a chat message makes
 // the user do the retry by hand — so do it here instead.
 const PAYMENT_RETRIES = 3;
-async function postChat(body, contextId) {
+/**
+ * ADAPTIVE top_k. We have learned this one the expensive way already.
+ *
+ * On leCore the miss was never the ranker — BM25 ranked correctly. It was
+ * top_k=16 against a 7,000-chunk corpus: we only ever ASKED for sixteen. Same
+ * shape here, and worse: grokui never set the header at all, so every call fell
+ * to the gateway default of EIGHT, while a whole project's bots write into one
+ * shared context. Six bots working for an hour and the model sees eight chunks
+ * of it.
+ *
+ * So scale with the corpus instead of picking a number. sqrt keeps it sane at
+ * both ends — 100 chunks -> 20, 1k -> 63, 7k -> 167, and it saturates at the
+ * gateway's 256 ceiling rather than growing without bound. Floor of 16 so a
+ * brand-new thread is never worse off than the old default.
+ *
+ * Cost is real and proportional (measured on leCore: top_k 16 = $0.0070,
+ * top_k 128 = $0.0489 on the same question) — which is the point. The extra
+ * spend IS the extra corpus actually being read.
+ */
+export function adaptiveTopK(boundItems) {
+  const n = Math.max(0, Number(boundItems) || 0);
+  return Math.max(16, Math.min(256, Math.ceil(Math.sqrt(n) * 2)));
+}
+
+async function postChat(body, contextId, topK) {
   let r;
   for (let attempt = 0; attempt <= PAYMENT_RETRIES; attempt++) {
     r = await fetch(`${PROXY}/chat/completions`, {
       method: 'POST',
       headers: {
         'content-type': 'application/json', authorization: 'Bearer sk-openzoo',
+        // Only sent when we actually know the corpus size; without it the
+        // gateway keeps its own default rather than getting a made-up number.
+        ...(topK ? { 'x-hrr-top-k': String(topK) } : {}),
         // real leCore memory for this thread, bound via POST /v1/hrr/bind — NOT
         // a fabricated mechanism. Retrieval runs automatically once this header
         // is set; nothing more for the model to invent or explain.
@@ -284,7 +311,7 @@ function withModelId(messages, model) {
     : m));
 }
 
-export async function brain(messages, contextId, modelOverride) {
+export async function brain(messages, contextId, modelOverride, topK) {
   // explicit plugins, not relying on the gateway's "inject when caller said
   // nothing" default — an explicit array is always respected as-is, so every
   // bot on every model actually has web search. max_tokens 900 was cutting
@@ -299,24 +326,53 @@ export async function brain(messages, contextId, modelOverride) {
   messages = vision ? messages : stripImages(messages);
   const r = await postChat(
     { model, max_tokens: 4096, messages: withModelId(messages, model), plugins: [{ id: 'web' }] },
-    contextId,
+    contextId, topK,
   );
   const j = await r.json().catch(() => ({}));
   const content = j?.choices?.[0]?.message?.content;
+  // Same truncation catch as the streaming path (see brainStream): a reply that
+  // stops because the budget ran out is not a finished reply, and this path is
+  // what non-streaming callers — including every SPAWNed subagent — go through.
+  if (content && j?.choices?.[0]?.finish_reason === 'length') {
+    const rest = await brainContinue(messages, content, contextId, modelOverride, 0);
+    return content + rest;
+  }
   return content || (r.ok ? '' : await httpErrorNote(r.status));
 }
 
+/** Resume a reply that hit the output cap, non-streaming. Bounded by
+ *  CONTINUE_ROUNDS for the same runaway reason brainStream is. */
+async function brainContinue(messages, sofar, contextId, modelOverride, round) {
+  if (round >= CONTINUE_ROUNDS) return '';
+  const vision = hasImages(messages);
+  const model = vision ? VISION_MODEL : (modelOverride || MODEL);
+  const next = [...messages,
+    { role: 'assistant', content: sofar },
+    { role: 'user', content: CONTINUE_NUDGE }];
+  const r = await postChat(
+    { model, max_tokens: Math.min(4096 * (2 ** (round + 1)), MAX_CONTINUE_TOKENS),
+      messages: withModelId(vision ? next : stripImages(next), model), plugins: [{ id: 'web' }] },
+    contextId,
+  );
+  const j = await r.json().catch(() => ({}));
+  const more = j?.choices?.[0]?.message?.content || '';
+  if (more && j?.choices?.[0]?.finish_reason === 'length') {
+    return more + await brainContinue(messages, sofar + more, contextId, modelOverride, round + 1);
+  }
+  return more;
+}
+
 /** Same call, but streamed — invokes onDelta(text) as tokens arrive (for a
  *  live-typing UI) and resolves with the full accumulated text at the end, so
  *  callers that need to parse a directive out of the complete reply still can. */
-export async function brainStream(messages, onDelta, contextId, modelOverride, maxTokens) {
+export async function brainStream(messages, onDelta, contextId, modelOverride, maxTokens, round = 0, topK = 0) {
   const vision = hasImages(messages);
   const model = vision ? VISION_MODEL : (modelOverride || MODEL);
   messages = vision ? messages : stripImages(messages);
   const budget = maxTokens || MAX_TOKENS;
   const r = await postChat(
     { model, max_tokens: budget, messages: withModelId(messages, model), plugins: [{ id: 'web' }], stream: true },
-    contextId,
+    contextId, topK,
   );
   if (!r.ok || !r.body) {
     // fall back to the non-streaming path rather than fail outright
@@ -327,7 +383,7 @@ export async function brainStream(messages, onDelta, contextId, modelOverride, m
   }
   const reader = r.body.getReader();
   const decoder = new TextDecoder();
-  let buf = '', full = '', reasonedChars = 0;
+  let buf = '', full = '', reasonedChars = 0, finish = '';
   for (;;) {
     const { value, done } = await reader.read();
     if (done) break;
@@ -340,7 +396,12 @@ export async function brainStream(messages, onDelta, contextId, modelOverride, m
       const payload = s.slice(5).trim();
       if (payload === '[DONE]') continue;
       try {
-        const d = JSON.parse(payload)?.choices?.[0]?.delta;
+        const c = JSON.parse(payload)?.choices?.[0];
+        const d = c?.delta;
+        // The LAST chunk carries why generation stopped. "length" means the
+        // budget ran out mid-answer — the only way to tell a finished reply
+        // from a guillotined one.
+        if (c?.finish_reason) finish = c.finish_reason;
         if (d?.content) { full += d.content; onDelta(d.content); }
         // Reasoning models emit their chain of thought on a SEPARATE field and
         // only then start producing content. Count it — not to show it, but to
@@ -358,9 +419,267 @@ export async function brainStream(messages, onDelta, contextId, modelOverride, m
   if (!full && reasonedChars > 0 && !maxTokens) {
     return brainStream(messages, onDelta, contextId, modelOverride, budget * 4);
   }
+
+  // CUT OFF MID-ANSWER. finish_reason "length" means the model had more to say
+  // and the budget ended the sentence for it — seen live as a reply that stops
+  // inside `for (`. Nothing above catches this, because `full` is non-empty:
+  // by every other measure the turn succeeded.
+  //
+  // CONTINUE rather than retry. Re-running the turn with a bigger budget makes
+  // the user pay twice for the half we already have (and on a reasoning model,
+  // pay for the whole chain of thought again). Handing the model back its own
+  // partial and asking for the rest costs only the rest.
+  //
+  // Bounded, because a model that ignores the nudge would otherwise continue
+  // forever on the user's wallet.
+  if (full && finish === 'length' && round < CONTINUE_ROUNDS) {
+    const more = await brainStream(
+      [...messages,
+        { role: 'assistant', content: full },
+        { role: 'user', content: CONTINUE_NUDGE }],
+      onDelta, contextId, modelOverride,
+      Math.min(budget * 2, MAX_CONTINUE_TOKENS), round + 1,
+    );
+    return full + (more || '');
+  }
   return full;
 }
 
+// How many times a single answer may be resumed after hitting the cap. Three
+// doublings off 4096 is ~57k tokens of answer, which is past any real reply and
+// well short of a runaway.
+const CONTINUE_ROUNDS = Number(process.env.OZ_CONTINUE_ROUNDS || 3);
+const MAX_CONTINUE_TOKENS = Number(process.env.OZ_MAX_CONTINUE_TOKENS || 32768);
+// Deliberately blunt about the seam: the partial usually ends mid-token, and a
+// model that "helpfully" restarts the sentence produces a visible stutter in
+// the middle of the user's code.
+const CONTINUE_NUDGE = 'You were cut off — your previous message hit the output limit mid-way. '
+  + 'Continue from EXACTLY where it stopped. Do not repeat any of it, do not summarise it, '
+  + 'do not add a preamble or an apology, and do not re-open a code fence that is already open. '
+  + 'Resume mid-word if that is where it ended.';
+
+// ---------------------------------------------------------------------------
+// MODEL TIERS  ·  cheap / medium / expensive
+// ---------------------------------------------------------------------------
+// Ranking the live catalog by price alone picks garbage at both ends: the most
+// expensive served model is o1-pro at $1800/Mtok (a bad coding model that would
+// drain the box wallet in a handful of turns), and the cheapest is a roleplay
+// finetune. Price is a proxy for capability only within a band, never across
+// the whole catalog. So each tier is a CURATED, ordered preference list, and
+// the catalog is used to check what is actually served today — the zoo's model
+// list changes under us, and a tier that resolves to a 404 is worse than no
+// tier at all.
+//
+// Each list is ordered best-first (that is what a non-racing "auto" picks) but
+// deliberately WIDE, because a race samples from it at random: a pool of three
+// would race the same three models every time, which is neither a real hedge
+// against a single provider having a bad minute nor a real sample of the tier.
+// Prices in the comments are completion USD per Mtok as served, measured.
+const TIERS = {
+  // ≲ $3/Mtok. Fast, good enough for glue work, cheap enough to race widely.
+  cheap: [
+    'deepseek/deepseek-v4-flash',        // 0.45
+    'meta-llama/llama-4-scout',          // 0.90
+    'z-ai/glm-4.7-flash',                // 1.20
+    'bytedance-seed/seed-2.0-mini',      // 1.20
+    'meta-llama/llama-4-maverick',       // 2.40
+    'z-ai/glm-4.5-air',                  // 2.55
+    'minimax/minimax-m2.5',              // 2.70
+    'z-ai/glm-4.6v',                     // 2.70
+    'minimax/minimax-m2',                // 3.06
+    'inclusionai/ling-3.0-flash',        // 0.19
+  ],
+  // ~$4.5–11/Mtok. The default band; deepseek-v4-pro is the app default.
+  medium: [
+    'deepseek/deepseek-v4-pro-0813',     // 5.94
+    'z-ai/glm-4.7',                      // 5.25
+    'google/gemini-3.7-flash',           // 5.63
+    'x-ai/grok-4.3',                     // 7.50
+    'moonshotai/kimi-k2.7-code',         // 10.50
+    'z-ai/glm-5',                        // 5.76
+    'moonshotai/kimi-k2.6',              // 7.08
+    'mistralai/mistral-large-2512',      // 4.50
+    'bytedance-seed/seed-2.0-code',      // 9.00
+    'qwen/qwen3.8-27b',                  // 9.60
+  ],
+  // ≥ $18/Mtok. Frontier. NOTE the ceiling: o1-pro ($1800) and the *-pro tiers
+  // ($240–540) are deliberately NOT here. A race of four across that band can
+  // cost dollars per turn on a box funded with a few cents.
+  expensive: [
+    'anthropic/claude-opus-5',           // 75
+    'openai/gpt-5.5',                    // 90
+    'anthropic/claude-sonnet-5',         // 30
+    'x-ai/grok-4.6',                     // 18
+    'moonshotai/kimi-k3',                // 45
+    'anthropic/claude-opus-4.8',         // 75
+    'openai/gpt-5.4',                    // 45
+    'qwen/qwen3.8-max',                  // 18
+    'x-ai/grok-4.5',                     // 18
+  ],
+};
+export const TIER_NAMES = Object.keys(TIERS);
+
+let catalogCache = { at: 0, ids: null };
+async function servedIds() {
+  // 5 minutes: long enough that a race does not re-fetch per model, short
+  // enough that a model coming back after an outage is picked up the same
+  // session.
+  if (catalogCache.ids && Date.now() - catalogCache.at < 300_000) return catalogCache.ids;
+  try {
+    const r = await fetch(`${PROXY}/models`);
+    const j = await r.json();
+    const ids = new Set((j?.data || []).map((m) => m.id).filter(Boolean));
+    if (ids.size) catalogCache = { at: Date.now(), ids };
+  } catch { /* proxy down — fall through to whatever we had, or null */ }
+  return catalogCache.ids;
+}
+
+/**
+ * The models a tier resolves to right now, only ones actually served.
+ *
+ * `random` is what a race uses: pick n from the whole tier at random rather
+ * than always the top n. Two reasons it must be random and not top-n — a fixed
+ * trio is not a hedge (they can share an upstream having a bad minute, which is
+ * precisely the failure racing is meant to survive), and it silently reduces a
+ * ten-model tier to three models the user never chose.
+ *
+ * Falls back to the curated list unchecked if the catalog is unreachable — a
+ * stale-but-plausible id beats refusing to answer.
+ */
+export async function tierModels(tier, n = 1, random = false) {
+  const want = TIERS[tier] || TIERS.medium;
+  const ids = await servedIds();
+  const live = ids ? want.filter((m) => ids.has(m)) : want;
+  const pool = live.length ? live : want;
+  const take = Math.max(1, Math.min(n, pool.length));
+  if (!random) return pool.slice(0, take);
+  // Fisher-Yates on a copy: sampling without replacement, because racing a
+  // model against itself buys nothing and still bills twice.
+  const a = pool.slice();
+  for (let i = a.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [a[i], a[j]] = [a[j], a[i]];
+  }
+  return a.slice(0, take);
+}
+
+/**
+ * Launch N models at once, judge the FIRST K that come back.
+ *
+ * "/race 2 3" — start three, and the moment two of them have returned a real
+ * answer, judge those two and ship the winner. The third is abandoned mid-flight.
+ *
+ * This is the useful shape, and it is neither of the obvious two:
+ *   - first-past-the-post (K=1) optimises latency only, and on a hard question
+ *     it rewards whichever model thought LEAST.
+ *   - wait-for-all-then-judge (K=N) buys quality with the slowest entrant's
+ *     latency, and one wedged provider stalls the whole turn.
+ * Taking the first K bounds the wait at the Kth-fastest while still giving the
+ * judge something to compare. The straggler is exactly the entrant you were
+ * least likely to want anyway.
+ *
+ * Reliability comes free with it: empty completions and provider 5xx are
+ * per-model and uncorrelated, which is why "the model returned nothing 4 times"
+ * was never fixable by a fourth try at the same model. An empty reply does NOT
+ * count toward K — otherwise the fastest model to FAIL would decide the race,
+ * the exact bug this exists to fix.
+ *
+ * Streaming is deliberately not forwarded while the race runs: nobody knows who
+ * is winning until they finish, and interleaving deltas from three models would
+ * render as noise. The winner's text is emitted whole.
+ *
+ * Every entrant is paid for, including the abandoned one — this trades money
+ * for latency and quality, which is why it is opt-in and capped.
+ */
+export async function brainRace(messages, onDelta, contextId, models, need = 1, maxTokens) {
+  const list = (models || []).filter(Boolean).slice(0, RACE_MAX);
+  if (list.length < 2) return brainStream(messages, onDelta, contextId, list[0], maxTokens);
+  const want = Math.max(1, Math.min(Number(need) || 1, list.length));
+
+  const done = [];
+  let finished = 0;
+  let release;
+  const enough = new Promise((r) => { release = r; });
+
+  const attempts = list.map((m) => brainStream(messages, () => {}, contextId, m, maxTokens)
+    .then((text) => { if (text && text.trim()) done.push({ model: m, text }); })
+    .catch(() => { /* one entrant dying is not the race dying */ })
+    .finally(() => {
+      finished += 1;
+      // Either we have what we asked for, or everyone is done and no more is
+      // coming — without the second condition a race where two of three fail
+      // would hang forever waiting for a K that can never arrive.
+      if (done.length >= want || finished === list.length) release();
+    }));
+  // Losers keep running; swallow their rejections so one cannot take the
+  // process down after the winner has already been returned.
+  for (const p of attempts) p.catch(() => {});
+
+  await enough;
+  // Completion order, so this really is the first K back — not the first K
+  // launched.
+  const cands = done.slice(0, want);
+  if (!cands.length) return '';
+  // Nothing to compare — do not spend a judging call to rubber-stamp one answer.
+  if (cands.length === 1) { onDelta(cands[0].text); return cands[0].text; }
+
+  const winner = await judge(messages, cands);
+  onDelta(winner.text);
+  return winner.text;
+}
+
+/**
+ * Pick the best of several finished answers with a small model.
+ *
+ * BLIND, as A/B/C/D. A judge told "this one is Claude and this one is a 4B
+ * llama" is being handed the answer and will take it, which would turn the
+ * whole thing into an expensive way to re-pick the tier's first entry.
+ *
+ * Cheap on purpose: reading finished replies and comparing them against a
+ * question is a far easier task than answering it, and paying frontier prices
+ * to referee frontier models would roughly double the cost of the expensive
+ * tier for no measured gain.
+ */
+async function judge(messages, cands) {
+  const letters = cands.map((_, i) => String.fromCharCode(65 + i));
+  // The question, not the transcript: the judge needs to know what was ASKED,
+  // and a full history would cost more to judge than the turn cost to answer.
+  const asked = [...messages].reverse().find((m) => m.role === 'user')?.content;
+  const question = typeof asked === 'string' ? asked : '(see candidates)';
+  const prompt = 'You are judging answers to one question. Pick the single best one.\n\n'
+    + 'QUESTION:\n' + String(question).slice(0, 4000) + '\n\n'
+    + cands.map((c, i) => 'ANSWER ' + letters[i] + ':\n' + c.text.slice(0, 6000)).join('\n\n')
+    + '\n\nJudge on: correctness first, then completeness, then whether it actually did what was asked '
+    + '(a directive like RUN: or DONE: on one line is the correct format here, not a flaw). '
+    + 'Ignore length and confidence of tone.\n'
+    + 'Reply with ONE letter and nothing else: ' + letters.join(' or ') + '.';
+  try {
+    const verdict = await brainStream([{ role: 'user', content: prompt }], () => {}, undefined, JUDGE_MODEL, 8);
+    // First in-range letter anywhere in the reply. A judge that ignores "one
+    // letter and nothing else" and writes "The best is B." still counts, which
+    // is most of them.
+    const hit = String(verdict).toUpperCase().split('').find((ch) => {
+      const n = ch.charCodeAt(0) - 65;
+      return n >= 0 && n < cands.length;
+    });
+    if (hit) return cands[hit.charCodeAt(0) - 65];
+  } catch { /* fall through */ }
+  // A dead or delisted judge must not lose the answers. Falling back to the
+  // first finisher degrades this to "fastest wins" — worse than judged, far
+  // better than empty.
+  return cands[0];
+}
+
+const RACE_MAX = Number(process.env.OZ_RACE_MAX || 4);
+
+// brainBest is GONE — brainRace(models, need) subsumes it. "wait for all N
+// then judge" is exactly need === N, and keeping a second judged-race entry
+// point meant two call sites that could disagree about what a race is.
+
+// Cheapest thing that can reliably output one letter. Overridable because the
+// catalog moves; if it is delisted the try/catch above falls back cleanly.
+const JUDGE_MODEL = process.env.OZ_JUDGE_MODEL || 'deepseek/deepseek-v4-flash';
+
 const SYSTEM = `You are the brain of a Grok-Bot-style coding/ops agent. The polished chat UI
 the user sees is Grok Bot (Anysphere's app); its "sandbox" has been pointed at THIS box, and
 your reasoning is served by openzoo (pay-per-call access to ~435 models over x402 — no API key,

package/lib/proxy.js

@@ -16,6 +16,7 @@ import { forgetContext } from './contexts.js';
 import { injectBrief } from './brief.js';
 import { withNamespace } from './namespace.js';
 import { anthropicToOpenAI, openAIToAnthropic, writeAnthropicSse } from './anthropic.js';
+import { responsesToChat, chatToResponses, writeResponsesSse } from './responses.js';
 
 const HOP_BY_HOP = new Set([
   'host', 'connection', 'keep-alive', 'transfer-encoding', 'upgrade',
@@ -41,7 +42,7 @@ const HOP_BY_HOP = new Set([
 function normalizePath(url) {
   const [path, query] = (url || '/').split(/(?=\?)/);
   let p = path.replace(/^(?:\/v1)+(?=\/v1\/)/, '');       // /v1/v1/x -> /v1/x
-  if (!/^\/v1(\/|$)/.test(p) && /^\/(hrr|chat|models|completions|embeddings|usage)/.test(p)) p = `/v1${p}`;
+  if (!/^\/v1(\/|$)/.test(p) && /^\/(hrr|chat|models|completions|embeddings|usage|responses)/.test(p)) p = `/v1${p}`;
   return p === path ? url : `${p}${query || ''}`;
 }
 
@@ -547,7 +548,51 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
     // answer back on the way out. See lib/anthropic.js.
     let anthropicMode = false;
     let anthropicModel = null;
+    let responsesMode = false;
+    let responsesModel = null;
+    let responsesCustom = null;   // names of freeform tools needing custom_tool_call on the way back
     const rawPath = (req.url || '').split('?')[0];
+
+    // RESPONSES API. Some harnesses speak only this wire format — OpenAI's
+    // Codex Security CLI pins `wire_api: "responses"` in its provider table, so
+    // a bare 404 here made it fall back to wss://api.openai.com and bypass the
+    // proxy entirely while reporting the failure as an auth error. Translate
+    // in, translate out; everything between stays on the chat path.
+    if (req.method === 'POST' && (rawPath === '/v1/responses' || rawPath === '/responses')) {
+      try {
+        const inbound = JSON.parse(bodyBuf.toString('utf8'));
+        // TEMP CAPTURE: dump the first few Responses requests so the agent's
+        // actual wire usage (store / previous_response_id / tool shapes) can be
+        // read rather than inferred. Guarded by an env var so it is off unless
+        // asked for.
+        if (process.env.OZ_CAPTURE_RESPONSES) {
+          try {
+            const fs = await import('node:fs');
+            const dir = process.env.OZ_CAPTURE_RESPONSES;
+            fs.mkdirSync(dir, { recursive: true });
+            const n = fs.readdirSync(dir).length;
+            // Capture the LATER turns too. Turn 1 is already understood; the
+            // unknown is what codex sends back after running a tool, so bias
+            // the capture toward requests that carry a tool result.
+            const hasResult = Array.isArray(inbound.input)
+              && inbound.input.some((i) => i && String(i.type || '').endsWith('_call_output'));
+            const tag = hasResult ? 'result' : 'plain';
+            if (n < 24) fs.writeFileSync(`${dir}/${tag}-${n}.json`, JSON.stringify(inbound, null, 2));
+          } catch { /* capture must never break a paid call */ }
+        }
+        responsesModel = inbound.model;
+        const meta = {};
+        bodyBuf = Buffer.from(JSON.stringify(responsesToChat(inbound, meta)));
+        responsesCustom = meta.custom;
+        responsesMode = true;
+        req.url = '/v1/chat/completions';
+        url = `${config.apiBase}${req.url}`;
+      } catch {
+        jsonErr(res, 400, 'invalid responses body');
+        return;
+      }
+    }
+
     if (req.method === 'POST' && (rawPath === '/v1/messages' || rawPath === '/messages')) {
       try {
         const inbound = JSON.parse(bodyBuf.toString('utf8'));
@@ -604,6 +649,18 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
       const hit = replayGet(rKey);
       if (hit) {
         log('identical request within 30s — served the cached completion, NOT re-paid');
+        // The cache stores the CHAT shape. A Responses caller must get its own
+        // wire format back, or the replay path silently answers in a format the
+        // client cannot parse — a bug that only appears on the SECOND identical
+        // request, which is exactly when nobody is watching.
+        if (responsesMode) {
+          if (wantsStream) { writeResponsesSse(res, hit.data, responsesModel, null, responsesCustom); return; }
+          const rh = { 'content-type': 'application/json' };
+          if (hit.settle) rh['x-payment-response'] = hit.settle;
+          res.writeHead(200, rh);
+          res.end(JSON.stringify(chatToResponses(hit.data, responsesModel, responsesCustom)));
+          return;
+        }
         if (wantsStream) { serveAsSse(res, hit.data, null); return; }
         const h = { 'content-type': 'application/json' };
         if (hit.settle) h['x-payment-response'] = hit.settle;
@@ -752,6 +809,20 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
             res.end(JSON.stringify(msg));
             return;
           }
+          if (responsesMode) {
+            // A Responses client that asked to stream is WAITING for
+            // `response.completed`; handing it a JSON body closes the socket
+            // mid-stream and it reports "stream disconnected before
+            // completion". Honour the streaming contract when it asked for it.
+            if (wantsStream) { writeResponsesSse(res, data, responsesModel, response, responsesCustom); return; }
+            const out = chatToResponses(data, responsesModel, responsesCustom);
+            const h = { 'content-type': 'application/json' };
+            const settleHdr = response.headers.get('x-payment-response');
+            if (settleHdr) h['x-payment-response'] = settleHdr;
+            res.writeHead(200, h);
+            res.end(JSON.stringify(out));
+            return;
+          }
           if (wantsStream) { serveAsSse(res, data, response); return; }
           const h = { 'content-type': 'application/json' };
           const settleHdr = response.headers.get('x-payment-response');
@@ -790,10 +861,40 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
   // AND a tunnel token, so the RunPod-fronted port stays gated exactly like the
   // public tunnel path.
   const bindHost = process.env.OPENZOO_BIND || '127.0.0.1';
-  await new Promise((resolve, reject) => {
-    server.on('error', reject);
-    server.listen(config.port, bindHost, resolve);
-  });
+  // SELF-HEAL A TAKEN PORT. A killed-but-not-reaped run, a second terminal, or
+  // anything else already on 8402 made listen() reject and took the whole start
+  // down — and because `openzoo claude` starts us with silent:true, the user saw
+  // only "starting the proxy in the background..." and no reason. Walk up to the
+  // next free port instead of dying; the caller reads config.port back out, so
+  // every URL printed afterwards is the one we actually bound.
+  //
+  // EXCEPTION: if the thing already on the port is a HEALTHY openzoo proxy,
+  // reuse it rather than starting a rival that splits spend across two wallets.
+  const wanted = config.port;
+  for (let attempt = 0; ; attempt++) {
+    try {
+      await new Promise((resolve, reject) => {
+        const onErr = (e) => { server.removeListener('error', onErr); reject(e); };
+        server.on('error', onErr);
+        server.listen(config.port, bindHost, () => { server.removeListener('error', onErr); resolve(); });
+      });
+      break;
+    } catch (e) {
+      if (e?.code !== 'EADDRINUSE' || attempt >= 12) throw e;
+      if (attempt === 0) {
+        try {
+          const probe = await fetch(`http://127.0.0.1:${config.port}/v1/models`, { signal: AbortSignal.timeout(2500) });
+          if (probe.ok) {
+            say(`openzoo: a healthy proxy is already on :${config.port} — reusing it`);
+            return { server: null, client, reused: true, port: config.port, spent: () => 0, publicUrl: null, tunnelToken: null, tunnelError: null };
+          }
+        } catch { /* not ours, or wedged — take the next port */ }
+      }
+      config.port += 1;
+      say(`openzoo: :${config.port - 1} busy — trying :${config.port}`);
+    }
+  }
+  if (config.port !== wanted) say(`openzoo: listening on :${config.port} (:${wanted} was busy)`);
 
   // AUTO-PREPAY. Paying on-chain per call is where the latency lives: the
   // gateway answers its 402 challenge in ~0.12s while a full settled call