QuoxEngine

Overview

QuoxEngine handles the full lifecycle of an objective: decomposition into a task DAG, agent assignment (with optional learning router override), parallel execution with heartbeat monitoring, failure recovery (guided retry, circuit breaker, fallback routing), and completion with structured results.

It is NOT a workflow engine (that's QuoxFlow). QuoxEngine handles adaptive, AI-driven objectives where the plan is created at runtime by the orchestrator LLM. QuoxFlow handles deterministic, pre-built automation pipelines.

Execution Model

The execution loop runs every 5 seconds:

1. Find running objectives — scan objectives table for status = 'running'
2. Check dependencies — skip objectives blocked by parent objectives
3. Check budget — skip if token/tool-call limits exhausted
4. Find ready tasks — tasks with all dependencies met and no pending checkpoints
5. Pipeline stage enforcement — for pipeline topology, block tasks whose stage predecessors haven't completed
6. Atomic claim — UPDATE WHERE status = 'pending' prevents double execution
7. Execute — call collector agent invoke, heartbeat every 15s
8. Record performance — success/failure, latency, tokens, quality score
9. Check completion — when all tasks are terminal, finalise the objective

scheduler.tick() → findAllReadyTasks() → claimTask() → executeTask()
  → recordPerformance() → checkObjectiveCompletion()

Topology Modes

Teams define their coordination pattern via the topology field in the manifest:

// Team manifest topology field
{
  "topology": {
    "type": "hierarchical",
    "subOrchestrators": ["system-architect", "qa-lead"],
    "maxDepth": 2
  }
}

Learning Router

After every task, QuoxEngine records the agent's performance (success, latency, tokens, quality). When decomposing future objectives, the epsilon-greedy router can override the LLM's agent assignment with a better-performing candidate.

Composite score: success_rate × 0.35 + speed × 0.20 + cost × 0.20 + quality × 0.25

Quality heuristic: base 50, +20 schema valid, +10 result length, +10 tools used, +10 first attempt

Exploration: 10% of the time, a random agent is selected instead of the best — this allows the router to discover improving agents.

Confidence ramps from 0 to 1 over 30 tasks. Until confident, the LLM's choice is respected.

Recovery & Resilience

• Crash recovery: On startup, scans for tasks stuck in 'running' with stale heartbeats. Marks as failed, triggers orchestrator kickback.
• Orphan reaper: Runs every 60 seconds. Detects tasks with no heartbeat in 2× the expected interval.
• Cancellation guard: All completion UPDATEs include WHERE status NOT IN ('cancelled', 'skipped').
• In-flight abort: AbortController registry allows external cancellation of running HTTP requests.
• Exponential backoff: 30s, 2m, 10m (configurable per team).
• Guided retry: Orchestrator reviews the failure, rewrites the prompt, tries a different approach.
• Circuit breaker: N consecutive failures → pause objective, escalate to inbox.
• Fallback routing: When retries exhausted, domain-compatible agent substituted automatically.

Policy Configuration

All policies are per-team via the manifest policies object: