tools

type ActionRoute struct {
	Action    string
	Tool      ID
	FixedArgs map[string]string
}

type ActionTool struct {
	Kind              ID
	Routes            []ActionRoute
	BypassPermissions bool
	// RequirePersistedChat hides and rejects resources whose results need a
	// durable client-visible destination.
	RequirePersistedChat bool
	// DefaultAction accepts historical calls that predate the action field when
	// a canonical resource reuses an older single-operation name.
	DefaultAction string
}

type BashStoredResult struct {
	Command   string `json:"command"`
	Workdir   string `json:"workdir"`
	TimeoutMS int64  `json:"timeout_ms"`
	ExitCode  int    `json:"exit_code"`
	Output    string `json:"output,omitempty"`
}

type BrowserStoredResult struct {
	Kind       string               `json:"kind"`
	SessionID  string               `json:"session_id,omitempty"`
	Path       string               `json:"path,omitempty"`
	Summary    string               `json:"summary,omitempty"`
	Text       string               `json:"text,omitempty"`
	Attachment *attachment.Metadata `json:"attachment,omitempty"`
}

type ChatListStoredResult struct {
	Items []ChatStoredItem `json:"items,omitempty"`
}

type ChatStatusControl interface {
	SetChatActivity(context.Context, domain.ChatActivity) (domain.Chat, error)
}

type ChatStoredItem struct {
	ID                 id.ID  `json:"id"`
	Title              string `json:"title"`
	Role               string `json:"role,omitempty"`
	Backend            string `json:"backend,omitempty"`
	InteractionMode    string `json:"interaction_mode,omitempty"`
	ModelID            string `json:"model_id,omitempty"`
	PermissionProfile  string `json:"permission_profile,omitempty"`
	State              string `json:"state,omitempty"`
	Archived           bool   `json:"archived,omitempty"`
	QueuedInputs       int    `json:"queued_inputs,omitempty"`
	ActiveMilestoneKey string `json:"active_milestone_key,omitempty"`
	AssignedTaskRef    string `json:"assigned_task_ref,omitempty"`
	StatusText         string `json:"status_text,omitempty"`
	Response           string `json:"response,omitempty"`
}

type CompactFormatLimits struct {
	MaxBytes      int
	HeadLines     int
	TailLines     int
	ReadMaxLines  int
	ExecHeadLines int
	ExecTailLines int
}

type DeniedError struct {
	Tool   ID
	Reason string
}

type DeniedStoredResult struct {
	Message string `json:"message"`
}

type DiagnosticReportStored struct {
	Diagnostics []DiagnosticStored `json:"diagnostics,omitempty"`
	Skipped     []string           `json:"skipped,omitempty"`
}

type DiagnosticStored struct {
	Source   string `json:"source,omitempty"`
	Path     string `json:"path,omitempty"`
	Line     int    `json:"line,omitempty"`
	Column   int    `json:"column,omitempty"`
	Severity string `json:"severity,omitempty"`
	Tool     string `json:"tool,omitempty"`
	Code     string `json:"code,omitempty"`
	Message  string `json:"message,omitempty"`
}

type EditStoredHunk struct {
	OldStart int      `json:"old_start"`
	NewStart int      `json:"new_start"`
	OldLines []string `json:"old_lines,omitempty"`
	NewLines []string `json:"new_lines,omitempty"`
}

type EditStoredResult struct {
	Path             string                 `json:"path"`
	ReplaceAll       bool                   `json:"replace_all,omitempty"`
	Occurrences      int                    `json:"occurrences,omitempty"`
	Summary          string                 `json:"summary,omitempty"`
	Matcher          string                 `json:"matcher,omitempty"`
	Verification     string                 `json:"verification,omitempty"`
	Diagnostics      string                 `json:"diagnostics,omitempty"`
	DiagnosticReport DiagnosticReportStored `json:"diagnostic_report,omitempty"`
	Diff             string                 `json:"diff,omitempty"`
	Hunks            []EditStoredHunk       `json:"hunks,omitempty"`
	Truncated        bool                   `json:"truncated,omitempty"`
}

