shell

Documentation

Overview

Package shell exposes a single LLM-callable shell tool plus a small Executor SPI. The package itself does not pick where commands run — local, sandboxed, or remote backends each implement Executor and plug in via NewTool.

The local executor (NewLocalExecutor) is the reference impl and covers the common case (run on the same host as the agent).

Index

• Variables
• type Executor
• type Input
• type LocalExecutor
  • func NewLocalExecutor() *LocalExecutor
  • func (l *LocalExecutor) Run(ctx context.Context, in Input) (Output, error)
• type Output
• type Request
• type Response
• type Tool
  • func NewTool(executor Executor) *Tool
  • func (t *Tool) Call(ctx context.Context, invocation toolcontract.Invocation) (chat.ToolOutput, error)
  • func (t *Tool) Definition() chat.ToolDefinition

Variables

var (
	ErrEmptyCommand  = errors.New("shell: command must not be empty")
	ErrInvalidConfig = errors.New("shell: executor configuration is invalid")
	ErrInvalidInput  = errors.New("shell: input is invalid")
	ErrNilExecutor   = errors.New("shell: executor must not be nil")
)

Types

type Executor

type Executor interface {
	// Run executes exactly one command within the executor's frozen authority.
	// It honors ctx and Input.Timeout, returns non-zero exit status as Output
	// rather than error, and reserves error for spawn, I/O, or collection failure.
	Run(ctx context.Context, in Input) (Output, error)
}

Executor is the authority boundary behind the model-facing shell tool. The concrete implementation owns process creation, working-directory policy, environment exposure, output capture, termination, and platform semantics.

type Input

type Input struct {
	// Cmd is the shell command line. Required.
	Cmd string

	// Timeout bounds the run. 0 = no timeout; ctx cancellation still
	// applies.
	Timeout time.Duration
}

Input captures everything an executor needs to launch a single command. Only Cmd is required.

type LocalExecutor

type LocalExecutor struct {
	// Shell is the interpreter; defaults to "/bin/sh".
	Shell string

	// Dir is the working directory commands run in. "" inherits the
	// host process's cwd (os/exec's default). Set it to confine a
	// command's relative-path resolution to a project root — the shell
	// working directory policy for shell execution. Unlike the immutable rooted
	// authority of fs.LocalExecutor, it does NOT jail the command
	// (a command can still cd / touch absolute paths); jailing is the
	// caller's job via OS sandbox / container.
	Dir string

	// MaxOutputBytes caps the captured size of each stream (stdout
	// and stderr independently). 0 = use [defaultMaxOutputBytes].
	// Bytes beyond the cap are dropped and a "[N bytes truncated]"
	// marker is appended.
	MaxOutputBytes int
}

LocalExecutor runs commands on the local host via the configured shell. Default shell is "/bin/sh -c".

func NewLocalExecutor

func NewLocalExecutor() *LocalExecutor

func (*LocalExecutor) Run

func (l *LocalExecutor) Run(ctx context.Context, in Input) (Output, error)

type Output

type Output struct {
	Stdout   []byte
	Stderr   []byte
	ExitCode int
	Duration time.Duration

	// Killed is true when the process was terminated by ctx or
	// Input.Timeout rather than exiting on its own.
	Killed bool
}

Output is what every executor returns. A non-zero ExitCode is not an error — only spawn/I/O failures populate the error return.

type Request

type Request struct {
	Command   string `json:"command" jsonschema:"minLength=1" jsonschema_description:"Shell command line run by /bin/sh -c."`
	TimeoutMS int    `` /* 169-byte string literal not displayed */
}

Request is the LLM-facing argument shape. It is a strict subset of Input — environment, working directory, and streaming are executor-side concerns, not LLM knobs.

type Response

type Response struct {
	Stdout   string `json:"stdout"`
	Stderr   string `json:"stderr"`
	ExitCode int    `json:"exit_code"`
	Killed   bool   `json:"killed,omitempty"`
	Duration string `json:"duration"`
}

Response is the LLM-facing return shape. Stdout/stderr are strings (not []byte) because every consumer is a chat model.

type Tool

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

func NewTool

func NewTool(executor Executor) *Tool

func (*Tool) Call

func (t *Tool) Call(ctx context.Context, invocation toolcontract.Invocation) (chat.ToolOutput, error)

func (*Tool) Definition

func (t *Tool) Definition() chat.ToolDefinition