runtime

type AgentExecution struct {
	LLM     AgentLLM
	Tools   AgentTools
	Session AgentSession
	Limits  AgentLimits
}

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

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

type AgentSession struct {
	Conversation     interfaces.Conversation
	ConversationSize int
}

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 AgentTools struct {
	Tools          []interfaces.Tool
	Registry       interfaces.ToolRegistry
	ApprovalPolicy interfaces.AgentToolApprovalPolicy
}

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

type ExecuteRequest struct {
	UserPrompt       string
	ConversationID   string
	StreamingEnabled bool
	// EventTypes filters streamed events; empty means default (implementation-defined, often all types).
	EventTypes       []types.AgentEventType
	SubAgentRoutes   map[string]types.SubAgentRoute
	MaxSubAgentDepth int

	ApprovalHandler types.ApprovalHandler

	// AgentSpec is identity and output-format metadata for this run (name, description, system prompt, response format).
	AgentSpec *AgentSpec
	// AgentExecution is LLM, tools, conversation, sampling, and policy for this run.
	AgentExecution *AgentExecution
}

type LLMSampling struct {
	Temperature *float64
	MaxTokens   int
	TopP        *float64
	TopK        *int
	Reasoning   *interfaces.LLMReasoning
}

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 is on req.AgentSpec.Name when AgentSpec is set.
	Execute(ctx context.Context, req *ExecuteRequest) (*types.AgentResponse, error)

	// ExecuteStream starts the run and returns a channel of AgentEvent. Events are streamed until
	// AgentEventComplete from this agent (the root of the run). Complete events from delegated
	// sub-agents are still delivered but do not close the stream. After that root complete, the
	// channel may remain open until the implementation finishes the run (e.g. backend cleanup), then closes.
	// For approvals (tool or delegation), receive AgentEventApproval and call the approval path
	// provided by the agent package (e.g. OnApproval in streaming examples).
	// When using conversation, pass the conversation ID on the request.
	// Agent identity is on req.AgentSpec.Name when AgentSpec is set.
	ExecuteStream(ctx context.Context, req *ExecuteRequest) (chan *types.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 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()
}