Skip to content

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

Python
40.0 KB
Raw Blame
//! Provider round trip and retry loop; focused policy helpers are re-exported below.

const std = @import("std");
const Io = std.Io;
const Value = std.json.Value;

const main_mod = @import("main.zig");
const Agent = @import("agent.zig").Agent;

const messages_mod = @import("messages.zig");

const http = @import("http.zig");
const http_headers = @import("http_headers.zig");
const postWatched = http.postWatched;
const RetryPlan = http.RetryPlan;

const tools_mod = @import("tools.zig");
const apiErrorMessage = tools_mod.apiErrorMessage;
const telemetry = @import("telemetry.zig");
const tool_spill = @import("tool_spill.zig"); // #409: did the cap preserve the bytes, or destroy them?
const run_budget_mod = @import("run_budget.zig");
const wire_messages = @import("messages.zig");
const policy = @import("agent_request_policy.zig");

const overflow = @import("agent_overflow.zig");
const errorCode = policy.errorCode;
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
// to fit and had no room left to generate (MiMo). Neither shape produces an
// error to keyword-match, so it is classified from the reported usage instead.
const recoverBehavioralOverflow = overflow.recoverBehavioralOverflow;
const retryAfterAuthRefresh = policy.retryAfterAuthRefresh;
const retryTransientServerError = policy.retryTransientServerError;

const context = @import("agent_context.zig");
pub const recordUsage = context.recordUsage;
pub const usageInt = context.usageInt;
pub const recordCost = context.recordCost;
pub const fullInputEstimateTokens = context.fullInputEstimateTokens;
pub const fullRequestEstimateTokens = context.fullRequestEstimateTokens;
pub const contextEstimate = context.contextEstimate;
pub const contextEstimateFromInputBytes = context.contextEstimateFromInputBytes;
pub const effectiveContextTokens = context.effectiveContextTokens;
pub const pairContextMeterWithCurrentLocal = context.pairContextMeterWithCurrentLocal;
pub const rebaseContextMeter = context.rebaseContextMeter;
pub const inputOverCompactThreshold = context.inputOverCompactThreshold;
pub const recordUsageResponses = context.recordUsageResponses;

const responses = @import("agent_responses.zig");
pub const ResponsesFailure = responses.ResponsesFailure;
pub const ResponsesResult = responses.ResponsesResult;
pub const parseResponses = responses.parseResponses;
pub const errorMessage = responses.errorMessage;
pub const errorRequestId = responses.errorRequestId;

pub const buildBody = @import("agent_request_body.zig").buildBody;
const codex_chain = @import("codex_chain.zig");

const req_stats = @import("req_stats.zig"); // GRAFF_REQ_STATS anatomy (session_settings arms req_stats.g_armed)
const scratch = @import("agent_request_scratch.zig");
const jitter = @import("retry_jitter.zig"); // #1274: every computed backoff is jittered upward

/// #390 — appended once, on the run's final admitted model call, right where
/// the tools disappear, so the model knows WHY and lands instead of retrying.
pub const landing_note =
    "[budget landing] This is the final model call this run's --max-model-calls budget admits, so " ++
    "no tools are offered. Land the answer NOW from the evidence already gathered: state what was " ++
    "completed and what was verified, then name what remains unchecked. Honestly-labeled partial " ++
    "results beat dying mid-tool-call.";

fn sayTypedApiError(self: *Agent, etype: []const u8, ecode: ?[]const u8, emsg: []const u8, request_id: ?[]const u8) !void {
    const rid = request_id orelse "";
    if (ecode) |c| {
        if (rid.len != 0) return self.sayApiError("api error ({s} {s}): {s} [{s}]", .{ etype, c, emsg, rid });
        return self.sayApiError("api error ({s} {s}): {s}", .{ etype, c, emsg });
    }
    if (rid.len != 0) return self.sayApiError("api error ({s}): {s} [{s}]", .{ etype, emsg, rid });
    return self.sayApiError("api error ({s}): {s}", .{ etype, emsg });
}

