engine

type ActivityHeartbeatRecorder interface {
	RecordHeartbeat(details ...any)
}

type ActivityOptions struct {
	// Queue overrides the default activity queue. If empty, the activity inherits
	// the workflow's task queue.
	Queue string
	// RetryPolicy controls retry behavior for this activity. If zero-valued, the
	// engine uses its default retry policy.
	RetryPolicy RetryPolicy
	// ScheduleToStartTimeout bounds how long the activity may wait in the task
	// queue before a worker starts the attempt. Zero means leave queue-wait
	// unspecified here and let the engine adapter apply its own defaults.
	ScheduleToStartTimeout time.Duration
	// StartToCloseTimeout bounds one activity attempt once a worker has started
	// executing it. This is the primary "healthy attempt" budget for planner and
	// tool work. Zero means use the engine default.
	StartToCloseTimeout time.Duration
	// HeartbeatTimeout bounds the maximum gap between heartbeats emitted by the
	// running activity. Zero disables heartbeat-based liveness detection.
	HeartbeatTimeout time.Duration
}

type Canceler interface {
	// CancelByID requests cancellation of the workflow identified by
	// workflowID.
	CancelByID(ctx context.Context, workflowID string) error
}

type ChildWorkflowHandle interface {
	// Get waits for child completion and returns the typed result.
	Get(ctx context.Context) (*api.RunOutput, error)
	// IsReady returns true if the child workflow has completed (success or failure)
	// and Get() will not block.
	IsReady() bool
	// Cancel requests cancellation of the child workflow execution.
	Cancel(ctx context.Context) error
	// RunID returns the engine-assigned run identifier of the child.
	RunID() string
}

type ChildWorkflowRequest struct {
	// ID is the child workflow identifier, unique within the engine scope.
	ID string
	// Workflow is the provider workflow name to execute.
	Workflow string
	// TaskQueue is the queue to schedule the child on.
	TaskQueue string
	// Input is the payload passed to the child workflow handler.
	Input *api.RunInput
	// RunTimeout bounds the total child workflow execution time.
	RunTimeout time.Duration
	// RetryPolicy controls start retries for the child workflow start attempt.
	RetryPolicy RetryPolicy
}

type CompletionQuerier interface {
	// QueryRunCompletion returns the workflow output for successful runs or the
	// terminal error for failed/timed-out/canceled runs, addressed by
	// workflowID.
	QueryRunCompletion(ctx context.Context, workflowID string) (*api.RunOutput, error)
}

type Engine interface {
	// RegisterWorkflow registers a workflow definition with the engine.
	RegisterWorkflow(ctx context.Context, def WorkflowDefinition) error

	// RegisterHookActivity registers a typed activity that publishes workflow-emitted
	// hook events outside of the deterministic workflow thread. The activity accepts
	// *api.HookActivityInput and returns an error.
	RegisterHookActivity(ctx context.Context, name string, opts ActivityOptions, fn func(context.Context, *api.HookActivityInput) error) error

	// RegisterPlannerActivity registers a typed planner activity (PlanStart or
	// PlanResume) that accepts *api.PlanActivityInput and returns *api.PlanActivityOutput.
	RegisterPlannerActivity(ctx context.Context, name string, opts ActivityOptions, fn func(context.Context, *api.PlanActivityInput) (*api.PlanActivityOutput, error)) error

	// RegisterExecuteToolActivity registers a typed execute_tool activity that
	// accepts *api.ToolInput and returns *api.ToolOutput.
	RegisterExecuteToolActivity(ctx context.Context, name string, opts ActivityOptions, fn func(context.Context, *api.ToolInput) (*api.ToolOutput, error)) error

	// StartWorkflow initiates a new workflow execution and returns a handle for
	// interacting with it. The workflow ID in req must be unique for the engine
	// instance. Returns an error if the workflow name is not registered, the ID
	// conflicts with a running workflow, or if scheduling fails.
	StartWorkflow(ctx context.Context, req WorkflowStartRequest) (WorkflowHandle, error)

	// QueryRunStatus returns the current lifecycle status for the workflow
	// identified by workflowID. The engine is the source of truth for durable
	// workflow status. Returns an error if the workflow does not exist or if
	// querying fails.
	QueryRunStatus(ctx context.Context, workflowID string) (RunStatus, error)
}

type Future[T any] interface {
	// Get blocks until the activity completes and returns the typed result.
	// Calling Get multiple times on the same Future returns the same value/error.
	Get(ctx context.Context) (T, error)

	// IsReady returns true if the activity has completed (success or failure) and Get()
	// will not block. This allows workflows to poll or implement custom waiting strategies.
	IsReady() bool
}

