Events Knowledge and Observability

Events, Knowledge, and Observability

Relevant source files

The following files were used as context for generating this wiki page:

• cmd/axis/main_test.go
• docs/lifecycle.md
• internal/api/main_test.go
• internal/events/events.go
• internal/events/webhooks.go
• internal/events/webhooks_test.go
• internal/git/doc.go
• internal/git/git.go
• internal/git/git_test.go
• internal/knowledge/context.go
• internal/knowledge/context_test.go
• internal/knowledge/execution.go

The Events, Knowledge, and Observability systems in AXIS provide the telemetry and context necessary for both automated orchestration and human-in-the-loop oversight. AXIS utilizes an asynchronous event bus for lifecycle tracking, a structured knowledge aggregator for agentic context, and webhook integration for external observability.

System Interconnectivity

The following diagram illustrates how raw system events flow into the event bus, are recorded for observability, and how the state is aggregated into a ClusterKnowledge object for the advisory layer.

Event and Knowledge Flow

graph TD
    subgraph "Code Entity Space"
        [internal/events] --> |"notifyListeners()"| L["Listener (fn)"]
        [internal/events] --> |"dispatchWebhooks()"| W["Webhook Target"]
        [internal/knowledge] --> |"Build()"| CK["ClusterKnowledge (struct)"]
    end

    subgraph "Natural Language Space"
        E["Lifecycle Events"] --> [internal/events]
        S["Cluster Snapshot"] --> [internal/knowledge]
        G["Git Repo State"] --> [internal/knowledge]
        K["Cluster Knowledge"] --> A["AI Agent / Safety System"]
    end

    [internal/events] -.-> |"Event Names"| E
    CK -.-> |"Context for Agents"| K

Loading

Sources: [internal/events/events.go:152-170](), [internal/knowledge/context.go:25-61]()

---

8.1 Event Bus and Webhooks

AXIS implements an in-process, asynchronous event bus within the internal/events package. This bus decouples the core execution logic from observability consumers like logging, webhooks, and the Cortex coordination layer.

Event Lifecycle

Events are defined by string constants representing major state transitions in the cluster.

• Task Execution: Tracks the journey from task.placement.requested through task.execution.started to task.execution.finished [internal/events/events.go:34-53]().
• Reservations: Tracks resource commitments via reservation.granted and reservation.released [internal/events/events.go:56-65]().
• Daemon/Snapshot: Monitors the health of the background refresh cycle via daemon.refresh.post [internal/events/events.go:68-77]().

Webhook Dispatcher

The system supports operational event dispatching via HTTP POST to registered URLs.

• Retries: The dispatcher implements an exponential backoff strategy, attempting delivery up to 4 times [internal/events/webhooks.go:64-94]().
• Dead-Letter Logs: If a webhook fails all retry attempts, the event is written to a local webhook-deadletter.jsonl file for auditing [internal/events/webhooks.go:105-136]().

For implementation details on listeners and Cortex propagation, see Event Bus and Webhooks.

Sources: [internal/events/events.go:1-53](), [internal/events/webhooks.go:39-62](), [internal/events/webhooks.go:105-136]()

---

8.2 Cluster Knowledge and Context

The internal/knowledge package is responsible for aggregating raw cluster state into a high-level, queryable context. This "Knowledge" is the primary source of truth for the AI Advisory layer (Layer 5).

Knowledge Aggregation

The ClusterKnowledge struct acts as a unified view of the system at a specific point in time, combining:

• Snapshots: The full ClusterSnapshot including resource availability [internal/knowledge/context.go:15]().
• Reservations: An overlay of the reservation.Ledger onto the snapshot to show actual allocatable RAM [internal/knowledge/context.go:30]().
• Workload Metadata: System load (Load1M) and Ollama backend status for each node [internal/knowledge/context.go:17-18]().
• Git Context: If the command is run within a repository, AXIS includes branch, commit, and dirty file status via git.GetRepoState [internal/knowledge/context.go:39-52]().

Execution Context

When a task is executed, AXIS generates an ExecutionContextJSON payload. This provides the task-specific environment, including the placement decision, the task description, and any relevant learned skills or scripts [internal/knowledge/execution.go:13-42]().

Knowledge Mapping

graph LR
    subgraph "Code Entities"
        NF["models.NodeFacts"]
        RS["state.NodeState"]
        GS["git.RepoState"]
        CK["knowledge.ClusterKnowledge"]
    end

    subgraph "Logical Context"
        NF --> |"Hardware/Load"| CK
        RS --> |"Reservations"| CK
        GS --> |"Workspace Info"| CK
    end

Loading

Sources: [internal/knowledge/context.go:13-21](), [internal/knowledge/execution.go:13-42](), [internal/git/git.go:14-24]()

For details on how context is formatted for external agents, see Cluster Knowledge and Context.

Sources: [internal/knowledge/context.go:25-61](), [internal/knowledge/execution.go:10-42]()

---