openzoo 0.9.7 → 0.9.9

package/lib/brief.js

@@ -0,0 +1,44 @@
+/**
+ * The capability briefing the proxy injects into every conversation.
+ *
+ * WHY THIS EXISTS: an agent on the other side of this proxy has no idea what
+ * it is connected to. It assumes a stock OpenAI endpoint, so it chunks corpora
+ * it could bind whole, hunts for metadata by shelling around the operator's
+ * machine, and re-uploads the same megabytes every turn. Documentation the
+ * agent never reads does not help it. Telling it IN BAND does.
+ *
+ * Kept short on purpose — it rides every request, so it earns its tokens.
+ * OPENZOO_NO_BRIEF=1 turns it off.
+ */
+
+export const BRIEF = [
+  'You are connected through an openzoo proxy (openzoo.fun), not a stock OpenAI endpoint. What that changes:',
+  '',
+  '1. CONTEXT IS EFFECTIVELY UNBOUNDED. Any model here accepts corpora far past its own attention window: bodies over ~16KB are automatically carved and bound to a holographic (HRR) memory before the model sees them, and you then query against that. `context_length` in /v1/models is the client-usable ceiling (128M tokens), not the transformer window (that is `max_model_len`). DO NOT summarise, truncate, or "chunk to fit" a corpus to preserve context — send it whole and ask your question. One POST should stay under ~9.8M tokens (~32MiB) or the edge rejects it; for more than that, bind in several calls.',
+  '',
+  '2. THE BODY NEVER SHIPS TWICE. Put the corpus first, then a blank line, then your question. The corpus binds ONCE and every later question that reuses it ships only the question — near-free, and much faster. Re-pasting the same corpus each turn wastes real money. You can also bind explicitly: POST /v1/hrr/bind {"corpus": "..."} (free) returns a context_id; send it as the X-HRR-Context header on later calls.',
+  '',
+  '3. PAYMENT IS HANDLED. Every call is paid per-request from the operator\'s wallet via x402 (Solana / Base / Robinhood Chain, whichever is funded). There is no API key to find, no account, no rate limit to negotiate. Never search the operator\'s machine for credentials or endpoints — GET / on this proxy returns everything discoverable about it.',
+  '',
+  '4. MODEL IDS ARE FORGIVING. Ask for any model id you like; unknown ids are matched to the nearest served model, and /v1/models lists what is real (each alias row carries `served_by`).',
+].join('\n');
+
+/**
+ * Inject the briefing as a system message. Idempotent (never doubles up if a
+ * conversation already carries it), non-destructive (an existing system
+ * message keeps its position and content — ours is appended after it, since
+ * harnesses often pin behaviour in the first system turn).
+ * Returns null when nothing should change.
+ */
+export function injectBrief(body) {
+  if (process.env.OPENZOO_NO_BRIEF === '1') return null;
+  const msgs = body?.messages;
+  if (!Array.isArray(msgs) || !msgs.length) return null;
+  if (msgs.some((m) => typeof m?.content === 'string' && m.content.includes('connected through an openzoo proxy'))) return null;
+
+  const brief = { role: 'system', content: BRIEF };
+  const lastSystem = msgs.reduce((acc, m, i) => (m?.role === 'system' ? i : acc), -1);
+  const out = [...msgs];
+  out.splice(lastSystem + 1, 0, brief); // after any leading system block, before the user turns
+  return { ...body, messages: out };
+}

package/lib/mcp.js

@@ -18,14 +18,34 @@ function text(obj) {
 /** `npx openzoo mcp` — stdio MCP server sharing the proxy's wallet + payment core. */
 export async function startMcp() {
   const client = new PayClient();
-  const server = new McpServer({ name: 'openzoo', version: pkg.version });
+  // MCP's own channel for "what am I connected to" — clients surface this to
+  // the model before any tool is called, which is exactly when it needs to
+  // know it can hand over a corpus whole instead of chunking it. Same facts
+  // the proxy injects as a system message (lib/brief.js), MCP-shaped.
+  const server = new McpServer({ name: 'openzoo', version: pkg.version }, {
+    instructions: [
+      'openzoo — pay-per-call access to ~435 models (openzoo.fun). No API key, no account: each call is paid',
+      'from the operator\'s local burner wallet via x402 (Solana / Base / Robinhood Chain).',
+      '',
+      'CONTEXT IS EFFECTIVELY UNBOUNDED. Pass big bodies to zoo_ask\'s `corpus` WHOLE — do not summarise,',
+      'truncate, or chunk-to-fit. leCore holographic memory sits in front of every model: the corpus is bound',
+      'once (client-usable ceiling ~128M tokens; keep a single call under ~9.8M) and the model reads only a few',
+      'thousand tokens of it. A corpus already bound is never re-uploaded — later asks against it are near-free,',
+      'so ask many questions of the same corpus rather than re-sending it. zoo_contexts lists what is bound.',
+      '',
+      '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.',
+    ].join('\n'),
+  });
 
   server.registerTool('zoo_ask', {
     description:
       'Ask a question through openzoo.fun, paying the x402 quote transparently from the local burner wallet. '
-      + 'The zoo puts leCore holographic memory in front of every model, so `corpus` can be a HUGE text body '
-      + '(hundreds of thousands to ~1M tokens) that the model itself would refuse — the zoo spills it and the '
-      + 'model reads only a few thousand tokens. Returns the answer plus a payment receipt '
+      + 'PASS BIG CONTEXT WHOLE in `corpus` — do not summarise, truncate or chunk it to fit a context window. '
+      + 'leCore holographic memory sits in front of every model, so a corpus far past the model\'s own limit '
+      + '(client-usable ceiling ~128M tokens; keep one call under ~9.8M) is bound once and the model reads only '
+      + 'a few thousand tokens of it. Re-asking against an already-bound corpus is near-free and much faster, so '
+      + 'send the corpus once and ask many questions. Returns the answer plus a payment receipt '
       + '(billedUsd, savesVsDirect, tokens actually read).',
     inputSchema: {
       prompt: z.string().describe('The question or instruction.'),

package/lib/proxy.js

@@ -10,6 +10,7 @@ import { evmTokenBalance } from './evm.js';
 import { bindCorpus, contextCacheDisabled, BIND_MIN_CHARS } from './hrr.js';
 import { maybeRewriteModel, rewritablePath, augmentModelList, ALIAS_IDS } from './models.js';
 import { forgetContext } from './contexts.js';
+import { injectBrief } from './brief.js';
 
 const HOP_BY_HOP = new Set([
   'host', 'connection', 'keep-alive', 'transfer-encoding', 'upgrade',
@@ -324,7 +325,17 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
         log(`model "${rw.from}" is not on the zoo — nearest match ${rw.to} (OPENZOO_DEFAULT_MODEL overrides)`);
         bodyBuf = rw.body;
       }
-      try { wantsStream = JSON.parse(bodyBuf.toString('utf8'))?.stream === true; } catch { /* not JSON */ }
+      try {
+        const parsed = JSON.parse(bodyBuf.toString('utf8'));
+        wantsStream = parsed?.stream === true;
+        // Tell the agent what it is actually connected to — in band, where it
+        // will read it, instead of leaving it to guess (and to chunk corpora
+        // it could bind whole). See lib/brief.js.
+        if ((req.url || '').includes('/chat/completions')) {
+          const briefed = injectBrief(parsed);
+          if (briefed) bodyBuf = Buffer.from(JSON.stringify(briefed));
+        }
+      } catch { /* not JSON */ }
     }
 
     // Retry of a body we answered seconds ago? Serve the cached completion —

package/package.json

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