@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/[email protected] was generated by codex-cli 0.159.2. Provenance is also recorded in package.json:

{
  "version": "0.159.2",
  "codexCliVersion": "0.159.2",  // 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.159.2 (875 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

In 0.159.2, thread/items/list returns ThreadItemEntry values with nullable startedAtMs and completedAtMs fields (Unix milliseconds). They represent item lifecycle times when the producer recorded them. Turn.items in read and turn-list responses, and ordinary thread/timeline/list items, still contain bare ThreadItem values without per-item timing. The server binary must also support these fields; installing newer types alone does not change an older server's responses.

Earlier 0.153.4 investigation

Investigated 2026-09-06 against the then-latest stable Codex release, 0.153.4 (published September 4; commit 3d2ee51ca2d5db578f328aa75e20aa22c0197c9a). That release did not expose historical per-item timestamps for ordinary messages, plans, or activities. The table below records the 0.153.4 surface.

| 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.

Earlier upstream proposal

The 0.153.4 investigation proposed the following broader API. Version 0.159.2 implements the two lifecycle fields on ThreadItemEntry; the proposed timing fields on timeline entries and Turn.items are still absent.

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. For any remaining upstream changes, regenerate this package from the exact released binary and follow PUBLISHING.md.

Consumer integration with 0.159.2

Consume startedAtMs and completedAtMs from thread/items/list when present. Keep capturing live lifecycle notifications by (threadId, turnId, item.id) for item views that do not use item-list entries and for older servers. Preserve known values across history refreshes; leave unknown item times absent. Treat local receipt time separately from server lifecycle time, and do not derive item time from UUIDs, cursors, timeline positions, or turn boundaries. thread/items/list can return JSON-RPC -32601 for unsupported stores, so retain a history fallback. The broader proposal above has not been submitted as an upstream issue or comment.

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.