shelltool

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

type EnvironmentProviderConfig struct {
	// SourceID identifies context injected by this provider.
	// Defaults to "shell_environment".
	SourceID string

	// ProbeTools lists CLI tools whose --version output should be probed.
	// Nil uses a small default list; an empty non-nil slice disables tool probes.
	ProbeTools []string

	// OverrideFamily forces the reported shell family when non-nil.
	OverrideFamily *ShellFamily

	// ProbeTimeout bounds each individual probe. Nil uses a 5 second default.
	// Negative values are invalid.
	ProbeTimeout *time.Duration

	// InstructionsFormatter renders a snapshot into agent instructions.
	// Defaults to [DefaultShellEnvironmentInstructions].
	InstructionsFormatter func(ShellEnvironmentSnapshot) string
}

type Executor interface {
	Initialize(context.Context) error
	Run(context.Context, string) (Result, error)
}

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

type LocalConfig struct {
	// Shell is an optional override for the shell binary path. When empty,
	// the AGENT_FRAMEWORK_SHELL environment variable is consulted; if that is
	// also unset, the OS default is used (/bin/bash on POSIX, pwsh/cmd on
	// Windows). Mutually exclusive with [LocalConfig.ShellArgv].
	Shell string

	// ShellArgv overrides the shell launch argv. The first element is the
	// shell binary; remaining elements are passed as a launch-time prefix
	// before the standard -c / -Command / persistent suffix. Mutually
	// exclusive with [LocalConfig.Shell].
	ShellArgv []string

	// Mode selects stateless-per-call or persistent-shell execution.
	// Defaults to [ModePersistent].
	Mode Mode

	// WorkingDirectory is the initial working directory for the shell.
	// When empty, defaults to the current process working directory.
	WorkingDirectory string

	// ConfineWorkingDirectory controls whether each persistent command is
	// prefixed with a cd/Set-Location back to [LocalConfig.WorkingDirectory].
	// The default is true.
	ConfineWorkingDirectory *bool

	// Environment contains extra environment variables for the spawned shell.
	// A nil value removes an inherited variable. A nil map means no overrides.
	Environment map[string]*string

	// CleanEnvironment starts the shell with only a small allowlist of
	// inherited variables (PATH, HOME, USER, USERNAME, USERPROFILE,
	// SystemRoot, TEMP, TMP) before applying [LocalConfig.Environment].
	CleanEnvironment bool

	// Timeout is the per-command deadline. Nil means no timeout. Negative values
	// are invalid. 30s is the recommended value.
	Timeout *time.Duration

	// MaxOutputBytes caps each captured output stream per command.
	// Defaults to 64 KiB. Output beyond this limit is
	// silently truncated and [Result.Truncated] is set.
	MaxOutputBytes int

	// Policy is an optional allow/deny filter checked before the command
	// reaches the shell. Nil means allow everything.
	Policy *Policy

	// AcknowledgeUnsafe opts out of the default approval-required gate.
	// When false (the default), the returned tool's ApprovalRequired method
	// reports true so the harness prompts a human before every execution. Set
	// this to true only when you have an independent isolation mechanism and
	// accept the risk.
	AcknowledgeUnsafe bool
}

type Mode int

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

type PolicyConfig struct {
	// DenyList contains patterns that trigger a deny outcome. Nil or empty
	// disables the deny list.
	DenyList []string

	// AllowList contains explicit-allow patterns. A match here short-circuits
	// the deny list.
	AllowList []string
}

type Result struct {
	// Stdout is the captured standard output, possibly truncated.
	Stdout string
	// Stderr is the captured standard error, possibly truncated.
	Stderr string
	// ExitCode is the exit status reported by the process. -1 if the process
	// did not exit cleanly.
	ExitCode int
	// Duration is how long the command ran end-to-end.
	Duration time.Duration
	// Truncated is true when stdout or stderr was truncated.
	Truncated bool
	// TimedOut is true when the command was killed for exceeding the timeout.
	TimedOut bool
}

type ShellEnvironmentSnapshot struct {
	Family           ShellFamily
	OSDescription    string
	ShellVersion     string
	WorkingDirectory string
	ToolVersions     map[string]ToolVersion
}

type ShellFamily int

type ShellRequest struct {
	// Command is the full command line that the agent wants to run.
	Command string

	// WorkingDirectory is the optional working directory the command will
	// execute in, if known.
	WorkingDirectory string
}

type ToolVersion struct {
	Version string
	Found   bool
}