README
¶
// Package shell provides an eino shell tool backed by the Dagger engine. // It gives LLM agents a secure, sandboxed shell inside an OCI base image // (golang, node, python, etc.) with shared caching across agents. // // The tool implements both tool.InvokableTool and tool.StreamableTool. // // Usage: // // cfg := &shell.Config{ // Workdir: "/path/to/project", // } // shellTool, err := shell.NewShellTool(ctx, cfg) // // // With safety middleware: // tools, mw, err := shell.NewAllToolsWithSafety(ctx, cfg, nil) // agent, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{ // Name: "shell-agent", // Model: myModel, // Tools: tools, // Handlers: []adk.ChatModelAgentMiddleware{mw}, // }) // // Requirements: // - A reachable Dagger engine (local or remote). // - The engine URL can be set via DAGGER_HOST env var or EngineURL config. // // Security: // - Command blocklist prevents destructive commands (rm, kill, etc.). // - Egress network policy restricts outbound traffic. // - No confirmation gate: commands execute directly in the disposable sandbox // (shell_exec is not a write tool). dryRun=true still returns a preview. // // Parameters: // - Command: the command to execute as an array of strings. // - Stdin: optional text piped to the command's standard input. // - FilterPattern: optional Go RE2 regex applied to each output line. // // Composability: // - RawExec is a trusted, gate-free primitive that runs a command and returns // raw stdout/stderr/exit code. It always enforces the blocklist and is // intended for compositors such as the pipe tool, not direct end users. package shell
Documentation
¶
Overview ¶
Package shell provides an eino shell tool backed by the Dagger engine. It gives LLM agents a secure, sandboxed shell inside an OCI base image (golang, node, python, etc.) with shared caching across agents.
The tool implements both tool.InvokableTool and tool.StreamableTool.
Index ¶
- func Check(ctx context.Context, cfg *Config) checkup.Results
- func NewAllToolsWithSafety(ctx context.Context, cfg *Config, safetyCfg *safetymw.Config) ([]tool.InvokableTool, *safetymw.Middleware, error)
- func NewShellToolsForProfiles(ctx context.Context, cfg *Config) (map[string]*Tool, error)
- func WriteToolNames() []string
- type Config
- type Params
- type RawExecParams
- type Tool
- func (t *Tool) Close() error
- func (t *Tool) Info(ctx context.Context) (*schema.ToolInfo, error)
- func (t *Tool) InvokableRun(ctx context.Context, args string, opts ...tool.Option) (string, error)
- func (t *Tool) Invoke(ctx context.Context, params *Params) (string, error)
- func (t *Tool) InvokeAsStream(ctx context.Context, params *Params) (*schema.StreamReader[string], error)
- func (t *Tool) RawExec(ctx context.Context, params RawExecParams) (stdout, stderr string, exitCode int, err error)
- func (t *Tool) StreamableRun(ctx context.Context, args string, opts ...tool.Option) (*schema.StreamReader[string], error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewAllToolsWithSafety ¶
func NewAllToolsWithSafety(ctx context.Context, cfg *Config, safetyCfg *safetymw.Config) ([]tool.InvokableTool, *safetymw.Middleware, error)
NewAllToolsWithSafety creates all shell tools with a pre-configured safety middleware.
func NewShellToolsForProfiles ¶
NewShellToolsForProfiles creates Tools for each configured profile.
func WriteToolNames ¶
func WriteToolNames() []string
WriteToolNames returns the tool names of all shell write tools.
shell_exec is intentionally NOT a write tool: it executes commands in an isolated, disposable Dagger sandbox and never mutates production systems directly, so it is not gated by the safety middleware. (The command blocklist is still enforced on every execution.)
Types ¶
type Config ¶
type Config struct {
BaseImage string `validate:"omitempty" jsonschema:"description=Default OCI base image when no profile matches"`
Profiles map[string]profile.Profile `validate:"omitempty" jsonschema:"description=Profile overrides keyed by profile name"`
Workdir string `validate:"required" jsonschema:"description=Project workdir to mount into containers"`
NetworkPolicy *egress.Policy `validate:"omitempty" jsonschema:"description=Egress network policy for container outbound access"`
CacheKey string `validate:"omitempty" jsonschema:"description=Cache volume key prefix for shared installs"`
RegistryAuth map[string]dagger.RegistryAuth `validate:"omitempty" jsonschema:"description=Registry auth credentials keyed by hostname"`
Blocklist []string `validate:"omitempty" jsonschema:"description=Custom command blocklist patterns (extend defaults)"`
DefaultTimeout time.Duration `validate:"omitempty" jsonschema:"description=Default timeout for command execution"`
}
Config holds configuration for shell tool instances and profiles.
type Params ¶
type Params struct {
Command []string `json:"command" validate:"required,min=1" jsonschema:"(required) The command to execute as an array of strings"`
Stdin string `json:"stdin,omitempty" validate:"omitempty" jsonschema:"(optional) Text to pipe to the command's standard input (stdin)"`
Profile string `json:"profile,omitempty" validate:"omitempty" jsonschema:"(optional) Profile name to override default container image"`
DryRun bool `json:"dryRun,omitempty" jsonschema:"(optional) If true, preview the command without executing"`
FilterPattern string `` /* 306-byte string literal not displayed */
Timeout string `json:"timeout,omitempty" validate:"omitempty" jsonschema:"(optional) Timeout duration string (e.g. '30s', '5m')"`
AllowLocalNetwork *bool `json:"allowLocalNetwork,omitempty" jsonschema:"(optional) Override to allow local network access for this call"`
}
Params defines the parameters for shell command execution.
type RawExecParams ¶
type RawExecParams struct {
Command []string // required, non-empty
Profile string // optional; "" means auto-detect
Stdin string // optional text piped to the command
Timeout time.Duration // <= 0 falls back to Config.DefaultTimeout / defaultExecTimeout
}
RawExecParams is a trusted, gate-free shell execution request used by the pipe tool (and future compositors). It applies the blocklist and resolves the profile, but skips dry-run and output filtering — the composing caller owns those. It is NOT intended for direct end-user invocation.
type Tool ¶
type Tool struct {
// contains filtered or unexported fields
}
Tool is an eino tool for executing shell commands.
func NewShellTool ¶
NewShellTool creates a new Tool from the given configuration.
func (*Tool) InvokableRun ¶
InvokableRun implements the eino InvokableTool interface.
func (*Tool) InvokeAsStream ¶
func (t *Tool) InvokeAsStream(ctx context.Context, params *Params) (*schema.StreamReader[string], error)
InvokeAsStream runs the shell command and returns a stream reader.
func (*Tool) RawExec ¶
func (t *Tool) RawExec(ctx context.Context, params RawExecParams) (stdout, stderr string, exitCode int, err error)
RawExec runs a command in the sandbox and returns its raw stdout, stderr and exit code. It is a trusted, gate-free primitive for compositors (e.g. the pipe tool): the blocklist is always enforced, but dry-run and output filtering are the caller's responsibility. It is NOT intended for direct end-user invocation.
Source Files