type ErrorStoredResult struct {
	Message string `json:"message"`
}

type ExecListStoredItem struct {
	ProcessID string `json:"process_id"`
	Command   string `json:"command"`
	State     string `json:"state"`
	TTY       bool   `json:"tty,omitempty"`
	ExitCode  *int   `json:"exit_code,omitempty"`
	Output    string `json:"output,omitempty"`
}

type ExecListStoredResult struct {
	Scope   string               `json:"scope,omitempty"`
	Message string               `json:"message,omitempty"`
	Items   []ExecListStoredItem `json:"items,omitempty"`
}

type ExecProcess struct {
	ProcessID   string                   `json:"process_id"`
	Command     string                   `json:"command"`
	Workdir     string                   `json:"workdir,omitempty"`
	Shell       string                   `json:"shell,omitempty"`
	TTY         bool                     `json:"tty,omitempty"`
	State       string                   `json:"state"`
	ExitCode    *int                     `json:"exit_code,omitempty"`
	TimeoutMS   int64                    `json:"timeout_ms,omitempty"`
	Output      string                   `json:"output,omitempty"`
	OutputBytes int                      `json:"output_bytes,omitempty"`
	Stream      []ExecProcessStreamEntry `json:"stream,omitempty"`
	StdinClosed bool                     `json:"stdin_closed,omitempty"`
	Lost        bool                     `json:"lost,omitempty"`
}

type ExecProcessStreamEntry struct {
	Source string `json:"source"`
	Text   string `json:"text"`
}

type ExecStoredResult struct {
	ProcessID   string `json:"process_id"`
	Command     string `json:"command"`
	Comment     string `json:"comment,omitempty"`
	Workdir     string `json:"workdir,omitempty"`
	Shell       string `json:"shell,omitempty"`
	TTY         bool   `json:"tty,omitempty"`
	State       string `json:"state"`
	ExitCode    *int   `json:"exit_code,omitempty"`
	TimeoutMS   int64  `json:"timeout_ms,omitempty"`
	Output      string `json:"output,omitempty"`
	OutputMode  string `json:"output_mode,omitempty"`
	OutputBytes int    `json:"output_bytes,omitempty"`
	// OmittedBytes counts output left out before Output by the size limit.
	OmittedBytes int  `json:"omitted_bytes,omitempty"`
	StdinClosed  bool `json:"stdin_closed,omitempty"`
	// StateNote explains State in the model-facing text, e.g. that a
	// command outlived exec_command's startup wait.
	StateNote string `json:"state_note,omitempty"`
	// Reporting says what a running session sends to the chat on its own.
	Reporting string `json:"reporting,omitempty"`
	Message   string `json:"message,omitempty"`
}

type FileTracker interface {
	TouchFile(context.Context, string, string)
}

type GlobStoredResult struct {
	Pattern   string   `json:"pattern"`
	BasePath  string   `json:"base_path,omitempty"`
	Matches   []string `json:"matches,omitempty"`
	Footer    string   `json:"footer,omitempty"`
	Truncated bool     `json:"truncated,omitempty"`
}

type GrepStoredResult struct {
	Pattern   string `json:"pattern"`
	BasePath  string `json:"base_path,omitempty"`
	Include   string `json:"include,omitempty"`
	Output    string `json:"output,omitempty"`
	Truncated bool   `json:"truncated,omitempty"`
}

type ID = domain.ToolKind

type LintStoredResult struct {
	Path             string                 `json:"path"`
	Mode             string                 `json:"mode,omitempty"`
	Summary          string                 `json:"summary,omitempty"`
	Diagnostics      string                 `json:"diagnostics,omitempty"`
	DiagnosticReport DiagnosticReportStored `json:"diagnostic_report,omitempty"`
}

type MCPExecutor interface {
	ExecuteTool(context.Context, string, string, map[string]any) (Result, error)
}

type MCPStoredContentItem struct {
	Type        string `json:"type"`
	Text        string `json:"text,omitempty"`
	URI         string `json:"uri,omitempty"`
	MIMEType    string `json:"mime_type,omitempty"`
	Description string `json:"description,omitempty"`
	Data        []byte `json:"data,omitempty"`
	Size        int64  `json:"size,omitempty"`
	SHA256      string `json:"sha256,omitempty"`
	Truncated   bool   `json:"truncated,omitempty"`
}

