graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
Keep transport retries observable and report incomplete usage
Rach Pradhan53ec30a852c4
diff --git a/apps/native/components/site/ChatBubbles.tsx b/apps/native/components/site/ChatBubbles.tsxindex e3a3070e..064ec6ec 100644--- a/apps/native/components/site/ChatBubbles.tsx+++ b/apps/native/components/site/ChatBubbles.tsx@@ -1,5 +1,6 @@"use client";+import { usageCaption } from "@/lib/acp-usage";import { memo, useEffect, useLayoutEffect, useMemo, useRef, useState, type RefObject } from "react";import Markdown from "@/components/primitives/Markdown";import { BrowserLinkText } from "@/components/primitives/BrowserLinks";@@ -229,7 +230,10 @@ export const AssistantBody = memo(function AssistantBody({{turn.recap && turn.status === "done" && (<p className="mt-3 text-[12px] text-ink-3">{turn.recap}</p>)}- {turn.costUsd !== undefined && turn.status === "done" && (+ {turn.usage && (turn.status === "done" || turn.status === "error") && (+ <p aria-label="Usage since connection" className="mt-1 font-mono text-[11px] text-ink-3">{usageCaption(turn.usage)}</p>+ )}+ {!turn.usage && turn.costUsd !== undefined && turn.status === "done" && (<p className="mt-1 font-mono text-[11px] text-ink-3">${turn.costUsd.toFixed(4)}</p>)}{turn.status === "done" && turn.diffs.length > 0 && onReview && (diff --git a/apps/native/lib/acp-client.ts b/apps/native/lib/acp-client.tsindex 510c42d6..d2b3d3f6 100644--- a/apps/native/lib/acp-client.ts+++ b/apps/native/lib/acp-client.ts@@ -1,3 +1,4 @@+import { usageUpdate } from "./acp-usage";import { permissionRequest } from "./acp-permission";import { parseRpcLine, type AcpCommand, type AcpUpdate, type JsonRpcLine } from "./acp";import { liveAppearanceTokens } from "./appearance-note";@@ -118,6 +119,8 @@ export async function* prompt(}, true);let terminal = false;for await (const line of ndjson(res)) {+ const usage = usageUpdate(line, sessionId);+ if (usage) { yield usage; continue; }const permission = permissionRequest(line);if (permission) { yield { sessionUpdate: "gui_permission", permission }; continue; }if ("method" in line && line.method === "session/update") {@@ -154,6 +157,8 @@ export async function* idleUpdates(throw new Error(`ACP session/idle → ${res.status}: ${detail.slice(0, 240)}`);}for await (const line of ndjson(res)) {+ const usage = usageUpdate(line, sessionId);+ if (usage) { yield usage; continue; }const permission = permissionRequest(line);if (permission) { yield { sessionUpdate: "gui_permission", permission }; continue; }if ("method" in line && line.method === "session/update") yield line.params.update;diff --git a/apps/native/lib/acp-retry-notice.ts b/apps/native/lib/acp-retry-notice.tsindex 68d8d19d..f0d402f1 100644--- a/apps/native/lib/acp-retry-notice.ts+++ b/apps/native/lib/acp-retry-notice.ts@@ -6,5 +6,5 @@ const TRANSIENT_RETRY =/** Inner notice for TurnActivity, or null when the chunk is ordinary prose. */export function transientRetryNotice(text: string): string | null {const line = text.trim();- return TRANSIENT_RETRY.test(line) ? line.slice(1, -1) : null;+ return (TRANSIENT_RETRY.test(line) || /^\[network error: [A-Za-z0-9_]+ — retrying in \d+ms \(\d+\/\d+\)\]$/.test(line)) ? line.slice(1, -1) : null;}diff --git a/apps/native/lib/acp-usage.test.ts b/apps/native/lib/acp-usage.test.tsnew file mode 100644index 00000000..899516a7--- /dev/null+++ b/apps/native/lib/acp-usage.test.ts@@ -0,0 +1,58 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { readFileSync } from 'node:fs';+import { applyAcpUpdate, emptyTurn, finishAcpTurn, parseRpcLine } from './acp';+import { parseAcpUsage, usageCaption, usageUpdate } from './acp-usage';+const update = { sessionUpdate: 'gui_usage', scope: 'connection', usage_complete: false, cost_complete: false,+ cost_usd: null, known_cost_usd: 0.012, input_tokens: 14, cache_read_tokens: 4, cache_write_tokens: 0, output_tokens: 2,+ api_calls: 1, missing_usage_calls: 0, unreported_failed_attempts: 1, subscription_calls: 0, unpriced_calls: 0 };+test('ACP usage wire keeps known subtotals distinct from unknown totals through reducer', () => {+ const line = parseRpcLine(JSON.stringify({ jsonrpc: '2.0', method: '_codegraff/usage', params: { sessionId: 's', usage: update } }));+ assert.ok(line && 'method' in line);+ const turn = applyAcpUpdate(emptyTurn(), usageUpdate(line, 's')!);+ assert.equal(usageUpdate(line, 'different-session'), undefined);+ assert.equal(turn.usage?.costUsd, null);+ assert.equal(turn.usage?.input, 14);+ assert.equal(turn.costUsd, undefined);+ const caption = usageCaption(turn.usage!);+ assert.match(caption, /Total cost unknown/);+ assert.match(caption, /known metered subtotal \$0.0120/);+ assert.match(caption, /total tokens unknown/);+ assert.match(caption, /1 failed attempt/);+ assert.match(caption, /Usage since connection/);+ assert.match(caption, /4 cached read · 0 cache write/);+});+test('complete subscription tokens still do not imply free or known total billing', () => {+ const value = parseAcpUsage({ ...update, usage_complete: true, unreported_failed_attempts: 0, subscription_calls: 1, known_cost_usd: 0 })!;+ assert.equal(value.usageComplete, true);+ assert.equal(value.costUsd, null);+ assert.match(usageCaption(value), /subscription billing/);+ assert.doesNotMatch(usageCaption(value), /\$0\.0000/);+ assert.equal(parseAcpUsage({ ...update, input_tokens: -1 }), undefined);+ assert.equal(parseAcpUsage({ ...update, usage_complete: undefined }), undefined);+});+test('network retry indicator preserves previous prose and excludes quoted matches', () => {+ const prior = { ...emptyTurn(), text: 'Working.' };+ const text = '[network error: EndOfStream — retrying in 200ms (1/6)]\n';+ const turn = applyAcpUpdate(prior, { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text } });+ assert.equal(turn.text, 'Working.');+ assert.match(turn.retryNotice!, /EndOfStream/);+ const quoted = applyAcpUpdate(prior, { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: 'Example: ' + text } });+ assert.match(quoted.text, /Example:/);+ assert.equal(emptyTurn().usage, undefined);+});++test('real ACP failure and recovery receipts reach GUI without fabricated totals', { skip: !process.env.GRAFF_ACP_USAGE_CAPTURE }, () => {+ const lines = readFileSync(process.env.GRAFF_ACP_USAGE_CAPTURE!, 'utf8').trim().split('\n').map(line => JSON.parse(line));+ const receipts = lines.filter(line => line.method === '_codegraff/usage');+ assert.equal(receipts.length, 2);+ for (const [index, line] of receipts.entries()) {+ const turn = applyAcpUpdate(emptyTurn(), usageUpdate(line, line.params.sessionId)!);+ assert.equal(turn.usage?.failed, index === 0 ? 1 : 7);+ assert.equal(turn.usage?.calls, 1);+ assert.equal(turn.usage?.costUsd, null);+ assert.match(usageCaption(turn.usage!), /Total cost unknown/);+ }+ assert.ok(lines.some(line => line.error));+ assert.ok(lines.some(line => line.params?.update?.content?.text?.includes('network error:')));+});diff --git a/apps/native/lib/acp-usage.ts b/apps/native/lib/acp-usage.tsnew file mode 100644index 00000000..0523c7e5--- /dev/null+++ b/apps/native/lib/acp-usage.ts@@ -0,0 +1,40 @@+/** Codegraff extension, not an ACP v1 standard usage field. Counts cover this connection, including after loading historical messages. */+export type AcpUsage = {+ usageComplete: boolean; costComplete: boolean; costUsd: number | null; knownCostUsd: number;+ input: number; cached: number; written: number; output: number; calls: number;+ missing: number; failed: number; subscription: number; unpriced: number;+};+export function parseAcpUsage(value: Record<string, unknown>): AcpUsage | undefined {+ const names = ['input_tokens', 'cache_read_tokens', 'cache_write_tokens', 'output_tokens', 'api_calls', 'missing_usage_calls',+ 'unreported_failed_attempts', 'subscription_calls', 'unpriced_calls'] as const;+ if (value.scope !== 'connection' || typeof value.usage_complete !== 'boolean' || typeof value.cost_complete !== 'boolean') return;+ if (names.some(k => !Number.isSafeInteger(value[k]) || (value[k] as number) < 0)) return;+ if (typeof value.known_cost_usd !== 'number' || !Number.isFinite(value.known_cost_usd) || value.known_cost_usd < 0) return;+ const [input, cached, written, output, calls, missing, failed, subscription, unpriced] = names.map(k => value[k] as number);+ if (cached + written > input) return;+ const usageComplete = value.usage_complete && missing === 0 && failed === 0;+ const costComplete = value.cost_complete && usageComplete && subscription === 0 && unpriced === 0;+ const cost = value.cost_usd;+ if (costComplete && (typeof cost !== 'number' || !Number.isFinite(cost) || cost < 0)) return;+ return { usageComplete, costComplete, costUsd: costComplete ? cost as number : null,+ knownCostUsd: value.known_cost_usd, input, cached, written, output, calls, missing, failed, subscription, unpriced };+}+export function usageCaption(usage: AcpUsage): string {+ const amount = usage.costComplete ? `$${usage.costUsd!.toFixed(4)}` : 'Total cost unknown';+ const known = `${usage.input.toLocaleString('en-US')} input · ${usage.output.toLocaleString('en-US')} output tokens · ${usage.cached.toLocaleString('en-US')} cached read · ${usage.written.toLocaleString('en-US')} cache write tokens`;+ const notes = [usage.failed ? `${usage.failed} failed attempt(s) without usage` : '',+ usage.missing ? `${usage.missing} completed call(s) missing usage` : '',+ usage.subscription ? 'subscription billing' : '', usage.unpriced ? 'unpriced calls' : ''].filter(Boolean);+ const subtotal = !usage.costComplete && usage.knownCostUsd > 0 ? ` · known metered subtotal $${usage.knownCostUsd.toFixed(4)}` : '';+ return `Usage since connection: ${amount}${subtotal} · ${usage.usageComplete ? known : `known subtotal ${known}; total tokens unknown`}${notes.length ? ` · ${notes.join(' · ')}` : ''}`;+}++/** Normalize our negotiated wire extension into a client-only reducer event. */+export function usageUpdate(line: unknown, sessionId: string): ({ sessionUpdate: 'gui_usage' } & Record<string, unknown>) | undefined {+ if (!line || typeof line !== 'object') return;+ const message = line as { method?: unknown; params?: { sessionId?: unknown; usage?: unknown } };+ if (message.method !== '_codegraff/usage' || message.params?.sessionId !== sessionId) return;+ const usage = message.params.usage;+ if (!usage || typeof usage !== 'object' || Array.isArray(usage)) return;+ return { ...usage, sessionUpdate: 'gui_usage' };+}diff --git a/apps/native/lib/acp.ts b/apps/native/lib/acp.tsindex 8d98eaae..f9bed47e 100644--- a/apps/native/lib/acp.ts+++ b/apps/native/lib/acp.ts@@ -1,3 +1,4 @@+import { parseAcpUsage } from "./acp-usage";import { htmlArtifactId } from "./html-artifacts";import { parseContextMeter } from "./context-meter";import { boundToolDetail } from "./tool-detail";@@ -40,6 +41,7 @@ export type AcpUpdate =| { sessionUpdate: string; [key: string]: unknown };export type JsonRpcLine =+ | { jsonrpc?: string; method: "_codegraff/usage"; params: { sessionId: string; usage: Record<string, unknown> } }| { jsonrpc?: string; method: "session/update"; params: { sessionId?: string; update: AcpUpdate } }| { jsonrpc?: string; id: number | string; result: unknown }| { jsonrpc?: string; id: number | string; error: { code: number; message: string } };@@ -275,6 +277,7 @@ export function turnBlocks(text: string, tools: ToolRow[]): TurnBlock[] {export function applyAcpUpdate(turn: AssistantTurn, update: AcpUpdate): AssistantTurn {turn = { ...turn, lastUpdateAt: Date.now(), activityKind: update.sessionUpdate, connected: true };switch (update.sessionUpdate) {+ case "gui_usage": return { ...turn, usage: parseAcpUsage(update), costUsd: undefined };case "gui_context_meter": return { ...turn, contextMeter: parseContextMeter(update) };case "gui_turn_end": return { ...turn, stopReason: typeof update.stopReason === "string" ? update.stopReason : "end_turn" };case "agent_thought_chunk": {@@ -289,7 +292,7 @@ export function applyAcpUpdate(turn: AssistantTurn, update: AcpUpdate): Assistanconst text = stripCiteMarkup((update as { content?: AcpContent }).content?.text ?? "");const retry = transientRetryNotice(text);if (retry) {- return { ...turn, text: "", pendingBreak: false, status: "streaming", retryNotice: retry };+ return { ...turn, text: retry.startsWith("network error:") ? turn.text : "", pendingBreak: false, status: "streaming", retryNotice: retry };}const needsBreak = turn.pendingBreak && turn.text.length > 0 && !/\s$/.test(turn.text) && !/^\s/.test(text);return {diff --git a/apps/native/lib/graff-events.ts b/apps/native/lib/graff-events.tsindex c5942594..bc56a357 100644--- a/apps/native/lib/graff-events.ts+++ b/apps/native/lib/graff-events.ts@@ -95,6 +95,7 @@ export function parseAskOptions(input: unknown): string[] {export type TurnStatus = "thinking" | "streaming" | "ask" | "done" | "error" | "snapshot";export type AssistantTurn = {+ usage?: import("./acp-usage").AcpUsage;contextMeter?: import("./context-meter").ContextMeter;endedAt?: number;startedAt?: number;diff --git a/build.zig.zon b/build.zig.zonindex d7ff0bdd..8f91de04 100644--- a/build.zig.zon+++ b/build.zig.zon@@ -8,8 +8,8 @@.hash = "accord-0.0.0-aQy1J3iBAgADDHWM0hIAXhISKtQ0zasFN7TyLhI_tkI8",},.http_zig = .{- .url = "git+https://github.com/justrach/http-zig#9958d594a5d2e431fa7ff3d80a6a08105bacdc0d",- .hash = "http_zig-0.1.0-2CB7E2r-AgC2AJp4zQIzrr1qJRqne4EKdbgHl7oAo2Tt",+ .url = "git+https://github.com/justrach/http-zig#459e8eb2a6227cce937549a6d656ca5049d4fe63",+ .hash = "http_zig-0.1.0-2CB7ExwFAwBn4Hk9aRpSLLkhMyIAruz65-IpVlCmHtn8",},},.paths = .{""},diff --git a/docs/adr/0182-acp-connection-usage-is-an-extension.md b/docs/adr/0182-acp-connection-usage-is-an-extension.mdnew file mode 100644index 00000000..91818475--- /dev/null+++ b/docs/adr/0182-acp-connection-usage-is-an-extension.md@@ -0,0 +1,39 @@+# 0182. ACP connection usage is an extension++Status: accepted++## Decision++Expose cumulative usage since the current connection through the custom+`_codegraff/usage` notification, advertised in `agentCapabilities._meta` under+`codegraff/usage`. Its parameters bind the receipt to `sessionId` and contain a+`usage` object with `scope: "connection"`. This is a Codegraff extension, not a+new member of the standard ACP session-update union.++Emit the receipt after the provider turn returns, including failure and+cancellation, after request uncertainty accounting has settled. Serialize the+whole notification under the existing shared output lock. Delivery is best-effort+and deferred until after turn tracing and checkpoint work; a disconnected client+cannot replace the original outcome with a metadata-write error. Historical conversation+loading does not restore billing totals; clients label the reading "Usage since+connection" rather than implying an all-time session bill.++Token fields are known subtotals. Include cached-read and cache-write counts,+completed calls missing usage, and failed request attempts without usage.+`usage_complete` is false whenever either unknown-usage counter is nonzero.+`cost_usd` is null unless usage and pricing are complete; subscription or unpriced+calls do not imply a zero bill. `known_cost_usd` remains a separate known metered+subtotal. Clients must not derive context occupancy from these billing counters.++The desktop client accepts usage only for its active session, normalizes it to a+client-only reducer event, and displays incomplete totals explicitly. New turns+start without a previous usage receipt. Network retry notices already emitted by+the harness appear in the retry indicator rather than answer prose. Existing+provider retry behavior and request budgets remain unchanged.++## Validation++Tests cover wire serialization, uncertainty after real failed and recovered+requests, terminal-error delivery, client session binding, known subtotals,+subscription billing, cache counts, and retry-notice rendering. The integration+fixture uses only a local scripted HTTP server.diff --git a/docs/adr/0183-request-policy-owns-ambiguous-retries.md b/docs/adr/0183-request-policy-owns-ambiguous-retries.mdnew file mode 100644index 00000000..4012d011--- /dev/null+++ b/docs/adr/0183-request-policy-owns-ambiguous-retries.md@@ -0,0 +1,29 @@+# 0183. Request policy owns ambiguous retries++Status: accepted++## Decision++A send failure does not prove that a request failed to reach the server.+The HTTP/2 streaming transport must return ambiguous failures to the request+policy instead of replaying the body or silently switching to HTTP/1.1.++HTTP/1.1 fallback remains available before a request is sent, or when a valid+GOAWAY or REFUSED_STREAM response proves the stream was not processed. A+malformed GOAWAY does not provide that proof, and later GOAWAY frames cannot+raise the last accepted stream limit.++The existing request policy still controls bounded retries and backoff. Its+attempt ledger marks failed attempts without usage as unknown, and its retry+events remain observable. This is not an exactly-once guarantee: retrying an+ambiguously delivered request can repeat remote work.++## Validation++Unit tests cover fallback classification and GOAWAY handling. A local fault+fixture injects an error after the body flush and verifies that recovery passes+through the request policy and its uncertainty ledger. The dependency also+reconnects before reusing a session whose failed connection was torn down.++Run `python3 scripts/test-acp-http2-retry.py` after `zig build` to exercise the+pinned dependency through local TLS, HTTP/2, and ACP without provider calls.diff --git a/docs/adr/README.md b/docs/adr/README.mdindex 1073fc63..c78c1f35 100644--- a/docs/adr/README.md+++ b/docs/adr/README.md@@ -207,6 +207,8 @@ record only when you need the evidence or the edge cases.| [0180](0180-acp-permissions-belong-to-the-client.md) | ACP permission decisions belong to the active client and request; cancellation never grants approval. || [0181](0181-acp-load-replays-saved-conversation.md) | Live ACP loads saved conversations in their selected workspace and replays history without rerunning tools. |+| [0182](0182-acp-connection-usage-is-an-extension.md) | Connection-scoped ACP usage preserves unknown totals through a custom notification; network retries remain activity indicators. |+| [0183](0183-request-policy-owns-ambiguous-retries.md) | Ambiguous HTTP/2 failures return to the request retry policy so attempts and unknown usage remain observable. |## When to write onediff --git a/scripts/eval/http2-retry-mock.cjs b/scripts/eval/http2-retry-mock.cjsnew file mode 100644index 00000000..37650b2e--- /dev/null+++ b/scripts/eval/http2-retry-mock.cjs@@ -0,0 +1,47 @@+// Offline ACP retry peer: records complete POST bodies and serves one SSE reply.+const http2 = require('node:http2');+const fs = require('node:fs');+const crypto = require('node:crypto');+const [key, cert, log] = process.argv.slice(2);+const record = row => fs.appendFileSync(log, JSON.stringify(row) + '\n');+const server = http2.createSecureServer({+ key: fs.readFileSync(key), cert: fs.readFileSync(cert), allowHTTP1: true,+});+let sessions = 0;+const reply = 'data: {"choices":[{"index":0,"delta":{"content":"OK"},"finish_reason":null}]}\n\n' ++ 'data: {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}\n\n' ++ 'data: {"choices":[],"usage":{"prompt_tokens":10,"completion_tokens":2,"total_tokens":12}}\n\n' ++ 'data: [DONE]\n\n';+function post(protocol, body, extra) {+ record({event:'post', protocol, bytes:Buffer.byteLength(body),+ sha256:crypto.createHash('sha256').update(body).digest('hex'),+ atMs:Number(process.hrtime.bigint() / 1000000n), ...extra});+}+server.on('session', session => {+ session.fixtureId = ++sessions;+ session.on('error', () => {});+ record({event:'session', id:sessions, alpn:session.socket.alpnProtocol});+});+server.on('stream', (stream, headers) => {+ const session = stream.session.fixtureId;+ stream.on('error', () => {});+ let body = '';+ stream.on('data', chunk => { body += chunk; });+ stream.on('end', () => {+ post('h2', body, {session, stream:stream.id,+ method:headers[':method'], path:headers[':path']});+ try { stream.respond({':status':200,'content-type':'text/event-stream'}); stream.end(reply); }+ catch (_) { /* The injected client failure may close its stream. */ }+ });+});+server.on('request', (req, res) => {+ if (req.httpVersionMajor !== 1) return;+ let body = '';+ req.on('data', chunk => { body += chunk; });+ req.on('end', () => {+ post('h1', body, {method:req.method, path:req.url});+ res.writeHead(200, {'content-type':'text/event-stream'}); res.end(reply);+ });+});+server.on('tlsClientError', error => record({event:'tls-error', code:error.code}));+server.listen(0, '127.0.0.1', () => console.log(server.address().port));diff --git a/scripts/test-acp-http2-retry.py b/scripts/test-acp-http2-retry.pynew file mode 100644index 00000000..c5e86b9b--- /dev/null+++ b/scripts/test-acp-http2-retry.py@@ -0,0 +1,148 @@+#!/usr/bin/env python3+"""Offline ACP regression for an ambiguous HTTP/2 failure after POST flush.++Builds with a verified copy of the pinned http-zig dependency. Only the local+CA trust source and a one-shot post-flush fault are injected into that copy.+The production harness and retry policy are used unchanged.+"""+import importlib.util+import json+from pathlib import Path+import queue+import re+import shutil+import subprocess+import tempfile+import threading+import time++REPO = Path(__file__).resolve().parents[1]+spec = importlib.util.spec_from_file_location('acp_http2_fixture', REPO/'scripts/test-acp-http2.py')+fixture = importlib.util.module_from_spec(spec)+spec.loader.exec_module(fixture)+++def build(root):+ manifest = (REPO/'build.zig.zon').read_text()+ expected = re.search(r'\.http_zig\s*=\s*\.\{.*?\.hash\s*=\s*"([^"]+)"', manifest, re.S).group(1)+ source = REPO/'zig-pkg'/expected+ assert source.is_dir(), 'Run zig build first to fetch the pinned HTTP/2 dependency'+ actual = fixture.run(['zig', 'fetch', str(source)], cwd=REPO).stdout.strip()+ assert actual == expected, 'Pinned HTTP/2 dependency contents changed'+ packages = root/'packages'+ packages.mkdir()+ for package in (REPO/'zig-pkg').iterdir():+ if package.name == expected:+ shutil.copytree(package, packages/package.name)+ else:+ (packages/package.name).symlink_to(package.resolve(), target_is_directory=True)+ dep = packages/expected/'src'+ session = dep/'session.zig'+ contents = session.read_text()+ site = ' try self.ca.rescan(self.gpa, self.io, now);'+ assert contents.count(site) == 1, 'Review CA seam after dependency update'+ session.write_text(contents.replace(site, site + '\n try self.ca.addCertsFromFilePathAbsolute(self.gpa, self.io, now, ' + json.dumps(str(root/'ca.pem')) + ');'))+ conn = dep/'conn.zig'+ contents = conn.read_text()+ start = contents.index(' pub fn startLines(self: *Conn, req: Request) !LineStream {')+ site = ' try self.sendBody(sid, req.body);'+ position = contents.index(site, start)+ assert contents.find(site, position + len(site), contents.index('\n }', start)) == -1+ contents = contents[:position + len(site)] + '\n // Test-only fault after the complete POST flush.\n if (!retry_fault_once.swap(true, .acq_rel)) return error.EndOfStream;' + contents[position + len(site):]+ contents = contents.replace('const std = @import("std");', 'const std = @import("std");\nvar retry_fault_once: std.atomic.Value(bool) = .init(false);', 1)+ conn.write_text(contents)+ fixture.run(['zig', 'build', '--system', str(packages), '--cache-dir', str(root/'cache'),+ '-p', str(root/'install')], cwd=REPO, timeout=240)+ return root/'install/bin/graff'+++def exercise(root, binary):+ case = root/'case'+ case.mkdir()+ (case/'mcp.json').write_text('{"mcpServers":{}}')+ shim = case/'bin'+ shim.mkdir()+ (shim/'security').write_text('#!/bin/sh\nexit 44\n')+ (shim/'security').chmod(0o700)+ log = root/'server.jsonl'+ log.touch()+ server = worker = None+ with (root/'server-stderr').open('w') as server_error, (root/'worker-stderr').open('w') as worker_error:+ try:+ server = subprocess.Popen(['node', str(REPO/'scripts/eval/http2-retry-mock.cjs'),+ str(root/'server.key'), str(root/'server.pem'), str(log)],+ stdout=subprocess.PIPE, stderr=server_error, text=True,+ start_new_session=True)+ ports = queue.Queue()+ threading.Thread(target=lambda: ports.put(server.stdout.readline()), daemon=True).start()+ port = int(ports.get(timeout=10))+ env = dict(HOME=str(case), PATH=str(shim)+':/usr/bin:/bin', TERM='dumb',+ AI_GATEWAY_API_KEY='fixture', GRAFF_VERCEL_URL=f'https://localhost:{port}/v1/chat/completions',+ GRAFF_MCP_CONFIG=str(case/'mcp.json'), GRAFF_HTTP2='1', GRAFF_NO_TELEMETRY='1',+ GRAFF_FLEET='off', GRAFF_NO_ADOPT='1', GRAFF_NO_SMOLIFY='1', GRAFF_NO_CODEDB_GUARD='1')+ worker = subprocess.Popen([str(binary), 'acp', '--model', 'vercel', '--yolo'],+ cwd=case, env=env, stdin=subprocess.PIPE, stdout=subprocess.PIPE,+ stderr=worker_error, text=True, start_new_session=True)+ events = queue.Queue()++ def read_events():+ for line in worker.stdout:+ events.put(json.loads(line))+ events.put(None)++ threading.Thread(target=read_events, daemon=True).start()++ def call(method, params, identifier, timeout=35):+ worker.stdin.write(json.dumps({'jsonrpc':'2.0', 'id':identifier, 'method':method, 'params':params})+'\n')+ worker.stdin.flush()+ deadline = time.monotonic() + timeout+ updates = []+ while True:+ event = events.get(timeout=max(0, deadline-time.monotonic()))+ assert isinstance(event, dict), f'ACP exited before response {identifier}'+ if event.get('id') == identifier:+ return event, updates+ assert 'id' not in event, f'Unexpected ACP response: {event}'+ updates.append(event)++ def chunks(updates):+ return [e.get('params', {}).get('update', {}).get('content', {}).get('text', '')+ for e in updates if e.get('params', {}).get('update', {}).get('sessionUpdate') == 'agent_message_chunk']++ init, _ = call('initialize', {'protocolVersion':1}, 1)+ assert init['result']['protocolVersion'] == 1+ created, _ = call('session/new', {'cwd':str(case), 'mcpServers':[]}, 2)+ sid = created['result']['sessionId']+ result, updates = call('session/prompt', {'sessionId':sid, 'prompt':[{'type':'text', 'text':'Say OK.'}]}, 3)+ assert result.get('result', {}).get('stopReason') == 'end_turn', result+ reply_chunks = chunks(updates)+ assert len(reply_chunks) == 2 and re.fullmatch(+ r'\[network error: EndOfStream — retrying in 250ms \(1/6\)\]', reply_chunks[0]+ ) and reply_chunks[1] == 'OK', reply_chunks+ rows = [json.loads(line) for line in log.read_text().splitlines()]+ posts = [row for row in rows if row['event'] == 'post']+ assert len(posts) == 2, posts+ assert not any(row['protocol'] == 'h1' for row in posts), posts+ assert all(row['protocol'] == 'h2' and row['method'] == 'POST' and row['path'] == '/v1/chat/completions' for row in posts), posts+ assert posts[0]['sha256'] == posts[1]['sha256'] and posts[0]['bytes'] > 0, posts+ assert all(row['alpn'] == 'h2' for row in rows if row['event'] == 'session'), rows+ cost, cost_updates = call('session/prompt', {'sessionId':sid, 'prompt':[{'type':'text', 'text':'/cost'}]}, 4)+ assert cost.get('result', {}).get('stopReason') == 'end_turn', cost+ receipt = ''.join(chunks(cost_updates))+ assert '1 failed request attempt(s) without usage' in receipt, receipt+ assert 'known subtotal: 1 api call(s) · 10 in' in receipt, receipt+ assert '+ 2 out tokens' in receipt, receipt+ assert posts[1]['atMs'] - posts[0]['atMs'] >= 200, 'Second POST bypassed the 250ms request-level retry'+ after_cost = [json.loads(line) for line in log.read_text().splitlines()]+ assert len([row for row in after_cost if row['event'] == 'post']) == 2, '/cost caused a model POST'+ print('ACP HTTP/2 post-flush retry: 2 matching h2 POSTs, outer retry observed, 1 failed attempt reported')+ finally:+ fixture.terminate(worker)+ fixture.terminate(server)+++if __name__ == '__main__':+ with tempfile.TemporaryDirectory(prefix='acp-http2-retry-') as name:+ root = Path(name)+ fixture.certificates(root)+ exercise(root, build(root))diff --git a/scripts/test-acp-usage.py b/scripts/test-acp-usage.pynew file mode 100644index 00000000..450196f4--- /dev/null+++ b/scripts/test-acp-usage.py@@ -0,0 +1,109 @@+#!/usr/bin/env python3+"""Offline real ACP: transport retry/failure preserve usage uncertainty on the wire."""+import argparse+import json+import os+from pathlib import Path+import queue+import subprocess+import tempfile+import threading+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer+++def main():+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument('binary', type=Path)+ parser.add_argument('--capture', type=Path)+ args = parser.parse_args()+ requests = []++ class Handler(BaseHTTPRequestHandler):+ def log_message(self, *_):+ pass++ def do_POST(self):+ requests.append(json.loads(self.rfile.read(int(self.headers['Content-Length']))))+ if len(requests) != 2:+ # Complete request accepted, no response headers: outer retry is observable.+ self.close_connection = True+ return+ chunks = [+ {'choices': [{'index': 0, 'delta': {'content': 'Recovered.'}, 'finish_reason': None}]},+ {'choices': [{'index': 0, 'delta': {}, 'finish_reason': 'stop'}],+ 'usage': {'prompt_tokens': 10, 'completion_tokens': 2, 'total_tokens': 12}},+ ]+ payload = ''.join('data: ' + json.dumps(c) + '\n\n' for c in chunks) + 'data: [DONE]\n\n'+ data = payload.encode()+ self.send_response(200)+ self.send_header('Content-Type', 'text/event-stream')+ self.send_header('Content-Length', str(len(data)))+ self.end_headers()+ self.wfile.write(data)++ server = ThreadingHTTPServer(('127.0.0.1', 0), Handler)+ threading.Thread(target=server.serve_forever, daemon=True).start()+ captured = []+ try:+ with tempfile.TemporaryDirectory(prefix='graff-acp-usage-') as tmp:+ config = Path(tmp)/'mcp.json'+ config.write_text('{"mcpServers":{}}')+ env = {k: v for k, v in os.environ.items() if not k.endswith('_API_KEY') and not k.startswith(('GRAFF_', 'HARNESS_'))}+ env.update(HOME=tmp, AI_GATEWAY_API_KEY='local', GRAFF_VERCEL_URL=f'http://127.0.0.1:{server.server_port}/v1/chat/completions',+ GRAFF_MCP_CONFIG=str(config), GRAFF_NO_TELEMETRY='1', GRAFF_FLEET='off', GRAFF_NO_SMOLIFY='1',+ GRAFF_NO_CODEDB_GUARD='1', GRAFF_BEHAVIOR_UPLOAD='off', NO_COLOR='1')+ with (Path(tmp)/'stderr').open('w') as stderr:+ process = subprocess.Popen([str(args.binary.resolve()), 'acp', '--model', 'vercel', '--yolo', '--old', '--no-lean'],+ cwd=tmp, env=env, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=stderr, text=True)+ messages = queue.Queue()+ def reader():+ for line in process.stdout:+ try: messages.put(json.loads(line))+ except ValueError: pass+ messages.put(None)+ threading.Thread(target=reader, daemon=True).start()+ def call(method, params, identifier):+ process.stdin.write(json.dumps(dict(jsonrpc='2.0', id=identifier, method=method, params=params))+'\n')+ process.stdin.flush()+ events = []+ while True:+ message = messages.get(timeout=40)+ assert message is not None, 'ACP exited without terminal reply'+ captured.append(message)+ if message.get('id') == identifier: return message, events+ events.append(message)+ try:+ initialized, _ = call('initialize', {'protocolVersion': 1}, 1)+ assert initialized['result']['agentCapabilities']['_meta']['codegraff/usage'] is True+ reply, _ = call('session/new', {'cwd': tmp, 'mcpServers': []}, 2)+ sid = reply['result']['sessionId']+ prompt = {'sessionId': sid, 'prompt': [{'type': 'text', 'text': 'Reply briefly.'}]}+ reply, events = call('session/prompt', prompt, 3)+ assert reply['result']['stopReason'] == 'end_turn', reply+ updates = [e['params']['update'] for e in events if e.get('method') == 'session/update']+ usage = [e['params']['usage'] for e in events if e.get('method') == '_codegraff/usage']+ assert len(usage) == 1 and usage[0]['unreported_failed_attempts'] == 1, usage+ assert usage[0]['api_calls'] == 1 and usage[0]['input_tokens'] == 10, usage+ assert not usage[0]['usage_complete'] and usage[0]['cost_usd'] is None, usage+ assert any('network error:' in u.get('content', {}).get('text', '') for u in updates), updates+ assert len(requests) == 2, len(requests)+ reply, events = call('session/prompt', prompt, 4)+ assert 'error' in reply, reply+ usage = [e['params']['usage'] for e in events if e.get('method') == '_codegraff/usage']+ assert len(usage) == 1 and usage[0]['unreported_failed_attempts'] == 7, usage+ assert usage[0]['api_calls'] == 1 and usage[0]['cost_usd'] is None, usage+ assert len(requests) == 8, len(requests)+ if args.capture:+ args.capture.write_text(''.join(json.dumps(e)+'\n' for e in captured))+ print('PASS real ACP: retry then success, exhausted retry, known usage retained, total cost unknown')+ finally:+ process.stdin.close()+ try: process.wait(timeout=5)+ except subprocess.TimeoutExpired: process.kill(); process.wait()+ finally:+ server.shutdown()+ server.server_close()+++if __name__ == '__main__':+ main()diff --git a/src/acp_engine.zig b/src/acp_engine.zigindex 99c43f3d..f696a374 100644--- a/src/acp_engine.zig+++ b/src/acp_engine.zig@@ -161,6 +161,7 @@ fn respondInitialize(w: *Io.Writer, req: proto.Request, can_load: bool) !void {.protocolVersion = negotiateVersion(req.params),.agentCapabilities = .{.loadSession = can_load,+ ._meta = .{ .@"codegraff/usage" = can_load },.promptCapabilities = proto.PromptCapabilities{},},.agentInfo = proto.AgentImplementation{ .version = implementation_version },diff --git a/src/acp_live_turn.zig b/src/acp_live_turn.zigindex bed55165..c22c117c 100644--- a/src/acp_live_turn.zig+++ b/src/acp_live_turn.zig@@ -90,6 +90,15 @@ pub const LiveTurn = struct {turn_trace.recordLive(self.root, text, turn_id, self.prev_turn_id);const started = Io.Timestamp.now(self.root.io, .awake);const result = providers.runTurnWithFallback(self.root, self.keys, arena, null);+ // Supplemental metadata must not replace the turn outcome or prevent+ // trace/session persistence if the client disconnects. Emit on exit,+ // after the durable work below, while retaining whole-message locking.+ defer {+ sink.writer.flush() catch {};+ main_mod.g_gui_mu.lockUncancelable(self.root.io);+ defer main_mod.g_gui_mu.unlock(self.root.io);+ @import("acp_usage.zig").writeBestEffort(self.out, self.session_id, &@import("pricing.zig").g_cost, self.root.io);+ }turn_trace.record(self.root, self.root.io, arena, text, turn_id, started, result, self.root.effectiveContextTokens(), before, &self.prev_turn_id, &self.prev_prompt_fp);const isolated = context.restore(self.root);if (isolated) {diff --git a/src/acp_usage.zig b/src/acp_usage.zignew file mode 100644index 00000000..a5749db2--- /dev/null+++ b/src/acp_usage.zig@@ -0,0 +1,67 @@+//! Codegraff ACP extension: cumulative known usage, never an inferred bill.+const std = @import("std");+const pricing = @import("pricing.zig");+const proto = @import("acp_protocol.zig");++/// Supplemental delivery never changes the original turn's result. Caller owns+/// the ACP output lock; do not split serialization and flush across lock scopes.+pub fn writeBestEffort(w: *std.Io.Writer, sid: []const u8, tally: *pricing.CostTally, io: std.Io) void {+ write(w, sid, tally, io) catch return;+ w.flush() catch {};+}++pub fn write(w: *std.Io.Writer, sid: []const u8, tally: *pricing.CostTally, io: std.Io) !void {+ const c = tally.snap(io);+ const complete = c.missing_usage_calls == 0 and c.unreported_failed_attempts == 0;+ const cost_complete = complete and c.sub_calls == 0 and c.unpriced_calls == 0;+ try proto.writeNotification(w, "_codegraff/usage", .{+ .sessionId = sid,+ .usage = .{+ .scope = "connection",+ .usage_complete = complete,+ .cost_complete = cost_complete,+ .cost_usd = if (cost_complete) @as(?f64, c.usd) else null,+ .known_cost_usd = c.usd,+ .input_tokens = c.in_tokens +| c.cache_tokens,+ .cache_read_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,+ .unreported_failed_attempts = c.unreported_failed_attempts,+ .subscription_calls = c.sub_calls,+ .unpriced_calls = c.unpriced_calls,+ },+ });+}++test "ACP usage preserves failed-attempt uncertainty and subscription unknown dollars" {+ const io = std.testing.io;+ var tally: pricing.CostTally = .{};+ tally.add(io, .sub, "fixture", 10, 4, 3, 2);+ tally.failedWithoutUsage(io, 1);+ var out: std.Io.Writer.Allocating = .init(std.testing.allocator);+ defer out.deinit();+ try write(&out.writer, "session-fixture", &tally, io);+ var parsed = try std.json.parseFromSlice(std.json.Value, std.testing.allocator, out.written(), .{});+ defer parsed.deinit();+ const params = parsed.value.object.get("params").?.object;+ try std.testing.expectEqualStrings("session-fixture", params.get("sessionId").?.string);+ try std.testing.expectEqualStrings("_codegraff/usage", parsed.value.object.get("method").?.string);+ const update = params.get("usage").?.object;+ try std.testing.expect(!update.get("usage_complete").?.bool);+ try std.testing.expect(update.get("cost_usd").? == .null);+ try std.testing.expectEqual(@as(i64, 17), update.get("input_tokens").?.integer);+ try std.testing.expectEqual(@as(i64, 1), update.get("unreported_failed_attempts").?.integer);+ try std.testing.expectEqual(@as(i64, 1), update.get("api_calls").?.integer);+ try std.testing.expectEqual(@as(i64, 3), update.get("cache_write_tokens").?.integer);+}++test "ACP supplemental usage tolerates a rejected writer" {+ var storage: [0]u8 = .{};+ var broken = std.Io.Writer.fixed(&storage);+ var tally: pricing.CostTally = .{};+ // Prove this writer actually rejects the real serialized notification.+ try std.testing.expectError(error.WriteFailed, write(&broken, "disconnected", &tally, std.testing.io));+ writeBestEffort(&broken, "disconnected", &tally, std.testing.io);+}diff --git a/src/agent_request.zig b/src/agent_request.zigindex 2b818d4d..b648f41c 100644--- a/src/agent_request.zig+++ b/src/agent_request.zig@@ -357,7 +357,7 @@ pub fn request(self: *Agent, tools_in: ?[]const u8) !std.json.ObjectMap {const delay_ms = RetryPlan.delayMs(throttled, attempt);@import("turn_chrome.zig").emitRetryNotice(self.io, @errorName(err), attempt + 1, max_attempts);if (scratch.showRecoveredTransportRetry(self.call_kind))- try self.say("[network error: {t} — retrying in {d}ms ({d}/{d})]\n", .{ err, delay_ms, attempt + 1, max_attempts });+ try scratch.announceNetworkRetry(self, err, delay_ms, 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.diff --git a/src/agent_request_scratch.zig b/src/agent_request_scratch.zigindex 0f0ceb98..daa8b5c8 100644--- a/src/agent_request_scratch.zig+++ b/src/agent_request_scratch.zig@@ -29,6 +29,16 @@ pub fn showRecoveredTransportRetry(kind: run_budget_mod.CallKind) bool {return kind != .recap;}+/// Preserve the existing notice in JSON/ACP, where say() is deliberately silent.+pub fn announceNetworkRetry(self: *Agent, err: anyerror, delay_ms: u64, attempt: usize, limit: usize) !void {+ try self.say("[network error: {t} — retrying in {d}ms ({d}/{d})]\n", .{ err, delay_ms, attempt, limit });+ if (@import("main.zig").json_mode and !self.sub) {+ var buf: [192]u8 = undefined;+ const text = try std.fmt.bufPrint(&buf, "[network error: {t} — retrying in {d}ms ({d}/{d})]", .{ err, delay_ms, attempt, limit });+ self.emit(.{ .type = "text", .text = text });+ }+}+/// A response body of only SSE comment lines (`: OPENROUTER PROCESSING` …)/// means the gateway queued us and never produced tokens — back off and re-ask/// like a 5xx instead of dying on an "unparseable" JSON parse.diff --git a/src/agent_stream_h2.zig b/src/agent_stream_h2.zigindex 3236ab09..496be2ea 100644--- a/src/agent_stream_h2.zig+++ b/src/agent_stream_h2.zig@@ -1,9 +1,9 @@//! HTTPS SSE over http-zig. Returns null to keep the std.http/1.1 path, but-//! only while the request provably never reached the server: the dial or the-//! send failed, the server did not pick h2 via ALPN, or it answered GOAWAY /+//! only while the request provably never reached the server: the dial failed,+//! the server did not pick h2 via ALPN, or it answered GOAWAY ///! REFUSED_STREAM for our stream (RFC 9113 §8.7). Once the request is on the//! wire any other failure is an error for request()'s retry loop -- falling-//! back would POST the same prompt twice and bill two generations.+//! back would silently resend an ambiguously delivered request.const std = @import("std");const Io = std.Io;@@ -219,18 +219,25 @@ fn raceHead(io: Io, head: *Head, poll_stdin: bool) !HeadResult {}/// Falling back to HTTP/1.1 re-sends the POST, so it is allowed only when-/// the server cannot have acted on it: the body never fully left (dial or-/// send failed), or it said so -- GOAWAY above our stream id, REFUSED_STREAM.+/// the server cannot have acted on it: dial failed, ALPN selected H1, or the+/// peer said so -- GOAWAY above our stream id, REFUSED_STREAM. A send-phase+/// error can occur after the complete POST reached the peer.fn mayResendOnH1(phase: Phase, err: anyerror) bool {if (err == error.Canceled) return false;- if (phase != .wait) return true;+ if (phase == .dial) return true;+ if (err == error.H1NoStream) return true;return err == error.GoAway or err == error.StreamRefused;}test "HTTP/1.1 fallback only when the request provably never reached the server" {try std.testing.expect(mayResendOnH1(.dial, error.ConnectionRefused));try std.testing.expect(mayResendOnH1(.dial, error.H1NoStream));- try std.testing.expect(mayResendOnH1(.send, error.WriteFailed));+ try std.testing.expect(mayResendOnH1(.send, error.H1NoStream));+ try std.testing.expect(mayResendOnH1(.send, error.GoAway));+ try std.testing.expect(mayResendOnH1(.send, error.StreamRefused));+ try std.testing.expect(!mayResendOnH1(.send, error.WriteFailed));+ try std.testing.expect(!mayResendOnH1(.send, error.EndOfStream));+ try std.testing.expect(!mayResendOnH1(.send, error.InvalidGoAway));try std.testing.expect(mayResendOnH1(.wait, error.GoAway));try std.testing.expect(mayResendOnH1(.wait, error.StreamRefused));// Sent and possibly generating: retry via request(), never a silent re-POST.diff --git a/src/main.zig b/src/main.zigindex 44d4f8a3..77367b25 100644--- a/src/main.zig+++ b/src/main.zig@@ -558,7 +558,7 @@ const agentJobsReap = subagent.agentJobsReap; // #276 P0-3: background subagentsconst workflow = @import("workflow_test.zig"); // the engine's tests live here (workflow.zig hit the 600-line cap)const exec = @import("exec.zig");test { // ── Unit tests (`zig build test`): pull in tests from imported modules (mcp.zig)- _ = .{ @import("mcp_apps.zig"), @import("html_view.zig"), @import("providers_confirmation_tests.zig"), @import("repl_model_confirmation_tests.zig"), @import("repl_model_pick_tests.zig"), @import("engine_sink_citation_tests.zig"), @import("cite_markup_stream_tests.zig"), @import("oneshot_citation_tests.zig"), @import("tui_acp.zig"), @import("acp_permission.zig") };+ _ = .{ @import("mcp_apps.zig"), @import("html_view.zig"), @import("providers_confirmation_tests.zig"), @import("repl_model_confirmation_tests.zig"), @import("repl_model_pick_tests.zig"), @import("engine_sink_citation_tests.zig"), @import("cite_markup_stream_tests.zig"), @import("oneshot_citation_tests.zig"), @import("tui_acp.zig"), @import("acp_permission.zig"), @import("acp_usage.zig") };_ = .{ @import("mcp_server_tests.zig"), @import("main_test.zig"), @import("artifact_claim_command.zig"), @import("cli_path_hint.zig"), @import("run_budget.zig"), @import("pr_review_input.zig"), @import("pr_claim_review.zig"), @import("tui_paste_transfer.zig") };_ = .{ @import("session_catalog.zig"), @import("session_prompt.zig"), @import("session_discovery.zig") };_ = .{ @import("prompt_astra.zig"), @import("prompt_guidance.zig") }; // per-model guidance (Astra, GPT-5.6)