@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.153.4 was generated by codex-cli 0.153.4. Provenance is also recorded in package.json:

{
  "version": "0.153.4",
  "codexCliVersion": "0.153.4",  // 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.153.4 (827 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.

Historical item timing: upstream gap and proposal

Investigated 2026-09-06 against the latest stable Codex release, 0.153.4 (published September 4; commit 3d2ee51ca2d5db578f328aa75e20aa22c0197c9a). It does not expose historical per-item timestamps for ordinary messages, plans, or activities. This package mirrors 0.153.4 for its other protocol changes; this release does not solve historical item timing. Type declarations cannot make an older or newer server send additional data.

Wire surface in 0.153.4	Timing available
thread/read → thread.turns[].items[]	Bare ThreadItem; no general item timestamp
thread/turns/list → data[].items[]	Bare ThreadItem; no general item timestamp
thread/items/list → data[]	ThreadItemEntry contains only turnId and item
Experimental thread/timeline/list → ordinary item entry	position, turnId, item; position is ordering, not time
Turn and timeline turn boundaries	startedAt / completedAt in Unix seconds, durationMs in milliseconds
Live notification envelope	Optional emittedAtMs in Unix milliseconds; server emission time
Live item/started notification	startedAtMs in Unix milliseconds
Live item/completed notification	completedAtMs in Unix milliseconds

These findings come from the released Rust history envelopes, generated Turn, and generated ThreadItem. The six relevant generated definitions (ThreadItem, ThreadItemEntry, Turn, and the three read/list responses) were also identical on upstream main at 3cd6004dc43c96c38946d9697a7cf72af1562563. Item-specific tool durations are not general message creation timestamps.

Where upstream loses the information

• The history projection carries optional lifecycle start and completion times from persisted item completion events into ThreadHistoryItemChange.
• The item materializer uses lifecycle start, or a persisted record timestamp fallback, as created_at_ms. It preserves the first creation value when updating an item. The fallback source is the record timestamp, not a guaranteed lifecycle start.
• StoredThreadItem exposes created_at_ms internally, but no separate lifecycle start/completion fields. The items response conversion retains only turn_id and deserialized item_json.
• The stored-turn conversion likewise deserializes items without their metadata. The legacy history builder records changed items with unknown lifecycle times. Adding a response field alone would not repair all history paths.

Only public upstream source code and repository types were inspected; no local Codex rollout, session, or SQLite data was accessed.

Proposed upstream change (not an existing API)

Add a shared ThreadItemTiming type with nullable startedAtMs and completedAtMs, explicitly defined as lifecycle times in Unix milliseconds. Add optional timing to ThreadItemEntry and ordinary timeline item entries. To preserve the existing Turn.items: ThreadItem[] shape, add an optional Turn.itemTimings map keyed by item ID, populated for the returned items in both full and summary views. Omit it for notLoaded views. Use the same metadata for read, resume, and live turn snapshots.

Carry both lifecycle fields through the history projection, durable item representation, store reads, and API conversions. Keep projection creation time separate: if exposed as createdAtMs, document its fallback semantics and provenance instead of labeling it a lifecycle start. Legacy replay must associate available lifecycle events with the correct stable item IDs; missing evidence remains null. Never substitute turn start, replay time, or an ordinal. Any migration/backfill belongs inside Codex, through its supported history handling, rather than requiring consumers to access its storage.

Upstream acceptance tests should cover two commentary items emitted hours apart within one turn; cold read and resume; full/summary turn pagination; item and timeline pagination; partial and legacy timing; duplicate updates; stable IDs and timestamps across restart; rollback/fork handling; and seconds versus milliseconds. Verify serialized responses and generated schemas, including preservation of a known start when only a completion update arrives. Release Codex with those changes before regenerating this package from that exact released binary and following PUBLISHING.md.

Consumer integration now

Upgrading to 0.153.4 does not supply missing historical times. Capture live startedAtMs and completedAtMs by (threadId, turnId, item.id) and preserve those known values when history refreshes. Treat locally observed receipt time as separate from server lifecycle time. For cold history with no known item time, leave the timestamp absent; use turn timing only to label the turn. Do not derive item time from UUIDs, cursors, timeline positions, or turn boundaries.

After an upstream release implements the proposal, update the server binary and matching type package together, consume the actual released field names, and tolerate absent metadata from older servers. thread/items/list can return JSON-RPC -32601 for unsupported stores; keep a history fallback that preserves unknown timestamps. No upstream issue or comment has been submitted.

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.