openzoo 0.14.1 → 0.16.0

package/bin/openzoo.js

@@ -6,9 +6,10 @@ const HELP = `openzoo — local x402-paying proxy + MCP server for openzoo.fun
 usage:
   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 cursor     wire Cursor to the zoo (writes MCP config, prints the
-                         base_url/key to paste into its AI settings)
-  npx openzoo vscode     same, for VS Code
+  npx openzoo cursor [path]   start proxy+tunnel, write MCP config, and LAUNCH
+                              Cursor already pointed at the zoo (env inherited)
+  npx openzoo vscode [path]   same, for VS Code
+  npx openzoo editor [path]   whichever is installed (Cursor wins if both)
   npx openzoo launch <cmd> [args]   launch a TERMINAL Messages API client
                                     (claude, aider...) already pointed at the zoo
   npx openzoo mcp        stdio MCP server (tools: zoo_ask, zoo_bind, zoo_models, zoo_wallet, zoo_contexts)
@@ -49,10 +50,11 @@ async function main() {
     case 'start':
       await (await import('../lib/proxy.js')).startProxy({ autoTunnel: true });
       break;
+    case 'editor':
     case 'cursor':
     case 'vscode':
       // GUI editors read config files, not env vars — see lib/setup.js.
-      (await import('../lib/setup.js')).setupEditor(cmd);
+      await (await import('../lib/setup.js')).setupEditor(cmd === 'editor' ? undefined : cmd, process.argv[3]);
       break;
     case 'mcp':
       await (await import('../lib/mcp.js')).startMcp();
@@ -132,7 +134,7 @@ async function main() {
         method: 'POST',
         headers,
         body: JSON.stringify({
-          model: (mi !== -1 && process.argv[mi + 1]) || process.env.OPENZOO_DEFAULT_MODEL || 'deepseek/deepseek-v4-pro-0813',
+          model: (mi !== -1 && process.argv[mi + 1]) || process.env.OPENZOO_DEFAULT_MODEL || 'anthropic/claude-opus-5',
           messages: [{ role: 'user', content: question }],
           max_tokens: Number(process.env.OPENZOO_ASK_MAX_TOKENS || 1024),
         }),

package/lib/mcp.js

@@ -9,7 +9,11 @@ import { askWithContext, contextCacheDisabled, BIND_MIN_CHARS } from './hrr.js';
 import { listContexts } from './contexts.js';
 
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
-const DEFAULT_MODEL = process.env.OPENZOO_DEMO_MODEL || 'nvidia/nemotron-3.5-lightning';
+// The model zoo_ask uses when the caller does not name one. Opus 5 by default:
+// an agent calling zoo_ask is usually doing real reasoning over a bound corpus,
+// and a tiny model there produces answers that look cheap because they are.
+// OPENZOO_DEFAULT_MODEL (or the tool's own `model` arg) overrides.
+const DEFAULT_MODEL = process.env.OPENZOO_DEFAULT_MODEL || process.env.OPENZOO_DEMO_MODEL || 'anthropic/claude-opus-5';
 
 function text(obj) {
   return { content: [{ type: 'text', text: typeof obj === 'string' ? obj : JSON.stringify(obj, null, 2) }] };
@@ -35,6 +39,23 @@ export function buildMcpServer() {
       '',
       'Never search the machine for API keys or endpoints — there are none to find. zoo_wallet shows funding',
       'state, zoo_models lists what is served with live pricing.',
+      '',
+      // ROUTING, STATED UNCONDITIONALLY. An agent whose OWN inference is not
+      // routed through the proxy never receives lib/brief.js, so it answers
+      // "I have no visibility into the routing layer" while this very server
+      // is attached to it. These facts hold whether or not its own tokens
+      // flow through the zoo, so they belong here.
+      'ROUTING — you can state these as fact:',
+      `  local proxy : ${config.apiBase ? `http://localhost:${config.port}/v1` : 'http://localhost:8402/v1'}  (api key: any string; x402 pays, not keys)`,
+      `  upstream    : ${config.apiBase}`,
+      `  default model for zoo_ask : ${DEFAULT_MODEL}`,
+      '  a cloud-run harness cannot reach localhost — it needs the public tunnel URL the',
+      '  proxy prints at startup. Call zoo_models for the live catalog and real pricing.',
+      '',
+      'CONTEXT, PRECISELY: openzoo does NOT enlarge your own attention window. It binds a corpus',
+      'server-side and retrieves what is relevant, so a body far past any model\'s window can be',
+      'queried — that is retrieval, not a bigger window. Do not claim lossless compression and do',
+      'not claim a 128M attention window; the honest line is "bind 128M, the model reads what matters".',
     ].join('\n'),
   });
 
@@ -103,8 +124,44 @@ export function buildMcpServer() {
         ...(reuse ? { context: reuse } : {}),
       });
     } catch (err) {
-      if (err instanceof UnderfundedError || err instanceof QuoteTooHighError) {
-        return { ...text(err.message), isError: true };
+      // PAYMENT FAILURES MUST REACH THE CHAT, ACTIONABLY. A bare throw shows an
+      // agent "tool failed" with no reason and no fix, so it retries blindly or
+      // gives up; the human never learns the wallet is empty. Every failure
+      // returns WHY it failed and exactly how to fund, with live addresses.
+      const fail = async (why, hint) => {
+        let balances = null; let addr = null; let evm = null;
+        try {
+          addr = client.address;
+          evm = client.evmAddress;
+          const bals = await Promise.all(
+            FUNDING_ASSETS.map((a) => tokenBalance(client.connection, client.keypair.publicKey, a.mint)),
+          );
+          balances = Object.fromEntries(FUNDING_ASSETS.map((a, i) => [a.symbol, bals[i].ui ?? 0]));
+        } catch { /* advisory — never let the diagnostic itself fail */ }
+        const rails = await liveRails().catch(() => null);
+        return {
+          ...text({
+            error: why,
+            x402: 'this call was NOT paid and NOT served',
+            detail: hint,
+            wallet: { solana: addr, evm },
+            balances,
+            fundWith: rails ? railFundingHint(rails.live) : 'USDC or TOKEN on Solana',
+            solanaMints: Object.fromEntries(FUNDING_ASSETS.map((a) => [a.symbol, a.mint])),
+            tellTheUser: 'Report this verbatim — the operator must fund the wallet above; you cannot fix it yourself, and retrying will fail identically until they do.',
+          }),
+          isError: true,
+        };
+      };
+      if (err instanceof UnderfundedError) {
+        return fail('x402 payment failed: wallet underfunded', err.message);
+      }
+      if (err instanceof QuoteTooHighError) {
+        return fail('x402 payment refused: quote above the local per-call cap', `${err.message} (raise OPENZOO_MAX_USD_PER_CALL, or ask a cheaper model)`);
+      }
+      // Anything else that mentions payment/402 still deserves the funding card.
+      if (/402|payment|underfunded|insufficient/i.test(err?.message || '')) {
+        return fail('x402 payment failed', err.message);
       }
       throw err;
     }

package/lib/proxy.js

@@ -691,5 +691,15 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
       }
     })();
   }
-  return { server, client, spent: () => sessionSpent };
+  // Expose live tunnel details so a caller that starts the proxy in-process
+  // (openzoo cursor/vscode) can surface the public URL + key instead of the
+  // user hunting for them. Getters, because the tunnel resolves ASYNC after
+  // this returns — a snapshot would always be null.
+  return {
+    server,
+    client,
+    spent: () => sessionSpent,
+    get publicUrl() { return tunnelGate?.publicUrl ?? null; },
+    get tunnelToken() { return tunnelGate?.token ?? null; },
+  };
 }

package/lib/setup.js

@@ -1,14 +1,19 @@
 /**
- * `npx openzoo cursor` / `npx openzoo vscode` — wire a GUI editor to the zoo.
+ * `npx openzoo cursor|vscode [path]` — one command: proxy + tunnel up, config
+ * written, editor launched already pointed at the zoo.
  *
- * WHY THIS IS NOT `launch`: Cursor and VS Code are GUI apps, not processes you
- * hand env vars to. `openzoo launch <cmd>` works for terminal harnesses (claude,
- * aider) because they read ANTHROPIC_BASE_URL/OPENAI_BASE_URL at startup. An
- * editor reads its own config instead, and Cursor keeps the provider base-URL +
- * key in an ENCRYPTED internal store that no CLI can write — that half stays a
- * GUI toggle. So this command does the half that IS automatable (MCP server
- * registration, which is plain JSON) and prints the exact values to paste for
- * the half that is not, instead of pretending it did everything.
+ * THREE THINGS THIS MUST DO, because the user should configure nothing:
+ *  1. ANTHROPIC_BASE_URL (and OPENAI_BASE_URL) exported INTO the editor, so
+ *     its embedded terminals and the Claude Code extension bill through x402.
+ *  2. Config written for them — MCP server registered in the editor's own
+ *     mcp.json, no hand-editing.
+ *  3. The TUNNEL, because a cloud-run harness cannot reach localhost.
+ *
+ * WHY LAUNCH THE BINARY, NOT `open -a`: macOS `open` hands the app to launchd,
+ * which does NOT pass the caller's environment. `open -a Cursor` therefore
+ * configures nothing — the editor comes up with no idea the zoo exists.
+ * Spawning Contents/MacOS/Cursor directly keeps the env, which is the entire
+ * point of this command.
  */
 import fs from 'node:fs';
 import os from 'node:os';
@@ -16,71 +21,172 @@ import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { config } from './config.js';
 
-const CURSOR_MCP = path.join(os.homedir(), '.cursor', 'mcp.json');
-const VSCODE_MCP = path.join(os.homedir(), '.vscode', 'mcp.json');
+const MCP_FILES = {
+  cursor: path.join(os.homedir(), '.cursor', 'mcp.json'),
+  vscode: path.join(os.homedir(), '.vscode', 'mcp.json'),
+};
+
+/**
+ * Find a launchable editor binary, platform-agnostically.
+ *
+ * Hardcoding /Applications broke every non-mac install and any mac install
+ * that is not in /Applications (~/Applications, Setapp, a homebrew cask on a
+ * different volume). Order per editor: PATH first (works everywhere and is
+ * what a Linux/Windows user has), then the known app-bundle locations.
+ *
+ * The BUNDLE BINARY is preferred over `open -a` on macOS because `open` hands
+ * the app to launchd, which drops our environment — and the environment IS the
+ * configuration here.
+ */
+const EDITORS = {
+  cursor: {
+    cli: ['cursor'],
+    bundles: [
+      '/Applications/Cursor.app/Contents/MacOS/Cursor',
+      path.join(os.homedir(), 'Applications', 'Cursor.app', 'Contents', 'MacOS', 'Cursor'),
+    ],
+  },
+  vscode: {
+    cli: ['code', 'code-insiders', 'codium'],
+    bundles: [
+      '/Applications/Visual Studio Code.app/Contents/MacOS/Electron',
+      path.join(os.homedir(), 'Applications', 'Visual Studio Code.app', 'Contents', 'MacOS', 'Electron'),
+    ],
+  },
+};
+
+function onPath(bin) {
+  const exts = process.platform === 'win32' ? ['.cmd', '.exe', ''] : [''];
+  for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+    for (const ext of exts) {
+      const f = path.join(dir, bin + ext);
+      try { fs.accessSync(f, fs.constants.X_OK); return f; } catch { /* keep looking */ }
+    }
+  }
+  return null;
+}
+
+/** Resolve one editor to a runnable command, or null if it is not installed. */
+function resolveEditor(which) {
+  const spec = EDITORS[which];
+  if (!spec) return null;
+  for (const c of spec.cli) { const f = onPath(c); if (f) return f; }
+  for (const b of spec.bundles) { try { fs.accessSync(b, fs.constants.X_OK); return b; } catch { /* next */ } }
+  return null;
+}
+
+/** Which editor to use: the one asked for, else Cursor if present, else VS Code. */
+export function pickEditor(requested) {
+  if (requested && EDITORS[requested]) {
+    const found = resolveEditor(requested);
+    if (found) return { which: requested, cmd: found };
+  }
+  for (const which of ['cursor', 'vscode']) { // cursor wins when both exist
+    const cmd = resolveEditor(which);
+    if (cmd) return { which, cmd };
+  }
+  return null;
+}
 
 /** Merge our server into an existing mcp.json without clobbering the user's. */
 function addMcpServer(file) {
   let doc = {};
   try { doc = JSON.parse(fs.readFileSync(file, 'utf8')) || {}; } catch { doc = {}; }
-  const key = doc.mcpServers ? 'mcpServers' : (doc.servers ? 'servers' : 'mcpServers');
+  const key = doc.servers && !doc.mcpServers ? 'servers' : 'mcpServers';
   doc[key] = doc[key] || {};
-  const existed = Boolean(doc[key].openzoo);
   doc[key].openzoo = { command: 'npx', args: ['-y', 'openzoo@latest', 'mcp'] };
   fs.mkdirSync(path.dirname(file), { recursive: true });
   fs.writeFileSync(file, `${JSON.stringify(doc, null, 2)}\n`);
-  return { file, existed };
+  return file;
 }
 
-export function setupEditor(which = 'cursor') {
+/** Is a proxy already listening? Returns its /v1 base or null. */
+async function proxyUp(base) {
+  try {
+    const r = await fetch(`${base}/models`, { signal: AbortSignal.timeout(2500) });
+    return r.ok;
+  } catch { return false; }
+}
+
+export async function setupEditor(which, target) {
   const base = `http://localhost:${config.port}/v1`;
