Repository navigation
Description
What
wmux ships one half of the OpenCode integration: the server-side plugin at ~/.config/opencode/plugin/wmux.js. When the TUI is a client of a remote server, or of v2's shared opencode serve --service, that half cannot attribute anything to a pane: the server process has no WMUX_SURFACE_ID, and on a shared server it has exactly one pane's. The docs already record the consequence for session handles ("Session handle for restore" → shared background server reports nothing), and #305's prompt capture inherits the same limit.
The missing half is the CLI-side (TUI) plugin proposed in #290: OpenCode v2 loads it in the TUI process, against a remote server, with the pane's WMUX_* environment. wmux has no support for it today — src/ has zero handling of <config>/plugins/ or cli.json, and opencode-context.ts installs the one server file.
Live verification of the prototype (hand-installed at <config>/plugins/wmux-cli/tui.js, prototype posted in #290):
- Windows wmux + a WSL pane whose TUI is a client of a remote OpenCode server (
opencode2 --server https://…) — the shipped server-side half never runs there. - The plugin loads once per TUI process;
WMUX=1andWMUX_CLIare present,WMUX_NODEis not (Windows path, by design in WSL) and the runtime falls back tonodeon PATH. ui.router.current()re-fires with the viewed session (ses_…) on navigation; a viewed subagent resolves to its root, mirroring the server half'sparentIDskip.wmux report-session <id> --provider opencodeanswers{"accepted": true}over the automatic npiperelay transport (connectTransport, WSL branch), andwmux agent-statelists the surface with its id.
Proposed scope, in phases
- Session handle (this issue's first PR): ship
tui.jsas a wmux-installed artifact and a way to install it. Delivers answer to "Resume OpenCode sessions on restore" for remote/shared setups. - Prompt log: report the user's submitted prompt from the TUI half through the same
hook.eventpath feat(opencode): report submitted prompts to the prompt log via v2's admission hook (#304) #305 made end-to-end (wmux hook --event UserPromptSubmit --prompt). Needs one diagnostic pass to pick the client-side signal (data.listenevent vs reactivedata.session.message/pending); the shipped TUI half can log each distinct event type once underWMUX_PLUGIN_DEBUGto make that pass cheap. - Blocked / activity:
ui.tabs.list()(busy,attention),data.session.status(id),data.session.permission.list(id)/form.list(id)→ the samereport-agentdeclarations. Must stay idempotent declarations only:--run-start/--run-endarerunDelta: ±1refcounts, so a second producer reporting for the same pane would inflate them.
Installation (proposed): an in-pane CLI verb, not a Windows-side WSL write
wmux opencode-tui [--remove], run from the pane that will host the TUI. It resolves $XDG_CONFIG_HOME / $HOME in the environment it actually runs in (WSL distro, devcontainer, native Windows), copies tui.js from the shipped resources/opencode-plugin/, and compares the // wmux-plugin-version: marker like pluginNeedsUpdate does. Removal is guarded by isWmuxPluginFile.
Why not have Windows write into \\wsl.localhost\<distro>\home\… automatically: it needs distro/user discovery, silently writes into arbitrary homes (the #132 consent question at another level), has no precedent in src/, and cannot work for devcontainers at all. The in-pane verb covers every environment with one mechanism, and the user has already chosen the pane. Native-Windows auto-install can ride agent-integration.ts later if wanted; it would call the same copy function.
Known questions for the maintainer
- Half-split policy once both exist: keep the server half for v1 and non-pane-attributed signals, move pane-attributed reporting to the TUI half — or let both report and rely on idempotent declarations + the prompt log's identical-text window? (Proposal: keep both for now; the TUI half is additive.)
- Double prompts when both halves run on a local server: the renderer's 1500 ms identical-text dedupe (
AGENT_DEDUPE_MS) should absorb it; worth a test rather than new coordination.
Activity
docs(opencode): a backup inside plugins/ shadows the live TUI half (a…
feat(opencode): CLI-side (TUI) half — session handles from inside the…
feat(opencode): TUI half reports user prompts via session.inbox.enque…
docs(opencode): a backup inside plugins/ shadows the live TUI half (a…
feat(opencode): TUI half reports user prompts via session.inbox.enque…
amirlehmam commentedon Oct 20, 2026
Thanks a lot @Mattheinrichs — phases 1 and 2 are merged (#311, #312) and ship in v2.31.0, which is building now.
Notes from the review:
wmux opencode-tuiinstall → current → remove → absent against a tempXDG_CONFIG_HOMEfrom the built CLI. The live WSL + remote-server verification you posted is what settled it; thanks for doing that, and for theplugins/*.bakshadowing finding.On your two open questions:
Phase 3 (blocked/activity): agreed on the constraint you wrote down. Idempotent
report-agentdeclarations only, and never--run-start/--run-endfrom the TUI half, because two producers on one refcount would inflate it. I'm leaving this issue open to track that phase.Mattheinrichs commentedon Oct 20, 2026
Phase 3 plan, split the way phases 1/2 landed — two small PRs, blocked first.
3a — blocked ("Needs you")
Events (matching
packages/schema/src/permission.tsand the bundled TUI notifications plugin):permission.asked{id, sessionID, action, resources, message?}report-agent --blocked "<message ?? action>"permission.replied{sessionID, requestID, reply}--unblockedform.created{form:{id, sessionID, title}}--blocked "<form.title>"form.replied/form.cancelled--unblockedsession.execution.interrupted/.failed--unblocked(mirrors the server half's error/interrupt)Same hosted-session scoping as prompts (viewed session or open tab), dedupe by permission/form id, and the #188/#189 rule: never unblock on tool or streaming events — only explicit replies/cancels and turn-ending failures. This also carries the two-producer prompt test you asked for: identical
UserPromptSubmittext inside the renderer's 1500 ms window → one entry, outside → two.3b — activity
session.execution.started→report-agent --run-depth 1;succeeded|failed|interrupted→--run-depth 0. Absolute values, so the second producer converges instead of inflating — no--run-start/--run-end, per your note. Hosted sessions only; tool labels stay out of this.Plugin marker 2 → 3 in 3a (installed halves update via
wmux opencode-tui). Say if you'd rather have it as one PR; otherwise 3a comes first.feat(opencode): TUI half reports blocked state from permissions and f…
fix(opencode): TUI blocked state tracks each open ask (#310)
amirlehmam commentedon Oct 20, 2026
Phase 3a merged (#314) and ships in v2.33.0, with a follow-up (01df550) that tracks each open ask by id; details in #314. Keeping this open for 3b.
feat(opencode): TUI half declares working/idle from execution events (#…
amirlehmam commentedon Oct 22, 2026
Phase 3b (working/idle from
session.execution.*, absolute--run-depth, never--run-start/--run-end) merged in #317 and shipped in v2.34.0, so every phase planned here is done. Closing. Thanks @Mattheinrichs for carrying the whole CLI-side half. The known gap (a turn already running when the TUI starts shows up only from the next turn) is in the 2.34.0 notes; a new issue is welcome if it matters in practice.