domain

type AgentMode ¶

type AgentMode int

AgentMode represents the operational mode of the agent

const (
	// AgentModeStandard is the default mode with all configured tools and approval checks
	AgentModeStandard AgentMode = iota
	// AgentModePlan is a read-only mode for planning without execution
	AgentModePlan
	// AgentModeAutoAccept bypasses all approval checks (YOLO mode)
	AgentModeAutoAccept
	// AgentModeAutoWithJudge keeps the standard approval rules but hands every
	// gated call to an LLM judge (see judge.yaml) instead of a human: allow-listed
	// commands still pass for free, anything off-list is decided by one judge
	// call. The no-human approver for headless/CI runs.
	AgentModeAutoWithJudge
	// AgentModeReadOnly is an Explore-like capability for subagents: only
	// read/search tools are offered and approval is bypassed (the toolset is
	// read-only by construction). It is a subagent capability selected by the
	// Agent tool's `type` parameter, not a human shift+tab mode.
	AgentModeReadOnly
)

func AgentModeFromContext(ctx context.Context) (AgentMode, bool)

func ParseAgentMode(s string) (AgentMode, bool)

func (m AgentMode) DisplayName() string

func (m AgentMode) ModeKey() string

func (m AgentMode) String() string

func (m *AgentMode) UnmarshalYAML(node *yaml.Node) error

type AgentModeState ¶ added in v0.207.0

type AgentModeState interface {
	GetAgentMode() AgentMode
	SetAgentMode(mode AgentMode)
	CycleAgentMode() AgentMode
}

AgentModeState handles agent mode switching

type AgentRequest ¶

type AgentRequest struct {
	RequestID                  string        `json:"request_id"`
	Model                      string        `json:"model"`
	Messages                   []sdk.Message `json:"messages"`
	IsChatMode                 bool          `json:"is_chat_mode"`
	ApprovalBrokerAttached     bool          `json:"approval_broker_attached"`
	UserQuestionBrokerAttached bool          `json:"user_question_broker_attached"`
	GroupKey                   string        `json:"group_key,omitempty"`
}

AgentRequest represents a request to the agent service

type AgentService ¶

type AgentService interface {
	// Run executes an agent task synchronously (for background/batch processing)
	Run(ctx context.Context, req *AgentRequest) (*ChatSyncResponse, error)

	// RunWithStream executes an agent task with streaming (for interactive chat)
	RunWithStream(ctx context.Context, req *AgentRequest) (<-chan ChatEvent, error)

	// RunStreaming executes a single model turn with streaming, invoking onDelta
	// for each content/reasoning/tool-call delta, and returns the assembled
	// response like Run. For callers that own their own agentic loop (the
	// headless AG-UI agent) but want token-level output. onDelta may be nil.
	RunStreaming(ctx context.Context, req *AgentRequest, onDelta func(content, reasoning string, toolCalls []sdk.ChatCompletionMessageToolCallChunk)) (*ChatSyncResponse, error)

	// CancelRequest cancels an active request
	CancelRequest(requestID string) error

	// GetMetrics returns metrics for a completed request
	GetMetrics(requestID string) *ChatMetrics

	// BuildSystemPrompt returns the static system prompt sent as message[0],
	// byte-stable across turns; volatile context travels separately as a hidden
	// per-request message (see `infer debug agent system_prompt`).
	BuildSystemPrompt() string

	// SetReasoningEffort updates the reasoning effort applied to subsequent
	// requests. An empty string resets to the provider default.
	SetReasoningEffort(effort string) error

	// GetReasoningEffort returns the effort level currently applied to
	// requests ("" = provider default).
	GetReasoningEffort() string
}

AgentService handles agent operations with both sync and streaming modes

type AnnotateOptions ¶

type AnnotateOptions struct {
	Prompt string // task instruction (UI-element detection, scene description, or a user question); "" -> annotator default
	Width  int    // image width in pixels, stated in the prompt and used to rescale normalized coordinates
	Height int    // image height in pixels
}

AnnotateOptions carries per-call annotation parameters.

type AnnotatedElement ¶

type AnnotatedElement struct {
	Index int    `json:"index"`
	Label string `json:"label"`
	Text  string `json:"text,omitempty"`
	BBox  [4]int `json:"bbox"` // [x1, y1, x2, y2] in the image's pixel space
}

AnnotatedElement is one detected element of an annotated image.

type ApprovalAction ¶

type ApprovalAction int

ApprovalAction represents the user's choice for tool approval

const (
	ApprovalApprove ApprovalAction = iota
	ApprovalReject
	ApprovalAutoAccept
)

func (a ApprovalAction) String() string

type ApprovalEscalation ¶ added in v0.188.0

type ApprovalEscalation interface {
	// Escalate validates eligibility (the call must be judge-rejected and not
	// yet escalated), prompts the user, and returns the decision.
	Escalate(ctx context.Context, req ApprovalEscalationRequest) (ApprovalEscalationResult, error)
}

ApprovalEscalation lets the RequestApproval tool ask the user to override a judge rejection. It is implemented by the agent service, which owns the judge-rejection registry and prompts through the regular tool approval box; it is injected into the tool's execution context on the chat path only, so headless runs degrade to a distinguishable "no approver reachable" result.

func GetApprovalEscalation(ctx context.Context) ApprovalEscalation

type ApprovalEscalationRequest ¶ added in v0.188.0

type ApprovalEscalationRequest struct {
	ToolCall sdk.ChatCompletionMessageToolCall
	What     string
	Why      string
}

ApprovalEscalationRequest is one ask-the-user-to-override-a-judge-rejection request: the rejected tool call to run, what the permission is needed for, and the agent's justification in its own words.

type ApprovalEscalationResult ¶ added in v0.188.0

type ApprovalEscalationResult struct {
	Approved    bool
	Status      string
	JudgeReason string
}

ApprovalEscalationResult is the user's decision. JudgeReason echoes the judge's rejection reason so the tool result can show the user and the judge both sides of the disagreement.

type ApprovalPolicy ¶

type ApprovalPolicy interface {
	// ShouldRequireApproval returns true if the tool execution requires user approval
	// ctx: context for the approval decision
	// toolCall: the tool being invoked with its arguments
	// isChatMode: whether execution is in interactive chat mode
	ShouldRequireApproval(ctx context.Context, toolCall *sdk.ChatCompletionMessageToolCall, isChatMode bool) bool
}

ApprovalPolicy determines whether a tool execution requires user approval This interface allows for different approval strategies (standard, permissive, strict, etc.) Implementations define the business rules for when user approval is required before executing potentially dangerous or state-changing operations.

type BackgroundTasksChangedEvent ¶

type BackgroundTasksChangedEvent struct{}

BackgroundTasksChangedEvent signals that a background job's status changed (submitted, signalled, completed, or failed). The supervisor pushes it so the /tasks view and the inline conversation rows refresh on real change instead of polling at render time.

