Skip to content

Plan OpenCode V2 plugin API support #55

Description

@DanRioDev

Context

OpenCode V2 is currently beta and intentionally does not load V1 plugins. The migration guide describes the new plugin shape (Plugin.define({ id, setup })) and runtime registration APIs: https://opencode.ai/v2/docs/migrate-v1

opencode-pty currently targets the V1 contract in src/plugin.ts, exporting an async plugin function with PluginContext / PluginResult and depending on @opencode-ai/plugin ^1.3.13.

This issue is a planning request, not an expectation that unstable V2 support ship immediately.

Suggested port plan

  • Keep the current V1 entry point while V2 remains beta; add a separate V2 entry point/export.
  • Replace the V1 async plugin export with a unique V2 id and setup.
  • Register PTY tools through the V2 tool transform/registration surface, preserving existing schemas and descriptions.
  • Map command handling and session notifications to V2 command/session APIs.
  • Review process ownership and cleanup against V2 session interruption, service restart, and standalone/managed modes.
  • Avoid sharing host-specific client calls between V1 and V2; keep the PTY/process core shared and adapters thin.

Compatibility checks

  • Plugin appears in opencode2 api get /api/plugin.
  • PTY creation, input, resize, output polling, and termination work in opencode2 --standalone.
  • Managed service mode behaves the same as standalone mode.
  • Session interruption and service shutdown leave no orphan process.
  • Invalid or expired PTY IDs return bounded errors rather than crashing the host.
  • Existing V1 tests and package entry point remain unchanged.

Would V2 support be in scope once the API settles? I can help test a branch against current opencode2 previews.

Activity

  1. BananaAcid commented on Aug 28, 2026

    @BananaAcid

    would love to see this. especially the options for plugins. and being able to fix the port there - allowing me to add plugin and specific port in main opencode.json to be set for all projects.

  2. kumar-shivang commented on Sep 18, 2026

    @kumar-shivang
    Contributor

    I have implemented OpenCode V2 plugin support in #59!

    Highlights:

    1. Decoupled Adapter Layer: Core PTY management and permissions dispatching are now host-agnostic via clean interfaces (SessionNotifier, PermissionAuthorizer, HostAdapter).
    2. Dedicated V2 Entrypoint: Added opencode-pty/v2 export conforming to Plugin.define({ id: "opencode-pty", setup }) while preserving 100% backwards compatibility for V1.
    3. Configurable Port & Options: Supported plugin options via ctx.options (addressing @BananaAcid's request). You can now configure a fixed port and hostname in opencode.json:
      {
        "plugins": [
          {
            "package": "opencode-pty/v2",
            "options": {
              "port": 4200,
              "hostname": "127.0.0.1"
            }
          }
        ]
      }
    4. Command Transforms & Cleanup: Slash commands (/pty-open-background-spy, /pty-show-server-url) are registered via ctx.command.transform, and session cleanup is hooked up to prevent orphan processes.
    5. Live Verification: Tested and validated live against the opencode2 CLI and external plugin loader specifications.
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