Skip to content

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

Python
15.4 KB
Raw Blame
//! macOS clipboard → a file we can stage: the pasteboard flavor cascade behind
//! Ctrl-V and `/paste`, the per-invocation temp path, the `sips`-based
//! is-it-really-an-image gate / PNG normalizer / downscaler, and the raw-byte
//! budget a staged image has to fit inside. Split out of vision.zig (600-line
//! goal); vision.zig re-exports the parts its callers need.

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

const trace = @import("trace.zig");

/// Raw (pre-base64) ceiling for one staged image.
///
/// An image travels base64-encoded, which inflates it by 4/3 — `ceil(n/3)*4`
/// bytes on the wire. Providers cap a SINGLE image at ~5 MB of *encoded*
/// payload, so the raw file has to stay under `5_000_000 * 3/4 = 3_750_000`
/// bytes. 3,700,000 encodes to 4,933,336 bytes and leaves the JSON envelope
/// (media_type, quoting, the rest of the message) a little room.
///
/// The old ceiling was 5 MiB of raw bytes, which base64-expands to 6.99 MB:
/// simultaneously too tight for reading (a 7.3 MB screenshot was refused) and
/// too loose for the wire (a 4 MB one was accepted and then 400'd), #349.
/// Raising it makes the wire failure worse, so the fix is `fitToBudget` —
/// downscale, then refuse only if it still will not fit.
pub const max_staged_image_bytes: u64 = 3_700_000;

/// Successively smaller max-dimensions handed to `sips -Z`. Ordered
/// largest-first so a paste keeps as much detail as the budget allows.
pub const downscale_steps = [_][]const u8{ "2048", "1568", "1024" };

/// Which pasteboard flavor produced the file. Recorded on the trace so a
/// dropped paste can be told apart from a PDF-only or file-url-only clipboard
/// after the fact (#350).
pub const Flavor = enum {
    /// `«class PNGf»` — macOS lazily synthesizes this from any raster flavor
    /// (TIFF, JPEG, HEIC, live data-provider promises), so it covers almost
    /// every real screenshot/copy-image clipboard.
    png,
    /// `«class furl»` / `NSFilenamesPboardType` — a file the user copied in
    /// Finder, Telegram, Slack… The pasteboard carries a path, never pixels.
    /// Telegram cache files often have no image extension.
    furl,
    /// `«class PDF »` — Preview, Illustrator, Keynote and friends put up a
    /// vector-only clipboard with no raster flavor at all.
    pdf,

    pub fn name(self: Flavor) []const u8 {
        return @tagName(self);
    }
};

/// Why a clipboard extraction failed without yielding an image (#843).
/// Categories stay privacy-safe: they never include clipboard contents.
pub const FailKind = enum { access, denied, unavailable, spawn, cancelled, timeout, changed, extract, convert };

/// Result of one pasteboard grab. Null used to mean both "nothing there"
/// and "osascript/sips failed", which Ctrl-V then reported as an empty
/// clipboard.
pub const GrabAttempt = union(enum) {
    ok: Grab,
    empty,
    failed: FailKind,
};

/// A clipboard image that made it to disk.
pub const Grab = struct {
    path: []const u8,
    flavor: Flavor,
    /// The file at `path` is OURS and must be deleted on release. False when
    /// the cascade landed on a file the *user* owns (a `furl` clipboard whose
    /// target is already a stageable image) — deleting that would destroy the
    /// thing they just copied.
    owned: bool,

    /// Drop the temp file (if any) and free the path. Safe to call exactly
    /// once, success or failure, from a `defer` at the paste call site.
    pub fn release(self: Grab, io: Io, gpa: Allocator) void {
        if (self.owned) deleteQuietly(io, self.path);
        gpa.free(self.path);
    }
};

// ── temp paths ────────────────────────────────────────────────────────────

