graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! Durable background jobs (crash survival, ADR 0218). A finite job started in
//! the background writes its stdout and stderr straight to files under
//! `.graff/job-output/<id>/` instead of pipes into graff, and its shell leaves
//! an exit receipt beside them. graff dying mid-task (a crash, a SIGKILL, a
//! closed terminal) then neither kills the job on its next write nor loses
//! what it printed: resuming the session re-attaches a job that is still
//! running and reports one that finished while graff was down
//! (job_recover.zig).
//!
//! POSIX only. Servers and foreground commands keep pipes: a server never
//! finishes, and a foreground call's `cmd &` idioms depend on pipe EOF.
const std = @import("std");
const builtin = @import("builtin");
const Io = std.Io;
const Allocator = std.mem.Allocator;
pub const enabled = builtin.os.tag != .windows and builtin.os.tag != .wasi;
pub const dir_rel = ".graff/job-output";
/// A reader that has caught up past this empties the file: the job appends,
/// so it carries on from 0 and a chatty job cannot fill the disk while graff
/// watches it.
pub const trunc_at: u64 = 8 * 1024 * 1024;
/// The job's own shell writes its exit status to `$2` on the way out. An
/// EXIT trap in that one shell, not a parent wrapper, so `exec cmd` still
/// makes `cmd` the process-group leader. `set --` leaves the command with no
/// positional parameters, as under `sh -c cmd`. A command that execs or sets
/// its own EXIT trap leaves no receipt; graff's own waitpid still sees it.
pub const wrapper = "__graff_cmd=$1 __graff_exit=$2; set --; trap 'printf \"%s\\n\" \"$?\" >\"$__graff_exit\"' EXIT; eval \"$__graff_cmd\"";
/// What survives the process that started the job.
pub const Meta = struct {
id: u64,
session: []const u8,
cmd: []const u8,
cwd: []const u8 = "",
pid: i32 = 0,
start_id: u64 = 0,
owner_pid: i32 = 0,
owner_start_id: u64 = 0,
started_ms: i64 = 0,
};
pub const Stream = enum(u1) { stdout, stderr };
/// A job's capture directory and how far each output file has been read.
pub const Capture = struct {
dir: []u8, // absolute, gpa-owned
offs: [2]u64 = .{ 0, 0 },
readers: [2]?Io.File = .{ null, null },
/// Re-attached after a restart: not graff's child, so it is watched
/// through its receipt and its leader's start identity, never waitpid.
adopted: bool = false,
start_id: u64 = 0,
pub fn path(self: *const Capture, buf: []u8, name: []const u8) []const u8 {
return std.fmt.bufPrint(buf, "{s}/{s}", .{ self.dir, name }) catch "";
}
};
/// Test override for the capture root, so unit tests never touch the
/// workspace's own `.graff`.
pub var test_root: ?[]const u8 = null;
/// `<cwd>/.graff/job-output`, absolute: a job running in a worktree agent's
/// cwd, or past a later workspace switch, still writes its receipt here.
pub fn rootPath(io: Io, buf: []u8) ?[]const u8 {
if (builtin.is_test) if (test_root) |r| return std.fmt.bufPrint(buf, "{s}", .{r}) catch null;
var cwd: [std.fs.max_path_bytes]u8 = undefined;
const n = std.process.currentPath(io, &cwd) catch return null;
return std.fmt.bufPrint(buf, "{s}/" ++ dir_rel, .{cwd[0..n]}) catch null;
}
/// A capture made ready for spawn: the child's argv and its two output files.
pub const Setup = struct {
capture: *Capture,
argv: [6][]const u8,
exit_path: []u8, // gpa-owned; argv borrows it until spawn returns
out: Io.File,
err: Io.File,
/// Spawn copied argv and dup'ed the files: the child holds its own.
pub fn spawned(self: *Setup, gpa: Allocator, io: Io) void {
self.out.close(io);
self.err.close(io);
gpa.free(self.exit_path);
}
/// Spawn failed: nothing runs, so nothing is kept.
pub fn abandon(self: *Setup, gpa: Allocator, io: Io) void {
self.spawned(gpa, io);
release(gpa, io, self.capture, true);
}
};
/// Create `<root>/<id>/` with empty output files and the argv that runs `cmd`
/// with an exit receipt. Null when it cannot: durability is best-effort, and
/// the caller keeps the job on pipes.
pub fn prepare(io: Io, gpa: Allocator, id: u64, cmd: []const u8) ?Setup {
var rbuf: [std.fs.max_path_bytes]u8 = undefined;
const root = rootPath(io, &rbuf) orelse return null;
if (!builtin.is_test) @import("graff_dir.zig").ensure(io, Io.Dir.cwd()); // #1273: out of git
return create(io, gpa, root, id, cmd) catch null;
}
pub fn create(io: Io, gpa: Allocator, root: []const u8, id: u64, cmd: []const u8) !Setup {
const dir = try std.fmt.allocPrint(gpa, "{s}/{d}", .{ root, id });
errdefer gpa.free(dir);
try Io.Dir.cwd().createDirPath(io, dir);
errdefer Io.Dir.cwd().deleteTree(io, dir) catch {};
const capture = try gpa.create(Capture);
errdefer gpa.destroy(capture);
capture.* = .{ .dir = dir };
var buf: [std.fs.max_path_bytes]u8 = undefined;
const out = try openAppend(capture.path(&buf, "stdout"));
errdefer out.close(io);
const err = try openAppend(capture.path(&buf, "stderr"));
errdefer err.close(io);
const exit_path = try gpa.dupe(u8, capture.path(&buf, "exit"));
return .{
.capture = capture,
.argv = .{ "/bin/sh", "-c", wrapper, "/bin/sh", cmd, exit_path },
.exit_path = exit_path,
.out = out,
.err = err,
};
}
/// O_APPEND, so a reader may empty the file under a writer (see trunc_at).
fn openAppend(path: []const u8) !Io.File {
const fd = try std.posix.openat(std.posix.AT.FDCWD, path, .{ .ACCMODE = .WRONLY, .CREAT = true, .TRUNC = true, .APPEND = true, .CLOEXEC = true }, 0o600);
return .{ .handle = fd, .flags = .{ .nonblocking = false } };
}
/// Best-effort: a missing record costs recovery, never the job.
pub fn writeMeta(io: Io, capture: *const Capture, meta: Meta) void {
var buf: [std.fs.max_path_bytes]u8 = undefined;
var jbuf: [16 * 1024]u8 = undefined;
var w: Io.Writer = .fixed(&jbuf);
var s: std.json.Stringify = .{ .writer = &w };
s.write(meta) catch return;
Io.Dir.cwd().writeFile(io, .{ .sub_path = capture.path(&buf, "meta.json"), .data = w.buffered() }) catch {};
}
pub fn readMeta(io: Io, arena: Allocator, dir: []const u8) ?Meta {
var buf: [std.fs.max_path_bytes]u8 = undefined;
const p = std.fmt.bufPrint(&buf, "{s}/meta.json", .{dir}) catch return null;
const data = Io.Dir.cwd().readFileAlloc(io, p, arena, .limited(64 * 1024)) catch return null;
return std.json.parseFromSliceLeaky(Meta, arena, data, .{ .ignore_unknown_fields = true, .allocate = .alloc_always }) catch null;
}
/// The recorded exit status, or null while the job runs (or when it ended
/// without its shell reaching the EXIT trap).
pub fn exitStatus(io: Io, dir: []const u8) ?u8 {
var buf: [std.fs.max_path_bytes]u8 = undefined;
const p = std.fmt.bufPrint(&buf, "{s}/exit", .{dir}) catch return null;
var data: [16]u8 = undefined;
const text = Io.Dir.cwd().readFile(io, p, &data) catch return null;
return std.fmt.parseInt(u8, std.mem.trim(u8, text, " \t\r\n"), 10) catch null;
}
/// The exit reached the model: a restart must not report it again.
pub fn markReported(io: Io, capture: *const Capture) void {
var buf: [std.fs.max_path_bytes]u8 = undefined;
Io.Dir.cwd().writeFile(io, .{ .sub_path = capture.path(&buf, "reported"), .data = "" }) catch {};
}
pub fn reported(io: Io, dir: []const u8) bool {
var buf: [std.fs.max_path_bytes]u8 = undefined;
const p = std.fmt.bufPrint(&buf, "{s}/reported", .{dir}) catch return false;
Io.Dir.cwd().access(io, p, .{}) catch return false;
return true;
}
/// New bytes of one output file since the last read, appended to `out`. Keeps
/// the newest `keep` bytes of a larger burst and returns true when it skipped
/// older ones.
pub fn readNew(io: Io, gpa: Allocator, capture: *Capture, which: Stream, keep: usize, out: *std.ArrayList(u8)) bool {
const i = @backingInt(which);
const f = capture.readers[i] orelse blk: {
var buf: [std.fs.max_path_bytes]u8 = undefined;
const opened = Io.Dir.cwd().openFile(io, capture.path(&buf, @tagName(which)), .{ .mode = .read_write }) catch return false;
capture.readers[i] = opened;
break :blk opened;
};
const off = &capture.offs[i];
const len = f.length(io) catch return false;
if (len < off.*) off.* = 0; // emptied elsewhere: start over
var skipped = false;
if (len - off.* > keep) {
off.* = len - keep;
skipped = true;
}
var chunk: [64 * 1024]u8 = undefined;
var bufs = [_][]u8{&chunk};
while (off.* < len) {
const n = f.readPositional(io, &bufs, off.*) catch break;
if (n == 0) break;
const take = @min(n, len - off.*);
out.appendSlice(gpa, chunk[0..take]) catch break;
off.* += take;
}
if (off.* >= trunc_at and off.* == (f.length(io) catch 0)) {
f.setLength(io, 0) catch return skipped;
off.* = 0;
}
return skipped;
}
/// Close the readers and free the capture. The directory goes too unless the
/// job still writes to it (kept past session end).
pub fn release(gpa: Allocator, io: Io, capture: *Capture, remove: bool) void {
for (capture.readers) |r| if (r) |f| f.close(io);
if (remove) Io.Dir.cwd().deleteTree(io, capture.dir) catch {};
gpa.free(capture.dir);
gpa.destroy(capture);
}
test "the receipt records the command's own exit status, and output lands in the files" {
if (!enabled) return error.SkipZigTest;
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
var rbuf: [std.fs.max_path_bytes]u8 = undefined;
const root = rbuf[0..try tmp.dir.realPath(io, &rbuf)];
var setup = try create(io, gpa, root, 42, "printf out; printf err >&2; [ $# -eq 0 ] || exit 9; exit 7");
var child = try std.process.spawn(io, .{ .argv = &setup.argv, .stdin = .ignore, .stdout = .{ .file = setup.out }, .stderr = .{ .file = setup.err } });
const capture = setup.capture;
setup.spawned(gpa, io);
const term = try child.wait(io);
try std.testing.expectEqual(@as(u8, 7), term.exited);
try std.testing.expectEqual(@as(?u8, 7), exitStatus(io, capture.dir));
var out: std.ArrayList(u8) = .empty;
defer out.deinit(gpa);
try std.testing.expect(!readNew(io, gpa, capture, .stdout, 1024, &out));
try std.testing.expect(!readNew(io, gpa, capture, .stderr, 1024, &out));
try std.testing.expectEqualStrings("outerr", out.items);
_ = readNew(io, gpa, capture, .stdout, 1024, &out); // nothing new: offsets advanced
try std.testing.expectEqualStrings("outerr", out.items);
writeMeta(io, capture, .{ .id = 42, .session = "s-1", .cmd = "exit 7", .pid = 99 });
var arena = std.heap.ArenaAllocator.init(gpa);
defer arena.deinit();
const meta = readMeta(io, arena.allocator(), capture.dir).?;
try std.testing.expectEqual(@as(u64, 42), meta.id);
try std.testing.expectEqualStrings("s-1", meta.session);
try std.testing.expect(!reported(io, capture.dir));
markReported(io, capture);
try std.testing.expect(reported(io, capture.dir));
release(gpa, io, capture, true);
try std.testing.expectError(error.FileNotFound, tmp.dir.statFile(io, "42", .{}));
}
test "exec keeps the command as the group leader; a burst past keep skips its oldest bytes" {
if (!enabled) return error.SkipZigTest;
const gpa = std.testing.allocator;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
var rbuf: [std.fs.max_path_bytes]u8 = undefined;
const root = rbuf[0..try tmp.dir.realPath(io, &rbuf)];
// `exec` replaces the job's shell, so no receipt: the leader is the command.
var setup = try create(io, gpa, root, 43, "printf 0123456789; exec /bin/sh -c 'echo $$ >&2'");
var child = try std.process.spawn(io, .{ .argv = &setup.argv, .stdin = .ignore, .stdout = .{ .file = setup.out }, .stderr = .{ .file = setup.err }, .pgid = 0 });
const pid = child.id.?;
const capture = setup.capture;
defer release(gpa, io, capture, true);
setup.spawned(gpa, io);
_ = try child.wait(io);
try std.testing.expectEqual(@as(?u8, null), exitStatus(io, capture.dir));
var out: std.ArrayList(u8) = .empty;
defer out.deinit(gpa);
try std.testing.expect(readNew(io, gpa, capture, .stdout, 4, &out));
try std.testing.expectEqualStrings("6789", out.items);
out.clearRetainingCapacity();
_ = readNew(io, gpa, capture, .stderr, 64, &out);
var pbuf: [16]u8 = undefined;
try std.testing.expectEqualStrings(try std.fmt.bufPrint(&pbuf, "{d}\n", .{pid}), out.items);
}