[idea] Add native OpenCode 2 beta integration

[Akram012388]

idea / problem

OpenCode 2 is available as the separate opencode2 beta executable. Herdr 0.7.5 accepts herdr integration install opencode, but that installer writes the V1 plugin shape. OpenCode 2 requires a default { id, setup } V2 plugin, so the installed integration is not activated there.

I locally ported it and confirmed Herdr reports the OpenCode session ID and lifecycle state with opencode2 v0.0.0-next-16365.

The V2 plugin API is still beta, so the integration may need to track API changes until 2.0 is stable.

Screenshot of the local proof:

update: multi-pane attribution bug

Testing two simultaneous OpenCode 2 TUIs exposed a cross-pane bug in the first proof. A TUI plugin is pane-scoped, but ctx.data.listen can still receive events for sessions owned by other TUI panes. Without ownership filtering, both panes can report another pane's session ID and Herdr animates the wrong agent row.

The corrected local integration now:

• loads only as a TUI plugin through ~/.config/opencode/cli.json
• prevents the auto-discovered file from running as a shared server plugin
• binds reports to the active root session in the TUI process's working directory
• resolves child sessions through ctx.data.session.root()
• ignores events outside that session family
• resynchronizes when the TUI route changes

Verified with ~/.config/opencode and orfloat-admin open simultaneously: each Herdr pane now reports its own OpenCode session ID and idle state.

requested change

Please add a native opencode2 integration target during beta, or make the existing opencode installer version-aware.

The V2 integration should be loaded as a TUI plugin through ~/.config/opencode/cli.json, not as an auto-discovered server plugin. OpenCode 2's background server is shared, while HERDR_PANE_ID and HERDR_SOCKET_PATH are pane-scoped in the TUI process. TUI process scoping alone is insufficient because session events still require explicit ownership filtering.

Suggested event mapping:

• session created, updated, and status events: register the session and state
• execution started and admitted input: working
• execution succeeded, interrupted, and idle: idle
• permission, question, or form requests: blocked
• replies and cancellations: working

It should include status and uninstall handling, detect the opencode2 executable, and coexist with V1 while the beta uses a separate name.

why you want this

This would make Herdr's built-in integration work with OpenCode 2 without requiring users to maintain a local compatibility plugin. Correct session-family filtering keeps multi-pane state transitions and session restoration reliable with the shared service architecture.

Related, but distinct: #1885 asks for multiple OpenCode sessions per pane. This request is specifically for OpenCode 2 API compatibility.

[Akram012388]

Verification update: deterministic route ownership and teardown

I reproduced a stronger version of the multi-pane bug with two OpenCode 2 TUIs in the same cwd. The focused conversation belonged to one pane, but the cwd/latest-session fallback attributed its session ID to the other pane. Cwd filtering is therefore not an ownership boundary and should be removed rather than refined.

For the installed { id, setup } TUI runtime, I confirmed from the next-16370 build and at runtime that:

• ctx.ui.router.current() is pane-local and returns { type: "session", sessionID } for the active conversation
• the cleanup function returned by setup is awaited during TUI shutdown
• shared ctx.data.listen events still need filtering to the root family of that pane-local route

The corrected local integration now:

• treats the pane-local session route as the only session authority, with no argv, cwd, or latest-session fallback
• resolves child events through ctx.data.session.root() and ignores other session families
• reports each route binding with session_start_source: "new", Herdr’s supported OpenCode replacement signal, so switching sessions replaces the prior same-owner reference instead of being rejected as cross-talk
• serializes all Herdr reports so sequence order is deterministic
• clears stale ownership once during initial home setup, clears only its local binding when no session route is active, and sends pane.release_agent as the final awaited setup cleanup request

Verification on Herdr 0.7.5:

• a deterministic fake-socket Node test covers home-route isolation, route binding, route unbinding/rebinding, replacement signaling, monotonic sequence order, and final teardown release
• a disposable Herdr pane running OpenCode 2 next-16378 stayed unattributed on the home route
• launching that pane with a fresh session produced the exact route session ID, idle, and screen_detection_skipped: true
• exiting with Ctrl+C removed the pane from agent list, cleared agent_session, and logged the final pane.release_agent; no standalone process remained

One Herdr lifecycle detail mattered during testing: reusing the exact session ID immediately after releasing it is intentionally suppressed as a stale same-process report. A fresh session ID reacquired authority correctly. This is expected stale-resurrection protection, not an OpenCode attribution failure. For the same reason, pane.release_agent must be reserved for a TUI process-generation boundary, not an ordinary route transition.

The native V2 integration should therefore use route identity only and must return a teardown cleanup that releases the pane.

[phall1]

chiming in since i hit exactly this — opencode2 is more than a rename: the v1 plugin file doesn't load on v2 at all (different registry shape), so even with the symlink trick you lose lifecycle reporting and session restore and fall back to the screen manifest.

while waiting on a native integration i got both hosts covered from one plugin: @phux/herdr-opencode (https://github.com/no-phux/herdr-opencode). v1 uses the event hook, v2 uses ctx.event.subscribe(), both report the same socket methods herdr's stock integration uses, and the root/child session filtering is fixed for the 1.18+ event shape. maybe useful as a reference implementation for the native one.