Guarded Execution Pipeline

Guarded Execution Pipeline

Relevant source files

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

• docs/integrations/agent-hooks-and-mcp.md
• internal/execution/guarded.go
• internal/execution/guarded_test.go
• internal/execution/nix.go
• internal/execution/nix_test.go
• internal/scripts/registry.go
• internal/scripts/registry_test.go
• internal/skills/autodiscover.go
• internal/skills/skills.go
• internal/skills/skills_test.go

The Guarded Execution Pipeline is the core orchestration layer of AXIS (Layer 4: Execution Plane). It manages the transition from a user's natural language intent or raw command into a safely executed task on the optimal cluster node. This pipeline ensures that every execution is preceded by resource reservation, safety evaluation, and environment preparation, while providing real-time observability and post-execution learning.

The primary entry point for this logic is the RunGuarded function in internal/execution/guarded.go [internal/execution/guarded.go:215-215].

Execution Flow Overview

The pipeline follows a strict sequence to maintain the "Truth Rule" and cluster stability.

1. Intent Resolution and Requirement Inference

The pipeline first resolves the user's Description into an Intent [internal/execution/guarded.go:134-139]. This involves:

• Script Matching: Checking the scripts.Registry for pre-defined templates that match the description [internal/scripts/registry.go:75-99].
• Skill Retrieval: Searching the skills.Store for previously learned successful commands [internal/skills/skills.go:132-150].
• Workload Inference: If no script or skill matches, the pipeline infers hardware requirements (RAM, Tools, GPU backends) from the raw command string [internal/execution/guarded.go:55-69].

2. Placement and Safety Gating

Once requirements are known, the pipeline selects a target node:

• Deterministic Placement: The placement engine filters and ranks nodes based on the inferred TaskRequirements [internal/execution/guarded.go:275-290].
• Safety Evaluation: The safety.Evaluator inspects the command for dangerous patterns (e.g., destructive actions, privilege escalation) [internal/execution/guarded.go:61-61]. If the request lacks the required Confirm flag (YES), the execution is blocked [internal/execution/guarded.go:40-40].

3. Resource Reservation

Before the command is dispatched, a commitment is made in the reservation.Ledger [internal/execution/guarded.go:343-356].

• RAM/VRAM Locking: Memory is reserved on the target node to prevent overcommitment during the task's lifecycle.
• Heartbeat Mechanism: A background task periodically updates the ledger to signify the execution is still alive [internal/execution/guarded.go:53-58].

4. Environment Injection and Execution

The pipeline prepares the execution environment:

• AXIS_CONTEXT_FILE: A JSON file containing the current ClusterSnapshot and placement reasoning is generated and its path injected as an environment variable [internal/execution/guarded.go:375-385].
• Local vs. Remote:
  • Local: Executed via bash -lc using RunLocalShell [internal/execution/guarded.go:171-180].
  • Remote: Dispatched over SSH using transport.SSHExecutor [internal/execution/guarded.go:163-165].
• Nix Wrapper: If the target node has Nix installed, the pipeline may wrap the command in a nix shell to provide ephemeral dependencies [internal/execution/nix.go:32-103].

5. Observation and Learning

After completion, the pipeline records the outcome:

• Telemetry: Peak RAM usage (PeakRAMMB) and wall-clock time (WallTimeMS) are captured [internal/execution/guarded.go:111-113].
• Skill Reinforcement: Successful executions are recorded in the skills.Store to improve future placement and auto-routing [internal/skills/skills.go:79-129].

Technical Architecture Diagrams

Intent to Code Entity Mapping

This diagram maps the conceptual "Natural Language Intent" to the specific Go types and logic used during the resolution phase.

Conceptual Step	Code Entity / Symbol	File Reference
User Input	GuardedExecutionRequest	internal/execution/guarded.go
Template Match	scripts.Script	internal/scripts/registry.go
Past Success	skills.LearnedSkill	internal/skills/skills.go
Hardware Needs	models.TaskRequirements	internal/models/tasks.go
Execution State	PreparedExecution	internal/execution/guarded.go

graph TD
    subgraph "Natural Language Space"
        Input["User Description: 'run llama3'"]
    end

    subgraph "Code Entity Space"
        REQ["GuardedExecutionRequest"]
        INT["Intent (struct)"]
        REG["scripts.Registry"]
        SKL["skills.Store"]
        INF["InferRequirements()"]
        PREP["PreparedExecution"]
    end

    Input --> REQ
    REQ --> REG
    REQ --> SKL
    REG -- "Match" --> INT
    SKL -- "Match" --> INT
    INT -- "None Found" --> INF
    
    INT --> PREP
    INF --> PREP

Loading

Sources: internal/execution/guarded.go:72-132, internal/scripts/registry.go:26-52, internal/skills/skills.go:15-34

The Guarded Lifecycle

This diagram illustrates the sequence of operations within RunGuarded, highlighting the interaction between the safety system, the ledger, and the transport layer.

sequenceDiagram
    participant CLI as axis binary
    participant GE as execution.RunGuarded
    participant SE as safety.Evaluator
    participant RL as reservation.Ledger
    participant TX as transport.SSHExecutor
    participant SK as skills.Store

    CLI->>GE: Call RunGuarded(req)
    GE->>SE: Check(command)
    Note over SE: Applies RuleSet
    SE-->>GE: SafetyVerdict (Allow/Deny)
    
    GE->>RL: Reserve(node, ram_mb)
    RL-->>GE: LedgerExecID
    
    loop Heartbeat
        GE->>RL: Heartbeat(LedgerExecID)
    end
    
    alt isLocal
        GE->>GE: RunLocalShell()
    else isRemote
        GE->>TX: Stream(ctx, command, stdout, stderr)
    end
    
    GE->>RL: Release(LedgerExecID)
    GE->>SK: RecordSuccess(desc, cmd, node)
    GE-->>CLI: GuardedExecutionResult (NDJSON)

Loading

Sources: internal/execution/guarded.go:215-410, internal/execution/guarded.go:53-58, internal/skills/skills.go:79-88

Key Data Structures

GuardedExecutionRequest

The input configuration for the pipeline.

• Description: Natural language or raw command [internal/execution/guarded.go:73-73].
• Confirm: Must be set to YES for high-risk commands [internal/execution/guarded.go:75-75].
• MemoryRequestMB: Manual override for RAM requirements [internal/execution/guarded.go:77-77].

PreparedExecution

An internal transient state containing all context needed to launch the process.

• TargetNode: The NodeFacts of the selected host [internal/execution/guarded.go:125-125].
• ContextJSON: The serialized cluster state for AXIS_CONTEXT_FILE [internal/execution/guarded.go:124-124].
• Command: The final shell-escaped command string [internal/execution/guarded.go:122-122].

Observability and Output

The pipeline produces streaming output. When invoked via the API or CLI, it typically emits NDJSON (Newline Delimited JSON) representing the GuardedExecutionResult [internal/execution/guarded.go:90-114]. This allows clients to track:

1. Placement Reasoning: Why a specific node was chosen [internal/execution/guarded.go:102-102].
2. Safety Status: If the command was blocked or requires confirmation [internal/execution/guarded.go:103-104].
3. Resource Usage: Real-time telemetry from the process once it finishes [internal/execution/guarded.go:111-113].

Sources: internal/execution/guarded.go:1-410, internal/scripts/registry.go:1-137, internal/skills/skills.go:1-177, internal/execution/nix.go:1-157

---