Skip to content

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

Python
13.5 KB
Raw Blame
//! The automatic half of the learning loop.
//!
//! `graff learn` shipped as a complete engine that nothing ever called: every
//! trial needed a human to type it, so no workspace ever produced a second
//! generation. This module is the missing edge. When a session that did real
//! model work ends, it configures the workspace's store if it has none, counts
//! the session and — on cadence — starts one detached trial in the background.
//!
//! Deliberate limits, because a trial spends real model calls:
//!   * a workspace earns a store only once it has done real model work, and it
//!     gets exactly one automatic attempt at creating one,
//!   * automatic promotion still needs `auto.enabled` in the immutable
//!     configuration plus every statistical gate,
//!   * one trial per cadence window, never two at once, and
//!   * `GRAFF_LEARN_AUTO=off` disables the trigger outright.

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

const posix_process_groups = switch (builtin.os.tag) {
    .windows, .wasi => false,
    else => true,
};

const store_mod = @import("learn_store.zig");
const checkpoint = @import("learn_checkpoint.zig");
const scoring = @import("scoring.zig");
const util = @import("util.zig");

pub const schema = "codegraff.learn.auto.v1";
pub const file_name = "auto.json";
pub const log_name = "auto.log";

/// Sessions between trials, and the floor on wall-clock between them. A busy
/// day of short sessions should not queue up a trial per session.
pub const default_every_sessions: u64 = 5;
pub const default_minimum_interval_ms: i64 = 6 * 60 * 60 * 1000;

pub const Record = struct {
    schema: []const u8 = schema,
    sessions_since_trial: u64 = 0,
    trials_started: u64 = 0,
    last_started_unix_ms: i64 = 0,
};

pub const Skip = enum {
    /// GRAFF_LEARN_AUTO said no.
    disabled,
    /// Nothing to learn from: the session made no model calls.
    idle_session,
    /// This workspace has no learning store and has not earned an automatic
    /// one: too little model work, or its one bootstrap attempt already ran.
    unconfigured,
    /// The configuration keeps promotion manual, so a background trial would
    /// only pile up evidence nobody reads.
    manual_only,
    /// Another learning operation holds the engine lock.
    busy,
    /// Cadence not reached yet.
    not_due,
};

pub const Started = struct { resumed: bool, contribute: bool };

pub const Outcome = union(enum) {
    skipped: Skip,
    started: Started,
    /// This workspace does real work and has no learning store yet, so the
    /// caller should create one now. Claimed once per workspace: a bootstrap
    /// that cannot succeed here (no python3, no usable credential) must not
    /// retry at the end of every session forever.
    needs_store,
};

/// Marker claiming the single automatic bootstrap this workspace gets.
const bootstrap_marker = ".graff/learn-auto-init";
/// Enough model calls that this is a working repository, not a one-liner.
const bootstrap_minimum_calls: u64 = 5;

const dir_permissions: Io.File.Permissions =
    if (builtin.os.tag == .windows) .default_dir else .fromMode(0o700);

/// Claim this workspace's one automatic bootstrap. The marker is created
/// exclusively, so two sessions ending at once cannot both start materializing
/// a kit into the same tree.
pub fn claimBootstrap(io: Io, base: Io.Dir, model_calls: u64) Outcome {
    if (model_calls < bootstrap_minimum_calls) return .{ .skipped = .unconfigured };
    // A workspace that has never written a session has no .graff yet.
    base.createDir(io, ".graff", dir_permissions) catch |err| switch (err) {
        error.PathAlreadyExists => {},
        else => return .{ .skipped = .unconfigured },
    };
    const file = base.createFile(io, bootstrap_marker, .{ .exclusive = true }) catch
        return .{ .skipped = .unconfigured };
    file.close(io);
    return .needs_store;
}

pub const Options = struct {
    /// Model calls this session made; zero means there is nothing new to learn
    /// from and the trigger stays quiet.
    model_calls: u64,
    /// Fleet + learning-privacy allow publishing prompt-free aggregate grades.
    contribute: bool,
    every_sessions: u64 = default_every_sessions,
    minimum_interval_ms: i64 = default_minimum_interval_ms,
};

/// Off only when explicitly turned off: the loop is on by default in a
/// workspace that has already opted into learning by initializing a store.
pub fn enabled(value: ?[]const u8) bool {
    const raw = value orelse return true;
    if (std.ascii.eqlIgnoreCase(raw, "off") or std.mem.eql(u8, raw, "0") or
        std.ascii.eqlIgnoreCase(raw, "false") or std.ascii.eqlIgnoreCase(raw, "no")) return false;
    return true;
}

