opencode-zen-freex 0.2.8 → 0.2.9

package/LICENSE

@@ -1,14 +1,7 @@
 MIT License
 
 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:
-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.
+Copyright (c) 2026 OpenCode-Zen-FreeX contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -26,4 +19,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/MAINTAINING.md

@@ -156,13 +156,21 @@ It reports each request as:
 | `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 |
+| `malformed` | the request could not be built: a name in `required` has no tool behind it in `fingerprint.json`. Zen was never asked, and the line names the generation, the shape and the name |
 | `unreachable` | Zen could not be asked at all |
 
+A `malformed` row is a `fingerprint.json` problem, not a network one, and the
+summary says so rather than sending the reader to `capture`. It is deliberately
+not counted as `answered`: a run whose floors are all `malformed` exits non-zero.
+
 The `floor` decides the exit code, because it is the shape this plugin exists to
 send. The `full` is reported for what it says about a wording that has gone
 stale. Asking only the full shape left a real gap: `read` alone is `answered` and
 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.
+name would keep `full` passing while the shape actually sent was refused. The
+diagnosis at the end reads the floor rows only: a stray 5xx on a `full` request
+says something about that request and nothing about whether the wording is
+current, so it must not turn "nothing was served" into "check the network".
 
 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
@@ -195,6 +203,13 @@ name is served either way, which is why only the `floor` shows this.
 "your client is too old", which is a different problem from 403 and is not fixed
 by changing tools.
 
+**`malformed`.** `fingerprint.json` names a tool in `required` that the same
+profile does not carry under `tools`, so the gate could not build the request it
+wants to ask with. This is not a network problem and not something Zen said: the
+line names the generation, the shape and the missing name. Fix the file — a
+capture from a current OpenCode is the usual way — and ask again. The run exits
+non-zero, and the summary says the same thing in one sentence.
+
 **`unreachable`.** Not a fingerprint problem. Check the network, and whether
 repeated refusals from this address have put it in a cooldown — they can, and
 the cooldown answers like a refusal.
@@ -261,9 +276,18 @@ that passes under the stricter of them, since the looser one will not last.
 | `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 |
+| `limits-audit.mjs` | asks the route which ids it still offers and which look under-declared (`limits:audit`) |
 | `capture.mjs` | takes a new capture |
 | `tools-smoke.mjs` | asks Zen what it accepts (`check:gate`) |
 
+`capture.mjs`, `limits-audit.mjs` and `tools-smoke.mjs` are maintenance tools for
+this repository, not part of what a host loads: they are not in `package.json`'s
+`files`, so a published tarball carries only the modules a host imports plus
+`fingerprint.json`. `package.json`'s `exports` names those public modules one by
+one rather than mapping `./*`, so a file that was never meant to be imported
+cannot be reached as a subpath — `capture.mjs` in particular starts a server and
+rewrites `fingerprint.json` the moment it is imported.
+
 ## Which copy of the icon and the concurrency is authoritative
 
 `icon` and `maxConcurrency` are declared twice, and neither copy can be read by
@@ -288,8 +312,18 @@ 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.
+it: the gate falls back to comparing the entry path. That comparison resolves
+both paths and then their real paths, so a symlink or a junction naming this file
+is still recognised as this file, and a hard link is compared by device and inode
+(only where the filesystem reports an inode at all). A question it cannot answer
+exits non-zero saying nothing was asked — never a silent success, which is the
+one outcome a release gate must not have.
+
+Both scripts read their endpoint and model from the environment when the
+defaults are wrong: `ZEN_BASE_URL`, `ZEN_CHECK_MODEL` (gate), `ZEN_CATALOG_URL`,
+`ZEN_GENERATION` (audit) and `CAPTURE_PORT` (capture). `.env.example` lists them
+with their defaults. Nothing loads a file by itself, so export them or copy that
+file to `.env` and export from it.
 
 ## Publishing
 
@@ -305,6 +339,13 @@ 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.
 
+What ships is `package.json`'s `files` list, and it is deliberately narrower than
+the repository: the three maintenance scripts (`capture.mjs`, `tools-smoke.mjs`,
+`limits-audit.mjs`) stay here, because a host never loads them and one of them
+rewrites the shipped `fingerprint.json` if it is ever imported. `LICENSE` is
+verbatim MIT; the fork's provenance is in `NOTICE`, so a licence scanner reads a
+standard MIT file and a reader still finds why this fork exists.
+
 **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:

package/NOTICE

