Skip to content

feat(opencode): CLI-side (TUI) half — session handles from inside the pane (#310) - #311

Merged
amirlehmam merged 1 commit into
amirlehmam:masterfrom
Mattheinrichs:feat/opencode-tui-half
Oct 20, 2026
Merged

amirlehmam merged 1 commit into
amirlehmam:masterfrom
Mattheinrichs:feat/opencode-tui-half

Conversation

@Mattheinrichs

Copy link
Copy Markdown
Contributor

Why

The server-side plugin cannot attribute anything when the TUI is a client of a remote OpenCode server, or of v2's shared opencode serve --service for another pane: the server process has no pane's environment, and on a shared server it has exactly one pane's. The docs already record that for session handles, and #304's prompt hook inherits it. The missing half was proposed in #290 and verified live on Windows wmux + a WSL pane against a remote server: a CLI-side (TUI) plugin, loaded once per TUI process, with the pane's WMUX_*.

What this PR adds (phase 1 of #310)

  • wmux opencode-tui [--remove] — a local file operation, deliberately not a pipe command. It runs from the pane that will host the TUI, so the config directory it resolves is the distro/container/native home the TUI actually reads. It honours an absolute $XDG_CONFIG_HOME, else ~/.config/opencode, and writes <config>/plugins/wmux-cli/{tui,core}.js — the directory form OpenCode's CLI resolves without a package.json, live-verified in Resume OpenCode sessions on restore, alongside Claude Code and Codex #290.
  • The Windows side never writes WSL homes: that needs distro/user discovery, silently writes into arbitrary homes (the wmux modifies global claude settings without permission and/or warning #132 consent question at another level), and cannot serve devcontainers. The in-pane verb covers every environment with one mechanism.
  • resources/opencode-plugin/wmux-tui.js — the entry, the shape verified in Resume OpenCode sessions on restore, alongside Claude Code and Codex #290 (Plugin.define, ui.router.current() followed with createRoot/createEffect, no polling). Reports the viewed session via wmux report-session <id> --provider opencode, resolves a viewed subagent to its root (the server half's parentID skip), dedupes per session, and releases the handle on dispose/exit. Marker 1; --remove refuses a tui.js without it.
  • resources/opencode-plugin/wmux-tui-core.js — runtime resolution (WSL has no usable WMUX_NODE, so PATH falls back like the server half), the file logger (OpenCode plugin: log to file instead of console.error so agents can self-diagnose #190), the CLI caller, and the route→report rules. Node builtins only, so wmux's suite can load it; the entry carries just the two host-provided imports (@opencode/plugin/tui, solid-js).
  • Distinct TUI event types are logged once each under WMUX_PLUGIN_DEBUG — the one-pass diagnostic that will pick the client-side signal for phase 2 (the prompt log). Until then prompts and blocked/activity remain server-half features and are unchanged.
  • Packaging: opencode-tui-install.js added to resources/cli/ and extraResources (the packaging test derives it from the new relative import); resources/opencode-plugin/ already ships as a directory.

Verification

Open question for the maintainer

The half-split policy once both halves exist: keep the server half for v1 and non-pane-attributed signals and let this one add pane-attributed reporting (phase 2/3), or move attribution over wholesale? This PR is additive only — nothing the server half reports today changes.

Part of #310

… pane (amirlehmam#310)

The server-side plugin cannot attribute anything when the TUI is a client of
a remote OpenCode server, or of v2's shared `opencode serve --service`: the
server process has no pane environment, and on a shared server it has exactly
one pane's. The documented consequence is that "Resume OpenCode sessions on
restore" never captures a handle on those setups.

This adds the half that runs in the TUI process, against a remote server,
with the pane's WMUX_*: `wmux opencode-tui` installs `tui.js` + `core.js` to
<config>/plugins/wmux-cli/ from inside the environment that will host the TUI
(WSL distro, devcontainer, native Windows), honouring an absolute
XDG_CONFIG_HOME; `--remove` is guarded by the version marker. The Windows side
never writes WSL homes — that would need distro/user discovery, would write
into arbitrary homes, and cannot serve containers.

It reports the viewed session (`report-session`, subagents resolved to their
root, release on quit) by following `ui.router.current()` reactively. The core
is a plain ESM module importing node builtins only, so the wmux suite can load
it; the entry is the reactive glue OpenCode's host resolves. Unique event
types are logged once under WMUX_PLUGIN_DEBUG — the one-pass diagnostic the
prompt-log phase needs.

Part of amirlehmam#310
@Mattheinrichs

Copy link
Copy Markdown
Contributor Author

Live verification of this half on Windows wmux 2.30.0 + a WSL pane whose TUI is a client of a remote OpenCode server (@opencode/cli TUI 2.0.26):

  • wmux opencode-tui installed v1, re-run reported already current, and --remove is marker-guarded — as designed.
  • With the v2 branch (feat(opencode): TUI half reports user prompts via session.inbox.enqueued (#310) #312) installed, the half loads in the TUI process and reports the viewed session: init {surface, runtime, cli}, session ses_…, cli ["report-session", …] ok. This is the case the server-side plugin cannot serve: the server process has no WMUX_SURFACE_ID.
  • wmux report-session / release-agent probed directly against the same main create and remove the record (sessionId + sessionProvider: opencode), so record + release work end to end.

One environment finding worth recording: OpenCode loads every directory directly under <config>/plugins/ as a plugin, so keeping a backup as plugins/wmux-cli.bak/ registers the same wmux.cli id and shadows the live copy — the symptom is complete silence (no init, no reports). The fix is to keep backups outside plugins/; I've added that warning to the TUI-half docs in #312's branch (this PR's docs section predates it).

Phase 2 (prompt log, #312) was verified on top of this branch and is marked draft until this merges.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants