graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
ACP: report context left with the standard usage_update
justrache29296c6097a
diff --git a/docs/acp-compatibility.md b/docs/acp-compatibility.mdindex 39598906..cdc7f372 100644--- a/docs/acp-compatibility.md+++ b/docs/acp-compatibility.md@@ -34,6 +34,7 @@ optional feature or draft extension is enabled.| Configuration timing | Client changes arriving during a prompt are queued for after that turn. An effort-tool result applies on the owning agent thread before the next model request; clients refresh the affected session's controls. | `src/acp_idle.zig`, `src/jev_effort_state.zig`, `apps/native/lib/acp-client-stream.test.ts` || Content | Text, resource links and supported embedded text resources are accepted. `image` blocks (`data` + `mimeType`) are accepted and advertised (`promptCapabilities.image`); they reach the next model request when the model accepts images and are skipped otherwise, the same as `@[path]` attachments. Audio is advertised as false. | `src/acp_protocol.zig`, `src/acp_images.zig`, `scripts/test-acp-images.py` || Client filesystem and terminals | These are optional negotiated ACP facilities, not a requirement that local harness tools be replaced by client tools. The local tool implementation does not imply support for every client-side method. | Capability negotiation and the upstream v1 schema |+| Context meter | Standard `usage_update` (stable in ACP v1): `used` tokens in context and the model's `size`, plus `cost` `{amount, currency: "USD"}` only when every call so far was priced. Sent after tool steps whenever the count moved (so it drops visibly after compaction) and at the end of each prompt turn. | `src/acp_context_meter.zig`, `src/acp_engine_test.zig` || Usage | Connection usage is a namespaced extension. It preserves unknown totals and is not a standard ACP v1 billing contract. | `scripts/test-acp-usage.py`, ADR 0182 || Subagents | Default: a top-level subagent streams its work onto the parent tool call as standard `tool_call_update` content (a rolling log of its tool calls, failures and message tail), with no `status` change and `_meta["graff/subagent"]` = `{sessionId, name, state}`; `GRAFF_ACP_SUBAGENT_PROGRESS=0` disables it. Opt-in preview: the proposed child-session stream (client `subagents` capability plus `GRAFF_ACP_DRAFT_SUBAGENTS=1`) replaces it for foreground children. Detached workers also keep `graff/agents` inspection. Child history is not yet replayed on `session/load`. | `scripts/test-acp-subagent-update.py`, ADR 0194, ADR 0205 || Transport | ACP uses JSON-RPC over stdio. HTTP/2 checks exercise the model request transport behind ACP; they do not redefine ACP as an HTTP/2 protocol. | `scripts/test-acp-http2.py`, `scripts/test-acp-http2-retry.py` |diff --git a/src/acp.zig b/src/acp.zigindex a00d5881..69e1bc57 100644--- a/src/acp.zig+++ b/src/acp.zig@@ -101,7 +101,7 @@ fn liveBind(ctx: *anyopaque, session_id: []const u8) void {fn liveMeter(ctx: *anyopaque) engine.Meter {const live: *LiveTurn = @ptrCast(@alignCast(ctx));const root = live.root;- return .{ .used = root.effectiveContextTokens(), .window = root.provider.context };+ return .{ .used = root.effectiveContextTokens(), .window = root.provider.context, .cost_usd = @import("acp_context_meter.zig").knownCostUsd(root.io) };}/// The ACP user message: GUI `@[image]` attachments become native visiondiff --git a/src/acp_context_meter.zig b/src/acp_context_meter.zignew file mode 100644index 00000000..6c1f79ab--- /dev/null+++ b/src/acp_context_meter.zig@@ -0,0 +1,55 @@+//! The standard ACP context meter: `usage_update` (stable in ACP v1) with the+//! tokens in context, the model's window, and the session's cost when it is+//! fully known. It replaces the graff-only `gui_context_meter`, which no ACP+//! client but the old in-repo desktop understood (#1290), so Harness and other+//! clients showed no context remaining at all.+//!+//! Sent at the end of every prompt turn and, during a turn, after tool steps+//! whenever the count moved, so a client sees context fill up and drop again+//! after compaction.++const std = @import("std");+const Io = std.Io;+const proto = @import("acp_protocol.zig");+const pricing = @import("pricing.zig");++/// Cumulative session cost in USD, or null when any call was unpriced,+/// subscription-billed, or missing usage: the meter never shows a guess.+pub fn knownCostUsd(io: Io) ?f64 {+ const c = pricing.g_cost.snap(io);+ const complete = c.missing_usage_calls == 0 and c.unreported_failed_attempts == 0 and c.sub_calls == 0 and c.unpriced_calls == 0;+ return if (complete and c.api_calls > 0) c.usd else null;+}++pub fn write(w: *Io.Writer, sid: []const u8, used: u64, size: u64, cost_usd: ?f64) !void {+ const v2 = @import("acp_v2.zig");+ if (v2.on()) return v2.writeUsage(w, sid, used, size);+ if (cost_usd) |usd| return proto.writeNotification(w, "session/update", .{+ .sessionId = sid,+ .update = .{ .sessionUpdate = "usage_update", .used = used, .size = size, .cost = .{ .amount = usd, .currency = "USD" } },+ });+ try proto.writeNotification(w, "session/update", .{+ .sessionId = sid,+ .update = .{ .sessionUpdate = "usage_update", .used = used, .size = size },+ });+}++/// A per-turn step hook for acp_stream.EventSink: emits only when the count+/// changed since the last meter this session sent.+pub const Step = struct {+ ctx: *anyopaque,+ run: *const fn (ctx: *anyopaque, w: *Io.Writer) void,+};++test "usage_update carries used and size, and cost only when known" {+ var buf: [512]u8 = undefined;+ var w: Io.Writer = .fixed(&buf);+ try write(&w, "s1", 53000, 200000, null);+ const plain = w.buffered();+ try std.testing.expect(std.mem.indexOf(u8, plain, "\"sessionUpdate\":\"usage_update\",\"used\":53000,\"size\":200000}") != null);+ try std.testing.expect(std.mem.indexOf(u8, plain, "cost") == null);+ try std.testing.expect(std.mem.indexOf(u8, plain, "gui_context_meter") == null);+ w = .fixed(&buf);+ try write(&w, "s1", 1, 2, 0.045);+ try std.testing.expect(std.mem.indexOf(u8, w.buffered(), "\"cost\":{\"amount\":0.045,\"currency\":\"USD\"}") != null);+}diff --git a/src/acp_engine.zig b/src/acp_engine.zigindex 8d8d0b75..05a9cbc0 100644--- a/src/acp_engine.zig+++ b/src/acp_engine.zig@@ -36,10 +36,10 @@ pub const SlashFn = *const fn (ctx: *anyopaque, arena: Allocator, text: []constpub const AfterUserFn = *const fn (ctx: *anyopaque, arena: Allocator, text: []const u8, prompt: ?std.json.Value) void;pub const BindSessionFn = *const fn (ctx: *anyopaque, session_id: []const u8) void;pub const LoadSessionFn = *const fn (ctx: *anyopaque, arena: Allocator, w: *Io.Writer, req: proto.Request) anyerror!void;-/// Optional per-turn context meter: used and window tokens for the-/// `gui_context_meter` update available to clients.+/// Optional per-turn context meter: used and window tokens (plus the known+/// session cost) for the standard `usage_update` (acp_context_meter.zig)./// Null when the embed has no live agent (pure in-process loop, tests).-pub const Meter = struct { used: u64, window: u64 };+pub const Meter = struct { used: u64, window: u64, cost_usd: ?f64 = null };pub const MeterFn = *const fn (ctx: *anyopaque) Meter;/// Vendor-method escape hatch: gets every request the core loop does not/// claim; returns true when it answered (false falls through to -32601).@@ -211,15 +211,7 @@ pub fn emitMeter(d: *Dispatch, w: *Io.Writer, sid: []const u8) !void {if (d.meter) |meter| {// Report live occupancy independently of the model catalog.const m = meter(d.ctx);- if (m.window > 0 and v2.on()) return v2.writeUsage(w, sid, m.used, m.window);- if (m.window > 0) try proto.writeNotification(w, "session/update", .{- .sessionId = sid,- .update = .{- .sessionUpdate = "gui_context_meter",- .used = m.used,- .window = m.window,- },- });+ if (m.window > 0) try @import("acp_context_meter.zig").write(w, sid, m.used, m.window, m.cost_usd);}}diff --git a/src/acp_engine_test.zig b/src/acp_engine_test.zigindex bd7394b2..7a35da0f 100644--- a/src/acp_engine_test.zig+++ b/src/acp_engine_test.zig@@ -53,7 +53,7 @@ test "live context occupancy precedes the terminal prompt reply" {w = .fixed(&buf);try handleLine(&d, a, &w, "{\"id\":2,\"method\":\"session/prompt\",\"params\":{\"prompt\":[{\"type\":\"text\",\"text\":\"hi\"}]}}");const output = w.buffered();- const occupancy = std.mem.indexOf(u8, output, "\"gui_context_meter\",\"used\":123,\"window\":1000") orelse return error.MissingMeter;+ const occupancy = std.mem.indexOf(u8, output, "\"usage_update\",\"used\":123,\"size\":1000") orelse return error.MissingMeter;const terminal = std.mem.indexOf(u8, output, "\"stopReason\":\"end_turn\"") orelse return error.MissingTerminalReply;try std.testing.expect(occupancy < terminal);}diff --git a/src/acp_live_turn.zig b/src/acp_live_turn.zigindex eb769a29..0b8fe53d 100644--- a/src/acp_live_turn.zig+++ b/src/acp_live_turn.zig@@ -28,6 +28,19 @@ pub const LiveTurn = struct {dispatch: ?*@import("acp_engine.zig").Dispatch = null,/// Launch `--model`: outranks a loaded session's saved model, as on CLI resume.model_override: ?provider_mod.Provider = null,+ /// The context count the last mid-turn meter carried.+ last_meter_used: u64 = 0,++ /// Mid-turn `usage_update`, only when the count moved since the last one.+ fn stepMeter(ctx: *anyopaque, w: *Io.Writer) void {+ const self: *LiveTurn = @ptrCast(@alignCast(ctx));+ const meter = @import("acp_context_meter.zig");+ const used = self.root.effectiveContextTokens();+ const window = self.root.provider.context;+ if (window == 0 or used == self.last_meter_used) return;+ self.last_meter_used = used;+ meter.write(w, self.session_id, used, window, meter.knownCostUsd(self.root.io)) catch {};+ }pub fn errorMessage(ctx: *anyopaque, err: anyerror) []const u8 {const self: *LiveTurn = @ptrCast(@alignCast(ctx));@@ -77,6 +90,7 @@ pub const LiveTurn = struct {sink.init(self.root.gpa, self.out, &self.session_id, &self.saw_text);sink.output_lock = &output_lock;sink.output_io = self.root.io;+ sink.step = .{ .ctx = self, .run = stepMeter };// Standard progress on the parent tool call by default; the draft// child-session stream only when both sides opted in (ADR 0194/0205).const draft = self.dispatch != null and self.dispatch.?.subagents and self.dispatch.?.draft_subagents_enabled;diff --git a/src/acp_stream.zig b/src/acp_stream.zigindex 81f4ee30..a3ab4770 100644--- a/src/acp_stream.zig+++ b/src/acp_stream.zig@@ -248,6 +248,9 @@ pub const EventSink = struct {pending: std.ArrayList(u8),gpa: Allocator,next_tool: u32 = 0,+ /// Called after each tool event, under the output lock: the live+ /// context meter (acp_context_meter.zig).+ step: ?@import("acp_context_meter.zig").Step = null,last_id: [64]u8 = @splat(0),buf: [4096]u8 = undefined,writer: Io.Writer = undefined,@@ -304,7 +307,10 @@ pub const EventSink = struct {self.saw_text.* = false;self.streamed_any = true;},- .tool => self.saw_text.* = false,+ .tool => {+ self.saw_text.* = false;+ if (self.step) |step| step.run(step.ctx, self.out);+ },else => {},}self.out.flush() catch {};