type HookActivityCall struct {
	// Name identifies the registered hook activity.
	Name string

	// Input is the typed payload passed to the activity handler.
	Input *api.HookActivityInput

	// Options overrides the registered activity defaults for this invocation.
	Options ActivityOptions
}

type PlannerActivityCall struct {
	// Name identifies the registered planner activity.
	Name string

	// Input is the typed payload passed to the activity handler.
	Input *api.PlanActivityInput

	// Options overrides the registered activity defaults for this invocation.
	Options ActivityOptions
}

type Receiver[T any] interface {
	// Receive blocks until a signal value is delivered and returns it.
	// Implementations should respect ctx when possible; for engines that do not
	// support context cancellation, Receive may ignore ctx and rely on workflow
	// cancellation semantics instead.
	Receive(ctx context.Context) (T, error)

	// ReceiveWithTimeout blocks until a signal value is delivered or the timeout
	// elapses and returns an error. A non-positive timeout must return
	// context.DeadlineExceeded immediately.
	//
	// This method is required so workflow code can enforce global run deadlines
	// while awaiting external signals (pause/resume, confirmations, clarifications,
	// external tool results) without relying on engine-level timeouts.
	ReceiveWithTimeout(ctx context.Context, timeout time.Duration) (T, error)

	// ReceiveAsync attempts to receive a signal without blocking.
	ReceiveAsync() (T, bool)
}

type RegistrationSealer interface {
	// SealRegistration closes the registration phase and makes staged handlers
	// visible to execution. Implementations must be idempotent.
	SealRegistration(ctx context.Context) error
}

type RetryPolicy struct {
	// MaxAttempts caps the total number of retry attempts. Zero means unlimited retries.
	MaxAttempts int
	// InitialInterval is the delay before the first retry. Zero means use engine default.
	InitialInterval time.Duration
	// BackoffCoefficient multiplies the delay after each retry. Values < 1 are treated
	// as 1 (constant backoff). A value of 2 provides exponential backoff.
	BackoffCoefficient float64
}

type RunStatus string

type Signaler interface {
	// SignalByID sends a signal to the given workflow identified by workflowID
	// and optional runID. The payload is engine-specific and must be
	// serializable by the engine client.
	SignalByID(ctx context.Context, workflowID, runID, name string, payload any) error
}

type ToolActivityCall struct {
	// Name identifies the registered execute_tool activity.
	Name string

	// Input is the typed payload passed to the activity handler.
	Input *api.ToolInput

	// Options overrides the registered activity defaults for this invocation.
	Options ActivityOptions
}

