Background Tasks

The BackgroundTracker provides Cortex-backed tracking for long-running agent tasks. Tasks are automatically tracked via the agent_end hook when agents are marked with background: true.

Task lifecycle

mermaid
stateDiagram-v2
    [*] --> Pending : track()
    Pending --> Running : agent starts work
    Running --> Completed : success
    Running --> Failed : error
    Running --> Cancelled : cancel()
    Pending --> Cancelled : cancel()

Tracking tasks

Tasks are tracked automatically for agents with background: true in their markdown definition:

markdown
---
name: indexer
background: true
---

# Indexer Agent

Re-indexes the codebase in the background.

The agent_end hook records task completion, failure, and results.

Operations

MethodDescription
track(params)Create a new tracked task
updateStatus(taskId, status, result?)Update task status
updateProgress(taskId, progress)Set progress (0–100)
cancel(taskId)Cancel a task
getTask(taskId)Get task details
listTasks(opts?)List tasks with optional filters
summary()Aggregate statistics

Agent tools

  • agent_background_status — check status of background tasks
  • agent_background_cancel — cancel a running task

Cortex storage

{ns}:bgtask:{taskId} → {ns}:bgtask:agentId → "indexer"
{ns}:bgtask:{taskId} → {ns}:bgtask:status → "running"
{ns}:bgtask:{taskId} → {ns}:bgtask:progress → "45"
{ns}:bgtask:{taskId} → {ns}:bgtask:startedAt → "2025-01-15T10:30:00Z"

Configuration

json5
{
  background: {
    maxConcurrentTasks: 5,       // Max simultaneous background tasks
    taskTimeoutSeconds: 3600,    // Task timeout (1 hour default)
  },
}