Skip to content

Reason Network: your team's coding agents, talking to each other. The engine behind `reason network`.

Busy Codex sessions get mail at their next tool call, however long the turn (#123)

Lars Talian15c620b2ae03
diff --git a/DESIGN.md b/DESIGN.md
index 52b05f0..846c31c 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -311,7 +311,7 @@ The hard part. Each session advertises a **delivery tier** so senders know when
| Agent | Tier | Mechanism |
|---|---|---|
| Claude Code | push | MCP child posts to the session's own inbox socket (`CLAUDE_CODE_MESSAGING_SOCKET`, `{"type":"user",…}` frame): delivered between tool calls, starts a turn if idle. Fallbacks: `asyncRewake` hook (documented idle wake), channels (`notifications/claude/channel`, needs a dev flag until allowlisted). |
-| Codex | push | `codex queue --thread <id>` / app-server `turn/start` (default daemon mode). Mid-turn: `PostToolUse` `additionalContext`. Stop: `decision:block`. Hooks need one-time approval in `/hooks`. |
+| Codex | push | While a turn runs (its rollout, the transcript its hooks name, records `task_started` and no end yet), however long: `PostToolUse` `additionalContext` at the next tool call, or Stop `decision:block`. If the turn ends without Stop (interrupted or failed), mail no hook took goes to `codex queue` within seconds. Otherwise (idle, or no rollout known): `codex queue --thread <id>` / app-server `turn/start` (default daemon mode). Limit: if the daemon restarts while mail waits for a running turn, and the turn then ends without Stop before any of its hooks runs, the mail waits until the next prompt. Hooks need one-time approval in `/hooks`. |
| opencode | push | Plugin (one file for 1.x and 2.x): `client.session.promptAsync` (1.x), `ctx.session.prompt` (2.x, where busy/idle come from `session.execution.*` events). |
| pi | push | Extension (`~/.pi/agent/extensions/reason-network.ts`): registers the MCP server per session (`deferred`, with `REASON_NETWORK_SESSION`), `sendUserMessage` (`deliverAs: "steer"` mid-run, a new turn when idle), busy/idle from `agent_start`/`agent_settled`, the session name as `doing`. |
| Reason | push | Its agent runs in Reason's cloud: the daemon lists live sessions (`reason session list --json`, when `reason = true`) and sends with `reason session send`. Replies go through the CLI: `reason-network send <to> --from <its address>`. |
diff --git a/README.md b/README.md
index c210b14..6cbfb92 100644
--- a/README.md
+++ b/README.md
@@ -112,7 +112,7 @@ With the Reason CLI: `reason network leave`, then `reason network setup --remove
```sh
cargo fmt && cargo clippy --all-targets -- -D warnings && cargo test
cargo build && python3 tests/e2e/two_machines.py # two machines over iroh (needs internet)
-python3 tests/e2e/hooks.py && python3 tests/e2e/guided.py
+python3 tests/e2e/hooks.py && python3 tests/e2e/codex_busy.py && python3 tests/e2e/guided.py
```
A `v*` tag builds the macOS, Linux and Windows archives and the install scripts; the Reason CLI pins the macOS and
diff --git a/src/codex.rs b/src/codex.rs
new file mode 100644
index 0000000..e0d22ab
--- /dev/null
+++ b/src/codex.rs
@@ -0,0 +1,188 @@
+//! What a Codex thread's rollout (the transcript its hooks name) says about its turn.
+//!
+//! Codex records each turn's start (`task_started`) and its end: `task_complete` when it finishes or fails,
+//! `turn_aborted` when it is interrupted. The last two run no Stop hook, and a single tool call can run for hours
+//! without any hook, so only the rollout tells a running turn from one that is over.
+
+use std::{
+ collections::HashMap,
+ fs::File,
+ io::{Read, Seek, SeekFrom},
+ path::{Path, PathBuf},
+ sync::{Mutex, OnceLock},
+};
+
+/// How much is read at a time, from the end back, to find the last turn event.
+const CHUNK: u64 = 256 << 10;
+
+/// Whether the turn the rollout at `path` records last is still running. A rollout without a turn yet is idle.
+/// `None` when it can't be read. Remembers how far it read, so later calls read only what was appended.
+pub fn turn_running(path: &Path) -> Option<bool> {
+ static SEEN: OnceLock<Mutex<HashMap<PathBuf, (u64, bool)>>> = OnceLock::new();
+ // Only a regular file: opening a pipe a hook named would wait for a writer.
+ if !std::fs::metadata(path).ok()?.is_file() {
+ return None;
+ }
+ let mut seen = SEEN.get_or_init(Default::default).lock().unwrap();
+ let mut file = File::open(path).ok()?;
+ let len = file.metadata().ok()?.len();
+ // Rollouts only grow: a shorter one was rewritten, and is read again.
+ let (from, before) = match seen.get(path) {
+ Some(&(at, running)) if at <= len => (at, running),
+ _ => (0, false),
+ };
+ let (end, last) = last_turn_event(&mut file, from, len).ok()?;
+ let running = last.unwrap_or(before);
+ seen.insert(path.to_path_buf(), (end, running));
+ Some(running)
+}
+
+/// The last turn event in `from..to` (whole lines from `from`, which starts one), and where the last whole line in it
+/// ends: a line still being written is read next time.
+fn last_turn_event(file: &mut File, from: u64, to: u64) -> std::io::Result<(u64, Option<bool>)> {
+ // `rest`: the pieces of a line that begins in a chunk before, last piece first.
+ let (mut end, mut whole_to, mut rest) = (to, None, Vec::<Vec<u8>>::new());
+ while end > from {
+ let start = end.saturating_sub(CHUNK).max(from);
+ let mut buf = vec![0; (end - start) as usize];
+ file.seek(SeekFrom::Start(start))?;
+ file.read_exact(&mut buf)?;
+ if whole_to.is_none() {
+ // Up to the last newline: what follows it isn't a whole line yet.
+ let Some(i) = buf.iter().rposition(|&b| b == b'\n') else {
+ end = start;
+ continue;
+ };
+ whole_to = Some(start + i as u64 + 1);
+ buf.truncate(i + 1);
+ } else if start > from && !buf.contains(&b'\n') {
+ // All of it is inside that line: put the line together once its start is read, not every chunk.
+ rest.push(buf);
+ end = start;
+ continue;
+ } else {
+ for piece in rest.drain(..).rev() {
+ buf.extend_from_slice(&piece);
+ }
+ }
+ // The first line here may begin in the chunk before: keep it for then.
+ let first = if start > from { buf.iter().position(|&b| b == b'\n').map_or(buf.len(), |i| i + 1) } else { 0 };
+ if let Some(running) = buf[first..].split(|&b| b == b'\n').rev().find_map(turn_event) {
+ return Ok((whole_to.unwrap_or(from), Some(running)));
+ }
+ rest.push(buf[..first].to_vec());
+ end = start;
+ }
+ Ok((whole_to.unwrap_or(from), None))
+}
+
+/// Some(true) for a line recording a turn's start, Some(false) for one recording its end.
+fn turn_event(line: &[u8]) -> Option<bool> {
+ // Most lines are something else: parse only those that may be one.
+ let text = std::str::from_utf8(line).ok()?;
+ if !text.contains("event_msg") || !["task_", "turn_"].iter().any(|k| text.contains(k)) {
+ return None;
+ }
+ let v: serde_json::Value = serde_json::from_str(text).ok()?;
+ if v["type"] != "event_msg" {
+ return None;
+ }
+ match v["payload"]["type"].as_str()? {
+ "task_started" | "turn_started" => Some(true),
+ "task_complete" | "turn_complete" | "turn_aborted" => Some(false),
+ _ => None,
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use std::io::Write;
+
+ fn event(kind: &str) -> String {
+ format!(r#"{{"timestamp":"t","type":"event_msg","payload":{{"type":"{kind}","turn_id":"1"}}}}"#) + "\n"
+ }
+
+ fn append(path: &Path, s: &str) {
+ std::fs::OpenOptions::new().create(true).append(true).open(path).unwrap().write_all(s.as_bytes()).unwrap();
+ }
+
+ #[test]
+ fn the_last_turn_event_says_whether_a_turn_runs() {
+ let dir = std::env::temp_dir().join(format!("reason-network-codex-turn-{}", std::process::id()));
+ let _ = std::fs::remove_dir_all(&dir);
+ std::fs::create_dir_all(&dir).unwrap();
+ let path = dir.join("rollout.jsonl");
+ assert_eq!(turn_running(&path), None, "no rollout");
+
+ append(&path, "{\"type\":\"session_meta\",\"payload\":{}}\n");
+ assert_eq!(turn_running(&path), Some(false), "no turn yet");
+ append(&path, &event("task_started"));
+ assert_eq!(turn_running(&path), Some(true));
+ // A message that mentions turn events is not one.
+ let quoted = r#"{"type":"response_item","payload":{"text":"\"type\":\"event_msg\" task_complete"}}"#;
+ append(&path, &format!("{quoted}\n"));
+ append(&path, "{\"type\":\"turn_context\",\"payload\":{\"type\":\"task_complete\",\"note\":\"event_msg\"}}\n");
+ append(&path, r#"{"type":"event_msg","payload":{"type":"token_count"}}"#);
+ append(&path, "\n");
+ assert_eq!(turn_running(&path), Some(true), "only turn events count");
+ append(&path, &event("turn_aborted"));
+ assert_eq!(turn_running(&path), Some(false), "interrupted");
+ append(&path, &event("turn_started"));
+ assert_eq!(turn_running(&path), Some(true), "the v2 name");
+ append(&path, &event("task_complete"));
+ assert_eq!(turn_running(&path), Some(false), "finished or failed");
+
+ // A line still being written counts once it is whole.
+ append(&path, &event("task_started"));
+ let end = event("task_complete");
+ append(&path, &end[..20]);
+ assert_eq!(turn_running(&path), Some(true));
+ append(&path, &end[20..]);
+ assert_eq!(turn_running(&path), Some(false), "the rest of the line was read");
+
+ // Read fresh (a restarted daemon), from far back: the turn started long before the last chunk.
+ let fresh = dir.join("long.jsonl");
+ append(&fresh, &event("task_complete"));
+ append(&fresh, &event("task_started"));
+ let output = format!(r#"{{"type":"response_item","payload":{{"output":"{}"}}}}"#, "x".repeat(100_000)) + "\n";
+ for _ in 0..12 {
+ append(&fresh, &output);
+ }
+ assert_eq!(turn_running(&fresh), Some(true), "found {} KB back", 12 * 100);
+ // One line longer than a chunk, right after the start.
+ let fresh2 = dir.join("longline.jsonl");
+ append(&fresh2, &event("task_started"));
+ append(&fresh2, &(format!(r#"{{"x":"{}"}}"#, "y".repeat(3 * CHUNK as usize)) + "\n"));
+ assert_eq!(turn_running(&fresh2), Some(true));
+
+ // A turn event cut by a chunk boundary, read fresh.
+ let cut = dir.join("cut.jsonl");
+ append(&cut, &event("task_complete"));
+ append(&cut, &(format!(r#"{{"x":"{}"}}"#, "z".repeat(CHUNK as usize)) + "\n"));
+ append(&cut, &event("task_started"));
+ let tail = CHUNK as usize - 10;
+ append(&cut, &(format!(r#"{{"x":"{}"}}"#, "w".repeat(tail - 9)) + "\n"));
+ assert_eq!(turn_running(&cut), Some(true), "the line across the boundary was put back together");
+ // A turn event across four chunks, its type in the middle one, read fresh: its pieces go back in order.
+ let spread = dir.join("spread.jsonl");
+ append(&spread, &event("task_started"));
+ let half = "m".repeat(3 * CHUNK as usize / 2);
+ let end = format!(r#"{{"type":"event_msg","payload":{{"a":"{half}","type":"task_complete","b":"{half}"}}}}"#);
+ append(&spread, &(end + "\n"));
+ assert_eq!(turn_running(&spread), Some(false), "the end, put back together");
+
+ // A pipe is not a rollout, and is not waited on.
+ #[cfg(unix)]
+ {
+ let pipe = dir.join("pipe");
+ assert!(std::process::Command::new("mkfifo").arg(&pipe).status().unwrap().success());
+ assert_eq!(turn_running(&pipe), None);
+ }
+
+ // Rewritten shorter: read again.
+ std::fs::write(&path, event("task_started")).unwrap();
+ assert_eq!(turn_running(&path), Some(true));
+ let _ = std::fs::remove_dir_all(&dir);
+ }
+}
diff --git a/src/daemon/mail.rs b/src/daemon/mail.rs
index c42792c..928d646 100644
--- a/src/daemon/mail.rs
+++ b/src/daemon/mail.rs
@@ -6,7 +6,7 @@
use super::{Daemon, Inner, directory::Target, log};
use crate::{
- agent, claude,
+ agent, claude, codex,
config::Policy,
files,
proto::*,
@@ -31,6 +31,8 @@ const LOOP_LIMIT: usize = 12;
const LOOP_WINDOW: Duration = Duration::from_secs(600);
/// A push or hook not confirmed within this long is shown through the inbox and hooks again.
const IN_FLIGHT_TTL: Duration = Duration::from_secs(90);
+/// How often a Codex session's rollout is checked while mail waits for a hook of its turn.
+const CODEX_TURN_POLL: Duration = Duration::from_secs(2);
/// How a session on this machine gets a message into its conversation.
enum Channel {
@@ -327,11 +329,17 @@ impl Daemon {
return ("queued".into(), "queued: Reason didn't take the last delivery; it is retried shortly".into());
}
let has = |bin: &str| !l.push_failed && agent::find_bin(bin).is_some();
+ // A Codex turn is running (and `codex queue` is there for when it ends).
+ let codex_turn = l.reg.agent == "codex"
+ && has("codex")
+ && l.transcript.as_deref().and_then(codex::turn_running) == Some(true);
let channel = match (l.reg.tier, l.conn, &l.reg.agent_session_id) {
// Its MCP server knows its inbox; else (it may not yet) the daemon posts into the one Claude Code lists.
(Tier::Push, Some(conn), _) if l.reg.agent == agent::CLAUDE_CODE && l.mcp_push => {
Channel::ClaudeSocket(conn)
}
+ // In a turn, its next PostToolUse (or Stop) shows it; `codex queue` would hold it until the turn ends.
+ (Tier::Push, _, Some(_)) if codex_turn => Channel::Hook,
(Tier::Push, _, Some(id)) if l.reg.agent == "codex" && has("codex") => {
Channel::Command("codex", vec!["queue".into(), "--thread".into(), id.clone(), "--message".into()])
}
@@ -395,11 +403,54 @@ impl Daemon {
.unwrap_or("delivered into the session: it reads it between tool calls, or wakes up if idle");
("pushed".into(), note.into())
}
- Channel::Hook => ("queued".into(), hook_note.into()),
+ Channel::Hook => {
+ if codex_turn {
+ self.watch_codex_turn(g, key);
+ }
+ ("queued".into(), hook_note.into())
+ }
Channel::Pull => ("queued".into(), "queued: this agent only sees it when it checks its inbox".into()),
}
}
+ /// Codex runs no Stop hook when a turn is interrupted or fails: until the turn `key` is in ends, checks its
+ /// rollout, and once it has ended hands the wake mail no hook took to `codex queue`. One watch per session.
+ /// The watch is not kept across a daemon restart: if the daemon restarts while mail waits for a running turn, and
+ /// that turn then ends without Stop before any of its hooks runs, the mail waits until the next prompt.
+ fn watch_codex_turn(self: &Arc<Self>, g: &mut Inner, key: &str) {
+ if !g.codex_watch.insert(key.to_string()) {
+ return;
+ }
+ let (this, key) = (self.clone(), key.to_string());
+ tokio::spawn(async move {
+ loop {
+ tokio::time::sleep(CODEX_TURN_POLL).await;
+ let mut g = this.inner.lock().unwrap();
+ let Some(l) = g.live.get(&key) else {
+ g.codex_watch.remove(&key);
+ return;
+ };
+ let (address, transcript) = (this.addr(&l.name), l.transcript.clone());
+ if !g.store.unread_wakes(&address).unwrap_or_default() {
+ g.codex_watch.remove(&key);
+ return;
+ }
+ if transcript.as_deref().and_then(codex::turn_running) == Some(true) {
+ continue;
+ }
+ // What a hook showed and hasn't confirmed yet is left to it until its confirmation is overdue.
+ let waiting: Vec<Message> =
+ g.pending(&address).unwrap_or_default().into_iter().filter(|m| m.wake).collect();
+ if waiting.is_empty() {
+ continue;
+ }
+ g.codex_watch.remove(&key);
+ this.deliver(&mut g, &key, waiting, true);
+ return;
+ }
+ });
+ }
+
/// A session's MCP server had no inbox to push `ids` into: they are unread again, for the session to read when it
/// checks, and nothing is pushed through it until it registers knowing one (or Claude Code lists one to post into).
pub(super) fn push_failed(&self, key: &str, ids: &[String]) {
@@ -1019,6 +1070,43 @@ mod tests {
assert_eq!((r.recipients[0].state.as_str(), rx.try_recv().is_err()), ("queued", true));
}
+ #[tokio::test]
+ async fn a_codex_session_has_one_turn_watch_and_it_ends_once_its_wake_mail_is_read() {
+ let d = Arc::new(super::super::test_daemon(crate::config::Config::default()));
+ d.register(Some(1), codex("codex:1"), crate::git::GitInfo::default()).unwrap();
+ let reg = SessionReg { cwd: "/work/web".into(), ..codex("codex:2") };
+ let to = d.register(Some(2), reg, crate::git::GitInfo::default()).unwrap().address;
+ let send = |body: &'static str, wake| d.send("codex:1".into(), &to, body, None, wake, false, None, Vec::new());
+ send("fyi", false).await.unwrap();
+ send("wake", true).await.unwrap();
+ // Its turn runs.
+ let rollout = std::env::temp_dir().join(format!("reason-network-watch-{}.jsonl", Ulid::generate()));
+ std::fs::write(&rollout, "{\"type\":\"event_msg\",\"payload\":{\"type\":\"task_started\"}}\n").unwrap();
+ d.inner.lock().unwrap().live.get_mut("codex:2").unwrap().transcript = Some(rollout.clone());
+
+ let tasks = || tokio::runtime::Handle::current().metrics().num_alive_tasks();
+ let watching = || d.inner.lock().unwrap().codex_watch.contains("codex:2");
+ let before = tasks();
+ {
+ let mut g = d.inner.lock().unwrap();
+ d.watch_codex_turn(&mut g, "codex:2");
+ d.watch_codex_turn(&mut g, "codex:2");
+ }
+ assert_eq!(tasks(), before + 1, "more mail for the turn starts no second watch");
+ tokio::time::sleep(CODEX_TURN_POLL + Duration::from_millis(500)).await;
+ assert!(watching(), "watching while wake mail waits and the turn runs");
+ // A hook took the wake mail; the FYI mail is still unread, and keeps no watch going.
+ let wake: Vec<String> = {
+ let g = d.inner.lock().unwrap();
+ g.store.unread(&to).unwrap().into_iter().filter(|m| m.wake).map(|m| m.id).collect()
+ };
+ d.inner.lock().unwrap().store.mark_read(&wake, util::now_ms()).unwrap();
+ tokio::time::sleep(CODEX_TURN_POLL + Duration::from_millis(500)).await;
+ assert!(!watching(), "the watch ended");
+ assert!(tasks() <= before, "…and its task with it");
+ let _ = std::fs::remove_file(&rollout);
+ }
+
#[test]
fn a_peers_message_id_is_a_ulid_as_written() {
let msg = |id: &str| Message {
diff --git a/src/daemon/mod.rs b/src/daemon/mod.rs
index 8c22a89..6f9c11c 100644
--- a/src/daemon/mod.rs
+++ b/src/daemon/mod.rs
@@ -26,7 +26,7 @@ use anyhow::{Result, anyhow};
use iroh::SecretKey;
use serde_json::{Value, json};
use std::{
- collections::{HashMap, VecDeque},
+ collections::{HashMap, HashSet, VecDeque},
sync::{Arc, Mutex, RwLock},
time::{Duration, Instant},
};
@@ -150,6 +150,8 @@ struct Inner {
quota: crate::files::Quota,
/// Sessions whose hooks say they are in a folder that is off: whether each is mid-turn, and when it last said.
off: HashMap<String, (bool, i64)>,
+ /// Codex sessions whose wake mail waits for a hook of the turn they are in, watched for that turn ending first.
+ codex_watch: HashSet<String>,
}
/// A session running on this machine.
@@ -223,6 +225,7 @@ impl Daemon {
swept: 0,
quota: Default::default(),
off: HashMap::new(),
+ codex_watch: HashSet::new(),
}),
arrived: Notify::new(),
git_cache: Mutex::new(HashMap::new()),
diff --git a/src/daemon/sessions.rs b/src/daemon/sessions.rs
index 2e23c10..0f93131 100644
--- a/src/daemon/sessions.rs
+++ b/src/daemon/sessions.rs
@@ -363,6 +363,12 @@ impl Daemon {
self.mailbox(&key, now)?;
}
+ // Read a Codex rollout that is new here now, not later while holding the lock (see `deliver`).
+ if agent == "codex"
+ && let Some(t) = &transcript
+ {
+ crate::codex::turn_running(std::path::Path::new(t));
+ }
let mut g = self.inner.lock().unwrap();
let g = &mut *g;
let Some(l) = g.live.get_mut(&key) else { return Ok(HookReply::default()) };
diff --git a/src/main.rs b/src/main.rs
index c722675..2541bab 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,6 +1,7 @@
mod agent;
mod claude;
mod client;
+mod codex;
mod config;
mod daemon;
mod doing;
diff --git a/src/store.rs b/src/store.rs
index 899fa8d..ed4faf8 100644
--- a/src/store.rs
+++ b/src/store.rs
@@ -259,6 +259,15 @@ impl Store {
Ok(rows.collect::<rusqlite::Result<_>>()?)
}
+ /// Whether a mailbox has unread mail that wakes its session.
+ pub fn unread_wakes(&self, recipient: &str) -> Result<bool> {
+ Ok(self.db.query_row(
+ "SELECT EXISTS(SELECT 1 FROM messages WHERE recipient = ?1 AND read_at IS NULL AND held = 0 AND wake != 0)",
+ [recipient],
+ |r| r.get(0),
+ )?)
+ }
+
pub fn unread_count(&self, recipient: &str) -> Result<u32> {
Ok(self.db.query_row(
"SELECT COUNT(*) FROM messages WHERE recipient = ?1 AND read_at IS NULL AND held = 0",
diff --git a/tests/e2e/codex_busy.py b/tests/e2e/codex_busy.py
new file mode 100644
index 0000000..3deca17
--- /dev/null
+++ b/tests/e2e/codex_busy.py
@@ -0,0 +1,362 @@
+"""Codex delivery routing against an isolated daemon, a queue-accepting fake CLI and fake rollouts.
+
+Mail to a Codex turn that is still running waits for its next PostToolUse (or Stop), however long the turn runs.
+Mail to a thread whose last turn ended (completed, interrupted or failed: the last two run no Stop hook) wakes it
+through `codex queue`. Each fake rollout records turns the way Codex does (`task_started`, then `task_complete` or
+`turn_aborted`); the fake CLI records queue commands. Neither proves what real Codex shows.
+
+ cargo build && python3 tests/e2e/codex_busy.py # about 2.5 minutes: it waits out real two-minute gaps
+"""
+import json
+import os
+import queue
+import socket
+import sqlite3
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+
+ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+BIN = os.path.join(ROOT, "target", "debug", "reason-network")
+LONG = 130 # past two minutes, the bound the hooks alone could tell
+
+results = []
+lock = threading.Lock()
+
+
+def check(name, ok, detail=""):
+ with lock:
+ results.append(ok)
+ print(f"{'PASS' if ok else 'FAIL'}: {name}" + ("" if ok else f"\n {detail}"), flush=True)
+
+
+with tempfile.TemporaryDirectory(prefix="rn-codex-") as d:
+ queue_log = os.path.join(d, "queue.log")
+ fake = os.path.join(d, "codex")
+ with open(fake, "w") as f:
+ f.write('#!/bin/sh\nprintf "%s\\n" "$*" >> "$CODEX_QUEUE_LOG"\n')
+ os.chmod(fake, 0o755)
+ env = {k: v for k, v in os.environ.items() if not k.startswith(("CLAUDE", "CODEX", "REASON_NETWORK", "TINCAN"))}
+ env.update(REASON_NETWORK_HOME=os.path.join(d, "home"), REASON_NETWORK_NO_MDNS="1",
+ REASON_NETWORK_NO_SERVICE="1", REASON_NETWORK_MACHINE="box",
+ REASON_NETWORK_CODEX_BIN=fake, CODEX_QUEUE_LOG=queue_log)
+
+ def run(*args, payload=None, cwd=d):
+ r = subprocess.run([BIN, *args], env=env, cwd=cwd, input=json.dumps(payload) if payload else None,
+ capture_output=True, text=True, timeout=30)
+ assert r.returncode == 0, r.stdout + r.stderr
+ return (r.stdout + r.stderr).strip()
+
+ class Thread:
+ """One Codex thread: its folder (so its name, `<folder>-codex`), its hooks and its rollout."""
+
+ def __init__(self, name, transcript=True):
+ self.name, self.cwd = f"{name}-codex", os.path.join(d, name)
+ os.makedirs(self.cwd)
+ self.rollout = os.path.join(d, f"rollout-{name}.jsonl") if transcript else None
+ if self.rollout:
+ self.record("session_meta", top=True)
+
+ def record(self, kind, top=False, **extra):
+ line = {"timestamp": "2026-10-22T00:00:00.000Z"}
+ if top:
+ line.update(type=kind, payload={"id": self.name})
+ else:
+ line.update(type="event_msg", payload={"type": kind, **extra})
+ with open(self.rollout, "a") as f:
+ f.write(json.dumps(line) + "\n")
+
+ def hook(self, event):
+ payload = {"session_id": f"thread-{self.name}", "cwd": self.cwd}
+ if self.rollout:
+ payload["transcript_path"] = self.rollout
+ return run("hook", "codex", event, payload=payload, cwd=self.cwd)
+
+ def start_turn(self):
+ self.record("task_started", turn_id="t")
+ self.hook("user-prompt-submit")
+
+ def send(self, body, *flags):
+ return run("send", self.name, *flags, body)
+
+ def queued(body=None):
+ """How many queue commands carried `body`; without one, the bodies queued so far (for failure details)."""
+ text = open(queue_log).read() if os.path.exists(queue_log) else ""
+ if body is not None:
+ return text.count(body)
+ return [line for line in text.splitlines() if line and not line.startswith(("queue ", "<", "From "))]
+
+ def queued_within(body, secs):
+ deadline = time.monotonic() + secs
+ while not queued(body) and time.monotonic() < deadline:
+ time.sleep(0.05)
+ return queued(body) > 0
+
+ def read(body, secs=5):
+ with sqlite3.connect(os.path.join(env["REASON_NETWORK_HOME"], "network.db")) as db:
+ deadline = time.monotonic() + secs
+ while True:
+ row = db.execute("SELECT read_at FROM messages WHERE body = ?", (body,)).fetchone()
+ if (row and row[0] is not None) or time.monotonic() >= deadline:
+ return bool(row and row[0] is not None)
+ time.sleep(0.05)
+
+ def shown_once(t, body, event="post-tool-use"):
+ out = t.hook(event)
+ again = t.hook("post-tool-use")
+ return body in out and body not in again, f"{event}: {out!r}; next: {again!r}"
+
+ # Each scenario runs in its own thread against the one daemon, so the real waits overlap.
+
+ def busy():
+ t = Thread("busy")
+ t.start_turn()
+ t.send("busy message")
+ run("who") # a queue command, if one were started, finishes meanwhile
+ ok, detail = shown_once(t, "busy message")
+ check("busy: the next PostToolUse shows the message, once", ok and '"PostToolUse"' in detail, detail)
+ check("busy: …and it is not queued as well", queued("busy message") == 0, queued())
+
+ def idle():
+ t = Thread("idle")
+ t.start_turn()
+ t.hook("post-tool-use")
+ t.hook("stop")
+ t.record("task_complete", turn_id="t")
+ out = t.send("idle message")
+ check("idle: the sender hears it is queued into Codex", "queued into the Codex session" in out, out)
+ check("idle: woken through codex queue", queued_within("idle message", 5), queued())
+ check("idle: the queue's success counts as delivered", read("idle message"))
+ check("idle: …and no hook shows it again", t.hook("post-tool-use") == "")
+
+ def ending():
+ # Mail that lands between Stop and the turn's end in the rollout.
+ t = Thread("ending")
+ t.start_turn()
+ t.hook("post-tool-use")
+ t.hook("stop")
+ t.send("ending message")
+ time.sleep(0.5)
+ t.record("task_complete", turn_id="t")
+ check("turn ending: queued once the rollout records the end", queued_within("ending message", 10), queued())
+ check("turn ending: …once", read("ending message") and queued("ending message") == 1, queued())
+
+ def interrupted():
+ t = Thread("interrupted")
+ t.start_turn()
+ t.hook("post-tool-use")
+ t.record("turn_aborted", turn_id="t", reason="interrupted") # no Stop
+ t.send("after interrupt")
+ check("interrupted: new mail wakes through codex queue right away", queued_within("after interrupt", 10),
+ queued())
+ check("interrupted: …once, and no hook shows it again",
+ read("after interrupt") and queued("after interrupt") == 1 and t.hook("post-tool-use") == "")
+
+ def interrupted_pending():
+ t = Thread("pending")
+ t.start_turn()
+ t.hook("post-tool-use")
+ bodies = [f"waiting at interrupt {i}" for i in range(3)]
+ for body in bodies:
+ t.send(body)
+ time.sleep(1)
+ check("interrupted with mail waiting: held for the hook while the turn runs",
+ all(queued(b) == 0 for b in bodies), queued())
+ t.record("turn_aborted", turn_id="t", reason="interrupted") # no Stop
+ check("interrupted with mail waiting: queued within seconds of the interrupt",
+ all(queued_within(b, 10) for b in bodies), queued())
+ time.sleep(3)
+ check("interrupted with mail waiting: each once, in one queue command",
+ all(read(b) and queued(b) == 1 for b in bodies) and queued("--thread thread-pending-codex ") == 1,
+ queued())
+ check("interrupted with mail waiting: no hook shows it again", t.hook("post-tool-use") == "")
+
+ def daemon(request):
+ """One request straight over the daemon's socket, as a hook client sends it; returns its result."""
+ with socket.socket(socket.AF_UNIX) as sock:
+ sock.settimeout(30)
+ sock.connect(os.path.join(env["REASON_NETWORK_HOME"], "network.sock"))
+ sock.sendall((json.dumps({"id": 1, **request}) + "\n").encode())
+ reply = json.loads(sock.makefile().readline())
+ assert reply.get("ok"), reply
+ return reply.get("result")
+
+ def unconfirmed():
+ # A PostToolUse showed the mail, and its confirmation comes only after the turn was interrupted: while it may
+ # still come, the mail is left to that hook, not queued as well (which would show it twice).
+ t = Thread("late")
+ t.start_turn()
+ t.hook("post-tool-use")
+ t.send("confirmed late")
+ shown = daemon({"op": "hook", "agent": "codex", "event": "tool", "session_id": f"thread-{t.name}",
+ "cwd": t.cwd, "transcript": t.rollout})
+ t.record("turn_aborted", turn_id="t", reason="interrupted") # no Stop
+ time.sleep(6)
+ daemon({"op": "delivered", "key": f"codex:thread-{t.name}", "ids": shown["ids"]})
+ time.sleep(3)
+ check("confirmed late: the hook showed it, and it is not queued as well",
+ "confirmed late" in (shown["text"] or "") and read("confirmed late") and queued("confirmed late") == 0,
+ (shown, queued()))
+ # A PostToolUse took the mail but could not print it, so never confirms: queued once that is overdue (90 s).
+ u = Thread("unconfirmed")
+ u.start_turn()
+ u.hook("post-tool-use")
+ u.send("never confirmed")
+ r, w = os.pipe()
+ os.close(r)
+ try:
+ payload = {"session_id": f"thread-{u.name}", "cwd": u.cwd, "transcript_path": u.rollout}
+ subprocess.run([BIN, "hook", "codex", "post-tool-use"], env=env, cwd=u.cwd, input=json.dumps(payload),
+ text=True, stdout=w, stderr=subprocess.DEVNULL, timeout=30)
+ finally:
+ os.close(w)
+ u.record("turn_aborted", turn_id="t", reason="interrupted") # no Stop
+ time.sleep(6)
+ check("never confirmed: not queued at the interrupt, while its confirmation may come",
+ queued("never confirmed") == 0, queued())
+ check("never confirmed: queued once that is overdue", queued_within("never confirmed", 100), queued())
+ time.sleep(3)
+ check("never confirmed: …once", read("never confirmed") and queued("never confirmed") == 1, queued())
+
+ def no_rollout():
+ # A thread whose hooks name no rollout (Codex has none for a remote thread store): as before, codex queue.
+ t = Thread("norollout", transcript=False)
+ t.hook("user-prompt-submit")
+ t.hook("post-tool-use")
+ t.send("no rollout message")
+ check("no rollout known: woken through codex queue, as before", queued_within("no rollout message", 5),
+ queued())
+
+ def failed():
+ t = Thread("failed")
+ t.start_turn()
+ t.hook("post-tool-use")
+ t.record("task_complete", turn_id="t", last_agent_message=None,
+ error={"message": "stream disconnected"}) # a failed turn: no Stop
+ t.send("after failure")
+ check("failed turn: mail wakes through codex queue right away", queued_within("after failure", 10), queued())
+
+ def continued():
+ # Stop hands over mail (decision: block), so the turn goes on; mail for it still waits for the hook.
+ t = Thread("continued")
+ t.start_turn()
+ t.hook("post-tool-use")
+ t.send("first message")
+ out = t.hook("stop")
+ check("continued: Stop shows the first message as a block", "first message" in out and '"block"' in out, out)
+ t.send("second message")
+ time.sleep(3)
+ check("continued: the second message is not queued while the turn goes on", queued("second message") == 0,
+ queued())
+ ok, detail = shown_once(t, "second message")
+ check("continued: the next PostToolUse shows the second message, once", ok, detail)
+
+ def long_call():
+ # One tool call runs past two minutes (a long build); mail arrives during it.
+ t = Thread("longcall")
+ t.start_turn()
+ t.hook("post-tool-use")
+ time.sleep(LONG)
+ t.send("during the long call")
+ time.sleep(3)
+ check("long tool call: mail during it is not queued behind the turn", queued("during the long call") == 0,
+ queued())
+ ok, detail = shown_once(t, "during the long call")
+ check("long tool call: the PostToolUse after it shows the mail, once", ok, detail)
+
+ def long_gap():
+ # Mail arrives just after a tool call; the next one comes more than two minutes later (long thinking).
+ t = Thread("longgap")
+ t.start_turn()
+ t.hook("post-tool-use")
+ t.send("early in the gap")
+ time.sleep(LONG)
+ check("long gap: mail is still waiting for the hook, not queued", queued("early in the gap") == 0, queued())
+ ok, detail = shown_once(t, "early in the gap")
+ check("long gap: the next PostToolUse shows it, once", ok, detail)
+
+ def long_turn():
+ # A turn with many short tool calls, longer than any bound: every message arrives at the next tool call.
+ t = Thread("longturn")
+ t.start_turn()
+ started, sent, missed = time.monotonic(), 0, []
+ while time.monotonic() - started < LONG:
+ body = f"long turn message {sent}"
+ t.send(body)
+ sent += 1
+ time.sleep(10)
+ out = t.hook("post-tool-use")
+ if body not in out:
+ missed.append((body, out))
+ time.sleep(10)
+ t.hook("post-tool-use")
+ check(f"long turn: all {sent} messages arrived at the next PostToolUse", not missed, missed)
+ check("long turn: none queued", queued("long turn message") == 0, queued())
+
+ try:
+ run("init", "codex-test", "--as", "alex", "--no-setup")
+
+ # FYI mail never wakes: it waits for check_inbox (or a pause).
+ fyi = Thread("fyi")
+ fyi.start_turn()
+ cx = subprocess.Popen([BIN, "mcp"], env=env, cwd=fyi.cwd, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+ stderr=subprocess.DEVNULL, text=True)
+ try:
+ def rpc(request):
+ cx.stdin.write(json.dumps(request) + "\n")
+ cx.stdin.flush()
+ if "id" not in request:
+ return None
+ responses = queue.Queue()
+
+ def receive():
+ while line := cx.stdout.readline():
+ response = json.loads(line)
+ if response.get("id") == request["id"]:
+ responses.put(response)
+ return
+
+ threading.Thread(target=receive, daemon=True).start()
+ return responses.get(timeout=10)
+
+ rpc({"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {
+ "protocolVersion": "2025-06-18", "capabilities": {},
+ "clientInfo": {"name": "codex-mcp-client", "version": "1"}}})
+ rpc({"jsonrpc": "2.0", "method": "notifications/initialized"})
+ out = fyi.send("polled FYI", "--fyi")
+ check("fyi: queued as FYI", "queued as FYI" in out, out)
+ check("fyi: not shown at PostToolUse", fyi.hook("post-tool-use") == "")
+ response = rpc({"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {
+ "name": "check_inbox", "arguments": {}, "_meta": {"sessionId": f"thread-{fyi.name}"}}})
+ check("fyi: check_inbox returns it", "polled FYI" in json.dumps(response), response)
+ check("fyi: never queued", queued("polled FYI") == 0, queued())
+ finally:
+ cx.kill()
+ cx.wait()
+
+ scenarios = [busy, idle, ending, interrupted, interrupted_pending, unconfirmed, failed, continued, no_rollout,
+ long_call, long_gap, long_turn]
+ print(f"Running {len(scenarios)} scenarios at once; the long ones wait {LONG} seconds", flush=True)
+ threads = [threading.Thread(target=s) for s in scenarios]
+ for th in threads:
+ th.start()
+ for th in threads:
+ th.join()
+
+ # A daemon restart while mail waits for a running turn: the next PostToolUse still shows it, once.
+ r = Thread("restart")
+ r.start_turn()
+ r.hook("post-tool-use")
+ r.send("across a restart")
+ run("stop")
+ ok, detail = shown_once(r, "across a restart")
+ check("restart: mail waiting for a running turn reaches the next PostToolUse", ok, detail)
+ check("restart: …and is not queued", queued("across a restart") == 0, queued())
+ finally:
+ run("stop")
+
+ failed_count = results.count(False)
+ print(f"\n{len(results) - failed_count}/{len(results)} passed")
+ sys.exit(1 if failed_count else 0)