type BaseChatEvent ¶

type BaseChatEvent struct {
	RequestID string
	Timestamp time.Time
}

BaseChatEvent provides common implementation for ChatEvent interface

func (e BaseChatEvent) GetRequestID() string

func (e BaseChatEvent) GetTimestamp() time.Time

type BashDetachChannelHolder ¶

type BashDetachChannelHolder interface {
	SetBashDetachChan(chan<- struct{})
	GetBashDetachChan() chan<- struct{}
	ClearBashDetachChan()
}

BashDetachChannelHolder manages the bash detach channel for background shell operations

func GetChatHandler(ctx context.Context) BashDetachChannelHolder

type BashOutputCallback ¶

type BashOutputCallback func(output string)

BashOutputCallback receives streaming bash output. Output is coalesced before delivery, so a single invocation may carry several newline-joined lines (the argument never has a trailing newline). This keeps the number of callbacks bounded for high-volume commands; the full command output is captured separately by the tool and is unaffected.

func GetBashOutputCallback(ctx context.Context) BashOutputCallback

type BashOutputChunkEvent ¶

type BashOutputChunkEvent struct {
	BaseChatEvent
	ToolCallID string
	Output     string
	IsComplete bool
}

BashOutputChunkEvent indicates a new chunk of bash output is available

type BashToolResult ¶

type BashToolResult struct {
	Command  string `json:"command"`
	Output   string `json:"output"`
	Error    string `json:"error,omitempty"`
	ExitCode int    `json:"exit_code"`
	Duration string `json:"duration"`
}

BashToolResult represents the result of a bash command execution

type BrowserExtensionStatusEvent ¶ added in v0.182.0

type BrowserExtensionStatusEvent struct {
	Connected bool
}

BrowserExtensionStatusEvent is pushed through the UI notifier when the browser extension connects to or drops off the CLI bridge.

type CallApprover ¶ added in v0.216.0

type CallApprover interface {
	RequiresApproval(args map[string]any, mode AgentMode) bool
}

CallApprover is implemented by tools that decide per call whether it needs approval, ahead of the agent mode, such as the computer-use tools.

type ChatChunkEvent ¶

type ChatChunkEvent struct {
	RequestID        string
	Timestamp        time.Time
	Content          string
	ReasoningContent string
	ToolCalls        []sdk.ChatCompletionMessageToolCallChunk
	Delta            bool
	Usage            *sdk.CompletionUsage
}

ChatChunkEvent represents a streaming chunk of chat response

func (e ChatChunkEvent) GetRequestID() string

func (e ChatChunkEvent) GetTimestamp() time.Time

type ChatCompleteEvent ¶

type ChatCompleteEvent struct {
	RequestID        string
	Timestamp        time.Time
	Message          string
	ReasoningContent string
	ToolCalls        []sdk.ChatCompletionMessageToolCall
	Metrics          *ChatMetrics
	Cancelled        bool
	// MaxTurnsReached marks a completion forced by the turn limit rather than
	// the task finishing; headless renderers map it to ErrMaxTurnsReached.
	MaxTurnsReached bool
}

ChatCompleteEvent indicates chat completion. Cancelled is set when the completion is the result of a user-initiated cancel (Esc) rather than the model finishing on its own - the UI uses this to show "User interrupted" rather than "Response complete".

func (e ChatCompleteEvent) GetRequestID() string

func (e ChatCompleteEvent) GetTimestamp() time.Time

type ChatErrorEvent ¶

type ChatErrorEvent struct {
	RequestID string
	Timestamp time.Time
	Error     error
}

ChatErrorEvent represents an error during chat

func (e ChatErrorEvent) GetRequestID() string

func (e ChatErrorEvent) GetTimestamp() time.Time

type ChatEvent ¶

type ChatEvent interface {
	GetRequestID() string
	GetTimestamp() time.Time
}

ChatEvent represents events during chat operations

type ChatMetrics ¶

type ChatMetrics struct {
	Duration time.Duration
	Usage    *sdk.CompletionUsage
}

ChatMetrics holds performance and usage metrics

type ChatStartEvent ¶

type ChatStartEvent struct {
	RequestID string
	Timestamp time.Time
	Model     string
}

ChatStartEvent indicates a chat request has started

func (e ChatStartEvent) GetRequestID() string

func (e ChatStartEvent) GetTimestamp() time.Time

type ChatSyncResponse ¶

type ChatSyncResponse struct {
	RequestID        string                              `json:"request_id"`
	Content          string                              `json:"content"`
	ReasoningContent string                              `json:"reasoning_content,omitempty"`
	ToolCalls        []sdk.ChatCompletionMessageToolCall `json:"tool_calls,omitempty"`
	Usage            *sdk.CompletionUsage                `json:"usage,omitempty"`
	Duration         time.Duration                       `json:"duration"`
	FinishReason     string                              `json:"finish_reason,omitempty"`
}

ChatSyncResponse represents a synchronous chat completion response

type ComputerUsePause ¶ added in v0.207.0

type ComputerUsePause interface {
	SetComputerUsePaused(paused bool, requestID string)
	IsComputerUsePaused() bool
	GetPausedRequestID() string
	ClearComputerUsePauseState()
}

ComputerUsePause handles computer use pause state

type ComputerUsePausedEvent ¶

type ComputerUsePausedEvent struct {
	RequestID string
	Timestamp time.Time
}

ComputerUsePausedEvent indicates computer-use execution has been paused

func (e ComputerUsePausedEvent) GetRequestID() string

func (e ComputerUsePausedEvent) GetTimestamp() time.Time

type ComputerUseResumedEvent ¶

type ComputerUseResumedEvent struct {
	RequestID string
	Timestamp time.Time
}

ComputerUseResumedEvent indicates computer-use execution has resumed

func (e ComputerUseResumedEvent) GetRequestID() string

func (e ComputerUseResumedEvent) GetTimestamp() time.Time

type DeleteToolResult ¶

type DeleteToolResult struct {
	Path              string   `json:"path"`
	DeletedFiles      []string `json:"deleted_files"`
	DeletedDirs       []string `json:"deleted_dirs"`
	TotalFilesDeleted int      `json:"total_files_deleted"`
	TotalDirsDeleted  int      `json:"total_dirs_deleted"`
	WildcardExpanded  bool     `json:"wildcard_expanded"`
	Errors            []string `json:"errors,omitempty"`
}

DeleteToolResult represents the result of a delete operation

type DrainQueueEvent ¶

type DrainQueueEvent struct{}

DrainQueueEvent asks the orchestrator to start a fresh agent turn when the agent is idle on the chat view and the shared message queue has content (background-job completion notes or user messages typed while busy). Unlike the old queue-drain tick it is not a clock: it is pushed exactly once per real trigger (a background job landing work, a turn completing with a non-empty queue, or re-entering the chat view), and HandleDrainQueueEvent is a pure gate that starts a turn (Idle -> CheckingQueue -> ... -> Completing -> Idle) or returns nil. There is no self-reschedule.

type EditOperationResult ¶

type EditOperationResult struct {
	OldString     string `json:"old_string"`
	NewString     string `json:"new_string"`
	ReplaceAll    bool   `json:"replace_all"`
	ReplacedCount int    `json:"replaced_count"`
	Success       bool   `json:"success"`
	Error         string `json:"error,omitempty"`
	// WhitespaceNormalized is true when this edit matched via the indentation-tolerant fallback.
	WhitespaceNormalized bool `json:"whitespace_normalized,omitempty"`
}

EditOperationResult represents the result of a single edit operation within MultiEdit

type EditToolResult ¶

type EditToolResult struct {
	FilePath             string `json:"file_path"`
	OldString            string `json:"old_string"`
	NewString            string `json:"new_string"`
	ReplacedCount        int    `json:"replaced_count"`
	ReplaceAll           bool   `json:"replace_all"`
	FileModified         bool   `json:"file_modified"`
	OriginalSize         int64  `json:"original_size"`
	NewSize              int64  `json:"new_size"`
	BytesDifference      int64  `json:"bytes_difference"`
	OriginalLines        int    `json:"original_lines"`
	NewLines             int    `json:"new_lines"`
	LinesDifference      int    `json:"lines_difference"`
	Diff                 string `json:"diff,omitempty"`
	WhitespaceNormalized bool   `json:"whitespace_normalized,omitempty"`
	StartLine            int    `json:"start_line,omitempty"`
}

EditToolResult represents the result of an edit operation

type EventBridge ¶

type EventBridge interface {
	// Tap intercepts an event stream and multicasts it to all subscribers
	// Returns a new channel that mirrors the input channel
	Tap(input <-chan ChatEvent) <-chan ChatEvent

	// Publish broadcasts an event to all subscribers
	Publish(event ChatEvent)

	// Subscribe creates a new event channel and returns it
	Subscribe() chan ChatEvent

	// SubscribeFuture is Subscribe without the ring-buffer replay, for
	// subscribers that backfill history another way.
	SubscribeFuture() chan ChatEvent

	// Unsubscribe removes a subscriber and closes its channel
	Unsubscribe(ch chan ChatEvent)
}

EventBridge multicasts chat events to multiple subscribers (e.g., terminal UI and the opentask extension bridge)

type FetchResult ¶

type FetchResult struct {
	Content     string            `json:"content"`
	URL         string            `json:"url"`
	Status      int               `json:"status"`
	Size        int64             `json:"size"`
	ContentType string            `json:"content_type"`
	Cached      bool              `json:"cached"`
	SavedPath   string            `json:"saved_path,omitempty"`
	Metadata    map[string]string `json:"metadata,omitempty"`
	Warning     string            `json:"warning,omitempty"`
}

FetchResult represents the result of a fetch operation

type FileReadToolResult ¶

type FileReadToolResult struct {
	FilePath  string `json:"file_path"`
	Content   string `json:"content"`
	Size      int64  `json:"size"`
	StartLine int    `json:"start_line,omitempty"`
	EndLine   int    `json:"end_line,omitempty"`
	Error     string `json:"error,omitempty"`
}

FileReadToolResult represents the result of a file read operation

type FileService ¶

type FileService interface {
	ListProjectFiles() ([]string, error)
	ReadFile(path string) (string, error)
	ValidateFile(path string) error
}

FileService handles file operations

type FileWriteToolResult ¶

type FileWriteToolResult struct {
	FilePath     string `json:"file_path"`
	BytesWritten int64  `json:"bytes_written"`
	LinesWritten int    `json:"lines_written"`
	Created      bool   `json:"created"`
	Overwritten  bool   `json:"overwritten"`
	ChunkIndex   int    `json:"chunk_index,omitempty"`
	TotalChunks  int    `json:"total_chunks,omitempty"`
	IsComplete   bool   `json:"is_complete"`
	Error        string `json:"error,omitempty"`
}

FileWriteToolResult represents the result of a file write operation

type FormatterType ¶

type FormatterType string

FormatterType defines the context for formatting tool results

const (
	FormatterUI    FormatterType = "ui"    // Compact display for UI
	FormatterLLM   FormatterType = "llm"   // Formatted for LLM consumption
	FormatterShort FormatterType = "short" // Brief summary format
)

type Frame ¶

type Frame struct {
	ID        string    `json:"id"`
	Timestamp time.Time `json:"timestamp"`
	Data      string    `json:"data"`   // base64 encoded image
	Path      string    `json:"-"`      // on-disk path when the frame exists as a file
	Width     int       `json:"width"`  // Final image width (after scaling)
	Height    int       `json:"height"` // Final image height (after scaling)
	Format    string    `json:"format"` // "png" or "jpeg"
	Method    string    `json:"method"` // capture method, e.g. "x11", "wayland", "directory"
}

Frame represents a captured image frame (screenshot, camera frame, ...) with metadata

type FrameSource ¶

type FrameSource interface {
	GetLatestFrame() (*Frame, error)
}

FrameSource provides the most recent frame of a named frame source (the screen ring buffer, a camera directory, ...).

type FrameToolResult ¶

type FrameToolResult struct {
	Source     string           `json:"source,omitempty"`
	Display    string           `json:"display"`
	Region     *ScreenRegion    `json:"region,omitempty"`
	Width      int              `json:"width"`
	Height     int              `json:"height"`
	Format     string           `json:"format"`
	Method     string           `json:"method"`
	Annotated  bool             `json:"annotated,omitempty"`
	Annotation *ImageAnnotation `json:"annotation,omitempty"`
	Note       string           `json:"note,omitempty"` // degrade note, e.g. "annotation unavailable: ..."
}

FrameToolResult represents the result of a frame retrieval

type GitHubIssue ¶

type GitHubIssue struct {
	Number    int
	Title     string
	Body      string
	State     string
	URL       string
	UpdatedAt time.Time
	Author    string
	Comments  []GitHubIssueComment
}

GitHubIssue is a minimal projection of a GitHub issue, big enough for both the autocomplete dropdown (Number, Title, State) and inline expansion into a chat-message block (Body, URL, Comments, UpdatedAt). Comments is nil for the list variant and populated for the view variant.

type GitHubIssueComment ¶

type GitHubIssueComment struct {
	Author    string
	Body      string
	CreatedAt time.Time
}

GitHubIssueComment is a single comment on a GitHub issue, sorted by CreatedAt ascending.

type GitHubIssueService ¶

