tools

type CommandEnv struct {
	Inherit        string // all, core or none
	ExcludeSecrets bool
	Vars           []string // KEY=VALUE entries given to every command
	Passed         []string // sorted names in Vars
	Withheld       []string // sorted names in tinyagent's environment not in Vars
	Missing        []string // pass entries that matched nothing
}

type CommandTool struct {
	Name        string
	Description string
	Schema      *outschema.Schema
	Argv        []string // template; placeholders are whole elements
	Timeout     time.Duration
	Dir         string // absolute working directory inside Root
}

type Container struct {
	Runtime string // docker or podman
	Image   string
	ID      string
	Mount   string // host directory mounted at the same path
	// Extra are additional directories mounted at the same paths; read
	// mode ones are mounted read-only.
	Extra []ExtraDir
}

type DeniedError struct {
	Path    string // the path as the caller named it
	List    string // "deny_read" or "deny_write"
	Pattern string // the rule that matched, as configured
}

type Environment interface {
	// Command returns an unstarted `bash -c command` that runs in root.
	// Cancelling ctx must kill the command and everything it spawned.
	Command(ctx context.Context, root, command string) *exec.Cmd
	// Exec returns an unstarted command that runs argv directly, without a
	// shell, in root. argv[0] is looked up on the environment's PATH.
	// Cancelling ctx must kill the command and everything it spawned.
	Exec(ctx context.Context, root string, argv []string) *exec.Cmd
}

type Executor struct {
	Root           string // absolute working directory
	ReadOnly       bool   // permits only read_file, list_files, and grep
	BashTimeout    time.Duration
	MaxOutputChars int // 0 = unlimited
	// MaxProcesses bounds concurrently running background processes
	// (0 = DefaultMaxProcesses).
	MaxProcesses int
	// ProcessBufferBytes caps the output kept per background process
	// (0 = DefaultProcessBufferBytes); older output is dropped.
	ProcessBufferBytes int
	// Env decides where bash and start_process commands run. nil means
	// Local{}: on the host, unsandboxed.
	Env Environment
	// Stream receives bash output as it is produced when a call sets
	// stream: true. nil discards it (the result is unchanged either way).
	Stream io.Writer
	// CommandTools are the configured command_tools (never offered or run
	// in read-only mode). CommandLog, when set, gets one line per call
	// with the final argv.
	CommandTools  []*CommandTool
	CommandLog    io.Writer
	ExternalSpecs []model.ToolSpec
	// ExternalCall runs a tool from ExternalSpecs. ok is false when name is
	// not an external tool; isErr marks a failed call.
	ExternalCall func(ctx context.Context, name, args string) (out string, isErr, ok bool)
	// Plan offers the opt-in update_plan tool (also in read-only mode). The
	// agent handles its calls; the executor only advertises it.
	Plan bool
	// Images offers the opt-in view_image tool (also in read-only mode) and
	// lets ExternalCallImages pass MCP images through. MaxImageBytes caps
	// one image (0 = DefaultMaxImageBytes).
	Images        bool
	MaxImageBytes int
	// ExternalCallImages, when set and Images is on, replaces ExternalCall
	// and also returns the result's images.
	ExternalCallImages func(ctx context.Context, name, args string) (out string, images []model.Image, isErr, ok bool)
	// Skills, when it holds at least one skill, adds the read-only skill
	// tool (also in read-only mode). nil or empty offers nothing.
	Skills *skills.Set
	// ApplyPatch offers the opt-in apply_patch tool (never in read-only
	// mode).
	ApplyPatch bool
	// Delegate offers the opt-in delegate tool (also in read-only mode).
	// The agent loop runs its calls; the executor never does.
	Delegate bool
	// WebFetch, when set, offers the opt-in web_fetch tool (also in
	// read-only mode). nil leaves it off.
	WebFetch *WebFetcher
	// LSP, when set, offers the opt-in read-only lsp tool (also in
	// read-only mode) and, with AfterEdit, appends language-server
	// diagnostics to write_file, edit_file and apply_patch results. nil
	// leaves both off.
	LSP *LSP
	// AskUser offers the opt-in ask_user tool (also in read-only mode).
	// The agent loop handles its calls; the executor never runs them.
	AskUser bool
	// OutputFiles, when set, saves the full text of over-limit results to a
	// per-run file and keeps that directory out of grep and list_files
	// walks. nil keeps plain truncation.
	OutputFiles *OutputFiles
	// FileAccess denies the built-in file tools access to configured paths
	// (file_access config). nil denies nothing. It does not apply to bash,
	// start_process, hooks or MCP servers.
	FileAccess *FileAccess
	// ExtraDirs are additional directories outside Root that the built-in
	// file tools may reach by absolute path (additional_dirs). Read-mode
	// directories, and all of them in read-only mode, refuse writes. nil
	// keeps the tools inside Root.
	ExtraDirs []ExtraDir
	// Redactor, when set (redact_secrets), masks known secret values in
	// the results of every tool except the built-in file tools, before
	// truncation, saving and hooks. nil masks nothing.
	Redactor *eventlog.Redactor
	// contains filtered or unexported fields
}

