Skip to content

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

Python
17.1 KB
Raw Blame
//! #441: the append-only per-session transcript — the history compaction
//! discards, kept and kept greppable.
//!
//! THE FALSE PREMISE THIS CORRECTS. #438 (issue #410) added a prompt line
//! telling the model that the session file preserves what compaction throws
//! away. It does not. `.graff/sessions/<name>.session.json` is a SINGLE JSON
//! object whose `messages` array is rewritten in place: when compact() replaces
//! a hundred turns with one summary, the very next autosave overwrites the file
//! and the pre-compaction history is gone for good. Prime-agent's "grep your
//! own conversation log" property — recovering the exact wording of an error a
//! summary paraphrased — therefore had no graff equivalent. The trace and
//! trajectory JSONLs do not provide it either: they record events for
//! telemetry, not the conversation for recall.
//!
//! WHAT THIS IS. `.graff/sessions/<name>.transcript.jsonl`, one line per
//! message as it FIRST enters history, appended and never rewritten. A line is
//! that message's provider-native JSON verbatim — JSON escapes every control
//! character, so a message is always exactly one line — which makes the file
//! greppable with no tooling and re-readable with no parser state. Compaction
//! cannot touch it: it rewrites `root.messages` in memory, while every line
//! already on disk stays exactly where it was.
//!
//! WHERE IT HOOKS. session.queueSave, the point at which the autosave already
//! observes a new message. The history has ~25 mutation sites (session_writer's
//! own comment counts them); hooking each one is the hand-maintained dirty flag
//! that file rejects for the same reason. Observing the array instead costs one
//! serialization per turn — see `collect`'s fast path.
//!
//! IDENTITY. A message is already transcribed when its serialized bytes digest
//! to a line already written — counted, not positioned. `counts` is a MULTISET
//! of the digests on disk, because a rewrite reorders as well as removes:
//! compact() builds `[handoff summary] ++ recent_messages` with the tail
//! verbatim, so the summary sits at the FRONT of the history while it is the
//! LAST line in the file, and any position-based match re-appends the tail
//! behind it. Counting instead: the tail's digests are already accounted for,
//! only the summary is new. emergencyTrim drops a prefix and the survivors are
//! likewise accounted for; capOversizedToolOutputs edits a message in place,
//! and the transcript simply keeps the PRE-truncation bytes, which is the whole
//! point of it. A genuine repeat is still recorded twice: the second identical
//! "ok" is the history's SECOND, and the file holds only one.
//!
//! The one thing counting gives up, deliberately: a message identical to one
//! whose every copy compaction has already discarded is not written again. Its
//! bytes are in the file verbatim either way, so recall — what this exists for
//! — is unaffected; only exact multiplicity is, and only after a compaction.
//!
//! BOUNDS. Subagents are excluded — their history is never persisted, so there
//! is no durable session to attach a transcript to (#409's rule, unchanged).
//! The size cap ROTATES rather than head-truncates; `rotate` says why. The
//! lifecycle is #409's rather than a second one: `tool_spill.sweepSessionsOnce`
//! now reclaims transcripts and artifact dirs together, by the same rule (the
//! session file is the ground truth for "this session is gone") and the same
//! grace window.

const std = @import("std");
const Io = std.Io;
const Value = std.json.Value;
const Allocator = std.mem.Allocator;

const agent_mod = @import("agent.zig");
const Agent = agent_mod.Agent;
const session_index = @import("session_index.zig");
const tool_spill = @import("tool_spill.zig"); // #409: safeName + the shared session sweep

pub const transcript_ext = session_index.transcript_ext;
pub const transcript_rotated_ext = session_index.transcript_rotated_ext;

/// Ceiling on ONE generation, so a session keeps at most twice this on disk
/// (the live file plus the one rotated generation). `pub var` so a test can
/// shrink it without writing 16 MiB.
pub var cap_bytes: usize = 16 * 1024 * 1024;

/// `.graff/sessions/<name>.transcript.jsonl`. Pure; #411's post-compaction note
/// and anything else that needs the path calls this instead of re-deriving the
/// filename.
///
/// Forward-slashed on every platform, Windows included — deliberately, and
/// downstream may rely on it. session_index.zig states the invariant and why.
pub fn transcriptPath(arena: Allocator, name: []const u8) ![]const u8 {
    return std.fmt.allocPrint(arena, "{s}/{s}{s}", .{ session_index.sessions_dir, name, transcript_ext });
}