type GitHubIssueService interface {
	// ListIssues returns recent open issues for the current repo, newest first.
	// Results are cached for a short TTL so repeated autocomplete keystrokes
	// don't shell out per character. Returns ([], nil) on environment failures.
	ListIssues(ctx context.Context) ([]GitHubIssue, error)

	// GetIssue fetches an issue with body and the most-recent comments (capped
	// internally). Uncached. Returns (nil, err) on failure so the expansion
	// path can leave the raw token in place.
	GetIssue(ctx context.Context, number int) (*GitHubIssue, error)

	// IsAvailable reports whether the service can serve requests in the
	// current environment. Used by the autocomplete trigger to short-circuit
	// a slow first shell-out when gh / repo / auth are missing.
	IsAvailable() bool
}

GitHubIssueService provides cached access to the current repository's GitHub issues via the gh CLI. Implementations gracefully degrade (return empty/nil with no error) when not in a git repo, when gh is not installed, or when the remote/auth is not configured - the chat input's "#" autocomplete and "#N" inline expansion simply become no-ops in those environments.

type GitHubSetupService ¶

type GitHubSetupService interface {
	GetCurrentRepo() (string, error)
	IsOrgRepo(repo string) (bool, error)
	CheckOrgSecretsExist(orgName string) (bool, error)
	SetOrgSecret(orgName, name, value string) error
	InstallWorkflow(ctx context.Context, opts InstallWorkflowOptions) (string, error)
}

GitHubSetupService handles git/gh/CI operations for the GitHub Action CI setup flow triggered from the install-opentask wizard. Every shell invocation carries a context so a wedged subprocess cannot hang the UI.

type HookCommand ¶

type HookCommand struct {
	Name    string
	Command string
	Timeout time.Duration
}

HookCommand is a resolved command hook ready to run at a hook point: a named shell command with a wall-clock timeout. It is the command-action sibling of SystemReminder (the text-injection action). The agent - not the provider - runs it, through the same bash allow-list a model-proposed command faces.

type HookCommandProvider ¶

type HookCommandProvider interface {
	CommandsDue(hook HookPoint) []HookCommand
}

HookCommandProvider resolves which command hooks are due at a hook point. It is the command-action sibling of SystemReminderProvider, implemented by config from the user's hooks list. The provider only resolves the commands; the agent runs them through the existing bash allow-list, so config stays free of os/exec. The agent depends on this interface so the command set can be faked in tests.

type HookPoint ¶

type HookPoint string

HookPoint is one of the pre-defined points in the agent loop where actions can attach. The catalog is fully symmetric: every loop phase exposes a pre_/post_ pair. System reminders attach a text-injection action here today; executable command hooks attach a command-execution action at the same points later, both flowing through the single dispatchHooks(point) seam.

const (
	HookPreSession     HookPoint = "pre_session"      // run begins, before the first stream (turn 1)
	HookPostSession    HookPoint = "post_session"     // run finished ("agent finished generating")
	HookPreStream      HookPoint = "pre_stream"       // before each LLM streaming turn
	HookPostStream     HookPoint = "post_stream"      // after each LLM response, before tool evaluation
	HookPreTool        HookPoint = "pre_tool"         // before tool execution
	HookPostTool       HookPoint = "post_tool"        // after tool execution
	HookPreQueueDrain  HookPoint = "pre_queue_drain"  // before draining queued user messages
	HookPostQueueDrain HookPoint = "post_queue_drain" // after draining queued user messages
)

func (h HookPoint) Valid() bool

type ImageAnnotation ¶

type ImageAnnotation struct {
	Summary  string             `json:"summary"`
	Elements []AnnotatedElement `json:"elements,omitempty"`
}

ImageAnnotation is the structured result of annotating an image: a short scene summary plus a numbered element list. Elements may be empty when the annotator degraded to a plain-text summary.

type ImageAnnotator ¶

type ImageAnnotator interface {
	AnnotateImage(ctx context.Context, img ImageAttachment, opts AnnotateOptions) (*ImageAnnotation, error)
}

ImageAnnotator turns an image into text (summary + element list) via a vision model, so text-only session models can understand frames and images.

type ImageAttachment ¶

type ImageAttachment struct {
	Data        string `json:"data"`
	MimeType    string `json:"mime_type"`
	Filename    string `json:"filename,omitempty"`
	DisplayName string `json:"display_name"`
	SourcePath  string `json:"-"`
}

ImageAttachment represents an image attachment in a message

type ImageService ¶

type ImageService interface {
	// ReadImageFromFile reads an image from a file path and returns it as a base64 attachment
	ReadImageFromFile(filePath string) (*ImageAttachment, error)
	// ReadImageFromBinary reads an image from binary data and returns it as a base64 attachment
	ReadImageFromBinary(imageData []byte, filename string) (*ImageAttachment, error)
	// ReadImageFromURL fetches an image from a URL and returns it as a base64 attachment
	ReadImageFromURL(imageURL string) (*ImageAttachment, error)
	// IsImageFile checks if a file is a supported image format
	IsImageFile(filePath string) bool
	// GenerateImage generates an image from prompt using model ("provider/name")
	// and returns the path of the saved file. A blank quality or size leaves the
	// provider's own default
	GenerateImage(ctx context.Context, model, prompt, quality, size string) (string, error)
	// EditImage edits the image at imagePath using prompt and model
	// ("provider/name") and returns the path of the saved file. A blank quality
	// or size leaves the provider's own default. A non-empty maskPath points to
	// a PNG whose transparent (alpha=0) areas mark the editable region; all
	// other pixels are preserved exactly.
	EditImage(ctx context.Context, model, prompt, imagePath, quality, size, maskPath string) (string, error)
	// CreateImageVariation creates a variation of the image at imagePath using
	// model ("provider/name") and returns the path of the saved file. A blank
	// size leaves the provider's own default
	CreateImageVariation(ctx context.Context, model, imagePath, size string) (string, error)
}

ImageService handles image operations including loading and encoding

type InstallWorkflowOptions ¶ added in v0.182.0

type InstallWorkflowOptions struct {
	// Repo is "owner/name"; empty means the current repository.
	Repo string
	// Model runs the install agent and becomes the workflow's default model.
	Model string
	// Context is extra user-supplied guidance appended to the agent prompt.
	Context string
	// GitHubApp selects the GitHub App token variant of the workflow.
	GitHubApp bool
}

InstallWorkflowOptions parameterizes GitHubSetupService.InstallWorkflow.

type JudgeDecision ¶ added in v0.188.0

type JudgeDecision string

JudgeDecision is the verdict value the LLM judge returns for one pending tool call.

const (
	JudgeDecisionApproved JudgeDecision = "approved"
	JudgeDecisionRejected JudgeDecision = "rejected"
)

type JudgeVerdictChatEvent ¶ added in v0.188.0

type JudgeVerdictChatEvent struct {
	BaseChatEvent
	Tool     string
	Model    string // the judge model that decided
	Decision JudgeDecision
	Reason   string
	Turn     int
}

