Skip to content

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

Python
7.9 KB
Raw Blame
//! #372 — the observability half of learned orchestration: emitting one
//! worker's routing decision, and capturing a scored one back into the local
//! DGM archive so the policy in route_policy.zig has something to learn from.
//!
//! Split from route_policy.zig (which owns the decision TYPES and the policy
//! itself) both to stay under the 600-line cap and because the two halves
//! have opposite dependency shapes: the policy is a leaf over shapes/bench,
//! while emission reaches the tracer, the trajectory archive, and the --json
//! protocol stream.
//!
//! Three sinks, one call:
//!
//!   tracer     `{"ev":"route","detail":"shape=… role=… source=…"}` in
//!              .graff/traces/<run>.jsonl — the diagnostics path a user
//!              greps to answer "why did this worker get that model".
//!   trajectory `{"kind":"route", …}` in .graff/trajectories/<run>.jsonl —
//!              the same fact as structured columns, so an offline reader can
//!              reconstruct which policy ran without parsing the line.
//!   --json     an additive `agent_route` event on the shared stdout stream,
//!              carrying the worker's label so a UI can pair it with the
//!              `workflow_progress` task row it belongs to.
//!
//! Best-effort everywhere: a routing trace must never be able to fail a
//! spawn, so every error path is a silent return.

const std = @import("std");
const Io = std.Io;

const policy = @import("route_policy.zig");
const Cell = policy.Cell;
const Decision = policy.Decision;
const Shape = policy.Shape;
const Source = policy.Source;

const trace = @import("trace.zig");
const util = @import("util.zig");
const main_mod = @import("main.zig");
const protocol_seq = @import("protocol_seq.zig");
const scoring = @import("scoring.zig");
const selection = @import("subagent_selection.zig");
const Provider = @import("provider.zig").Provider;

/// Model-authored labels are capped so one absurd description cannot turn a
/// route line into a megabyte of JSONL (workflow_progress.label_cap's rule).
const field_cap = 64;
const line_cap = 320;

pub const RouteEvent = struct {
    type: []const u8 = "agent_route",
    /// The worker's own description/label, so a UI can pair this with the
    /// workflow_progress task row it belongs to.
    task: []const u8,
    shape: []const u8,
    role: []const u8,
    tier: []const u8,
    resolved_model: []const u8,
    provider: []const u8,
    source: []const u8,
    policy_or_genome_id: []const u8,
};

/// Test seam, mirroring workflow_progress.g_test_sink: when set, the --json
/// event renders here instead of stdout.
pub var g_test_sink: ?*Io.Writer.Allocating = null;

fn guiEmit(io: Io, ev: RouteEvent) void {
    if (g_test_sink) |sink| {
        var s: std.json.Stringify = .{ .writer = &sink.writer };
        s.write(ev) catch return;
        sink.writer.writeByte('\n') catch return;
        return;
    }
    if (!main_mod.json_mode) return;
    const w = main_mod.g_out orelse return;
    // The same lock guiEmit/printDelta take: workers emit from pool threads,
    // and a half-written line would corrupt the SDK's JSONL parse.
    main_mod.g_gui_mu.lockUncancelable(io);
    defer main_mod.g_gui_mu.unlock(io);
    protocol_seq.writeEvent(w, ev) catch return;
    w.writeByte('\n') catch return;
    w.flush() catch return;
}

fn tierName(t: ?policy.Tier) []const u8 {
    return if (t) |x| x.label() else "";
}

/// Emit one worker's routing decision on all three paths at once.
pub fn emit(io: Io, tracer: ?*trace.Tracer, label: []const u8, provider_id: []const u8, d: Decision) void {
    var buf: [line_cap]u8 = undefined;
    if (tracer) |tr| tr.note("route", policy.formatDecision(&buf, d));
    if (trace.g_traj) |tj| tj.node(.{
        .kind = "route",
        .label = util.utf8Prefix(label, field_cap),
        .shape = d.shape.label(),
        .role = d.role,
        .tier = tierName(d.tier),
        .model = d.resolved_model,
        .provider = provider_id,
        .source = d.source.label(),
        .policy_or_genome_id = d.policy_id,
        .t = tj.elapsedMs(),
    });
    guiEmit(io, .{
        .task = util.utf8Prefix(label, field_cap),
        .shape = d.shape.label(),
        .role = d.role,
        .tier = tierName(d.tier),
        .resolved_model = d.resolved_model,
        .provider = provider_id,
        .source = d.source.label(),
        .policy_or_genome_id = d.policy_id,
    });
}

