Skip to content

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

Python
6.2 KB
Raw Blame
//! Idle lifecycle for background bash jobs (#199). A dev server graff
//! started can outlive the turn, the session's attention, and — per the
//! postmortem on #199 — three days of a machine's memory and a port. The
//! activity graff can see without proxying traffic: bytes the job wrote, a
//! bash_output read or blocking wait, a /jobs touch. Past `warn_ms` of that
//! silence the user gets one dim notice naming the stop and the pin; past
//! `stop_ms` the job's whole process group is killed and the job stays
//! listed as stopped-idle with its command, so `/jobs restart` or a plain
//! rerun brings it back. Pinned jobs (`/jobs keep`) are exempt.
//!
//! No SIGSTOP "pause" state: it keeps the memory and the port and cannot
//! notice a request. Stopped-with-the-command-kept is the honest pause.

const std = @import("std");
const Io = std.Io;
const tool_pulse = @import("tool_pulse.zig");
const util = @import("util.zig");

pub const Policy = struct {
    warn_ms: u64 = 30 * std.time.ms_per_min,
    stop_ms: u64 = 2 * std.time.ms_per_hour,
};

/// Session policy. GRAFF_JOB_IDLE_WARN_MINS / GRAFF_JOB_IDLE_STOP_MINS
/// override the defaults; 0 turns that step off.
pub var policy: Policy = .{};

pub const Verdict = enum { none, warn, stop };

pub fn verdict(idle_ms: u64, warned: bool, pinned: bool) Verdict {
    return verdictUnder(policy, idle_ms, warned, pinned);
}

pub fn verdictUnder(p: Policy, idle_ms: u64, warned: bool, pinned: bool) Verdict {
    if (pinned) return .none;
    if (p.stop_ms != 0 and idle_ms >= p.stop_ms) return .stop;
    if (!warned and p.warn_ms != 0 and idle_ms >= p.warn_ms) return .warn;
    return .none;
}

/// Minutes; unparseable values are ignored, 0 disables, a week is the cap.
pub fn applyEnv(environ_map: anytype) void {
    if (environ_map.get("GRAFF_JOB_IDLE_WARN_MINS")) |v| {
        if (parseMins(v)) |ms| policy.warn_ms = ms;
    }
    if (environ_map.get("GRAFF_JOB_IDLE_STOP_MINS")) |v| {
        if (parseMins(v)) |ms| policy.stop_ms = ms;
    }
}

fn parseMins(v: []const u8) ?u64 {
    const mins = std.fmt.parseInt(u64, std.mem.trim(u8, v, " \t"), 10) catch return null;
    const capped: u64 = @min(mins, 7 * 24 * 60);
    return capped * std.time.ms_per_min;
}

/// The one dim chrome line at the warn threshold.
pub fn warnLine(buf: []u8, id: u64, idle_ms: u64, stop_ms: u64, cmd: []const u8) []const u8 {
    var a: [16]u8 = undefined;
    var b: [16]u8 = undefined;
    return std.fmt.bufPrint(buf, "· job {d} idle {s} ({s}) · stops after {s} idle · /jobs keep {d} pins it", .{
        id, tool_pulse.formatElapsed(&a, idle_ms), util.utf8Prefix(cmd, 32), tool_pulse.formatElapsed(&b, stop_ms), id,
    }) catch buf[0..0];
}

/// Pump thread: paint the warn line (hosted sink or line-REPL stdout).
pub fn warn(io: Io, id: u64, idle_ms: u64, cmd: []const u8) void {
    var buf: [160]u8 = undefined;
    const line = warnLine(&buf, id, idle_ms, policy.stop_ms, cmd);
    if (line.len > 0) tool_pulse.emitNotice(io, "{s}", .{line});
}

/// The bash_output status line for a job the policy stopped.
pub fn printStopped(w: *Io.Writer, id: u64, stop_ms: u64) !void {
    var b: [16]u8 = undefined;
    try w.print("[job {d}: stopped after {s} with no output and no reads — rerun it if it is still needed; the user pins a long-lived server with /jobs keep {d}]", .{ id, tool_pulse.formatElapsed(&b, stop_ms), id });
}

test "verdict: warn once past warn_ms, stop past stop_ms, nothing before" {
    const p: Policy = .{ .warn_ms = 1000, .stop_ms = 5000 };
    try std.testing.expectEqual(Verdict.none, verdictUnder(p, 999, false, false));
    try std.testing.expectEqual(Verdict.warn, verdictUnder(p, 1000, false, false));
    try std.testing.expectEqual(Verdict.none, verdictUnder(p, 4999, true, false)); // already warned
    try std.testing.expectEqual(Verdict.stop, verdictUnder(p, 5000, true, false));
    try std.testing.expectEqual(Verdict.stop, verdictUnder(p, 5000, false, false)); // a stop needs no prior warn
}

test "verdict: a pinned job is never warned or stopped; 0 turns a step off" {
    const p: Policy = .{ .warn_ms = 1000, .stop_ms = 5000 };
    try std.testing.expectEqual(Verdict.none, verdictUnder(p, 1_000_000, false, true));
    const no_stop: Policy = .{ .warn_ms = 1000, .stop_ms = 0 };
    try std.testing.expectEqual(Verdict.warn, verdictUnder(no_stop, 1_000_000, false, false));
    try std.testing.expectEqual(Verdict.none, verdictUnder(no_stop, 1_000_000, true, false));
    const off: Policy = .{ .warn_ms = 0, .stop_ms = 0 };
    try std.testing.expectEqual(Verdict.none, verdictUnder(off, 1_000_000, false, false));
}

test "applyEnv: minutes to ms, 0 disables, junk ignored, a week caps" {
    const saved = policy;
    defer policy = saved;
    const Env = struct {
        warn: ?[]const u8,
        stop: ?[]const u8,
        pub fn get(self: @This(), name: []const u8) ?[]const u8 {
            if (std.mem.eql(u8, name, "GRAFF_JOB_IDLE_WARN_MINS")) return self.warn;
            if (std.mem.eql(u8, name, "GRAFF_JOB_IDLE_STOP_MINS")) return self.stop;
            return null;
        }
    };
    policy = .{};
    applyEnv(Env{ .warn = "5", .stop = "0" });
    try std.testing.expectEqual(@as(u64, 5 * std.time.ms_per_min), policy.warn_ms);
    try std.testing.expectEqual(@as(u64, 0), policy.stop_ms);
    applyEnv(Env{ .warn = "junk", .stop = "99999999" });
    try std.testing.expectEqual(@as(u64, 5 * std.time.ms_per_min), policy.warn_ms);
    try std.testing.expectEqual(@as(u64, 7 * 24 * 60 * std.time.ms_per_min), policy.stop_ms);
}

test "warnLine names the job, the idle time, the stop, and the pin" {
    var buf: [160]u8 = undefined;
    const line = warnLine(&buf, 3, 30 * std.time.ms_per_min, 2 * std.time.ms_per_hour, "npm run dev -p 3002");
    try std.testing.expectEqualStrings("· job 3 idle 30m00s (npm run dev -p 3002) · stops after 2h00m idle · /jobs keep 3 pins it", line);
}

test "printStopped tells the model the job is gone and how it comes back" {
    var aw: Io.Writer.Allocating = .init(std.testing.allocator);
    defer aw.deinit();
    try printStopped(&aw.writer, 7, 2 * std.time.ms_per_hour);
    try std.testing.expect(std.mem.indexOf(u8, aw.written(), "[job 7: stopped after 2h00m") != null);
    try std.testing.expect(std.mem.indexOf(u8, aw.written(), "/jobs keep 7") != null);
}