Background Task System

Relevant source files

The Background Task System enables asynchronous execution of agent sessions with automatic lifecycle management, concurrency control, and parent notification. This system allows agents to spawn long-running subagent sessions that execute in parallel while the parent agent continues working, with automatic notifications upon completion.

For information about how agents use background tasks for delegation, see Agent Orchestration For configuration of concurrency limits and spawn depth, see Configuration Reference

Purpose and Scope

The background task system provides:

Asynchronous execution: Spawn agent sessions that run independently of the parent via BackgroundManager.launch() packages/omo-opencode/src/features/background-agent/manager.ts223-245
Concurrency management: Per-model/provider limits with FIFO queueing managed by ConcurrencyManager packages/omo-opencode/src/features/background-agent/manager.ts57 packages/omo-opencode/src/features/background-agent/manager.ts148-158
Lifecycle tracking: Automatic polling and state transitions from pending → running → completed/error packages/omo-opencode/src/features/background-agent/types.ts5-11
Parent notifications: Serialized notifications to parent sessions with OS toast integration via TaskToastManager packages/omo-opencode/src/features/background-agent/manager.ts39 packages/omo-opencode/src/features/background-agent/manager.ts129-132
Spawn controls: Hierarchical depth limits and descendant budgets enforced by assertCanSpawn packages/omo-opencode/src/features/background-agent/manager.ts207-215
Error recovery: Automatic model fallback on provider errors using tryFallbackRetry packages/omo-opencode/src/features/background-agent/manager.ts74
Loop Protection: Circuit breaker to detect and stop repetitive tool calls via detectRepetitiveToolUse packages/omo-opencode/src/features/background-agent/loop-detector.ts90-102

Sources: packages/omo-opencode/src/features/background-agent/manager.ts186-215 packages/omo-opencode/src/features/background-agent/types.ts5-98 packages/omo-opencode/src/features/background-agent/constants.ts4-16

Core Architecture

BackgroundManager Class

The BackgroundManager class is the central orchestrator. It maintains task state, manages concurrency, and coordinates polling packages/omo-opencode/src/features/background-agent/manager.ts186-212

Entity Association Map

Key state maps:

tasks: Complete task registry indexed by task ID packages/omo-opencode/src/features/background-agent/manager.ts219
notifications: Tasks awaiting parent notification packages/omo-opencode/src/features/background-agent/manager.ts222
queuesByKey: FIFO queue per concurrency key (e.g., model name) packages/omo-opencode/src/features/background-agent/manager.ts148

Sources: packages/omo-opencode/src/features/background-agent/manager.ts186-222 packages/omo-opencode/src/features/background-agent/types.ts44-100 packages/omo-opencode/src/features/background-agent/task-poller.ts174-184

Task Lifecycle

State Machine

Background tasks transition through states defined in BackgroundTaskStatus packages/omo-opencode/src/features/background-agent/types.ts5-11

Task Transition Diagram

State definitions:

pending: Queued, waiting for concurrency slot packages/omo-opencode/src/features/background-agent/types.ts6
running: Session active, polling for completion packages/omo-opencode/src/features/background-agent/types.ts7
completed: Successfully finished with output packages/omo-opencode/src/features/background-agent/types.ts8
error: Unrecoverable failure or max retries exceeded packages/omo-opencode/src/features/background-agent/types.ts9
cancelled: Aborted by user or staleTimeoutMs packages/omo-opencode/src/features/background-agent/types.ts10

Sources: packages/omo-opencode/src/features/background-agent/types.ts5-11 packages/omo-opencode/src/features/background-agent/task-poller.ts25-30 packages/omo-opencode/src/features/background-agent/constants.ts15 packages/omo-opencode/src/features/background-agent/spawner.ts26-150

Polling and Staleness Detection

The system uses a 3-second polling interval (POLLING_INTERVAL_MS) to monitor tasks packages/omo-opencode/src/features/background-agent/constants.ts59

Staleness Checks packages/omo-opencode/src/features/background-agent/task-poller.ts174-205:

No Progress Timeout: If a task has no progress.lastUpdate for messageStalenessTimeoutMs (default 60 min), it is cancelled packages/omo-opencode/src/features/background-agent/task-poller.ts199-203
Idle Timeout: If a running task has no activity for staleTimeoutMs (default 45 min), it is cancelled packages/omo-opencode/src/features/background-agent/task-poller.ts195-203
Session Gone: If the session disappears from the registry for sessionGoneTimeoutMs (default 1 min), it is aborted packages/omo-opencode/src/features/background-agent/task-poller.ts196-203
Pruning: Terminal tasks are removed from memory after TASK_CLEANUP_DELAY_MS packages/omo-opencode/src/features/background-agent/constants.ts61

Sources: packages/omo-opencode/src/features/background-agent/task-poller.ts1-125 packages/omo-opencode/src/features/background-agent/constants.ts59-63 packages/omo-opencode/src/features/background-agent/types.ts19-27

Concurrency and Spawn Limits

ConcurrencyManager

The ConcurrencyManager enforces limits per provider/model packages/omo-opencode/src/features/background-agent/manager.ts148

Default: 5 concurrent tasks per key.
Configuration: Managed via BackgroundTaskConfig passed to the BackgroundManager packages/omo-opencode/src/features/background-agent/manager.ts3

