Skip to content

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

Python
16.9 KB
Raw Blame
//! #554's REPL surface: `/snapshot` captures the active sandbox's filesystem
//! into `.graff/sessions/<session>/snapshots/<id>/`, `/rewind <id>` brings one
//! back up, `/teleport <id>` restores the same tar on a different CLI backend,
//! and `/snapshot gc` drops old snapshot trees.
//!
//! `/rewind` was already taken by the CONVERSATION rewind (commands_model.zig,
//! `/rewind <n>`), and the two are deliberately the same word: they are the
//! same gesture on two different substrates. The argument decides which — a
//! number is a prompt index and falls through to the old handler untouched,
//! anything else is a snapshot id. This module is dispatched from
//! commands_session.tryHandle, which runs BEFORE commands_model, so the
//! numeric path is reached exactly as it was.
//!
//! A sandbox rewind restores FILESYSTEM state and nothing else. The
//! conversation and the event log stay canonical, every output here says so,
//! and processes inside the sandbox are relaunched rather than resumed.
//!
//! Every failure here is an explanation. No sandbox attached, no docker
//! installed, no such snapshot, a backend that cannot capture at all: each
//! prints what is true and returns, because a slash command that panics on a
//! missing container runtime is worse than one that does nothing.

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

const agent_mod = @import("agent.zig");
const Agent = agent_mod.Agent;
const ansi = @import("ansi.zig");
const style = &ansi.style;
const main_mod = @import("main.zig");
const sandbox = @import("sandbox.zig");
const sandbox_docker = @import("sandbox_docker.zig");
const util = @import("util.zig");

/// Process-wide CLI backends. A live `Handle` points into a Sandbox that
/// points back here, so these outlive any one command — the same shape as
/// sandbox.active(). `g_container` is the Apple Container slot teleport uses.
var g_docker: sandbox_docker.Docker = undefined;
var g_container: sandbox_docker.Docker = undefined;

/// The sentence every rewind output carries. A user who believed the
/// transcript had moved too would read it as the record of a run that never
/// happened, so this is pinned by a test rather than left to phrasing.
pub const log_note = "the conversation and event log are NOT rewound — filesystem state only";

/// True when `/rewind <arg>` means a snapshot rather than a prompt index.
/// An empty or all-digit argument belongs to the conversation rewind.
pub fn isSnapshotArg(arg: []const u8) bool {
    if (arg.len == 0) return false;
    for (arg) |c| if (!std.ascii.isDigit(c)) return true;
    return false;
}

/// What went wrong, in words a user can act on.
pub fn explain(err: anyerror) []const u8 {
    return switch (err) {
        error.SandboxUnavailable => "the sandbox backend is not usable here — `docker` is not on PATH, or the daemon refused the command",
        error.SnapshotUnsupported => "this backend cannot capture state (the local backend runs without isolation, so there is nothing to snapshot) — attach a Docker sandbox instead",
        error.SnapshotFailed => "the capture failed — `docker commit`/`docker save` did not succeed",
        error.RestoreFailed => "the restore failed — `load`/`run` did not succeed, and the previous sandbox was already released; nothing is attached now, so `/snapshot attach` starts a fresh one",
        error.ExecFailed => "the sandbox command could not be run",
        else => "the sandbox operation failed",
    };
}

/// `/snapshot` (capture), `/snapshot attach [image]`, `/snapshot detach`,
/// `/snapshot list`, `/snapshot gc [n]`, `/teleport <id> [backend]`, and
/// `/rewind <id>`. Returns false for anything else, including `/rewind` with
/// a numeric or absent argument.
pub fn tryHandle(root: *Agent, arena: Allocator, line: []const u8, out: *Io.Writer) !bool {
    if (argOf(line, "/snapshot")) |arg| {
        if (std.mem.eql(u8, arg, "list") or std.mem.eql(u8, arg, "ls")) {
            try renderList(root, arena, out);
        } else if (argOf(arg, "attach")) |image| {
            try attach(root, image, out);
        } else if (std.mem.eql(u8, arg, "detach")) {
            try detach(out);
        } else if (argOf(arg, "gc") != null or std.mem.eql(u8, arg, "gc")) {
            try collect(root, arena, if (argOf(arg, "gc")) |n| n else "", out);
        } else {
            try capture(root, arena, out);
        }
        try out.flush();
        return true;
    }
    if (argOf(line, "/teleport")) |arg| {
        try teleport(root, arena, arg, out);
        try out.flush();
        return true;
    }
    if (argOf(line, "/rewind")) |arg| {
        if (!isSnapshotArg(arg)) return false; // the conversation rewind owns it
        try restore(root, arena, arg, out);
        try out.flush();
        return true;
    }
    return false;
}