type WorkflowContext interface {
	// Context returns the Go context for the workflow. In deterministic engines
	// (like Temporal), this is a special replay-aware context. Use this for activity
	// execution and cancellation propagation.
	Context() context.Context
	// SetQueryHandler registers a read-only query handler that can be invoked by
	// external clients to retrieve workflow state. Handlers must be deterministic
	// and side-effect free. Engines that do not support queries may implement
	// this as a no-op.
	SetQueryHandler(name string, handler any) error

	// WorkflowID returns the unique identifier for this workflow execution.
	WorkflowID() string

	// RunID returns the engine-assigned run identifier, used for observability
	// and run-level correlation.
	RunID() string

	// PublishHook schedules the runtime hook activity and waits for completion.
	// Implementations must run hook publishing outside of the deterministic workflow
	// thread (e.g., via activities in Temporal) so subscribers can perform I/O.
	PublishHook(ctx context.Context, call HookActivityCall) error

	// ExecutePlannerActivity schedules a planner activity (PlanStart/PlanResume)
	// and blocks until it completes. Planner activities are executed outside the
	// deterministic workflow thread and may perform I/O.
	ExecutePlannerActivity(ctx context.Context, call PlannerActivityCall) (*api.PlanActivityOutput, error)

	// ExecuteToolActivity schedules a tool execution activity and blocks until it
	// completes. This is useful for sequential execution (finalizers, single tools).
	ExecuteToolActivity(ctx context.Context, call ToolActivityCall) (*api.ToolOutput, error)

	// ExecuteToolActivityAsync schedules a tool execution activity and returns a Future
	// so workflows can run multiple tools concurrently and collect results later.
	ExecuteToolActivityAsync(ctx context.Context, call ToolActivityCall) (Future[*api.ToolOutput], error)

	// PauseRequests returns a typed receiver for pause signals.
	PauseRequests() Receiver[*api.PauseRequest]

	// ResumeRequests returns a typed receiver for resume signals.
	ResumeRequests() Receiver[*api.ResumeRequest]

	// ClarificationAnswers returns a typed receiver for clarification answers.
	ClarificationAnswers() Receiver[*api.ClarificationAnswer]

	// ExternalToolResults returns a typed receiver for external tool results.
	ExternalToolResults() Receiver[*api.ToolResultsSet]

	// ConfirmationDecisions returns a typed receiver for tool confirmation decisions.
	ConfirmationDecisions() Receiver[*api.ConfirmationDecision]

	// Now returns the current workflow time in a deterministic manner. Implementations
	// must return a time source that is replay-safe (e.g., Temporal's workflow.Now).
	Now() time.Time

	// NewTimer returns a Future that becomes ready after the given duration elapses
	// in workflow time. This is the engine-agnostic primitive for waking up on time
	// without polling.
	//
	// Implementations must schedule a deterministic timer (e.g., Temporal's
	// workflow.NewTimer). A non-positive duration should produce a Future that is
	// already ready.
	NewTimer(ctx context.Context, d time.Duration) (Future[time.Time], error)

	// Await blocks until condition returns true, or ctx is done.
	//
	// Condition must be deterministic and side-effect free. A typical use is to
	// wait on a set of Futures using IsReady() without draining them in a fixed
	// order (e.g., "wait until any tool future completes").
	Await(ctx context.Context, condition func() bool) error

	// StartChildWorkflow starts a child workflow execution and returns a handle
	// to await its completion or cancel it. Implementations should honor the
	// provided workflow name, task queue and timeouts without requiring local
	// registration lookups in the parent process.
	StartChildWorkflow(ctx context.Context, req ChildWorkflowRequest) (ChildWorkflowHandle, error)

	// Detached returns a derived WorkflowContext whose cancellation is disconnected
	// from the parent workflow scope.
	//
	// This is intended for cleanup/terminal work (e.g., emitting RunCompleted
	// hooks) that should still be attempted even when the main workflow context is
	// canceled.
	Detached() WorkflowContext

	// WithCancel returns a derived WorkflowContext whose cancellation can be
	// triggered independently of the parent workflow scope. This is used to
	// cooperatively cancel in-flight activities/child workflows when the runtime
	// needs to finalize (e.g., time budget reached).
	//
	// In deterministic engines, this must map to a workflow-level cancel scope
	// (e.g., Temporal's workflow.WithCancel).
	WithCancel() (WorkflowContext, func())
}

type WorkflowDefinition struct {
	// Name is the logical identifier registered with the engine (e.g., "AgentWorkflow").
	Name string
	// TaskQueue is the default queue used when starting new workflows. Workers
	// subscribe to this queue to receive workflow tasks.
	TaskQueue string
	// Handler is the workflow function invoked by the engine when the workflow executes.
	Handler WorkflowFunc
}

type WorkflowFunc func(ctx WorkflowContext, input *api.RunInput) (*api.RunOutput, error)

type WorkflowHandle interface {
	// Wait blocks until the workflow completes and returns the typed result.
	// Returns an error if the workflow fails or is cancelled.
	Wait(ctx context.Context) (*api.RunOutput, error)

	// Signal sends an asynchronous message to the workflow. The workflow can listen
	// for signals using engine-specific APIs. Returns an error if the signal cannot
	// be delivered (e.g., workflow already completed).
	Signal(ctx context.Context, name string, payload any) error

	// Cancel requests cancellation of the workflow. The workflow's context will be
	// cancelled, and in-flight activities may be cancelled depending on the engine.
	// Returns an error if cancellation fails.
	Cancel(ctx context.Context) error
}

type WorkflowStartRequest struct {
	// ID is the workflow identifier, which must be unique within the engine scope.
	// Typically derived from the agent ID and a UUID.
	ID string
	// Workflow names the registered workflow definition to execute. Engines that
	// support multiple workflows (one per agent) require this field.
	Workflow string
	// TaskQueue selects the queue to schedule the workflow on. Workers listening
	// on this queue will pick up the workflow.
	TaskQueue string
	// Input is the typed payload passed to the workflow handler.
	Input *api.RunInput
	// RunTimeout bounds the total workflow execution time at the engine level.
	// Zero means use the engine default (if any). Engines may map this to their
	// native execution timeout/TTL (Temporal: WorkflowRunTimeout/ExecutionTimeout).
	RunTimeout time.Duration
	// Memo stores small diagnostic payloads alongside the workflow execution.
	// Engines like Temporal persist these for queries/visibility. Nil means no memo.
	Memo map[string]any
	// SearchAttributes captures indexed metadata used for visibility queries.
	// Nil means no attributes are set.
	SearchAttributes map[string]any
	// RetryPolicy controls automatic restarts of the workflow start attempt if
	// scheduling fails. Not to be confused with activity retries.
	RetryPolicy RetryPolicy
}