agent

type Agent interface {
	// Type returns the agent's type identifier.
	Type() AgentType

	// Execute runs the agent with the given request.
	Execute(ctx context.Context, req *Request) (*Response, error)
}

type AgentType string

type AgenticOptions struct {
	MaxTurns    int
	Tools       []llm.Tool
	ToolHandler func(ctx context.Context, calls []llm.ToolCall) []llm.Message
	Timeout     time.Duration
	TurnTimeout time.Duration
	Reasoning   *llm.ReasoningConfig
	Plugins     []llm.Plugin
	ToolChoice  any // "auto", "none", "required", or specific tool
}

type Capabilities struct {
	// Execution model
	IsAgentic         bool // Uses tool calls (multi-turn)
	SupportsStreaming bool // Can stream responses

	// Input capabilities
	SupportedMedia []string // ["image", "audio", "pdf"]
	MaxInputTokens int      // Context limit

	// Output format
	OutputFormat string // "text", "json", "structured"
}

type CapableAgent interface {
	Agent

	// Capabilities returns the agent's capabilities.
	Capabilities() Capabilities

	// Description returns a human-readable description for tool use.
	Description() string
}

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

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

type FlexID string

type MediaEntry struct {
	Filename  string `json:"filename"`
	Mime      string `json:"mime"`
	SizeBytes int    `json:"size_bytes"`
	SHA256    string `json:"sha256,omitempty"`
	// Source distinguishes where in the prompt the part lives —
	// laplace uses it to mark current_message vs reranker_selected vs
	// input_artifact_id; reranker/enricher pass empty string.
	Source string `json:"source,omitempty"`
}

type MediaPart struct {
	Type     string // "image", "audio", "file"
	MimeType string
	Data     []byte
	URL      string // Alternative to Data
}

type MediaPartWithSource struct {
	Part   interface{}
	Source string
}

type Message struct {
	Role    string
	Content string
}

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

type Request struct {
	// Context (from ContextService)
	Shared *SharedContext

	// Query
	Query    string    // Main query/content to process
	Messages []Message // Conversation history (for chat agents)

	// Multimodal
	Media []MediaPart // Images, audio, files

	// IsChannel marks the scope as a multi-participant channel (Phase 6). Agents
	// use it to select channel-framed prompts; false for DMs. Set by the caller
	// from ScopeRepository.IsChannelScope at the invocation site (background loops
	// have no SharedContext).
	IsChannel bool

	// Agent-specific
	Params map[string]any // Custom parameters
}

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

type Response struct {
	// Content
	Content    string // Text response
	Structured any    // Parsed result (for JSON agents)

	// Metadata
	Tokens    TokenUsage
	Duration  time.Duration
	Reasoning string // Chain-of-thought (if available)

	// Agent-specific
	Metadata map[string]any
}

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

type SharedContext struct {
	UserID storage.ScopeID

	// Profile (always loaded)
	Profile      string         // Formatted <user_profile> for prompts
	ProfileFacts []storage.Fact // Raw facts (for custom formatting)

	// Topics
	RecentTopics string // Formatted <recent_topics>

	// Social Graph (v0.5.1)
	InnerCircle string // Formatted <inner_circle> (Work_Inner + Family), or <channel_participants> for channels

	// IsChannel marks the scope as a multi-participant channel (Phase 6). Agents
	// use it to select channel-framed prompts; false for DMs.
	IsChannel bool

	// Metadata
	Language      string // "en" or "ru"
	ReferenceTime time.Time
	LoadedAt      time.Time
}

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

type SingleShotRequest struct {
	AgentType    AgentType
	UserID       storage.ScopeID
	Model        string
	SystemPrompt string
	UserPrompt   string
	Messages     []llm.Message // Alternative to SystemPrompt+UserPrompt
	Temperature  *float64
	JSONMode     bool
	JSONSchema   *llm.JSONSchema      // Optional: strict JSON schema validation
	Reasoning    *llm.ReasoningConfig // Optional: nil omits the field (provider default)
}

type TokenUsage struct {
	Prompt     int
	Completion int
	Total      int
	Cost       *float64
}