type MCPStoredResult struct {
	ServerID          string                 `json:"server_id"`
	ServerName        string                 `json:"server_name,omitempty"`
	ToolName          string                 `json:"tool_name"`
	StructuredContent string                 `json:"structured_content,omitempty"`
	IsError           bool                   `json:"is_error,omitempty"`
	NeedsInput        bool                   `json:"needs_input,omitempty"`
	InputRequests     string                 `json:"input_requests,omitempty"`
	RequestState      string                 `json:"request_state,omitempty"`
	Content           []MCPStoredContentItem `json:"content,omitempty"`
}

type MediaInput struct {
	Path  string `json:"path"`
	Title string `json:"title,omitempty"`
}

type MilestonePlanStoredResult struct {
	Summary    string                `json:"summary,omitempty"`
	Milestones []MilestoneStoredItem `json:"milestones,omitempty"`
}

type MilestoneStoredItem struct {
	ID                 id.ID  `json:"id,omitempty"`
	Key                string `json:"key,omitempty"`
	LegacyRef          string `json:"ref,omitempty"`
	Title              string `json:"title"`
	Status             string `json:"status"`
	Archived           bool   `json:"archived,omitempty"`
	Notes              string `json:"notes,omitempty"`
	DependsOnKey       string `json:"depends_on_key,omitempty"`
	LegacyDependsOnKey string `json:"depends_on_ref,omitempty"`
	OwnerChatID        string `json:"owner_chat_id,omitempty"`
	TaskSummary        string `json:"task_summary,omitempty"`
}

type ModelImage struct {
	Data       []byte
	SourcePath string
	SessionID  string
	Attachment *attachment.Metadata
	MIMEType   string
}

type OfferFileStoredResult struct {
	Token    string `json:"token"`
	Name     string `json:"name"`
	MIMEType string `json:"mime_type,omitempty"`
	Size     int64  `json:"size"`
	Title    string `json:"title,omitempty"`
	Summary  string `json:"summary,omitempty"`
}

type Options struct {
	Runtime Runtime
	Request Request
	// Progress, when set, shows the user what a long-running tool is doing.
	// Each call replaces the previous report.
	Progress func(domain.ToolProgress)
}

type PlanStoredStep struct {
	Step   string `json:"step"`
	Status string `json:"status"`
}

type PlanUpdateStoredResult struct {
	Explanation string           `json:"explanation,omitempty"`
	Steps       []PlanStoredStep `json:"steps"`
}

type PlanningLifecycleStoredResult struct {
	Entity string `json:"entity"`
	Key    string `json:"key"`
	Action string `json:"action"`
}

type Presentation struct {
	Title    string
	Subtitle string
	Preview  string
}

type PresentationStoredResult struct {
	Title    string `json:"title,omitempty"`
	MIMEType string `json:"mime_type"`
	Content  string `json:"content"`
}

type Presenter interface {
	Presentation(req Request) Presentation
}

type ProviderCallError struct {
	Request Request
	Err     error
}

type QuestionStoredResult struct {
	Question string            `json:"question,omitempty"`
	Answers  []UserInputAnswer `json:"answers,omitempty"`
}

type ReadStoredLine struct {
	Number int    `json:"number"`
	Text   string `json:"text"`
}

type ReadStoredMode string

type ReadStoredResult struct {
	Path           string           `json:"path"`
	Mode           ReadStoredMode   `json:"mode"`
	Lines          []ReadStoredLine `json:"lines,omitempty"`
	Entries        []string         `json:"entries,omitempty"`
	Footer         string           `json:"footer,omitempty"`
	StartLine      string           `json:"start_line,omitempty"`
	EndLine        string           `json:"end_line,omitempty"`
	Offset         string           `json:"offset,omitempty"`
	Limit          string           `json:"limit,omitempty"`
	Start          int              `json:"start,omitempty"`
	End            int              `json:"end,omitempty"`
	Total          int              `json:"total,omitempty"`
	NextStartLine  int              `json:"next_start_line,omitempty"`
	NextOffset     int              `json:"next_offset,omitempty"`
	EffectiveLimit int              `json:"effective_limit,omitempty"`
	AutoCapped     bool             `json:"auto_capped,omitempty"`
	RangeCapped    bool             `json:"range_capped,omitempty"`
	ByteCapped     bool             `json:"byte_capped,omitempty"`
	HasMore        bool             `json:"has_more,omitempty"`
	Truncated      bool             `json:"truncated,omitempty"`
}

