Skip to content

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

Python

ws steer: follow the whole response.steer protocol

justrachc237ec9d0dba
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 6545a5a7..5bf5be3d 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -229,6 +229,9 @@ jobs:
- 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: TUI GPT-6 follow-ups steer the running reply (ADR 0222)
+ run: python3 scripts/test-tui-steer-gpt6.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/docs/adr/0222-gpt-6-follow-ups-steer-the-running-reply.md b/docs/adr/0222-gpt-6-follow-ups-steer-the-running-reply.md
new file mode 100644
index 00000000..bc30cfe9
--- /dev/null
+++ b/docs/adr/0222-gpt-6-follow-ups-steer-the-running-reply.md
@@ -0,0 +1,60 @@
+# 0222. GPT-6 follow-ups steer the running reply
+
+Status: accepted 2026-09-30
+
+## Context
+
+ADR 0217 left GPT-6 on the Responses WebSocket to act on a follow-up
+server-side, through `response.steer`. graff sent the steer and followed the
+protocol no further:
+
+- `response.steer.failed` was ignored. The follow-up was gone, and the turn
+ waited for a continuation that never came until the stall budget ended it.
+- A response that ends in client tool calls holds an accepted steer until
+ their outputs arrive (`response.steer.pending`). The turn kept reading for
+ a continuation the server only starts after those outputs, and stalled.
+- The steered text never entered history, so a full resend, `/resume` or
+ compaction lost it.
+- Later steers kept targeting the first response, not the continuation.
+- Every request carried the server-compaction directive
+ (`context_management`), and the server refuses to steer a request that
+ carries it (`steering_not_supported`).
+
+## Decision
+
+- A root turn request with a GPT-6 model on Codex or Platform OpenAI steers.
+ Its body leaves the server-compaction directive off until the context meter
+ comes within a quarter of the compaction threshold, where the directive
+ starts to matter. From there compaction wins, and a follow-up supersedes
+ the reply as in ADR 0217. Compaction, titles, judges and children never
+ steer.
+- Queued follow-ups go out as `response.steer` on the live response (the
+ newest `response.created`) while it streams. The terminal frame never
+ carries one; the step boundary delivers it instead.
+- Each steer is tracked until the server answers it:
+ - Accepted: the server ends the response (`incomplete` with reason
+ `steered`, or `completed` when the item in progress was its last) and
+ streams a continuation on the same socket. The read loop follows it, and
+ the continuation's inter-frame budget starts over.
+ - Accepted on a response that ends in client tool calls: the steer waits
+ for their outputs. The read loop stops so the tool loop runs, and the
+ chained output request does not repeat the steer; the server prepends it.
+ - Failed: the text goes back to the head of the follow-up queue for the
+ next step boundary or turn. `steering_not_supported` turns steering off
+ for the session.
+- An applied steer joins history as a user message where the server applied
+ it: ahead of the continuation's items, or after the tool calls it waits on.
+- A steer lives only on its socket. When the stream fails (a drop, a stall,
+ Esc, a failed response), every steer it carried goes back on the queue.
+- The last response's usage drives the context meter. The responses a steer
+ ended are billed without moving it.
+
+## Consequences
+
+- Near the compaction threshold, GPT-6 follow-ups supersede instead of
+ steering.
+- A follow-up typed while the model reasons goes out with the next frame;
+ reasoning summaries keep frames coming.
+- The Codex mock (`scripts/codex_ws_mock.py`) plays the server side of
+ steering, and `scripts/test-tui-steer-gpt6.py` covers the continuation,
+ pending and failure paths end to end.
diff --git a/scripts/codex_ws_mock.py b/scripts/codex_ws_mock.py
index e502461c..9b5ffdfd 100644
--- a/scripts/codex_ws_mock.py
+++ b/scripts/codex_ws_mock.py
@@ -18,6 +18,10 @@ The assistant item is shaped exactly the way stepResponses
array holds an ``output_text`` block. ``ws_turns``/``sse_turns`` count which
transport actually served each turn so tests can prove no silent fallback.
+With ``on_steer`` set, the socket also takes GPT-6 ``response.steer`` frames
+while a reply streams (a reader thread feeds the sender between events), so a
+test can script accepted / pending / failed and the continuation that follows.
+
Importable (``CodexMock().start() -> port`` / ``stop()``) and runnable:
``python3 scripts/codex_ws_mock.py [--port N]`` serves until Ctrl-C, tracing
events to stderr.
@@ -29,6 +33,7 @@ import argparse
import base64
import hashlib
import json
+import queue
import socket
import struct
import sys
@@ -232,6 +237,15 @@ class CodexMock:
delay_for_request: Callable[[RecordedRequest], float] | None = field(
default=None, repr=False
)
+ # Optional GPT-6 mid-turn steering: called for each ``response.steer`` frame
+ # with the request whose reply is streaming (None when idle), the steer
+ # event, and the events not yet sent. Returns (events to send now, the new
+ # remaining events) -- e.g. accepted now, then a cut reply and a
+ # continuation. Steer frames are recorded in ``steers`` either way.
+ on_steer: Callable[
+ [RecordedRequest | None, dict, list[dict]], tuple[list[dict], list[dict]]
+ ] | None = field(default=None, repr=False)
+ steers: list[dict] = field(default_factory=list, 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)
@@ -388,6 +402,9 @@ class CodexMock:
).encode("ascii")
)
self._log(f"ws upgraded (connection {connection_id})")
+ if self.on_steer is not None:
+ self._serve_ws_steering(conn, reader, headers, connection_id)
+ return
while True:
message = _read_message(reader, conn)
if message.opcode == OP_CLOSE:
@@ -438,6 +455,89 @@ class CodexMock:
if any(ev.get("type") == "error" for ev in events):
return
+ def _send_ws(self, conn: socket.socket, ev: dict) -> None:
+ _send_frame(conn, OP_TEXT, json.dumps(ev, separators=(",", ":")).encode("utf-8"))
+ self._log(f"ws -> {ev['type']}")
+
+ def _serve_ws_steering(
+ self,
+ conn: socket.socket,
+ reader: _SockReader,
+ headers: dict[str, str],
+ connection_id: int,
+ ) -> None:
+ """The WebSocket loop with a reader thread, so ``response.steer`` frames
+ land while a reply is still streaming (the plain loop reads only
+ between requests)."""
+ inbox: queue.Queue = queue.Queue()
+
+ def pump() -> None:
+ try:
+ while True:
+ message = _read_message(reader, conn)
+ inbox.put(message)
+ if message.opcode == OP_CLOSE:
+ return
+ except (ConnectionError, OSError):
+ inbox.put(None)
+
+ threading.Thread(target=pump, daemon=True).start()
+ streaming: RecordedRequest | None = None
+ last: RecordedRequest | None = None
+ remaining: list[dict] = []
+ delay = 0.0
+ while True:
+ try:
+ message = inbox.get(timeout=delay if remaining else None)
+ except queue.Empty: # only while a reply streams: nothing arrived in time
+ message = False
+ if message is False: # send the next event
+ self._send_ws(conn, remaining.pop(0))
+ if not remaining:
+ with self._lock:
+ self.ws_turns += 1
+ streaming = None
+ continue
+ if message is None:
+ return
+ if message.opcode == OP_CLOSE:
+ try:
+ _send_frame(conn, OP_CLOSE, b"")
+ except OSError:
+ pass
+ return
+ try:
+ event = json.loads(message.payload.decode("utf-8"))
+ except ValueError:
+ continue
+ etype = event.get("type") if isinstance(event, dict) else None
+ self._log(f"ws <- {etype} ({len(message.payload)}b)")
+ if etype == "response.steer":
+ with self._lock:
+ self.steers.append(event)
+ now, remaining = self.on_steer(streaming or last, event, remaining)
+ for ev in now:
+ self._send_ws(conn, ev)
+ if streaming is None and remaining:
+ streaming = last
+ continue
+ if etype != "response.create":
+ continue
+ if event.get("generate") is False:
+ prewarm_id = f"resp_prewarm_{self.ws_turns + 1}"
+ with self._lock:
+ self.prewarm_ids[connection_id] = prewarm_id
+ self._send_ws(conn, {"type": "response.completed", "response": {"id": prewarm_id, "usage": dict(USAGE)}})
+ continue
+ for ev in remaining: # what the last reply still owed goes out first
+ self._send_ws(conn, ev)
+ request = self._record("ws", connection_id, event, headers)
+ streaming = last = request
+ remaining = list(self._events_for(request))
+ delay = self.delay_for_request(request) if self.delay_for_request else 0.0
+ if delay <= 0:
+ delay = 0.001
+
def _serve_sse(
self, conn: socket.socket, reader: _SockReader, headers: dict[str, str]
) -> None:
diff --git a/scripts/test-tui-steer-gpt6.py b/scripts/test-tui-steer-gpt6.py
new file mode 100644
index 00000000..55f935bb
--- /dev/null
+++ b/scripts/test-tui-steer-gpt6.py
@@ -0,0 +1,353 @@
+#!/usr/bin/env python3
+"""GPT-6 mid-turn steering end to end: the real binary under a pty, a mock
+Codex socket playing the server's side of `response.steer`.
+
+ 1. continuation: a follow-up typed while the reply streams goes out as a
+ steer; the server accepts it, ends the reply `incomplete: steered` and
+ streams a continuation. No rebuilt request, and the next turn's full
+ input carries the steer once, between the cut reply and the
+ continuation (the TUI re-anchors every turn on a fresh socket).
+ 2. pending: a steer that meets a client tool call waits for the tool output.
+ The tool loop runs at once (no wait for a continuation that never
+ comes), and the output request does not repeat the steer.
+ 3. failed: a rejected steer is not lost; it runs as the next message.
+
+Usage: python3 scripts/test-tui-steer-gpt6.py [path/to/graff]
+Exit 0 = pass. Skips (exit 0, notice) with no pty support.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+import time
+
+from codex_ws_mock import USAGE, CodexMock, RecordedRequest
+
+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"STORY_{i:02d} " for i in range(60)]
+FOLLOW_UP = "also mention the tests"
+
+
+def created(rid: str) -> dict:
+ return {"type": "response.created", "response": {"id": rid, "status": "in_progress"}}
+
+
+def delta(text: str) -> dict:
+ return {"type": "response.output_text.delta", "item_id": "msg", "output_index": 0, "content_index": 0, "delta": text}
+
+
+def message(text: str) -> dict:
+ return {"type": "response.output_item.done", "item": {
+ "type": "message", "id": "msg", "status": "completed", "role": "assistant",
+ "content": [{"type": "output_text", "text": text, "annotations": []}]}}
+
+
+def ended(rid: str, reason: str | None = None) -> dict:
+ response = {"id": rid, "status": "incomplete" if reason else "completed", "usage": dict(USAGE)}
+ if reason:
+ response["incomplete_details"] = {"reason": reason}
+ return {"type": "response.incomplete" if reason else "response.completed", "response": response}
+
+
+def reply(rid: str, text: str) -> list[dict]:
+ return [created(rid), delta(text), message(text), ended(rid)]
+
+
+def story(rid: str) -> list[dict]:
+ return [created(rid)] + [delta(w) for w in WORDS] + [message("".join(WORDS)), ended(rid)]
+
+
+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 type_line(fd, text):
+ # Keep reading while typing: a TUI whose pty output nobody drains blocks
+ # on its next write and never sees the keys.
+ for ch in text:
+ os.write(fd, ch.encode())
+ drain(fd, 0.01)
+ drain(fd, 0.4) # past the composer's paste-burst window, so Enter sends
+ os.write(fd, b"\r")
+
+
+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/gpt-6-sol", "--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 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_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 session(mock: CodexMock, flow) -> str | None:
+ port = mock.start()
+ try:
+ with tempfile.TemporaryDirectory(prefix="graff-tui-steer6-") as tmp:
+ env, unset = workspace(tmp, port)
+ pid, fd = spawn(tmp, env, unset)
+ try:
+ boot(fd)
+ return flow(fd)
+ finally:
+ reap(pid, fd)
+ finally:
+ mock.stop()
+
+
+def user_texts(body: dict) -> list[str]:
+ """Every user message in a request's input (either content shape)."""
+ out = []
+ for item in body.get("input") or []:
+ if not isinstance(item, dict) or item.get("role") != "user":
+ continue
+ content = item.get("content")
+ if isinstance(content, str):
+ out.append(content)
+ elif isinstance(content, list):
+ out.extend(part.get("text", "") for part in content if isinstance(part, dict))
+ return out
+
+
+def continuation() -> str | None:
+ def events(r: RecordedRequest) -> list[dict]:
+ return story("resp_story") if r.ordinal == 1 else reply(f"resp_after_{r.ordinal}", "SECOND_REPLY_OK")
+
+ def on_steer(_r, steer, remaining):
+ cut = [e for e in remaining if e["type"] != "response.output_text.delta"][:1] # the reply's item, finished
+ return [{"type": "response.steer.accepted", "steer": {"id": "steer_1", "previous_response_id": steer["previous_response_id"]}}], (
+ cut + [ended("resp_story", "steered")] + reply("resp_cont", "CONTINUATION_OK"))
+
+ mock = CodexMock(events_for_request=events, on_steer=on_steer, delay_for_request=lambda r: 0.12 if r.ordinal == 1 else 0.0)
+
+ def flow(fd):
+ type_line(fd, "tell me a story")
+ if wait_for(fd, "STORY_03", 20.0) is None:
+ return "the first reply never started streaming"
+ type_line(fd, FOLLOW_UP)
+ if wait_for(fd, "CONTINUATION_OK", 30.0) is None:
+ return "the continuation never reached the screen"
+ type_line(fd, "what next")
+ if wait_for(fd, "SECOND_REPLY_OK", 20.0) is None:
+ return "the next turn never finished"
+ return None
+
+ err = session(mock, flow)
+ if err:
+ return err
+ if len(mock.steers) != 1 or mock.steers[0].get("previous_response_id") != "resp_story" or mock.steers[0].get("input") != FOLLOW_UP:
+ return f"expected one steer on resp_story carrying the follow-up, got {mock.steers}"
+ requests = mock.recorded_requests()
+ if len(requests) != 2:
+ return f"expected the story and the next turn (no rebuilt reply), got {len(requests)} requests"
+ full = requests[1].body
+ texts = user_texts(full)
+ if texts.count(FOLLOW_UP) != 1:
+ return f"the next turn's input carried the steer {texts.count(FOLLOW_UP)} times: {texts}"
+ items = json.dumps(full.get("input"))
+ at_story, at_steer, at_cont = items.find("STORY_00"), items.find(FOLLOW_UP), items.find("CONTINUATION_OK")
+ if not (0 <= at_story < at_steer < at_cont):
+ return "history does not hold the steer between the cut reply and the continuation"
+ return None
+
+
+def pending() -> str | None:
+ steer_text = "keep it to one line"
+ thinking = [{"type": "response.reasoning_summary_text.delta", "item_id": "rs", "output_index": 0, "summary_index": 0, "delta": "thinking "}] * 25
+ call = {"type": "response.output_item.done", "item": {
+ "type": "function_call", "id": "fc_1", "call_id": "call_todo", "name": "todo_read", "arguments": "{}", "status": "completed"}}
+
+ def events(r: RecordedRequest) -> list[dict]:
+ if r.ordinal == 1:
+ return [created("resp_tool")] + thinking + [call, ended("resp_tool")]
+ return reply(f"resp_after_{r.ordinal}", "PENDING_APPLIED_OK")
+
+ def on_steer(_r, steer, remaining):
+ held = {"type": "response.steer.pending", "steer": {"id": "steer_1", "previous_response_id": steer["previous_response_id"]},
+ "reason": "waiting_for_required_input",
+ "required_input": [{"type": "function_call_output", "call_id": "call_todo", "name": "todo_read"}]}
+ return [{"type": "response.steer.accepted", "steer": {"id": "steer_1", "previous_response_id": steer["previous_response_id"]}}], remaining + [held]
+
+ mock = CodexMock(events_for_request=events, on_steer=on_steer, delay_for_request=lambda r: 0.15 if r.ordinal == 1 else 0.0)
+ timing = {}
+
+ def flow(fd):
+ type_line(fd, "draft a short plan")
+ drain(fd, 1.2) # the reply is thinking
+ type_line(fd, steer_text)
+ timing["steered"] = time.time()
+ if wait_for(fd, "PENDING_APPLIED_OK", 40.0) is None:
+ return "the tool output request never finished"
+ timing["done"] = time.time()
+ return None
+
+ err = session(mock, flow)
+ if err:
+ return err
+ if len(mock.steers) != 1:
+ return f"expected one steer, got {len(mock.steers)}"
+ requests = mock.recorded_requests()
+ if len(requests) != 2:
+ return f"expected the tool call and its output request, got {len(requests)} requests"
+ out = requests[1].body
+ if out.get("previous_response_id") != "resp_tool":
+ return f"the tool output chained on {out.get('previous_response_id')!r}, not the steered response"
+ if "call_todo" not in json.dumps(out.get("input")):
+ return "the output request did not carry the tool output"
+ if steer_text in json.dumps(out.get("input")):
+ return "the output request repeated a steer the server prepends itself"
+ if timing["done"] - timing["steered"] > 20:
+ return f"the tool loop waited {timing['done'] - timing['steered']:.0f}s for a continuation that never comes"
+ return None
+
+
+def failed() -> str | None:
+ def events(r: RecordedRequest) -> list[dict]:
+ return story("resp_story") if r.ordinal == 1 else reply(f"resp_next_{r.ordinal}", "REQUEUED_OK")
+
+ def on_steer(_r, steer, remaining):
+ return [{"type": "response.steer.failed", "steer": {"previous_response_id": steer["previous_response_id"]},
+ "error": {"code": "invalid_input", "type": "invalid_request_error", "message": "mock rejection"}}], remaining
+
+ mock = CodexMock(events_for_request=events, on_steer=on_steer, delay_for_request=lambda r: 0.12 if r.ordinal == 1 else 0.0)
+
+ def flow(fd):
+ type_line(fd, "tell me a story")
+ if wait_for(fd, "STORY_03", 20.0) is None:
+ return "the first reply never started streaming"
+ type_line(fd, FOLLOW_UP)
+ if wait_for(fd, "REQUEUED_OK", 40.0) is None:
+ return "the rejected follow-up never ran"
+ return None
+
+ err = session(mock, flow)
+ if err:
+ return err
+ requests = mock.recorded_requests()
+ if len(requests) != 2:
+ return f"expected the story and the follow-up's own request, got {len(requests)}"
+ if user_texts(requests[1].body).count(FOLLOW_UP) != 1:
+ return "the follow-up request did not carry the rejected steer exactly once"
+ return None
+
+
+def main():
+ if not os.path.exists(BIN):
+ print(f"tui-steer-gpt6: {BIN} not built — skipping")
+ return 0
+ try:
+ import pty # noqa: F401
+ except ImportError:
+ print("tui-steer-gpt6: no pty support here — skipping")
+ return 0
+ failures = 0
+ for name, case in (("continuation", continuation), ("pending", pending), ("failed", failed)):
+ err = case()
+ if err:
+ failures += 1
+ print(f" ✗ gpt-6 steer {name}: {err}")
+ else:
+ print(f" ✓ gpt-6 steer {name}")
+ return 1 if failures else 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/src/agent_request.zig b/src/agent_request.zig
index f51af1e0..ac432111 100644
--- a/src/agent_request.zig
+++ b/src/agent_request.zig
@@ -403,6 +403,7 @@ pub fn request(self: *Agent, tools_in: ?[]const u8) !std.json.ObjectMap {
.ok => |obj| {
if (!self.compaction_request) self.compact_transport_failures = 0;
usage_attempts.completed();
+ @import("agent_ws_steer.zig").billEnded(self, obj); // the responses a steer ended, before the last
self.recordUsageResponses(obj, body.len);
try @import("agent_async_tools.zig").join(self);
// #414: an empty output whose usage already fills the window
diff --git a/src/agent_responses.zig b/src/agent_responses.zig
index 26d6b5f9..385c73b7 100644
--- a/src/agent_responses.zig
+++ b/src/agent_responses.zig
@@ -31,6 +31,9 @@ pub fn parseResponses(self: *Agent, body: []const u8) !ResponsesResult {
const result_arena = self.messageMutationAlloc();
var items = std.json.Array.init(result_arena);
var usage: ?Value = null;
+ // A steered WS stream (agent_ws_steer) ends a response per steer before the
+ // last; their usage is billed there, while the meter keeps the last one.
+ var steered_usage = std.json.Array.init(result_arena);
var resp_id: ?[]const u8 = null; // response.id, for previous_response_id delta continuation (#codex-ws)
var saw_completed = false;
var saw_incomplete = false;
@@ -53,11 +56,18 @@ pub fn parseResponses(self: *Agent, body: []const u8) !ResponsesResult {
saw_completed = std.mem.eql(u8, t.string, "response.completed");
saw_incomplete = std.mem.eql(u8, t.string, "response.incomplete");
if (v.object.get("response")) |r| if (r == .object) {
- if (r.object.get("usage")) |u| usage = try util.dupeJsonValue(result_arena, u);
+ if (r.object.get("usage")) |u| {
+ if (usage) |earlier| try steered_usage.append(earlier);
+ usage = try util.dupeJsonValue(result_arena, u);
+ }
if (r.object.get("id")) |idv| if (idv == .string) {
resp_id = try result_arena.dupe(u8, idv.string);
};
};
+ } else if (std.mem.eql(u8, t.string, @import("agent_ws_steer.zig").applied_type)) {
+ // A steer the server applied here: the user's words where the model read them.
+ if (v.object.get("text")) |txt| if (txt == .string)
+ try items.append(try @import("session_wake.zig").message(result_arena, txt.string));
} else if (std.mem.eql(u8, t.string, "response.failed") or std.mem.eql(u8, t.string, "error")) {
err_msg = if (errorMessage(v.object)) |m|
result_arena.dupe(u8, m) catch "codex stream reported a failure"
@@ -76,6 +86,7 @@ pub fn parseResponses(self: *Agent, body: []const u8) !ResponsesResult {
var resp: std.json.ObjectMap = .empty;
try resp.put(result_arena, "output", .{ .array = items });
if (usage) |u| try resp.put(result_arena, "usage", u);
+ if (steered_usage.items.len > 0) try resp.put(result_arena, "steered_usage", .{ .array = steered_usage });
if (resp_id) |rid| try resp.put(result_arena, "id", .{ .string = rid });
// Item-only streams are tolerated for ordinary turns, but are not a
// safe sole source for a compaction handoff: no terminal completed event
diff --git a/src/agent_server_compact.zig b/src/agent_server_compact.zig
index febd7f89..57caf6aa 100644
--- a/src/agent_server_compact.zig
+++ b/src/agent_server_compact.zig
@@ -95,16 +95,24 @@ pub fn noteClientSummary(chars: usize) void {
/// of 1,000 guarantees every real graff context crosses it; the flag is route-
/// gated so a non-OpenAI Responses provider can never enter this path.
pub fn writeContextManagement(self: *const Agent, s: anytype) !void {
+ try writeContextManagementBody(s, directive(self) orelse return);
+}
+
+/// The compaction threshold this request's body carries, or null for none.
+pub fn directive(self: anytype) ?u64 {
// #502: an explicit-compact provider (xAI) ignores the in-stream directive
// — probed live; compaction goes through explicitCompact instead.
- if (self.provider.serverCompactUrl() != null) return;
- const threshold = if (self.server_compaction_request and manualRoute(self.provider) == .in_stream)
- @as(u64, 1_000)
- else if (enabled(self.provider))
- self.provider.compactAt()
- else
- return;
- try writeContextManagementBody(s, threshold);
+ if (self.provider.serverCompactUrl() != null) return null;
+ if (self.server_compaction_request and manualRoute(self.provider) == .in_stream) return 1_000;
+ if (!enabled(self.provider)) return null;
+ const threshold = self.provider.compactAt();
+ // A request carrying the directive answers every GPT-6 `response.steer`
+ // with steering_not_supported (probed on Codex). It is inert below its
+ // threshold, so a root turn that can steer leaves it off until the
+ // context comes within a quarter of the threshold; from there compaction
+ // wins and a follow-up supersedes the reply instead (agent_ws_steer).
+ if (@import("agent_ws_steer.zig").rootTurnOnSteeringRoute(self) and self.last_context_tokens +| threshold / 4 < threshold) return null;
+ return threshold;
}
pub fn writeContextManagementBody(s: anytype, threshold: u64) !void {
diff --git a/src/agent_ws.zig b/src/agent_ws.zig
index b5228886..84e8074d 100644
--- a/src/agent_ws.zig
+++ b/src/agent_ws.zig
@@ -475,6 +475,7 @@ pub fn postResponsesWs(self: *Agent, body: []const u8) ![]u8 {
var sig: TokenSignal = .{};
var text_seen = false;
var steer_st: @import("agent_ws_steer.zig").Session = .{};
+ defer steer_st.settle(gpa); // a steer the returned body does not carry goes back on the queue
stream: while (true) {
// Race the frame read against a stall watchdog so a dead ws can't hang
@@ -578,13 +579,13 @@ pub fn postResponsesWs(self: *Agent, body: []const u8) ![]u8 {
if (self.tracer) |tr| tr.note("ws", "terminal API error frame");
break :stream;
}
- if (try @import("agent_ws_steer.zig").tick(self, client, fbuf.items, orig_tio != null, &steer_st)) {
+ if (try @import("agent_ws_steer.zig").tick(self, client, fbuf.items, &steer_st, &full.writer, &text_seen)) {
if (self.tracer) |tr| tr.note("ws", "completed");
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)) {
+ // GPT-6 on Codex/OpenAI steers server-side (tick above); anything else supersedes the reply.
+ if (!@import("agent_ws_steer.zig").steers(self) and @import("steer_now.zig").pending(self)) {
engine_sink.forAgent(self).emit(self.io, .{ .stream_aborted = .steered });
return error.Steered;
}
diff --git a/src/agent_ws_steer.zig b/src/agent_ws_steer.zig
index 98abce0f..54eb3a21 100644
--- a/src/agent_ws_steer.zig
+++ b/src/agent_ws_steer.zig
@@ -1,25 +1,73 @@
-//! GPT-6 Astra mid-turn steering over Responses WebSocket (`response.steer`).
+//! GPT-6 mid-turn steering over the Responses WebSocket (`response.steer`).
//!
-//! GPT-5.6 and earlier do not support this. After `response.created`, a follow-up
-//! typed while the turn is live is sent as `{type:response.steer, previous_response_id, input}`
-//! instead of waiting for the turn to finish. The original response may end
-//! `incomplete` with `reason: steered`; keep reading for the successor.
-//! Queued steer exists only on this socket — a disconnect drops it.
+//! A follow-up typed while a GPT-6 turn streams goes out on the same socket as
+//! `{type: response.steer, previous_response_id, input}` instead of waiting
+//! for the turn to end. What the server does with it (OpenAI's steering guide;
+//! the Codex route behaves the same):
+//!
+//! * `response.steer.accepted` queues it. The server finishes the output item
+//! in progress, ends the response (`incomplete` with reason `steered`, or
+//! `completed` when that item was its last) and starts a continuation, a
+//! new response on this socket that carries the update. Keep reading and
+//! never send another response.create for it; later steers target the
+//! continuation.
+//! * A response that ends with client tool calls keeps an accepted steer
+//! waiting (`response.steer.pending`): the server prepends it to the next
+//! response.create chained on that response, the one with the tool
+//! outputs. Stop reading so the tool loop runs, and never resend it.
+//! * `response.steer.failed` means it was not applied and never will be. The
+//! text goes back on the follow-up queue for the next step boundary;
+//! `steering_not_supported` turns steering off for the session.
+//!
+//! An applied steer joins history as a user message where the server applied
+//! it (ahead of the continuation's items, or after the calls whose outputs it
+//! precedes), so a full resend, /resume and compaction keep it. A steer lives
+//! only on this socket: one the returned body does not carry (a failed
+//! response, a stall, a drop, Esc) goes back on the queue.
const std = @import("std");
const Io = std.Io;
const Allocator = std.mem.Allocator;
const Value = std.json.Value;
-const ws = @import("ws.zig");
-const main_mod = @import("main.zig");
-const repl_glue = @import("repl_glue.zig");
+const steer_now = @import("steer_now.zig");
+const Agent = @import("agent.zig").Agent;
const isStreamEnd = @import("agent_stream.zig").isStreamEnd;
+/// A steer the server applied, as a line of the reassembled body:
+/// parseResponses turns it into a user message at that point of the output.
+/// graff's own event; it never goes on the wire.
+pub const applied_type = "graff.steer";
+
pub fn modelSupports(model: []const u8) bool {
return std.mem.startsWith(u8, model, "gpt-6");
}
+/// Set by a `steering_not_supported` failure: the rest of the session
+/// supersedes the reply instead (steer_now), as for models without steering.
+pub var g_unsupported = false;
+
+/// GPT-6 on the routes that implement steering (Platform OpenAI and Codex).
+/// Other sockets serving GPT-6 names supersede the reply instead.
+pub fn active(provider_id: []const u8, model: []const u8) bool {
+ if (g_unsupported or !modelSupports(model)) return false;
+ return std.mem.eql(u8, provider_id, "codex") or std.mem.eql(u8, provider_id, "openai");
+}
+
+/// The root's own turn request on a steering route: the requests a typed
+/// follow-up can steer (not a compaction, title or child call).
+pub fn rootTurnOnSteeringRoute(self: anytype) bool {
+ if (self.sub or self.call_kind != .root or self.compaction_request or self.server_compaction_request) return false;
+ return active(self.provider.id, self.provider.model);
+}
+
+/// This request steers: a root turn on a steering route whose body carries no
+/// server-compaction directive (the two exclude each other; see
+/// agent_server_compact.directive). Any other request supersedes the reply.
+pub fn steers(self: anytype) bool {
+ return rootTurnOnSteeringRoute(self) and @import("agent_server_compact.zig").directive(self) == null;
+}
+
/// Who actually serves a Responses WebSocket. Platform OpenAI only for GPT-6
/// (mid-turn `response.steer`); GPT-5.6 stays HTTP SSE. Codex/xAI/gateway
/// keep their existing sockets. 426 still latches SSE.
@@ -28,75 +76,252 @@ pub fn providerHasWs(id: []const u8, model: []const u8) bool {
return std.mem.eql(u8, id, "openai") and modelSupports(model);
}
+const State = enum { sent, accepted, placed, failed };
+
+const Steer = struct {
+ /// Page-allocated, as queued (steer_input, steer_now.send).
+ text: []const u8,
+ /// The server's steer.id once accepted (gpa); a later failure names it.
+ id: []const u8 = "",
+ state: State = .sent,
+};
+
+/// One request's steering, from its first frame to settle().
pub const Session = struct {
+ /// Where the next steer goes: the newest `response.created` id (gpa).
live_id: []const u8 = "",
- successor_id: []const u8 = "",
- awaiting_successor: bool = false,
+ /// live_id before its `response.created`, streaming, or past its end.
+ phase: enum { waiting, running, ended } = .waiting,
+ /// live_id ended `incomplete` with reason `steered`: a continuation follows.
+ steered: bool = false,
+ /// Client tool calls in live_id's output. An accepted steer then waits for
+ /// their outputs instead of opening a continuation.
+ calls: u32 = 0,
+ /// A failed steer pauses steering until the next response starts.
+ paused: bool = false,
+ /// The stream ended cleanly, so the placed steers ride the returned body.
+ committed: bool = false,
+ steers: std.ArrayList(Steer) = .empty,
+
+ fn count(st: *const Session, state: State) usize {
+ var n: usize = 0;
+ for (st.steers.items) |s| n += @intFromBool(s.state == state);
+ return n;
+ }
+
+ fn oldest(st: *Session, state: State) ?*Steer {
+ for (st.steers.items) |*s| if (s.state == state) return s;
+ return null;
+ }
+
+ fn named(st: *Session, id: []const u8) ?*Steer {
+ if (id.len == 0) return null;
+ for (st.steers.items) |*s| {
+ if ((s.state == .sent or s.state == .accepted) and std.mem.eql(u8, s.id, id)) return s;
+ }
+ return null;
+ }
+
+ /// Hand back every steer the returned body does not carry (all of them
+ /// when the stream failed, since the body is dropped and the request
+ /// retries or the turn ends; else any the server never applied), then
+ /// free the rest.
+ pub fn settle(st: *Session, gpa: Allocator) void {
+ var back: std.ArrayList([]const u8) = .empty;
+ defer back.deinit(gpa);
+ for (st.steers.items) |s| {
+ gpa.free(s.id);
+ if (s.state == .failed) continue; // the queue took it back when it failed
+ if (s.state == .placed and st.committed) {
+ std.heap.page_allocator.free(s.text);
+ continue;
+ }
+ back.append(gpa, s.text) catch std.heap.page_allocator.free(s.text);
+ }
+ steer_now.requeue(back.items);
+ st.steers.deinit(gpa);
+ gpa.free(st.live_id);
+ st.* = .{};
+ }
+};
+
+const Kind = enum { other, created, call, accepted, pending, failed, ended, broke };
+
+const Event = struct {
+ kind: Kind = .other,
+ /// response.id (created) or steer.id (accepted, failed).
+ id: []const u8 = "",
+ /// The failure's error code.
+ code: []const u8 = "",
+ /// An `incomplete` end whose reason is `steered`.
+ steered: bool = false,
};
-fn responseId(arena: Allocator, frame: []const u8) []const u8 {
- const v = std.json.parseFromSliceLeaky(Value, arena, frame, .{ .allocate = .alloc_always }) catch return "";
- if (v != .object) return "";
- const resp = v.object.get("response") orelse return "";
- if (resp != .object) return "";
- const id = resp.object.get("id") orelse return "";
- return if (id == .string) id.string else "";
-}
-
-fn incompleteSteered(arena: Allocator, frame: []const u8) bool {
- const v = std.json.parseFromSliceLeaky(Value, arena, frame, .{ .allocate = .alloc_always }) catch return false;
- if (v != .object) return false;
- const t = v.object.get("type") orelse return false;
- if (t != .string or !std.mem.eql(u8, t.string, "response.incomplete")) return false;
- const resp = v.object.get("response") orelse return false;
- if (resp != .object) return false;
- const details = resp.object.get("incomplete_details") orelse return false;
- if (details != .object) return false;
- const reason = details.object.get("reason") orelse return false;
- return reason == .string and std.mem.eql(u8, reason.string, "steered");
-}
-
-pub fn noteFrame(arena: Allocator, st: *Session, frame: []const u8) void {
- const ty = blk: {
- const v = std.json.parseFromSliceLeaky(Value, arena, frame, .{ .allocate = .alloc_always }) catch return;
- if (v != .object) return;
- const t = v.object.get("type") orelse return;
- break :blk if (t == .string) t.string else "";
+fn get(v: ?Value, name: []const u8) ?Value {
+ const o = v orelse return null;
+ return if (o == .object) o.object.get(name) else null;
+}
+
+fn str(v: ?Value) []const u8 {
+ const s = v orelse return "";
+ return if (s == .string) s.string else "";
+}
+
+fn classify(scratch: Allocator, frame: []const u8) Event {
+ const eql = std.mem.eql;
+ const v = std.json.parseFromSliceLeaky(Value, scratch, frame, .{ .allocate = .alloc_always }) catch return .{};
+ const ty = str(get(v, "type"));
+ if (eql(u8, ty, "response.created")) return .{ .kind = .created, .id = str(get(get(v, "response"), "id")) };
+ if (eql(u8, ty, "response.output_item.done")) {
+ const item = str(get(get(v, "item"), "type"));
+ const call = eql(u8, item, "function_call") or eql(u8, item, "custom_tool_call");
+ return .{ .kind = if (call) .call else .other };
+ }
+ if (eql(u8, ty, "response.steer.accepted")) return .{ .kind = .accepted, .id = str(get(get(v, "steer"), "id")) };
+ if (eql(u8, ty, "response.steer.pending")) return .{ .kind = .pending };
+ if (eql(u8, ty, "response.steer.failed")) return .{
+ .kind = .failed,
+ .id = str(get(get(v, "steer"), "id")),
+ .code = str(get(get(v, "error"), "code")),
};
- if (std.mem.eql(u8, ty, "response.created")) {
- const id = responseId(arena, frame);
- if (id.len == 0) return;
- if (st.live_id.len == 0) {
- st.live_id = id;
- } else if (!std.mem.eql(u8, id, st.live_id)) {
- st.successor_id = id;
- }
- return;
+ if (eql(u8, ty, "response.completed") or eql(u8, ty, "response.incomplete")) {
+ const reason = str(get(get(get(v, "response"), "incomplete_details"), "reason"));
+ return .{ .kind = .ended, .steered = eql(u8, reason, "steered") };
}
- if (std.mem.eql(u8, ty, "response.steer.accepted") or std.mem.eql(u8, ty, "response.steer.pending")) {
- st.awaiting_successor = true;
- return;
+ if (eql(u8, ty, "response.failed") or eql(u8, ty, "error")) return .{ .kind = .broke };
+ return .{};
+}
+
+/// Drive one inbound WS frame; true when this request's stream is done.
+/// Applied steers are written into `body`, the reassembled stream the caller
+/// returns. `text_seen` is the caller's inter-frame budget signal: a
+/// continuation thinks afresh, so it starts over.
+pub fn tick(self: anytype, client: anytype, frame: []const u8, st: *Session, body: *Io.Writer, text_seen: *bool) !bool {
+ const scratch = self.scratchAlloc();
+ if (!steers(self))
+ return isStreamEnd(scratch, self.provider.kind, try std.mem.concat(scratch, u8, &.{ "data: ", frame }));
+ const ev = classify(scratch, frame);
+ switch (ev.kind) {
+ .created => {
+ if (st.phase != .waiting) text_seen.* = false;
+ try place(self, st, body); // accepted steers open the continuation
+ self.gpa.free(st.live_id);
+ st.live_id = "";
+ st.live_id = try self.gpa.dupe(u8, ev.id);
+ st.phase = .running;
+ st.steered = false;
+ st.calls = 0;
+ st.paused = false;
+ },
+ .call => st.calls += 1,
+ .accepted => if (st.oldest(.sent)) |s| {
+ s.state = .accepted;
+ s.id = self.gpa.dupe(u8, ev.id) catch "";
+ note(self, "response.steer accepted");
+ },
+ .pending => try place(self, st, body),
+ .failed => fail(self, st, ev),
+ .ended => {
+ st.phase = .ended;
+ st.steered = ev.steered;
+ },
+ .broke => return true, // not committed: settle hands every steer back
+ .other => {},
}
- if (incompleteSteered(arena, frame)) {
- st.awaiting_successor = true;
+ if (st.phase == .running and !st.paused and st.live_id.len > 0) flush(self, client, st);
+ return finished(self, st, body);
+}
+
+/// Once the live response has ended: is this request's stream done?
+fn finished(self: anytype, st: *Session, body: *Io.Writer) !bool {
+ if (st.phase != .ended) return false;
+ if (st.count(.sent) > 0) return false; // the server still owes each an accepted or a failed
+ if (st.calls > 0) {
+ try place(self, st, body); // they wait for the tool outputs; the server prepends them
+ } else if (st.steered or st.count(.accepted) > 0) return false; // a continuation carries them
+ st.committed = true;
+ return true;
+}
+
+/// Send each queued soft follow-up as a steer on the live response. A force
+/// entry stays queued for the interrupt path, as in turn_inbox.
+fn flush(self: anytype, client: anytype, st: *Session) void {
+ while (@import("turn_inbox.zig").popSteerSoft()) |entry| {
+ if (entry.text.len == 0) {
+ std.heap.page_allocator.free(entry.text);
+ continue;
+ }
+ const frame = buildSteerFrame(self.gpa, st.live_id, entry.text) catch return steer_now.requeue(&.{entry.text});
+ defer self.gpa.free(frame);
+ st.steers.append(self.gpa, .{ .text = entry.text }) catch return steer_now.requeue(&.{entry.text});
+ client.sendText(frame) catch {
+ _ = st.steers.pop(); // a dead socket: the read loop fails next
+ return steer_now.requeue(&.{entry.text});
+ };
+ note(self, "a follow-up went out as response.steer");
}
}
-pub fn shouldStop(arena: Allocator, st: *const Session, kind: anytype, sse_line: []const u8, frame: []const u8) bool {
- if (incompleteSteered(arena, frame)) return false;
- if (!isStreamEnd(arena, kind, sse_line)) return false;
- if (!st.awaiting_successor) return true;
- const id = responseId(arena, frame);
- if (st.successor_id.len > 0 and std.mem.eql(u8, id, st.successor_id)) return true;
- const ty = blk: {
- const v = std.json.parseFromSliceLeaky(Value, arena, frame, .{ .allocate = .alloc_always }) catch break :blk "";
- if (v != .object) break :blk "";
- const t = v.object.get("type") orelse break :blk "";
- break :blk if (t == .string) t.string else "";
- };
- if (std.mem.eql(u8, ty, "response.failed")) return true;
- // Original completed/failed while a successor is still due — keep reading.
- return std.mem.eql(u8, ty, "response.failed");
+/// Write each accepted steer into the body where the server applied it, and
+/// show it there: the reply it interrupted closes, then the steer's own line.
+fn place(self: anytype, st: *Session, body: *Io.Writer) !void {
+ var closed = false;
+ for (st.steers.items) |*s| {
+ if (s.state != .accepted) continue;
+ var w: std.json.Stringify = .{ .writer = body };
+ try body.writeAll("data: ");
+ try w.beginObject();
+ try w.objectField("type");
+ try w.write(applied_type);
+ try w.objectField("text");
+ try w.write(s.text);
+ try w.endObject();
+ try body.writeByte('\n');
+ s.state = .placed;
+ note(self, if (st.phase == .ended and st.calls > 0) "a steer joined history after the tool calls it waits on" else "a steer joined history ahead of the continuation");
+ if (@TypeOf(self) != *Agent) continue;
+ const sink = @import("engine_sink.zig").forAgent(self);
+ if (!closed) sink.emit(self.io, .{ .stream_complete = .{ .streamed_text = self.streamed_text } });
+ closed = true;
+ sink.emit(self.io, .{ .session_notice = .{ .text = s.text, .tone = .dim } });
+ }
+}
+
+fn fail(self: anytype, st: *Session, ev: Event) void {
+ // Nothing in flight under that id: an earlier request's steer, not ours to hand back.
+ const s = st.named(ev.id) orelse st.oldest(.sent) orelse return;
+ s.state = .failed;
+ steer_now.requeue(&.{s.text}); // the next step boundary or turn delivers it
+ st.paused = true;
+ if (std.mem.eql(u8, ev.code, "steering_not_supported")) g_unsupported = true;
+ var buf: [128]u8 = undefined;
+ note(self, std.fmt.bufPrint(&buf, "response.steer failed ({s}); the follow-up waits for the next step", .{ev.code}) catch "response.steer failed");
+}
+
+fn note(self: anytype, msg: []const u8) void {
+ if (@TypeOf(self) != *Agent) return;
+ if (self.tracer) |tr| tr.note("steer", msg);
+}
+
+/// The responses a steer ended before the body's last one used tokens too:
+/// parseResponses keeps their usage aside so the context meter stays on the
+/// last response (which read everything they did). Bill them first, so the
+/// cache readout ends on the last one.
+pub fn billEnded(self: *Agent, response: std.json.ObjectMap) void {
+ const ended = response.get("steered_usage") orelse return;
+ if (ended != .array) return;
+ const usageInt = @import("agent_context.zig").usageInt;
+ for (ended.array.items) |u| {
+ if (u != .object) continue;
+ const in = usageInt(u.object, "input_tokens");
+ var cached: i64 = 0;
+ var written: i64 = 0;
+ if (u.object.get("input_tokens_details")) |d| if (d == .object) {
+ cached = usageInt(d.object, "cached_tokens");
+ written = usageInt(d.object, "cache_write_tokens");
+ };
+ self.recordCost(@max(in - cached - written, 0), cached, written, usageInt(u.object, "output_tokens"));
+ }
}
pub fn buildSteerFrame(gpa: Allocator, response_id: []const u8, input: []const u8) ![]u8 {
@@ -114,34 +339,6 @@ pub fn buildSteerFrame(gpa: Allocator, response_id: []const u8, input: []const u
return aw.toOwnedSlice();
}
-/// Queued steer text is page-allocated (steer_input, steer_now.send) and every
-/// consumer frees it there; freeing it with gpa aborted release builds on each
-/// queued prompt ("pointer being freed was not allocated"). A force entry
-/// stays queued for the interrupt path, as in turn_inbox.
-fn flushOne(self: anytype, client: anytype, st: *Session, poll_stdin: bool) !void {
- _ = poll_stdin;
- if (st.live_id.len == 0) return;
- const entry = @import("turn_inbox.zig").popSteerSoft() orelse return;
- defer std.heap.page_allocator.free(entry.text);
- if (entry.text.len == 0) return;
- const frame = buildSteerFrame(self.gpa, st.live_id, entry.text) catch return;
- defer self.gpa.free(frame);
- client.sendText(frame) catch return;
- st.awaiting_successor = true;
-}
-
-/// Drive one inbound WS frame. Returns true when this turn's stream is done.
-pub fn tick(self: anytype, client: *ws.WsClient, frame: []const u8, poll_stdin: bool, st: *Session) !bool {
- const arena = self.arena;
- const sse = try std.fmt.allocPrint(arena, "data: {s}", .{frame});
- if (!modelSupports(self.provider.model)) {
- return isStreamEnd(arena, self.provider.kind, sse);
- }
- noteFrame(arena, st, frame);
- try flushOne(self, client, st, poll_stdin);
- return shouldStop(arena, st, self.provider.kind, sse, frame);
-}
-
test "modelSupports is gpt-6 only" {
try std.testing.expect(modelSupports("gpt-6-astra"));
try std.testing.expect(modelSupports("gpt-6"));
@@ -159,45 +356,6 @@ test "providerHasWs: Platform OpenAI GPT-6 only; Codex always" {
try std.testing.expect(providerHasWs("codegraff", "gpt-6-astra"));
}
-test "a queued steer goes out and is freed where it was allocated; a force entry stays queued" {
- const Socket = struct {
- sent: std.ArrayList(u8) = .empty,
- pub fn sendText(sock: *@This(), frame: []const u8) !void {
- try sock.sent.appendSlice(std.testing.allocator, frame);
- }
- };
- var sock: Socket = .{};
- defer sock.sent.deinit(std.testing.allocator);
- // gpa is the leak-checked test allocator: a page-allocated entry freed through it panics.
- const agent = .{ .gpa = std.testing.allocator };
- const page = std.heap.page_allocator;
- repl_glue.steerLock();
- for (main_mod.g_steer_queue.items) |e| page.free(e.text);
- main_mod.g_steer_queue.clearRetainingCapacity();
- try main_mod.g_steer_queue.append(page, .{ .text = try page.dupe(u8, "also mention the tests"), .force = false });
- repl_glue.steerUnlock();
- defer {
- repl_glue.steerLock();
- for (main_mod.g_steer_queue.items) |e| page.free(e.text);
- main_mod.g_steer_queue.clearRetainingCapacity();
- repl_glue.steerUnlock();
- }
-
- var st: Session = .{ .live_id = "resp_1" };
- try flushOne(agent, &sock, &st, false);
- try std.testing.expect(std.mem.indexOf(u8, sock.sent.items, "\"input\":\"also mention the tests\"") != null);
- try std.testing.expect(st.awaiting_successor);
-
- // Double-Enter's force entry belongs to the interrupt path: nothing is sent, it stays.
- repl_glue.steerLock();
- try main_mod.g_steer_queue.append(page, .{ .text = try page.dupe(u8, "stop"), .force = true });
- repl_glue.steerUnlock();
- sock.sent.clearRetainingCapacity();
- try flushOne(agent, &sock, &st, false);
- try std.testing.expectEqual(@as(usize, 0), sock.sent.items.len);
- try std.testing.expectEqual(@as(usize, 1), main_mod.g_steer_queue.items.len);
-}
-
test "buildSteerFrame is type + previous_response_id + input" {
const gpa = std.testing.allocator;
const frame = try buildSteerFrame(gpa, "resp_1", "keep it small");
@@ -207,20 +365,6 @@ test "buildSteerFrame is type + previous_response_id + input" {
try std.testing.expect(std.mem.indexOf(u8, frame, "\"input\":\"keep it small\"") != null);
}
-test "steered incomplete is not end of turn; successor completed is" {
- var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
- defer arena_state.deinit();
- const a = arena_state.allocator();
- var st: Session = .{};
- noteFrame(a, &st, "{\"type\":\"response.created\",\"response\":{\"id\":\"resp_1\"}}");
- try std.testing.expectEqualStrings("resp_1", st.live_id);
- const inc = "{\"type\":\"response.incomplete\",\"response\":{\"id\":\"resp_1\",\"incomplete_details\":{\"reason\":\"steered\"}}}";
- noteFrame(a, &st, inc);
- try std.testing.expect(st.awaiting_successor);
- const Kind = @import("provider.zig").Provider.Kind;
- try std.testing.expect(!shouldStop(a, &st, Kind.responses, "data: " ++ inc, inc));
- noteFrame(a, &st, "{\"type\":\"response.created\",\"response\":{\"id\":\"resp_2\"}}");
- try std.testing.expectEqualStrings("resp_2", st.successor_id);
- const done = "{\"type\":\"response.completed\",\"response\":{\"id\":\"resp_2\"}}";
- try std.testing.expect(shouldStop(a, &st, Kind.responses, "data: " ++ done, done));
+test {
+ _ = @import("agent_ws_steer_tests.zig");
}
diff --git a/src/agent_ws_steer_tests.zig b/src/agent_ws_steer_tests.zig
new file mode 100644
index 00000000..ef72b4d8
--- /dev/null
+++ b/src/agent_ws_steer_tests.zig
@@ -0,0 +1,349 @@
+//! agent_ws_steer, frame by frame, in the orders the Codex route sends them.
+
+const std = @import("std");
+const Io = std.Io;
+const steer = @import("agent_ws_steer.zig");
+const main_mod = @import("main.zig");
+const repl_glue = @import("repl_glue.zig");
+const engine_sink = @import("engine_sink.zig");
+const Agent = @import("agent.zig").Agent;
+const page = std.heap.page_allocator;
+const expect = std.testing.expect;
+
+const created1 = "{\"type\":\"response.created\",\"response\":{\"id\":\"resp_1\",\"status\":\"in_progress\"}}";
+const created2 = "{\"type\":\"response.created\",\"response\":{\"id\":\"resp_2\",\"status\":\"in_progress\"}}";
+const accepted = "{\"type\":\"response.steer.accepted\",\"steer\":{\"id\":\"steer_1\",\"previous_response_id\":\"resp_1\"}}";
+const bees = "{\"type\":\"response.output_item.done\",\"item\":{\"type\":\"message\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"bees\"}]}}";
+const ants = "{\"type\":\"response.output_item.done\",\"item\":{\"type\":\"message\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"ants\"}]}}";
+const thought = "{\"type\":\"response.output_item.done\",\"item\":{\"type\":\"reasoning\",\"summary\":[]}}";
+const call = "{\"type\":\"response.output_item.done\",\"item\":{\"type\":\"function_call\",\"call_id\":\"call_1\",\"name\":\"get_project_status\",\"arguments\":\"{}\"}}";
+const done1 = "{\"type\":\"response.completed\",\"response\":{\"id\":\"resp_1\",\"status\":\"completed\",\"usage\":{\"input_tokens\":100,\"output_tokens\":10,\"total_tokens\":110}}}";
+const steered1 = "{\"type\":\"response.incomplete\",\"response\":{\"id\":\"resp_1\",\"status\":\"incomplete\",\"incomplete_details\":{\"reason\":\"steered\"},\"usage\":{\"input_tokens\":100,\"output_tokens\":5,\"total_tokens\":105}}}";
+const done2 = "{\"type\":\"response.completed\",\"response\":{\"id\":\"resp_2\",\"status\":\"completed\",\"usage\":{\"input_tokens\":120,\"output_tokens\":20,\"total_tokens\":140}}}";
+const pending = "{\"type\":\"response.steer.pending\",\"steer\":{\"id\":\"steer_1\",\"previous_response_id\":\"resp_1\"},\"reason\":\"waiting_for_required_input\",\"required_input\":[{\"type\":\"function_call_output\",\"call_id\":\"call_1\",\"name\":\"get_project_status\"}]}";
+const invalid = "{\"type\":\"response.steer.failed\",\"steer\":{\"previous_response_id\":\"resp_1\"},\"error\":{\"code\":\"invalid_input\",\"type\":\"invalid_request_error\"}}";
+const unsupported = "{\"type\":\"response.steer.failed\",\"steer\":{\"previous_response_id\":\"resp_1\"},\"error\":{\"code\":\"steering_not_supported\",\"type\":\"invalid_request_error\"}}";
+
+const drop = struct {
+ fn emit(_: *anyopaque, _: engine_sink.Stamped) void {}
+};
+const drop_vt = engine_sink.VTable{ .emit = drop.emit, .durable = false };
+
+const Socket = struct {
+ sent: std.ArrayList(u8) = .empty,
+ frames: usize = 0,
+ pub fn sendText(sock: *Socket, frame: []const u8) !void {
+ sock.frames += 1;
+ try sock.sent.appendSlice(std.testing.allocator, frame);
+ try sock.sent.append(std.testing.allocator, '\n');
+ }
+};
+
+/// One request's read loop: each frame joins the body, then steering sees it
+/// (agent_ws.postResponsesWs's order).
+const Run = struct {
+ arena_state: std.heap.ArenaAllocator,
+ agent: Agent,
+ sock: Socket,
+ st: steer.Session,
+ body: Io.Writer.Allocating,
+ text_seen: bool,
+
+ fn start(r: *Run, model: []const u8) !void {
+ r.arena_state = .init(std.testing.allocator);
+ r.agent = try @import("agent_request_body_responses.zig").testAgentFor(r.arena_state.allocator(), "codex", .responses, model);
+ r.agent.sink = .{ .ctx = undefined, .vt = &drop_vt };
+ r.sock = .{};
+ r.st = .{};
+ r.body = .init(std.testing.allocator);
+ r.text_seen = true;
+ }
+
+ fn feed(r: *Run, frame: []const u8) !bool {
+ try r.body.writer.print("data: {s}\n", .{frame});
+ return steer.tick(&r.agent, &r.sock, frame, &r.st, &r.body.writer, &r.text_seen);
+ }
+
+ /// The items stepResponses would append to history, in order.
+ fn output(r: *Run) ![]std.json.Value {
+ return switch (try @import("agent_responses.zig").parseResponses(&r.agent, r.body.written())) {
+ .ok => |root| root.get("output").?.array.items,
+ .err => error.TestUnexpectedResult,
+ };
+ }
+
+ fn end(r: *Run) void {
+ r.st.settle(std.testing.allocator);
+ r.body.deinit();
+ r.sock.sent.deinit(std.testing.allocator);
+ r.arena_state.deinit();
+ }
+};
+
+fn clearQueue() void {
+ repl_glue.steerLock();
+ defer repl_glue.steerUnlock();
+ for (main_mod.g_steer_queue.items) |e| page.free(e.text);
+ main_mod.g_steer_queue.clearRetainingCapacity();
+}
+
+fn enqueue(text: []const u8, force: bool) !void {
+ const owned = try page.dupe(u8, text);
+ repl_glue.steerLock();
+ defer repl_glue.steerUnlock();
+ try main_mod.g_steer_queue.append(page, .{ .text = owned, .force = force });
+}
+
+fn expectQueue(expected: []const []const u8) !void {
+ repl_glue.steerLock();
+ defer repl_glue.steerUnlock();
+ const q = main_mod.g_steer_queue.items;
+ try std.testing.expectEqual(expected.len, q.len);
+ for (expected, q) |want, got| try std.testing.expectEqualStrings(want, got.text);
+}
+
+fn userText(item: std.json.Value) []const u8 {
+ if (item != .object) return "";
+ const role = item.object.get("role") orelse return "";
+ if (role != .string or !std.mem.eql(u8, role.string, "user")) return "";
+ const content = item.object.get("content") orelse return "";
+ return if (content == .string) content.string else "";
+}
+
+test "steer mid-reply: accepted, the reply completes, a continuation carries it, history holds it between them" {
+ clearQueue();
+ defer clearQueue();
+ var r: Run = undefined;
+ try r.start("gpt-6-sol");
+ defer r.end();
+
+ try enqueue("list ants instead", false);
+ try expect(!try r.feed(created1));
+ try std.testing.expectEqual(@as(usize, 1), r.sock.frames);
+ try expect(std.mem.indexOf(u8, r.sock.sent.items, "\"previous_response_id\":\"resp_1\"") != null);
+ try expect(std.mem.indexOf(u8, r.sock.sent.items, "\"input\":\"list ants instead\"") != null);
+ try expect(!try r.feed(accepted));
+ try expect(!try r.feed(bees));
+ try expect(!try r.feed(done1)); // the continuation is still due
+ try expect(!try r.feed(created2));
+ try expect(!r.text_seen); // the continuation's budget starts over
+ try expect(!try r.feed(ants));
+ try expect(try r.feed(done2));
+ try expect(r.st.committed);
+
+ const out = try r.output();
+ try std.testing.expectEqual(@as(usize, 3), out.len);
+ try std.testing.expectEqualStrings("list ants instead", userText(out[1]));
+ try expect(@import("session_wake.zig").isNotice(out[1]));
+ const parsed = (try @import("agent_responses.zig").parseResponses(&r.agent, r.body.written())).ok;
+ try std.testing.expectEqualStrings("resp_2", parsed.get("id").?.string);
+ try std.testing.expectEqual(@as(i64, 120), parsed.get("usage").?.object.get("input_tokens").?.integer);
+ try std.testing.expectEqual(@as(usize, 1), parsed.get("steered_usage").?.array.items.len);
+ try expectQueue(&.{});
+}
+
+test "steer while reasoning: the response ends incomplete:steered and the continuation answers it" {
+ clearQueue();
+ defer clearQueue();
+ var r: Run = undefined;
+ try r.start("gpt-6-sol");
+ defer r.end();
+
+ try enqueue("write about ants", false);
+ try expect(!try r.feed(created1));
+ try expect(!try r.feed(accepted));
+ try expect(!try r.feed(thought));
+ try expect(!try r.feed(steered1));
+ try expect(!try r.feed(created2));
+ try expect(!try r.feed(thought));
+ try expect(!try r.feed(ants));
+ try expect(try r.feed(done2));
+ const out = try r.output();
+ try std.testing.expectEqual(@as(usize, 4), out.len);
+ try std.testing.expectEqualStrings("write about ants", userText(out[1]));
+}
+
+test "steer that meets a tool call waits for its output: after the call in history, no wait for the pending notice" {
+ clearQueue();
+ defer clearQueue();
+ var r: Run = undefined;
+ try r.start("gpt-6-sol");
+ defer r.end();
+
+ try enqueue("keep it to two weeks", false);
+ try expect(!try r.feed(created1));
+ try expect(!try r.feed(accepted));
+ try expect(!try r.feed(call));
+ // The server holds the steer for the tool output (and prepends it there),
+ // so the tool loop runs now; response.steer.pending may follow later.
+ try expect(try r.feed(done1));
+ const out = try r.output();
+ try std.testing.expectEqual(@as(usize, 2), out.len);
+ try std.testing.expectEqualStrings("function_call", out[0].object.get("type").?.string);
+ try std.testing.expectEqualStrings("keep it to two weeks", userText(out[1]));
+
+ // The next request's read loop meets that notice first; it ends nothing.
+ var next: Run = undefined;
+ try next.start("gpt-6-sol");
+ defer next.end();
+ try expect(!try next.feed(pending));
+ try expect(!try next.feed(created2));
+ try expect(!try next.feed(ants));
+ try expect(try next.feed(done2));
+}
+
+test "a failed steer goes back on the queue and waits: no resend on the same response" {
+ clearQueue();
+ defer clearQueue();
+ var r: Run = undefined;
+ try r.start("gpt-6-sol");
+ defer r.end();
+
+ try enqueue("also add tests", false);
+ try expect(!try r.feed(created1));
+ try std.testing.expectEqual(@as(usize, 1), r.sock.frames);
+ try expect(!try r.feed(invalid));
+ try expectQueue(&.{"also add tests"});
+ try expect(!try r.feed(bees));
+ try std.testing.expectEqual(@as(usize, 1), r.sock.frames); // paused for this response
+ try expect(try r.feed(done1));
+ r.st.settle(std.testing.allocator);
+ try expectQueue(&.{"also add tests"}); // delivered at the next step boundary instead
+}
+
+test "steering_not_supported turns steering off for the session" {
+ clearQueue();
+ defer clearQueue();
+ defer steer.g_unsupported = false;
+ var r: Run = undefined;
+ try r.start("gpt-6-sol");
+ defer r.end();
+
+ try enqueue("stop and summarize", false);
+ try expect(!try r.feed(created1));
+ try expect(!try r.feed(unsupported));
+ try expect(!steer.active("codex", "gpt-6-sol"));
+ try expectQueue(&.{"stop and summarize"}); // steer_now supersedes the reply with it
+ try expect(try r.feed(done1));
+}
+
+test "several steers accepted before one continuation go into history in order" {
+ clearQueue();
+ defer clearQueue();
+ var r: Run = undefined;
+ try r.start("gpt-6-sol");
+ defer r.end();
+
+ for ([_][]const u8{ "one", "two", "three" }) |t| try enqueue(t, false);
+ try expect(!try r.feed(created1));
+ try std.testing.expectEqual(@as(usize, 3), r.sock.frames);
+ for (0..3) |_| try expect(!try r.feed(accepted));
+ try expect(!try r.feed(bees));
+ try expect(!try r.feed(done1));
+ try expect(!try r.feed(created2));
+ try expect(!try r.feed(ants));
+ try expect(try r.feed(done2));
+ const out = try r.output();
+ try std.testing.expectEqual(@as(usize, 5), out.len);
+ for ([_][]const u8{ "one", "two", "three" }, out[1..4]) |want, got| try std.testing.expectEqualStrings(want, userText(got));
+}
+
+test "a steer sent as the reply ends: keep reading until the server answers it" {
+ clearQueue();
+ defer clearQueue();
+ var r: Run = undefined;
+ try r.start("gpt-6-sol");
+ defer r.end();
+
+ try expect(!try r.feed(created1));
+ try enqueue("one more thing", false);
+ try expect(!try r.feed(bees)); // goes out here
+ try expect(!try r.feed(done1)); // sent, not yet answered
+ try expect(!try r.feed(accepted)); // a completed response still gets a continuation
+ try expect(!try r.feed(created2));
+ try expect(!try r.feed(ants));
+ try expect(try r.feed(done2));
+ try std.testing.expectEqualStrings("one more thing", userText((try r.output())[1]));
+}
+
+test "the terminal frame carries no steer, and a force entry stays for the interrupt path" {
+ clearQueue();
+ defer clearQueue();
+ var r: Run = undefined;
+ try r.start("gpt-6-sol");
+ defer r.end();
+
+ try enqueue("stop", true);
+ try expect(!try r.feed(created1));
+ try expect(!try r.feed(bees));
+ try std.testing.expectEqual(@as(usize, 0), r.sock.frames);
+ clearQueue();
+ try enqueue("after the reply", false);
+ try expect(try r.feed(done1));
+ try std.testing.expectEqual(@as(usize, 0), r.sock.frames);
+ try expectQueue(&.{"after the reply"}); // the step boundary delivers it
+}
+
+test "a stream that dies hands every steer back, in order, ahead of later follow-ups" {
+ clearQueue();
+ defer clearQueue();
+ var r: Run = undefined;
+ try r.start("gpt-6-sol");
+ defer r.end();
+
+ try enqueue("first", false);
+ try enqueue("second", false);
+ try expect(!try r.feed(created1));
+ try expect(!try r.feed(accepted));
+ try expect(!try r.feed(accepted));
+ try expect(!try r.feed(bees));
+ try expect(!try r.feed(done1));
+ try expect(!try r.feed(created2)); // both placed in a body that now gets dropped
+ try enqueue("typed later", false);
+ r.st.settle(std.testing.allocator); // a stall or drop: postResponsesWs returns an error
+ try expectQueue(&.{ "first", "second", "typed later" });
+}
+
+test "steering is Codex and Platform OpenAI GPT-6 only; everything else ends on the terminal event" {
+ try expect(steer.active("codex", "gpt-6-sol"));
+ try expect(steer.active("openai", "gpt-6-astra"));
+ try expect(!steer.active("codegraff", "gpt-6-sol"));
+ try expect(!steer.active("codex", "gpt-5.6-sol"));
+
+ clearQueue();
+ defer clearQueue();
+ var r: Run = undefined;
+ try r.start("gpt-5.6-sol");
+ defer r.end();
+ try enqueue("queued", false);
+ try expect(!try r.feed(created1));
+ try expect(try r.feed(done1));
+ try std.testing.expectEqual(@as(usize, 0), r.sock.frames);
+}
+
+test "a GPT-6 root turn leaves server compaction off until the context nears its threshold, then stops steering" {
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ var agent = try @import("agent_request_body_responses.zig").testAgentFor(arena_state.allocator(), "codex", .responses, "gpt-6-sol");
+ const sc = @import("agent_server_compact.zig");
+ const threshold = agent.provider.compactAt();
+
+ try expect(sc.directive(&agent) == null); // inert this far below it anyway
+ try expect(steer.steers(&agent));
+ agent.last_context_tokens = threshold - threshold / 4 - 1;
+ try expect(steer.steers(&agent));
+ agent.last_context_tokens = threshold - threshold / 4; // compaction wins from here
+ try std.testing.expectEqual(threshold, sc.directive(&agent).?);
+ try expect(!steer.steers(&agent));
+
+ // Requests nobody steers keep the directive at any size.
+ agent.last_context_tokens = 0;
+ agent.compaction_request = true;
+ try std.testing.expectEqual(threshold, sc.directive(&agent).?);
+ agent.compaction_request = false;
+ agent.server_compaction_request = true;
+ try std.testing.expectEqual(@as(u64, 1_000), sc.directive(&agent).?);
+ agent.server_compaction_request = false;
+ agent.provider.model = "gpt-5.6-sol";
+ try std.testing.expectEqual(threshold, sc.directive(&agent).?);
+}
diff --git a/src/steer_now.zig b/src/steer_now.zig
index c226c766..8ea52a0c 100644
--- a/src/steer_now.zig
+++ b/src/steer_now.zig
@@ -56,6 +56,22 @@ pub fn send(text: []const u8) bool {
return true;
}
+/// Put follow-ups back at the head of the queue, in order: a steer the server
+/// rejected, or one a failed stream never delivered (agent_ws_steer). Takes
+/// the page-allocated texts; one the queue cannot hold is dropped.
+pub fn requeue(texts: []const []const u8) void {
+ repl_glue.steerLock();
+ defer repl_glue.steerUnlock();
+ var at: usize = 0;
+ for (texts) |t| {
+ main_mod.g_steer_queue.insert(std.heap.page_allocator, at, .{ .text = t, .force = false }) catch {
+ std.heap.page_allocator.free(t);
+ continue;
+ };
+ at += 1;
+ }
+}
+
/// 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.