graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
Quiet terminal startup and expose live thinking controls
Rach Pradhan9461d7799aba
diff --git a/docs/adr/0230-mcp-connects-in-the-background.md b/docs/adr/0230-mcp-connects-in-the-background.mdindex bfa5e370..a2fc8df9 100644--- a/docs/adr/0230-mcp-connects-in-the-background.md+++ b/docs/adr/0230-mcp-connects-in-the-background.md@@ -23,12 +23,16 @@ ahead without a server that is not ready, and reports each server's startup.- No model request waits for a handshake. Each request merges the startsthat have finished (ADR 0035, 0221), and the catalog rebuilds when onejoined.-- The root request reports what changed: "MCP still connecting — native- tools this turn" on the first request that goes out while servers connect,- then "mcp: NAME connected (N tool(s))" or "mcp: NAME did not connect" when- a start finishes. The registry queues the notices under its lock; the root- agent's request emits them through the agent's own sink, which is what the- TUI shows.+- The root request drains connection receipts after each merge. Normal+ interactive sessions keep these diagnostics quiet, avoiding startup chatter+ interleaved with the prompt. `GRAFF_REPL_DEBUG=1` exposes "MCP still+ connecting — native tools this turn", followed by each server's connection+ result. The registry's existing diagnostic switch gates emission, not+ connection, catalog updates, consent, or the explicit `/mcp` status view.+ Companion auto-connect receipts and legacy-listener startup probes use the+ same opt-in; `graff servers` remains available and no ownership or stop+ authority is inferred from a marker. Boot timing remains in the trace;+ `GRAFF_BOOT_DEBUG=1` opts into phase lines on stderr, even for slow phases.- ACP `session/new` and `session/load` wait at most 250 ms for the serversthe client named: enough for one restored from the tool cache, never areal handshake.diff --git a/docs/adr/README.md b/docs/adr/README.mdindex f743114e..e44eafad 100644--- a/docs/adr/README.md+++ b/docs/adr/README.md@@ -256,7 +256,7 @@ record only when you need the evidence or the edge cases.| [0227](0227-children-inherit-the-roots-loaded-mcp-tools.md) | A spawned child's catalog gains the MCP tools its root loaded, with full schemas (`worker_mcp.inherit` into `Agent.worker_tools`, served first by `toolsJson`). Unloaded tools stay out; children still have no load tool. || [0228](0228-read-only-child-calls-declared-read-only-mcp-tools.md) | An MCP tool is a read when its server declares `readOnlyHint: true` (`mcp.Tool.read_only`). A read-only (informational) child may call those and inherits only those from its root; undeclared MCP tools stay refused. || [0229](0229-every-chatgpt-login-is-chatgpt-new.md) | The Codex client's login no longer works, so every ChatGPT login name (`chatgpt`, `codex`, `openai`, `gpt`, `oai`) and the model picker run the `chatgpt-new` sign-in, and `chatgpt-new` precedes `codex` in the provider table. The `codex` provider stays for an existing Codex CLI `auth.json`. Replaces ADR 0221's "Codex first". |-| [0230](0230-mcp-connects-in-the-background.md) | Every session but `--json` connects MCP servers in the background (interactive after consent, `--yolo`, `-p`, ACP); no request waits for a handshake, finished starts join the next request, and the root request says which server connected or did not. ACP `session/new` waits at most 250 ms; `/mcp` lists without waiting. |+| [0230](0230-mcp-connects-in-the-background.md) | Every session but `--json` connects MCP servers in the background (interactive after consent, `--yolo`, `-p`, ACP); no request waits for a handshake, finished starts join the next request, and debug diagnostics report connection results without normal startup chatter. ACP `session/new` waits at most 250 ms; `/mcp` lists without waiting. || [0231](0231-no-round-trip-the-model-does-not-need.md) | No call the task did not ask for: a named small MCP server (and subagents, when asked for) loads with the first request, with the slim-shape note; `write_file` refuses to replace an unread file unless `replace: true` and reports created/replaced and JSON validity; inherited child MCP tools are never deferred; a piped bracketed paste is one prompt; unwatched (`-p`, piped) sessions get no `ask_user` and no low-effort reasoning summaries. || [0232](0232-sub-agents-at-parity-with-the-codex-route.md) | Sub-agents measured (`subagents` suite and its `subagents-solo` counterfactual, `subagent_split.py`) and brought to parity: `write_file` creates a new file's directory; unwatched sessions get no `todo_write` nudges; `agent_output` takes `ids` and spawn receipts name the running children; a fresh child starts with the user's prompts and its parent's live effort (`/effort` or Jev) unless pinned, and can ask Jev mid-run for its own; a read-only child's shell runs under macOS seatbelt instead of an allowlist; one `subagent` trace line per child; a script that computes a file writes it. || [0233](0233-tool-results-the-model-already-has.md) | No tool result the model already has: interactive roots ignore a model's shell `timeout` (the 15s park of ADR 0154 stands) and unattended roots floor it at 5s, so a `timeout: 1000` habit no longer parks quick commands and ends the turn; `todo_write` answers the model with counts and the items graff kept, not the list it just sent (the UI still gets the full list). |diff --git a/scripts/test-repl-thinking.py b/scripts/test-repl-thinking.pynew file mode 100644index 00000000..f98b742b--- /dev/null+++ b/scripts/test-repl-thinking.py@@ -0,0 +1,85 @@+#!/usr/bin/env python3+"""Offline real-terminal check of discoverable live thinking fold controls."""+from pathlib import Path+import json+import os+import sys+import tempfile+import time++ROOT = Path(__file__).resolve().parents[1]+sys.path.insert(0, str(ROOT / "scripts"))+sys.path.insert(0, str(ROOT / "scripts/eval"))+from pty_harness import PtySession+from frontend_model import FrontendModel+++def run(binary):+ deltas = [{"role": "assistant", "reasoning_content": "Sample work.\n"}]+ deltas.extend({"reasoning_content": "."} for _ in range(120))+ deltas.append({"content": "THINKING_DEMO_COMPLETE"})+ requests_dir = tempfile.TemporaryDirectory(prefix="graff-thinking-requests-")+ model = FrontendModel([{"stream_deltas": deltas, "finish": "stop"}],+ Path(requests_dir.name) / "requests.json")+ model.after_stream_delta = lambda _: time.sleep(0.04)+ port = model.start(0)+ try:+ with tempfile.TemporaryDirectory(prefix="graff-thinking-") as temporary:+ base = Path(temporary)+ home = base / "home"+ work = base / "workspace"+ (home / ".harness").mkdir(parents=True)+ work.mkdir()+ (home / ".harness/settings.json").write_text(json.dumps({+ "ai_title": False, "skills": {"codedbpro": False},+ }))+ config = home / "empty-mcp.json"+ config.write_text('{"mcpServers":{}}')+ env = {+ "HOME": str(home), "AI_GATEWAY_API_KEY": "local-fixture",+ "GRAFF_VERCEL_URL": f"http://127.0.0.1:{port}/v1/chat/completions",+ "GRAFF_FLEET": "off", "GRAFF_LEARN_AUTO": "off",+ "GRAFF_MCP_CONFIG": str(config), "GRAFF_NO_TELEMETRY": "1",+ "GRAFF_NO_SMOLIFY": "1", "GRAFF_BEHAVIOR_UPLOAD": "off",+ "NO_PROXY": "*", "no_proxy": "*",+ }+ env.update({key: "" for key in (+ "HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY",+ "http_proxy", "https_proxy", "all_proxy",+ )})+ unset = tuple(key for key in os.environ if key not in env and (+ key.startswith(("GRAFF_", "HARNESS_")) or+ any(part in key.upper() for part in ("API_KEY", "ACCESS_TOKEN", "AUTH_TOKEN"))+ )) + ("CODEX_HOME", "NO_COLOR")+ with PtySession(str(binary), ["--model", "vercel", "--old", "--yolo", "--no-telemetry"],+ cwd=str(work), env=env, unset_env=unset,+ color=True, timeout=15, rows=30, cols=80) as session:+ session.wait_for_prompt()+ for diagnostic in ("possible pre-registry listener", "[boot +", "companion:"):+ assert diagnostic not in session.text, "normal startup exposed diagnostics: " + diagnostic+ cursor = len(session.raw)+ session.send_line("/thinking on")+ session.wait_for_prompt(start=cursor)+ cursor = len(session.raw)+ session.send_line("Reply briefly to this sample request.")+ session.wait_for_literal("Ctrl+T collapse", start=cursor)+ cursor = len(session.raw)+ session.send_text("\x14")+ session.wait_for_literal("Ctrl+T expand", start=cursor)+ cursor = len(session.raw)+ session.send_text("\x14")+ session.wait_for_literal("Ctrl+T collapse", start=cursor)+ session.wait_for_literal("THINKING_DEMO_COMPLETE", start=cursor)+ session.wait_for_prompt(start=cursor)+ session.send_text("\x04")+ result = session.read_until_exit(5)+ assert not result.timed_out and result.exit_code == 0, result.text+ assert len(model.requests) == 1, "unexpected extra fixture requests"+ print("PASS: quiet startup; visible Ctrl+T collapse/expand; live replay; clean exit")+ finally:+ model.stop()+ requests_dir.cleanup()+++if __name__ == "__main__":+ run(Path(sys.argv[1] if len(sys.argv) > 1 else ROOT / "zig-out/bin/graff").resolve())diff --git a/src/agent_stream_render.zig b/src/agent_stream_render.zigindex 0cfeb7c4..27fb56e3 100644--- a/src/agent_stream_render.zig+++ b/src/agent_stream_render.zig@@ -110,6 +110,16 @@ pub fn spinnerStop(self: *Agent) void {}}+fn writeThinkingHeader(self: *Agent) !void {+ const w = self.out orelse return;+ const label = if (self.thinking_folded) "▶ Thinking · Ctrl+T expand" else "▼ Thinking · Ctrl+T collapse";+ try w.print("{s}{s}{s}\n{s}", .{ style.muted, label, style.reset, style.muted });+ self.thinking_rows = 0;+ self.thinking_col = 0;+ advanceThinkingRows(&self.thinking_rows, &self.thinking_col, termCols(), label);+ advanceThinkingRows(&self.thinking_rows, &self.thinking_col, termCols(), "\n");+}+/// Stream a chunk of the model's reasoning into a live, dimmed "Thinking"/// block in the terminal, opening the block (and handing the line off from/// the spinner) on the first chunk. Gated by /thinking; when off the block is@@ -125,12 +135,10 @@ pub fn streamThinking(self: *Agent, chunk: []const u8) void {if (visible.len == 0) return;if (!self.thinking_open) {self.spinnerStop();- w.print("{s}▼ Thinking{s}\n{s}", .{ style.dim, style.reset, style.dim }) catch return;+ self.thinking_overflow = false;+ writeThinkingHeader(self) catch return;self.thinking_open = true;main_mod.g_thinking_open = true;- self.thinking_rows = 1; // the header newline already moved us down one line- self.thinking_col = 0;- self.thinking_overflow = false;// The block owns every row below this one and collapses them by cursor// math — a child's tick printed inside it would be erased with the// block (or shift the erase onto real output). Hold until it closes.@@ -178,18 +186,13 @@ pub fn closeThinkingBlock(self: *Agent) void {pub fn toggleThinkingFold(self: *Agent) void {if (!self.thinking_open or self.thinking_overflow or !main_mod.use_color) return;const w = self.out orelse return;+ w.print("\x1b[{d}F\x1b[0J", .{self.thinking_rows}) catch return;+ self.thinking_folded = !self.thinking_folded;+ writeThinkingHeader(self) catch return;if (!self.thinking_folded) {- w.print("\x1b[{d}F\x1b[0J{s}▶ Thinking (folded · ^T){s}\n", .{ self.thinking_rows, style.dim, style.reset }) catch return;- self.thinking_folded = true;- self.thinking_rows = 1;- self.thinking_col = 0;- } else {- w.print("\x1b[1F\x1b[0J{s}▼ Thinking{s}\n{s}", .{ style.dim, style.reset, style.dim }) catch return;- self.thinking_folded = false;- self.thinking_rows = 1;- self.thinking_col = 0;w.writeAll(self.thinking_text.items) catch return;advanceThinkingRows(&self.thinking_rows, &self.thinking_col, termCols(), self.thinking_text.items);+ if (self.thinking_rows + 1 >= termRows()) self.thinking_overflow = true;}w.flush() catch return;}diff --git a/src/companion_boot.zig b/src/companion_boot.zigindex 28082af5..32fff094 100644--- a/src/companion_boot.zig+++ b/src/companion_boot.zig@@ -60,9 +60,8 @@ fn interactive(flags: args.Flags, json_mode: bool) bool {/// every other path still `addServer`s on this thread.pub fn connectCompanion(io: Io, arena: Allocator, registry: *mcp.Registry, flags: args.Flags, out: *Io.Writer, json_mode: bool, environ_map: anytype) !void {const sink = engine_sink.writerSink(out);- const speak = interactive(flags, json_mode);+ const speak = interactive(flags, json_mode) and environ_map.get("GRAFF_REPL_DEBUG") != null;const background = deferCompanion(flags, json_mode);- _ = environ_map;connect: {for (skills.companion_servers) |c| {if (mcp_boot.alreadyStarting(registry, c.server)) break :connect;diff --git a/src/main_test.zig b/src/main_test.zigindex 08713a79..5ef7f4e3 100644--- a/src/main_test.zig+++ b/src/main_test.zig@@ -467,8 +467,12 @@ test "citation annotations stay out of reasoning and fold replay" {}try std.testing.expectEqualStrings(citation_clean, a.thinking_text.items);sink.emit(std.testing.io, .thinking_fold_toggle);+ try std.testing.expect(a.thinking_folded);sink.emit(std.testing.io, .thinking_fold_toggle);+ try std.testing.expect(!a.thinking_folded);const output = aw.writer.buffered();+ try std.testing.expect(std.mem.indexOf(u8, output, "Ctrl+T collapse") != null);+ try std.testing.expect(std.mem.indexOf(u8, output, "Ctrl+T expand") != null);try std.testing.expect(!@import("cite_markup.zig").contains(output));try std.testing.expect(std.mem.indexOf(u8, output, "turn0") == null);try std.testing.expect(std.mem.indexOf(u8, output, citation_clean) != null);diff --git a/src/mcp_connect_notice.zig b/src/mcp_connect_notice.zigindex 5c6bad3f..64bc2277 100644--- a/src/mcp_connect_notice.zig+++ b/src/mcp_connect_notice.zig@@ -1,9 +1,8 @@//! What a background MCP connect tells the session (ADR 0230). Handshakes no-//! longer hold up the start, so the session says when the first request goes-//! out while servers are still connecting, and the request that merges a-//! finished one names it: connected with its tool count, or did not connect.-//! The registry queues them under its lock; the root agent's request drains-//! them through the agent's own sink (`drain`), which is what a TUI shows.+//! longer hold up the start. The registry queues connection receipts under+//! its lock; the root request drains them through its sink only when startup+//! diagnostics are enabled. Normal sessions stay quiet; `/mcp` still exposes+//! connection state without waiting for a handshake.const std = @import("std");const Io = std.Io;@@ -62,7 +61,7 @@ pub fn drain(reg: *mcp.Registry, sink: EngineSink, io: Io) void {const queued = reg.connect_notices;reg.connect_notices = .{};reg.mutex.unlock(reg.io);- queued.emitTo(sink, io);+ if (reg.show_diagnostics) queued.emitTo(sink, io);}/// Servers whose start is still running, for `/mcp`. Call after `joinReady`@@ -109,3 +108,39 @@ test "a finished start is named once it merges; an unfinished one stays connectibusy.store(true, .release);_ = boot.joinPending(®);}++test "background MCP notices require diagnostics and drain only once" {+ const Capture = struct {+ count: usize = 0,+ failed: bool = false,+ fn emit(ctx: *anyopaque, event: @import("engine_sink.zig").Stamped) void {+ const self: *@This() = @ptrCast(@alignCast(ctx));+ switch (event.event) {+ .session_notice => |n| {+ self.count += 1;+ if (std.mem.indexOf(u8, n.text, "did not connect") != null) self.failed = true;+ },+ else => {},+ }+ }+ const vt: @import("engine_sink.zig").VTable = .{ .emit = emit, .durable = false };+ };+ for ([_]bool{ false, true }) |debug| {+ var reg = mcp.Registry.empty(std.testing.allocator, std.testing.io);+ defer reg.deinit();+ reg.show_diagnostics = debug;+ reg.connect_notices.still_connecting = true;+ reg.connect_notices.n = 2;+ reg.connect_notices.names[0] = "ready";+ reg.connect_notices.tools[0] = 3;+ reg.connect_notices.names[1] = "unavailable";+ reg.connect_notices.tools[1] = null;+ var capture: Capture = .{};+ const sink: EngineSink = .{ .ctx = &capture, .vt = &Capture.vt };+ drain(®, sink, std.testing.io);+ try std.testing.expectEqual(@as(usize, if (debug) 3 else 0), capture.count);+ try std.testing.expectEqual(debug, capture.failed);+ drain(®, sink, std.testing.io);+ try std.testing.expectEqual(@as(usize, if (debug) 3 else 0), capture.count);+ }+}diff --git a/src/startup.zig b/src/startup.zigindex 8e63ce82..172ec334 100644--- a/src/startup.zig+++ b/src/startup.zig@@ -557,7 +557,7 @@ pub fn runSubcommand(io: Io, gpa: Allocator, arena: Allocator, init: std.processreturn true;}- if (!main_mod.json_mode and flags.oneshot_prompt == null)+ if (!main_mod.json_mode and flags.oneshot_prompt == null and init.environ_map.get("GRAFF_REPL_DEBUG") != null)@import("server_diagnostics.zig").warnStartup(arena, io);return false;diff --git a/src/startup_timing.zig b/src/startup_timing.zigindex aca0f580..a148e57b 100644--- a/src/startup_timing.zig+++ b/src/startup_timing.zig@@ -53,10 +53,9 @@ pub const Tracker = struct {self.phases_len = 0;}- /// `GRAFF_BOOT_DEBUG` prints every phase. Interactive boots also name- /// anything ≥80ms so a hang after `plugins:` is visible without an env var.- pub fn shouldPrint(debug: bool, phase_ms: i64) bool {- return debug or phase_ms >= 80;+ /// Phase receipts always reach the trace; stderr is an explicit debug view.+ pub fn shouldPrint(debug: bool, _: i64) bool {+ return debug;}fn emit(tracer: *trace.Tracer, phase: Phase) void {@@ -85,9 +84,10 @@ test "startup phases retain order and non-negative deltas before attach" {try std.testing.expect(tracker.phases[1].cumulative_ms >= tracker.phases[0].cumulative_ms);}-test "slow boot phases print without GRAFF_BOOT_DEBUG" {+test "boot phase diagnostics require GRAFF_BOOT_DEBUG even for slow phases" {try std.testing.expect(!Tracker.shouldPrint(false, 0));try std.testing.expect(!Tracker.shouldPrint(false, 79));- try std.testing.expect(Tracker.shouldPrint(false, 80));+ try std.testing.expect(!Tracker.shouldPrint(false, 80));+ try std.testing.expect(!Tracker.shouldPrint(false, 80_000));try std.testing.expect(Tracker.shouldPrint(true, 0));}