System Structure

This section describes the static structure of Agent Vigilo: the CLI runtime, coordinator, worker, PostgreSQL placement model, RabbitMQ message broker, evaluator registry, and Wasmtime evaluator boundary.

Agent Vigilo is structured as a distributed AI evaluation system. Runs are created through the CLI, dispatched by coordinators, processed by workers, evaluated through isolated WASM components, persisted through routed PostgreSQL workflows, and signaled through durable outbox publication.

What This Section Covers

• Runtime boundaries: which responsibilities live in the CLI, coordinator, worker, database, broker, target agent, and evaluator packages.
• Container relationships: how PostgreSQL, RabbitMQ, workers, coordinators, and the command runtime collaborate.
• Component ownership: which subsystem owns evaluator publishing, run creation, dispatch, finalization, worker execution, result persistence, and outbox publishing.
• Isolation boundaries: how WASM evaluator execution is separated from the host by Wasmtime store limits, fuel, timeout, log caps, and worker-local concurrency permits.
• Reliability boundaries: where chunk leases, attempt authority checks, durable outbox delivery rows, RabbitMQ confirms, and idempotency keys protect state.

Structure Views

System Context

External actors and systems around Agent Vigilo, including engineers, CI/CD, agent clients, target agents, evaluator packages, PostgreSQL, and RabbitMQ.

Open Context

Container View

Deployable runtime boundaries for the CLI, coordinator, worker, database, queue, evaluator packages, and target agent integration.

Open Containers

Vigilo Components

Internal CLI and command runtime components for setup, evaluator publishing, run creation, querying, service startup, and shared runtime context.

Open Vigilo Components

Coordinator Components

Dispatch, finalization, and outbox publisher components, including durable RabbitMQ publication and ledger/queue outbox handling.

Open Coordinator Components

Worker Components

Chunk claiming, run-context caching, target-agent invocation, sandboxed WASM evaluator execution, result persistence, and message settlement.

Open Worker Components

Component Overview

Entry point for comparing CLI, coordinator, and worker internals before going into a specific component diagram.

Open Components

Current Runtime Shape

• CLI runtime parses commands, initializes shared context, applies migrations, publishes evaluators, creates runs, starts services, and renders JSON or TOON output.
• Coordinator recovers expired chunk leases, marks abandoned running attempts stale, claims coordinator leases, dispatches runnable chunks, finalizes completed runs, and publishes state-change events from the outbox delivery queue.
• Worker consumes run.chunk.ready messages, claims chunk leases, allocates due attempts with worker and message ownership, renews chunk and attempt leases, delays retry-scheduled chunks until retry_after, invokes target agents, runs evaluator bindings, persists results, and settles RabbitMQ deliveries.
• PostgreSQL placements hold control metadata and routed execution data: evaluators, datasets, runs, shard-partitioned chunks, attempts, evaluator results, execution aggregates, coordinator leases, outbox ledger rows, and hot delivery rows.
• RabbitMQ distributes worker-ready chunk messages and receives confirmed durable event publications from the outbox publisher.
• Wasmtime executes versioned WASI Preview 2 evaluator components with per-invocation store limits and a process-wide active-evaluation semaphore.

Reliability Boundaries

• Chunk ownership is guarded by database chunk status and lease timestamps.
• Attempt authority requires the current attempt id, attempt number, worker id, and live attempt lease before worker-owned terminal writes are accepted.
• Evaluator results are append-oriented evidence rows with uniqueness guards at the persistence boundary.
• Outbox publication uses a durable outbox_events ledger and a partitioned outbox_delivery_queue for hot publish work.
• RabbitMQ publication uses durable topology, persistent messages, mandatory routing, publisher confirms, and the outbox dedupe key as the AMQP message id.
• Evaluator isolation combines Wasmtime memory/table/instance limits, fuel metering, epoch timeouts, host log caps, denied outbound HTTP by default, and a worker-local semaphore.

Complete Documentation Map

Runtime behavior and state transitions are documented outside the structure section:

• Architecture landing page
• Execution flow and state model
• Failure modes
• Scale-out and shard migration
• Command flows
• Coordinator flows
• Worker flows
• Run command flows
• Evaluator command flows
• State management
• Run lifecycle
• Chunk lifecycle
• Execution lifecycle
• Outbox lifecycle
• State ownership
• Runtime limits
• Run profile configuration
• Dataset format
• Vigilo.toml evaluator manifest
• Creating evaluators
• Publishing evaluators

Reading Order

Recommended progression for new contributors:

1. System Context
2. Container View
3. Component Overview
4. Vigilo Components
5. Coordinator Components
6. Worker Components
7. State Management
8. Failure Modes

Scope

These diagrams document conceptual architecture and runtime ownership boundaries. Exact SQL queries, CLI parser details, and internal helper functions may evolve, but the boundaries here should remain aligned with the current implementation.