Skip to content

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

Python
14.9 KB
Raw Blame

v0.0.282 (2026-08-31)

Next cut after v0.0.281 merged to main (#670). The headline is three yxlyx product PRs that were open against the old main tip: atomic paste spans, terminal Codex WS errors, and recoverable HTTP client generations.

281 stays published as-is. This is not a retag.

What graff is, and how it works

graff is one static Zig binary — about 3.7 MB, zero dependencies, its HTTP client brings its own TLS — that turns the AI subscriptions you already pay for into an agent that does work on your machine. You sign in with Codex, SuperGrok, Kimi, Claude, or any API key; you hand it a task in plain English; it plans, writes and runs code, edits your real files, and keeps going until the task verifies — including spinning up a team of subagents in parallel worktrees. You don't chat with it. You give it work.

One agent, many faces. A single Agent type is the unit of execution: the line REPL's root, every subagent, graff acp's session, the embedded libgraff/wasm engine (ADR 0038), and the TUI's in-process client (ADR 0041) are all the same struct running the same turn loop. Nothing is re-implemented per surface — a surface is a sink.

Many seats, one wire contract. Provider adapters decouple wire format from auth style, so subscription logins and API keys are interchangeable: ChatGPT OAuth speaks the Responses API (with server-side compaction and a WebSocket turn transport), Claude Code OAuth speaks Anthropic Messages, SuperGrok tokens speak xAI's Responses wire over WebSocket with hosted x_search, and plain API keys speak OpenAI Chat or Anthropic. A model election ranks signed-in plans above metered keys on the same model (ADR 0017), so a flat-rate seat is what actually gets used.

The turn loop. buildBody serializes the request against a stable prompt-cache prefix — the catalog, tool schemas, and skill list are pinned so a warm cache hit survives every load — then streams the response over SSE and normalizes everything into typed EngineEvents. Sinks render those events; the REPL, --json stream, and TUI are proven byte-identical against the same trace. Tool calls fan out on the Io thread pool: built-ins (bash, edit_file/write_file/read_file — exact-string replaces, path-confined), subagent and workflow (dynamic fan-out as data), and MCP servers from .mcp.json (namespaced, schemas loaded lazily, deferred past first paint). A structural permission gate sits under every state-changing call — metacharacter-aware bash matching, cwd lock, path confinement that /yolo cannot bypass — so autonomy is a dial, not a hope.

Resilience is engineered, not hoped for. This cut is largely the transport hardening that keeps a whole workday alive: TLS client generations rotate on a poisoned construction (ADR 0048), a Codex type:error frame is honored as a terminal API answer instead of a redial (#693), deterministic short flakes on the Codegraff seat retry twice while auth and quota stay fail-fast (ADR 0053), and lean one-shots bounce a prose-only fake completion (ADR 0052).

Context discipline is the product. The transcript is append-only and compaction cannot rewrite it (ADR 0021); OpenAI routes use first-party server-side compaction with a local transactional fallback; oversized tool results spill to a 4 KB handle the model can open instead of occupying context turn after turn; the RLM + mid-stream spec-ptc loop lets the model program over context instead of pasting it back into the prompt (ADR 0022). That stack is why the same model on the same seat below runs 2–6× cheaper and faster than peer harnesses (see the frontier below) — without a 4-tool catalog or a 1 GB heap (ADR 0024).

Sessions are durable and forkable. Every conversation autosaves to .graff/sessions; /resume restores provider history, and this cut adds clone-on-write branches — --resume SOURCE --branch DEST forks a saved session once and the two lives never write each other's files again (ADR 0049). The GUI sidebar is the same directory.

A learning loop that runs itself. Sessions record behavior metrics; a workspace that does real model work bootstraps its own learning store once, detached so teardown never waits on suite generation; the kit pins the live binary by hardlink — no 127M copy; generated suites and independent holdouts drive background tournaments that promote a new genome only through statistical gates.

Surfaces. graff (line REPL), graff tui (the Grok-style fullscreen pager), graff acp (Agent Client Protocol for Zed and the desktop apps), @codegraff/sdk (TypeScript + Python, embeddable in-process or remote), and two GUIs: the Tauri desktop app in gui/ with its auto-updater, and the native Codex-class harness introduced in 281 (files pane, git Changes review, per-tab agents, session-history sidebar) — unchanged here, it rides the same ACP wire.

Atomic pasted-text placeholders (#674 / #673)

The composer used to store a long paste body out of band and represent it with ordinary editable text. Submit searched for the exact display string and replaced every match, so Option+Backspace chewed the marker word by word and a typed lookalike could resurrect a hidden body.

readline now owns a semantic paste store: each collapsed [Pasted text #N +L lines] chip is a positional span. Navigation and deletion treat it as one unit. Expansion happens only for a live span and consumes its identity, so a typed lookalike stays literal. History replay drops identity (history has no hidden body to restore). readline_replay.zig holds history replay so readline.zig stays under the 600-line ceiling.

Codex WS type:error is a terminal API response (#693 / #692)

Codex sends a useful type:error frame and then closes the socket. Graff recognized only two special codes as terminal; a generic error waited for another frame, treated the expected close as transport loss, discarded the API body, and redialed. Users saw Bad Request and the fullscreen TUI replaced the failure with an API-key row.

Every authoritative Responses type:error is now a terminal API response. A bounded single-line provider/code/message diagnostic rides last_api_error (no raw envelope). A stale previous_response_id rebuilds full input exactly once. Generic deterministic API errors return immediately and do not consume the WS-retry / SSE-fallback ladder.

Model HTTP client generations (ADR 0048 / #694 / #691)

TlsInitializationFailed at std.http.Client.request happens before a Request exists, so the #177 connection-poison path cannot mark anything closing. Retrying the same launch-owned client left every later TUI turn failing until process restart.

Model HTTP constructors lease an active launch-level generation. A construction TLS failure retires that generation and publishes a prewarmed replacement. In-flight callers keep the retired generation through reference-counted leases; later retries resolve the original launch pointer to the replacement. The original launch client is never reclaimed by the manager (unrelated launch consumers still hold its pointer). WebSocket transport stays independently managed. The two production constructor catches share one predicate now: a handshake that dies mid-read — on Windows an aborted peer surfaces as error.Unexpected (NTSTATUS LOCAL_DISCONNECT), not TlsInitializationFailed — traverses the same recovery, so the malformed-peer contract holds on every platform.

#694 recorded this as ADR 0042. That number is already TUI claims screen on main. This cut remaps the record to 0048. The follow-up hardens lease teardown (drain on shutdown, retry accounting, child coverage) and keeps 0048.

Clone-on-write session branches (ADR 0049 / #697 / #689)

Two processes resuming the same name wrote the same .session.json. --resume SOURCE --branch DEST (and /resume … --branch) clones provider history and the peer cursor once; later saves belong only to DEST. A filesystem-exclusive claim stops a destination race. Branches do not auto-merge. #697 numbered this 0042; remapped to 0049. #698 reopened the same head with three follow-ups now on this tip: raise the learn-pin ceiling to 160 MiB so a Linux debug image still pins after session branching linked in, match source suffixes at a token boundary so a compaction handoff's .session.json / .transcript.jsonl is not a JavaScript nudge, and parse Codex compaction user text from either a chat string or Responses input_text blocks.

Warmed TLS on MCP HTTP and WSS (ADR 0050 / #679)

MCP probe/initialized stay on the persistent HTTP client. WSS CA is scanned once per process. WS→SSE keeps the prewarmed pool. MCP HTTP accepts gzip catalogs. #679 numbered this 0043; remapped to 0050.

Empty tool catalog is omitted (#695)

A wide-native RLM showcase that invalidated the root catalog and did not rebuild it serialized "tools":, and every provider 400'd (reproduced on 0.0.280). Showcase callers rebuild now; buildBody also omits the field when the catalog string is empty — the same shape text_only already uses. Responses, Chat, and Anthropic bodies are pinned.

12-task in-house remasure after #697

Same SuperGrok seat, jobs=1, grok-4.6, x_search on. Graff is still the unique frontier vs grok-build and OpenCode on pass / wall / calls / tokens / list$ / RSS (run-20260831-021035-composite). Calls stayed 52. list$ ticked down. Wall is +9s vs the 141658 pin, almost all on one model-variance retry of atomic-symlink-write. peer-resume (the #697-shaped fixture) passed. First-token is not a named win.

Sandbox teleport and snapshot GC (ADR 0051 / #677)

Leftover of #554. /teleport <id> [docker|container] restores a captured docker_image_tar onto another CLI backend. Apple Container is the second backend (same wire, different bin_name). Dest defaults to container when the live backend is docker or nothing is attached. /snapshot gc [n] keeps the newest n snapshot trees (default 1). The conversation is never rewound. Missing CLIs explain, they do not crash. #677 numbered this 0042; remapped to 0051.

DeepSeek thinking-off and lean 15s bash (ADR 0052–0055 / #675)

Hillclimb of DeepSeek flash SWE on the Codegraff seat. Do not steal Pi's four-tool catalog or OpenCode's ~1G heap.

  1. Lean -p bounces a first-turn prose-only "done" (ADR 0052).
  2. Short Codegraff follow-up flakes retry twice (ADR 0053), including the 110-byte invalid_request_error / "Body must be valid JSON". Auth / quota / a real invalid prompt stay fail-fast. opencode-codegraff is the same-seat OpenCode A/B harness.
  3. DeepSeek family default low sends thinking.type=disabled (ADR 0054). /effort high still thinks. GLM stays low-only.
  4. Lean -p bash auto-backgrounds at 15s (ADR 0055). Interactive stays 120s (ADR 0026).

#675 numbered these 0048–0051. 282 already owns 0048–0051; remapped to 0052–0055. Keep-alive-only bodies share the short-flake retry in agent_gateway_retry.zig so 282's request-scratch split stays.

We are the Pareto frontier — remeasured on this tip

Same SuperGrok seat, same 12 shipped-PR fixtures, jobs=1, grok-4.6, x_search on — re-run against this exact release tip (b1fcf67, session branches and the empty-catalog omit included). Every axis named is lower-is-better, and graff is still the unique frontier on all of them (run-20260831-021035-composite):

harness pass wall calls tokens list$ RSS
graff 12/12 200.9s 52 230k $0.34 8.8M
grok-build 12/12 387.7s 64 1.17M $1.05 160.9M
OpenCode 12/12 310.4s 81 737k $0.93 1149.9M

Calls stayed exactly 52 and list price ticked down ($0.3504 → $0.3410) with session branching in the tree. Wall is +8.8s vs the 281 pin, almost all of it one model-variance retry on atomic-symlink-write — not a regression. peer-resume (the fixture shaped like #697 itself) passed and got faster.

Pareto frontier, 12 in-house fixtures remeasured on the v0.0.282 tip: wall and tool calls vs list price — graff lower-left

For scale, the spine loop you feel per keystroke was 3/3 in 19.9s / 0.6s first / 8 calls on the same seat. Full tables, methodology, and the prior pin: graff-evals/hillclimb/baseline.md. How: the stable cache prefix, the RLM + spec-ptc loop, slim tool results, and the hardlink learn pin. We do not steal grok-build's heap or a 4-tool catalog to win (ADR 0024).

Parked

#277 (Streamable HTTP OAuth / Smolify) and #200 (idle localhost servers) were closed as abandoned vs tip; the issues stay inventory in yxlyx-leftovers.md. Smolify is not a reserved core MCP.

Tests

This cut raises the release-cut floor to 1861 (slack 25). Paste spans, Codex WS errors, HTTP generations, session branches, MCP TLS-reuse, empty-catalog omit, teleport/GC, and DeepSeek/lean-bash tests land on top of the 1804 floor from 281. The suite count is re-ratcheted after zig build test on this revision. agent_request.zig split request-scratch helpers into agent_request_scratch.zig so the Codex WS merge stays under the 600-line ceiling.

Downloads

All six CLI archives, the curl installer, and checksums:

File Platform
graff-aarch64-linux.tar.gz Linux arm64
graff-aarch64-macos.tar.gz macOS Apple Silicon — Developer ID signed, Apple notarized
graff-aarch64-windows.tar.gz Windows arm64
graff-x86_64-linux.tar.gz Linux x86_64
graff-x86_64-macos.tar.gz macOS Intel — Developer ID signed, Apple notarized
graff-x86_64-windows.tar.gz Windows x86_64
install.sh curl installer
SHA256SUMS checksums for the six archives
curl -fsSL https://github.com/justrach/codegraff/releases/download/v0.0.282/install.sh | bash

Both macOS binaries are Developer ID Application signed (hardened runtime, timestamped) and Apple notarized (notary-local, Accepted: 28299935-b4c5-48ca-916d-d03e04e1e021 aarch64, 0fdbb93f-ddb4-4424-8135-a37acd92a11c x86_64). Stapling is skipped on the bare CLI (stapler error 73); Gatekeeper checks the ticket online at first launch. GitHub also attaches the usual source zip/tarball for the tag.