graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
Cache release-matrix builds with pinned nanocompile
justrach4f24adf8087d
diff --git a/.github/actions/setup-nanocompile/action.yml b/.github/actions/setup-nanocompile/action.ymlnew file mode 100644index 00000000..2f271435--- /dev/null+++ b/.github/actions/setup-nanocompile/action.yml@@ -0,0 +1,29 @@+name: Setup nanocompile release cache+description: Build a pinned nanocompile and restore the target's declared-task cache+inputs:+ target:+ description: Release-matrix target+ required: true+runs:+ using: composite+ steps:+ - uses: actions/checkout@v7+ with:+ repository: justrach/nanocompile+ ref: dec24ac64b2c810cca247f850ed1784830362df5+ path: .nanocompile-source+ persist-credentials: false+ - name: Build pinned nanocompile+ shell: bash+ working-directory: .nanocompile-source+ run: |+ zig build -Doptimize=ReleaseFast --prefix "$GITHUB_WORKSPACE/.nanocompile-tools"+ echo "NANOCOMPILE_EXE=$GITHUB_WORKSPACE/.nanocompile-tools/bin/nanocompile" >> "$GITHUB_ENV"+ echo "NANOCOMPILE_DIR=$GITHUB_WORKSPACE/.nanocompile-cache" >> "$GITHUB_ENV"+ - name: Restore nanocompile task artifacts+ uses: actions/cache@v6+ with:+ path: .nanocompile-cache+ key: nanocompile-release-v1-${{ runner.os }}-${{ runner.arch }}-${{ inputs.target }}-dec24ac-${{ github.sha }}+ restore-keys: |+ nanocompile-release-v1-${{ runner.os }}-${{ runner.arch }}-${{ inputs.target }}-dec24ac-diff --git a/.github/workflows/beta-release.yml b/.github/workflows/beta-release.ymlindex 804d14c3..49462b9a 100644--- a/.github/workflows/beta-release.yml+++ b/.github/workflows/beta-release.yml@@ -50,17 +50,20 @@ jobs:steps:- uses: actions/checkout@v7- uses: ./.github/actions/setup-codegraff-zig+ - uses: ./.github/actions/setup-nanocompile+ with:+ target: ${{ matrix.target }}- name: Cross-compile beta CLI (${{ matrix.target }})env:BETA_VERSION: ${{ needs.plan.outputs.version }}TARGET: ${{ matrix.target }}run: |set -euo pipefail- zig build graff -Doptimize=ReleaseFast -Dtarget="$TARGET" -Dversion="$BETA_VERSION"+ python3 scripts/build-release.py --target "$TARGET" --version "$BETA_VERSION" --verify-restorename="graff-$TARGET"mkdir "$name"case "$TARGET" in *-windows) bin=graff.exe ;; *) bin=graff ;; esac- cp "zig-out/bin/$bin" "$name/$bin"+ cp "zig-out/$TARGET/bin/$bin" "$name/$bin"cp README.md LICENSE "$name/"tar -czf "$name.tar.gz" "$name"- uses: actions/upload-artifact@v7diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 7d494c53..fbc00713 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -46,6 +46,10 @@ jobs:- name: Install Ziguses: ./.github/actions/setup-codegraff-zig+ - uses: ./.github/actions/setup-nanocompile+ with:+ target: ${{ matrix.target }}+- name: Cross-compile (${{ matrix.target }})env:TARGET: ${{ matrix.target }}@@ -55,7 +59,7 @@ jobs:# Release builds phone usage/evolution telemetry here by default# (anonymous, opt out with --no-telemetry / GRAFF_NO_TELEMETRY).TELEMETRY_ENDPOINT="https://harness-telemetry.rachpradhan.workers.dev"- zig build graff -Doptimize=ReleaseFast -Dtarget="$TARGET" -Dversion="$VERSION" -Dtelemetry-endpoint="$TELEMETRY_ENDPOINT"+ python3 scripts/build-release.py --target "$TARGET" --version "$VERSION" --telemetry-endpoint "$TELEMETRY_ENDPOINT" --verify-restorename="graff-$TARGET"mkdir "$name"# Windows targets emit graff.exe; every other target emits graff.@@ -63,7 +67,7 @@ jobs:*-windows) bin=graff.exe ;;*) bin=graff ;;esac- cp "zig-out/bin/$bin" "$name/$bin"+ cp "zig-out/$TARGET/bin/$bin" "$name/$bin"cp README.md LICENSE "$name/"tar -czf "$name.tar.gz" "$name"diff --git a/.gitignore b/.gitignoreindex 7cc08993..209fbb1c 100644--- a/.gitignore+++ b/.gitignore@@ -1,5 +1,6 @@# build output.zig-cache/+.zig-global-cache/zig-out/zig-pkg/target/@@ -16,6 +17,11 @@ harness.trajectory.jsonl.simple-harness-keys.json.simple-harness-codegraff.json+# release task-cache checkout, tool and artifact stores+.nanocompile-source/+.nanocompile-tools/+.nanocompile-cache/+# tooling artifacts.zigrep_archivecodedb.snapshotdiff --git a/docs/adr/0291-release-builds-use-declared-task-caching.md b/docs/adr/0291-release-builds-use-declared-task-caching.mdnew file mode 100644index 00000000..0703128a--- /dev/null+++ b/docs/adr/0291-release-builds-use-declared-task-caching.md@@ -0,0 +1,32 @@+# 0291: Release builds use declared-task caching++## Context++The release and beta workflows build six CLI targets on Linux runners. A plain+`nanocompile zig build` transparently delegates to Zig; it does not cache the+nested compiler commands. Calling that a cached matrix would be misleading.+Nanocompile already supports explicit, ordered whole-task contracts, including+artifacts for targets its direct compiler cache conservatively bypasses.++## Decision++Pin the published nanocompile source revision and build it with the same pinned+Zig as the CLI. Run each matrix build as one declared task. Include tracked+repository files, the fetched dependency tree, the compiler/library resources,+and the selected SDK when running locally on macOS. Pass the target, version,+and telemetry choice explicitly. Give each target its own output prefix.++Use a small fixed child environment instead of forwarding CI tokens, run IDs,+and unrelated shell variables. Nanocompile still keys every retained value.+Restore its artifact store with a target-specific Actions cache. Before+packaging, remove the generated binary and require a byte-identical restoration+and a recorded task hit. Signing and publishing remain outside the cache.++## Consequences++This is conservative whole-build reuse, not finer-grained compiler caching or a+measured speed improvement. A new version or changed input may miss. Inputs+are rehashed and artifact bytes are checked by nanocompile; the existing tests,+six-target matrix, signing, and release freshness checks remain required.+The source pin changes only after verification, not automatically with upstream+`main`. New build-time resources must join the explicit contract.diff --git a/docs/adr/README.md b/docs/adr/README.mdindex ba9be0f8..fdfc85ee 100644--- a/docs/adr/README.md+++ b/docs/adr/README.md@@ -305,6 +305,7 @@ record only when you need the evidence or the edge cases.| [0288](0288-anthropic-native-login-is-source-aware.md) | Native subscription PKCE login is shared across CLI, REPL and ACP; subscription wire compatibility stays credential-source-aware. || [0289](0289-mcp-results-preserve-typed-and-display-content.md) | Preserve typed MCP results independently of display content, show resource references without fetching them and answer pings during shared waits. || [0290](0290-mcp-task-replies-outlive-child-deadlines.md) | HTTP task calls wait for validated child and required preprocessing budgets plus reply cleanup; other requests keep their deadlines. |+| [0291](0291-release-builds-use-declared-task-caching.md) | Pin nanocompile and cache complete release build tasks with explicit inputs, tool resources, and a verified byte-identical restore before packaging. |## When to write onediff --git a/scripts/build-release.py b/scripts/build-release.pynew file mode 100644index 00000000..7ecb6ca7--- /dev/null+++ b/scripts/build-release.py@@ -0,0 +1,102 @@+#!/usr/bin/env python3+"""Build one release-matrix target through nanocompile's declared-task cache."""+import argparse+import hashlib+import json+import os+from pathlib import Path+import re+import shutil+import subprocess+import sys++TARGETS = ("aarch64-macos", "x86_64-macos", "x86_64-linux", "aarch64-linux",+ "x86_64-windows", "aarch64-windows")+ROOT = Path(__file__).resolve().parents[1]+++def files(root):+ return sorted({str(p.resolve()) for p in root.rglob("*") if p.is_file()})+++def contract(target, version, zig, telemetry=None):+ # A fixed version avoids an undeclared dependency on git describe / .git.+ output = ROOT / "zig-out" / target / "bin" / ("graff.exe" if target.endswith("windows") else "graff")+ command = [str(zig), "build", "graff", "-Doptimize=ReleaseFast",+ "-Dtarget=" + target, "-Dversion=" + version,+ "--prefix", str(ROOT / "zig-out" / target)]+ if telemetry is not None:+ command.append("-Dtelemetry-endpoint=" + telemetry)+ tracked = subprocess.check_output(["git", "ls-files", "-z"], cwd=ROOT).decode().split("\0")+ inputs = {str(ROOT / p) for p in tracked if p and (ROOT / p).is_file()}+ inputs.add(str(Path(__file__).resolve()))+ # Zig 0.17 fetches its pinned package tree here. Include content, not just+ # the dependency lock: local package edits must invalidate a task restore.+ inputs.update(files(ROOT / "zig-pkg"))+ description = subprocess.check_output([str(zig), "env"], text=True)+ match = re.search(r'\.lib_dir = "([^"]+)"', description)+ if not match:+ raise RuntimeError("Cannot identify the selected Zig library tree")+ resources = {str(zig)}+ resources.update(files(Path(match.group(1))))+ # On macOS the selected SDK is another installed tool resource. Linux+ # matrix runners cross-link using Zig's bundled libraries instead.+ if sys.platform == "darwin":+ sdk = subprocess.check_output(["xcrun", "--show-sdk-path"], text=True).strip()+ resources.update(files(Path(sdk)))+ return {"schema": 1, "tasks": [{"name": "graff-" + target, "cwd": str(ROOT),+ "command": command, "inputs": sorted(inputs), "outputs": [str(output)],+ "tool_resources": sorted(resources)}]}, output+++def environment(cache):+ # Run IDs, CI tokens and incidental shell variables must neither reach the+ # compiler nor perturb its key. Every retained value is still keyed by Nano.+ return {"PATH": os.defpath, "HOME": str(Path.home()), "LANG": "C", "LC_ALL": "C",+ "TZ": "UTC", "NANOCOMPILE_DIR": str(cache),+ "ZIG_GLOBAL_CACHE_DIR": str(ROOT / ".zig-global-cache"),+ "ZIG_LOCAL_PKG_DIR": str(ROOT / "zig-pkg")}+++def main():+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument("--target", required=True, choices=TARGETS)+ parser.add_argument("--version", required=True)+ parser.add_argument("--telemetry-endpoint")+ parser.add_argument("--nanocompile", default=os.environ.get("NANOCOMPILE_EXE"))+ parser.add_argument("--verify-restore", action="store_true",+ help="remove the built output and prove a byte-identical cache hit")+ args = parser.parse_args()+ zig = Path(shutil.which("zig") or "zig").resolve()+ cache = Path(os.environ.get("NANOCOMPILE_DIR", ROOT / ".nanocompile-cache")).resolve()+ env = environment(cache)+ subprocess.run([str(zig), "build", "--fetch=all"], cwd=ROOT, env=env, check=True)+ spec, output = contract(args.target, args.version, zig, args.telemetry_endpoint)+ if not args.nanocompile:+ if args.verify_restore:+ parser.error("--verify-restore requires --nanocompile or NANOCOMPILE_EXE")+ return subprocess.call(spec["tasks"][0]["command"], cwd=ROOT, env=env)+ binary = str(Path(args.nanocompile).resolve())+ spec_path = ROOT / ".zig-cache" / ("nanocompile-" + args.target + ".json")+ spec_path.parent.mkdir(parents=True, exist_ok=True)+ spec_path.write_text(json.dumps(spec, sort_keys=True) + "\n")+ command = [binary, "task", str(spec_path)]+ subprocess.run(command, cwd=ROOT, env=env, check=True)+ if args.verify_restore:+ digest = hashlib.sha256(output.read_bytes()).hexdigest()+ events = cache / "events"+ offset = events.stat().st_size if events.exists() else 0+ output.unlink()+ subprocess.run(command, cwd=ROOT, env=env, check=True)+ with events.open("rb") as source:+ source.seek(offset)+ if b"task_hit\n" not in source.read():+ raise RuntimeError("nanocompile did not report a task cache hit")+ if hashlib.sha256(output.read_bytes()).hexdigest() != digest:+ raise RuntimeError("nanocompile restored different artifact bytes")+ print("Verified byte-identical nanocompile restore:", args.target)+ return 0+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/src/main.zig b/src/main.zigindex 3494cabe..a4f4c0db 100644--- a/src/main.zig+++ b/src/main.zig@@ -560,7 +560,7 @@ test { // ── Unit tests (`zig build test`): pull in tests from imported modu_ = .{ @import("beta_feed.zig"), @import("jev_tool.zig"), @import("jev_model_scope.zig"), @import("jev_provider_switch_tests.zig"), @import("jev_effort_state.zig"), @import("gemini_turns.zig"), @import("gemini_turns_tests.zig") };_ = .{ @import("mcp_apps.zig"), @import("html_view.zig"), @import("usage_trace.zig"), @import("providers_confirmation_tests.zig"), @import("repl_model_confirmation_tests.zig"), @import("repl_model_pick_tests.zig"), @import("engine_sink_citation_tests.zig"), @import("cite_markup_stream_tests.zig"), @import("oneshot_citation_tests.zig"), @import("acp_permission.zig"), @import("acp_usage.zig") };_ = .{ @import("mcp_server_tests.zig"), @import("main_test.zig"), @import("artifact_claim_command.zig"), @import("cli_path_hint.zig"), @import("run_budget.zig") };- _ = .{ @import("session_catalog.zig"), @import("session_prompt.zig"), @import("session_discovery.zig"), @import("session_workspaces.zig"), @import("commands_resume.zig"), @import("peer_live.zig"), @import("presence_tests.zig"), @import("mcp_rpc_tests.zig") };+ _ = .{ @import("session_catalog.zig"), @import("session_size_tests.zig"), @import("session_prompt.zig"), @import("session_discovery.zig"), @import("session_workspaces.zig"), @import("commands_resume.zig"), @import("peer_live.zig"), @import("presence_tests.zig"), @import("mcp_rpc_tests.zig") };_ = .{ @import("prompt_astra.zig"), @import("prompt_guidance.zig"), @import("oauth_chatgpt.zig"), @import("chatgpt_reauth.zig"), @import("oauth_anthropic.zig"), @import("anthropic_oauth_wire.zig"), @import("anthropic_login_tests.zig") };_ = .{ @import("agent_empty_completion.zig"), @import("agent_length_cutoff.zig"), @import("agent_model_loop.zig"), @import("publication_policy_tests.zig"), @import("jobs_completion_tests.zig"), @import("headless_result.zig"), @import("oneshot.zig"), @import("agent_length.zig"), @import("agent_length_tests.zig") };_ = .{ @import("provider_routing_tests.zig"), @import("codegraff_messages_tests.zig"), @import("tool_result_empty_tests.zig"), @import("history_wire.zig"), @import("path_lookup.zig"), @import("agents_prepare.zig"), @import("catalog_price.zig"), @import("readline_paste_number_tests.zig"), @import("test_hooks.zig"), @import("peer_wake_loop.zig") };