graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! The chat session's conversation, owned by the ENGINE (#551).
//!
//! Before this file the TUI rebuilt the model's history out of its own
//! rendered rows every turn: `.user`/`.assistant` text only, every tool row
//! dropped, into a throwaway Agent. So the model never saw the tool_use /
//! tool_result blocks from its own previous turns — it could not remember what
//! it had read or run — and because the prefix was re-materialized each time,
//! prompt caching had nothing stable to hit.
//!
//! Now the conversation lives here for the life of the session, exactly as
//! mainloop's root agent keeps `root.messages`, and the frontend's transcript
//! is a PROJECTION of it. The per-turn Agent borrows these messages and hands
//! them back, so assistant turns and tool blocks accumulate in place.
//!
//! Allocation: message content must outlive the turn that created it, so this
//! owns a dedicated arena and the turn agent uses it as its `arena` (the
//! allocator `messageMutationAlloc` writes provider responses into). Per-turn
//! parse garbage goes to the agent's `scratch_arena`, which is reset per
//! request — the same split the root agent has had since #124.
const std = @import("std");
const Allocator = std.mem.Allocator;
const Value = std.json.Value;
const messages_mod = @import("messages.zig");
const repl = @import("repl.zig");
pub const Conversation = struct {
arena: std.heap.ArenaAllocator,
/// Initialized lazily by `list()`: the arena's allocator embeds a pointer
/// to the arena, so nothing may allocate from it until the Conversation
/// has settled at its final address.
messages: std.json.Array = undefined,
live: bool = false,
compaction_window: @import("compaction_window.zig").State = .{},
pub fn init(gpa: Allocator) Conversation {
return .{ .arena = std.heap.ArenaAllocator.init(gpa) };
}
pub fn deinit(self: *Conversation) void {
self.arena.deinit();
}
pub fn alloc(self: *Conversation) Allocator {
return self.arena.allocator();
}
pub fn list(self: *Conversation) *std.json.Array {
if (!self.live) {
self.messages = std.json.Array.init(self.arena.allocator());
self.live = true;
}
return &self.messages;
}
pub fn len(self: *Conversation) usize {
return if (self.live) self.messages.items.len else 0;
}
pub fn seed(self: *Conversation, source: std.json.Array) !void {
self.reset();
self.messages = try cloneArray(self.alloc(), source);
self.live = true;
}
pub fn cloneInto(self: *Conversation, dest: Allocator) !std.json.Array {
return cloneArray(dest, self.list().*);
}
/// `/new` and `/clear`: the session starts over, and the memory goes with
/// it. Everything the old messages pointed at lived in this arena.
pub fn reset(self: *Conversation) void {
_ = self.arena.reset(.free_all);
self.live = false;
self.compaction_window = .{};
}
/// `/rewind`: drop back to just before the last human prompt, so the
/// engine's history matches the transcript the frontend just truncated.
/// A tool result is a user-role message with ARRAY content, so it is never
/// mistaken for the prompt.
pub fn rewind(self: *Conversation) void {
if (!self.live) return;
var i = self.messages.items.len;
while (i > 0) {
i -= 1;
if (isUserPrompt(self.messages.items[i])) {
self.messages.shrinkRetainingCapacity(i);
return;
}
}
self.messages.clearRetainingCapacity();
}
/// Fold the frontend's flattened transcript into the session conversation.
/// An empty conversation adopts all of it — the first turn, or a transcript
/// replayed after a compaction. A live one takes only the trailing user
/// message: everything before it is already here, in richer form than the
/// frontend could hand back.
pub fn adopt(self: *Conversation, history: []const repl.Turn) !void {
const msgs = self.list();
if (msgs.items.len == 0) {
for (history) |t| try msgs.append(try textOf(self.alloc(), t));
return;
}
if (history.len == 0) return;
const last = history[history.len - 1];
if (last.role != .user) return;
// #714: a host that re-submits the same trailing user row must not
// inject another turn. The named-source gate then re-read the file
// and the session looped the same Q&A.
if (messages_mod.trailingUserIs(msgs.items, last.text) and
@import("session_wake.zig").isNotice(msgs.items[msgs.items.len - 1]) == last.notification) return;
try msgs.append(try textOf(self.alloc(), last));
}
/// Put a line into the conversation that the model did not produce and did
/// not ask for — a `!cmd` the user ran, and what it printed. The model has
/// to see it: the user is talking about that output on the next turn.
pub fn note(self: *Conversation, text: []const u8) !void {
const msgs = self.list();
try msgs.append(try messages_mod.textMessage(self.alloc(), "user", text));
}
/// Replace the whole conversation (compaction rewrote it). The messages
/// must already be allocated from this conversation's arena.
pub fn replace(self: *Conversation, rewritten: []const Value) !void {
const msgs = self.list();
msgs.clearRetainingCapacity();
self.compaction_window = .{};
try msgs.appendSlice(rewritten);
}
};
fn cloneArray(a: Allocator, source: std.json.Array) !std.json.Array {
var aw: std.Io.Writer.Allocating = .init(a);
var s: std.json.Stringify = .{ .writer = &aw.writer };
try s.write(Value{ .array = source });
const cloned = try std.json.parseFromSliceLeaky(Value, a, aw.writer.buffered(), .{ .allocate = .alloc_always });
if (cloned != .array) return error.InvalidConversation;
return cloned.array;
}
fn textOf(a: Allocator, t: repl.Turn) !Value {
if (t.notification) return @import("session_wake.zig").message(a, t.text);
return messages_mod.textMessage(a, switch (t.role) {
.user => "user",
.assistant => "assistant",
}, t.text);
}
fn isUserPrompt(v: Value) bool {
if (v != .object or @import("session_wake.zig").isNotice(v)) return false;
const role = v.object.get("role") orelse return false;
if (role != .string or !std.mem.eql(u8, role.string, "user")) return false;
const content = v.object.get("content") orelse return false;
if (content == .string) return true;
// Image user messages are an array of text + image blocks (#577), not a
// tool_result wrapper (those also ride the user role).
if (content != .array) return false;
for (content.array.items) |b| {
if (b != .object) continue;
const ty = b.object.get("type") orelse continue;
if (ty != .string) continue;
if (std.mem.eql(u8, ty.string, "tool_result")) return false;
if (std.mem.eql(u8, ty.string, "image") or
std.mem.eql(u8, ty.string, "image_url") or
std.mem.eql(u8, ty.string, "input_image")) return true;
}
return false;
}
const testing = std.testing;
fn roleOf(v: Value) []const u8 {
return v.object.get("role").?.string;
}
test "adopt takes the whole transcript once, then only the new prompt" {
var convo = Conversation.init(testing.allocator);
defer convo.deinit();
// Turn 1: nothing here yet, so the frontend's transcript seeds it.
try convo.adopt(&.{.{ .role = .user, .text = "one" }});
try testing.expectEqual(@as(usize, 1), convo.len());
// The engine then writes what only it knows: a tool call and its result.
const msgs = convo.list();
try msgs.append(try messages_mod.textMessage(convo.alloc(), "assistant", "TOOL_USE_BLOCK"));
// Turn 2: the frontend hands back its flattened rows. The tool block must
// survive, and "one" must not be duplicated.
try convo.adopt(&.{
.{ .role = .user, .text = "one" },
.{ .role = .assistant, .text = "answer" },
.{ .role = .user, .text = "two" },
});
try testing.expectEqual(@as(usize, 3), convo.len());
try testing.expectEqualStrings("TOOL_USE_BLOCK", msgs.items[1].object.get("content").?.string);
try testing.expectEqualStrings("two", msgs.items[2].object.get("content").?.string);
}
test "#714: adopt does not replay an identical trailing user prompt" {
var convo = Conversation.init(testing.allocator);
defer convo.deinit();
try convo.adopt(&.{.{ .role = .user, .text = "Read SPEC.md" }});
try convo.adopt(&.{.{ .role = .user, .text = "Read SPEC.md" }});
try testing.expectEqual(@as(usize, 1), convo.len());
const msgs = convo.list();
try msgs.append(try messages_mod.textMessage(convo.alloc(), "assistant", "affinity is the git root"));
// The same words after an answer are a new ask (learn-auto, a re-type).
try convo.adopt(&.{
.{ .role = .user, .text = "Read SPEC.md" },
.{ .role = .assistant, .text = "affinity is the git root" },
.{ .role = .user, .text = "Read SPEC.md" },
});
try testing.expectEqual(@as(usize, 3), convo.len());
try testing.expectEqualStrings("Read SPEC.md", msgs.items[2].object.get("content").?.string);
}
test "reset clears the conversation; rewind drops back to before the last prompt" {
var convo = Conversation.init(testing.allocator);
defer convo.deinit();
try convo.adopt(&.{.{ .role = .user, .text = "first" }});
const msgs = convo.list();
try msgs.append(try messages_mod.textMessage(convo.alloc(), "assistant", "reply"));
try convo.adopt(&.{ .{ .role = .user, .text = "first" }, .{ .role = .assistant, .text = "reply" }, .{ .role = .user, .text = "second" } });
try testing.expectEqual(@as(usize, 3), convo.len());
convo.compaction_window = .{ .canonical_blob = @as([32]u8, @splat(7)) };
convo.rewind();
try testing.expectEqual(@as(?[32]u8, @as([32]u8, @splat(7))), convo.compaction_window.canonical_blob);
try testing.expectEqual(@as(usize, 2), convo.len());
try testing.expectEqualStrings("assistant", roleOf(convo.list().items[1]));
convo.reset();
try testing.expectEqual(@as(?[32]u8, null), convo.compaction_window.canonical_blob);
try testing.expectEqual(@as(usize, 0), convo.len());
// Usable again after a reset — the arena was freed, not poisoned.
try convo.adopt(&.{.{ .role = .user, .text = "fresh" }});
try testing.expectEqual(@as(usize, 1), convo.len());
try testing.expectEqualStrings("fresh", convo.list().items[0].object.get("content").?.string);
}
test "a tool result is not mistaken for the human prompt on rewind" {
var convo = Conversation.init(testing.allocator);
defer convo.deinit();
try convo.adopt(&.{.{ .role = .user, .text = "run it" }});
const a = convo.alloc();
const msgs = convo.list();
try msgs.append(try messages_mod.textMessage(a, "assistant", "calling"));
// Anthropic wraps a tool_result in a USER message whose content is an array.
var blocks = std.json.Array.init(a);
try blocks.append(try messages_mod.toolResultMessage(a, .anthropic, "id-1", "ok", false));
var wrapper: std.json.ObjectMap = .empty;
try wrapper.put(a, "role", .{ .string = "user" });
try wrapper.put(a, "content", .{ .array = blocks });
try msgs.append(.{ .object = wrapper });
convo.rewind();
// Back to before "run it" — not to just before the tool result.
try testing.expectEqual(@as(usize, 0), convo.len());
}
test "rewind treats an image user message as the human prompt (#577)" {
var convo = Conversation.init(testing.allocator);
defer convo.deinit();
const a = convo.alloc();
const img = try @import("vision.zig").imageMessage(a, .anthropic, "look", .{
.media_type = "image/png",
.b64 = "AAA=",
.label = "/tmp/a.png",
});
try convo.list().append(img);
try testing.expectEqual(@as(usize, 1), convo.len());
convo.rewind();
try testing.expectEqual(@as(usize, 0), convo.len());
}