Scheduler

Scarab-Runtime includes a cost-aware and deadline-aware scheduler that manages agent priorities and enforces per-agent budgets.

Overview

The scheduler tracks:

• Token cost accumulated by each agent (from lm.complete and other cost-bearing tools)
• Deadlines set by operators or agents
• Priority (1–100, higher = higher priority)
• Budget (maximum allowed cost before the agent is paused or terminated)

Viewing Stats

# Global stats: tool cost totals + all agent summaries
ash scheduler stats

# Per-agent info
ash scheduler info <agent-id>

Output includes: current priority, cost accumulated, deadline (if set), and budget usage.

Setting a Deadline

ash scheduler set-deadline <agent-id> 2026-12-31T00:00:00Z

Deadlines must be in RFC3339 format. The scheduler boosts the priority of agents approaching their deadline automatically.

Clearing a Deadline

ash scheduler clear-deadline <agent-id>

Setting Priority

ash scheduler set-priority <agent-id> 80

Priority range: 1–100. Default: 50. Higher priority agents get preferential tool dispatch when the system is under load.

Budget Enforcement

Declare a cost budget in the manifest:

spec:
  resources:
    # (budget is declared via scheduler config, not manifest resources directly)

When an agent exceeds its budget, the scheduler emits an anomaly event and optionally pauses the agent pending operator review.

Deadline Priority Boost

The scheduler continuously monitors deadlines. As an agent's deadline approaches:

• >1h remaining: normal priority
• 30min–1h: priority boosted by 10
• <30min: priority boosted by 25
• Past deadline: anomaly event generated; agent priority set to maximum

User-declared deadlines take priority over agent-declared deadlines.

Tool Cost Tracking

Each built-in tool has an estimated_cost field (fractional units). The scheduler accumulates cost per agent and per tool type. Use ash scheduler stats to see cost breakdowns.