examples: rewrite clients around v0.2.0 ops (delete, tournament, MCP)

The three clients used to be near-duplicate 'hand-rolled branch loop' demos
hitting only head/exec/checkout. Each now shows a distinct v0.2.0 pattern:

- branch_explore.py (socket): kept the manual exploration loop and added a
  'delete' pass that prunes the losing branches from the DAG.
- goclient/main.go (socket): rewritten around the high-level 'tournament' op
  — one round-trip, the daemon runs the candidates in parallel workspaces.
  Same 'delete' pruning at the end.
- mcp_client.py (NEW): drives 'agentenv mcp' over JSON-RPC stdio from any
  language, no Claude Code needed — calls agentenv__log, __branches,
  __delete. Shows the MCP surface that powers self-rollback is portable.

Removed Client.java — it added nothing the other two socket clients didn't
already cover, and three near-identical socket demos was just noise.
examples/README updated to reflect the new lineup.

Author: css521

.gitignore

@@ -37,3 +37,7 @@ coverage.txt
 
 # Recording tool binaries (fetched via scripts/fetch-recording-tools.sh)
 /scripts/.recorder-bin/
+
+# Python
+__pycache__/
+*.pyc

examples/Client.java

@@ -46,15 +46,14 @@ Error frames have `{"error":"…"}` instead of `{"ok":true,…}`. Streaming ops
 
 ## Clients (all stdlib, no dependencies)
 
-| File | Language | Run |
-|------|----------|-----|
-| `branch_explore.py` | Python | `python3 branch_explore.py <sock>` |
-| `goclient/main.go`  | Go      | `go run goclient/main.go <sock>` |
-| `Client.java`       | Java 16+| `javac Client.java -d /tmp && java -cp /tmp Client <sock>` |
-
-Each forks the environment from one base, tries three candidate environments in
-parallel DAG branches (each in its own isolated workspace), and keeps the one
-that passes the test — purely over the socket.
+Each demonstrates a distinct v0.2.0 pattern, so they're complements rather than
+translations of each other.
+
+| File | Driver | Pattern |
+|------|--------|---------|
+| `branch_explore.py` | Socket (NDJSON) | Hand-rolled exploration: fork base → try 3 candidates → keep winner → **`delete` the losing branches** |
+| `goclient/main.go`  | Socket (NDJSON) | High-level `tournament` op: one round-trip, daemon runs the candidates in parallel workspaces; then `delete` the losers |
+| `mcp_client.py`     | MCP (JSON-RPC over stdio) | Drive `agentenv mcp` from any language (no Claude Code needed); calls `agentenv__log` / `__branches` / `__delete` |
 
 ## Simplest driver: the CLI
 

examples/README.md

@@ -65,6 +65,11 @@ def head(self):
     def checkout(self, node):
         return self.call(op="checkout", node=node)["head"]
 
+    def delete(self, node):
+        """Remove a node from the DAG (children re-parent). Used to prune
+        dead-end exploration branches once we know they lost."""
+        return self.call(op="delete", node=node)
+
 
 def main():
     sock = sys.argv[1] if len(sys.argv) > 1 else "/agentfs/agentenv.sock"
@@ -93,13 +98,20 @@ def main():
             winner = name
     print("winner:", winner)
 
-    # Keep the winner; the other branches remain in history but are not HEAD.
+    # Keep the winner; PRUNE the losing branches with `delete` (v0.2.0) so the
+    # DAG doesn't keep dead-end snapshots forever. Children of a deleted node
+    # re-parent to its parent — harmless here because the losers are leaves.
     env.checkout(tips[winner])
+    for name, tip in tips.items():
+        if name != winner:
+            env.delete(tip)
+            print(f"  pruned dead-end {name} (node {tip})")
+
     have = env.exec("command -v jq && (command -v tree || echo no-tree) && (command -v figlet || echo no-figlet)")
     print("final env:\n" + have["stdout"].rstrip())
 
     if winner == "B":
-        print("PASS: agent explored 3 environments over the socket and kept the winner")
+        print("PASS: agent explored 3 environments, kept the winner, pruned the losers")
     else:
         print("FAIL: unexpected winner", winner)
         sys.exit(1)

examples/branch_explore.py

@@ -1,7 +1,11 @@
 //go:build ignore
 
-// A Go client for the agentenv JSON socket API — same branch-exploration as the
-// Python example, showing the protocol is language-neutral (stdlib only).
+// A Go client for agentenv that drives the high-level `tournament` op — the
+// daemon forks N parallel branches from a base, runs each candidate plus a test
+// command, and tells you which branch passed first. Compared to the manual
+// loop in ../branch_explore.py (head → checkout → exec → check, repeat), it's
+// one round-trip and the parallelism happens inside agentenv (true parallel
+// workspaces, not serial like a hand-rolled loop).
 //
 // Run: go run examples/goclient/main.go /agentfs/agentenv.sock
 package main
