Task Management Commands

Task Management Commands

Relevant source files

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

• cmd/axis/context.go
• cmd/axis/main.go
• cmd/axis/observations.go
• cmd/axis/observations_test.go
• cmd/axis/reservations.go
• cmd/axis/reservations_test.go
• cmd/axis/task.go
• cmd/axis/task_test.go
• cmd/axis/testdata/task_context_turboquant.golden
• cmd/axis/testdata/task_place_turboquant_json.golden
• cmd/axis/turboquant_contract_test.go

The task management surface in AXIS provides the tools for workload scheduling, guarded execution, and post-execution observability. It bridges the gap between raw cluster facts and actual workload performance by using deterministic placement and resource reservations.

Task Placement and Planning

The axis task place command serves as an advisory scheduling engine. It analyzes a task description, infers requirements (such as RAM, GPU, or specific tools), and selects the optimal node from a ClusterSnapshot.

Implementation Details

Placement planning is orchestrated by planTaskPlacement cmd/axis/task.go:147-160, which can utilize either a live discovery or a cached daemon snapshot. The decision process involves:

1. Workload Inference: Parsing the natural language description into TaskRequirements.
2. Filtering: Removing nodes that lack required tools or sufficient RAM.
3. Ranking: Scoring eligible nodes based on resource availability, memory topology (e.g., Unified Memory), and "TurboQuant" capabilities for LLM workloads.

Code Entity Mapping: Placement Data Flow

The following diagram illustrates how a placement request moves from the CLI into the core models.

Placement Request Flow

graph TD
    subgraph "CLI Layer"
        A["axis task place [desc]"] --> B["planTaskPlacement()"]
    end

    subgraph "Code Entity Space"
        B --> C["daemon.FetchSnapshot()"]
        B --> D["placement.Explain()"]
        D --> E["models.PlacementDecision"]
    end

    subgraph "Logic Entities"
        E --> F["models.TaskRequirements"]
        F --> G["models.WorkloadClass"]
    end

Loading

Sources: cmd/axis/task.go:78-87, cmd/axis/task.go:147-160, cmd/axis/task.go:57-60

Task Execution and Resource Reservation

The axis task run command implements Guarded Execution. Unlike a raw shell command, it validates safety rules and commits resources to the reservation.Ledger before dispatching the task.

Execution Lifecycle

1. Intent Resolution: resolveTaskRunIntent cmd/axis/task.go:185-241 determines if the input is a raw command, a known script, or a learned skill.
2. Safety Gating: The command is passed through the execution.PrepareGuardedExecution cmd/axis/task.go:34 pipeline.
3. Reservation: If the task requires significant RAM (e.g., LLM inference), AXIS attempts to reserve capacity. reservationMBForRequirements cmd/axis/task.go:174-176 calculates the needed memory, typically adding a 25% headroom cmd/axis/task_test.go:208-213.
4. Dispatch: The task is executed locally or via SSHExecutor for remote nodes.

Resource Ledger

The cluster's active commitments are managed via the reservations command group. The reservation.Ledger tracks reservation.Entry objects cmd/axis/reservations.go:92-101, which include the owner PID, RAM requirements, and heartbeats to detect stale executions.

Execution Guardrail Architecture

graph TD
    subgraph "Execution Surface"
        RUN["axis task run"] --> INTENT["resolveTaskRunIntent()"]
        INTENT --> PREP["execution.PrepareGuardedExecution()"]
    end

    subgraph "Resource Control"
        PREP --> LEDGER["reservation.Ledger.Reserve()"]
        LEDGER --> SNAP["models.ClusterSnapshot (with reservations)"]
    end

    subgraph "Dispatch"
        PREP --> LOCAL["bash"]
        PREP --> REMOTE["SSHExecutor"]
    end

Loading

Sources: cmd/axis/task.go:185-200, cmd/axis/reservations.go:92-101, cmd/axis/task.go:178-183

Context and Observability

AXIS maintains a feedback loop where past executions inform future placement decisions.

Task Context

The axis task context command generates a "System Prompt" block used to ground AI agents in cluster reality. It includes the turboQuantCapabilityMatrix cmd/axis/task_test.go:146-151 and detailed node-level allocatable RAM.

Execution Observations

Post-execution, AXIS records models.ExecutionObservation cmd/axis/observations.go:40-43. These observations track:

• WallTimeMS: Actual duration of the task.
• PeakRAMMB: Highest memory usage recorded.
• SampleCount: Number of times this specific (Node, Workload, Tool) triplet has been seen.

This data is persisted in ~/.axis/state.json and is retrieved via state.Load() cmd/axis/observations.go:32.

Command Reference Table

Command	Purpose	Key Function/Struct
axis task place	Advisory node selection	planTaskPlacement
axis task run	Guarded workload execution	execution.RunPreparedExecution
axis task context	LLM-ready cluster state	buildContextBlock
axis task history	View previous executions	state.ClusterState.ActiveExecs
axis observations	Performance telemetry	models.ExecutionObservation
axis reservations	Active resource commitments	reservation.Ledger

Sources: cmd/axis/task.go:44-55, cmd/axis/observations.go:18-29, cmd/axis/reservations.go:29-45, cmd/axis/context.go:12-16

Diagnostic Reasoning

When a placement or execution fails, AXIS provides structured reasoning. The PlacementDecision struct contains a Reasoning slice cmd/axis/task.go:111-113 that details why nodes were skipped (e.g., "insufficient RAM", "missing tool: nvcc"). For LLM tasks, it specifically highlights TurboQuant verification status cmd/axis/testdata/task_place_turboquant_json.golden:20-21.

Sources: cmd/axis/task.go:106-115, cmd/axis/testdata/task_place_turboquant_json.golden:1-47

---