Skip to content

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

Python
19.6 KB
Raw Blame
//! Scripted `graff repl` Model: conversation history, slash commands, and a
//! pane renderer for piped/CI stdin. TTY `graff repl` uses the ordinary line
//! REPL, not this Model. Styling is local (`repl_style.zig`).
//!
//! The model call runs on a background thread so the ensō thinking spinner
//! can animate while a scripted job is in flight. The whole conversation is
//! sent each turn. Without a model wired in it falls back to a pure i64
//! arithmetic evaluator, which keeps it fully unit-testable.
//!
//! Split across sibling files (#123, 600-line goal): repl_parser.zig (the
//! offline arithmetic evaluator), repl_util.zig (stateless string/format
//! helpers), repl_markdown.zig (Markdown and table rendering), and
//! repl_model_{turn,commands,render}.zig (the Model struct's
//! method bodies, reached back through the member aliases below via the
//! same technique used for the Agent struct split — self.method() and
//! Model.method() resolve unchanged regardless of which file backs them).

const std = @import("std");
const zz = @import("repl_style.zig");

const parser_mod = @import("repl_parser.zig");
const util = @import("repl_util.zig");
const repl_markdown = @import("repl_markdown.zig");
const model_turn = @import("repl_model_turn.zig");
const model_commands = @import("repl_model_commands.zig");
const model_render = @import("repl_model_render.zig");
const repl_run = @import("repl_run.zig");
const repl_types = @import("repl_types.zig");

test {
    _ = repl_types;
    _ = parser_mod;
    _ = util;
    _ = repl_markdown;
    _ = model_turn;
    _ = model_commands;
    _ = model_render;
    _ = repl_run;
    _ = @import("repl_style.zig");
}

// ---------------------------------------------------------------------------
// Arithmetic evaluator — split out to repl_parser.zig (#123, 600-line goal):
// EvalError/Parser/eval (+ their tests) live there now. Offline fallback
// engine + the thing the headless tests exercise when no turn_fn is wired in.
// ---------------------------------------------------------------------------

// ---------------------------------------------------------------------------
// Model hook — injected by the host (src/main.zig). The callback receives the
// whole conversation + the current thinking settings and returns a reply
// allocated with the given allocator (caller owns), or null on failure. This
// keeps repl.zig decoupled from the harness's Agent/Provider (no circular import).
// ---------------------------------------------------------------------------

// The vocabulary itself lives in repl_types.zig (move+alias, 600-line cap);
// #551 grew Params a `mode`/`strict` so a frontend's policy reaches the engine.
pub const Effort = repl_types.Effort;
pub const Turn = repl_types.Turn;
pub const Mode = repl_types.Mode;
pub const Params = repl_types.Params;
pub const StreamBuf = repl_types.StreamBuf;
pub const TurnFn = repl_types.TurnFn;

pub var g_turn_fn: ?TurnFn = null;
pub var g_turn_ctx: ?*anyopaque = null;
pub var g_model_name: []const u8 = "";
/// The backend compares provider AND model; a model-only display cannot detect a seat change.
pub const ModelPick = struct { model: []const u8, changed: bool };
pub const ModelFn = *const fn (turn_ctx: ?*anyopaque, gpa: std.mem.Allocator, name: []const u8) ?ModelPick;
pub var g_models: []const u8 = ""; // comma-joined model names (for /models)
pub var g_model_fn: ?ModelFn = null; // switch the active model by name
pub const CancelFn = *const fn (turn_ctx: ?*anyopaque) void;
pub var g_cancel_fn: ?CancelFn = null; // force-interrupt the running turn (steer drain)
pub const VersionFn = *const fn (turn_ctx: ?*anyopaque, gpa: std.mem.Allocator) ?[]const u8;
pub var g_version_fn: ?VersionFn = null;
pub const UpdateFn = *const fn (turn_ctx: ?*anyopaque, gpa: std.mem.Allocator, action: []const u8) ?[]const u8;
pub var g_update_fn: ?UpdateFn = null;
pub var g_debug: bool = false; // GRAFF_REPL_DEBUG / `/debug` → dump raw stream + frames to stderr

// ---------------------------------------------------------------------------
// Look & feel.
// ---------------------------------------------------------------------------

pub const accent = util.accent;

