Documentation
¶
Overview ¶
Package bash provides a shell command execution tool for the ore tool extension.
It exports a pre-built Bash tool function together with its provider.Tool JSON-schema descriptor, so applications can register it in a tool.Registry without defining the logic inline.
WARNING: The bash tool executes arbitrary shell commands on the host system. There is no sandbox, allowlist, or confirmation prompt. Register this tool only in trusted, isolated environments.
Usage:
registry := tool.NewRegistry()
if err := registry.Register(bash.BashTool.Name, bash.BashTool.Description, bash.BashTool.Schema, bash.Bash); err != nil {
...
}
// Registry.Tools() is the single source of truth for the provider.
tools := registry.Tools()
See also: x/tool/bash/bash.go for the tool implementation.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var BashTool = tool.Tool{ Name: "bash", Description: "Execute a shell command. Returns stdout, stderr, and exit code.\n\n" + "Output limits: stdout and stderr are each captured by a streaming, " + "bounded-memory accumulator. When a stream exceeds the cap, the full " + "output is written to a temp file (path included in the result) and " + "only the tail is returned.\n\n" + "Recovery: when truncation occurs, the result includes the temp file " + "path. Use read_file on the path to read the full output, or use " + "grep/tail/head on it to extract the relevant lines.", Schema: map[string]any{ "type": "object", "properties": map[string]any{ "command": map[string]any{ "type": "string", "description": "The shell command to execute.", }, "working_directory": map[string]any{ "type": "string", "description": "The directory to execute the command in. Defaults to the current working directory.", }, "timeout_seconds": map[string]any{ "type": "integer", "description": "Maximum execution time in seconds. Defaults to 30.", "default": 30, }, }, "required": []string{"command"}, }, DisplayHint: BashDisplayHint, Format: tool.Format{ Truncate: tool.TruncateConfig{ MaxBytes: 50_000, MaxLines: 2_000, }, }, }
BashTool is the tool.Tool descriptor for Bash.
Functions ¶
func Bash ¶
Bash executes a shell command and returns its stdout, stderr, and exit code. Output is captured by a streaming, bounded accumulator (BoundedBuffer) that retains a rolling 2*frameworkDefaultTailCap tail in memory and spills the full byte stream to a temp file when the cap is exceeded. The temp file path is included in the result so the LLM can read the full output via read_file.
Parameters:
- command (string, required): the shell command to execute.
- working_directory (string, optional): the directory to execute the command in.
- timeout_seconds (number, optional, default 30): maximum execution time in seconds.
func BashDisplayHint ¶ added in v0.3.0
BashDisplayHint is the display-hint formatter for the bash tool.
Types ¶
type BoundedBuffer ¶ added in v0.3.5
type BoundedBuffer struct {
// contains filtered or unexported fields
}
BoundedBuffer is an io.Writer that retains only a rolling 2*cap tail in memory and optionally spills the full byte stream to a temp file (created lazily on first overflow). The Write method never blocks and never returns an error (other than from the underlying temp file write).
Mechanics:
- Internally, BoundedBuffer keeps a single byte slice "tail" of length at most 2*cap. On each Write, the bytes are appended to the slice; if the result exceeds 2*cap, the front is dropped to maintain the cap.
- The first time tail exceeds cap, a temp file is opened (os.CreateTemp with prefix "ore-bash-") and the cumulative tail content is written to it. Subsequent writes are also appended to the file, so the file always contains the full byte stream from the first overflow onwards.
- Path() returns the temp file path, or "" if no spill has occurred.
- Close() closes the temp file. It is safe to call Close on a BoundedBuffer that has not spilled.
- TotalBytes() returns the number of bytes that have been written to the buffer, including bytes that have been dropped from the in-memory tail. When a spill has occurred, this is the size of the temp file (and the total subprocess output); when no spill has occurred, this equals len(tail).
- The struct is safe for concurrent use. The mutex serializes access to the tail and the temp file. The bash tool only writes from a single goroutine (cmd.Stdout), so contention is not a concern in practice; the lock is defensive.
func NewBoundedBuffer ¶ added in v0.3.5
func NewBoundedBuffer(cap int) *BoundedBuffer
NewBoundedBuffer creates a BoundedBuffer that retains at most 2*cap bytes in memory. A non-positive cap is treated as frameworkDefaultTailCap.
func (*BoundedBuffer) Bytes ¶ added in v0.3.5
func (b *BoundedBuffer) Bytes() []byte
Bytes returns the current in-memory tail as a byte slice. The returned slice is a copy; callers may modify it freely.
func (*BoundedBuffer) Close ¶ added in v0.3.5
func (b *BoundedBuffer) Close() error
Close closes the temp file. It is safe to call Close on a BoundedBuffer that has not spilled. The temp file is NOT removed; the caller (typically the bash tool) keeps the path so the LLM can read the full output via read_file.
func (*BoundedBuffer) Path ¶ added in v0.3.5
func (b *BoundedBuffer) Path() string
Path returns the temp file path, or "" if no spill has occurred.
func (*BoundedBuffer) Spilled ¶ added in v0.3.5
func (b *BoundedBuffer) Spilled() bool
Spilled reports whether the buffer has spilled to a temp file.
func (*BoundedBuffer) String ¶ added in v0.3.5
func (b *BoundedBuffer) String() string
String returns the current in-memory tail as a string. The returned string is a copy; callers may modify it freely.
func (*BoundedBuffer) TotalBytes ¶ added in v0.3.5
func (b *BoundedBuffer) TotalBytes() int64
TotalBytes returns the total number of bytes written to the buffer, including bytes that have been dropped from the in-memory tail. When a spill has occurred, this equals the size of the temp file (the full subprocess output).
func (*BoundedBuffer) Write ¶ added in v0.3.5
func (b *BoundedBuffer) Write(p []byte) (int, error)
Write appends p to the buffer. It never returns an error except in the pathological case where the temp file write fails; in that case, Write returns the error and the bytes are still retained in the in-memory tail so the rest of the stream is not lost.
type Result ¶ added in v0.2.1
type Result struct {
Stdout string `json:"stdout"`
Stderr string `json:"stderr"`
ExitCode int `json:"exit_code"`
StdoutPath string `json:"stdout_path,omitempty"`
StderrPath string `json:"stderr_path,omitempty"`
Truncation *artifact.Truncation `json:"truncation,omitempty"`
}
Result holds the output of a shell command execution. The streaming output capture in runCommand bounds each stream (stdout, stderr) to a rolling 2*frameworkDefaultTailCap tail in memory and, if a stream exceeds the cap, spills the full byte stream to a temp file. The path is exposed in StdoutPath / StderrPath so the LLM can read the full output via read_file.
func (*Result) MarshalLLM ¶ added in v0.3.5
MarshalLLM returns the LLM-facing string representation. It implements artifact.LLMRenderer; the framework handler respects this output verbatim (no further truncation). When the output was spilled to a temp file, the LLM-facing message includes a recovery hint pointing the model to the temp file.
The recovery hint is rendered with the tool's standard template. The temp file path is included in the hint as {path}. A "X lines shown of Y total" notice is appended when stdout or stderr was truncated.
func (*Result) MarshalMarkdown ¶ added in v0.2.1
MarshalMarkdown renders the result as human-readable Markdown. Fenced code blocks for stdout and stderr are omitted if empty.
Source Files