docs(adapters): codex adapter docs reflect the tiered install#398
Merged
Conversation
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
github-actions
Bot
added
docs
Closed
7 tasks
dripsmvcp
force-pushed
the
docs/codex-adapter-refresh
branch
from
2b2dc4f to
3556cce
Compare
with `vouch capture ingest-codex` available, codex can self-capture the way claude-code T4 does. the ticket assumed the `notify` setting in config.toml, but codex only honours notify in user-global config — it is a restricted key in project-local layers — and the vouchdev#179 rule forbids touching ~/.codex. codex's hooks system is the project-local equivalent: `.codex/hooks.json` (loaded in trusted projects) fires Stop when a turn completes, with a payload carrying the session id and transcript path. T4 ships that file through json_merge, so an existing user hooks.json is deep-merged into, never overwritten, and re-runs don't duplicate the hook. the handler is a new --hook mode on ingest-codex: read the stop payload from stdin, resolve the session's rollout (transcript_path when present, else by session id in the rollout filename), ingest idempotently, and exit 0 no matter what — the same never-break-the- host rule capture observe follows. stop fires per turn, not per session end, so the finalize policy the ticket left open is resolved as idempotent re-ingest: the dedup guard now refreshes a session's still-PENDING proposal in place when the rollout grew (same id, updated summary, audit-logged), reports an unchanged rollout as a no-op, and never resurrects a proposal a human already decided. storage gains update_proposal, a pure-I/O in-place rewrite of a pending proposal file. wiring only — everything still lands through propose_page; nothing touches approve(). closes vouchdev#388
tests/test_openclaw_plugin_load_real.py set the pattern: exercise the real host cli when it's on PATH, skip cleanly where it isn't. the codex adapter had no equivalent, so regressions in the shipped config only surfaced when a user hit them — the old T1 silent-skip no-op is exactly the class of bug a live gate would have caught. the new suite installs the adapter into a temp project at T4, marks the project trusted inside an isolated CODEX_HOME, and asserts through `codex mcp list --json` that the vouch server is visible: next to a pre-seeded unrelated server on the merge path, alone on the fresh path, and absent for an untrusted project (the config must stay inert where codex says it does). a full-tier check covers the fenced AGENTS.md, the skills, and the Stop hook, and an isolation check pins every written artifact under the temp project. assertions target the observable contract — server listed, config parses, snippet present — not codex internals, so version bumps shouldn't break the suite. no network, no credentials, never touches the real ~/.codex; runs in the normal pytest invocation. closes vouchdev#389
three surfaces went stale once the codex tier work landed. the adapters table row described codex as a one-file config.toml snippet; it now lists the tiered install. the codex adapter readme led with the manual ~/.codex edit; it now leads with `vouch install-mcp codex`, explains the project-local .codex/config.toml choice and the trust requirement, summarizes what each tier adds (mcp wire / AGENTS.md snippet / skills / capture hook) with the merge-safety guarantees, and keeps the manual edit as an explicit fallback section. getting-started treated codex as a one-liner aside inside the claude instructions; the install section now shows both hosts side by side. the prompts-location decision from the T3 ticket and the notify restriction from the T4 ticket stay documented in their sections. no code; placeholder examples only. closes vouchdev#390
dripsmvcp
force-pushed
the
docs/codex-adapter-refresh
branch
from
3556cce to
4b93764
Compare
github-actions
Bot
added
size: L
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
closes out the codex tracking issue's docs item: with the tier work landed, three surfaces had gone stale.
the adapters table still described codex as "
config.tomlsnippet" — one file, one tier. the row now reads "tiered install:.codex/config.tomlmerge,AGENTS.mdexcerpt, skills, capture hook", matching what actually ships.adapters/codex/README.mddocumented only the manual~/.codex/config.tomledit. it now leads withvouch install-mcp codex, explains the project-local.codex/config.tomlchoice and codex's trust requirement, and summarizes each tier in a small table — mcp wire, AGENTS.md snippet, skills, capture hook — along with the merge-safety guarantees (existing config deep-merged with user-wins conflicts, fenced append, flat-noop re-runs). the T3 prompts-location decision (skills over deprecated user-global prompts, with the manual-copy escape hatch) and the T4 notify restriction (project-local hooks instead of the user-global-only notify) keep their sections, the manual-ingest commands for past sessions are shown, and the old manual edit survives as an explicit fallback section rather than the lead.docs/getting-started.mdmentioned codex once, inside themcp addone-liner. the install section now shows the two hosts side by side (vouch install-mcp claude-code/vouch install-mcp codex) with a line on idempotence and merge safety; the quickmcp addone-liner stays for the config-free path.no code, lowercase prose matching the existing adapter readme voice, placeholder examples only. no remaining references to the old copy-only behavior — grepped the readme, getting-started, and the adapters table.
stacks on the codex chain (#392–#397); merge last so the docs never describe unlanded behavior.
closes #390