/// The previous generation (see `rotate`), which is just as greppable.
pub fn rotatedPath(arena: Allocator, name: []const u8) ![]const u8 {
    return std.fmt.allocPrint(arena, "{s}/{s}{s}", .{ session_index.sessions_dir, name, transcript_rotated_ext });
}

/// The transcript path for THIS agent, or null when it has none: a subagent, a
/// name that cannot be a file, or a session no save has reached yet. #411's
/// note calls this rather than building the path itself, so it can never cite a
/// file that does not exist.
pub fn activePath(root: *Agent, arena: Allocator) ?[]const u8 {
    if (root.sub or g.total == 0) return null;
    if (g.name.len == 0 or !std.mem.eql(u8, g.name, root.session_name)) return null;
    return transcriptPath(arena, g.name) catch null;
}

/// How many messages this session's transcript is known to hold — the "N
/// messages" half of a note that cites the path. Known: a resume re-reads the
/// live generation, not the rotated one behind it.
pub fn lineCount() usize {
    return g.total;
}

/// The session currently attached and what is already on disk for it. One root
/// agent owns the durable session, so this is process state rather than agent
/// state; `attach` re-seeds it whenever the name changes (startup, /resume,
/// /new, /save <other>, the AI-title rename).
const State = struct {
    name: []const u8 = "", // a slice of name_buf; "" = nothing attached
    /// How many lines carry each digest — see IDENTITY above.
    counts: std.AutoHashMapUnmanaged(u64, u32) = .empty,
    total: usize = 0, // lines accounted for
    /// The cursor the fast path rides: this many messages of the CURRENT
    /// history are accounted for, and `anchor` is the digest the last of them
    /// had when that became true. If it still does, nothing before it moved.
    seen_len: usize = 0,
    anchor: u64 = 0,
    bytes: usize = 0, // size of the live generation on disk
};

var g: State = .{};
// Owns `g.name`'s bytes, and `g.counts` is allocated with the page allocator
// rather than the session's `gpa`, for session_writer.zig's #365 reason: this
// is PROCESS state that outlives every session in it, so charging it to the
// conversation's allocator makes the last session's state a leak at exit —
// and, in the test suite, a free across a test boundary that has already
// reclaimed the arena underneath it.
var name_buf: [256]u8 = undefined;
const state_gpa = std.heap.page_allocator;
// std.Io owns the synchronization primitives (session_writer.zig's note): the
// save path is the caller's thread, and `serve` can hold more than one session
// in a process.
var mutex: Io.Mutex = .init;

fn digest(line: []const u8) u64 {
    return std.hash.Wyhash.hash(0x441, line);
}

/// One message as it goes to disk. Serializing to the arena is the same walk
/// std.json.Stringify performs for the save itself.
fn serialize(arena: Allocator, m: Value) ?[]const u8 {
    var aw: Io.Writer.Allocating = .init(arena);
    var s: std.json.Stringify = .{ .writer = &aw.writer };
    s.write(m) catch return null;
    return aw.toOwnedSlice() catch null;
}

const Line = struct { text: []const u8, hash: u64 };

fn push(arena: Allocator, out: *std.ArrayList(Line), m: Value) void {
    const text = serialize(arena, m) orelse return;
    out.append(arena, .{ .text = text, .hash = digest(text) }) catch {};
}

/// The messages in `items` that are not yet in the transcript, in order.
///
/// The fast path is the one every ordinary turn takes: the accounted-for prefix
/// is still in place — proven by re-digesting its LAST message — so everything
/// after it is new by construction. Two serializations plus one per new
/// message, instead of one per message in the whole history, every save.
///
/// The slow path runs on the first append of a session, and after a rewrite:
/// tally the history's digests in order and write a message only once its
/// running tally passes the number of lines the file already has for it.
fn collect(arena: Allocator, items: []const Value, out: *std.ArrayList(Line)) void {
    if (g.seen_len > 0 and g.seen_len <= items.len and lastMatches(arena, items[g.seen_len - 1], g.anchor)) {
        for (items[g.seen_len..]) |m| push(arena, out, m);
        return;
    }
    var seen: std.AutoHashMapUnmanaged(u64, u32) = .empty; // arena-owned, dies with the save
    for (items) |m| {
        const text = serialize(arena, m) orelse continue;
        const h = digest(text);
        const e = seen.getOrPut(arena, h) catch return;
        e.value_ptr.* = (if (e.found_existing) e.value_ptr.* else 0) + 1;
        if (e.value_ptr.* <= (g.counts.get(h) orelse 0)) continue; // this copy is already a line
        out.append(arena, .{ .text = text, .hash = h }) catch return;
    }
}

