Define V2 plugin API for server metadata #36116

Summary

Define the OpenCode V2 plugin API contract for server metadata contributed by plugins and consumed by mobile/pairing clients.

This should not be modeled as QR-specific metadata, and it probably should not be a general /api/server mutation endpoint either. The durable concept is plugin-contributed server metadata; QR/pairing can consume a snapshot or reference from that plugin API-owned contract.

A possible shape is producer-owned metadata under the plugin id:

{
  "metadata": {
    "acme-mobile": {
      "capabilities": ["handoff"],
      "displayName": "Ryan's MacBook"
    }
  }
}

Proposed direction

• Core service owns server identity, pairing, auth, and compatibility fields.
• The plugin API exposes a way for plugins to contribute public server metadata at metadata[plugin.id].
• A plugin can only write its own key.
• Duplicate plugin ids are rejected at plugin registration/load time.
• Metadata values are JSON-serializable objects, not arbitrary scalars.
• Plugin metadata is public client hint data, not authority.
• No credentials, bearer tokens, private payloads, or authorization decisions belong in metadata.
• QR generation can include a snapshot of this metadata or a reference to fetch it, but QR encoding should not be the owning mutation boundary.
• If a plugin needs to affect trust or pairing behavior, use a separate server-side hook such as pairing.authorize or pairing.complete; do not overload metadata.

Plugin API shape to consider

Prefer plugin-owned contribution over a generic client PATCH endpoint. For example:

plugin({
  id: "acme-mobile",
  hooks: {
    "server.metadata": () => ({
      capabilities: ["handoff"],
      displayName: "Ryan's MacBook",
    }),
  },
})

or a replayable/scoped registration if that better matches V2 plugin lifecycle:

const update = yield* ServerMetadata.contribute()
yield* update({ capabilities: ["handoff"] })

The important boundary: the plugin API owns contribution and cleanup semantics; ordinary server API clients should not get ambient authority to patch arbitrary plugin metadata keys.

Alignment with existing V2 metadata style

This matches the multi-producer metadata style already present in V2 provider metadata:

Record<string, Record<string, unknown>>

Provider examples use top-level producer keys such as openai, anthropic, google, and bedrock. Generic single-owner metadata elsewhere can remain a flat Record<string, unknown>, but server/plugin metadata has multiple independent producers, so the top-level key should identify the producer.

Open questions

• Is this metadata global to the running server, location-scoped, or pairing-session-scoped?
• Should plugin metadata contribution be append-only return values, mutable draft hooks, catalog-style replayable transforms, or scoped registration?
• What is the total payload size budget, and what is the per-plugin budget?
• Should missing/failing plugin metadata fail server/QR metadata generation, get omitted with diagnostics, or be policy-selectable?
• Do we need canonical ordering for deterministic signatures and stable QR output?
• What metadata, if any, should the mobile client understand initially versus preserve/ignore as opaque plugin hints?

Acceptance criteria

• A typed schema exists for plugin-contributed server metadata.
• Plugin contributions are namespaced by stable plugin id.
• Core server and pairing fields cannot be mutated through plugin metadata.
• Invalid, oversized, or non-object plugin metadata is rejected or omitted according to a documented policy.
• The QR/pairing path consumes server metadata through the same contract rather than owning a separate ad hoc metadata shape.
• Tests cover namespacing, duplicate ids, invalid metadata, size limits, and unknown metadata ignored by clients.

Source discussion

Slack thread: https://slack.com/archives/C0BE69AHCQP/p1783614034749019