AGENTS.md

1# src/features/background-agent/ — Core Orchestration Engine
2 
3**Generated:** 2026-05-20
4 
5## OVERVIEW
6 
745 non-test files. Manages async task lifecycle: launch → queue → run → poll → complete/error. Concurrency limited per model/provider (default 5). Central to multi-agent orchestration.
8 
9## TASK LIFECYCLE
10 
11```
12LaunchInput → pending → [ConcurrencyManager queue] → running → polling → completed/error/cancelled/interrupt
13```
14 
15## KEY FILES
16 
17| File | Purpose |
18|------|---------|
19| `manager.ts` | `BackgroundManager` — main class: launch, cancel, getTask, listTasks |
20| `spawner.ts` | Task spawning: create session → inject prompt → start polling |
21| `concurrency.ts` | `ConcurrencyManager` — FIFO queue per concurrency key, slot acquisition/release |
22| `task-poller.ts` | 3s interval polling, completion via idle events + stability detection (10s unchanged) |
23| `types.ts` | `BackgroundTask`, `LaunchInput`, `ResumeInput`, `BackgroundTaskStatus` |
24| `parent-wake-notifier.ts` | 587 LOC. Dependency-injected client + enqueue callback. Notifies parent session when a background task wants attention. |
25| `loop-detector.ts` | Detects polling/event loops that would otherwise burn budget. |
26| `error-classifier.ts` | Maps raw provider errors → `BackgroundTaskError` categories. |
27| `fallback-retry-handler.ts` | Coordinates retries with the runtime-fallback system. |
28| `process-cleanup.ts` | Best-effort cleanup on parent exit. `OMO_DISABLE_PROCESS_CLEANUP=1` opts out entirely. |
29| `subagent-spawn-limits.ts` | Enforces per-parent subagent spawn caps. |
30| `session-status-classifier.ts` | Normalizes OpenCode session status across versions. |
31| `compaction-aware-message-resolver.ts` | Resolves task result content even across mid-task compaction. |
32| `attempt-lifecycle.ts` | Tracks retry attempts on a single task. |
33| `task-history.ts` | Append-only history for completed tasks. |
34| `session-idle-event-handler.ts` | Bridges OpenCode `session.idle` → task-poller completion signal. |
35| `session-existence.ts` | Cheap existence check used by recovery code. |
36| `abort-with-timeout.ts` | Force-abort tasks past `syncPollTimeoutMs`. |
37| `remove-task-toast-tracking.ts` | Strips lingering toast tracker entries on task end. |
38| `background-task-notification-template.ts` | Template for parent-session result injection. |
39 
40## SPAWNER SUBDIRECTORY
41 
42| File | Purpose |
43|------|---------|
44| `spawner-context.ts` | `SpawnerContext` interface composing all spawner deps |
45| `background-session-creator.ts` | Create OpenCode session for background task |
46| `concurrency-key-from-launch-input.ts` | Derive concurrency key from model/provider |
47| `tmux-callback-invoker.ts` | Notify TmuxSessionManager on session creation |
48 
49## COMPLETION DETECTION
50 
51Two signals combined:
521. **Session idle event** — OpenCode reports session became idle
532. **Stability detection** — message count unchanged for 10s (3+ stable polls at 3s interval)
54 
55Both must agree before marking a task complete. Prevents premature completion on brief pauses.
56 
57## CONCURRENCY MODEL
58 
59- Key format: `{providerID}/{modelID}` (e.g., `anthropic/claude-opus-4-7`)
60- Default limit: 5 concurrent per key (configurable via `background_task` config)
61- FIFO queue: tasks wait in order when slots full
62- Slot released on: completion, error, cancellation
63 
64## NOTIFICATION FLOW
65 
66```
67task completed → result-handler → parent-session-notifier → inject system message into parent session
68```
69