Skip to content

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.zig
index 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.py
new file mode 100644
index 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.py
index 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 ScriptedModel
class 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.zig
index 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.zig
index 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.zig
index 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 o
var 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);