agent-radar
2ed3415fb7
Publish Claude Code Binaries / Stage and publish binaries (push) Canceled after 0s
Publish Tutti App Runtime / Build darwin-arm64 (push) Canceled after 0s
Publish Tutti App Runtime / Build darwin-amd64 (push) Canceled after 0s
Publish Tutti App Runtime / Build linux-amd64 (push) Canceled after 0s
Publish Tutti App Runtime / Build windows-amd64 (push) Canceled after 0s
Sync Tutti Agent Skills / sync (push) Canceled after 0s
Windows Agent Adapters / Test Windows agent adapters (push) Canceled after 0s
Windows Daemon Adapters / Test Windows daemon adapters (push) Canceled after 0s
Publish Tutti App Runtime / Publish runtime catalog (push) Canceled after 0s
62 lines
3.0 KiB
Markdown
62 lines
3.0 KiB
Markdown
# ADR 0002 — codexproto: pinning, source acquisition, drift tolerance
|
|
|
|
- Date: 2026-07-02
|
|
- Status: Accepted (grilling session)
|
|
- Context: Step 1 codegen inputs. Corroborated by two independent real
|
|
consumers: `codex-sdk-go` (Go) and `t3code/effect-codex-app-server` (TS).
|
|
|
|
## Decisions
|
|
|
|
### Pinning (Q3-A)
|
|
|
|
- codexproto is generated against an explicit **codex git commit SHA**, stamped
|
|
into `metadata_gen.go` (cf. codex-sdk-go `Source codex commit:` and t3code
|
|
`meta.gen.ts` `Upstream protocol ref:`).
|
|
- The Step-0 runtime **binary** baseline (`codex-cli 0.142.5`) and this **source
|
|
SHA** are recorded together in the bug-corpus/baseline doc. They are distinct
|
|
axes: source SHA governs the typed surface; binary version is what the daemon
|
|
actually spawns.
|
|
|
|
### Source acquisition (Q4 → option 1)
|
|
|
|
- **Vendor the upstream _already-committed_ `schema/json/*.json` at the pinned
|
|
SHA. Do NOT run the Rust `export` bin.** The schema artifacts are tracked in
|
|
the codex repo (`git ls-files codex-rs/app-server-protocol/schema/json`), so
|
|
no Rust toolchain or local codex checkout is required.
|
|
- **Eliminates design Risk #1** ("codegen toolchain depends on the Rust export
|
|
bin"). Ops-2 becomes: vendor committed schema at pinned SHA + CI re-fetches the
|
|
same ref and diffs.
|
|
- Generator = adapted `codex-sdk-go/internal/codegen` (Go, go-jsonschema), with
|
|
its `exportSchemas` (run-Rust) step **replaced** by "read vendored JSON".
|
|
|
|
### Drift tolerance (Q3-B)
|
|
|
|
- The runtime codex binary floats (auto-updates) relative to the pinned source.
|
|
The CI drift check only catches codexproto-vs-pinned-source drift, NOT
|
|
codexproto-vs-running-binary drift.
|
|
- Therefore: generated types **allow unknown fields**, and notification/server-
|
|
request dispatch keeps an explicit **unknown-method fallback** (cf. t3code
|
|
`handleUnknownServerRequest` / `handleUnknownServerNotification`) that logs and
|
|
degrades instead of crashing. This preserves the tolerance `map[string]any`
|
|
has today. Extends the Step-4 "lossless tier / degradable events" principle
|
|
down into the decode layer.
|
|
|
|
### Manual type supplement
|
|
|
|
- A hand-maintained supplement is unavoidable and universal across consumers
|
|
(codex-sdk-go `manual_types.go` 214 lines; t3code `ManualSchemas`).
|
|
- **`collaborationMode/list` is "used-but-unexported":** tutti calls it live
|
|
(`codex_appserver_adapter.go:807`, feeding `turn/start`'s `collaborationMode`),
|
|
but it is absent from upstream `ClientRequest.json` and from both reference
|
|
consumers' generated output. It goes in tutti's manual supplement — NOT
|
|
deleted, NOT expected from the generator.
|
|
|
|
## Evidence
|
|
|
|
- `git ls-files` lists `ClientRequest.json`, `codex_app_server_protocol.schemas.json`,
|
|
`…v2.schemas.json` → schema is committed upstream.
|
|
- t3code `generate.ts`: `UPSTREAM_REF` SHA + GitHub API `?ref=` fetch of committed
|
|
JSON; `ManualSchemas`; `handleUnknown*` fallbacks.
|
|
- collaborationMode exists upstream only as a ServerNotification/ThreadSettings
|
|
field, never as a `collaborationMode/list` method.
|