runner

type BoundedExecRunner interface {
	ExecBounded(ctx context.Context, spec RunSpec, maxCapture int) (RunResult, error)
}

type DirectExecRunner struct{}

type EnvAssignmentError struct {
	Name string
}

type ExecutableNotFoundError struct {
	Name string
}

type PipelineResult struct {
	// InvocationID echoes the stage's RunSpec.InvocationID verbatim for every produced result.
	InvocationID string
	// Stdout and Stderr are the first maxCapture bytes the parent read from that stream.
	Stdout []byte
	Stderr []byte
	// ExitCode is the process exit status, or -1 when the stage failed to launch or never ran.
	ExitCode int
	// Duration is that stage's own wall-clock time from launch to exit; stages overlap, so summing
	// these across a pipeline overstates the elapsed time.
	Duration time.Duration
	// LaunchErrCategory is set only for a stage that failed to launch, matching Exec.
	LaunchErrCategory fserrors.Category
	// StdoutTotal and StderrTotal count every byte the parent read from that stream, including the
	// bytes past maxCapture that were counted but not retained. A pipeline stage can be ended before
	// it finishes producing — a downstream exit closes the upstream read end so the producer takes
	// SIGPIPE — so a total counts what was captured, not what the stage would have gone on to emit.
	StdoutTotal int64
	StderrTotal int64
	// PipelineErrCategory is set only for a stage affected by a post-launch copier, collector,
	// internal, or cancellation failure, which Pipeline also reports as its returned error.
	PipelineErrCategory PipelineStageFailure
}

type PipelineRunner interface {
	// PreflightPipeline validates every spec and decides capability support before any process
	// starts. It returns ErrPipelineUnsupported only when this runner cannot run a pipeline at all,
	// and any other non-nil error means nothing was started.
	PreflightPipeline(ctx context.Context, specs []RunSpec) error
	// Pipeline runs the ordered specs as one pipeline after a successful preflight, bounding each
	// captured stream to maxCapture bytes. It never returns ErrPipelineUnsupported. A non-nil error
	// is returned only once there is one PipelineResult per input spec and every started process,
	// copier, and collector has been joined.
	Pipeline(ctx context.Context, specs []RunSpec, maxCapture int) ([]PipelineResult, error)
}

type PipelineStageFailure string

type RunResult struct {
	// InvocationID echoes RunSpec.InvocationID verbatim for every produced result, so the paired
	// tool_exec_start/tool_exec_end events share one id.
	InvocationID string
	// Stdout and Stderr are empty on a launch failure because the process never ran.
	Stdout []byte
	Stderr []byte
	// ExitCode is the process exit status, or -1 when the process failed to launch.
	ExitCode int
	// Duration is the wall-clock time spent in cmd.Run.
	Duration time.Duration
	// LaunchErrCategory is set only when the process failed to launch before starting; it is empty
	// on normal completion, including a non-zero exit.
	LaunchErrCategory fserrors.Category
	StdoutTotal       int64
	StderrTotal       int64
}

type RunSpec struct {
	// InvocationID is the UUIDv7 the caller minted via Runner.NewInvocationID at invocation
	// start — the single source of the paired tool_exec_start/tool_exec_end id.
	// Exec validates it and echoes it verbatim into RunResult.InvocationID.
	InvocationID string
	// Argv is the command and its arguments; Argv[0] is the binary, run directly with no shell
	// interpretation. It must be non-empty.
	Argv []string
	// Cwd, when non-empty, sets the process working directory (exec.Cmd.Dir). Callers own path
	// validation and resolution; the runner passes it through unchanged.
	Cwd string
	// Env is an optional complete environment block: nil inherits the parent process environment,
	// non-nil is passed to exec.Cmd.Env as-is.
	Env         []string
	Assignments []string
	// Stdin is fed to the process standard input; nil or empty means the process gets no input.
	Stdin                []byte
	ExceptionalAuthority string
}

type Runner interface {
	// NewInvocationID mints a fresh UUIDv7 invocation id. The caller calls this at invocation
	// start, emits tool_exec_start with it, then passes it back in RunSpec.InvocationID.
	NewInvocationID() string
	// Exec runs spec directly with no shell interpretation and returns a RunResult. It returns a
	// non-nil error only for invalid input (empty or malformed InvocationID, empty Argv) or
	// internal failures; non-zero exits and launch failures are carried on RunResult.
	Exec(ctx context.Context, spec RunSpec) (RunResult, error)
}