tools

Documentation

Overview

Package tools is the local tool registry: file access, command execution, CTF/reverse helpers, and the host-side task list tool. Every tool goes through the same approval gate and output budget.

Index

• func CommandOutput(name string, result CommandResult) []types.ContentBlock
• func CommandText(name string, result CommandResult) string
• func CreateReverseTools() []types.Tool
• func Find(list []types.Tool, name string) *types.Tool
• func Preview(text string, maxChars int) (string, bool)
• func ResolveShell() (string, error)
• func ShellCommand(command string) ([]string, error)
• type CommandResult
  • func Run(command []string, options RunOptions) (CommandResult, error)
• type RunOptions
• type SpillOptions
• type SpillResult
  • func SpillIfLarge(text string, options SpillOptions) SpillResult
• type StreamOptions
• type StreamedResult
  • func Stream(command []string, options StreamOptions) (StreamedResult, error)

Functions

func CommandOutput

func CommandOutput(name string, result CommandResult) []types.ContentBlock

func CommandText

func CommandText(name string, result CommandResult) string

CommandText is the transcript rendering of one command run: header, exit code, streams.

func CreateReverseTools

func CreateReverseTools() []types.Tool

CreateReverseTools returns the built-in registry, in the order the operator sees it in `/tools`.

func Find

func Find(list []types.Tool, name string) *types.Tool

Find looks a tool up by name.

func Preview

func Preview(text string, maxChars int) (string, bool)

func ResolveShell

func ResolveShell() (string, error)

ResolveShell returns a usable command shell for workspace shell escapes, run_command, and CLI runner scripts. Prefer stable system locations before PATH so a stale Homebrew-style bash symlink cannot shadow /bin/bash.

func ShellCommand

func ShellCommand(command string) ([]string, error)

ShellCommand builds argv for running a command through the resolved shell.

Types

type CommandResult

type CommandResult struct {
	Code   int
	Stdout string
	Stderr string
}

func Run

func Run(command []string, options RunOptions) (CommandResult, error)

Run executes a command, capturing both streams. The caller's context is honoured so the operator's ^C reaches the child too — otherwise an interrupted turn leaves a long `strings`/`objdump` running until its timeout.

type RunOptions

type RunOptions struct {
	Cwd       string
	TimeoutMs int
	Env       []string
	Ctx       context.Context
}

type SpillOptions

type SpillOptions struct {
	Context  types.ToolContext
	Label    string
	MaxChars int
}

type SpillResult

type SpillResult struct {
	Text string
	// Artifact is the absolute path of the full output, when it did not fit.
	Artifact      string
	OriginalChars int
}

func SpillIfLarge

func SpillIfLarge(text string, options SpillOptions) SpillResult

SpillIfLarge caps text at the policy budget. When it overflows, the full text is written to <sessionDir>/artifacts/ and referenced from the preview.

type StreamOptions

type StreamOptions struct {
	Cwd       string
	TimeoutMs int
	Env       []string
	Ctx       context.Context
	// OnChunk is called with each decoded chunk as it arrives, for live echoing.
	OnChunk func(stream string, text string)
}

type StreamedResult

type StreamedResult struct {
	CommandResult
	// TimedOut: the command exceeded TimeoutMs and was killed.
	TimedOut bool
	// Aborted: the caller's context fired (^C in the REPL) and the child was killed.
	Aborted bool
}

func Stream

func Stream(command []string, options StreamOptions) (StreamedResult, error)

Stream is Run with output handed to the caller as it arrives instead of only at exit, so a long command narrates itself. The full text is still captured.