Skip to content

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

Python
18.4 KB
Raw Blame
//! Startup-time routing for the optional worker model shape.
//!
//! A provider boundary is materially different from a model pin: prompts,
//! tool results, billing, and credentials move to another service. Cross-
//! provider workers therefore require both an explicit provider and an
//! explicit consent flag.
//!
//! Absent an explicit --subagent-model/--subagent-provider, a default worker
//! tier ladder (#291, tier_ladder.zig) descends one rung from wherever the
//! root model sits — same precedence-tail as the explicit pin's own
//! provider-local/cross-provider-consent rules, since the default is
//! resolved through the same subagentProvider() call with cross-provider
//! forced off. --no-subagent-tier (or GRAFF_NO_SUBAGENT_TIER) opts out and
//! restores today's plain inherit-root behavior.
const std = @import("std");

const catalog_selection = @import("catalog_selection.zig");
const pricing = @import("pricing.zig");
const provider_mod = @import("provider.zig");
const tier_ladder = @import("subagent_tier_ladder.zig");

pub const Error = error{
    UnknownModel,
    UnknownProvider,
    ModelNotOnProvider,
    CrossProviderConsentRequired,
    MissingKey,
};

fn knownProvider(id: []const u8) bool {
    return provider_mod.specFor(id) != null;
}

/// Resolve `query` to a catalogued model name served by `provider_id`: exact
/// match, then alias-equality, then a UNIQUE substring match (ambiguous →
/// null). Provider-local by construction — this is the one resolver both the
/// startup pins (--subagent-model, the #291 ladder) and the #292 per-persona /
/// per-spawn pins go through, so all three agree on what a model name means.
pub fn modelForProvider(provider_id: []const u8, query: []const u8) ?[]const u8 {
    for (pricing.models()) |model| {
        if (std.mem.eql(u8, model.provider, provider_id) and
            std.mem.eql(u8, model.name, query)) return model.name;
    }
    for (pricing.models()) |model| {
        if (std.mem.eql(u8, model.provider, provider_id) and
            pricing.modelAliasEquals(model.name, query)) return model.name;
    }
    var query_buf: [128]u8 = undefined;
    const normalized_query = pricing.normalizeModelAlias(&query_buf, query);
    var candidate: ?[]const u8 = null;
    for (pricing.models()) |model| {
        if (!std.mem.eql(u8, model.provider, provider_id)) continue;
        var name_buf: [128]u8 = undefined;
        const normalized_name = pricing.normalizeModelAlias(&name_buf, model.name);
        if (std.mem.indexOf(u8, normalized_name, normalized_query) == null) continue;
        if (candidate != null) return null;
        candidate = model.name;
    }
    return candidate;
}

/// Default worker sibling for `root` on its own ladder, descending exactly
/// one rung. `root.model` must exactly match a rung name (frontier or mid)
/// for this provider's ladder — an off-ladder or unrecognized root model
/// returns null rather than guessing at the nearest rung.
///
/// GPT-6 roots keep their model: demoting Astra onto Sol is a SWE-bench
/// regression (Astra-low beats Sol-high). Unpinned workers inherit;
/// `tier: mid` / `tier: small` still seat Sol / Luna when asked.
fn defaultLadderModel(root: provider_mod.Provider) ?[]const u8 {
    const ladder = tier_ladder.forModel(root.id, root.model) orelse return null;
    if (std.mem.startsWith(u8, root.model, "gpt-6")) return null;
    if (ladder.small) |small| {
        if (pricing.modelAliasEquals(small, "mimo-v2.6-flash")) {
            if (!pricing.modelAliasEquals(root.model, small) and @import("subagent_pin.zig").rungAffordableOn(root, small)) return small;
            return null;
        }
    }
    if (std.mem.eql(u8, root.model, ladder.frontier)) return ladder.mid orelse ladder.small;
    if (ladder.mid) |mid| {
        if (std.mem.eql(u8, root.model, mid)) return ladder.small;
    }
    return null; // root is already the bottom rung, or isn't on this ladder
}