fn lastMatches(arena: Allocator, last: Value, anchor: u64) bool {
    const text = serialize(arena, last) orelse return false;
    return digest(text) == anchor;
}

/// Append every message that is not already in this session's transcript.
/// Called from session.queueSave, after the blank-draft and unchanged-session
/// gates, so a transcript exists exactly when a durable session does.
///
/// Never fails a save: every error path is a skip. A skipped append costs a
/// duplicate line on the next one, never a lost message.
///
/// Serializes into a scratch arena of its own rather than the caller's: the
/// turn path's arena lives as long as the process (mainloop.Ctx.arena), and a
/// copy of every new message per turn parked there for the whole session would
/// double what the conversation already costs.
pub fn record(root: *Agent, dir: Io.Dir, name: []const u8) void {
    if (root.sub) return; // a subagent's history is never persisted
    if (!tool_spill.safeName(name)) return; // never write outside .graff/sessions
    if (root.messages.items.len == 0) return;
    const io = root.io;
    var scratch = std.heap.ArenaAllocator.init(root.gpa);
    defer scratch.deinit();
    const arena = scratch.allocator();
    mutex.lockUncancelable(io);
    defer mutex.unlock(io);
    attach(io, dir, arena, name);
    if (!std.mem.eql(u8, g.name, name)) return; // attach failed; try again next save
    const items = root.messages.items;
    var pending: std.ArrayList(Line) = .empty;
    collect(arena, items, &pending);
    // A batch that never reached the disk leaves the cursor alone, so the next
    // save writes it instead of stepping over it.
    if (pending.items.len > 0 and !flush(io, dir, arena, name, pending.items)) return;
    g.seen_len = items.len;
    g.anchor = if (serialize(arena, items[items.len - 1])) |text| digest(text) else 0;
}

/// Point the state at `name`, rebuilding it from disk when the session changed.
/// A resumed conversation is the case that matters: its history is restored
/// whole, and every message in it is already a line in its transcript.
fn attach(io: Io, dir: Io.Dir, arena: Allocator, name: []const u8) void {
    if (g.name.len > 0 and std.mem.eql(u8, g.name, name)) return;
    detach();
    if (name.len > name_buf.len) return; // safeName caps well below this
    @memcpy(name_buf[0..name.len], name);
    g.name = name_buf[0..name.len];
    // #409's sweep, now shared: at the first append as well as the first spill,
    // so a run that never spills still reclaims what deleted sessions left.
    tool_spill.sweepSessionsOnce(io, dir, arena, name);
    seed(io, dir, arena, name);
}

fn detach() void {
    g.counts.deinit(state_gpa);
    g = .{};
}

/// Read back the digests of the lines already in the live generation. Exact,
/// because a line IS the serialized message: hashing the line bytes reproduces
/// the digest the writer recorded. An unreadable file seeds nothing, which
/// costs duplicated lines and never a lost one.
fn seed(io: Io, dir: Io.Dir, arena: Allocator, name: []const u8) void {
    const path = transcriptPath(arena, name) catch return;
    const data = dir.readFileAlloc(io, path, arena, .limited(cap_bytes)) catch return;
    g.bytes = data.len;
    // '\n' explicitly, both here and in `flush` — never a platform default.
    // The digest is over the line's bytes, so a stray '\r' from an editor that
    // rewrote the file with CRLF would silently stop every line matching and
    // re-append the whole history; strip it rather than trust the writer.
    var it = std.mem.splitScalar(u8, data, '\n');
    while (it.next()) |raw| {
        const line = std.mem.trimEnd(u8, raw, "\r");
        if (line.len == 0) continue; // the trailing newline, or a torn write
        bump(digest(line));
    }
}

