sandbox

type EnvironmentKind string

type Executor interface {
	// Run executes a command inside the sandbox and streams its output.
	// Implementations must respect ctx cancellation and RunRequest.Timeout.
	Run(ctx context.Context, req RunRequest) (RunResult, error)

	// Kind identifies which backend this is.
	Kind() EnvironmentKind

	// Healthy returns nil when the executor is ready to accept work.
	// A non-nil error means the backend is unavailable. The engine calls this once at startup.
	Healthy(ctx context.Context) error
}

type ExecutorConfig struct {
	// Kind selects the backend.
	Kind EnvironmentKind

	// Sandboxd holds sidecar configuration.
	// Only used when Kind == EnvironmentSandboxed.
	Sandboxd SandboxdConfig

	// MicroVM configures the microVM backend when Kind is EnvironmentMicroVM.
	MicroVM MicroVMConfig
}

type MicroVMConfig struct {
	// BinaryPath is the msb executable. Required. The embedder provides it.
	BinaryPath string

	// Home holds msb's images, sandboxes and volumes, and this backend's records.
	// Required: a default under the user's profile would mix with a separate install.
	Home string

	// Image is the OCI image of the environment. Empty means DefaultMicroVMImage.
	Image string

	// CPUs and MemoryMB size each sandbox. Zero means the defaults below.
	CPUs     int
	MemoryMB int

	// Ports are msb port mappings published when a sandbox is created. Nil means
	// DefaultMicroVMPorts: a command does not announce its port, so they are set ahead.
	Ports []string

	// Shell runs a command in the guest. Empty means bash, which the default image has.
	Shell []string

	// Env is added to every command. The host's environment is never passed in.
	Env map[string]string
}

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

type RunRequest struct {
	// Command is the shell command string to execute.
	// Passed as-is to the interpreter defined by Shell.
	Command string

	// Shell specifies the interpreter. Empty means the backend's default.
	Shell []string

	// Env is a set of KEY=VALUE pairs injected into the command environment
	// on top of the executor's base environment.
	Env map[string]string

	// WorkDir is the host working directory for the command. A microVM maps it into
	// the guest, and mounts it if it is a new project.
	WorkDir string

	// Stdin is connected to the command's standard input (may be nil).
	Stdin io.Reader

	// Timeout is the maximum duration for the command.
	// Zero means no timeout beyond the parent context deadline.
	Timeout time.Duration

	// OnOutput, when set, receives output as the command produces it, with the
	// stream ("stdout" or "stderr"). The RunResult still holds all of it. A remote
	// executor may hand output over only when the command ends.
	OnOutput func(stream string, data []byte)
}

type RunResult struct {
	// Stdout and Stderr capture the command output.
	// Empty when Background=true.
	Stdout string
	Stderr string

	// ExitCode is the process exit code. Non-zero indicates failure.
	ExitCode int

	// Duration is the wall-clock time the command took.
	Duration time.Duration

	// Cwd is the working directory the command left the environment in.
	// Only populated by executors backed by a persistent shell (e.g.
	// RemoteExecutor) where a `cd` genuinely changes state for the next
	// command; empty for one-shot-per-call executors, where WorkDir never changes
	// out from under the caller.
	Cwd string
}

type SandboxdConfig struct {
	// BinaryPath is the seshat-sandboxd executable. Required.
	BinaryPath string

	// Shell is the interpreter used when a RunRequest does not name one,
	// e.g. []string{"/bin/bash", "-c"}. Empty lets the sidecar pick the
	// platform default (/bin/sh on Unix, cmd.exe /C on Windows).
	Shell []string

	// MaxOutputBytes caps each stream *inside* the sidecar, protecting this
	// process from a runaway command. Zero means no cap: the tools' own
	// output handling applies, exactly as on the unsandboxed path.
	MaxOutputBytes int64

	// DefaultTimeout applies when RunRequest.Timeout is zero. Zero means no
	// deadline beyond the caller's context.
	DefaultTimeout time.Duration

	// HandshakeTimeout bounds startup plus the hello exchange.
	HandshakeTimeout time.Duration

	// Profile names the identity on Windows: SandboxdProfileProject or
	// SandboxdProfileStrict. Empty means strict. See ADR-0002.
	Profile string

	// CapabilitySID is the SID the project profile's token carries and its deny
	// ACEs name, random and made once per install. The embedder keeps it: taking an
	// ACE back later needs the same one. Required by the project profile.
	CapabilitySID string

	// DenyRead names what the project profile refuses to read. A path that exists
	// and cannot be protected refuses the whole session. The model never sets this,
	// nor the profile: a command cannot widen its own sandbox.
	DenyRead []string
}

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