From 3e6d1aa7d51bb3e331b8edde1673139b1a445a34 Mon Sep 17 00:00:00 2001 From: Ollie Agent Date: Tue, 11 Aug 2026 08:06:38 +0200 Subject: [PATCH] doc: update concurrency section with parallel fan-out and protocol constraints --- doc/resources/evolution.md | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/doc/resources/evolution.md b/doc/resources/evolution.md index 758a5e1..de122f4 100644 --- a/doc/resources/evolution.md +++ b/doc/resources/evolution.md @@ -1170,9 +1170,27 @@ are different programs with different lifecycles. Tool execution in toolsrv is capable of running in the background (`proc/new.bg`), but foreground blocking execution (`proc/new`) remains the default. The reason: -**concurrency is an unsolved problem.** When multiple tools run simultaneously, -the agent must reason about interleaved results, partial state, and ordering — -LLMs handle this poorly. Background processes exist for cases where the user -or agent explicitly opts in (long-running builds, watchers), but the default -serial execution is a deliberate constraint, not a limitation of the architecture. +**full concurrency is an unsolved problem.** The LLM tool-use protocol requires +all tool results to arrive before the model gets another turn — there is no way +to inject a late result into the conversation without violating message ordering. +Background processes exist for cases where the model explicitly opts in +(long-running builds, watchers), but the default execution must block until +all results are collected. + +Within a single turn, however, **parallel fan-out** is now safe and automatic. +Resource-based conflict scheduling (Phase 20) groups non-conflicting tool calls +into parallel batches: + +- **scope "read"** — never conflicts (always parallel) +- **scope "write"** — conflicts only on same file path (different files parallel) +- **scope "global"** (or unset) — full serialization barrier + +This maximizes throughput within the protocol constraint: N file edits on +different paths complete in one round-trip instead of N. The model still +blocks per-turn, but the turn completes faster. + +The remaining unsolved case: the model emits a slow tool call and wants to +keep working. The protocol doesn't allow retroactive result injection — +the model must consciously decide to background a process upfront via +`proc/new.bg` and collect results later via a separate tool call.