/// Resolves the default ladder sibling to an actual Provider, reusing
/// subagentProvider's exact/alias/key resolution so a ladder name a live
/// catalog refresh has since dropped fails soft into "inherit root" instead
/// of the fatal path an explicit --subagent-model takes. Always same-
/// provider — cross_provider is forced off, since ladder siblings never
/// cross a provider boundary implicitly (preserves the invariant explicit
/// pins already enforce).
fn defaultLadderProvider(keys: provider_mod.Keys, root: provider_mod.Provider) ?provider_mod.Provider {
    const target = defaultLadderModel(root) orelse return null;
    const resolved = subagentProvider(keys, root, null, target, false) catch return null;
    g_default_from_ladder = true;
    return resolved;
}

/// #372 routing trace: true when the session's worker provider came from the
/// #291 default ladder descent rather than an explicit --subagent-model, so
/// an unpinned spawn can honestly report `source=ladder` vs
/// `source=session-default` instead of conflating the two.
pub var g_default_from_ladder: bool = false;

pub fn subagentProvider(
    keys: provider_mod.Keys,
    root: provider_mod.Provider,
    provider_query: ?[]const u8,
    model_query: []const u8,
    allow_cross_provider: bool,
) Error!provider_mod.Provider {
    const requested_provider = if (provider_query) |raw|
        std.mem.trim(u8, raw, " \t\r\n")
    else
        root.id;
    if (!knownProvider(requested_provider)) return error.UnknownProvider;
    if (!std.mem.eql(u8, requested_provider, root.id) and !allow_cross_provider)
        return error.CrossProviderConsentRequired;

    const requested_model = std.mem.trim(u8, model_query, " \t\r\n");
    const model = modelForProvider(requested_provider, requested_model) orelse explicit: {
        // Same rule as `--model <provider>/<model>`: a login-served router
        // (the codegraff gateway) serves what its live catalog lists, which
        // the baked table does not carry, so an explicitly named worker
        // provider takes the exact model name the way the root model does.
        if (provider_query != null) if (provider_mod.specFor(requested_provider)) |spec| {
            if (catalog_selection.acceptsExplicitModel(spec, requested_model)) break :explicit requested_model;
        };
        if (pricing.resolveModelName(keys, requested_model) != null)
            return error.ModelNotOnProvider;
        return error.UnknownModel;
    };
    return keys.providerById(requested_provider, model) catch error.MissingKey;
}

/// The session consented (--allow-cross-provider-subagents) to workers on
/// another provider. Latches on at startup; a later model switch re-resolving
/// the worker without the flag does not withdraw it. Read by per-persona
/// `<provider>/<model>` pins (subagent_pin.zig).
pub var g_cross_provider_consent: bool = false;

