openzoo 0.7.2 → 0.9.0

package/bin/openzoo.js

@@ -4,10 +4,10 @@ const cmd = process.argv[2] || 'proxy';
 const HELP = `openzoo — local x402-paying proxy + MCP server for openzoo.fun
 
 usage:
-  npx openzoo            start the proxy on http://localhost:8402/v1
+  npx openzoo            start the proxy: http://localhost:8402/v1 (keyless) PLUS a
+                         public HTTPS url for cloud IDEs (key required, printed at start)
   npx openzoo mcp        stdio MCP server (tools: zoo_ask, zoo_models, zoo_wallet)
-  npx openzoo tunnel     public HTTPS url for cloud IDEs that cannot reach localhost
-                         (installs cloudflared itself; mints a required api key)
+  npx openzoo tunnel     public-url-only mode (everything key-gated, no keyless localhost)
   npx openzoo demo       ~1M-token needle demo: direct refuses, the zoo answers
                          (run it twice — the second run reuses the bound corpus and is near-free)
   npx openzoo contexts   list corpora bound to the zoo (never re-uploaded)
@@ -35,13 +35,14 @@ env:
   OPENZOO_NO_CONTEXT_CACHE (0 — set 1 to always ship the full body)
   OPENZOO_ENABLE_RH (0 — let DEFAULT selection fall through to the Robinhood rail;
                      OPENZOO_RAIL=robinhood forces it without this)
-  OPENZOO_TUNNEL_MAX_USD (1.00 — tunnel session ceiling)  OPENZOO_TUNNEL_TOKEN (pin the api key)`;
+  OPENZOO_TUNNEL_MAX_USD (1.00 — public-url session ceiling)  OPENZOO_TUNNEL_TOKEN (pin the api key)
+  OPENZOO_NO_TUNNEL (0 — set 1 for localhost-only, no public url)`;
 
 async function main() {
   switch (cmd) {
     case 'proxy':
     case 'start':
-      await (await import('../lib/proxy.js')).startProxy();
+      await (await import('../lib/proxy.js')).startProxy({ autoTunnel: true });
       break;
     case 'mcp':
       await (await import('../lib/mcp.js')).startMcp();

package/lib/models.js

@@ -0,0 +1,175 @@
+import { config } from './config.js';
+
+/**
+ * Model-id rewriting — "any harness, zero model setup".
+ *
+ * Cursor and friends send THEIR model ids ("gpt-5.6-sol", "gpt-4o",
+ * "claude-…") to whatever base URL is configured, and the zoo answers
+ * "model not available". Users will not hand-add custom models per harness,
+ * so the proxy maps unknown ids onto the zoo's live catalog instead:
+ *
+ *   1. an id the zoo serves passes through UNTOUCHED — this layer can never
+ *      hijack an explicit, valid choice;
+ *   2. a family hint in the requested id (grok→x-ai/, gemini→google/, …)
+ *      picks the plain (non-:free/:batch) model of that family;
+ *   3. anything else — gpt-*, claude-*, composer, o3 — falls through to
+ *      OPENZOO_DEFAULT_MODEL, or a preference-ordered pick from the catalog.
+ *
+ * Every rewrite is logged with both ids. The catalog is fetched live and
+ * cached briefly, so new zoo models resolve without shipping this package.
+ */
+
+const CATALOG_TTL_MS = 5 * 60 * 1000;
+let cache = { at: 0, ids: null };
+
+export async function zooModelIds() {
+  if (cache.ids && Date.now() - cache.at < CATALOG_TTL_MS) return cache.ids;
+  const r = await fetch(`${config.apiBase}/v1/models`);
+  if (!r.ok) throw new Error(`model catalog fetch failed: HTTP ${r.status}`);
+  const d = await r.json();
+  const ids = (d.data || []).map((m) => m.id).filter(Boolean);
+  if (ids.length) cache = { at: Date.now(), ids };
+  return ids;
+}
+
+/** Vendor fingerprints in harness model ids → zoo catalog prefixes. Order
+ *  matters only for overlapping hints; first match wins. */
+const FAMILIES = [
+  [/^gpt|^chatgpt|^o[134]\b|^o[134]-|openai/i, 'openai/'],
+  [/claude|anthropic/i, 'anthropic/'],
+  [/gemini|google/i, 'google/'],
+  [/grok|x-?ai/i, 'x-ai/'],
+  [/deepseek/i, 'deepseek/'],
+  [/qwen/i, 'qwen/'],
+  [/mistral|mixtral|codestral/i, 'mistralai/'],
+  [/llama|meta\b/i, 'meta-llama/'],
+  [/glm|z-ai|zhipu/i, 'z-ai/'],
+  [/kimi|moonshot/i, 'moonshotai/'],
+  [/minimax/i, 'minimax/'],
+  [/command|cohere/i, 'cohere/'],
+  [/nova|amazon/i, 'amazon/'],
+  [/sonar|perplexity/i, 'perplexity/'],
+  [/nemotron|nvidia/i, 'nvidia/'],
+  [/seed|doubao|bytedance/i, 'bytedance-seed/'],
+  [/solar|upstage/i, 'upstage/'],
+  [/liquid|lfm/i, 'liquid/'],
+  [/sakana/i, 'sakana/'],
+];
+
+/**
+ * Capability-tier fingerprints. The rewrite must land on a LIKE model — a
+ * harness asking for a flagship gets the zoo's flagship, "mini"/"flash" gets
+ * a light model, a reasoning id gets the heaviest thing available — never a
+ * one-size-fits-all default.
+ */
+const LIGHT_RE = /mini|nano|flash|lite|small|tiny|haiku|lightning|turbo/i;
+const HEAVY_RE = /pro\b|pro-|max\b|opus|ultra|large|\bsol\b/i;
+const REASON_RE = /^o[134]\b|^o[134]-|reason|think|r1\b|deepthink/i;
+const CODE_RE = /code|coder|codex|composer|copilot/i;
+
+/** "2.6b" → light, "70b"/"2.4t" → heavy; a param count in the id outranks words. */
+function paramTier(id) {
+  const m = /(\d+(?:\.\d+)?)([bt])\b/i.exec(id);
+  if (!m) return null;
+  const n = Number(m[1]) * (m[2].toLowerCase() === 't' ? 1000 : 1);
+  return n >= 60 ? 'heavy' : n < 15 ? 'light' : 'mid';
+}
+
+function tierOf(id) {
+  if (REASON_RE.test(id)) return 'reason';
+  return paramTier(id) || (LIGHT_RE.test(id) ? 'light' : HEAVY_RE.test(id) ? 'heavy' : 'mid');
+}
+
+const GENERIC_TOKENS = new Set(['chat', 'model', 'latest', 'preview', 'instruct', 'v1', 'v2', 'v3', 'v4']);
+const tokensOf = (id) => id.toLowerCase().split(/[^a-z0-9.]+/).filter((t) => t && !GENERIC_TOKENS.has(t));
+
+/**
+ * Map a requested model id onto the catalog by similarity. Returns null when
+ * the id is already servable (no rewrite), otherwise the closest zoo id.
+ * OPENZOO_DEFAULT_MODEL is an explicit user override, not a fallback tier.
+ */
+export function resolveModel(requested, ids) {
+  if (!requested || !ids?.length || ids.includes(requested)) return null;
+  const env = process.env.OPENZOO_DEFAULT_MODEL;
+  if (env && ids.includes(env)) return env;
+
+  const reqTier = tierOf(requested);
+  const reqCode = CODE_RE.test(requested);
+  const reqToks = new Set(tokensOf(requested));
+
+  let best = null;
+  let bestScore = -Infinity;
+  for (const id of ids) {
+    let score = 0;
+    // Same vendor family is the strongest signal there is.
+    for (const [re, prefix] of FAMILIES) {
+      if (re.test(requested) && id.startsWith(prefix)) { score += 100; break; }
+    }
+    // Tier: exact match strong; reasoning degrades to heavy (a reasoner's
+    // nearest neighbour is a flagship, never a mini); mid borders both.
+    const t = tierOf(id);
+    if (t === reqTier) score += 40;
+    else if (reqTier === 'reason' && t === 'heavy') score += 30;
+    else if ((reqTier === 'mid') !== (t === 'mid') && t !== 'light' && reqTier !== 'light') score += 15;
+    else if ((reqTier === 'light' && t === 'mid') || (reqTier === 'mid' && t === 'light')) score += 15;
+    // Specialisation: code asks want code models; nothing else does.
+    if (CODE_RE.test(id)) score += reqCode ? 25 : -8;
+    // Shared name tokens ("grok", "4.6", "sonnet") pull toward the namesake.
+    for (const tok of tokensOf(id)) if (reqToks.has(tok)) score += 10;
+    // Full-strength beats :free/:batch variants at equal similarity.
+    if (!id.includes(':')) score += 5;
+    if (score > bestScore) { bestScore = score; best = id; }
+  }
+  return best;
+}
+
+/**
+ * Ids harnesses ship as DEFAULTS (Cursor, Continue, Aider, Codex CLI, Cline,
+ * OpenClaw, LangChain templates…). Merged into GET /v1/models so a harness
+ * that validates its configured model against the list passes validation —
+ * the POST is then rewritten by resolveModel. Every one of these resolves.
+ */
+export const ALIAS_IDS = [
+  'gpt-4o', 'gpt-4o-mini', 'gpt-4.1', 'gpt-4.1-mini', 'gpt-4-turbo', 'gpt-3.5-turbo',
+  'gpt-5', 'gpt-5-mini', 'chatgpt-4o-latest', 'o1', 'o3', 'o3-mini', 'o4-mini',
+  'claude-3-5-sonnet-latest', 'claude-sonnet-4-0', 'claude-opus-4-1',
+  'gemini-2.5-pro', 'gemini-2.5-flash', 'grok-4', 'grok-3',
+  'deepseek-chat', 'deepseek-reasoner', 'qwen-max', 'llama-3.3-70b',
+];
+
+/** Merge alias rows into a /v1/models payload without duplicating real ids. */
+export function augmentModelList(payload) {
+  const data = Array.isArray(payload?.data) ? payload.data : [];
+  const have = new Set(data.map((m) => m.id));
+  const aliases = ALIAS_IDS.filter((id) => !have.has(id))
+    .map((id) => ({ id, object: 'model', owned_by: 'openzoo-alias' }));
+  return { ...payload, object: payload?.object || 'list', data: [...data, ...aliases] };
+}
+
+/**
+ * Which request paths carry a rewritable model field. POST-only; embeddings /
+ * audio / image / moderation models are DIFFERENT model families — rewriting
+ * a chat model into those would corrupt the call, so they pass untouched.
+ */
+export function rewritablePath(method, url) {
+  if (method !== 'POST') return false;
+  const p = (url || '').split('?')[0];
+  return !/embed|audio|image|moderation/.test(p);
+}
+
+/**
+ * Rewrite the model field of any request body that has one.
+ * Returns null (send as-is) or { body, from, to }. Any failure — bad JSON,
+ * unreachable catalog — returns null: this layer must never break a call
+ * that would have worked without it.
+ */
+export async function maybeRewriteModel(bodyBuf) {
+  let body;
+  try { body = JSON.parse(bodyBuf.toString('utf8')); } catch { return null; }
+  if (typeof body?.model !== 'string') return null;
+  let ids;
+  try { ids = await zooModelIds(); } catch { return null; }
+  const to = resolveModel(body.model, ids);
+  if (!to) return null;
+  return { body: Buffer.from(JSON.stringify({ ...body, model: to })), from: body.model, to };
+}

package/lib/proxy.js

@@ -6,6 +6,7 @@ import {
 import { PayClient, QuoteTooHighError, UnderfundedError } from './pay.js';
 import { tokenBalance } from './x402.js';
 import { bindCorpus, contextCacheDisabled, BIND_MIN_CHARS } from './hrr.js';
+import { maybeRewriteModel, rewritablePath, augmentModelList, ALIAS_IDS } from './models.js';
 import { forgetContext } from './contexts.js';
 
 const HOP_BY_HOP = new Set([
@@ -110,13 +111,23 @@ async function maybeCacheCorpus(req, bodyBuf, log) {
  * becomes the only thing between a stranger and your wallet. Both are off by
  * default, so localhost behaviour is unchanged.
  */
-export async function startProxy({ silent = false, requireToken = null, sessionMaxUsd = null } = {}) {
+export async function startProxy({ silent = false, requireToken = null, sessionMaxUsd = null, autoTunnel = false } = {}) {
   const client = new PayClient();
   const log = silent ? () => {} : (...a) => console.log(...a);
   let sessionSpent = 0;
+  let tunnelSpent = 0;
+  // Set once cloudflared is up (see below). Gating keys off the REQUEST's
+  // origin, not off whether the URL exists yet, so there is no startup window
+  // where public traffic slips through ungated.
+  let tunnelGate = null;
 
   const server = http.createServer(async (req, res) => {
     const url = `${config.apiBase}${req.url}`;
+    // Requests that arrived over the public quick-tunnel URL carry cloudflared's
+    // headers; nothing dialing 127.0.0.1 directly does. That distinction is what
+    // lets localhost stay keyless while the SAME port is safely public.
+    const viaTunnel = !requireToken && tunnelGate
+      && Boolean(req.headers['cf-connecting-ip'] || req.headers['cf-ray']);
     // Auth first: refuse before reading a body, forwarding, quoting or paying.
     if (requireToken) {
       const got = (req.headers.authorization || '').replace(/^Bearer\s+/i, '').trim();
@@ -130,6 +141,18 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
         return;
       }
     }
+    if (viaTunnel) {
+      const got = (req.headers.authorization || '').replace(/^Bearer\s+/i, '').trim();
+      if (got !== tunnelGate.token) {
+        log(`public url: 401 ${req.method} ${req.url}`);
+        jsonErr(res, 401, 'unauthorized: this openzoo public URL requires the api key printed at startup');
+        return;
+      }
+      if (tunnelSpent >= tunnelGate.sessionMaxUsd) {
+        jsonErr(res, 402, `openzoo public-URL session cap reached ($${tunnelGate.sessionMaxUsd}) — restart the proxy or raise OPENZOO_TUNNEL_MAX_USD`);
+        return;
+      }
+    }
     let bodyBuf;
     try {
       bodyBuf = await readBody(req);
@@ -137,9 +160,41 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
       jsonErr(res, 400, 'bad request body');
       return;
     }
+    // Harness model ids ("gpt-5.6-sol", "claude-…") are rewritten onto the
+    // NEAREST zoo model BEFORE anything else sees the body — any POST that
+    // carries a model field, not just chat/completions, so /completions,
+    // /responses and future shapes all work. Never silent.
+    if (rewritablePath(req.method, req.url)) {
+      const rw = await maybeRewriteModel(bodyBuf);
+      if (rw) {
+        log(`model "${rw.from}" is not on the zoo — nearest match ${rw.to} (OPENZOO_DEFAULT_MODEL overrides)`);
+        bodyBuf = rw.body;
+      }
+    }
     const init = { method: req.method, headers: upstreamHeaders(req) };
     if (req.method !== 'GET' && req.method !== 'HEAD') init.body = bodyBuf;
 
+    // Harnesses validate their configured model BEFORE ever POSTing — some
+    // list /v1/models, some probe /v1/models/<id>. Both must succeed for the
+    // ids we know how to rewrite, or the harness refuses upfront and the
+    // rewrite never gets its chance.
+    const path = (req.url || '').split('?')[0];
+    if (req.method === 'GET' && path === '/v1/models') {
+      try {
+        const { response } = await client.fetch(url, init);
+        const payload = await response.json();
+        res.writeHead(response.status, { 'content-type': 'application/json' });
+        res.end(JSON.stringify(response.ok ? augmentModelList(payload) : payload));
+        return;
+      } catch { /* fall through to the plain relay below */ }
+    }
+    const probe = req.method === 'GET' && /^\/v1\/models\/(.+)$/.exec(path);
+    if (probe && ALIAS_IDS.includes(decodeURIComponent(probe[1]))) {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ id: decodeURIComponent(probe[1]), object: 'model', owned_by: 'openzoo-alias' }));
+      return;
+    }
+
     try {
       let cached = null;
       try {
@@ -175,11 +230,17 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
       }
       const { response, paid, receipt } = result;
       if (paid && receipt) {
-        if (receipt.ok && typeof receipt.billedUsd === 'number') sessionSpent += receipt.billedUsd;
+        if (receipt.ok && typeof receipt.billedUsd === 'number') {
+          sessionSpent += receipt.billedUsd;
+          // The public-URL ceiling meters only public-origin spend — your own
+          // local calls never eat into it.
+          if (viaTunnel) tunnelSpent += receipt.billedUsd;
+        }
         const line = receipt.ok ? receipt.line : `paid retry -> HTTP ${receipt.status}`;
-        // In tunnel mode the running total is the thing you actually want to
-        // watch, so it rides on every receipt.
-        log(requireToken ? `${line}  ·  session $${sessionSpent.toFixed(6)}` : line);
+        // Wherever a running total is the thing to watch, it rides the receipt.
+        if (requireToken) log(`${line}  ·  session $${sessionSpent.toFixed(6)}`);
+        else if (viaTunnel) log(`${line}  ·  public-url session $${tunnelSpent.toFixed(6)}`);
+        else log(line);
       }
       await relay(res, response);
     } catch (err) {
@@ -252,5 +313,35 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
     console.log(`  base_url = http://localhost:${config.port}/v1`);
     console.log('  api_key  = sk-openzoo   (any value works; the zoo takes payment, not keys)');
   }
