|
| 1 | +# Follow-up-Issues: Nested-Agent-Spawning (Phase 2) |
| 2 | + |
| 3 | +Quelle: `design-final.md` §9/§10 (Branch `feat/nested-agents`). Jedes Kapitel ist als |
| 4 | +eigenständiges GitHub-Issue gedacht. Keines dieser Themen ist Teil von V1. |
| 5 | + |
| 6 | +--- |
| 7 | + |
| 8 | +## Issue 1: Parallelitäts-Cap für Subagent-Spawns |
| 9 | + |
| 10 | +**Kontext:** V1 hat bewusst keinen Semaphor (design-final §2.2): Foreground-Tasks blockieren |
| 11 | +ihren Eltern-Step ohnehin, Background bleibt flag-gated |
| 12 | +(`OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS`), Lifetime-Cap (200/Baum) + Tiefenlimit |
| 13 | +begrenzen den Fan-out. Ein Parallelitäts-Cap ist ein reines Phase-2-Thema. |
| 14 | + |
| 15 | +**Scope:** Begrenzung gleichzeitig laufender Subagents pro Session-Baum bzw. pro Ebene. |
| 16 | + |
| 17 | +**BINDENDE DESIGN-NOTIZ (design-final.md §10, wörtlich — bei der Umsetzung zwingend beachten):** |
| 18 | + |
| 19 | +> **NIEMALS ein einzelner baumweiter Semaphor über Foreground-Ketten.** Beweisbares |
| 20 | +> Gegenbeispiel: Cap 2, zwei parallele L2-Foreground-Tasks halten beide Permits und warten auf |
| 21 | +> L3-Kinder, die nie ein Permit bekommen → Deadlock (wartende Eltern halten Permits, die ihre |
| 22 | +> Kinder brauchen). Zulässige Varianten: (a) Per-Ebene-Permits — Pools strikt nach Ebene |
| 23 | +> geordnet, ein Halter von Ebene N wartet nie auf Ebene ≤ N, Ebene `max_depth` spawnt nie ⇒ per |
| 24 | +> Induktion drainieren alle Pools; (b) Fail-Fast-Breiten-Cap pro Session mit klarem Fehlertext |
| 25 | +> (kein stilles Queuing). In beiden Fällen muss das Warten interrupt-fähig sein (Abort-Kaskade |
| 26 | +> darf nie an einem Permit hängen). Diese Notiz gehört wörtlich in das Follow-up-Issue. |
| 27 | +
|
| 28 | +**Akzeptanzkriterien:** |
| 29 | +- Implementierung ist Variante (a) Per-Ebene-Permits ODER (b) Fail-Fast-Breiten-Cap pro |
| 30 | + Session — KEIN baumweiter Semaphor über Foreground-Ketten. |
| 31 | +- Warten ist interrupt-fähig: Die Abort-Kaskade darf nie an einem Permit hängen |
| 32 | + (Regressionstest analog Abort-Kaskaden-Test in `test/session/nested-task.test.ts`). |
| 33 | +- Deadlock-Gegenbeispiel aus der Notiz (Cap 2, zwei parallele L2-Foreground-Tasks mit |
| 34 | + L3-Kindern) als Test abgedeckt. |
| 35 | + |
| 36 | +--- |
| 37 | + |
| 38 | +## Issue 2: Config-Key für das Tree-Limit |
| 39 | + |
| 40 | +**Kontext:** `SUBAGENT_TREE_LIMIT = 200` ist in V1 eine Konstante mit Test-Seam |
| 41 | +(`__testHooks.treeLimit` in `packages/opencode/src/session/subagent-limits.ts`, Vorbild |
| 42 | +`__testHooks.agentLimit` in workflow.ts). design-final §2.5: Config-Key = Phase 2. |
| 43 | + |
| 44 | +**Scope:** `experimental`-Config-Key (z. B. `subagent_tree_limit`), Konsum ausschließlich |
| 45 | +über einen Clamp-Helper in `subagent-limits.ts` (Single Source of Truth, analog `maxDepth(cfg)`). |
| 46 | +Der Zähler bleibt in-memory pro Prozess-Lebensdauer (Safety-Ceiling, kein Abrechnungszähler — |
| 47 | +DB-Priming wurde in design-final §1.3 explizit verworfen). |
| 48 | + |
| 49 | +--- |
| 50 | + |
| 51 | +## Issue 3: `depth`/`rootID` als additive Wire-Felder |
| 52 | + |
| 53 | +**Kontext:** V1 leitet Tiefe und Root rein aus der `parentID`-Kette ab (`Session.lineage`), |
| 54 | +null Schema-Änderungen. Phase 2 kann beide Werte als Convenience-Felder am Wire nachrüsten |
| 55 | +(design-final §3/§9) — jederzeit additiv möglich, Wire-Format bleibt kompatibel. |
| 56 | + |
| 57 | +**Scope:** |
| 58 | +- `depth` und `rootID` als additive Felder an `Session.Info` / OpenAPI / SDK (Regeneration). |
| 59 | +- **Backfill für Bestandsdaten: einmalige Migration per rekursiver CTE** (Vorlage in |
| 60 | + design-robust). **NICHT Lazy-Backfill-on-read** (Write in Lesepfaden = Wartbarkeits-Smell, |
| 61 | + zwei Wahrheitsquellen — in design-final §1.3 explizit verworfen). |
| 62 | +- `recursive`-Param für `GET /session/:id/children`. |
| 63 | + |
| 64 | +--- |
| 65 | + |
| 66 | +## Issue 4: TUI-Baumansicht / Breadcrumbs / Tiefen-Badges |
| 67 | + |
| 68 | +**Kontext:** V1 verzichtet bewusst auf den UI-Umbau (größte Regressionsoberfläche, |
| 69 | +design-final §1.3). Root-Routing der Permission-Asks macht die TUI bereits ohne Umbau |
| 70 | +funktionsfähig; Ebene-3+-Navigation läuft pro Ebene über die bestehenden |
| 71 | +`session_child_*`-Keybinds. |
| 72 | + |
| 73 | +**Scope (Komfort, Folge-PRs):** Baumansicht für Session-Hierarchien, Breadcrumb-Kette in der |
| 74 | +Kopfzeile, Tiefen-Badges an Task-Cards, Run-Footer-Gruppierung nach Teilbaum, Tree-Dialog. |
| 75 | +UIs können "asked by @agent (depth N)" aus `metadata.originSessionID`/`originAgent`/ |
| 76 | +`originDepth` der Permission-Requests rendern. Profitiert von Issue 3 (Wire-Felder), hängt |
| 77 | +aber nicht hart daran (Lineage-Walk reicht). |
| 78 | + |
| 79 | +--- |
| 80 | + |
| 81 | +## Issue 5: Per-Task-Timeout |
| 82 | + |
| 83 | +**Kontext:** V1 hat kein Timeout pro Ebene (design-final §2.2): Abort-Kaskade + Budget genügen; |
| 84 | +der Zyklen-Deadlock ist durch die `task_id`-Ancestry-Validierung (nur direkte Kinder) |
| 85 | +geschlossen. |
| 86 | + |
| 87 | +**Scope:** Optionales Timeout pro Task-Spawn (Config und/oder Tool-Param). Muss sauber in die |
| 88 | +Abort-Kaskade integrieren (Timeout = Abort des Teilbaums, kein verwaister Job) und darf |
| 89 | +Foreground-Eltern nicht in undefinierte Zustände bringen. |
| 90 | + |
| 91 | +--- |
| 92 | + |
| 93 | +## Issue 6: Kosten-Rollup über den Session-Baum |
| 94 | + |
| 95 | +**Kontext:** V1 zählt Kosten wie heute pro Session, keine Doppelzählung, kein Rollup |
| 96 | +(design-final §4.6). Für tiefe Bäume fehlt die aggregierte Sicht. |
| 97 | + |
| 98 | +**Scope:** Anzeige-Rollup der Kind-Kosten in der Task-Part-Metadata (Anzeige, keine |
| 99 | +Doppel-Abrechnung); Aggregation über `Session.descendants` oder die Wire-Felder aus Issue 3. |
0 commit comments