Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

A follow-up typed mid-reply supersedes the streaming reply

justrachb3f5001cc8fd
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ddd09ed5..6f8e1e24 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -220,6 +220,12 @@ jobs:
- name: PTY /goal run holds for its own background work (#1278)
run: python3 scripts/test-pty-goal-hold.py zig-out/bin/graff
+ - name: PTY a follow-up typed mid-reply supersedes it (line REPL)
+ run: python3 scripts/test-pty-steer-mid-reply.py zig-out/bin/graff
+
+ - name: TUI a follow-up typed mid-reply joins the running turn
+ run: python3 scripts/test-tui-steer-mid-reply.py zig-out/bin/graff
+
- name: PTY peer-channel delivery smoke test (#469)
run: python3 scripts/test-pty-peer-channel.py zig-out/bin/graff
diff --git a/TUI/dispatch.zig b/TUI/dispatch.zig
index 5153fbdc..eed59ab9 100644
--- a/TUI/dispatch.zig
+++ b/TUI/dispatch.zig
@@ -72,6 +72,20 @@ fn withImages(self: *Model, line: []const u8) []const u8 {
/// Queue a mid-turn follow-up, including any attached chips. Idle applyLine
/// already prefixes `@[path]`; steer used to copy only the typed text, so the
/// pixels never left the composer.
+/// A follow-up typed with Enter mid-turn. Plain text joins the running turn
+/// (a streaming reply restarts with it); commands and image chips wait for
+/// the turn to end, as a /btw aside does.
+pub fn steerLine(self: *Model, text: []const u8) void {
+ const line = std.mem.trim(u8, text, " \t\r\n");
+ if (self.images.items.len == 0 and line.len > 0 and line[0] != '/') if (engine.g_steer_send_fn) |send| if (send(line)) {
+ if (engine.g_followup_fn) |f| f();
+ self.input.setValue("") catch {};
+ self.push(.system, "↳ sent to the running turn") catch {};
+ return;
+ };
+ queueSteerLine(self, text);
+}
+
pub fn queueSteerLine(self: *Model, text: []const u8) void {
const line = std.mem.trim(u8, text, " \t\r\n");
if (line.len == 0 and self.images.items.len == 0) return;
diff --git a/TUI/dispatch_command_tests.zig b/TUI/dispatch_command_tests.zig
index cd836f42..32f5fb7a 100644
--- a/TUI/dispatch_command_tests.zig
+++ b/TUI/dispatch_command_tests.zig
@@ -459,3 +459,68 @@ test "lastLines caps ! output to the tail" {
try std.testing.expectEqualStrings("c\nd", lastLines("a\nb\nc\nd", 2));
try std.testing.expectEqualStrings("a\nb", lastLines("a\nb", 5));
}
+
+var handed_buf: [128]u8 = undefined;
+var handed_len: usize = 0;
+var hand_accepts = true;
+fn fakeSteerSend(text: []const u8) bool {
+ if (!hand_accepts) return false;
+ handed_len = @min(text.len, handed_buf.len);
+ @memcpy(handed_buf[0..handed_len], text[0..handed_len]);
+ return true;
+}
+
+fn pendingModel(m: *Model) !*engine.Job {
+ m.setup(std.testing.allocator);
+ const job = try std.testing.allocator.create(engine.Job);
+ job.* = .{ .gpa = std.testing.allocator, .history = &.{}, .params = .{}, .stream = .{}, .threaded = false };
+ m.pending = job;
+ return job;
+}
+
+test "Enter mid-turn hands plain text to the running turn" {
+ var m: Model = undefined;
+ const job = try pendingModel(&m);
+ defer {
+ m.pending = null;
+ std.testing.allocator.destroy(job);
+ m.deinit();
+ }
+ engine.g_steer_send_fn = fakeSteerSend;
+ defer engine.g_steer_send_fn = null;
+ hand_accepts = true;
+ handed_len = 0;
+ try m.input.setValue("also run the tests");
+ turn.steerEnter(&m);
+ try std.testing.expectEqualStrings("also run the tests", handed_buf[0..handed_len]);
+ try std.testing.expectEqual(@as(usize, 0), m.steer_queue.items.len);
+ try std.testing.expectEqualStrings("", m.input.getValue());
+ try std.testing.expect(std.mem.indexOf(u8, m.history.items[m.history.items.len - 1].text, "sent to the running turn") != null);
+}
+
+test "commands, images, /btw and a refused hand-off still wait for the turn" {
+ var m: Model = undefined;
+ const job = try pendingModel(&m);
+ defer {
+ m.pending = null;
+ std.testing.allocator.destroy(job);
+ m.deinit();
+ }
+ engine.g_steer_send_fn = fakeSteerSend;
+ defer engine.g_steer_send_fn = null;
+ hand_accepts = true;
+ handed_len = 0;
+ try m.input.setValue("/model gpt-6");
+ turn.steerEnter(&m);
+ m.attachImage("/tmp/shot.png");
+ try m.input.setValue("look at this");
+ turn.steerEnter(&m);
+ _ = applyLine(&m, "/btw remember the tests");
+ hand_accepts = false;
+ try m.input.setValue("plain but refused");
+ turn.steerEnter(&m);
+ try std.testing.expectEqual(@as(usize, 0), handed_len); // nothing was handed over
+ try std.testing.expectEqual(@as(usize, 4), m.steer_queue.items.len);
+ try std.testing.expectEqualStrings("remember the tests", m.steer_queue.items[2]);
+ try std.testing.expectEqualStrings("plain but refused", m.steer_queue.items[3]);
+}
diff --git a/TUI/engine.zig b/TUI/engine.zig
index e4dab1d9..6c113923 100644
--- a/TUI/engine.zig
+++ b/TUI/engine.zig
@@ -66,6 +66,14 @@ pub var g_raw: ?*StreamBuf = null;
pub const FollowupFn = *const fn () void;
pub var g_followup_fn: ?FollowupFn = null;
+/// Host sets these so a plain-text follow-up typed mid-turn joins the running
+/// turn: `send` hands it over (a streaming reply restarts with it), and
+/// `reclaim` takes back any the turn ended before delivering, to run next.
+pub const SteerSendFn = *const fn (text: []const u8) bool;
+pub var g_steer_send_fn: ?SteerSendFn = null;
+pub const SteerReclaimFn = *const fn (gpa: std.mem.Allocator, out: *std.array_list.Managed([]const u8)) void;
+pub var g_steer_reclaim_fn: ?SteerReclaimFn = null;
+
/// Idle auto-wake: a finished background job wants a turn (grok-build notify).
pub const IdleWakeFn = *const fn (turn_ctx: ?*anyopaque, buf: []u8) ?[]const u8;
pub var g_idle_wake_fn: ?IdleWakeFn = null;
diff --git a/TUI/root.zig b/TUI/root.zig
index 0f90e1b4..96d8cb7a 100644
--- a/TUI/root.zig
+++ b/TUI/root.zig
@@ -24,6 +24,10 @@ pub fn rawStream() ?*engine.StreamBuf {
pub fn setFollowupFn(f: ?engine.FollowupFn) void {
engine.g_followup_fn = f;
}
+pub fn setSteerFns(send: ?engine.SteerSendFn, reclaim: ?engine.SteerReclaimFn) void {
+ engine.g_steer_send_fn = send;
+ engine.g_steer_reclaim_fn = reclaim;
+}
pub const Event = engine.Event;
pub const EventQueue = engine.EventQueue;
pub const ToolEvent = engine.ToolEvent;
diff --git a/TUI/turn.zig b/TUI/turn.zig
index 96bb049a..631bb179 100644
--- a/TUI/turn.zig
+++ b/TUI/turn.zig
@@ -108,6 +108,7 @@ pub fn finishJob(self: *Model) void {
job.events.deinit();
self.alloc.destroy(job);
self.pending = null;
+ if (engine.g_steer_reclaim_fn) |f| f(self.alloc, &self.steer_queue); // undelivered follow-ups run next
@import("owned_images.zig").collect(self);
self.cancel_requested = false;
self.scroll = 0;
@@ -150,7 +151,7 @@ pub fn drainSteer(self: *Model) Effect {
pub fn steerEnter(self: *Model) void {
const v = std.mem.trim(u8, self.input.getValue(), " \t\r\n");
if (v.len > 0 or self.images.items.len > 0) {
- @import("dispatch.zig").queueSteerLine(self, v);
+ @import("dispatch.zig").steerLine(self, v);
} else if (self.steer_queue.items.len > 0) {
cancelTurn(self);
self.push(.system, "↳ force › interrupting…") catch {};
diff --git a/docs/adr/0217-follow-ups-supersede-the-streaming-reply.md b/docs/adr/0217-follow-ups-supersede-the-streaming-reply.md
new file mode 100644
index 00000000..8f5b2bbd
--- /dev/null
+++ b/docs/adr/0217-follow-ups-supersede-the-streaming-reply.md
@@ -0,0 +1,42 @@
+# 0217. A follow-up typed mid-reply supersedes the streaming reply
+
+Status: accepted 2026-09-29
+
+## Context
+
+A follow-up typed during a turn used to wait. The line REPL delivered it at
+the next step boundary, after the model had finished its whole reply and its
+tools had run. The TUI held it until the whole turn ended. Only GPT-6 over the
+Responses WebSocket could act on it mid-reply, through the provider's
+server-side `response.steer`. A model spending a minute on a reply the user
+had already asked to change kept going to the end.
+
+The unreal-agent harness treats input that lands during an active model
+request as a reason to cut that request and rebuild it with the input.
+
+## Decision
+
+- While the root's own turn request is streaming (SSE, HTTP/2, or a WebSocket
+ without server-side steer), a pending plain follow-up cuts the stream
+ (`stream_aborted = steered`). The partial reply was never committed to
+ history, so it is dropped. The follow-up is delivered and the request
+ rebuilt (`steer_now.zig`, `request()`'s rebuild loop). The transcript says
+ "follow-up received — restarting the reply".
+- Not superseded: compaction, titles, judges, children, a stream whose early
+ async tools already started (ADR 0177), and GPT-6 on the Responses
+ WebSocket, which steers server-side. Tools that are already running finish,
+ and the follow-up lands at the next step boundary as before.
+- A force follow-up (double Enter in the line REPL, empty Enter in the TUI)
+ still interrupts the turn.
+- In the TUI, Enter mid-turn hands plain text to the running turn. Commands,
+ image chips and `/btw` asides still wait for the turn to end. A follow-up
+ the turn ended before delivering runs as the next turn.
+- ACP clients are unchanged: a `session/prompt` sent during a turn still
+ queues as the next request.
+
+## Consequences
+
+- The cut request's output tokens are billed and thrown away.
+- The partial reply on screen is replaced by the new one. That is the point:
+ the user asked for something different.
+- Revisit for ACP once a client can say that a prompt joins the running turn.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 874f7708..101e4bb4 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -243,6 +243,7 @@ record only when you need the evidence or the edge cases.
| [0214](0214-evals-are-mined-and-hillclimbed-on-a-held-out-split.md) | Mine live eval tasks from merged PRs, with graders validated red on the parent and green and stable on the merge, and a person approving each. Hill-climb on a fixed held-out split with measured noise: keep a change only when train beats the noise band and test improves. Model-guide advice enters as candidates, not edits. |
| [0215](0215-headless-runs-wait-until-idle.md) | Headless roots (`-p`, `--json`, `graff serve`, piped stdin) wait for their own background work to report before a plain final ends the run. Servers do not count, a 10-minute heartbeat wakes the model, and interactive surfaces keep their idle wake. |
| [0216](0216-loop-is-retired.md) | `/loop` is retired: `/goal` is the one autonomous run, and waiting for background work is how every run works (ADR 0215). Typing `/loop` prints a pointer to `/goal` and makes no model call. |
+| [0217](0217-follow-ups-supersede-the-streaming-reply.md) | A plain follow-up typed while the root reply streams cuts that stream, drops the uncommitted partial and rebuilds the request with the follow-up (not for compaction, children, started async tools, or GPT-6 WebSocket steer). TUI Enter hands plain text to the running turn; `/btw`, commands and images still wait; ACP is unchanged. |
## When to write one
diff --git a/scripts/codex_ws_mock.py b/scripts/codex_ws_mock.py
index e46080bf..e502461c 100644
--- a/scripts/codex_ws_mock.py
+++ b/scripts/codex_ws_mock.py
@@ -226,6 +226,12 @@ class CodexMock:
raw_for_request: Callable[[RecordedRequest], bytes | None] | None = field(
default=None, repr=False
)
+ # Optional per-request pause between events (SSE and WebSocket), so a reply
+ # streams slowly enough for a test to act mid-stream. SSE goes chunked; a
+ # client that hangs up mid-stream just ends the response.
+ delay_for_request: Callable[[RecordedRequest], float] | None = field(
+ default=None, repr=False
+ )
requests: list[RecordedRequest] = field(default_factory=list, repr=False)
prewarm_ids: dict[int, str] = field(default_factory=dict, repr=False)
_sock: socket.socket | None = field(default=None, repr=False)
@@ -413,12 +419,16 @@ class CodexMock:
separators=(",", ":")).encode("utf-8"))
self._log("ws -> response.completed (prewarm)")
continue
- events = self._events("ws", connection_id, event, headers)
+ request = self._record("ws", connection_id, event, headers)
+ events = self._events_for(request)
+ delay = self.delay_for_request(request) if self.delay_for_request else 0.0
for ev in events:
_send_frame(
conn, OP_TEXT, json.dumps(ev, separators=(",", ":")).encode("utf-8")
)
self._log(f"ws -> {ev['type']}")
+ if delay > 0:
+ time.sleep(delay)
with self._lock:
self.ws_turns += 1
# Real Codex closes immediately after a terminal type:error frame.
@@ -450,6 +460,10 @@ class CodexMock:
self.sse_turns += 1
return
events = self._events_for(request)
+ delay = self.delay_for_request(request) if self.delay_for_request else 0.0
+ if delay > 0:
+ self._serve_sse_slow(conn, events, delay)
+ return
payload = "".join(
f"data: {json.dumps(ev, separators=(',', ':'))}\n\n" for ev in events
).encode("utf-8")
@@ -468,6 +482,23 @@ class CodexMock:
with self._lock:
self.sse_turns += 1
+ def _serve_sse_slow(self, conn: socket.socket, events: list[dict], delay: float) -> None:
+ conn.sendall(
+ b"HTTP/1.1 200 OK\r\nContent-Type: text/event-stream\r\n"
+ b"Transfer-Encoding: chunked\r\nConnection: close\r\n\r\n"
+ )
+ try:
+ for ev in events:
+ data = f"data: {json.dumps(ev, separators=(',', ':'))}\n\n".encode("utf-8")
+ conn.sendall(f"{len(data):x}\r\n".encode("ascii") + data + b"\r\n")
+ self._log(f"sse -> {ev['type']} (slow)")
+ time.sleep(delay)
+ conn.sendall(b"0\r\n\r\n")
+ except OSError as exc:
+ self._log(f"sse slow stream ended early: {exc}")
+ with self._lock:
+ self.sse_turns += 1
+
def main() -> None:
parser = argparse.ArgumentParser(
diff --git a/scripts/test-pty-steer-mid-reply.py b/scripts/test-pty-steer-mid-reply.py
new file mode 100644
index 00000000..7e13fef1
--- /dev/null
+++ b/scripts/test-pty-steer-mid-reply.py
@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""Real-PTY regression: a follow-up typed while the reply streams supersedes it.
+
+Mock script (by request ordinal):
+ 1 "tell me a story" -> a long reply streamed slowly. Mid-stream the user
+ types a follow-up and presses Enter. The stream must be cut there.
+ 2 the rebuilt request -> a short reply. It must carry the follow-up and
+ none of the abandoned partial reply, which never entered history.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+
+from codex_ws_mock import USAGE, CodexMock, RecordedRequest, turn_events
+from pty_harness import PtySession
+
+
+_arg = sys.argv[1] if len(sys.argv) > 1 else "graff"
+GRAFF = os.path.abspath(_arg) if os.sep in _arg else _arg
+
+WORDS = [f"PARTIAL_STORY_{i:02d} " for i in range(60)]
+FOLLOW_UP = "also mention the tests"
+
+
+def story_events() -> list[dict]:
+ events: list[dict] = [
+ {"type": "response.output_text.delta", "item_id": "msg_story", "output_index": 0, "content_index": 0, "delta": w}
+ for w in WORDS
+ ]
+ events.append({
+ "type": "response.output_item.done",
+ "item": {
+ "type": "message",
+ "id": "msg_story",
+ "status": "completed",
+ "role": "assistant",
+ "content": [{"type": "output_text", "text": "".join(WORDS), "annotations": []}],
+ },
+ })
+ events.append({"type": "response.completed", "response": {"id": "resp_story", "usage": dict(USAGE)}})
+ return events
+
+
+def events(request: RecordedRequest) -> list[dict]:
+ if request.ordinal == 1:
+ return story_events()
+ done = turn_events(f"resp_steer_{request.ordinal}")
+ done[0]["item"]["content"][0]["text"] = "STEERED_REPLY_DONE"
+ return done
+
+
+def run_case(label: str, env_extra: dict[str, str], model: str) -> None:
+ mock = CodexMock(
+ events_for_request=events,
+ delay_for_request=lambda r: 0.12 if r.ordinal == 1 else 0.0,
+ )
+ port = mock.start()
+ try:
+ with tempfile.TemporaryDirectory(prefix="graff-steer-") as tmp:
+ codex_home = os.path.join(tmp, "codex-home")
+ os.makedirs(codex_home)
+ with open(os.path.join(codex_home, "auth.json"), "w", encoding="utf-8") as fh:
+ json.dump({"tokens": {"access_token": "steer-mock", "account_id": "acct-steer"}}, fh)
+ harness_dir = os.path.join(tmp, ".harness")
+ os.makedirs(harness_dir)
+ with open(os.path.join(harness_dir, "settings.json"), "w", encoding="utf-8") as fh:
+ # Title/recap calls would shift the scripted request ordinals.
+ json.dump({"ai_title": False, "session_recap": False, "skills": {"codedbpro": False}}, fh)
+ env = {
+ "HOME": tmp,
+ "CODEX_HOME": codex_home,
+ "GRAFF_CODEX_URL": f"http://127.0.0.1:{port}/backend-api/codex/responses",
+ "GRAFF_FLEET": "off",
+ "GRAFF_NO_TELEMETRY": "1",
+ **env_extra,
+ }
+ ambient = tuple(
+ name
+ for name in os.environ
+ if (name.startswith("GRAFF_") or name.startswith("CODEX_") or name == "NO_COLOR")
+ and name not in env
+ )
+ with PtySession(
+ GRAFF,
+ ["--model", model, "--no-telemetry", "--yolo"],
+ cwd=tmp,
+ env=env,
+ unset_env=ambient,
+ timeout=20.0,
+ ) as session:
+ session.wait_for_prompt()
+ cursor = len(session.raw)
+ session.send_line("tell me a story")
+ session.wait_for_literal("PARTIAL_STORY_03", start=cursor, timeout=15.0)
+ session.send_line(FOLLOW_UP)
+ session.wait_for_literal("restarting the reply", start=cursor, timeout=15.0)
+ session.wait_for_literal("STEERED_REPLY_DONE", start=cursor, timeout=15.0)
+ session.wait_for_prompt(start=cursor)
+ session.send_key("ctrl-d")
+ result = session.read_until_exit(5.0)
+ if result.timed_out or result.exit_code != 0:
+ raise AssertionError(f"{label}: session did not exit cleanly: exit={result.exit_code} timed_out={result.timed_out}")
+ finally:
+ mock.stop()
+
+ turns = [r for r in mock.recorded_requests() if r.body.get("generate") is not False]
+ if len(turns) != 2:
+ raise AssertionError(f"{label}: expected exactly 2 model requests, got {len(turns)}")
+ rebuilt = json.dumps(turns[1].body)
+ if FOLLOW_UP not in rebuilt:
+ raise AssertionError(f"{label}: the rebuilt request did not carry the follow-up: {rebuilt[-600:]!r}")
+ if "PARTIAL_STORY_" in rebuilt:
+ raise AssertionError(f"{label}: the abandoned partial reply leaked into the rebuilt request's history")
+ print(f"ok {label}: a follow-up typed mid-stream supersedes the reply and the request is rebuilt with it")
+
+
+def main() -> None:
+ run_case("sse", {"GRAFF_CODEX_WS": "off"}, "codex")
+ # A model without server-side response.steer: the WebSocket reply is cut too.
+ run_case("websocket", {}, "codex/gpt-5.6-sol")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/test-tui-steer-mid-reply.py b/scripts/test-tui-steer-mid-reply.py
new file mode 100644
index 00000000..f2a7a405
--- /dev/null
+++ b/scripts/test-tui-steer-mid-reply.py
@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""Live proof that a follow-up typed in the TUI while the reply streams joins
+the running turn: the streaming reply is superseded and the request rebuilt.
+
+Against the real binary under a pty, with a mock provider streaming slowly:
+
+ 1. boots `graff tui --yolo --model codex` pointed at scripts/codex_ws_mock,
+ 2. sends a prompt; the first reply streams a long story a word at a time,
+ 3. mid-stream, types a follow-up and presses Enter,
+ 4. asserts the second request carries the follow-up and none of the
+ abandoned partial story, and that its reply reaches the screen.
+
+Usage: python3 scripts/test-tui-steer-mid-reply.py [path/to/graff]
+Exit 0 = pass. Skips (exit 0, notice) with no pty support.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import tempfile
+import time
+
+from codex_ws_mock import USAGE, CodexMock, RecordedRequest, turn_events
+
+BIN = os.path.abspath(sys.argv[1] if len(sys.argv) > 1 else "zig-out/bin/graff")
+BOOT_MAX = 20.0
+ROWS, COLS = 40, 110
+WORDS = [f"PARTIAL_STORY_{i:02d} " for i in range(60)]
+FOLLOW_UP = "also mention the tests"
+
+
+def story_events() -> list[dict]:
+ events: list[dict] = [
+ {"type": "response.output_text.delta", "item_id": "msg_story", "output_index": 0, "content_index": 0, "delta": w}
+ for w in WORDS
+ ]
+ events.append({
+ "type": "response.output_item.done",
+ "item": {
+ "type": "message",
+ "id": "msg_story",
+ "status": "completed",
+ "role": "assistant",
+ "content": [{"type": "output_text", "text": "".join(WORDS), "annotations": []}],
+ },
+ })
+ events.append({"type": "response.completed", "response": {"id": "resp_story", "usage": dict(USAGE)}})
+ return events
+
+
+def events(request: RecordedRequest) -> list[dict]:
+ if request.ordinal == 1:
+ return story_events()
+ done = turn_events(f"resp_steer_{request.ordinal}")
+ done[0]["item"]["content"][0]["text"] = "STEERED_REPLY_DONE"
+ return done
+
+
+def drain(fd, seconds):
+ import select
+
+ out = b""
+ end = time.time() + seconds
+ while time.time() < end:
+ r, _, _ = select.select([fd], [], [], min(0.1, max(end - time.time(), 0.01)))
+ if not r:
+ continue
+ try:
+ chunk = os.read(fd, 65536)
+ except OSError:
+ break
+ if not chunk:
+ break
+ out += chunk
+ return out
+
+
+def resize(fd, rows, cols):
+ import fcntl
+ import struct
+ import termios
+
+ fcntl.ioctl(fd, termios.TIOCSWINSZ, struct.pack("HHHH", rows, cols, 0, 0))
+
+
+def boot(fd):
+ out = b""
+ end = time.time() + BOOT_MAX
+ while time.time() < end:
+ out += drain(fd, 0.3)
+ if b"\x1b[?1049h" in out:
+ return out + drain(fd, 1.5)
+ return out
+
+
+def wait_for(fd, needle, seconds):
+ out = b""
+ end = time.time() + seconds
+ while time.time() < end:
+ out += drain(fd, 0.3)
+ if needle.encode() in out:
+ return out
+ return None
+
+
+def spawn(cwd, env_extra, unset):
+ import pty
+
+ pid, fd = pty.fork()
+ if pid == 0:
+ os.chdir(cwd)
+ for name in unset:
+ os.environ.pop(name, None)
+ os.environ.update(env_extra)
+ os.execv(BIN, [BIN, "tui", "--yolo", "--model", "codex", "--no-telemetry"])
+ resize(fd, ROWS, COLS)
+ return pid, fd
+
+
+def reap(pid, fd):
+ import signal
+
+ try:
+ os.write(fd, b"\x11") # Ctrl+Q
+ drain(fd, 2.0)
+ except OSError:
+ pass
+ for call in (lambda: os.kill(pid, signal.SIGKILL), lambda: os.waitpid(pid, 0)):
+ try:
+ call()
+ except OSError:
+ pass
+
+
+def full_frame(fd):
+ """Screen rows, in order, from a FORCED full repaint (see #529's probe)."""
+ resize(fd, ROWS - 1, COLS)
+ drain(fd, 0.4)
+ resize(fd, ROWS, COLS)
+ stream = drain(fd, 1.5)
+ frame = stream.rsplit(b"\x1b[2J\x1b[H", 1)
+ if len(frame) < 2:
+ return None
+ text = re.sub(rb"\x1b\][^\x07\x1b]*(\x07|\x1b\\)", b"", frame[1])
+ text = re.sub(rb"\x1b\[[0-9;?<>]*[a-zA-Z]", b"", text)
+ return [ln.decode(errors="replace") for ln in text.split(b"\r\n")]
+
+
+def workspace(tmp, port):
+ codex_home = os.path.join(tmp, "codex-home")
+ os.makedirs(codex_home)
+ with open(os.path.join(codex_home, "auth.json"), "w", encoding="utf-8") as fh:
+ json.dump({"tokens": {"access_token": "steer-mock", "account_id": "acct-steer"}}, fh)
+ harness = os.path.join(tmp, ".harness")
+ os.makedirs(harness)
+ with open(os.path.join(harness, "settings.json"), "w", encoding="utf-8") as fh:
+ json.dump({"ai_title": False, "session_recap": False, "skills": {"codedbpro": False}}, fh)
+ empty_mcp = os.path.join(tmp, "empty-mcp.json")
+ with open(empty_mcp, "w", encoding="utf-8") as fh:
+ fh.write('{"mcpServers": {}}')
+ env = {
+ "HOME": tmp,
+ "CODEX_HOME": codex_home,
+ "GRAFF_CODEX_URL": f"http://127.0.0.1:{port}/backend-api/codex/responses",
+ "GRAFF_CODEX_WS": "off",
+ "GRAFF_FLEET": "off",
+ "GRAFF_NO_TELEMETRY": "1",
+ "GRAFF_MCP_CONFIG": empty_mcp,
+ "GRAFF_LEARN_AUTO": "off",
+ }
+ unset = tuple(
+ name
+ for name in os.environ
+ if (name.startswith("GRAFF_") or name.startswith("CODEX_") or name == "NO_COLOR")
+ and name not in env
+ )
+ return env, unset
+
+
+
+def run():
+ mock = CodexMock(events_for_request=events, delay_for_request=lambda r: 0.12 if r.ordinal == 1 else 0.0)
+ port = mock.start()
+ try:
+ with tempfile.TemporaryDirectory(prefix="graff-tui-steer-") as tmp:
+ env, unset = workspace(tmp, port)
+ pid, fd = spawn(tmp, env, unset)
+ try:
+ boot(fd)
+ os.write(fd, b"tell me a story\r")
+ if wait_for(fd, "PARTIAL_STORY_03", 20.0) is None:
+ return "the first reply never started streaming"
+ for ch in FOLLOW_UP:
+ os.write(fd, ch.encode())
+ time.sleep(0.01)
+ os.write(fd, b"\r")
+ if wait_for(fd, "STEERED_REPLY_DONE", 30.0) is None:
+ return "the rebuilt reply never reached the screen"
+ finally:
+ reap(pid, fd)
+ requests = mock.recorded_requests()
+ if len(requests) != 2:
+ return f"expected the story request and one rebuilt request, got {len(requests)}"
+ rebuilt = json.dumps(requests[1].body)
+ if FOLLOW_UP not in rebuilt:
+ return "the rebuilt request did not carry the follow-up"
+ if "PARTIAL_STORY_" in rebuilt:
+ return "the abandoned partial story leaked into the rebuilt request"
+ return None
+ finally:
+ mock.stop()
+
+
+def main():
+ if not os.path.exists(BIN):
+ print(f"tui-steer: {BIN} not built — skipping")
+ return 0
+ try:
+ import pty # noqa: F401
+ except ImportError:
+ print("tui-steer: no pty support here — skipping")
+ return 0
+ err = run()
+ if err:
+ print(f" ✗ tui steer: {err}")
+ return 1
+ print(" ✓ tui steer: a follow-up typed mid-stream joins the turn and rebuilds the reply")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/src/agent_request.zig b/src/agent_request.zig
index f40b397c..b054e003 100644
--- a/src/agent_request.zig
+++ b/src/agent_request.zig
@@ -254,6 +254,7 @@ pub fn request(self: *Agent, tools_in: ?[]const u8) !std.json.ObjectMap {
// transport. In particular, session-close cancellation of a
// detached title must not launch a replacement request.
if (err == error.Interrupted) return error.Interrupted;
+ if (err == error.Steered) if (@import("steer_now.zig").supersede(self)) continue :rebuild;
if (err == error.Canceled) return error.Canceled;
// #56: a mid-stream idle stall or a connection drop (the
// provider closed/reset before its terminal event) — NOT a
diff --git a/src/agent_stream.zig b/src/agent_stream.zig
index b9892969..ae2ac033 100644
--- a/src/agent_stream.zig
+++ b/src/agent_stream.zig
@@ -341,6 +341,11 @@ pub fn postStreamWithClient(self: *Agent, client: *std.http.Client, body: []cons
if (req.connection) |conn| conn.closing = true;
return error.Interrupted;
}
+ if (@import("steer_now.zig").pending(self)) { // a follow-up supersedes this reply
+ sink.emit(self.io, .{ .stream_aborted = .steered });
+ if (req.connection) |conn| conn.closing = true;
+ return error.Steered;
+ }
if (!more) break;
reader.toss(1);
}
diff --git a/src/agent_stream_h2.zig b/src/agent_stream_h2.zig
index 496be2ea..63c7c3b8 100644
--- a/src/agent_stream_h2.zig
+++ b/src/agent_stream_h2.zig
@@ -158,6 +158,10 @@ pub fn postStream(self: *Agent, body: []const u8, poll_stdin: bool) !?[]u8 {
sink.emit(self.io, .{ .stream_aborted = .interrupted });
return error.Interrupted;
}
+ if (@import("steer_now.zig").pending(self)) { // a follow-up supersedes this reply
+ sink.emit(self.io, .{ .stream_aborted = .steered });
+ return error.Steered;
+ }
}
// A connection the peer is draining (GOAWAY) takes no new streams.
keep = keep and head.lease.?.session.reusable();
diff --git a/src/agent_ws.zig b/src/agent_ws.zig
index 2ec23803..b5228886 100644
--- a/src/agent_ws.zig
+++ b/src/agent_ws.zig
@@ -119,7 +119,7 @@ pub fn postLive(self: *Agent, body: []const u8) ![]u8 {
if (!wsEligible(self)) return self.postStream(body);
const response = postResponsesWs(self, body) catch |e| {
if (@import("agent_async_tools.zig").started(self)) return e;
- if (e == error.Interrupted or e == error.StreamStalled or e == error.ModelLoop) return e;
+ if (e == error.Interrupted or e == error.StreamStalled or e == error.ModelLoop or e == error.Steered) return e;
// Preemptive idle expiry is not a failed transport attempt; it only asks
// request() to rebuild the already-created delta as full input.
if (e == error.CodexWsReanchor) return e;
@@ -583,6 +583,11 @@ pub fn postResponsesWs(self: *Agent, body: []const u8) ![]u8 {
break :stream;
}
if (orig_tio != null and escPressed(true)) return error.Interrupted;
+ // GPT-6 steers server-side (tick above); other models supersede the reply.
+ if (!@import("agent_ws_steer.zig").modelSupports(self.provider.model) and @import("steer_now.zig").pending(self)) {
+ engine_sink.forAgent(self).emit(self.io, .{ .stream_aborted = .steered });
+ return error.Steered;
+ }
}
self.traceFirstToken(); // tool-only responses fall back to completion time
self.codex_ws_used_ms = nowAwakeMs(self.io); // completed turn — restart the idle window (#codex-ws)
diff --git a/src/engine_events.zig b/src/engine_events.zig
index eb418905..be46836d 100644
--- a/src/engine_events.zig
+++ b/src/engine_events.zig
@@ -37,6 +37,7 @@ pub const StreamAbort = enum {
stalled,
/// The provider closed/reset the socket before its terminal event (#133).
dropped,
+ steered, // a follow-up superseded the streaming reply; the request is rebuilt with it (steer_now.zig)
};
/// A streamed content chunk. `text` is never empty — emitters drop empty
diff --git a/src/engine_sink.zig b/src/engine_sink.zig
index e52098f3..a5f5a7e5 100644
--- a/src/engine_sink.zig
+++ b/src/engine_sink.zig
@@ -268,6 +268,7 @@ fn tuiEmit(ctx: *anyopaque, ev: Stamped) void {
.interrupted => {}, // a deliberate Esc needs no notice
.stalled => notice(a, "\n⚠ stream stalled — ending turn\n"),
.dropped => notice(a, "\n⚠ connection dropped — response ended early\n"),
+ .steered => notice(a, "\n↳ follow-up received — restarting the reply\n"),
}
},
.stream_complete => |c| {
@@ -477,7 +478,7 @@ pub fn compactArg(input: std.json.Value) []const u8 {
fn transportEndingNotice(t: engine_events.TransportAbort) ?[]const u8 {
if (!t.turn_ending or t.reason == .interrupted) return null;
return switch (t.reason) {
- .interrupted => null,
+ .interrupted, .steered => null,
.stalled => "\n⚠ stream stalled — ending turn\n",
.dropped => "\n⚠ connection dropped — response ended early\n",
};
diff --git a/src/steer_now.zig b/src/steer_now.zig
new file mode 100644
index 00000000..c226c766
--- /dev/null
+++ b/src/steer_now.zig
@@ -0,0 +1,147 @@
+//! Act on a new message mid-reply. A follow-up the user sends while the model
+//! is still streaming supersedes that reply: the stream is cut, the partial
+//! answer (never committed to history) is dropped, and the request is rebuilt
+//! with the follow-up appended. Tools that are already running finish first,
+//! and the follow-up then lands at the next step boundary as before.
+//!
+//! GPT-6 over the Responses WebSocket keeps its server-side `response.steer`
+//! (agent_ws_steer.zig), so the WebSocket path supersedes only models without
+//! it. Follow-ups reach this queue from the line REPL's stdin scan and from
+//! the TUI (tui_launch's steer hand-off).
+
+const std = @import("std");
+const Agent = @import("agent.zig").Agent;
+const main_mod = @import("main.zig");
+const repl_glue = @import("repl_glue.zig");
+
+/// A soft follow-up is waiting, and this request is the root's own turn
+/// request (not compaction, a title, a judge or a child), so it may be
+/// superseded. A force follow-up interrupts the turn instead.
+pub fn pending(self: *const Agent) bool {
+ if (self.sub or self.call_kind != .root or self.compaction_request) return false;
+ // Early-started tools (ADR 0177) own this stream's results; let it finish.
+ if (@import("agent_async_tools.zig").started(self)) return false;
+ return queued();
+}
+
+/// The head of the follow-up queue is a soft one.
+pub fn queued() bool {
+ repl_glue.steerLock();
+ defer repl_glue.steerUnlock();
+ const q = &main_mod.g_steer_queue;
+ return q.items.len > 0 and !q.items[0].force;
+}
+
+/// The stream was cut for a follow-up: hand it (and anything else waiting)
+/// to the conversation and rebuild the request. Always true: the caller
+/// rebuilds even when delivery found nothing left to add.
+pub fn supersede(self: *Agent) bool {
+ self.partial_text.clearRetainingCapacity(); // the fresh stream restarts the reply, no concat
+ @import("turn_inbox.zig").deliver(self) catch {};
+ self.closeCodexWs(); // a codex WS chain is keyed on the abandoned response
+ if (self.tracer) |t| t.note("steer", "a follow-up superseded the streaming reply; request rebuilt");
+ return true;
+}
+
+/// The TUI hands a mid-turn follow-up to the running turn. Page-allocated,
+/// like the line REPL's entries (turn_inbox frees them the same way).
+pub fn send(text: []const u8) bool {
+ const owned = std.heap.page_allocator.dupe(u8, text) catch return false;
+ repl_glue.steerLock();
+ defer repl_glue.steerUnlock();
+ main_mod.g_steer_queue.append(std.heap.page_allocator, .{ .text = owned, .force = false }) catch {
+ std.heap.page_allocator.free(owned);
+ return false;
+ };
+ return true;
+}
+
+/// Soft follow-ups the finished turn never delivered (they arrived after its
+/// last reply), moved out for the frontend to run as the next turn. Force
+/// entries stay for the interrupt path.
+pub fn reclaim(gpa: std.mem.Allocator, out: *std.array_list.Managed([]const u8)) void {
+ repl_glue.steerLock();
+ defer repl_glue.steerUnlock();
+ const q = &main_mod.g_steer_queue;
+ var i: usize = 0;
+ while (i < q.items.len) {
+ const e = q.items[i];
+ if (e.force) {
+ i += 1;
+ continue;
+ }
+ const copy = gpa.dupe(u8, e.text) catch {
+ i += 1;
+ continue;
+ };
+ out.append(copy) catch {
+ gpa.free(copy);
+ i += 1;
+ continue;
+ };
+ std.heap.page_allocator.free(e.text);
+ _ = q.orderedRemove(i);
+ }
+}
+
+fn clearQueue() void {
+ repl_glue.steerLock();
+ defer repl_glue.steerUnlock();
+ for (main_mod.g_steer_queue.items) |e| std.heap.page_allocator.free(e.text);
+ main_mod.g_steer_queue.clearRetainingCapacity();
+}
+
+test "only a soft follow-up at the head supersedes a root turn request" {
+ clearQueue();
+ defer clearQueue();
+ var root: Agent = undefined;
+ root.sub = false;
+ root.call_kind = .root;
+ root.compaction_request = false;
+ root.async_tools = null;
+ try std.testing.expect(!pending(&root));
+
+ try std.testing.expect(send("also run the tests"));
+ try std.testing.expect(pending(&root));
+ root.compaction_request = true; // the summary call is not the user's reply
+ try std.testing.expect(!pending(&root));
+ root.compaction_request = false;
+ root.call_kind = .title;
+ try std.testing.expect(!pending(&root));
+ root.call_kind = .root;
+ root.sub = true;
+ try std.testing.expect(!pending(&root));
+ root.sub = false;
+
+ clearQueue();
+ const force = try std.heap.page_allocator.dupe(u8, "stop");
+ repl_glue.steerLock();
+ try main_mod.g_steer_queue.append(std.heap.page_allocator, .{ .text = force, .force = true });
+ repl_glue.steerUnlock();
+ try std.testing.expect(!pending(&root)); // force interrupts; it never rebuilds
+}
+
+test "reclaim moves undelivered soft follow-ups out and leaves force behind" {
+ clearQueue();
+ defer clearQueue();
+ try std.testing.expect(send("first"));
+ const force = try std.heap.page_allocator.dupe(u8, "stop");
+ repl_glue.steerLock();
+ try main_mod.g_steer_queue.append(std.heap.page_allocator, .{ .text = force, .force = true });
+ repl_glue.steerUnlock();
+ try std.testing.expect(send("second"));
+
+ var out = std.array_list.Managed([]const u8).init(std.testing.allocator);
+ defer {
+ for (out.items) |t| std.testing.allocator.free(t);
+ out.deinit();
+ }
+ reclaim(std.testing.allocator, &out);
+ try std.testing.expectEqual(@as(usize, 2), out.items.len);
+ try std.testing.expectEqualStrings("first", out.items[0]);
+ try std.testing.expectEqualStrings("second", out.items[1]);
+ repl_glue.steerLock();
+ defer repl_glue.steerUnlock();
+ try std.testing.expectEqual(@as(usize, 1), main_mod.g_steer_queue.items.len);
+ try std.testing.expect(main_mod.g_steer_queue.items[0].force);
+}
diff --git a/src/tui_launch.zig b/src/tui_launch.zig
index 4290fcbe..b6d7c4d7 100644
--- a/src/tui_launch.zig
+++ b/src/tui_launch.zig
@@ -129,6 +129,8 @@ pub fn run(
acp_session.ensure();
tui.setFollowupFn(noteFollowupCb);
defer tui.setFollowupFn(null);
+ tui.setSteerFns(@import("steer_now.zig").send, @import("steer_now.zig").reclaim);
+ defer tui.setSteerFns(null, null);
try tui.run(gpa, io, environ_map, .{
.turn_ctx = &repl_ctx,
.turn_fn = turnCb,
diff --git a/src/tui_sink.zig b/src/tui_sink.zig
index d811c547..22fba1a4 100644
--- a/src/tui_sink.zig
+++ b/src/tui_sink.zig
@@ -194,7 +194,7 @@ fn emit(ctx: *anyopaque, ev: engine_sink.Stamped) void {
// people hit Esc on a turn that was still recovering.
if (!t.turn_ending) return;
switch (t.reason) {
- .interrupted => {},
+ .interrupted, .steered => {},
.stalled => b.queue.push(.{ .notice = "⚠ stream stalled — ending turn" }),
.dropped => b.queue.push(.{ .notice = "⚠ connection dropped — response ended early" }),
}
@@ -205,6 +205,7 @@ fn emit(ctx: *anyopaque, ev: engine_sink.Stamped) void {
.interrupted => {},
.stalled => b.queue.push(.{ .notice = "⚠ stream stalled — ending turn" }),
.dropped => b.queue.push(.{ .notice = "⚠ connection dropped — response ended early" }),
+ .steered => b.queue.push(.{ .notice = "↳ follow-up received — restarting the reply" }),
}
},
// The status bar's model name is a TUI-owned global; a mid-turn
diff --git a/src/turn_inbox.zig b/src/turn_inbox.zig
index bf94c082..94fcd8d8 100644
--- a/src/turn_inbox.zig
+++ b/src/turn_inbox.zig
@@ -78,6 +78,10 @@ test "deliverSteer injects one non-force line and leaves force queued" {
try std.testing.expect(main_mod.g_steer_queue.items[0].force);
}
+test {
+ _ = @import("steer_now.zig");
+}
+
test "deliverSteer is a no-op on subagents" {
var root: Agent = undefined;
root.sub = true;