From 3097caa66e8d3ae709ad7981a09ffd499f5750ce Mon Sep 17 00:00:00 2001 From: Levi Neely Date: Thu, 16 Apr 2026 20:35:22 +0200 Subject: [PATCH] doc: document parallel execution and subagent fork-join pattern - README.md: add parallel execution benefit; update sub-agents benefit to describe subagent_spawn and heterogeneous fan-out composition - doc/ARCHITECTURE.md: update execute tool descriptions; add Parallel Execution and Sub-agents section documenting the fork-join pattern and architecture boundary preservation --- README.md | 6 ++++-- doc/ARCHITECTURE.md | 23 +++++++++++++++++++++-- 2 files changed, 25 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 49bc674..d993768 100644 --- a/README.md +++ b/README.md @@ -87,15 +87,17 @@ git submodule update --remote **[Code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool)** — Anthropic describes code execution as "a foundational primitive for building high-performance agents." ollie takes that literally: `execute_code` is the base layer, and `execute_tool` and `execute_pipe` build directly on top of it. New capabilities are added by dropping a script into `t/` and a skill in `sk/` — the tools provide the capability, and the skill tells the agent when and how to use them. +**Parallel execution** — `execute_code` accepts a `steps` array; multiple steps run concurrently in goroutines and results are collected in submission order. `execute_pipe` supports `{parallel: [...]}` stages for fan-out within a pipeline. Both accept inline code and named tool scripts interchangeably. + **Radical transparency** — The rendered system prompt for any session is readable at `s/{id}/systemprompt` — the prompt the agent is actually running with, not a reconstruction. The prompt parts that compose it live in `p/`; the agent can read its own instructions but cannot modify them. **Discoverability** — `ls s/{id}/` shows every control surface. `cat t/idx` and `cat sk/idx` list available tools and skills. `cat help` explains the rest. -**Composability** — Tools can be composed via `execute_pipe`, chaining `execute_code` and `execute_tool` steps the same way Unix pipes chain programs. Sessions can be chained by reading `s/{id}/chat` and writing to another session's `prompt` or `enqueue`. +**Composability** — Tools compose via `execute_pipe`, chaining `execute_code` and `execute_tool` steps the same way Unix pipes chain programs. Sessions chain by reading `s/{id}/chat` and writing to another session's `prompt` or `enqueue`. **Passive memory** — Every session's chat history accumulates at `s/{id}/chat`, searchable with `grep`. An agent doesn't need to actively decide what to remember. This extends across sessions: an agent can search another session's chat for answers that have already been worked through. -**Sub-agents** — An agent can fan out work by writing to `b/new` (ephemeral one-shot jobs) or `s/new` (persistent sessions), then collect results from `b/{id}/result` or `s/{id}/chat`. Multiple jobs run concurrently with `parallel=N`; each gets its own result file. +**Sub-agents** — `subagent_spawn` implements fork-join over the `b/` namespace: spawn N specialized agents with a shared prompt, wait for all to complete, collect results in submission order. For heterogeneous parallel delegation (N agents, N different prompts), combine with `execute_code` parallel steps — each step calls `subagent_spawn` with a different prompt, all running concurrently. ## Credits diff --git a/doc/ARCHITECTURE.md b/doc/ARCHITECTURE.md index aae52fc..eeac37d 100644 --- a/doc/ARCHITECTURE.md +++ b/doc/ARCHITECTURE.md @@ -82,9 +82,9 @@ Twelve tools across five servers: | Server | Tool | What it does | |---|---|---| -| `execute` | `execute_code` | Runs inline bash in a landrun sandbox | +| `execute` | `execute_code` | Runs one or more code steps in a sandbox; multiple steps run in parallel, results in submission order | | `execute` | `execute_tool` | Reads a named script from `OLLIE_TOOLS_PATH` and runs it sandboxed | -| `execute` | `execute_pipe` | Chains steps, piping stdout of each into stdin of the next | +| `execute` | `execute_pipe` | Chains stages sequentially, piping stdout → stdin; stages may be `{parallel:[...]}` for concurrent fan-out | | `file` | `file_read` | Reads a file from the filesystem | | `file` | `file_write` | Writes a file to the filesystem | | `file` | `file_edit` | Edits a file with precise string replacement | @@ -113,6 +113,25 @@ Twelve tools across five servers: Everything else — listing plans, inspecting a specific step, bulk operations — goes through `file_*` or `execute_code`. The task server handles only creation and step completion. +## Parallel Execution and Sub-agents + +`execute_code` implements fork-join at the shell level: multiple steps run concurrently in goroutines, results collected in submission order. Steps may be inline code (`{code, language}`) or named tool scripts (`{tool, args}`). `execute_pipe` extends this with `{parallel:[...]}` stages for fan-out within a sequential pipeline. + +Sub-agents are implemented as a tool script (`subagent_spawn`) on top of the `b/` batch namespace. The script writes a job spec to `b/new`, polls `b/{id}/status` per job in background subshells, joins on all, and concatenates results. The `b/` namespace (backed by `BatchStore`) handles agent lifecycle, cancellation, and result storage. + +For heterogeneous parallel delegation (N agents, N different prompts), `execute_code` parallel steps compose with `subagent_spawn`: each step is one shell invocation of the script with a distinct prompt, all running concurrently. This is the fork-join pattern for agent-level work: + +``` +execute_code parallel steps + ├── subagent_spawn "prompt A" → b/{id-0}/result + ├── subagent_spawn "prompt B" → b/{id-1}/result + └── subagent_spawn "prompt C" → b/{id-2}/result + ↓ + joined in submission order +``` + +The architecture boundary is preserved: `execute_code` and `execute_pipe` are built-in tools in `core`; `subagent_spawn` is a tool script; `b/` is a 9P namespace. No layer knows about the others. + ## Typical Consumer Setup ```go