/// A fresh scratch path for this paste.
///
/// The old code hardcoded `/tmp/.harness-clip.png` in TWO places — a Zig
/// constant and, separately, a string inside the AppleScript source — which
/// had to be kept in sync by hand. Being fixed and world-writable it was also
/// a symlink-planting target and a live race: a second graff (or anything
/// else) could delete the file between osascript writing it and the stager
/// reading it, which reads out as a spurious "couldn't read the clipboard
/// image" (#349). The path is built ONCE here and interpolated into the
/// script's argv, so the two can no longer drift, and the 64 random bits make
/// it unguessable.
///
/// Only `[A-Za-z0-9./-]` ever appears, so the result needs no shell or
/// AppleScript quoting.
pub fn tempPath(io: Io, gpa: Allocator, ext: []const u8) ?[]const u8 {
    var raw: [8]u8 = undefined;
    io.random(&raw);
    const hex = std.fmt.bytesToHex(raw, .lower);
    return std.fmt.allocPrint(gpa, "/tmp/graff-clip-{d}-{s}.{s}", .{ trace.currentPid(), hex[0..], ext }) catch null;
}

/// Delete a temp file and free its path — the cleanup half of `tempPath`.
pub fn discard(io: Io, gpa: Allocator, path: []const u8) void {
    deleteQuietly(io, path);
    gpa.free(path);
}

fn deleteQuietly(io: Io, path: []const u8) void {
    Io.Dir.cwd().deleteFile(io, path) catch {};
}

// ── filesystem probes ─────────────────────────────────────────────────────

/// Size of `path` if it is a regular file, else null. Null therefore means
/// "not there, or not a file" — never "too big", which is the distinction the
/// old single `.read_fail` threw away.
pub fn regularFileSize(io: Io, path: []const u8) ?u64 {
    if (fileSizeAt(io, Io.Dir.cwd(), path)) |n| return n;
    if (!std.fs.path.isAbsolute(path)) return null;
    const dir_path = std.fs.path.dirname(path) orelse return null;
    var dir = Io.Dir.openDirAbsolute(io, dir_path, .{}) catch return null;
    defer dir.close(io);
    return fileSizeAt(io, dir, std.fs.path.basename(path));
}

fn fileSizeAt(io: Io, dir: Io.Dir, path: []const u8) ?u64 {
    const st = dir.statFile(io, path, .{}) catch return null;
    if (st.kind != .file) return null;
    return st.size;
}

/// Extensions a provider accepts as-is (`imageMediaType` knows all of them).
pub fn stageableExtension(path: []const u8) bool {
    for ([_][]const u8{ ".png", ".jpg", ".jpeg", ".gif", ".webp" }) |ext|
        if (std.ascii.endsWithIgnoreCase(path, ext)) return true;
    return false;
}

/// `sips` as an is-this-an-image oracle: it exits 0 on an image it can read
/// and 13 on anything else, without writing a file.
pub fn sipsIsImage(io: Io, path: []const u8) bool {
    if (builtin.os.tag != .macos) return false;
    return runQuiet(io, &.{ "sips", "-g", "pixelWidth", path });
}

/// Can this `«class furl»` path actually be staged?
///
/// The coercion itself proves NOTHING. On a *plain-text* clipboard
/// `the clipboard as «class furl»` still succeeds: copying the word "hello"
/// yields the POSIX path `/hello` with exit status 0. So every furl path is
/// validated here — it must exist, be a regular non-empty file, and either
/// carry an image extension or survive the `sips` probe. `probe` is injected
/// so the trap can be tested without a pasteboard or a subprocess.
///
/// The leading-`/` test is deliberately POSIX-shaped rather than
/// `std.fs.path.isAbsolute`: the input is always AppleScript's
/// `POSIX path of …`, so a path that does not start with `/` is coercion
/// output rather than a file. No comptime OS gate is needed — the only caller
/// is `grabFurl`, reached solely through `grabClipboardImage`, which already
/// returns `.empty` off macOS.
pub fn furlLooksStageable(io: Io, path: []const u8, probe: anytype) bool {
    if (path.len == 0 or path[0] != '/') return false;
    const size = regularFileSize(io, path) orelse return false;
    if (size == 0) return false;
    if (stageableExtension(path)) return true;
    return probe(io, path);
}

