Skip to content

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

Python
22.0 KB
Raw Blame
//! API-key storage + the `graff key` CLI + OpenAI-compatible model listing.
//! Split out of main.zig (600-line goal, #123).
//!
//! Safe API-key store: on macOS, keys live in the login Keychain (service
//! "simple-harness", account=provider id) via the `security` CLI — never on
//! disk in plaintext. Other platforms use ~/.simple-harness-keys.json: mode
//! 0600 on POSIX, while Windows inherits the home directory's ACL because Zig
//! 0.17 exposes no portable API for installing an owner-only DACL.
//! `harness key set <provider> <key>` writes;
//! startup reads the selected provider first (env always wins), then fills the
//! remaining providers when a picker, switch, resume, or fallback needs them.
//!
//! storeKey stays pub — commands_model.zig and pickers.zig back-import it as
//! `main_mod.storeKey`; isLocalUrl/openAiModelsUrl/fetchOpenAIModels stay pub
//! for the same reason (commands_model.zig's local-server model picker).

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

const credential_store = @import("credential_store.zig");
const main_mod = @import("main.zig");
const provider_mod = @import("provider.zig");
const provider_specs = provider_mod.provider_specs;

const util = @import("util.zig");
const strFieldObj = util.strFieldObj;

/// True for a provider served by a local server (LM Studio, mlx-lm) on the
/// loopback host — these expose a live, user-controlled model set.
pub fn isLocalUrl(url: []const u8) bool {
    return std.mem.indexOf(u8, url, "127.0.0.1") != null or std.mem.indexOf(u8, url, "localhost") != null;
}

/// Derive the OpenAI-compatible `/v1/models` URL from a provider's chat URL
/// (`…/v1/chat/completions` → `…/v1/models`).
pub fn openAiModelsUrl(arena: Allocator, chat_url: []const u8) []const u8 {
    const suffix = "/chat/completions";
    if (std.mem.endsWith(u8, chat_url, suffix))
        return std.fmt.allocPrint(arena, "{s}/models", .{chat_url[0 .. chat_url.len - suffix.len]}) catch chat_url;
    return chat_url;
}

/// GET an OpenAI-compatible `/v1/models` endpoint and return every model id it
/// advertises (arena-owned), or an empty slice on any failure. Lets `/model
/// <local-provider>` list what a local server (LM Studio :1234, mlx-lm :8080)
/// actually has loaded instead of a baked-in name.
pub fn fetchOpenAIModels(io: Io, gpa: Allocator, arena: Allocator, models_url: []const u8, key: []const u8) [][]const u8 {
    var list: std.ArrayList([]const u8) = .empty;
    var client: std.http.Client = .{ .allocator = gpa, .io = io };
    defer client.deinit();
    var aw: Io.Writer.Allocating = .init(arena);
    const bearer = std.fmt.allocPrint(arena, "Bearer {s}", .{key}) catch return list.items;
    const extra = [_]std.http.Header{
        .{ .name = "authorization", .value = bearer },
        .{ .name = "Accept", .value = "application/json" },
    };
    const res = client.fetch(.{
        .location = .{ .url = models_url },
        .method = .GET,
        .response_writer = &aw.writer,
        .extra_headers = &extra,
    }) catch return list.items;
    if (@backingInt(res.status) != 200) return list.items;
    const v = std.json.parseFromSliceLeaky(Value, arena, aw.writer.buffered(), .{ .allocate = .alloc_always }) catch return list.items;
    if (v != .object) return list.items;
    const data = v.object.get("data") orelse return list.items;
    if (data != .array) return list.items;
    for (data.array.items) |item| {
        if (item != .object) continue;
        if (strFieldObj(item.object, "id")) |id| if (id.len > 0)
            list.append(arena, arena.dupe(u8, id) catch continue) catch {};
    }
    return list.toOwnedSlice(arena) catch list.items;
}

test "openAiModelsUrl derives /v1/models from the chat URL; isLocalUrl flags loopback" {
    var a = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer a.deinit();
    try std.testing.expectEqualStrings("http://127.0.0.1:1234/v1/models", openAiModelsUrl(a.allocator(), "http://127.0.0.1:1234/v1/chat/completions"));
    try std.testing.expectEqualStrings("http://127.0.0.1:8080/v1/models", openAiModelsUrl(a.allocator(), "http://127.0.0.1:8080/v1/chat/completions"));
    try std.testing.expect(isLocalUrl("http://127.0.0.1:1234/v1/chat/completions"));
    try std.testing.expect(isLocalUrl("http://localhost:1234/v1/chat/completions"));
    try std.testing.expect(!isLocalUrl("https://api.openai.com/v1/chat/completions"));
}

