From 279ca75d98b5927f79fe2efdd89ffa050e90fa44 Mon Sep 17 00:00:00 2001 From: Yvette Carlisle Date: Tue, 2 Jun 2026 18:26:12 +0800 Subject: [PATCH] {"schema":"decodex/commit/1","summary":"Record Codex app-server compatibility range","authority":"XY-698"} --- README.md | 2 ++ docs/index.md | 2 ++ docs/spec/app-server.md | 51 ++++++++++++++++++++++++++++++++++++++--- docs/spec/index.md | 3 ++- docs/spec/runtime.md | 3 ++- 5 files changed, 56 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 44184ae7..44023ead 100644 --- a/README.md +++ b/README.md @@ -91,6 +91,8 @@ Decodex follow-up, public content, or only ledger trace. - The Decodex runtime contract is Unix-only: macOS and Linux. - Windows is outside the runtime contract. +- Current Codex/app-server compatibility is capability-gated and recorded in + [`docs/spec/app-server.md`](docs/spec/app-server.md). - The public site is static and deploys through GitHub Pages. - Starting `decodex serve` without its `--config` option loads enabled projects from the explicit registry only. It does not scan Codex history, repo-local config files, diff --git a/docs/index.md b/docs/index.md index 37176521..7954155a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -30,6 +30,8 @@ The split below is by question type, not by human-versus-agent audience. - Need runtime contracts, invariants, schemas, enums, state machines, or required behavior -> `docs/spec/` +- Need current Decodex/Codex app-server compatibility range or protocol support + evidence -> `docs/spec/app-server.md` - Need public static-site contracts, GitHub bundle schemas, signal-entry schemas, or release-delta schemas -> `docs/spec/` - Need runbooks, migrations, validation steps, troubleshooting, or operational diff --git a/docs/spec/app-server.md b/docs/spec/app-server.md index 3a36d674..8c926224 100644 --- a/docs/spec/app-server.md +++ b/docs/spec/app-server.md @@ -34,9 +34,54 @@ codex app-server generate-json-schema --experimental --out target/decodex-app-se - `decodex` must treat the generated schema as more authoritative than stale handwritten assumptions. - `--experimental` is required when inspecting `dynamicTools` and related experimental fields in the generated bundle. -- As of the 2026-05 refresh, the local compatibility baseline is - `codex-cli 0.132.0-alpha.1` from `PATH` and the Codex Beta app bundle's - `codex-cli 0.131.0-alpha.9`; both expose `PluginListParams.marketplaceKinds`. + +## Compatibility range + +The current Decodex app-server support range is capability-gated rather than a broad +"latest Codex" promise. A Codex CLI or bundled Codex binary is inside the supported +range only when all of these are true: + +- `codex app-server generate-json-schema --experimental` succeeds. +- The generated schema contains the Decodex-owned request and notification contract in + this spec, including `initialize`, `thread/start`, `thread/resume`, `turn/start`, + `thread/archive`, `command/exec`, the bounded preflight methods, `item/tool/call`, + dynamic tool `namespace`, dynamic tool `deferLoading`, `inputText` tool responses, + and `PluginListParams.marketplaceKinds`. +- `decodex probe stdio://` completes the app-server capability preflight, + standalone `command/exec` health check, and dynamic-tool round trip with + `PROBE_OK`. + +As of the 2026-06-02 self-compatibility pass, the verified local range is: + +| Codex surface | Version | Evidence | +| --- | --- | --- | +| `PATH` `codex` | `codex-cli 0.136.0` | Generated `--experimental` schema contains the required methods and fields; `decodex probe stdio://` returned `PROBE_OK`. | +| Codex Beta app bundled `codex` | `codex-cli 0.136.0-alpha.2` | Running `decodex probe stdio://` with the bundle resource directory first on `PATH` returned `PROBE_OK`. | + +The same pass compared that range against upstream Codex: + +- GitHub release `rust-v0.136.0` is covered by the verified `PATH` `codex-cli 0.136.0` + probe above. +- Upstream `main` commits after `rust-v0.136.0` are outside the local support claim + until Radar review, schema regeneration, and `decodex probe stdio://` cover that + newer head or release. +- The checked-in upstream review queue generated on 2026-06-02 contained 40 queued + `openai/codex` subjects, including critical and high-priority app-server protocol, + plugin/tool metadata, sandbox/config, and release-packaging candidates. + Those queue entries are compatibility watch items, not adoption authorization. + +The previous 2026-05 local refresh covered `codex-cli 0.132.0-alpha.1` from `PATH` +and the Codex Beta app bundle's `codex-cli 0.131.0-alpha.9`. Treat those as historical +compatibility evidence, not the current upgrade target. + +Current upstream Codex signals are beyond the local support claim whenever they are +newer than the latest locally probed version, or when checked-in Radar queue entries +flag app-server protocol, plugin metadata, dynamic tool, sandbox/config, GitHub/Linear +routing, or retained-lane lifecycle risk that has not yet been source-reviewed and +probed locally. In that case Decodex must not force an upgrade. It should keep running +the latest locally verified Codex surface, route the upstream change through Radar +review, regenerate the app-server schema, run `decodex probe stdio://`, and only then +promote the new Codex version or protocol shape into this compatibility range. ## Implementation guidance diff --git a/docs/spec/index.md b/docs/spec/index.md index 136d2d15..e82115a7 100644 --- a/docs/spec/index.md +++ b/docs/spec/index.md @@ -57,7 +57,8 @@ Then keep the body explicit: - [`runtime.md`](./runtime.md) defines the runtime state model, reconciliation rules, and tracker writeback boundaries. - [`app-server.md`](./app-server.md) defines the direct Codex `app-server` interaction - contract used by the runtime. + contract, current compatibility range, and protocol support evidence used by the + runtime. - [`github-change-bundle.md`](./github-change-bundle.md) defines the normalized GitHub input model for PR-first public signal analysis. - [`signal-entry.md`](./signal-entry.md) defines the published signal-entry schema used diff --git a/docs/spec/runtime.md b/docs/spec/runtime.md index ed292b04..aba359f7 100644 --- a/docs/spec/runtime.md +++ b/docs/spec/runtime.md @@ -85,7 +85,8 @@ This boundary does not create a project-local runtime database contract. The run - Runtime policy decisions that depend on Codex behavior, such as idle timeout, stall thresholds, retry cutoffs, or liveness heuristics, must not be tuned from local Decodex observation alone. - For those decisions, use three inputs together: - - the generated `codex app-server` schema for protocol shape + - the generated `codex app-server` schema for protocol shape and the current + compatibility range in [`app-server.md`](./app-server.md) - live pilot telemetry for observed event cadence and failure modes - the relevant Codex or `app-server` implementation path for terminal semantics, waiting states, and progress signals - If those inputs disagree, treat the local implementation and generated schema as more authoritative than stale design assumptions.