// Package sandbox provides a secure execution environment for running commands.
//
// The sandbox restricts resource usage (timeout, output size, working directory)
// and environment variable access to prevent runaway or malicious commands.
// This is the execution backend used by the Tool system's built-in exec tool.
package sandbox

import (
	"context"
)

// Result holds the output and exit status of a sandboxed command execution.
type Result struct {
	Stdout   string `json:"stdout"`
	Stderr   string `json:"stderr"`
	ExitCode int    `json:"exit_code"`
}

// Sandbox defines the interface for command execution environments.
//
// Implementations may use OS processes (os/exec), containers, or other
// isolation mechanisms. The context controls cancellation and timeouts.
type Sandbox interface {
	// Execute runs a command with the given arguments inside the sandbox.
	// The context can be used to set timeouts or cancel the execution.
	// Returns the combined output, error output, and exit code.
	Execute(ctx context.Context, cmd string, args ...string) (*Result, error)
}