opencode-zen-freex 0.2.7 → 0.2.8

package/LICENSE

@@ -4,7 +4,9 @@ Copyright (c) 2026 xiaozhou26
 Copyright (c) 2026 opencode-zen-free contributors
 
 This is a maintained fork of the OpenCode Zen Free plugin from
-magpie-community/plugins, which is MIT licensed and carries the notice above.
+magpie-community/plugins, which is MIT licensed and carries the notice above:
+the `Copyright (c) 2026 xiaozhou26` line is upstream's and has to be kept with
+it, and the `opencode-zen-free contributors` line covers this fork.
 The fork is maintained separately because the free tier's request fingerprint
 moves faster than that repository follows it.
 

package/MAINTAINING.md

@@ -155,6 +155,7 @@ It reports each request as:
 | `answered` | Zen served it; this shape is current |
 | `refused` | Zen did not recognise it (403) |
 | `superseded` | Zen wants a newer OpenCode than the profile claims (426) |
+| `failed` | Zen answered with something other than a 403, so it never judged the fingerprint |
 | `unreachable` | Zen could not be asked at all |
 
 The `floor` decides the exit code, because it is the shape this plugin exists to
@@ -163,6 +164,11 @@ stale. Asking only the full shape left a real gap: `read` alone is `answered` an
 everything but `read` is `refused`, so a Zen that began insisting on one more
 name would keep `full` passing while the shape actually sent was refused.
 
+Only a 403 and a 426 are Zen answering about the fingerprint. A 5xx, a 429 or a
+401 says nothing about the wording, and the gate says so rather than sending the
+reader to `capture` over an outage — as it does when nothing was reached, or when
+part of a run answered and part of it did not.
+
 `capture` needs `opencode` on PATH. It points a real OpenCode at a server running
 locally and reads the request it makes, so nothing is sent to Zen and no key is
 involved.
@@ -193,6 +199,12 @@ by changing tools.
 repeated refusals from this address have put it in a cooldown — they can, and
 the cooldown answers like a refusal.
 
+**`failed`.** Zen answered, but not with 403: a 5xx or a 429, or a 401 if the
+request was not authorized. Not a fingerprint problem either, and the gate says
+so rather than naming the wording. A 429 is the one to read twice: repeated
+refusals from this address can put it in a cooldown, and a cooldown answers
+quickly and often.
+
 ## Things that are easy to break
 
 **Marking a list as fallen back when Zen's own list was read.** `discover()`
@@ -252,6 +264,33 @@ that passes under the stricter of them, since the looser one will not last.
 | `capture.mjs` | takes a new capture |
 | `tools-smoke.mjs` | asks Zen what it accepts (`check:gate`) |
 
+## Which copy of the icon and the concurrency is authoritative
+
+`icon` and `maxConcurrency` are declared twice, and neither copy can be read by
+the other: `package.json`'s `magpie` block is host-facing JSON, and the `auth`
+object in `provider.mjs` is the runtime's. Nothing builds one from the other, so
+a change to either alone drifts.
+
+The runtime values are authoritative for what the plugin asks for. The manifest
+block is what a host reads before it loads the plugin, so a host that reads it
+will act on that copy, and one that does not will act on the runtime's — which
+means editing one and not the other silently changes how many requests the host
+makes at once (too high and Zen rate-limits them, too low and they queue behind
+each other). Change both, and keep them saying the same thing.
+
+## What runs this
+
+Every script in `package.json` names `bun`: `bun test` is the suite, and
+`check:gate`, `limits:audit` and `capture` are the tools. `bun test` is what CI
+runs, at the version pinned in `.github/workflows/ci.yml` so a run says something
+about the commit rather than about whatever Bun was newest that morning.
+
+Nothing here is installed with Bun — there are no dependencies — so Bun is the
+tools only. `import.meta.main` is what decides whether `tools-smoke.mjs` runs its
+gate or is being imported by a test, and a Node older than 22.18 does not define
+it: the gate falls back to comparing the entry path, and exits non-zero saying
+nothing was asked if it cannot tell the two apart.
+
 ## Publishing
 
 The package is `opencode-zen-freex`; the provider it registers is

package/capture.mjs

@@ -17,6 +17,7 @@
 import { spawn } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { mkdtempSync } from "node:fs";
