Skip to content

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

Python

Release v0.302.39

justrachf330ded828a1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9e295551..31573e46 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,15 @@ The release workflow uses a tag's section here as its release notes (a
hand-written `docs/releases/<tag>.md` wins if present), so keeping this file
current is part of cutting a release.
+## v0.302.39
+
+### Unattended runs
+
+- Output limits continue with bounded recovery and incremental file writes; incomplete tool calls are never executed.
+- Empty replies retry with cancellable, jittered backoff. Account-limit and sign-in failures stop with distinct exit codes instead of wasting retries.
+- `-p --output-format stream-json` emits a session handle at startup and a final result with status, usage, cost completeness and checkpoint status. Forced budget landings report partial work, not completion.
+- Buffered generation gets request-local silence allowances, and raw MCP startup exceptions are debug-only. Recovery still uses session checkpoints, not exactly-once journal replay.
+
## v0.302.38
### Windows
diff --git a/docs/adr/0284-output-limits-are-recovery-not-completion.md b/docs/adr/0284-output-limits-are-recovery-not-completion.md
new file mode 100644
index 00000000..f4326ae1
--- /dev/null
+++ b/docs/adr/0284-output-limits-are-recovery-not-completion.md
@@ -0,0 +1,47 @@
+# 0284. Provider recovery must not masquerade as completion
+
+Status: accepted 2026-10-17
+
+## Context
+
+Unattended authoring stopped on output limits and exhausted empty replies.
+A supervisor had neither a reliable execution result nor a resume handle,
+so retrying often required filename discovery and could waste attempts on
+an account failure. Existing tool-batch checkpoints preserve useful work,
+but are not a write-ahead execution journal.
+
+## Decision
+
+Treat output-length stops as bounded in-turn continuations, preserving
+partial history and requesting small complete file-writing calls. Never
+execute cut tool arguments. Keep the allowance on the turn stack so tool
+progress or compaction cannot reset it. Empty replies back off with jitter
+and fail explicitly after exhaustion. Account billing/auth faults outrank
+transient envelopes, with no blind retry into a hard cap.
+
+One-shot `--output-format stream-json` reuses the existing event transport,
+with an initial resume handle and a terminal result containing the outcome,
+classified exit code, usage completeness, elapsed time and cost. Ordinary
+text stdout stays compatible. Save the session before reporting the result,
+including on errors. Unknown charges stay null, not fabricated zeroes.
+Latch a forced tools-off final-budget landing and report budget exhaustion,
+not completion inferred from its prose, even without an open checklist.
+An ordinary final answer before the forced landing remains successful.
+Keep startup's raw MCP exceptions behind the debug switch without hiding
+configured servers from the agent. Buffered Gemini-4 generation gets a
+request-local silence allowance after headers, not a process-global timeout
+increase; explicit overrides and active-prose watchdogs retain precedence.
+
+## Consequences
+
+Recovery is bounded and may stop with partial work, but is no longer a
+successful blank/truncated final. The result describes what this invocation
+knows, not a proof of semantic task success or whole-run accounting across
+processes. Do not claim exactly-once tools: snapshot recovery cannot decide
+whether a crash after an unjournalled side effect completed it. A real
+journal/replay migration needs operation-specific reconciliation rather
+than hashes as an idempotency guarantee.
+
+The offline supervisor regressions live in
+`scripts/test-headless-durability.py`; the precise output contract and
+remaining gaps are in `docs/headless-durability.md`.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index ea733fb6..1aae9835 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -294,6 +294,7 @@ record only when you need the evidence or the edge cases.
| [0281](0281-anthropic-console-sign-in-reads-the-sdk-profile.md) | Anthropic Console sign-in: graff reads the `user_oauth` profile Anthropic's CLI writes (`ant auth login`), in the SDK's precedence (API key wins), sends it as Bearer, and refreshes through `ant auth print-credentials`; `graff login anthropic` runs `ant auth login`. No claude.ai subscription login. |
| [0282](0282-claude-system-breakpoint-closes-before-the-repo-context.md) | On Claude, the system prompt is two text blocks with the same bytes: the cache breakpoint closes the static instructions, before the project instructions and layout, so every repo shares the tools + instructions prefix. |
| [0283](0283-agents-prepare-and-linked.md) | New task worktrees symlink the gitignored paths `.agents/linked` lists from the main checkout and run `.agents/prepare` when `.graff/workspace.toml` names no setup script. |
+| [0284](0284-output-limits-are-recovery-not-completion.md) | Output limits continue with bounded recovery; empty replies back off; one-shots expose a saved-session handle and classified result without claiming unknown costs or exactly-once replay. |
## When to write one
diff --git a/docs/headless-durability.md b/docs/headless-durability.md
new file mode 100644
index 00000000..53c8b326
--- /dev/null
+++ b/docs/headless-durability.md
@@ -0,0 +1,104 @@
+# Unattended runs: recovery and supervisor contract
+
+Use the one-shot stream when a program owns the job:
+
+```sh
+graff -p --output-format stream-json --max-model-calls 500 "Write the deliverables to files"
+graff -p --output-format stream-json --resume SESSION_ID "Continue the saved work"
+```
+
+`--output-format stream-json` (or `-p --json`) keeps stdout JSONL. Its first
+one-shot lifecycle event is `run_started`, carrying `run_id`, `session_id`
+and nullable `parent_session_id`. Save the session id immediately rather
+than scanning session filenames. Ordinary text mode also writes that start
+record to stderr; its stdout remains the answer.
+
+The final event is `result`, with `status`, `reason`, `exit_code`,
+`retryable`, `session_saved`, the same ids, `turns`, `model_calls`,
+`duration_ms`, `usage`, `total_cost_usd`, `known_cost_usd`, `cost_complete`,
+`unpriced_calls`, `subscription_calls` and `result` (answer/error text).
+Events between the start and result use the existing text/tool JSON stream.
+A successful turn is not independent proof that an artifact satisfies the
+brief: use `--eval` for an executable acceptance check. Open checklist work,
+unsatisfied evaluation and recovery exhaustion must not report completion.
+
+`total_cost_usd` is null when any charge is unknown; `known_cost_usd` is only
+a subtotal in that case. Token totals expose missing usage and failed
+attempts without usage rather than inventing numbers. Subscription calls
+have no incremental token charge and are counted separately. These are
+invocation totals, including recorded descendant usage, not cumulative
+multi-process resumed-run totals. Duration is elapsed one-shot execution
+in this process, not time across retries or startup.
+
+## Exit codes after one-shot execution starts
+
+| Code | Meaning | Supervisor action |
+|---|---|---|
+| 0 | Completed turn, with no known unfinished checklist/evaluation | Validate deliverables as required |
+| 1 | Other failure, including an unsuccessful final session save | Inspect the result |
+| 2 | Unfinished work, model loop, or exhausted length continuation | Inspect partial work before continuing |
+| 3 | Invocation model/tool budget exhausted | Resume with an explicitly raised budget |
+| 4 | Credit/billing/quota cap | Fix the account limit; do not blindly retry |
+| 75 | Transient provider/transport failure after bounded recovery | Retry/resume with supervisor backoff |
+| 77 | Authentication/permission or required fallback consent | Repair credentials/consent first |
+| 78 | Invalid provider request | Fix the request/configuration |
+| 130 | Cancelled | Resume only if still wanted |
+
+The execution boundary saves the current session on both success and
+failure and reports whether saving worked. Abrupt process termination,
+output-pipe failure and startup/argument/credential errors before this
+boundary cannot promise a terminal result event. `--resume` takes an
+explicit saved name; `last` is not a newest-session alias. Normal resume
+continues that session; `--branch` records an independent child session.
+
+## Recovery policy
+
+An output-length stop retains partial history and grants a bounded in-turn
+continuation that asks for incremental file writes, not another full draft
+in a reply. The allowance is per turn and cannot be refilled by tools or
+compaction. Truncated tool arguments remain non-executable. Reasoning-only
+length stops also receive a brief-answer note. Cancellation and invocation
+budgets take precedence. A forced tools-off final-budget landing is reported
+as budget exhaustion, even if its prose sounds successful; it is not proof
+that the requested work finished.
+
+Empty completions are transient failures, with cancellation-aware jittered
+backoff rather than immediate identical calls. Billing/auth refusals take
+precedence over generic retryable HTTP envelopes. Exhausting recovery is a
+failure, not a successful empty answer.
+
+Gemini-4 model ids, including provider-qualified aliases, get a request-local
+20-minute silence allowance for buffered output after HTTP headers. Active
+answer prose retains the normal short stall/reconnect policy. Explicit
+`GRAFF_STREAM_STALL_SECS` and `GRAFF_STREAM_HEAD_STALL_SECS` settings override
+the model defaults; connect/header deadlines are unchanged. This protects
+client-side waits, not gateway/upstream idle deadlines.
+
+Raw MCP startup exception lines are debug-only (`GRAFF_REPL_DEBUG=1`).
+Configured servers are not removed or silently disabled: cached stdio
+servers retain their existing lazy start, and normal MCP status/tool-call
+errors remain available. This is quiet startup, not universal lazy discovery.
+
+## Still not journal-first execution
+
+Current checkpoints record messages and completed tool batches, and
+compaction context survives session snapshots. Recovery loads a snapshot,
+not an authoritative write-ahead execution journal. A crash between a side
+effect and its checkpoint is still ambiguous. Input hashes cannot make an
+arbitrary shell command or remote API exactly-once; that needs explicit
+prepare/commit records and operation-specific reconciliation or a
+cooperating idempotent service.
+
+Remaining larger work:
+
+- Authoritative append-before-dispatch journal, replay state machine and
+ explicit reconciliation of interrupted side effects.
+- Whole-run identity/lineage, wall/agent time and accounting across resumed
+ processes, rather than just invocation ids plus saved session parentage.
+- Dollar budgets and route-specific pre-flight credit checks. Current
+ budgets count calls/tools; unknown charges cannot enforce a dollar cap.
+- Account-wide route capacity discovery and cross-process queuing. The
+ existing invocation-local concurrency limiter does not discover an
+ upstream account's actual limit.
+- Gateway-side heartbeat and idle-timeout support. A longer client-side
+ silence allowance cannot keep an upstream gateway connection alive.
diff --git a/scripts/eval/mock_model.py b/scripts/eval/mock_model.py
index 5bf6ebfa..30332a7e 100644
--- a/scripts/eval/mock_model.py
+++ b/scripts/eval/mock_model.py
@@ -90,7 +90,7 @@ class ScriptedModel:
model.request_headers.append({k.lower(): v for k, v in self.headers.items()})
reply = model.next_reply(body)
if reply.get("http_status"):
- payload = json.dumps({"error": {"message": reply.get("error", "Scripted request failure")}}).encode()
+ payload = reply.get("raw_error_body", json.dumps({"error": {"message": reply.get("error", "Scripted request failure")}})).encode()
self.send_response(reply["http_status"])
self.send_header("content-type", "application/json")
self.send_header("content-length", str(len(payload)))
diff --git a/scripts/eval/tier1-manifest.json b/scripts/eval/tier1-manifest.json
index 3f17b5d5..961e4f5a 100644
--- a/scripts/eval/tier1-manifest.json
+++ b/scripts/eval/tier1-manifest.json
@@ -14,7 +14,7 @@
"src/main.zig",
"src/repl.zig"
],
- "test_count_baseline": 3254,
+ "test_count_baseline": 3276,
"test_count_slack": 25,
"required_invariants": [
{
diff --git a/scripts/test-headless-durability.py b/scripts/test-headless-durability.py
new file mode 100644
index 00000000..96decd3f
--- /dev/null
+++ b/scripts/test-headless-durability.py
@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""Offline one-shot supervisor regressions using the project's scripted model."""
+import argparse
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import tempfile
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "scripts" / "eval"))
+from mock_model import ScriptedModel
+
+
+def run_case(binary, script, code=0, reason="completed", extra=(), resume=False, plain=False):
+ model = ScriptedModel(script)
+ port = model.start(0)
+ try:
+ with tempfile.TemporaryDirectory(prefix="graff-durable-") as temp:
+ work = Path(temp)
+ (work / ".graff").mkdir()
+ (work / ".graff" / ".config.router").write_text(json.dumps({
+ "id": "durability-fixture", "base_url": f"http://127.0.0.1:{port}/v1",
+ "env_key": "DURABILITY_FIXTURE_KEY", "default_model": "mock",
+ }))
+ env = {key: value for key, value in os.environ.items()
+ if not key.endswith(("_API_KEY", "_TOKEN")) and not key.startswith("GRAFF_")}
+ env.update(HOME=temp, XDG_CONFIG_HOME=temp, DURABILITY_FIXTURE_KEY="fixture",
+ GRAFF_NO_TELEMETRY="1", GRAFF_FLEET="off", GRAFF_NO_PLUGINS="1",
+ GRAFF_NO_SMOLIFY="1", GRAFF_NO_CODEDB_GUARD="1", GRAFF_ACCORD="0",
+ GRAFF_AUTO_ISOLATE="0", NO_COLOR="1")
+ command = [str(binary), "--no-telemetry", "--old", "--model", "durability-fixture/mock"]
+ if not plain:
+ command += ["--output-format", "stream-json"]
+ done = subprocess.run(command + list(extra) + ["-p", "Write the requested artifact to result.txt, then report completion."],
+ cwd=work, env=env, text=True, capture_output=True, timeout=60)
+ assert done.returncode == code, (done.returncode, done.stdout[-2500:], done.stderr[-2500:])
+ if plain:
+ assert done.stdout.strip() == "saved", done.stdout
+ start = next(json.loads(line) for line in done.stderr.splitlines() if line.startswith('{"type":"run_started"'))
+ assert start["session_id"]
+ return
+ events = [json.loads(line) for line in done.stdout.splitlines() if line.strip()]
+ assert events[0]["type"] == "run_started", events
+ results = [event for event in events if event.get("type") == "result"]
+ assert len(results) == 1 and events[-1] == results[0], events
+ final = results[0]
+ assert final["reason"] == reason and final["exit_code"] == code, final
+ assert final["run_id"] == events[0]["run_id"] and final["session_id"] == events[0]["session_id"], events
+ assert final["session_saved"], final
+ assert final["duration_ms"] >= 0 and final["model_calls"] >= 1, final
+ if code == 0:
+ assert final["status"] == "completed", final
+ # The fixture route is deliberately unpriced: never fabricate $0.
+ assert final["total_cost_usd"] is None and not final["cost_complete"], final
+ if code in (4, 77):
+ assert len(model.requests) == 1 and not final["retryable"], (final, model.requests)
+ if script[0].get("finish") == "length" and code == 0:
+ assert (work / "result.txt").read_text() == "saved\n"
+ assert len(model.requests) == 3, model.requests
+ assert "increment" in json.dumps(model.requests[1]).lower() or "pieces" in json.dumps(model.requests[1]).lower(), model.requests[1]
+ if resume:
+ assert (work / "result.txt").read_text() == "saved\n"
+ resumed = subprocess.run(command + ["--resume", final["session_id"], "-p", "Continue from the saved checkpoint."],
+ cwd=work, env=env, text=True, capture_output=True, timeout=60)
+ assert resumed.returncode == 0, (resumed.stdout, resumed.stderr)
+ continued = [json.loads(line) for line in resumed.stdout.splitlines() if line.strip()]
+ assert continued[0]["session_id"] == final["session_id"], continued
+ assert continued[-1]["status"] == "completed", continued
+ assert "saved" in json.dumps(model.requests[-1]), model.requests[-1]
+ finally:
+ model.stop()
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--graff", type=Path, default=ROOT / "zig-out" / "bin" / "graff")
+ args = parser.parse_args()
+ binary = args.graff.resolve()
+ write = {"tool": "write_file", "arguments": {"path": "result.txt", "content": "saved\n"}}
+ run_case(binary, [{"text": "saved"}], plain=True)
+ print("PASS plain stdout preserved; startup resume handle on stderr", flush=True)
+ run_case(binary, [{"text": "partial draft", "finish": "length"}, write, {"text": "saved"}])
+ print("PASS length continues through file write; one terminal JSON result", flush=True)
+ run_case(binary, [write, {"text": "saved"}], code=3, reason="budget_exhausted", extra=("--max-model-calls", "1"), resume=True)
+ print("PASS budget stop saves partial work and resumes by emitted session id", flush=True)
+ run_case(binary, [{"text": "Partial work remains; continue with more budget."}], code=3, reason="budget_exhausted", extra=("--max-model-calls", "1"))
+ print("PASS forced tools-off budget landing never reports completed", flush=True)
+ run_case(binary, [{"http_status": 402, "error": "exhausted credit"}], code=4, reason="quota_exhausted")
+ print("PASS exhausted credit has a distinct non-retryable exit", flush=True)
+ run_case(binary, [{"http_status": 401, "error": "invalid_api_key"}], code=77, reason="authentication_required")
+ print("PASS authentication has a distinct non-retryable exit", flush=True)
+ run_case(binary, [{"http_status": 429, "error": "exhausted credit; try again"}], code=4, reason="quota_exhausted")
+ run_case(binary, [{"http_status": 500, "error": "exhausted credit; try again"}], code=4, reason="quota_exhausted")
+ print("PASS quota outranks retryable 429/500 envelopes without another request", flush=True)
+ for status, code, reason in [(401, 77, "authentication_required"), (402, 4, "quota_exhausted"), (403, 77, "authentication_required")]:
+ run_case(binary, [{"http_status": status, "raw_error_body": "plain text account refusal"}], code=code, reason=reason)
+ print("PASS non-JSON 401/402/403 retain terminal classification", flush=True)
+ run_case(binary, [{"text": "partial", "finish": "length"}] * 5, code=2, reason="output_length_exhausted")
+ print("PASS repeated length stops exhaust bounded recovery, never report completion", flush=True)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/src/agent_empty_completion.zig b/src/agent_empty_completion.zig
index 6e7aef6f..41145583 100644
--- a/src/agent_empty_completion.zig
+++ b/src/agent_empty_completion.zig
@@ -15,7 +15,12 @@ const no_local_tools = @import("no_local_tools.zig");
const messages = @import("messages.zig");
/// Retries allowed per turn for consecutive degenerate completions.
-pub const max_consecutive: u8 = 2;
+pub const max_consecutive: u8 = 5;
+
+const retry = @import("agent_empty_retry.zig");
+pub const retryDelayMs = retry.retryDelayMs;
+pub const wait = retry.wait;
+const checkBudget = retry.checkBudget;
/// True when `final_text` is a degenerate completion worth one more ask.
/// `retries` = attempts already spent on this turn. Whitespace-only text is
@@ -132,7 +137,18 @@ test "#1013 without a bounce note the follow-up is the answer" {
/// Handle a degenerate completion inside runTurn. Returns true when the
/// caller should `continue` the loop.
pub fn handle(self: *Agent, final_text: []const u8, hist_len: usize) !bool {
- if (shouldRetry(final_text, self.empty_completion_retries)) {
+ return handleWithWait(self, final_text, hist_len, wait);
+}
+
+fn handleWithWait(self: *Agent, final_text: []const u8, hist_len: usize, comptime sleep: anytype) !bool {
+ if (std.mem.trim(u8, final_text, " \t\r\n").len == 0) {
+ if (Agent.esc_cancel.load(.acquire) or @import("acp_engine.zig").cancel_flag.load(.acquire)) return error.Interrupted;
+ if (!shouldRetry(final_text, self.empty_completion_retries)) {
+ self.last_api_error = "provider returned empty completions after 5 retries";
+ return error.EmptyCompletion;
+ }
+ try checkBudget(self);
+ const delay_ms = @import("retry_jitter.zig").ms(self.io, retryDelayMs(self.empty_completion_retries));
const keep = @min(hist_len, self.messages.items.len);
const reasoned = reasonedWithoutAnswer(self.messages.items[keep..]);
self.empty_completion_retries += 1;
@@ -140,8 +156,11 @@ pub fn handle(self: *Agent, final_text: []const u8, hist_len: usize) !bool {
self.messages.shrinkRetainingCapacity(keep);
if (reasoned) {
try self.messages.append(try messages.userNote(self.arena, self.provider.kind, reasoning_budget_note));
- try self.say("[model reasoned without answering — retrying with a brief-answer note ({d}/{d})]\n", .{ self.empty_completion_retries, max_consecutive });
- } else try self.say("[model returned an empty completion — retrying ({d}/{d})]\n", .{ self.empty_completion_retries, max_consecutive });
+ try self.say("[model reasoned without answering — retrying with a brief-answer note in {d}s ({d}/{d})]\n", .{ delay_ms / 1000, self.empty_completion_retries, max_consecutive });
+ } else try self.say("[model returned an empty completion — retrying in {d}s ({d}/{d})]\n", .{ delay_ms / 1000, self.empty_completion_retries, max_consecutive });
+ if (self.tracer) |tr| tr.note("retry", "empty completion; bounded jittered backoff");
+ try sleep(self, delay_ms);
+ try checkBudget(self); // a sibling may have spent the shared budget while waiting
return true;
}
if (@import("task_intent.zig").current(self) == .informational) return false;
@@ -245,6 +264,7 @@ test {
fn pendingFixture(arena: std.mem.Allocator) Agent {
var self: Agent = undefined;
self.arena = arena;
+ self.io = std.testing.io;
self.sub = false;
self.review_mode = false;
self.text_only = false;
@@ -253,6 +273,7 @@ fn pendingFixture(arena: std.mem.Allocator) Agent {
self.todos = .empty;
self.messages = .init(arena);
self.provider.kind = .openai;
+ self.depth = 0;
self.run_budget = null;
self.tool_calls_this_turn = 3; // unlike the zero-tool guards, tools ran
self.model_calls_this_turn = 4;
@@ -445,7 +466,7 @@ test "exact reply bypasses only fake done while mixed requests and empty replies
self.model_calls_this_turn = 1;
try self.messages.append(try messages.textMessage(self.arena, "user", case[0]));
const before = self.messages.items.len;
- try std.testing.expectEqual(case[2], try handle(&self, case[1], before));
+ try std.testing.expectEqual(case[2], try handleWithWait(&self, case[1], before, testWait));
const empty = std.mem.trim(u8, case[1], " \t\r\n").len == 0;
try std.testing.expectEqual(@as(usize, if (case[2] and !empty) before + 1 else before), self.messages.items.len);
try std.testing.expectEqual(@as(u8, if (empty) 1 else 0), self.empty_completion_retries);
@@ -507,3 +528,46 @@ test "#1582 an informational question does not resume an earlier task's untouche
state = PendingWork.begin(&self);
try std.testing.expect((try state.finish(&self, "Stopping here.")) == null);
}
+
+fn testWait(_: *Agent, ms: u64) !void {
+ try std.testing.expect(ms >= 10_000 and ms <= 150_000);
+}
+
+test "empty completion recovery backs off, keeps reasoning note, fails explicitly and obeys budgets and cancellation" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ var self = pendingFixture(arena.allocator());
+ self.in = null;
+ self.codex_ws = null;
+ self.codex_prev_id = null;
+ self.call_kind = .title;
+ self.empty_completion_retries = 0;
+ const reasoning = try std.json.parseFromSliceLeaky(std.json.Value, self.arena, "[{\"type\":\"reasoning\",\"summary\":[]}]", .{});
+ try self.messages.append(reasoning.array.items[0]);
+ try std.testing.expect(try handleWithWait(&self, "", 0, testWait));
+ try std.testing.expectEqualStrings(reasoning_budget_note, self.messages.items[0].object.get("content").?.string);
+ var total: u64 = 0;
+ for (0..max_consecutive) |i| total += retryDelayMs(@intCast(i));
+ try std.testing.expectEqual(@as(u64, 270_000), total);
+ self.empty_completion_retries = max_consecutive;
+ try std.testing.expectError(error.EmptyCompletion, handleWithWait(&self, " \n", 0, testWait));
+ self.empty_completion_retries = 0;
+ var budget: @import("run_budget.zig").RunBudget = .{ .max_model_calls = 1 };
+ budget.model_calls.store(1, .release);
+ self.run_budget = &budget;
+ try std.testing.expectError(error.RunBudgetExhausted, handleWithWait(&self, "", 0, testWait));
+ try std.testing.expectEqual(@as(u8, 0), self.empty_completion_retries);
+ self.run_budget = null;
+ const old_cap = @import("turn_chrome.zig").max_turn_model_calls;
+ @import("turn_chrome.zig").max_turn_model_calls = self.model_calls_this_turn;
+ defer @import("turn_chrome.zig").max_turn_model_calls = old_cap;
+ try std.testing.expectError(error.RunBudgetExhausted, handleWithWait(&self, "", 0, testWait));
+ const old_cancel = Agent.esc_cancel.swap(true, .acq_rel);
+ defer Agent.esc_cancel.store(old_cancel, .release);
+ try std.testing.expectError(error.Interrupted, wait(&self, 120_000));
+ try std.testing.expectError(error.Interrupted, handleWithWait(&self, "", 0, testWait));
+ Agent.esc_cancel.store(false, .release);
+ const old_acp_cancel = @import("acp_engine.zig").cancel_flag.swap(true, .acq_rel);
+ defer @import("acp_engine.zig").cancel_flag.store(old_acp_cancel, .release);
+ try std.testing.expectError(error.Interrupted, wait(&self, 120_000));
+}
diff --git a/src/agent_empty_retry.zig b/src/agent_empty_retry.zig
new file mode 100644
index 00000000..659b5dd3
--- /dev/null
+++ b/src/agent_empty_retry.zig
@@ -0,0 +1,38 @@
+//! Cancellation-aware empty-reply retry timing and budget admission.
+const Agent = @import("agent.zig").Agent;
+const main_mod = @import("main.zig");
+
+/// Five retries span 4.5–5.6 minutes, rather than hammering an unhealthy route.
+/// Reuse the shared upward-only jitter; each delay is independently randomized.
+pub fn retryDelayMs(retries: u8) u64 {
+ return @min(@as(u64, 10_000) << @intCast(@min(retries, 4)), 120_000);
+}
+
+/// Unlike the legacy short-backoff sleeper, also observe headless/ACP flags
+/// and IO cancellation. Keep terminal Esc handling without touching its owner.
+pub fn wait(self: *Agent, ms: u64) error{Interrupted}!void {
+ const watch = !self.sub and self.in != null and main_mod.use_color and !main_mod.json_mode;
+ const orig = if (watch) Agent.rawNonblockStdin() else null;
+ defer if (orig) |o| Agent.restoreStdin(o);
+ var left = ms;
+ while (true) {
+ if (Agent.esc_cancel.load(.acquire) or @import("acp_engine.zig").cancel_flag.load(.acquire)) return error.Interrupted;
+ if (orig != null and Agent.escPressed(true)) return error.Interrupted;
+ if (left == 0) return;
+ const chunk = @min(left, 100);
+ self.io.sleep(.fromMilliseconds(@intCast(chunk)), .awake) catch return error.Interrupted;
+ left -= chunk;
+ }
+}
+
+pub fn checkBudget(self: *Agent) !void {
+ if (self.run_budget) |b| if (!b.canAfford(if (self.depth > 0) 2 else 1)) {
+ self.last_api_error = "model-call budget exhausted before empty-completion retry";
+ return error.RunBudgetExhausted;
+ };
+ const cap = @import("turn_chrome.zig").max_turn_model_calls;
+ if (cap != 0 and self.model_calls_this_turn >= cap) {
+ self.last_api_error = "model-call limit reached before empty-completion retry";
+ return error.RunBudgetExhausted;
+ }
+}
diff --git a/src/agent_gateway_retry.zig b/src/agent_gateway_retry.zig
index 60d34b3b..2ec414e1 100644
--- a/src/agent_gateway_retry.zig
+++ b/src/agent_gateway_retry.zig
@@ -95,7 +95,7 @@ pub fn afterServerErrorOrParseReject(self: *Agent, etype: []const u8, code: ?[]c
// its diagnostic also mentions capacity or a request-body parse error,
// or a ChatGPT plan code OpenAI says to stop on, such as a spent allowance
// whose message says "try again later" (ADR 0221).
- if (isModelUnavailable(code) or isStructuredOverflow(code) or quota.isPlanStop(code)) return false;
+ if (quota.classify(etype, code, msg) != null or isModelUnavailable(code) or isStructuredOverflow(code) or quota.isPlanStop(code)) return false;
if (try retryTransientServerError(self, etype, code, msg, server_retries)) return true;
if (try retryShortGatewayFlake(self, etype, code, msg, server_retries)) return true;
return retryBodyParseAfterTimeouts(self, msg, state);
@@ -123,7 +123,7 @@ pub fn isShortGatewayFlake(etype: []const u8, code: ?[]const u8, msg: []const u8
// Gateway 110-byte follow-up. etype is often invalid_request_error, which
// would otherwise hard-fail on the "invalid" needle. Auth/quota still die,
// and so does every ChatGPT plan code: its 503s have the transient ladder.
- if (isModelUnavailable(code) or isStructuredOverflow(code) or quota.isPlanCode(code)) return false;
+ if (quota.classify(etype, code, msg) != null or isModelUnavailable(code) or isStructuredOverflow(code) or quota.isPlanCode(code)) return false;
if (isBodyParseRejection(msg)) return true;
const hard = [_][]const u8{ "invalid", "authentication", "unauthorized", "insufficient", "quota", "permission", "tool_choice", "not found" };
for (hard) |n| {
@@ -193,7 +193,7 @@ pub const max_server_retries: usize = 3; // #opencode-parity: bounded retries fo
/// surfaced mid-stream and should be retried, not hard-failed. Billing / quota /
/// invalid-input errors are NOT transient and fall through to a hard fail.
pub fn isTransientServerError(etype: []const u8, code: ?[]const u8, msg: []const u8) bool {
- if (isModelUnavailable(code)) return false;
+ if (quota.classify(etype, code, msg) != null or isModelUnavailable(code) or quota.isPlanStop(code)) return false;
// ChatGPT plan usage or user data temporarily unavailable (503, possibly
// mid-stream): keep the credentials and back off like an overload.
if (quota.isPlanTransient(code)) return true;
@@ -390,6 +390,21 @@ test "serverRetryDelayMs honors try-again/retry-after seconds, ignores 0 and >60
try std.testing.expect(serverRetryDelayMs("try again in 350000 seconds") == null);
}
+test "terminal provider faults outrank every gateway retry ladder" {
+ for ([_][]const u8{ "exhausted credit; try again", "insufficient credits; upstream overloaded", "API key expired; server_error", "Body must be valid JSON; exhausted credit" }) |msg| {
+ try std.testing.expect(!isShortGatewayFlake("api_error", null, msg));
+ try std.testing.expect(!isTransientServerError("server_error", null, msg));
+ }
+ try std.testing.expect(!isShortGatewayFlake("api_error", "402", "Body must be valid JSON"));
+ try std.testing.expect(!isTransientServerError("server_error", "401", "overloaded"));
+ var self: Agent = undefined; // a terminal guard must never access retry IO/state
+ var retries: usize = 0;
+ var state: GatewayRetryState = .{ .transport_timeouts = 3 };
+ try std.testing.expect(!try afterServerErrorOrParseReject(&self, "server_error", "402", "Body must be valid JSON", &retries, &state));
+ try std.testing.expectEqual(@as(usize, 0), retries);
+ try std.testing.expectEqual(@as(usize, 0), state.parse_retries);
+}
+
test "#748: error-only SSE is not a truncated gateway body" {
const err_sse = "event: error\ndata: {\"error\":{\"type\":\"invalid_request_error\",\"message\":\"bad\"}}\n";
try std.testing.expect(sseLooksLikeError(err_sse));
diff --git a/src/agent_length.zig b/src/agent_length.zig
new file mode 100644
index 00000000..07d7e87d
--- /dev/null
+++ b/src/agent_length.zig
@@ -0,0 +1,114 @@
+//! Output limits are a continuation boundary, not successful completion.
+//! The allowance belongs to runTurn's stack: tools, compaction and empty
+//! completions cannot refill it, and the next user turn starts fresh.
+const std = @import("std");
+const Agent = @import("agent.zig").Agent;
+const Kind = @import("provider.zig").Provider.Kind;
+const messages = @import("messages.zig");
+const args = @import("tool_call_args.zig");
+
+pub const max_continuations: u8 = 4;
+pub const note = "Your previous response reached its output limit and is partial. Continue from where it stopped; do not repeat completed work. Write long artifacts incrementally to files in small, complete tool calls instead of a long reply. Re-issue any truncated tool call with complete arguments.";
+pub const exhausted_message = "output-length continuation limit reached; work is partial and has been preserved. Send a new message or resume to continue";
+
+fn str(object: std.json.ObjectMap, key: []const u8) []const u8 {
+ const value = object.get(key) orelse return "";
+ return if (value == .string) value.string else "";
+}
+
+pub fn limited(kind: Kind, root: std.json.ObjectMap) bool {
+ return switch (kind) {
+ .anthropic => std.mem.eql(u8, str(root, "stop_reason"), "max_tokens"),
+ .openai => blk: {
+ const choices = root.get("choices") orelse break :blk false;
+ if (choices != .array or choices.array.items.len == 0 or choices.array.items[0] != .object) break :blk false;
+ break :blk std.mem.eql(u8, str(choices.array.items[0].object, "finish_reason"), "length");
+ },
+ .responses => blk: {
+ // Do not retry content filters or an interrupted stream merely
+ // because they too are marked incomplete.
+ const details = root.get("incomplete_details") orelse break :blk false;
+ break :blk details == .object and std.mem.eql(u8, str(details.object, "reason"), "max_output_tokens");
+ },
+ .interactions => false,
+ };
+}
+
+/// Raw JSON replies do not pass through the stream assembler's cut markers.
+/// An empty argument string is only a valid empty call on a completed reply.
+/// A Responses item explicitly marked incomplete is never executable.
+pub fn callCut(gpa: std.mem.Allocator, response_limited: bool, object: std.json.ObjectMap, raw: []const u8) bool {
+ return std.mem.eql(u8, str(object, "status"), "incomplete") or
+ (response_limited and !args.isObjectString(gpa, raw));
+}
+
+/// Preserve terminal metadata when Responses SSE is reduced to output items.
+/// Called for each terminal event, then copied onto the assembled response.
+pub const ResponsesTerminal = struct {
+ details: ?std.json.Value = null,
+
+ pub fn record(state: *ResponsesTerminal, allocator: std.mem.Allocator, response: std.json.ObjectMap) !void {
+ state.details = if (response.get("incomplete_details")) |d| try @import("util.zig").dupeJsonValue(allocator, d) else null;
+ }
+
+ pub fn apply(state: ResponsesTerminal, allocator: std.mem.Allocator, response: *std.json.ObjectMap) !void {
+ if (state.details) |d| try response.put(allocator, "incomplete_details", d);
+ }
+};
+
+fn reasoningOnly(kind: Kind, root: std.json.ObjectMap) bool {
+ const empty = @import("agent_empty_completion.zig");
+ if (kind == .responses) {
+ const output = root.get("output") orelse return false;
+ return output == .array and empty.reasonedWithoutAnswer(output.array.items);
+ }
+ if (kind == .anthropic) return empty.reasonedWithoutAnswer(&.{.{ .object = root }});
+ if (kind == .openai) {
+ const choices = root.get("choices") orelse return false;
+ if (choices != .array or choices.array.items.len == 0 or choices.array.items[0] != .object) return false;
+ const message = choices.array.items[0].object.get("message") orelse return false;
+ return empty.reasonedWithoutAnswer(&.{message});
+ }
+ return false;
+}
+
+pub const State = struct {
+ continuations: u8 = 0,
+
+ pub fn step(state: *State, self: *Agent, root: std.json.ObjectMap) !?[]const u8 {
+ const done = try @import("agent_steps.zig").stepForWire(self, root);
+ return state.afterStep(self, root, done);
+ }
+
+ pub fn afterStep(state: *State, self: *Agent, root: std.json.ObjectMap, done: ?[]const u8) !?[]const u8 {
+ if (!limited(self.provider.kind, root) or self.completed != null) return done;
+ if (done) |text| {
+ if (@import("tool_call_repair.zig").isLoopStop(text) or std.mem.eql(u8, text, @import("agent_eval_control.zig").verifier_hard_stop)) return done;
+ }
+ if (Agent.esc_cancel.load(.acquire) or @import("acp_engine.zig").cancel_flag.load(.acquire)) return error.Interrupted;
+ if (self.run_budget) |budget| {
+ if (budget.tool_exhausted.load(.acquire)) return error.ToolBudgetExhausted;
+ // A child must retain the root's landing reservation too.
+ if (!budget.canAfford(if (self.depth > 0) 2 else 1)) return error.RunBudgetExhausted;
+ }
+ if (state.continuations >= max_continuations) {
+ try self.sayApiError("{s}", .{exhausted_message});
+ return error.OutputLengthExceeded;
+ }
+ var body: []const u8 = note;
+ // Never route a reasoning-only length stop through empty-completion
+ // rewind: preserve its history, but break the reasoning-budget loop.
+ if (done) |text| if (std.mem.trim(u8, text, " \t\r\n").len == 0 and reasoningOnly(self.provider.kind, root)) {
+ body = try std.fmt.allocPrint(self.arena, "{s} {s}", .{ note, @import("agent_empty_completion.zig").reasoning_budget_note });
+ };
+ try self.messages.append(try messages.userNote(self.arena, self.provider.kind, body));
+ state.continuations += 1;
+ try self.say("[output limit — continuing ({d}/{d})]\n", .{ state.continuations, max_continuations });
+ if (self.tracer) |tr| tr.note("length_continuation", "partial output retained; incremental file-writing continuation granted");
+ return null;
+ }
+};
+
+test {
+ _ = @import("agent_length_tests.zig");
+}
diff --git a/src/agent_length_tests.zig b/src/agent_length_tests.zig
new file mode 100644
index 00000000..ff89097d
--- /dev/null
+++ b/src/agent_length_tests.zig
@@ -0,0 +1,196 @@
+//! Offline regression coverage for shared REPL/ACP output-limit recovery.
+const std = @import("std");
+const Agent = @import("agent.zig").Agent;
+const Kind = @import("provider.zig").Provider.Kind;
+const length = @import("agent_length.zig");
+const messages = @import("messages.zig");
+
+fn parse(allocator: std.mem.Allocator, raw: []const u8) !std.json.ObjectMap {
+ return (try std.json.parseFromSliceLeaky(std.json.Value, allocator, raw, .{ .allocate = .alloc_always })).object;
+}
+
+fn fixture(allocator: std.mem.Allocator, writer: *std.Io.Writer, kind: Kind) Agent {
+ return .{
+ .gpa = std.testing.allocator,
+ .arena = allocator,
+ .io = undefined,
+ .client = undefined,
+ .provider = .{ .id = "test", .kind = kind, .auth = .bearer, .url = "", .api_key = "", .model = "test", .context = 100_000 },
+ .messages = .init(allocator),
+ .sub = false,
+ .label = "test",
+ .out = writer,
+ };
+}
+
+const chat_partial = "{\"choices\":[{\"finish_reason\":\"length\",\"message\":{\"role\":\"assistant\",\"content\":\"partial document\"}}]}";
+const chat_done = "{\"choices\":[{\"finish_reason\":\"stop\",\"message\":{\"role\":\"assistant\",\"content\":\"saved the document\"}}]}";
+
+test "length continuation preserves chat partial history and marks its internal file-writing note" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ var buffer: [4096]u8 = undefined;
+ var writer = std.Io.Writer.fixed(&buffer);
+ var agent = fixture(arena.allocator(), &writer, .openai);
+ var state: length.State = .{};
+ try agent.messages.append(try messages.textMessage(agent.arena, "user", "Write the document"));
+ try std.testing.expect((try state.step(&agent, try parse(agent.arena, chat_partial))) == null);
+ try std.testing.expectEqual(@as(u8, 1), state.continuations);
+ try std.testing.expectEqual(@as(usize, 3), agent.messages.items.len);
+ try std.testing.expectEqualStrings("partial document", agent.messages.items[1].object.get("content").?.string);
+ try std.testing.expect(@import("session_wake.zig").isNotice(agent.messages.items[2]));
+ const serialized = try std.json.Stringify.valueAlloc(agent.arena, agent.messages.items[2], .{});
+ try std.testing.expect(std.mem.indexOf(u8, serialized, "incrementally to files") != null);
+ try std.testing.expectEqualStrings("Write the document", messages.latestUserText(agent.messages.items));
+ try std.testing.expectEqualStrings("saved the document", (try state.step(&agent, try parse(agent.arena, chat_done))).?);
+ try std.testing.expectEqual(@as(u8, 1), state.continuations);
+ try std.testing.expect(std.mem.indexOf(u8, writer.buffered(), "[stopped: length]") == null);
+}
+
+test "length continuation handles Anthropic max_tokens and Responses max_output_tokens, not refusals" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ var buffer: [4096]u8 = undefined;
+ var writer = std.Io.Writer.fixed(&buffer);
+ const cases = [_]struct { kind: Kind, raw: []const u8 }{
+ .{ .kind = .anthropic, .raw = "{\"stop_reason\":\"max_tokens\",\"content\":[{\"type\":\"text\",\"text\":\"partial document\"}]}" },
+ .{ .kind = .responses, .raw = "{\"status\":\"incomplete\",\"incomplete_details\":{\"reason\":\"max_output_tokens\"},\"output\":[{\"type\":\"message\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"partial document\"}]}]}" },
+ };
+ for (cases) |case| {
+ var agent = fixture(arena.allocator(), &writer, case.kind);
+ var state: length.State = .{};
+ try std.testing.expect((try state.step(&agent, try parse(agent.arena, case.raw))) == null);
+ try std.testing.expectEqual(@as(usize, 2), agent.messages.items.len);
+ try std.testing.expectEqual(@as(u8, 1), state.continuations);
+ }
+ try std.testing.expect(!length.limited(.responses, try parse(arena.allocator(), "{\"incomplete\":true,\"incomplete_details\":{\"reason\":\"content_filter\"}}")));
+ try std.testing.expect(!length.limited(.responses, try parse(arena.allocator(), "{\"incomplete\":true}")));
+ try std.testing.expect(!length.limited(.anthropic, try parse(arena.allocator(), "{\"stop_reason\":\"refusal\"}")));
+ try std.testing.expect(!length.limited(.openai, try parse(arena.allocator(), "{\"choices\":[{\"finish_reason\":\"content_filter\"}]}")));
+}
+
+test "length continuation allowance stays bounded across tool progress and resets only on a new turn" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ var buffer: [4096]u8 = undefined;
+ var writer = std.Io.Writer.fixed(&buffer);
+ var agent = fixture(arena.allocator(), &writer, .openai);
+ const root = try parse(agent.arena, chat_partial);
+ var state: length.State = .{};
+ for (0..length.max_continuations) |_| {
+ // null is the step result after a tool batch. Progress cannot refill
+ // the allowance and these length stops must be counted too.
+ try std.testing.expect((try state.afterStep(&agent, root, null)) == null);
+ agent.tool_calls_this_turn += 1;
+ _ = try state.afterStep(&agent, try parse(agent.arena, chat_done), null);
+ }
+ const count = agent.messages.items.len;
+ try std.testing.expectError(error.OutputLengthExceeded, state.afterStep(&agent, root, "partial"));
+ try std.testing.expectEqual(count, agent.messages.items.len);
+ try std.testing.expectEqualStrings(length.exhausted_message, agent.last_api_error.?);
+ var next_turn: length.State = .{};
+ try std.testing.expect((try next_turn.afterStep(&agent, root, "new partial")) == null);
+ try std.testing.expectEqual(@as(u8, 1), next_turn.continuations);
+}
+
+test "length continuation preserves reasoning-only output instead of empty-completion rewind" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ var buffer: [4096]u8 = undefined;
+ var writer = std.Io.Writer.fixed(&buffer);
+ var agent = fixture(arena.allocator(), &writer, .openai);
+ var state: length.State = .{};
+ const root = try parse(agent.arena, "{\"choices\":[{\"finish_reason\":\"length\",\"message\":{\"role\":\"assistant\",\"content\":null,\"reasoning_content\":\"unfinished thought\"}}]}");
+ try std.testing.expect((try state.step(&agent, root)) == null);
+ try std.testing.expectEqual(@as(usize, 2), agent.messages.items.len);
+ try std.testing.expectEqualStrings("unfinished thought", agent.messages.items[0].object.get("reasoning_content").?.string);
+ const serialized = try std.json.Stringify.valueAlloc(agent.arena, agent.messages.items[1], .{});
+ try std.testing.expect(std.mem.indexOf(u8, serialized, "Think briefly") != null);
+ try std.testing.expectEqual(@as(u8, 0), agent.empty_completion_retries);
+}
+
+test "length continuation respects run budgets and both engine cancellation flags without granting another call" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ var buffer: [4096]u8 = undefined;
+ var writer = std.Io.Writer.fixed(&buffer);
+ var agent = fixture(arena.allocator(), &writer, .openai);
+ const root = try parse(agent.arena, chat_partial);
+ var state: length.State = .{};
+ const acp = @import("acp_engine.zig");
+ const previous_esc = Agent.esc_cancel.swap(true, .acq_rel);
+ defer Agent.esc_cancel.store(previous_esc, .release);
+ try std.testing.expectError(error.Interrupted, state.afterStep(&agent, root, "partial"));
+ Agent.esc_cancel.store(false, .release);
+ const previous_acp = acp.cancel_flag.swap(true, .acq_rel);
+ defer acp.cancel_flag.store(previous_acp, .release);
+ try std.testing.expectError(error.Interrupted, state.afterStep(&agent, root, "partial"));
+ acp.cancel_flag.store(false, .release);
+ var budget: @import("run_budget.zig").RunBudget = .{ .max_model_calls = 1 };
+ budget.model_calls.store(1, .release);
+ agent.run_budget = &budget;
+ try std.testing.expectError(error.RunBudgetExhausted, state.afterStep(&agent, root, "partial"));
+ budget.model_calls.store(0, .release);
+ agent.depth = 1;
+ try std.testing.expectError(error.RunBudgetExhausted, state.afterStep(&agent, root, "partial"));
+ agent.depth = 0;
+ budget.tool_exhausted.store(true, .release);
+ try std.testing.expectError(error.ToolBudgetExhausted, state.afterStep(&agent, root, "partial"));
+ try std.testing.expectEqual(@as(usize, 0), agent.messages.items.len);
+ try std.testing.expectEqual(@as(u8, 0), state.continuations);
+}
+
+test "length continuation cut safeguards reject empty or truncated raw tool args but retain completed object calls" {
+ const gpa = std.testing.allocator;
+ try std.testing.expect(length.callCut(gpa, true, .empty, ""));
+ try std.testing.expect(length.callCut(gpa, true, .empty, "{\"path\":\"unfinished"));
+ try std.testing.expect(length.callCut(gpa, true, .empty, "[]"));
+ try std.testing.expect(!length.callCut(gpa, true, .empty, "{}"));
+ try std.testing.expect(!length.callCut(gpa, true, .empty, "{\"path\":\"complete\"}"));
+ try std.testing.expect(!length.callCut(gpa, false, .empty, ""));
+ var arena = std.heap.ArenaAllocator.init(gpa);
+ defer arena.deinit();
+ const incomplete = try parse(arena.allocator(), "{\"status\":\"incomplete\"}");
+ try std.testing.expect(length.callCut(gpa, false, incomplete, "{}"));
+}
+
+test "length continuation never dispatches truncated tool calls and leaves replayable error pairs on every wire" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ var buffer: [4096]u8 = undefined;
+ var writer = std.Io.Writer.fixed(&buffer);
+ const cases = [_]struct { kind: Kind, raw: []const u8 }{
+ .{ .kind = .openai, .raw = "{\"choices\":[{\"finish_reason\":\"length\",\"message\":{\"role\":\"assistant\",\"content\":null,\"tool_calls\":[{\"id\":\"c\",\"type\":\"function\",\"function\":{\"name\":\"read_file\",\"arguments\":\"\"}}]}}]}" },
+ .{ .kind = .responses, .raw = "{\"incomplete_details\":{\"reason\":\"max_output_tokens\"},\"output\":[{\"type\":\"function_call\",\"call_id\":\"c\",\"name\":\"read_file\",\"arguments\":\"\"}]}" },
+ .{ .kind = .anthropic, .raw = "{\"stop_reason\":\"max_tokens\",\"content\":[{\"type\":\"tool_use\",\"id\":\"c\",\"name\":\"read_file\"}]}" },
+ };
+ for (cases) |case| {
+ var agent = fixture(arena.allocator(), &writer, case.kind);
+ agent.sub = true;
+ var state: length.State = .{};
+ try std.testing.expect((try state.step(&agent, try parse(agent.arena, case.raw))) == null);
+ try std.testing.expectEqual(@as(usize, 3), agent.messages.items.len);
+ const result = try std.json.Stringify.valueAlloc(agent.arena, agent.messages.items[1], .{});
+ try std.testing.expect(std.mem.indexOf(u8, result, "truncated: the response ended") != null);
+ const history = try std.json.Stringify.valueAlloc(agent.arena, agent.messages.items[0], .{});
+ try std.testing.expect(std.mem.indexOf(u8, history, "graff_invalid_input") == null);
+ try std.testing.expectEqual(@as(u8, 1), state.continuations);
+ }
+}
+
+test "length continuation Responses terminal metadata survives scratch teardown and resets on a completed terminal" {
+ var result = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer result.deinit();
+ var scratch = std.heap.ArenaAllocator.init(std.testing.allocator);
+ var terminal: length.ResponsesTerminal = .{};
+ const response = try parse(scratch.allocator(), "{\"incomplete_details\":{\"reason\":\"max_output_tokens\"}}");
+ try terminal.record(result.allocator(), response);
+ scratch.deinit();
+ var assembled: std.json.ObjectMap = .empty;
+ try terminal.apply(result.allocator(), &assembled);
+ try std.testing.expect(length.limited(.responses, assembled));
+ try terminal.record(result.allocator(), .empty);
+ var completed: std.json.ObjectMap = .empty;
+ try terminal.apply(result.allocator(), &completed);
+ try std.testing.expect(!length.limited(.responses, completed));
+}
diff --git a/src/agent_request.zig b/src/agent_request.zig
index 2beda2e0..c557d625 100644
--- a/src/agent_request.zig
+++ b/src/agent_request.zig
@@ -28,7 +28,7 @@ const policy = @import("agent_request_policy.zig");
const overflow = @import("agent_overflow.zig");
const errorCode = policy.errorCode;
-const isQuotaExceeded = policy.isQuotaExceeded;
+const quota = @import("agent_request_quota.zig");
const recoverContextOverflow = overflow.recoverContextOverflow;
// #414: an HTTP 200 that overflowed silently — the provider accepted an
// over-window input and answered with nothing (z.ai), or truncated our input
@@ -141,6 +141,7 @@ pub fn request(self: *Agent, tools_in: ?[]const u8) !std.json.ObjectMap {
if (self.run_budget) |b| if (budget_permit) |p| {
if (b.max_model_calls != 0 and p.call_number == b.max_model_calls and tools != null) {
tools = null;
+ b.model_landed.store(true, .release);
try self.messages.append(try wire_messages.userNote(self.arena, self.provider.kind, landing_note));
if (self.tracer) |tr| tr.note("budget", "final call: tools withheld so the run lands its answer (#390)");
}
@@ -270,6 +271,10 @@ 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 (quota.transportCode(err)) |code| {
+ if (try quota.handle(self, "", code, "", &auth_refreshed)) continue;
+ return err;
+ }
// #56: a mid-stream idle stall or a connection drop (the
// provider closed/reset before its terminal event) — NOT a
// user Esc, which is handled above. Usually transient, so
@@ -336,24 +341,10 @@ pub fn request(self: *Agent, tools_in: ?[]const u8) !std.json.ObjectMap {
const throttled = err == error.RateLimited or err == error.ServerError;
const max_attempts = retry_limit orelse RetryPlan.maxAttempts(throttled);
retry_limit = max_attempts;
- // #opencode-parity: a 429 that's a billing/quota cap (not
- // transient throttling) won't clear by retrying — fail fast so
- // cross-provider /fallback can take over, instead of burning all
- // 5 attempts (~23s). Detected from the captured 429 body.
- if (err == error.RateLimited and main_mod.g_5xx_body_len > 0 and
- isQuotaExceeded(main_mod.g_5xx_body_buf[0..main_mod.g_5xx_body_len]))
- {
- // #471: a flat-rate plan that has run out is exactly
- // when the metered key it outranked earns its keep.
- // Hand over and retry rather than failing a session
- // with a working credential sitting unused. One-way
- // and announced — see credential_failover.
- if (policy.handOffExhaustedPlan(self)) continue;
- const plan_hint = if (std.mem.eql(u8, self.provider.id, "chatgpt-new")) " \xe2\x80\x94 " ++ @import("oauth_chatgpt.zig").usage_hint else "";
- self.last_api_error = std.fmt.allocPrint(self.arena, "rate limited (429): {s}{s}", .{ policy.quota_cap_marker, plan_hint }) catch "rate limited (429): quota exceeded";
- if (telemetry.g_telem) |t| t.errorEvent("quota", self.last_api_error orelse "quota exceeded");
- if (self.tracer) |tr| tr.api(self.label, self.sub, self.provider.model, 0, body.len, 0, 0, 0, true);
- return error.ApiError;
+ // A proxy may wrap a billing/auth refusal in 429 OR 5xx.
+ // Terminal account faults outrank the generic retry status.
+ if (throttled and main_mod.g_5xx_body_len > 0) {
+ if (try quota.handle(self, "", null, main_mod.g_5xx_body_buf[0..main_mod.g_5xx_body_len], &auth_refreshed)) continue;
}
if (err == error.TlsRequestConstructionFailed or err == error.TlsRequestConstructionCaWarmFailed) if (self.tracer) |tr| tr.note(
"tls_request_construction",
@@ -445,6 +436,7 @@ pub fn request(self: *Agent, tools_in: ?[]const u8) !std.json.ObjectMap {
return error.ApiError;
}
if (ws_error_frame) if (self.tracer) |tr| tr.note("ws_api_error", diagnostic);
+ if (try quota.handle(self, "", failure.code, msg, &auth_refreshed)) continue :rebuild;
if (codex_chain.shouldReanchorRequest(body, msg, failure.code)) {
self.closeCodexWs();
if (self.tracer) |tr| tr.note("ws", "server dropped previous_response_id — re-anchoring with full input");
@@ -498,7 +490,8 @@ pub fn request(self: *Agent, tools_in: ?[]const u8) !std.json.ObjectMap {
const eo = if (root.get("error")) |ev| (if (ev == .object) ev.object else null) else null;
const etype = if (eo) |e| (if (e.get("type")) |tv| (if (tv == .string) tv.string else "error") else "error") else "error";
const emsg = if (eo) |e| (if (e.get("message")) |mv| (if (mv == .string) mv.string else "") else "") else "";
- const ecode = if (eo) |e| (if (e.get("code")) |cv| (if (cv == .string) cv.string else null) else null) else null;
+ const ecode = errorCode(root);
+ if (try quota.handle(self, etype, ecode, emsg, &auth_refreshed)) continue;
if (recoverContextOverflow(self, emsg, ecode, &context_retried)) continue; // #193/#203: streamed error event overflow (by code or phrasing) → trim + retry
if (policy.retryWithout(self, emsg, &force, &stream_usage)) continue; // ADR 0219: Anthropic errors take the ladder too
if (try policy.afterServerErrorOrParseReject(self, etype, ecode, emsg, &server_retries, &gw_retry)) continue;
@@ -548,7 +541,8 @@ pub fn request(self: *Agent, tools_in: ?[]const u8) !std.json.ObjectMap {
const eo = if (root.get("error")) |ev| (if (ev == .object) ev.object else null) else null;
const etype = if (eo) |e| (if (e.get("type")) |tv| (if (tv == .string) tv.string else "error") else "error") else "error";
const emsg = if (eo) |e| (if (e.get("message")) |mv| (if (mv == .string) mv.string else "") else "") else "";
- const ecode = if (eo) |e| (if (e.get("code")) |cv| (if (cv == .string) cv.string else null) else null) else null;
+ const ecode = errorCode(root);
+ if (try quota.handle(self, etype, ecode, emsg, &auth_refreshed)) continue;
if (recoverContextOverflow(self, emsg, ecode, &context_retried)) continue; // #193/#203: {"type":"error"} overflow (by code or phrasing) → trim + retry
if (policy.retryWithout(self, emsg, &force, &stream_usage)) continue; // ADR 0219: Anthropic errors take the ladder too
if (try policy.afterServerErrorOrParseReject(self, etype, ecode, emsg, &server_retries, &gw_retry)) continue;
@@ -557,6 +551,7 @@ pub fn request(self: *Agent, tools_in: ?[]const u8) !std.json.ObjectMap {
return error.ApiError;
};
if (apiErrorMessage(root)) |msg| {
+ if (try quota.handle(self, "", errorCode(root), msg, &auth_refreshed)) continue;
if (policy.retryWithout(self, msg, &force, &stream_usage)) continue;
// #148: a stale login token 401s here with the provider's "API Key
// invalid/expired"; adopt a newer on-disk token or force a refresh
diff --git a/src/agent_request_policy.zig b/src/agent_request_policy.zig
index 88424c3c..97a68691 100644
--- a/src/agent_request_policy.zig
+++ b/src/agent_request_policy.zig
@@ -206,7 +206,7 @@ pub fn retryWithout(self: *Agent, msg: []const u8, force: *bool, stream_usage: *
/// have helped either, so it does not earn a retry. Neither does a credential
/// belonging to a DIFFERENT ChatGPT account (refreshOAuthKey returns null).
pub fn retryAfterAuthRefresh(self: *Agent, msg: []const u8, refreshed: *bool) bool {
- if (refreshed.* or self.provider.source != .login or !isAuthError(msg)) return false;
+ if (refreshed.* or self.provider.source != .login or quota.isQuotaExceeded(msg) or !isAuthError(msg)) return false;
refreshed.* = true;
// ADR 0253: when the refresh cannot help, an interactive ChatGPT session signs in again.
const fresh = oauth.refreshOAuthKey(self.io, self.gpa, self.scratchAlloc(), self.home, self.provider.id, true, self.provider.api_key, self.provider.account) orelse return @import("chatgpt_reauth.zig").renewed(self);
@@ -384,11 +384,13 @@ pub fn errorCode(root: std.json.ObjectMap) ?[]const u8 {
if (ev == .object) {
if (ev.object.get("code")) |cv| {
if (cv == .string) return cv.string;
+ if (quota.numericStatusCode(cv)) |c| return c;
}
}
}
if (root.get("code")) |cv| {
if (cv == .string) return cv.string;
+ if (quota.numericStatusCode(cv)) |c| return c;
}
// The ChatGPT plan route's 401: {"detail":{"error_code":"invalid_token"}}.
if (root.get("detail")) |dv| {
diff --git a/src/agent_request_quota.zig b/src/agent_request_quota.zig
index 53805814..8003417d 100644
--- a/src/agent_request_quota.zig
+++ b/src/agent_request_quota.zig
@@ -20,11 +20,105 @@ pub const quota_cap_marker = "quota/billing cap";
pub fn isQuotaExceeded(body: []const u8) bool {
// ChatGPT plan usage limits (ADR 0221): stop, never retry into them.
- return util.indexOfIgnoreCase(body, plan_limit_code) != null or
- util.indexOfIgnoreCase(body, "insufficient_quota") != null or
- util.indexOfIgnoreCase(body, "insufficient quota") != null or
- util.indexOfIgnoreCase(body, "exceeded your current quota") != null or
- util.indexOfIgnoreCase(body, "quota exceeded") != null;
+ const needles = [_][]const u8{
+ plan_limit_code, "insufficient_quota", "insufficient quota",
+ "exceeded your current quota", "quota exceeded", quota_cap_marker,
+ "exhausted credit", "credits exhausted", "credit exhausted",
+ "insufficient credit", "not enough credit", "no credits",
+ "out of credits", "credit balance", "requires more credits",
+ "payment required", "payment_required", "billing limit",
+ "billing_hard_limit_reached", "billing hard limit", "insufficient_credits",
+ "credits_exhausted", "credit_limit_exceeded", "insufficient_funds",
+ "http 402", "exhausted_credit", "credit_balance_too_low",
+ "subscription_sharing_v2_usage_limit_exceeded",
+ };
+ for (needles) |needle| if (util.indexOfIgnoreCase(body, needle) != null) return true;
+ return false;
+}
+
+/// Terminal faults take precedence over an envelope's generic server-error
+/// type or "try again" wording. Keep these distinct for headless exit policy.
+pub const Fault = enum { quota, authentication, access_denied };
+
+pub fn classify(etype: []const u8, code: ?[]const u8, msg: []const u8) ?Fault {
+ const c = code orelse "";
+ if (std.mem.eql(u8, c, "402") or isQuotaExceeded(c) or isQuotaExceeded(etype) or isQuotaExceeded(msg)) return .quota;
+ if (std.mem.eql(u8, c, "401") or isAuthenticationFailure(c) or isAuthenticationFailure(etype) or isAuthenticationFailure(msg)) return .authentication;
+ if (std.mem.eql(u8, c, "403")) return .access_denied;
+ for ([_][]const u8{ "permission_denied", "permission_error", "permission denied", "access_denied", "access denied", "forbidden" }) |needle| {
+ if (util.indexOfIgnoreCase(c, needle) != null or util.indexOfIgnoreCase(etype, needle) != null or util.indexOfIgnoreCase(msg, needle) != null) return .access_denied;
+ }
+ return null;
+}
+
+fn isAuthenticationFailure(text: []const u8) bool {
+ // "expired" alone may describe an upstream request, not a credential.
+ for ([_][]const u8{
+ "authentication", "unauthorized", "invalid_api_key", "invalid_token",
+ "invalid api key", "invalid token", "incorrect api key", "missing api key",
+ "api key is invalid", "api key appears to be invalid", "expired api key", "api key expired",
+ "api key has expired", "token is expired", "token has expired", "token expired",
+ "expired token", "subscription_sharing_invalid_user", "subscription_sharing_v2_invalid_user",
+ }) |needle| if (util.indexOfIgnoreCase(text, needle) != null) return true;
+ return false;
+}
+
+/// Some OpenAI-compatible envelopes put the HTTP status in error.code as a
+/// number. Preserve only known terminal statuses; never coerce arbitrary ids.
+pub fn numericStatusCode(v: std.json.Value) ?[]const u8 {
+ if (v != .integer) return null;
+ return switch (v.integer) {
+ 401 => "401",
+ 402 => "402",
+ 403 => "403",
+ else => null,
+ };
+}
+
+/// Transport adapters can preserve a terminal HTTP status without copying an
+/// untrusted or non-JSON response body into diagnostics or the retry ladder.
+pub fn httpError(status: u16) ?anyerror {
+ return switch (status) {
+ 401 => error.ProviderAuthenticationFailed,
+ 402 => error.ProviderQuotaExceeded,
+ 403 => error.ProviderAccessDenied,
+ else => null,
+ };
+}
+
+pub fn transportCode(err: anyerror) ?[]const u8 {
+ return switch (err) {
+ error.ProviderQuotaExceeded => "402",
+ error.ProviderAuthenticationFailed => "401",
+ error.ProviderAccessDenied => "403",
+ else => null,
+ };
+}
+
+/// The existing one-shot login refresh and consented plan handoff remain the
+/// only exceptions. Never send a quota fault through an auth refresh ladder.
+pub fn handle(self: *@import("agent.zig").Agent, etype: []const u8, code: ?[]const u8, msg: []const u8, refreshed: *bool) !bool {
+ const fault = classify(etype, code, msg) orelse return false;
+ const policy = @import("agent_request_policy.zig");
+ if (fault == .quota and policy.handOffExhaustedPlan(self)) {
+ self.closeCodexWs(); // an existing socket still carries the spent credential
+ return true;
+ }
+ if (fault == .authentication and policy.retryAfterAuthRefresh(self, if (policy.isAuthError(msg)) msg else "authentication_error", refreshed)) {
+ self.closeCodexWs();
+ return true;
+ }
+ self.last_api_error = switch (fault) {
+ .quota => "provider quota/billing cap: credit or allowance exhausted; retry requires account action",
+ .authentication => "provider authentication failed: sign in again or check the API key",
+ .access_denied => "provider access denied: check account permissions or route eligibility",
+ };
+ if (self.tracer) |tr| tr.note("provider_terminal", self.last_api_error.?);
+ return switch (fault) {
+ .quota => error.ProviderQuotaExceeded,
+ .authentication => error.ProviderAuthenticationFailed,
+ .access_denied => error.ProviderAccessDenied,
+ };
}
// ChatGPT plan errors, as OpenAI's errors-and-recovery page classifies them
@@ -99,3 +193,60 @@ test "ChatGPT plan codes follow OpenAI's recovery table" {
}) |c| try std.testing.expect(isPlanStop(c));
try std.testing.expect(!isPlanCode("rate_limit_exceeded") and !isPlanCode(null) and !isPlanStop(null));
}
+
+test "terminal provider faults: credit variants outrank transient wording and auth hints" {
+ for ([_][]const u8{
+ "exhausted credit", "Exhausted Credits", "credits exhausted", "credit exhausted",
+ "insufficient credits", "insufficient credit", "payment required", "payment_required",
+ "This request requires more credits", "credit balance too low", "billing_hard_limit_reached", "insufficient_credits",
+ "credits_exhausted", "credit_limit_exceeded", "insufficient_funds", "HTTP 402",
+ "The API key has exhausted credit; server_error, try again later", "exhausted_credits", "credit_balance_too_low", "subscription_sharing_v2_usage_limit_exceeded",
+ }) |msg| {
+ try std.testing.expect(isQuotaExceeded(msg));
+ try std.testing.expectEqual(Fault.quota, classify("server_error", null, msg).?);
+ }
+ try std.testing.expectEqual(Fault.quota, classify("server_error", "402", "temporarily unavailable").?);
+ try std.testing.expectEqual(Fault.authentication, classify("server_error", "401", "try again later").?);
+ try std.testing.expectEqual(Fault.authentication, classify("authentication_error", null, "upstream overloaded").?);
+ try std.testing.expectEqual(Fault.access_denied, classify("permission_error", "403", "upstream overloaded").?);
+ try std.testing.expect(classify("server_error", "rate_limit_exceeded", "try again later") == null);
+ try std.testing.expect(classify("", null, "too many concurrent requests") == null);
+ try std.testing.expect(classify("server_error", null, "upstream request expired; try again") == null);
+ try std.testing.expect(classify("", "subscription_sharing_usage_unavailable", "temporarily unavailable") == null);
+}
+
+test "terminal provider faults: numeric HTTP status codes survive envelope parsing" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ for ([_][]const u8{
+ "{\"error\":{\"code\":402,\"message\":\"try again\"}}",
+ "{\"code\":402,\"error\":\"try again\"}",
+ }) |raw| {
+ const root = try std.json.parseFromSliceLeaky(std.json.Value, arena.allocator(), raw, .{});
+ try std.testing.expectEqualStrings("402", @import("agent_request_policy.zig").errorCode(root.object).?);
+ }
+ try std.testing.expectEqualStrings("401", numericStatusCode(.{ .integer = 401 }).?);
+ try std.testing.expectEqualStrings("403", numericStatusCode(.{ .integer = 403 }).?);
+ try std.testing.expect(numericStatusCode(.{ .integer = 429 }) == null);
+ try std.testing.expectEqualStrings("402", transportCode(error.ProviderQuotaExceeded).?);
+ try std.testing.expectEqualStrings("401", transportCode(error.ProviderAuthenticationFailed).?);
+ try std.testing.expectEqualStrings("403", transportCode(error.ProviderAccessDenied).?);
+ try std.testing.expect(transportCode(error.Timeout) == null);
+}
+
+test "terminal provider faults: hard caps and env auth stop without a refresh or retry" {
+ var self: @import("agent.zig").Agent = undefined;
+ self.provider = .{ .id = "codegraff", .kind = .openai, .auth = .bearer, .url = "", .api_key = "", .model = "test", .context = 1000, .source = .environment };
+ self.tracer = null;
+ var refreshed = false;
+ try std.testing.expectError(error.ProviderQuotaExceeded, handle(&self, "server_error", null, "API key: exhausted credit; try again", &refreshed));
+ try std.testing.expect(!refreshed);
+ try std.testing.expect(isQuotaExceeded(self.last_api_error.?));
+ try std.testing.expectError(error.ProviderAuthenticationFailed, handle(&self, "authentication_error", null, "overloaded", &refreshed));
+ try std.testing.expect(!refreshed);
+ try std.testing.expectError(error.ProviderAccessDenied, handle(&self, "permission_error", "403", "", &refreshed));
+ try std.testing.expect(!try handle(&self, "server_error", null, "overloaded", &refreshed));
+ self.provider.source = .login;
+ try std.testing.expectError(error.ProviderQuotaExceeded, handle(&self, "", null, "API key: exhausted credit", &refreshed));
+ try std.testing.expect(!refreshed); // even a login credential must not refresh for a billing cap
+}
diff --git a/src/agent_responses.zig b/src/agent_responses.zig
index 72f0a9ff..0237604a 100644
--- a/src/agent_responses.zig
+++ b/src/agent_responses.zig
@@ -44,6 +44,7 @@ pub fn parseResponses(self: *Agent, body: []const u8) !ResponsesResult {
var resp_id: ?[]const u8 = null; // response.id, for previous_response_id delta continuation (#codex-ws)
var saw_completed = false;
var saw_incomplete = false;
+ var terminal: @import("agent_length.zig").ResponsesTerminal = .{};
var err_msg: ?[]const u8 = null;
var err_code: ?[]const u8 = null;
var err_rid: ?[]const u8 = null;
@@ -63,6 +64,7 @@ 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) {
+ try terminal.record(result_arena, r.object);
if (r.object.get("usage")) |u| {
if (usage) |earlier| try steered_usage.append(earlier);
usage = try util.dupeJsonValue(result_arena, u);
@@ -92,6 +94,7 @@ pub fn parseResponses(self: *Agent, body: []const u8) !ResponsesResult {
if (saw_completed or saw_incomplete or items.items.len > 0) {
var resp: std.json.ObjectMap = .empty;
try resp.put(result_arena, "output", .{ .array = items });
+ try terminal.apply(result_arena, &resp);
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 });
@@ -237,6 +240,25 @@ test "parseResponses: terminal failure beats partial items; incomplete stays mar
}
}
+test "parseResponses preserves output-limit reasons without continuing filtered responses" {
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ var agent: Agent = undefined;
+ agent.arena = arena_state.allocator();
+ agent.scratch_arena = null;
+ agent.message_mutation_arena = null;
+ for ([_][]const u8{ "max_output_tokens", "content_filter" }) |reason| {
+ const body = try std.fmt.allocPrint(agent.arena, "data: {{\"type\":\"response.incomplete\",\"response\":{{\"incomplete_details\":{{\"reason\":\"{s}\"}},\"usage\":{{\"total_tokens\":42}}}}}}\n", .{reason});
+ switch (try parseResponses(&agent, body)) {
+ .ok => |root| {
+ try std.testing.expect(root.get("incomplete").?.bool);
+ try std.testing.expectEqual(std.mem.eql(u8, reason, "max_output_tokens"), @import("agent_length.zig").limited(.responses, root));
+ },
+ .err => return error.TestUnexpectedResult,
+ }
+ }
+}
+
test "#1019: type:error token-parse frame yields failure.message" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
diff --git a/src/agent_steps.zig b/src/agent_steps.zig
index 46c45d17..e4eed765 100644
--- a/src/agent_steps.zig
+++ b/src/agent_steps.zig
@@ -25,6 +25,7 @@ const toolResultMessage = messages_mod.toolResultMessage;
const turn_checkpoint = @import("turn_checkpoint.zig");
const tool_call_args = @import("tool_call_args.zig");
const tool_call_repair = @import("tool_call_repair.zig");
+const length = @import("agent_length.zig");
pub fn surfaceUnstreamedText(self: *Agent, text: []const u8) !void {
if (self.sub or self.streamed_text or text.len == 0) return;
@@ -108,7 +109,8 @@ pub fn stepResponses(self: *Agent, response: std.json.ObjectMap) !?[]const u8 {
const call_id = if (item.object.get("call_id")) |c| (if (c == .string) c.string else continue) else continue;
const args = if (item.object.get("arguments")) |a| (if (a == .string) a.string else "") else "";
const parsed = tool_call_args.parse(self.scratchAlloc(), args); // #124: execution-only tree
- try calls.append(self.gpa, .{ .id = call_id, .name = name, .input = parsed.input, .args_ok = parsed.valid });
+ const cut = length.callCut(self.gpa, length.limited(.responses, response), item.object, args);
+ try calls.append(self.gpa, .{ .id = call_id, .name = name, .input = parsed.input, .args_ok = parsed.valid and !cut, .cut = cut });
}
}
tool_call_args.repairHistory(self.gpa, self.arena, self.messages.items);
@@ -202,7 +204,9 @@ pub fn stepAnthropic(self: *Agent, root: std.json.ObjectMap) !?[]const u8 {
const id = if (block.object.get("id")) |x| (if (x == .string) x.string else "") else "";
const why = tool_call_args.takeInvalidMark(&block.object);
const input = block.object.get("input") orelse Value{ .object = .empty };
- try calls.append(self.gpa, .{ .id = id, .name = name, .input = input, .args_ok = why == .none, .cut = why == .cut });
+ const cut = why == .cut or (length.limited(.anthropic, root) and !block.object.contains("input"));
+ if (!block.object.contains("input") or input != .object) try block.object.put(self.arena, "input", .{ .object = .empty });
+ try calls.append(self.gpa, .{ .id = id, .name = name, .input = input, .args_ok = why == .none and !cut and input == .object, .cut = cut });
}
}
self.pairContextMeterWithCurrentLocal();
@@ -230,7 +234,7 @@ pub fn stepAnthropic(self: *Agent, root: std.json.ObjectMap) !?[]const u8 {
}
if (std.mem.eql(u8, stop_reason, "pause_turn")) return null;
- if (!std.mem.eql(u8, stop_reason, "end_turn")) try self.say("[stopped: {s}]\n", .{stop_reason});
+ if (!std.mem.eql(u8, stop_reason, "end_turn") and !length.limited(.anthropic, root)) try self.say("[stopped: {s}]\n", .{stop_reason});
return final_text;
}
@@ -267,14 +271,17 @@ pub fn stepOpenAI(self: *Agent, root: std.json.ObjectMap) !?[]const u8 {
try self.sayApiError("api error: choice had no message", .{});
return error.ApiError;
};
- // Lost arguments rebuilt from the reply's own tool-call markup (MiMo only).
- if (@import("effort_route.zig").mimoRoute(self.provider.id, self.provider.model))
- _ = try tool_call_repair.repairCalls(self.arena, self.scratchAlloc(), &message, self.toolsJson());
- // Announced tools come back untyped where the wire types only declared ones (MiMo, Claude).
- if (@import("additional_tools.zig").active(self.provider))
- _ = try tool_call_repair.retypeArgs(self.arena, self.scratchAlloc(), &message, self.toolsJson());
- // #1247: calls the server's parser left in `content` as markup.
- _ = try tool_call_repair.recoverInlineCalls(self.arena, self.scratchAlloc(), &message, self.toolsJson());
+ // Never reconstruct executable arguments from a reply cut mid-output.
+ if (!length.limited(.openai, root)) {
+ // Lost arguments rebuilt from the reply's own tool-call markup (MiMo only).
+ if (@import("effort_route.zig").mimoRoute(self.provider.id, self.provider.model))
+ _ = try tool_call_repair.repairCalls(self.arena, self.scratchAlloc(), &message, self.toolsJson());
+ // Announced tools come back untyped where the wire types only declared ones (MiMo, Claude).
+ if (@import("additional_tools.zig").active(self.provider))
+ _ = try tool_call_repair.retypeArgs(self.arena, self.scratchAlloc(), &message, self.toolsJson());
+ // #1247: calls the server's parser left in `content` as markup.
+ _ = try tool_call_repair.recoverInlineCalls(self.arena, self.scratchAlloc(), &message, self.toolsJson());
+ }
const msg_obj = tools_mod.json_args.object(message) orelse {
try self.sayApiError("api error: choice message was not an object", .{});
return error.ApiError;
@@ -303,7 +310,8 @@ pub fn stepOpenAI(self: *Agent, root: std.json.ObjectMap) !?[]const u8 {
const name = if (function.object.get("name")) |n| (if (n == .string) n.string else "") else "";
if (name.len == 0) continue; // can't dispatch a nameless call
const id = if (tc.object.get("id")) |x| (if (x == .string) x.string else "") else "";
- try calls.append(self.gpa, .{ .id = id, .name = name, .input = parsed.input, .args_ok = parsed.valid and why == .none, .cut = why == .cut });
+ const cut = why == .cut or length.callCut(self.gpa, length.limited(.openai, root), tc.object, args_str);
+ try calls.append(self.gpa, .{ .id = id, .name = name, .input = parsed.input, .args_ok = parsed.valid and why == .none and !cut, .cut = cut });
}
};
tool_call_args.repairMessage(self.gpa, self.arena, &self.messages.items[self.messages.items.len - 1]);
@@ -338,7 +346,7 @@ pub fn stepOpenAI(self: *Agent, root: std.json.ObjectMap) !?[]const u8 {
// not). An unconditional `.?` here panicked the whole harness on that input;
// null-guard it like every other field read in this file (#134 audit P0).
if (choice.get("finish_reason")) |finish| {
- if (finish == .string and !std.mem.eql(u8, finish.string, "stop")) try self.say("[stopped: {s}]\n", .{finish.string});
+ if (finish == .string and !std.mem.eql(u8, finish.string, "stop") and !length.limited(.openai, root)) try self.say("[stopped: {s}]\n", .{finish.string});
}
return final_text;
}
diff --git a/src/agent_stream.zig b/src/agent_stream.zig
index 0e221704..2c8db91e 100644
--- a/src/agent_stream.zig
+++ b/src/agent_stream.zig
@@ -30,7 +30,6 @@ const providerUserAgent = http.providerUserAgent;
const capture5xxBodyStream = http.capture5xxBodyStream;
const WatchdogFired = http.WatchdogFired;
const sendHeadTask = http.sendHeadTask;
-const headStallTask = http.headStallTask;
const streamLineTask = http.streamLineTask;
const deadlineStallTask = http.deadlineStallTask;
const watchdogError = http.watchdogError;
@@ -163,7 +162,7 @@ pub fn postStreamWithClient(self: *Agent, client: *std.http.Client, body: []cons
if (req.connection) |conn| conn.closing = true;
return error.HungRequest;
};
- hsel.concurrent(.stall, headStallTask, .{ self.io, orig_tio != null }) catch {
+ hsel.concurrent(.stall, deadlineStallTask, .{ self.io, orig_tio != null, http.head_stall_ms }) catch {
const r = hsel.await() catch |e| {
hsel.cancelDiscard();
return e;
@@ -193,6 +192,10 @@ pub fn postStreamWithClient(self: *Agent, client: *std.http.Client, body: []cons
// 429/5xx before any body: a retryable throttle — request() backs
// off and retries (surfaced in the trace as a "retry" note).
const status_code = @backingInt(response.head.status);
+ if (@import("agent_request_quota.zig").httpError(status_code)) |err| {
+ if (req.connection) |conn| conn.closing = true;
+ return err;
+ }
if (status_code == 429 or status_code >= 500) {
http.captureRetryAfter(&response); // #retry-after: honor the provider's requested backoff
// Drain a snippet for quota classifiers. Do not echo it on the REPL
@@ -236,6 +239,7 @@ pub fn postStreamWithClient(self: *Agent, client: *std.http.Client, body: []cons
var phase: @import("agent_ws_signal.zig").Phase = .{}; // ADR 0248: commentary does not tighten
defer line.deinit();
+ const policy = http_stall.streamPolicy(self.provider.model, http.stream_stall_ms);
stream: while (true) {
// Race the line read against an idle-stall watchdog so a dead stream can't
// hang the turn (the Esc escape below is TTY-only, so --json/GUI sessions
@@ -246,7 +250,8 @@ pub fn postStreamWithClient(self: *Agent, client: *std.http.Client, body: []cons
var rd_buf: [2]ReadDone = undefined;
var rsel: Io.Select(ReadDone) = .init(self.io, &rd_buf);
// #680: widened by each stall reconnect this request has already made.
- const stall_budget = http_stall.interFrameBudgetMs(http.stream_stall_ms, got_body, prose_open, self.stall.widen);
+ // 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 {
// #56 Fix-B: pool exhausted — no idle-stall watchdog for this read.
// A bare blocking streamDelimiterEnding here is the last forever-hang:
@@ -420,28 +425,8 @@ test {
_ = @import("agent_model_loop.zig");
}
-/// #680: what request() does before each stall reconnect. The partial is
-/// cleared so the fresh stream re-streams cleanly (no concat), and the
-/// between-lines budget widens (http_stall.budgetMsWidened) so the retry can
-/// outlast the pause that killed the last attempt, instead of re-paying the
-/// whole generation into the identical wait.
-pub fn noteStallRetry(self: *Agent, retries: usize) void {
- self.partial_text.clearRetainingCapacity();
- self.stall.widen = @intCast(@min(retries, 255));
- if (self.tracer) |tr| {
- const widened = http_stall.budgetMsWidened(http.stream_stall_ms, true, self.stall.widen);
- tr.note("stall_budget", std.fmt.allocPrint(self.arena, "reconnect {d}: between-lines budget {d}s", .{ retries, widened / 1000 }) catch "widened");
- }
-}
-
-/// #680: the turn-ending stall message, from the budget that actually tripped
-/// rather than the configured total (the between-lines wait is a fraction of
-/// it, so "120s" was never what a mid-response stall had waited).
-pub fn stallGiveUpMessage(self: *Agent, retries: usize) ?[]const u8 {
- const base = http.stream_stall_ms;
- const waited = if (self.stall.tripped_ms != 0) self.stall.tripped_ms else base;
- return std.fmt.allocPrint(self.arena, "stream stalled: no data from the model for {d}s — ended the turn after {d} reconnect attempts, each waiting longer, up to GRAFF_STREAM_STALL_SECS={d}s between lines (raise it if your model pauses longer mid-response)", .{ waited / 1000, retries, base / 1000 }) catch null;
-}
+pub const noteStallRetry = @import("agent_stream_stall.zig").noteStallRetry;
+pub const stallGiveUpMessage = @import("agent_stream_stall.zig").stallGiveUpMessage;
/// Extract the user-visible content from one SSE line and dispatch it as
/// typed events through the sink. Best-effort: parse failures are ignored
diff --git a/src/agent_stream_h2.zig b/src/agent_stream_h2.zig
index 903d241b..3a255177 100644
--- a/src/agent_stream_h2.zig
+++ b/src/agent_stream_h2.zig
@@ -18,7 +18,6 @@ const http_zig = @import("http_zig");
const WatchdogFired = http.WatchdogFired;
const watchdogError = http.watchdogError;
const deadlineStallTask = http.deadlineStallTask;
-const headStallTask = http.headStallTask;
const ssePayload = Agent.ssePayload;
const escPressed = Agent.escPressed;
@@ -89,10 +88,11 @@ pub fn postStream(self: *Agent, body: []const u8, poll_stdin: bool) !?[]u8 {
// Dial, send and time-to-first-HEADERS race the head-stall watchdog, as
// the HTTP/1.1 send + receiveHead do (issue #54): a half-open socket or a
// server that accepts the stream and goes silent must not hang the turn.
- switch (try raceHead(self.io, &head, poll_stdin)) {
+ switch (try raceHead(self.io, &head, poll_stdin, http.head_stall_ms)) {
.ok => {},
.fallback => return null,
}
+ if (@import("agent_request_quota.zig").httpError(head.status)) |err| return err;
if (head.status == 429) return error.RateLimited;
if (head.status >= 500) return error.ServerError;
if (head.status == 404 and head.openai) return error.OpenAiFlaky404;
@@ -110,9 +110,13 @@ pub fn postStream(self: *Agent, body: []const u8, poll_stdin: bool) !?[]u8 {
var loop_guard: @import("agent_model_loop.zig").Stream = .{};
var got_body = false;
var saw_done = false;
+ var prose_open = false;
+ var phase: @import("agent_ws_signal.zig").Phase = .{}; // ADR 0241/0248, same as HTTP/1.1
+ const policy = http_stall.streamPolicy(provider.model, http.stream_stall_ms);
while (true) {
- const stall_budget = http_stall.interFrameBudgetMs(http.stream_stall_ms, got_body, self.partial_text.items.len != 0, self.stall.widen);
+ // 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 {
// #56 Fix-B: no spare concurrency for the read. Fail safe.
if (saw_done) break;
@@ -148,7 +152,10 @@ pub fn postStream(self: *Agent, body: []const u8, poll_stdin: bool) !?[]u8 {
try full.writer.writeAll(line.items);
try full.writer.writeByte('\n');
got_body = true;
+ const prose_len = self.partial_text.items.len;
self.printDelta(line.items);
+ phase.feed(gpa, line.items);
+ if (self.partial_text.items.len > prose_len) prose_open = !phase.commentary else if (@import("agent_ws_signal.zig").closesItem(gpa, line.items)) prose_open = false;
if (main_mod.g_thinking_fold_request) {
main_mod.g_thinking_fold_request = false;
sink.emit(self.io, .thinking_fold_toggle);
@@ -200,14 +207,14 @@ const Head = struct {
const HeadResult = enum { ok, fallback };
-fn raceHead(io: Io, head: *Head, poll_stdin: bool) !HeadResult {
+fn raceHead(io: Io, head: *Head, poll_stdin: bool, budget_ms: u64) !HeadResult {
const HeadDone = union(enum) { done: anyerror!void, stall: WatchdogFired };
var hd_buf: [2]HeadDone = undefined;
var hsel: Io.Select(HeadDone) = .init(io, &hd_buf);
// #56 Fix-B: no slot for the task means no watchdog either. Nothing has
// been sent, so fail retryable instead of blocking the turn.
hsel.concurrent(.done, headTask, .{head}) catch return error.HungRequest;
- hsel.concurrent(.stall, headStallTask, .{ io, poll_stdin }) catch {};
+ hsel.concurrent(.stall, deadlineStallTask, .{ io, poll_stdin, budget_ms }) catch {};
const first = hsel.await() catch |e| {
hsel.cancelDiscard();
return e;
diff --git a/src/agent_stream_stall.zig b/src/agent_stream_stall.zig
new file mode 100644
index 00000000..88926bac
--- /dev/null
+++ b/src/agent_stream_stall.zig
@@ -0,0 +1,25 @@
+//! Stream reconnect accounting and terminal stall diagnostics.
+const std = @import("std");
+const Agent = @import("agent.zig").Agent;
+const http = @import("http.zig");
+const http_stall = @import("http_stall.zig");
+
+/// #680: what request() does before each stall reconnect. The partial is
+/// cleared so the fresh stream re-streams cleanly (no concat), and the
+/// between-lines budget widens (http_stall.budgetMsWidened) so the retry can
+/// outlast the pause that killed the last attempt, instead of re-paying the
+/// whole generation into the identical wait.
+pub fn noteStallRetry(self: *Agent, retries: usize) void {
+ self.partial_text.clearRetainingCapacity();
+ self.stall.widen = @intCast(@min(retries, 255));
+ if (self.tracer) |tr| {
+ const widened = http_stall.budgetMsWidened(http.stream_stall_ms, true, self.stall.widen);
+ tr.note("stall_budget", std.fmt.allocPrint(self.arena, "reconnect {d}: between-lines budget {d}s", .{ retries, widened / 1000 }) catch "widened");
+ }
+}
+
+pub fn stallGiveUpMessage(self: *Agent, retries: usize) ?[]const u8 {
+ const base = http_stall.streamPolicy(self.provider.model, http.stream_stall_ms).silence_ms;
+ const waited = if (self.stall.tripped_ms != 0) self.stall.tripped_ms else base;
+ return std.fmt.allocPrint(self.arena, "stream stalled: no data from the model for {d}s — ended the turn after {d} reconnect attempts, each waiting longer (stream silence allowance {d}s; set GRAFF_STREAM_STALL_SECS to override)", .{ waited / 1000, retries, base / 1000 }) catch null;
+}
diff --git a/src/agent_turn.zig b/src/agent_turn.zig
index 81e09337..5b149a15 100644
--- a/src/agent_turn.zig
+++ b/src/agent_turn.zig
@@ -16,6 +16,8 @@ pub fn run(self: *Agent, root_turn_prepared: *std.atomic.Value(bool)) anyerror![
defer if (!self.sub) @import("peer_idle.zig").noteTurnEnd();
var pending_work = empty_completion.PendingWork.begin(self);
var bounced_answer: empty_completion.BounceAnswer = .{};
+ var length: @import("agent_length.zig").State = .{};
+ self.empty_completion_retries = 0;
self.completed = null;
self.yielded = null;
self.read_miss.reset();
@@ -75,7 +77,7 @@ pub fn run(self: *Agent, root_turn_prepared: *std.atomic.Value(bool)) anyerror![
}
const hist_len = self.messages.items.len;
const root = self.request(if (self.text_only) null else self.toolsJson()) catch |err| return review_deadline.finish(try @import("agent_model_loop.zig").finishError(self, err));
- const done = try @import("agent_steps.zig").stepForWire(self, root);
+ const done = try length.step(self, root);
if (done) |final_text| {
if (self.yielded != null) return review_deadline.finish(final_text);
if (@import("tool_call_repair.zig").endsTurn(self, final_text)) return review_deadline.finish(final_text); // final: no retry/nudge
diff --git a/src/args.zig b/src/args.zig
index 33fc9386..0ebeb1c2 100644
--- a/src/args.zig
+++ b/src/args.zig
@@ -49,6 +49,7 @@ pub const Flags = struct {
help_flag: bool = false,
version_flag: bool = false,
print_flag: bool = false,
+ stream_json_flag: bool = false, // --output-format stream-json: one-shot lifecycle + result
update_force: bool = false, // graff update --force
selftest_spinner_flag: bool = false, // --selftest-spinner: headless spinner render for the PTY anti-stealth test
selftest_markdown_flag: bool = false, // --selftest-markdown: render the real streaming markdown fixture in a PTY
@@ -166,6 +167,11 @@ pub fn parse(init: std.process.Init) !Flags {
main_mod.show_cost = true;
} else if (std.mem.eql(u8, arg, "--json")) {
main_mod.json_mode = true;
+ } else if (std.mem.eql(u8, arg, "--output-format")) {
+ const format = it.next() orelse std.process.fatal("--output-format needs text|stream-json", .{});
+ if (!std.mem.eql(u8, format, "text") and !std.mem.eql(u8, format, "stream-json"))
+ std.process.fatal("--output-format needs text|stream-json", .{});
+ flags.stream_json_flag = std.mem.eql(u8, format, "stream-json");
} else if (std.mem.eql(u8, arg, "--max-tool-calls")) {
const mv = it.next() orelse std.process.fatal("--max-tool-calls needs a non-negative integer — graff --help", .{});
main_mod.max_tool_calls = std.fmt.parseInt(u64, mv, 10) catch std.process.fatal("--max-tool-calls needs a non-negative integer, got '{s}'", .{mv});
@@ -284,6 +290,10 @@ pub fn parse(init: std.process.Init) !Flags {
flags.oneshot_prompt = try std.mem.join(arena, " ", flags.positionals.items);
}
if (flags.print_flag and flags.oneshot_prompt == null) std.process.fatal("-p needs a prompt: harness -p \"do something\"", .{});
+ if (flags.stream_json_flag) {
+ if (flags.oneshot_prompt == null) std.process.fatal("--output-format stream-json needs a one-shot prompt", .{});
+ main_mod.json_mode = true;
+ }
if (flags.branch_flag != null and flags.resume_flag == null) std.process.fatal("--branch needs --resume <source>", .{});
if (flags.branch_flag != null and (flags.new_session_flag or flags.no_resume_flag)) std.process.fatal("--branch cannot be combined with --new or --no-resume", .{});
diff --git a/src/cli.zig b/src/cli.zig
index 1c1b0d93..731a70c0 100644
--- a/src/cli.zig
+++ b/src/cli.zig
@@ -24,6 +24,11 @@ const update_target = @import("update_target.zig");
pub const changelog_text =
\\What's new
\\──────────
+ \\0.302.39
+ \\ • unattended runs recover from output limits and empty replies
+ \\ • one-shot stream-json reports a resume handle, outcome and usage
+ \\ • exhausted budgets and account limits stop with distinct exit codes
+ \\
\\0.302.38
\\ • Windows: faster start, and the companion is found on PATH
\\
@@ -275,6 +280,7 @@ pub const usage_text =
\\ --no-lean opt a one-shot out of the implied --lean: full tool surface + eager MCP schemas, the pre-default -p behavior
\\ --no-local-tools embedder mode: hard-disable the built-in bash/bash_output/bash_kill/read_file/edit_file/write_file/codedb tools for the whole process (subagents included), so graff can run outside the sandbox and get its coding tools from an MCP server instead; webfetch, orchestration and MCP tools still work (GRAFF_NO_LOCAL_TOOLS=1)
\\ -p, --print one-shot print mode (answer on stdout, progress on stderr)
+ \\ --output-format text|stream-json one-shot output; stream-json emits run_started and result
\\ --timing show per-tool wall-clock on result lines
\\ --cost show running session spend in the prompt
\\ --json structured stdio protocol (JSON in, JSONL events out)
diff --git a/src/headless_result.zig b/src/headless_result.zig
new file mode 100644
index 00000000..2316a79f
--- /dev/null
+++ b/src/headless_result.zig
@@ -0,0 +1,93 @@
+//! Machine-readable one-shot lifecycle. Unknown charges are never reported as zero.
+const std = @import("std");
+const Agent = @import("agent.zig").Agent;
+const pricing = @import("pricing.zig");
+const quota = @import("agent_request_quota.zig");
+const util = @import("util.zig");
+
+pub const Failure = struct { reason: []const u8, exit_code: u8, retryable: bool = false };
+
+pub fn classify(err: anyerror, detail: []const u8) Failure {
+ if (err == error.Interrupted or err == error.Canceled) return .{ .reason = "cancelled", .exit_code = 130 };
+ if (err == error.RunBudgetExhausted or err == error.ToolBudgetExhausted) return .{ .reason = "budget_exhausted", .exit_code = 3 };
+ if (err == error.OutputLengthExceeded) return .{ .reason = "output_length_exhausted", .exit_code = 2 };
+ if (err == error.FallbackConsentRequired) return .{ .reason = "authentication_required", .exit_code = 77 };
+ if (err == error.ProviderQuotaExceeded) return .{ .reason = "quota_exhausted", .exit_code = 4 };
+ if (err == error.ProviderAuthenticationFailed or err == error.ProviderAccessDenied)
+ return .{ .reason = "authentication_required", .exit_code = 77 };
+ if (quota.classify("", null, detail)) |fault| return switch (fault) {
+ .quota => .{ .reason = "quota_exhausted", .exit_code = 4 },
+ .authentication, .access_denied => .{ .reason = "authentication_required", .exit_code = 77 },
+ };
+ if (util.indexOfIgnoreCase(detail, "HTTP 401") != null or util.indexOfIgnoreCase(detail, "HTTP 403") != null)
+ return .{ .reason = "authentication_required", .exit_code = 77 };
+ if (err == error.EmptyCompletion or err == error.StreamStalled or err == error.StreamDropped or err == error.HungRequest or err == error.RateLimited or err == error.ServerError or
+ err == error.StreamInterrupted or err == error.StreamReadFailed or err == error.UnknownHostName or err == error.ConnectionResetByPeer or err == error.ConnectionRefused or
+ util.indexOfIgnoreCase(detail, "timeout") != null or util.indexOfIgnoreCase(detail, "timed out") != null or
+ util.indexOfIgnoreCase(detail, "network error:") != null or util.indexOfIgnoreCase(detail, "rate limited (429)") != null or
+ util.indexOfIgnoreCase(detail, "server error (5xx)") != null or util.indexOfIgnoreCase(detail, "HTTP 429") != null or
+ util.indexOfIgnoreCase(detail, "HTTP 500") != null or util.indexOfIgnoreCase(detail, "HTTP 502") != null or
+ util.indexOfIgnoreCase(detail, "HTTP 503") != null or util.indexOfIgnoreCase(detail, "HTTP 504") != null)
+ return .{ .reason = "transient_failure", .exit_code = 75, .retryable = true };
+ if (util.indexOfIgnoreCase(detail, "HTTP 400") != null or util.indexOfIgnoreCase(detail, "invalid_request") != null)
+ return .{ .reason = "invalid_request", .exit_code = 78 };
+ return .{ .reason = "failed", .exit_code = 1 };
+}
+
+pub const Run = struct {
+ started: std.Io.Timestamp,
+ turns: u64 = 1,
+
+ pub fn start(root: *Agent) Run {
+ const run: Run = .{ .started = .now(root.io, .awake) };
+ if (@import("main.zig").json_mode) {
+ root.emit(.{ .type = "run_started", .run_id = &@import("scoring.zig").g_run_id, .session_id = root.session_name, .parent_session_id = root.session_parent });
+ } else {
+ // stderr is a JSON line too: wrappers can obtain a handle without
+ // changing the existing plain-answer stdout contract.
+ const line = std.json.Stringify.valueAlloc(root.arena, .{ .type = "run_started", .run_id = &@import("scoring.zig").g_run_id, .session_id = root.session_name, .parent_session_id = root.session_parent }, .{}) catch return run;
+ std.debug.print("{s}\n", .{line});
+ }
+ return run;
+ }
+
+ pub fn finish(run: Run, root: *Agent, failure: ?Failure, answer: []const u8, saved: bool) void {
+ if (!@import("main.zig").json_mode) return;
+ const c = pricing.g_cost.snap(root.io);
+ const cost_complete = c.unpriced_calls == 0 and c.missing_usage_calls == 0 and c.unreported_failed_attempts == 0;
+ root.emit(.{
+ .type = "result",
+ .run_id = &@import("scoring.zig").g_run_id,
+ .session_id = root.session_name,
+ .parent_session_id = root.session_parent,
+ .status = if (failure) |f| (if (f.exit_code == 130) "cancelled" else "failed") else "completed",
+ .reason = if (failure) |f| f.reason else "completed",
+ .exit_code = if (failure) |f| f.exit_code else @as(u8, 0),
+ .retryable = if (failure) |f| f.retryable else false,
+ .session_saved = saved,
+ .turns = run.turns,
+ .model_calls = if (root.run_budget) |b| b.used() else c.api_calls,
+ .duration_ms = @max(0, run.started.untilNow(root.io, .awake).toMilliseconds()),
+ .usage = .{ .input_tokens = c.in_tokens +| c.cache_tokens, .cached_input_tokens = c.cache_tokens, .cache_write_tokens = c.cache_write_tokens, .output_tokens = c.out_tokens, .api_calls = c.api_calls, .missing_usage_calls = c.missing_usage_calls, .failed_attempts_without_usage = c.unreported_failed_attempts },
+ .total_cost_usd = if (cost_complete) @as(?f64, c.usd) else null,
+ .known_cost_usd = c.usd,
+ .cost_complete = cost_complete,
+ .unpriced_calls = c.unpriced_calls,
+ .subscription_calls = c.sub_calls,
+ .result = answer,
+ });
+ }
+};
+
+test "headless result classifies terminal limits separately from transient failures" {
+ try std.testing.expectEqual(@as(u8, 3), classify(error.RunBudgetExhausted, "").exit_code);
+ try std.testing.expectEqual(@as(u8, 4), classify(error.ApiError, "HTTP 402 payment required").exit_code);
+ try std.testing.expectEqual(@as(u8, 77), classify(error.ApiError, "invalid_api_key").exit_code);
+ try std.testing.expectEqual(@as(u8, 78), classify(error.ApiError, "HTTP 400 invalid request").exit_code);
+ try std.testing.expect(classify(error.EmptyCompletion, "").retryable);
+ try std.testing.expectEqualStrings("output_length_exhausted", classify(error.OutputLengthExceeded, "").reason);
+ try std.testing.expectEqual(@as(u8, 130), classify(error.Interrupted, "").exit_code);
+ try std.testing.expect(!classify(error.ApiError, "insufficient_quota").retryable);
+ try std.testing.expect(classify(error.ApiError, "network error: TemporaryNameServerFailure (gave up after 6 attempts)").retryable);
+ try std.testing.expect(!classify(error.ProviderQuotaExceeded, "server error (5xx)").retryable);
+}
diff --git a/src/http_stall.zig b/src/http_stall.zig
index 1dbea164..04a89f99 100644
--- a/src/http_stall.zig
+++ b/src/http_stall.zig
@@ -1,7 +1,7 @@
-//! Stall-budget arithmetic for the streaming watchdogs (#56). Pure: no Io, no
-//! globals, so both regimes are testable at their boundary without sleeping
-//! through a real 120s stall. Lives beside http.zig (which is at the 600-line
-//! cap) the way http_headers.zig does; http.zig owns the watchdog loops and
+//! Stall-budget arithmetic for the streaming watchdogs (#56). Policy choices
+//! are testable without Io or sleeping through real stalls; streamPolicy is
+//! the boundary that reads configured/env overrides. Lives beside http.zig
+//! like http_headers.zig; http.zig owns the watchdog loops and
//! the configured budget, this owns the decision they make each tick.
const std = @import("std");
@@ -77,12 +77,150 @@ pub fn interFrameBudgetMs(base_ms: u64, saw_protocol: bool, tokens_flowing: bool
return budgetMsWidened(base_ms, false, widen);
}
+/// Request-local policy: buffered Gemini-4 generations may be silent after
+/// HTTP headers, even before their first SSE frame. Keep connect/HTTP-head
+/// watchdogs unchanged, and keep the usual fast budget while prose is open.
+/// This cannot extend a gateway's own upstream/idle deadline or send SSE
+/// keepalives on the server's behalf.
+pub const StreamPolicy = struct {
+ silence_ms: u64,
+ initial_ms: u64,
+ prose_base_ms: u64,
+
+ pub fn init(model: []const u8, base_ms: u64, head_ms: u64, stream_override: bool, head_override: bool) StreamPolicy {
+ // Non-default configured values also win for embedded callers/tests
+ // that set budgets without going through the process environment.
+ const explicit_stream = stream_override or base_ms != 120 * 1000;
+ const buffered = bufferedToolModel(model) and !explicit_stream;
+ const silence = if (buffered) @max(base_ms, 20 * 60 * 1000) else base_ms;
+ const initial = if (buffered and !head_override and head_ms == 45 * 1000) silence else @min(silence, head_ms);
+ return .{ .silence_ms = silence, .initial_ms = initial, .prose_base_ms = base_ms };
+ }
+
+ pub fn interFrameBudgetMs(self: StreamPolicy, saw_protocol: bool, prose_open: bool, widen: u8) u64 {
+ if (prose_open) return budgetMsWidened(self.prose_base_ms, true, widen);
+ return if (saw_protocol) self.silence_ms else self.initial_ms;
+ }
+};
+
+/// Compute once per stream, never mutate shared watchdog budgets. Inspect the
+/// explicit knobs as well as their configured values: an override equal to
+/// the shipped default is still an override. Validation matches settings.
+pub fn streamPolicy(model: []const u8, base_ms: u64) StreamPolicy {
+ return StreamPolicy.init(model, base_ms, head_ceiling_ms, validSecondsEnv("GRAFF_STREAM_STALL_SECS"), validSecondsEnv("GRAFF_STREAM_HEAD_STALL_SECS"));
+}
+
+fn validSecondsEnv(name: [*:0]const u8) bool {
+ const raw = std.c.getenv(name) orelse return false;
+ return validSeconds(std.mem.span(raw));
+}
+
+fn validSeconds(raw: []const u8) bool {
+ const seconds = std.fmt.parseInt(u64, std.mem.trim(u8, raw, " \t"), 10) catch return false;
+ return seconds > 0;
+}
+
+fn bufferedToolModel(qualified_model: []const u8) bool {
+ const model = if (std.mem.lastIndexOfScalar(u8, qualified_model, '/')) |slash| qualified_model[slash + 1 ..] else qualified_model;
+ const prefix = "gemini-4";
+ if (model.len < prefix.len or !std.ascii.eqlIgnoreCase(model[0..prefix.len], prefix)) return false;
+ if (model.len == prefix.len) return true;
+ // Bound the family match: gemini-40 and gemini-4ish are not Gemini-4.
+ return switch (model[prefix.len]) {
+ '-', '.', ':' => true,
+ else => false,
+ };
+}
+
/// True once a silent read has outlasted its budget — the watchdog loop's only
/// decision, split out so it can be exercised at the boundary in a unit test.
pub fn expired(waited_ms: u64, base_ms: u64, tokens_flowing: bool) bool {
return waited_ms >= budgetMs(base_ms, tokens_flowing);
}
+test "stream policy: Gemini-4 model ids allow buffered tool silence, not slow prose" {
+ const models = [_][]const u8{
+ "gemini-4", "gemini-4-argon", "gemini-4.0-pro", "google/gemini-4-argon",
+ "openrouter/google/gemini-4-argon", "google/gemini-4-argon:free", "GEMINI-4-ARGON",
+ };
+ for (models) |model| {
+ const policy = StreamPolicy.init(model, 120_000, 45_000, false, false);
+ try std.testing.expectEqual(@as(u64, 1_200_000), policy.interFrameBudgetMs(false, false, 0));
+ try std.testing.expectEqual(@as(u64, 1_200_000), policy.interFrameBudgetMs(true, false, 0));
+ // A multi-minute buffered function call fits; a dead mid-answer
+ // socket still gets the usual 30s / 60s / 120s reconnect ladder.
+ try std.testing.expect(10 * 60 * 1000 < policy.interFrameBudgetMs(true, false, 0));
+ try std.testing.expectEqual(@as(u64, 30_000), policy.interFrameBudgetMs(true, true, 0));
+ try std.testing.expectEqual(@as(u64, 60_000), policy.interFrameBudgetMs(true, true, 1));
+ try std.testing.expectEqual(@as(u64, 120_000), policy.interFrameBudgetMs(true, true, 2));
+ }
+}
+
+test "stream policy: other models retain fast first-frame and prose defaults" {
+ const models = [_][]const u8{
+ "", "gpt-6.1-sol", "claude-opus", "gemini-3.7-flash", "google/gemini-3.7-pro",
+ "openrouter/google/gemini-40-argon", "gemini-4ish", "not-gemini-4-argon", "google/",
+ };
+ for (models) |model| {
+ const policy = StreamPolicy.init(model, 120_000, head_ceiling_ms, false, false);
+ for ([_]bool{ false, true }) |protocol| {
+ for ([_]bool{ false, true }) |prose| {
+ for ([_]u8{ 0, 1, 2, 7 }) |widen| {
+ try std.testing.expectEqual(interFrameBudgetMs(120_000, protocol, prose, widen), policy.interFrameBudgetMs(protocol, prose, widen));
+ }
+ }
+ }
+ }
+}
+
+test "stream policy: explicit stream overrides win even at the shipped default" {
+ for ([_]u64{ 5_000, 120_000, 600_000, 1_800_000, 86_400_000 }) |base| {
+ const policy = StreamPolicy.init("openrouter/google/gemini-4-argon", base, base, true, false);
+ try std.testing.expectEqual(base, policy.interFrameBudgetMs(false, false, 0));
+ try std.testing.expectEqual(base, policy.interFrameBudgetMs(true, false, 0));
+ try std.testing.expectEqual(budgetMsWidened(base, true, 1), policy.interFrameBudgetMs(true, true, 1));
+ }
+ // Embedded callers and shortened stall fixtures remain bounded too.
+ const configured = StreamPolicy.init("gemini-4-argon", 1_200, 45_000, false, false);
+ try std.testing.expectEqual(@as(u64, 1_200), configured.interFrameBudgetMs(false, false, 0));
+}
+
+test "stream policy: explicit HEAD overrides only the first SSE frame, not HTTP connect" {
+ for ([_]u64{ 9_000, 45_000, 600_000, 1_800_000 }) |head| {
+ const policy = StreamPolicy.init("google/gemini-4-argon", 120_000, head, false, true);
+ try std.testing.expectEqual(@min(head, @as(u64, 1_200_000)), policy.interFrameBudgetMs(false, false, 0));
+ try std.testing.expectEqual(@as(u64, 1_200_000), policy.interFrameBudgetMs(true, false, 0));
+ try std.testing.expectEqual(@as(u64, 30_000), policy.interFrameBudgetMs(true, true, 0));
+ }
+ const both = StreamPolicy.init("gemini-4-argon", 120_000, 9_000, true, true);
+ try std.testing.expectEqual(@as(u64, 9_000), both.interFrameBudgetMs(false, false, 0));
+ try std.testing.expectEqual(@as(u64, 120_000), both.interFrameBudgetMs(true, false, 0));
+}
+
+test "stream policy: interleaved requests never leak the buffered allowance" {
+ const saved_head = head_ceiling_ms;
+ const saved_floor = idle_floor_ms;
+ const gemini = StreamPolicy.init("openrouter/google/gemini-4-argon", 120_000, 45_000, false, false);
+ const other = StreamPolicy.init("gpt-6.1-sol", 120_000, 45_000, false, false);
+ const gemini_override = StreamPolicy.init("gemini-4-argon", 120_000, 120_000, true, false);
+ try std.testing.expectEqual(@as(u64, 1_200_000), gemini.interFrameBudgetMs(true, false, 0));
+ try std.testing.expectEqual(@as(u64, 45_000), other.interFrameBudgetMs(false, false, 0));
+ try std.testing.expectEqual(@as(u64, 120_000), other.interFrameBudgetMs(true, false, 0));
+ try std.testing.expectEqual(@as(u64, 120_000), gemini_override.interFrameBudgetMs(true, false, 0));
+ try std.testing.expectEqual(@as(u64, 1_200_000), gemini.interFrameBudgetMs(false, false, 0));
+ try std.testing.expectEqual(saved_head, head_ceiling_ms);
+ try std.testing.expectEqual(saved_floor, idle_floor_ms);
+}
+
+test "stream policy: only valid positive seconds suppress model defaults" {
+ for ([_][]const u8{ "", "0", " 0 ", "-1", "oops", "1.5", "18446744073709551616" }) |raw| {
+ try std.testing.expect(!validSeconds(raw));
+ const policy = StreamPolicy.init("gemini-4-argon", 120_000, 45_000, validSeconds(raw), validSeconds(raw));
+ try std.testing.expectEqual(@as(u64, 1_200_000), policy.interFrameBudgetMs(false, false, 0));
+ }
+ for ([_][]const u8{ "1", "120", " \t120\t", "86401", "18446744073709551615" }) |raw| try std.testing.expect(validSeconds(raw));
+}
+
test "stall budget (#56): between-lines silence trips sooner than a pre-first-token pause" {
const base: u64 = 120 * 1000; // the shipped http.stream_stall_ms default
diff --git a/src/main.zig b/src/main.zig
index a2b160f7..4e35f9a6 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -564,7 +564,7 @@ test { // ── Unit tests (`zig build test`): pull in tests from imported modu
_ = .{ @import("mcp_server_tests.zig"), @import("main_test.zig"), @import("artifact_claim_command.zig"), @import("cli_path_hint.zig"), @import("run_budget.zig") };
_ = .{ @import("session_catalog.zig"), @import("session_prompt.zig"), @import("session_discovery.zig"), @import("session_workspaces.zig"), @import("commands_resume.zig"), @import("peer_live.zig"), @import("presence_tests.zig"), @import("mcp_rpc_tests.zig") };
_ = .{ @import("prompt_astra.zig"), @import("prompt_guidance.zig"), @import("oauth_chatgpt.zig"), @import("chatgpt_reauth.zig") }; // per-model guidance (Astra, GPT-5.6); ChatGPT plan sign-in (ADR 0253)
- _ = .{ @import("agent_empty_completion.zig"), @import("agent_model_loop.zig"), @import("publication_policy_tests.zig"), @import("jobs_completion_tests.zig") };
+ _ = .{ @import("agent_empty_completion.zig"), @import("agent_model_loop.zig"), @import("publication_policy_tests.zig"), @import("jobs_completion_tests.zig"), @import("headless_result.zig"), @import("oneshot.zig"), @import("agent_length.zig"), @import("agent_length_tests.zig") };
_ = .{ @import("provider_routing_tests.zig"), @import("codegraff_messages_tests.zig"), @import("tool_result_empty_tests.zig"), @import("history_wire.zig"), @import("path_lookup.zig"), @import("agents_prepare.zig"), @import("catalog_price.zig"), @import("readline_paste_number_tests.zig"), @import("test_hooks.zig"), @import("peer_wake_loop.zig") };
_ = .{ @import("list_dir_nearmiss.zig"), @import("tool_preview_tests.zig") };
_ = @import("repo_map.zig");
diff --git a/src/oneshot.zig b/src/oneshot.zig
new file mode 100644
index 00000000..748dd47b
--- /dev/null
+++ b/src/oneshot.zig
@@ -0,0 +1,171 @@
+//! One-shot execution and durable supervisor result boundary.
+const std = @import("std");
+const Io = std.Io;
+const Allocator = std.mem.Allocator;
+const main_mod = @import("main.zig");
+const agent_mod = @import("agent.zig");
+const provider_mod = @import("provider.zig");
+const trace = @import("trace.zig");
+const shapes = @import("shapes.zig");
+const prompts = @import("prompts.zig");
+const telemetry = @import("telemetry.zig");
+const repl_glue = @import("repl_glue.zig");
+const eval_memory = @import("eval_memory.zig");
+const providers = @import("providers.zig");
+const fleet = @import("fleet.zig");
+const jobs = @import("jobs.zig");
+const pricing = @import("pricing.zig");
+const messages_mod = @import("messages.zig");
+const session = @import("session.zig");
+const title_mod = @import("title.zig");
+const engine_sink = @import("engine_sink.zig");
+const result = @import("headless_result.zig");
+
+pub fn runOneshotPrompt(gpa: Allocator, io: Io, arena: Allocator, root: *agent_mod.Agent, keys: *provider_mod.Keys, tracer: *trace.Tracer, out: *Io.Writer, prompt_text: []const u8) !void {
+ if (@import("goal_pacing.zig").oneshotSlashRefusal(prompt_text)) |why| std.process.fatal("{s}", .{why}); // usage error, not a prompt
+ main_mod.unattended = true;
+ @import("run_idle.zig").enabled = true; // nothing wakes a finished one-shot: wait for its background work
+ @import("named_work.zig").rememberOn(root, prompt_text);
+ root.in = null; // gate: deny instead of prompt; ask_user: self-decide
+ root.out = if (main_mod.json_mode) out else null;
+ root.stream_quiet = true;
+ var run = result.Run.start(root);
+ // stderr only: same class of "process is live" as Pi's JSONL session line.
+ // Eval first_out used to wait for the call-2 stdout pulse (ADR 0046).
+ std.debug.print("calling {s}\n", .{root.provider.model});
+ const ultracode_msg = try shapes.applyUltracodeSteering(arena, prompt_text, prompt_text, prompts.ultracodeActive(root));
+ if (ultracode_msg.explicit) {
+ tracer.note("ultracode", prompt_text[0..@min(prompt_text.len, 120)]);
+ if (telemetry.g_telem) |t| t.ultracode();
+ }
+ const goal_note = try repl_glue.goalSteeringNote(arena, root.goal);
+ const eval_note = try repl_glue.evalSteeringNote(
+ arena,
+ root.eval_cmd,
+ root.eval_target,
+ root.eval_judge != null,
+ root.eval_verified,
+ root.eval_repair_pending,
+ eval_memory.load(root),
+ );
+ var oneshot_user = if (goal_note.len > 0) try std.fmt.allocPrint(arena, "{s}\n\n{s}", .{ ultracode_msg.text, goal_note }) else ultracode_msg.text;
+ if (eval_note.len > 0) oneshot_user = try std.fmt.allocPrint(arena, "{s}\n\n{s}", .{ oneshot_user, eval_note });
+ try root.messages.append(try @import("named_work.zig").userNudge(arena, root.provider.kind, oneshot_user));
+ if (telemetry.g_telem) |t| t.beginTurn(@intCast(@min(prompt_text.len, std.math.maxInt(u32))), root.provider.model);
+ // #502: --output-schema runs TWO-PHASE. A strict grammar on every message
+ // pulls the model into answering immediately instead of touching tools
+ // (graff-evals caught grok-4.6 guessing a file-inspection answer), so the
+ // agentic phase runs unconstrained and one tools-off formatting turn then
+ // restates the final answer under the schema — same conversation, so it
+ // reads the real evidence.
+ const pending_schema = root.output_schema;
+ root.output_schema = null;
+ var final_text = providers.runTurnWithFallback(root, keys, arena, null) catch |err| {
+ // std.process.fatal does not unwind main's defers. Mirror their order:
+ // join the fleet, reap jobs/pumps, then the terminal behavioral event.
+ fleet.joinElites(io);
+ jobs.jobsReap(gpa, io);
+ @import("subagent.zig").agentJobsReap(gpa, io);
+ // Flush buffered OTLP too: a fatal one-shot stays visible in ordinary telemetry.
+ if (telemetry.g_telem) |t| t.flush();
+ if (tracer.behavior) |behavior| behavior.finish(.failed);
+ pricing.printUsageFooter(io);
+ const saved = save(root, arena);
+ const detail = root.last_api_error orelse @errorName(err);
+ const failure = result.classify(err, detail);
+ run.finish(root, failure, detail, saved);
+ if (root.tools_used.count() > 0) std.debug.print("note: {d} tool call(s) completed before the failure; their work was not rolled back\n", .{root.tools_used.count()});
+ std.debug.print("turn failed ({s}): {s}\n", .{ failure.reason, detail });
+ @import("orchestration_rows.zig").flushPending(0, if (root.run_budget) |b| b.used() else 0, 0, false, "");
+ std.process.exit(failure.exit_code);
+ };
+ const had_schema = pending_schema != null;
+ if (pending_schema) |schema_json| {
+ root.output_schema = schema_json;
+ // Gemini (via the gateway) accepts json_schema then ignores it, so the
+ // #543 sox path never learns. Force schema-in-prompt + structured_output.
+ if (std.mem.startsWith(u8, root.provider.model, "gemini")) root.sox_json_object = true;
+ root.text_only = true;
+ defer {
+ root.text_only = false;
+ root.output_schema = null;
+ }
+ try root.messages.append(try messages_mod.textMessage(arena, "user", "Return ONLY the final answer matching the enforced output schema: call the structured_output tool if it is offered, otherwise reply with a single JSON object. No prose."));
+ if (telemetry.g_telem) |t| t.countTurn();
+ run.turns += 1;
+ final_text = providers.runTurnWithFallback(root, keys, arena, null) catch blk: {
+ // Best-effort: schema-shaping must never lose a finished answer.
+ std.debug.print("warning: output-schema formatting call failed — printing the unshaped answer\n", .{});
+ break :blk final_text;
+ };
+ }
+ const answer = if (had_schema) unwrapFencedJson(final_text) else final_text;
+ // Live -p deltas already rode stdout (`printDelta`); reprinting would
+ // duplicate the answer and push first_out to the footer.
+ if (!main_mod.json_mode) {
+ if (!root.streamed_text) try out.print("{s}\n", .{answer}) else try out.writeAll("\n");
+ }
+ try out.flush();
+ // Usage summary → stderr, so stdout stays exactly the answer.
+ pricing.printUsageFooter(io);
+ const saved = save(root, arena);
+ const incomplete: ?result.Failure = if (root.run_budget != null and (root.run_budget.?.tool_exhausted.load(.acquire) or root.run_budget.?.model_landed.load(.acquire)))
+ .{ .reason = "budget_exhausted", .exit_code = 3 }
+ else if (root.eval_repair_pending or root.yielded != null or @import("subagent_interactive.zig").yielded or @import("goal_state.zig").openCount(root.todos.items, @import("goal_state.zig").currentEpoch(root.goal)) > 0)
+ .{ .reason = "unfinished_work", .exit_code = 2 }
+ else if (std.mem.endsWith(u8, answer, "\n\n" ++ @import("agent_model_loop.zig").marker))
+ .{ .reason = "model_loop", .exit_code = 2 }
+ else if (!saved) .{ .reason = "session_save_failed", .exit_code = 1 } else null;
+
+ // --worktree: checkpoint the one-shot's edits to the scratch branch too.
+ // Headless swarm agents (graff -w name -p "task") are the main -w use
+ // case — they must not exit with their work left uncommitted.
+ jobs.worktreeAutoCommit(gpa, io, std.fmt.allocPrint(arena, "wip: {s}", .{title_mod.titleFromPrompt(prompt_text)}) catch "wip: graff oneshot");
+ // One-shot returns here, before the REPL cleanup defer below is even
+ // registered, so free the root's gpa-backed buffers explicitly (else a
+ // tool-using one-shot leaks its tool log / render buffers on exit).
+ @import("subagent.zig").agentJobsReap(gpa, io);
+ @import("agent_render_cleanup.zig").deinit(root);
+ root.tools_used.deinit(gpa);
+ // Presence announced this session at boot (#469); a one-shot returns
+ // before finalizeSession, so retire + free its gpa-owned globals here or
+ // they reach the exit-time leak check — and our record would linger in
+ // the registry until a peer's liveness probe reaps it.
+ @import("session_globals.zig").release(gpa, io);
+ // #396: the run is over. The frontend hands the terminal back and latches
+ // its reader shut before main()'s teardown — a terminal-ownership move the
+ // sink owns now, in EVERY mode, exactly as the old unconditional call did.
+ engine_sink.writerSink(out).emit(io, .run_finished);
+ run.finish(root, incomplete, answer, saved);
+ if (incomplete) |f| std.process.exit(f.exit_code);
+}
+
+fn save(root: *agent_mod.Agent, arena: Allocator) bool {
+ session.saveSession(root, arena, root.session_name) catch |err| {
+ std.debug.print("⚠ session save failed: {s}\n", .{@errorName(err)});
+ return false;
+ };
+ return true;
+}
+
+fn unwrapFencedJson(text: []const u8) []const u8 {
+ const trimmed = std.mem.trim(u8, text, " \t\r\n");
+ if (!std.mem.startsWith(u8, trimmed, "```")) return trimmed;
+ var rest = trimmed[3..];
+ if (std.mem.startsWith(u8, rest, "json")) rest = rest[4..];
+ rest = std.mem.trimStart(u8, rest, " \t\r\n");
+ if (std.mem.lastIndexOf(u8, rest, "```")) |end| return std.mem.trim(u8, rest[0..end], " \t\r\n");
+ return rest;
+}
+
+test "unwrapFencedJson strips a markdown fence and leaves bare JSON alone" {
+ try std.testing.expectEqualStrings("{\"a\":1}", unwrapFencedJson("```json\n{\"a\":1}\n```\n"));
+ try std.testing.expectEqualStrings("{\"a\":1}", unwrapFencedJson("{\"a\":1}"));
+}
+
+test "one-shot and --json do not auto-init a learning store" {
+ try std.testing.expect(!@import("session_run.zig").shouldAutoLearn(true, false));
+ try std.testing.expect(!@import("session_run.zig").shouldAutoLearn(false, true));
+ try std.testing.expect(!@import("session_run.zig").shouldAutoLearn(true, true));
+ try std.testing.expect(@import("session_run.zig").shouldAutoLearn(false, false));
+}
diff --git a/src/prompt_golden.zig b/src/prompt_golden.zig
index 32bacdea..1c815824 100644
--- a/src/prompt_golden.zig
+++ b/src/prompt_golden.zig
@@ -38,6 +38,9 @@ pub const full_prompt =
\\read, so write a new file without first checking that its path is free.
\\When a script computes a file's content, let that script write the file
\\instead of printing it for write_file.
+ \\For long artifacts requested as files, save sections incrementally with
+ \\small, complete file-writing calls instead of drafting the whole artifact
+ \\in a reply. Keep the final reply a summary unless full inline content is requested.
\\For a read-only exact-key lookup in one known file,
\\call read_file once with contains set to the exact key and answer from its
\\output; do not request the whole file first. To navigate code — finding symbols,
diff --git a/src/prompt_text.zig b/src/prompt_text.zig
index 2fda095f..7b1a98dc 100644
--- a/src/prompt_text.zig
+++ b/src/prompt_text.zig
@@ -43,6 +43,9 @@ pub const local_tools_note =
\\read, so write a new file without first checking that its path is free.
\\When a script computes a file's content, let that script write the file
\\instead of printing it for write_file.
+ \\For long artifacts requested as files, save sections incrementally with
+ \\small, complete file-writing calls instead of drafting the whole artifact
+ \\in a reply. Keep the final reply a summary unless full inline content is requested.
\\For a read-only exact-key lookup in one known file,
\\call read_file once with contains set to the exact key and answer from its
\\output; do not request the whole file first. To navigate code — finding symbols,
diff --git a/src/providers.zig b/src/providers.zig
index dc105db8..8159ec16 100644
--- a/src/providers.zig
+++ b/src/providers.zig
@@ -187,6 +187,7 @@ pub fn failoverEligible(provider_id: []const u8, detail: []const u8) bool {
for (needles) |needle| if (util.indexOfIgnoreCase(detail, needle) != null) return true;
if (!std.mem.eql(u8, provider_id, "codegraff")) return false;
const gateway_billing = [_][]const u8{
+ @import("agent_request_quota.zig").quota_cap_marker,
"insufficient_quota",
"quota exceeded",
"credits exhausted",
@@ -231,7 +232,8 @@ pub fn runTurnWithFallback(root: *Agent, keys: *Keys, arena: Allocator, out: ?*I
} else |err| {
// A Codex-shaped review is an isolated one-shot, not a provider switch for its parent.
if (root.review_mode) return err;
- if (err != error.ApiError or root.partial_text.items.len != 0 or root.tool_calls_this_turn != 0)
+ const account_failure = err == error.ProviderQuotaExceeded or err == error.ProviderAuthenticationFailed or err == error.ProviderAccessDenied;
+ if ((err != error.ApiError and !account_failure) or root.partial_text.items.len != 0 or root.tool_calls_this_turn != 0)
return err;
const detail = root.last_api_error orelse return err;
if (!failoverEligible(root.provider.id, detail)) return err;
@@ -411,6 +413,7 @@ test "failoverEligible: billing needles only fire for the gateway (#294)" {
"billing limit reached",
"quota exceeded for this account",
"insufficient_quota",
+ "provider quota/billing cap: credit or allowance exhausted; retry requires account action",
};
for (billing) |detail| {
try std.testing.expect(failoverEligible("codegraff", detail));
diff --git a/src/run_budget.zig b/src/run_budget.zig
index 38f44a60..578254ea 100644
--- a/src/run_budget.zig
+++ b/src/run_budget.zig
@@ -53,6 +53,8 @@ pub const RunBudget = struct {
max_tool_calls: ?u64 = null,
tool_calls: std.atomic.Value(u64) = .init(0),
tool_exhausted: std.atomic.Value(bool) = .init(false),
+ /// Tools were forcibly withheld for the last admitted model call.
+ model_landed: std.atomic.Value(bool) = .init(false),
max_concurrency: u32 = default_max_concurrency,
max_depth: u8 = default_max_depth,
model_calls: std.atomic.Value(u64) = .init(0),
diff --git a/src/session_run.zig b/src/session_run.zig
index 86584551..acb8fb57 100644
--- a/src/session_run.zig
+++ b/src/session_run.zig
@@ -146,111 +146,7 @@ pub fn runFrontendCommands(gpa: Allocator, io: Io, environ_map: anytype, root: *
/// denies anything not pre-approved instead of prompting (there's no one to
/// ask). Moved out of main() verbatim (600-line goal); `root`/`tracer` are
/// already stable main()-owned storage by the time this runs.
-pub fn runOneshotPrompt(gpa: Allocator, io: Io, arena: Allocator, root: *agent_mod.Agent, keys: *provider_mod.Keys, tracer: *trace.Tracer, out: *Io.Writer, prompt_text: []const u8) !void {
- if (@import("goal_pacing.zig").oneshotSlashRefusal(prompt_text)) |why| std.process.fatal("{s}", .{why}); // usage error, not a prompt
- main_mod.unattended = true;
- @import("run_idle.zig").enabled = true; // nothing wakes a finished one-shot: wait for its background work
- @import("named_work.zig").rememberOn(root, prompt_text);
- root.in = null; // gate: deny instead of prompt; ask_user: self-decide
- root.out = null; // tool progress → stderr; stdout carries only the answer
- root.stream_quiet = true;
- // stderr only: same class of "process is live" as Pi's JSONL session line.
- // Eval first_out used to wait for the call-2 stdout pulse (ADR 0046).
- std.debug.print("calling {s}\n", .{root.provider.model});
- const ultracode_msg = try shapes.applyUltracodeSteering(arena, prompt_text, prompt_text, prompts.ultracodeActive(root));
- if (ultracode_msg.explicit) {
- tracer.note("ultracode", prompt_text[0..@min(prompt_text.len, 120)]);
- if (telemetry.g_telem) |t| t.ultracode();
- }
- const goal_note = try repl_glue.goalSteeringNote(arena, root.goal);
- const eval_note = try repl_glue.evalSteeringNote(
- arena,
- root.eval_cmd,
- root.eval_target,
- root.eval_judge != null,
- root.eval_verified,
- root.eval_repair_pending,
- eval_memory.load(root),
- );
- var oneshot_user = if (goal_note.len > 0) try std.fmt.allocPrint(arena, "{s}\n\n{s}", .{ ultracode_msg.text, goal_note }) else ultracode_msg.text;
- if (eval_note.len > 0) oneshot_user = try std.fmt.allocPrint(arena, "{s}\n\n{s}", .{ oneshot_user, eval_note });
- try root.messages.append(try @import("named_work.zig").userNudge(arena, root.provider.kind, oneshot_user));
- if (telemetry.g_telem) |t| t.beginTurn(@intCast(@min(prompt_text.len, std.math.maxInt(u32))), root.provider.model);
- // #502: --output-schema runs TWO-PHASE. A strict grammar on every message
- // pulls the model into answering immediately instead of touching tools
- // (graff-evals caught grok-4.6 guessing a file-inspection answer), so the
- // agentic phase runs unconstrained and one tools-off formatting turn then
- // restates the final answer under the schema — same conversation, so it
- // reads the real evidence.
- const pending_schema = root.output_schema;
- root.output_schema = null;
- var final_text = providers.runTurnWithFallback(root, keys, arena, null) catch |err| {
- // std.process.fatal does not unwind main's defers. Mirror their order:
- // join the fleet, reap jobs/pumps, then the terminal behavioral event.
- fleet.joinElites(io);
- jobs.jobsReap(gpa, io);
- // Flush buffered OTLP too: a fatal one-shot stays visible in ordinary telemetry.
- if (telemetry.g_telem) |t| t.flush();
- if (tracer.behavior) |behavior| behavior.finish(.failed);
- pricing.printUsageFooter(io); // #387/#389: fatal exits still owe cost accounting
- if (root.tools_used.count() > 0) std.debug.print("note: {d} tool call(s) completed before the failure; their work was not rolled back\n", .{root.tools_used.count()});
- switch (err) {
- error.FallbackConsentRequired => std.process.fatal("saved model unavailable; provider '{s}' is not allowlisted — run graff interactively, then /fallback allow {s}", .{ root.provider.id, root.provider.id }),
- error.ApiError => std.process.fatal("{s}", .{root.last_api_error orelse "api error"}),
- error.RunBudgetExhausted => @import("run_budget.zig").RunBudget.exhaustedFatal(if (root.run_budget) |b| b.max_model_calls else 0, &@import("scoring.zig").g_run_id), // #368
- else => |e| std.process.fatal("turn failed: {t}", .{e}),
- }
- };
- const had_schema = pending_schema != null;
- if (pending_schema) |schema_json| {
- root.output_schema = schema_json;
- // Gemini (via the gateway) accepts json_schema then ignores it, so the
- // #543 sox path never learns. Force schema-in-prompt + structured_output.
- if (std.mem.startsWith(u8, root.provider.model, "gemini")) root.sox_json_object = true;
- root.text_only = true;
- defer {
- root.text_only = false;
- root.output_schema = null;
- }
- try root.messages.append(try messages_mod.textMessage(arena, "user", "Return ONLY the final answer matching the enforced output schema: call the structured_output tool if it is offered, otherwise reply with a single JSON object. No prose."));
- if (telemetry.g_telem) |t| t.countTurn();
- final_text = providers.runTurnWithFallback(root, keys, arena, null) catch blk: {
- // Best-effort: schema-shaping must never lose a finished answer.
- std.debug.print("warning: output-schema formatting call failed — printing the unshaped answer\n", .{});
- break :blk final_text;
- };
- }
- const answer = if (had_schema) unwrapFencedJson(final_text) else final_text;
- // Live -p deltas already rode stdout (`printDelta`); reprinting would
- // duplicate the answer and push first_out to the footer.
- if (!root.streamed_text) try out.print("{s}\n", .{answer}) else try out.writeAll("\n");
- try out.flush();
- // Usage summary → stderr, so stdout stays exactly the answer.
- pricing.printUsageFooter(io);
- session.saveSession(root, arena, root.session_name) catch |err| {
- std.debug.print("⚠ session save failed: {s}\n", .{@errorName(err)});
- };
-
- // --worktree: checkpoint the one-shot's edits to the scratch branch too.
- // Headless swarm agents (graff -w name -p "task") are the main -w use
- // case — they must not exit with their work left uncommitted.
- jobs.worktreeAutoCommit(gpa, io, std.fmt.allocPrint(arena, "wip: {s}", .{title_mod.titleFromPrompt(prompt_text)}) catch "wip: graff oneshot");
- // One-shot returns here, before the REPL cleanup defer below is even
- // registered, so free the root's gpa-backed buffers explicitly (else a
- // tool-using one-shot leaks its tool log / render buffers on exit).
- @import("subagent.zig").agentJobsReap(gpa, io);
- @import("agent_render_cleanup.zig").deinit(root);
- root.tools_used.deinit(gpa);
- // Presence announced this session at boot (#469); a one-shot returns
- // before finalizeSession, so retire + free its gpa-owned globals here or
- // they reach the exit-time leak check — and our record would linger in
- // the registry until a peer's liveness probe reaps it.
- @import("session_globals.zig").release(gpa, io);
- // #396: the run is over. The frontend hands the terminal back and latches
- // its reader shut before main()'s teardown — a terminal-ownership move the
- // sink owns now, in EVERY mode, exactly as the old unconditional call did.
- engine_sink.writerSink(out).emit(io, .run_finished);
-}
+pub const runOneshotPrompt = @import("oneshot.zig").runOneshotPrompt;
/// Loads persisted command/tool approvals + lifecycle hooks + the MAP-Elites
/// agent-type registry (builtins + .harness/agents/*.{md,toml}), and prints the
@@ -566,27 +462,3 @@ pub fn startBackgroundLearning(gpa: Allocator, arena: Allocator, io: Io, environ
.skipped => {},
}
}
-
-/// `--output-schema` checks `json.load` the printed answer. Models that ignore
-/// json_schema often wrap the object in a markdown fence; strip that only.
-fn unwrapFencedJson(text: []const u8) []const u8 {
- const trimmed = std.mem.trim(u8, text, " \t\r\n");
- if (!std.mem.startsWith(u8, trimmed, "```")) return trimmed;
- var rest = trimmed[3..];
- if (std.mem.startsWith(u8, rest, "json")) rest = rest[4..];
- rest = std.mem.trimStart(u8, rest, " \t\r\n");
- if (std.mem.lastIndexOf(u8, rest, "```")) |end| return std.mem.trim(u8, rest[0..end], " \t\r\n");
- return rest;
-}
-
-test "unwrapFencedJson strips a markdown fence and leaves bare JSON alone" {
- try std.testing.expectEqualStrings("{\"a\":1}", unwrapFencedJson("```json\n{\"a\":1}\n```\n"));
- try std.testing.expectEqualStrings("{\"a\":1}", unwrapFencedJson("{\"a\":1}"));
-}
-
-test "one-shot and --json do not auto-init a learning store" {
- try std.testing.expect(!shouldAutoLearn(true, false));
- try std.testing.expect(!shouldAutoLearn(false, true));
- try std.testing.expect(!shouldAutoLearn(true, true));
- try std.testing.expect(shouldAutoLearn(false, false));
-}
diff --git a/src/session_start.zig b/src/session_start.zig
index 0b2df328..a1410533 100644
--- a/src/session_start.zig
+++ b/src/session_start.zig
@@ -523,7 +523,7 @@ pub fn initRegistryConsent(io: Io, gpa: Allocator, arena: Allocator, out: *Io.Wr
sink.emit(io, dimNotice(mcp_line));
}
const mcp_t0 = Io.Timestamp.now(io, .awake);
- var registry: mcp.Registry = if (connect_mcp and !skip_imported) ((mcp.Registry.init(gpa, io, mcp_config_path, global_path, home, json_mode or flags.oneshot_prompt != null or environ_map.get("GRAFF_REPL_DEBUG") != null, environ_map, defer_join) catch |err| inner: {
+ var registry: mcp.Registry = if (connect_mcp and !skip_imported) ((mcp.Registry.init(gpa, io, mcp_config_path, global_path, home, environ_map.get("GRAFF_REPL_DEBUG") != null, environ_map, defer_join) catch |err| inner: {
sink.emit(io, .{ .session_notice = .{ .text = try std.fmt.allocPrint(arena, "[mcp] init failed: {t} — continuing without MCP", .{err}) } });
if (telemetry.g_telem) |t| t.errorEvent("mcp", @errorName(err));
break :inner null;
diff --git a/src/term.zig b/src/term.zig
index d66f9402..a32e2062 100644
--- a/src/term.zig
+++ b/src/term.zig
@@ -525,8 +525,8 @@ test "#396 firewall: both completion paths release the terminal" {
// pin follows the emission, and a second pin holds the sink arm that turns
// it back into a release. Both halves have to exist or the run never gives
// the terminal back.
- const oneshot = @embedFile("session_run.zig");
- const answer_at = std.mem.indexOf(u8, oneshot, "session.saveSession(root, arena, root.session_name)").?;
+ const oneshot = @embedFile("oneshot.zig");
+ const answer_at = std.mem.lastIndexOf(u8, oneshot, "const saved = save(root, arena);").?;
const release_at = std.mem.indexOf(u8, oneshot, ".emit(io, .run_finished);").?;
try std.testing.expect(answer_at < release_at);
const sink = @embedFile("session_render.zig");