engine

type AIExecutor struct{}

type AgentCloudBackend struct {
	Provider string `json:"provider"`
	Bucket   string `json:"bucket"`
	Prefix   string `json:"prefix,omitempty"`
	Object   string `json:"object,omitempty"`
	Region   string `json:"region,omitempty"`
	Endpoint string `json:"endpoint,omitempty"`
}

type AgentTransferEndpoint struct {
	Record hosts.Record `json:"record"`
	Path   string       `json:"path"`
}

type AgentTransferEvent struct {
	Stage     string    `json:"stage"`
	Host      string    `json:"host,omitempty"`
	Success   bool      `json:"success"`
	Message   string    `json:"message,omitempty"`
	Error     string    `json:"error,omitempty"`
	Attempt   int       `json:"attempt,omitempty"`
	Timestamp time.Time `json:"timestamp"`
}

type AgentTransferExecutor struct{}

type AgentTransferJob struct {
	SSHUser                 string                `json:"ssh_user"`
	ResolvedSourceUser      string                `json:"resolved_source_user"`
	ResolvedDestUser        string                `json:"resolved_dest_user"`
	AgentLocalAbs           string                `json:"agent_local_path"`
	SourceAgentLocalAbs     string                `json:"source_agent_local_path,omitempty"`
	DestAgentLocalAbs       string                `json:"dest_agent_local_path,omitempty"`
	AgentRemoteDir          string                `json:"agent_remote_dir,omitempty"`
	Source                  AgentTransferEndpoint `json:"source"`
	Destination             AgentTransferEndpoint `json:"destination"`
	Cloud                   AgentCloudBackend     `json:"cloud"`
	CredentialProvider      string                `json:"credential_provider,omitempty"`
	CredentialEnv           map[string]string     `json:"credential_env,omitempty"`
	CredentialExpiresAtUnix int64                 `json:"credential_expires_at_unix,omitempty"`
	KeepObject              bool                  `json:"keep_object,omitempty"`
	MaxRetries              int                   `json:"max_retries,omitempty"`
	// FallbackPlan is non-nil when the curl-based presigned-URL transport should be
	// used instead of the staged-agent path. See docs/superpowers/specs/2026-05-12-presigned-url-transfer-path-design.md.
	FallbackPlan          *presign.Plan `json:"-"`
	FallbackCapabilitySrc string        `json:"-"`
	FallbackCapabilityDst string        `json:"-"`
	// RetryWithAgentOnCurlFailure controls whether a fallback-path failure transparently
	// retries via the agent path.
	RetryWithAgentOnCurlFailure bool `json:"retry_with_agent_on_curl_failure,omitempty"`
}

type AgentTransferValidationError struct {
	// contains filtered or unexported fields
}

type AppDialerTransport string

type BatchOptions struct {
	MaxConc        int
	Cache          *ClientCache
	RecipeKV       *RecipeKVCoordinator
	RecipeScopedKV bool
	Post           SSHPostHostResultFunc
	RetryCfg       cuetry.RecipeStepRetry
	Obs            metrics.Observer
	AttemptMax     *atomic.Int32
	Reg            hostexec.Registry
	// CmdTimeout bounds each per-host remote command; 0 means no timeout. On
	// expiry the SSH session is closed (best-effort kill) and the host result
	// is marked failed/timed-out.
	CmdTimeout time.Duration
	// MaxOutputBytes limits the captured output per host. 0 = default (6000), < 0 = unlimited.
	MaxOutputBytes int
}

type BiometricVerifier interface {
	VerifyToken(actor, token string) bool
}

type CacheStats struct {
	Hits         int64
	Misses       int64
	RaceHits     int64
	DialAttempts int64
	DialErrors   int64
}

type ClientCache struct {
	// contains filtered or unexported fields
}

type ClientLease struct {
	// contains filtered or unexported fields
}

type CloudBackendRef struct {
	Kind  string `json:"kind"`
	Name  string `json:"name,omitempty"`
	Index *int   `json:"index,omitempty"`
}

type CommandExecutor struct{}

type CommandRunRequest struct {
	Command        string
	IsScript       bool
	FileExtension  string
	ScriptOpts     ScriptUploadRunOptions
	Target         *hostapi.SearchHostsInput
	Records        []hosts.Record // bypasses Target resolution if populated
	SSHUser        string
	ActorID        string
	AISystemPrompt string
	RecordSession  bool
	RecordLabel    string
	CmdTimeout     time.Duration
	MaxOutputBytes int
}

