graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
v0.0.267 (2026-08-19)
This release makes long-running jobs dramatically cheaper to supervise and
makes prompt-cache behavior visible instead of implicit. It also lets /btw
reuse the parent turn's cached prefix and strengthens the executable
specification behind that cache contract.
Wait for exit, not the next byte
Background jobs now wait like grok-build: one bash_output(wait_ms>0) blocks
until the process exits, rather than returning on each new output chunk or
after 30 seconds. A measured CI watch had turned the old polling loop into
hundreds of model calls; the model now sleeps while the process runs.
wait_ms = 0(or omitted) remains an immediate snapshot.wait_ms > 0waits for exit or cancellation, with a 10-hour ceiling.- Existing
1…30000values are promoted to that ceiling, so older 30-second callers automatically get completion semantics instead of a poll loop. agent_outputfollows the same contract.- Tool schemas and spawn guidance explicitly say that one wait covers exit.
See ADR 0010 for the measured failure mode and trade-offs.
See what the prompt cache is doing
The new /cache HUD exposes the cache posture without revealing prompt
contents, paths, or tool bodies:
- stable-prefix hash and the latest cache read/write counts;
- session hit rate, catalog mode, and the last named bust reason;
- xAI conversation, session, and
prompt_cache_keyaffinity; - the remaining opt-in levers for maximizing reuse.
/debug includes a compact row from the same snapshot. Prefix-changing
mutations such as goal, playbook, compaction, persona, tool, and MCP updates
are recorded where they happen, but count as a bust only when the next
request's system-and-tools prefix actually changes. Stable catalog mode stays
opt-in because earlier live measurement showed no benefit from making it the
default.
/btw reuses the parent prefix
Side questions now send the same system prompt, tools JSON, and
prompt_cache_key as their parent request, then append the side question as a
user message. Tools remain advertised to preserve identical prefix bytes but
are not executed by /btw.
In a live Grok 4.6 measurement, an append-only second turn reused 3,712 of
3,721 prior input tokens, and the following /btw reused the same 3,712 tokens
(99.8% of the prior prompt). xAI requests also send the project-derived
x-grok-session-id alongside the existing conversation and prompt-cache
identifiers.
See ADR 0011 for the visibility and default-policy decision.
Cache behavior is executable and proved
Two new reference kernels, conformance suites, and Lean proofs document the cache contract independently of the production implementation:
- Prompt prefix models the maximizing walk that preserves stable bytes and identifies the cacheable boundary.
- Prompt stability proves the must-nots that would silently invalidate an otherwise reusable prefix.
The kernels are part of the normal conformance manifest, so future changes are checked against the same contract rather than relying on release-time measurements alone.
Reliability fixes included
- Streamable HTTP MCP startup performs one modern
tools/listprobe and enters legacy initialization only when the server returns a legacy-shaped response, avoiding duplicate discovery and initialization traffic. - CodeDB Pro prepared paths use native separators on Windows.
- CI parsers understand folded native-tool schema listings.
- Hosted TUI cancellation and goal-loop checks are isolated from unrelated recap behavior.
Distribution
Prebuilt archives are available for Linux, macOS, and Windows on arm64 and
x86_64. Both macOS binaries are Developer ID signed, hardened-runtime enabled,
and notarized by Apple; SHA256SUMS covers all six platform archives.