ports

type AgentProvider interface {
	// Execute invokes the agent with the given prompt and options.
	// Returns AgentResult containing output, parsed response, token usage, and any errors.
	Execute(ctx context.Context, prompt string, options map[string]any) (*workflow.AgentResult, error)

	// ExecuteConversation invokes the agent with conversation history for multi-turn interactions.
	// The state parameter contains the conversation history (turns) to send to the agent.
	// Returns ConversationResult containing the updated conversation state, final output, and token usage.
	ExecuteConversation(ctx context.Context, state *workflow.ConversationState, prompt string, options map[string]any) (*workflow.ConversationResult, error)

	// Name returns the provider identifier (e.g., "claude", "codex", "gemini").
	Name() string

	// Validate checks if the provider is properly configured and available.
	// Returns error if the agent CLI binary is not found or misconfigured.
	Validate() error
}

type AgentRegistry interface {
	// Register adds a provider to the registry.
	// Returns error if a provider with the same name already exists.
	Register(provider AgentProvider) error

	// Get retrieves a provider by name.
	// Returns error if provider is not found.
	Get(name string) (AgentProvider, error)

	// List returns all registered provider names.
	List() []string

	// Has checks if a provider with the given name is registered.
	Has(name string) bool
}

type AuditTrailWriter interface {
	Write(ctx context.Context, event *workflow.AuditEvent) error
	Close() error
}

type CLIExecutor interface {
	// Run executes a binary with given arguments.
	// Returns stdout and stderr as byte slices, plus any execution error.
	//
	// The context allows cancellation and timeout control.
	// If the context is cancelled, the execution should be terminated.
	//
	// Error cases:
	// - Binary not found: error != nil
	// - Non-zero exit code: error != nil (error should contain exit code info)
	// - Context cancelled/timeout: error will be context.Canceled or context.DeadlineExceeded
	Run(ctx context.Context, name string, args ...string) (stdout, stderr []byte, err error)
}

type Command struct {
	Program      string
	Dir          string
	Env          map[string]string
	IsScriptFile bool
	Stdout       io.Writer
	Stderr       io.Writer
}

type CommandExecutor interface {
	Execute(ctx context.Context, cmd *Command) (*CommandResult, error)
}

type CommandResult struct {
	Stdout   string
	Stderr   string
	ExitCode int
}

type ErrorFormatter interface {
	// FormatError converts a StructuredError into a formatted string representation.
	// The format depends on the implementation (JSON, human-readable, etc.).
	//
	// Parameters:
	//   - err: The structured error to format
	//
	// Returns:
	//   - Formatted error string according to the implementation's output mode
	//
	// Example:
	//
	//	// JSON formatter:
	//	// {"error_code":"USER.INPUT.MISSING_FILE","message":"workflow file not found",...}
	//
	//	// Human formatter:
	//	// [USER.INPUT.MISSING_FILE] workflow file not found
	FormatError(err *errors.StructuredError) string
}

type ExpressionEvaluator interface {
	// EvaluateBool evaluates a boolean expression against the provided context.
	// Returns the boolean result of the expression, or an error if evaluation fails.
	// Example: "inputs.count > 5" → true/false
	EvaluateBool(expr string, ctx *interpolation.Context) (bool, error)

	// EvaluateInt evaluates an arithmetic expression against the provided context.
	// Returns the integer result of the expression, or an error if evaluation fails.
	// The result is coerced to int type regardless of the underlying numeric type.
	// Example: "20 / 4" → 5
	EvaluateInt(expr string, ctx *interpolation.Context) (int, error)
}

type ExpressionValidator interface {
	// Compile validates the syntax of an expression string.
	// Returns nil if the expression is syntactically valid, error otherwise.
	// This method does NOT evaluate the expression, only checks if it can be compiled.
	Compile(expression string) error
}

type HistoryStore interface {
	Record(ctx context.Context, record *workflow.ExecutionRecord) error
	List(ctx context.Context, filter *workflow.HistoryFilter) ([]*workflow.ExecutionRecord, error)
	GetStats(ctx context.Context, filter *workflow.HistoryFilter) (*workflow.HistoryStats, error)
	Cleanup(ctx context.Context, olderThan time.Duration) (int, error)
	Close() error
}

type InputCollector interface {
	// PromptForInput prompts the user to provide a value for a single workflow input.
	//
	// Behavior by input type:
	//   - Required inputs: Empty value triggers error and re-prompt
	//   - Optional inputs: Empty value returns input.Default or nil
	//   - Enum inputs: Display numbered list (1-9) for selection
	//   - Validated inputs: Apply workflow.InputValidation constraints, re-prompt on error
	//
	// Type coercion is applied based on input.Type:
	//   - "string": Return value as-is
	//   - "integer": Parse string to int
	//   - "boolean": Parse "true"/"false" to bool
	//
	// Returns:
	//   - Validated input value (typed as any for flexibility)
	//   - Error if user cancels (Ctrl+C, EOF) or validation fails repeatedly
	//
	// Implementation notes:
	//   - Check stdin is terminal before calling (fail if non-interactive)
	//   - Handle io.EOF as cancellation, not panic
	//   - Display validation errors with constraint details
	PromptForInput(ctx context.Context, input *workflow.Input) (any, error)
}

type InteractivePrompt interface {
	StepPresenter
	StatusPresenter
	UserInteraction
}

type Logger interface {
	Debug(msg string, fields ...any)
	Info(msg string, fields ...any)
	Warn(msg string, fields ...any)
	Error(msg string, fields ...any)
	WithContext(ctx map[string]any) Logger
}

type OperationProvider interface {
	// GetOperation returns an operation by name.
	GetOperation(name string) (*pluginmodel.OperationSchema, bool)
	// ListOperations returns all available operations.
	ListOperations() []*pluginmodel.OperationSchema
	// Execute runs a plugin operation.
	Execute(ctx context.Context, name string, inputs map[string]any) (*pluginmodel.OperationResult, error)
}

type ParallelExecutor interface {
	// Execute runs multiple branches concurrently according to the given strategy.
	// It respects the MaxConcurrent limit via semaphore and applies the strategy
	// to determine overall success/failure.
	Execute(
		ctx context.Context,
		wf *workflow.Workflow,
		branches []string,
		config workflow.ParallelConfig,
		execCtx *workflow.ExecutionContext,
		stepExecutor StepExecutor,
	) (*workflow.ParallelResult, error)
}

type Plugin interface {
	// Name returns the unique plugin identifier.
	Name() string
	// Version returns the plugin version.
	Version() string
	// Init initializes the plugin with configuration.
	Init(ctx context.Context, config map[string]any) error
	// Shutdown gracefully stops the plugin.
	Shutdown(ctx context.Context) error
}

type PluginConfig interface {
	// SetEnabled enables or disables a plugin by name.
	SetEnabled(ctx context.Context, name string, enabled bool) error
	// IsEnabled returns whether a plugin is enabled.
	// Default is true: plugins not explicitly disabled are considered enabled.
	// Only plugins whose name appears in the disabled set return false.
	// Unknown plugin names return true (default-enabled contract).
	IsEnabled(name string) bool
	// GetConfig returns the stored configuration for a plugin.
	GetConfig(name string) map[string]any
	// SetConfig stores configuration for a plugin.
	SetConfig(ctx context.Context, name string, config map[string]any) error
}

type PluginLoader interface {
	// DiscoverPlugins scans a directory for plugins and returns their info.
	// Each subdirectory with a plugin.yaml is considered a plugin.
	DiscoverPlugins(ctx context.Context, pluginsDir string) ([]*pluginmodel.PluginInfo, error)
	// LoadPlugin loads a single plugin from a directory path.
	LoadPlugin(ctx context.Context, pluginDir string) (*pluginmodel.PluginInfo, error)
	// ValidatePlugin checks if a discovered plugin is valid and compatible.
	ValidatePlugin(info *pluginmodel.PluginInfo) error
}

type PluginManager interface {
	// Discover finds plugins in the plugins directory.
	Discover(ctx context.Context) ([]*pluginmodel.PluginInfo, error)
	// Load loads a plugin by name.
	Load(ctx context.Context, name string) error
	// Init initializes a loaded plugin.
	Init(ctx context.Context, name string, config map[string]any) error
	// Shutdown stops a running plugin.
	Shutdown(ctx context.Context, name string) error
	// ShutdownAll stops all running plugins.
	ShutdownAll(ctx context.Context) error
	// Get returns plugin info by name.
	Get(name string) (*pluginmodel.PluginInfo, bool)
	// List returns all known plugins.
	List() []*pluginmodel.PluginInfo
}