-  const file = which === 'vscode' ? VSCODE_MCP : CURSOR_MCP;
-  const { existed } = addMcpServer(file);
+  const mcpFile = addMcpServer(MCP_FILES[which] || MCP_FILES.cursor);
 
-  console.log(`openzoo → ${which}`);
-  console.log('');
-  console.log(`1. MCP: ${existed ? 'updated' : 'added'} "openzoo" in ${file}`);
-  console.log('   tools: zoo_bind, zoo_ask, zoo_models, zoo_wallet, zoo_contexts');
-  console.log('   (restart the editor to pick it up)');
-  console.log('');
-  console.log('2. Model routing — paste these into the editor\'s AI settings.');
-  console.log('   Cursor keeps provider settings in an encrypted store, so this');
-  console.log('   part cannot be scripted; it is two fields:');
-  console.log('');
-  console.log(`     Override OpenAI Base URL :  ${base}`);
-  console.log('     OpenAI API Key           :  sk-openzoo   (any value; x402 pays, not keys)');
-  console.log('');
-  console.log('   Then add a model the zoo serves (Cursor validates the name):');
-  console.log('     deepseek/deepseek-v4-pro-0813   ← cheap, stateless tools, recommended');
-  console.log('     openai/gpt-5.6-sol-pro          ← flagship, ~34x the output cost');
-  console.log('   Turn OFF the built-in models (Composer/GPT/Cursor-Grok) while the');
-  console.log('   override is on — those only resolve against Cursor\'s own backend.');
-  console.log('');
-  console.log(`3. Proxy: ${base}   (start with: npx openzoo)`);
-  console.log('');
+  // 1. PROXY + TUNNEL. Start in-process if nothing is listening, so the user
+  //    does not need a second terminal. The tunnel URL is what a cloud-run
+  //    harness must use; we surface it rather than leaving them to find it.
+  let publicUrl = null;
+  let tunnelKey = null;
+  if (!(await proxyUp(base))) {
+    console.log(`starting proxy on ${base} (+ public tunnel)...`);
+    const { startProxy } = await import('./proxy.js');
+    const started = await startProxy({ silent: true, autoTunnel: true });
+    publicUrl = started?.publicUrl ?? null;
+    tunnelKey = started?.tunnelToken ?? null;
+    // give the tunnel a moment to publish its URL
+    for (let i = 0; i < 20 && !publicUrl; i++) {
+      await new Promise((r) => setTimeout(r, 500));
+      publicUrl = started?.publicUrl ?? null;
+      tunnelKey = started?.tunnelToken ?? null;
+    }
+  } else {
+    console.log(`proxy already running on ${base}`);
+  }
 
