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       []events.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 = types.LLMSampling

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.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.
	// Agent identity is on req.AgentSpec.Name when AgentSpec is set.
	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 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()
}