+
+  // AUTO-TUNNEL: `npx openzoo` must be end-to-end for cloud IDEs too — their
+  // servers cannot dial localhost, so the default command also publishes a
+  // quick-tunnel URL. It comes up in the background (never delays localhost),
+  // failure degrades to local-only, and public traffic is gated above by
+  // token + its own spend ceiling. OPENZOO_NO_TUNNEL=1 opts out.
+  if (autoTunnel && process.env.OPENZOO_NO_TUNNEL !== '1') {
+    (async () => {
+      try {
+        const { ensureCloudflared, startCloudflared, mintToken } = await import('./tunnel.js');
+        const token = mintToken();
+        const cap = Number(process.env.OPENZOO_TUNNEL_MAX_USD || 1);
+        const bin = await ensureCloudflared((m) => log(m));
+        const { url, proc } = await startCloudflared(bin, config.port, log);
+        tunnelGate = { token, sessionMaxUsd: cap };
+        const bye = () => { try { proc.kill('SIGTERM'); } catch { /* already gone */ } };
+        process.once('SIGINT', () => { bye(); process.exit(0); });
+        process.once('SIGTERM', () => { bye(); process.exit(0); });
+        process.once('exit', bye);
+        log('');
+        log('cloud IDE / remote harness? use the public URL (they cannot reach localhost):');
+        log(`  base_url = ${url}/v1`);
+        log(`  api_key  = ${token}`);
+        log(`  (key REQUIRED on the public URL — it spends this wallet; capped at $${cap.toFixed(2)}/session,`);
+        log('   OPENZOO_TUNNEL_MAX_USD to change, OPENZOO_NO_TUNNEL=1 for localhost-only)');
+      } catch (err) {
+        log(`public URL unavailable (${err.message}) — localhost still works; OPENZOO_NO_TUNNEL=1 hides this line`);
+      }
+    })();
+  }
   return { server, client, spent: () => sessionSpent };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openzoo",
-  "version": "0.7.2",
+  "version": "0.9.0",
   "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",