/// Named CLI backend. `docker` is the default attach; `container` is Apple
/// Container — same wire, different binary. Unknown names stay null so the
/// command can explain instead of guessing.
pub fn backendNamed(name: []const u8) ?[]const u8 {
    if (std.mem.eql(u8, name, "docker") or std.mem.eql(u8, name, "container")) return name;
    return null;
}

/// The argument after `cmd`, or null when `line` is a different command.
/// `/rewinds` is not `/rewind`: the next byte has to be a space or the end.
fn argOf(line: []const u8, cmd: []const u8) ?[]const u8 {
    if (!std.mem.startsWith(u8, line, cmd)) return null;
    const rest = line[cmd.len..];
    if (rest.len > 0 and rest[0] != ' ' and rest[0] != '\t') return null;
    return std.mem.trim(u8, rest, " \t");
}

/// Put this session in a Docker sandbox so there is something to capture.
/// Nothing attaches one automatically in the MVP — the bot runner and the DGM
/// trials that #554 exists for will call sandbox.attach directly — so this is
/// how a person drives the seam by hand.
fn attach(root: *Agent, image: []const u8, out: *Io.Writer) !void {
    // One Docker slot per process, and a live Handle points into it, so a
    // second attach would move the ground under the first. Refusing is the
    // honest answer; `/snapshot detach` is one keystroke away.
    if (sandbox.active()) |prev| {
        try out.print("a sandbox is already attached ({s}) — /snapshot detach first\n", .{prev.handle.id});
        return;
    }
    g_docker = fillCli(root, "docker", image);
    const backend = g_docker.backend();
    if (!backend.available()) {
        try out.print("docker backend: {s}\n", .{explain(error.SandboxUnavailable)});
        return;
    }
    const handle = backend.acquire(root.gpa, root.session_name) catch |err| {
        try out.print("could not start a sandbox — {s}\n", .{explain(err)});
        return;
    };
    sandbox.attach(.{ .backend = backend, .handle = handle });
    try out.print("sandbox attached — {s} on {s} (key {s})\n", .{ handle.id, g_docker.image, handle.key });
}

fn detach(out: *Io.Writer) !void {
    const act = sandbox.active() orelse {
        try out.writeAll("no sandbox is attached\n");
        return;
    };
    act.handle.release();
    sandbox.detach();
    try out.writeAll("sandbox released — its snapshots stay on disk\n");
}

fn capture(root: *Agent, arena: Allocator, out: *Io.Writer) !void {
    if (!sandbox.safeName(root.session_name)) {
        try out.writeAll("this session has no name a snapshot directory could be built from\n");
        return;
    }
    const act = sandbox.active() orelse {
        try out.print("no sandbox is active — {s}/snapshot{s} captures the filesystem of a sandbox this session is running in, and there is none attached\n", .{ style.accent, style.reset });
        try renderList(root, arena, out);
        return;
    };
    if (!act.backend.available()) {
        try out.print("{s} backend: {s}\n", .{ act.backend.name(), explain(error.SandboxUnavailable) });
        return;
    }
    const id = try sandbox.newId(arena, root.io);
    const blob: sandbox.Blob = .{
        .io = root.io,
        .dir = sandbox.workspace(),
        .rel = try sandbox.payloadPath(arena, root.session_name, id),
    };
    const payload = act.handle.snapshot(root.gpa, blob) catch |err| {
        try out.print("snapshot failed — {s}\n", .{explain(err)});
        return;
    };
    sandbox.writeManifest(root.io, sandbox.workspace(), arena, root.session_name, .{
        .id = id,
        .backend = act.backend.name(),
        .kind = payload.kind.tag(),
        .ref = payload.ref,
        .len = payload.len,
        .created_ms = util.unixMs(root.io),
    }) catch |err| {
        try out.print("captured the payload but could not record it: {s}\n", .{@errorName(err)});
        return;
    };
    try out.print("📸 snapshot {s}{s}{s} — {d} bytes at {s}\n", .{ style.accent, id, style.reset, payload.len, blob.rel });
    try out.print("{s}   /rewind {s} brings this filesystem back; {s}{s}\n", .{ style.dim, id, log_note, style.reset });
}

