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. // - Safety middleware gates all executions behind dry-run/confirmed flow. 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 Tool
- 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) 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. These names can be passed to the safety middleware's Config.WriteToolNames.
Contract: every name listed here MUST honor dryRun=true as a no-side-effect preview. The safety gate treats dry-run as always-safe, so a tool that mutates during dry-run would let an unconfirmed model call bypass the gate.
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"`
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"`
Confirmed bool `json:"confirmed,omitempty" jsonschema:"(optional) Must be true to actually execute"`
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 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.
Source Files