Skip to content

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

Python
8.9 KB
Raw Blame
//! `render_html` — the model draws something for the user, and the desktop
//! app renders it inline in the transcript instead of making them imagine it.
//!
//! The snapshot is the model's page VERBATIM: no wrapper document, no host
//! script, no handshake. Isolation is a response header, not a shell — the
//! desktop's `/api/views` serves this file with a CSP `sandbox` plus
//! `default-src 'none'`, so the page runs in an opaque origin with no network
//! and no reach into the app, whether it is framed by the transcript or opened
//! straight from disk in a browser.
//!
//! Same private-snapshot shape as an MCP app result (mcp_apps.zig): a random
//! 32-hex id under `$HOME/.graff/views`, 0700 directory, 0600 file, and a
//! result line carrying only the path. Nothing about the page enters model
//! context a second time.

const std = @import("std");
const Io = std.Io;
const Allocator = std.mem.Allocator;
const Value = std.json.Value;
const tools = @import("tools.zig");

pub const tool_name = "render_html";
pub const tool_desc =
    "Draw something for the user as a live HTML page they open from the transcript. Reach for it when a result is easier to SEE than to read — a chart, a diagram, a timeline, a before/after comparison, a small layout mock, or something they can poke at — not for ordinary prose, code, or a file list, which belong in your reply. The page is saved as one private local snapshot and rendered in an isolated frame: no network at all (inline images as data: URIs; no CDNs, no fonts, no fetch), no access to the app or its APIs, no forms, no popups, and links stay inside the frame. Make it self-contained — one document with its own inline <style>/<script> — and keep it under 1 MB. One call makes one view and the saved path stays openable later. Saving is not showing: tell the user the page is ready to open, never that it is displayed above.";
pub const tool_schema =
    \\{"type": "object", "properties": {"html": {"type": "string", "description": "The complete page: markup plus whatever inline <style>/<script> it needs. It must stand alone — nothing is fetched and nothing outside it is available."}}, "required": ["html"]}
;

/// Catalog entry for this tool. schema.zig sits on the 600-line ceiling, so
/// the spec lives with the module that owns it and is spliced in there as
/// `@import("html_view.zig").spec` — the same one-line pattern `skill_docs`
/// and `imagegen` use, minus the import.
pub const spec: @import("schema.zig").ToolSpec = .{ .name = tool_name, .desc = tool_desc, .schema = tool_schema };

/// One call, one page. A view is for a pane, not a 40 MB canvas.
const max_html = 1024 * 1024;
pub const dir_name = ".graff/views";

/// The home the session resolved: the MCP registry already carries it, the
/// fleet pins it before any prompt, and credential_store pins it at startup.
/// A tool running on a pool thread has no environment map of its own.
fn homeDir(ctx: tools.ToolCtx) []const u8 {
    if (ctx.registry) |reg| if (reg.home.len > 0) return reg.home;
    if (@import("fleet.zig").g_home) |h| if (h.len > 0) return h;
    return @import("credential_store.zig").g_home;
}

/// Why this page cannot be rendered, or null when it can. Separate from exec
/// so the wording is testable without a whole ToolCtx.
fn refusal(html: []const u8, a: Allocator) !?[]u8 {
    if (std.mem.trim(u8, html, " \t\r\n").len == 0)
        return try a.dupe(u8, "render_html needs the page in `html` — an empty string draws nothing.");
    if (html.len > max_html)
        return try std.fmt.allocPrint(a, "that page is {d} KB and the limit is {d} KB per view. Inline less (base64 media is what usually blows the budget) or draw it as two views.", .{ html.len / 1024, max_html / 1024 });
    return null;
}

/// The one line the transcript and the model see. The page itself never
/// travels in it — the GUI matches the opaque path. Saving is all this tool
/// can vouch for: no client acknowledges display, and a client that shows no
/// views still gets this line, so it must not claim the page is on screen
/// (#1677).
fn marker(a: Allocator, path: []const u8) ![]u8 {
    return std.fmt.allocPrint(a, "[Rendered view]({s}) — saved. The user opens it from this tool's row in the transcript; it renders with no network and no access to the app. Say it is ready to open, not that it is displayed.", .{path});
}

