feat(simulation): add endpoint handshake protocol

[kitlangton]

What

Add a canonical simulation.handshake request to both simulation WebSocket endpoints so controllers can detect protocol skew before issuing UI or LLM operations.

The handshake reports:

• Endpoint role: ui or backend
• Simulation protocol version
• Running OpenCode version
• Capabilities actually installed by that endpoint

Clients declare offered protocol versions plus required and optional capabilities. OpenCode rejects role mismatches, unsupported versions, and missing required capabilities with typed failures.

How

• packages/simulation/src/protocol/index.ts defines the shared handshake schemas, typed errors, dispatch validation, and canonical endpoint capability lists.
• packages/simulation/src/frontend/server.ts handles the handshake before UI operations and advertises the installed frontend handlers.
• packages/simulation/src/backend/simulated-provider.ts handles the same request on the LLM controller endpoint.
• Protocol schemas reject empty identities/capabilities, empty or duplicate version offers, non-positive versions, and duplicate capability declarations.
• Simulation specs document negotiation and recommend handshaking before endpoint-specific requests.

Scope

This retains the existing JSON-RPC transport and all current method payloads. It does not migrate simulation control to Effect RPC, add tool lifecycle simulation, or extract a shared protocol package.

Older controllers remain compatible because the new method is additive. Controllers that require negotiation can fail early against older OpenCode builds; controllers that support a legacy profile can explicitly fall back.

Testing

• bun run typecheck in packages/simulation
• bun test in packages/simulation: 25 tests
• Repository pre-push typecheck: 32 packages
• Frontend WebSocket handshake integration
• Backend WebSocket handshake integration
• Protocol decoding and validation for success, role mismatch, unsupported versions, missing required capabilities, malformed version offers, and duplicate declarations

Flow

sequenceDiagram
  participant Drive as Simulation controller
  participant Endpoint as OpenCode UI or backend

  Drive->>Endpoint: simulation.handshake<br/>role, versions, required + optional capabilities
  Endpoint->>Endpoint: Validate role and select protocol v1
  Endpoint->>Endpoint: Verify required capabilities are installed
  alt compatible
    Endpoint-->>Drive: role, OpenCode version, protocol v1, capabilities
    Drive->>Endpoint: ui.* or llm.* operations
  else incompatible
    Endpoint-->>Drive: typed JSON-RPC failure
  end

Loading