opencode-zen-freex 0.2.2 → 0.2.4

package/MAINTAINING.md

@@ -1,6 +1,6 @@
 # Maintaining this plugin
 
-The plugin is one file of logic and one piece of data, and the data is the part
+The plugin is one file of logic and two pieces of data, and the data is the part
 that goes out of date. This is how to look after it.
 
 ## What is actually fragile
@@ -14,6 +14,68 @@ Nothing about a stale copy looks different from a working one. The symptom is a
 `403 FreeTierError` on every request, which reads as "you are not OpenCode" and
 sends people off to change headers.
 
+## Limits Zen under-reports
+
+`models.mjs` declares each model's limits from Zen's catalogue, and for some free
+ids the catalogue is wrong in the one direction nothing complains about: too
+small. `deepseek-v4.1-flash-free` is declared 200000/32000 while
+`deepseek-v4.1-flash` — the paid id serving the same upstream model, which
+`x-opencode-upstream-model-id` confirms — is declared 1000000/384000 in that
+same catalogue.
+
+Both numbers are acted on. The window decides when a conversation is compacted
+and how much of it is ever sent; the output cap is sent as `max_tokens` on every
+request, so a reply is cut at it with a finish reason that reads like the
+model's own decision. A window that is too small is never refused, it is just
+quietly never used, which is why this stayed invisible for so long.
+
+`limits.mjs` holds what was measured, per axis, with the catalogue value it was
+measured against. Each axis carries `samples` and `how`; the short of it:
+
+| axis | value | from |
+| --- | --- | --- |
+| context | 1048576 | the route's own refusal, in its own words |
+| output | 384000 | what this route declares for the same upstream model |
+
+A prompt sized just over the window is refused with
+
+```
+This model's maximum context length is 1048576 tokens. However, you requested
+1422278 tokens (1038278 in the messages, 384000 in the completion).
+```
+
+which is the route stating its own window, and better evidence than any vendor
+page. The output figure is the paid twin's declaration, so the route has already
+published what that model does; a single reply of 306,880 completion tokens
+(`finish_reason: stop`) was watched and is recorded as the witness.
+
+**Re-measuring.** The window: send a prompt of about 1.05M tokens and read the
+number out of the refusal, three times, interleaved, per the rule below. The
+filler measured 4.887 characters per token with about 1700 tokens of fixed
+request overhead, and a request that is *served* says nothing about where the
+wall is. The output: re-read the paid id's `limit` in
+`https://models.opencode.ai/api.json`. A value Zen accepts is not evidence —
+`max_tokens: 2000000` under a short prompt answers 200 and writes nothing like
+it — and neither is a generation nobody watched finish.
+
+**What voids it.** Each axis records the catalogue value it was measured
+against, and an axis whose declaration moved is dropped rather than kept: a
+measurement of one question is not an answer to another. A catalogue that raises
+the free id to the paid twin's figures therefore makes this file inert on its
+own, which is the intended end state.
+
+**While the plugin runs.** A refusal that names a window is read on its way past
+(`observeRouteStatement`, called from the provider's `fetch`), and it corrects
+that model's window for the rest of the process. The list is rebuilt at every
+start and hourly after, so a route that changes the window it enforces is
+followed without anyone editing this file. Nothing is persisted: a restart falls
+back to what is measured here.
+
+**A lead, not evidence.** `mimo-v2.6-flash-free` is declared 200000/32000 here
+too, and another plugin on this route has reported Zen answering that id with
+`maximum context length is 1048576 tokens`. That is somebody else's measurement
+of a different id, so it is not in `limits.mjs`: measure it before adding it.
+
 ## The loop
 
 ```sh
@@ -107,10 +169,11 @@ that passes under the stricter of them, since the looser one will not last.
 
 | file | what it is |
 | --- | --- |
-| `fingerprint.json` | the capture. The only thing that goes out of date |
+| `fingerprint.json` | the capture: the wording and User-Agent Zen accepts |
 | `core-tools.mjs` | reads the capture; says which generation a request is |
 | `provider.mjs` | the plugin: discovery, headers, tools, the diagnostic |
 | `models.mjs` | which models are free, and what protocol each speaks |
+| `limits.mjs` | what a model's limits are, where the catalogue under-reports them |
 | `stream.mjs`, `tool-response.mjs` | replies Zen cuts short, and tool calls |
 | `capture.mjs` | takes a new capture |
 | `tools-smoke.mjs` | asks Zen what it accepts (`check:gate`) |
@@ -124,22 +187,43 @@ either way, so one stays in place whichever is installed. It does mean the two
 are mutually exclusive — installing both leaves two plugins claiming one
 provider id, and which one wins is down to load order. Pick one.
 
-To publish: bump `version`, `npm publish`, and tag. `magpie plugin add
-opencode-zen-freex` installs it by that name.
+To publish: bump `version`, commit, `npm publish` in a terminal, and tag — in
+that order, so the tarball, the commit the tag names, and the tree both were
+built from are one thing. `magpie plugin add opencode-zen-freex` installs it by
+that name.
 
-Publishing is the one step here that cannot be run unattended, because it is
-the one step npm asks a person about. Run it as yourself.
+**The second factor is a browser, not a password.** Run `npm publish` in a
+terminal. When the account has 2FA on, the command stops and offers the whole
+exchange at once:
 
-**With 2FA on the account.** `npm publish` fails with `EOTP` and prints a
-`https://www.npmjs.com/auth/cli/...` address, redacted in the error and
-different every time. Open it, finish, and the same command carries on. There
-is nothing to pass to a script: the address is tied to the browser session that
-prints it.
+```
+Authenticate your account at:
+https://www.npmjs.com/auth/cli/...
+Press ENTER to open in the browser...
+```
 
-**With a granular token.** A token with publish permission authorizes the
-publish on its own and never asks for the second factor. Write it to an npmrc
-outside the repository and point npm at it for that one command, so it does
-not land in a tracked file:
+Press ENTER, authorize in the browser, and the same command carries on by
+itself. Nothing is typed back into the terminal and nothing is passed to a
+script: the address is tied to the browser session that printed it and differs
+every time, so it is read out of the running command rather than composed in
+advance. Whoever is at the browser authorizes, so the command can be started for
+them and left waiting — the one thing it needs from them is the ENTER that opens
+it.
+
+Both halves of that depend on the command having a terminal. Run as a background
+job or piped into a file, npm has no browser to offer, redacts the address to
+`https://www.npmjs.com/auth/cli/***` and exits `EOTP` rather than waiting, so a
+log of the failed attempt cannot be used to finish it — start it again in a
+terminal.
+
+An account with no second factor to give publishes in one step. So does
+`npm login --auth-type=web`, which is the same browser exchange kept as a
+session, and so does a granular token below.
+
+**With a granular token** (unattended, CI). A token with publish permission
+authorizes the publish on its own and never asks for the second factor. Write it
+to an npmrc outside the repository and point npm at it for that one command, so
+it does not land in a tracked file:
 
 ```sh
 printf '//registry.npmjs.org/:_authToken=npm_...\n' > "$TMP/npmrc"

package/README.md

@@ -4,7 +4,7 @@
 
 ## 为什么有这个分支
 
-上游 [zen-free](https://github.com/magpie-community/plugins/tree/main/packages/zen-free) 是这个插件的前身。它一直在修，修得也不慢，但「免费模型还能不能用」这件事在上游那里翻过一次，而往哪边翻不掌握在使用它的人手里：
+上游 [zen-free](https://github.com/magpie-community/plugins/tree/main/packages/zen-free) 是这个插件的前身。它一直在维护，修bug也不慢，但对「给免费模型适配」这件事的态度摇摆不定，时而维护而放弃维护故催生本分支：
 
 | UTC | 提交 | 那一下说了什么 |
 | --- | --- | --- |
@@ -45,6 +45,8 @@ magpie plugin login opencode-zen-free
 
 插件会去发现 Zen 当前的免费模型，包括它们的上下文窗口和思考（reasoning）等级。用 `opencode-zen-free/<模型名>`，例如 `opencode-zen-free/big-pickle`。
 
+免费模型的目录上限有时被 Zen 少报，而少报的那一边没有谁会报错：`deepseek-v4.1-flash-free` 在目录里是 20 万上下文 / 3.2 万输出，而同一上游模型的付费 id 是 100 万 / 38.4 万。上下文窗口太小只会让宿主安静地早点压缩，输出上限太小会把回复截断成看起来像模型自己停下的样子，所以插件对这类模型按实测与路由自述对齐（依据与复测方法见 `MAINTAINING.md` 的 “Limits Zen under-reports”），并在运行中采用上游自报的窗口。
+
 已下线的模型和 SystemOne 模型会被排除。这份列表在宿主每次列举模型时重新获取（magpie 在启动时做一次，之后每小时一次）：Zen 不再免费开放的模型会退出列表，新转为免费的模型会加入列表。如果读不到 Zen 的列表，就沿用上一次的结果；第一次还没读到之前，用的是打包在插件里的那份，所以这个 provider 不会空着。请求一个当前并不免费的模型，会得到一个 404 并列出当时免费的模型；若某个模型是在上次列举之后才转免费的，请求会在重新获取列表后照常服务（最多每分钟一次）。可用性和限流由 Zen 决定，插件这边拿不到剩余额度。
 
 ## 免费层不再应答时

package/limits.mjs

@@ -0,0 +1,123 @@
+// Zen's catalogue is where a model's limits are declared from, and for some
+// free ids it under-reports them. A free id and its paid twin are the same
+// upstream model — x-opencode-upstream-model-id answers
+// "deepseek/deepseek-v4.1-flash" whichever of the two is asked for — and only
+// the paid one is declared at what that model can actually do.
+//
+// A limit the host believes is acted on. The window decides when a
+// conversation is compacted and whether a request is worth sending at all; the
+// output cap is sent as max_tokens on every request. So an under-reported limit
+// is not the conservative choice, it is a wrong one nobody can see: a window
+// that is too small is never refused, it is just quietly never used, and an
+// output cap that is too small cuts replies off with a finish reason that looks
+// like the model's own decision.
+//
+// Only evidence moves a value here, and evidence is sorted:
+//
+//   route       the route's own refusal, in its own words
+//   route-twin  what this route declares for the same upstream model
+//   vendor      the model vendor's published page
+//   witnessed   a generation somebody watched finish
+//
+// Being accepted is not evidence. Zen answers 200 to max_tokens 2000000 under a
+// short prompt, so a value that is accepted says something about the request
+// and nothing about what the model writes. A route or route-twin value may set
+// any number; a vendor or witnessed one may only raise, because lowering a
+// limit on weaker evidence invents a restriction nobody asked for.
+//
+// Every axis carries the catalogue value it was measured against. A catalogue
+// that moves voids that axis rather than leaving a stale number behind, and a
+// refusal that names a different window while the plugin is running corrects it
+// for the rest of the process (see observeRouteStatement).
+export const LIMITS = {
+  "deepseek-v4.1-flash-free": {
+    context: {
+      value: 1048576,
+      source: "route",
+      declaredAt: 200000,
+      measured: "2026-10-15",
+      samples: "1,048,507 tokens served; 1,048,707 and 1,060,000 refused 4/4",
+      how: "a prompt sized just over the window; Zen's own 400 answers \"This model's maximum context length is 1048576 tokens. However, you requested 1422278 tokens (1038278 in the messages, 384000 in the completion).\"",
+    },
+    output: {
+      value: 384000,
+      source: "route-twin",
+      declaredAt: 32000,
+      measured: "2026-10-15",
+      samples: "one reply of 306,880 completion tokens, finish=stop; nothing above it observed",
+      how: "deepseek-v4.1-flash, the paid id serving the same upstream model, is declared 384000 in this same catalogue; DeepSeek's own page says 384K, which is 393216 read as binary K",
+    },
+  },
+};
+
+// "This model's maximum context length is 1048576 tokens. However, you
+// requested 1422278 tokens (1038278 in the messages, 384000 in the
+// completion)." — the route's own words, and the only sentence seen on this
+// route that states a window. A generic 400 says nothing attributable and is
+// left alone; §7 of the measured notes has a context overflow and an invalid
+// parameter answering with byte-identical 400s on another Zen model.
+const NAMED_CONTEXT = /maximum context length is (\d+) tokens/i;
+
+// Windows named by a refusal while this process is running, by model id. Not
+// persisted: it is the same kind of fact as LIMITS, only newer, and a restart
+// falls back to what was measured last.
+const OBSERVED = new Map();
+
+// The window a refusal names, or undefined when the body says nothing
+// attributable. Exported for the tests and for anyone reading a capture.
+export function namedContextWindow(text) {
+  const match = NAMED_CONTEXT.exec(typeof text === "string" ? text : "");
+  if (!match) return undefined;
+  const tokens = Number.parseInt(match[1], 10);
+  return Number.isSafeInteger(tokens) && tokens > 0 ? tokens : undefined;
+}
+
+// Read a refusal for a window it names. Only non-2xx 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.
+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 tokens = namedContextWindow(text.slice(0, limit));
+    if (tokens !== undefined) OBSERVED.set(id, tokens);
+    return tokens;
+  } catch {
+    return undefined;
+  }
+}
+
+const ROUTE_TIERS = new Set(["route", "route-twin"]);
+
+// What this plugin declares for a model instead of what the catalogue says, as
+// a plain object to spread over the catalogue's own limit. Empty when there is
+// no evidence, when the evidence was measured against a different catalogue, or
+// when it would change nothing.
+export function limitOverrides(id, declared = {}, table = LIMITS, observed = OBSERVED) {
+  const overrides = {};
+  const record = table?.[id];
+  const live = observed?.get(id);
+  for (const axis of ["context", "output"]) {
+    const declaredValue = declared?.[axis];
+    const entry = record?.[axis];
+    // 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 =
+      axis === "context" && live !== undefined
+        ? live
+        : entry && entry.declaredAt === declaredValue
+          ? entry.value
+          : undefined;
+    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)
+      continue;
+    overrides[axis] = value;
+  }
+  return overrides;
+}

package/models.mjs

@@ -1,3 +1,5 @@
+import { limitOverrides } from "./limits.mjs";
+
 export const PROVIDER = "opencode-zen-free";
 export const SDK = {
   chat: "@ai-sdk/openai-compatible",
@@ -63,7 +65,7 @@ export function buildModels(ids, provider, protocols, baseURL) {
       providerID: PROVIDER,
       name: model.name ?? id,
       api: { id, url: baseURL, npm: SDK[protocol] },
-      limit: { context: 32768, output: 4096, ...model.limit },
+      limit: { context: 32768, output: 4096, ...model.limit, ...limitOverrides(id, model.limit) },
       capabilities: {
         temperature: model.temperature ?? true,
         reasoning: model.reasoning ?? false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-zen-freex",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "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",
@@ -9,6 +9,7 @@
     "provider.mjs",
     "core-tools.mjs",
     "fingerprint.json",
+    "limits.mjs",
     "models.mjs",
     "stream.mjs",
     "tool-response.mjs",

package/provider.mjs

@@ -9,6 +9,7 @@ import {
   configModels,
   parseProtocolDocs,
 } from "./models.mjs";
+import { observeRouteStatement } from "./limits.mjs";
 import { collapseResponse } from "./stream.mjs";
 import { guardToolResponse } from "./tool-response.mjs";
 
@@ -466,6 +467,11 @@ async function server(_input, options = {}) {
               signal: request.signal,
               redirect: "error",
             });
+            // A refusal is the one place this route states its own window, and
+            // it has to be read before explain() replaces the body. See
+            // limits.mjs: an under-declared window is never refused, it is just
+            // quietly never used.
+            await observeRouteStatement(body.model, response);
             const guarded = await guardToolResponse(await explain(response, toolPolicy), protocol, toolPolicy, {
               endCutShort: streaming,
             });