const keychain_service = "simple-harness";
const keys_file = ".simple-harness-keys.json";

/// User home directory env value: $HOME, or %USERPROFILE% on Windows (which has
/// no HOME). Key storage, sessions, history, login credentials, and saved model
/// all hang off this, so the Windows fallback is what makes them work there.
pub fn homeEnv(env: anytype) ?[]const u8 {
    return homeEnvFor(env, builtin.os.tag == .windows);
}

fn homeEnvFor(env: anytype, windows: bool) ?[]const u8 {
    // Empty overrides are not homes: on Windows they must not hide the
    // profile directory or send credential paths to the root of a drive.
    if (env.get("HOME")) |h| if (h.len > 0) return h;
    if (windows) {
        if (env.get("USERPROFILE")) |h| if (h.len > 0) return h;
    }
    return null;
}

const KeychainLookup = union(enum) { found: []const u8, missing, transient };

/// `security` exits 44 (errSecItemNotFound) when no item exists. Any other
/// failure (spawn error, busy securityd while several sessions start at once)
/// says nothing about whether the key is stored.
fn keychainLookup(io: Io, arena: Allocator, provider: []const u8) KeychainLookup {
    var child = std.process.spawn(io, .{
        .argv = &.{ "security", "find-generic-password", "-s", keychain_service, "-a", provider, "-w" },
        .stdin = .ignore,
        .stdout = .pipe,
        .stderr = .ignore,
    }) catch return .transient;
    const out: ?[]u8 = if (child.stdout) |f| read: {
        var rbuf: [8 * 1024]u8 = undefined;
        var fr = f.readerStreaming(io, &rbuf);
        break :read fr.interface.allocRemaining(arena, .limited(64 * 1024)) catch null;
    } else null;
    const term = child.wait(io) catch return .transient;
    const key = std.mem.trim(u8, out orelse "", " \t\r\n");
    if (key.len > 0) return .{ .found = key };
    return if (term == .exited and (term.exited == 0 or term.exited == 44)) .missing else .transient;
}

test "homeEnv: Windows finds shared login credentials without a nonempty HOME" {
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena_state.deinit();
    const arena = arena_state.allocator();
    try tmp.dir.writeFile(io, .{
        .sub_path = ".simple-harness-codegraff.json",
        .data = "{\"api_key\":\"cg_sk_profile_fixture\"}",
    });
    var path_buf: [std.fs.max_path_bytes]u8 = undefined;
    const profile = path_buf[0..try tmp.dir.realPath(io, &path_buf)];
    var env = std.StringHashMap([]const u8).init(std.testing.allocator);
    defer env.deinit();
    try env.put("USERPROFILE", profile);
    for ([_]?[]const u8{ null, "" }) |home| {
        if (home) |value| try env.put("HOME", value);
        const resolved = homeEnvFor(env, true).?;
        try std.testing.expectEqualStrings(profile, resolved);
        try std.testing.expectEqualStrings("cg_sk_profile_fixture", @import("oauth_codegraff.zig").loadKey(io, arena, resolved).?);
        if (builtin.os.tag == .windows) try std.testing.expectEqualStrings(resolved, homeEnv(env).?);
    }
}

test "homeEnv: nonempty HOME takes precedence on every platform" {
    var env = std.StringHashMap([]const u8).init(std.testing.allocator);
    defer env.deinit();
    try env.put("HOME", "override home");
    try env.put("USERPROFILE", "profile home");
    for ([_]bool{ false, true }) |windows| {
        try std.testing.expectEqualStrings("override home", homeEnvFor(env, windows).?);
    }
    try std.testing.expectEqualStrings("override home", homeEnv(env).?);
}

test "homeEnv: missing homes stay absent and Unix ignores USERPROFILE" {
    var env = std.StringHashMap([]const u8).init(std.testing.allocator);
    defer env.deinit();
    for ([_]?[]const u8{ null, "" }) |home| {
        if (home) |value| try env.put("HOME", value);
        _ = env.remove("USERPROFILE");
        for ([_]?[]const u8{ null, "" }) |profile| {
            if (profile) |value| try env.put("USERPROFILE", value);
            try std.testing.expect(homeEnvFor(env, true) == null);
            try std.testing.expect(homeEnvFor(env, false) == null);
        }
        try env.put("USERPROFILE", "profile home");
        try std.testing.expect(homeEnvFor(env, false) == null);
    }
}

