composer

type Composer interface {
	// ExecuteWorkflow executes a composite tool workflow.
	// Returns the workflow result or an error if execution fails.
	ExecuteWorkflow(ctx context.Context, def *WorkflowDefinition, params map[string]any) (*WorkflowResult, error)

	// ValidateWorkflow checks if a workflow definition is valid.
	// This includes checking for cycles, invalid tool references, etc.
	ValidateWorkflow(ctx context.Context, def *WorkflowDefinition) error

	// GetWorkflowStatus returns the current status of a running workflow.
	// Used for long-running workflows with elicitation.
	GetWorkflowStatus(ctx context.Context, workflowID string) (*WorkflowStatus, error)

	// CancelWorkflow cancels a running workflow.
	CancelWorkflow(ctx context.Context, workflowID string) error
}

type ElicitationConfig struct {
	// Message is the prompt message shown to the user.
	Message string

	// Schema is the JSON Schema for the requested data.
	// Per MCP spec, must be a flat object with primitive properties.
	Schema map[string]any

	// Timeout is how long to wait for user response.
	// Default: 5 minutes.
	Timeout time.Duration

	// OnDecline defines what to do if user declines.
	OnDecline *ElicitationHandler

	// OnCancel defines what to do if user cancels.
	OnCancel *ElicitationHandler
}

type ElicitationHandler struct {
	// Action defines what to do.
	// Options: "skip_remaining", "abort", "continue"
	Action string
}

type ElicitationProtocolHandler interface {
	// SendElicitation sends an elicitation request to the client.
	SendElicitation(ctx context.Context, workflowID string, stepID string, config *ElicitationConfig) error

	// ReceiveElicitationResponse waits for and returns the user's response.
	// Blocks until response is received or timeout occurs.
	ReceiveElicitationResponse(ctx context.Context, workflowID string, stepID string) (*ElicitationResponse, error)
}

type ElicitationResponse struct {
	// Action is what the user did: "accept", "decline", "cancel"
	Action string

	// Content contains the user-provided data (for accept action).
	Content map[string]any

	// ReceivedAt is when the response was received.
	ReceivedAt time.Time
}

type ErrorHandler struct {
	// Action defines what to do when the step fails.
	// Options: "abort", "continue", "retry"
	Action string

	// RetryCount is the number of retry attempts (for retry action).
	RetryCount int

	// RetryDelay is the initial delay between retries.
	// Uses exponential backoff: delay * 2^attempt
	RetryDelay time.Duration

	// ContinueOnError indicates whether to continue workflow on error.
	ContinueOnError bool
}

type PendingElicitation struct {
	// StepID is the elicitation step ID.
	StepID string

	// Message is the elicitation message.
	Message string

	// Schema is the requested data schema.
	Schema map[string]any

	// ExpiresAt is when the elicitation times out.
	ExpiresAt time.Time
}

type StepResult struct {
	// StepID identifies the step.
	StepID string

	// Status is the step status.
	Status StepStatusType

	// Output contains the step output data.
	Output map[string]any

	// Error contains error information if the step failed.
	Error error

	// StartTime is when the step started.
	StartTime time.Time

	// EndTime is when the step completed.
	EndTime time.Time

	// Duration is the step execution time.
	Duration time.Duration

	// RetryCount is the number of retries performed.
	RetryCount int
}

type StepStatusType string

type StepType string

type TemplateExpander interface {
	// Expand evaluates templates in the given data using the workflow context.
	Expand(ctx context.Context, data map[string]any, workflowCtx *WorkflowContext) (map[string]any, error)

	// EvaluateCondition evaluates a condition template to a boolean.
	EvaluateCondition(ctx context.Context, condition string, workflowCtx *WorkflowContext) (bool, error)
}

type ValidationError struct {
	// Field is the field that failed validation.
	Field string

	// Message is the error message.
	Message string

	// Cause is the underlying error.
	Cause error
}

type WorkflowContext struct {
	// WorkflowID is the unique workflow execution ID.
	WorkflowID string

	// Params are the input parameters.
	Params map[string]any

	// Steps contains the results of completed steps.
	Steps map[string]*StepResult

	// Variables stores workflow-scoped variables.
	Variables map[string]any
}

