tools

type BashExecOptions struct {
	// OnData is invoked with each chunk of stdout/stderr output as it
	// arrives. Chunks are NOT line-buffered; they reflect the underlying
	// pipe buffer boundaries. May be nil.
	OnData func(chunk []byte)
	// Timeout, if greater than zero, kills the process after the
	// duration. A zero value means no timeout.
	Timeout time.Duration
	// Env overrides the process environment. If nil, the current
	// process environment is inherited.
	Env []string
}

type BashExecResult struct {
	// ExitCode is the process exit code. -1 indicates the process was
	// killed (by signal, timeout, or context cancellation).
	ExitCode int
	// Stdout is the accumulated stdout bytes.
	Stdout []byte
	// Stderr is the accumulated stderr bytes.
	Stderr []byte
	// Signal is the signal name that killed the process, if any (e.g.
	// "KILL", "TERM"). Empty for normal exits.
	Signal string
}

type BashOperations interface {
	// Exec runs command in cwd and returns the accumulated output and
	// exit code. Streaming output (if opts.OnData is set) is delivered
	// as it arrives. ctx cancellation kills the process tree.
	Exec(ctx context.Context, command, cwd string, opts BashExecOptions) (BashExecResult, error)
}

type EditOperations interface {
	// ReadFile returns the file's current content.
	ReadFile(absolutePath string) ([]byte, error)
	// WriteFile replaces the file's content atomically (temp + rename).
	// The mode of the existing file (if any) is preserved; new files use
	// mode 0644.
	WriteFile(absolutePath string, content []byte) error
	// Access verifies the file is readable AND writable.
	Access(absolutePath string) error
}

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

type FindOperations interface {
	// IsDirectory returns true if absolutePath exists and is a directory.
	// Returns os.ErrNotExist (wrapped) if the path is missing.
	IsDirectory(absolutePath string) (bool, error)
	// WalkDir walks the file tree rooted at root, invoking fn for each
	// file and directory. Implementations MUST honor gitignore-style
	// external filtering (the caller applies gitignore internally); this
	// is just a directory traversal primitive.
	WalkDir(root string, fn fs.WalkDirFunc) error
}

type GrepOperations interface {
	// IsDirectory returns true if absolutePath exists and is a directory.
	// Returns os.ErrNotExist (wrapped) if the path is missing.
	IsDirectory(absolutePath string) (bool, error)
	// ReadFile returns the full content of the file at absolutePath.
	ReadFile(absolutePath string) ([]byte, error)
	// WalkDir walks the file tree rooted at root, invoking fn for each
	// file and directory. Implementations MUST honor gitignore-style
	// external filtering (the caller applies gitignore internally); this
	// is just a directory traversal primitive.
	WalkDir(root string, fn fs.WalkDirFunc) error
	// LookPath searches for the named executable on PATH. Returns the
	// full path on success, or an error matching exec.ErrNotFound on
	// failure. Used to detect whether ripgrep is installed.
	LookPath(name string) (string, error)
}

type HeadlessTool interface {
	// Name is the unique tool identifier. Lowercase ASCII, words
	// separated by dots (e.g., "read", "git.status"). The Registry
	// rejects duplicate names.
	Name() string

	// Description is a human- and model-readable summary of what the
	// tool does. Providers embed this verbatim in the tool definition.
	Description() string

	// Parameters returns the input JSON Schema. The schema MUST be
	// draft-2020-12 compliant so the provider can embed it directly.
	Parameters() jsonschema.Schema

	// Execute runs the tool. The context carries cancellation and
	// deadlines; tools MUST honor ctx.Done() promptly.
	//
	// call.Args is the raw JSON arguments payload from the model. Tools
	// validate it against their own Parameters() before running; a
	// validation failure produces a ToolResult with IsError=true and a
	// descriptive message rather than a returned error.
	//
	// A non-nil error is reserved for infrastructure failures (panic,
	// context cancellation, internal bug). Application-level failures
	// (file not found, command exit non-zero, validation error) are
	// returned as ToolResult.IsError=true.
	Execute(ctx context.Context, call ToolCall) (ToolResult, error)
}