/// `/ultracode` ember shine — a slow coral/rust/gold border sweep.
pub const ultracode_palette = [_]zz.Color{
    zz.Color.fromRgb(0xA8, 0x63, 0x43), zz.Color.fromRgb(0xB3, 0x5C, 0x49),
    zz.Color.fromRgb(0xC4, 0x51, 0x3D), zz.Color.fromRgb(0xB3, 0x5C, 0x49),
    zz.Color.fromRgb(0x9B, 0x6A, 0x35), zz.Color.fromRgb(0xA5, 0x65, 0x3B),
};

pub const enso_frames = [_][]const u8{ "◜", "◠", "◝", "◞", "◡", "◟" };
pub const braille_frames = [_][]const u8{ "⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏" };
pub const dragon_frames = [_][]const u8{ "🐉  ", "🐉 ✦", "🐉 ✧", "🐉 ✦" };

const Anim = enum { enso, braille, dragon };
pub const Toast = enum { none, copied, failed };
pub const TOAST_MS: u64 = 1500; // copy-confirmation toast window (wall-clock ms), #85

// ---------------------------------------------------------------------------
// Background model call.
// ---------------------------------------------------------------------------

pub const Job = struct {
    thread: std.Thread = undefined,
    threaded: bool = true,
    done: std.atomic.Value(bool) = std.atomic.Value(bool).init(false),
    result: ?[]const u8 = null,
    gpa: std.mem.Allocator,
    history: []Turn, // owned snapshot
    params: Params,
    stream: StreamBuf,
};

pub fn jobRun(job: *Job) void {
    const reply = if (g_turn_fn) |f| f(g_turn_ctx, job.gpa, job.history, job.params, &job.stream) else null;
    job.result = reply;
    job.done.store(true, .release);
}

// ---------------------------------------------------------------------------
// Model.
// ---------------------------------------------------------------------------

pub const Entry = struct {
    kind: Kind,
    text: []const u8, // owned by Model.alloc
    const Kind = enum { welcome, input, result, err, info, pending, assistant };
};

pub const Effect = enum { stay, quit };