/// Build and emit the decision for one spawned worker. `genome` is what
/// `policy_or_genome_id` reports for a decision fleet fitness did NOT make:
/// the root-authored system-prompt fingerprint, the persona niche, or "" for
/// a plain inherit. The tier is read BACK off the resolved model, so a worker
/// that stated no tier still reports the rung it actually landed on — which
/// is the whole point: an inherited route was previously invisible.
pub fn emitSpawn(
    io: Io,
    tracer: ?*trace.Tracer,
    label: []const u8,
    provider_id: []const u8,
    model: []const u8,
    cell: Cell,
    source: Source,
    genome: []const u8,
) void {
    var pbuf: [128]u8 = undefined;
    const tier = policy.tierOf(provider_id, model);
    const policy_id = switch (source) {
        .learned_policy => if (tier) |t| policy.cellId(&pbuf, cell, t) else "",
        .ladder => std.fmt.bufPrint(&pbuf, "ladder:{s}", .{provider_id}) catch "",
        else => util.utf8Prefix(genome, field_cap),
    };
    emit(io, tracer, label, provider_id, .{
        .shape = cell.shape,
        .role = cell.role,
        .tier = tier,
        .resolved_model = model,
        .source = source,
        .policy_id = policy_id,
    });
}

/// What an UNPINNED worker inherited. A session whose worker route came from
/// the #291 ladder descent reports `ladder`; an explicit --subagent-model (or
/// a plain inherit-the-root) reports `session-default`. Conflating the two is
/// exactly the blindness #372 is about.
pub fn sessionSource(session_pinned: bool) Source {
    return if (session_pinned and selection.g_default_from_ladder) .ladder else .session_default;
}

/// emitSpawn for an already-resolved child Provider — the spawn-site
/// convenience. Fingerprints an inline root-authored genome for
/// `policy_or_genome_id`, else names the persona niche the worker ran under.
pub fn emitSpawnProvider(
    io: Io,
    tracer: ?*trace.Tracer,
    label: []const u8,
    child: Provider,
    cell: Cell,
    source: Source,
    sys_override: ?[]const u8,
    niche: []const u8,
) void {
    var fp: [16]u8 = undefined;
    if (sys_override) |so| fp = scoring.promptFingerprint(so);
    emitSpawn(io, tracer, label, child.id, child.model, cell, source, if (sys_override != null) &fp else niche);
}

/// Local DGM capture of one SCORED worker configuration (#372 part 2): the
/// same `kind:"score"` row the eval loop already writes, plus the cell
/// coordinates route_policy.foldCells partitions on. Deliberately OUTSIDE the
/// telemetry gate — a default-local-privacy session must accumulate its own
/// policy evidence with zero egress, exactly like agent_eval's local capture.
pub fn captureScore(prompt_sha: []const u8, niche: []const u8, provider_id: []const u8, d: Decision, score: f64) void {
    const tj = trace.g_traj orelse return;
    tj.node(.{
        .kind = "score",
        .prompt_sha = prompt_sha,
        .score = score,
        .niche = niche,
        .shape = d.shape.label(),
        .role = d.role,
        .tier = tierName(d.tier),
        .model = d.resolved_model,
        .provider = provider_id,
        .t = tj.elapsedMs(),
    });
}

/// One scored variant's policy observation. Role and tier are derived here so
/// the call site (subagent.zig, at the 600-line cap) spends one line on it.
pub fn captureVariant(child: Provider, shape: Shape, title: []const u8, niche: []const u8, genome: []const u8, s01: f64) void {
    captureScore(genome, niche, child.id, .{
        .shape = shape,
        .role = policy.roleOf(title, niche),
        .tier = policy.tierOf(child.id, child.model),
        .resolved_model = child.model,
    }, s01);
}