pub fn due(record: Record, now_unix_ms: i64, options: Options) bool {
    if (record.sessions_since_trial < options.every_sessions) return false;
    // A never-run store is due as soon as the session count says so; a clock
    // that jumped backwards must not make a trial unreachable forever.
    if (record.last_started_unix_ms <= 0) return true;
    const elapsed = now_unix_ms -| record.last_started_unix_ms;
    return elapsed < 0 or elapsed >= options.minimum_interval_ms;
}

pub fn load(arena: Allocator, store: *store_mod.Store) Record {
    const bytes = store_mod.readFileNoFollow(store.io, store.refs, file_name, arena, 4096) catch return .{};
    const record = std.json.parseFromSliceLeaky(Record, arena, bytes, .{}) catch return .{};
    if (!std.mem.eql(u8, record.schema, schema)) return .{};
    return record;
}

pub fn save(gpa: Allocator, store: *store_mod.Store, record: Record) !void {
    const bytes = try store_mod.jsonBytes(gpa, record);
    defer gpa.free(bytes);
    try store.writeAtomicReplace(store.refs, file_name, bytes);
}

fn hasPendingTrial(store: *store_mod.Store) bool {
    const file = store.refs.openFile(store.io, checkpoint.file_name, .{ .follow_symlinks = false, .resolve_beneath = true }) catch return false;
    file.close(store.io);
    return true;
}

/// Build the automatic `learn init` command. Kept next to the trial argv so
/// both background children are testable without spawning.
pub fn initArgv(argv: *[3][]const u8, exe_path: []const u8) []const []const u8 {
    argv.* = .{ exe_path, "learn", "init" };
    return argv;
}

/// Own process group (when the OS has them): the child outlives this session,
/// and a Ctrl-C aimed at the shell's foreground group afterwards must not
/// kill suite generation or a tournament mid-holdout.
fn spawnDetached(io: Io, argv: []const []const u8, log: ?Io.File) bool {
    _ = std.process.spawn(io, .{
        .argv = argv,
        .stdin = .ignore,
        .stdout = if (log) |file| .{ .file = file } else .ignore,
        .stderr = if (log) |file| .{ .file = file } else .ignore,
        .pgid = if (posix_process_groups) 0 else null,
    }) catch return false;
    return true;
}

/// Detached `graff learn init` of this executable. Session end must not wait
/// on suite generation (~38s of CPU); the next session that finds a store
/// starts counting toward a trial.
pub fn startInit(io: Io, exe_path: []const u8) bool {
    var argv_buf: [3][]const u8 = undefined;
    const argv = initArgv(&argv_buf, exe_path);
    const log = Io.Dir.cwd().createFile(io, ".graff/learn-auto-init.log", .{ .truncate = true }) catch null;
    defer if (log) |file| file.close(io);
    return spawnDetached(io, argv, log);
}

/// Build the trial command. Kept separate from spawning so the shape of an
/// automatic trial is testable without starting one.
pub fn trialArgv(argv: *[8][]const u8, exe_path: []const u8, resumed: bool, contribute: bool) []const []const u8 {
    var argc: usize = 0;
    for ([_][]const u8{ exe_path, "--learning-privacy", if (contribute) "aggregate" else "local", "learn", "run", "--auto" }) |arg| {
        argv[argc] = arg;
        argc += 1;
    }
    // A checkpointed tournament must continue, not restart: restarting would
    // re-expose the holdout it already reserved.
    if (resumed) {
        argv[argc] = "--resume";
        argc += 1;
    }
    if (contribute) {
        argv[argc] = "--submit";
        argc += 1;
    }
    return argv[0..argc];
}

fn openLog(store: *store_mod.Store) ?Io.File {
    return store.root.createFile(store.io, log_name, .{ .truncate = true }) catch null;
}

