Repository navigation
V2: define protocol/schema boundary for API payloads #34362
Description
Summary
Define the ownership boundary between packages/schema and packages/protocol for V2 API contracts.
Why
Current V2 protocol groups often import API-ish input types directly from @opencode-ai/schema, while core services sometimes accept the same shapes. This makes it unclear which package owns the external contract vs reusable domain/leaf schemas.
Examples to review
PromptInput.Promptused bysession.promptSessionInput.Admittedused as a protocol responseProjectCopy.CreateInputpartially omitted to build a protocol payloadPty.CreateInputused directly as a protocol payloadQuestion.ReplyandPermission.Replyused directly or wrapped
Proposed direction
- Keep reusable domain/leaf schemas in
packages/schema. - Put endpoint payload/query/response wrappers in
packages/protocol. - Compose protocol wrappers from schema pieces rather than duplicating leaf schemas.
- Add named protocol schemas where they improve OpenAPI/client generation and reviewability.
Acceptance criteria
- Document the boundary rule.
- Audit
packages/protocol/src/groups/*for inline/imported payloads. - Introduce named protocol-level wrappers for central session endpoints where useful.
- Check generated client types for regressions or improvements.
Activity
opencode-agent commentedon Jul 2, 2026
Tracker update from V2 release-prep discussion (2026-07-02):\n\nRelated new pre-beta audit issue: https://github.com/anomalyco/opencode/issues/34832\n\nThe broader schema-boundary work should feed into that audit, especially event names/versions, protocol payload ownership, and any durable schema decisions that become expensive after beta users exist.
Dante-dan commentedon Oct 1, 2026
I implemented a bounded first slice of the ownership rule requested here: fixed reference patch.
The new Protocol README documents reusable domain contracts versus HTTP wrappers and records the current group patterns: canonical domain values, path/query adaptation, response envelopes, public location projections, and transport contracts.
session.promptnow uses namedSessionPromptPayloadandSessionPromptResponsewrappers. They compose the same Schema values and preserve the existing fields, optionality, errors, and encoded shapes; no schema identifiers were added.My October 1 survey used older contract names. On current dev, the prompt result is
SessionInbox.User, replacingSessionInput.Admitted.PromptInput.Promptand the inbox domain contracts stay in Schema;project.updatekeeps its route-ID omission in Protocol. This patch does not move reusable inputs or alter the event/versioning work consolidated into #34922.Verification: Protocol tests (9) and Schema tests (89) pass; Protocol and Client typechecks and the normal pre-push checks (35 tasks) pass. Client generation completed with no generated Promise/Effect diff. The full Client suite had 237 passing tests and one timeout in the existing “fragmented SSE event below the size limit” test; that test also timed out when run alone with the package's 5-second timeout. This is a partial session-only contribution, not a claim that every remaining boundary concern is resolved.