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 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 RunHandle interface {
	// ID returns the unique run identifier, stable across process restarts when the
	// backend supports reconnect (e.g. Temporal workflow ID).
	ID() string

	// Status returns the current [types.RunStatus] of this run.
	// Returns [ErrRunNotFound] when the underlying run is no longer known.
	Status(ctx context.Context) (types.RunStatus, error)

	// Cancel requests cancellation of this run.
	// Returns [ErrRunAlreadyCompleted] when the run has already finished.
	// Returns [ErrRunNotFound] when the underlying run is no longer known.
	Cancel(ctx context.Context) error

	// Get blocks until the run finishes and returns the result.
	// Cancelling ctx unblocks Get but does NOT cancel the agent run itself —
	// use [RunHandle.Cancel] for that.
	Get(ctx context.Context) (*types.AgentRunResult, error)

	// Done returns a channel that is closed when the run finishes (success or failure).
	// Safe to call multiple times; always returns the same channel.
	Done() <-chan struct{}
}

type RunRequest struct {
	UserPrompt string `json:"user_prompt"`
	// ConversationID is the conversation session for this run. Empty means no conversation.
	// Agent and worker must use the same ID when conversation is enabled.
	ConversationID string `json:"conversation_id,omitempty"`
	// EnableLLMStream requests token-level LLM streaming (Agent.Stream typically sets true;
	// Agent.Run sets false). Distinct from agent-event streaming on [StreamHandle.Events].
	EnableLLMStream bool `json:"enable_llm_stream"`
	// EventTypes filters streamed agent 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:"-"`
}

type Runtime interface {
	// Run starts one blocking-style agent run and returns a [RunHandle] immediately.
	// The run continues asynchronously; use [RunHandle.Get] or [RunHandle.Done] to wait for
	// completion, and [RunHandle.Status]/[RunHandle.Cancel] for lifecycle control.
	// The runtime mints the run ID exposed by [RunHandle.ID]. When using conversation, set
	// [RunRequest.ConversationID]; agent and worker must use the same ID. Agent identity
	// lives on the runtime [AgentSpec] configured at construction. The agent package supplies
	// approval via [RunRequest] when needed.
	Run(ctx context.Context, req *RunRequest) (RunHandle, error)

	// GetRunHandle returns a [RunHandle] for an existing run identified by runID
	// (e.g. after a process restart). Use this instead of [Runtime.Run] when the run
	// was already started. Live same-process reuse is handled at the agent layer
	// (run registry); this method is for runtime-level reconnect.
	// Returns [ErrRunNotFound] when runID is unknown or the runtime cannot recover
	// a handle (e.g. LocalRuntime has no durable run tracking).
	// Returns [ErrRunAlreadyCompleted] when the run has already finished.
	GetRunHandle(ctx context.Context, runID string) (RunHandle, error)

	// Stream starts one streaming agent run and returns a [StreamHandle] immediately.
	// It does not subscribe to events; call [StreamHandle.Events] on the returned handle.
	// The runtime mints the run ID exposed by [StreamHandle.ID]. For approvals (tool or
	// delegation), subscribe via [StreamHandle.Events], handle CUSTOM events, then call
	// [StreamHandle.Approve]. When using conversation, set [RunRequest.ConversationID] on the request.
	Stream(ctx context.Context, req *RunRequest) (StreamHandle, error)

	// OnApproval completes a pending stream approval by token. Prefer [StreamHandle.Approve].
	// Returns [types.ErrApprovalAlreadyResolved] when the token was already completed.
	//
	// Deprecated: Use [StreamHandle.Approve] on the handle from [Runtime.Stream] or
	// [Runtime.GetStreamHandle] instead. This method will be removed in v0.4.0.
	OnApproval(ctx context.Context, approvalToken string, status types.ApprovalStatus) error

	// GetStreamHandle returns a [StreamHandle] for an existing streaming run identified by
	// runID (e.g. after a process restart). Use this instead of [Runtime.Stream]
	// when the run was already started; then call [StreamHandle.Events] (optionally with
	// a non-zero fromOffset) to subscribe. Live same-process reuse is handled at the
	// agent layer (stream registry); this method is for runtime-level reconnect.
	// Returns [ErrStreamNotFound] when runID is unknown or the runtime cannot recover
	// a stream handle (e.g. LocalRuntime has no durable stream tracking).
	// Returns [ErrRunAlreadyCompleted] when the run has already finished.
	// Returns [ErrStreamOffsetNotSupported] when the runtime cannot replay at the requested offset.
	GetStreamHandle(ctx context.Context, runID string) (StreamHandle, error)

	// Close releases runtime resources (connections, workers, background goroutines).
	Close()
}

type StreamHandle interface {
	// ID returns the unique run identifier, stable across process restarts when the
	// backend supports reconnect (e.g. Temporal workflow ID).
	ID() string

	// Status returns the current [types.RunStatus] of this run.
	// Returns [ErrRunNotFound] when the underlying run is no longer known.
	Status(ctx context.Context) (types.RunStatus, error)

	// Cancel requests cancellation of this run.
	// Returns [ErrRunAlreadyCompleted] when the run has already finished.
	// Returns [ErrRunNotFound] when the underlying run is no longer known.
	Cancel(ctx context.Context) error

	// Get blocks until the stream run finishes and returns the result.
	// Cancelling ctx unblocks Get but does NOT cancel the agent run itself —
	// use [StreamHandle.Cancel] for that.
	Get(ctx context.Context) (*types.AgentRunResult, error)

	// Done returns a channel that is closed when the stream run finishes (success or failure).
	// Safe to call multiple times; always returns the same channel.
	Done() <-chan struct{}

	// Approve completes a tool approval request using the token from the approval event
	// and the chosen status (e.g., [ApprovalStatusApproved] or [ApprovalStatusRejected]).
	// Returns [ErrApprovalAlreadyResolved] when the token was already completed.
	Approve(ctx context.Context, approvalToken string, status types.ApprovalStatus) error

	// Events subscribes to this run's event stream starting at fromOffset.
	// fromOffset == 0 means from the beginning of the run (first-time subscriber).
	// fromOffset > 0 resumes after a crash or reconnect (Temporal only; LocalRuntime
	// returns [ErrStreamOffsetNotSupported] for fromOffset > 0).
	// Returns [ErrRunAlreadyCompleted] if the run has already finished.
	// Returns [ErrRunNotFound] if the run is unknown.
	// The channel is closed after the terminal lifecycle event (RUN_FINISHED / RUN_ERROR).
	Events(ctx context.Context, fromOffset int64) (<-chan events.AgentEvent, error)
}

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()
}