Opencode 2.0 #171

Closed
opened 2026-10-16 00:53:15 -04:00 by cmoriarty · 2 comments
Owner

Braid uses opencode, and there is a new major version out. I think we should upgrade, assuming it makes sense to do so.

Braid uses opencode, and there is a new major version out. I think we should upgrade, assuming it makes sense to do so.
Author
Owner

What Opencode 2 means for Braid, from its migration guide, the release coverage and its source at tag v2.0.30 (read 2026-10-16). This issue follows #170: #170 ships on opencode 1.18.35 first, so its comparison with run 62 measures its own changes alone.

What moving costs

  • The v1 server API is gone. Braid sends and reads everything through it: prompt_async, /session/status, /event?directory=, the message lists, fork, abort, revert and question replies (src/osf/agent/client.py, which says outright that Braid drives and reads with v1 because 1.x's v2 API could not see sessions driven that way). v2 has about 139 /api/... endpoints instead (V2_HTTP_API_AUDIT.md): a prompt goes into a durable inbox with steer or queue delivery, task is subagent, a permission reply takes decision, questions are backed by forms, and events come from one /api/event feed plus a replayable per-session log.
  • Almost every key of the run config changes: provider → providers, a model's id → modelID, variants become an array, options splits into settings, headers and body, the permission map becomes an ordered permissions list (bash → shell), agent → agents (prompt → system), skill paths become one skills list, MCP servers move under mcp.servers.
  • Dropped: language servers (lsp is accepted and does nothing), the CLAUDE.md fallback (only AGENTS.md is read), 1.x plugins.
  • Braid's own pieces to redo: the opencode pin in the image, the fake-model recordings, the simulated runs, the needs_opencode tests.
  • One server per run still works: opencode serve --stdio --port 0 with OPENCODE_PASSWORD and OPENCODE_DB (packages/cli/src/services/standalone.ts), so Braid need not use the shared background service.

Where it meets #170

  • The last call: v2 keeps the tool list on a step's final turn and sends toolChoice: "none", "so the cached prompt prefix survives" (specs/v2/tools.md, packages/core/src/session/runner/llm.ts). That is the fix #170 made by hand.
  • Instructions: v2 never rewrites the system prompt mid-session. A changed instruction is added as a chronological message, folded into the user turn on OpenAI-compatible routes (specs/v2/session.md, packages/ai/src/protocols/openai-chat.ts): one cause of full re-prefills fewer on trogdor.
  • Effort Auto: #170's model entry per effort (qwen3.8-27b@high with an id override) becomes v2's own variants, provider/model#high, chosen per session, agent or command. On trogdor a session still keeps one effort, because the Qwen template writes it into the system message; v2 drops mid-session effort changes on OpenAI-compatible routes for the same cache reason (packages/ai/src/effort-updates.ts). On the Claude backend, Claude 5.1 and later take per-turn effort changes without losing the cache, so there Auto could change effort mid-session.
  • Knowing a session is done: experimental.session.wait, a race-free idle barrier, could replace Braid's quiet detection, which exists because v1 has none. It is experimental.
  • Restarts: the per-session log replays from a sequence (after, follow) and could replace much of Braid's backfill. To settle: v2 resumes the sessions it was running when it starts again, which overlaps Braid's own restart recovery.
  • Handoff: v2's compaction keeps a rolling summary and the recent context by token budget, but it still rebuilds the history, so it is a re-prefill too. It does not beat Braid's handoff note.
  • Code Mode: an agent can chain several MCP calls in one short script instead of a turn each. It could cut turns in the browser-heavy steps (browser check, judge). The gains are claims, not measurements, and Qwen 27B writing those scripts is untried.
  • Parallel apply groups (#170 section 10) don't need v2: Braid makes its own worktrees and scopes sessions by folder on v1.

Risk

v2 became the main line on 2026-10-12, and its tags went from v2.0.5 to v2.0.30 since. 1.x still gets fixes (1.19.2 on 2026-10-16), and 1.19 is the bridge release.

Plan

  1. A trial before any proposal: a v2 server against the fake model and trogdor's /tokenize, checking that the prompt prefix holds across a whole step with the last call; variants for effort; the equivalents of permissions, the outside-path rule and agent questions; the event feed and the idle barrier.
  2. Then the migration as its own OpenSpec change, with #170's run as the baseline.

Sources: migration guide, The New Stack, explainx upgrade guide.

What Opencode 2 means for Braid, from its migration guide, the release coverage and its source at tag `v2.0.30` (read 2026-10-16). This issue follows #170: #170 ships on opencode 1.18.35 first, so its comparison with run 62 measures its own changes alone. ## What moving costs - **The v1 server API is gone.** Braid sends and reads everything through it: `prompt_async`, `/session/status`, `/event?directory=`, the message lists, fork, abort, revert and question replies (`src/osf/agent/client.py`, which says outright that Braid drives and reads with v1 because 1.x's v2 API could not see sessions driven that way). v2 has about 139 `/api/...` endpoints instead (`V2_HTTP_API_AUDIT.md`): a prompt goes into a durable inbox with `steer` or `queue` delivery, `task` is `subagent`, a permission reply takes `decision`, questions are backed by forms, and events come from one `/api/event` feed plus a replayable per-session log. - **Almost every key of the run config changes:** `provider` → `providers`, a model's `id` → `modelID`, variants become an array, `options` splits into `settings`, `headers` and `body`, the `permission` map becomes an ordered `permissions` list (`bash` → `shell`), `agent` → `agents` (`prompt` → `system`), skill paths become one `skills` list, MCP servers move under `mcp.servers`. - **Dropped:** language servers (`lsp` is accepted and does nothing), the `CLAUDE.md` fallback (only `AGENTS.md` is read), 1.x plugins. - **Braid's own pieces to redo:** the opencode pin in the image, the fake-model recordings, the simulated runs, the `needs_opencode` tests. - **One server per run still works:** `opencode serve --stdio --port 0` with `OPENCODE_PASSWORD` and `OPENCODE_DB` (`packages/cli/src/services/standalone.ts`), so Braid need not use the shared background service. ## Where it meets #170 - **The last call:** v2 keeps the tool list on a step's final turn and sends `toolChoice: "none"`, "so the cached prompt prefix survives" (`specs/v2/tools.md`, `packages/core/src/session/runner/llm.ts`). That is the fix #170 made by hand. - **Instructions:** v2 never rewrites the system prompt mid-session. A changed instruction is added as a chronological message, folded into the user turn on OpenAI-compatible routes (`specs/v2/session.md`, `packages/ai/src/protocols/openai-chat.ts`): one cause of full re-prefills fewer on trogdor. - **Effort Auto:** #170's model entry per effort (`qwen3.8-27b@high` with an `id` override) becomes v2's own variants, `provider/model#high`, chosen per session, agent or command. On trogdor a session still keeps one effort, because the Qwen template writes it into the system message; v2 drops mid-session effort changes on OpenAI-compatible routes for the same cache reason (`packages/ai/src/effort-updates.ts`). On the Claude backend, Claude 5.1 and later take per-turn effort changes without losing the cache, so there Auto could change effort mid-session. - **Knowing a session is done:** `experimental.session.wait`, a race-free idle barrier, could replace Braid's quiet detection, which exists because v1 has none. It is experimental. - **Restarts:** the per-session log replays from a sequence (`after`, `follow`) and could replace much of Braid's backfill. To settle: v2 resumes the sessions it was running when it starts again, which overlaps Braid's own restart recovery. - **Handoff:** v2's compaction keeps a rolling summary and the recent context by token budget, but it still rebuilds the history, so it is a re-prefill too. It does not beat Braid's handoff note. - **Code Mode:** an agent can chain several MCP calls in one short script instead of a turn each. It could cut turns in the browser-heavy steps (browser check, judge). The gains are claims, not measurements, and Qwen 27B writing those scripts is untried. - **Parallel apply groups** (#170 section 10) don't need v2: Braid makes its own worktrees and scopes sessions by folder on v1. ## Risk v2 became the main line on 2026-10-12, and its tags went from `v2.0.5` to `v2.0.30` since. 1.x still gets fixes (1.19.2 on 2026-10-16), and 1.19 is the bridge release. ## Plan 1. A trial before any proposal: a v2 server against the fake model and trogdor's `/tokenize`, checking that the prompt prefix holds across a whole step with the last call; variants for effort; the equivalents of permissions, the outside-path rule and agent questions; the event feed and the idle barrier. 2. Then the migration as its own OpenSpec change, with #170's run as the baseline. Sources: [migration guide](https://opencode.ai/v2/docs/migrate-v1/), [The New Stack](https://thenewstack.io/?p=22840157), [explainx upgrade guide](https://explainx.ai/blog/opencode-2-0-code-mode-background-agents-shared-server-sdk-upgrade-guide-2026).
Author
Owner

opencode 2.0.30: what shipped

Braid now drives opencode 2.0.30 (@opencode/cli) on its /api, through the opencode-2 change, archived as 2026-10-16-opencode-2. It was one cutover, and the 1.x client is gone.

  • Client. Sessions are created at their step's agent, model and variant (the effort) and permissions, so a session's first prompt switches nothing. A prompt is its text and Braid's own message id. The composer's Queue asks for delivery: queue, and the last call is steered into the running turn. Questions are forms. The worktree is named by its real path.
  • Stream. osf.agent.v2 turns opencode 2's events into the events Braid already recorded, so the log, the console and the budget gauge didn't move. A stream cut by an overflow is made whole by the backfill, which tests replay on recorded cases.
  • Run config. It is written in v2's format: one variant per effort, ordered permission rules, and the run's own skills and AGENTS.md. Code Mode (execute), web search and opencode's own opencode and report skills are denied for every agent. MCP servers are written codemode: false; without it, opencode 2 offers their tools only inside Code Mode, and browser had no browser.
  • Plugins. The app tool and the guards (bounded reads, no Playwright filename, one browser at a time) are opencode 2 plugins.
  • Shapes, measured on 2.0.30. The implement floor is 16,930 characters and lean's is 10,004; on 1.18 they were 34,722 and 22,736.
  • Restarts. A server killed mid-turn sends nothing until Braid prompts, and stopping a run interrupts its sessions first.

Verified

  • Locally. The unit and live suites on 2.0.30, all 29 simulated runs, the full lane, and the rebuilt image's self-check. On the same scenarios the simulated runs took 683 s summed, against 1,080 s on 1.18.35.
  • On trogdor, from a local osfd on 2.0.30. A quick-fix run on vLLM succeeded and merged scratch PR 16; every implement turn was at its node's high variant, and its test subagent ran. A probe of the llama.cpp stack, qwen38-flash-next, worked too: a streamed tool call, reasoning and text, and the medium variant accepted.
  • On production, after the deploy (74e261c). osfd doctor reports opencode 2.0.30. In run 67 (solo, Subagents Off, llama.cpp at a fixed medium effort):
    • The run's config denies execute, websearch and both of opencode's skills, and no step called any of them.
    • The judge drove the browser itself: in its own session, no child session, its 14 allowed Playwright tools, and every one of its 64 turns at medium.
    • The run succeeded end to end, merged and archived, at 23:01Z. A forked step's first turn read 73,891 tokens from llama.cpp's prefix cache against 14,574 new, so a fork continues the session it copies without a fresh prefill.

Fixed after the deploy, from run 67 (deployed in 55f376c)

  1. A fork lost its effort. opencode 2 records a turn's variant apart from its model, so a forked step named the bare model and was switched to the default variant. Run 67's propose, both revises and apply thought at high in a medium run. The fork's model is now named with its variant.
  2. opencode's own notices were drawn as Braid's brief. opencode 2 tells the model in a synthetic user turn that a background shell or subagent ended, or to carry on after a cut-off, and the console labelled one "braid · the brief for this step". They are quiet status rows now.
  3. Live reasoning had no kind (braid#177, fixed in the same deploy). Thinking showed as answer text until it settled.

Follow-ups

  • braid#172 (parallel apply groups) builds on this.
  • Whether Code Mode pays for itself on this model is a measured change of its own.
## opencode 2.0.30: what shipped Braid now drives opencode 2.0.30 (`@opencode/cli`) on its `/api`, through the opencode-2 change, archived as `2026-10-16-opencode-2`. It was one cutover, and the 1.x client is gone. - **Client.** Sessions are created at their step's agent, model and variant (the effort) and permissions, so a session's first prompt switches nothing. A prompt is its text and Braid's own message id. The composer's Queue asks for `delivery: queue`, and the last call is steered into the running turn. Questions are forms. The worktree is named by its real path. - **Stream.** `osf.agent.v2` turns opencode 2's events into the events Braid already recorded, so the log, the console and the budget gauge didn't move. A stream cut by an overflow is made whole by the backfill, which tests replay on recorded cases. - **Run config.** It is written in v2's format: one variant per effort, ordered permission rules, and the run's own skills and `AGENTS.md`. Code Mode (`execute`), web search and opencode's own `opencode` and `report` skills are denied for every agent. MCP servers are written `codemode: false`; without it, opencode 2 offers their tools only inside Code Mode, and `browser` had no browser. - **Plugins.** The `app` tool and the guards (bounded reads, no Playwright `filename`, one browser at a time) are opencode 2 plugins. - **Shapes, measured on 2.0.30.** The implement floor is 16,930 characters and lean's is 10,004; on 1.18 they were 34,722 and 22,736. - **Restarts.** A server killed mid-turn sends nothing until Braid prompts, and stopping a run interrupts its sessions first. ### Verified - **Locally.** The unit and live suites on 2.0.30, all 29 simulated runs, the full lane, and the rebuilt image's self-check. On the same scenarios the simulated runs took 683 s summed, against 1,080 s on 1.18.35. - **On trogdor, from a local osfd on 2.0.30.** A quick-fix run on vLLM succeeded and merged scratch PR 16; every implement turn was at its node's `high` variant, and its `test` subagent ran. A probe of the llama.cpp stack, qwen38-flash-next, worked too: a streamed tool call, reasoning and text, and the medium variant accepted. - **On production, after the deploy (74e261c).** `osfd doctor` reports opencode 2.0.30. In run 67 (solo, Subagents Off, llama.cpp at a fixed medium effort): - The run's config denies `execute`, `websearch` and both of opencode's skills, and no step called any of them. - The judge drove the browser itself: in its own session, no child session, its 14 allowed Playwright tools, and every one of its 64 turns at `medium`. - The run succeeded end to end, merged and archived, at 23:01Z. A forked step's first turn read 73,891 tokens from llama.cpp's prefix cache against 14,574 new, so a fork continues the session it copies without a fresh prefill. ### Fixed after the deploy, from run 67 (deployed in 55f376c) 1. **A fork lost its effort.** opencode 2 records a turn's variant apart from its model, so a forked step named the bare model and was switched to the default variant. Run 67's propose, both revises and apply thought at high in a medium run. The fork's model is now named with its variant. 2. **opencode's own notices were drawn as Braid's brief.** opencode 2 tells the model in a synthetic user turn that a background shell or subagent ended, or to carry on after a cut-off, and the console labelled one "braid · the brief for this step". They are quiet status rows now. 3. **Live reasoning had no kind** (braid#177, fixed in the same deploy). Thinking showed as answer text until it settled. ### Follow-ups - braid#172 (parallel apply groups) builds on this. - Whether Code Mode pays for itself on this model is a measured change of its own.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
cmoriarty/braid#171
No description provided.