Define Code Bridge protocol, trust, and payload contract #45

Current Status

Updated 2026-06-14 by Code.

State: Implementation PR open: #88 defines the first Code Bridge protocol contract in a standalone codex-code-bridge-protocol crate. The slice covers the versioned envelope, hello/helloResponse/heartbeat/event/subscribe/ack/error/screenshot/control message families, bounded console/error/pageview/screenshot/control-result events, screenshot and JavaScript control commands, local descriptor shape under the resolved Codex Lab home, loopback/local endpoint validation, auth-secret validation, payload caps, model-visible summary caps, and explicit capability helpers for screenshot and JavaScript control.

Validation completed locally before opening PR #88:

• cargo test -p codex-code-bridge-protocol
• cargo fmt --all -- --check
• git diff --check

Agent review found three contract issues before PR creation: missing hello response payload family, screenshot response conflicting with the 64 KiB normal message cap, and missing descriptor endpoint validation. All three were fixed and covered by regression tests before the commit.

Next action: wait for PR #88 CI. If it passes, merge #88 and close this issue. After #45 lands, #46 is unblocked for the minimal Code Bridge service skeleton.

Acceptance Criteria

• Defines producer, subscriber, and service-control message families for the MVP: hello, heartbeat, event publish, screenshot request/response, control request/response, subscribe, ack, and error.
• Event families are explicitly limited to console, error, pageview, screenshot, and control-result for the first slice.
• Local trust model is documented: bind scope, auth token/secret handling, client role separation, and fail-closed behavior.
• Hard caps are named for message size, retained event count, screenshot size/encoding, control timeout, and model-visible summaries.
• Product-specific fields for discord-blue or Launchplane are excluded from the core protocol; source/provenance metadata is generic and bounded.
• The contract states whether the first artifact lives in a new bridge protocol crate or app-server-protocol-adjacent schema, and why.

Target Surface

Codex Lab planning/design first. Likely implementation target: a new codex-rs/code-bridge-protocol crate or similarly isolated protocol module that avoids codex-core and avoids app-server product coupling.

Validation Gate

Review against AGENTS.md model-visible context rules, app-server v2 payload conventions, restored Every Code Code Bridge evidence, and discord-blue bridge compatibility constraints. No runtime code should begin until this contract is accepted.

Risks

Over-scoping the protocol is the biggest risk. The first contract should describe the app telemetry/control bridge, not remote inbox, Discord session threads, or Launchplane work-request orchestration.

Finish Line

A versioned Code Bridge wire contract exists with local trust assumptions, payload caps, event/control families, and compatibility rules before daemon or product-adapter implementation starts.