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 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 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 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 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 PlanExitOutcome ¶ added in v0.6.15

type PlanExitOutcome struct {
	Approved bool `json:"approved"`
}

PlanExitOutcome is the structured successful result of exit_plan_mode.

type PlanModeState ¶ added in v0.6.15

type PlanModeState interface {
	PlanModeActive() bool
	ExitPlanMode(context.Context) error
}

PlanModeState is the session-owned state used by exit_plan_mode. The tool reads and changes it without owning persistence or prompt assembly.

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 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 */
	// Detail and Intent are product-owned presentation hints. They are excluded
	// from the model-facing ask_user_question schema.
	Detail string         `json:"-" jsonschema:"-"`
	Intent QuestionIntent `json:"-" jsonschema:"-"`
}

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 QuestionIntent ¶ added in v0.6.15

type QuestionIntent string

QuestionIntent lets a product surface specialize a question without changing how answers flow back through Asker.

const QuestionIntentPlanReview QuestionIntent = "plan_review"

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.

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 TodoItem ¶ added in v0.6.15

type TodoItem struct {
	Content string     `json:"content" jsonschema:"description=One short imperative step,minLength=1,maxLength=200"`
	Status  TodoStatus `json:"status" jsonschema:"description=The step's current execution state,enum=pending,enum=in_progress,enum=completed"`
}

TodoItem is one concrete step in the current turn's execution checklist.

type TodoSnapshot ¶ added in v0.6.15

type TodoSnapshot struct {
	Todos []TodoItem `json:"todos"`
}

TodoSnapshot is the complete, canonical checklist returned to product projections. Every successful todo_write replaces the previous snapshot.

type TodoStatus ¶ added in v0.6.15

type TodoStatus string

TodoStatus is the model-visible lifecycle state of one checklist item.

const (
	TodoPending    TodoStatus = "pending"
	TodoInProgress TodoStatus = "in_progress"
	TodoCompleted  TodoStatus = "completed"
)

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 BrowserTabs(providers ...BrowserTabsProvider) Tool

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

func ExitPlanMode(asker Asker, state PlanModeState) Tool

func InspectBrowser(inspectors ...BrowserInspector) Tool

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

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

func (t Tool) Name() string