pub const Model = struct {
    alloc: std.mem.Allocator,
    input: zz.TextInput,
    history: std.array_list.Managed(Entry),
    pending: ?*Job = null,

    // Settings (mirror the harness thinking controls).
    chat: bool = false,
    effort: Effort = .medium,
    fast: bool = false,
    thinking_show: bool = false,
    ultracode: bool = false,
    goal: ?[]const u8 = null, // owned
    anim: Anim = .enso,
    scroll: usize = 0,
    // Mouse drag-selection → auto-copy (OSC52). Screen rows, 0-based.
    sel_anchor_row: ?usize = null,
    sel_cur_row: ?usize = null,
    view_start: usize = 0,
    view_rows: usize = 0,
    // Copy-confirmation toast (time-based; auto-dismisses, no tick plumbing), #85.
    toast: Toast = .none,
    toast_until_ms: u64 = 0,
    last_term_width: usize = 0, // cached each frame for post-hoc markdown layout
    visible_text: std.array_list.Managed([]const u8) = undefined, // owned plaintext of visible rows
    dump_next: bool = false,
    quit_requested: bool = false,
    keepcontext: bool = true,
    strict: bool = false,
    yolo: bool = false,
    plan: bool = false,
    title: bool = true,
    session_name: ?[]const u8 = null,
    turns: usize = 0,
    chars_in: usize = 0,
    chars_out: usize = 0,
    // Steering: lines typed while a turn streams are queued here and run as
    // follow-up turns; an empty Enter force-interrupts so they drain now.
    steer_queue: std.array_list.Managed([]const u8) = undefined,
    cancel_requested: bool = false,

    pub fn setup(self: *Model, alloc: std.mem.Allocator) void {
        self.* = .{
            .alloc = alloc,
            .input = zz.TextInput.init(alloc),
            .history = std.array_list.Managed(Entry).init(alloc),
            .visible_text = std.array_list.Managed([]const u8).init(alloc),
            .steer_queue = std.array_list.Managed([]const u8).init(alloc),
            .chat = g_turn_fn != null,
        };
        self.input.setPrompt("> ");
        self.input.setPlaceholder(if (self.chat) "Ask anything, or /help" else "Try an expression, or /help");
        self.push(.welcome, "") catch {};
    }

    pub fn deinit(self: *Model) void {
        if (self.pending) |job| {
            if (job.threaded) job.thread.join();
            if (job.result) |r| self.alloc.free(r);
            for (job.history) |t| self.alloc.free(t.text);
            self.alloc.free(job.history);
            if (job.stream.buf.len > 0) self.alloc.free(job.stream.buf);
            self.alloc.destroy(job);
            self.pending = null;
        }
        for (self.history.items) |e| self.alloc.free(e.text);
        self.history.deinit();
        if (self.goal) |g| self.alloc.free(g);
        if (self.session_name) |s| self.alloc.free(s);
        for (self.visible_text.items) |l| self.alloc.free(l);
        self.visible_text.deinit();
        for (self.steer_queue.items) |s| self.alloc.free(s);
        self.steer_queue.deinit();
        self.input.deinit();
    }

    pub fn push(self: *Model, kind: Entry.Kind, text: []const u8) !void {
        const owned = try self.alloc.dupe(u8, text);
        errdefer self.alloc.free(owned);
        try self.history.append(.{ .kind = kind, .text = owned });
    }
    pub fn pushFmt(self: *Model, kind: Entry.Kind, comptime fmt: []const u8, args: anytype) !void {
        const text = try std.fmt.allocPrint(self.alloc, fmt, args);
        errdefer self.alloc.free(text);
        try self.history.append(.{ .kind = kind, .text = text });
    }
    pub fn pushOwned(self: *Model, kind: Entry.Kind, owned: []const u8) !void {
        try self.history.append(.{ .kind = kind, .text = owned });
    }

    pub fn clearHistory(self: *Model) void {
        for (self.history.items) |e| self.alloc.free(e.text);
        self.history.clearRetainingCapacity();
        self.push(.welcome, "") catch {};
    }

    // Chat-turn/background-thread logic (startJob/finishJob/drainSteer/
    // steerEnter) lives in repl_model_turn.zig.
    pub const startJob = model_turn.startJob;
    pub const finishJob = model_turn.finishJob;
    pub const drainSteer = model_turn.drainSteer;

    // /command handlers live in repl_model_commands.zig.
    pub const setGoal = model_commands.setGoal;

    /// Core submit logic. Returns the Effect; on a chat prompt it spawns a job
    /// (self.pending becomes non-null), which the caller turns into a poll tick.
    pub fn applyLine(self: *Model, raw: []const u8) Effect {
        const line = std.mem.trim(u8, raw, " \t\r\n");
        if (line.len == 0) return .stay;
        self.push(.input, line) catch {};

        if (line[0] == '/') {
            self.runCommand(line);
            return if (self.quit_requested) .quit else .stay;
        }

        if (self.chat) {
            self.turns += 1;
            self.chars_in += line.len;
            self.startJob();
            return .stay;
        }
        if (parser_mod.eval(line)) |v| {
            self.pushFmt(.result, "{d}", .{v}) catch {};
        } else |e| {
            self.pushFmt(.err, "{s}", .{@errorName(e)}) catch {};
        }
        return .stay;
    }

    pub const runCommand = model_commands.runCommand;
    pub const rewind = model_commands.rewind;
    pub const compact = model_commands.compact;
    pub const setSession = model_commands.setSession;

    pub const steerEnter = model_turn.steerEnter;

    // Pane rendering (spinnerFrame/statusLine/render) lives in
    // repl_model_render.zig.
    pub const spinnerFrame = model_render.spinnerFrame;
    pub const statusLine = model_render.statusLine;
    pub const render = model_render.render;
    pub const selectionText = model_render.selectionText;
};

pub const HELP_CALC =
    \\Commands:
    \\  /help     this help
    \\  /clear    clear the conversation
    \\  /version  running binary and latest release status
    \\  /update   install a release for the next launch (this session keeps running)
    \\  /animation enso|braille|dragon   spinner style
    \\  /quit     exit  (also /q, ctrl-c)
    \\
    \\Offline mode (no model): evaluates i64 arithmetic — + - * / %, parens.
;

// Markdown and pipe-table rendering lives in repl_markdown.zig.
pub const renderMarkdown = repl_markdown.renderMarkdown;