pub fn storeKey(io: Io, gpa: Allocator, arena: Allocator, home: []const u8, provider: []const u8, key: []const u8) bool {
    if (builtin.os.tag == .macos) {
        var child = std.process.spawn(io, .{
            .argv = &.{ "security", "add-generic-password", "-U", "-s", keychain_service, "-a", provider, "-w", key },
            .stdin = .ignore,
            .stdout = .ignore,
            .stderr = .ignore,
        }) catch return false;
        const term = child.wait(io) catch return false;
        return term == .exited and term.exited == 0;
    }
    // Non-macOS: merge into one JSON file. POSIX uses 0600; Windows inherits
    // the home directory ACL because Io.File.Permissions has no ACL semantics.
    _ = gpa;
    const path = std.fmt.allocPrint(arena, "{s}/{s}", .{ home, keys_file }) catch return false;
    var obj: std.json.ObjectMap = .empty;
    if (Io.Dir.cwd().readFileAlloc(io, path, arena, .limited(64 * 1024))) |data| {
        if (std.json.parseFromSliceLeaky(Value, arena, data, .{ .allocate = .alloc_always })) |v| {
            if (v == .object) obj = v.object;
        } else |_| {}
    } else |_| {}
    obj.put(arena, provider, .{ .string = key }) catch return false;
    var aw: Io.Writer.Allocating = .init(arena);
    var s: std.json.Stringify = .{ .writer = &aw.writer };
    s.write(Value{ .object = obj }) catch return false;
    // Atomic + private on POSIX: this is a read-modify-write of EVERY
    // provider's key, so a truncate-in-place that dies mid-write does not lose
    // one key, it loses all of them at once. The old POSIX createFile took the
    // umask default, which could leave API keys world-readable.
    credential_store.replaceFile(io, Io.Dir.cwd(), path, aw.writer.buffered(), credential_store.private_file) catch return false;
    return true;
}

pub fn loadStoredKey(io: Io, arena: Allocator, home: []const u8, provider: []const u8) ?[]const u8 {
    if (builtin.os.tag == .macos) {
        // A transient miss drops a stored key for the whole session, so retry
        // once. Only errSecItemNotFound is a definite absence; it costs one
        // lookup, keeping keyless providers as cheap as before.
        for (0..2) |_| switch (keychainLookup(io, arena, provider)) {
            .found => |key| return key,
            .missing => return null,
            .transient => {},
        };
        return null;
    }
    const path = std.fmt.allocPrint(arena, "{s}/{s}", .{ home, keys_file }) catch return null;
    const data = Io.Dir.cwd().readFileAlloc(io, path, arena, .limited(64 * 1024)) catch return null;
    const v = std.json.parseFromSliceLeaky(Value, arena, data, .{ .allocate = .alloc_always }) catch return null;
    if (v != .object) return null;
    if (v.object.get(provider)) |k| if (k == .string and k.string.len > 0) return k.string;
    return null;
}

test "file-backed key store merges and loads keys on its live platforms" {
    if (builtin.os.tag == .macos) return;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena_state.deinit();
    const arena = arena_state.allocator();
    var home_buf: [std.fs.max_path_bytes]u8 = undefined;
    const home = home_buf[0..try tmp.dir.realPath(io, &home_buf)];

    try std.testing.expect(storeKey(io, std.testing.allocator, arena, home, "openai", "sk-first"));
    try std.testing.expect(storeKey(io, std.testing.allocator, arena, home, "anthropic", "sk-second"));
    try std.testing.expectEqualStrings("sk-first", loadStoredKey(io, arena, home, "openai").?);
    try std.testing.expectEqualStrings("sk-second", loadStoredKey(io, arena, home, "anthropic").?);

    if (Io.File.Permissions.has_executable_bit) {
        const path = try std.fmt.allocPrint(arena, "{s}/{s}", .{ home, keys_file });
        const mode = (try Io.Dir.cwd().statFile(io, path, .{})).permissions.toMode() & 0o777;
        try std.testing.expectEqual(@as(std.posix.mode_t, 0o600), mode);
    }
}