@@ -14,79 +18,82 @@ import (
 	"os"
 )
 
-type resp struct {
-	OK     bool   `json:"ok"`
-	Error  string `json:"error"`
-	Exit   *int   `json:"exit"`
-	Stdout string `json:"stdout"`
-	Head   string `json:"head"`
-	Node   string `json:"node"`
-}
-
-type client struct {
-	conn net.Conn
-	r    *bufio.Reader
+type branch struct {
+	Name     string `json:"name"`
+	Cmd      string `json:"cmd"`
+	Node     string `json:"node"`
+	TestExit int    `json:"test_exit"`
 }
 
-func dial(sock string) *client {
-	c, err := net.Dial("unix", sock)
-	if err != nil {
-		panic(err)
-	}
-	return &client{conn: c, r: bufio.NewReader(c)}
+type resp struct {
+	OK         bool     `json:"ok"`
+	Error      string   `json:"error"`
+	Head       string   `json:"head"`
+	Branches   []branch `json:"branches"`
+	Winner     string   `json:"winner"`
+	WinnerNode string   `json:"winner_node"`
 }
 
-// call sends one request and returns the TERMINAL frame. For "exec", agentenv
-// streams stdout/stderr frames first; we drain them until we see a frame with
-// "ok":true or "error". Other ops return one frame, so the loop exits after one
-// iteration.
-func (c *client) call(req map[string]any) resp {
+// call sends one request and returns the terminal frame. The tournament op is
+// single-frame; streaming ops (exec) would need draining first.
+func call(c net.Conn, r *bufio.Reader, req map[string]any) resp {
 	b, _ := json.Marshal(req)
-	c.conn.Write(append(b, '\n'))
-	for {
-		line, err := c.r.ReadBytes('\n')
-		if err != nil {
-			panic(err)
-		}
-		var out resp
-		json.Unmarshal(line, &out)
-		if out.Error != "" {
-			panic("api error: " + out.Error)
-		}
-		if out.OK {
-			return out
-		}
-		// streaming output frame: drop on the floor in this minimal example
-		// (a real client would print or buffer it).
+	c.Write(append(b, '\n'))
+	line, _ := r.ReadBytes('\n')
+	var out resp
+	json.Unmarshal(line, &out)
+	if out.Error != "" {
+		panic("api error: " + out.Error)
 	}
+	return out
 }
 
 func main() {
 	sock := "/agentfs/agentenv.sock"
 	if len(os.Args) > 1 {
 		sock = os.Args[1]
 	}
-	c := dial(sock)
+	c, err := net.Dial("unix", sock)
+	if err != nil {
+		panic(err)
+	}
+	defer c.Close()
+	r := bufio.NewReader(c)
 
-	base := c.call(map[string]any{"op": "head"}).Head
-	fmt.Println("base:", base)
+	apt := "apt-get -o APT::Sandbox::User=root install -y -qq"
+	req := map[string]any{
+		"op":   "tournament",
+		"base": "HEAD",
+		"test": "command -v jq",
+		"candidates": []map[string]string{
+			{"name": "A", "cmd": apt + " tree"},
+			{"name": "B", "cmd": apt + " jq"},
+			{"name": "C", "cmd": apt + " figlet"},
+		},
+	}
+	out := call(c, r, req)
 
-	apt := "apt-get -o APT::Sandbox::User=root install -y -qq "
-	tips := map[string]string{}
-	for _, pkg := range []string{"tree", "jq", "figlet"} {
-		c.call(map[string]any{"op": "checkout", "node": base})
-		c.call(map[string]any{"op": "exec", "cmd": apt + pkg})
-		tips[pkg] = c.call(map[string]any{"op": "head"}).Head
-		fmt.Printf("  explored %s -> %s\n", pkg, tips[pkg])
+	fmt.Println("tournament results:")
+	for _, b := range out.Branches {
+		verdict := fmt.Sprintf("exit %d", b.TestExit)
+		if b.TestExit == 0 {
+			verdict = "PASS"
+		}
+		fmt.Printf("  %s  %s  %s\n", b.Name, b.Node, verdict)
+	}
+	if out.Winner == "" {
+		fmt.Println("no candidate passed the test")
+		os.Exit(1)
 	}
+	fmt.Printf("winner: %s (node %s) — HEAD now %s\n", out.Winner, out.WinnerNode, out.Head)
 
-	winner := ""
-	for pkg, tip := range tips {
-		c.call(map[string]any{"op": "checkout", "node": tip})
-		if *c.call(map[string]any{"op": "exec", "cmd": "command -v jq >/dev/null"}).Exit == 0 {
-			winner = pkg
+	// Optional clean-up: prune the losing branches with the v0.2.0 `delete` op.
+	// Children re-parent to the deleted node's parent; harmless here (losers
+	// are leaves) and keeps the DAG free of dead-end snapshots.
+	for _, b := range out.Branches {
+		if b.Name != out.Winner {
+			call(c, r, map[string]any{"op": "delete", "node": b.Node})
+			fmt.Printf("  pruned %s (node %s)\n", b.Name, b.Node)
 		}
 	}
-	fmt.Println("winner:", winner)
-	c.call(map[string]any{"op": "checkout", "node": tips[winner]})
 }

examples/goclient/main.go

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""Drive `agentenv mcp` as a generic MCP client (no Claude Code needed).
+
+The MCP server (added in v0.1.0) is what lets Claude Code roll back its own
+environment via the agentenv__checkout / agentenv__delete tools. This file
+shows the same surface is reachable from any language that can fork a process
+and exchange newline-delimited JSON-RPC over stdio — useful as a smoke test, a
+CI integration, or the foundation for another agent harness.
+
+Walks through every v0.2.0 tool: log, head, branches, show, diff, checkout,
+delete (the new one — prunes a node from the DAG). Requires `agentenv mcp` on
+PATH and a running daemon (or pass --socket to a known control socket).
+
+  python3 mcp_client.py [--socket /var/lib/agentenv/agentenv.sock]
+"""
+import json
+import os
+import subprocess
+import sys
+
+
+class MCP:
+    """Minimal MCP client: subprocess agentenv mcp, framed JSON-RPC on stdio."""
+
+    def __init__(self, socket=None):
+        env = os.environ.copy()
+        if socket:
+            env["AGENTENV_SOCKET"] = socket
+        self.p = subprocess.Popen(
+            ["agentenv", "mcp"],
+            stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+            env=env, text=True, bufsize=1,
+        )
+        self.id = 0
+        self._req("initialize", {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {},
+            "clientInfo": {"name": "mcp-client-py", "version": "0"},
+        })
+        # An MCP host normally sends "initialized" as a notification; the
+        # agentenv server tolerates skipping it for one-shot drivers like this.
+
+    def _req(self, method, params):
+        self.id += 1
+        self.p.stdin.write(json.dumps({
+            "jsonrpc": "2.0", "id": self.id, "method": method, "params": params,
+        }) + "\n")
+        self.p.stdin.flush()
+        # Drain frames until we see our own id (server may emit notifications).
+        while True:
+            line = self.p.stdout.readline()
+            if not line:
+                raise RuntimeError("mcp server closed stdout: " + self.p.stderr.read())
+            msg = json.loads(line)
+            if msg.get("id") == self.id:
+                if "error" in msg:
+                    raise RuntimeError(f"{method}: {msg['error']}")
+                return msg["result"]
+
+    def tool(self, name, **args):
+        """Invoke an agentenv__* MCP tool, return the joined text content."""
+        r = self._req("tools/call", {"name": name, "arguments": args})
+        if r.get("isError"):
+            raise RuntimeError(f"{name} returned isError: {r}")
+        return "".join(c.get("text", "") for c in r.get("content", []))
+
+    def close(self):
+        try:
+            self.p.stdin.close()
+        finally:
+            self.p.wait(timeout=5)
+
+
+def main():
+    socket = None
+    if "--socket" in sys.argv:
+        socket = sys.argv[sys.argv.index("--socket") + 1]
+    mcp = MCP(socket=socket)
+    try:
+        print("HEAD:", mcp.tool("agentenv__head").strip())
+        print("--- log ---")
+        log = mcp.tool("agentenv__log")
+        print(log.rstrip())
+
+        # Pick any non-HEAD, non-root leaf node to prune as a demo. Parsing the
+        # log text is brittle (it's human-readable) — a real driver would call
+        # agentenv__branches and pick from there.
+        leaves = [
+            line.split()[0] for line in mcp.tool("agentenv__branches").splitlines()
+            if line.strip() and "init from" not in line and "<- HEAD" not in line
+        ]
+        if leaves:
+            target = leaves[0]
+            print(f"--- delete leaf {target} (v0.2.0 op) ---")
+            print(mcp.tool("agentenv__delete", node=target).rstrip())
+            print("--- log after delete ---")
+            print(mcp.tool("agentenv__log").rstrip())
+        else:
+            print("(no non-HEAD leaves to prune — skipping delete demo)")
+    finally:
+        mcp.close()
+
+
+if __name__ == "__main__":
+    main()