type PluginRegistry interface {
	// RegisterOperation adds a plugin operation.
	RegisterOperation(op *pluginmodel.OperationSchema) error
	// UnregisterOperation removes a plugin operation.
	UnregisterOperation(name string) error
	// Operations returns all registered operations.
	Operations() []*pluginmodel.OperationSchema
}

type PluginStateStore interface {
	PluginStore
	PluginConfig
}

type PluginStore interface {
	// Save persists all plugin states to storage.
	Save(ctx context.Context) error
	// Load reads plugin states from storage.
	Load(ctx context.Context) error
	// GetState returns the full state for a plugin, or nil if not found.
	GetState(name string) *pluginmodel.PluginState
	// ListDisabled returns names of all explicitly disabled plugins.
	ListDisabled() []string
}

type StateStore interface {
	Save(ctx context.Context, state *workflow.ExecutionContext) error
	Load(ctx context.Context, workflowID string) (*workflow.ExecutionContext, error)
	Delete(ctx context.Context, workflowID string) error
	List(ctx context.Context) ([]string, error)
}

type StatusPresenter interface {
	// ShowAborted displays a message indicating workflow was aborted.
	ShowAborted()

	// ShowSkipped displays a message indicating step was skipped.
	ShowSkipped(stepName string, nextStep string)

	// ShowCompleted displays a message indicating workflow completed.
	ShowCompleted(status workflow.ExecutionStatus)

	// ShowError displays an error message.
	ShowError(err error)
}

type StepExecutor interface {
	// ExecuteStep runs a single step and returns the result.
	// The step is looked up by name from the workflow.
	ExecuteStep(
		ctx context.Context,
		wf *workflow.Workflow,
		stepName string,
		execCtx *workflow.ExecutionContext,
	) (*workflow.BranchResult, error)
}

type StepPresenter interface {
	// ShowHeader displays the interactive mode header with workflow name.
	ShowHeader(workflowName string)

	// ShowStepDetails displays step information before execution.
	ShowStepDetails(info *workflow.InteractiveStepInfo)

	// ShowExecuting displays a message indicating step execution is in progress.
	ShowExecuting(stepName string)

	// ShowStepResult displays the outcome of step execution.
	ShowStepResult(state *workflow.StepState, nextStep string)
}

type TemplateRepository interface {
	GetTemplate(ctx context.Context, name string) (*workflow.Template, error)
	ListTemplates(ctx context.Context) ([]string, error)
	Exists(ctx context.Context, name string) bool
}

type Tokenizer interface {
	// CountTokens returns the number of tokens in the given text.
	// The count may be exact (tiktoken) or approximate (character-based)
	// depending on the implementation.
	CountTokens(text string) (int, error)

	// CountTurnsTokens returns the total token count across multiple conversation turns.
	// This allows optimizations for batch counting in some implementations.
	CountTurnsTokens(turns []string) (int, error)

	// IsEstimate returns true if this tokenizer produces approximate counts.
	// Used to set TokensEstimated flag in conversation results.
	IsEstimate() bool

	// ModelName returns the tokenizer model identifier (e.g., "cl100k_base", "approximation").
	// Used for debugging and logging.
	ModelName() string
}

type UserInteraction interface {
	// PromptAction prompts the user for an action and returns their choice.
	// hasRetry indicates whether the [r]etry option should be available.
	PromptAction(ctx context.Context, hasRetry bool) (workflow.InteractiveAction, error)

	// EditInput prompts the user to edit an input value.
	// Returns the new value and any error from parsing.
	EditInput(ctx context.Context, name string, current any) (any, error)

	// ShowContext displays the current runtime context (inputs, states).
	ShowContext(ctx *workflow.RuntimeContext)
}

type WorkflowRepository interface {
	Load(ctx context.Context, name string) (*workflow.Workflow, error)
	List(ctx context.Context) ([]string, error)
	Exists(ctx context.Context, name string) (bool, error)
}