docs: record omp subagent fan-out caps and per-endpoint in-flight ceilings
Codifies the limits set in agent/config.yml 2026-10-19: task concurrency 2, no nested subagent spawns (maxRecursionDepth 1 - and why 0 must never be set), 30-min runtime / 120-request budgets, isolation opt-in enabled, completion probes off, 600s tool timeout ceiling, and per-provider in-flight caps (archon 3, dragoon 2, zealot 3) keyed by models.yml provider ids with their per-machine scope caveat. Small docs-only change; no issue opened per trunk-based small-fix exemption.
This commit is contained in:
Frank
@@ -28,7 +28,8 @@
|
||||
|
||||
## Subagent Architecture
|
||||
|
||||
- [Pi Subagents](/pi/packages/pi-subagents.md) — Core subagent delegation system. Chains, parallel execution, TUI clarification.
|
||||
- [OMP Subagent Limits & Fan-out Policy](/pi/subagent-limits.md) — Live caps: concurrency 2, no nested spawns (and the `maxRecursionDepth: 0` trap), per-endpoint in-flight ceilings, isolation policy.
|
||||
- [Pi Subagents](/pi/packages/pi-subagents.md) — (historical) pi-era delegation system. Chains, parallel execution, TUI clarification.
|
||||
|
||||
## Architecture
|
||||
|
||||
|
||||
@@ -0,0 +1,97 @@
|
||||
---
|
||||
type: reference
|
||||
title: OMP Subagent Limits & Fan-out Policy
|
||||
description: The live caps on omp subagents — concurrency 2, no nested spawns, per-endpoint in-flight ceilings, 30-min runtime, soft request budget, and the isolated-workspace policy; includes the maxRecursionDepth=0 trap.
|
||||
tags:
|
||||
- omp
|
||||
- subagents
|
||||
- config
|
||||
- fleet
|
||||
timestamp: 2026-10-19
|
||||
---
|
||||
|
||||
# OMP Subagent Limits & Fan-out Policy
|
||||
|
||||
Enforced caps on subagents spawned through the `task` tool / eval `agent()`+`workpool()`
|
||||
from this workstation (config root `agent/config.yml`, machine-live tier — the live-sync
|
||||
heartbeat commits it). Set 2026-10-19; values verified against the live config and the
|
||||
enforcement code in the installed bundle (`@oh-my-pi/pi-coding-agent/dist/cli.js`).
|
||||
|
||||
## The caps in force
|
||||
|
||||
| Key | Value | Default | Effect |
|
||||
|---|---|---|---|
|
||||
| `task.maxConcurrency` | 2 | 32 | Session-scoped semaphore; excess spawns queue, never drop. |
|
||||
| `task.maxRecursionDepth` | 1 | 2 | Subagents cannot spawn their own subagents. See depth semantics. |
|
||||
| `task.maxRuntimeMs` | 1800000 | 0 (off) | Hard 30-min wall clock per subagent; overrun = `aborted`. |
|
||||
| `task.softRequestBudget` | 120 | 200 | Wrap-up notice at 120 assistant requests; force-stopped to yield at 180 (1.5×). |
|
||||
| `task.agentIdleTtlMs` | 420000 | same | Finished subagents parked to disk after 7 min idle (revivable via `agent://`). |
|
||||
| `task.enableEffort` | false | false | Per-spawn `effort` hint hidden from the schema. |
|
||||
| `task.isolation.enabled` | true | false | `isolated: true` spawns run in a copy of the checkout; only successful patches land (merge=patch, apply). Opt-in per spawn. |
|
||||
| `task.completionProbe` | false | true | No periodic completeness side-requests into running subagents. |
|
||||
| `tools.maxTimeout` | 600 | 0 (off) | No agent may request a tool timeout above 10 min; kills `timeout: 0` runaways. |
|
||||
| `providers.maxInFlightRequests` | see below | {} (unlimited) | Per-provider ceiling on concurrent LLM requests, shared across local omp processes. |
|
||||
|
||||
## Depth semantics — never set `maxRecursionDepth: 0`
|
||||
|
||||
Bundle predicate (`U_`): a session at `taskDepth` *s* keeps the `task` tool iff
|
||||
`n < 0 || s < n` where `n = maxRecursionDepth`. The preflight repeats the check
|
||||
(`Cannot spawn another agent at task depth s; maximum depth is n`).
|
||||
|
||||
- `n = 1` → main (depth 0) spawns; children (depth 1) have `task` stripped. **This is
|
||||
"no nested subagents".**
|
||||
- `n = 0` → `0 < 0` fails → **not even the main session can spawn anything.** Don't.
|
||||
- `n < 0` → cap disabled.
|
||||
|
||||
## Per-endpoint in-flight ceilings
|
||||
|
||||
```yaml
|
||||
providers:
|
||||
maxInFlightRequests:
|
||||
"llamacpp (dankserver)": 3 # main session + up to 2 task/reviewer subagents
|
||||
"llamacpp (dankclaw)": 2 # frank-dragoon: security-reviewer + fallbacks
|
||||
"llamacpp (dankclaw-3090)": 3 # frank-zealot: scout/sonic/librarian/designer + smol/tiny/plan/commit/vision roles
|
||||
```
|
||||
|
||||
- Keys are **provider ids** = the quoted block labels in `agent/models.yml`
|
||||
(one provider per host:port). The consumer does a flat map lookup by provider id;
|
||||
absent or ≤0 = unlimited, otherwise clamped to ≥1.
|
||||
- Scope is **per machine, per config root**: it bounds what *this workstation's* omp
|
||||
processes put on each endpoint. Other workstations, OpenWebUI, and any non-omp
|
||||
client are not counted. Requests past the ceiling queue, never fail.
|
||||
- `web/searxng` intentionally uncapped.
|
||||
|
||||
## Isolation note
|
||||
|
||||
`task.isolation.enabled: true` makes the per-spawn `isolated` flag available — it is
|
||||
**opt-in per spawn**, not a blanket sandbox. Requires a git repo; unavailable in plan
|
||||
mode; baseline snapshot capped at 1 GiB; backends resolve via `isolation.backend: auto`
|
||||
(overlayfs/reflink/rcopy chain on this box). Given *the checkout is the deployment*,
|
||||
prefer `isolated: true` for any subagent that edits tracked files.
|
||||
|
||||
## Deliberately not set
|
||||
|
||||
- `bash.gitGuard` — offered 2026-10-19, declined; destructive-git protection stays opt-in.
|
||||
- `task.disabledAgents` — no bundled agent type warrants a ban.
|
||||
- `task.agentAccountPools`, `tier.subagent` — no-op against keyless local endpoints.
|
||||
- `PI_TASK_MAX_OUTPUT_BYTES` / `PI_TASK_MAX_OUTPUT_LINES` — 500 KB / 5000 line defaults are sane.
|
||||
- `before_subagent_spawn` hook — programmable spawn policy; revisit if these caps prove insufficient.
|
||||
|
||||
## Verification
|
||||
|
||||
`cfg://task`, `cfg://providers/maxInFlightRequests` reflect all rows above; persisted
|
||||
copies in `agent/config.yml`. Depth semantics confirmed against the shipped bundle, not
|
||||
just the setting description.
|
||||
|
||||
# Citations
|
||||
|
||||
- `agent/config.yml` (live config, this repo)
|
||||
- `agent/models.yml` — provider id block labels
|
||||
- `@oh-my-pi/pi-coding-agent/dist/cli.js` — `U_` depth predicate, in-flight map lookup
|
||||
- omp docs: `omp://tools/task.md` § Limits & Caps
|
||||
|
||||
# See Also
|
||||
|
||||
- [/pi/statusline.md](/pi/statusline.md) — the omp-era bundle-audit page pattern this page follows
|
||||
- [/pi/packages/pi-subagents.md](/pi/packages/pi-subagents.md) — retired pi-era subagent system (historical)
|
||||
- [/system/index.md](/system/index.md) — fleet endpoints these ceilings target
|
||||
Reference in New Issue
Block a user