@tduyng/pi-opencode-z 0.0.2 → 0.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +46 -24
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,42 +1,54 @@
|
|
|
1
1
|
# pi-opencode-z
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
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.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## What it costs
|
|
6
|
+
|
|
7
|
+
No tools, no prompt block, no schema. It is a model provider, so the context and the cold start are pi's own.
|
|
8
|
+
|
|
9
|
+
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.
|
|
10
|
+
|
|
11
|
+
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.
|
|
12
|
+
|
|
13
|
+
## Why it works this way
|
|
14
|
+
|
|
15
|
+
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.
|
|
16
|
+
|
|
17
|
+
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.
|
|
6
18
|
|
|
7
19
|
## How it works
|
|
8
20
|
|
|
9
|
-
The bridge reads the server
|
|
21
|
+
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.
|
|
10
22
|
|
|
11
|
-
Each
|
|
23
|
+
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`.
|
|
12
24
|
|
|
13
|
-
Pi's
|
|
25
|
+
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.
|
|
14
26
|
|
|
15
27
|
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.
|
|
16
28
|
|
|
17
|
-
|
|
29
|
+
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.
|
|
18
30
|
|
|
19
|
-
|
|
31
|
+
A full tool-calling turn, measured end to end with a real file read, takes about 10 seconds.
|
|
20
32
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
## Using it
|
|
33
|
+
## Use
|
|
24
34
|
|
|
25
35
|
Run `/model` and pick anything under the `opencode-z` provider, for example `opencode-z/mimo-v2.6-flash-free`.
|
|
26
36
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
```
|
|
37
|
+
```text
|
|
30
38
|
pi --provider opencode-z --model mimo-v2.6-flash-free
|
|
31
39
|
```
|
|
32
40
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
`/opencode-z status`
|
|
41
|
+
| Command | Effect |
|
|
42
|
+
| --- | --- |
|
|
43
|
+
| `/opencode-z status` | Server url, config file, models filter, MCP endpoint, live sessions, model list |
|
|
44
|
+
| `/opencode-z models` | The models alone, free ones first |
|
|
45
|
+
| `/opencode-z refresh` | Re-read the config and the catalogue without restarting pi |
|
|
46
|
+
| `/opencode-z config` | Resolved settings and where they come from |
|
|
47
|
+
| `/opencode-z help` | Usage |
|
|
36
48
|
|
|
37
|
-
##
|
|
49
|
+
## Configure
|
|
38
50
|
|
|
39
|
-
Settings live in
|
|
51
|
+
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.
|
|
40
52
|
|
|
41
53
|
Free models only:
|
|
42
54
|
|
|
@@ -55,16 +67,26 @@ A pinned list with a custom binary:
|
|
|
55
67
|
}
|
|
56
68
|
```
|
|
57
69
|
|
|
58
|
-
`
|
|
70
|
+
`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.
|
|
59
71
|
|
|
60
72
|
## Notes
|
|
61
73
|
|
|
62
|
-
The bridge never denies opencode's built-in tools. A `deny` rule anywhere in the agent's permissions trips the free
|
|
74
|
+
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.
|
|
75
|
+
|
|
76
|
+
opencode adds and retires Zen models often, so the catalogue is read live at startup and `/opencode-z refresh` re-reads it.
|
|
77
|
+
|
|
78
|
+
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`.
|
|
63
79
|
|
|
64
|
-
|
|
80
|
+
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.
|
|
65
81
|
|
|
66
|
-
|
|
82
|
+
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.
|
|
67
83
|
|
|
68
|
-
opencode
|
|
84
|
+
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.
|
|
85
|
+
|
|
86
|
+
## Install
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
pi install npm:@tduyng/pi-opencode-z
|
|
90
|
+
```
|
|
69
91
|
|
|
70
|
-
|
|
92
|
+
Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-opencode-z`
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tduyng/pi-opencode-z",
|
|
3
|
-
"version": "0.0.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.0.3",
|
|
4
|
+
"description": "opencode's Zen models in Pi, free ones included, by driving the local opencode server. No API key of your own.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"pi",
|
|
7
7
|
"pi-package",
|