Skip to content

Commit bf26ed4

Browse files
committed
docs: document the free-model limitation and release 0.3.0
Zen free models cannot power predictions: the upstream free-tier gateway rejects the tool-stripped prediction request (anomalyco/opencode#49723), so the docs now state that a non-free prediction model is required. Bump to 0.3.0 and close out the Unreleased section.
1 parent d779981 commit bf26ed4

3 files changed

Lines changed: 11 additions & 2 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10+
## [0.3.0] - 2026-11-01
11+
1012
### Changed
1113

1214
- **Suggestion lifecycle**: a prediction is made when the session is idle, no permission or form dialog is waiting, and no message is queued. Typing, focus changes, and shell mode only hide the suggestion; they do not cancel an in-flight call or discard a ready one. Accepting fills the input without consuming it, so deleting the accepted text reveals the same suggestion again. The suggestion is keyed by its turn, not by what the user did; a new turn, revert, compaction, or session switch discards it
@@ -20,6 +22,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
2022
- The 800 ms retry, the timeout retry budget, the runtime version-warning toast, and the active-session/global fallback chain
2123
- **Older-host compatibility**: the OpenTUI 0.5 `getLayoutNode().markDirty()` fallback, the OpenCode 2.0.x `session.idle` event without a session id, the guards for a missing `session.create`/`generate`/`remove`, and the shell placeholder heuristic for hosts without a keymap mode. The plugin now requires OpenCode ≥ 2.1.4 (OpenTUI ≥ 0.6)
2224

25+
### Docs
26+
27+
- Documented that OpenCode Zen free models (`opencode/*-free`) cannot power predictions: the upstream free-tier gateway rejects the tool-stripped prediction request with a misleading `Free usage limit reached` error ([anomalyco/opencode#49723](https://github.com/anomalyco/opencode/issues/49723)), so a non-free prediction model is required
28+
2329
### Testing
2430

2531
- Rewrote the conversation, predictor, and plugin suites around the new contract: tail preservation, tiered retention, code collapse, tool facts, dialog/queued blocking, suggestion preservation across typing/focus/shell, accept/deletion round-trip, no retry, and helper cleanup

‎README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ Predicts your next message after the assistant replies and shows it at the promp
44

55
Requires OpenCode **≥ 2.1.4** (latest V2 plugin API).
66

7+
Predictions need a non-free model: OpenCode Zen free models (`opencode/*-free`) are **not supported** because of an [upstream bug](#limitations).
8+
79
## Install
810

911
Add to `~/.config/opencode/cli.json`:
@@ -56,7 +58,7 @@ Restart opencode. The package is installed automatically; OpenCode provides the
5658
|---|---|---|
5759
| `acceptKey` | `right` | Key to accept the suggestion (only effective while the input is empty). Invalid values fall back to the default with a warning |
5860
| `timeoutMs` | `20000` | Per-prediction timeout, 1000–300000 ms. The timed-out call is aborted; there is no retry |
59-
| `model` | unset | Fast model for predictions as `provider/model` (or `provider/model#variant`); a bare model id uses the session's provider (then a configured agent provider, or a unique matching provider). Falls back to `agents["next-prompt"].model`, then `agents.title.model` in `opencode.json(c)`, then the current session's model. Unknown providers, models, and variants are reported with an error toast instead of running a silently wrong prediction |
61+
| `model` | unset | Fast model for predictions as `provider/model` (or `provider/model#variant`); a bare model id uses the session's provider (then a configured agent provider, or a unique matching provider). Falls back to `agents["next-prompt"].model`, then `agents.title.model` in `opencode.json(c)`, then the current session's model. Do not point this at an `opencode/*-free` model (see [Limitations](#limitations)). Unknown providers, models, and variants are reported with an error toast instead of running a silently wrong prediction |
6062
| `variant` | auto | Model variant (reasoning effort) used for predictions. By default the lowest variant the model supports is picked automatically (e.g. `none`, `minimal`, `min`, `low`); models without variants are left untouched. Set it explicitly (e.g. `"high"`) to override, or `"default"` to disable variants entirely |
6163
| `includeToolContext` | `false` | Include the last completed tool's input and output in the prediction context. The tool name and its success/failure are always included; without this option, no tool content is sent |
6264

@@ -122,6 +124,7 @@ Release steps: bump `package.json` and `CHANGELOG.md`, run `bun run check && bun
122124

123125
## Limitations
124126

127+
- **OpenCode Zen free models (`opencode/*-free`) are not supported for predictions — this is an upstream bug.** The Zen free-tier gateway only accepts model requests that carry OpenCode's full default tool set, while a prediction deliberately strips every tool from its helper session. So each prediction on a free model is refused with a misleading `Free usage limit reached` error and that turn silently shows no suggestion; the main conversation on the same free model is unaffected. The gateway rejects a legitimate request made from inside OpenCode, which the plugin cannot work around from its side (tracked upstream as [anomalyco/opencode#49723](https://github.com/anomalyco/opencode/issues/49723)). Configure a non-free prediction model (`model`, `agents["next-prompt"].model`, or `agents.title.model`) to use the plugin.
125128
- The prompt has no plugin slot for an inline hint, so the suggestion is written into the input placeholder. This relies on OpenTUI's placeholder semantics and structural editor detection; a host UI change can break it.
126129
- Shell mode is detected through the keymap mode. If that changes upstream, verify that the accept key never inserts text into a shell command.
127130
- Predictions are only generated for the focused session; switching to another tab/session starts a fresh prediction on its next turn.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "opencode-next-prompt",
3-
"version": "0.2.0",
3+
"version": "0.3.0",
44
"description": "Predicts your next message after the assistant replies in OpenCode — accept it with a keypress",
55
"type": "module",
66
"exports": {

0 commit comments

Comments
 (0)