Skip to content

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

Python
23.1 KB
Raw Blame
//! The engine's internal event vocabulary (#422 slice 1): one tagged union of
//! every distinct output emission the live streaming path (agent_stream.zig)
//! produces, expressed as semantic content — no ANSI, no pre-rendered text.
//! Frontends never see engine internals: a sink (engine_sink.zig) receives
//! these events and renders them (TUI) or serializes them (--json wire).
//!
//! Growth rules for the vocabulary:
//! - New engine output = a new variant (or a new field on a payload struct),
//!   never a pre-rendered string where structure exists. Rendering choices
//!   (color, spinners, wording of notices) belong to sinks.
//! - `durable` classifies each variant: durable events are the protocol
//!   stream a wire/log sink persists and are what reserve sequence ids;
//!   everything else is a presentation pulse that rides at the current
//!   position. Promoting a pulse to the wire is an externally visible shape
//!   change and is gated behind a schema_version bump (epic #422 rule 1).
//! - Payloads are structs so fields can grow without call-site churn.

const std = @import("std");
const protocol_seq = @import("protocol_seq.zig");

/// Position of an event in a session's event log. `sequence` alone is
/// meaningless across restarts: `generation` increments whenever the log
/// restarts (process restart, resume — wired in a later #422 slice), and
/// `sequence` is monotonic within a generation (protocol_seq.zig, the one
/// counter the --json wire already stamps).
pub const Cursor = struct {
    generation: u64,
    sequence: u64,
};

/// Why a delta stream stopped before the provider's terminal event.
pub const StreamAbort = enum {
    /// The user cancelled (Esc) — a deliberate stop, rendered silently.
    interrupted,
    /// The stream went silent past its watchdog budget, or the read path lost
    /// its watchdog (pool exhaustion) — the harness is ending the turn.
    stalled,
    /// The provider closed/reset the socket before its terminal event (#133).
    dropped,
    steered, // a follow-up superseded the streaming reply; the request is rebuilt with it (steer_now.zig)
};

/// A streamed content chunk. `text` is never empty — emitters drop empty
/// deltas before dispatch.
pub const Delta = struct {
    text: []const u8,
};

/// A live transport attempt was cut before the provider's terminal event —
/// the transport-layer counterpart of StreamAbort, born in the connection/
/// read guards (agent_ws.zig slice 1b) where nothing of the answer has
/// rendered yet: sinks may surface a notice but have no held output to
/// flush. `reason == .interrupted` is never emitted today (a deliberate Esc
/// propagates as an error, silently); a sink renders nothing for it.
pub const TransportAbort = struct {
    reason: StreamAbort,
    /// The guard is giving the turn up (its notice says so); false = an
    /// attempt-level cut the reconnect ladder may still retry — silent on
    /// the transcript (ADR 0021).
    turn_ending: bool,
};

/// One tool call as the engine hands it to a frontend (#422 slice 1c).
/// `ask_user` is called out on its own because a --json client learns of
/// that moment through its own `ask_user` event, never as a tool-call pair.
/// `arg_streamed` says the call's prose already streamed out of its
/// still-in-flight arguments (agent_argstream.zig), so an announcement line
/// would repeat what the reader just watched arrive.
pub const ToolInvocation = struct {
    id: []const u8 = "",
    name: []const u8,
    input: std.json.Value,
    ask_user: bool = false,
    arg_streamed: bool = false,
};

/// One finished tool call. `text` is the model-facing result the engine
/// already capped and previewed; `ms` is its measured wall clock. `meta`
/// marks a meta tool (schema.isMetaName) — those own their UX and, except
/// for ask_user, never carried a result on the wire.
/// What a delegated MCP task reported about the context it was handed, and
/// whether its own cost is known. Only these facts cross into ACP `_meta`
/// (`codegraff/runTask`): the task's text and the caller's context do not
/// travel with them (ADR 0253).
pub const RunTaskMeta = struct {
    context_chars: u64 = 0,
    context_used_chars: u64 = 0,
    context_summarized: bool = false,
    usage_reported: bool = false,
    usage_unavailable_reason: []const u8 = "",
};

pub const ToolOutcome = struct {
    id: []const u8 = "",
    name: []const u8,
    text: []const u8,
    is_error: bool,
    cancelled: bool = false,
    ms: i64 = 0,
    meta: bool = false,
    ask_user: bool = false,
    /// Set only for a delegated MCP task that reported context metadata.
    run_task: ?RunTaskMeta = null,
};