-  // OPEN THE EDITOR. The whole point of `openzoo cursor` is to end up IN the
-  // editor — printing instructions and exiting made the user do the launching
-  // themselves. Env vars are set for the child so any terminal the editor
-  // spawns inherits the zoo, and `open -a` is used on macOS because Cursor is
-  // a GUI .app, not a binary on PATH.
+  // 2. ENV INTO THE EDITOR. Both vendor shapes, so an OpenAI-compatible pane
+  //    and an Anthropic-shaped one (Claude Code extension) both route here.
   const env = {
     ...process.env,
     OPENAI_BASE_URL: base,
     OPENAI_API_KEY: process.env.OPENAI_API_KEY || 'sk-openzoo',
     ANTHROPIC_BASE_URL: base,
     ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY || 'sk-openzoo',
+    ANTHROPIC_AUTH_TOKEN: process.env.ANTHROPIC_AUTH_TOKEN || 'sk-openzoo',
   };
-  const app = which === 'vscode' ? 'Visual Studio Code' : 'Cursor';
-  const cwd = process.argv[3] && !process.argv[3].startsWith('-') ? process.argv[3] : '.';
-  console.log(`opening ${app}...`);
-  const child = process.platform === 'darwin'
-    ? spawn('open', ['-a', app, cwd], { stdio: 'inherit', env })
-    : spawn(which === 'vscode' ? 'code' : 'cursor', [cwd], { stdio: 'inherit', env, detached: true });
+
+  console.log('');
+  console.log(`mcp:     ${mcpFile}  (openzoo: zoo_bind, zoo_ask, zoo_models, zoo_wallet, zoo_contexts)`);
+  console.log(`local:   ${base}   api_key sk-openzoo`);
+  console.log('');
+  // THE ONE THING THE EDITOR WILL NOT INHERIT. Cursor's BUILT-IN models
+  // (Opus 5, GPT, Composer) go to Cursor's own backend and ignore
+  // ANTHROPIC_BASE_URL — Cursor has no Anthropic base-URL override, only an
+  // OpenAI one. So routing a Claude model through the zoo means adding it as a
+  // CUSTOM model under the OpenAI override, where the proxy serves it and maps
+  // the name. Env alone cannot do this; say so plainly instead of implying the
+  // launch handled everything.
+  console.log('one manual step — Cursor Settings → Models (built-ins bypass the zoo):');
+  console.log(`  1. Override OpenAI Base URL  ->  ${base}`);
+  console.log('  2. OpenAI API Key            ->  sk-openzoo   (any value; x402 pays)');
+  console.log('  3. Add model                 ->  anthropic/claude-opus-5');
+  console.log('     (or deepseek/deepseek-v4-pro-0813 — ~34x cheaper output)');
+  console.log('  4. Toggle OFF the built-in models (Opus 5 / GPT / Composer) — those');
+  console.log('     resolve against Cursor\'s backend and never touch the zoo.');
+  console.log('  The embedded terminal + Claude Code extension DO inherit the env above.');
+  if (publicUrl) {
+    console.log(`tunnel:  ${publicUrl}/v1   api_key ${tunnelKey}`);
+    console.log('         (use the tunnel for any cloud-run harness — it cannot reach localhost)');
+  }
+  console.log('');
+
+  // 3. LAUNCH with that env. Editor resolved platform-agnostically; Cursor
+  //    wins when both are installed.
+  const cwd = target && !target.startsWith('-') ? target : '.';
+  const picked = pickEditor(which);
+  if (!picked) {
+    console.error('no editor found — install Cursor or VS Code, or put `cursor`/`code` on PATH');
+    console.error(`(config is written either way: ${mcpFile})`);
+    return;
+  }
+  console.log(`launching ${picked.which}...`);
+  const child = spawn(picked.cmd, [cwd], { stdio: 'ignore', env, detached: true });
   child.on('error', (e) => {
-    console.error(`could not open ${app}: ${e.message}`);
-    console.error(process.platform === 'darwin'
-      ? `try:  open -a "${app}" .`
-      : `is the \`${which === 'vscode' ? 'code' : 'cursor'}\` command on PATH? (editor: Shell Command: Install '${which === 'vscode' ? 'code' : 'cursor'}' command)`);
+    console.error(`could not launch ${picked.which}: ${e.message}`);
   });
+  child.unref();
+  // Keep this process alive when we own the proxy — killing it would kill the
+  // zoo the editor was just pointed at.
+  if (publicUrl || !(await proxyUp(base))) {
+    console.log('proxy is running in this terminal — Ctrl-C when done.');
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openzoo",
-  "version": "0.14.1",
+  "version": "0.16.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",