// ── downscaling ───────────────────────────────────────────────────────────

/// `sips -s format png -Z <max_dim> <in> --out <out>`: fit the image inside a
/// square of `max_dim` points, preserving aspect ratio, and re-encode it as a
/// real PNG.
///
/// `-s format png` is NOT optional. `sips -Z` alone keeps the SOURCE encoding
/// whatever the output is called: `sips -Z 2048 photo.jpg --out step.png`
/// exits 0 and writes JPEG bytes into a `.png`. Every downscale temp is named
/// `.png` and the stager reads `media_type` off that extension, so without the
/// explicit format a downscaled JPEG/GIF/WebP ships as `image/png` and the
/// provider 400s on the mismatch — turning the #349 fix into a new failure for
/// exactly the photos it was meant to rescue.
pub fn sipsResize(io: Io, in: []const u8, max_dim: []const u8, out: []const u8) bool {
    if (builtin.os.tag != .macos) return false;
    return runQuiet(io, &.{ "sips", "-s", "format", "png", "-Z", max_dim, in, "--out", out });
}

/// Injected so `fitToBudget` is testable without macOS or a subprocess.
pub const Resizer = *const fn (io: Io, in: []const u8, max_dim: []const u8, out: []const u8) bool;

/// The 8 bytes every PNG starts with.
pub const png_magic = "\x89PNG\r\n\x1a\n";

/// Does `path` actually hold a PNG? The downscale temp is named `.png` and the
/// media type is read back off that extension, so the bytes have to agree —
/// the belt to `sipsResize`'s `-s format png` braces, and it holds for any
/// resizer, not just the one we ship.
pub fn looksLikePng(io: Io, path: []const u8) bool {
    const file = Io.Dir.cwd().openFile(io, path, .{}) catch return false;
    defer file.close(io);
    var head: [png_magic.len]u8 = undefined;
    const got = file.readPositionalAll(io, &head, 0) catch return false;
    return got == head.len and std.mem.eql(u8, &head, png_magic);
}

/// The file that will actually be read and encoded.
pub const Fit = struct {
    path: []const u8,
    bytes: u64,
    /// `path` is a downscale temp file: delete + free it after reading.
    temp: bool,
};

/// Bring `path` under `budget`, re-encoding at successively smaller max
/// dimensions rather than dropping the paste outright. Returns null only when
/// even the smallest step is still too big (or the resizer is unavailable),
/// which is what lets the caller report a real `too_large`.
///
/// A step is only accepted if it really produced a PNG (see `looksLikePng`).
/// The PNG re-encode is also far bigger than a JPEG source — a 4 MB phone
/// photo lands at ~2.8 MB at 2048px, not ~0.5 MB — which is why the ladder
/// goes all the way down to 1024.
pub fn fitToBudget(io: Io, gpa: Allocator, path: []const u8, size: u64, budget: u64, resize: Resizer) ?Fit {
    if (size <= budget) return .{ .path = path, .bytes = size, .temp = false };
    for (downscale_steps) |dim| {
        const out = tempPath(io, gpa, "png") orelse return null;
        if (resize(io, path, dim, out)) {
            if (regularFileSize(io, out)) |n| {
                if (n > 0 and n <= budget and looksLikePng(io, out))
                    return .{ .path = out, .bytes = n, .temp = true };
            }
        }
        discard(io, gpa, out);
    }
    return null;
}

/// What staging `path` will do, decided before a single byte is read. Split
/// out of the Agent-facing stager so the size math is testable on its own.
pub const Plan = union(enum) {
    /// Missing, or not a regular file.
    not_found,
    /// Over budget and undownscalable; the payload is the file's REAL size,
    /// statted rather than inferred from `error.StreamTooLong`.
    too_large: u64,
    fits: Fit,
};

