Preface
Reading Contract: Use this preface to lock the thesis before the mechanics: context is governed runtime state, not a growing transcript. Track the six owners it names — ledger, envelope, fragments, optional planes, compaction, and replay — and keep them separate while reading the chapters.
This book is about one part of Codex that is easy to underestimate: context management. Most agent write-ups talk about tools, models, and user interfaces. Codex is interesting because it treats context as governed runtime state. The prompt sent to the model is not a string that grows until it fails. It is the projection of a thread ledger, a turn envelope, typed context fragments, policy diffs, optional knowledge planes, compaction checkpoints, and replay evidence.
The source snapshot used throughout this book is 569ff6a1c400bd514ff79f5f1050a684dc3afde3. The book is meant to be read without opening the source first. Source links are audit anchors, not homework.
Read the evidence in three layers. Direct statements about structs, functions, fields, and comments come from pinned public source links. The ownership language in the prose is a bounded engineering interpretation of those visible contracts. Anything that would require provider-internal state or unpublished service behavior is outside this book’s claim boundary.
The Thesis
The architectural bet is simple:
Codex keeps long agent work coherent by making context a runtime boundary, not a prompt-building convenience.
That bet explains the shape of the subsystem. A turn has an explicit envelope. History is normalized before sampling. Runtime facts are injected as typed fragments. Optional material is budgeted. Compaction installs replacement history. Resume and fork rebuild the prompt from rollout evidence. Clients render context state, but they do not own it.
A Map Before You Start
The subsystem is easiest to read as a route through owners. Each owner has a chapter home:
| Chapter | Owner | Question |
|---|---|---|
| Chapter 1 | Context boundary | Why is the prompt a projection rather than a transcript? |
| Chapter 2 | Turn envelope | Which runtime facts govern one model request? |
| Chapter 3 | History ledger | How does durable evidence become prompt-ready state? |
| Chapter 4 | Typed fragments | How do runtime facts enter the model view safely? |
| Chapter 5 | Optional planes | Which helpful context gets a budget instead of a guarantee? |
| Chapter 6 | Compaction | How does Codex install a checkpoint without losing protocol shape? |
| Chapter 7 | Replay | How does resume, rollback, and fork rebuild effective context? |
| Chapter 8 | Client surfaces | How do clients display context without owning it? |
Read the chapters in that order the first time. Each chapter assumes the previous owners exist and concentrates on its own concern.
What This Book Covers
This is not a tutorial on using Codex. It is a technical publication about how Codex carries context through a long-running software-engineering agent:
| Layer | What it teaches |
|---|---|
| Turn envelope | How model identity, policy, workspace, tools, hooks, and feature gates are gathered for one turn. |
| History ledger | How response items become prompt-ready history while preserving call/output invariants. |
| Context fragments | How environment, permissions, realtime, skills, plugins, hooks, and memory become model-visible state. |
| Budgeting | How Codex prevents optional context from consuming the whole window. |
| Compaction | How long threads are rewritten into checkpointed replacement history. |
| Replay | How resumed, rolled-back, and forked threads reconstruct the effective context. |
| Client surfaces | How TUI, app-server, realtime, trace, and token usage expose context without becoming the source of truth. |
Reading Without Rust Expertise
Rust details appear only when they expose design. When the book says “struct”, read it as “a named packet of state.” When it says “enum”, read it as “a closed set of runtime cases.” When it says “async task”, read it as “work that can pause while waiting for the model, tools, hooks, or I/O.”
The source links point to the public Codex repository. The prose describes visible contracts and intentionally avoids provider-internal templates or service implementation bodies. When pseudocode appears, it illustrates a pattern and uses generic names.
How to Use This Book
Technical leaders can read the opening sections, hand-drawn figures, and “Apply This” sections to understand the design rationale. Senior engineers should read every chapter, including the deep dives, because the real lesson is not “summarize old messages.” The lesson is how to keep a mutable prompt projection tied to durable evidence.
Each chapter ends with five “Apply This” items. They are the transferable patterns. If you are designing a new agent runtime, the patterns matter more than the exact field names. If you are reading Codex source, the chapter narrative matters more than the patterns.