type ExtraDir struct {
	Path string `json:"path"`
	Mode string `json:"mode"`
}

type FileAccess struct {
	// contains filtered or unexported fields
}

type LSP struct {
	Manager *lsp.Manager
	// AfterEdit appends diagnostics to edit results.
	AfterEdit bool
	// Wait is the longest wait for diagnostics.
	Wait time.Duration
	// Max caps the diagnostics listed per file.
	Max int
	// Warnings also reports warnings (severity: warning).
	Warnings bool
}

type Local struct {
	Sandbox *Sandbox
	// CommandEnv, when non-nil, is the whole environment commands get;
	// nil inherits tinyagent's.
	CommandEnv *CommandEnv
}

type OutputFiles struct {
	Root  string // absolute working root (--cwd)
	Dir   string // absolute output directory, inside Root
	RunID string
	// Warn, when set, reports the first save failure of the run.
	Warn func(string)
	// contains filtered or unexported fields
}

type ReadDirError struct {
	Path string // the path as the caller named it
	Dir  string // the additional directory
}

type RegisteredProcess struct {
	ID      string
	PID     int
	Command string
	Running bool
}

type Result struct {
	Text    string
	Images  []model.Image
	IsError bool
	// OutputFile is the saved full output (relative to Root, slash
	// separated) when OutputFiles is on and the text was over the limit.
	OutputFile  string
	OutputBytes int
	// Notice is the line ending Text that points at the saved file (or, for
	// read_file, at the rest of the file); empty when none was added.
	Notice string
	// Paths are the absolute paths a successful built-in file tool call
	// touched: read_file, write_file, edit_file, view_image and lsp's
	// path, list_files and grep's path argument (default "."), and every
	// file an apply_patch call added, updated, deleted or moved. They may
	// lie outside Root (additional directories); nil for other tools and
	// for failed calls.
	Paths []string
	// Instructions is the suffix of Text holding scoped AGENTS.md blocks
	// appended by the agent loop; feedback re-truncation keeps it whole.
	Instructions string
	// Redactions counts the secret values Redactor masked in the result.
	Redactions int
}

type Sandbox struct {
	Backend  string   // e.g. "landlock (ABI 6)" or "seatbelt"
	Writable []string // directories commands may write, including Tmp
	Network  bool
	// AllowedDomains, when set, are the only hosts commands may reach, over
	// HTTP and HTTPS through a proxy tinyagent runs outside the sandbox.
	AllowedDomains []string
	Tmp            string // per-run temporary directory, exported as TMPDIR
	// contains filtered or unexported fields
}

type WebFetchRecord struct {
	URL          string
	FinalURL     string
	Status       int
	ContentType  string
	Bytes        int
	Truncated    bool
	Duration     time.Duration
	DeniedReason string
	Error        string
}

type WebFetcher struct {
	// Domains are the configured web_fetch.allowed_domains entries.
	Domains []string

	MaxBytes int
	Timeout  time.Duration
	// UserAgent is sent with every request.
	UserAgent string

	// Resolve and Dial default to the system resolver and a net.Dialer;
	// tests replace them.
	Resolve func(ctx context.Context, host string) ([]netip.Addr, error)
	Dial    func(ctx context.Context, network, addr string) (net.Conn, error)
	// contains filtered or unexported fields
}