Skip to content

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

Python

fix(stream): prevent false stalls during partial SSE events (#1765)

yxlyxcef66577a73a
diff --git a/docs/adr/0302-sse-idle-watchdogs-follow-body-byte-progress.md b/docs/adr/0302-sse-idle-watchdogs-follow-body-byte-progress.md
new file mode 100644
index 00000000..0584054c
--- /dev/null
+++ b/docs/adr/0302-sse-idle-watchdogs-follow-body-byte-progress.md
@@ -0,0 +1,38 @@
+# 0302. SSE idle watchdogs follow body-byte progress
+
+Status: accepted
+
+## Context
+
+An SSE event can contain a large completed output item rather than small text
+fragments. Racing a whole newline-delimited read against an inactivity timer
+mistakes a steadily arriving partial event for a silent connection (#1686).
+Reconnect then discards progress and repeats the request. The existing prose,
+reasoning and reconnect policies choose the idle allowance; they do not make a
+missing newline evidence of missing bytes.
+
+## Decision
+
+Keep those allowances and cancellation rules. During each line read, publish
+body progress through an atomic timestamp and expire inactivity only when that
+progress stops. The HTTP/1 delimiter reader uses an unbuffered forwarding writer;
+the HTTP/2 reader consumes `LineStream.readChunk`, preserving bytes after a
+newline for its next read. HTTP/2 control traffic is not response-body progress.
+Buffers remain owned by the read task, and cancellation joins it before cleanup.
+
+Bound an unfinished event separately: at most 128 MiB and fifteen minutes of
+assembly. An explicitly longer idle allowance also raises the assembly deadline,
+so the new deadline does not shorten an explicit silence setting. These bounds
+prevent oversized events and indefinitely dripping partial lines from disabling
+recovery. Event-size and assembly-deadline failures have distinct errors and are
+not replayed as transient network failures. Normal completion, delayed usage
+trailers, and genuine silence retain their existing outcomes.
+
+## Consequences
+
+A large event may take longer than one idle allowance while its body continues
+to arrive, without reconnecting. HTTP/2 reports body progress at DATA-chunk
+boundaries exposed by the pinned transport; no dependency change or raw
+connection/control-frame activity is needed. Synthetic HTTP/1 and HTTP/2 tests
+cover flowing and stopped partial events; `sse-partial-line-byte-progress` runs
+the actual engine against a fragmented scripted response and asserts one request.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 967e4d16..d43fae4d 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -326,6 +326,8 @@ record only when you need the evidence or the edge cases.
| [0301](0301-failed-requests-settle-the-pending-turn.md) | Exhausted request retries leave a truthful failure boundary in history so an identical prompt can run after reconnecting, including after save/load; duplicate-host protection and bounded retries stay unchanged. |
+| [0302](0302-sse-idle-watchdogs-follow-body-byte-progress.md) | SSE idle watchdogs observe partial body-byte progress, while separate unfinished-event time and size bounds preserve recovery. |
+
## When to write one
Write an ADR when a decision is load-bearing and non-obvious: it was reached
diff --git a/evals/harness_behavior.jsonl b/evals/harness_behavior.jsonl
index 3b59414d..3381bf8e 100644
--- a/evals/harness_behavior.jsonl
+++ b/evals/harness_behavior.jsonl
@@ -157,3 +157,4 @@
{"id": "issue-recurrence-search-failed", "why": "#1701: search-failed. Scripted policy delivery and local issue-state roundtrip, not live-model judgment. Independent verifiers reject incorrect state, missing evidence, extra mutations and missing final reads.", "scripted_only": true, "args": ["--old"], "env": {"GRAFF_NO_CODEDB_GUARD": "1", "GRAFF_AUTO_ISOLATE": "off"}, "github_fixture": {"repo": "fixture/primary", "issues": {"101": {"number": 101, "title": "recurrence fixture", "body": "Previously fixed fixture recurrence.", "state": "CLOSED", "stateReason": "COMPLETED", "comments": [], "url": "https://github.com/fixture/primary/issues/101"}}, "issue_list_denied": true}, "workspace_seed": {"recurrence.md": "**graff:** fixture (latest: fixture)\n**Harness:** not used\n**Surface:** terminal\n**Platform:** fixture\n\n## Symptom\nThe fixture failure recurs on the current fixture release.\n\n## Repro\nRepeat the local fixture operation.\n"}, "prompt": "Report the supplied fixture findings using only the installed local gh. Inspect resolution and tested-version evidence, follow canonical duplicate tracking, avoid duplicate issues and report any failed operation accurately.", "script": [{"tool": "bash", "arguments": {"command": "gh issue list --repo fixture/primary --state all --search 'recurrence fixture' --json number,title,body,state,stateReason"}}, {"text": "Issue search failed with permission denied. No issue was created, commented on or reopened; canonical tracking could not be verified."}], "verify_command": ["python3", "-c", "import json,pathlib\np=pathlib.Path\nexpected=json.loads('{\"101\": {\"number\": 101, \"title\": \"recurrence fixture\", \"body\": \"Previously fixed fixture recurrence.\", \"state\": \"CLOSED\", \"stateReason\": \"COMPLETED\", \"comments\": [], \"url\": \"https://github.com/fixture/primary/issues/101\"}}')\nstate=json.loads(p('gh-state.json').read_text())\nassert state['issues']==expected, ('issue state/evidence mismatch',state['issues'],expected)\nreads=[json.loads(x) for x in p('gh-argv.jsonl').read_text().splitlines()] if p('gh-argv.jsonl').exists() else []\nmutations=[json.loads(x) for x in p('mutations.jsonl').read_text().splitlines()] if p('mutations.jsonl').exists() else []\nassert [(r[1],r[2]) for r in mutations]==[], ('incorrect mutations',mutations)\nassert any(r[:2]==['issue','list'] and '--state' in r and r[r.index('--state')+1]=='all' for r in reads), 'must search all states'\nprint('Independent extended issue lifecycle verified')\n"], "assert": [{"request_contains": {"index": 0, "text": "A comment alone does not complete a recurrence report."}}, {"final_text_contains": "Issue search failed with permission denied. No issue was created, commented on or reopened; canonical tracking could not be verified."}, {"events_at_least": {"match": {"type": "tool_call", "name": "bash"}, "count": 1}}, {"events_at_least": {"match": {"type": "tool_call_finished", "name": "bash", "is_error": true}, "count": 1}}, {"events_at_most": {"match": {"type": "tool_call_finished", "name": "bash", "is_error": true}, "count": 1}}], "fixture_exit_codes": {"gh issue list --repo fixture/primary --state all --search 'recurrence fixture' --json number,title,body,state,stateReason": 1}, "fixture_negative_omissions": ["issue list"]}
{"why": "#1701: custom root prompts must retain issue lifecycle guidance; scripted policy-delivery coverage, not live-model judgment.", "scripted_only": true, "prompt": "Prepare a generic fixture report; do not publish anything.", "script": [{"text": "Fixture report prepared locally."}], "assert": [{"request_contains": {"index": 0, "text": "A comment alone does not complete a recurrence report."}}, {"request_contains": {"index": 0, "text": "CUSTOM_ROOT"}}, {"final_text_contains": "Fixture report prepared locally."}], "id": "issue-policy-custom-root-startup", "args": ["--system-prompt", "CUSTOM_ROOT"]}
{"why": "#1701: custom root prompts must retain issue lifecycle guidance; scripted policy-delivery coverage, not live-model judgment.", "scripted_only": true, "prompt": "Prepare a generic fixture report; do not publish anything.", "script": [{"text": "Fixture report prepared locally."}], "assert": [{"request_contains": {"index": 0, "text": "A comment alone does not complete a recurrence report."}}, {"request_contains": {"index": 0, "text": "CUSTOM_ROOT"}}, {"final_text_contains": "Fixture report prepared locally."}], "id": "issue-policy-custom-root-replaced", "controls_before_prompt": [{"type": "set_system_prompt", "text": "CUSTOM_ROOT"}]}
+{"id": "sse-partial-line-byte-progress", "why": "#1686: bytes inside an unfinished SSE event reset inactivity; a long, steadily arriving tool-call event must not reconnect or replay the request.", "env": {"GRAFF_STREAM_STALL_SECS": "1", "GRAFF_STREAM_HEAD_STALL_SECS": "1"}, "prompt": "Complete the synthetic transfer fixture.", "script": [{"tool": "attempt_completion", "arguments": {"result": "Partial-line transfer completed."}, "stream_fragment_bytes": 16, "stream_fragment_delay_ms": 100}], "assert": [{"request_count": 1}, {"event": {"type": "tool_call", "name": "attempt_completion"}}, {"final_text_contains": "Partial-line transfer completed."}, {"no_event": {"type": "error"}}]}
diff --git a/scripts/eval/mock_model.py b/scripts/eval/mock_model.py
index 30332a7e..c7d1ee75 100644
--- a/scripts/eval/mock_model.py
+++ b/scripts/eval/mock_model.py
@@ -32,6 +32,7 @@ import http.server
import json
import socketserver
import threading
+import time
from typing import Any
@@ -129,6 +130,8 @@ class ScriptedModel:
}).encode(), "application/json")
def _stream(self, reply: dict[str, Any]) -> None:
+ self._fragment_bytes = reply.get("stream_fragment_bytes", 0)
+ self._fragment_delay = reply.get("stream_fragment_delay_ms", 0) / 1000
self.send_response(200)
self.send_header("content-type", "text/event-stream")
self.send_header("cache-control", "no-cache")
@@ -176,7 +179,14 @@ class ScriptedModel:
def _chunk(self, payload: dict[str, Any]) -> None:
framed = dict(payload, id="mock", object="chat.completion.chunk", model="mock")
- self.wfile.write(b"data: " + json.dumps(framed).encode() + b"\n\n")
+ wire = b"data: " + json.dumps(framed).encode() + b"\n\n"
+ if not self._fragment_bytes:
+ self.wfile.write(wire)
+ return
+ for start in range(0, len(wire), self._fragment_bytes):
+ self.wfile.write(wire[start:start + self._fragment_bytes])
+ self.wfile.flush()
+ time.sleep(self._fragment_delay)
def log_message(self, *_args) -> None:
pass
diff --git a/src/agent_request.zig b/src/agent_request.zig
index ede0d7cf..9bf9a2f4 100644
--- a/src/agent_request.zig
+++ b/src/agent_request.zig
@@ -274,6 +274,7 @@ pub fn request(self: *Agent, tools_in: ?[]const u8) !std.json.ObjectMap {
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;
+ if (err == error.StreamTooLong or err == error.StreamEventDeadline) return err; // deterministic event bounds: replay cannot repair them
if (quota.transportCode(err)) |code| {
if (try quota.handle(self, "", code, "", &auth_refreshed)) continue;
return err;
diff --git a/src/agent_stream.zig b/src/agent_stream.zig
index 03747230..1aa551ff 100644
--- a/src/agent_stream.zig
+++ b/src/agent_stream.zig
@@ -30,7 +30,8 @@ const providerUserAgent = http.providerUserAgent;
const capture5xxBodyStream = http.capture5xxBodyStream;
const WatchdogFired = http.WatchdogFired;
const sendHeadTask = http.sendHeadTask;
-const streamLineTask = http.streamLineTask;
+const stream_progress = @import("stream_read_progress.zig");
+const streamLineTask = stream_progress.lineTask;
const deadlineStallTask = http.deadlineStallTask;
const watchdogError = http.watchdogError;
const http_stall = @import("http_stall.zig");
@@ -252,7 +253,8 @@ pub fn postStreamWithClient(self: *Agent, client: *std.http.Client, body: []cons
// #680: widened by each stall reconnect this request has already made.
// A terminal finish_reason may precede usage; never extend that completed response's trailer wait.
const stall_budget = if (saw_done) http_stall.interFrameBudgetMs(http.stream_stall_ms, got_body, prose_open, self.stall.widen) else policy.interFrameBudgetMs(got_body, prose_open, self.stall.widen);
- rsel.concurrent(.line, streamLineTask, .{ reader, &line.writer }) catch {
+ var progress = stream_progress.Progress.init(self.io, .{ .idle_ms = stall_budget });
+ rsel.concurrent(.line, streamLineTask, .{ reader, &line.writer, &progress }) catch {
// #56 Fix-B: pool exhausted — no idle-stall watchdog for this read.
// A bare blocking streamDelimiterEnding here is the last forever-hang:
// on a half-open socket it never returns and nothing can trip it. Fail
@@ -266,7 +268,7 @@ pub fn postStreamWithClient(self: *Agent, client: *std.http.Client, body: []cons
if (req.connection) |conn| conn.closing = true;
return error.StreamStalled;
};
- rsel.concurrent(.stall, deadlineStallTask, .{ self.io, orig_tio != null, stall_budget }) catch {
+ rsel.concurrent(.stall, stream_progress.Progress.watch, .{ &progress, orig_tio != null }) catch {
const r = rsel.await() catch |e| {
rsel.cancelDiscard();
return e;
@@ -308,7 +310,7 @@ pub fn postStreamWithClient(self: *Agent, client: *std.http.Client, body: []cons
if (w == .deadline) self.stall.tripped_ms = stall_budget; // #680: the turn-ending message reports THIS wait
if (w == .deadline) sink.emit(self.io, .{ .transport_aborted = .{ .reason = .stalled, .turn_ending = false } }) else sink.emit(self.io, .{ .stream_aborted = .interrupted });
if (req.connection) |conn| conn.closing = true;
- return watchdogError(w, error.StreamStalled);
+ return watchdogError(w, progress.deadlineError());
},
}
}
diff --git a/src/agent_stream_h2.zig b/src/agent_stream_h2.zig
index e3ef8a0f..f5416d66 100644
--- a/src/agent_stream_h2.zig
+++ b/src/agent_stream_h2.zig
@@ -18,6 +18,7 @@ const http_zig = @import("http_zig");
const WatchdogFired = http.WatchdogFired;
const watchdogError = http.watchdogError;
const deadlineStallTask = http.deadlineStallTask;
+const stream_progress = @import("stream_read_progress.zig");
const ssePayload = Agent.ssePayload;
const escPressed = Agent.escPressed;
@@ -99,6 +100,7 @@ pub fn postStream(self: *Agent, body: []const u8, poll_stdin: bool) !?[]u8 {
// Esc pressed while connecting / waiting for headers? Stop before the body.
if (poll_stdin and escPressed(true)) return error.Interrupted;
const lines = &head.lines.?;
+ var reader: stream_progress.H2Lines = .{ .source = lines };
// Any other status streams its body like the HTTP/1.1 path does: a 4xx
// error envelope is what request()'s parser classifies.
@@ -117,7 +119,7 @@ pub fn postStream(self: *Agent, body: []const u8, poll_stdin: bool) !?[]u8 {
while (true) {
// Buffered generation is over once finish_reason arrives; usage trailers keep the normal deadline.
const stall_budget = if (saw_done) http_stall.interFrameBudgetMs(http.stream_stall_ms, got_body, prose_open, self.stall.widen) else policy.interFrameBudgetMs(got_body, prose_open, self.stall.widen);
- const got = raceLine(self.io, lines, &line, gpa, poll_stdin, stall_budget) orelse {
+ const got = raceLine(self.io, &reader, &line, gpa, poll_stdin, stall_budget) orelse {
// #56 Fix-B: no spare concurrency for the read. Fail safe.
if (saw_done) break;
self.stall.tripped_ms = stall_budget;
@@ -127,7 +129,7 @@ pub fn postStream(self: *Agent, body: []const u8, poll_stdin: bool) !?[]u8 {
switch (got) {
.line => |r| {
const more = r catch |e| {
- if (e == error.Canceled) return e;
+ if (e == error.Canceled or e == error.StreamTooLong or e == error.StreamEventDeadline) return e;
if (saw_done) break;
if (got_body) {
sink.emit(self.io, .{ .stream_aborted = .dropped });
@@ -163,7 +165,7 @@ pub fn postStream(self: *Agent, body: []const u8, poll_stdin: bool) !?[]u8 {
if (self.provider.kind == .openai and openaiComplete(line.items)) saw_done = true;
if (isStreamEnd(self.scratchAlloc(), self.provider.kind, line.items)) {
saw_done = true;
- keep = settleAfterEnd(self.io, lines, gpa);
+ keep = settleAfterEnd(self.io, &reader, gpa);
break;
}
if ((poll_stdin and escPressed(true)) or (self.sub and Agent.esc_cancel.load(.acquire))) {
@@ -297,42 +299,36 @@ fn captureErrorBody(gpa: std.mem.Allocator, lines: *http_zig.LineStream) void {
}
}
-const ReadDone = union(enum) { line: anyerror!bool, stall: WatchdogFired };
+pub const ReadDone = union(enum) { line: anyerror!bool, stall: WatchdogFired };
/// One readLine raced against the between-lines watchdog. Null when there is
/// no concurrency slot for the read at all.
-fn raceLine(io: Io, lines: *http_zig.LineStream, line: *std.ArrayList(u8), gpa: std.mem.Allocator, poll_stdin: bool, budget_ms: u64) ?ReadDone {
+pub fn raceLine(io: Io, reader: *stream_progress.H2Lines, line: *std.ArrayList(u8), gpa: std.mem.Allocator, poll_stdin: bool, budget_ms: u64) ?ReadDone {
var rd_buf: [2]ReadDone = undefined;
var rsel: Io.Select(ReadDone) = .init(io, &rd_buf);
- rsel.concurrent(.line, lineTask, .{ lines, line, gpa }) catch return null;
- rsel.concurrent(.stall, deadlineStallTask, .{ io, poll_stdin, budget_ms }) catch {};
+ var progress = stream_progress.Progress.init(io, .{ .idle_ms = budget_ms });
+ rsel.concurrent(.line, stream_progress.H2Lines.readLine, .{ reader, line, gpa, &progress }) catch return null;
+ rsel.concurrent(.stall, stream_progress.Progress.watch, .{ &progress, poll_stdin }) catch {};
const first = rsel.await() catch |e| {
rsel.cancelDiscard();
return .{ .line = e };
};
rsel.cancelDiscard();
+ if (first == .stall and first.stall == .deadline and progress.assembly_expired)
+ return .{ .line = error.StreamEventDeadline };
return first;
}
/// The terminal event landed. Reuse the connection only if END_STREAM
/// follows promptly; a server that holds the stream open costs one dial.
-fn settleAfterEnd(io: Io, lines: *http_zig.LineStream, gpa: std.mem.Allocator) bool {
+fn settleAfterEnd(io: Io, reader: *stream_progress.H2Lines, gpa: std.mem.Allocator) bool {
var junk: std.ArrayList(u8) = .empty;
defer junk.deinit(gpa);
while (true) {
- if (lines.ended) {
- while (lines.readLine(&junk) catch return false) {}
- return true;
- }
- const got = raceLine(io, lines, &junk, gpa, false, trailing_end_ms) orelse return false;
+ const got = raceLine(io, reader, &junk, gpa, false, trailing_end_ms) orelse return false;
switch (got) {
- .line => |r| if (!(r catch return false)) return lines.ended,
+ .line => |r| if (!(r catch return false)) return reader.source.ended,
.stall => return false,
}
}
}
-
-fn lineTask(ls: *http_zig.LineStream, dest: *std.ArrayList(u8), gpa: std.mem.Allocator) !bool {
- _ = gpa;
- return ls.readLine(dest);
-}
diff --git a/src/agent_stream_h2_progress_test.zig b/src/agent_stream_h2_progress_test.zig
new file mode 100644
index 00000000..61c0fc3d
--- /dev/null
+++ b/src/agent_stream_h2_progress_test.zig
@@ -0,0 +1,181 @@
+//! The production H2 line race must observe DATA bytes before the first LF.
+//! Scripted HTTP/2 frames only: no sockets, TLS, provider, or user data.
+const std = @import("std");
+const Io = std.Io;
+const http_zig = @import("http_zig");
+const h2 = @import("agent_stream_h2.zig");
+const H2Lines = @import("stream_read_progress.zig").H2Lines;
+
+const idle_ms: u64 = 250;
+const frame_delay_ms: i64 = 25;
+const fragments: usize = 40;
+const control_frames: usize = 80;
+const fragment: [128]u8 = @splat('A');
+
+/// Like the pinned dependency's RecordReader, refill the Reader buffer instead
+/// of bypassing it through the Writer. Each refill exposes one complete frame,
+/// so even a read that requests more bytes cannot swallow the whole script.
+const PacedReader = struct {
+ interface: Io.Reader = undefined,
+ buffer: [1024]u8 = undefined,
+ bytes: []const u8 = &.{},
+ io: Io = undefined,
+ hold_open: bool = false,
+ data_seen: usize = 0,
+ controls_seen: usize = 0,
+
+ fn init(self: *PacedReader, io: Io, bytes: []const u8, hold_open: bool) void {
+ self.io = io;
+ self.bytes = bytes;
+ self.hold_open = hold_open;
+ self.interface = .{ .vtable = &.{ .stream = stream }, .buffer = &self.buffer, .seek = 0, .end = 0 };
+ }
+
+ fn stream(r: *Io.Reader, _: *Io.Writer, _: Io.Limit) Io.Reader.StreamError!usize {
+ const self: *PacedReader = @alignCast(@fieldParentPtr("interface", r));
+ if (self.bytes.len == 0) {
+ // Sleep is cancellable: raceLine.cancelDiscard joins this read
+ // before the fixture, connection, or destination is deinitialized.
+ while (self.hold_open) self.io.sleep(.fromMilliseconds(10), .awake) catch return error.ReadFailed;
+ return error.EndOfStream;
+ }
+ if (self.bytes.len < 9) return error.ReadFailed;
+ const n = 9 + (@as(usize, self.bytes[0]) << 16) + (@as(usize, self.bytes[1]) << 8) + self.bytes[2];
+ if (n > self.bytes.len) return error.ReadFailed;
+ const typ = self.bytes[3];
+ if (typ == 0 or typ == 6) {
+ self.io.sleep(.fromMilliseconds(frame_delay_ms), .awake) catch return error.ReadFailed;
+ }
+ const pending = r.buffered();
+ if (pending.len + n > r.buffer.len) return error.ReadFailed;
+ @memmove(r.buffer[0..pending.len], pending);
+ @memcpy(r.buffer[pending.len..][0..n], self.bytes[0..n]);
+ r.seek = 0;
+ r.end = pending.len + n;
+ self.bytes = self.bytes[n..];
+ if (typ == 0) self.data_seen += 1;
+ if (typ == 6) self.controls_seen += 1;
+ return 0;
+ }
+};
+
+fn writeHead(w: *Io.Writer) !void {
+ try http_zig.frame.write(w, .{ .typ = .settings, .flags = 0, .stream_id = 0, .payload = &.{} });
+ // HPACK's static-table :status 200, END_HEADERS, without END_STREAM.
+ try http_zig.frame.write(w, .{ .typ = .headers, .flags = 0x4, .stream_id = 1, .payload = &.{0x88} });
+}
+
+fn writeData(w: *Io.Writer, bytes: []const u8, end_stream: bool) !void {
+ try http_zig.frame.write(w, .{ .typ = .data, .flags = if (end_stream) 0x1 else 0, .stream_id = 1, .payload = bytes });
+}
+
+fn readLine(reader: *H2Lines, line: *std.ArrayList(u8)) !bool {
+ const got = h2.raceLine(std.testing.io, reader, line, std.testing.allocator, false, idle_ms) orelse return error.NoReadTask;
+ return switch (got) {
+ .line => |result| try result,
+ .stall => error.UnexpectedStall,
+ };
+}
+
+fn elapsedMs(start: Io.Timestamp) u64 {
+ const ns = Io.Timestamp.now(std.testing.io, .awake).nanoseconds - start.nanoseconds;
+ return @intCast(@divTrunc(ns, std.time.ns_per_ms));
+}
+
+test "HTTP/2 SSE byte progress keeps a fragmented line alive beyond its idle budget" {
+ const gpa = std.testing.allocator;
+ const io = std.testing.io;
+ var wire: Io.Writer.Allocating = .init(gpa);
+ defer wire.deinit();
+ try writeHead(&wire.writer);
+ try writeData(&wire.writer, "data: ", false);
+ for (0..fragments) |_| try writeData(&wire.writer, &fragment, false);
+ // Both the blank line and an unterminated final line share the last frame:
+ // subsequent races must retain bytes beyond the first delimiter.
+ try writeData(&wire.writer, "\n\ndata: tail", true);
+
+ var peer: PacedReader = .{};
+ peer.init(io, wire.written(), false);
+ var client: Io.Writer.Allocating = .init(gpa);
+ defer client.deinit();
+ var conn = http_zig.Conn.init(gpa, &peer.interface, &client.writer);
+ defer conn.deinit();
+ var source = try conn.startLines(.{ .method = "POST", .scheme = "https", .authority = "fixture.invalid", .path = "/events", .body = "{}" });
+ defer source.deinit();
+ try std.testing.expectEqual(@as(u16, 200), try source.waitStatus());
+ var reader: H2Lines = .{ .source = &source };
+ var line: std.ArrayList(u8) = .empty;
+ defer line.deinit(gpa);
+
+ const start = Io.Timestamp.now(io, .awake);
+ try std.testing.expect(try readLine(&reader, &line));
+ // Forty 25 ms fragments take at least four idle budgets, while every
+ // individual DATA gap has a tenfold allowance for scheduling jitter.
+ try std.testing.expect(elapsedMs(start) >= 3 * idle_ms);
+ try std.testing.expectEqual(@as(usize, 6 + fragments * fragment.len), line.items.len);
+ try std.testing.expectEqualStrings("data: ", line.items[0..6]);
+ for (line.items[6..]) |byte| try std.testing.expectEqual(@as(u8, 'A'), byte);
+ try std.testing.expectEqual(@as(usize, fragments + 2), peer.data_seen);
+ try std.testing.expect(try readLine(&reader, &line));
+ try std.testing.expectEqualStrings("", line.items);
+ try std.testing.expect(try readLine(&reader, &line));
+ try std.testing.expectEqualStrings("data: tail", line.items);
+ try std.testing.expect(!try readLine(&reader, &line));
+ try std.testing.expect(source.ended);
+}
+
+fn expectStoppedPartial(with_controls: bool) !void {
+ const gpa = std.testing.allocator;
+ const io = std.testing.io;
+ var wire: Io.Writer.Allocating = .init(gpa);
+ defer wire.deinit();
+ try writeHead(&wire.writer);
+ try writeData(&wire.writer, "data: partial", false);
+ if (with_controls) {
+ // ACKs need no response. They exercise Conn.readFrame's control loop
+ // without adding any response-body bytes or completing the SSE line.
+ for (0..control_frames) |_| try http_zig.frame.write(&wire.writer, .{ .typ = .ping, .flags = 0x1, .stream_id = 0, .payload = "12345678" });
+ }
+
+ var peer: PacedReader = .{};
+ peer.init(io, wire.written(), true);
+ var client: Io.Writer.Allocating = .init(gpa);
+ defer client.deinit();
+ var conn = http_zig.Conn.init(gpa, &peer.interface, &client.writer);
+ defer conn.deinit();
+ var source = try conn.startLines(.{ .method = "POST", .scheme = "https", .authority = "fixture.invalid", .path = "/events", .body = "{}" });
+ defer source.deinit();
+ try std.testing.expectEqual(@as(u16, 200), try source.waitStatus());
+ var reader: H2Lines = .{ .source = &source };
+ var line: std.ArrayList(u8) = .empty;
+ defer line.deinit(gpa);
+
+ const start = Io.Timestamp.now(io, .awake);
+ const got = h2.raceLine(io, &reader, &line, gpa, false, idle_ms) orelse return error.NoReadTask;
+ switch (got) {
+ .stall => |reason| try std.testing.expectEqual(.deadline, reason),
+ .line => |result| {
+ _ = try result;
+ return error.ExpectedIdleTimeout;
+ },
+ }
+ try std.testing.expect(elapsedMs(start) >= idle_ms);
+ try std.testing.expectEqual(@as(usize, 1), peer.data_seen);
+ try std.testing.expectEqualStrings("data: partial", line.items);
+ try std.testing.expect(!source.ended);
+ if (with_controls) {
+ try std.testing.expect(peer.controls_seen > 0);
+ // A timeout only after all two seconds of PINGs would falsely treat
+ // transport traffic as progress. Require cancellation during them.
+ try std.testing.expect(peer.controls_seen < control_frames);
+ try std.testing.expect(peer.bytes.len > 0);
+ }
+}
+
+test "HTTP/2 SSE byte progress still times out a stopped partial line" {
+ try expectStoppedPartial(false);
+}
+
+test "HTTP/2 SSE byte progress ignores control traffic after a partial line" {
+ try expectStoppedPartial(true);
+}
diff --git a/src/agent_stream_progress_test.zig b/src/agent_stream_progress_test.zig
new file mode 100644
index 00000000..7b95bcf1
--- /dev/null
+++ b/src/agent_stream_progress_test.zig
@@ -0,0 +1,93 @@
+//! Partial SSE events are active reads, not silent sockets (#1686).
+//! Synthetic loopback traffic drives the production HTTP/1 SSE entry point.
+const std = @import("std");
+const builtin = @import("builtin");
+const Io = std.Io;
+const Agent = @import("agent.zig").Agent;
+const http = @import("http.zig");
+const agent_stream = @import("agent_stream.zig");
+
+const Server = struct {
+ const Mode = enum { flowing, stopped };
+
+ fn run(io: Io, listener: *Io.net.Server, mode: Mode, done: *std.atomic.Value(bool)) void {
+ const conn = listener.accept(io) catch return;
+ defer conn.close(io);
+ var input_buf: [8192]u8 = undefined;
+ var input = Io.net.Stream.Reader.init(conn, io, &input_buf);
+ while (true) {
+ const line = (input.interface.takeDelimiter('\n') catch return) orelse return;
+ if (line.len == 0 or (line.len == 1 and line[0] == '\r')) break;
+ }
+ var output_buf: [1024]u8 = undefined;
+ var output = Io.net.Stream.Writer.init(conn, io, &output_buf);
+ output.interface.writeAll("HTTP/1.1 200 OK\r\ncontent-type: text/event-stream\r\nconnection: close\r\n\r\n" ++
+ ": ready\n\ndata: {\"choices\":[],\"padding\":\"") catch return;
+ output.interface.flush() catch return;
+ const fragment: [1]u8 = @splat('A');
+ for (0..18) |_| {
+ if (done.load(.acquire)) return;
+ output.interface.writeAll(&fragment) catch return;
+ output.interface.flush() catch return;
+ if (mode == .stopped) break;
+ io.sleep(.fromMilliseconds(40), .awake) catch return;
+ }
+ if (mode == .flowing) {
+ output.interface.writeAll("\"}\n\ndata: [DONE]\n\n") catch return;
+ output.interface.flush() catch return;
+ }
+ while (!done.load(.acquire)) io.sleep(.fromMilliseconds(10), .awake) catch return;
+ }
+};
+
+fn exercise(mode: Server.Mode) !void {
+ if (builtin.os.tag == .windows) return error.SkipZigTest;
+ const gpa = std.testing.allocator;
+ const io = std.testing.io;
+ var addr = try Io.net.IpAddress.parseLiteral("127.0.0.1:0");
+ var listener = try Io.net.IpAddress.listen(&addr, io, .{});
+ defer listener.deinit(io);
+ var done: std.atomic.Value(bool) = .init(false);
+ var server = io.async(Server.run, .{ io, &listener, mode, &done });
+ defer server.await(io);
+ defer done.store(true, .release);
+
+ const saved_budget = http.stream_stall_ms;
+ http.stream_stall_ms = 150;
+ defer http.stream_stall_ms = saved_budget;
+ var arena_state = std.heap.ArenaAllocator.init(gpa);
+ defer arena_state.deinit();
+ var client: std.http.Client = .{ .allocator = gpa, .io = io };
+ defer client.deinit();
+ var url_buf: [96]u8 = undefined;
+ const url = try std.fmt.bufPrint(&url_buf, "http://127.0.0.1:{d}/v1/chat/completions", .{listener.socket.address.getPort()});
+ var agent: Agent = .{
+ .gpa = gpa,
+ .arena = arena_state.allocator(),
+ .io = io,
+ .client = &client,
+ .provider = .{ .id = "test", .kind = .openai, .auth = .bearer, .url = url, .api_key = "synthetic", .model = "fixture", .context = 0 },
+ .messages = std.json.Array.init(arena_state.allocator()),
+ .sub = true,
+ .label = "fixture",
+ .out = null,
+ };
+ const response = agent_stream.postStreamWithClient(&agent, &client, "{}");
+ if (mode == .stopped) {
+ try std.testing.expectError(error.StreamStalled, response);
+ try std.testing.expectEqual(@as(u64, 150), agent.stall.tripped_ms);
+ } else {
+ const body = try response;
+ defer gpa.free(body);
+ try std.testing.expect(std.mem.indexOf(u8, body, "data: [DONE]") != null);
+ try std.testing.expectEqual(@as(usize, 18), std.mem.count(u8, body, "A"));
+ }
+}
+
+test "SSE byte progress keeps an unfinished event alive beyond its idle budget" {
+ try exercise(.flowing);
+}
+
+test "SSE byte progress does not hide a stopped partial event" {
+ try exercise(.stopped);
+}
diff --git a/src/main.zig b/src/main.zig
index 736edcda..c3041d84 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -577,7 +577,7 @@ test { // ── Unit tests (`zig build test`): pull in tests from imported modu
_ = @import("agent_ws_steer.zig");
_ = @import("agent_ws_signal.zig");
_ = .{ @import("agent_ws_prewarm.zig"), @import("agent_ws_headers.zig") };
- _ = .{ @import("http2_pool.zig"), @import("agent_stream_h2.zig"), @import("agent_stream_h2_transport_test.zig") }; // h2 stream path, and graff's request/response contract over the pinned http-zig
+ _ = .{ @import("http2_pool.zig"), @import("agent_stream_h2.zig"), @import("agent_stream_h2_transport_test.zig"), @import("agent_stream_progress_test.zig"), @import("agent_stream_h2_progress_test.zig"), @import("stream_read_progress.zig") }; // transport contracts and partial-event byte progress
_ = @import("acp_preauth.zig"); // credential-free ACP loop must stay in the test root
_ = .{ @import("acp_protocol.zig"), @import("acp_v2.zig"), @import("acp_v2_prompt.zig"), @import("acp_session_load.zig"), @import("acp_session_fork.zig"), @import("session_fork.zig"), @import("acp_elicit.zig"), @import("hot_context.zig"), @import("history_translate.zig"), @import("mcp_notify.zig"), @import("mcp_wait.zig"), @import("mcp_pages.zig"), @import("mcp_mrtr.zig"), @import("ask_user_args.zig"), @import("mcp_add.zig"), @import("mcp_lazy.zig"), @import("mcp_share.zig"), @import("acp_room.zig"), @import("mcp_catalog.zig"), @import("mcp_watch.zig"), @import("acp_engine_test.zig"), @import("subagent_mimo_tests.zig"), @import("mimo_effort_tests.zig"), @import("gateway_picker_catalog.zig"), @import("ask_user_answers.zig"), @import("job_class.zig"), @import("startup_claim.zig") };
_ = @import("task_outcome.zig"); // goal-outcome telemetry events
diff --git a/src/stream_read_progress.zig b/src/stream_read_progress.zig
new file mode 100644
index 00000000..925883df
--- /dev/null
+++ b/src/stream_read_progress.zig
@@ -0,0 +1,170 @@
+//! SSE inactivity is lack of body-byte progress, not lack of a complete line.
+//! The read task owns all buffers; its watchdog observes only an atomic clock.
+const std = @import("std");
+const Io = std.Io;
+const http = @import("http.zig");
+const Agent = @import("agent.zig").Agent;
+const cancel_source = @import("cancel_source.zig");
+
+pub const Limits = struct {
+ idle_ms: u64,
+ // A peer dripping bytes cannot hold an unfinished event open forever.
+ total_ms: u64 = 15 * 60 * 1000,
+ max_bytes: usize = 128 * 1024 * 1024,
+};
+
+pub fn expired(start_ms: i64, last_ms: i64, now_ms: i64, limits: Limits) bool {
+ const idle: u64 = @intCast(@max(now_ms - last_ms, 0));
+ const total: u64 = @intCast(@max(now_ms - start_ms, 0));
+ return idle >= limits.idle_ms or total >= @max(limits.total_ms, limits.idle_ms);
+}
+
+fn nowMs(io: Io) i64 {
+ return @intCast(@divTrunc(Io.Timestamp.now(io, .awake).nanoseconds, std.time.ns_per_ms));
+}
+
+pub const Progress = struct {
+ io: Io,
+ limits: Limits,
+ started_ms: i64,
+ last_ms: std.atomic.Value(i64),
+ assembly_expired: bool = false, // read only after the watchdog has joined
+
+ pub fn init(io: Io, limits: Limits) Progress {
+ const now = nowMs(io);
+ return .{ .io = io, .limits = limits, .started_ms = now, .last_ms = .init(now) };
+ }
+
+ pub fn note(self: *Progress) void {
+ self.last_ms.store(nowMs(self.io), .monotonic);
+ }
+
+ pub fn watch(self: *Progress, poll_stdin: bool) http.WatchdogFired {
+ while (!expired(self.started_ms, self.last_ms.load(.monotonic), nowMs(self.io), self.limits)) {
+ self.io.sleep(.fromMilliseconds(10), .awake) catch return .deadline;
+ if (poll_stdin and Agent.drainSteerStdin(true)) {
+ cancel_source.cancelFromStdin();
+ return .esc;
+ }
+ if (Agent.esc_cancel.load(.acquire)) return .esc;
+ }
+ const elapsed: u64 = @intCast(@max(nowMs(self.io) - self.started_ms, 0));
+ self.assembly_expired = elapsed >= @max(self.limits.total_ms, self.limits.idle_ms);
+ return .deadline;
+ }
+
+ pub fn deadlineError(self: *const Progress) anyerror {
+ return if (self.assembly_expired) error.StreamEventDeadline else error.StreamStalled;
+ }
+};
+
+/// An unbuffered forwarding writer observes each fragment the delimiter reader
+/// consumes, including fragments much smaller than a normal writer buffer.
+const Writer = struct {
+ out: *Io.Writer,
+ progress: *Progress,
+ bytes: usize = 0,
+ too_long: bool = false,
+ writer: Io.Writer = .{ .vtable = &.{ .drain = drain }, .buffer = &.{}, .end = 0 },
+
+ fn write(self: *Writer, bytes: []const u8) Io.Writer.Error!void {
+ if (bytes.len > self.progress.limits.max_bytes - self.bytes) {
+ self.too_long = true;
+ return error.WriteFailed;
+ }
+ try self.out.writeAll(bytes);
+ self.bytes += bytes.len;
+ if (bytes.len > 0) self.progress.note();
+ }
+
+ fn drain(w: *Io.Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize {
+ const self: *Writer = @alignCast(@fieldParentPtr("writer", w));
+ var written: usize = 0;
+ for (data[0 .. data.len - 1]) |part| {
+ try self.write(part);
+ written += part.len;
+ }
+ const pattern = data[data.len - 1];
+ for (0..splat) |_| try self.write(pattern);
+ return written + pattern.len * splat;
+ }
+};
+
+pub fn lineTask(reader: *Io.Reader, out: *Io.Writer, progress: *Progress) !usize {
+ var writer: Writer = .{ .out = out, .progress = progress };
+ return reader.streamDelimiterEnding(&writer.writer, '\n') catch |err| {
+ if (writer.too_long) return error.StreamTooLong;
+ return err;
+ };
+}
+
+/// http-zig's readLine hides DATA progress until LF. Consume its body chunks
+/// instead, retaining any bytes beyond LF across successive line reads. Control
+/// frames and DATA for other streams do not count as this response's progress.
+pub const H2Lines = struct {
+ source: *@import("http_zig").LineStream,
+ buffer: [8192]u8 = undefined,
+ start: usize = 0,
+ end: usize = 0,
+
+ pub fn readLine(self: *H2Lines, dest: *std.ArrayList(u8), gpa: std.mem.Allocator, progress: *Progress) !bool {
+ dest.clearRetainingCapacity();
+ while (true) {
+ if (self.start == self.end) {
+ self.start = 0;
+ self.end = try self.source.readChunk(&self.buffer);
+ if (self.end == 0) return dest.items.len > 0;
+ progress.note();
+ }
+ const bytes = self.buffer[self.start..self.end];
+ const end = std.mem.indexOfScalar(u8, bytes, '\n');
+ const n = end orelse bytes.len;
+ if (n > progress.limits.max_bytes - dest.items.len) return error.StreamTooLong;
+ try dest.appendSlice(gpa, bytes[0..n]);
+ self.start += n;
+ if (end != null) {
+ self.start += 1;
+ return true;
+ }
+ }
+ }
+};
+
+test "SSE byte progress resets idle time but not the unfinished-event deadline" {
+ const limits: Limits = .{ .idle_ms = 100, .total_ms = 500 };
+ try std.testing.expect(!expired(0, 90, 100, limits));
+ try std.testing.expect(expired(0, 90, 190, limits));
+ try std.testing.expect(expired(0, 490, 500, limits));
+ try std.testing.expect(!expired(0, 490, 499, limits));
+ // An explicitly longer silence allowance is not shortened by the cap.
+ try std.testing.expect(!expired(0, 590, 600, .{ .idle_ms = 700, .total_ms = 500 }));
+}
+
+test "SSE byte progress bounds an oversized unfinished event before appending it" {
+ var reader: Io.Reader = .fixed("abcdefgh\n");
+ var out: Io.Writer.Allocating = .init(std.testing.allocator);
+ defer out.deinit();
+ var progress = Progress.init(std.testing.io, .{ .idle_ms = 100, .max_bytes = 4 });
+ try std.testing.expectError(error.StreamTooLong, lineTask(&reader, &out.writer, &progress));
+ try std.testing.expectEqual(@as(usize, 0), out.written().len);
+}
+
+test "SSE byte progress still ends a peer that drips an event forever" {
+ const Drip = struct {
+ fn run(progress: *Progress, done: *std.atomic.Value(bool)) void {
+ while (!done.load(.acquire)) {
+ progress.note();
+ progress.io.sleep(.fromMilliseconds(20), .awake) catch return;
+ }
+ }
+ };
+ var progress = Progress.init(std.testing.io, .{ .idle_ms = 150, .total_ms = 300 });
+ var done: std.atomic.Value(bool) = .init(false);
+ var peer = std.testing.io.async(Drip.run, .{ &progress, &done });
+ defer peer.await(std.testing.io);
+ defer done.store(true, .release);
+ try std.testing.expectEqual(http.WatchdogFired.deadline, progress.watch(false));
+ const elapsed = nowMs(std.testing.io) - progress.started_ms;
+ try std.testing.expect(elapsed >= 300 and elapsed < 2000);
+ try std.testing.expectEqual(error.StreamEventDeadline, progress.deadlineError());
+}