execution

Documentation

Overview

Package execution is EXPERIMENTAL — guarded execution path with safety gating. It is subordinate to observed state and emits warnings automatically.

Index

• Constants
• Variables
• func CanReserve(snap *models.ClusterSnapshot, node string, mb int64) bool
• func LocalExecutionOrigin(rt *runtimectx.Context) models.ExecutionOrigin
• func NormalizeRequest(req *GuardedExecutionRequest)
• func RemoteExecPrefix(node, contextPath string, extraEnv []string) string
• func ReservationMBForRequirements(reqs models.TaskRequirements) int64
• func ValidateRequest(req GuardedExecutionRequest) error
• type GuardedExecutionRequest
• type GuardedExecutionResult
  • func RunGuarded(ctx context.Context, rt *runtimectx.Context, req GuardedExecutionRequest) (GuardedExecutionResult, error)
  • func RunPreparedExecution(ctx context.Context, prepared PreparedExecution) (GuardedExecutionResult, error)
• type Intent
  • func ResolveIntent(description, mode string, skillStore *skills.Store) (Intent, error)
• type NixPlan
  • func PlanNixWrapper(node models.NodeFacts, reqs models.TaskRequirements, command string) NixPlan
• type PreparedExecution
  • func PrepareGuardedExecution(ctx context.Context, rt *runtimectx.Context, req GuardedExecutionRequest) (PreparedExecution, error)
• type RemoteExecutor
• type StreamingRemoteExecutor
• type ValidationError
  • func (e *ValidationError) Error() string

Constants

const (
	ModeScript = "script"
	ModeExec   = "exec"

	ConfirmWord = "YES"

	StateChangeExecutionReserved = "execution-reserved"
	StateChangeExecutionFinished = "execution-finished"

	OwnerSurfaceGuardedExec   = "guarded-exec"
	OwnerSurfaceTaskRun       = "task-run"
	OwnerSurfaceHTTPRun       = "http-run"
	OwnerSurfaceAgentRunShell = "agent-run-shell"
)

Variables

var NewRemoteExecutor = func(nc config.NodeConfig) RemoteExecutor {
	return transport.NewSSHExecutor(nc.Hostname, nc.EffectiveSSHPort(), nc.SSHUser, nc.EffectiveTimeout())
}

var PlanNixExecution = PlanNixWrapper

var ProbeLocalAvailableRAMMB = probeLocalAvailableRAMMB

var RunLocalShell = func(ctx context.Context, command string, env []string) ([]byte, int64, error) {

	cmd := exec.CommandContext(ctx, "bash", "-lc", command)
	cmd.Env = env
	out, err := cmd.CombinedOutput()
	return out, peakRAMFromProcessState(cmd.ProcessState), err
}

RunLocalShell executes command in a login bash shell and returns its combined output, the peak RSS of the child process in MB (0 if unavailable), and any error. The second return value is populated from cmd.ProcessState.SysUsage() after the process exits, giving per-execution accuracy.

var StreamLocalShell = func(ctx context.Context, command string, env []string, stdout, stderr io.Writer) (int64, error) {

	cmd := exec.CommandContext(ctx, "bash", "-lc", command)
	cmd.Env = env
	cmd.Stdout = stdout
	cmd.Stderr = stderr
	err := cmd.Run()
	return peakRAMFromProcessState(cmd.ProcessState), err
}

StreamLocalShell executes command in a login bash shell, streaming output to the supplied writers. Returns the peak RSS in MB (0 if unavailable) and any error.

Functions

func CanReserve

func CanReserve(snap *models.ClusterSnapshot, node string, mb int64) bool

func LocalExecutionOrigin

func LocalExecutionOrigin(rt *runtimectx.Context) models.ExecutionOrigin

LocalExecutionOrigin derives the trusted local AXIS execution origin from the current runtime context.

func NormalizeRequest

func NormalizeRequest(req *GuardedExecutionRequest)

func RemoteExecPrefix

func RemoteExecPrefix(node, contextPath string, extraEnv []string) string

func ReservationMBForRequirements

