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 []spec.ToolStoreOutputUnion, err error)
  • func (st *ShellTool) SetAllowedWorkdirRoots(roots []string) error
  • func (st *ShellTool) Tool() spec.Tool
• type ShellToolOption
  • func WithShellAllowedWorkdirRoots(roots []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).

const GOOSWindows = "windows"

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"`

	StdoutBytes     int64 `json:"stdoutBytes"`
	StderrBytes     int64 `json:"stderrBytes"`
	StdoutTruncated bool  `json:"stdoutTruncated"`
	StderrTruncated bool  `json:"stderrTruncated"`

	Warnings []string `json:"warnings,omitempty"`
}

type ShellCommandPolicy

type ShellCommandPolicy struct {
	// If true, skip dangerous-command checks (NOT recommended as default).
	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 []spec.ToolStoreOutputUnion, 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 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).