test "file-backed key store preserves keys across repeated read-modify-writes" {
    if (builtin.os.tag == .macos) return;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{ .iterate = true });
    defer tmp.cleanup();
    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena_state.deinit();
    const arena = arena_state.allocator();
    var home_buf: [std.fs.max_path_bytes]u8 = undefined;
    const home = home_buf[0..try tmp.dir.realPath(io, &home_buf)];

    try std.testing.expect(storeKey(io, std.testing.allocator, arena, home, "openai", "sk-openai-initial"));
    try std.testing.expect(storeKey(io, std.testing.allocator, arena, home, "anthropic", "sk-anthropic-initial"));
    try std.testing.expect(storeKey(io, std.testing.allocator, arena, home, "deepseek", "sk-deepseek-initial"));

    // Each update rereads the file produced by the preceding update. Checking
    // after every pass catches a lost unrelated provider at the exact write
    // that drops it, rather than only observing the final state.
    for (0..8) |round| {
        const openai_key = try std.fmt.allocPrint(arena, "sk-openai-{d}", .{round});
        const anthropic_key = try std.fmt.allocPrint(arena, "sk-anthropic-{d}", .{round});
        try std.testing.expect(storeKey(io, std.testing.allocator, arena, home, "openai", openai_key));
        try std.testing.expect(storeKey(io, std.testing.allocator, arena, home, "anthropic", anthropic_key));
        try std.testing.expectEqualStrings(openai_key, loadStoredKey(io, arena, home, "openai").?);
        try std.testing.expectEqualStrings(anthropic_key, loadStoredKey(io, arena, home, "anthropic").?);
        try std.testing.expectEqualStrings("sk-deepseek-initial", loadStoredKey(io, arena, home, "deepseek").?);
    }

    if (Io.File.Permissions.has_executable_bit) {
        const path = try std.fmt.allocPrint(arena, "{s}/{s}", .{ home, keys_file });
        const mode = (try Io.Dir.cwd().statFile(io, path, .{})).permissions.toMode() & 0o777;
        try std.testing.expectEqual(@as(std.posix.mode_t, 0o600), mode);
    }
}

pub const StoredKeyScope = union(enum) {
    all,
    provider: []const u8,
    mask: [provider_specs.len]bool,

    pub fn includes(scope: StoredKeyScope, index: usize, provider_id: []const u8) bool {
        return switch (scope) {
            .all => true,
            .provider => |id| std.mem.eql(u8, id, provider_id),
            .mask => |mask| mask[index],
        };
    }

    pub fn includesRouter(scope: StoredKeyScope, provider_id: []const u8) bool {
        return switch (scope) {
            .all => true,
            .provider => |id| std.mem.eql(u8, id, provider_id),
            .mask => false,
        };
    }
};

test "StoredKeyScope selects all, one provider, or an exact mask" {
    const all: StoredKeyScope = .all;
    try std.testing.expect(all.includes(0, provider_specs[0].id));
    const one: StoredKeyScope = .{ .provider = "deepseek" };
    try std.testing.expect(one.includes(2, "deepseek"));
    try std.testing.expect(!one.includes(1, "codegraff"));
    var mask: [provider_specs.len]bool = @splat(false);
    mask[1] = true;
    const selected: StoredKeyScope = .{ .mask = mask };
    try std.testing.expect(selected.includes(1, "codegraff"));
    try std.testing.expect(!selected.includes(2, "deepseek"));
}

fn loadStoredKeyTask(io: Io, gpa: Allocator, home: []const u8, provider_id: []const u8) ?[]u8 {
    var task_arena = std.heap.ArenaAllocator.init(gpa);
    defer task_arena.deinit();
    const key = loadStoredKey(io, task_arena.allocator(), home, provider_id) orelse return null;
    return gpa.dupe(u8, key) catch null;
}

/// Fill selected missing credential slots. macOS stores one Keychain item per
/// provider, so its independent `security` processes run concurrently with
/// task-local arenas. Other platforms keep all keys in one JSON file: read and
/// parse it once, then fill every selected slot from that single object.
pub fn loadMissingStoredKeys(io: Io, gpa: Allocator, arena: Allocator, home: []const u8, keys: *provider_mod.Keys, scope: StoredKeyScope) void {
    if (builtin.os.tag == .macos) {
        var futures: [provider_specs.len]?Io.Future(?[]u8) = @splat(null);
        for (provider_specs, keys.values, 0..) |spec, value, i| {
            if (value != null or !scope.includes(i, spec.id)) continue;
            const task_args = .{ io, gpa, home, spec.id };
            futures[i] = io.concurrent(loadStoredKeyTask, task_args) catch
                io.async(loadStoredKeyTask, task_args);
        }
        for (&futures, &keys.values, &keys.sources) |*maybe_future, *value, *source| {
            const owned = if (maybe_future.*) |*future| future.await(io) orelse continue else continue;
            value.* = arena.dupe(u8, owned) catch null;
            gpa.free(owned);
            if (value.* != null) source.* = .stored;
        }
        if (provider_mod.additional_router) |spec| {
            if (keys.router_value == null and scope.includesRouter(spec.id)) {
                keys.router_value = loadStoredKey(io, arena, home, spec.id);
                if (keys.router_value != null) keys.router_source = .stored;
            }
        }
        return;
    }

    const path = std.fmt.allocPrint(arena, "{s}/{s}", .{ home, keys_file }) catch return;
    const data = Io.Dir.cwd().readFileAlloc(io, path, arena, .limited(64 * 1024)) catch return;
    const parsed = std.json.parseFromSliceLeaky(Value, arena, data, .{ .allocate = .alloc_always }) catch return;
    if (parsed != .object) return;
    for (provider_specs, &keys.values, &keys.sources, 0..) |spec, *value, *source, i| {
        if (value.* != null or !scope.includes(i, spec.id)) continue;
        const stored = parsed.object.get(spec.id) orelse continue;
        if (stored != .string or stored.string.len == 0) continue;
        value.* = stored.string;
        source.* = .stored;
    }
    if (provider_mod.additional_router) |spec| {
        if (keys.router_value == null and scope.includesRouter(spec.id)) {
            const stored = parsed.object.get(spec.id) orelse return;
            if (stored == .string and stored.string.len > 0) {
                keys.router_value = stored.string;
                keys.router_source = .stored;
            }
        }
    }
}

/// `harness key set <provider> <key>` / `harness key list` — manage the safe
/// key store. Validates the provider id against built-ins plus the optional
/// workspace router.
pub fn keyCommand(io: Io, gpa: Allocator, arena: Allocator, home: []const u8, args: []const []const u8) !void {
    var obuf: [4096]u8 = undefined;
    var ow = Io.File.stdout().writer(io, &obuf);
    const out = &ow.interface;

    if (args.len == 0 or std.mem.eql(u8, args[0], "list")) {
        var stored_keys: provider_mod.Keys = .{ .values = @splat(null) };
        loadMissingStoredKeys(io, gpa, arena, home, &stored_keys, .all);
        try out.writeAll("provider        env var               stored\n");
        for (0..provider_mod.specCount()) |i| {
            const spec = provider_mod.specAt(i).?;
            const stored = stored_keys.get(spec.id) != null;
            try out.print("  {s:<14}{s:<22}{s}\n", .{ spec.id, spec.env_key, if (stored) "yes" else "—" });
        }
        try out.flush();
        return;
    }
    if (std.mem.eql(u8, args[0], "set")) {
        if (args.len < 3) {
            try out.writeAll("usage: graff key set <provider> <key>\n");
            try out.flush();
            return;
        }
        const provider = args[1];
        const key = args[2];
        if (provider_mod.specFor(provider) == null) {
            try out.print("unknown provider '{s}' — see /models for valid ids\n", .{provider});
            try out.flush();
            return;
        }
        if (storeKey(io, gpa, arena, home, provider, key)) {
            const where = if (builtin.os.tag == .macos) "macOS Keychain" else "~/" ++ keys_file;
            try out.print("✓ stored {s} key in the {s}\n", .{ provider, where });
        } else {
            try out.writeAll("✗ failed to store key\n");
        }
        try out.flush();
        return;
    }
    try out.writeAll("usage: graff key set <provider> <key>  |  graff key list\n");
    try out.flush();
}

/// Load (or create on first run) a 32-hex-char anonymous id at ~/<fname>.
/// All-zero id when HOME is missing or the file can't be created.
pub fn loadOrCreateId(io: Io, gpa: Allocator, home: []const u8, fname: []const u8) [32]u8 {
    var id: [32]u8 = @splat('0');
    if (home.len == 0) return id;
    var pbuf: [512]u8 = undefined;
    const path = std.fmt.bufPrint(&pbuf, "{s}/{s}", .{ home, fname }) catch return id;
    existing: {
        const data = Io.Dir.cwd().readFileAlloc(io, path, gpa, .limited(64)) catch break :existing;
        defer gpa.free(data);
        const trimmed = std.mem.trim(u8, data, " \t\r\n");
        if (trimmed.len != 32) break :existing;
        for (trimmed) |c| switch (c) { // lowercase hex only, like the writer
            '0'...'9', 'a'...'f' => {},
            else => break :existing,
        };
        @memcpy(&id, trimmed);
        return id;
    }
    var raw: [16]u8 = undefined;
    io.random(&raw);
    id = std.fmt.bytesToHex(raw, .lower);
    const f = Io.Dir.cwd().createFile(io, path, .{}) catch return id;
    defer f.close(io);
    var wbuf: [64]u8 = undefined;
    var fw = f.writer(io, &wbuf);
    fw.interface.print("{s}\n", .{&id}) catch return id;
    fw.interface.flush() catch return id;
    return id;
}