+import { rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { PROFILES } from "./core-tools.mjs";
@@ -26,8 +27,12 @@ const DRY = process.argv.includes("--dry");
 const HERE = import.meta.dir;
 const FINGERPRINT = join(HERE, "fingerprint.json");
 
-// The names Zen reads. Everything else a host declares is ignored by it.
-const READ = ["bash", "glob", "grep", "read", "write", "edit"];
+// The names Zen reads, by generation: 2.x sends `shell` where 1.x sends `bash`
+// and carries none of the others. Everything else a host declares is ignored.
+const READ = {
+  "1.x": ["bash", "glob", "grep", "read", "write", "edit"],
+  "2.x": ["shell", "read"],
+};
 
 // The capture host's own scratch directory and OS banner belong to the machine
 // the capture ran on, not to the tool. These are put back to something neutral
@@ -42,6 +47,15 @@ const NEUTRALISE = [
 const KEEP = 1200;
 
 const capturedPath = join(tmpdir(), `zen-capture-${process.pid}.json`);
+// A run that was killed leaves its file behind and a PID comes round again, so
+// this one is removed rather than read back as if it were this run's capture.
+rmSync(capturedPath, { force: true });
+// OpenCode makes more than one request (a short one for the title, then the
+// real one). The one worth reading is the longest, since it is the one that
+// carries the full toolset. It is kept here rather than written from the handler
+// as it arrives: two requests in flight at once would both be writing this one
+// file, and the writes interleave into it.
+let longest = { agent: null, body: "" };
 const server = Bun.serve({
   port: PORT,
   hostname: "127.0.0.1",
@@ -49,16 +63,8 @@ const server = Bun.serve({
     const url = new URL(request.url);
     if (url.pathname.endsWith("/models"))
       return Response.json({ object: "list", data: [{ id: "big-pickle", object: "model", owned_by: "opencode" }] });
-    // OpenCode makes more than one request (a short one for the title, then the
-    // real one). The one worth reading is the longest, since it is the one that
-    // carries the full toolset.
     const body = await request.text();
-    let previous = { agent: null, body: "" };
-    try {
-      previous = JSON.parse(readFileSync(capturedPath, "utf8"));
-    } catch {}
-    if (body.length > previous.body.length)
-      await Bun.write(capturedPath, JSON.stringify({ agent: request.headers.get("user-agent"), body }));
+    if (body.length > longest.body.length) longest = { agent: request.headers.get("user-agent"), body };
     return new Response(
       [
         'data: {"id":"c1","object":"chat.completion.chunk","created":1,"model":"big-pickle","choices":[{"index":0,"delta":{"role":"assistant","content":"OK"},"finish_reason":null}]}',
@@ -101,6 +107,8 @@ const code = await new Promise((done) => {
 });
 server.stop(true);
 if (!ran) process.exit(1);
+// Written here, once nothing else can be writing it.
+if (longest.body.length) await Bun.write(capturedPath, JSON.stringify(longest));
 
 let request;
 try {
@@ -110,11 +118,25 @@ try {
   process.exit(1);
 }
 
-const body = JSON.parse(request.body);
+let body;
+try {
+  body = JSON.parse(request.body);
+} catch {
+  console.error("the captured request body is not JSON; nothing to read");
+  process.exit(1);
+}
+
+// Which generation this client is: the names it sends say so. It is read
+// before the tools are, since the two generations do not send the same names
+// and 2.x has to be recognised by `shell` rather than judged against 1.x's.
+const names = new Set((body.tools ?? []).map((raw) => (raw.function ?? raw)?.name));
+const generation = names.has("shell") ? "2.x" : "1.x";
+const read = READ[generation];
+
 const tools = {};
 for (const raw of body.tools ?? []) {
   const tool = raw.function ?? raw;
-  if (!tool?.name || !READ.includes(tool.name) || !tool.description) continue;
+  if (!tool?.name || !read.includes(tool.name) || !tool.description) continue;
   tools[tool.name] = {
     name: tool.name,
     description: NEUTRALISE.reduce((text, [find, to]) => text.replace(find, to), tool.description).slice(0, KEEP),
@@ -122,7 +144,7 @@ for (const raw of body.tools ?? []) {
   };
 }
 
-const missing = READ.filter((name) => !tools[name]);
+const missing = read.filter((name) => !tools[name]);
 if (missing.length) {
   console.error(
     `the captured request has no ${missing.join(", ")}; this OpenCode no longer sends them, so it cannot be captured this way`,
@@ -135,8 +157,6 @@ for (const [name, tool] of Object.entries(tools))
     process.exit(1);
 }
 
-// Which generation this client is: the names it sends say so.
-const generation = body.tools.some((t) => (t.function ?? t).name === "shell") ? "2.x" : "1.x";
 const required = generation === "2.x" ? ["shell", "read"] : ["bash", "glob", "grep", "read"];
 const absent = required.filter((name) => !tools[name]);
 if (absent.length) {
@@ -146,6 +166,14 @@ if (absent.length) {
 
 // Which protocol was captured, since each of 1.x's protocols bundles its own
 // provider-utils and a capture must not overwrite the ones it did not observe.
+// Anthropic is not one this can read: its tools carry `input_schema` where the
+// other two carry `parameters`, so read as the chat one it would write every
+// tool without its parameters and take the chat slot's provider-utils from an
+// anthropic client. Refused rather than written.
+if ((body.tools ?? []).some((raw) => (raw.function ?? raw)?.input_schema !== undefined)) {
+  console.error("the captured request is in the anthropic shape, which this script cannot read; nothing written");
+  process.exit(1);
+}
 const protocol = body.input !== undefined && body.messages === undefined ? "responses" : "chat";
 
 console.log(`\nagent:  ${request.agent}`);

package/index.mjs

@@ -1,3 +1,11 @@
 import plugin from "./provider.mjs"
 
+// Only the `server` factory is forwarded: that is the hook a magpie host builds
+// a plugin from, so the provider's `id` is deliberately not repeated here. Say
+// so where the mismatch is, rather than handing the host an undefined plugin to
+// fail with something opaque later.
+if (typeof plugin?.server !== "function") {
+  throw new TypeError("provider.mjs must default-export a plugin with a `server` factory")
+}
+
 export const ZenFreePlugin = plugin.server

package/limits-audit.mjs

@@ -35,9 +35,10 @@
 // Exit code is 0 when at least one offered id answered, 1 when none did: being
 // unable to ask is not a finding about limits.
 
+import { fileURLToPath } from "node:url";
 import { PROFILES } from "./core-tools.mjs";
 import { LIMITS, limitOverrides, namedContextWindow, namedOutputCap } from "./limits.mjs";
-import { SDK, bootstrapProtocols } from "./models.mjs";
+import { SDK, bootstrapProtocols, isFree } from "./models.mjs";
 import { CATALOG, DEFAULT_BASE } from "./provider.mjs";
 import { chatRequest } from "./tools-smoke.mjs";
 
@@ -46,6 +47,10 @@ const CATALOG_URL = process.env.ZEN_CATALOG_URL ?? CATALOG;
 const GENERATION = process.env.ZEN_GENERATION ?? "1.x";
 const READ_BUDGET = 4096;
 const ASKED_CEILING = 1_000_000;
+// How many ids are asked at once. Each ask stops as soon as the answer starts,
+// so the connection and the upstream load stay modest while the 45 s abort of
+// one id no longer holds up every id behind it.
+const POOL = 4;
 
 // The ids the plugin would offer: the listing's, kept where the catalogue calls
 // them free — or, for an id neither the catalogue nor the docs describe, where
@@ -53,14 +58,15 @@ const ASKED_CEILING = 1_000_000;
 // models.mjs offers on its own say-so. An id the snapshot already calls
 // something this plugin has no SDK for is not offered by anyone: `jev-1.13-free`
 // is SystemOne, and stays out here for the same reason buildModels leaves it out.
-// Exported for the tests.
+// "Free" is models.mjs's own answer, retirement included, so the audited set and
+// the offered set cannot drift apart. Exported for the tests.
 export function offeredIds(listing, catalog, snapshot = bootstrapProtocols) {
   return listing.filter((id) => {
     const protocol = snapshot?.[id];
     if (protocol !== undefined && !Object.hasOwn(SDK, protocol)) return false;
     const model = catalog?.[id];
     if (!model) return /-free$/.test(id);
-    return /free/i.test(id) || (model.cost?.input === 0 && model.cost?.output === 0);
+    return isFree(id, model);
   });
 }
 
@@ -100,8 +106,11 @@ export function findings(rows, covered = new Set()) {
     // finding and must not sit in this list for ever: it is said once, beside the
     // ids that were not asked at all.
     if (protocolScoped(row)) continue;
-    if (row.status !== 200 && !named) {
-      // What is left is worth reading: a 410, and a 400 that named nothing.
+    if (row.status !== 200 && row.status !== 0 && !named) {
+      // What is left is worth reading: a 410, and a 400 that named nothing. A 0
+      // is a question that was never answered — timeout, DNS, a closed socket —
+      // and the audit's own rule is that being unable to ask is not a finding
+      // about limits, so the id, its status and its message stay in the table.
       out.push(`${row.id}: HTTP ${row.status}${row.says ? ` — ${row.says}` : ""}`);
     }
   }
@@ -136,9 +145,15 @@ function says(text) {
 
 // A refusal that names the protocol rather than a limit. This audit asks the
 // chat shape, so a model that speaks Responses or Messages answers by saying so;
-// that is the host's business, not a limit to measure.
+// that is the host's business, not a limit to measure. The wording has to name
+// another shape or say it cannot be spoken at all: `format` alone is how an
+// ordinary `invalid request format` is worded, which is a question that was
+// asked and refused and belongs in the candidate list, not beside the ids that
+// were never asked.
+const OTHER_SHAPE = /protocol|\b(?:responses|messages)\b|anthropic/i;
+
 export function protocolScoped(row) {
-  return /protocol|format/i.test(row?.says ?? "");
+  return OTHER_SHAPE.test(row?.says ?? "");
 }
 
 async function getJSON(url) {
@@ -183,12 +198,17 @@ async function ask(id, names) {
     }
     const upstream = response.headers.get("x-opencode-upstream-model-id") ?? undefined;
     const endpoint = response.headers.get("x-opencode-endpoint-id") ?? undefined;
+    // limits.mjs reads refusals, and a refusal is the only place this route
+    // states a limit. The body of a 200 is the model's own prose, which an
+    // answer about token limits — or one that merely mentions them — would turn
+    // into a ceiling nobody stated, and a `named` row then skips its status line
+    // in findings() as well.
     return {
       status: response.status,
       upstream,
       endpoint,
-      window: namedContextWindow(text),
-      ceiling: namedOutputCap(text),
+      window: response.ok ? undefined : namedContextWindow(text),
+      ceiling: response.ok ? undefined : namedOutputCap(text),
       says: response.ok ? "" : says(text),
     };
   } catch (error) {
@@ -199,9 +219,54 @@ async function ask(id, names) {
   }
 }
 
+// Whether this module is the file that was run rather than one the tests
+// import. `import.meta.main` is the direct answer and the one Bun gives, but it
+// arrived in Node 22.18 and nothing before that has it — and an audit that cannot
+// tell whether it was run is an audit that reports success without asking.
+function invokedDirectly() {
+  // `typeof` rather than `??`: a runtime without the property throws on the
+  // member access itself, where there is nothing to fall back from.
+  if (typeof import.meta.main === "boolean") return import.meta.main;
+  try {
+    return process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1];
+  } catch {
+    return undefined;
+  }
+}
+
 // Only a run asks the route. The tests import the helpers above and must not
 // reach the network.
-if (import.meta.main) {
+const entry = invokedDirectly();
+if (entry === undefined) {
+  console.error(
+    "Could not tell whether this file was run or imported, so nothing was asked: neither import.meta.main nor process.argv[1] named an entry point. Run it with `bun run limits:audit`.",
+  );
+  process.exit(1);
+}
+
+if (entry) {
+  // A generation nobody captured is a typo or a Zen that has moved on, and is
+  // worth saying in one line rather than throwing a TypeError out of the first
+  // line of the run.
+  if (!Object.hasOwn(PROFILES, GENERATION)) {
+    console.error(
+      `limits audit — ZEN_GENERATION "${GENERATION}" is not a captured generation (${Object.keys(PROFILES).join(", ")})`,
+    );
+    process.exitCode = 1;
+  } else {
+    try {
+      await run();
+    } catch (error) {
+      // Being unable to ask is not a finding about limits, so it is a sentence
+      // and an exit code rather than a stack trace about a fetch that failed.
+      console.error(`\nlimits audit — unable to ask: ${error?.message ?? error}`);
+      console.error("The route or the catalogue could not be read. Check the network and ZEN_BASE_URL, then ask again.");
+      process.exitCode = 1;
+    }
+  }
+}
+
+async function run() {
   const names = [...PROFILES[GENERATION].required];
   const [listing, catalog] = await Promise.all([getJSON(`${BASE}/models`), getJSON(CATALOG_URL)]);
   const models = catalog?.opencode?.models ?? {};
@@ -221,13 +286,24 @@ if (import.meta.main) {
   // finding it cannot be.
   const asked = ids.filter((id) => (bootstrapProtocols[id] ?? "chat") === "chat");
   const elsewhere = ids.filter((id) => !asked.includes(id));
-  for (const id of asked) {
-    const answer = await ask(id, names);
-    const declared = models[id]?.limit ?? {};
-    rows.push({ id, declared, ...answer });
-    // What the plugin declares is the catalogue's limit with limits.mjs over it,
-    // so that is what is printed; the catalogue's own pair is shown beside it
-    // when the two differ, since that is the under-report being answered.
+  // The asks are independent, and each one can sit until its 45 s abort, so a
+  // few run together: 4 at a time overlaps the waiting without opening a
+  // connection per id. Answers are gathered first and printed in `asked` order,
+  // which is the order the listing gave.
+  for (let at = 0; at < asked.length; at += POOL) {
+    const batch = await Promise.all(
+      asked.slice(at, at + POOL).map(async (id) => {
+        const answer = await ask(id, names);
+        return { id, declared: models[id]?.limit ?? {}, ...answer };
+      }),
+    );
+    rows.push(...batch);
+  }
+
+  // What the plugin declares is the catalogue's limit with limits.mjs over it,
+  // so that is what is printed; the catalogue's own pair is shown beside it when
+  // the two differ, since that is the under-report being answered.
+  for (const { id, declared, ...answer } of rows) {
     const effective = { ...declared, ...limitOverrides(id, declared) };
     const moved = effective.context !== declared.context || effective.output !== declared.output;
     const pair = (limit) => `${limit.context ?? "—"}/${limit.output ?? "—"}`;
@@ -255,7 +331,9 @@ if (import.meta.main) {
 
   if (!answered.length) {
     console.log(
-      "\nNothing answered, so this says nothing about limits. Check the network or ZEN_BASE_URL and ask again.",
+      asked.length
+        ? "\nNothing answered, so this says nothing about limits. Check the network or ZEN_BASE_URL and ask again."
+        : "\nNo offered id speaks the chat shape, so nothing was asked and this says nothing about limits.",
     );
     process.exitCode = 1;
   }

package/limits.mjs

@@ -158,17 +158,24 @@ function namedNumber(pattern, text) {
 // responses are read, and only the first `limit` characters of one: this is an
 // error path on the request's way to a caller that is waiting, so it must never
 // be able to fail a request, change a response, or buffer a body that is not
-// small. Returns undefined when the body names nothing attributable, otherwise
-// whichever axes it named.
+// small. A number the read cut in half names nothing either, since half of one
+// is a smaller limit that looks like a whole one. Returns undefined when the
+// body names nothing attributable, otherwise whichever axes it named.
 export async function observeRouteStatement(id, response, limit = 4096) {
   try {
     if (typeof id !== "string" || !id || response?.ok !== false) return undefined;
-    const text = await response
-      .clone()
-      .text()
-      .catch(() => "");
-    const context = namedContextWindow(text.slice(0, limit));
-    const output = namedOutputCap(text.slice(0, limit));
+    const text = await readPrefix(response, limit);
+    // `readPrefix` stops at `limit`, so the last character read may be the first
+    // half of a longer number. Both words this reads are numbers inside prose —
+    // the window's ends in the literal "tokens", but the second ceiling wording
+    // ends with the digits it captured, so `/max_tokens: 1000000 is not less or
+    // equal to 2621` carved out of 262144 reads as a ceiling Zen stated. Live
+    // values are taken as they stand, past the staleness check and the guard
+    // below, so that half a number would become the applied max_tokens. A match
+    // that runs up to the cut is therefore not evidence, on either axis: asking
+    // again over one character less only finds the same number one digit
+    // shorter, and reading the rest of the body is what this path must not do.
+    const { context, output } = namedAxes(text, limit, text.length > limit);
     if (context === undefined && output === undefined) return undefined;
     if (context !== undefined) OBSERVED.set(id, context);
     if (output !== undefined) OBSERVED_OUTPUT.set(id, output);
@@ -178,6 +185,42 @@ export async function observeRouteStatement(id, response, limit = 4096) {
   }
 }
 
+// Read at most `limit` characters of a refusal without buffering the rest: this
+// is an error path on a request whose caller is waiting, so a body that is not
+// small is dropped as soon as the part that is read is in hand.
+async function readPrefix(response, limit) {
+  const body = response.clone().body;
+  if (typeof body?.getReader !== "function") return response.clone().text().catch(() => "");
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let text = "";
+  try {
+    while (text.length < limit) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      text += decoder.decode(value, { stream: true });
+    }
+  } catch {
+    // A body that fails halfway is still worth what was read of it.
+  }
+  await reader.cancel().catch(() => {});
+  return text;
+}
+
+// The axes the first `limit` characters of `text` name. `cut` says the body went
+// on past that point, so a match ending on the last character read may have been
+// a longer number: that axis is left unread rather than reported a digit short.
+function namedAxes(text, limit, cut) {
+  const head = text.slice(0, limit);
+  const contextMatch = NAMED_CONTEXT.exec(head);
+  const outputMatch = NAMED_OUTPUT.map((pattern) => pattern.exec(head)).find(Boolean);
+  const onCut = (match) => cut && Boolean(match) && match.index + match[0].length >= limit;
+  return {
+    context: onCut(contextMatch) ? undefined : namedContextWindow(head),
+    output: onCut(outputMatch) ? undefined : namedOutputCap(head),
+  };
+}
+
 const ROUTE_TIERS = new Set(["route", "route-twin"]);
 
 // What this plugin declares for a model instead of what the catalogue says, as
@@ -199,12 +242,26 @@ export function limitOverrides(
     const live = (axis === "context" ? observed : observedOutput)?.get(id);
     // A route statement made while this process was running is the same tier as
     // the table and newer than it, so it is taken as it stands. Everything else
-    // has to have been measured against the catalogue in front of us now.
-    const value =
-      live !== undefined ? live : entry && entry.declaredAt === declaredValue ? entry.value : undefined;
+    // has to have been measured against the catalogue in front of us now: the
+    // value it was measured against has to exist and still be the declaration,
+    // and one that names no such value was measured against nothing.
+    let value;
+    if (live !== undefined) {
+      value = live;
+    } else if (entry && declaredValue !== undefined && entry.declaredAt === declaredValue) {
+      value = entry.value;
+    }
     if (value === undefined || !Number.isSafeInteger(value) || value <= 0) continue;
     if (value === declaredValue) continue;
-    if (entry && !ROUTE_TIERS.has(entry.source) && Number.isSafeInteger(declaredValue) && value < declaredValue)
+    // Weaker evidence may only raise, and that holds for the table alone: a live
+    // refusal is the route itself and is taken as it stands, entry or no entry.
+    if (
+      live === undefined &&
+      entry &&
+      !ROUTE_TIERS.has(entry.source) &&
+      Number.isSafeInteger(declaredValue) &&
+      value < declaredValue
+    )
       continue;
     overrides[axis] = value;
   }

package/models.mjs

@@ -7,17 +7,21 @@ export const SDK = {
   anthropic: "@ai-sdk/anthropic",
 };
 
+// The endpoint each table row names, as this file's names for them. A row that
+// names one outside this set is not a protocol this plugin can ask.
+const PROTOCOLS = {
+  "chat/completions": "chat",
+  responses: "responses",
+  messages: "anthropic",
+  systemone: "systemone",
+};
+
 export function parseProtocolDocs(text) {
   const protocols = {};
   const pattern =
     /\|[^|]+\|\s*`?([^|`\s]+)`?\s*\|\s*`[^`]+\/v1\/(chat\/completions|responses|messages|systemone)`/g;
   for (const match of text.matchAll(pattern)) {
-    protocols[match[1]] = {
-      "chat/completions": "chat",
-      responses: "responses",
-      messages: "anthropic",
-      systemone: "systemone",
-    }[match[2]];
+    protocols[match[1]] = PROTOCOLS[match[2]];
   }
   return protocols;
 }
@@ -28,18 +32,22 @@ function sdkProtocol(npm) {
   if (npm?.includes("openai-compatible")) return "chat";
 }
 
+// Set, and not merely present: the catalogue writes both a missing date and an
+// explicit null, and neither retires a model.
+const hasValue = (value) => value !== null && value !== undefined;
+
 function isRetired(model) {
   return (
     model.deprecated === true ||
     ["deprecated", "retired", "disabled"].includes(model.status ?? model.lifecycle) ||
-    model.deprecated_at != null ||
-    model.retirement_date != null
+    hasValue(model.deprecated_at) ||
+    hasValue(model.retirement_date)
   );
 }
 
 export function isFree(id, model = {}) {
   return (
-    !isRetired(model) && (/free/i.test(id) || (model.cost?.input === 0 && model.cost?.output === 0))
+    !isRetired(model) && (/-free$/i.test(id) || (model.cost?.input === 0 && model.cost?.output === 0))
   );
 }
 
@@ -55,26 +63,39 @@ function listedFree(id) {
   return /-free$/.test(id);
 }
 
+// Which protocol a model is asked at, in the order the answer is trusted: the
+// console docs' own endpoint first, then the package the catalogue gives the
+// model (or its provider), and last the provider's own protocol for an id that
+// names itself free and neither of those describes. Nothing here is a guess at
+// an endpoint — the fallback is openai-compatible, which is what the provider
+// speaks. A protocol outside `SDK` leaves the model out below rather than
+// sending it somewhere it is not served: `systemone` and a model the catalogue
+// drops do not appear.
+function protocolFor(id, model, raw, provider, protocols) {
+  if (protocols[id]) return protocols[id];
+  if (raw) return sdkProtocol(model.provider?.npm ?? provider.npm);
+  if (listedFree(id)) return sdkProtocol(provider.npm) ?? "chat";
+  return undefined;
+}
+
+const modalities = (values) =>
+  Object.fromEntries(
+    ["text", "image", "audio", "video", "pdf"].map((name) => [
+      name,
+      Array.isArray(values) && values.includes(name),
+    ]),
+  );
+
 export function buildModels(ids, provider, protocols, baseURL) {
   const result = {};
   for (const id of ids) {
     if (typeof id !== "string" || !id || id === "__proto__") continue;
     const raw = provider.models?.[id];
     const model = raw ?? {};
-    const protocol =
-      protocols[id] ??
-      (raw
-        ? sdkProtocol(model.provider?.npm ?? provider.npm)
-        : listedFree(id)
-          ? (sdkProtocol(provider.npm) ?? "chat")
-          : undefined);
+    const protocol = protocolFor(id, model, raw, provider, protocols);
     if (!isFree(id, model) || !Object.hasOwn(SDK, protocol)) continue;
     const input = model.modalities?.input ?? ["text"];
     const output = model.modalities?.output ?? ["text"];
-    const modalities = (values) =>
-      Object.fromEntries(
-        ["text", "image", "audio", "video", "pdf"].map((name) => [name, values.includes(name)]),
-      );
     const efforts = (model.reasoning_options ?? [])
       .filter((option) => option.type === "effort")
       .flatMap((option) => option.values ?? []);

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "opencode-zen-freex",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "OpenCode Zen's free models, for hosts that are not OpenCode: the public credential, automatic discovery and native streaming protocols",
   "type": "module",
   "main": "./index.mjs",
+  "exports": { ".": "./index.mjs", "./*": "./*" },
   "files": [
     "index.mjs",
     "provider.mjs",

package/provider.mjs

@@ -140,10 +140,6 @@ function normalizeTools(body, protocol) {
   // it carries say which: `shell` is 2.x, `bash` is 1.x. Names move far less
   // often than descriptions do, so this survives a rewording that a pinned
   // User-Agent would not.
-  // Zen takes a request for one generation of OpenCode or the other, and the tools
-  // it carries say which: `shell` is 2.x, `bash` is 1.x. Names move far less
-  // often than descriptions do, so this survives a rewording that a pinned
-  // User-Agent would not.
   const generation = generationOf(body.tools) ?? DEFAULT_GENERATION;
   const profile = PROFILES[generation];
   const filled = [];
@@ -187,21 +183,22 @@ function normalizeTools(body, protocol) {
 // on the other two, and which one a host used is its own business: it is
 // matched by where the name was found, so a tool sent in the other shape still
 // has its wording read and replaced.
-function descriptionAt(tool) {
-  return tool?.function ? tool.function.description : tool?.description;
-}
-
 function setDescription(tool, description) {
   if (tool?.function) tool.function.description = description;
   else if (tool) tool.description = description;
 }
 
-const shapeOf = (definition, protocol) =>
-  protocol === "chat"
-    ? { type: "function", function: definition }
-    : protocol === "anthropic"
-      ? { name: definition.name, description: definition.description, input_schema: definition.parameters }
-      : { type: "function", ...definition };
+function shapeOf(definition, protocol) {
+  if (protocol === "chat") return { type: "function", function: definition };
+  if (protocol === "anthropic") {
+    return {
+      name: definition.name,
+      description: definition.description,
+      input_schema: definition.parameters,
+    };
+  }
+  return { type: "function", ...definition };
+}
 
 // Zen's own wording for a refusal says only that the request did not look like
 // OpenCode's, which sends people off to change headers. Everything the plugin
@@ -321,7 +318,10 @@ async function server(_input, options = {}) {
   );
   let metadata = bootstrapProvider;
   let protocols = { ...bootstrapProtocols };
-  let listed = false;
+  // When the list was last read, or last asked for: 0 until the first ask. A
+  // failed ask sets it too, so a host whose listing can't be read waits out the
+  // same interval as one whose listing can, instead of asking three times with
+  // a 15 s timeout each on every request that names a model it doesn't know.
   let listedAt = 0;
 
   async function discover(signal) {
@@ -346,6 +346,7 @@ async function server(_input, options = {}) {
       partial = true;
     }
     if (listing.status !== "fulfilled" || !Array.isArray(listing.value?.data)) {
+      listedAt = Date.now();
       const fallback = { ...known };
       fallback[Symbol.for("magpie.fellBack")] = true;
       return fallback;
@@ -368,7 +369,6 @@ async function server(_input, options = {}) {
       // list there was.
     }
     known = discovered;
-    listed = true;
     listedAt = Date.now();
     return discovered;
   }
@@ -416,10 +416,7 @@ async function server(_input, options = {}) {
             const body = await request.json();
             if (!body || typeof body !== "object" || Array.isArray(body))
               throw new Error("Expected a JSON request object");
-            if (
-              !Object.hasOwn(known, body.model) &&
-              (!listed || Date.now() - listedAt >= RELIST_AFTER)
-            ) {
+            if (!Object.hasOwn(known, body.model) && Date.now() - listedAt >= RELIST_AFTER) {
               await discover(request.signal);
             }
             const model = Object.hasOwn(known, body.model) ? known[body.model] : undefined;

package/stream.mjs

@@ -1,9 +1,25 @@
 const MAX_BYTES = 32 * 1024 * 1024;
 
+// The headers that describe the bytes a reply arrived as. A reply whose body
+// is written again — a stream collapsed into one JSON document, or a guarded
+// stream whose frames may be rewritten or added to — no longer describes
+// those bytes: a length, an encoding, hop-by-hop framing, and the validators
+// a cache or a conditional request would compare against all describe the
+// old ones only. What says something about the reply itself (a retry-after,
+// a request id) is left alone. One list, so the two places that write a body
+// again cannot drift apart.
+export const STALE_BODY_HEADERS = [
+  "content-length",
+  "content-encoding",
+  "transfer-encoding",
+  "content-md5",
+  "etag",
+  "last-modified",
+];
+
 function jsonResponse(source, protocol, value, error) {
   const headers = new Headers(source.headers);
-  headers.delete("content-length");
-  headers.delete("content-encoding");
+  for (const name of STALE_BODY_HEADERS) headers.delete(name);
   headers.set("content-type", "application/json");
   if (error) {
     const detail = { type: "upstream_error", message: error };
@@ -108,12 +124,15 @@ function responsesAccumulator() {
   let body = { object: "response", output: [] };
   let final;
   const output = new Map();
+  // The slot a frame belongs to: the output_index it carries, or the slot
+  // of the item it names when the upstream left output_index out.
+  function slot(data, id) {
+    if (data.output_index !== undefined) return index(data.output_index);
+    const position = id ? [...output].find(([, value]) => value.id === id)?.[0] : undefined;
+    return index(position);
+  }
   function item(data, type = "message") {
-    let position = data.output_index;
-    if (position === undefined && data.item_id) {
-      position = [...output].find(([, value]) => value.id === data.item_id)?.[0];
-    }
-    position = index(position);
+    const position = slot(data, data.item_id);
     if (!output.has(position)) {
       const value = { type };
       if (data.item_id) value.id = data.item_id;
@@ -133,7 +152,7 @@ function responsesAccumulator() {
             output.set(position, value);
         }
       } else if (type === "response.output_item.added" || type === "response.output_item.done") {
-        if (data.item) output.set(index(data.output_index), data.item);
+        if (data.item) output.set(slot(data, data.item.id), data.item);
       } else if (type === "response.content_part.added" || type === "response.content_part.done") {
         const value = item(data);
         value.content ??= [];
@@ -239,8 +258,14 @@ function anthropicAccumulator() {
     },
     finish() {
       for (const [position, value] of argumentsJSON) {
+        // An upstream may send an empty delta set for a call that takes no
+        // arguments: there are no bytes to parse, and the block's own input
+        // stands. JSON.parse("") would fail a valid call.
+        if (!value.trim()) continue;
+        const block = blocks.get(position);
+        if (!block) throw new Error("Tool input for no content block in upstream stream");
         try {
-          blocks.get(position).input = JSON.parse(value);
+          block.input = JSON.parse(value);
         } catch {
           throw new Error("Invalid tool input JSON in upstream stream");
         }
@@ -370,7 +395,7 @@ export async function collapseResponse(response, protocol) {
         if (done) break;
         bytes += value.byteLength;
         if (bytes > MAX_BYTES) {
-          failure = "Upstream SSE exceeds the 32 MiB buffer limit";
+          failure = `Upstream SSE exceeds the ${MAX_BYTES / (1024 * 1024)} MiB limit`;
           await reader.cancel();
           break;
         }

package/tool-response.mjs

@@ -1,21 +1,33 @@
+import { STALE_BODY_HEADERS } from "./stream.mjs";
+
 const MAX_BYTES = 32 * 1024 * 1024;
+// The limit as a failure's message names it, from the one place it is set.
+const LIMIT = `${MAX_BYTES / (1024 * 1024)} MiB`;
 const encoder = new TextEncoder();
 
-class GuardError extends Error {}
+class GuardError extends Error {
+  constructor(message, code = "upstream_error") {
+    super(message);
+    this.code = code;
+  }
+}
 
 function headersFor(response) {
   const headers = new Headers(response.headers);
-  headers.delete("content-length");
-  headers.delete("content-encoding");
+  for (const name of STALE_BODY_HEADERS) headers.delete(name);
   return headers;
 }
 
-function failure(protocol, message, stream = false) {
+// failure answers the error a client reads. `code` says what went wrong
+// where the shape has room for it: only a call of no tool the agent has is
+// an undeclared one, and a limit, a truncation or a malformed upstream is
+// not.
+function failure(protocol, message, stream = false, code = "upstream_error") {
   if (protocol === "anthropic") return { type: "error", error: { type: "api_error", message } };
   if (protocol === "responses") {
     return stream
-      ? { type: "error", code: "undeclared_tool", message }
-      : { error: { type: "upstream_error", code: "undeclared_tool", message } };
+      ? { type: "error", code, message }
+      : { error: { type: "upstream_error", code, message } };
   }
   return { error: { message, type: "upstream_error" } };
 }
@@ -198,7 +210,7 @@ function checkSnapshots(data, protocol, checkName) {
     if (isCall(protocol, value)) {
       const name = checkName(value.name);
       if (name == null) {
-        if (!holder) throw new GuardError(droppedNote(value.name));
+        if (!holder) throw new GuardError(droppedNote(value.name), "undeclared_tool");
         holder[key] = inPlaceOf(protocol, value, droppedNote(value.name));
         changed = true;
         left++;
@@ -267,7 +279,7 @@ function chatBuffer(checkName) {
     bytes += size;
     state.bytes += size;
     if (bytes > MAX_BYTES)
-      throw new GuardError("Pending upstream tools exceed the 32 MiB buffer limit");
+      throw new GuardError(`Pending upstream tools exceed the ${LIMIT} buffer limit`);
   }
   function stateFor(index, data) {
     if (!pending.has(index)) {
@@ -485,6 +497,35 @@ function snapshotStream(protocol, checkName) {
   };
 }
 
+// A reply that is not a stream is read whole before it is checked, so it is
+// read through the same limit a streamed reply's events are: a body past it
+// is a 502, rather than the whole of it sitting in memory first.
+async function readBounded(response) {
+  const reader = response.body?.getReader();
+  if (!reader) return "";
+  const parts = [];
+  let bytes = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      bytes += value.byteLength;
+      if (bytes > MAX_BYTES)
+        throw new GuardError(`Upstream response exceeds the ${LIMIT} buffer limit`);
+      parts.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const all = new Uint8Array(bytes);
+  let offset = 0;
+  for (const part of parts) {
+    all.set(part, offset);
+    offset += part.length;
+  }
+  return new TextDecoder().decode(all);
+}
+
 function parseJSON(text) {
   let value;
   try {
@@ -519,7 +560,7 @@ async function* framesFrom(reader) {
   function append(value) {
     eventBytes += value.byteLength;
     if (eventBytes > MAX_BYTES)
-      throw new GuardError("Upstream SSE event exceeds the 32 MiB buffer limit");
+      throw new GuardError(`Upstream SSE event exceeds the ${LIMIT} buffer limit`);
     if (value.byteLength) {
       parts.push(value);
       lineBytes += value.byteLength;
@@ -546,7 +587,7 @@ async function* framesFrom(reader) {
         start = 1;
       }
       if (eventBytes > MAX_BYTES)
-        throw new GuardError("Upstream SSE event exceeds the 32 MiB buffer limit");
+        throw new GuardError(`Upstream SSE event exceeds the ${LIMIT} buffer limit`);
       skipLF = false;
       if (pendingFrame) {
         const frame = pendingFrame;
@@ -559,7 +600,7 @@ async function* framesFrom(reader) {
       if (value[offset] !== 10 && value[offset] !== 13) continue;
       append(value.subarray(start, offset));
       if (++eventBytes > MAX_BYTES)
-        throw new GuardError("Upstream SSE event exceeds the 32 MiB buffer limit");
+        throw new GuardError(`Upstream SSE event exceeds the ${LIMIT} buffer limit`);
       const bytes = new Uint8Array(lineBytes);
       let cursor = 0;
       for (const part of parts) {
@@ -584,7 +625,7 @@ async function* framesFrom(reader) {
           rawLine += "\n";
           offset++;
           if (++eventBytes > MAX_BYTES)
-            throw new GuardError("Upstream SSE event exceeds the 32 MiB buffer limit");
+            throw new GuardError(`Upstream SSE event exceeds the ${LIMIT} buffer limit`);
         } else if (offset + 1 === value.length) skipLF = true;
       }
       start = offset + 1;
@@ -826,7 +867,7 @@ function guardedStream(response, protocol, checkName, endCutShort) {
             controller.enqueue(
               encoder.encode(
                 encodeEvent(
-                  failure(protocol, error.message, true),
+                  failure(protocol, error.message, true, error.code),
                   protocol === "chat" ? "" : "error",
                 ),
               ),
@@ -865,16 +906,15 @@ export async function guardToolResponse(response, protocol, policy, options = {}
       headers,
     });
   }
-  const text = await response.text();
   let value;
   let status = response.status;
   try {
-    value = parseJSON(text);
+    value = parseJSON(await readBounded(response));
     checkSnapshots(value, protocol, checkName);
   } catch (error) {
     if (!(error instanceof GuardError)) throw error;
     status = 502;
-    value = failure(protocol, error.message);
+    value = failure(protocol, error.message, false, error.code);
   }
   headers.set("content-type", "application/json");
   return new Response(JSON.stringify(value), { status, headers });

package/tools-smoke.mjs

@@ -34,12 +34,15 @@
 //   answered   Zen served the request; this shape is current
 //   refused    Zen did not recognise this generation (403)
 //   superseded Zen wants a newer OpenCode than the one this profile claims (426)
+//   failed     Zen answered something other than 403: the request was made, and
+//              what came back is not a verdict on the fingerprint
 //   unreachable the free tier could not be asked at all
 //
 // Exit code is 0 when at least one generation's floor is answered. A generation
 // being refused is not a failure while another still works.
 
 import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
 import { PROFILES, agentFor } from "./core-tools.mjs";
 import { outboundHeaders } from "./provider.mjs";
 
@@ -90,7 +93,15 @@ export function chatRequest({ model, generation, profile, names, maxTokens = 40,
     body: {
       model,
       messages: messages ?? [{ role: "user", content: "hi" }],
-      tools: names.map((name) => ({ type: "function", function: profile.tools[name] })),
+      // A name in `required` that the profile does not carry is a broken
+      // fingerprint, not a request to ask Zen with: without this it is sent as
+      // `{"type":"function"}`, Zen refuses it as malformed, and the gate blames
+      // the wording instead of the file it came from.
+      tools: names.map((name) => {
+        const tool = profile.tools[name];
+        if (!tool) throw new Error(`${generation} has no tool named "${name}" in fingerprint.json`);
+        return { type: "function", function: tool };
+      }),
       stream: true,
       stream_options: { include_usage: true },
       max_tokens: maxTokens,
@@ -117,20 +128,55 @@ async function check(generation, profile, shape, names) {
         verdict: "superseded",
         detail: "Zen wants a newer OpenCode than this profile claims",
       };
-    return { generation, shape, verdict: "refused", detail: `HTTP ${response.status}${says(text)}` };
+    // Only a 403 is the answer this gate reads: Zen quoting the fingerprint
+    // back. A 5xx, a 429 or a 401 says something about the service or the way
+    // it was asked, and reading any of them as "the fingerprint is stale" sends
+    // the reader to `capture` over a problem capturing cannot fix.
+    if (response.status === 403)
+      return { generation, shape, verdict: "refused", detail: `HTTP 403${says(text)}` };
+    return { generation, shape, verdict: "failed", detail: `HTTP ${response.status}${says(text)}` };
   } catch (error) {
     return { generation, shape, verdict: "unreachable", detail: error.message };
   }
 }
 
+// Whether this module is the file that was run rather than one the tests
+// import. `import.meta.main` is the direct answer and the one Bun gives, but it
+// arrived in Node 22.18 and nothing before that has it — and a gate that cannot
+// tell whether it was run is a gate that reports success without asking.
+function invokedDirectly() {
+  // `typeof` rather than `??`: a runtime without the property throws on the
+  // member access itself, where there is nothing to fall back from.
+  if (typeof import.meta.main === "boolean") return import.meta.main;
+  try {
+    return process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1];
+  } catch {
+    return undefined;
+  }
+}
+
 // Only a run asks Zen. index.test.mjs imports this module to hold its request
 // against the plugin's, and an import must not reach the network.
-if (import.meta.main) {
-  const results = [];
-  for (const [generation, profile] of Object.entries(PROFILES)) {
-    results.push(await check(generation, profile, "floor", [...profile.required]));
-    results.push(await check(generation, profile, "full", Object.keys(profile.tools)));
-  }
+const entry = invokedDirectly();
+if (entry === undefined) {
+  console.error(
+    "Could not tell whether this file was run or imported, so nothing was asked: neither import.meta.main nor process.argv[1] named an entry point. Run it with `bun run check:gate`.",
+  );
+  process.exit(1);
+}
+
+if (entry) {
+  // Each request is independent and every result is printed in order, so the
+  // two shapes of every profile are asked at once rather than one abort's
+  // worth of waiting after another.
+  const results = (
+    await Promise.all(
+      Object.entries(PROFILES).map(async ([generation, profile]) => [
+        await check(generation, profile, "floor", [...profile.required]),
+        await check(generation, profile, "full", Object.keys(profile.tools)),
+      ]),
+    )
+  ).flat();
 
   const width = Math.max(...results.map((result) => result.generation.length));
   for (const result of results)
@@ -159,13 +205,26 @@ if (import.meta.main) {
   if (!served.length) {
     // Being unable to ask is not an answer. Saying the fingerprint has gone stale
     // when nothing was reached sends the reader to `capture` over a dead network.
-    if (results.every((result) => result.verdict === "unreachable")) {
+    // Only 403 and 426 are Zen answering about the fingerprint at all: a 5xx or a
+    // 429 was answered by something that never judged it, and counting those as a
+    // verdict would blame the wording for an outage.
+    const answered = (result) => ["refused", "superseded"].includes(result.verdict);
+    const unreached = results.filter((result) => result.verdict === "unreachable");
+    if (results.every(answered)) {
       console.log(
-        "The free tier could not be reached at all, so this says nothing about the fingerprint. Check the network or ZEN_BASE_URL and ask again.",
+        "None of them. Zen has moved past every generation this plugin knows; the tool wording in core-tools.mjs needs capturing again from a current OpenCode.",
+      );
+    } else if (results.some(answered)) {
+      console.log(
+        "Some of this run was answered about the fingerprint and some of it was not, which is not a fact about the fingerprint either way. Check the network or ZEN_BASE_URL and ask again.",
+      );
+    } else if (!unreached.length) {
+      console.log(
+        "Zen answered every request, but none of them with a verdict on the fingerprint, so this says nothing about it. Check the service or ZEN_BASE_URL and ask again.",
       );
     } else {
       console.log(
-        "None of them. Zen has moved past every generation this plugin knows; the tool wording in core-tools.mjs needs capturing again from a current OpenCode.",
+        "The free tier could not be reached at all, so this says nothing about the fingerprint. Check the network or ZEN_BASE_URL and ask again.",
       );
     }
     process.exitCode = 1;