agentx

type Agent interface {
	AgentIdentity
	AgentDetector
	AgentConfig
	AgentExtensions
	AgentSession
}

type AgentConfig interface {
	// UserConfigPath returns the user-level configuration directory (e.g., ~/.claude)
	UserConfigPath(env Environment) (string, error)

	// ProjectConfigPath returns the project-level configuration directory (e.g., .claude/)
	// Returns empty string if the agent doesn't support project-level config
	ProjectConfigPath() string

	// ContextFiles returns the list of context/instruction files this agent supports
	// Examples: CLAUDE.md, AGENTS.md, .cursorrules, .windsurfrules
	ContextFiles() []string

	// SupportsXDGConfig returns true if the agent stores user config in XDG-compliant
	// locations (~/.config/app/) rather than home directory dotfiles (~/.app/).
	// XDG Base Directory Specification is the preferred standard for config locations.
	// See: https://specifications.freedesktop.org/basedir-spec/latest/
	SupportsXDGConfig() bool
}

type AgentDetector interface {
	// Detect checks if this agent is currently running
	Detect(ctx context.Context, env Environment) (bool, error)

	// IsInstalled checks if this agent is installed on the system.
	// Detection methods vary by agent: binary in PATH, config directory exists,
	// application bundle present (macOS), etc.
	IsInstalled(ctx context.Context, env Environment) (bool, error)

	// DetectVersion attempts to determine the installed version of this agent.
	// Returns empty string if version cannot be determined (best-effort).
	// Strategies vary by agent: CLI --version, reading package.json, etc.
	DetectVersion(ctx context.Context, env Environment) string
}

type AgentExtensions interface {
	// Capabilities returns what features this agent supports
	Capabilities() Capabilities

	// HookManager returns the hook manager for this agent, or nil if hooks not supported
	HookManager() HookManager

	// CommandManager returns the command manager for this agent, or nil if custom commands not supported
	CommandManager() CommandManager
}

type AgentIdentity interface {
	// Type returns the agent type slug
	Type() AgentType

	// Name returns the human-readable agent name
	Name() string

	// URL returns the official project URL (typically GitHub repo)
	URL() string

	// Role returns whether this is a coding agent or an orchestrator
	Role() AgentRole
}

type AgentRole string

type AgentSession interface {
	// SupportsSession returns true if this agent has a native session/thread
	// concept. True means the agent CAN provide a session ID, even if one
	// isn't available right now (e.g., agent not running, env var not set).
	SupportsSession() bool

	// SessionID returns the agent's native session identifier from the
	// environment. Returns empty string if not currently available.
	// For hook-based agents without a dedicated env var, this returns ""
	// and the caller should use HookInput.SessionID instead.
	SessionID(env Environment) string
}

type AgentType string

type Capabilities struct {
	// Hooks indicates the agent supports hook installation
	Hooks bool

	// MCPServers indicates the agent supports MCP server configuration
	MCPServers bool

	// SystemPrompt indicates the agent supports custom system instructions
	SystemPrompt bool

	// ProjectContext indicates the agent reads project context files (CLAUDE.md, etc.)
	ProjectContext bool

	// CustomCommands indicates the agent supports custom slash commands
	CustomCommands bool

	// MinVersion is the minimum agent version required for full feature support (future)
	MinVersion string
}

type CommandFile struct {
	// Name is the filename (e.g., "ox-status.md")
	Name string

	// Content is the file content (without stamp; stamp is added on write)
	Content []byte

	// Version is the version that ships this command.
	// Used as a downgrade guard: an older binary won't overwrite commands
	// installed by a newer binary.
	Version string
}

