Skip to content

Orchestrator and Workers

The worker system provides structured delegation for complex tasks. The Orchestrator coordinates multi-step conversation turns, while the Background Task Runner handles long-running web research independently of the main generation loop.

Orchestrator

Orchestrator (core/worker/orchestrator.py) is the primary conversational coordinator — a single orchestrator with helper worker delegation. It replaces the multi-agent loop (preserved as legacy_mode).

Flow per Conversation Turn

  1. Intent detection — The orchestrator analyzes incoming messages for patterns:
  2. _PLANNER_KEYWORDS → spawn PLANNER worker for complex task planning
  3. _SUMMARIZER_THRESHOLD (500 chars) → SUMMARIZER for long context compression

  4. memory_mode active → RETRIEVER for vector memory lookup

  5. Helper worker spawn — Workers dispatched via WorkerPool.delegate() with typed configurations

  6. Primary agent generation — Main agent generates response enriched with worker results

  7. Return result — OrchestratorResult (frozen dataclass) containing:

  8. response_text — final generated response
  9. worker_results — outputs from each helper worker
  10. correlation_id — unique trace identifier
  11. duration_ms — total turn duration
  12. primary_agent_name — which agent handled the turn
  13. worker_count — number of helper workers spawned
  14. first_token_ms — time to first generated token

Key Classes

  • Orchestrator — orchestrate() for full turn execution, delegate() for single-worker delegation
  • OrchestratorResult — Frozen result with traces and timing data
  • OrchestratorProtocol — Defined in service_protocols.py for dependency injection

Worker System

WorkerPool (core/worker/worker_system.py) manages non-speaking internal workers that communicate through typed events:

Worker Type Purpose
PLANNER Breaks complex requests into step-by-step plans
RETRIEVER Queries vector memory for relevant context
SUMMARIZER Compresses long conversation history
INDEXER Organizes and indexes knowledge bases
TOOL_PREPARER Pre-validates tool availability
REASONER Independent reasoning pass for complex logic

The worker pool provides bounded concurrency, per-type limits, token budgets, timeouts, cancellation support, and trace event publishing.

Background Task Runner

BackgroundTaskRunner (core/worker/background_task_runner.py) executes long-running operations independently of the main generation loop. Primary use case: deep web research.

Web Research Protocol

The three-phase protocol replaces title-only results with full-page deep research:

Search → Fetch → Synthesize
  1. Search — web_search returns DuckDuckGo titles and URLs only (no snippets or summaries)
  2. Fetch — fetch_url extracts full page content via curl_cffi with Chrome TLS impersonation
  3. Synthesize — Agent generates comprehensive response from full-page content

Quality Guards

Four guards prevent wasteful or redundant research:

Guard Purpose
Duplicate URL guard Won't re-fetch the same URL within a task
Near-dup query detection Avoids semantically similar search queries
Consecutive search guard Enforces fetching content between searches
Multi-topic awareness Tracks distinct topics for broad coverage

Task Queue

TaskQueue (core/worker/task_queue.py) is a bounded async queue with:

  • Priority ordering (semaphore + size limit)
  • Retry with exponential back-off
  • Per-task timeouts and cancellation
  • Result futures for async completion
  • EventBus integration for status updates
  • Bounded history retention

Telemetry

Metric Description
queue.depth Current queue depth (gauge)
queue.task_ms Task execution duration

Worker spawn/complete events publish via EventBus with correlation IDs for end-to-end tracing.

See Also