pub fn resolveSubagentProvider(
    keys: provider_mod.Keys,
    root: provider_mod.Provider,
    provider_query: ?[]const u8,
    model_query: ?[]const u8,
    allow_cross_provider: bool,
    disable_default_ladder: bool,
) ?provider_mod.Provider {
    if (allow_cross_provider) g_cross_provider_consent = true;
    const raw_provider = provider_query orelse "";
    const requested_provider = std.mem.trim(u8, raw_provider, " \t\r\n");
    const raw_model = model_query orelse {
        if (requested_provider.len != 0)
            std.process.fatal("--subagent-provider requires --subagent-model", .{});
        if (disable_default_ladder) return null;
        return defaultLadderProvider(keys, root);
    };
    const requested_model = std.mem.trim(u8, raw_model, " \t\r\n");
    if (requested_model.len == 0)
        std.process.fatal("--subagent-model/GRAFF_SUBAGENT_MODEL cannot be empty", .{});
    const provider_arg: ?[]const u8 = if (requested_provider.len == 0) null else requested_provider;
    return subagentProvider(keys, root, provider_arg, requested_model, allow_cross_provider) catch |err| switch (err) {
        error.UnknownModel => std.process.fatal("unknown subagent model '{s}' — run `graff models refresh` or see /models", .{requested_model}),
        error.UnknownProvider => std.process.fatal("unknown subagent provider '{s}' — run `graff models` to list providers", .{requested_provider}),
        error.ModelNotOnProvider => std.process.fatal("subagent model '{s}' is not available through provider '{s}'", .{ requested_model, if (provider_arg) |id| id else root.id }),
        error.CrossProviderConsentRequired => std.process.fatal("subagent provider '{s}' differs from root provider '{s}' — add --allow-cross-provider-subagents to confirm prompts and code may be sent to both providers", .{ requested_provider, root.id }),
        error.MissingKey => std.process.fatal("no key/login for subagent model '{s}' via '{s}'", .{ requested_model, if (provider_arg) |id| id else root.id }),
    };
}

test "worker selection stays provider-local unless explicitly allowed" {
    var keys: provider_mod.Keys = .{ .values = @splat(null) };
    for (provider_mod.provider_specs, &keys.values) |spec, *value| {
        if (std.mem.eql(u8, spec.id, "codex") or
            std.mem.eql(u8, spec.id, "kimi")) value.* = "test-token";
    }
    const root = try keys.providerById("codex", "gpt-6-astra");
    const luna = try subagentProvider(keys, root, null, "gpt-6-luna", false);
    try std.testing.expectEqualStrings("codex", luna.id);
    try std.testing.expectEqualStrings("gpt-6-luna", luna.model);
    try std.testing.expectError(
        error.CrossProviderConsentRequired,
        subagentProvider(keys, root, "kimi", "k3", false),
    );
    const kimi = try subagentProvider(keys, root, "kimi", "k3", true);
    try std.testing.expectEqualStrings("kimi", kimi.id);
    try std.testing.expectEqualStrings("k3", kimi.model);
    try std.testing.expectError(
        error.ModelNotOnProvider,
        subagentProvider(keys, root, null, "deepseek-v4-pro", false),
    );
    try std.testing.expectError(
        error.UnknownModel,
        subagentProvider(keys, root, null, "not-a-real-model", false),
    );
    try std.testing.expectError(
        error.UnknownProvider,
        subagentProvider(keys, root, "not-a-provider", "k3", true),
    );
}

test "an explicit worker provider takes a gateway model the baked table lacks" {
    var keys: provider_mod.Keys = .{ .values = @splat(null) };
    for (provider_mod.provider_specs, &keys.values) |spec, *value| {
        if (std.mem.eql(u8, spec.id, "codex") or
            std.mem.eql(u8, spec.id, "codegraff")) value.* = "test-token";
    }
    const root = try keys.providerById("codex", "gpt-6.1-sol");
    const gateway_only = "gateway-only-model-not-in-the-baked-table";
    try std.testing.expect(modelForProvider("codegraff", gateway_only) == null);
    const worker = try subagentProvider(keys, root, "codegraff", gateway_only, true);
    try std.testing.expectEqualStrings("codegraff", worker.id);
    try std.testing.expectEqualStrings(gateway_only, worker.model);
    // Consent is still required to cross the provider boundary, and a bare
    // name with no provider still has to be a catalogued model.
    try std.testing.expectError(error.CrossProviderConsentRequired, subagentProvider(keys, root, "codegraff", gateway_only, false));
    try std.testing.expectError(error.UnknownModel, subagentProvider(keys, root, null, gateway_only, false));
}

