execution

package
v0.14.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 25, 2026 License: MIT Imports: 31 Imported by: 0

Documentation

Overview

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

Index

Constants

View Source 
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"
	OwnerSurfaceAgentRunOnNode = "agent-run-on-node"
	OwnerSurfaceAgentRunTask   = "agent-run-task"
)

Variables

View Source 
var GetGitRepoState = git.GetRepoState
View Source 
var IsTerminalFunc = func(r io.Reader) bool {
	f, ok := r.(*os.File)
	if !ok || f == nil {
		return false
	}
	stat, err := f.Stat()
	if err != nil {
		return false
	}
	return (stat.Mode() & os.ModeCharDevice) != 0
}
View Source 
var NewRemoteExecutor = func(nc config.NodeConfig) RemoteExecutor {
	spec := nc.SSHDialSpec()
	return transport.NewSSHExecutorFromDial(spec.Host, spec.Port, spec.User, spec.DialTimeoutSec, spec.Fallbacks)
}
View Source 
var PlanNixExecution = PlanNixWrapper
View Source 
var ProbeLocalAvailableRAMMB = probeLocalAvailableRAMMB
View Source 
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.

View Source 
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 added in v0.7.0 

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 ParseExposePorts added in v0.12.0 

func ParseExposePorts(s string) (remote, local int, err error)

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 ExecutionContextBuilder added in v0.14.3 

type ExecutionContextBuilder func(
	snap *models.ClusterSnapshot,
	st *state.ClusterState,
	decision models.PlacementDecision,
	taskDesc string,
	script any,
	skill any,
) ([]byte, error)

ExecutionContextBuilder assembles the script/skill execution-context JSON. Optional; nil yields no context.

type ExecutionEventSink added in v0.14.3 

type ExecutionEventSink interface {
	PlacementRequested(taskID string)
	PlacementDecided(taskID, node string, fitScore int, ok bool)
	ExecutionReserved(taskID, node string)
	StateChanged(taskID, node, trigger string, ok bool)
}

ExecutionEventSink receives advisory execution-lifecycle events. Optional; nil disables emission.

type GuardedExecutionRequest 

type GuardedExecutionRequest struct {
	Description      string                                                `json:"description"`
	Mode             string                                                `json:"mode,omitempty"`
	Confirm          string                                                `json:"confirm,omitempty"`
	ExposePorts      string                                                `json:"expose_ports,omitempty"`
	MemoryRequestMB  int64                                                 `json:"memory_request_mb,omitempty"`
	MemoryMaxMB      int64                                                 `json:"memory_max_mb,omitempty"`
	RequestedNode    string                                                `json:"requested_node,omitempty"`
	OwnerSurface     string                                                `json:"-"`
	OwnerLabel       string                                                `json:"-"`
	OriginOverride   models.ExecutionOrigin                                `json:"-"`
	Stdout           io.Writer                                             `json:"-"`
	Stderr           io.Writer                                             `json:"-"`
	Stdin            io.Reader                                             `json:"-"`
	OnReady          func(GuardedExecutionResult)                          `json:"-"`
	OnStateChange    func(context.Context, string, GuardedExecutionResult) `json:"-"`
	Events           ExecutionEventSink                                    `json:"-"`
	BuildContextJSON ExecutionContextBuilder                               `json:"-"`
}

type GuardedExecutionResult 

type GuardedExecutionResult struct {
	ExecID         string                      `json:"exec_id,omitempty"`
	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"`
	PeakRAMMB      int64                       `json:"peak_ram_mb,omitempty"`
	PeakVRAMMB     int64                       `json:"peak_vram_mb,omitempty"`
	WallTimeMS     int64                       `json:"wall_time_ms,omitempty"`
}

func RunGuarded 

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

func RunPreparedExecution added in v0.10.0 

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 PortForwardingRemoteExecutor added in v0.12.0 

type PortForwardingRemoteExecutor interface {
	ForwardLocal(ctx context.Context, localPort, remotePort int) (int, func(), error)
}

type PreparedExecution added in v0.10.0 

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 added in v0.10.0 

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.