Spawn Guards

Before launching, the system checks hierarchical limits via resolveSubagentSpawnContext packages/omo-opencode/src/features/background-agent/subagent-spawn-limits.ts104:

Max Depth: Prevents deep subagent nesting via getMaxSubagentDepth packages/omo-opencode/src/features/background-agent/subagent-spawn-limits.ts103
Depth Enforcement: BackgroundManager throws SubagentDepthLimitError if depth exceeds configured limits packages/omo-opencode/src/features/background-agent/subagent-spawn-limits.ts102

Sources: packages/omo-opencode/src/features/background-agent/manager.ts207-215 packages/omo-opencode/src/features/background-agent/subagent-spawn-limits.ts101-105

Loop Protection (Circuit Breaker)

To prevent infinite loops that burn tokens, the BackgroundManager uses a circuit breaker packages/omo-opencode/src/features/background-agent/loop-detector.ts1-13

Logic packages/omo-opencode/src/features/background-agent/loop-detector.ts33-102:

Signature: Every tool call is hashed into a signature based on name and arguments packages/omo-opencode/src/features/background-agent/loop-detector.ts77-88
Tracking: recordToolCall maintains a consecutiveCount for identical signatures packages/omo-opencode/src/features/background-agent/loop-detector.ts33-62
Trigger: If consecutiveCount exceeds consecutiveThreshold (default 20), detectRepetitiveToolUse returns triggered: true, and the task is failed packages/omo-opencode/src/features/background-agent/loop-detector.ts90-102

Sources: packages/omo-opencode/src/features/background-agent/loop-detector.ts1-102 packages/omo-opencode/src/features/background-agent/constants.ts10-11

Parent Session Notifications

The ParentWakeNotifier manages the injection of notifications into parent sessions when background tasks finish or reach terminal states packages/omo-opencode/src/features/background-agent/parent-wake-notifier.ts18

Notification Flow

Queueing: Notifications are queued via queuePendingParentWake packages/omo-opencode/src/features/background-agent/parent-wake-notifier.ts88
Idle Detection: The system waits for the parent session to become idle using settleAfterSessionIdle packages/omo-opencode/src/features/background-agent/parent-wake-notifier.ts113
Collision Avoidance: To prevent crashes on specific platforms (e.g., macOS Electron), the system checks for fresh user messages via PARENT_WAKE_USER_MESSAGE_IN_PROGRESS_WINDOW_MS packages/omo-opencode/src/features/background-agent/manager.ts157
Injection: Notifications are injected using dispatchInternalPrompt which uses the prompt-async-gate to add synthetic messages without interrupting the user's flow packages/omo-opencode/src/features/background-agent/manager.ts7 packages/omo-opencode/src/shared/prompt-async-gate.ts69

Sources: packages/omo-opencode/src/features/background-agent/parent-wake-notifier.ts18-172 packages/omo-opencode/src/features/background-agent/manager.ts82 docs/reference/prompt-async-gate-rfc.md1-42

Process Cleanup and Graceful Shutdown

The BackgroundManager registers with the registerManagerForCleanup utility to ensure background sessions are aborted when the host process exits packages/omo-opencode/src/features/background-agent/process-cleanup.ts83

Cleanup Mechanism:

Signal Handlers: Listens for SIGINT, SIGTERM, and SIGBREAK (Windows) packages/omo-opencode/src/features/background-agent/process-cleanup.ts183-186
Grace Period: Initiates a 6-second forced-exit timer via scheduleForcedExit while waiting for manager.shutdown() to complete packages/omo-opencode/src/features/background-agent/process-cleanup.ts44-51
Log-only Error Handlers: uncaughtException and unhandledRejection are log-only and do not trigger cleanup to avoid tearing down tasks on transient streaming errors packages/omo-opencode/src/features/background-agent/process-cleanup.ts167-180

Sources: packages/omo-opencode/src/features/background-agent/process-cleanup.ts1-200 packages/omo-opencode/src/features/background-agent/manager.ts84

Tool Integration

The background system is exposed through several tools:

Tool	Implementation	Purpose
`background_task`	`createTask` packages/omo-opencode/src/features/background-agent/spawner.ts26	Spawns a new task and returns a `task_id` packages/omo-opencode/src/features/background-agent/spawner.ts27
`background_output`	`createBackgroundOutput` packages/omo-opencode/src/tools/background-task/create-background-output.ts	Retrieves output or blocks until completion.
`background_cancel`	`background_cancel`	Aborts a specific background task or all tasks.
`call_omo_agent`	`startTask` packages/omo-opencode/src/features/background-agent/spawner.ts30	High-level tool to spawn specialized agents in background or sync mode packages/omo-opencode/src/features/background-agent/spawner.ts30-174

Output Handling: Notifications are sent to the parent session once a task reaches a terminal state. If the parent is idle, handleSessionIdleBackgroundEvent triggers a prompt to the parent to check results packages/omo-opencode/src/features/background-agent/manager.ts90

Sources: packages/omo-opencode/src/features/background-agent/spawner.ts26-174 packages/omo-opencode/src/features/background-agent/task-poller.ts174-205 packages/omo-opencode/src/features/background-agent/manager.ts90