type RemoteMedia struct {
	Data     []byte
	Name     string
	MIMEType string
	URL      string
}

type Request struct {
	Tool       ID                `json:"tool"`
	ToolCallID string            `json:"tool_call_id,omitempty"`
	Args       map[string]string `json:"-"`
}

type Result = domain.ToolResult

type Runtime struct {
	Workdir     string
	HTTPClient  *http.Client
	SessionID   id.ID
	SessionKind domain.SessionKind
	ChatID      id.ID
	// ChatProviderID and ChatModelID name the chat's model, for tools
	// that ask it for help, such as pulling facts out of web pages.
	ChatProviderID        string
	ChatModelID           string
	ChatRole              chatrole.Role
	InteractionMode       chatinteraction.Mode
	ActiveMilestoneKey    string
	AssignedTaskBucketKey string
	AssignedTaskRef       string
	SessionControl        SessionControl
	TaskControl           TaskControl
	ChatStatusControl     ChatStatusControl
	Services              map[string]any
	AllowedTools          map[ID]bool
	ManagedSkillsDir      string
	DisabledSkillPaths    []string
	SkillCatalogMaxChars  int
	Exec                  execruntime.Control
	MCP                   MCPExecutor
	Browser               browserapi.Service
	Attachments           *attachment.Manager
	OfferedFiles          *offeredfile.Manager
	FileTracker           FileTracker
	AccessSettings        accesssettings.Settings
	// Memory holds the notes the model keeps across chats.
	Memory *memory.Store
	// OutputBudgetBytes bounds one tool's output by the room left in the
	// model's context; zero means unknown and tools use their own default.
	OutputBudgetBytes int
}

type SessionControl interface {
	GetMilestonePlan(context.Context, id.ID) (planning.Plan, error)
	SetMilestonePlan(context.Context, id.ID, string, []planning.Milestone) (planning.Plan, error)
	ArchiveMilestone(context.Context, id.ID, string, bool) (planning.Milestone, error)
	DeleteMilestone(context.Context, id.ID, string) error
	AddTasks(context.Context, id.ID, string, []string) ([]planning.Task, error)
	UpdateTask(context.Context, string, planning.TaskStatus, string, string) (planning.Task, error)
	ArchiveTask(context.Context, string, bool) (planning.Task, error)
	DeleteTask(context.Context, string) error
	ListTasks(context.Context, id.ID, string) ([]planning.Task, error)
}

type ShowImageStoredResult = ShowMediaStoredResult

type ShowMediaStoredItem struct {
	Path       string               `json:"path"`
	SourcePath string               `json:"source_path,omitempty"`
	MIMEType   string               `json:"mime_type"`
	MediaKind  string               `json:"media_kind,omitempty"`
	Title      string               `json:"title,omitempty"`
	SessionID  string               `json:"session_id,omitempty"`
	Attachment *attachment.Metadata `json:"attachment,omitempty"`
}

type ShowMediaStoredResult struct {
	Path       string                `json:"path"`
	SourcePath string                `json:"source_path,omitempty"`
	MIMEType   string                `json:"mime_type"`
	MediaKind  string                `json:"media_kind,omitempty"`
	Title      string                `json:"title,omitempty"`
	SessionID  string                `json:"session_id,omitempty"`
	Attachment *attachment.Metadata  `json:"attachment,omitempty"`
	Summary    string                `json:"summary,omitempty"`
	Items      []ShowMediaStoredItem `json:"items,omitempty"`
	Errors     []string              `json:"errors,omitempty"`
}