// runScripted (piped/CI twin of the Model) lives in repl_run.zig.
pub const runScripted = repl_run.runScripted;

// ---------------------------------------------------------------------------
// Tests — headless. Chat path uses a stubbed turn_fn (no network); it still
// exercises the real background-thread path.
// ---------------------------------------------------------------------------

test "model: offline arithmetic path (no turn_fn)" {
    g_turn_fn = null;
    var m: Model = undefined;
    m.setup(std.testing.allocator);
    defer m.deinit();
    try std.testing.expectEqual(Anim.enso, m.anim);

    try std.testing.expectEqual(Effect.stay, m.applyLine("2 + 3 * 4"));
    const out = try m.render(std.testing.allocator, 60, 24, 0);
    defer std.testing.allocator.free(out);
    try std.testing.expect(std.mem.indexOf(u8, out, "Welcome to graff repl") != null);
    try std.testing.expect(std.mem.indexOf(u8, out, "14") != null);

    _ = m.applyLine("/clear");
    try std.testing.expectEqual(@as(usize, 1), m.history.items.len);
    try std.testing.expectEqual(Effect.quit, m.applyLine("/quit"));
}

test "model: copy toast shows within window then auto-dismisses (#85)" {
    g_turn_fn = null;
    var m: Model = undefined;
    m.setup(std.testing.allocator);
    defer m.deinit();
    m.toast = .copied;
    m.toast_until_ms = 1000;
    const shown = try m.render(std.testing.allocator, 60, 24, 500);
    defer std.testing.allocator.free(shown);
    try std.testing.expect(std.mem.indexOf(u8, shown, "Copied to clipboard") != null);
    const gone = try m.render(std.testing.allocator, 60, 24, 2000);
    defer std.testing.allocator.free(gone);
    try std.testing.expect(std.mem.indexOf(u8, gone, "Copied to clipboard") == null);
}

test "model: selectionText joins non-empty rows and ignores whitespace-only (#85)" {
    g_turn_fn = null;
    var m: Model = undefined;
    m.setup(std.testing.allocator);
    defer m.deinit();
    try m.visible_text.append(try std.testing.allocator.dupe(u8, "hello"));
    try m.visible_text.append(try std.testing.allocator.dupe(u8, "world"));
    try m.visible_text.append(try std.testing.allocator.dupe(u8, "   "));
    m.view_rows = 3;
    const joined = m.selectionText(std.testing.allocator, 0, 1).?;
    defer std.testing.allocator.free(joined);
    try std.testing.expectEqualStrings("hello\nworld", joined);
    try std.testing.expect(m.selectionText(std.testing.allocator, 2, 2) == null); // whitespace-only
    try std.testing.expect(m.toast == .none and m.toast_until_ms == 0); // no toast raised
}

test "model: commands toggle settings" {
    g_turn_fn = null;
    var m: Model = undefined;
    m.setup(std.testing.allocator);
    defer m.deinit();
    _ = m.applyLine("/effort high");
    try std.testing.expectEqual(Effort.high, m.effort);
    _ = m.applyLine("/effort ultra");
    try std.testing.expectEqual(Effort.ultra, m.effort);
    _ = m.applyLine("/fast on");
    try std.testing.expect(m.fast);
    _ = m.applyLine("/ultracode");
    try std.testing.expect(m.ultracode);
    _ = m.applyLine("/goal ship the repl");
    try std.testing.expect(m.goal != null);
    _ = m.applyLine("/animation dragon");
    try std.testing.expectEqual(Anim.dragon, m.anim);
    _ = m.applyLine("/animation enso");
    try std.testing.expectEqual(Anim.enso, m.anim);
}

fn stubTurn(_: ?*anyopaque, gpa: std.mem.Allocator, history: []const Turn, params: Params, _: *StreamBuf) ?[]const u8 {
    const last = history[history.len - 1].text;
    return std.fmt.allocPrint(gpa, "echo[{s}]: {s}", .{ @tagName(params.effort), last }) catch null;
}

