Skip to content

OpenCode v2 CLI-side (TUI) plugin half: report from the pane when the server process cannot #310

Closed

Description

@Mattheinrichs

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=1 and WMUX_CLI are present, WMUX_NODE is not (Windows path, by design in WSL) and the runtime falls back to node on PATH.
  • ui.router.current() re-fires with the viewed session (ses_…) on navigation; a viewed subagent resolves to its root, mirroring the server half's parentID skip.
  • wmux report-session <id> --provider opencode answers {"accepted": true} over the automatic npiperelay transport (connectTransport, WSL branch), and wmux agent-state lists the surface with its id.

Proposed scope, in phases

  1. Session handle (this issue's first PR): ship tui.js as a wmux-installed artifact and a way to install it. Delivers answer to "Resume OpenCode sessions on restore" for remote/shared setups.
  2. Prompt log: report the user's submitted prompt from the TUI half through the same hook.event path 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.listen event vs reactive data.session.message/pending); the shipped TUI half can log each distinct event type once under WMUX_PLUGIN_DEBUG to make that pass cheap.
  3. Blocked / activity: ui.tabs.list() (busy, attention), data.session.status(id), data.session.permission.list(id) / form.list(id) → the same report-agent declarations. Must stay idempotent declarations only: --run-start/--run-end are runDelta: ±1 refcounts, 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

  1. amirlehmam commented on Oct 20, 2026

    @amirlehmam
    Owner

    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:

    On your two open questions:

    1. Half-split policy: keep both halves, additive. The server half stays the only producer for v1 and for anything not attributable to a pane; the TUI half adds pane-attributed reporting. No wholesale move.
    2. Double prompts on a local server: rely on the renderer's identical-text window for now. A test that pins it for the two-producer case would be welcome in the phase-3 PR, if you get there.

    Phase 3 (blocked/activity): agreed on the constraint you wrote down. Idempotent report-agent declarations only, and never --run-start/--run-end from the TUI half, because two producers on one refcount would inflate it. I'm leaving this issue open to track that phase.

  2. Mattheinrichs commented on Oct 20, 2026

    @Mattheinrichs
    ContributorAuthor

    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.ts and the bundled TUI notifications plugin):

    Event Report
    permission.asked {id, sessionID, action, resources, message?} report-agent --blocked "<message ?? action>"
    permission.replied {sessionID, requestID, reply} --unblocked
    form.created {form:{id, sessionID, title}} --blocked "<form.title>"
    form.replied / form.cancelled --unblocked
    session.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 UserPromptSubmit text 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.

  3. amirlehmam commented on Oct 20, 2026

    @amirlehmam
    Owner

    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.

  4. amirlehmam commented on Oct 22, 2026

    @amirlehmam
    Owner

    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.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions