tools

type Answer ¶

type Answer struct {
	Question string   `json:"question"`
	Values   []string `json:"values"`
}

Answer is the user's response to one Question. Values holds one entry for a single-select question and may hold several for a multi-select one; free text the user typed instead of picking an option arrives here unchanged.

type Asker ¶

type Asker interface {
	Ask(context.Context, []Question) ([]Answer, error)
}

Asker puts questions to the user and blocks until they answer. Implementations must honor ctx cancellation, so aborting a run cannot leave a question waiting forever, and must not invent an answer the user did not give: a cancelled or abandoned question is an error, not an empty answer.

type BrowserControlCapability ¶

type BrowserControlCapability string

const (
	BrowserControlRead     BrowserControlCapability = "read"
	BrowserControlNavigate BrowserControlCapability = "navigate"
	BrowserControlInteract BrowserControlCapability = "interact"
)

type BrowserControlledTab ¶

type BrowserControlledTab struct {
	TabID        string                     `json:"tabID"`
	Capabilities []BrowserControlCapability `json:"capabilities"`
}

BrowserControlledTab describes temporary Agent attachment to an open tab. It intentionally does not record who originally created the tab.

type BrowserController ¶

type BrowserController interface {
	OpenBrowser(context.Context, BrowserRequest) (BrowserResult, error)
}

BrowserController delivers a navigation command to the product shell and waits for its terminal acknowledgement.

type BrowserDisposition ¶

type BrowserDisposition string

BrowserDisposition describes where a product shell should apply an agent navigation request. Reuse prefers the selected Agent-controlled tab and is the default; new tabs require an explicit user request surfaced by the model.

const (
	BrowserReuseAgentTab    BrowserDisposition = "reuse_agent_tab"
	BrowserNewForegroundTab BrowserDisposition = "new_foreground_tab"
	BrowserNewBackgroundTab BrowserDisposition = "new_background_tab"
)

type BrowserInspectionResult ¶

type BrowserInspectionResult struct {
	ID          string
	Status      BrowserInspectionStatus
	URL         string
	Title       string
	PageStatus  BrowserPageStatus
	Revision    int
	VisibleText string
	Truncated   bool
	Error       string
}

BrowserInspectionResult is a bounded, read-only observation of one open tab in the requesting session. It intentionally contains no DOM, storage, cookies, form values, or executable page code.

type BrowserInspectionStatus ¶

type BrowserInspectionStatus string

const (
	BrowserInspectionCompleted BrowserInspectionStatus = "completed"
	BrowserInspectionFailed    BrowserInspectionStatus = "failed"
	BrowserInspectionCancelled BrowserInspectionStatus = "cancelled"
	BrowserInspectionTimeout   BrowserInspectionStatus = "timeout"
)

type BrowserInspector ¶

type BrowserInspector interface {
	InspectBrowser(context.Context, string) (BrowserInspectionResult, error)
}

type BrowserOpenTab ¶

type BrowserOpenTab struct {
	TabID  string           `json:"tabID"`
	URL    string           `json:"url,omitempty"`
	Title  string           `json:"title,omitempty"`
	Status BrowserTabStatus `json:"status"`
}

BrowserOpenTab is bounded metadata for one tab in the requesting session's browser workspace. TabID is stable until that tab is closed.

type BrowserPageStatus ¶

type BrowserPageStatus string

const (
	BrowserPageReady      BrowserPageStatus = "ready"
	BrowserPageNavigating BrowserPageStatus = "navigating"
	BrowserPageFailed     BrowserPageStatus = "failed"
)

type BrowserRequest ¶

type BrowserRequest struct {
	Preview     PreviewRequest
	Disposition BrowserDisposition
}

BrowserRequest is the validated navigation intent handed to the product transport. It contains no Electron view or renderer state.

type BrowserResult ¶

type BrowserResult struct {
	ID           string
	Status       BrowserResultStatus
	RequestedURL string
	CommittedURL string
	Title        string
	Error        string
	Preview      PreviewRequest
}

BrowserResult is the product shell's terminal acknowledgement. RequestedURL and CommittedURL remain separate so redirects are visible to the model.

type BrowserResultStatus ¶

type BrowserResultStatus string

BrowserResultStatus is a terminal browser-command outcome. A controller must return exactly one terminal result for each accepted request.

const (
	BrowserCommitted BrowserResultStatus = "committed"
	BrowserFailed    BrowserResultStatus = "failed"
	BrowserCancelled BrowserResultStatus = "cancelled"
	BrowserTimeout   BrowserResultStatus = "timeout"
)

type BrowserTabStatus ¶

type BrowserTabStatus string

const (
	BrowserTabIdle       BrowserTabStatus = "idle"
	BrowserTabNavigating BrowserTabStatus = "navigating"
	BrowserTabReady      BrowserTabStatus = "ready"
	BrowserTabFailed     BrowserTabStatus = "failed"
)

type BrowserTabsProvider ¶

type BrowserTabsProvider interface {
	BrowserTabs(context.Context) (BrowserTabsResult, error)
}

type BrowserTabsResult ¶

type BrowserTabsResult struct {
	ID             string
	Status         BrowserTabsStatus
	OpenTabs       []BrowserOpenTab
	ControlledTabs []BrowserControlledTab
	Selected       string
	Error          string
}

type BrowserTabsStatus ¶

type BrowserTabsStatus string

const (
	BrowserTabsCompleted BrowserTabsStatus = "completed"
	BrowserTabsFailed    BrowserTabsStatus = "failed"
	BrowserTabsCancelled BrowserTabsStatus = "cancelled"
	BrowserTabsTimeout   BrowserTabsStatus = "timeout"
)

type ChangeKind ¶

type ChangeKind string

ChangeKind reports whether a write created a new file or updated an existing one.

const (
	ChangeCreate ChangeKind = "create"
	ChangeUpdate ChangeKind = "update"
)

type ExecOps ¶

type ExecOps interface {
	// Exec runs command in a shell within dir and returns its combined output.
	// A non-zero exit code is reported in ExecResult, not as an error; an error
	// is returned only when the command could not be started. Exec must honor ctx
	// cancellation (e.g. a timeout).
	Exec(ctx context.Context, command string, dir string) (ExecResult, error)
	// Start launches command in a shell within dir, writing its combined output
	// to out, and returns once the command is running. A background command
	// outlives the turn that started it, so it is bounded by its Process rather
	// than by a context.
	Start(command string, dir string, out io.Writer) (Process, error)
}

ExecOps abstracts shell command execution for the bash tool. Both the foreground and the background paths go through it, so a backend that sandboxes, containerizes, or forwards commands governs every command the session runs rather than only the ones the model waits on.

type ExecResult ¶

type ExecResult struct {
	// Output is the combined stdout and stderr.
	Output string
	// ExitCode is the process exit status. Zero means success.
	ExitCode int
}

ExecResult is the outcome of one shell command.

type FileChange ¶

type FileChange struct {
	// Path is the file path as the model supplied it (relative to the workspace
	// root when the input was relative), so it can be passed straight to read.
	Path string
	// Kind is create for a new file or update for an existing one.
	Kind ChangeKind
	// Additions and Deletions are the line counts of the change.
	Additions int
	Deletions int
	// Hunks is the diff. A newly created non-empty file is represented as a diff
	// from an empty file. Lines within a hunk are prefixed with " ", "+", or "-".
	Hunks []Hunk
	// Bytes is the size of the content written.
	Bytes int
}

FileChange is the structured result of a successful edit or write. It is the single source of truth: the tool's text Content is formatted from it, and UIs render it directly.

type FileOps ¶

type FileOps interface {
	Open(ctx context.Context, path string) (io.ReadCloser, error)
	ReadFile(ctx context.Context, path string) ([]byte, error)
	// WriteFile replaces path without exposing a partially written destination
	// when the backend supports atomic replacement.
	WriteFile(ctx context.Context, path string, data []byte, perm os.FileMode) error
	MkdirAll(ctx context.Context, path string, perm os.FileMode) error
	Stat(ctx context.Context, path string) (os.FileInfo, error)
	ReadDir(ctx context.Context, path string) ([]os.DirEntry, error)
}

FileOps abstracts filesystem access for the file tools. Paths passed to it are already resolved to absolute form by the tool. Implementations must honor ctx cancellation where the underlying operation supports it.

type FileStateStore ¶

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

FileStateStore tracks disk versions observed by one coding tool set. It is safe for concurrent reads while mutating tools execute sequentially.

func NewFileStateStore() *FileStateStore

func (s *FileStateStore) Check(path string, info os.FileInfo) error

func (s *FileStateStore) Delete(path string)

func (s *FileStateStore) Record(path string, info os.FileInfo)

type FileVersion ¶

type FileVersion struct {
	ModTime time.Time
	Size    int64
}

FileVersion is the portable, inexpensive identity used for optimistic file concurrency checks. It deliberately avoids hashing the full file so a small range read of a large file remains a range read.

func (v FileVersion) Equal(other FileVersion) bool

type Hunk ¶

type Hunk struct {
	OldStart int
	OldLines int
	NewStart int
	NewLines int
	// Lines carry a leading " ", "+", or "-" marking context, addition, or
	// deletion.
	Lines []string
}

Hunk is one contiguous region of a unified diff. Start lines are 1-based.

type LocalOps ¶

type LocalOps struct{}

LocalOps runs against the local filesystem and a bash shell. It is the default backend and holds no state.

func (LocalOps) Exec(ctx context.Context, command string, dir string) (ExecResult, error)

func (LocalOps) MkdirAll(ctx context.Context, path string, perm os.FileMode) error

func (LocalOps) Open(ctx context.Context, path string) (io.ReadCloser, error)

func (LocalOps) ReadDir(_ context.Context, path string) ([]os.DirEntry, error)

func (LocalOps) ReadFile(_ context.Context, path string) ([]byte, error)

func (LocalOps) Start(command string, dir string, out io.Writer) (Process, error)

func (LocalOps) Stat(_ context.Context, path string) (os.FileInfo, error)

func (LocalOps) WriteFile(ctx context.Context, path string, data []byte, perm os.FileMode) error

type MutationFailure ¶

type MutationFailure struct {
	// Path is the file path the model supplied.
	Path string
	// Reason is a stable machine code for the failure class.
	Reason string
	// Detail is the human-facing explanation, matching the text summary.
	Detail string
}

MutationFailure is the structured result attached to a failed edit or write, so a shell can show why the write did not happen rather than only a text blob.

type Ops ¶

type Ops interface {
	FileOps
	ExecOps
}

Ops is the full operation surface the built-in tools need. LocalOps satisfies it; a custom backend can compose its own value from a FileOps and an ExecOps.

type Option ¶

type Option struct {
	Label string `json:"label" jsonschema:"description=Display text for this option. Keep it to a few words,minLength=1"`
	// Description explains what choosing this option means. It gives the user
	// the trade-off the model already knows but the label has no room for.
	Description string `json:"description" jsonschema:"description=What this option means or what happens if it is chosen. State the trade-off"`
}

Option is one selectable answer to a Question.

type PreviewRequest ¶

type PreviewRequest struct {
	URL          string
	Path         string
	RelativePath string
	Title        string
	GrantID      string
	PreviewPath  string
}

PreviewRequest is the structured UI intent emitted by open_preview. Product shells act on it live, and ToolOutcome.Data retains it so a reopened conversation can offer the same preview again.

type Process ¶ added in v0.6.2

type Process interface {
	// Wait blocks until the command exits and reports its exit code. A command
	// that exits non-zero is not an error; a failure to wait on it is, and
	// reports exit code -1.
	Wait() (exitCode int, err error)
	// Stop asks the command to exit and returns without waiting for it.
	Stop() error
	// Kill terminates the command immediately.
	Kill() error
}

Process is one running background command. Implementations must terminate everything the command spawned, not just the shell that fronts it.

type Question ¶

type Question struct {
	Question string `json:"question" jsonschema:"description=The complete question. Make it specific and end it with a question mark,minLength=1"`
	// Header labels the question in the product surface, where a full sentence
	// does not fit.
	Header      string   `` /* 134-byte string literal not displayed */
	Options     []Option `json:"options" jsonschema:"description=The available choices. Each must be distinct,minItems=2,maxItems=4"`
	MultiSelect bool     `` /* 151-byte string literal not displayed */
}

Question is one multiple-choice question put to the user. The same type is both the model-facing schema and the value handed to an Asker so the product shell renders exactly what the model asked.

type QuestionAnswers ¶

type QuestionAnswers struct {
	Questions []Question `json:"questions"`
	Answers   []Answer   `json:"answers"`
}

QuestionAnswers is the structured result product shells render.

type ReadResult ¶

type ReadResult struct {
	Path       string
	Content    string
	StartLine  int
	LineCount  int
	Limit      int
	HasMore    bool
	NextOffset int
}

ReadResult is the provider- and UI-independent result of a text range read. Content does not include line-number prefixes; those are added only when the result is serialized for the model.

type TaskInfo ¶

type TaskInfo struct {
	ID          string
	Command     string
	Description string
	OutputPath  string
	StartedAt   time.Time
}

TaskInfo is returned immediately after a background task starts.

type TaskManager ¶

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

TaskManager owns background processes and their output files for one coding session. Tasks run in separate process groups, survive across turns, and are stopped and removed when the session closes.

Commands are launched through the session's ExecOps, the same seam the foreground bash tool uses, so a backend cannot be bypassed by asking for a background task.

func NewTaskManager(ops ExecOps) *TaskManager

func (m *TaskManager) Completed() []TaskState

func (m *TaskManager) OwnsOutputPath(path string) bool

func (m *TaskManager) ReadOutput(id string, maxBytes int64) (TaskOutput, error)

func (m *TaskManager) Shutdown()

func (m *TaskManager) Snapshot() []TaskState

func (m *TaskManager) Start(command, description, dir string) (TaskInfo, error)

func (m *TaskManager) Stop(id string) error

func (m *TaskManager) Subscribe(listener func(TaskState)) func()

type TaskOutput ¶

type TaskOutput struct {
	Content   string
	Truncated bool
}

TaskOutput is a bounded tail of one task's combined stdout and stderr.

type TaskState ¶

type TaskState struct {
	TaskInfo
	Status      TaskStatus
	ExitCode    *int
	CompletedAt time.Time
}

TaskState is the latest state of one managed background task. CompletedAt is zero and ExitCode is nil while the task is running.

type TaskStatus ¶

type TaskStatus string

TaskStatus is the lifecycle state of a background task.

const (
	TaskRunning   TaskStatus = "running"
	TaskSucceeded TaskStatus = "succeeded"
	TaskFailed    TaskStatus = "failed"
	TaskStopped   TaskStatus = "stopped"
)

type Tool ¶

type Tool struct {
	agent.AgentTool

	// Guidelines are bullet points appended to the system prompt's guidelines
	// section while this tool is active. A tool's own description travels in its
	// schema; only rules that span tools belong here.
	Guidelines []string
	// AccessFor describes the effects of one validated call. A nil function is
	// treated as unknown access and therefore requires approval.
	AccessFor func(args map[string]any) []permission.Access
}

Tool is a coding-agent tool: the executable agent.AgentTool the model calls, plus the metadata the tool contributes to the system prompt. Keeping prompt contribution on the tool itself means the system prompt is assembled from whichever tools are active, rather than maintained as one central block.

func AskUserQuestion(asker Asker) Tool

func Bash(root string, ops ExecOps, tasks *TaskManager) Tool

func BrowserTabs(providers ...BrowserTabsProvider) Tool

func BrowserTools(root string, browserControllers ...BrowserController) []Tool

func Edit(root string, ops FileOps, files *FileStateStore) Tool

func Glob(root string, ops FileOps) Tool

func Grep(root string, ops FileOps) Tool

func InspectBrowser(inspectors ...BrowserInspector) Tool

func OpenPreview(root string, controllers ...BrowserController) Tool

func Read(root string, ops FileOps, files *FileStateStore, trustedPaths ...func(string) bool) Tool

func TaskStop(tasks *TaskManager) Tool

func Write(root string, ops FileOps, files *FileStateStore) Tool

func (t Tool) Accesses(args map[string]any) []permission.Access

func (t Tool) Name() string