/// Write the page to one private snapshot and return its path (caller-owned).
pub fn write(io: Io, a: Allocator, home: []const u8, html: []const u8) ![]const u8 {
    if (home.len == 0) return error.NoHomeDirectory;
    var scratch = std.heap.ArenaAllocator.init(a);
    defer scratch.deinit();
    const dir = try std.fmt.allocPrint(scratch.allocator(), "{s}/{s}", .{ home, dir_name });
    try Io.Dir.cwd().createDirPath(io, dir);
    // Windows inherits the user profile ACL; Zig does not implement POSIX chmod there.
    if (@import("builtin").os.tag != .windows)
        try Io.Dir.cwd().setFilePermissions(io, dir, @fromBackingInt(@intCast(0o700)), .{});
    var random: [16]u8 = undefined;
    io.random(&random);
    const path = try std.fmt.allocPrint(scratch.allocator(), "{s}/{s}.html", .{ dir, std.fmt.bytesToHex(random, .lower) });
    try @import("credential_store.zig").replaceFile(io, Io.Dir.cwd(), path, html, @fromBackingInt(@intCast(0o600)));
    return try a.dupe(u8, path);
}

pub fn exec(ctx: tools.ToolCtx, input: Value) !tools.ToolOutput {
    const html = tools.strField(input, "html") orelse "";
    if (try refusal(html, ctx.gpa)) |text| return .{ .text = text, .is_error = true };
    const path = write(ctx.io, ctx.gpa, homeDir(ctx), html) catch |err| return .{
        .text = try std.fmt.allocPrint(ctx.gpa, "could not save the view: {s}", .{@errorName(err)}),
        .is_error = true,
    };
    return .{ .text = try marker(ctx.gpa, path) };
}

const testing = std.testing;

fn tmpHome(a: Allocator, tmp: *std.testing.TmpDir) ![]u8 {
    return std.fmt.allocPrint(a, ".zig-cache/tmp/{s}", .{&tmp.sub_path});
}

test "render_html writes the page verbatim to one private snapshot" {
    const a = testing.allocator;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    const home = try tmpHome(a, &tmp);
    defer a.free(home);
    const html = "<!doctype html><h1>Flow</h1><style>h1{color:#059669}</style>";
    const path = try write(testing.io, a, home, html);
    defer a.free(path);
    // Opaque id, fixed shape — this is what the GUI's link matcher accepts.
    const suffix = try std.fmt.allocPrint(a, "{s}/{s}", .{ home, dir_name });
    defer a.free(suffix);
    try testing.expect(std.mem.startsWith(u8, path, suffix));
    const id = path[suffix.len + 1 ..];
    try testing.expectEqual(@as(usize, 32 + 5), id.len);
    try testing.expect(std.mem.endsWith(u8, id, ".html"));
    for (id[0..32]) |c| try testing.expect(std.ascii.isHex(c));
    // The file is the model's bytes, unchanged (no wrapper injected).
    const saved = try Io.Dir.cwd().readFileAlloc(testing.io, path, a, .limited(4096));
    defer a.free(saved);
    try testing.expectEqualStrings(html, saved);
    if (@import("builtin").os.tag != .windows) {
        const st = try Io.Dir.cwd().statFile(testing.io, path, .{});
        try testing.expectEqual(@as(u32, 0o600), st.permissions.toMode() & 0o777);
    }
}

test "two calls never collide on one id" {
    const a = testing.allocator;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    const home = try tmpHome(a, &tmp);
    defer a.free(home);
    const first = try write(testing.io, a, home, "<p>one</p>");
    defer a.free(first);
    const second = try write(testing.io, a, home, "<p>two</p>");
    defer a.free(second);
    try testing.expect(!std.mem.eql(u8, first, second));
}

test "an empty page, an oversized page and a home-less session are refused" {
    const a = testing.allocator;
    const empty = (try refusal("   \n", a)).?;
    defer a.free(empty);
    try testing.expect(std.mem.indexOf(u8, empty, "empty string") != null);
    const big = try a.alloc(u8, max_html + 1);
    defer a.free(big);
    @memset(big, 'x');
    const oversized = (try refusal(big, a)).?;
    defer a.free(oversized);
    try testing.expect(std.mem.indexOf(u8, oversized, "limit") != null);
    try testing.expect((try refusal("<p>fine</p>", a)) == null);
    try testing.expectError(error.NoHomeDirectory, write(testing.io, a, "", "<p>x</p>"));
}

test "the marker carries the path and never the page" {
    const a = testing.allocator;
    const text = try marker(a, "/home/u/.graff/views/0123456789abcdef0123456789abcdef.html");
    defer a.free(text);
    try testing.expect(std.mem.indexOf(u8, text, "/.graff/views/0123456789abcdef0123456789abcdef.html") != null);
    try testing.expect(std.mem.indexOf(u8, text, "<") == null);
    // Saving is all the tool knows; the ACP view hint still finds the path.
    try testing.expect(std.mem.indexOf(u8, text, "saved") != null);
    try testing.expect(std.mem.indexOf(u8, text, "shown") == null);
    try testing.expect(@import("acp_view_meta.zig").detect(text) != null);
}