fn bump(h: u64) void {
    const e = g.counts.getOrPut(state_gpa, h) catch return;
    e.value_ptr.* = (if (e.found_existing) e.value_ptr.* else 0) + 1;
    g.total += 1;
}

fn flush(io: Io, dir: Io.Dir, arena: Allocator, name: []const u8, pending: []const Line) bool {
    var buf: std.ArrayList(u8) = .empty;
    for (pending) |line| {
        buf.appendSlice(arena, line.text) catch return false;
        buf.append(arena, '\n') catch return false;
    }
    if (g.bytes +| buf.items.len > cap_bytes) rotate(io, dir, arena, name);
    const path = transcriptPath(arena, name) catch return false;
    const size = appendWhole(io, dir, path, buf.items) orelse return false;
    g.bytes = size;
    for (pending) |line| bump(line.hash); // only now: these bytes are on disk
    return true;
}

/// ONE positional write at the current end of file (playbook.appendLine's and
/// serve_events.EventLog's shape). Nothing already in the file is read, moved
/// or rewritten — that is the whole append-only guarantee, and it is why a
/// compaction running against the same session cannot cost the transcript a
/// byte. Returns the new size.
///
/// `.read = true` is load-bearing on WINDOWS and cost-free everywhere else.
/// Io.Dir.createFile maps `read` straight onto the NT access mask
/// (`GENERIC = .{ .WRITE = true, .READ = flags.read }`), and a write-only
/// handle carries FILE_GENERIC_WRITE, which does NOT include
/// FILE_READ_ATTRIBUTES. `File.stat` is NtQueryInformationFile(.All), which
/// needs exactly that right, so on a write-only handle it fails with
/// ACCESS_DENIED — and this function then returned null having already CREATED
/// the file, so every Windows transcript was an empty file and no message was
/// ever recorded. The path-based `statFile` fallback keeps a future std change
/// from re-introducing a silent no-write instead of an append.
fn appendWhole(io: Io, dir: Io.Dir, path: []const u8, data: []const u8) ?usize {
    dir.createDirPath(io, session_index.sessions_dir) catch {};
    @import("graff_dir.zig").ensureIgnore(io, dir); // #1273
    const f = dir.createFile(io, path, .{ .truncate = false, .read = true }) catch return null;
    defer f.close(io);
    const end: u64 = if (f.stat(io)) |st| st.size else |_| blk: {
        const st = dir.statFile(io, path, .{}) catch return null;
        break :blk st.size;
    };
    f.writePositionalAll(io, data, end) catch return null;
    return @as(usize, @intCast(end)) + data.len;
}

/// At the cap the live generation is RENAMED aside, never trimmed in place.
///
/// Head-truncation would mean reading the file, dropping a prefix and writing
/// what is left back over it — an in-place rewrite of the history, which is
/// precisely the failure mode this file exists to fix, and one a crash halfway
/// through turns into total loss. A rename is a single atomic syscall: the old
/// bytes survive intact under a sibling name the model greps exactly like the
/// live one, every line ever written stays a line somewhere, and the bound is
/// simply two generations. The previous generation is what the next rotation
/// replaces, so disk use is capped rather than merely slowed.
///
/// Replacing an EXISTING previous generation is the part Windows would
/// normally refuse (its rename does not overwrite). Io.Dir.rename is the
/// replacing one on every OS — dirRenameWindows passes replace_if_exists=true,
/// and Io.Dir.renamePreserve is the variant that fails on a taken name — so
/// the second and every later rotation works there too. The test below rotates
/// twice for exactly that reason.
fn rotate(io: Io, dir: Io.Dir, arena: Allocator, name: []const u8) void {
    const live = transcriptPath(arena, name) catch return;
    const prev = rotatedPath(arena, name) catch return;
    dir.rename(live, dir, prev, io) catch return;
    g.bytes = 0;
    // The digests stay: they identify messages, not file offsets, so a message
    // already in the rotated generation is still not re-appended to the live one.
}

pub fn resetForTest() void {
    detach();
}

// The tests live in session_transcript_tests.zig — the 600-line cap — and are
// reached through test_hooks.zig.