JudgeVerdictChatEvent reports the LLM judge's decision for one pending tool call when the judge approval delivery is active. Emitted for both decisions; a rejection surfaces as a TUI flash status / headless stderr line.

type MCPToolResult ¶

type MCPToolResult struct {
	ServerName string `json:"server_name"`
	ToolName   string `json:"tool_name"`
	Content    string `json:"content"`
	Error      string `json:"error,omitempty"`
}

MCPToolResult represents the result of an MCP tool execution

type ManifestTool ¶ added in v0.216.0

type ManifestTool interface {
	Manifest() ToolManifest
}

ManifestTool is implemented by tools that bring their own manifest, such as the browser and computer tools, so the tool registry can answer their policy.

type MessageQueuedEvent ¶

type MessageQueuedEvent struct {
	RequestID string
	Timestamp time.Time
	Message   sdk.Message
}

MessageQueuedEvent indicates a message was received from the queue and stored

func (e MessageQueuedEvent) GetRequestID() string

func (e MessageQueuedEvent) GetTimestamp() time.Time

type ModelSelectedEvent ¶ added in v0.182.0

type ModelSelectedEvent struct {
	Model string
}

ModelSelectedEvent is pushed through the UI notifier when something other than the TUI's own selector (e.g. the browser extension) switched the model, so an open selector can close and indicators refresh.

type MultiEditToolResult ¶

type MultiEditToolResult struct {
	FilePath        string                `json:"file_path"`
	Edits           []EditOperationResult `json:"edits"`
	TotalEdits      int                   `json:"total_edits"`
	SuccessfulEdits int                   `json:"successful_edits"`
	FileModified    bool                  `json:"file_modified"`
	OriginalSize    int64                 `json:"original_size"`
	NewSize         int64                 `json:"new_size"`
	BytesDifference int64                 `json:"bytes_difference"`
	NormalizedEdits int                   `json:"normalized_edits,omitempty"`
}

MultiEditToolResult represents the result of a MultiEdit operation

type MusicService ¶ added in v0.206.0

type MusicService interface {
	Compose(ctx context.Context, prompt, outPath string, seconds *float32, instrumental *bool) error
}

MusicService composes a music clip from a text prompt through the gateway's Music API, writing the audio to outPath. A non-nil seconds caps the clip length in seconds; a non-nil instrumental requests a vocal-free clip. An omitted knob leaves the choice to the configured provider.

type NoopUINotifier ¶

type NoopUINotifier struct{}

NoopUINotifier is the useful zero value: producers can always call Notify even before the program exists or after shutdown, with no nil checks. The container defaults to it until cmd/chat.go swaps in the real (program-backed) notifier.

func (NoopUINotifier) Notify(any)

type OptimizationStatusEvent ¶

type OptimizationStatusEvent struct {
	RequestID      string
	Timestamp      time.Time
	Message        string
	IsActive       bool
	OriginalCount  int
	OptimizedCount int
}

OptimizationStatusEvent indicates conversation optimization status

func (e OptimizationStatusEvent) GetRequestID() string

func (e OptimizationStatusEvent) GetTimestamp() time.Time

type PlanApprovalAction ¶

type PlanApprovalAction int

PlanApprovalAction represents the user's choice for plan approval

const (
	PlanApprovalAccept PlanApprovalAction = iota
	PlanApprovalReject
	PlanApprovalAcceptStandard
)

func (a PlanApprovalAction) String() string

type PlanApprovalRequestedEvent ¶

type PlanApprovalRequestedEvent struct {
	RequestID    string
	Timestamp    time.Time
	PlanContent  string
	PlanID       string
	ResponseChan chan PlanApprovalAction `json:"-"`
}

PlanApprovalRequestedEvent indicates plan mode completion requires user approval

func (e PlanApprovalRequestedEvent) GetRequestID() string

func (e PlanApprovalRequestedEvent) GetTimestamp() time.Time

type ReminderQuery ¶

type ReminderQuery struct {
	Hook             HookPoint
	Turn             int
	SessionTurn      int
	MaxTurns         int
	Fired            map[string]bool
	ToolFailed       bool
	RepeatedFailures int
	FailedTool       string
	FinishReason     string
	IncompleteTodos  []TodoItem
	StalledStrikes   int
	EmptyResponse    bool
	TodoCount        int
	ModeChanged      bool
	PrevMode         AgentMode
	Mode             AgentMode
	ModeGuidance     map[string]string
}

ReminderQuery carries the context a SystemReminderProvider needs to decide which reminders are due at a hook point.

Turn and SessionTurn differ deliberately. Turn is the agent-loop turn within the CURRENT run (one user message in chat), used by the turns_before_max trigger relative to MaxTurns. SessionTurn is the cumulative model-turn count across the whole chat session - it does NOT reset when a new user message starts a fresh run, so the `interval` trigger fires on every Nth conversational turn as users expect (per-request Turns would reset to 1 each message and an interval reminder would essentially never fire in chat). In headless `infer headless` a single invocation IS the session, so the two are equal.

Fired carries reminder names already emitted this session (consulted by the `once` trigger); the caller marks names fired after injecting.

ToolFailed reports whether the tool batch that just completed had any failed call. It is meaningful only at the post_tool hook (set right before that dispatch) and drives the `on_failure` trigger.

RepeatedFailures and FailedTool are set at the post_tool hook when the same tool call has failed threshold+ consecutive times; they drive the `on_repeated_failure` trigger. FailedTool is the function name, for templating.

FinishReason carries the LLM response's finish_reason string. It drives the `on_truncation` trigger at the post_stream hook (firing when the value is "length").

IncompleteTodos carries the remaining open todo items from the model's TodoWrite list; it drives the `on_stalled_todos` trigger at the post_stream hook (firing when non-empty and the response had no tool calls). StalledStrikes is the count of consecutive no-tool-call responses, gating that trigger's strike cap (threshold).

EmptyResponse reports that the just-finished assistant turn carried neither text nor a tool call (a reasoning-only reply); it drives the `on_empty_response` trigger at the post_stream hook.

ModeChanged reports whether the agent mode differs from the previous streaming turn; PrevMode/Mode carry the transition. They are meaningful only at the pre_stream hook (set right before that dispatch) and drive the `on_mode_change` trigger.

type RetryStatus ¶

type RetryStatus struct {
	Attempt     int
	MaxAttempts int
}

RetryStatus tracks the current retry state for reconnection attempts. A nil *RetryStatus means no retry is in progress.

type RetryStatusSink ¶ added in v0.207.0

type RetryStatusSink interface {
	SetRetryStatus(status *RetryStatus)
}

RetryStatusSink receives the agent's retry progress so a UI can show it.

type ScreenRecordingStatusEvent ¶ added in v0.208.0

type ScreenRecordingStatusEvent struct {
	Active    bool
	Timestamp time.Time
}

