Skip to content

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

Python
12.1 KB
Raw Blame
//! Claude Agent sessions (ADR 0309): one long-running `claude` child per
//! graff agent, held between model steps so a tool call can stay open while
//! graff's own loop runs it, and between user turns so Claude Code keeps its
//! prompt cache. A session idle past `idle_ms` is stopped; the next request
//! starts a fresh one and replays graff's history as a checkpoint.

const std = @import("std");
const Io = std.Io;
const Allocator = std.mem.Allocator;
const wire = @import("claude_agent_wire.zig");
const http = @import("http.zig");

pub const idle_ms: i64 = 5 * std.time.ms_per_min;
/// Lines carry whole assistant messages and echoed tool results; a line past
/// this is skipped (it is always an echo graff does not read).
const out_buf_len = 8 << 20;
const in_buf_len = 256 << 10;

/// A `tools/call` Claude Code is waiting on.
pub const Pending = struct {
    request_id: []u8,
    /// The JSON-RPC id, raw JSON.
    rpc_id: []u8,
    tool_use_id: []u8,
};

pub const Session = struct {
    gpa: Allocator,
    io: Io,
    child: std.process.Child,
    env: ?std.process.Environ.Map,
    in_buf: []u8,
    out_buf: []u8,
    writer: Io.File.Writer,
    reader: Io.File.Reader,
    /// Model, effort, prompt mode, system prompt, tools and folder: a change
    /// to any of them needs a new process (the CLI takes them at start).
    props_fp: u64,
    /// The tool list Claude Code last read from graff's server.
    tools_fp: u64 = 0,
    /// How many times Claude Code has read graff's tools/list.
    tools_listed: u32 = 0,
    /// graff messages Claude Code already holds, and a hash of them.
    seen: usize = 0,
    seen_fp: u64 = 0,
    rewrites: u32 = 0,
    pending: std.ArrayList(Pending) = .empty,
    /// Results graff produced for calls Claude Code has not asked for yet
    /// (it runs a response's calls one after another): tool_use id → MCP
    /// result JSON. gpa-owned keys and values.
    results: std.StringHashMapUnmanaged([]u8) = .empty,
    /// Response lines that arrived while graff waited on a control answer
    /// (a tool-list re-read while the model was already answering), kept in
    /// order for the turn that reads them.
    kept: Kept = .{},
    used_ms: i64 = 0,

    pub fn start(gpa: Allocator, io: Io, argv: []const []const u8, parent_env: ?*const std.process.Environ.Map, cwd: ?[]const u8, props_fp: u64) !*Session {
        const self = try gpa.create(Session);
        errdefer gpa.destroy(self);
        var env: ?std.process.Environ.Map = null;
        if (parent_env) |p| {
            var m = try p.clone(gpa);
            errdefer m.deinit();
            var drop: std.ArrayList([]const u8) = .empty;
            defer drop.deinit(gpa);
            for (m.keys()) |k| if (wire.dropsEnv(k)) try drop.append(gpa, k);
            for (drop.items) |k| _ = m.swapRemove(k);
            for (wire.isolation_env) |kv| try m.put(kv[0], kv[1]);
            env = m;
        }
        errdefer if (env) |*m| m.deinit();
        var child = try std.process.spawn(io, .{
            .argv = argv,
            .stdin = .pipe,
            .stdout = .pipe,
            .stderr = .ignore,
            .environ_map = if (env) |*m| m else null,
            .cwd = if (cwd) |path| .{ .path = path } else .inherit,
        });
        errdefer @import("mcp_stdio.zig").stopChild(io, &child);
        const in_buf = try gpa.alloc(u8, in_buf_len);
        errdefer gpa.free(in_buf);
        const out_buf = try gpa.alloc(u8, out_buf_len);
        self.* = .{
            .gpa = gpa,
            .io = io,
            .child = child,
            .env = env,
            .in_buf = in_buf,
            .out_buf = out_buf,
            .writer = undefined,
            .reader = undefined,
            .props_fp = props_fp,
        };
        self.writer = self.child.stdin.?.writerStreaming(io, self.in_buf);
        self.reader = self.child.stdout.?.readerStreaming(io, self.out_buf);
        return self;
    }

    pub fn send(self: *Session, line: []const u8) !void {
        const w = &self.writer.interface;
        w.writeAll(line) catch return error.ClaudeAgentExited;
        w.writeByte('\n') catch return error.ClaudeAgentExited;
        w.flush() catch return error.ClaudeAgentExited;
    }

    /// A kept line first (copied onto `a`), then the next one read.
    pub fn nextLine(self: *Session, a: Allocator, poll_stdin: bool, budget_ms: u64) ![]u8 {
        if (try self.kept.take(self.gpa, a)) |line| return line;
        return self.readLine(poll_stdin, budget_ms);
    }

    /// Claude Code abandoned a call it was waiting on.
    pub fn cancel(self: *Session, request_id: []const u8) void {
        for (self.pending.items, 0..) |p, i| if (std.mem.eql(u8, p.request_id, request_id)) {
            self.dropPending(i);
            return;
        };
    }

    /// The next line, or a stall/Esc error once `budget_ms` passes silent.
    pub fn readLine(self: *Session, poll_stdin: bool, budget_ms: u64) ![]u8 {
        const Done = union(enum) { line: anyerror![]u8, stall: http.WatchdogFired };
        var buf: [2]Done = undefined;
        var sel: Io.Select(Done) = .init(self.io, &buf);
        sel.concurrent(.line, readLineTask, .{&self.reader.interface}) catch return error.StreamStalled;
        sel.concurrent(.stall, http.deadlineStallTask, .{ self.io, poll_stdin, budget_ms }) catch {
            const only = sel.await() catch |e| {
                sel.cancelDiscard();
                return e;
            };
            sel.cancelDiscard();
            return only.line;
        };
        const first = sel.await() catch |e| {
            sel.cancelDiscard();
            return e;
        };
        sel.cancelDiscard();
        return switch (first) {
            .line => |l| l,
            .stall => |w| http.watchdogError(w, error.StreamStalled),
        };
    }

    pub fn addPending(self: *Session, request_id: []const u8, rpc_id: []const u8, tool_use_id: []const u8) !void {
        try self.pending.append(self.gpa, .{
            .request_id = try self.gpa.dupe(u8, request_id),
            .rpc_id = try self.gpa.dupe(u8, rpc_id),
            .tool_use_id = try self.gpa.dupe(u8, tool_use_id),
        });
    }

    pub fn dropPending(self: *Session, index: usize) void {
        const p = self.pending.orderedRemove(index);
        self.gpa.free(p.request_id);
        self.gpa.free(p.rpc_id);
        self.gpa.free(p.tool_use_id);
    }

    pub fn putResult(self: *Session, tool_use_id: []const u8, result: []const u8) !void {
        const gop = try self.results.getOrPut(self.gpa, tool_use_id);
        if (gop.found_existing) {
            self.gpa.free(gop.value_ptr.*);
        } else {
            gop.key_ptr.* = self.gpa.dupe(u8, tool_use_id) catch |e| {
                self.results.removeByPtr(gop.key_ptr);
                return e;
            };
        }
        gop.value_ptr.* = try self.gpa.dupe(u8, result);
    }

    /// Remove and return a stored result (caller frees with gpa).
    pub fn takeResult(self: *Session, tool_use_id: []const u8) ?[]u8 {
        const kv = self.results.fetchRemove(tool_use_id) orelse return null;
        self.gpa.free(kv.key);
        return kv.value;
    }

    pub fn stop(self: *Session) void {
        @import("mcp_stdio.zig").stopChild(self.io, &self.child);
        while (self.pending.items.len > 0) self.dropPending(self.pending.items.len - 1);
        self.pending.deinit(self.gpa);
        var it = self.results.iterator();
        while (it.next()) |kv| {
            self.gpa.free(kv.key_ptr.*);
            self.gpa.free(kv.value_ptr.*);
        }
        self.results.deinit(self.gpa);
        self.kept.deinit(self.gpa);
        if (self.env) |*m| m.deinit();
        self.gpa.free(self.in_buf);
        self.gpa.free(self.out_buf);
        self.gpa.destroy(self);
    }
};