test "defaultLadderModel: descends one rung per provider, bottom rung inherits" {
    const mk = struct {
        fn p(id: []const u8, model: []const u8) provider_mod.Provider {
            return .{ .id = id, .kind = .openai, .auth = .bearer, .url = "", .api_key = "", .model = model, .context = 0 };
        }
    }.p;
    // codex / openai: GPT-6 roots keep their model (Astra-low beats Sol-high);
    // tier pins still reach Sol and Luna.
    for ([_][]const u8{ "codex", "openai" }) |id| {
        for ([_][]const u8{ "gpt-6-astra", "gpt-6-sol", "gpt-6-luna" }) |model|
            try std.testing.expect(defaultLadderModel(mk(id, model)) == null);
    }
    // anthropic: opus-5-5 -> sonnet-5-5 -> (bottom) (ADR 0219). #471: a rung
    // must be a cheaper seat, so older opus generations are not rungs, and a
    // root still on one is off-ladder and inherits.
    try std.testing.expectEqualStrings("claude-sonnet-5-5", defaultLadderModel(mk("anthropic", "claude-opus-5-5")).?);
    try std.testing.expect(defaultLadderModel(mk("anthropic", "claude-sonnet-5-5")) == null);
    try std.testing.expect(defaultLadderModel(mk("anthropic", "claude-opus-5")) == null);
    try std.testing.expect(defaultLadderModel(mk("anthropic", "claude-opus-4-8")) == null);
    // deepseek / codegraff: pro (the session default) descends to flash;
    // a flash root is already the cheap seat and inherits.
    try std.testing.expectEqualStrings("deepseek-v4-flash", defaultLadderModel(mk("deepseek", "deepseek-v4-pro")).?);
    try std.testing.expect(defaultLadderModel(mk("deepseek", "deepseek-v4-flash")) == null);
    try std.testing.expectEqualStrings("deepseek-v4-flash", defaultLadderModel(mk("codegraff", "deepseek-v4-pro")).?);
    // unlisted provider -> no ladder at all
    try std.testing.expect(defaultLadderModel(mk("xai", "grok-4.3")) == null);
    // a real, catalogued model that just isn't a rung on its own provider's
    // ladder -> never guess at the nearest one
    try std.testing.expect(defaultLadderModel(mk("anthropic", "claude-opus-4-5")) == null);
}

test "default ladder: resolves the mid sibling when no flags are given" {
    var keys: provider_mod.Keys = .{ .values = @splat(null) };
    for (provider_mod.provider_specs, &keys.values) |spec, *value| {
        if (std.mem.eql(u8, spec.id, "codex") or std.mem.eql(u8, spec.id, "anthropic"))
            value.* = "test-token";
    }
    const astra_root = try keys.providerById("codex", "gpt-6-astra");
    try std.testing.expect(resolveSubagentProvider(keys, astra_root, null, null, false, false) == null);

    const anthropic_root = try keys.providerById("anthropic", "claude-opus-5-5");
    const anthropic_worker = resolveSubagentProvider(keys, anthropic_root, null, null, false, false).?;
    try std.testing.expectEqualStrings("anthropic", anthropic_worker.id);
    try std.testing.expectEqualStrings("claude-sonnet-5-5", anthropic_worker.model);
}

test "default ladder: bottom-rung and off-ladder roots inherit (resolve to null)" {
    var keys: provider_mod.Keys = .{ .values = @splat(null) };
    for (provider_mod.provider_specs, &keys.values) |spec, *value| {
        if (std.mem.eql(u8, spec.id, "codex") or std.mem.eql(u8, spec.id, "xai"))
            value.* = "test-token";
    }
    const luna_root = try keys.providerById("codex", "gpt-6-luna");
    try std.testing.expect(resolveSubagentProvider(keys, luna_root, null, null, false, false) == null);

    const xai_root = try keys.providerById("xai", "grok-4.3"); // unlisted family, never guess
    try std.testing.expect(resolveSubagentProvider(keys, xai_root, null, null, false, false) == null);
}

