@pwrdrvr/codex-app-server-protocol

TypeScript types for the Codex App Server JSON-RPC protocol, generated from the locally-installed Codex CLI via codex app-server generate-ts --experimental. The experimental protocol surface is included.

These are the raw App Server protocol types — the low-level JSON-RPC interface Codex exposes for embedding. This is not @openai/codex-sdk (a higher-level wrapper that spawns codex exec and emits a one-way event stream with no client-registered tools, approval routing, or experimental surface). OpenAI documents and supports the App Server protocol but ships its types only as a per-version generate-ts artifact rather than a package — so we vendor them here.

The contents of src/ are generator output — do not hand-edit. Every file in src/ and src/v2/ carries a // GENERATED CODE! DO NOT MODIFY BY HAND! header.

Versioning — the package version mirrors the Codex CLI version

This package's version equals the codex-cli version that generated it. So @pwrdrvr/codex-app-server-protocol@0.135.0 was generated by codex-cli 0.135.0. Provenance is also recorded in package.json:

{
  "version": "0.135.0",
  "codexCliVersion": "0.135.0",  // the codex-cli that generated src/
  "codexExperimental": true       // generated with --experimental
}

Query it without installing:

npm view @pwrdrvr/codex-app-server-protocol codexCliVersion

Caveat (important): because npm versions are unique and immutable, the mirror scheme has no room for a packaging-only re-release against the same Codex version. If src/ is unchanged but packaging needs a fix, ship it when the next codex-cli version lands, or publish iterations under a prerelease dist-tag (0.133.0-next.N on next) and promote the clean 0.133.0 to latest once happy. Do not bump the patch to 0.133.1 for a packaging fix — that would falsely imply a Codex 0.133.1 surface.

Current generated source: codex-cli 0.135.0 (591 generated .ts files; v1 surface in src/, v2 surface in src/v2/).

Install

pnpm add @pwrdrvr/codex-app-server-protocol

The package ships type-only TypeScript source (every export is export type). It targets consumers using moduleResolution: "bundler" (or node/classic) — the generated imports are extensionless, so a nodenext consumer would need to resolve them via a bundler. All @pwrdrvr/* and PwrDrvr apps use bundler resolution. There is no build step and no runtime JavaScript: the types erase completely at compile time.

Subpath exports

Import path	Maps to	Use for
@pwrdrvr/codex-app-server-protocol	src/index.ts	v1 protocol surface
@pwrdrvr/codex-app-server-protocol/v2	src/v2/index.ts	v2 protocol surface (preferred — has DynamicToolCall*, ContentItem with image, ThreadRealtime*, and the newer thread/turn/item surface)

Regenerating

Use the clean-room procedure — it deletes src/ first, so types the new Codex version renamed or removed surface as deletions/renames in the diff (a plain re-run leaves stale files behind):

pnpm regenerate

This runs scripts/regenerate.sh: delete src/ → codex app-server generate-ts --out ./src --experimental → git add -A src → print an added/deleted/modified summary. By default it uses Codex Desktop's bundled binary (/Applications/Codex.app/Contents/Resources/codex); override to pin an exact released version:

PWRDRVR_CODEX_BIN=/path/to/codex pnpm regenerate

pnpm generate is the raw generator (no delete, no staging) — prefer pnpm regenerate. After regenerating, bump version and codexCliVersion to match codex --version and refresh the "Current generated source" line above. Regenerate whenever Codex publishes a new version a consumer wants, or codexCliVersion drifts from the codex --version you intend to mirror.

The full step-by-step procedure (binary selection, version bump, verify, commit) lives in AGENTS.md.

Source of truth

The Rust source for the protocol lives in the Codex repo under codex-rs/app-server/. The generator emits one TS file per Rust type, plus barrel index.ts files.

License

MIT © PwrDrvr LLC. The generated type definitions describe OpenAI's open-source Codex App Server protocol; this package is an independent re-distribution of generator output and is not affiliated with OpenAI.