Skip to content

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.md
index 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 starts
that have finished (ADR 0035, 0221), and the catalog rebuilds when one
joined.
-- 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 servers
the client named: enough for one restored from the tool cache, never a
real handshake.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 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.py
new file mode 100644
index 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.zig
index 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.zig
index 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.zig
index 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.zig
index 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 connecti
busy.store(true, .release);
_ = boot.joinPending(&reg);
}
+
+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(&reg, 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(&reg, 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.zig
index 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.process
return 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.zig
index 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));
}