executor

type Capability string

type Config struct {
	// Default executor to use when none specified
	DefaultExecutor string

	// Claude configuration
	ClaudePath       string   // Path to claude CLI binary
	ClaudeModel      string   // Default Claude model
	ClaudeTools      []string // Allowed tools for Claude
	ClaudePermission string   // Permission mode (bypassPermissions, etc.)

	// Gemini configuration
	GeminiPath  string // Path to gemini CLI binary
	GeminiModel string // Default Gemini model
	GeminiTools []string

	// Codex configuration
	CodexPath  string // Path to codex CLI binary
	CodexModel string // Default Codex model

	// opencode configuration
	OpenCodePath  string // Path to opencode CLI binary
	OpenCodeModel string // Default opencode model (provider/model format)

	// pi configuration
	PiPath  string // Path to pi CLI binary
	PiModel string // Default pi model (provider/model format)

	// Common settings
	TimeoutSeconds int
	WorkspaceDir   string
}

type ContextAwareHandler interface {
	EventHandler
	SetContext(ctx context.Context)
}

type CostModel struct {
	ProviderName    string
	InputTokenCost  float64 // Cost per 1K input tokens
	OutputTokenCost float64 // Cost per 1K output tokens
	CacheReadCost   float64 // Cost per 1K cache read tokens
	CacheWriteCost  float64 // Cost per 1K cache write tokens
	MinimumCharge   float64 // Minimum per-request charge
}

type EnvironmentOptions struct {
	// Task is the task being executed
	Task *Task

	// SessionID is the unique session identifier
	SessionID string

	// Context is used for trace context extraction
	Context context.Context

	// EnableClaudeTelemetry enables Claude Code specific telemetry vars
	EnableClaudeTelemetry bool

	// EnableGeminiTelemetry enables Gemini CLI specific telemetry vars
	EnableGeminiTelemetry bool

	// GCPProject overrides GOOGLE_CLOUD_PROJECT for this subprocess.
	// When empty, falls back to the shell environment value.
	GCPProject string

	// GCPLocation overrides GOOGLE_CLOUD_LOCATION for this subprocess.
	// When empty, falls back to the shell environment value.
	GCPLocation string
}

type EventHandler interface {
	OnTurnStart(turnNum int)
	OnText(text string)
	OnToolUse(toolName string, input string)
	OnToolResult(toolName string, output string)
	OnTurnEnd(turnNum int)
	OnError(err error)
}

type ExecutionMetrics struct {
	NumTurns     int
	InputTokens  int
	OutputTokens int
	CostUSD      float64
	DurationMS   int
	SessionID    string
	Success      bool
}

type Executor interface {
	// Name returns the executor identifier (e.g., "claude", "gemini", "codex")
	Name() string

	// Execute runs a task and returns the result
	Execute(ctx context.Context, task *Task) (*Result, error)

	// ExecuteStreaming runs a task with real-time event callbacks
	ExecuteStreaming(ctx context.Context, task *Task, handler EventHandler) (*Result, error)

	// Capabilities returns the list of features this executor supports
	Capabilities() []Capability

	// CostModel returns pricing information for cost calculations
	CostModel() *CostModel

	// HealthCheck verifies the executor is configured and accessible
	HealthCheck(ctx context.Context) error

	// Close releases any resources held by the executor
	Close() error
}

type ExecutorBuilder func(cfg *Config) (Executor, error)

type ExecutorFactory struct {
	// contains filtered or unexported fields
}

type MetricsHandler interface {
	EventHandler
	OnMetrics(metrics ExecutionMetrics)
}

type NoOpEventHandler struct{}

type PluginsConfig struct {
	Marketplaces []string // Marketplaces to register (e.g., "anthropics/claude-code")
	Install      []string // Plugins to install (e.g., "frontend-design@anthropics-claude-code")
}

type Result struct {
	Success bool   // Overall success
	Output  string // Final text output from agent
	Error   string // Error message if failed

	// Metrics
	DurationMS    int     // Total execution time in milliseconds
	NumTurns      int     // Conversation turns
	ToolCallCount int     // Number of tool invocations (file edits, bash, etc.)
	CostUSD       float64 // Total cost in USD

	// Token usage
	InputTokens              int
	OutputTokens             int
	CacheReadInputTokens     int
	CacheCreationInputTokens int

	// Session info
	SessionID  string // Provider's session identifier
	Transcript string // Full conversation log

	// Artifacts
	FilesCreated  []string // Files created in workspace
	FilesModified []string // Files modified

	// Provider-specific data
	ProviderData map[string]any // Raw provider response data
}

type Task struct {
	ID           string            // Unique task identifier
	ParentTaskID string            // Parent task ID for hierarchy tracking (M-TASK-HIERARCHY)
	Directive    string            // The instruction/prompt
	SystemPrompt string            // Optional system-level context
	Workspace    string            // Working directory (local path)
	Timeout      time.Duration     // Hard ceiling execution timeout
	IdleTimeout  time.Duration     // Kill if no events for this long after first event (0 = use default 3m)
	TTFTTimeout  time.Duration     // Kill if no output before first event (prefill budget; 0 = use default 30s)
	AllowedTools []string          // Tools the agent can use
	Model        string            // Model to use (provider-specific)
	Metadata     map[string]string // Provider-specific options

	// Effort level (Claude Code 2.1.47+: "low", "medium", "high")
	Effort string

	// Plugin directories for Claude Code (M-CLOUD-PLUGIN-SKILLS, v0.9.1)
	// Each entry is a path to a plugin directory containing .claude-plugin/plugin.json.
	// Passed as --plugin-dir flags to Claude CLI.
	PluginDirs []string

	// Plugins specifies third-party plugins to install before execution (M-CLOUD-PLUGIN-SKILLS, v0.9.1).
	// Marketplaces are registered first, then plugins installed from those marketplaces.
	Plugins *PluginsConfig

	// Session continuity (M-TRANSCRIPT)
	Iteration       int    // Iteration number (1 = first run, 2+ = re-run with feedback)
	ResumeSessionID string // Previous session ID to resume (for Iteration > 1)

	// GCP override — when set, overrides GOOGLE_CLOUD_PROJECT/LOCATION env vars
	// for the subprocess. Populated from models.yml gcp_project / gcp_location fields.
	GCPProject  string
	GCPLocation string
}

type TokenUsage struct {
	InputTokens              int
	OutputTokens             int
	CacheReadInputTokens     int
	CacheCreationInputTokens int
}