@tduyng/pi-opencode-z 0.0.1 → 0.0.3

package/README.md

@@ -1,42 +1,54 @@
 # pi-opencode-z
 
-Use opencode's Zen models from Pi, including the free ones.
+opencode's Zen models in pi, free ones included. No API key, no proxy, no key of your own: the bridge drives the opencode server already running on your machine.
 
-Since September 2026 the free tier answers any direct API call with `403 FreeTierError: "OpenCode's free tier can only be used from within OpenCode"`. No API key or proxy gets around it, because the check is on where the request originates. So this extension does not call the Zen API. It drives the opencode background server already running on your machine and lets opencode make the upstream call, which is the one thing the free tier accepts.
+## What it costs
+
+No tools, no prompt block, no schema. It is a model provider, so the context and the cold start are pi's own.
+
+The 7k input floor is opencode's, not this extension's. A plain `opencode run` on a free model spends 9,176 input tokens on a one-line prompt, while this bridge spends 6,941 with 2,048 of those served from cache. That floor is opencode's system prompt and built-in tool schemas, and every approach pays it, because stripping those tools is exactly what trips the 403.
+
+What the bridge does save is per turn. opencode holds the conversation, so each turn sends only the new message instead of re-serializing the transcript, and the tool schemas sit in the cached prefix rather than being pasted back as prose on every request.
+
+## Why it works this way
+
+Since September 2026 the free tier answers any direct API call with `403 FreeTierError: "OpenCode's free tier can only be used from within OpenCode"`. No key and no proxy gets around it, because the check is on where the request originates.
+
+So the extension does not call the Zen API. It drives the opencode background server and lets opencode make the upstream call, which is the one thing the free tier accepts.
 
 ## How it works
 
-The bridge reads the server's url and password from `~/.local/state/opencode/service.json` and talks to it over HTTP basic auth as user `opencode`. If the server is not running, `opencode service start` brings it back.
+The bridge reads the server url and password from `~/.local/state/opencode/service.json` and talks to it over HTTP basic auth as user `opencode`. If the server is not running, `opencode service start` brings it back.
 
-Each Pi session gets one opencode session, rooted in a throwaway temp directory that holds its `opencode.jsonc`. Nothing is written to your repo or to `~/.config/opencode`.
+Each pi session gets one opencode session, rooted in a throwaway temp directory holding its `opencode.jsonc`. Nothing is written to your repo or to `~/.config/opencode`.
 
-Pi's own tools reach the model through a local MCP server, exposed as `pi_read`, `pi_bash`, `pi_edit` and so on. When the model calls one, the bridge holds that MCP request open, hands the call to Pi, and Pi runs the real tool against your real project. The answer goes back over the same held request and opencode carries on in the same session, none the wiser. The model never touches your files directly. Pi does, under Pi's own permissions.
+Pi's tools reach the model through a local MCP server, exposed as `pi_read`, `pi_bash`, `pi_edit`, and so on. When the model calls one, the bridge holds that MCP request open, hands the call to pi, and pi runs the real tool against your real project. The answer goes back over the same held request and opencode carries on in the same session. The model never touches your files directly, and pi does, under pi's own permissions.
 
 Pi hands providers a transcript rather than a prompt and a tool list, so the bridge replays the transcript's system messages to recover the current instructions and tool set before each turn.
 
-Cold start costs nothing extra. A plain `opencode run` on a free model spends 9176 input tokens on a one-line prompt. The bridge spends 6941, with 2048 of those served from cache. That 7k floor is opencode's own system prompt and built-in tool schemas. Every approach to this problem pays it, because stripping those tools is exactly what trips the 403.
+A mode switch that adds or removes tools keeps the session too: the bridge pushes `notifications/tools/list_changed` over MCP, opencode re-lists, and the cached prefix survives.
 
-The savings are per turn. opencode holds the conversation, so each turn sends only the new message instead of re-serializing the whole transcript. Tool schemas sit in the cached prefix rather than being pasted back as prose every time. Extensions that drive the opencode CLI instead have to resend everything on every turn and teach the model to hand-write tool calls inside text markers. A mode switch that adds or removes tools keeps the session too: the bridge pushes `notifications/tools/list_changed` over MCP, opencode re-lists, and the cached prefix survives.
+A full tool-calling turn, measured end to end with a real file read, takes about 10 seconds.
 
