Skip to content

Advisory Layer AI Surfaces

Jump to bottom
Smithanator edited this page Jul 15, 2026 · 2 revisions

Advisory Layer: AI Surfaces

Relevant source files

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

The Advisory Layer (Layer 5) is the highest plane of the AXIS architecture. It provides AI-powered interfaces that consume cluster state to assist operators with inspection, debugging, and task automation.

In accordance with the Truth Rule, this layer is strictly advisory: AI components can read the fact plane and suggest actions, but they never possess inherent execution authority or the ability to override the deterministic state of the cluster internal/agent/agent.go:45-46. Shell and cluster execution tools (run_shell, run_on_node, axis_run_task, remote run_background) pass through the Execution Plane (Layer 4) for placement, reservation, safety scoring, and operator confirmation. File-edit tools use agent-level confirmation and path sandboxing but are not RunGuarded executions.

Relationship to Lower Layers

The Advisory Layer interacts with the system through three primary integration points:

  1. Fact Consumption: Surfaces like axis chat and the Agent consume ClusterSnapshot and NodeFacts to provide context-aware answers cmd/axis/chat.go:75-78.
  2. Tooling: The ToolRegistry provides the LLM with capabilities to invoke AXIS commands (e.g., axis_status, axis_place) and local system tools (e.g., read_file, git_diff) internal/agent/tools.go:113-143.
  3. Guarded Execution: Approved run_shell / run_on_node / axis_run_task (and remote run_background) are routed through execution.RunGuarded (or daemon /run) with local or requested-node pin, matching axis task run safety rules. Not every agent tool is a Layer-4 execution (e.g. write_file uses confirm + sandbox only).

AI-to-Code Mapping: The Advisory Plane

The following diagram bridges the natural language intent of the AI surfaces to the underlying code entities and data structures.

Diagram: Advisory Entity Mapping

graph TD
    subgraph "Natural Language Space"
        UserIntent["User: 'Why is node-alpha slow?'"]
        AgentPrompt["System Prompt: 'You are an AXIS assistant...'"]
    end

    subgraph "Code Entity Space"
        AgentStruct["Agent (internal/agent/agent.go)"]
        ToolReg["ToolRegistry (internal/agent/tools.go)"]
        Conv["Conversation (internal/chat/message.go)"]
        
        subgraph "Tools"
            StatusTool["axis_status (summarizeSnapshot)"]
            PlaceTool["axis_place (SelectBestNode)"]
            ShellTool["run_shell (RunGuarded)"]
        end
    end

    UserIntent --> AgentStruct
    AgentPrompt --> Conv
    AgentStruct --> Conv
    AgentStruct --> ToolReg
    ToolReg --> StatusTool
    ToolReg --> PlaceTool
    ToolReg --> ShellTool
Loading

Sources: internal/agent/agent.go:46-80, internal/agent/tools.go:113-143, internal/chat/message.go:38-41

Agent Framework

The Agent is a multi-turn tool-calling loop that orchestrates complex tasks. It manages a Conversation with token-budget awareness and uses a ToolRegistry to interact with the environment.

  • Autonomy Modes: Supports default, edit, and full modes to control the breadth of auto-approval for tool calls internal/agent/agent.go:90.
  • Safety Gating: Every risky tool call triggers a ConfirmFunc, which can prompt the operator for yes/no/always/never decisions internal/agent/confirm.go:14-26.
  • Context Management: Implements "Context Compaction" to truncate old tool results, keeping the conversation within LLM context limits internal/chat/message.go:106-110.

For details, see Agent Framework.

Sources: internal/agent/agent.go:1-122, internal/agent/confirm.go:1-73

Chat Interface

The axis chat command provides a cluster-aware REPL. It extends the basic LLM chat with AXIS-specific "Slash Commands" and intelligent networking.

  • Intelligent Auto-Routing: Automatically detects if a model is better suited for a remote node and establishes an SSH Tunnel to route inference to that node's local Ollama instance cmd/axis/chat.go:81-97.
  • Slash Commands: Built-in commands like /status, /facts, and /models allow the operator to bypass the LLM and query the fact plane directly cmd/axis/chat.go:52-58.
  • Persistence: Conversations are saved to ~/.axis/history/chat to allow resuming sessions cmd/axis/chat.go:109-119.

For details, see Chat Interface.

Sources: cmd/axis/chat.go:33-158

MCP Server and Client

AXIS implements the Model Context Protocol (MCP) to expose cluster state to external AI IDEs (like Cursor or Claude Desktop) and to consume tools from external MCP servers.

  • AXIS MCP Server: Exposes resources like cluster://snapshot and tools like placement_decision and ssh_connectivity_test internal/mcp/server.go:139-177.
  • Event Notifications: Uses the AXIS internal event bus to send notifications/resources/updated to MCP clients when the cluster state changes internal/mcp/server.go:117-128.
  • MCP Client: The mcpclient.Registry allows the AXIS Agent to connect to external servers, expanding its toolset beyond the built-in AXIS tools internal/agent/agent.go:121-122.

For details, see MCP Server and Client.

Sources: internal/mcp/server.go:1-137, internal/agent/agent.go:174-185

HTTP API

The HTTP API is the programmatic gateway to the Advisory Layer, used by the axis CLI and external integrations to query the daemon.

  • V1/V2 Routes: Provides endpoints for raw state (/v2/nodes), diagnostic checks (/doctor), and task execution (/run) internal/daemon/daemon.go:161.
  • Streaming: Supports NDJSON streaming for execution logs, allowing the Advisory Layer to display real-time progress of remote tasks cmd/axis/agent.go:41-42.
  • Advisory Leases: Exposes the reservation ledger so external agents can see committed resources before suggesting new workloads internal/daemon/daemon.go:89.

For details, see HTTP API.

Sources: internal/daemon/daemon.go:159-169, cmd/axis/agent.go:39-47

Advisory Flow: Intent to Execution

The following diagram illustrates how a natural language request moves from the Advisory Layer down through the Execution Plane.

Diagram: Advisory Request Lifecycle

sequenceDiagram
    participant U as Operator
    participant A as Agent (Layer 5)
    participant T as ToolRegistry
    participant E as Execution Engine (Layer 4)
    participant S as Snapshot (Layer 2)

    U->>A: "Run a benchmark on the fastest node"
    A->>T: call axis_place(description="benchmark")
    T->>S: query NodeFacts
    S-->>T: returns cluster state
    T-->>A: suggests "node-gpu-01"
    A->>U: Prompt: "Confirm run_shell on node-gpu-01?"
    U->>A: "yes"
    A->>E: RunGuarded("ssh node-gpu-01 '...'")
    E-->>U: Stream results to terminal
Loading

Sources: internal/agent/agent.go:46-80, internal/agent/tools.go:226-250, internal/execution/guarded.go:1-50

AXIS Wiki

Architecture Artifacts

DeepWiki

Clone this wiki locally