Codex Harness Deconstructed: Agent Runtime Beyond the Execution Loop

Codex Core Contains an Agent Loop

The core execution logic lives in session/turn.rs with run_turn: the model returns function calls, the runtime executes tools and feeds results back for the next sampling; when the model returns a final message, the turn ends. This is a classic Agent Loop—model thinks, calls tools, gets results, continues.

However, run_turn already handles context compression, hooks, MCP dependencies, plugin injection, skill invocation, tool routing, execution differences, cancellation signals, retries, event recording, and session state. Once an agent modifies real code and runs real commands, a single model call is no longer a complete engineering object.

A Single Execution Loop Cannot Support a Full Product

Only an Agent Loop can complete one task but cannot support a full product: tasks need recovery, forking, event streams, approval gates, collaboration, and stop states. These cannot be solved by adding prompts; prompts cannot establish persistent state, real permissions, concurrency control, or lifecycle management. A mature Harness must separate engineering concerns outside the model loop.

Codex Is a Layered Runtime

The open repository includes Core, App Server, TypeScript SDK, Python SDK, MCP, Skill, Plugin, sandbox, and state storage. They operate at different layers. The TypeScript SDK launches the codex CLI and exchanges JSONL events via stdio. The Python SDK is a typed JSON-RPC client that calls codex app-server via stdio. This difference shows Codex Harness cannot be summarized as a "unified SDK shell"; different entry points target different layers. CLI is just an entry; the Agent Loop is only a key execution mechanism in Core; the layered Runtime behind them enables productization.

Thread → Turn → Item: Not Ordinary Chat History

Codex App Server defines three-layer interaction objects: Thread contains multiple Turns; Turn persists process facts via Items. Saving only final answers loses intermediate execution details. With Items, frontends show real progress via item/started, incremental updates, and item/completed; approval mechanisms can intervene on a single command or file edit; session recovery reloads actual facts, not just summaries. Threads can be resumed, archived, and forked—forked threads inherit history but diverge. This state model is more fundamental than model choice; unstable Thread/Turn/Item boundaries break recovery, auditing, and multi-client access.

App Server Is a Control Plane, Not a Model Proxy

codex app-server

provides JSON-RPC bidirectional communication for rich clients like IDEs. Clients start/resume Threads, begin/interrupt Turns; the server streams state, Items, tool progress, and approval requests. It handles control responsibilities: Thread lifecycle, Turn control, Item streaming, approval gating, and multi-client coordination. Core handles "how tasks actually execute"; App Server handles "how external products control, observe, and intervene." Separation lets terminals, IDEs, and business products share execution while keeping distinct interactions.

Goal, Queue, and Memory Enable Tasks Beyond One Conversation

Goal binds to a Thread, persists objective and status.

Queue stores subsequent tasks in order, submits when thread is idle.

Memory retains cross-task information with thread-scoped modes.

Context Compaction compresses history near limits.

Multi-agent operations provide create, communicate, delegate, wait, and interrupt.

These solve task persistence across time, not better prompts. However, Queue, dynamic tools, and some remote capabilities are still marked experimental in the protocol; presence in source does not mean stable or production-ready.

Multi-Agent Is a Runtime Problem, Not a Prompt Trick

Core shows multi-agent thread management and collaboration tools: a parent agent can create child agents, send messages, delegate, wait, or interrupt. Without thread identity, concurrency limits, message passing, and termination conditions, multi-agent is just concurrent conversations that may duplicate file edits, use inconsistent contexts, or each declare completion. Runtime provides creation and communication mechanisms, but task decomposition, role responsibilities, result merging, and design-gap feedback belong to task graphs, role definitions, and engineering workflows.

Control Mechanisms ≠ Complete Security Governance

Codex provides sandbox, permission config, approval, and execution logs, but boundaries must be explicit: WebSocket transport is experimental and unsupported for production; Dynamic Tools are experimental API; thread/shellCommand runs with full user permissions, not inheriting Thread sandbox; some permissions, remote environments, and background process interfaces require explicit experimental flags. Runtime provides control points; enterprise governance decides what rules those points enforce—identity sources, role permissions, data scopes, tool allowlists, secret management, audit retention, and high-risk action confirmation.

What "Open Source Codex Harness" Actually Means

Open sourced: client, runtime, and protocol implementations in the repo—not the model itself.

Local code ≠ OpenAI cloud service internals.

Experimental capabilities ≠ stable product commitments.

General coding runtime ≠ enterprise business agent production readiness.

Accurate statement: "Codex Harness's core client and runtime structure are now publicly researchable and reusable."

Enterprise Agents Still Miss the Last Mile

Codex solves generic coding agent runtime: it knows working directory, tools, history, permissions—but not business semantics: customer, contract, device, case, metric, or business action meanings. Runtime can control tool invocation, but business systems must answer: can this user view this object? Is this action allowed in this state? What preconditions, idempotency constraints, approval rules apply? Which system wins on conflict? What evidence must a decision retain? On failure: retry, compensate, rollback, or escalate? Without Runtime, enterprises rebuild threads, tools, state, permissions repeatedly; with only Runtime, it remains a generic tool-calling assistant.

Five Architectural Questions After Deconstruction

What objects represent session, execution turn, task step, tool result?

Which state must persist; how to recover after exit or interruption?

Are model loop, tool execution, product integration, and permission control cleanly bounded?

How do Skill, Plugin, MCP, and multi-agent extend—and how are they stopped and constrained?

Which capabilities belong to generic Runtime; which require business semantics and enterprise governance?

Unanswered, adding more tools, models, and roles only increases execution complexity.

Summary

Codex Core has an Agent Loop, but Codex Harness far exceeds a loop. It manages continuous model-tool interaction via Core, builds state model through Thread → Turn → Item, exposes events, approval, and control protocols via App Server, and supports longer, complex tasks via Goal, Queue, Memory, Skill, Plugin, MCP, and multi-agent. A mature Harness = Agent Loop + Runtime + State & Event Protocol + Permission & Execution Control + Extension & Collaboration Mechanisms. Yet it is not the whole enterprise agent: generic Runtime solves stable agent operation; business semantics and governance decide if it enters real business. Seeing this boundary avoids underestimating Harness engineering complexity and overestimating what open-source Runtime directly solves.