-A full tool-calling turn, measured end to end including a real file read, takes about 10 seconds.
-
-## Using it
+## Use
 
 Run `/model` and pick anything under the `opencode-z` provider, for example `opencode-z/mimo-v2.6-flash-free`.
 
-From the command line:
-
-```
+```text
 pi --provider opencode-z --model mimo-v2.6-flash-free
 ```
 
-## Commands
-
-`/opencode-z status` shows the server url, the config file, the active models filter, the MCP endpoint, live sessions and the model list. `/opencode-z models` lists the models alone, free ones first. `/opencode-z refresh` re-reads the config file and the catalogue from opencode. `/opencode-z config` shows the resolved settings and where they come from. `/opencode-z help` prints usage.
+| Command | Effect |
+| --- | --- |
+| `/opencode-z status` | Server url, config file, models filter, MCP endpoint, live sessions, model list |
+| `/opencode-z models` | The models alone, free ones first |
+| `/opencode-z refresh` | Re-read the config and the catalogue without restarting pi |
+| `/opencode-z config` | Resolved settings and where they come from |
+| `/opencode-z help` | Usage |
 
-## Settings
+## Configure
 
-Settings live in `opencode-z.json` inside Pi's agent directory (usually `~/.pi/agent/opencode-z.json`). A project's `.pi/opencode-z.json` overrides it field by field. Environment variables override both, so either mechanism works and one-off runs never need to touch a file. `/opencode-z config` shows the resolved values, and `/opencode-z refresh` re-reads both files without restarting Pi.
+Settings live in `~/.pi/agent/opencode-z.json`, and a project's `.pi/opencode-z.json` overrides it field by field. Environment variables override both, so a one-off run never needs a file.
 
 Free models only:
 
@@ -55,16 +67,26 @@ A pinned list with a custom binary:
 }
 ```
 