type CommandRunner struct {
	// contains filtered or unexported fields
}

type CommandRunnerOptions struct {
	ExecRegistry   hostexec.Registry
	SearchRegistry *searchrun.Registry // required for host resolution
	Metrics        metrics.Observer
	RecordDir      string // "" disables session recording
}

type CueRecipeRunParams struct {
	Recipe         cuetry.Recipe
	RecipeDir      string
	Records        []hosts.Record
	SSHUser        string
	ActorID        string // caller identity for OPA policy input; "" resolves to "api"
	CLIEnv         map[string]string
	ConfigPath     string
	AISystemPrompt string
	SecretResolver cuetry.SecretResolver
	PluginMgr      *plugins.Manager
	Execute        bool
	JSON           bool
	Reg            hostexec.Registry
	Obs            metrics.Observer
	Pools          *postgres.PoolManager
	Cache          *ClientCache     // optional shared cache; nil = create a fresh per-run cache
	Enforcer       *policy.Enforcer // optional OPA host-filter gate; nil = allow all
	Inventory      config.Inventory // config inventory; resolved per-host into OPA host_vars
	CmdTimeout     time.Duration    // per-host command timeout; 0 = none
}

type CueRun struct {
	Params            CueRecipeRunParams
	Cache             *ClientCache
	RecipeKV          *RecipeKVCoordinator
	TunnelCoord       *RecipeTunnelCoordinator
	DockerPluginSess  *plugins.DockerHostSession
	OutputStore       *cuetry.StepOutputStore
	OutputCapture     *cuetry.RecipeOutputCapture
	Facts             map[string]map[string]any
	TriggeredHandlers map[string]bool
}

type DockerExecutor struct{}

type DockerNativeClient = dockerprovider.DockerNativeClient

type ErrPendingApproval struct {
	ID     string
	Reason string
}

type Event interface {
	Kind() EventKind
}

type EventKind string

type EventStepCompleted struct {
	StepIdx int
}

type EventStepFailed struct {
	StepIdx int
	Error   error
}

type EventStepStarted struct {
	StepIdx int
}

type EventStepStderr struct {
	StepIdx int
	Output  []byte
}

type EventStepStdout struct {
	StepIdx int
	Output  []byte
}

type ExecutionOptions struct {
	Execute           bool
	JSON              bool
	Recipe            cuetry.Recipe
	RecipeDir         string
	SSHUser           string
	ActorID           string
	CLIEnv            map[string]string
	AISystemPrompt    string
	SecretResolver    cuetry.SecretResolver
	PluginMgr         *plugins.Manager
	Obs               metrics.Observer
	Cache             *ClientCache
	RecipeKV          *RecipeKVCoordinator
	ConfigPath        string
	Enforcer          *policy.Enforcer
	Inventory         config.Inventory
	CmdTimeout        time.Duration
	Reg               hostexec.Registry
	Pools             *postgres.PoolManager
	Records           []hosts.Record
	OutputStore       *cuetry.StepOutputStore
	OutputCapture     *cuetry.RecipeOutputCapture
	Facts             map[string]map[string]any
	TriggeredHandlers map[string]bool
	TunnelCoord       *RecipeTunnelCoordinator
	// DockerPluginSess scopes remote runtime:docker plugin containers to the
	// run (one shim-container per plugin+host, torn down at run end). nil on
	// paths that never run remote docker plugins.
	DockerPluginSess *plugins.DockerHostSession
}

type ExecutionRequest struct {
	Targets    []TargetContext
	Index      int
	Step       cuetry.Step
	Kind       string
	RetryCfg   cuetry.RecipeStepRetry
	AttemptMax *atomic.Int32
	History    [][]HostExecResult
}

type Executor = hostexec.Executor

type GetExecutor struct{}

type GlobalTunnelPool struct {
	// contains filtered or unexported fields
}

type HostClient = hostexec.HostClient

type HostClientTransferNode struct {
	// contains filtered or unexported fields
}

