Scheduler And Tasks

The scheduler is an optional in-memory task queue for multi-agent coordination. It accepts tasks over /tasks, applies admission and fairness rules, then dispatches work to the same tab action executor used by the immediate browsing routes.

It does not replace the normal direct path. Routes such as POST /tabs/{id}/action still work independently.

There is no CLI scheduler command today.

Enable The Scheduler

The scheduler is off by default. Dashboard mode registers the task routes only when scheduler.enabled is true.

{
  "scheduler": {
    "enabled": true
  }
}

Scheduler Config

{
  "scheduler": {
    "enabled": true,
    "strategy": "fair-fifo",
    "maxQueueSize": 1000,
    "maxPerAgent": 100,
    "maxInflight": 20,
    "maxPerAgentInflight": 10,
    "resultTTLSec": 300,
    "workerCount": 4
  }
}

Task Object

Tasks are scheduler-owned records with these main fields:

Task IDs are currently generated as tsk_XXXXXXXX, but callers should still treat them as opaque IDs.

Submit A Task

curl -X POST http://localhost:9867/tasks \  -H "Content-Type: application/json" \  -d '{    "agentId": "agent-crawl-01",    "action": "click",    "tabId": "8f9c7d4e1234567890abcdef12345678",    "ref": "e14",    "priority": 5,    "deadline": "2026-03-08T12:05:00Z"  }'

curl -X POST http://localhost:9867/tasks \  -H "Content-Type: application/json" \  -d '{    "agentId": "agent-crawl-01",    "action": "click",    "tabId": "8f9c7d4e1234567890abcdef12345678",    "ref": "e14",    "priority": 5,    "deadline": "2026-03-08T12:05:00Z"  }'

{
  "taskId": "tsk_a1b2c3d4",
  "state": "queued",
  "position": 1,
  "createdAt": "2026-03-08T12:00:01Z"
}

This endpoint returns 202 Accepted on successful queue submission.

Request fields:

Important:

• request validation enforces only agentId and action
• missing tabId is rejected later during execution with tabId is required for task execution
• past deadlines are rejected at submission time

Queue Full Response

If admission fails because the global queue or an agent queue is full, the scheduler returns 429 Too Many Requests.

curl -X POST http://localhost:9867/tasks \  -H "Content-Type: application/json" \  -d '{"agentId":"agent-crawl-01","action":"click","tabId":"8f9c7d4e1234567890abcdef12345678"}'

curl -X POST http://localhost:9867/tasks \  -H "Content-Type: application/json" \  -d '{"agentId":"agent-crawl-01","action":"click","tabId":"8f9c7d4e1234567890abcdef12345678"}'

{
  "code": "queue_full",
  "error": "rejected: global queue full",
  "retryable": true,
  "details": {
    "agentId": "agent-crawl-01",
    "queued": 1000,
    "maxQueue": 1000,
    "maxPerAgent": 100
  }
}

List Tasks

GET /tasks returns the scheduler’s in-memory task snapshots, including queued, running, and recently completed tasks that are still within the TTL window.

curl http://localhost:9867/tasks

curl http://localhost:9867/tasks

{
  "tasks": [
    {
      "taskId": "tsk_a1b2c3d4",
      "state": "done",
      "agentId": "agent-crawl-01",
      "action": "click",
      "latencyMs": 842
    }
  ],
  "count": 1
}

Supported query filters:

• agentId
• state

Example:

curl 'http://localhost:9867/tasks?agentId=agent-crawl-01&state=done,failed'

curl 'http://localhost:9867/tasks?agentId=agent-crawl-01&state=done,failed'

Get One Task

curl http://localhost:9867/tasks/tsk_a1b2c3d4

curl http://localhost:9867/tasks/tsk_a1b2c3d4

{
  "taskId": "tsk_a1b2c3d4",
  "agentId": "agent-crawl-01",
  "action": "click",
  "tabId": "8f9c7d4e1234567890abcdef12345678",
  "ref": "e14",
  "priority": 5,
  "state": "done",
  "createdAt": "2026-03-08T12:00:01Z",
  "startedAt": "2026-03-08T12:00:01Z",
  "completedAt": "2026-03-08T12:00:02Z",
  "latencyMs": 842,
  "result": {
    "success": true
  }
}

If the task is not found, the scheduler returns:

{
  "code": "not_found",
  "error": "task not found"
}

Cancel A Task

curl -X POST http://localhost:9867/tasks/tsk_a1b2c3d4/cancel

curl -X POST http://localhost:9867/tasks/tsk_a1b2c3d4/cancel

{
  "status": "cancelled",
  "taskId": "tsk_a1b2c3d4"
}

Behavior:

• queued tasks are removed from the queue
• running tasks have their execution context cancelled
• terminal tasks return 409 Conflict

Task States

Implemented states:

• queued
• assigned
• running
• done
• failed
• cancelled
• rejected

Terminal states:

• done
• failed
• cancelled
• rejected

How Tasks Execute

The scheduler forwards each task to the normal tab action endpoint:

POST /tabs/{tabId}/action

It builds the action body like this:

{
  "kind": "<action>",
  "ref": "<ref>",
  "...params": "..."
}

That means:

• action becomes kind
• top-level ref is forwarded when present
• every key in params is merged into the top-level action body

Example:

curl -X POST http://localhost:9867/tasks \  -H "Content-Type: application/json" \  -d '{    "agentId": "my-agent",    "action": "type",    "tabId": "8f9c7d4e1234567890abcdef12345678",    "ref": "e12",    "params": {      "text": "Alan Turing"    }  }'

curl -X POST http://localhost:9867/tasks \  -H "Content-Type: application/json" \  -d '{    "agentId": "my-agent",    "action": "type",    "tabId": "8f9c7d4e1234567890abcdef12345678",    "ref": "e12",    "params": {      "text": "Alan Turing"    }  }'

In practice, task payloads should use the same action fields that the immediate /tabs/{id}/action route expects.

Fairness, Deadlines, And Retention

• within one agent queue, lower priority values run first
• equal-priority tasks for the same agent fall back to FIFO order
• across agents, the scheduler prefers the agent with the fewest in-flight tasks
• if a queued task passes its deadline before execution starts, it is marked failed with deadline exceeded while queued
• terminal task snapshots are retained in memory for resultTTLSec