This PR introduces an opt-in gRPC transport to the OpenCode server, running alongside the existing HTTP interface. It provides a strongly-typed, backpressure-aware API surface suitable for headless clients, remote tooling, and multi-client workflows.

Scope

The gRPC transport is additive and optional. No existing HTTP behavior or APIs are changed.

What’s included

• New gRPC server transport

  • Enabled via opencode serve --grpc [--grpc-port <N>]
  • Runs concurrently with the HTTP server
  • Uses shared service logic to preserve parity

• Services exposed (opencode.v1)

  • ProjectService – list/get projects
  • SessionService – create/get/list sessions
  • EventService – server-streaming event subscription with cursor resumption
  • PtyService – bidirectional PTY streaming with strict lifecycle enforcement
  • HealthService – standard gRPC health checks

• Authentication parity

  • Mirrors HTTP auth via OPENCODE_TOKEN
  • Bearer token passed through gRPC metadata
  • UNAUTHENTICATED / PERMISSION_DENIED mapped consistently

• Workspace scoping

  • Per-RPC workspace selection via x-opencode-directory metadata
  • Defaults to process CWD when omitted

• Event persistence & resumption

  • Disk-backed event log (events.jsonl)
  • Configurable retention (count / bytes)
  • Cursor-based resume with explicit reset contract when pruned
  • EventService.Info exposes cursor bounds and retention limits

• PTY protocol guarantees

  • Explicit state machine (IDLE → OPEN → ACTIVE → CLOSED)
  • Strict validation of invalid transitions
  • Ordered output delivery before exit
  • Backpressure enforcement with deterministic termination

• Operational hardening

  • Message size limits
  • Structured metrics in logs
  • Optional gRPC reflection (env-gated)
  • Health checks for readiness

• Tests & verification

  • gRPC integration tests
  • HTTP ↔ gRPC conformance tests for shared functionality
  • PTY protocol violation tests
  • Typechecking verified

Non-goals

• No removal or deprecation of HTTP APIs
• No UI changes
• No breaking protocol changes (all protos are additive under opencode.v1)

Why this belongs in core (not a plugin)

This defines a stable transport boundary, not an internal feature:

• Required for headless and multi-client usage
• Enforces backpressure, ordering, and lifecycle semantics
• Participates in core auth, workspace scoping, and persistence
• Versioned and testable as part of the public API surface

Docs

• Added GRPC_TRANSPORT.md as the implementation and usage reference
• Includes configuration, limits, protocol semantics, and client guidance

Follow-ups

• Monitor production metrics post-release
• Collect client feedback during v1 stabilization window
• Defer any breaking changes to a future opencode.v2