type SkillStoredResult struct {
	Name      string `json:"name"`
	Path      string `json:"path"`
	Content   string `json:"content,omitempty"`
	Truncated bool   `json:"truncated,omitempty"`
}

type StoredResultPayload interface {
	// contains filtered or unexported methods
}

type StoredResultStatus string

type TaskControl interface {
	AddTask(context.Context, id.ID, string, planning.LegacyTaskStatus) (planning.LegacyTask, error)
}

type TaskListStoredResult struct {
	MilestoneKey       string           `json:"milestone_key,omitempty"`
	LegacyMilestoneKey string           `json:"milestone_ref,omitempty"`
	MilestoneTitle     string           `json:"milestone_title,omitempty"`
	Message            string           `json:"message,omitempty"`
	Items              []TaskStoredItem `json:"items,omitempty"`
}

type TaskStoredItem struct {
	ID       id.ID  `json:"id"`
	Key      string `json:"key,omitempty"`
	Content  string `json:"content"`
	Note     string `json:"note,omitempty"`
	Status   string `json:"status"`
	Archived bool   `json:"archived,omitempty"`
}

type TaskStoredResult struct {
	Body   string                    `json:"body"`
	Status planning.LegacyTaskStatus `json:"status"`
}

type Tool interface {
	ID() ID
	BypassesPermission() bool
	NormalizeArgs(map[string]string) (map[string]string, error)
	Preview(req Request) string
	Call(ctx context.Context, options Options) (Result, error)
}

type ToolInt int

type ToolSpec struct {
	Title       string
	Description string
	Usage       string
	Parameters  string
	ExposeToLLM bool
	// Legacy keeps a tool executable for stored transcripts and compatibility
	// while excluding its definition from new model requests.
	Legacy bool
}

type UserInputAnswer struct {
	ToolCallID string `json:"tool_call_id"`
	QuestionID string `json:"question_id"`
	Selected   string `json:"selected,omitempty"`
	Comment    string `json:"comment,omitempty"`
}

type UserInputOption struct {
	Label       string `json:"label"`
	Description string `json:"description"`
}

type UserInputQuestion struct {
	ID       string            `json:"id"`
	Header   string            `json:"header"`
	Question string            `json:"question"`
	Options  []UserInputOption `json:"options"`
}

type ViewImageStoredResult struct {
	Path       string               `json:"path"`
	SourcePath string               `json:"source_path,omitempty"`
	MIMEType   string               `json:"mime_type"`
	Detail     string               `json:"detail,omitempty"`
	SessionID  string               `json:"session_id,omitempty"`
	Attachment *attachment.Metadata `json:"attachment,omitempty"`
	Summary    string               `json:"summary,omitempty"`
	Page       int                  `json:"page,omitempty"`
	PageCount  int                  `json:"page_count,omitempty"`
}

type WebFetchStoredResult struct {
	URL         string `json:"url"`
	FinalURL    string `json:"final_url,omitempty"`
	Format      string `json:"format,omitempty"`
	Status      int    `json:"status"`
	ContentType string `json:"content_type,omitempty"`
	Body        string `json:"body,omitempty"`
	Truncated   bool   `json:"truncated,omitempty"`
}

type WebSearchStoredItem struct {
	Title   string `json:"title"`
	URL     string `json:"url"`
	Snippet string `json:"snippet,omitempty"`
}

type WebSearchStoredResult struct {
	Query          string                `json:"query"`
	AllowedDomains string                `json:"allowed_domains,omitempty"`
	BlockedDomains string                `json:"blocked_domains,omitempty"`
	Items          []WebSearchStoredItem `json:"items,omitempty"`
}

type WriteStoredResult struct {
	Path             string                 `json:"path"`
	Action           string                 `json:"action,omitempty"`
	Summary          string                 `json:"summary,omitempty"`
	Content          string                 `json:"content,omitempty"`
	Diagnostics      string                 `json:"diagnostics,omitempty"`
	DiagnosticReport DiagnosticReportStored `json:"diagnostic_report,omitempty"`
	Truncated        bool                   `json:"truncated,omitempty"`
}