/// Lines read ahead of the turn that owns them, oldest first. gpa-owned.
pub const Kept = struct {
    lines: std.ArrayList([]u8) = .empty,
    head: usize = 0,

    pub fn keep(self: *Kept, gpa: Allocator, line: []const u8) !void {
        const copy = try gpa.dupe(u8, line);
        errdefer gpa.free(copy);
        try self.lines.append(gpa, copy);
    }

    /// The oldest kept line, copied onto `a`, or null when none is left.
    pub fn take(self: *Kept, gpa: Allocator, a: Allocator) !?[]u8 {
        if (self.head == self.lines.items.len) return null;
        const line = try a.dupe(u8, self.lines.items[self.head]);
        gpa.free(self.lines.items[self.head]);
        self.head += 1;
        if (self.head == self.lines.items.len) {
            self.lines.clearRetainingCapacity();
            self.head = 0;
        }
        return line;
    }

    pub fn deinit(self: *Kept, gpa: Allocator) void {
        for (self.lines.items[self.head..]) |line| gpa.free(line);
        self.lines.deinit(gpa);
        self.* = .{};
    }
};

test "kept lines come back in order, and what is left is freed" {
    const gpa = std.testing.allocator;
    var arena = std.heap.ArenaAllocator.init(gpa);
    defer arena.deinit();
    var kept: Kept = .{};
    defer kept.deinit(gpa);
    try kept.keep(gpa, "message_start");
    try kept.keep(gpa, "content_block_start");
    try std.testing.expectEqualStrings("message_start", (try kept.take(gpa, arena.allocator())).?);
    try kept.keep(gpa, "content_block_delta");
    try std.testing.expectEqualStrings("content_block_start", (try kept.take(gpa, arena.allocator())).?);
    try std.testing.expectEqualStrings("content_block_delta", (try kept.take(gpa, arena.allocator())).?);
    try std.testing.expectEqual(@as(?[]u8, null), try kept.take(gpa, arena.allocator()));
    try kept.keep(gpa, "left for stop");
}