/// A tool call the harness refused before it ran: the verifier boundary, a
/// stale eval, the --max-tool-calls budget, the dedupe rule, or review mode.
pub const ToolRejection = struct {
    id: []const u8 = "",
    name: []const u8,
    input: std.json.Value,
    reason: []const u8,
    message: []const u8,
};

/// How a parallel tool batch ended (#266): the tallies, not a rendered line.
pub const BatchOutcome = struct { done: usize, failed: usize, cancelled: usize };

/// Text whose layout belongs to the meta tool that produced it (a completion
/// answer, a rendered todo list) — carried whole because the structure lives
/// in that tool's own module, not in this vocabulary.
pub const ToolText = struct { text: []const u8 };

/// One operational line about the session itself (slice 2): a config file that
/// did not parse, an MCP server that would not connect, what startup loaded.
/// The engine owns the wording — the shared shape is what keeps the lifecycle
/// cluster from needing a variant per call site — and a sink owns how loud it
/// looks. Anything with real structure a frontend would want to read gets its
/// own variant instead (see session_banner and its neighbours below).
pub const Notice = struct {
    /// An emphasized opening fragment (a badge like "⚠ YOLO") a sink may draw
    /// apart from the rest of the line; empty for an ordinary notice.
    lead: []const u8 = "",
    text: []const u8,
    tone: Tone = .plain,

    /// How much attention the line is asking for — the only rendering decision
    /// the engine delegates, since it is about meaning, not palette.
    pub const Tone = enum { plain, dim, warn, alert };
};

/// The interactive startup line. Only the two facts vary per run; what else
/// goes on it (the key hints) is frontend knowledge and lives in the sink.
pub const SessionBanner = struct { cwd: []const u8, trace_path: []const u8 };

/// `-w/--worktree` entered its scratch checkout. `autocommit` says the run
/// will checkpoint each turn onto that branch (main.g_worktree_autocommit).
pub const WorktreeEntry = struct { path: []const u8, branch: []const u8, autocommit: bool };

/// A live Graff session already owns the checkout this session entered. Kept
/// structured so a frontend can foreground the owner and isolation action
/// instead of printing the collision warning as an undifferentiated string.
pub const SharedWorktreeOwner = struct {
    session_id: []const u8,
    pid: i32,
    active_minutes: i64,
    goal: []const u8,
};

/// Startup could not honor the saved model preference and picked another.
/// `blocked` means the substitute is cross-provider and not on the fallback
/// allow-list, so it stays a one-session choice until the user widens it.
pub const SavedModelNotice = struct {
    saved: []const u8,
    model: []const u8,
    provider: []const u8,
    blocked: bool,
};

/// A mid-turn provider failover (providers.runTurnWithFallback). Wire: the
/// existing `model` event, which carries the SUBSTITUTE only — `context_note`
/// (what happened to the conversation across the switch) is the terminal's
/// half, and the wire's own fixed note lives in the sink that writes it.
pub const ProviderFallback = struct {
    from_provider: []const u8,
    from_model: []const u8,
    to_provider: []const u8,
    to_model: []const u8,
    to_context: u64,
    context_note: []const u8,
};

/// The durable session file was written. `ext` is session.session_ext, kept in
/// the payload rather than the sink because the extension belongs to the
/// session format, not to any frontend.
pub const SessionSaved = struct { name: []const u8, ext: []const u8 };

// ── The interactive status line (#429 batch 3) ───────────────────────────────
// Its own value types rather than main.zig's/learning_privacy's: this file is
// the vocabulary, and a transport-split sink must be able to read an event
// without importing the engine. The emit site maps with an exhaustive switch,
// so adding a tier upstream is a compile error here rather than a silent
// mistranslation.

/// Reasoning depth, when the provider takes one at all (main.ReasoningEffort).
pub const ReasoningEffort = enum { low, medium, high, xhigh, max, ultra, none };

/// The federated-learning privacy ceiling (learning_privacy.Mode).
pub const PrivacyTier = enum { local, aggregate, templates, examples };

/// What the cost meter can say. Deliberately not a pre-formatted string: only
/// `.usd` has a figure, and the other three are states, not numbers.
pub const CostMeter = union(enum) {
    /// The meter is off (--no-cost): the segment does not exist.
    hidden,
    /// A flat-rate provider (codex): spend is not per-turn, so there is no
    /// figure to show.
    subscription,
    /// No price-table entry for this model — a real figure cannot be derived.
    unpriced,
    /// Session spend so far, in US dollars.
    usd: f64,
};

