Skip to content

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

Python
6.3 KB
Raw Blame

v0.0.266 (2026-08-19)

This cut is the peer / plugin / workspace stack on top of 0.0.265. Other harness trees are read where they already live. The system-prompt prefix stays byte-stable so prompt cache can hit.

Peer talk is a working set (ADR 0004)

History no longer carries a second copy of the room.

  • peer_message action=list — who is live
  • peer_message action=inbox — read and clear the process-local ring
  • peer_message / action=send — room or DM send
  • Inbound bodies park in the ring. The model sees one wake line: [peer] 2 unread from session-aaa — peer_message action=inbox
  • Named pings are DMs to the agent that is doing the work, not a broadcast
  • The human still sees full session_notice lines
  • Compact drops spent injects and never treats them as the human

Standing goal stays in the prefix (ADR 0005)

  • --goal / /goal is one [standing goal: …] line on the system prompt
  • The long todo-coaching essay injects on first sight and on change only — not every N turns
  • /loop checklist refresh is unchanged (still 8 quiet turns)
  • Bundled jspace skill is on-demand (skill name=jspace). It is not resident in every prompt

Mid-session workspace switch (ADR 0006)

A skill cannot move read_file / edit_file / bash — they bind to process cwd. cd in one bash call dies with the shell. graff -w only enters a tree at startup.

  • Folded workspace tool: action=list (default) or action=use path=
  • /workspace and /ws for the human
  • Bundled workspace skill is the playbook only — loading it does not chdir
  • Root session only; subagents keep their assigned tree
  • Exact path / folder / branch beat substring matches
  • Presence rebinds to the new folder's room; project instructions stay the ones from session start until /clear or restart

Plugins and foreign MCP, in place (ADR 0007)

Same model as Claude, grok-build, OpenCode, and Codex: do not copy other harness trees, do not walk hashed cache trees.

What counts as a plugin. A directory with .codex-plugin/plugin.json (first), .claude-plugin/plugin.json, .cursor-plugin/plugin.json, .grok-plugin/plugin.json, plugin.json, .mcp.json / mcp.json, skills/, agents/, Claude commands/*.md, or a root SKILL.md.

Where we look. ~/.cursor/plugins/, ~/.claude/plugins/, ~/.grok/plugins/, ~/.codex/plugins/, ~/.codegraff/plugins/, and the matching project trees. Parent dirs are listed two levels deep so Cursor local/<name>/ still shows. Cap 32.

Cache is never walked. cache/ and marketplaces/ are skipped.

  • Claude / Cursor cache installs come from installed_plugins.json installPath (user/unscoped always; local/project cwd-gated)
  • Codex does not write that file. Enabled ids in ~/.codex/config.toml ([plugins."name@marketplace"]) resolve to plugins/cache/<marketplace>/<name>/<version> (prefer local, else the last sorted version). Disabled keys stay invisible
  • A cache-only tree with no registry / config row stays invisible

Skills stay on-demand. Plugin skills/, Claude commands/*.md, and a plugin-root SKILL.md join the skill catalog. The named skill tool loads one body. Project .harness/skills still wins.

MCP is consent-gated. Plugin and foreign MCP fill missing names only. graff's ~/.codegraff/mcp.json and .mcp.json still win. /mcp trust / --yolo unchanged. ${CLAUDE_PLUGIN_ROOT} and ${CLAUDE_PROJECT_DIR} expand in MCP strings.

Load stays cheap.

  • One readdir per visited folder (not a stat per marker)
  • Skill catalog reads an 8 KB frontmatter prefix, not the whole SKILL.md
  • MCP merge only opens plugin trees that already have MCP
  • Production caches the first walk; /plugins prints N plugin(s) in Xms
  • GRAFF_NO_PLUGINS=1 disables the scan
  • Hooks and plugin bin/ PATH are not applied

Prompt-cache max

Codex's rule: the old prompt must be an exact prefix of the new one. We already send a sticky prompt_cache_key. The skill catalog now cooperates:

  • Pinned once at session start into the system-prompt prefix
  • Sorted by name so a rebuild cannot shuffle the first cache hash
  • No file paths (Codex prints file: ~/.codex/plugins/cache/.../SKILL.md; those move and bust the prefix)
  • Bodies stay on disk until skill name=
  • A mid-session skill is loadable via the tool without rewriting the prefix

GPT-5.6 explicit stable-prefix boundary (ADR 0009)

OpenAI Platform GPT-5.6 requests now mark the stable instructions/tool prefix with an explicit 30-minute cache boundary. Root conversations retain the useful implicit latest-message checkpoint; one-shot children avoid writing their unique task suffix. Codex and xAI stay on their supported keyed automatic-cache paths, and OpenAI/Codex child work is spread across four stable role lanes instead of one high-traffic key.

Cache creation tokens are also tracked separately from cache reads and ordinary input. Cost reports apply the documented 1.25× write rate for GPT-5.6 and Anthropic ephemeral caches rather than hiding writes inside ordinary input.

Install PATH

install.sh appends ~/bin (or HARNESS_DIR) to ~/.zshrc, and to ~/.bashrc / fish config when that is the login shell or the file already exists. HARNESS_NO_PATH=1 skips.

Long-horizon evals (ADR 0008)

evals/long_horizon/ generates seeded multi-file workspaces and grades them with external deterministic checks. Model judges may tiebreak, never decide correctness. --showcase --seed 469 prints the generated repo without a provider call.

Also: plugin out-of-band evals (evals/plugins_oob/), and a TUI fix so C0 controls cannot leak through the frame painter (already on main, now on this release line).

Executable behavior contracts

Path confinement, transport selection, score filing, and terminal mode cleanup now have executable state-machine references with matching Lean proofs. This makes lifecycle and fleet behavior checkable as transitions rather than a set of unrelated snapshots.

Suite

Unit suite floor is 1444. Tier 1 reach / lines / fmt stay the gate.

python3 evals/plugins_oob/run.py --self-test
python3 scripts/eval-tier2.py --only plugin-command-as-skill
python3 scripts/eval-tier2.py --only plugin-skill-on-demand
python3 scripts/eval-tier2.py --only plugin-off-keeps-personal-skills
python3 scripts/eval-tier2.py --only workspace-list-use