ScreenRecordingStatusEvent is pushed through the UI notifier when a RecordStart screen recording begins or its ffmpeg process ends (RecordStop, the max_duration cap, or shutdown). It is also a ChatEvent so headless can bridge it into the rendered stream.

func (e ScreenRecordingStatusEvent) GetRequestID() string

func (e ScreenRecordingStatusEvent) GetTimestamp() time.Time

type ScreenRegion ¶

type ScreenRegion struct {
	X      int `json:"x"`
	Y      int `json:"y"`
	Width  int `json:"width"`
	Height int `json:"height"`
}

ScreenRegion represents a rectangular region of the screen

type SelfGatedTool ¶ added in v0.216.0

type SelfGatedTool interface {
	SelfGated() bool
}

SelfGatedTool is implemented by tools that a context of their own switches on, such as the A2A tools under a2a.enabled. The tools.enabled switch for local tools does not gate them, their IsEnabled alone decides.

type SessionTool ¶ added in v0.216.0

type SessionTool interface {
	NeedsSession() bool
}

SessionTool is implemented by tools that keep state past their own call, such as a running screen recording, and so need a chat or headless session.

type ShellDetachedEvent ¶

type ShellDetachedEvent struct {
	RequestID string
	Timestamp time.Time
	ShellID   string
	Command   string
}

ShellDetachedEvent indicates a Bash command has been moved to background

func (e ShellDetachedEvent) GetRequestID() string

func (e ShellDetachedEvent) GetTimestamp() time.Time

type Skill ¶

type Skill struct {
	Name        string
	Description string
	Path        string
	Scope       SkillScope
	PluginName  string
}

Skill is the in-memory metadata for a discovered SKILL.md. The body of the file is intentionally not loaded at startup - only frontmatter - so the model reads it on demand via the existing Read tool (progressive disclosure, matching the contract).

func (s Skill) DisplayName() string

func (s Skill) Summary() SkillSummary

type SkillLoadError ¶

type SkillLoadError struct {
	Path   string
	Reason string
}

SkillLoadError records a per-skill validation failure so `infer skills list` can surface why a directory was skipped without crashing startup.

type SkillScope ¶

type SkillScope string

SkillScope identifies where a skill came from: the project (.infer/skills/), the open-standard location (.agents/skills/), the user-global location (~/.infer/skills/), an installed plugin (~/.infer/plugins/<name>/skills/), or the centralized catalog (dynamically discovered at runtime).

const (
	SkillScopeProject SkillScope = "project"
	SkillScopeAgents  SkillScope = "agents"
	SkillScopeUser    SkillScope = "user"
	SkillScopePlugin  SkillScope = "plugin"
	SkillScopeCatalog SkillScope = "catalog"
)

type SkillSummary ¶

type SkillSummary struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Scope       string `json:"scope"`
}

SkillSummary is the serializable projection of a Skill (qualified name, description, scope) used wherever skills cross a wire boundary.

type SkillsService ¶

type SkillsService interface {
	// Load scans the configured skill directories and populates the
	// in-memory list. Safe to call once at startup; calling again rescans.
	// Returns nil and does nothing when skills are disabled in config.
	Load(ctx context.Context) error
	// List returns the currently loaded skills. The slice is a defensive
	// copy - callers may retain or mutate it freely.
	List() []Skill
	// Get returns the loaded skill with the given name and true, or a zero
	// Skill and false when no such skill is loaded. Used by deterministic
	// activation to resolve an explicitly invoked skill name to its metadata
	// (description + path) for injection.
	Get(name string) (Skill, bool)
	// Errors returns validation failures encountered during the most recent
	// Load. Cleared on each Load call.
	Errors() []SkillLoadError
	// Discover looks up a skill by name in the centralized catalog when
	// progressive discovery is enabled and no local skill of that name
	// exists. Returns the skill metadata (name, description, path) and
	// true on success, or a zero Skill and false when the skill is not
	// found in the catalog or discovery is disabled. The skill body is
	// fetched only when the skill is actually activated (progressive).
	// Local skills always take precedence - if a skill with the same name
	// is already loaded, no catalog lookup is performed.
	Discover(ctx context.Context, name string) (Skill, bool)
	// CleanupDynamic removes dynamically downloaded skills from disk.
	// When cleanup is enabled in config, this is called after the session
	// ends to remove any skills that were fetched from the catalog.
	CleanupDynamic(ctx context.Context) error
}

SkillsService discovers and exposes Agent Skills. Implementations must be safe for concurrent reads after Load returns.

type SoundEffectService ¶ added in v0.206.0

type SoundEffectService interface {
	Generate(ctx context.Context, prompt, outPath string, seconds *float32, loop *bool) error
}

SoundEffectService generates a short sound effect or ambience clip from a text prompt through the gateway's SFX API, writing WAV audio to outPath. A non-nil seconds caps the clip length in seconds; a non-nil loop requests a clip that loops seamlessly. An omitted knob leaves the choice to the configured provider.

type SpeechService ¶ added in v0.186.0

type SpeechService interface {
	Synthesize(ctx context.Context, text, voiceSamplePath, outPath string) error
}

SpeechService synthesizes speech through the gateway's Audio API, writing the audio to outPath; a non-empty voiceSamplePath is forwarded as a reference sample for zero-shot voice cloning.

type SubagentInfo ¶ added in v0.214.0

type SubagentInfo struct {
	Name        string   `json:"name"`
	Description string   `json:"description"`
	Model       string   `json:"model,omitempty"`
	Tools       []string `json:"tools,omitempty"`
	ReadOnly    bool     `json:"read_only"`
	Source      string   `json:"source"`
}

