Skip to content

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.md
index 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.zig
index 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 vision
diff --git a/src/acp_context_meter.zig b/src/acp_context_meter.zig
new file mode 100644
index 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.zig
index 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: []const
pub 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.zig
index 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.zig
index 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.zig
index 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 {};