func ReservationMBForRequirements(reqs models.TaskRequirements) int64

func ValidateRequest

func ValidateRequest(req GuardedExecutionRequest) error

Types

type GuardedExecutionRequest

type GuardedExecutionRequest struct {
	Description    string                                                `json:"description"`
	Mode           string                                                `json:"mode,omitempty"`
	Confirm        string                                                `json:"confirm,omitempty"`
	OwnerSurface   string                                                `json:"-"`
	OwnerLabel     string                                                `json:"-"`
	OriginOverride models.ExecutionOrigin                                `json:"-"`
	Stdout         io.Writer                                             `json:"-"`
	Stderr         io.Writer                                             `json:"-"`
	OnReady        func(GuardedExecutionResult)                          `json:"-"`
	OnStateChange  func(context.Context, string, GuardedExecutionResult) `json:"-"`
}

type GuardedExecutionResult

type GuardedExecutionResult struct {
	OK             bool                        `json:"ok"`
	Description    string                      `json:"description"`
	Mode           string                      `json:"mode,omitempty"`
	Intent         string                      `json:"intent,omitempty"`
	Command        string                      `json:"command,omitempty"`
	Node           string                      `json:"node,omitempty"`
	Tool           string                      `json:"tool,omitempty"`
	Workload       models.WorkloadProfileMatch `json:"workload,omitempty"`
	FitScore       int                         `json:"fit_score,omitempty"`
	IsLocal        bool                        `json:"is_local,omitempty"`
	Reasoning      []string                    `json:"reasoning,omitempty"`
	Blocked        bool                        `json:"blocked,omitempty"`
	BlockReason    string                      `json:"block_reason,omitempty"`
	DumbScore      int                         `json:"dumb_score,omitempty"`
	Output         string                      `json:"output,omitempty"`
	Error          string                      `json:"error,omitempty"`
	ExitCode       int                         `json:"exit_code,omitempty"`
	SnapshotStatus models.SnapshotStatus       `json:"snapshot_status,omitempty"`
	Summary        *models.ClusterSummary      `json:"summary,omitempty"`
}

func RunGuarded

func RunGuarded(ctx context.Context, rt *runtimectx.Context, req GuardedExecutionRequest) (GuardedExecutionResult, error)

func RunPreparedExecution

func RunPreparedExecution(ctx context.Context, prepared PreparedExecution) (GuardedExecutionResult, error)

type Intent

type Intent struct {
	Command       string
	Label         string
	MatchedScript *scripts.Script
	MatchedSkill  *skills.LearnedSkill
}

func ResolveIntent

func ResolveIntent(description, mode string, skillStore *skills.Store) (Intent, error)

type NixPlan

type NixPlan struct {
	Enabled  bool
	Command  string
	Packages []string
	Env      []string
	Notes    []string
}

func PlanNixWrapper

func PlanNixWrapper(node models.NodeFacts, reqs models.TaskRequirements, command string) NixPlan

type PreparedExecution

type PreparedExecution struct {
	Request       GuardedExecutionRequest
	Intent        Intent
	Requirements  models.TaskRequirements
	Result        GuardedExecutionResult
	ReservationMB int64
	Command       string
	ExtraEnv      []string
	ContextJSON   []byte
	TargetNode    models.NodeFacts
	TargetConfig  config.NodeConfig
	Owner         state.ExecutionOwner
	SkillStore    *skills.Store
	State         *state.ClusterState
	Ledger        *reservation.Ledger
	Err           error
}

func PrepareGuardedExecution

func PrepareGuardedExecution(ctx context.Context, rt *runtimectx.Context, req GuardedExecutionRequest) (PreparedExecution, error)

type RemoteExecutor

type RemoteExecutor interface {
	Run(context.Context, string) (string, error)
	Close() error
}

type StreamingRemoteExecutor

type StreamingRemoteExecutor interface {
	RemoteExecutor
	Stream(context.Context, string, io.Writer, io.Writer) error
}

type ValidationError

type ValidationError struct {
	Message string
}

func (*ValidationError) Error

func (e *ValidationError) Error() string