type CommandManager interface {
	// Install writes command files to the agent's command directory.
	// When overwrite is false, existing files are skipped entirely (safe for init).
	// When overwrite is true, existing files are replaced only if content differs (safe for doctor).
	// Returns the list of filenames that were written.
	Install(ctx context.Context, projectRoot string, commands []CommandFile, overwrite bool) ([]string, error)

	// Uninstall removes command files matching the prefix from the command directory.
	// Returns the list of filenames that were removed.
	Uninstall(ctx context.Context, projectRoot string, prefix string) ([]string, error)

	// Validate checks which expected files are missing or stale in the command directory.
	// Returns missing filenames and stale filenames (content differs from expected).
	Validate(ctx context.Context, projectRoot string, commands []CommandFile) (missing []string, stale []string, err error)

	// CommandDir returns the path to the command directory for a project.
	CommandDir(projectRoot string) string
}

type Detector interface {
	// Detect identifies the active coding agent (RoleAgent), returning nil if none detected.
	// Orchestrators are excluded — use DetectOrchestrator for those.
	Detect(ctx context.Context) (Agent, error)

	// DetectOrchestrator returns the active orchestrator (RoleOrchestrator), or nil.
	// This is independent of Detect() which returns the coding agent.
	DetectOrchestrator(ctx context.Context) (Agent, error)

	// DetectAll returns all detected agents and orchestrators
	DetectAll(ctx context.Context) ([]Agent, error)

	// DetectByType checks if a specific agent type is active
	DetectByType(ctx context.Context, agentType AgentType) (bool, error)
}

type Environment interface {
	// GetEnv retrieves an environment variable value
	GetEnv(key string) string

	// LookupEnv retrieves an environment variable and reports if it exists
	LookupEnv(key string) (string, bool)

	// HomeDir returns the user's home directory
	HomeDir() (string, error)

	// ConfigDir returns the XDG config directory
	ConfigDir() (string, error)

	// DataDir returns the XDG data directory
	DataDir() (string, error)

	// CacheDir returns the XDG cache directory
	CacheDir() (string, error)

	// GOOS returns the operating system name
	GOOS() string

	// LookPath searches for an executable in PATH
	LookPath(name string) (string, error)

	// FileExists checks if a file or directory exists
	FileExists(path string) bool

	// IsDir checks if a path is a directory
	IsDir(path string) bool

	// Exec runs a command and returns its stdout output.
	// Returns error if the command fails or is not found.
	Exec(ctx context.Context, name string, args ...string) ([]byte, error)

	// ReadFile reads a file and returns its contents.
	ReadFile(path string) ([]byte, error)

	// WriteFile writes data to a file, creating it if necessary.
	WriteFile(path string, data []byte, perm os.FileMode) error

	// ReadDir reads a directory and returns its entries.
	ReadDir(path string) ([]os.DirEntry, error)

	// MkdirAll creates a directory and all parents.
	MkdirAll(path string, perm os.FileMode) error

	// Remove removes a file or empty directory.
	Remove(path string) error

	// Stat returns file info.
	Stat(path string) (os.FileInfo, error)
}

type EventHooks map[HookEvent][]HookRule

type EventPhaseMap map[HookEvent]Phase

type HookAction struct {
	// Type is the action type. Currently only "command" is supported.
	Type string `json:"type"`

	// Command is the shell command to execute. Receives tool context via stdin as JSON.
	// Exit code 2 from PreToolUse/PermissionRequest hooks denies the action.
	Command string `json:"command"`
}

type HookConfig struct {
	// SourcePath is the path to hook source files (templates, commands)
	SourcePath string

	// MCPServers are MCP server configurations to add
	MCPServers map[string]MCPServerConfig

	// SystemInstructions are custom instructions for the agent
	SystemInstructions string

	// EventHooks are lifecycle event hooks to install (PreToolUse, PostToolUse, etc.)
	// See HookEvent constants for available events.
	EventHooks EventHooks

	// Merge indicates whether to merge with existing config (true) or replace (false)
	Merge bool
}

type HookEvent string