/// The live context meter. Present only once a response has reported usage;
/// `tokens` is the effective count, which is not always what the last response
/// said (local estimates carry it between turns).
pub const ContextMeter = struct {
    tokens: u64,
    window: u64,
    /// The count at which this provider compacts.
    compact_at: u64,
};

/// One current-epoch checklist row for the git-style WORKING block.
pub const StandingTodo = struct {
    content: []const u8 = "",
    done: bool = false,
    /// `todo_write` in_progress — the ◌ mark in the WORKING tree.
    active: bool = false,
    /// #1520: cancelled (withdrawn or delegated) with its required reason.
    /// Not counted in `todos_done`/`todos_total`.
    cancelled: bool = false,
    reason: []const u8 = "",
};

/// Standing work the line REPL may draw above the model prompt. Empty
/// strings and zeros mean "nothing to show" so a sink can skip the block.
/// The engine snapshots facts the session already holds; the sink decides
/// order, clip, and whether the block exists at all.
pub const StandingWork = struct {
    /// Human title, or a non-default session name. Empty = untitled `last`.
    session: []const u8 = "",
    /// Live standing goal (not complete). Empty = none.
    goal: []const u8 = "",
    /// Lifecycle when the goal is not the default active: "paused" / "blocked".
    goal_status: []const u8 = "",
    /// Current-epoch checklist. `todos_total == 0` means no list to show.
    todos_done: u32 = 0,
    todos_total: u32 = 0,
    /// Current-epoch items in list order, already clipped. May be shorter
    /// than `todos_total` when the snapshot capped the block.
    todos: []const StandingTodo = &.{},
    /// `/image` or Ctrl-V staged a picture for the next send.
    image: bool = false,
    waiting: []const u8 = "", // ADR 0247: live work whose exit resumes the session
};

/// Everything the status line printed before a human turn actually says.
/// Deliberately semantic: no widths, no colors, no assembled segments. Which
/// badges survive a narrow pane is a rendering decision (#209) and belongs to
/// the sink, which is the only thing that knows the terminal.
pub const PromptStatus = struct {
    model: []const u8,
    provider_id: []const u8,
    cwd: []const u8,
    /// The privacy mode's own badge wording, owned by learning_privacy.zig —
    /// carried whole for the same reason ToolText is, while the tier beside it
    /// is what a sink picks a tone from.
    privacy_label: []const u8,
    privacy: PrivacyTier,
    /// null when this provider takes no reasoning effort, so no badge exists.
    effort: ?ReasoningEffort = null,
    /// null until a response has reported usage.
    context: ?ContextMeter = null,
    /// Prompt-cache hit on the last response; 0 = nothing cached.
    cache_read: u64 = 0,
    cost: CostMeter = .hidden,
    /// The Fast badge APPLIES — the flag is on and the provider honors it.
    fast: bool = false,
    fallback: bool = false,
    plan: bool = false,
    strict: bool = false,
    ultracode: bool = false,
    standing: StandingWork = .{},
    /// Saved conversations in `.graff/sessions` (0 = none / don't mention).
    saved_sessions: u32 = 0,
};

