agent

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

type BackgroundRun interface {
	RoundStart(ctx context.Context) (background.Delivery, error)
	BeforeFinal(ctx context.Context) (background.Delivery, error)
	TakeSeen() []string
}

type BuildSystemPromptOptions struct {
	SelectedTools    []string // Actual registered tools for this turn, after capability filtering
	SkillsMetadata   []*skills.SkillMetadata
	ShellExecEnabled bool
	SkillInstallMode bool
	Language         string         // User language name for {{language}} placeholder (e.g. "Chinese (Simplified)")
	Config           *config.Config // Config for reading prompt templates; nil leaves the default base empty
	MemoryPrompt     string
	ProtocolPrompt   string
	WorkspaceLayout  sandbox.WorkspaceLayout
}

type CollaborationDelivery struct {
	BeforeStep int `json:"before_step"`
	// BeforeUsers distinguishes finishing-boundary events from the next poll,
	// which happens after that round's queued user messages have been delivered.
	BeforeUsers bool                  `json:"before_users,omitempty"`
	Events      []collaboration.Event `json:"events"`
}

type ImageDescriberFunc func(ctx context.Context, imgBytes []byte, prompt string) (string, error)

type KnowledgeBaseInfo struct {
	ID          string
	Name        string
	Type        string // Knowledge base type: "document" or "faq"
	Description string
	DocCount    int
	// Capabilities lists the retrieval surfaces this KB exposes. Any subset of
	// {"wiki", "chunks"}. "chunks" is present when the KB has vector and/or
	// keyword (BM25) indexing enabled. This is the *deterministic* source of
	// truth the agent should consult before picking a retrieval strategy —
	// significantly more reliable than running probing searches.
	Capabilities []string
	RecentDocs   []RecentDocInfo // Recently added documents (up to 10)
	// Profile is the generated description (gist, merged topics, typical
	// questions) derived from document profiles. It complements the manual
	// Description: that one says what the KB is for, this one says what is
	// actually in it. nil when never generated.
	Profile *types.KnowledgeBaseProfile
}

type PageContextAgent struct {
	ID   string
	Name string
}

type PageContextInfo struct {
	Page              string // known page identifier, e.g. "settings_models"; may be empty
	Section           string // part of the page in view, e.g. "tools"; only with Page
	Agent             *PageContextAgent
	KnowledgeBaseID   string
	KnowledgeBaseName string
	Document          *SelectedDocumentInfo // nil unless a document is open
	WikiPage          *PageContextWikiPage  // nil unless a Wiki page is open
	WikiIssues        []*PageContextWikiIssue
	Model             *PageContextModel
	MCPService        *PageContextMCPService
	Message           *PageContextMessage
	// Title, View and Selection come from the page as the client reports it;
	// they are what the user sees, not verified resources.
	Title     string
	View      string
	Selection *types.PageSelection
}

type PageContextMCPService struct {
	ID        string
	Name      string
	Transport string
	Enabled   bool
}

type PageContextMessage struct {
	SessionID  string
	MessageID  string
	Role       string
	AgentID    string
	Question   string
	Answer     string
	References []*PageContextReference
}

type PageContextModel struct {
	ID        string
	Name      string
	Type      string
	Source    string
	IsBuiltin bool
}

type PageContextReference struct {
	KnowledgeID     string
	KnowledgeBaseID string
	Title           string
}

type PageContextWikiIssue struct {
	ID        string
	Slug      string
	IssueType string
	Status    string
}

type PageContextWikiPage struct {
	Slug  string
	Title string
}

type PendingCall struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	// Arguments is the decoded JSON the call executes with.
	Arguments         string                 `json:"arguments"`
	UnresolvedHandles []string               `json:"unresolved_handles,omitempty"`
	ProviderMetadata  types.ToolCallMetadata `json:"provider_metadata,omitempty"`
}

type PendingRound struct {
	// Step carries the round's thought and reasoning; its ToolCalls are the
	// calls that finished before the blocked one.
	Step  types.AgentStep `json:"step"`
	Calls []PendingCall   `json:"calls"`
	// BlockedIndex is the call waiting on the prompt. Calls after it have
	// not run.
	BlockedIndex int `json:"blocked_index"`
}

type PinnedMCPServiceInfo struct {
	Discoverable bool // Available through the scoped MCP directory.
	ID           string
	Name         string
	Description  string
	ToolNames    []string // Registered tool.function names for this service (mcp_{service}_{tool})
}

type PinnedSkillInfo struct {
	Name        string
	Description string
}

type PlaceholderDefinition struct {
	Name        string `json:"name"`
	Label       string `json:"label"`
	Description string `json:"description"`
}

type QuestionOriginInfo struct {
	KnowledgeBaseID   string
	KnowledgeBaseName string
	Document          *SelectedDocumentInfo // nil when only the base is known
}

type RecentDocInfo struct {
	ChunkID             string
	KnowledgeBaseID     string
	KnowledgeID         string
	Title               string
	Description         string
	FileName            string
	FileSize            int64
	Type                string
	CreatedAt           string // Formatted time string
	FAQStandardQuestion string
	FAQSimilarQuestions []string
	FAQAnswers          []string
}

type RunSnapshot struct {
	CollaborationDeliveries []CollaborationDelivery `json:"collaboration_deliveries,omitempty"`
	CollaborationCursor     *int64                  `json:"collaboration_cursor,omitempty"`
	MCPToolRefs             []string                `json:"mcp_tool_refs,omitempty"`
	Version                 int                     `json:"version"`
	CollaborationWait       bool                    `json:"collaboration_wait,omitempty"`
	BetweenRounds           bool                    `json:"between_rounds,omitempty"`
	// Request is the caller's types.ResumableAgentRequest.
	Request   json.RawMessage `json:"request,omitempty"`
	Query     string          `json:"query"`
	ImageURLs []string        `json:"image_urls,omitempty"`
	// UserMessages holds the raw text referenced by UserMessagesBefore.
	UserMessages map[string]string `json:"user_messages,omitempty"`

	CompletedSteps []types.AgentStep     `json:"completed_steps"`
	KnowledgeRefs  []*types.SearchResult `json:"knowledge_refs,omitempty"`
	CurrentRound   int                   `json:"current_round"`
	TurnUsage      types.TokenUsage      `json:"turn_usage"`

	PendingRound PendingRound `json:"pending_round"`
}

type SelectedDocumentInfo struct {
	KnowledgeID     string // Knowledge ID
	KnowledgeBaseID string // Knowledge base ID
	Title           string // Document title
	FileName        string // Original file name
	FileType        string // File type (pdf, docx, etc.)
}

type SystemPromptSection struct {
	Name    string
	Content string
}