type LSOperations interface {
	// IsDirectory returns true if absolutePath exists and is a directory.
	IsDirectory(absolutePath string) (bool, error)
	// ReadDir returns the entries within absolutePath, sorted by name.
	// The returned entries expose Name, IsDir, and Info via fs.DirEntry.
	ReadDir(absolutePath string) ([]fs.DirEntry, error)
}

type NoRender struct{}

type OSBashOperations struct{}

type OSEditOperations struct{}

type OSFindOperations struct{}

type OSGrepOperations struct{}

type OSLSOperations struct{}

type OSReadOperations struct{}

type OSWriteOperations struct{}

type ReadOperations interface {
	// ReadFile returns the raw bytes of the file at absolutePath.
	ReadFile(absolutePath string) ([]byte, error)
	// Access verifies the file is readable. Returns a descriptive error
	// (wrapping os.ErrNotExist, os.ErrPermission, etc.) if not.
	Access(absolutePath string) error
	// DetectImageMimeType returns the image MIME type (e.g. "image/png")
	// if the file at absolutePath is a supported image format, or "" if
	// it is not. A nil error with an empty string means "not an image";
	// the caller then falls through to the text/binary path.
	DetectImageMimeType(absolutePath string) (string, error)
}

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

type Theme struct {
	// Primary is the main accent color (tool name in call rendering).
	Primary string
	// Secondary is a supporting color (argument names, metadata keys).
	Secondary string
	// Accent is a high-attention color (active spinners, leaf indicators).
	Accent string
	// Success marks a successful (non-error) tool result.
	Success string
	// Error marks an errored tool result.
	Error string
	// Warning marks truncated output, partial results.
	Warning string
	// Muted is for low-priority text (timestamps, sizes).
	Muted string
	// Reset is the SGR reset sequence. Defaults to "\x1b[0m"; an empty
	// value is treated as the empty string for non-TTY themes.
	Reset string
	// Indent is the per-level indentation string used in rendered output.
	// Defaults to two spaces.
	Indent string
}

type Tool interface {
	HeadlessTool

	// RenderCall produces a human-readable representation of the tool
	// invocation for the TUI. The theme controls color/indentation; the
	// tools package uses ANSI codes directly so it has no TUI dependency.
	RenderCall(args json.RawMessage, theme *Theme) string

	// RenderResult produces a human-readable representation of the
	// tool's output. Used by the TUI when displaying completed tool
	// calls; never sent to the LLM.
	RenderResult(result ToolResult, theme *Theme) string
}

type ToolCall struct {
	// ID is the provider-assigned tool-use id. Echoed in ToolResult so
	// the provider can correlate results with calls.
	ID string `json:"id"`
	// Name is the tool name (matches Tool.Name()).
	Name string `json:"name"`
	// Args is the raw JSON arguments payload from the model. Tools parse
	// this against their own schema.
	Args json.RawMessage `json:"args,omitempty"`
	// Cwd is the working directory the agent loop has chosen for the
	// session. Tools that operate on files resolve relative paths
	// against this; tools that spawn subprocesses chdir here.
	Cwd string `json:"cwd,omitempty"`
}

type ToolResult struct {
	// Content is the LLM-facing content. Typically a single TextContent;
	// image-returning tools (read on a PNG/JPG) use ImageContent.
	Content []llm.ContentBlock `json:"content"`
	// IsError indicates the tool failed. The provider renders this as a
	// tool-call failure to the model. Set when the tool detected an
	// application-level error (file missing, validation failed,
	// command exit non-zero).
	IsError bool `json:"isError"`
	// Metadata carries tool-specific data for UI rendering (exit codes,
	// line counts, paths). Not sent to the LLM. Keys are tool-defined;
	// see each tool's doc for the shape.
	Metadata map[string]any `json:"metadata,omitempty"`
}

type WriteOperations interface {
	// WriteFile writes content atomically (temp + rename). The mode of
	// the existing file (if any) is preserved; new files use mode 0644.
	WriteFile(absolutePath string, content []byte) error
	// Stat returns the os.FileInfo for the path, or os.ErrNotExist if
	// the path does not exist. Used to detect overwrites and to refuse
	// to write to directories.
	Stat(absolutePath string) (fs.FileInfo, error)
}