/// Everything the streaming path tells a frontend. Each doc comment states
/// the emission site's contract, not how any one sink draws it.
pub const EngineEvent = union(enum) {
    /// A streaming model request is in flight; nothing has arrived yet. The
    /// TUI answers with the thinking spinner and a fresh per-stream render
    /// state; the wire has no shape for it.
    stream_begin,
    /// A chunk of the model's reasoning ("thinking") text. Wire: the
    /// existing `reasoning` event. TUI: the live dimmed Thinking block,
    /// gated by /thinking.
    reasoning_delta: Delta,
    /// A chunk of visible answer text. Wire: the existing `text` event.
    /// TUI: streamed markdown (or raw bytes off-color). The first one also
    /// ends the reasoning presentation (block close, spinner stop).
    text_delta: Delta,
    /// A chunk of user-facing prose streamed out of a whitelisted meta tool
    /// call's still-in-flight arguments (attempt_completion's result,
    /// ask_user's question — agent_argstream.zig, slice 1b). Never on the
    /// wire: --json clients get the assembled tool_call instead, so a wire
    /// sink stays silent. TUI: renders like answer text (spinner handoff
    /// included) but does NOT end the reasoning presentation — argument
    /// prose can stream while the model is still mid-call.
    tool_arg_delta: Delta,
    /// A chunk of a still-running tool's stdout/stderr (grok-build's
    /// `bash_output_chunk`). Presentation pulse: the --json wire already
    /// carries the assembled `tool_result`; live frames are progress, not
    /// history. TUI: raw append into the live tail. REPL: raw write.
    tool_output_delta: struct { name: []const u8, stderr: bool = false, text: []const u8 },
    /// A background bash job finished (grok-build TaskCompleted). Pulse:
    /// the model learns via the injected wake, not a durable wire id.
    job_completed: struct { id: u64, exit_code: ?u8 = null, killed: bool = false },
    /// A live transport attempt was cut; the payload says how and whether
    /// the turn ends with it (slice 1b). Distinct from stream_aborted: no
    /// partial answer is in flight, so sinks notice without flushing.
    transport_aborted: TransportAbort,
    /// The user asked to fold/unfold the live reasoning view (Ctrl-T, #92).
    /// Presentation-only; a headless frontend ignores it. TRANSITIONAL
    /// (Phase 1b): this is frontend INPUT round-tripping engine-ward through
    /// a global (g_thinking_fold_request) and coming back out — when input
    /// inversion lands it leaves this union (a frontend-owned command, not an
    /// engine event), so plan for removal, not extension.
    thinking_fold_toggle,
    /// The delta stream was cut before its terminal event; the payload says
    /// how. Sinks flush any held partial output and may surface a notice for
    /// the non-deliberate reasons.
    stream_aborted: StreamAbort,
    /// The delta stream ended normally (terminal event seen). streamed_text:
    /// at least one text_delta was emitted live, so the TUI ends the answer
    /// line.
    stream_complete: struct { streamed_text: bool },
    /// The streaming transport call is fully over — emitted on EVERY exit
    /// path, after stream_complete/stream_aborted when those fired. Sinks
    /// tear down live-stream presentation (spinner, an open reasoning-only
    /// Thinking block).
    stream_finished,

    // ── The tool-execution cluster (slice 1c) ────────────────────────────
    /// A tool call cleared the gates and is about to run. Wire: the existing
    /// `tool_call` event. TUI: the ⚙ announcement line.
    tool_call_announced: ToolInvocation,
    /// The same call, now dispatched — the bracket a supervisor times against.
    /// Wire: the existing `tool_call_started` event. TUI: nothing (the ⚙ line
    /// already said it).
    tool_call_started: ToolInvocation,
    /// A tool call returned. Wire: the existing `tool_result` event. TUI: the
    /// compact ✓/✗/⊘ line with a one-line preview.
    tool_result: ToolOutcome,
    /// The same call's closing bracket, carrying the outcome and duration
    /// rather than the text. Wire: `tool_call_finished`. TUI: nothing.
    tool_call_finished: ToolOutcome,
    /// A tool call the harness refused before running it. Wire: the existing
    /// `tool_rejected` event; the TUI has never drawn one (the refusal reaches
    /// the user as the model's next answer).
    tool_rejected: ToolRejection,
    /// A batch of external tool calls is fanning out across the pool.
    /// Presentation-only: the wire brackets each call individually.
    parallel_batch_started: struct { count: usize },
    /// That batch is joined; the payload is the tally (#266 — a cancelled
    /// batch used to just look "running" and then fail).
    parallel_batch_finished: BatchOutcome,
    /// attempt_completion was refused because the standing goal's checklist
    /// is not settled (#318). Presentation-only; the model gets the refusal
    /// as its tool result.
    completion_deferred,
    /// A standing --goal was retired by an accepted attempt_completion.
    goal_completed,
    /// The answer attempt_completion carried, surfaced because it did NOT
    /// stream live out of the call's arguments.
    completion_text: ToolText,
    /// todo_write applied; the payload is the list as goal_todo rendered it.
    todo_list_updated: ToolText,

    // ── The session-lifecycle cluster (slice 2) ──────────────────────────
    // These fire around the turn loop rather than inside it: startup, config
    // loading, provider failover, shutdown. Most of them happen before an
    // Agent exists or after it stops mattering, which is why they reach a
    // sink through engine_sink.writerSink rather than forAgent.
    //
    // The `!json_mode` / `oneshot_prompt == null` gates stay at the EMIT
    // sites, as slice 1c's review put the `!sub` gates back: who may write to
    // the terminal at all is engine policy about who owns it, not a drawing
    // decision, and a sink has no way to know a run is a one-shot.
    /// An operational line about the session. Presentation-only: none of these
    /// ever appeared on the --json wire.
    session_notice: Notice,
    /// The interactive startup banner.
    session_banner: SessionBanner,
    /// `-w/--worktree` entered its scratch checkout.
    worktree_entered: WorktreeEntry,
    /// Another live session owns the checkout used by this session.
    shared_worktree_owner: SharedWorktreeOwner,
    /// The saved model preference could not be honored this session. The
    /// startup twin of provider_fallback, and deliberately not a Notice: a
    /// frontend that wants to offer "use it anyway" needs the fields.
    saved_model_unavailable: SavedModelNotice,
    /// Untrusted MCP servers are configured and the session wants a decision
    /// before connecting them. TRANSITIONAL (Phase 1b): only the QUESTION is
    /// inverted here — the stdin read still happens at the emit site. When
    /// input inversion lands (#430) this becomes a request answered by a
    /// `respond` command, so plan for replacement, not extension.
    mcp_consent_prompt: struct { count: usize },
    /// The active provider failed over mid-turn. Wire: the existing `model`
    /// event; the terminal draws a notice instead.
    provider_fallback: ProviderFallback,
    /// The durable session file was written.
    session_saved: SessionSaved,
    /// The run is over and the engine is done with the frontend: a terminal
    /// frontend hands raw mode back here (#396). Emitted on the one-shot's
    /// completion path in EVERY mode, so a sink must not gate it on json_mode.
    run_finished,

    /// A human turn is about to be read: this is what the session looks like
    /// right now (#429). Presentation-only and always will be — the --json
    /// wire has no prompt because an SDK client drives turns itself, which is
    /// why the emit site skips json_mode entirely rather than relying on a
    /// silent sink.
    prompt_ready: PromptStatus,
};

