opencode-zen-freex 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,27 @@
+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 fork is maintained separately because the free tier's request fingerprint
+moves faster than that repository follows it.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+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.

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# OpenCode Zen Free
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+给非 OpenCode 宿主使用的 OpenCode Zen 免费模型。provider id：`opencode-zen-free`。
+
+Zen 的免费层会拒绝一切不像 OpenCode 发出的请求，回答 403 FreeTierError（"can only be used from within OpenCode"）。它不只看请求头，也读请求体：凡是它认得出名字的工具，描述都必须和 OpenCode 自己写的一样。这个插件直接去问真正提供免费层的那个端点，把工具按 OpenCode 的样子呈现出去，同时保留宿主自己的工具，所以模型发出的调用仍然跑得起来。
+
+不需要注册账号，也没有费用。凭据就是 `public` 这一个词。
+
+本项目是 `magpie-community/plugins` 里那个插件的维护分支，同样是 MIT。分叉的理由是那份指纹的变动比那个仓库跟得快：它最后一个版本仍然对着一个早已不提供免费层的端点。两个插件只能装一个——它们注册的是同一个 provider id，都装上的话谁生效取决于加载顺序。维护步骤见 [MAINTAINING.md](MAINTAINING.md)；想确认现在还能不能用，跑 `bun run check:gate`。
+
+## 目录
+
+- [安装](#安装)
+- [登录](#登录)
+- [模型](#模型)
+- [免费层不再应答时](#免费层不再应答时)
+- [请求](#请求)
+- [排查](#排查)
+
+## 安装
+
+```sh
+magpie plugin add opencode-zen-freex
+magpie plugin login opencode-zen-free
+```
+
+## 登录
+
+在密钥一栏填 `public`。不需要个人的 API key。
+
+凭据保存在 OpenCode 的 `auth.json` 或 magpie 的 `plugin-auth.json` 里。
+
+## 模型
+
+插件会去发现 Zen 当前的免费模型，包括它们的上下文窗口和思考（reasoning）等级。用 `opencode-zen-free/<模型名>`，例如 `opencode-zen-free/big-pickle`。
+
+已下线的模型和 SystemOne 模型会被排除。这份列表在宿主每次列举模型时重新获取（magpie 在启动时做一次，之后每小时一次）：Zen 不再免费开放的模型会退出列表，新转为免费的模型会加入列表。如果读不到 Zen 的列表，就沿用上一次的结果；第一次还没读到之前，用的是打包在插件里的那份，所以这个 provider 不会空着。请求一个当前并不免费的模型，会得到一个 404 并列出当时免费的模型；若某个模型是在上次列举之后才转免费的，请求会在重新获取列表后照常服务（最多每分钟一次）。可用性和限流由 Zen 决定，插件这边拿不到剩余额度。
+
+## 免费层不再应答时
+
+过期的指纹和好用的指纹看起来一模一样，直到有人被拒绝。要问 Zen 它还认哪几代 OpenCode：
+
+```sh
+bun run check:gate
+```
+
+每一代的结论是 `answered`（正常应答）、`refused`（被拒，403）、`superseded`（426——Zen 要求的 OpenCode 比这份指纹声称的更新）或 `unreachable`（根本联系不上）。只要还有一代能用，一代被拒就不算失败；只有全部应答时退出码才是 0。发版之前、以及有人报告 403 的时候，都该跑一次。`ZEN_CHECK_MODEL` 可以指定探测用的模型，`ZEN_BASE_URL` 可以指定端点，默认值不合适时就改这两个。
+
+如果每一代都被拒，就从当前版本的 OpenCode 重新采集措辞：把一个 release 指向本地服务器，从它发出的请求里把工具读出来。`bun run capture -- --dry` 取一份新采集并报告差异，`bun run capture` 才真正写入。插件在拒绝时会直接说出发出去的措辞是哪个版本、去哪里找，而不是让人自己猜。
+
+要注意这个闸门并不稳定：摸索它的过程中它一天之内挪动过不止一次，而且同一个地址反复被拒之后，接下来一段时间反而会被应答。这里的结论只能读成"此时此刻"，信之前再跑一遍。
+
+`bun test` 是这个循环的另一半。它从不联网，所以它回答不了指纹是否还有效——它只能说明这个包的行为和以前是否一致。
+
+## 请求
+
+请求发往 `https://opencode.ai/inference/v1`，按每个模型原生的 Chat Completions、Responses 或 Anthropic Messages 接口来走。流式和普通 JSON 两种回复都支持。
+
+宿主自己的工具会被完整保留。Zen 的模型经常去调 OpenCode 的工具名；这种调用会被对上宿主那个只差大小写的工具（`bash` 对 `Bash`），或者只差大小写和 `_`/`-` 的那个（`todowrite` 对 `todo_write`、`webfetch` 对 `web_fetch`），前提是恰好只有一个对得上。找不到对应工具（或者调用根本没有名字）的，不放进回复里，回复的正文会说明哪个名字被略去了；如果这一轮所有调用都被略去，这一轮就以一段普通回答结束。工具仍然在宿主里执行。
+
+Zen 的免费层读请求体，也读请求头，只有当整个请求都属于 OpenCode 的同一代时才作答：User-Agent、请求头和工具三者必须一致。当前一共有两代，请求带的工具说明是哪一代：`shell` 和 `read` 属于 2.x，`bash`、`glob`、`grep` 和 `read` 属于 1.x。如果宿主本身就是 OpenCode，它自己的 User-Agent 已经说明是哪一代，这个值会被原样传出去，而不是被钉死，所以永远不会落后。没有任何一方说明时，以工具为准，User-Agent 跟着工具走。
+
+在同一代之内，Zen 认得名字的工具——`bash`、`glob`、`grep`、`read`、`write`、`edit`——必须在场，并且要按 OpenCode 的说法描述。前四个在宿主缺了的时候会补上；后两个只在宿主本来就有的时候才去读。工具永远不会被丢弃：宿主自己的工具原封不动地保留，只有发往上游的措辞被替换掉，所以模型发出的调用仍然适配真正执行它的那个工具。别的名字的工具一概不看。
+
+被*补上*的工具背后什么都没有：宿主没有这个工具，调它也会被丢弃。但 Zen 要求按 OpenCode 的样子描述它，而这么描述又会让模型想去调它，所以在 Zen 会读的正文开头之后、它不读的那段收尾之前，插一句说明。那句话是只针对这一个工具写的：实测过一句笼统的"这些工具不可用"，会连宿主自己的工具也一起不用。
+
+发出去的请求头就是下面这些，一个不多，而这份清单是刻意从 Zen 曾经接受过的全部头里挑出来的子集：
+
+| 请求头 | 值 |
+| --- | --- |
+| `content-type` | `application/json` |
+| `accept` | `*/*` |
+| `user-agent` | 上面说的那一代的值 |
+| `x-opencode-project` | 宿主的 project id，或 `global` |
+| `x-opencode-session` | 整个会话共用的一个 id |
+| `x-opencode-session-id` | 同一个 id |
+| `x-opencode-client` | `cli` |
+| `authorization` | `Bearer public`；走 Messages 时是 `x-api-key: public` |
+
+`anthropic-version` 和 `anthropic-beta` 也会发出去，但只在走 Messages 时，而且只在宿主自己设了它们的时候。
+
+`x-opencode-request` 在 2026-10-14 实测被拒，而且从未测出它是必需的，所以不发。`x-session-affinity` 和 `x-session-id` 出现在 OpenCode 上游自己的请求头集合里，实测被拒，所以同样不发——不过进来的同名请求头仍然会被读，用来判断这次请求属于哪个会话。测试按名字钉住了发出的这组请求头，因为多加一个请求头是弄坏这个插件最容易的方式。
+
+Zen 的免费层会检查 session id 是否是 OpenCode 能生成的那种：时间戳加每毫秒计数器截成十二位十六进制，后面接十四个随机的 base62 字符；session 的那一种还会把低位取反。宿主给的 id 如果本来就是这个形状，就原样传出去；否则按会话的首条消息生成一个并记住，这样同一会话的各轮请求会共用一个 session id。
+
+偶尔 Zen 会在发出 `[DONE]` 之前就结束一个流式的 Chat Completions 回复。如果回复已经说了内容、且其中没有未完成的工具调用，就以普通回答结束，正文里会说明它被截断了；再问一次就会接着往下走。如果是带着未完成的工具调用被截断、或者什么都没说就断了、或者被折叠给一个不支持流式的客户端，请求就会失败，错误信息里写明这个回复的 id 和收到了多少。走 Anthropic Messages 或 Responses 的回复被截断同样会失败：magpie 能把它和完整的回复区分开，并且在该模型支持的情况下继续往下走。
+
+## 排查
+
+| 看到的现象 | 这是什么 | 怎么办 |
+| --- | --- | --- |
+| 每个请求都是 `403 FreeTierError` | `fingerprint.json` 里的措辞过期了 | 跑 `bun run check:gate`；如果每一代都被拒，跑 `bun run capture` |
+| `426 Upgrade Required` | 这个包自称的 OpenCode 版本比 Zen 要的旧 | 升级插件，或者在更新的 OpenCode 里运行 |
+| `404 … not available as an OpenCode Zen free model now` | Zen 不再免费开放这个模型 | 从错误信息列出的模型里换一个 |
+| `Model is not an available free model for this protocol` | 请求发来时列表变了 | 让宿主刷新模型列表再试 |
+| `uses the public credential` | 存的密钥不是 `public` | 用 `public` 重新登录 |
+| 不带 `FreeTierError` 的 403 | 是别的 403，原样透传 | 按 Zen 自己的错误来读，别当成这个插件的 |
+
+这个插件给出的 403 会写明发出去的措辞来自哪个 OpenCode 版本。那正是 `check:gate` 在问的那份指纹，所以从它开始查，而不是从请求头开始查。
+
+模型的可用性和限流归 Zen 管，插件拿不到剩余额度可显示。同一个地址反复被拒，也可能被放进一个冷却期，表现得和被拒很像。
+
+## 许可
+
+MIT。分叉自 `magpie-community/plugins`（MIT）。

package/core-tools.mjs

@@ -0,0 +1,48 @@
+// Which generation of OpenCode's request Zen's free tier will serve.
+//
+// Zen accepts a request only when the whole of it belongs to one generation:
+// the User-Agent, the header set and the tools have to agree. Two generations
+// are known to be current, and which one applies is the host's to decide:
+//
+//   1.x   bash, glob, grep, read  -  User-Agent opencode/<v> ai-sdk/provider-utils/<v> runtime/bun/<v>
+//   2.x   shell, read             -  User-Agent opencode/<channel>/<version>/<client>
+//
+// Within a generation, the tools named in `read` are compared against Zen's own
+// copy of OpenCode's, and the ones in `required` have to be there. Their data
+// lives in fingerprint.json, which is a capture of a real OpenCode rather than
+// anything written by hand; `bun run capture` takes a new one, and
+// `bun run check:gate` says whether Zen still accepts it.
+//
+// The descriptions there are the opening of OpenCode's, since that is the part
+// Zen reads, with the capture host's scratch directory and OS banner replaced
+// because those belong to the machine the capture ran on.
+
+import { readFileSync } from "node:fs";
+
+const captured = JSON.parse(readFileSync(new URL("./fingerprint.json", import.meta.url), "utf8"));
+
+export const PROFILES = captured.profiles;
+
+/**
+ * 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.
+ */
+export function generationOf(tools) {
+  const names = new Set((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 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}`;
+}

package/fingerprint.json

@@ -0,0 +1,241 @@
+{
+  "_note": "Captured from a real OpenCode by capture.mjs. Refresh with: bun run capture",
+  "profiles": {
+    "1.x": {
+      "agent": {
+        "opencode": "1.19.0",
+        "providerUtils": {
+          "chat": "4.0.23",
+          "responses": "4.0.40",
+          "anthropic": "4.0.46"
+        },
+        "runtime": "runtime/bun/1.3.14"
+      },
+      "required": [
+        "bash",
+        "glob",
+        "grep",
+        "read"
+      ],
+      "tools": {
+        "bash": {
+          "name": "bash",
+          "description": "Executes a given Windows PowerShell (5.1) command with optional timeout, ensuring proper handling and security measures.\n\nBe aware: OS: linux, Shell: bash\n\nAll commands run in the current working directory by default. Use the `workdir` parameter if you need to run a command in a different directory. AVOID changing directories inside the command - use `workdir` instead.\n\nUse `/tmp` for temporary work outside the workspace. This directory has already been created, already exists, and is pre-approved for external directory access.\n\nIMPORTANT: This tool is for terminal operations like git, npm, docker, etc. DO NOT use it for file operations (reading, writing, editing, searching, finding files) - use the specialized tools for this instead.\n\n# Windows PowerShell (5.1) shell notes\n- Use `cmd1; if ($?) { cmd2 }` to chain dependent commands.\n- Use double quotes for interpolated strings (`\"Hello $name\"`), single quotes for verbatim strings.\n- Prefer full cmdlet names like `Get-ChildItem`, `Set-Content`, `Remove-Item`, and `New-Item` over aliases.\n- Use `$(...)` for subexpressions. Use `@(...)` for array expressions.\n- To call a native executable whose path contains spaces, use the call opera",
+          "parameters": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "type": "object",
+            "properties": {
+              "command": {
+                "type": "string",
+                "description": "The command to execute"
+              },
+              "timeout": {
+                "minimum": -9007199254740991,
+                "exclusiveMinimum": 0,
+                "type": "integer",
+                "maximum": 9007199254740991,
+                "description": "Optional timeout in milliseconds"
+              },
+              "workdir": {
+                "type": "string",
+                "description": "The working directory to run the command in. Defaults to the current directory. Use this instead of 'cd' commands."
+              }
+            },
+            "required": [
+              "command"
+            ]
+          }
+        },
+        "glob": {
+          "name": "glob",
+          "description": "- Fast file pattern matching tool that works with any codebase size\n- Supports glob patterns like \"**/*.js\" or \"src/**/*.ts\"\n- Returns matching file paths\n- Use this tool when you need to find files by name patterns\n- When you are doing an open-ended search that may require multiple rounds of globbing and grepping, use the Task tool instead\n- You have the capability to call multiple tools in a single response. It is always better to speculatively perform multiple searches as a batch that are potentially useful.\n",
+          "parameters": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "type": "object",
+            "properties": {
+              "pattern": {
+                "type": "string",
+                "description": "The glob pattern to match files against"
+              },
+              "path": {
+                "type": "string",
+                "description": "The directory to search in. If not specified, the current working directory will be used. IMPORTANT: Omit this field to use the default directory. DO NOT enter \"undefined\" or \"null\" - simply omit it for the default behavior. Must be a valid directory path if provided."
+              }
+            },
+            "required": [
+              "pattern"
+            ]
+          }
+        },
+        "grep": {
+          "name": "grep",
+          "description": "- Fast content search tool that works with any codebase size\n- Searches file contents using regular expressions\n- Supports full regex syntax (eg. \"log.*Error\", \"function\\s+\\w+\", etc.)\n- Filter files by pattern with the include parameter (eg. \"*.js\", \"*.{ts,tsx}\")\n- Returns file paths and line numbers with matching lines\n- Use this tool when you need to find files containing specific patterns\n- If you need to identify/count the number of matches within files, use the Bash tool with `rg` (ripgrep) directly. Do NOT use `grep`.\n- When you are doing an open-ended search that may require multiple rounds of globbing and grepping, use the Task tool instead\n",
+          "parameters": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "type": "object",
+            "properties": {
+              "pattern": {
+                "type": "string",
+                "description": "The regex pattern to search for in file contents"
+              },
+              "path": {
+                "type": "string",
+                "description": "The directory to search in. Defaults to the current working directory."
+              },
+              "include": {
+                "type": "string",
+                "description": "File pattern to include in the search (e.g. \"*.js\", \"*.{ts,tsx}\")"
+              }
+            },
+            "required": [
+              "pattern"
+            ]
+          }
+        },
+        "read": {
+          "name": "read",
+          "description": "Read a file or directory from the local filesystem. If the path does not exist, an error is returned.\n\nUsage:\n- The filePath parameter should be an absolute path.\n- By default, this tool returns up to 2000 lines from the start of the file.\n- The offset parameter is the line number to start from (1-indexed).\n- To read later sections, call this tool again with a larger offset.\n- Use the grep tool to find specific content in large files or files with long lines.\n- If you are unsure of the correct file path, use the glob tool to look up filenames by glob pattern.\n- Contents are returned with each line prefixed by its line number as `<line>: <content>`. For example, if a file has contents \"foo\\n\", you will receive \"1: foo\\n\". For directories, entries are returned one per line (without line numbers) with a trailing `/` for subdirectories.\n- Any line longer than 2000 characters is truncated.\n- Call this tool in parallel when you know there are multiple files you want to read.\n- Avoid tiny repeated slices (30 line chunks). If you need more context, read a larger window.\n- This tool can read image files and PDFs and return them as file attachments.\n",
+          "parameters": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "type": "object",
+            "properties": {
+              "filePath": {
+                "type": "string",
+                "description": "The absolute path to the file or directory to read"
+              },
+              "offset": {
+                "minimum": 0,
+                "type": "integer",
+                "maximum": 9007199254740991,
+                "description": "The line number to start reading from (1-indexed)"
+              },
+              "limit": {
+                "minimum": 0,
+                "type": "integer",
+                "maximum": 9007199254740991,
+                "description": "The maximum number of lines to read (defaults to 2000)"
+              }
+            },
+            "required": [
+              "filePath"
+            ]
+          }
+        },
+        "edit": {
+          "name": "edit",
+          "description": "Performs exact string replacements in files. \n\nUsage:\n- You must use your `Read` tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file. \n- When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: line number + colon + space (e.g., `1: `). Everything after that space is the actual file content to match. Never include any part of the line number prefix in the oldString or newString.\n- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.\n- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.\n- The edit will FAIL if `oldString` is not found in the file with an error \"oldString not found in content\".\n- The edit will FAIL if `oldString` is found multiple times in the file with an error \"Found multiple matches for oldString. Provide more surrounding lines in oldString to identify the correct match.\" Either provide a larger string with more surrounding context to make it unique or use `replaceAll` to change every ",
+          "parameters": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "type": "object",
+            "properties": {
+              "filePath": {
+                "type": "string",
+                "description": "The absolute path to the file to modify"
+              },
+              "oldString": {
+                "type": "string",
+                "description": "The text to replace"
+              },
+              "newString": {
+                "type": "string",
+                "description": "The text to replace it with (must be different from oldString)"
+              },
+              "replaceAll": {
+                "type": "boolean",
+                "description": "Replace all occurrences of oldString (default false)"
+              }
+            },
+            "required": [
+              "filePath",
+              "oldString",
+              "newString"
+            ]
+          }
+        },
+        "write": {
+          "name": "write",
+          "description": "Writes a file to the local filesystem.\n\nUsage:\n- This tool will overwrite the existing file if there is one at the provided path.\n- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.\n- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.\n- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.\n- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.\n",
+          "parameters": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string",
+                "description": "The content to write to the file"
+              },
+              "filePath": {
+                "type": "string",
+                "description": "The absolute path to the file to write (must be absolute, not relative)"
+              }
+            },
+            "required": [
+              "content",
+              "filePath"
+            ]
+          }
+        }
+      }
+    },
+    "2.x": {
+      "agent": {
+        "channel": "latest",
+        "opencode": "2.0.29",
+        "client": "cli"
+      },
+      "required": [
+        "shell",
+        "read"
+      ],
+      "tools": {
+        "shell": {
+          "name": "shell",
+          "description": "Execute a shell command and return its output. Commands run on Windows using PowerShell (5.1). Quote file paths containing spaces or special characters. Prefer dedicated tools over shell commands when possible. When output is large, the full result is saved to a file and a truncated preview is returned. Rely on automatic truncation unless filtering the output is more useful. Commands accept an optional timeout, background commands have no timeout by default. Background commands return immediately, and you will be notified when they complete.",
+          "parameters": {
+            "type": "object",
+            "properties": {
+              "command": {
+                "type": "string",
+                "description": "Shell command string to execute"
+              },
+              "workdir": {
+                "type": "string",
+                "description": "Working directory to execute the command in."
+              },
+              "timeout": {
+                "type": "number",
+                "description": "Timeout in milliseconds. Set to 0 to disable the timeout."
+              }
+            },
+            "required": [
+              "command"
+            ]
+          }
+        },
+        "read": {
+          "name": "read",
+          "description": "Read the contents of a file or directory. Supports text files, images, and PDFs. Images and PDFs are presented directly to the model. Each text line is prefixed by its 1-based line number as <line>: <content>. The prefix is for reference and is not part of the file content. Directory entries are returned one per line. Use offset and limit to read large files or directories in sections. Prefer one larger read over many small slices, and use grep to find specific content in large files.",
+          "parameters": {
+            "type": "object",
+            "properties": {
+              "path": {
+                "type": "string",
+                "description": "File or directory to read"
+              },
+              "offset": {
+                "type": "number",
+                "description": "The line or directory entry to start reading from (1-based)"
+              },
+              "limit": {
+                "type": "number",
+                "description": "The maximum number of lines or directory entries to read"
+              }
+            },
+            "required": [
+              "path"
+            ]
+          }
+        }
+      }
+    }
+  }
+}