@@ -0,0 +1,18 @@
+# NOTICE
+
+This package is a maintained fork of the OpenCode Zen Free plugin from
+[magpie-community/plugins](https://github.com/magpie-community/plugins), which
+is MIT licensed. Upstream's notice, `Copyright (c) 2026 xiaozhou26`, is kept in
+[LICENSE](./LICENSE) alongside this fork's own.
+
+The fork is maintained separately from upstream under the name
+`opencode-zen-freex` (https://github.com/tkhs101/OpenCode-Zen-FreeX) because the
+free tier's request fingerprint moves faster than that repository follows it:
+the tool wording and User-Agent Zen accepts can be recaptured here with
+`bun run capture`, without waiting for a release upstream. `MAINTAINING.md`
+describes that loop.
+
+The provider id this package registers, `opencode-zen-free`, is deliberately the
+same one upstream's plugin registers — a model is written
+`opencode-zen-free/<model>` either way — so the two are mutually exclusive;
+install one.

package/README.md

@@ -66,7 +66,9 @@ bun run check:gate
 | `floor` | `required` 里的名字 | 宿主一个都没有时，插件替它补上的那几个。**这才是插件真实发出的形状，退出码由它决定** |
 | `full` | 这一代携带的全部工具 | 宿主本来就是 OpenCode 时发出来的形状。用来看措辞有没有过期，不决定退出码 |
 
-每一代的结论是 `answered`（正常应答）、`refused`（被拒，403）、`superseded`（426——Zen 要求的 OpenCode 比这份指纹声称的更新）或 `unreachable`（根本联系不上）。只要还有一代的 `floor` 被应答，退出码就是 0。某个 `floor` 被拒、而它自己的 `full` 被应答时会单独点出来：那意味着带着自己那套 OpenCode 工具来的宿主能用，而插件真正要服务的那种宿主会被拒。全部联系不上时它不会说指纹过期，只会说问不到——这两件事得分开。
+每一代的结论是 `answered`（正常应答）、`refused`（被拒，403）、`superseded`（426——Zen 要求的 OpenCode 比这份指纹声称的更新）、`failed`（Zen 答了，但不是 403，所以它没有对指纹表态）、`malformed`（请求根本没法构造：`required` 里的某个名字在 `fingerprint.json` 里没有对应的工具。Zen 没被问到，那一行会点名是哪一代、哪种形状、缺的是哪个名字）或 `unreachable`（根本联系不上）。只要还有一代的 `floor` 被应答，退出码就是 0；`malformed` 不算应答，所以整轮都是它的时候退出码非 0，并且会说明这是指纹文件的问题、不是网络的问题。
+
+某个 `floor` 被拒、而它自己的 `full` 被应答时会单独点出来：那意味着带着自己那套 OpenCode 工具来的宿主能用，而插件真正要服务的那种宿主会被拒。全部联系不上时它不会说指纹过期，只会说问不到——这两件事得分开，而且最后的判断只读 `floor` 那几行：某个 `full` 请求拿到 5xx 说明的是那次请求，不足以把「没有一代被服务」说成「去查网络」。
 
 闸门问的时候用的就是插件自己那份请求：请求头的名字来自 `provider.mjs` 里的 `outboundHeaders`，工具来自插件所顶替的同一份 `required`。所以它绿了是在说「插件真发的那个请求」被应答了，而不是在说「照抄的一份」被应答了——照抄的那一份曾经少发一个 `accept`，而且没有任何东西因此报错。
 
@@ -105,7 +107,7 @@ Zen 的免费层读请求体，也读请求头，只有当整个请求都属于
 | `x-opencode-client` | `cli` |
 | `authorization` | `Bearer public`；走 Messages 时是 `x-api-key: public` |
 
-`anthropic-version` 和 `anthropic-beta` 也会发出去，但只在走 Messages 时，而且只在宿主自己设了它们的时候。
+`anthropic-version` 在走 Messages 时总是发出去（宿主设了就用它的，没设就是 `2023-06-01`）；`anthropic-beta` 只在宿主自己设了的时候才发。
 
 `x-opencode-request`、`x-session-affinity` 和 `x-session-id` 都在 OpenCode 自己的请求头集合里，但没有一个是必需的，所以都不发——不过进来的同名请求头仍然会被读，用来判断这次请求属于哪个会话。这不是「一个个试过不行」得出的结论，2026-10-15 实测（1.x，其余不动）：
 
@@ -119,7 +121,7 @@ Zen 的免费层读请求体，也读请求头，只有当整个请求都属于
 
 两个各自无害的头放在一起会被拒，所以「某个头能不能加」不能靠单个试出来。测试按名字钉住了发出的这组请求头，因为多加一个请求头是弄坏这个插件最容易的方式。
 
-Zen 的免费层会检查 session id 是否是 OpenCode 能生成的那种：时间戳加每毫秒计数器截成十二位十六进制，后面接十四个随机的 base62 字符；session 的那一种还会把低位取反。宿主给的 id 如果本来就是这个形状，就原样传出去；否则按会话的首条消息生成一个并记住，这样同一会话的各轮请求会共用一个 session id。
+Zen 的免费层会检查 session id 是否是 OpenCode 能生成的那种：时间戳加每毫秒计数器截成十二位十六进制，后面接十四个随机的 base62 字符；session 的那一种还会把低位取反。宿主给的 id 如果本来就是这个形状，就原样传出去；否则按会话的首条消息生成一个并记住，这样同一会话的各轮请求会共用一个 session id。宿主既不声明会话、又没有可作依据的用户消息时，这一轮就拿一个自己的 id——没有东西可以据以记住它，所以它不会被并进另一个会话里去。
 
 偶尔 Zen 会在发出 `[DONE]` 之前就结束一个流式的 Chat Completions 回复。如果回复已经说了内容、且其中没有未完成的工具调用，就以普通回答结束，正文里会说明它被截断了；再问一次就会接着往下走。如果是带着未完成的工具调用被截断、或者什么都没说就断了、或者被折叠给一个不支持流式的客户端，请求就会失败，错误信息里写明这个回复的 id 和收到了多少。走 Anthropic Messages 或 Responses 的回复被截断同样会失败：magpie 能把它和完整的回复区分开，并且在该模型支持的情况下继续往下走。
 
@@ -140,4 +142,4 @@ Zen 的免费层会检查 session id 是否是 OpenCode 能生成的那种：时
 
 ## 许可
 
-MIT，分叉自 [zen-free](https://github.com/magpie-community/plugins/tree/main/packages/zen-free)。版权署名见 [LICENSE](https://github.com/tkhs101/OpenCode-Zen-FreeX/blob/main/LICENSE)：`Copyright (c) 2026 xiaozhou26` 是上游原作者，本分支的贡献者另有署名。
+MIT，分叉自 [zen-free](https://github.com/magpie-community/plugins/tree/main/packages/zen-free)。版权署名：`Copyright (c) 2026 xiaozhou26` 是上游原作者，本分支的贡献者另有署名。`LICENSE` 是原样的 MIT 正文，本分支的来源与维护缘由写在 [NOTICE](https://github.com/tkhs101/OpenCode-Zen-FreeX/blob/main/NOTICE)，这样许可证扫描器读到的是一份标准的 MIT 文件，而想知道这个分支为什么存在的人仍然找得到答案。

package/core-tools.mjs

@@ -18,31 +18,109 @@
 // because those belong to the machine the capture ran on.
 
 import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 
-const captured = JSON.parse(readFileSync(new URL("./fingerprint.json", import.meta.url), "utf8"));
+const CAPTURE = new URL("./fingerprint.json", import.meta.url);
 
-export const PROFILES = captured.profiles;
+// Read once, here, because every answer in this module comes out of it. Guarded
+// because the failure this replaces is a bare ENOENT or SyntaxError thrown out of
+// whichever module imported this one, which reads as *that* module being broken
+// and never names the file to fix. One message covers both, since the remedy is
+// the same for either: only a capture writes this file.
+function readProfiles() {
+  let captured;
+  try {
+    captured = JSON.parse(readFileSync(CAPTURE, "utf8"));
+  } catch (error) {
+    throw new Error(
+      `core-tools: could not load the capture at ${fileURLToPath(CAPTURE)}; ` +
+        "missing or invalid JSON — run `bun run capture` to write a new one",
+      { cause: error },
+    );
+  }
+  // An object carrying a non-empty map of profiles, and nothing more specific:
+  // which generations those are is the capture's to say — capture.mjs writes
+  // next.profiles[generation] — so the keys are never named here. A capture that
+  // lost every profile cannot tell one generation from another and fails now
+  // rather than at the first request.
+  const profiles = captured?.profiles;
+  if (
+    typeof profiles !== "object" ||
+    profiles === null ||
+    Array.isArray(profiles) ||
+    !Object.keys(profiles).length
+  ) {
+    throw new Error(
+      `core-tools: the capture at ${fileURLToPath(CAPTURE)} has no profiles; ` +
+        "run `bun run capture` to write a new one",
+    );
+  }
+  return profiles;
+}
+
+export const PROFILES = readProfiles();
 
 /**
  * The generation a request belongs to, told by the tools it carries. Tool names
  * move far less often than descriptions do, so this survives a rewording that a
  * pinned User-Agent would not.
+ *
+ * `undefined` is a normal return: it says neither generation's names were there,
+ * and the callers default it themselves (`provider.mjs` uses `?? DEFAULT_GENERATION`).
+ * A body whose `tools` is not an array is the same answer as an empty one — the
+ * body is client-supplied, so it can carry any shape at all, and "no generation
+ * recognised" is the only honest reading of one that is not a list of tools.
  */
 export function generationOf(tools) {
-  const names = new Set((tools ?? []).map((tool) => tool?.function?.name ?? tool?.name));
+  const names = new Set(
+    (Array.isArray(tools) ? tools : []).map((tool) => tool?.function?.name ?? tool?.name),
+  );
   if (names.has("shell")) return "2.x";
   if (names.has("bash")) return "1.x";
   return undefined;
 }
 
+// The profile a generation was captured into, or an Error naming both what was
+// asked for and what the capture holds. Ownership rather than truthiness: a
+// plain object answers `constructor` and `toString` out of Object.prototype, so
+// `PROFILES[generation]` alone would hand back a function and then fail on its
+// `.agent` with a TypeError that names nothing.
+function profileFor(generation) {
+  if (!Object.hasOwn(PROFILES, generation)) {
+    throw new Error(
+      `core-tools: no profile for generation ${JSON.stringify(generation)}; ` +
+        `the capture holds ${Object.keys(PROFILES).join(", ")}`,
+    );
+  }
+  return PROFILES[generation];
+}
+
 /**
  * The User-Agent that generation of OpenCode sends, for a protocol. Each
  * protocol's ai-sdk package bundles its own provider-utils, so 1.x differs by
  * protocol and 2.x does not.
  */
 export function agentFor(generation, protocol = "chat") {
-  const agent = PROFILES[generation].agent;
-  return agent.providerUtils
-    ? `opencode/${agent.opencode} ai-sdk/provider-utils/${agent.providerUtils[protocol]} ${agent.runtime}`
-    : `opencode/${agent.channel}/${agent.opencode}/${agent.client}`;
+  const agent = profileFor(generation).agent;
+  if (typeof agent !== "object" || agent === null) {
+    throw new Error(
+      `core-tools: the ${JSON.stringify(generation)} profile in the capture has no agent; ` +
+        "run `bun run capture` to write a new one",
+    );
+  }
+  // The release shape carries no provider-utils at all, and is composed the same
+  // way whatever protocol was asked for.
+  if (!agent.providerUtils) return `opencode/${agent.channel}/${agent.opencode}/${agent.client}`;
+  // `?? "undefined"` used to be interpolated here for a protocol the capture has
+  // no provider-utils for, and a prototype member (`toString`) as the version.
+  // Zen reads this header, so a malformed one is rejected upstream with an error
+  // that says nothing about where it came from; name the miss instead.
+  if (!Object.hasOwn(agent.providerUtils, protocol)) {
+    throw new Error(
+      `core-tools: generation ${JSON.stringify(generation)} composes its User-Agent ` +
+        `per protocol, and the capture has no provider-utils for ${JSON.stringify(protocol)}; ` +
+        `it holds ${Object.keys(agent.providerUtils).join(", ")}`,
+    );
+  }
+  return `opencode/${agent.opencode} ai-sdk/provider-utils/${agent.providerUtils[protocol]} ${agent.runtime}`;
 }

package/index.mjs

@@ -1,11 +1,21 @@
 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.
+// A host resolves a plugin module and reads the factory off it. Which shape it
+// reads is the host's business and not this package's to narrow: magpie builds
+// one from `default.server`, which is the shape provider.mjs already exports, so
+// that object is forwarded whole rather than the factory being renamed into a
+// shape nothing else in the package uses. The `id` comes with it, because a
+// loader that keys plugins by id needs the same one the provider registers — and
+// it is the provider's own id, not a second copy of it: it is read from the
+// module, so the two cannot drift.
+//
+// The named export stays for anything that already imported it by name, and
+// `server` is offered as a name too, so `mod.default.server` and `mod.server`
+// both resolve.
 if (typeof plugin?.server !== "function") {
   throw new TypeError("provider.mjs must default-export a plugin with a `server` factory")
 }
 
 export const ZenFreePlugin = plugin.server
+export const server = plugin.server
+export default plugin