Introducing a new way to review your PRs.

Read the announcement

openai / codex

Lightweight coding agent that runs in your terminal

View on GitHub

13 documents · Updated Nov 16, 2026

docs / collaboration-agents-and-message-board

Collaboration Agents and Message Board

Overview

This area covers the collaboration primitives used by multi-agent Codex runs: durable agent identity, user-defined agent roles, spawned-agent topology, message-board storage/tools, Guardian review context and evidence flows, plus adjacent extension plumbing for queues, history notes, git attribution, and extension-owned items.

Agent identity lives in codex-rs/…/lib.rs. It generates Ed25519 key material, registers durable agent runtimes with the Agent Identity auth API, registers per-run tasks, and builds AgentAssertion authorization headers by signing agent_runtime_id:task_id:timestamp. It also decodes Agent Identity JWTs, optionally verifying them against JWKS from agent_identity_jwks_url; production/staging ChatGPT URLs are the only accepted environments. The reusable identity is AgentIdentityKey { agent_runtime_id, private_key_pkcs8_base64 }; task IDs are deliberately scoped to a single Codex run.

Agent role configuration is loaded by codex-rs/…/loader.rs. Role definitions can be declared under agents.<role> in config or discovered as TOML files under a config layer's agents/ directory via codex-rs/…/discovery.rs. codex-rs/…/agent_role_config.rs parses role files, removes metadata keys (name, description, nickname_candidates) from the embedded config payload, validates nonblank descriptions/developer instructions, and normalizes nickname candidates. Layered config merges higher-precedence role fields with missing fields from lower layers; malformed roles become startup warnings when layers are present.

Spawned-agent graph state is abstracted by codex-rs/…/store.rs. AgentGraphStore persists directional parent/child edges keyed by ThreadId, with ThreadSpawnEdgeStatus::{Open, Closed} from codex-rs/…/types.rs. codex-rs/…/local.rs implements the trait on top of an existing codex_state::StateRuntime, translating status values to the state crate and returning children or breadth-first descendants in stable order.

The shared message-board contract is codex-rs/…/api.rs. AgentMessageBoard operates on one board identity (SessionId) and exposes channel creation/upsert, posting, silent append, channel/thread/post reads, search, and subscriptions. All backends receive host capabilities through MessageBoardHost in codex-rs/…/host.rs: caller-to-AgentPath lookup, path-to-ThreadId resolution, caller clock, and best-effort notification delivery. Posts use board-scoped UUIDs; thread IDs are root post IDs, not runtime thread IDs. Requests include caller-scoped request IDs so retries with identical payloads are idempotent and conflicting retries are rejected.

There are three board implementations/routes:

  • codex-rs/…/in_memory.rs is tree-owned, process-local storage for training or ephemeral flows. InMemoryMessageBoards::open shares a state object per board identity while handles exist. Mutations are atomic under a mutex, host callbacks run outside the lock, and state disappears when the last handle drops.
  • codex-rs/…/local.rs is the SQLite-backed durable board. It scopes every row by board identity and LocalBoardOptions.storage_namespace, serializes writes with immediate transactions, persists accepted posts across runtime unload/restart, and supports read-only fixed snapshots through BoardReadView in codex-rs/…/read_view.rs. codex-rs/…/connection.rs provides host-supplied read-only/read-write connections for isolated runtimes; connected boards derive synthetic paths from thread IDs rather than a shared agent tree.
  • codex-rs/…/client.rs is the remote HTTP/S client. It appends /v1/boards/{board} to the configured endpoint, sends bearer-token calls using the typed protocol in codex-rs/…/protocol.rs, bounds request/response/SSE frames, and implements only the operations supported by the service. Remote boards explicitly reject channel upsert and silent append because the remote protocol has no equivalent semantics.

Model-facing board tools are bound in codex-rs/…/tools.rs and described in codex-rs/…/spec.rs. Live tools include discussion mutations; read-only captured views expose only channel/thread/search/read tools. Tool arguments are capped at 128 KiB, responses at 8 KiB, and read operations retry with smaller page/preview limits when output exceeds the budget. codex-rs/…/permissions.rs converts backend permission denials into bounded structured model responses.

Core integration for agent boards is split by host and extension. codex-rs/…/backend.rs selects and opens BoardBackend::{Mcp, Connected, Remote, InMemory, Local} at thread startup and stores remote clients for turn-bound notification receivers. codex-rs/…/extension.rs validates that the opened board identity matches the tree or connected-board identity, stores the caller binding, and contributes the selected message-board tools under the runtime namespace. codex-rs/…/mcp.rs can expose an in-memory board as an MCP server contribution. codex-rs/…/lib.rs is the codex-core adapter: it gates automatic boards on MultiAgentV2 and message-board feature flags, maps board membership to loaded CodexThreads, resolves agent paths, uses CodexThread::current_time, and delivers notifications as Op::InterAgentCommunication without waking recipients (trigger_turn: false). Permanent local board cleanup goes through delete_agent_message_boards in that same file.

codex-rs/…/lib.rs is the legacy agent runner: it starts a resolved AgentInvocation as a forked legacy subagent through ThreadManager::spawn_legacy_subagent, then submits the rendered prompt as the first user turn. This crate is only the runtime launcher; discovery/rendering of prompt and skills are upstream.