pub fn request(self: *Agent, tools_in: ?[]const u8) !std.json.ObjectMap {
    self.last_api_reauth = null;
    // Pool-thread Jev results become session state only on this owner thread.
    if (Agent.esc_cancel.load(.acquire) or @import("acp_engine.zig").cancel_flag.load(.acquire))
        self.jev_effort_pending.invalidate(self.io)
    else
        @import("jev_effort_state.zig").apply(self);
    var usage_attempts: @import("request_usage_attempts.zig").Ledger = .{};
    defer usage_attempts.finish(self.io, &@import("pricing.zig").g_cost);
    errdefer {
        if (@import("agent_async_tools.zig").started(self)) self.closeCodexWs();
        @import("agent_async_tools.zig").reset(self);
    }
    // Root and title requests rendezvous after launch-time CA loading.
    http.waitForClientReady(self.io);
    if (http.takeCaWarmFailure()) if (self.tracer) |tr| tr.note("ca_prewarm_failed", "CA bundle rescan failed; request will use lazy TLS initialization");
    var tools_now = tools_in;
    const stale = self.toolsJson();
    const joined = if (self.registry) |reg| @import("mcp_pages.zig").beforeRequest(reg) else false; // joins deferred starts, re-lists changed servers
    if (self.registry) |reg| if (!self.sub) @import("mcp_connect_notice.zig").drain(reg, @import("engine_sink.zig").forAgent(self), self.io); // ADR 0230
    const preloaded = @import("mcp_preload.zig").namedServers(self); // ADR 0231: a named server's schemas ride this request
    const withdrawn = @import("agent_catalog.zig").refreshMcp(self);
    if (joined or preloaded or withdrawn or @import("additional_tools.zig").staleCatalog(self)) {
        self.invalidateRootTools();
        try self.ensureRootTools(self.provider.kind);
        // The caller's snapshot is the catalog that just went stale. Send the
        // rebuilt one, or servers that joined miss this request and change
        // `tools` on the next, throwing away the prompt cache (ADR 0221).
        if (tools_now) |t| if (stale.len > 0 and t.ptr == stale.ptr) {
            tools_now = self.toolsJson();
        };
    }
    var budget_permit: ?run_budget_mod.Permit = null;
    if (self.run_budget) |budget| {
        const kind: run_budget_mod.CallKind = if (self.compaction_request) .compaction else self.call_kind;
        budget_permit = budget.acquire(self.io, self.depth, kind) catch |err| {
            self.last_api_error = switch (err) {
                error.RunBudgetExhausted => "model-call budget exhausted for this graff run — restart or raise --max-model-calls",
                error.AgentDepthExceeded => "agent depth limit reached (max depth 1)",
                else => @errorName(err),
            };
            if (self.tracer) |tr| tr.note("budget", self.last_api_error.?);
            return err;
        };
    }
    defer if (budget_permit) |*permit| permit.release();
    // #390 — the landing reserve's root half: the pool's FINAL admitted call
    // belongs to the answer. Offer no tools (compaction's trick) and say why,
    // so the model lands a text answer now instead of asking for a tool the
    // budget can never pay for — which is how the audit smoke died narrating.
    // compaction/title requests pass tools=null already and skip this whole.
    var tools = try @import("jev_tool.zig").refreshCatalogForRequest(self, tools_now);
    if (self.tracer) |tr| {
        if (tools) |t| if (t.len == 0) tr.note("tools", "empty catalog at request time (#695)");
    }
    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)");
        }
    };
    self.last_request_context_overflow = false;
    self.last_request_write_failed = false;
    self.last_usage_includes_output = false;
    var force = !self.review_mode and (self.strict or self.eval_cmd != null or self.named_work_nudges > 0) and tools != null;
    var stream_usage = true; // openai stream_options; dropped if rejected
    var auth_refreshed = false; // #148: at most one forced token refresh + retry
    // #124: reclaim last request's transient parse garbage FIRST, so everything
    // below (per-event parse trees, tool-arg parses) can use the scratch arena
    // for this request. Safe: all scratch data is
    // consumed before the next request(); messages/todos/prompts live on the
    // session arena.
    if (self.scratch_arena) |sa| scratch.reset(sa);
    // #148/#402: a login-sourced OAuth token expires mid-session and is minted
    // only at startup; pick up whatever is currently on disk before the call, so
    // a long session — or a subagent that inherited the token — never 401s over
    // a credential somebody has already replaced. Login-sourced keys only (env
    // keys untouched), and see refreshLoginKeyBeforeSend for why its transients
    // do NOT go on the scratch arena.
    policy.refreshLoginKeyBeforeSend(self);
    // #95: scrub any malformed function_call_output before it hits the wire.
    const message_arena = self.messageMutationAlloc();
    @import("history_wire.zig").prepare(message_arena, self.provider.kind, &self.messages);
    // ADR 0221: on the ChatGPT plan route loaded tools ride additional_tools items, so `tools` never changes.
    if (!self.compaction_request and !self.server_compaction_request) @import("additional_tools.zig").sync(self);
    // #193/#440: window-proportional backstop for resumed legacy or externally
    // appended outputs; runTools already meets the durable handle contract.
    const spills_before = tool_spill.spillCount();
    const capped = self.capOversizedToolOutputs(self.provider.perOutputCap());
    if (capped > 0) {
        // #202: don't truncate silently. The model already sees an inline marker;
        // surface it to the trace and (interactively) to the user too. #409: say
        // which of the two happened — the elided bytes are only GONE when there
        // was no durable session to spill them to.
        const spilled = tool_spill.spillCount() > spills_before;
        if (self.tracer) |tr| tr.note("context", if (spilled)
            "capped an oversized tool output before send (full bytes kept as a session artifact)"
        else
            "capped an oversized tool output before send");
        if (!main_mod.json_mode and !self.sub) {
            if (spilled)
                self.say("[tool output over this model's per-result cap — {d} bytes elided before send; the full output is in this session's artifacts and the model has the path (#409)]\n", .{capped}) catch {}
            else
                self.say("[tool output over this model's per-result cap — truncated {d} bytes before send (#193)]\n", .{capped}) catch {};
        }
    }
    var context_retried = false; // #193: at most one in-turn overflow recovery per request
    var encrypted_restores: u8 = 0;
    // #56: bounded stream-stall / drop reconnect budget (codex's stream_max_retries analog), outside the rebuild loop so a WS reanchor can't reset it.
    self.stall = .{}; // #680: a fresh widen ladder + tripped budget per request
    var stall_retries: usize = 0;
    var drop_retries: usize = 0; // #1639: a peer close earns its own, larger budget (stream_reconnect.zig)
    const reconnect = @import("stream_reconnect.zig");
    var server_retries: usize = 0; // #opencode-parity: bounded retries for a transient in-stream server overload
    var openai404_retries: usize = 0; // #opencode-parity: bounded retries for OpenAI's spurious model 404s
    const max_openai404_retries: usize = 2;
    var gw_retry = policy.GatewayRetryState{}; // #gateway-artifact state (agent_gateway_retry.zig)
    var tls_failures: usize = 0; // Construction-only budget survives every body/WS rebuild.
    @import("cache_ttl.zig").begin(self); // #1320: before request_started moves
    var call: @import("model_call.zig").Call = .{}; // #1665: pairs every started attempt
    errdefer call.fail(self, false);
    rebuild: while (true) {
        if (@import("agent_async_tools.zig").started(self)) return error.AsyncToolStreamFailed;
        const live = self.usesLiveTransport();
        self.streamed_text = false;
        self.streamed_args = .none;
        const body = try self.buildBody(tools, force, live, stream_usage);
        defer self.gpa.free(body);
        if (!self.sub) {
            const hud = @import("prompt_cache_hud.zig");
            // Hash what goes out: where loaded tools ride announcements, the tail is not sent (ADR 0221).
            const at = @import("additional_tools.zig");
            const sent = if (tools) |t| (if (at.active(self.provider)) at.stripTail(self, self.scratchAlloc(), t) else t) else "";
            hud.noteRequest(self.io, self.systemPrompt(), sent);
            var aff_buf: [96]u8 = undefined;
            hud.noteAffinity(
                http_headers.promptCacheKey(self.io, self.label, self, &aff_buf),
                std.mem.eql(u8, self.provider.id, "xai"),
                self.provider.kind == .responses,
            );
        }
        // GRAFF_REQ_STATS=1: per-call request anatomy + body dumps (req_stats.zig).
        req_stats.report(self.io, body, tools, self.sys_normal);
        const t0: Io.Timestamp = .now(self.io, .awake);
        self.request_started = t0;
        self.first_token_traced = false;
        call.start(self);
        // HTTP calls are flaky: a kept-alive connection the server closed
        // (HttpConnectionClosing), a reset, a truncated TLS read. Retry a
        // few times with a fresh connection; on persistent failure surface
        // error.ApiError so the REPL returns to the prompt, never crashes.
        const resp_body = blk: {
            var ordinary_attempts: usize = 0;
            var retry_limit: ?usize = null;
            while (true) {
                ordinary_attempts += 1;
                var conv_buf: [96]u8 = undefined;
                const conv = http_headers.requestCacheKey(self.io, self.label, self, self.provider, &conv_buf);
                usage_attempts.begin();
                const attempt_body = if (live)
                    self.postLive(body)
                else
                    postWatched(self.gpa, self.io, self.client, self.provider, body, conv);
                if (attempt_body) |ok| break :blk ok else |err| {
                    if (@import("agent_async_tools.zig").started(self)) return err;
                    if (err == error.ModelLoop or err == error.ReplyRunaway) return err; // #743: repeated prose ends the turn WITHOUT retry (tier2 model-loop-bounded-prose)
                    if (self.streamed_text) if (self.out) |w| {
                        w.writeAll("\n") catch {};
                        w.flush() catch {};
                    };
                    self.streamed_text = false;
                    self.streamed_args = .none;
                    // Esc and task cancellation are deliberate stops, not flaky
                    // transport. In particular, session-close cancellation of a
                    // detached title must not launch a replacement request.
                    if (err == error.Interrupted) return error.Interrupted;
                    if (err == error.Steered) if (@import("steer_now.zig").supersede(self)) continue :rebuild;
                    if (err == error.Canceled) return error.Canceled;
                    if (err == error.StreamTooLong or err == error.StreamEventDeadline) return err; // deterministic event bounds: replay cannot repair them
                    if (quota.transportCode(err)) |code| {
                        if (try quota.handle(self, "", code, "", &auth_refreshed)) continue;
                        return err;
                    }
                    // #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
                    // reconnect on a fresh stream and re-send the full request,
                    // like codex's stream_max_retries (restart the request; the
                    // partial was never committed to history). Bounded; on
                    // exhaustion end the turn recorded as a stall/drop, never a
                    // user Esc (#134). The budget lives outside the rebuild loop
                    // so a WS reanchor can't reset it.
                    if (err == error.StreamStalled or err == error.StreamDropped) {
                        const stalled = err == error.StreamStalled;
                        const what: []const u8 = if (stalled) "stream stalled" else "stream dropped";
                        const retries = if (stalled) &stall_retries else &drop_retries;
                        if (retries.* < reconnect.maxRetries(stalled)) {
                            retries.* += 1;
                            // #56: give a fresh WS one reconnect; if it stalls again,
                            // fall back to the reliable SSE transport for the rest of
                            // the session — codex's WS→SSE fallback, and consistent
                            // with how a WS transport error is already handled (ws_off).
                            if (stall_retries + drop_retries > 1) self.ws_off = true;
                            if (self.tracer) |tr| tr.note("stream_retry", what);
                            if (telemetry.g_telem) |t| t.errorEvent("stream_retry", what);
                            @import("agent_stream.zig").noteStallRetry(self, stall_retries); // #680: clears the partial (fresh stream, no concat) + widens the between-lines budget (stalls only)
                            self.closeCodexWs(); // tear down the dead WS + null codex_prev_id for a full re-send (no-op off codex WS)
                            self.sleepInterruptible(jitter.ms(self.io, reconnect.backoffMs(stalled, retries.*))) catch return error.Interrupted; // #1274: desync parallel reconnects
                            continue :rebuild;
                        }
                        // Budget gone: the turn is ending. Mid-turn cuts stayed silent.
                        @import("engine_sink.zig").forAgent(self).emit(self.io, .{ .transport_aborted = .{ .reason = if (stalled) .stalled else .dropped, .turn_ending = true } });
                        if (stalled) {
                            self.last_api_error = @import("agent_stream.zig").stallGiveUpMessage(self, reconnect.max_stall_retries); // #680: reports the wait that tripped, not the configured total
                            if (telemetry.g_telem) |t| t.errorEvent("stream_stall", self.last_api_error orelse "stream stalled");
                            if (self.tracer) |tr| tr.note("stream_stall", self.last_api_error orelse "stream stalled");
                            return error.StreamStalled;
                        }
                        self.last_api_error = "stream dropped: the provider closed the connection before the response completed — ended the turn after reconnect attempts";
                        if (telemetry.g_telem) |t| t.errorEvent("stream_dropped", self.last_api_error.?);
                        if (self.tracer) |tr| tr.note("stream_dropped", self.last_api_error.?);
                        return error.StreamDropped;
                    }
                    // (#codex-ws) postLive already closed the dead WS session —
                    // rebuild (full input, no previous_response_id) + retry via
                    // a fresh WS instead of replaying the stale delta over SSE.
                    // codex_prev_id is now null, so this can't recur this request.
                    if (err == error.CodexWsReanchor) continue :rebuild;
                    // #opencode-parity: OpenAI proper spuriously 404s available models.
                    // Retry a bounded number of times; a PERSISTENT 404 is a real
                    // model-not-found, so surface it (with the body) as an ApiError whose
                    // message drives cross-provider failover, not a generic flake give-up.
                    if (err == error.OpenAiFlaky404) {
                        if (openai404_retries < max_openai404_retries) {
                            openai404_retries += 1;
                            try self.say("[openai 404 (often spurious) — retrying ({d}/{d})]\n", .{ openai404_retries, max_openai404_retries });
                            if (self.tracer) |tr| tr.note("retry", "openai 404");
                            self.sleepInterruptible(jitter.ms(self.io, RetryPlan.delayMs(false, openai404_retries - 1))) catch return error.Interrupted;
                            continue;
                        }
                        self.last_api_error = std.fmt.allocPrint(self.arena, "openai 404 (model not found?): {s}", .{if (main_mod.g_5xx_body_len > 0) main_mod.g_5xx_body_buf[0..main_mod.g_5xx_body_len] else "not found"}) catch "openai 404: model not found";
                        if (telemetry.g_telem) |t| t.errorEvent("openai_404", self.last_api_error orelse "openai 404");
                        return error.ApiError;
                    }
                    const construction_tls = err == error.TlsRequestConstructionFailed or err == error.TlsRequestConstructionCaWarmFailed;
                    if (construction_tls) {
                        ordinary_attempts -= 1;
                        tls_failures += 1;
                    }
                    const attempt = if (construction_tls) tls_failures - 1 else ordinary_attempts - 1;
                    const throttled = err == error.RateLimited or err == error.ServerError;
                    const max_attempts = if (construction_tls) RetryPlan.tls_construction_attempts else retry_limit orelse RetryPlan.maxAttempts(throttled);
                    if (!construction_tls) retry_limit = max_attempts;
                    // 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 (construction_tls) if (self.tracer) |tr| tr.note(
                        "tls_request_construction",
                        if (err == error.TlsRequestConstructionCaWarmFailed) "rotated shared HTTP client generation; replacement CA prewarm failed" else "rotated shared HTTP client generation",
                    );
                    if (attempt + 1 < max_attempts) {
                        if (throttled) {
                            // #retry-after: prefer the provider's Retry-After
                            // (429/503) over our computed backoff, capped — like
                            // opencode, so we wait at least as long as the server asked.
                            // #1274: jitter only adds on top, so parallel agents desync.
                            const server_ra = main_mod.g_retry_after_ms;
                            const delay_ms = jitter.ms(self.io, if (server_ra > 0) server_ra else RetryPlan.delayMs(throttled, attempt));
                            const ra_note: []const u8 = if (server_ra > 0) " (server retry-after)" else "";
                            const what: []const u8 = if (err == error.RateLimited) "rate limited (429)" else "server error (5xx)";
                            // Never echo the captured 429/5xx body. Envelopes from
                            // OpenRouter and similar include user ids, BYOK/settings
                            // URLs, and routing docs. Classifiers still read g_5xx_body_buf.
                            try self.say("[{s}{s} — retrying in {d}s ({d}/{d})]\n", .{ what, ra_note, delay_ms / 1000, attempt + 1, max_attempts });
                            policy.noteRetry(self, what);
                            self.sleepInterruptible(delay_ms) catch return error.Interrupted;
                        } else {
                            // Ordinary flakes keep six attempts; only construction TLS gets a longer outage window.
                            const delay_ms = jitter.ms(self.io, RetryPlan.delayMs(throttled, attempt));
                            if (scratch.showRecoveredTransportRetry(self.call_kind))
                                @import("turn_chrome.zig").emitRetryNotice(self.io, @errorName(err), attempt + 1, max_attempts);
                            // Same trace breadcrumb the 429/5xx branch leaves: a
                            // transport-flake retry is otherwise invisible in the
                            // session trace, hiding how flaky a provider really is.
                            policy.noteFlake(self, &gw_retry, err);
                            self.sleepInterruptible(delay_ms) catch return error.Interrupted;
                        }
                        continue;
                    }
                    // A refused loopback connection means the local server (oMLX, LM Studio, mlx-lm) is not running: name it.
                    const down: []const u8 = if (err == error.ConnectionRefused and @import("keys_cli.zig").isLocalUrl(self.provider.url)) self.provider.url else "";
                    try self.say("[request failed: {t}{s}{s} — giving up this turn]\n", .{ err, if (down.len > 0) " at " else "", down });
                    // Preserve whether this was provider throttling or a transport failure in the failed turn's JSON/trajectory (#86).
                    const failure_kind = if (err == error.RateLimited) "rate limited (429)" else if (err == error.ServerError) "server error (5xx)" else "network error";
                    self.last_api_error = std.fmt.allocPrint(self.arena, "{s}: {s}{s}{s} (gave up after {d} attempts)", .{ failure_kind, @errorName(err), if (down.len > 0) " at " else "", down, max_attempts }) catch null;
                    self.last_request_write_failed = std.mem.eql(u8, @errorName(err), "WriteFailed");
                    try scratch.preserveFailedRequest(self);
                    if (telemetry.g_telem) |t| t.errorEvent("net", @errorName(err));
                    if (self.tracer) |tr| tr.api(self.label, self.sub, self.provider.model, 0, body.len, 0, 0, 0, true);
                    return error.ApiError;
                }
            }
        };
        defer self.gpa.free(resp_body);
        const ms: i64 = t0.untilNow(self.io, .awake).toMilliseconds();
        if (!live) self.traceFirstToken();

        // object — pull the final `response` out of it (or an error).
        if (self.provider.kind == .responses) {
            const r = self.parseResponses(resp_body) catch {
                // Preserve a useful last_api_error without copying an unparsed
                // provider envelope: it may contain echoed request/auth data.
                const diagnostic = try responses.failureDiagnostic(self.arena, self.provider.id, .{ .message = "unparseable codex response" });
                try self.sayApiError("{s}", .{diagnostic});
                if (self.tracer) |tr| tr.api(self.label, self.sub, self.provider.model, ms, body.len, resp_body.len, 0, 0, true);
                return error.ApiError;
            };
            switch (r) {
                .ok => |obj| {
                    if (!self.compaction_request) self.compact_transport_failures = 0;
                    usage_attempts.completed();
                    @import("agent_ws_steer.zig").billEnded(self, obj); // the responses a steer ended, before the last
                    @import("opaque_state_usage.zig").learn(self, obj); // #1686: before the meter reads the estimate
                    self.recordUsageResponses(obj, body.len);
                    @import("usage_trace.zig").noteReasoning(obj);
                    try @import("agent_async_tools.zig").join(self);
                    // #414: an empty output whose usage already fills the window
                    // is an overflow the provider never reported. Re-anchor like
                    // the error branch above: the recovery trims full history.
                    if (recoverBehavioralOverflow(self, obj, &context_retried)) {
                        self.closeCodexWs();
                        continue :rebuild;
                    }
                    if (self.tracer) |tr| tr.api(self.label, self.sub, self.provider.model, ms, body.len, resp_body.len, self.last_context_tokens, self.last_cache_read, false);
                    call.finish(self, ms);
                    try @import("agent_model_loop.zig").checkResponse(self, obj);
                    return obj;
                },
                .err => |failure| {
                    const msg = failure.message;
                    const ws_error_frame = self.ws_api_error_pending;
                    self.ws_api_error_pending = false;
                    const diagnostic = try responses.failureDiagnostic(self.arena, self.provider.id, failure);
                    if (@import("agent_async_tools.zig").started(self)) {
                        try quota.afterToolsStarted(self, failure.code, msg, diagnostic);
                        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");
                        continue :rebuild;
                    }
                    if (@import("agent_encrypted_recovery.zig").recover(self, msg, failure.code, &encrypted_restores)) continue :rebuild;
                    // #174: a context-window rejection means the true input
                    // size blew past the wall while the chained meter lagged —
                    // and the rejected request never returns usage to correct
                    // it, so the meter would stay stuck under compact@ and the
                    // session would wedge (every retry resends the same
                    // oversized history). Pin the meter to the window so the
                    // ApiError compact-and-recover path engages.
                    if (recoverContextOverflow(self, msg, failure.code, &context_retried)) {
                        // Responses may have sent a previous_response_id delta.
                        // Re-anchor after the shared recovery trims full history.
                        self.closeCodexWs();
                        continue :rebuild;
                    }
                    // #402: a ChatGPT-backend 401 ("Provided authentication
                    // token is expired") lands here as a plain JSON error body,
                    // so the #148 reactive refresh further down — which only
                    // anthropic/openai bodies reach — never saw it. Auth-expired
                    // was terminal on this path: the session, and every
                    // auto-compaction it triggered, 401'd forever even after a
                    // successful /login.
                    if (retryAfterAuthRefresh(self, failure.authText(), &auth_refreshed)) {
                        // PR #195: a mid-turn resend must re-anchor — the chained
                        // WS meter desyncs otherwise — and the held socket was
                        // dialed with the stale bearer besides.
                        self.closeCodexWs();
                        continue :rebuild;
                    }
                    // Codex Responses reports capacity failures through this
                    // response.failed arm too. Keep it on the same bounded
                    // overload retry path as SSE and JSON error envelopes.
                    if (try policy.afterServerErrorOrParseReject(self, failure.etype, failure.code, msg, &server_retries, &gw_retry)) continue :rebuild; // #748: the class keeps invalid requests off the flake ladder
                    self.last_api_reauth = @import("auth_recovery.zig").forFailure(self.provider, failure.code, msg);
                    if (self.tracer) |tr| tr.api(self.label, self.sub, self.provider.model, ms, body.len, resp_body.len, 0, 0, true);
                    try self.sayApiError("{s}", .{diagnostic});
                    return error.ApiError;
                },
            }
        }

        // Streamed anthropic/openai bodies are SSE too: reassemble them.
        // null → the body wasn't SSE (a JSON error envelope, or a
        // provider that ignored `stream`) — fall through to the regular
        // parse, which also handles the soft-strict retry.
        if (live) {
            if (try self.assembleStream(resp_body)) |root| {
                if (root.get("type")) |t| if (t == .string and std.mem.eql(u8, t.string, "error")) {
                    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 = errorCode(root);
                    if (try quota.handle(self, etype, ecode, emsg, &auth_refreshed)) continue;
                    if (@import("interactions_chain.zig").dropRejected(self, body)) continue; // stored Interaction gone → full replay
                    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;
                    if (self.tracer) |tr| tr.api(self.label, self.sub, self.provider.model, ms, body.len, resp_body.len, 0, 0, true);
                    try sayTypedApiError(self, etype, ecode, emsg, errorRequestId(root));
                    return error.ApiError;
                };
                if (self.provider.kind == .openai) {
                    const usage = root.get("usage");
                    if (usage == null or usage.? != .object) @import("pricing.zig").g_cost.missingUsage(self.io);
                }
                usage_attempts.completed();
                self.recordUsage(root, body.len);
                if (recoverBehavioralOverflow(self, root, &context_retried)) continue; // #414: silent overflow / upstream truncation → trim + retry
                if (!self.compaction_request) self.compact_transport_failures = 0;
                if (self.tracer) |tr| tr.api(self.label, self.sub, self.provider.model, ms, body.len, resp_body.len, self.last_context_tokens, self.last_cache_read, false);
                call.finish(self, ms);
                try @import("agent_model_loop.zig").checkResponse(self, root);
                return root;
            }
        }

        const resp = std.json.parseFromSliceLeaky(Value, self.messageMutationAlloc(), resp_body, .{
            .allocate = .alloc_always,
        }) catch {
            if (try scratch.retryKeepAliveOnly(self, resp_body, &server_retries)) continue;
            try self.sayApiError("unparseable response: {s}", .{resp_body[0..@min(resp_body.len, 400)]});
            return error.ApiError;
        };
        // Google's OpenAI-compat layer wraps its error envelope in a ONE-ELEMENT
        // ARRAY ([{"error":{…}}]). An unchecked `.object` here took down the
        // whole process on a response every other provider reports as an error,
        // so unwrap that shape and refuse any other non-object root cleanly.
        const root = switch (resp) {
            .object => |o| o,
            .array => |a| if (a.items.len == 1 and a.items[0] == .object) a.items[0].object else {
                try self.sayApiError("unexpected response shape: {s}", .{resp_body[0..@min(resp_body.len, 400)]});
                return error.ApiError;
            },
            else => {
                try self.sayApiError("unexpected response shape: {s}", .{resp_body[0..@min(resp_body.len, 400)]});
                return error.ApiError;
            },
        };

        if (root.get("type")) |t| if (t == .string and std.mem.eql(u8, t.string, "error")) {
            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 = errorCode(root);
            if (try quota.handle(self, etype, ecode, emsg, &auth_refreshed)) continue;
            if (@import("interactions_chain.zig").dropRejected(self, body)) continue; // stored Interaction gone → full replay
            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;
            if (self.tracer) |tr| tr.api(self.label, self.sub, self.provider.model, ms, body.len, resp_body.len, 0, 0, true);
            try sayTypedApiError(self, etype, ecode, emsg, errorRequestId(root));
            return error.ApiError;
        };
        if (apiErrorMessage(root)) |msg| {
            if (try quota.handle(self, "", errorCode(root), msg, &auth_refreshed)) continue;
            if (@import("interactions_chain.zig").dropRejected(self, body)) continue; // stored Interaction gone → full replay
            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
            // and retry once (kimi-code's buildAuth(true)). Give up only if the
            // fresh token also fails. No closeCodexWs — this branch is never on
            // the codex WS.
            if (retryAfterAuthRefresh(self, msg, &auth_refreshed)) continue;
            // #193 follow-up: recover an anthropic/openai context-window rejection
            // in-turn instead of failing the turn (before this only codex recovered;
            // anthropic and openai died). Shared with the two error branches above.
            // #203: openai-compatible errors arrive here (no top-level "type":"error"),
            // so pull the structured code from root.error.code for isContextOverflow — a
            // local provider whose message text we don't match on still recovers.
            if (recoverContextOverflow(self, msg, errorCode(root), &context_retried)) continue;
            if (try policy.afterServerErrorOrParseReject(self, "", errorCode(root), msg, &server_retries, &gw_retry)) continue;
            if (self.tracer) |tr| tr.api(self.label, self.sub, self.provider.model, ms, body.len, resp_body.len, 0, 0, true);
            if (errorRequestId(root)) |rid|
                try self.sayApiError("api error: {s} [{s}]", .{ msg, rid })
            else
                try self.sayApiError("api error: {s}", .{msg});
            return error.ApiError;
        }

        usage_attempts.completed();
        self.recordUsage(root, body.len);
        if (recoverBehavioralOverflow(self, root, &context_retried)) continue; // #414: same, on the non-streamed body
        if (!self.compaction_request) self.compact_transport_failures = 0;
        if (self.tracer) |tr| tr.api(self.label, self.sub, self.provider.model, ms, body.len, resp_body.len, self.last_context_tokens, self.last_cache_read, false);
        call.finish(self, ms);
        try @import("agent_model_loop.zig").checkResponse(self, root);
        return root;
    }
}