test "--no-subagent-tier opts out of the default ladder back to plain inherit" {
    var keys: provider_mod.Keys = .{ .values = @splat(null) };
    for (provider_mod.provider_specs, &keys.values) |spec, *value| {
        if (std.mem.eql(u8, spec.id, "anthropic")) value.* = "test-token";
    }
    const root = try keys.providerById("anthropic", "claude-opus-5-5");
    try std.testing.expect(resolveSubagentProvider(keys, root, null, null, false, false) != null);
    try std.testing.expect(resolveSubagentProvider(keys, root, null, null, false, true) == null);
}

test "explicit --subagent-model still wins over the default ladder" {
    var keys: provider_mod.Keys = .{ .values = @splat(null) };
    for (provider_mod.provider_specs, &keys.values) |spec, *value| {
        if (std.mem.eql(u8, spec.id, "codex")) value.* = "test-token";
    }
    const root = try keys.providerById("codex", "gpt-6-astra");
    // The ladder default would inherit Astra; an explicit pin to luna wins.
    const pinned = resolveSubagentProvider(keys, root, null, "gpt-6-luna", false, false).?;
    try std.testing.expectEqualStrings("gpt-6-luna", pinned.model);
}

test "default ladder never crosses a provider boundary implicitly" {
    var keys: provider_mod.Keys = .{ .values = @splat(null) };
    for (provider_mod.provider_specs, &keys.values) |spec, *value| {
        if (std.mem.eql(u8, spec.id, "codex") or std.mem.eql(u8, spec.id, "openai") or
            std.mem.eql(u8, spec.id, "anthropic") or std.mem.eql(u8, spec.id, "deepseek"))
            value.* = "test-token";
    }
    const Case = struct { id: []const u8, model: []const u8 };
    for ([_]Case{
        .{ .id = "codex", .model = "gpt-6-sol" },
        .{ .id = "openai", .model = "gpt-6-astra" },
        .{ .id = "anthropic", .model = "claude-opus-4-8" },
        .{ .id = "deepseek", .model = "deepseek-v4-pro" },
    }) |case| {
        const root = try keys.providerById(case.id, case.model);
        const worker = resolveSubagentProvider(keys, root, null, null, false, false) orelse continue;
        try std.testing.expectEqualStrings(case.id, worker.id); // same provider as root, always
    }
}

test "ladder rungs vs providerClass: documented, intentional disagreement (#291)" {
    // #291 requires ladder tier labels to match scoring.providerClass()
    // output for the same models, "or report the discrepancy rather than
    // papering over it." The gpt family now agrees end-to-end with the
    // ladder, like claude: "sol"/"luna" are tier-distinct needles in
    // providerClass (as opus/sonnet/haiku are), so pullElites and fleet
    // propose events keyed on the class are no longer rung-blind — a sol
    // root pulls "mid" elites, not elites grown on astra.
    try std.testing.expectEqualStrings("frontier", @import("scoring.zig").providerClass("gpt-6-astra"));
    try std.testing.expectEqualStrings("mid", @import("scoring.zig").providerClass("gpt-6-sol")); // ladder rung: mid
    try std.testing.expectEqualStrings("small", @import("scoring.zig").providerClass("gpt-6-luna")); // ladder rung: small
    try std.testing.expectEqualStrings("frontier", @import("scoring.zig").providerClass("deepseek-v4-pro"));
    try std.testing.expectEqualStrings("small", @import("scoring.zig").providerClass("deepseek-v4-flash")); // ladder rung: small
    // Claude agrees end-to-end (opus/sonnet/haiku are tier-distinct needles
    // in providerClass, matching the ladder one-for-one).
    try std.testing.expectEqualStrings("frontier", @import("scoring.zig").providerClass("claude-opus-4-8"));
    try std.testing.expectEqualStrings("mid", @import("scoring.zig").providerClass("claude-sonnet-4-6"));
    try std.testing.expectEqualStrings("small", @import("scoring.zig").providerClass("claude-haiku-4-5"));
}