Skip to content

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

Python

Report what graff kept out of context on its ACP context meter

justrach2e88163562be
diff --git a/src/acp.zig b/src/acp.zig
index 857c0e8f..76aad0de 100644
--- a/src/acp.zig
+++ b/src/acp.zig
@@ -93,7 +93,12 @@ fn liveAfter(ctx: *anyopaque, arena: Allocator, text: []const u8, prompt: ?std.j
fn liveMeter(ctx: *anyopaque) engine.Meter {
const live: *LiveTurn = @ptrCast(@alignCast(ctx));
const root = live.root;
- return .{ .used = root.effectiveContextTokens(), .window = root.provider.context, .cost_usd = @import("acp_context_meter.zig").knownCostUsd(root.io) };
+ return .{
+ .used = root.effectiveContextTokens(),
+ .window = root.provider.context,
+ .cost_usd = @import("acp_context_meter.zig").knownCostUsd(root.io),
+ .savings = @import("context_savings.zig").snap(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
index 6c1f79ab..1cac572f 100644
--- a/src/acp_context_meter.zig
+++ b/src/acp_context_meter.zig
@@ -21,12 +21,26 @@ pub fn knownCostUsd(io: Io) ?f64 {
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 {
+/// `savings` rides as `_meta["codegraff/savings"]` once any count is nonzero
+/// (context_savings.zig); clients that don't know it ignore `_meta`.
+pub fn write(w: *Io.Writer, sid: []const u8, used: u64, size: u64, cost_usd: ?f64, savings: Savings) !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", .{
+ const meta = .{ .@"codegraff/savings" = savings };
+ if (cost_usd) |usd| {
+ const cost = .{ .amount = usd, .currency = "USD" };
+ if (savings.any()) return proto.writeNotification(w, "session/update", .{
+ .sessionId = sid,
+ .update = .{ .sessionUpdate = "usage_update", .used = used, .size = size, .cost = cost, ._meta = meta },
+ });
+ return proto.writeNotification(w, "session/update", .{
+ .sessionId = sid,
+ .update = .{ .sessionUpdate = "usage_update", .used = used, .size = size, .cost = cost },
+ });
+ }
+ if (savings.any()) return proto.writeNotification(w, "session/update", .{
.sessionId = sid,
- .update = .{ .sessionUpdate = "usage_update", .used = used, .size = size, .cost = .{ .amount = usd, .currency = "USD" } },
+ .update = .{ .sessionUpdate = "usage_update", .used = used, .size = size, ._meta = meta },
});
try proto.writeNotification(w, "session/update", .{
.sessionId = sid,
@@ -34,6 +48,8 @@ pub fn write(w: *Io.Writer, sid: []const u8, used: u64, size: u64, cost_usd: ?f6
});
}
+pub const Savings = @import("context_savings.zig").Snapshot;
+
/// 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 {
@@ -44,12 +60,24 @@ pub const Step = struct {
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);
+ 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 write(&w, "s1", 1, 2, 0.045, .{});
try std.testing.expect(std.mem.indexOf(u8, w.buffered(), "\"cost\":{\"amount\":0.045,\"currency\":\"USD\"}") != null);
+ try std.testing.expect(std.mem.indexOf(u8, w.buffered(), "_meta") == null);
+}
+
+test "usage_update carries graff's savings once there are any" {
+ var buf: [512]u8 = undefined;
+ var w: Io.Writer = .fixed(&buf);
+ try write(&w, "s1", 10, 100, null, .{ .handleBytes = 96000, .compactedTokens = 78000, .cacheReadTokens = 4000 });
+ try std.testing.expect(std.mem.indexOf(u8, w.buffered(), "\"_meta\":{\"codegraff/savings\":{\"handleBytes\":96000,\"compactedTokens\":78000,\"cacheReadTokens\":4000}}") != null);
+ w = .fixed(&buf);
+ try write(&w, "s1", 10, 100, 0.5, .{ .cacheReadTokens = 1 });
+ try std.testing.expect(std.mem.indexOf(u8, w.buffered(), "\"cost\":") != null);
+ try std.testing.expect(std.mem.indexOf(u8, w.buffered(), "\"cacheReadTokens\":1") != null);
}
diff --git a/src/acp_engine.zig b/src/acp_engine.zig
index 66c583a5..35fe46ce 100644
--- a/src/acp_engine.zig
+++ b/src/acp_engine.zig
@@ -42,7 +42,7 @@ pub const LoadSessionFn = *const fn (ctx: *anyopaque, arena: Allocator, w: *Io.W
/// 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, cost_usd: ?f64 = null };
+pub const Meter = struct { used: u64, window: u64, cost_usd: ?f64 = null, savings: @import("context_savings.zig").Snapshot = .{} };
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).
@@ -255,7 +255,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) try @import("acp_context_meter.zig").write(w, sid, m.used, m.window, m.cost_usd);
+ if (m.window > 0) try @import("acp_context_meter.zig").write(w, sid, m.used, m.window, m.cost_usd, m.savings);
}
}
diff --git a/src/acp_live_turn.zig b/src/acp_live_turn.zig
index 57568198..c7d5d216 100644
--- a/src/acp_live_turn.zig
+++ b/src/acp_live_turn.zig
@@ -40,7 +40,7 @@ pub const LiveTurn = struct {
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 {};
+ meter.write(w, self.session_id, used, window, meter.knownCostUsd(self.root.io), @import("context_savings.zig").snap(self.root.io)) catch {};
}
pub fn bindSession(ctx: *anyopaque, session_id: []const u8) void {
diff --git a/src/agent_compact.zig b/src/agent_compact.zig
index 8de9ce27..cad834d8 100644
--- a/src/agent_compact.zig
+++ b/src/agent_compact.zig
@@ -247,6 +247,7 @@ pub fn compact(self: *Agent) anyerror!usize {
self.goal_note_fp = 0; // the injected goal note died with the old history - re-state in full (#318)
self.history_rewrites +%= 1; // readers of pasted state (the run's checklist gate) re-carry it (#318)
installed_summary = true;
+ @import("context_savings.zig").noteCompaction(live_effective_context, self.fullRequestEstimateTokens());
acp_run.finish(.completed, summary, null);
// #445: the history the model was reading is gone and the durable file is
// now the only place its exact wording survives, so THIS is where the #410
diff --git a/src/agent_compact_recover.zig b/src/agent_compact_recover.zig
index 271ceb19..524bf93a 100644
--- a/src/agent_compact_recover.zig
+++ b/src/agent_compact_recover.zig
@@ -43,6 +43,7 @@ pub fn emergencyTrim(self: *Agent) usize {
self.pending_goal_note = goal_flow.compactionSnapshot(self.arena, self) catch null;
const after_tokens = self.fullInputEstimateTokens();
compact.accountForReclaimedTokens(self, before_tokens -| after_tokens);
+ @import("context_savings.zig").noteCompaction(before_tokens, after_tokens);
return cut;
}
// #163: no clean user turn to cut at (a runaway tool loop). Don't wedge the
diff --git a/src/agent_tool_batch.zig b/src/agent_tool_batch.zig
index f666fcbd..65c74b32 100644
--- a/src/agent_tool_batch.zig
+++ b/src/agent_tool_batch.zig
@@ -152,6 +152,7 @@ fn aborted() bool {
pub fn takeOutput(self: *Agent, call: ToolCall, output: ToolOutput, handle_threshold: usize, handle_target: tool_handle.Target) !ExecResult {
self.read_miss.noteOutput(call.name, call.input, output.text, output.is_error);
const handled = try tool_handle.forResult(self.gpa, self.arena, handle_target, output.text, handle_threshold);
+ @import("context_savings.zig").noteHandle(handled.bytes, handled.text.len);
const text = try tool_handle.withFirstNote(self.arena, handled, &self.handle_note_shown);
if (self.eval_cmd != null and eval_control.toolInvalidatesEval(call)) {
self.eval_verified = false;
diff --git a/src/context_savings.zig b/src/context_savings.zig
new file mode 100644
index 00000000..e1ba86c8
--- /dev/null
+++ b/src/context_savings.zig
@@ -0,0 +1,69 @@
+//! What graff kept out of the model's context, for a client that shows it
+//! next to the context meter (Harness). Every count is measured on what graff
+//! actually handled in this process; none models what another agent would
+//! have spent on the same task.
+//!
+//! - `handle_bytes`: tool results over the handle threshold were written to a
+//! file (#440). The bytes the model never received: the full result minus
+//! the preview and marker it got instead.
+//! - `compacted_tokens`: estimated context tokens freed by compaction or an
+//! emergency trim (before minus after).
+//! - `cache_read_tokens`: input the provider reported serving from its prompt
+//! cache (pricing.g_cost). Billed, but at the provider's cache rate.
+//!
+//! Process-wide, like pricing.g_cost: one ACP connection's sessions, with
+//! subagents included.
+
+const std = @import("std");
+const Io = std.Io;
+
+var handle_bytes: std.atomic.Value(u64) = .init(0);
+var compacted_tokens: std.atomic.Value(u64) = .init(0);
+
+/// A tool result of `full` bytes reached the model as `sent` bytes.
+pub fn noteHandle(full: usize, sent: usize) void {
+ if (full > sent) _ = handle_bytes.fetchAdd(full - sent, .monotonic);
+}
+
+/// Context went from `before` to `after` estimated tokens.
+pub fn noteCompaction(before: u64, after: u64) void {
+ if (before > after) _ = compacted_tokens.fetchAdd(before - after, .monotonic);
+}
+
+/// Wire names are the ACP `_meta["codegraff/savings"]` fields.
+pub const Snapshot = struct {
+ handleBytes: u64 = 0,
+ compactedTokens: u64 = 0,
+ cacheReadTokens: u64 = 0,
+
+ pub fn any(s: Snapshot) bool {
+ return s.handleBytes > 0 or s.compactedTokens > 0 or s.cacheReadTokens > 0;
+ }
+};
+
+pub fn snap(io: Io) Snapshot {
+ return .{
+ .handleBytes = handle_bytes.load(.monotonic),
+ .compactedTokens = compacted_tokens.load(.monotonic),
+ .cacheReadTokens = @import("pricing.zig").g_cost.snap(io).cache_tokens,
+ };
+}
+
+pub fn resetForTest() void {
+ handle_bytes.store(0, .monotonic);
+ compacted_tokens.store(0, .monotonic);
+}
+
+test "savings count only what was actually withheld or freed" {
+ resetForTest();
+ defer resetForTest();
+ noteHandle(100_000, 4_000);
+ noteHandle(10, 10); // passed through whole
+ noteHandle(10, 20); // a marker longer than its input is not a saving
+ noteCompaction(90_000, 12_000);
+ noteCompaction(5, 9);
+ try std.testing.expectEqual(@as(u64, 96_000), handle_bytes.load(.monotonic));
+ try std.testing.expectEqual(@as(u64, 78_000), compacted_tokens.load(.monotonic));
+ try std.testing.expect((Snapshot{}).any() == false);
+ try std.testing.expect((Snapshot{ .compactedTokens = 1 }).any());
+}
diff --git a/src/main.zig b/src/main.zig
index a4f4c0db..c77ae41a 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -558,7 +558,7 @@ const workflow = @import("workflow_test.zig"); // the engine's tests live here (
const exec = @import("exec.zig");
test { // ── Unit tests (`zig build test`): pull in tests from imported modules (mcp.zig)
_ = .{ @import("beta_feed.zig"), @import("jev_tool.zig"), @import("jev_model_scope.zig"), @import("jev_provider_switch_tests.zig"), @import("jev_effort_state.zig"), @import("gemini_turns.zig"), @import("gemini_turns_tests.zig") };
- _ = .{ @import("mcp_apps.zig"), @import("html_view.zig"), @import("usage_trace.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("acp_permission.zig"), @import("acp_usage.zig") };
+ _ = .{ @import("mcp_apps.zig"), @import("html_view.zig"), @import("usage_trace.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("acp_permission.zig"), @import("acp_usage.zig"), @import("context_savings.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("session_catalog.zig"), @import("session_size_tests.zig"), @import("session_prompt.zig"), @import("session_discovery.zig"), @import("session_workspaces.zig"), @import("commands_resume.zig"), @import("peer_live.zig"), @import("presence_tests.zig"), @import("mcp_rpc_tests.zig") };
_ = .{ @import("prompt_astra.zig"), @import("prompt_guidance.zig"), @import("oauth_chatgpt.zig"), @import("chatgpt_reauth.zig"), @import("oauth_anthropic.zig"), @import("anthropic_oauth_wire.zig"), @import("anthropic_login_tests.zig") };