fn readLineTask(r: *Io.Reader) anyerror![]u8 {
    while (true) {
        const line = r.takeDelimiter('\n') catch |err| switch (err) {
            error.StreamTooLong => {
                _ = r.discardDelimiterInclusive('\n') catch return error.ClaudeAgentExited;
                continue;
            },
            error.ReadFailed => return error.ClaudeAgentExited,
        };
        return line orelse error.ClaudeAgentExited;
    }
}

// Sessions are keyed by the owning Agent's address. A session is taken out
// while a request uses it, so parallel subagents never share one. A reused
// address is harmless: the history hash no longer matches, and the stale
// session is replaced.
var mutex: Io.Mutex = .init;
var sessions: std.AutoHashMapUnmanaged(usize, *Session) = .empty;
var map_gpa: ?Allocator = null;

pub fn take(io: Io, owner: usize) ?*Session {
    mutex.lockUncancelable(io);
    defer mutex.unlock(io);
    const kv = sessions.fetchRemove(owner) orelse return null;
    return kv.value;
}

/// Return a session after a request, stopping any other session left idle
/// past `idle_ms` (a finished subagent's, or the user walked away).
pub fn put(io: Io, owner: usize, s: *Session, now_ms: i64) void {
    var idle: std.ArrayList(*Session) = .empty;
    defer idle.deinit(s.gpa);
    {
        mutex.lockUncancelable(io);
        defer mutex.unlock(io);
        const gpa = map_gpa orelse blk: {
            map_gpa = s.gpa;
            break :blk s.gpa;
        };
        var it = sessions.iterator();
        while (it.next()) |kv| if (now_ms - kv.value_ptr.*.used_ms > idle_ms) idle.append(s.gpa, kv.value_ptr.*) catch {};
        for (idle.items) |old| {
            var it2 = sessions.iterator();
            while (it2.next()) |kv| if (kv.value_ptr.* == old) {
                _ = sessions.remove(kv.key_ptr.*);
                break;
            };
        }
        sessions.put(gpa, owner, s) catch {
            idle.append(s.gpa, s) catch {};
        };
    }
    for (idle.items) |old| old.stop();
}

/// Stop every held session (graff is exiting).
pub fn stopAll(io: Io) void {
    var all: std.ArrayList(*Session) = .empty;
    mutex.lockUncancelable(io);
    const gpa = map_gpa;
    if (gpa) |g| {
        var it = sessions.valueIterator();
        while (it.next()) |s| all.append(g, s.*) catch {};
        sessions.deinit(g);
        sessions = .empty;
    }
    mutex.unlock(io);
    for (all.items) |s| s.stop();
    if (gpa) |g| all.deinit(g);
}

/// The session held for `owner` is past its idle window.
pub fn expired(s: *const Session, now_ms: i64) bool {
    return s.used_ms != 0 and now_ms - s.used_ms > idle_ms;
}