type HookInput struct {
	SessionID     string          `json:"session_id"`
	HookEventName string          `json:"hook_event_name"`
	Source        string          `json:"source,omitempty"`  // session start/end source (startup, resume, clear, compact)
	Trigger       string          `json:"trigger,omitempty"` // compact trigger (manual, auto)
	ToolName      string          `json:"tool_name,omitempty"`
	ToolInput     json.RawMessage `json:"tool_input,omitempty"`
	ToolResponse  json.RawMessage `json:"tool_response,omitempty"`
	ToolError     string          `json:"error,omitempty"`

	// RawBytes is the original stdin payload, preserved for faithful passthrough
	// to subprocesses. Not serialized to JSON — used internally only.
	RawBytes []byte `json:"-"`
}

type HookManager interface {
	// Install installs hooks for the agent
	Install(ctx context.Context, config HookConfig) error

	// Uninstall removes installed hooks
	Uninstall(ctx context.Context) error

	// IsInstalled checks if hooks are installed
	IsInstalled(ctx context.Context) (bool, error)

	// Validate validates the current hook configuration
	Validate(ctx context.Context) error
}

type HookRule struct {
	// Matcher is a tool name pattern (e.g., "Bash", "Edit|Write", "*" for all).
	// Only applies to PreToolUse, PostToolUse, and PermissionRequest events.
	Matcher string `json:"matcher,omitempty"`

	// Hooks are the actions to execute when this rule matches.
	Hooks []HookAction `json:"hooks"`
}

type HookSupportEntry struct {
	AgentType AgentType
	AgentName string
	Phases    map[Phase][]HookEvent // phase -> native event names (may have multiple)
}

type LifecycleEventMapper interface {
	// EventPhases returns the mapping from this agent's native events to canonical phases.
	EventPhases() EventPhaseMap

	// AgentENVAliases returns the AGENT_ENV values that identify this agent in hook commands.
	// The first value is the canonical/preferred alias used in hook installation.
	// Example: Claude Code returns ["claude-code", "claudecode", "claude"].
	AgentENVAliases() []string
}

type MCPServerConfig struct {
	Command string            `json:"command"`
	Args    []string          `json:"args,omitempty"`
	Env     map[string]string `json:"env,omitempty"`
}

type MockEnvironment struct {
	EnvVars       map[string]string
	Home          string
	Config        string
	Data          string
	Cache         string
	OS            string
	HomeError     error
	ExecOutputs   map[string][]byte        // keyed by command name
	ExecErrors    map[string]error         // keyed by command name
	Files         map[string][]byte        // keyed by file path
	PathBinaries  map[string]string        // keyed by binary name -> path
	ExistingFiles map[string]bool          // keyed by path
	ExistingDirs  map[string]bool          // keyed by path
	WrittenFiles  map[string][]byte        // tracks WriteFile calls
	CreatedDirs   map[string]bool          // tracks MkdirAll calls
	RemovedPaths  map[string]bool          // tracks Remove calls
	WriteErrors   map[string]error         // inject write errors by path
	RemoveErrors  map[string]error         // inject remove errors by path
	DirEntries    map[string][]os.DirEntry // mock ReadDir results
	StatErrors    map[string]error         // inject stat errors by path
}

type Phase string

type Registry interface {
	// Register adds an agent to the registry
	Register(agent Agent) error

	// Get retrieves an agent by type
	Get(agentType AgentType) (Agent, bool)

	// List returns all registered agents
	List() []Agent

	// Detector returns a detector for registered agents
	Detector() Detector

	// BuildEventPhaseMap builds alias -> event phase map for all LifecycleEventMapper agents.
	BuildEventPhaseMap() map[string]EventPhaseMap

	// ResolveAgentENV resolves an AGENT_ENV alias to an AgentType.
	ResolveAgentENV(agentEnv string) AgentType

	// HookSupportMatrix returns hook support entries for all LifecycleEventMapper agents.
	HookSupportMatrix() []HookSupportEntry
}

type SessionOrigin string

type SystemEnvironment struct{}