launcher

Documentation

Overview

Package launcher orchestrates agent discovery, sandbox setup, and process execution.

Index

• Variables
• func CleanStale() error
• func CleanStaleIn(base string) error
• func EmitSignpost(w io.Writer)
• func IsFirstRun() bool
• func IsKnownAgent(name string) bool
• func ResolveAgentModule(agentName string) seatbelt.Module
• func ShouldShowSignpost(exitCode int, signal string) bool
• func YoloArgs(agentName string) ([]string, error)
• type DiagnoseExecer
  • func (d *DiagnoseExecer) Run(binary string, args []string, env []string) (*RunResult, error)
• type DiagnoseRunner
• type EmptyStateActions
• type Execer
• type Launcher
  • func (l *Launcher) Launch(cwd string, agentOverride string, extraArgs []string, cleanEnv bool, ...) error
  • func (l *Launcher) Passthrough(cwd string, agentOverride string, extraArgs []string) error
• type LookPathFunc
• type PassthroughResult
  • func ScanAgents(lookPath LookPathFunc) *PassthroughResult
• type RunResult
• type RuntimeDir
  • func NewRuntimeDir() (*RuntimeDir, error)
  • func (r *RuntimeDir) Cleanup() error
  • func (r *RuntimeDir) Path() string
  • func (r *RuntimeDir) RegisterSignalHandlers() context.CancelFunc
• type SyscallExecer
  • func (s *SyscallExecer) Exec(binary string, args []string, env []string) error

Variables

var ErrEmptyStateActionRanReloadNeeded = errors.New("empty-state action completed; caller should reload config")

ErrEmptyStateActionRanReloadNeeded signals that a [1]/[2] action ran successfully and the caller should reload config and re-resolve context before continuing the launch. The caller (launcher.Launch) handles this transparently; users never see this error.

var ErrEmptyStateCancelled = errors.New("aide: cancelled at empty-state prompt")

ErrEmptyStateCancelled is returned when the user picks [c] at the empty-state prompt.

var KnownAgents = []string{
	"claude",
	"codex",
	"aider",
	"goose",
	"amp",
	"gemini",
	"copilot",
}

KnownAgents is the list of agent binaries aide can detect on PATH.

Functions

func CleanStale

func CleanStale() error

CleanStale removes any leftover aide-* directories in $XDG_RUNTIME_DIR that belong to processes that no longer exist. Called on startup to handle SIGKILL edge cases.

func CleanStaleIn

func CleanStaleIn(base string) error

CleanStaleIn removes stale aide-* directories from the given base directory.

func EmitSignpost

func EmitSignpost(w io.Writer)

EmitSignpost writes the diagnostic hint to w. Caller is responsible for the predicate (see ShouldShowSignpost).

func IsFirstRun

func IsFirstRun() bool

IsFirstRun returns true if the first-run sentinel file does not exist.

func IsKnownAgent

func IsKnownAgent(name string) bool

IsKnownAgent returns true if the agent name is in KnownAgents.

func ResolveAgentModule

func ResolveAgentModule(agentName string) seatbelt.Module

ResolveAgentModule returns the seatbelt module for the named agent, or nil.

func ShouldShowSignpost

func ShouldShowSignpost(exitCode int, signal string) bool

ShouldShowSignpost reports whether to nudge the user toward --diagnose after an abnormal child exit. Suppresses on clean exits and on user/system shutdown signals (SIGINT, SIGTERM, SIGHUP, SIGQUIT) since those represent intentional termination, not a failure worth diagnosing.

Note: this predicate is currently unused in v1. The default exec path uses syscall.Exec, so aide is replaced by the child before it can observe the exit. Re-enabling the signpost becomes a one-line change once aide moves to fork+exec as the default execution strategy.

func YoloArgs

func YoloArgs(agentName string) ([]string, error)

YoloArgs returns the skip-permissions args for the given agent. Returns an error if the agent does not support yolo mode.

Types

type DiagnoseExecer

type DiagnoseExecer struct {
	StderrLineLimit int   // 0 → no line cap
	StderrByteLimit int64 // 0 → no byte cap
}

DiagnoseExecer runs the child via fork+exec so aide stays alive to gather post-mortem data. Used only when --diagnose is set; the default path remains SyscallExecer (process replacement).

func (*DiagnoseExecer) Run

func (d *DiagnoseExecer) Run(binary string, args []string, env []string) (*RunResult, error)

Run executes binary with args and env, returning observed run state.

type DiagnoseRunner

type DiagnoseRunner interface {
	Run(binary string, args []string, env []string) (*RunResult, error)
}

DiagnoseRunner is the narrow interface the diagnose path consumes. Lets tests inject fakes.

Contract: Run returns exactly one of:

• (result, nil) when the child process completed (regardless of exit code or signal); the result describes what happened.
• (nil, err) when the child could not be started or some pre-Wait operation failed.

Implementations must not return both a non-nil result and a non-nil error; callers may rely on this to simplify branching.

type EmptyStateActions

type EmptyStateActions interface {
	// Bind attaches cwd to an existing context. The provided name is
	// the user's pick from the empty-state picker; an empty name means
	// the action should run its own picker (e.g. when no context list
	// was shown).
	Bind(name string) error
	// Create runs the create wizard. The provided name pre-fills the
	// wizard's first question; an empty string means "ask".
	Create(name string) error
}

EmptyStateActions is the contract the launcher needs from the cmd layer to dispatch [1] / [2] choices. The cmd layer implements this using the same code paths as the standalone `bind` / `create` commands so behavior matches across surfaces.

type Execer

type Execer interface {
	Exec(binary string, args []string, env []string) error
}

Execer abstracts process execution for testability.

type Launcher

type Launcher struct {
	Execer              Execer
	ConfigDir           string       // override for testing (default: config.Dir())
	LookPath            LookPathFunc // override for testing (default: exec.LookPath)
	Yolo                bool         // inject agent-specific skip-permissions flag
	NoYolo              bool         // override: disable yolo mode (overrides config and --yolo)
	Stderr              io.Writer    // override for testing (default: os.Stderr)
	IgnoreProjectConfig bool         // skip .aide.yaml entirely
	UnrestrictedNetwork bool         // force unrestricted network, clear port rules (-N flag)
	TrustStore          *trust.Store // override for testing (default: trust.DefaultStore())

	// Variant selection inputs (optional; zero value disables variant flow).
	VariantOverrides map[string][]string
	ConsentStore     *consent.Store
	Prompter         capability.Prompter
	AutoYes          bool
	Interactive      bool

	// Diagnose enables post-mortem report generation (forks instead of execve).
	Diagnose bool
	// DiagnoseTrace implies Diagnose; additionally captures macOS sandbox denials.
	DiagnoseTrace bool

	// EmptyStateActions is invoked when context resolution fails AND
	// no default_context is configured. May be nil; nil disables the
	// interactive empty-state prompt and falls back to the legacy
	// hard error.
	EmptyStateActions EmptyStateActions

	// Version, Commit, BuildDate carry the goreleaser-injected build
	// metadata. They are populated in cmd/aide/main.go and surfaced in
	// the --diagnose report's Environment section. Empty values are
	// rendered verbatim ("dev", "none", "unknown" by default).
	Version   string
	Commit    string
	BuildDate string
}

Launcher orchestrates the full agent launch flow.

func (*Launcher) Launch

func (l *Launcher) Launch(cwd string, agentOverride string, extraArgs []string, cleanEnv bool, resolve bool, withCaps []string, withoutCaps []string) error

Launch resolves context, decrypts secrets, resolves templates, creates a runtime directory, applies sandbox policy, and execs the agent binary.

func (*Launcher) Passthrough

func (l *Launcher) Passthrough(cwd string, agentOverride string, extraArgs []string) error

Passthrough handles the zero-config case: no config.yaml exists. If agentOverride is set, it launches that specific agent (must be known). Otherwise it scans PATH for known agents and auto-selects.

type LookPathFunc

type LookPathFunc func(file string) (string, error)

LookPathFunc abstracts exec.LookPath for testability.

type PassthroughResult

type PassthroughResult struct {
	// Found agents with their resolved paths.
	Found map[string]string
}

PassthroughResult describes what the passthrough scanner found.

func ScanAgents

func ScanAgents(lookPath LookPathFunc) *PassthroughResult

ScanAgents scans PATH for known agent binaries.

type RunResult

type RunResult struct {
	ExitCode             int
	Signal               string // "SIGINT", "SIGTERM", ...; "" if not signal-killed
	Runtime              time.Duration
	StderrTail           string
	StderrTruncatedBytes int64
	Pid                  int // PID of the child process; populated after Start
}

RunResult captures everything observable from a fork+exec child run.

type RuntimeDir

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

RuntimeDir manages an ephemeral directory for aide's runtime files.

func NewRuntimeDir

func NewRuntimeDir() (*RuntimeDir, error)

NewRuntimeDir creates a new runtime directory at $XDG_RUNTIME_DIR/aide-<pid>/ with mode 0700. Falls back to os.TempDir() if XDG_RUNTIME_DIR is not set.

func (*RuntimeDir) Cleanup

func (r *RuntimeDir) Cleanup() error

Cleanup removes the runtime directory and all its contents. Safe to call multiple times.

func (*RuntimeDir) Path

func (r *RuntimeDir) Path() string

Path returns the runtime directory path.

func (*RuntimeDir) RegisterSignalHandlers

func (r *RuntimeDir) RegisterSignalHandlers() context.CancelFunc

RegisterSignalHandlers sets up signal handlers for SIGTERM, SIGINT, SIGQUIT, and SIGHUP that trigger Cleanup before exit. Returns a cancel function to deregister the handlers.

type SyscallExecer

type SyscallExecer struct{}

SyscallExecer replaces the current process with the given binary via syscall.Exec.

func (*SyscallExecer) Exec

func (s *SyscallExecer) Exec(binary string, args []string, env []string) error

Exec calls syscall.Exec, replacing the current process.