shelltool

Documentation

Index

• Constants
• Variables
• type ShellCommandArgs
• type ShellCommandExecResult
• type ShellCommandPolicy
• type ShellCommandResponse
• type ShellName
• type ShellTool
  • func NewShellTool(opts ...ShellToolOption) (*ShellTool, error)
  • func (st *ShellTool) Run(ctx context.Context, args ShellCommandArgs) (out *ShellCommandResponse, err error)
  • func (st *ShellTool) SetAllowedWorkdirRoots(roots []string) error
  • func (st *ShellTool) Tool() spec.Tool
• type ShellToolOption
  • func WithShellAllowedWorkdirRoots(roots []string) ShellToolOption
  • func WithShellBlockedCommands(cmds []string) ShellToolOption
  • func WithShellCommandPolicy(p ShellCommandPolicy) ShellToolOption
  • func WithShellMaxSessions(maxSessions int) ShellToolOption
  • func WithShellSessionTTL(ttl time.Duration) ShellToolOption

Constants

const (
	HardMaxTimeout             = 10 * time.Minute
	HardMaxOutputBytes   int64 = 4 * 1024 * 1024 // per stream
	HardMaxCommands            = 64
	HardMaxCommandLength       = 64 * 1024 // bytes
	MinOutputBytes       int64 = 1024

	DefaultTimeout                = 60 * time.Second
	DefaultMaxOutputBytes   int64 = 256 * 1024
	DefaultMaxCommands            = 64
	DefaultMaxCommandLength       = 64 * 1024
)

Fixed, package-wide hard limits (single source of truth).

Variables

var DefaultShellCommandPolicy = ShellCommandPolicy{
	AllowDangerous:   false,
	Timeout:          DefaultTimeout,
	MaxOutputBytes:   DefaultMaxOutputBytes,
	MaxCommands:      DefaultMaxCommands,
	MaxCommandLength: DefaultMaxCommandLength,
}

Types

type ShellCommandArgs

type ShellCommandArgs struct {
	Commands        []string          `json:"commands,omitempty"`
	Workdir         string            `json:"workdir,omitempty"`
	Env             map[string]string `json:"env,omitempty"`
	Shell           ShellName         `json:"shell,omitempty"`
	ExecuteParallel bool              `json:"executeParallel,omitempty"`
	SessionID       string            `json:"sessionID,omitempty"`
}

type ShellCommandExecResult

type ShellCommandExecResult struct {
	Command   string    `json:"command"`
	Workdir   string    `json:"workdir"`
	Shell     ShellName `json:"shell"`
	ShellPath string    `json:"shellPath"`

	ExitCode   int   `json:"exitCode"`
	TimedOut   bool  `json:"timedOut"`
	DurationMS int64 `json:"durationMS"`

	Stdout string `json:"stdout"`
	Stderr string `json:"stderr"`

	StdoutTruncated bool `json:"stdoutTruncated"`
	StderrTruncated bool `json:"stderrTruncated"`
}

type ShellCommandPolicy

type ShellCommandPolicy struct {
	// If true, skip heuristic checks (fork-bomb/backgrounding). NOTE: hard-blocked commands are ALWAYS blocked.
	AllowDangerous bool

	// Policy limits (clamped to package hard limits).
	Timeout          time.Duration
	MaxOutputBytes   int64
	MaxCommands      int
	MaxCommandLength int
}

ShellCommandPolicy provides policy / hardening knobs (package-level, so host app can tune).

type ShellCommandResponse

type ShellCommandResponse struct {
	SessionID string                   `json:"sessionID,omitempty"`
	Workdir   string                   `json:"workdir,omitempty"`
	Results   []ShellCommandExecResult `json:"results,omitempty"`
}

type ShellName

type ShellName string

const (
	ShellNameAuto       ShellName = "auto"
	ShellNameBash       ShellName = "bash"
	ShellNameZsh        ShellName = "zsh"
	ShellNameSh         ShellName = "sh"
	ShellNameDash       ShellName = "dash"
	ShellNameKsh        ShellName = "ksh"
	ShellNameFish       ShellName = "fish"
	ShellNamePwsh       ShellName = "pwsh"
	ShellNamePowershell ShellName = "powershell"
	ShellNameCmd        ShellName = "cmd"
)

type ShellTool

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

ShellTool is an instance-owned shell tool runner. It owns sessions, policy, and environment inheritance settings.

func NewShellTool

func NewShellTool(opts ...ShellToolOption) (*ShellTool, error)

func (*ShellTool) Run

func (st *ShellTool) Run(ctx context.Context, args ShellCommandArgs) (out *ShellCommandResponse, err error)

func (*ShellTool) SetAllowedWorkdirRoots

func (st *ShellTool) SetAllowedWorkdirRoots(roots []string) error

SetAllowedWorkdirRoots allows changing workdir roots at runtime (best-effort). Existing sessions whose workdir falls outside the new roots will fail when used.

func (*ShellTool) Tool

func (st *ShellTool) Tool() spec.Tool

type ShellToolOption

type ShellToolOption func(*ShellTool) error

func WithShellAllowedWorkdirRoots

func WithShellAllowedWorkdirRoots(roots []string) ShellToolOption

WithShellAllowedWorkdirRoots restricts workdir to be within one of the provided roots. Roots are canonicalized (clean+abs) and must exist as directories.

func WithShellBlockedCommands

func WithShellBlockedCommands(cmds []string) ShellToolOption

WithShellBlockedCommands adds additional commands to the instance blocklist. These are enforced before execution and cannot override/remove the hard default blocklist. Entries must be command names (e.g. "git", "python", "curl"), not full command lines.

func WithShellCommandPolicy

func WithShellCommandPolicy(p ShellCommandPolicy) ShellToolOption

func WithShellMaxSessions

func WithShellMaxSessions(maxSessions int) ShellToolOption

WithShellMaxSessions sets an upper bound on concurrent sessions (LRU eviction). "max<=0" disables max-session eviction (TTL may still evict).

func WithShellSessionTTL

func WithShellSessionTTL(ttl time.Duration) ShellToolOption

WithShellSessionTTL enables TTL eviction for sessions. "ttl<=0" disables TTL eviction (LRU max may still evict).