runtime

type AgentConfig struct {
	LLM                AgentLLM
	ToolApprovalPolicy interfaces.AgentToolApprovalPolicy
	Retrievers         AgentRetrievers
	Session            AgentSession
	Memory             AgentMemory
	Limits             AgentLimits
	ExecutionConfigs   ExecutionConfigs
	Hooks              []hooks.HookGroup
}

type AgentLLM struct {
	Client   interfaces.LLMClient
	Sampling *LLMSampling
}

type AgentLimits struct {
	MaxIterations   int
	Timeout         time.Duration
	ApprovalTimeout time.Duration
}

type AgentMemory struct {
	Config *memory.Config
}

type AgentRetrievers struct {
	// Retrievers is the list of retriever instances registered with the agent.
	Retrievers []interfaces.Retriever
	// Mode is the retriever mode (agentic, prefetch, hybrid).
	Mode types.RetrieverMode
}

type AgentSession struct {
	Conversation                interfaces.Conversation
	ConversationSize            int
	ConversationSaveOnIteration bool
}

type AgentSpec struct {
	// Name is a human-readable label (may include spaces). Runtimes may sanitize it when embedding in workflow IDs.
	Name           string
	Description    string
	SystemPrompt   string
	ResponseFormat *interfaces.ResponseFormat
}

type EventBusRuntime interface {
	Runtime
	SetEventBus(eventbus eventbus.EventBus)
	GetEventBus() eventbus.EventBus
}

type ExecuteRequest struct {
	UserPrompt string `json:"user_prompt"`
	// RunOptions is the per-call options forwarded from pkg/agent (e.g. conversation session). May be nil.
	// Runtimes must use [base.GetConversationID] to safely extract the conversation ID rather than
	// accessing the nested fields directly, so the nil-check is centralised.
	RunOptions       *types.AgentRunOptions `json:"run_options,omitempty"`
	StreamingEnabled bool                   `json:"streaming_enabled"`
	// EventTypes filters streamed events; empty means default (implementation-defined, often all types).
	EventTypes       []events.AgentEventType `json:"event_types,omitempty"`
	SubAgents        []*SubAgentSpec         `json:"sub_agents,omitempty"`
	MaxSubAgentDepth int                     `json:"max_sub_agent_depth"`

	// Tools is the registry-resolved tool list for this run.
	Tools []interfaces.Tool `json:"-"`

	ApprovalHandler types.ApprovalHandler `json:"approval_handler"`
}

type ExecutionConfig struct {
	Timeout     time.Duration
	MaxAttempts int
}

type ExecutionConfigs struct {
	LLM          ExecutionConfig
	ToolAuth     ExecutionConfig
	ToolExecute  ExecutionConfig
	MCP          ExecutionConfig
	A2A          ExecutionConfig
	Retriever    ExecutionConfig
	Memory       ExecutionConfig
	Conversation ExecutionConfig
	SubAgent     ExecutionConfig
}

type ExecutionPolicies struct {
	LLM          ExecutionPolicy
	ToolAuth     ExecutionPolicy
	ToolExecute  ExecutionPolicy
	MCP          ExecutionPolicy
	A2A          ExecutionPolicy
	Retriever    ExecutionPolicy
	Memory       ExecutionPolicy
	Conversation ExecutionPolicy
	SubAgent     ExecutionPolicy
}

type ExecutionPolicy struct {
	Timeout     time.Duration
	MaxAttempts int
	Retry       RetryPolicy
}

type LLMSampling = types.LLMSampling

type RetryPolicy struct {
	InitialInterval    time.Duration
	BackoffCoefficient float64
	MaximumInterval    time.Duration
}

type Runtime interface {
	// Execute runs one execution and returns the result. The agent package supplies approval via ExecuteRequest when needed.
	// Use WithTimeout or a context with deadline to avoid blocking.
	// When using conversation, pass the conversation ID on the request; agent and worker must use the same ID.
	// Agent identity lives on the runtime [AgentSpec] configured at construction.
	Execute(ctx context.Context, req *ExecuteRequest) (*types.AgentRunResult, error)

	// ExecuteStream starts the run and returns a channel of AgentEvent. Streams RUN_* lifecycle,
	// streaming assistant/tool/reasoning events, and CUSTOM approvals until RUN_FINISHED or RUN_ERROR ends the stream.
	// Delegated workflows may emit their own RUN_FINISHED; semantics for "root" completion are defined in pkg/agent.
	// After the terminal lifecycle event the channel may stay open briefly, then closes.
	// For approvals (tool or delegation), receive CUSTOM (AgentEventTypeCustom) events and use the agent
	// package approval path (e.g. OnApproval with the token from the custom payload).
	// When using conversation, pass the conversation ID on the request.
	ExecuteStream(ctx context.Context, req *ExecuteRequest) (<-chan events.AgentEvent, error)

	// Approve completes a pending tool approval when the runtime uses out-of-band approval
	// (e.g. Temporal CompleteActivity). Returns ErrApprovalNotSupported if not applicable.
	Approve(ctx context.Context, approvalToken string, status types.ApprovalStatus) error

	// Close closes the runtime and releases resources.
	Close()
}

type SubAgentSpec struct {
	Name     string  // human-readable agent name
	ToolName string  // tool name used to invoke this sub-agent (key in runtime route maps)
	Runtime  Runtime // the sub-agent's runtime instance
	Children []*SubAgentSpec
	// Tools is the registry-resolved tool list for this sub-agent at request time.
	Tools []interfaces.Tool `json:"-"`
}

type WorkerRuntime interface {
	Runtime
	// Start begins polling; it typically blocks until Stop is called or ctx is cancelled.
	Start(ctx context.Context) error
	// Stop stops polling and releases worker resources.
	Stop()
}