package/index.mjs

@@ -0,0 +1,3 @@
+import plugin from "./provider.mjs"
+
+export const ZenFreePlugin = plugin.server

package/models.mjs

@@ -0,0 +1,148 @@
+export const PROVIDER = "opencode-zen-free";
+export const SDK = {
+  chat: "@ai-sdk/openai-compatible",
+  responses: "@ai-sdk/openai",
+  anthropic: "@ai-sdk/anthropic",
+};
+
+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]];
+  }
+  return protocols;
+}
+
+function sdkProtocol(npm) {
+  if (npm?.includes("anthropic")) return "anthropic";
+  if (npm === SDK.responses) return "responses";
+  if (npm?.includes("openai-compatible")) return "chat";
+}
+
+function isRetired(model) {
+  return (
+    model.deprecated === true ||
+    ["deprecated", "retired", "disabled"].includes(model.status ?? model.lifecycle) ||
+    model.deprecated_at != null ||
+    model.retirement_date != null
+  );
+}
+
+export function isFree(id, model = {}) {
+  return (
+    !isRetired(model) && (/free/i.test(id) || (model.cost?.input === 0 && model.cost?.output === 0))
+  );
+}
+
+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));
+    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 ?? []);
+    result[id] = {
+      id,
+      providerID: PROVIDER,
+      name: model.name ?? id,
+      api: { id, url: baseURL, npm: SDK[protocol] },
+      limit: { context: 32768, output: 4096, ...model.limit },
+      capabilities: {
+        temperature: model.temperature ?? true,
+        reasoning: model.reasoning ?? false,
+        attachment: model.attachment ?? input.some((name) => name !== "text"),
+        toolcall: model.tool_call ?? true,
+        input: modalities(input),
+        output: modalities(output),
+        interleaved: model.interleaved ?? false,
+      },
+      cost: { input: 0, output: 0, cache: { read: 0, write: 0 } },
+      variants: Object.fromEntries(efforts.map((effort) => [effort, { reasoningEffort: effort }])),
+      options: {},
+      headers: {},
+      status: model.status ?? "active",
+      release_date: model.release_date ?? "",
+      free: true,
+    };
+  }
+  return result;
+}
+
+// Offline bootstrap metadata from the OpenCode catalog, 2026-10-06.
+export const bootstrapProvider = {
+  npm: SDK.chat,
+  models: {
+    "big-pickle": {
+      name: "Big Pickle",
+      cost: { input: 0, output: 0 },
+      limit: { context: 200000, input: 160000, output: 32000 },
+      reasoning: true,
+      tool_call: true,
+      interleaved: { field: "reasoning_content" },
+    },
+    "space-bunny-free": {
+      name: "Space Bunny Free",
+      cost: { input: 0, output: 0 },
+      limit: { context: 1048576, input: 524288, output: 524288 },
+      reasoning: true,
+      tool_call: true,
+    },
+    "muse-spark-1.3-contributor-free": {
+      name: "Muse Spark 1.3 Free",
+      cost: { input: 0, output: 0 },
+      provider: { npm: SDK.responses },
+      limit: { context: 1048576, output: 131072 },
+      reasoning: true,
+      tool_call: true,
+      modalities: { input: ["text", "image", "video", "pdf", "audio"], output: ["text"] },
+      reasoning_options: [
+        { type: "effort", values: ["minimal", "low", "medium", "high", "xhigh"] },
+      ],
+    },
+  },
+};
+
+export function configModels(models) {
+  return Object.fromEntries(
+    Object.entries(models).map(([id, model]) => [
+      id,
+      {
+        id,
+        name: model.name,
+        provider: { npm: model.api.npm, api: model.api.url },
+        limit: model.limit,
+        reasoning: model.capabilities.reasoning,
+        tool_call: model.capabilities.toolcall,
+        attachment: model.capabilities.attachment,
+        modalities: {
+          input: Object.keys(model.capabilities.input).filter(
+            (key) => model.capabilities.input[key],
+          ),
+          output: Object.keys(model.capabilities.output).filter(
+            (key) => model.capabilities.output[key],
+          ),
+        },
+        cost: { input: 0, output: 0 },
+        variants: model.variants,
+        free: true,
+      },
+    ]),
+  );
+}

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "opencode-zen-freex",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.1",
+  "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",
+  "files": [
+    "index.mjs",
+    "provider.mjs",
+    "core-tools.mjs",
+    "fingerprint.json",
+    "models.mjs",
+    "stream.mjs",
+    "tool-response.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": ["opencode", "opencode-plugin", "zen", "free", "magpie"],
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/tkhs101/OpenCode-Zen-FreeX.git" },
+  "bugs": { "url": "https://github.com/tkhs101/OpenCode-Zen-FreeX/issues" },
+  "homepage": "https://github.com/tkhs101/OpenCode-Zen-FreeX#readme",
+  "scripts": {
+    "test": "bun test",
+    "check:gate": "bun tools-smoke.mjs",
+    "capture": "bun capture.mjs"
+  },
+  "magpie": { "icon": "https://opencode.ai/favicon-v3.ico", "maxConcurrency": 2 }
 }