Skip to content

AGENTS.md

Latest commit

 

History

History
129 lines (97 loc) · 5.16 KB

AGENTS.md

File metadata and controls

129 lines (97 loc) · 5.16 KB
Raw

AGENTS.md

Guidance for AI agents and humans working in this repo.

What this repo is

@pwrdrvr/codex-app-server-protocol vendors the TypeScript types for the Codex App Server JSON-RPC protocol. Everything under src/ is generator output from codex app-server generate-ts --experimental — every file carries a // GENERATED CODE! DO NOT MODIFY BY HAND! header.

Never hand-edit src/. To change the types, regenerate from a different Codex version (below). The only files you edit by hand are package.json, README.md, PUBLISHING.md, this file, CLAUDE.md, and scripts/.

The package version mirrors the Codex CLI version

The package version equals the codex-cli version that generated src/. @pwrdrvr/codex-app-server-protocol@0.135.0 was generated by codex-cli 0.135.0. Provenance is duplicated in package.json as codexCliVersion. See the README for the full rationale and the npm-immutability caveat (no patch-bump for packaging-only fixes against an unchanged Codex surface).

Corollary: generate from an exact released version, not a prerelease. If you generate from 0.135.0-alpha.1, the honest package version is 0.135.0-alpha.1, not 0.135.0.

Clean-room regeneration procedure

This is the canonical way to bump to a new Codex version. The key idea is delete src/ first, so types the new version renamed or removed disappear from the working tree and surface as deletions/renames in the diff. A plain re-run leaves stale files behind and only ever shows additions/modifications.

1. Get the exact Codex binary you want to mirror

Pick one source. Listed best-first:

  • Exact released version from GitHub (recommended for a real release). Homebrew's codex cask is a rolling cask — it only ever offers the latest version, so it cannot pin an older exact version. Codex Desktop ships whatever the app bundles (often a -alpha). To pin an exact release, download its binary:

    VER=0.135.0
CACHE=~/.cache/pwrdrvr-codex/rust-v$VER
mkdir -p "$CACHE" && cd "$CACHE"
gh release download "rust-v$VER" --repo openai/codex \
  --pattern 'codex-aarch64-apple-darwin.tar.gz' --clobber   # arm64 macOS
tar -xzf codex-aarch64-apple-darwin.tar.gz
xattr -d com.apple.quarantine codex-aarch64-apple-darwin 2>/dev/null || true
./codex-aarch64-apple-darwin --version    # must print exactly: codex-cli 0.135.0

    (Swap the asset for your platform: *-x86_64-apple-darwin, *-aarch64-unknown-linux-musl, etc. Release tags are rust-vX.Y.Z; list them with gh release list --repo openai/codex.)

  • Codex Desktop's bundled binary (the script default), at /Applications/Codex.app/Contents/Resources/codex. Convenient, but it is whatever the installed app bundles — verify --version is a clean release before shipping it as one.

2. Run the clean-room regenerate

PWRDRVR_CODEX_BIN=~/.cache/pwrdrvr-codex/rust-v0.135.0/codex-aarch64-apple-darwin \
  pnpm regenerate

PWRDRVR_CODEX_BIN defaults to the Codex Desktop binary if unset. The script (scripts/regenerate.sh):

  1. prints the binary + --version,
  2. rm -rf src (so removals/renames show up),
  3. codex app-server generate-ts --out ./src --experimental,
  4. git add -A src,
  5. prints an A/D/M summary, the .ts file count, and the detected version.

3. Bump the version metadata to match

Set both fields in package.json to the detected codex --version:

{ "version": "0.135.0", "codexCliVersion": "0.135.0" }

Refresh the README's "Current generated source" line (version and the .ts file count printed by the script).

4. Verify

pnpm install              # if node_modules is missing
pnpm typecheck            # tsc --noEmit over the generated sources; must pass
pnpm dlx publint@0.3.21   # validate the published package shape; must pass

pnpm typecheck is the core check — it proves the generated, type-only sources compile for consumers. publint validates the published package shape (the exports map, files, types resolution) so a packaging regression fails here rather than reaching consumers. Both run in CI (and publish.yml before the npm publish), so green locally ≈ green CI.

Note: a globally-configured pnpmfile may inject a pnpmfileChecksum: line into pnpm-lock.yaml on install. The committed lockfile intentionally omits it (CI portability). If git status shows that as the only lockfile change, revert it: git checkout -- pnpm-lock.yaml.

5. Review the diff, then commit

git add -A
git status            # expect: src/ A/D/M, package.json, README.md

Sanity-check the deletions/renames are intentional (they reflect real protocol changes), then commit. Publishing is gated separately — see PUBLISHING.md.

Quick reference

Command What it does
pnpm regenerate Clean-room: delete src/, regenerate, stage, summarize. Use this.
pnpm generate Raw generator only (no delete, no stage). Won't surface removals.
pnpm typecheck tsc --noEmit over the generated sources.
pnpm dlx publint@0.3.21 Validate the published package shape (exports, files, types).