fn restore(root: *Agent, arena: Allocator, id: []const u8, out: *Io.Writer) !void {
    const found = sandbox.find(root.io, sandbox.workspace(), arena, root.session_name, id) orelse {
        try out.print("no snapshot {s} in this session — {s}/snapshot list{s} shows what there is\n", .{ id, style.accent, style.reset });
        return;
    };
    const act = sandbox.active() orelse {
        try out.print("no sandbox is active — a rewind restores a snapshot ONTO a backend, and there is none attached\n", .{});
        return;
    };
    if (!act.backend.available()) {
        try out.print("{s} backend: {s}\n", .{ act.backend.name(), explain(error.SandboxUnavailable) });
        return;
    }
    const blob: sandbox.Blob = .{
        .io = root.io,
        .dir = sandbox.workspace(),
        .rel = try sandbox.payloadPath(arena, root.session_name, found.id),
    };
    // Release BEFORE restoring, not after. The restore acquires the same key,
    // and a backend evicts the warm container on a key before it starts one —
    // so releasing afterwards would `docker rm -f` the container the restore
    // had just brought up. The old sandbox is doomed either way; this order is
    // the one where the new one survives.
    const key = try arena.dupe(u8, act.handle.key);
    act.handle.release();
    sandbox.detach();
    const fresh = act.backend.acquireFromSnapshot(root.gpa, key, found.payload(), blob) catch |err| {
        try out.print("rewind failed — {s}\n", .{explain(err)});
        return;
    };
    sandbox.attach(.{ .backend = act.backend, .handle = fresh });
    try out.print("⏪ sandbox rewound to {s}{s}{s} ({s}, {d} bytes)\n", .{ style.accent, found.id, style.reset, found.backend, found.len });
    try out.print("{s}   {s}; processes inside the sandbox were relaunched, not resumed{s}\n", .{ style.dim, log_note, style.reset });
}

fn fillCli(root: *Agent, bin_name: []const u8, image: []const u8) sandbox_docker.Docker {
    return .{
        .io = root.io,
        .path_env = main_mod.g_path_env,
        .image = if (image.len > 0) image else sandbox_docker.default_image,
        .bin_name = bin_name,
    };
}

fn slot(bin_name: []const u8) *sandbox_docker.Docker {
    return if (std.mem.eql(u8, bin_name, "container")) &g_container else &g_docker;
}

/// `/snapshot gc [n]` — keep the newest n snapshots (default 1). The exo miss
/// #554 named: leftover tars pile up unless something deletes them.
fn collect(root: *Agent, arena: Allocator, keep_arg: []const u8, out: *Io.Writer) !void {
    if (!sandbox.safeName(root.session_name)) {
        try out.writeAll("this session has no name a snapshot directory could be built from\n");
        return;
    }
    const keep: usize = if (keep_arg.len == 0) 1 else std.fmt.parseInt(usize, keep_arg, 10) catch {
        try out.print("usage: /snapshot gc [n] — n is how many newest snapshots to keep (default 1)\n", .{});
        return;
    };
    const result = try sandbox.gc(root.io, sandbox.workspace(), arena, root.session_name, keep);
    if (result.removed == 0) {
        try out.print("snapshot gc: nothing to drop — {d} kept\n", .{result.kept});
        return;
    }
    try out.print("snapshot gc: dropped {d} ({d} bytes), kept {d}\n", .{ result.removed, result.bytes, result.kept });
}

/// Restore `id` onto a backend other than the one that captured it. Dest
/// defaults to `container` when the live backend is docker (or nothing is
/// attached), and `docker` when the live backend is already container.
fn teleport(root: *Agent, arena: Allocator, arg: []const u8, out: *Io.Writer) !void {
    var it = std.mem.tokenizeAny(u8, arg, " \t");
    const id = it.next() orelse {
        try out.writeAll("usage: /teleport <id> [docker|container]\n");
        return;
    };
    const dest_arg = it.next() orelse "";
    const dest = if (dest_arg.len == 0)
        defaultDest()
    else
        backendNamed(dest_arg) orelse {
            try out.print("unknown backend {s} — teleport dest is docker or container\n", .{dest_arg});
            return;
        };
    try restoreOnto(root, arena, id, dest, out);
}

fn defaultDest() []const u8 {
    const act = sandbox.active() orelse return "container";
    return if (std.mem.eql(u8, act.backend.name(), "container")) "docker" else "container";
}