Guardian context assembly is centralized in codex-rs/…/lib.rs. SectionRegistry collects scoped SectionContributors for sync review and async scoring, using SectionInput to borrow host history, root conversation evidence, trusted answers/tools/skills, permissions, previous reviews, images, node REPL snapshots, and the planned action. codex-rs/…/composition.rs orders collected sections, frames sync/async transcripts, preserves native message boundaries, and converts composed context into user inputs or ResponseItems. codex-rs/…/mod.rs applies consumer-specific transcript selection, section preparation, image admission, native-message deduplication, and fixed-vs-elastic budgeting. codex-rs/…/enforcement.rs performs final request-budget fitting: required/protected action evidence is kept, optional evidence leaves before historical truncation, and omission notices are inserted when reductions occur. Root conversation selection and omission notices are in codex-rs/…/root.rs; prior sync-review evidence for async scoring is bounded in codex-rs/…/reviews.rs.

Synchronous Guardian review orchestration is in codex-rs/ext/guardian-reviewer. The public entry point codex-rs/…/review.rs implements SynchronousApprovalReviewer for ReviewRequest: the host validates and prepares an immutable action, emits start/complete events, runs up to three review attempts within a deadline, handles async cached approval races, records evidence only for completed non-cached assessments, and interrupts the servicing turn on denial-limit errors. Reviewer session identity helpers are in codex-rs/…/session.rs; Guardian reviewer subagents use the fixed name guardian and legacy prompt cache keys are scoped by parent thread.

codex-rs/…/lib.rs installs both async scoring and sync reviewer support. The async scorer registers lifecycle hooks in codex-rs/…/extension.rs: on thread start it resolves Guardian V2 config, initializes a LunaSampler, installs conversation backend/progress state, records trusted skill roots, optionally enables image capture, and contributes tool/skill lifecycle scoring hooks. codex-rs/…/sampler.rs builds tool-less Luna classification requests with stable item IDs, bounded input/output, parent-compaction compatibility, and pooled WebSocket/HTTP execution. Optional comparison classification via the Decisions API is isolated in codex-rs/…/decisions.rs, with bounded concurrency, deadlines, response limits, and credential-generation checks. The sync reviewer runtime hook in codex-rs/…/mod.rs owns reviewer agent pools, prewarm, turn-blocking metrics, isolated Guardian sessions, and cleanup on parent stop.

Guardian V3 stores durable original evidence in a local message board. codex-rs/…/host.rs starts one root worker for paginated, non-ephemeral root threads; user-message and turn-end events coalesce into wakeups. The worker flushes root history, captures unread originals via EvidenceCursor in codex-rs/…/evidence.rs, and routes them through a private housekeeper thread into a board opened with namespace guardian from codex-rs/…/lib.rs. Selection/delivery then use fixed board read views: codex-rs/…/delivery.rs plans undelivered posts by source ordinal and selected channels, reads post bodies page-by-page, admits bounded batches into reviewer context, and updates in-memory delivery state only after the host records the items.

Queue, history-note, git-attribution, and item crates are adjacent extension infrastructure:

  • codex-rs/…/service.rs is a durable user-message queue over a QueueStore. It validates queued TurnInput::UserInput, snapshots local media attachments, preserves or updates response metadata, emits ThreadQueueChanged, watches external queue changes, and dispatches the first item only when the target CodexThread is idle. codex-rs/…/lib.rs registers the service and starts the external-message watcher.
  • codex-rs/…/extension.rs installs HTTP-backed history/notes tools and optional thread-hint context. It enables the backend only when token-budget config opts in, the provider is OpenAI, and auth uses the Codex backend. codex-rs/…/backend.rs injects session/agent context into backend calls, forwards opaque JSON arguments, applies auth, and sends truncation-policy headers.
  • codex-rs/…/lib.rs contributes world-state instructions for commit/PR attribution. It resolves account policy through codex-rs/…/policy.rs, caches by auth generation, defers failed retries, and renders enabled/disabled fragments from codex-rs/…/world_state.rs.
  • codex-rs/…/lib.rs owns the typed extension-item envelope carried by core lifecycle events, currently image_gen.generation, clock.sleep, and web.search.

Path-routing notes: changes under agent-identity, agent-roles, and agent-graph-store are identity/config/topology primitives; changes under message-board, agent-message-board-client, agent-message-board-host, and ext/agent-message-board affect board contracts, storage, tools, backend selection, and core delivery; changes under guardian-context, ext/guardian-reviewer, ext/guardian-v2, and ext/guardian-v3 affect Guardian evidence collection/review/scoring/durable retrieval; changes under ext/agent, ext/queue, ext/history-notes, ext/git-attribution, and ext/items affect collaboration-adjacent extension launch, queueing, context/tool, attribution, or display-item behavior.

Coupling

Risks

  • codex-rs/…/local.rs commits posts before attempting notification fanout, and notification failures are logged without failing the post. If reviewers assume a successful post implies recipients saw the notice, collaboration can miss urgent messages; use board reads/subscriptions as the source of truth for durable content.
  • codex-rs/…/client.rs remote boards reject upsert_channel and append. If host configuration switches from local/in-memory to remote while tools or Guardian V3 flows depend on silent append or metadata upsert, those operations fail instead of falling back to discussion posts.
  • codex-rs/…/host.rs starts evidence intake only for root, non-ephemeral, paginated threads. If a host expects Guardian V3 durable evidence on ephemeral sessions, internal reviewer sessions, subthreads, or non-paginated history, no root worker is installed and no board evidence is captured.
  • codex-rs/…/evidence.rs aborts capture on replaced history (SessionMeta after the initial header or ThreadRolledBack) and rejects inherited or ambiguous user evidence. If a root history rollback or unsupported provenance appears, the housekeeper stops routing rather than writing partial/unsafe originals.
  • codex-rs/…/service.rs dispatches queued input only when the loaded thread is idle and not interrupted. If a queued item is invalid or non-user input, dispatch logs and deletes it; malformed external queue writes can therefore drop user-visible queued work.