A Multi-agent Graph Must Be Persisted

You ask the root session to dispatch an explorer into the auth module. The model calls spawn_agent; the tool returns a task name /root/explore_auth and the nickname Hypatia. A few minutes later you hit wait_agent, and a FINAL_ANSWER is lying in the mailbox.

The next day you open the same thread. The child session’s runtime is already unloaded. If the system only remembers that a call happened yesterday, this path is gone. Send send_message again and the control plane reports live agent path not found.

Codex makes parent–child a directed edge. An edge has two values. Open means it can still be restored as an open spawned agent. Closed means, from the graph’s view, it is already shut. Serialization is open and closed.

Source:codex-rs/agent-graph-store/src/types.rs lines 4–12

The graph lives in SQLite’s thread_spawn_edges table. child_thread_id is the primary key; one child cannot hang on two parents. Spawn the same child again and both parent and status are overwritten. Session body does not enter this table. A sub-agent’s model context still walks its own rollout. The graph only answers who spawned whom, and whether this edge is open or closed now.

Source:codex-rs/state/migrations/0021_thread_spawn_edges.sql lines 1–8

A non-ephemeral session upserts an Open edge the moment the thread is built. A write failure only warns. The child thread is already running; the graph can catch up later. The backfill uses ON CONFLICT DO NOTHING, and will not flip a Closed edge back.

Source:codex-rs/core/src/agent/control.rs lines 767–780

When listing descendants, the filter applies to every edge you walk. Some(Open) only follows Open. A subtree whose parent edge is already Closed will not be listed, even if a grandchild edge is still Open.

Source:codex-rs/agent-graph-store/src/store.rs lines 49–54

The path is the addressing key; the nickname is for humans. The root is /root. A relative name is appended to the current path. .. and . are rejected, so you cannot crawl to a sibling on a relative path. A role can shrink capability; it cannot replace the parent session’s authority. Built-in live roles are default, explorer, worker. explorer.toml is an empty file.

Source:codex-rs/core/src/agent/role.rs lines 1–4

After a restart you must be able to ask: does this child still count as alive? Remembering one spawn event cannot answer that. Only Open enters the restore list. Closed disappears from subtree walks. child_id as primary key keeps the graph a tree; walks can BFS by depth. Rewrite it in another language and the minimum shape is still a three-column table: parent, child, status.

The sub-agent finishes and must send a FINAL_ANSWER home. If that letter wakes by itself, a parent mid-sentence on a user-visible final answer is forced into a new turn. The user sees a half sentence, then a completion notice shoved in.

There are four communication tags: Spawn, Message, Followup, Result. Those are OTEL labels. On the protocol side there is one InterAgentCommunication; trigger_turn decides whether to wake.

send_message is QueueOnly — enqueue only. followup_task is TriggerTurn — that is the wake. Empty messages are rejected outright. followup_task cannot hit the root node.

Source:codex-rs/core/src/tools/handlers/multi_agents_v2/message_tool.rs lines 11–24

The handler enqueues first, then decides whether to start work. When trigger_turn is false, the letter stays put. Only if it is true, or the session still has an unfinished durable sleep, does work start. V2’s completion notice is Result, and trigger_turn is false. If the parent is talking, the letter queues in mailbox phase.

Source:codex-rs/core/src/session/handlers.rs lines 89–99

The mailbox is a session-level queue. User barge-in goes to pending_input; child mail goes to mailbox_pending_mails — two slots. Siblings can talk if they use an absolute path such as /root/worker_b. The relative name worker_b is appended to self and becomes your own child.

Source:codex-rs/core/src/session/input_queue.rs lines 76–80

The right to wake is scarce. Whoever can open a turn must not open one casually. Split delivery from start-of-work: a completion notice does not wake by default; wake is reserved for followup_task and the user. Another message bus can use the same boolean: wake, or enqueue only.

When V2’s resident slots fill, it unloads a child by LRU. If unloading the runtime also marks the edge Closed, that child vanishes from the Open subtree. The next restore cannot find it. The user never closed it — the system struck the name itself.

shutdown_live_agent shuts a live agent, flushes the rollout, sends Shutdown, and plucks the thread from the manager. The edge is still Open. The next restore still treats it as a live subtree member.

Source:codex-rs/core/src/agent/control/legacy.rs lines 6–8

close_agent first marks the target’s own inbound edge Closed, then shuts down. Descendant edges are not marked Closed here. A parent turn that ends normally walks TurnComplete and does not call close_agent. The child keeps running; the edge stays Open.

Source:codex-rs/core/src/agent/control/legacy.rs lines 48–58

V2 restore is two steps. First, Open descendants’ identities go back into the registry — the runtime is not reopened. Only when someone actually send_messages or followup_tasks is the thread hung back from the rollout.

Source:codex-rs/core/src/agent/control/spawn.rs lines 144–162

A live runtime and a name dropped from the graph are two independent facts. Resident LRU, a process restart, a user closing a window — any of them can unload a runtime. Only an orchestrator’s explicit close writes Closed. Restore walks Open edges. This split does not depend on Rust.