type HostExecResult struct {
	Name     string
	IP       string
	Provider string
	Success  bool
	Skipped  bool
	Changed  bool
	ExitCode int
	Output   string
	// Stdout is the step's raw stdout only, with no stderr mixed in — unlike
	// Output, which concatenates stdout+stderr for human display. Only
	// populated by executors that keep the two streams genuinely separate
	// internally (currently: plugin steps, via apiv1.ExecuteStepOutput);
	// empty otherwise (e.g. command/script steps, whose HostClient.Run
	// returns one already-merged stream from the SSH session — there is no
	// separate stdout to recover there). env_from/stepStdout consumers
	// should prefer this over Output when non-empty, since a step whose
	// process logs diagnostics to stderr (common, not a bug in the process)
	// would otherwise corrupt output_format: "json" parsing downstream.
	Stdout        string
	OutputCapture string
	// KVCaptureKey is set when a step wrote its output to the recipe KV store
	// (e.g. plugin.kv_key) instead of a named output capture. Unlike
	// OutputCapture, run.go's graph dispatch never overwrites this field, so
	// it survives to CueRecipeDisplayOutput to suppress the raw dump.
	KVCaptureKey string
	ErrMsg       string
	IsTransient  bool

	StepIndex int    `json:",omitempty"`
	StepID    string `json:",omitempty"`
	StepKind  string `json:",omitempty"`

	HookPhase  string
	HookOutput string
	HookFailed bool
}

type HostExecRetryOutcome struct {
	Result              HostExecResult
	Attempts            int
	LastAttemptDuration time.Duration
}

type HostTransport interface {
	RunCommand(ctx context.Context, user string, tc TargetContext, cache *ClientCache, kvTunnel bool, cmd SSHRemoteCmdFunc, opts BatchOptions) HostExecResult
}

type K8sExecutor struct{}

type K8sNativeClient = k8sprovider.K8sNativeClient

type K8sPodExecutor = k8sprovider.K8sPodExecutor

type KVTunnelProvider interface {
	SupportsKVTunnel() bool
}

type OPAExecutor struct{}

type OpensearchExecutor struct{}

type PackageExecutor struct{}

type PluginExecutor struct{}

type PluginLifecycle string

type PostgresExecutor struct{}

type PutExecutor struct{}

type RecipeExecutor struct{}

type RecipeKVCoordinator struct {
	// contains filtered or unexported fields
}

type RecipeMeta struct {
	RecipePath        string                  `json:"recipe_path"`
	HostCount         int                     `json:"host_count"`
	RecipeContentHash string                  `json:"recipe_content_hash"`
	StartedAt         time.Time               `json:"started_at"`
	Hosts             []hosts.Record          `json:"hosts,omitempty"`
	Plan              string                  `json:"plan,omitempty"`
	Graph             *cuetry.RecipeGraphPlan `json:"graph,omitempty"`
}

type RecipeRunner struct {
	// contains filtered or unexported fields
}

type RecipeTunnelCoordinator struct {
	// contains filtered or unexported fields
}

type RemoteFileEntry = hostexec.RemoteFileEntry

type RiskStepFilter struct {
	// contains filtered or unexported fields
}

type RunParams struct {
	Recipe         cuetry.Recipe
	RecipeDir      string
	Records        []hosts.Record
	SSHUser        string
	Execute        bool
	CliEnv         map[string]string
	ConfigPath     string
	SecretResolver cuetry.SecretResolver
	PluginMgr      *plugins.Manager
}

type RunReporter struct {
	// contains filtered or unexported fields
}

type RunRequest struct {
	Recipe           cuetry.Recipe
	RecipeSourcePath string
	RecipeDir        string
	Target           *hostapi.SearchHostsInput
	Records          []hosts.Record // bypasses Target resolution if populated
	SSHUser          string
	// Source names the ingress that initiated this run ("web", "webhook",
	// "scheduler"); recorded on the recipe_run admission audit event.
	Source string
	// ActorID is the caller identity (JWT subject or trusted-proxy header),
	// used as OPA policy input. Empty resolves to "api" downstream.
	ActorID string
	// ApprovalID references a previously-created approval that, once approved,
	// lets a require_approval recipe proceed.
	ApprovalID string
	// BiometricToken is a WebAuthn step-up token that satisfies a require_biometric
	// verdict for the actor.
	BiometricToken string
	Env            map[string]string
	AISystemPrompt string
	RecordSession  bool
	RecordLabel    string
	// CmdTimeout bounds each per-host remote command; 0 = no timeout.
	CmdTimeout time.Duration
	// Recorder, when non-nil, is used as-is and NOT closed by the runner (the
	// caller owns its lifecycle — needed by the async webhook, which must know
	// the recording ID before deferred execution). When nil and RecordSession
	// is true, the runner opens and closes its own recorder.
	Recorder *SessionRecorder

	PluginPolicy PluginLifecycle
}