/// Durable events are the protocol stream: what the --json wire emits today
/// and what a future event log persists. Only they reserve sequence ids —
/// presentation pulses must not open gaps in the wire's numbering.
///
/// This reads the PAYLOAD, not just the tag, and it has to: whether a tool
/// moment reaches the wire depends on which tool it is. A durable sink writes
/// exactly the events this returns true for (engine_sink.jsonEmit asserts it),
/// so a reserved id can never burn with no line behind it (#330).
pub fn durable(ev: EngineEvent) bool {
    return switch (ev) {
        .reasoning_delta, .text_delta => true,
        // Every tool's call bracket is on the wire except ask_user's: a
        // --json client is handed that moment as its own `ask_user` event,
        // and answers it on stdin.
        .tool_call_announced, .tool_call_started => |t| !t.ask_user,
        // Meta tools own their text UX, but correlated calls still need a
        // completion status so clients can close every announced tool row.
        .tool_result => |r| !r.meta or r.ask_user,
        .tool_call_finished => |r| !r.meta or r.ask_user or r.id.len != 0,
        .tool_rejected => true,
        // The lifecycle cluster is presentation-only except the failover,
        // which has always been the wire's `model` event.
        .provider_fallback => true,
        else => false,
    };
}

// Generation 1 is the first life of this process's event log; restart/resume
// wiring bumps it in a later #422 slice (serve attach, #420).
var g_generation: std.atomic.Value(u64) = .init(1);

pub fn generation() u64 {
    return g_generation.load(.monotonic);
}

/// The session's event log restarted: later sequences are a fresh line of
/// history, not a continuation the old cursor can index into.
pub fn bumpGeneration() u64 {
    return g_generation.fetchAdd(1, .monotonic) + 1;
}

/// Stamp a Cursor at the emission boundary. `reserve` draws a fresh id from
/// protocol_seq (durable events on a durable sink; in --json mode the caller
/// holds the stdout lock so reservation and wire order can never diverge —
/// an injected durable sink outside --json currently reserves unlocked, see
/// the engine_sink.zig header note); otherwise the event observes the last
/// reserved position without advancing it.
pub fn stamp(reserve: bool) Cursor {
    return .{
        .generation = generation(),
        .sequence = if (reserve) protocol_seq.next() else protocol_seq.current(),
    };
}