pub fn planStage(io: Io, gpa: Allocator, path: []const u8, budget: u64, resize: Resizer) Plan {
    const size = regularFileSize(io, path) orelse return .not_found;
    const fit = fitToBudget(io, gpa, path, size, budget, resize) orelse return .{ .too_large = size };
    return .{ .fits = fit };
}

// ── the flavor cascade ────────────────────────────────────────────────────

/// Type names `clipboard info` reports for image-bearing pasteboards.
/// The string is flavor metadata only — never clipboard contents (#843).
pub fn pasteboardHintFromInfo(info: []const u8) enum { image, none } {
    for ([_][]const u8{ "PNGf", "TIFF", "JPEG", "JIFf", "PDF ", "furl" }) |mark| {
        if (std.mem.indexOf(u8, info, mark) != null) return .image;
    }
    return .none;
}

/// Export actual pasteboard types through AppKit. The named-pasteboard entry
/// point is shared with native regressions without touching the user's board.
pub fn grabClipboardImage(io: Io, gpa: Allocator) GrabAttempt {
    return @import("clipboard_native.zig").grab(io, gpa, "");
}

// ── subprocess plumbing ───────────────────────────────────────────────────

const RunStatus = enum { ok, failed, spawn };

fn runQuiet(io: Io, argv: []const []const u8) bool {
    return runStatus(io, argv) == .ok;
}

fn runStatus(io: Io, argv: []const []const u8) RunStatus {
    var child = std.process.spawn(io, .{
        .argv = argv,
        .stdin = .ignore,
        .stdout = .ignore,
        .stderr = .ignore,
    }) catch return .spawn;
    const term = child.wait(io) catch return .spawn;
    return if (term == .exited and term.exited == 0) .ok else .failed;
}

const CaptureStatus = union(enum) { ok: []u8, failed, spawn };

/// stdout of a successful run, gpa-owned; null on spawn/read failure or a
/// non-zero exit.
fn runCapture(io: Io, gpa: Allocator, argv: []const []const u8) ?[]u8 {
    return switch (runCaptureStatus(io, gpa, argv)) {
        .ok => |s| s,
        .failed, .spawn => null,
    };
}

fn runCaptureStatus(io: Io, gpa: Allocator, argv: []const []const u8) CaptureStatus {
    var child = std.process.spawn(io, .{
        .argv = argv,
        .stdin = .ignore,
        .stdout = .pipe,
        .stderr = .ignore,
    }) catch return .spawn;
    const f = child.stdout orelse {
        _ = child.wait(io) catch {};
        return .spawn;
    };
    var rbuf: [4096]u8 = undefined;
    var fr = f.readerStreaming(io, &rbuf);
    const captured = fr.interface.allocRemaining(gpa, .limited(8 * 1024)) catch {
        _ = child.wait(io) catch {};
        return .spawn;
    };
    const term = child.wait(io) catch {
        gpa.free(captured);
        return .spawn;
    };
    if (term != .exited or term.exited != 0) {
        gpa.free(captured);
        return .failed;
    }
    return .{ .ok = captured };
}

// ── formatting ────────────────────────────────────────────────────────────

/// "7.3 MB" — MiB with one decimal, matching what a file manager shows, so the
/// number in the error line is the number the user can see on their own disk.
pub fn fmtMb(buf: *[16]u8, bytes: u64) []const u8 {
    const mb = @as(f64, @floatFromInt(bytes)) / (1024.0 * 1024.0);
    return std.fmt.bufPrint(buf, "{d:.1} MB", .{mb}) catch "?? MB";
}

// ── tests ─────────────────────────────────────────────────────────────────
// Split into vision_clipboard_tests.zig to stay under the 600-line ceiling;
// an unreferenced module's tests never run, hence the import below.

test {
    _ = @import("vision_clipboard_tests.zig");
}