type RunnerOptions struct {
	ConfigPath     string
	Config         *config.File
	ExecRegistry   hostexec.Registry
	SearchRegistry *searchrun.Registry // required for host resolution
	Metrics        metrics.Observer
	Pools          *postgres.PoolManager
	Cache          *ClientCache       // optional shared SSH client cache; nil = per-run cache
	PluginCache    *plugincache.Cache // optional shared plugin manager; nil = fresh manager per run
	RecordDir      string             // "" disables session recording
	Enforcer       *policy.Enforcer   // optional OPA admission gate; nil = allow all
	Approvals      *approval.Store    // optional pending-approval store; nil = require_approval hard-denies
	Biometric      BiometricVerifier  // optional WebAuthn token verifier; nil = require_biometric hard-denies
	AuditSink      audit.Sink         // optional; nil = no recipe_run admission audit
}

type SFTPDownloadJob struct {
	Record    hosts.Record
	RemoteAbs string
	LocalAbs  string
}

type SSHPostHostResultFunc func(ctx context.Context, tc TargetContext, res *HostExecResult)

type SSHRemoteCmdFunc func(tc TargetContext, kv map[string]string) string

type ScriptExecutor struct{}

type ScriptUploadRunOptions struct {
	ScriptInterpreter     string
	InterpreterArgsQuoted bool
	RemoveRemoteFile      bool
	// ScriptArgs are positional arguments passed to the script (Rundeck-style),
	// shell-quoted and appended after the interpreter/path.
	ScriptArgs []string
	// RunAs wraps the run step in sudo for that user (empty = run as the SSH user).
	RunAs string
}

type ServiceExecutor struct{}

type SessionRecorder struct {
	// contains filtered or unexported fields
}

type SessionRecorderOptions struct {
	Dir      string
	Trigger  string
	Mode     string
	Provider string
	HostName string
	HostIP   string
	User     string
	// HostSegment, when set, is used for the filename segment instead of HostName/IP (e.g. batch-12).
	HostSegment string
}

type StepEnvResolver interface {
	Resolve(ctx context.Context, step *cuetry.StepBase, target *hosts.Record, resolveSecrets, dryRun bool) (map[string]string, error)
}

type StepExecutor interface {
	// ExecuteDryRun performs a dry run of the step, writing its plan to out.
	ExecuteDryRun(ctx context.Context, req ExecutionRequest, opts ExecutionOptions, out io.Writer) error

	// ExecuteStream performs actual execution of the step, sending results to resCh.
	ExecuteStream(ctx context.Context, req ExecutionRequest, opts ExecutionOptions, resCh chan<- HostExecResult) error
}

type StepFilter interface {
	Filter(ctx context.Context, targets []hosts.Record) (allowed []hosts.Record, skipped []HostExecResult, err error)
}

type StepFilterPipeline struct {
	// contains filtered or unexported fields
}

type StepRisk struct {
	StepIndex   int                  `json:"step_index"`
	Kind        string               `json:"kind"`
	Host        string               `json:"host,omitempty"`
	Command     string               `json:"command,omitempty"`
	Interpreter string               `json:"interpreter,omitempty"`
	Analysis    commandrisk.Analysis `json:"analysis"`
	Decision    *policy.Decision     `json:"decision,omitempty"`
}

type SummarizeExecutor struct{}

type TargetContext struct {
	Record hosts.Record
	Env    map[string]string
}

type TemplateExecutor struct{}

type TransferNode interface {
	// HostLabel returns the display label for the node.
	HostLabel() string

	// Record returns the underlying inventory record.
	Record() hosts.Record

	// StageAgent ensures the agent binary is staged on the node.
	// Returns a boolean indicating if an upload actually occurred, a reason string, and an error.
	StageAgent(ctx context.Context, localAgentPath, remoteAgentPath string) (uploaded bool, reason string, err error)

	// RunAgentSession starts the agent binary in session mode over the transport streams.
	RunAgentSession(ctx context.Context, agentPath string, mintJWE func(string) (string, error), ops []agentSessionHostMsg) (jwe string, err error)

	// CleanupAgent removes the ephemeral agent binary from the node.
	CleanupAgent(ctx context.Context, agentPath string) error

	// RunScript executes a raw script on the node (used for the fallback path).
	RunScript(ctx context.Context, script string) (string, error)
}

type TunnelEndpoint struct {
	Host       string
	Port       int
	Mode       string
	TunName    string
	RemoteHost string
	RemotePort int
	ShareKey   string
}

type TunnelExecutor struct{}