graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
Honor positive waits for background agent output
Rach Pradhanddfe3e065d94
diff --git a/build.zig b/build.zigindex 65629a2b..e90eee0c 100644--- a/build.zig+++ b/build.zig@@ -140,6 +140,9 @@ pub fn build(b: *std.Build) void {const acp_effort_test = b.addSystemCommand(&.{ "python3", "scripts/test-acp-effort-config.py" });acp_effort_test.addArtifactArg(exe);test_step.dependOn(&acp_effort_test.step);+ const acp_agent_wait_test = b.addSystemCommand(&.{ "python3", "scripts/test-acp-agent-output-wait.py" });+ acp_agent_wait_test.addArtifactArg(exe);+ test_step.dependOn(&acp_agent_wait_test.step);const workflow_isolation_test = b.addSystemCommand(&.{ "python3", "scripts/test-workflow-isolation.py" });workflow_isolation_test.addArtifactArg(exe);test_step.dependOn(&workflow_isolation_test.step);diff --git a/scripts/test-acp-agent-output-wait.py b/scripts/test-acp-agent-output-wait.pynew file mode 100644index 00000000..7acce5df--- /dev/null+++ b/scripts/test-acp-agent-output-wait.py@@ -0,0 +1,191 @@+#!/usr/bin/env python3+"""Offline ACP regression: a positive agent_output wait consumes one model turn."""+import importlib.util+import json+import re+import sys+import tempfile+import threading+import time+from pathlib import Path++REPO = Path(__file__).resolve().parents[1]+spec = importlib.util.spec_from_file_location('acp_load', REPO / 'scripts/test-acp-session-load.py')+load = importlib.util.module_from_spec(spec)+spec.loader.exec_module(load)+++def tool_names(body):+ return [item.get('function', item).get('name') for item in body.get('tools', [])]+++def wait_for_tool(client, title, timeout=5):+ deadline=time.monotonic()+timeout+ while time.monotonic()<deadline:+ if any(e.get('method')=='session/update' and+ e.get('params',{}).get('update',{}).get('sessionUpdate')=='tool_call' and+ e.get('params',{}).get('update',{}).get('title')==title for e in client.events):+ return+ time.sleep(.01)+ raise AssertionError(f'ACP {title} tool call did not start')+++class DelayedChild(load.ScriptedModel):+ def __init__(self, delay=1.0, wait_ms=600000):+ super().__init__([], exhausted_text='unexpected extra model turn')+ self.delay = delay+ self.wait_ms = wait_ms+ self.wait_requested = threading.Event()+ self.third_root_call = threading.Event()+ self.child_started = threading.Event()+ self.child_finished = threading.Event()+ self.release_child = threading.Event() if delay is None else None+ self.root_calls = 0+ self.child_calls = 0+ self.aux_calls = 0+ self.wait_result = None++ def next_reply(self, body):+ with self._lock:+ self.requests.append(body)+ names=tool_names(body)+ if not names:+ self.aux_calls += 1+ kind, number = 'aux', self.aux_calls+ elif 'subagent' in names:+ self.root_calls += 1+ kind, number = 'root', self.root_calls+ if number >= 3:+ self.third_root_call.set()+ else:+ self.child_calls += 1+ kind, number = 'child', self.child_calls+ if kind == 'child':+ self.child_started.set()+ if self.release_child is not None:+ assert self.release_child.wait(10), 'held child was not released'+ else:+ time.sleep(self.delay)+ self.child_finished.set()+ return {'text': 'child completed the local task'}+ if kind == 'aux':+ return {'text':'Local task'}+ if number == 1:+ return {'tool':'subagent','arguments':{+ 'description':'Check local task','prompt':'Return a short completion report.',+ 'isolation':'shared_cwd','run_in_background':True}}+ if number == 2:+ last = load.tool_text(body)[-1]+ found = re.search(r'\[agent (\d+)', last)+ assert found, 'missing background agent handle'+ self.wait_requested.set()+ return {'tool':'agent_output','arguments':{'id':int(found.group(1)),'wait_ms':self.wait_ms}}+ if number == 3:+ self.wait_result = load.tool_text(body)[-1]+ return {'text':'Parent observed completion.'}+ return {'text':'unexpected extra model turn'}+++def run(binary):+ with tempfile.TemporaryDirectory(prefix='graff-acp-agent-wait-') as tmp:+ work=Path(tmp); home=work/'home'; home.mkdir()+ model=DelayedChild(delay=None); port=model.start(0)+ client=load.Acp(binary,work,home,port,extra_env={'GRAFF_NO_NATIVE_FOLD':'1'},+ extra_args=('--max-model-calls','5','--max-run-tool-calls','8'))+ prompt_result={}+ prompt_thread=None+ try:+ client.request('initialize',{'protocolVersion':1})+ created=client.request('session/new',{'cwd':str(work),'mcpServers':[]})+ sid=created['result']['sessionId']+ def prompt():+ try:+ prompt_result['response']=client.request('session/prompt',{'sessionId':sid,+ 'prompt':[{'type':'text','text':'Delegate once, wait for completion, then finish.'}]},timeout=15)+ except BaseException as exc:+ prompt_result['error']=exc+ prompt_thread=threading.Thread(target=prompt,daemon=True); prompt_thread.start()+ assert model.child_started.wait(5), 'child did not start'+ assert model.wait_requested.wait(5), 'parent did not request agent_output'+ wait_for_tool(client,'agent_output')+ assert not model.child_finished.is_set(), 'child was not held during wait'+ assert not model.third_root_call.wait(.3), 'parent spent an extra model turn before child release'+ model.release_child.set()+ prompt_thread.join(timeout=10)+ assert not prompt_thread.is_alive(), 'ACP prompt did not finish after child release'+ assert 'error' not in prompt_result,prompt_result+ done=prompt_result['response']+ assert done['result']['stopReason']=='end_turn',done+ finally:+ model.release_child.set()+ if prompt_thread: prompt_thread.join(timeout=2)+ client.close(); model.stop()+ assert (model.root_calls,model.child_calls)==(3,1),\+ (model.root_calls,model.child_calls,model.aux_calls,[tool_names(body) for body in model.requests])+ assert model.wait_result and 'completed' in model.wait_result.lower(),model.wait_result+ assert '[agent 1: running]' not in model.wait_result.lower(),model.wait_result+ print('ACP agent_output positive wait returned completed held child; 3 root + 1 child model calls')+++def run_snapshot(binary):+ with tempfile.TemporaryDirectory(prefix='graff-acp-agent-snapshot-') as tmp:+ work=Path(tmp); home=work/'home'; home.mkdir()+ model=DelayedChild(delay=None,wait_ms=0); port=model.start(0)+ client=load.Acp(binary,work,home,port,extra_env={'GRAFF_NO_NATIVE_FOLD':'1'},+ extra_args=('--max-model-calls','5','--max-run-tool-calls','8'))+ try:+ client.request('initialize',{'protocolVersion':1})+ sid=client.request('session/new',{'cwd':str(work),'mcpServers':[]})['result']['sessionId']+ response=client.request('session/prompt',{'sessionId':sid,'prompt':[{'type':'text','text':'Delegate and snapshot.'}]},timeout=10)+ assert response.get('result',{}).get('stopReason')=='end_turn',response+ updates=[e.get('params',{}).get('update',{}) for e in client.events if e.get('method')=='session/update']+ assert any('[agent 1: running]' in json.dumps(u) for u in updates), 'zero-wait lost running snapshot'+ assert model.child_started.is_set() and not model.child_finished.is_set(), 'snapshot waited for child exit'+ finally:+ model.release_child.set()+ client.close(); model.stop()+ print('ACP agent_output zero wait returned running snapshot before held child exited')+++def run_cancel(binary):+ with tempfile.TemporaryDirectory(prefix='graff-acp-agent-cancel-') as tmp:+ work=Path(tmp); home=work/'home'; home.mkdir()+ model=DelayedChild(delay=None); port=model.start(0)+ # Cancelling the client can close its SSE socket while the held child+ # emits its terminal frame; that expected disconnect is not a failure.+ model._server.handle_error=lambda *_: None+ client=load.Acp(binary,work,home,port,extra_env={'GRAFF_NO_NATIVE_FOLD':'1'},+ extra_args=('--max-model-calls','5','--max-run-tool-calls','8'))+ cancel_thread=None+ cancel_errors=[]+ try:+ client.request('initialize',{'protocolVersion':1})+ sid=client.request('session/new',{'cwd':str(work),'mcpServers':[]})['result']['sessionId']+ def cancel():+ try:+ assert model.wait_requested.wait(5), 'agent_output was not requested'+ assert model.child_started.wait(5), 'child was not running'+ wait_for_tool(client,'agent_output')+ time.sleep(.2)+ client.proc.stdin.write((json.dumps({'jsonrpc':'2.0','method':'session/cancel',+ 'params':{'sessionId':sid}})+'\n').encode())+ client.proc.stdin.flush()+ except BaseException as exc:+ cancel_errors.append(exc)+ cancel_thread=threading.Thread(target=cancel,daemon=True); cancel_thread.start()+ response=client.request('session/prompt',{'sessionId':sid,'prompt':[{'type':'text','text':'Delegate then wait.'}]},timeout=10)+ assert response.get('result',{}).get('stopReason')=='cancelled',response+ assert not model.child_finished.is_set(), 'cancel waited for child exit'+ finally:+ if cancel_thread: cancel_thread.join(timeout=2)+ model.release_child.set()+ client.close(); model.stop()+ assert not cancel_errors,cancel_errors+ print('ACP session/cancel interrupted positive wait before held child exited')+++if __name__=='__main__':+ binary=Path(sys.argv[1] if len(sys.argv)>1 else REPO/'zig-out/bin/graff').resolve()+ run(binary)+ run_snapshot(binary)+ run_cancel(binary)diff --git a/scripts/test-acp-session-load.py b/scripts/test-acp-session-load.pyindex 4065bbd0..0cfd5722 100644--- a/scripts/test-acp-session-load.py+++ b/scripts/test-acp-session-load.py@@ -18,15 +18,17 @@ from mock_model import ScriptedModelclass Acp:- def __init__(self, binary, cwd, home, port):+ def __init__(self, binary, cwd, home, port, extra_env=None, extra_args=()):env = {k: v for k, v in os.environ.items() if not k.endswith("_API_KEY") and not k.startswith(("GRAFF_", "HARNESS_"))}env.update(HOME=str(home), AI_GATEWAY_API_KEY="local", GRAFF_FLEET="off",GRAFF_VERCEL_URL=f"http://127.0.0.1:{port}/v1/chat/completions",GRAFF_NO_TELEMETRY="1", GRAFF_NO_SMOLIFY="1",GRAFF_BEHAVIOR_UPLOAD="off", NO_COLOR="1")+ if extra_env:+ env.update(extra_env)self.err = open(cwd / f"acp-{time.time_ns()}.stderr", "w")try:- self.proc = subprocess.Popen([str(binary), "acp", "--yolo", "--old", "--model", "vercel"],+ self.proc = subprocess.Popen([str(binary), "acp", "--yolo", "--old", "--model", "vercel", *extra_args],cwd=cwd, env=env, stdin=subprocess.PIPE, stdout=subprocess.PIPE,stderr=self.err, start_new_session=True)except BaseException:diff --git a/src/schema_agents.zig b/src/schema_agents.zigindex 731f9fda..99d9e268 100644--- a/src/schema_agents.zig+++ b/src/schema_agents.zig@@ -11,7 +11,7 @@ pub const subagent_spec = ToolSpec{pub const agent_output_spec = ToolSpec{.name = "agent_output",- .desc = "Fetch a background subagent's status/result (one started with subagent run_in_background:true). Running: a brief status line. Completed: the full report — the same text a synchronous subagent call would have returned, including any kept-worktree note — plus a usage summary (duration, tool-call count, context tokens, cache-read tokens). Failed: an is_error result explaining why; failures are always reported, never silent. In the interactive REPL this always returns promptly; a running result yields the parent and completion wakes it automatically. Headless callers use wait_ms=0 for a snapshot or wait_ms>0 to block until it finishes (up to 10h). Do not poll. Calling again after completion re-returns the same result — nothing is consumed.",+ .desc = "Fetch a background subagent's status/result (one started with subagent run_in_background:true). Running: a brief status line. Completed: the full report — the same text a synchronous subagent call would have returned, including any kept-worktree note — plus a usage summary (duration, tool-call count, context tokens, cache-read tokens). Failed: an is_error result explaining why; failures are always reported, never silent. wait_ms=0 returns an immediate snapshot; in the prompt-based interactive REPL it yields the parent for an automatic completion wake, while ACP/headless callers remain in the turn. wait_ms>0 waits for completion (up to 10h) on every surface; cancellation interrupts the wait. Do not poll. Calling again after completion re-returns the same result — nothing is consumed.",.schema =\\{"type": "object", "properties": {"id": {"type": "integer", "description": "Agent id returned by subagent with run_in_background:true"}, "wait_ms": {"type": "integer", "description": "0 = snapshot now. >0 = block until the agent finishes (capped at 10 hours). Do not poll every 30s."}}, "required": ["id"]},diff --git a/src/subagent_interactive.zig b/src/subagent_interactive.zigindex 020356bb..f1ef5e87 100644--- a/src/subagent_interactive.zig+++ b/src/subagent_interactive.zig@@ -1,5 +1,6 @@-//! Interactive parents yield after delegation; children own the work until a-//! completion wake or a new user turn. No cancellation signal is involved.+//! Prompt-based interactive parents may yield after delegation and wake on+//! completion. Explicit positive waits instead honor agent_output's joined+//! completion contract, including cancellation.const std = @import("std");const tools = @import("tools.zig");const subagent = @import("subagent.zig");@@ -89,7 +90,11 @@ pub fn rename(io: std.Io, old: []const u8, new: []const u8) void {}pub fn output(ctx: tools.ToolCtx, id: u32, wait_ms: u64) !tools.ToolOutput {- if (!ctx.interactive_children or ctx.from_sub) return subagent.agentOutput(ctx.gpa, ctx.io, id, wait_ms);+ // A positive wait is an explicit completion wait (ADR 0010), including+ // ACP/TUI roots. Only a zero-wait snapshot should park the interactive+ // parent and arrange a later wake; ignoring wait_ms spends model turns+ // polling a still-running child.+ if (!ctx.interactive_children or ctx.from_sub or wait_ms > 0) return subagent.agentOutput(ctx.gpa, ctx.io, id, wait_ms);const result = try subagent.agentOutput(ctx.gpa, ctx.io, id, 0);const registry = &subagent.g_agent_jobs;registry.mutex.lockUncancelable(ctx.io);diff --git a/src/subagent_tests.zig b/src/subagent_tests.zigindex 4393c6d6..76c03e9a 100644--- a/src/subagent_tests.zig+++ b/src/subagent_tests.zig@@ -363,7 +363,7 @@ test "interactive children yield once without cancellation or a model request" {try std.testing.expect(!interactive.yielded);}-test "interactive child output never waits and completion wakes only its owner once" {+test "interactive zero-wait child snapshot and completion wake only its owner once" {const interactive = @import("subagent_interactive.zig");interactive.configure(true);defer interactive.configure(false);@@ -379,7 +379,7 @@ test "interactive child output never waits and completion wakes only its owner ovar label = [_]u8{'x'};var job: subagent.AgentJob = .{ .id = 42, .label = &label, .prompt = &label, .niche = &label, .isolation = .shared_cwd, .isolation_fallback = false, .ctx = ctx, .owner = "owner" };try subagent.g_agent_jobs.list.append(gpa, &job);- const running = try interactive.output(ctx, 42, 1); // used to wait up to 10h+ const running = try interactive.output(ctx, 42, 0);defer gpa.free(running.text);try std.testing.expect(!running.is_error);try std.testing.expect(!job.done);