type WorkflowDefinition struct {
	// Name is the workflow name (must be unique).
	Name string

	// Description describes what the workflow does.
	Description string

	// Parameters defines the input parameter schema (JSON Schema).
	Parameters map[string]any

	// Steps are the workflow steps to execute.
	Steps []WorkflowStep

	// Timeout is the maximum execution time for the workflow.
	// Default: 30 minutes.
	Timeout time.Duration

	// FailureMode defines how to handle step failures.
	// Options: "abort" (default), "continue", "best_effort"
	FailureMode string

	// Metadata stores additional workflow information.
	Metadata map[string]string
}

type WorkflowError struct {
	// WorkflowID is the workflow execution ID.
	WorkflowID string

	// StepID is the step that caused the error (if applicable).
	StepID string

	// Message is the error message.
	Message string

	// Cause is the underlying error.
	Cause error
}

type WorkflowResult struct {
	// WorkflowID is the unique identifier for this execution.
	WorkflowID string

	// Status is the final workflow status.
	Status WorkflowStatusType

	// Output contains the workflow output data.
	// Typically the output of the last step.
	Output map[string]any

	// Steps contains the results of each step.
	Steps map[string]*StepResult

	// Error contains error information if the workflow failed.
	Error error

	// StartTime is when the workflow started.
	StartTime time.Time

	// EndTime is when the workflow completed.
	EndTime time.Time

	// Duration is the total execution time.
	Duration time.Duration

	// Metadata stores additional result information.
	Metadata map[string]string
}

type WorkflowStateStore interface {
	// SaveState persists workflow state.
	SaveState(ctx context.Context, workflowID string, state *WorkflowStatus) error

	// LoadState retrieves workflow state.
	LoadState(ctx context.Context, workflowID string) (*WorkflowStatus, error)

	// DeleteState removes workflow state.
	DeleteState(ctx context.Context, workflowID string) error

	// ListActiveWorkflows returns all active workflow IDs.
	ListActiveWorkflows(ctx context.Context) ([]string, error)
}

type WorkflowStatus struct {
	// WorkflowID identifies the workflow.
	WorkflowID string

	// Status is the current workflow status.
	Status WorkflowStatusType

	// CurrentStep is the currently executing step (if running).
	CurrentStep string

	// CompletedSteps are the steps that have completed.
	CompletedSteps []string

	// PendingElicitations are elicitations waiting for user response.
	PendingElicitations []*PendingElicitation

	// StartTime is when the workflow started.
	StartTime time.Time

	// LastUpdateTime is when the status was last updated.
	LastUpdateTime time.Time
}

type WorkflowStatusType string

type WorkflowStep struct {
	// ID uniquely identifies this step within the workflow.
	ID string

	// Type is the step type: "tool", "elicitation", "conditional"
	Type StepType

	// Tool is the tool to call (for tool steps).
	// Format: "toolname" or "backend.toolname"
	Tool string

	// Arguments are the tool arguments with template expansion support.
	// Templates use Go text/template syntax with access to:
	//   - {{.params.name}}: Input parameters
	//   - {{.steps.stepid.output}}: Previous step outputs
	//   - {{.steps.stepid.content}}: Elicitation response data
	//   - {{.steps.stepid.action}}: Elicitation action (accept/decline/cancel)
	Arguments map[string]any

	// Condition is an optional condition for conditional execution.
	// If specified and evaluates to false, the step is skipped.
	// Uses template syntax, must evaluate to boolean.
	Condition string

	// DependsOn lists step IDs that must complete before this step.
	// Enables DAG-based parallel execution.
	DependsOn []string

	// OnError defines error handling for this step.
	OnError *ErrorHandler

	// Elicitation defines elicitation parameters (for elicitation steps).
	Elicitation *ElicitationConfig

	// Timeout is the maximum execution time for this step.
	Timeout time.Duration

	// Metadata stores additional step information.
	Metadata map[string]string
}