From 12babf2f925cace343150d1b0e528e739e725dbc Mon Sep 17 00:00:00 2001 From: Ollie Agent Date: Tue, 11 Aug 2026 08:30:31 +0200 Subject: [PATCH] doc: document parallel execution, background interrupts, and dispatch flags --- README.md | 1 + doc/architecture.md | 19 ++++++++++++++++ doc/resources/evolution.md | 46 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 66 insertions(+) diff --git a/README.md b/README.md index d25aeb0..cb156dd 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,7 @@ Everything lives under `$XDG_CONFIG_HOME/ollie/` (default: `~/.config/ollie/`) | **One-shot LLM** | `o generate "explain monads"` or `echo "prompt" \| o generate` | | **Run an agent** | Create a session + agent via 9P — then connect with any frontend ([ellie](doc/ellie.md), KDE (GUI/KRunner/Kate), `o tui`) | | **Remote execution** | Set `remote=user@host` in session config | +| **Background processes** | Pass `"background": true` to any tool — output auto-injected into context | | **Agents** | Write a JSON config in `data/agents/` with agent prompt in `data/prompts/` | | **Tools** | Drop an executable + `.meta` in `~/.config/ollie/tools/` — load at runtime via `/tool_load` | | **Domain skills** | Load markdown skill modules at runtime | diff --git a/doc/architecture.md b/doc/architecture.md index 461003a..ad69708 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -146,6 +146,25 @@ The loop is the heart of the system. On each turn: 2. **Dispatch** — if the model returns tool calls, execute them via `toolsrv.Server` 3. **Update** — append assistant message + tool results to session history 4. **Repeat** — loop until the model produces a final text response (no tool calls) + +#### Parallel Tool Execution +Tool calls within a single turn are dispatched in parallel using resource-based conflict scheduling. Each tool declares a **scope** in its `.meta`: +- `"read"` — never conflicts (always parallel with everything) +- `"write"` — conflicts only on the same file path (different files run in parallel) +- `"global"` (or unset) — full serialization barrier (runs alone) + +This means N file edits on different paths complete in one round-trip instead of N sequential calls. Shell is always a barrier (global scope) since its effects are opaque. + +#### Background Processes +Any tool call can include `"background": true` to execute asynchronously. The result is an immediate PID; the tool runs in toolsrv's `proc/new.bg`. Background process output is automatically injected into the model's context as `` blocks at safe points (alongside subsequent tool results). The model can react to build failures, log events, etc. without polling. + +#### Dispatch Flags +All tools automatically receive four optional parameters (injected into schemas at runtime): +- `bypass` — run outside sandbox via bypass broker +- `timeout` — execution timeout in seconds +- `sandbox` — sandbox profile name +- `background` — run asynchronously, auto-inject output + Safety mechanisms: - **Consecutive error limits**: soft nudge at 5, hard abort at 10 - **Replan gate**: after 8 rounds without a PLAN: block, inject a replan nudge diff --git a/doc/resources/evolution.md b/doc/resources/evolution.md index de122f4..2ca7fb9 100644 --- a/doc/resources/evolution.md +++ b/doc/resources/evolution.md @@ -1166,6 +1166,52 @@ toolsrv uses `log/slog` (Go stdlib) with a `"svc": "toolsrv"` attribute. This is intentionally separate from olliesrv's `ollie/log` package — they are different programs with different lifecycles. +### Parallel Tool Execution + +Replaced binary ReadOnly/not batching with resource-based conflict scheduling. +Tool calls within a single turn are grouped into parallel batches based on +a three-class scope system declared in `.meta`: + +- **scope "read"** — never conflicts (always parallel) +- **scope "write"** — conflicts only on same file path +- **scope "global"** (or unset, default) — full serialization barrier + +The model's read-before-write pattern (enforced by the turn-based protocol) +guarantees that parallel writes are safe: each file_edit carries its own +`old_string` context from a prior read, and edits on different paths are +provably independent. + +Shell and tools with opaque effects (like `lsp_rename`) declare scope "global" +and always run alone. Unknown/unset scope defaults to global — tools must +opt in to parallelism. + +### Background Process Interrupts + +Any tool call can include `"background": true` to execute asynchronously +via `proc/new.bg`. The model receives a PID immediately and continues working. +Background process output is automatically injected into the model's context +as `` blocks alongside subsequent tool results: + +```xml + +--- FAIL: TestFoo (0.00s) + foo_test.go:12: expected 3, got 2 +FAIL + +``` + +The model sees these naturally — no polling, no explicit `process_output` calls. +It can react to failures or kill processes by PID when done. + +### Universal Dispatch Flags + +All tools receive four optional parameters injected into their schemas at +runtime (not declared per-tool): +- `bypass` — sandbox escape via bypass broker +- `timeout` — execution timeout in seconds +- `sandbox` — sandbox profile override +- `background` — async execution with auto-injected output + ### Open Problem: Concurrency Tool execution in toolsrv is capable of running in the background (`proc/new.bg`),