-`bin` overrides the `opencode` executable. `models` narrows what gets registered: `free` keeps zero-cost models, a comma-separated string or an array of ids pins the list. Unset or empty, the bridge registers every Zen model your account can reach, free and paid. Only Zen models appear here (the `opencode` provider in opencode's catalogue), never other providers. `OPENCODE_Z_BIN` and `OPENCODE_Z_MODELS` do the same per process and win over the file.
+`models` narrows what gets registered: `free` keeps zero-cost models, and a comma-separated string or an array pins the list. Unset or empty, every Zen model your account can reach is registered. Only Zen models appear, never other providers. `OPENCODE_Z_BIN` and `OPENCODE_Z_MODELS` do the same per process and win over the file.
 
 ## Notes
 
-The bridge never denies opencode's built-in tools. A `deny` rule anywhere in the agent's permissions trips the free tier 403 even for tools that were allowed, so every action stays on `ask` and the bridge rejects the unwanted ones at runtime. A weaker model sometimes reaches for its built-in `read` first, gets refused, and retries with `pi_read`, which costs one round trip.
+The bridge never denies opencode's built-in tools. A `deny` rule anywhere in the agent's permissions trips the free-tier 403 even for tools that were allowed, so every action stays on `ask` and the bridge rejects the unwanted ones at runtime. A weaker model sometimes reaches for its built-in `read` first, gets refused, and retries with `pi_read`, which costs one round trip.
+
+opencode adds and retires Zen models often, so the catalogue is read live at startup and `/opencode-z refresh` re-reads it.
+
+The first prompt lists the exact MCP names available in that turn. Some model hosts display these tools under a `functions.` namespace, and the bridge states that the label does not rename a tool, which keeps a model from mistaking a disabled `read` for `pi_read`.
 
-opencode adds and retires Zen models often. The catalogue is read live at startup, and `/opencode-z refresh` re-reads it without restarting Pi.
+A step that produces reasoning but no text and no tool call is re-prompted through the same bounded recovery path, and so is a step whose only text is a `pi_` call written out as chat template markup.
 
-The first prompt lists the exact MCP names available in that turn. Some model hosts display these tools under a `functions.` namespace. The bridge states that the label does not rename a tool, which keeps a model from mistaking disabled `read` for `pi_read`. A successful model step with reasoning but no text or tool call is re-prompted through the same bounded recovery path, and so is a step whose only text is a pi_ call written out as chat template markup instead of dispatched.
+opencode stops a whole step when the model calls two of its built-in tools at once: refusing one declines the rest. The bridge counts its own refusals and, when that stop was its doing, re-prompts the same session with a nudge back to the `pi_` tools, at most twice per turn, instead of failing the turn.
 
-opencode stops a whole step when the model calls two of its built-in tools at once: refusing one declines the rest. The bridge counts its own refusals and, when that stop was its doing, re-prompts the same session with a nudge back to the pi_ tools (at most twice per turn) instead of failing the turn.
+When a turn fails, the bridge interrupts opencode and answers waiting tool calls with an error. It keeps the opencode session when pi's transcript still ends at the last completed user message, so a retry reuses the prompt cache, and drops it to rebuild from the transcript when a partial assistant or tool result is present. A timeout usually means the model was still working, since large contexts on high thinking levels are slow, or that opencode got stuck waiting.
+
+## Install
+
+```bash
+pi install npm:@tduyng/pi-opencode-z
+```
 
-When a turn fails, the bridge interrupts opencode and answers waiting tool calls with an error. It keeps the opencode session when Pi's transcript still ends at the last completed user message, so a retry can reuse the prompt cache. If Pi's transcript contains a partial assistant or tool result, the bridge drops the session and rebuilds it from Pi's transcript. A timeout usually means the model was still working (large contexts on high thinking levels are slow) or opencode got stuck waiting.
+Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-opencode-z`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tduyng/pi-opencode-z",
-  "version": "0.0.1",
-  "description": "Use opencode's Zen models from Pi, including the free ones, by driving the local opencode server and bridging Pi tools over MCP.",
+  "version": "0.0.3",
+  "description": "opencode's Zen models in Pi, free ones included, by driving the local opencode server. No API key of your own.",
   "keywords": [
     "pi",
     "pi-package",

package/src/client.ts

@@ -128,9 +128,11 @@ export async function api<T = unknown>(
     try {
         return await request<T>(info, method, path, body, signal)
     } catch (error) {
-        // A cached url or password goes stale when the server restarts. Both failures happen
-        // before the app sees the request, so re-resolving cannot duplicate it.
-        const stale = error instanceof TypeError || (error instanceof Error && /failed \(401\)/.test(error.message))
+        // A cached url or password goes stale when the server restarts. Retry a read, or a write
+        // the server rejected outright with 401; a POST that drops mid-flight may already have run.
+        const stale =
+            (error instanceof Error && error.message.includes('(401)')) ||
+            ((method === 'GET' || method === 'DELETE') && error instanceof TypeError)
         if (signal?.aborted || !stale) throw error
         service = undefined
         return request<T>(await resolveService(), method, path, body, signal)

package/src/config.ts

@@ -88,7 +88,7 @@ export function resolveBin(envRaw: string | undefined, fileBin: string | undefin
 }
 
 export function bridgeBin(): string {
-    return resolveBin(process.env['OPENCODE_Z_BIN'], loadBridgeFile().bin)
+    return resolveBin(process.env['OPENCODE_Z_BIN'], readBridgeFile(configPath()).bin)
 }
 
 export function bridgeModelsRaw(): string | undefined {

package/src/index.ts

@@ -51,10 +51,12 @@ export default async function opencodeBridge(pi: ExtensionAPI): Promise<void> {
 
     async function start(): Promise<void> {
         await resolveService()
-        mcpServer = await startMcpServer()
-        attachMcpServer(runtime, mcpServer)
+        const models = await loadModels()
+        const server = await startMcpServer()
+        mcpServer = server
+        attachMcpServer(runtime, server)
         events = startEventStream((event) => routeEvent(runtime, event))
-        register(await loadModels())
+        register(models)
         startupError = undefined
     }