fn restoreOnto(root: *Agent, arena: Allocator, id: []const u8, dest_name: []const u8, out: *Io.Writer) !void {
    const found = sandbox.find(root.io, sandbox.workspace(), arena, root.session_name, id) orelse {
        try out.print("no snapshot {s} in this session — {s}/snapshot list{s} shows what there is\n", .{ id, style.accent, style.reset });
        return;
    };
    const dest_slot = slot(dest_name);
    dest_slot.* = fillCli(root, dest_name, "");
    const dest = dest_slot.backend();
    if (!dest.available()) {
        try out.print("{s} backend: {s}\n", .{ dest.name(), explain(error.SandboxUnavailable) });
        return;
    }
    const blob: sandbox.Blob = .{
        .io = root.io,
        .dir = sandbox.workspace(),
        .rel = try sandbox.payloadPath(arena, root.session_name, found.id),
    };
    const key = if (sandbox.active()) |act|
        try arena.dupe(u8, act.handle.key)
    else
        try arena.dupe(u8, root.session_name);
    if (sandbox.active()) |act| {
        act.handle.release();
        sandbox.detach();
    }
    const fresh = dest.acquireFromSnapshot(root.gpa, key, found.payload(), blob) catch |err| {
        try out.print("teleport failed — {s}\n", .{explain(err)});
        return;
    };
    sandbox.attach(.{ .backend = dest, .handle = fresh });
    try out.print("teleported {s}{s}{s} onto {s} ({d} bytes)\n", .{ style.accent, found.id, style.reset, dest.name(), found.len });
    try out.print("{s}   {s}; processes inside the sandbox were relaunched, not resumed{s}\n", .{ style.dim, log_note, style.reset });
}

fn renderList(root: *Agent, arena: Allocator, out: *Io.Writer) !void {
    const items = try sandbox.list(root.io, sandbox.workspace(), arena, root.session_name);
    if (items.len == 0) {
        try out.writeAll("no snapshots in this session yet\n");
        return;
    }
    try out.print("{s}snapshots{s}\n", .{ style.bold, style.reset });
    for (items) |m| {
        try out.print("  {s}{s}{s}  {s:<8} {d:>10} B  {s}\n", .{ style.accent, m.id, style.reset, m.backend, m.len, m.ref });
    }
    try out.print("{s}usage: /rewind <id> restores here; /teleport <id> [docker|container] restores onto another backend; /snapshot gc drops old tars; {s}{s}\n", .{ style.dim, log_note, style.reset });
}

test "a numeric /rewind argument stays with the conversation rewind" {
    try std.testing.expect(!isSnapshotArg(""));
    try std.testing.expect(!isSnapshotArg("3"));
    try std.testing.expect(!isSnapshotArg("12"));
    try std.testing.expect(isSnapshotArg("1754000000-ab12cd34"));
    try std.testing.expect(isSnapshotArg("abc"));
}

test "argOf claims only the exact command" {
    try std.testing.expectEqualStrings("", argOf("/snapshot", "/snapshot").?);
    try std.testing.expectEqualStrings("list", argOf("/snapshot list", "/snapshot").?);
    try std.testing.expect(argOf("/snapshots", "/snapshot") == null);
    try std.testing.expect(argOf("/rewinds 3", "/rewind") == null);
    try std.testing.expectEqualStrings("3", argOf("/rewind 3", "/rewind").?);
    try std.testing.expectEqualStrings("id container", argOf("/teleport id container", "/teleport").?);
}

test "teleport dest names are docker or container" {
    try std.testing.expectEqualStrings("docker", backendNamed("docker").?);
    try std.testing.expectEqualStrings("container", backendNamed("container").?);
    try std.testing.expect(backendNamed("daytona") == null);
    try std.testing.expect(backendNamed("") == null);
}

test "every sandbox failure has an explanation, and rewind never claims the log moved" {
    inline for (.{
        error.SandboxUnavailable,
        error.SnapshotUnsupported,
        error.SnapshotFailed,
        error.RestoreFailed,
        error.ExecFailed,
    }) |err| {
        try std.testing.expect(explain(err).len > 20);
    }
    try std.testing.expect(std.mem.indexOf(u8, log_note, "NOT rewound") != null);
    try std.testing.expect(std.mem.indexOf(u8, log_note, "filesystem state only") != null);
}