Skip to content

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

Python

Record confirmed optional charges

Rach Pradhan0e67577d5ee1
diff --git a/docs/adr/0187-optional-judgments-preserve-usage-uncertainty.md b/docs/adr/0187-optional-judgments-preserve-usage-uncertainty.md
index d346e0ad..90d6d3e2 100644
--- a/docs/adr/0187-optional-judgments-preserve-usage-uncertainty.md
+++ b/docs/adr/0187-optional-judgments-preserve-usage-uncertainty.md
@@ -15,13 +15,17 @@ model credential. The engine owns the behavior for both terminal and ACP
sessions. If the login is absent or the request fails, skip the judgment
without retrying it in the same session.
-Count reported tokens from a successful response, but leave its unsettled
-charge unknown. Mark a completed response without valid usage as missing
-usage, and a failed request attempt as uncertain. The session tally carries
-those distinctions to the terminal summary and ACP usage notification.
-Scripted mock judgments never affect the tally.
+Count reported tokens from a successful response. Count a charge only when
+the authenticated gateway response carries its server-owned, confirmed
+settlement receipt in integer micro-USD; never infer a settled charge from a
+catalog rate. Without that receipt, leave the charge unknown. Mark a
+completed response without valid usage as missing usage, and a failed
+request attempt as uncertain. The session tally carries those distinctions
+to the terminal summary and ACP usage notification. Scripted mock judgments
+never affect the tally.
## Validation
-`src/jev_tool.zig` and `src/acp_usage.zig` tests cover successful usage,
-missing usage, failed attempts, unknown cost, and mock isolation.
+`src/jev_tool.zig` and `src/acp_usage.zig` tests cover confirmed receipts,
+successful usage without a receipt, missing usage, failed attempts, unknown
+cost, and mock isolation.
diff --git a/src/jev_tool.zig b/src/jev_tool.zig
index 0abd0e79..815785bd 100644
--- a/src/jev_tool.zig
+++ b/src/jev_tool.zig
@@ -182,6 +182,19 @@ fn usageCount(v: Value) ?i64 {
return if (v == .integer and v.integer >= 0) v.integer else null;
}
+fn settledCharge(body: Value) ?u64 {
+ if (body != .object) return null;
+ const receipt = body.object.get("codegraff_billing") orelse return null;
+ if (receipt != .object) return null;
+ const settled = receipt.object.get("settled") orelse return null;
+ const currency = receipt.object.get("currency") orelse return null;
+ const charge = receipt.object.get("charge_micro_usd") orelse return null;
+ if (settled != .bool or !settled.bool or currency != .string or
+ !std.mem.eql(u8, currency.string, "USD") or charge != .integer or
+ charge.integer < 0 or charge.integer > 9_007_199_254_740_991) return null;
+ return @intCast(charge.integer);
+}
+
fn noteGatewayUsage(io: Io, tally: *pricing.CostTally, arena: Allocator, raw: []const u8) void {
const parsed = std.json.parseFromSliceLeaky(Value, arena, raw, .{}) catch {
tally.missingUsage(io);
@@ -192,9 +205,13 @@ fn noteGatewayUsage(io: Io, tally: *pricing.CostTally, arena: Allocator, raw: []
const input = usageCount(usage.object.get("input_tokens") orelse .null);
const output = usageCount(usage.object.get("output_tokens") orelse .null);
if (input != null and output != null) {
- // The gateway returns token usage but no settled charge. Preserve
- // known tokens while keeping the dollar total explicitly unknown.
- tally.addForProvider(io, .unpriced, "codegraff", "jev-latest", input.?, 0, 0, output.?);
+ // This parser is called only for the authenticated gateway endpoint.
+ // A published list rate cannot replace a confirmed charge receipt.
+ if (settledCharge(parsed)) |charge| {
+ tally.addSettled(io, input.?, output.?, charge);
+ } else {
+ tally.addForProvider(io, .unpriced, "codegraff", "jev-latest", input.?, 0, 0, output.?);
+ }
return;
}
}
@@ -446,3 +463,45 @@ test "native Jev gateway usage preserves tokens but marks unsettled cost unknown
try std.testing.expectEqual(@as(u64, 1), c.unreported_failed_attempts);
try std.testing.expectEqual(@as(u64, 4), c.api_calls); // failed attempts are separate
}
+
+test "native Jev gateway confirmed receipt records exact charge once" {
+ const io = std.testing.io;
+ var tally: pricing.CostTally = .{};
+ var temp = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer temp.deinit();
+ noteGatewayUsage(io, &tally, temp.allocator(),
+ "{\"usage\":{\"input_tokens\":296,\"output_tokens\":20},\"codegraff_billing\":{\"settled\":true,\"charge_micro_usd\":12,\"currency\":\"USD\"}}");
+ const c = tally.snap(io);
+ try std.testing.expectEqual(@as(u64, 1), c.api_calls);
+ try std.testing.expectEqual(@as(u64, 296), c.in_tokens);
+ try std.testing.expectEqual(@as(u64, 20), c.out_tokens);
+ try std.testing.expectEqual(@as(u64, 0), c.unpriced_calls);
+ try std.testing.expectApproxEqAbs(@as(f64, 0.000012), c.usd, 1e-12);
+ var wire: Io.Writer.Allocating = .init(std.testing.allocator);
+ defer wire.deinit();
+ try @import("acp_usage.zig").write(&wire.writer, "fixture", &tally, io);
+ const event = try std.json.parseFromSliceLeaky(Value, temp.allocator(), wire.written(), .{});
+ const usage = event.object.get("params").?.object.get("usage").?.object;
+ try std.testing.expect(usage.get("usage_complete").?.bool);
+ try std.testing.expect(usage.get("cost_complete").?.bool);
+ try std.testing.expectApproxEqAbs(@as(f64, 0.000012), usage.get("cost_usd").?.float, 1e-12);
+}
+
+test "native Jev gateway refuses malformed and unconfirmed charge claims" {
+ const io = std.testing.io;
+ var tally: pricing.CostTally = .{};
+ var temp = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer temp.deinit();
+ for ([_][]const u8{
+ "{\"usage\":{\"input_tokens\":20,\"output_tokens\":5},\"codegraff_billing\":{\"settled\":false,\"charge_micro_usd\":1,\"currency\":\"USD\"}}",
+ "{\"usage\":{\"input_tokens\":20,\"output_tokens\":5},\"codegraff_billing\":{\"settled\":true,\"charge_micro_usd\":-1,\"currency\":\"USD\"}}",
+ "{\"usage\":{\"input_tokens\":20,\"output_tokens\":5},\"codegraff_billing\":{\"settled\":true,\"charge_micro_usd\":1.5,\"currency\":\"USD\"}}",
+ "{\"usage\":{\"input_tokens\":20,\"output_tokens\":5},\"codegraff_billing\":{\"settled\":true,\"charge_micro_usd\":1,\"currency\":\"EUR\"}}",
+ "{\"usage\":{\"input_tokens\":20,\"output_tokens\":5},\"codegraff_billing\":{\"settled\":true,\"charge_micro_usd\":9007199254740992,\"currency\":\"USD\"}}",
+ }) |raw| noteGatewayUsage(io, &tally, temp.allocator(), raw);
+ const c = tally.snap(io);
+ try std.testing.expectEqual(@as(u64, 5), c.api_calls);
+ try std.testing.expectEqual(@as(u64, 5), c.unpriced_calls);
+ try std.testing.expectEqual(@as(u64, 100), c.in_tokens);
+ try std.testing.expectEqual(@as(f64, 0), c.usd);
+}
diff --git a/src/pricing.zig b/src/pricing.zig
index 1aa99c36..68f4f18d 100644
--- a/src/pricing.zig
+++ b/src/pricing.zig
@@ -90,6 +90,10 @@ pub const CostTally = struct {
}
}
+ pub fn addSettled(self: *CostTally, io: Io, input: i64, output: i64, charge_micro_usd: u64) void {
+ @import("pricing_settled.zig").add(self, io, input, output, charge_micro_usd);
+ }
+
pub fn missingUsage(self: *CostTally, io: Io) void {
self.mutex.lockUncancelable(io);
defer self.mutex.unlock(io);
@@ -580,7 +584,6 @@ pub fn providerModelInTable(provider_id: []const u8, model: []const u8) bool {
// Seat classification lives in billing.zig. Discovery / price-overlay / default
// catalog tests live in pricing_tests.zig (600-line cap).
-
test "completed response without usage marks totals incomplete without inventing tokens or cost" {
var tally: CostTally = .{};
tally.missingUsage(std.testing.io);
diff --git a/src/pricing_settled.zig b/src/pricing_settled.zig
new file mode 100644
index 00000000..a2e53fff
--- /dev/null
+++ b/src/pricing_settled.zig
@@ -0,0 +1,11 @@
+//! Exact gateway charge ingestion; never derive a settled amount from a list rate.
+const std = @import("std");
+
+pub fn add(tally: anytype, io: std.Io, input: i64, output: i64, charge_micro_usd: u64) void {
+ tally.mutex.lockUncancelable(io);
+ defer tally.mutex.unlock(io);
+ tally.api_calls +|= 1;
+ tally.in_tokens +|= @intCast(@max(input, 0));
+ tally.out_tokens +|= @intCast(@max(output, 0));
+ tally.usd += @as(f64, @floatFromInt(charge_micro_usd)) / 1_000_000;
+}