test "model: chat path (background thread + multi-turn) via stub" {
    g_turn_fn = stubTurn;
    g_turn_ctx = null;
    defer g_turn_fn = null;
    var m: Model = undefined;
    m.setup(std.testing.allocator);
    defer m.deinit();

    _ = m.applyLine("/effort high");
    try std.testing.expectEqual(Effect.stay, m.applyLine("hey there"));
    try std.testing.expect(m.pending != null);

    while (!m.pending.?.done.load(.acquire)) {} // wait for the worker
    m.finishJob();
    try std.testing.expect(m.pending == null);

    const out = try m.render(std.testing.allocator, 60, 24, 0);
    defer std.testing.allocator.free(out);
    try std.testing.expect(std.mem.indexOf(u8, out, "hey there") != null);
    try std.testing.expect(std.mem.indexOf(u8, out, "echo[high]: hey there") != null);
    try std.testing.expect(std.mem.indexOf(u8, out, "thinking") == null);
}

test "repl: runScripted type-checks" {
    _ = &runScripted;
}

test "model: /rewind and /compact (leak-checked)" {
    g_turn_fn = null;
    var m: Model = undefined;
    m.setup(std.testing.allocator);
    defer m.deinit();
    _ = m.applyLine("2 + 2");
    _ = m.applyLine("3 + 3");
    _ = m.applyLine("/rewind");
    try std.testing.expectEqual(Entry.Kind.welcome, m.history.items[0].kind);
    var i: usize = 0;
    while (i < 12) : (i += 1) _ = m.applyLine("1 + 1");
    _ = m.applyLine("/compact");
    try std.testing.expectEqual(Entry.Kind.welcome, m.history.items[0].kind);
    try std.testing.expect(m.history.items.len <= 9);
    _ = m.applyLine("/rename my-session");
    try std.testing.expect(m.session_name != null);
}

var g_test_cancelled: bool = false;
fn testCancel(_: ?*anyopaque) void {
    g_test_cancelled = true;
}

test "model: steering queues a line and drains it as the next turn" {
    g_turn_fn = stubTurn;
    g_turn_ctx = null;
    defer g_turn_fn = null;
    var m: Model = undefined;
    m.setup(std.testing.allocator);
    defer m.deinit();

    // Turn 1 in flight.
    try std.testing.expectEqual(Effect.stay, m.applyLine("first"));
    try std.testing.expect(m.pending != null);

    // Type a steer line while the turn streams → queued, input cleared (not submitted).
    m.input.setValue("second") catch {};
    m.steerEnter();
    try std.testing.expectEqual(@as(usize, 1), m.steer_queue.items.len);
    try std.testing.expectEqualStrings("", m.input.getValue());

    // Finish turn 1, then drain (what update(.tick) does) → the steer runs as turn 2.
    while (!m.pending.?.done.load(.acquire)) {}
    m.finishJob();
    try std.testing.expect(m.pending == null);
    _ = m.drainSteer();
    try std.testing.expectEqual(@as(usize, 0), m.steer_queue.items.len);
    try std.testing.expect(m.pending != null);

    while (!m.pending.?.done.load(.acquire)) {}
    m.finishJob();

    const out = try m.render(std.testing.allocator, 80, 24, 0);
    defer std.testing.allocator.free(out);
    try std.testing.expect(std.mem.indexOf(u8, out, "echo[medium]: first") != null);
    try std.testing.expect(std.mem.indexOf(u8, out, "echo[medium]: second") != null);
}

test "model: empty Enter force-interrupts when a steer line is queued" {
    g_turn_fn = stubTurn;
    g_turn_ctx = null;
    g_cancel_fn = testCancel;
    g_test_cancelled = false;
    defer {
        g_turn_fn = null;
        g_cancel_fn = null;
    }
    var m: Model = undefined;
    m.setup(std.testing.allocator);
    defer m.deinit();

    _ = m.applyLine("first");
    try std.testing.expect(m.pending != null);

    // Queue one steer line, then an empty Enter forces.
    m.input.setValue("urgent") catch {};
    m.steerEnter();
    m.input.setValue("") catch {};
    m.steerEnter();
    try std.testing.expect(m.cancel_requested); // turn flagged interrupted
    try std.testing.expect(g_test_cancelled); // cancel callback fired

    // Drain to completion so the queued line + jobs are freed (leak-checked).
    while (!m.pending.?.done.load(.acquire)) {}
    m.finishJob();
    _ = m.drainSteer();
    while (m.pending != null and !m.pending.?.done.load(.acquire)) {}
    if (m.pending != null) m.finishJob();
}