/// Count this session and, when due, start one detached trial. Never fails the
/// session: every error path is a skip.
pub fn maybeStart(gpa: Allocator, arena: Allocator, io: Io, environ: *const std.process.Environ.Map, options: Options) Outcome {
    if (!enabled(environ.get("GRAFF_LEARN_AUTO"))) return .{ .skipped = .disabled };
    if (options.model_calls == 0) return .{ .skipped = .idle_session };
    var store = store_mod.Store.openAt(io, Io.Dir.cwd()) catch
        return claimBootstrap(io, Io.Dir.cwd(), options.model_calls);
    defer store.deinit();
    var lock = store.acquireLock(0) catch return .{ .skipped = .busy };
    var lock_held = true;
    defer if (lock_held) lock.deinit();

    const config = store.loadConfig(arena) catch return .{ .skipped = .unconfigured };
    if (!config.value.auto.enabled) return .{ .skipped = .manual_only };

    var record = load(arena, &store);
    record.sessions_since_trial +|= 1;
    const now = util.unixMs(io);
    if (!due(record, now, options)) {
        save(gpa, &store, record) catch {};
        return .{ .skipped = .not_due };
    }

    // Contribution needs a signing key as well as consent. Asking for
    // `--submit` without one fails the whole trial in preflight, so a machine
    // that cannot sign simply learns locally.
    // Formal evidence is not represented by the current signed remote receipt.
    // Keep this trial local even when ordinary aggregate contribution is on.
    const contribute = config.value.formal_check == null and options.contribute and
        scoring.loadScoreKey(io, arena, environ) != null;
    const resumed = hasPendingTrial(&store);
    const exe_path = std.process.executablePathAlloc(io, gpa) catch return .{ .skipped = .unconfigured };
    defer gpa.free(exe_path);
    var argv_buf: [8][]const u8 = undefined;
    const argv = trialArgv(&argv_buf, exe_path, resumed, contribute);

    record.sessions_since_trial = 0;
    record.trials_started +|= 1;
    record.last_started_unix_ms = now;
    save(gpa, &store, record) catch {};

    const log = openLog(&store);
    defer if (log) |file| file.close(io);
    // Release the engine lock before the child asks for it.
    lock.deinit();
    lock_held = false;

    if (!spawnDetached(io, argv, log)) return .{ .skipped = .busy };
    // Deliberately not waited on. The trial reports through
    // `graff learn status` and .graff/learn/auto.log.
    return .{ .started = .{ .resumed = resumed, .contribute = contribute } };
}

test "the trigger is on unless it is explicitly turned off" {
    try std.testing.expect(enabled(null));
    try std.testing.expect(enabled("1"));
    try std.testing.expect(enabled("on"));
    try std.testing.expect(!enabled("off"));
    try std.testing.expect(!enabled("OFF"));
    try std.testing.expect(!enabled("0"));
    try std.testing.expect(!enabled("false"));
    try std.testing.expect(!enabled("no"));
}

test "cadence needs both the session count and the interval" {
    const options: Options = .{ .model_calls = 1, .contribute = false };
    const hour = 60 * 60 * 1000;
    try std.testing.expect(!due(.{ .sessions_since_trial = 4 }, 100 * hour, options));
    // Never run before: the session count alone is enough.
    try std.testing.expect(due(.{ .sessions_since_trial = 5 }, 100 * hour, options));
    try std.testing.expect(!due(.{ .sessions_since_trial = 9, .last_started_unix_ms = 99 * hour }, 100 * hour, options));
    try std.testing.expect(due(.{ .sessions_since_trial = 9, .last_started_unix_ms = 90 * hour }, 100 * hour, options));
    // A backwards clock jump must not wedge the loop permanently.
    try std.testing.expect(due(.{ .sessions_since_trial = 9, .last_started_unix_ms = 200 * hour }, 100 * hour, options));
}

test "a workspace bootstraps itself once, and only after real model work" {
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    // A one-liner session is not worth an 11MB kit and a spending cadence.
    try std.testing.expectEqual(
        Outcome{ .skipped = .unconfigured },
        claimBootstrap(io, tmp.dir, bootstrap_minimum_calls - 1),
    );
    // Real work: claimed, and .graff is created for a workspace that has none.
    try std.testing.expectEqual(
        Outcome.needs_store,
        claimBootstrap(io, tmp.dir, bootstrap_minimum_calls),
    );
    // Claimed exactly once: a bootstrap that failed must not retry forever.
    try std.testing.expectEqual(
        Outcome{ .skipped = .unconfigured },
        claimBootstrap(io, tmp.dir, 1000),
    );
}

test "an automatic trial always carries the two-key auto flag and never restarts a checkpoint" {
    var argv: [8][]const u8 = undefined;
    const local = trialArgv(&argv, "graff", false, false);
    try std.testing.expectEqualSlices([]const u8, &.{ "graff", "--learning-privacy", "local", "learn", "run", "--auto" }, local);
    const resumed = trialArgv(&argv, "graff", true, true);
    try std.testing.expectEqualSlices([]const u8, &.{ "graff", "--learning-privacy", "aggregate", "learn", "run", "--auto", "--resume", "--submit" }, resumed);
}

test "an automatic init is a bare learn init of this executable" {
    var argv: [3][]const u8 = undefined;
    const got = initArgv(&argv, "graff");
    try std.testing.expectEqualSlices([]const u8, &.{ "graff", "learn", "init" }, got);
}