Documentation
¶
Overview ¶
Package shell exposes a model-callable shell tool over the Executor SPI. Local, sandboxed, or remote backends implement Executor; NewLocalExecutor runs commands on the host.
A non-zero exit status is a completed execution result. Transport, collection, and cleanup errors can leave the outcome unknown; Tool retains the observed output as core/tool.CallError evidence without inventing a definite failure. Response streams use content.Content so binary data and a UTF-8 prefix split by a byte limit survive serialization without losing the other observations.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrEmptyCommand and ErrInvalidInput reject the command before execution. // Backends must not return either after dispatch or mutation. 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") )
Functions ¶
This section is empty.
Types ¶
type Executor ¶
type Executor interface {
// Run executes one command, honoring ctx and Input.Timeout. A non-zero exit
// status is Output, not an error. An error reports spawn, I/O, or
// collection failure and leaves side effects uncertain; Output still
// carries every available observation. Return core/tool.Failure only for an
// established unsuccessful outcome, since it owns its model-visible output.
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 LocalExecutor ¶
type LocalExecutor struct {
// contains filtered or unexported fields
}
LocalExecutor runs commands on the local host through one immutable construction-time configuration. Each call owns a Unix process group and kills that group on cancellation or return, including background children. A command that deliberately creates another session requires a host sandbox to keep its lifetime confined; this executor is not a process sandbox.
func NewLocalExecutor ¶
func NewLocalExecutor(config LocalExecutorConfig) (*LocalExecutor, error)
NewLocalExecutor freezes an absolute working directory and output limits.
type LocalExecutorConfig ¶ added in v0.41.0
type LocalExecutorConfig struct {
Directory string
Shell string
// MaxBytesPerStream caps captured stdout and stderr independently.
// Zero selects 30 KiB per stream. Capture never inserts presentation text.
MaxBytesPerStream int
}
LocalExecutorConfig makes the local process authority visible at construction. The directory controls relative-path resolution but is not a filesystem jail; callers that need confinement must supply an OS sandbox or container.
type Output ¶
type Output struct {
Stdout []byte
Stderr []byte
ExitCode int
Duration time.Duration
// Dropped counts include bytes observed but not retained, never bytes lost
// before collection. A zero count on error does not prove completeness.
StdoutDroppedBytes uint64
StderrDroppedBytes uint64
// CancellationObserved reports that cancellation or timeout was observed
// before returning; it does not establish why the process exited.
CancellationObserved bool
}
Output retains the executor's observations. ExitCode is -1 when no exit status was obtained, so an unobserved exit is never reported as success.
type Request ¶
type Request struct {
Command string `` /* 128-byte string literal not displayed */
TimeoutMS int `` /* 147-byte string literal not displayed */
}
Environment, working directory, and streaming remain executor-owned.
func (Request) JSONSchemaConstraints ¶ added in v0.60.0
func (Request) JSONSchemaConstraints() jsonschema.Constraints
type Response ¶
type Response struct {
Stdout content.Content `json:"stdout"`
Stderr content.Content `json:"stderr"`
StdoutDroppedBytes uint64 `json:"stdout_dropped_bytes,omitzero"`
StderrDroppedBytes uint64 `json:"stderr_dropped_bytes,omitzero"`
ExitCode int `json:"exit_code"`
CancellationObserved bool `json:"cancellation_observed,omitzero"`
Duration string `json:"duration"`
}
Captured bytes remain lossless for binary output and truncated UTF-8 text.
Source Files