SubagentInfo describes one Markdown-defined subagent preset (.infer/agents/*.md) for user-facing listings like /agents. An empty Model means inherit and an empty Tools list means the parent's tools are inherited.

type SystemReminder ¶

type SystemReminder struct {
	Name               string
	Text               string
	AppendToToolResult bool
}

SystemReminder is a resolved reminder ready to inject into the conversation. When AppendToToolResult is true, the Text is appended to the last tool-role message content (for tool_call/tool pairing) instead of inserted as a standalone user message. Set by the provider for on_repeated_failure reminders.

type SystemReminderProvider ¶

type SystemReminderProvider interface {
	RemindersDue(q ReminderQuery) []SystemReminder
}

SystemReminderProvider decides which system reminders are due for a given ReminderQuery (hook point, per-run turn, cumulative session turn, max turns, and the already-fired set). It is implemented by config from the user's reminders list; the agent depends on this interface so reminder policy can be faked in tests.

type TodoItem ¶

type TodoItem struct {
	ID      string `json:"id"`
	Content string `json:"content"`
	Status  string `json:"status"`
}

TodoItem represents a single todo item

type TodoList ¶ added in v0.207.0

type TodoList interface {
	SetTodos(todos []TodoItem)
	GetTodos() []TodoItem
}

TodoList handles todo list state

type TodoUpdateChatEvent ¶

type TodoUpdateChatEvent struct {
	BaseChatEvent
	Todos []TodoItem
}

TodoUpdateChatEvent indicates the todo list has been updated (flows through chat event channel)

type TodoWriteToolResult ¶

type TodoWriteToolResult struct {
	Todos          []TodoItem `json:"todos"`
	TotalTasks     int        `json:"total_tasks"`
	CompletedTasks int        `json:"completed_tasks"`
	InProgressTask string     `json:"in_progress_task,omitempty"`
	ValidationOK   bool       `json:"validation_ok"`
}

TodoWriteToolResult represents the result of a TodoWrite operation

type Tool ¶

type Tool interface {
	// Definition returns the tool definition for the LLM
	Definition() sdk.ChatCompletionTool

	// Execute runs the tool with given arguments
	Execute(ctx context.Context, args map[string]any) (*ToolExecutionResult, error)

	// Validate checks if the tool arguments are valid
	Validate(args map[string]any) error

	// IsEnabled returns whether this tool is enabled
	IsEnabled() bool

	// FormatResult formats tool execution results for different contexts
	FormatResult(result *ToolExecutionResult, formatType FormatterType) string

	// FormatPreview returns a short preview of the result for UI display
	FormatPreview(result *ToolExecutionResult) string

	// ShouldCollapseArg determines if an argument should be collapsed in display
	ShouldCollapseArg(key string) bool

	// ShouldAlwaysExpand determines if tool results should always be expanded in UI
	ShouldAlwaysExpand() bool
}

Tool represents a single tool with its definition, handler, and validator

type ToolApprovalRequestedEvent ¶

type ToolApprovalRequestedEvent struct {
	RequestID string
	Timestamp time.Time
	ToolCall  sdk.ChatCompletionMessageToolCall
	// Context is optional text shown above the call in the approval prompt.
	// RequestApproval escalations use it for the judge's reason and the
	// agent's justification; regular approvals leave it empty.
	Context      string
	ResponseChan chan ApprovalAction `json:"-"`
}

ToolApprovalRequestedEvent is used for standard tool approval workflow. Computer-use tools use a separate pause/resume mechanism.

func (e ToolApprovalRequestedEvent) GetRequestID() string

func (e ToolApprovalRequestedEvent) GetTimestamp() time.Time

type ToolApprovalResolvedEvent ¶

type ToolApprovalResolvedEvent struct {
	RequestID string
	Timestamp time.Time
}

ToolApprovalResolvedEvent signals that a tool approval was answered (terminal or panel), so bus subscribers like the extension bridge clear their card. It is the reliable "answered" signal, replacing the racy next-event heuristic.

func (e ToolApprovalResolvedEvent) GetRequestID() string

func (e ToolApprovalResolvedEvent) GetTimestamp() time.Time

type ToolApprovalResponseEvent ¶

type ToolApprovalResponseEvent struct {
	Action   ApprovalAction
	ToolCall sdk.ChatCompletionMessageToolCall
}

ToolApprovalResponseEvent captures the user's approval decision

type ToolCancelledEvent ¶

type ToolCancelledEvent struct {
	RequestID  string
	Timestamp  time.Time
	ToolCallID string
	ToolName   string
}

ToolCancelledEvent is published when the conversation validator synthesizes a Tool-role response for an assistant tool_call whose real execution never completed (typically because the user pressed Esc between the model emitting tool_calls and the tools running). The conversation view uses this to surface a "[cancelled]" entry so the user understands why a requested tool never produced output.

func (e ToolCancelledEvent) GetRequestID() string

func (e ToolCancelledEvent) GetTimestamp() time.Time

type ToolExecutionCompletedEvent ¶

type ToolExecutionCompletedEvent struct {
	SessionID     string
	RequestID     string
	Timestamp     time.Time
	TotalExecuted int
	SuccessCount  int
	FailureCount  int
	Results       []*ToolExecutionResult
}

ToolExecutionCompletedEvent indicates tool execution is complete

func (e ToolExecutionCompletedEvent) GetRequestID() string

func (e ToolExecutionCompletedEvent) GetTimestamp() time.Time

type ToolExecutionProgressEvent ¶

type ToolExecutionProgressEvent struct {
	BaseChatEvent
	ToolCallID string
	ToolName   string
	Arguments  string
	Status     string
	Message    string
	Images     []ImageAttachment
}

ToolExecutionProgressEvent indicates progress in tool execution

type ToolExecutionResult ¶

type ToolExecutionResult struct {
	ToolName   string            `json:"tool_name"`
	ToolCallID string            `json:"tool_call_id,omitempty"`
	Arguments  map[string]any    `json:"arguments"`
	Success    bool              `json:"success"`
	Duration   time.Duration     `json:"duration"`
	Error      string            `json:"error,omitempty"`
	Data       any               `json:"data,omitempty"`
	Metadata   map[string]string `json:"metadata,omitempty"`
	Diff       string            `json:"diff,omitempty"`
	Rejected   bool              `json:"rejected,omitempty"`
	Images     []ImageAttachment `json:"images,omitempty"`
}

ToolExecutionResult represents the complete result of a tool execution

type ToolManifest ¶ added in v0.216.0

type ToolManifest struct {
	Name            string         `yaml:"name"`
	Description     string         `yaml:"description"`
	Parameters      map[string]any `yaml:"parameters"`
	Modes           []AgentMode    `yaml:"modes,omitempty"`
	RequireApproval *bool          `yaml:"require_approval,omitempty"`
}

ToolManifest defines a tool: the JSON Schema the model sees, the agent modes it may run in and its default approval; the Go tool registered under the same name executes it. Nil Modes means defaultToolModes and a nil RequireApproval inherits tools.safety.require_approval, so the zero value is the policy of any tool without a manifest, such as an MCP tool.

func ParseToolManifest(data []byte) (ToolManifest, error)

func (m ToolManifest) AvailableIn(mode AgentMode) bool

func (m ToolManifest) Definition() sdk.ChatCompletionTool

func (m ToolManifest) RequiresApproval(inherited bool) bool

func (m ToolManifest) Validate() error

func (m ToolManifest) WithRequireApproval(configured *bool) ToolManifest

type ToolManifestLookup ¶ added in v0.216.0

type ToolManifestLookup interface {
	Manifest(name string) ToolManifest
}

ToolManifestLookup resolves a tool's manifest by name, so callers can ask for its policy (read-only, plan mode, default approval) without knowing which bounded context defines the tool.

type ToolManifests ¶ added in v0.216.0

type ToolManifests map[string]ToolManifest

ToolManifests are a bounded context's built-in tool manifests by tool name.

func LoadToolManifests(fsys fs.FS, dir string) (ToolManifests, error)

func MustLoadToolManifests(fsys fs.FS, dir string) ToolManifests

func (ms ToolManifests) Manifest(name string) ToolManifest

func (ms ToolManifests) MustGet(name string) ToolManifest

func (ms ToolManifests) Names() []string

type ToolProgressCallback ¶ added in v0.184.0

type ToolProgressCallback func(message string)

ToolProgressCallback receives a progress line describing what a tool is currently doing. Callers throttle their own reporting; a callback must be safe to invoke from the goroutine running the tool.

func GetToolProgressCallback(ctx context.Context) ToolProgressCallback

type ToolService ¶

type ToolService interface {
	ToolManifestLookup
	ListTools() []sdk.ChatCompletionTool
	ListToolsForMode(mode AgentMode) []sdk.ChatCompletionTool
	ListAvailableTools() []string
	ListMarkdownSubagents() []SubagentInfo
	ExecuteTool(ctx context.Context, tool sdk.ChatCompletionMessageToolCallFunction) (*ToolExecutionResult, error)
	ExecuteToolDirect(ctx context.Context, tool sdk.ChatCompletionMessageToolCallFunction) (*ToolExecutionResult, error)
	IsToolEnabled(name string) bool
	ValidateTool(name string, args map[string]any) error
	GetTool(name string) (Tool, error)
}

ToolService handles tool execution

type TreeToolResult ¶

type TreeToolResult struct {
	Path            string `json:"path"`
	Output          string `json:"output"`
	TotalFiles      int    `json:"total_files"`
	TotalDirs       int    `json:"total_dirs"`
	MaxDepth        int    `json:"max_depth"`
	MaxFiles        int    `json:"max_files"`
	ShowHidden      bool   `json:"show_hidden"`
	Format          string `json:"format"`
	UsingNativeTree bool   `json:"using_native_tree"`
	Truncated       bool   `json:"truncated"`
}

TreeToolResult represents the result of a tree operation

type UINotifier ¶

type UINotifier interface {
	Notify(event any)
}

UINotifier delivers a background-originated event to the single Bubble Tea Update loop. It is the one ingress every background producer uses to push work or status changes into the UI, replacing the per-source self-rescheduling pollers. The only production implementation wraps (*tea.Program).Send and lives in cmd/chat.go; keeping this interface tea-free lets services depend on it without importing bubbletea. The event is an `any` (tea.Msg is itself `any`).

type UserInputEvent ¶

type UserInputEvent struct {
	Content       string
	Images        []ImageAttachment
	FromExtension bool
}

UserInputEvent represents user input submission. FromExtension marks input injected over the browser-extension bridge: the sender watches the side panel, which has no terminal question UI, so interactive gates (like the catalog-skill install confirmation) must not block on it.

type UserMessageChatEvent ¶ added in v0.182.0

type UserMessageChatEvent struct {
	BaseChatEvent
	Content string
}

UserMessageChatEvent mirrors a user message that entered the conversation (typed in the TUI, queued, or sent from the extension) so external consumers such as the extension bridge can render it. Content is the plain text.

type UserQuestion ¶

type UserQuestion struct {
	Header      string               `json:"header"`
	Question    string               `json:"question"`
	Options     []UserQuestionOption `json:"options"`
	MultiSelect bool                 `json:"multiSelect"`
}

UserQuestion is one clarifying question the agent asks the user via the AskUserQuestion tool. It mirrors the tool schema: a short header chip, the question text, 2-4 options, and whether multiple options may be selected.

type UserQuestionAnswer ¶

type UserQuestionAnswer struct {
	Header         string   `json:"header"`
	Question       string   `json:"question"`
	SelectedLabels []string `json:"selectedLabels"`
	OtherText      string   `json:"otherText,omitempty"`
}

UserQuestionAnswer is the user's response to one UserQuestion. SelectedLabels holds the chosen option label(s); OtherText is non-empty when the user picked the synthesized "Other" free-text choice (it may coexist with selected labels in multi-select). Header and Question are echoed so the tool result is self-describing for the model.

type UserQuestionBroker ¶

type UserQuestionBroker interface {
	AskUserQuestions(ctx context.Context, questions []UserQuestion) (answers []UserQuestionAnswer, ok bool, err error)
}

UserQuestionBroker publishes an interactive clarifying-question request to the user (chat TUI, or a headless host over stdin) and blocks until the user answers or the context is cancelled. It is injected into the AskUserQuestion tool's execution context when UserQuestionsAvailable reports a host that can render the form. Returns ok=false when the user dismisses the form (the response channel is closed without a value) or on cancellation.

func GetUserQuestionBroker(ctx context.Context) UserQuestionBroker

type UserQuestionOption ¶

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

UserQuestionOption is a single selectable choice within a UserQuestion.

type UserQuestionRequestedEvent ¶

type UserQuestionRequestedEvent struct {
	RequestID    string
	ToolCallID   string
	Timestamp    time.Time
	Questions    []UserQuestion
	ResponseChan chan []UserQuestionAnswer `json:"-"`
}

UserQuestionRequestedEvent is published when the AskUserQuestion tool asks the user one or more interactive clarifying questions. ResponseChan delivers the collected answers back to the blocked tool goroutine; closing it without a value signals cancellation.

func (e UserQuestionRequestedEvent) GetRequestID() string

func (e UserQuestionRequestedEvent) GetTimestamp() time.Time

type VideoRequest ¶ added in v0.206.0

type VideoRequest struct {
	Prompt         string
	Seconds        string
	Size           string
	AvatarPath     string
	AudioPath      string
	ReferencePaths []string
}

VideoRequest is one video render: a text prompt (required unless the audio drives the render), the optional seconds and size passthroughs, the optional avatar portrait and driving audio for lip-synced talking clips, and the optional reference images of the subject (e.g. an avatar from several angles) that keep them consistent in a prompt render. The gateway rejects reference images together with a portrait.

func (r VideoRequest) IsAvatar() bool

type VideoService ¶ added in v0.206.0

type VideoService interface {
	Render(ctx context.Context, request VideoRequest, outPath string) error
}

VideoService renders a video clip through the gateway's Videos API, writing MP4 content to outPath. With an avatar and audio it renders a lip-synced talking clip; the render blocks until the gateway job completes, fails or the context ends.

type WebSearchResponse ¶

type WebSearchResponse struct {
	Query   string            `json:"query"`
	Engine  string            `json:"engine"`
	Results []WebSearchResult `json:"results"`
	Total   int               `json:"total"`
	Time    time.Duration     `json:"time"`
	Error   string            `json:"error,omitempty"`
}

WebSearchResponse represents the complete search response

type WebSearchResult ¶

type WebSearchResult struct {
	Title   string `json:"title"`
	URL     string `json:"url"`
	Snippet string `json:"snippet"`
}

WebSearchResult represents a single search result