Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

Align MCP task transport deadlines with bounded execution

justrach09a0a0b9edf9
diff --git a/docs/adr/0290-mcp-task-replies-outlive-child-deadlines.md b/docs/adr/0290-mcp-task-replies-outlive-child-deadlines.md
new file mode 100644
index 00000000..97e7f434
--- /dev/null
+++ b/docs/adr/0290-mcp-task-replies-outlive-child-deadlines.md
@@ -0,0 +1,33 @@
+# 0290. MCP task replies outlive child deadlines
+
+Status: accepted 2026-10-17
+
+## Context
+
+The HTTP MCP client ended every request after 15 seconds. The task server
+allows a child to run for up to 300 seconds, with a separate bounded
+preprocessing step for long context. The client could therefore discard the
+server's timeout result and captured partial output before the child reached
+its own deadline (#1517).
+
+## Decision
+
+For `tools/call` of `run_task` with arguments accepted by the task server's
+validator, derive the HTTP deadline from the child timeout, add the context
+summarization budget only when required, and reserve 15 seconds for process
+cleanup and delivery of the final result. Keep this allowance request-local.
+Discovery, other tools and malformed task arguments retain the ordinary
+HTTP deadline. User cancellation still interrupts the request immediately.
+
+Reuse the server's argument validation and preprocessing limits rather than
+maintaining a second timeout contract in the transport. Do not silently
+replay a timed-out task: it may already have edited files.
+
+## Consequences
+
+A bounded task can return its explicit failure and partial output instead of
+losing the transport first. Unresponsive task endpoints can occupy a request
+for the bounded task allowance; unrelated requests do not inherit it.
+Other MCP hosts still own their deadlines, and must allow the documented
+child, preprocessing and reply budgets. This change does not introduce a
+continuation handle or guarantee recovery after an external host disconnects.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 29c9394a..ba9be0f8 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -304,6 +304,7 @@ record only when you need the evidence or the edge cases.
| [0287](0287-loopback-inference-has-request-local-deadlines.md) | Loopback inference receives request-local default deadlines; explicit limits and remote recovery budgets remain unchanged. |
| [0288](0288-anthropic-native-login-is-source-aware.md) | Native subscription PKCE login is shared across CLI, REPL and ACP; subscription wire compatibility stays credential-source-aware. |
| [0289](0289-mcp-results-preserve-typed-and-display-content.md) | Preserve typed MCP results independently of display content, show resource references without fetching them and answer pings during shared waits. |
+| [0290](0290-mcp-task-replies-outlive-child-deadlines.md) | HTTP task calls wait for validated child and required preprocessing budgets plus reply cleanup; other requests keep their deadlines. |
## When to write one
diff --git a/docs/mcp-server.md b/docs/mcp-server.md
index 3b3f7993..7f47a0bc 100644
--- a/docs/mcp-server.md
+++ b/docs/mcp-server.md
@@ -135,6 +135,14 @@ small explanations, focused reviews, test runs, and narrowly scoped fixes.
summarizer runs on its own single-call budget.
- Root tool calls are capped at 64 per turn.
+When Graff calls this tool over HTTP, its transport waits for the validated
+child budget, any required context summarization, and 15 seconds for cleanup
+and the final partial-output reply. Discovery and unrelated tools retain their
+normal deadlines. Other MCP hosts control their own transport timeouts: allow
+at least the task timeout plus 15 seconds, or plus 75 seconds when context
+exceeds 8 KiB. A shorter host timeout can discard the reply; it does not prove
+the child stopped, and this tool has no continuation handle.
+
`context` carries text only. It cannot set cwd, credentials, model, permission
mode, or any CLI flag — those still come from the server launch.
diff --git a/scripts/test-mcp-streamable-http.py b/scripts/test-mcp-streamable-http.py
index 2de363aa..53f5fd60 100644
--- a/scripts/test-mcp-streamable-http.py
+++ b/scripts/test-mcp-streamable-http.py
@@ -15,8 +15,13 @@ from pathlib import Path
import subprocess
import tempfile
import threading
+import time
+import sys
from typing import Any
+sys.path.insert(0, str(Path(__file__).resolve().parent / "eval"))
+from mock_model import ScriptedModel
+
MODERN_PROTOCOL = "2026-07-28"
RESERVED_META_KEYS = (
@@ -185,15 +190,94 @@ def run(graff: Path) -> None:
thread.join(timeout=5)
+def run_task_deadline(graff: Path) -> None:
+ """A delayed tool failure must arrive intact, after the old 15-second bound."""
+ class TaskFixture(BaseHTTPRequestHandler):
+ calls = 0
+
+ def log_message(self, _format: str, *_args: object) -> None:
+ pass
+
+ def do_POST(self) -> None: # noqa: N802
+ message = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
+ if message["method"] == "tools/list":
+ result = {"tools": [{"name": "run_task", "description": "Run the fixture task.",
+ "inputSchema": {"type": "object", "properties": {
+ "prompt": {"type": "string"}, "timeout_seconds": {"type": "integer"}},
+ "required": ["prompt"]}}]}
+ elif message["method"] == "tools/call":
+ TaskFixture.calls += 1
+ time.sleep(16)
+ result = {"isError": True, "content": [{"type": "text", "text":
+ "MCP_PARTIAL_WORK\n[Task timed out; partial work may remain.]"}],
+ "structuredContent": {"status": "timed_out", "text": "MCP_PARTIAL_WORK"}}
+ else:
+ result = {}
+ if "id" not in message:
+ self.send_response(202)
+ self.send_header("Content-Length", "0")
+ self.end_headers()
+ return
+ body = json.dumps({"jsonrpc": "2.0", "id": message["id"], "result": result}).encode()
+ self.send_response(200)
+ self.send_header("Content-Type", "application/json")
+ self.send_header("Content-Length", str(len(body)))
+ self.end_headers()
+ try:
+ self.wfile.write(body)
+ except BrokenPipeError:
+ pass # The unfixed client closes before the delayed result.
+
+ server = ThreadingHTTPServer(("127.0.0.1", 0), TaskFixture)
+ thread = threading.Thread(target=server.serve_forever, daemon=True)
+ model = ScriptedModel([
+ {"tool": "load_tool_schemas", "arguments": {"server": "fixture"}},
+ {"tool": "mcp__fixture__run_task", "arguments": {
+ "prompt": "Return the fixture result.", "timeout_seconds": 16}},
+ {"text": "MCP_DEADLINE_DONE"},
+ ])
+ thread.start()
+ try:
+ model.start(1234)
+ with tempfile.TemporaryDirectory(prefix="graff-mcp-deadline-") as temp:
+ workspace = Path(temp)
+ (workspace / ".mcp.json").write_text(json.dumps({"mcpServers": {
+ "fixture": {"url": f"http://127.0.0.1:{server.server_port}/mcp"}}}))
+ env = {"PATH": os.environ.get("PATH", ""), "HOME": temp, "USERPROFILE": temp,
+ "LMSTUDIO_API_KEY": "local-fixture", "GRAFF_FLEET": "off",
+ "GRAFF_NO_PLUGINS": "1", "GRAFF_NO_TELEMETRY": "1",
+ "GRAFF_NO_SMOLIFY": "1", "GRAFF_BEHAVIOR_TRACE": "0"}
+ completed = subprocess.run([str(graff), "--json", "--yolo", "--no-resume",
+ "--model", "lmstudio", "--max-model-calls", "5"], cwd=workspace,
+ env=env, input=json.dumps({"type": "user", "text":
+ "Use the fixture run_task once and report its result. No file access is needed."}) + "\n",
+ text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, timeout=45)
+ assert completed.returncode == 0, completed.stderr
+ assert TaskFixture.calls == 1, TaskFixture.calls
+ tool_replies = [message.get("content", "") for request in model.requests
+ for message in request.get("messages", []) if message.get("role") == "tool"]
+ assert any("MCP_PARTIAL_WORK" in text for text in tool_replies), tool_replies
+ assert not any("McpRequestTimedOut" in text for text in tool_replies), tool_replies
+ assert "MCP_DEADLINE_DONE" in completed.stdout, completed.stdout
+ finally:
+ model.stop()
+ server.shutdown()
+ server.server_close()
+ thread.join(timeout=5)
+
+
def main() -> int:
parser = argparse.ArgumentParser()
parser.add_argument("--graff", type=Path, default=Path("zig-out/bin/graff"))
+ parser.add_argument("--only-task-deadline", action="store_true")
args = parser.parse_args()
graff = args.graff.resolve()
if not graff.is_file():
parser.error(f"graff binary not found: {graff}")
- run(graff)
- print("Streamable HTTP MCP E2E passed")
+ if not args.only_task_deadline:
+ run(graff)
+ run_task_deadline(graff)
+ print("Streamable HTTP MCP E2E passed (including delayed task failure with partial output)")
return 0
diff --git a/src/mcp_http.zig b/src/mcp_http.zig
index 28c442e1..416867f1 100644
--- a/src/mcp_http.zig
+++ b/src/mcp_http.zig
@@ -308,7 +308,7 @@ pub const PostOptions = struct {
/// Cancellation unwinds the request, whose errdefer poisons the connection so
/// a timed-out socket is never pooled.
pub fn post(http: *HttpTransport, body: []const u8, meta: RequestMeta, expected_id: ?i64) !?[]u8 {
- return postWith(http, body, meta, expected_id, .{});
+ return postWith(http, body, meta, expected_id, .{ .timeout_s = @import("mcp_server.zig").transportTimeoutSeconds(http.client.allocator, meta.method, meta.name, body) });
}
pub fn postWith(http: *HttpTransport, body: []const u8, meta: RequestMeta, expected_id: ?i64, opts: PostOptions) !?[]u8 {
diff --git a/src/mcp_server.zig b/src/mcp_server.zig
index f5a933f5..857e9cde 100644
--- a/src/mcp_server.zig
+++ b/src/mcp_server.zig
@@ -247,6 +247,22 @@ const context_max_bytes: usize = 32768;
const summary_stdout_cap: usize = 16 * 1024;
const summarize_deadline_ms: u64 = 60_000;
+/// Leave the bounded task time to stop its child and return partial output.
+/// Other tools, discovery, and invalid task inputs keep the normal HTTP bound.
+/// This is request-local: it never changes another server's client settings.
+pub fn transportTimeoutSeconds(a: Allocator, method: []const u8, name: ?[]const u8, body: []const u8) i64 {
+ if (!std.mem.eql(u8, method, "tools/call") or !std.mem.eql(u8, name orelse "", "run_task")) return 15;
+ const parsed = std.json.parseFromSlice(Value, a, body, .{}) catch return 15;
+ defer parsed.deinit();
+ const request = parsed.value;
+ if (request != .object) return 15;
+ const params = request.object.get("params") orelse return 15;
+ if (params != .object) return 15;
+ const task = parseTask(params.object.get("arguments") orelse return 15) catch return 15;
+ const preprocessing: u64 = if (task.context) |context| if (context.len > inline_context_max) summarize_deadline_ms / 1000 else 0 else 0;
+ return @intCast(task.timeout_seconds + preprocessing + 15);
+}
+
const raw_context_lead = "\n\nBackground context supplied by the caller for this task:\n\n";
const summary_context_lead = "\n\nBackground context supplied by the caller for this task (summarized to fit):\n\n";
const summarize_instruction =
diff --git a/src/mcp_server_tests.zig b/src/mcp_server_tests.zig
index 7ba9aff7..fb8b9136 100644
--- a/src/mcp_server_tests.zig
+++ b/src/mcp_server_tests.zig
@@ -190,6 +190,37 @@ test "MCP execution errors are tool errors and server remains usable" {
try std.testing.expect(std.mem.indexOf(u8, result, "\"id\":3,\"result\":{}") != null);
}
+test "MCP task HTTP deadline outlives the validated child budget" {
+ const a = std.testing.allocator;
+ const default = "{\"params\":{\"arguments\":{\"prompt\":\"hello\"}}}";
+ try std.testing.expectEqual(@as(i64, 135), mcp.transportTimeoutSeconds(a, "tools/call", "run_task", default));
+ const bounded = "{\"params\":{\"arguments\":{\"prompt\":\"hello\",\"timeout_seconds\":300}}}";
+ try std.testing.expectEqual(@as(i64, 315), mcp.transportTimeoutSeconds(a, "tools/call", "run_task", bounded));
+ try std.testing.expectEqual(@as(i64, 15), mcp.transportTimeoutSeconds(a, "tools/list", "run_task", bounded));
+ try std.testing.expectEqual(@as(i64, 15), mcp.transportTimeoutSeconds(a, "tools/call", "other", bounded));
+ try std.testing.expectEqual(@as(i64, 15), mcp.transportTimeoutSeconds(a, "tools/call", null, bounded));
+}
+
+test "MCP task HTTP deadline includes only required context preprocessing" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ const a = arena.allocator();
+ const context = try a.alloc(u8, 8193);
+ @memset(context, 'x');
+ const long = try std.fmt.allocPrint(a, "{{\"params\":{{\"arguments\":{{\"prompt\":\"hello\",\"context\":\"{s}\",\"timeout_seconds\":300}}}}}}", .{context});
+ try std.testing.expectEqual(@as(i64, 375), mcp.transportTimeoutSeconds(a, "tools/call", "run_task", long));
+ const short = try std.fmt.allocPrint(a, "{{\"params\":{{\"arguments\":{{\"prompt\":\"hello\",\"context\":\"{s}\",\"timeout_seconds\":300}}}}}}", .{context[0..8192]});
+ try std.testing.expectEqual(@as(i64, 315), mcp.transportTimeoutSeconds(a, "tools/call", "run_task", short));
+}
+
+test "MCP task HTTP deadline rejects unbounded or malformed inputs" {
+ const a = std.testing.allocator;
+ for ([_][]const u8{
+ "not json", "null", "{}", "{\"params\":[]}",
+ "{\"params\":{\"arguments\":{\"prompt\":\"x\",\"timeout_seconds\":301}}}", "{\"params\":{\"arguments\":{\"prompt\":\"x\",\"timeout_seconds\":-1}}}", "{\"params\":{\"arguments\":{\"prompt\":\"x\",\"timeout_seconds\":1.5}}}", "{\"params\":{\"arguments\":{\"prompt\":\"x\",\"cwd\":\"other\"}}}",
+ }) |input| try std.testing.expectEqual(@as(i64, 15), mcp.transportTimeoutSeconds(a, "tools/call", "run_task", input));
+}
+
test "MCP failed task preserves partial output and truncation markers" {
var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena.deinit();