plugins

type AgentDef struct {
	// ID is the agent identifier (unique within the plugin).
	ID string `yaml:"id" json:"id"`

	// Name is the human-readable agent name.
	Name string `yaml:"name" json:"name"`

	// Description explains the agent's purpose.
	Description string `yaml:"description" json:"description,omitempty"`

	// Instructions is inline system prompt text or a path to a .md file
	// (relative to plugin directory).
	Instructions string `yaml:"instructions" json:"instructions"`

	// Model overrides the LLM model for this agent (empty = use plugin/core default).
	Model string `yaml:"model" json:"model,omitempty"`

	// Triggers are keywords that activate this agent (matched against message content).
	Triggers []string `yaml:"triggers" json:"triggers,omitempty"`

	// Tools defines the tool allow/deny profile for this agent.
	Tools AgentToolProfile `yaml:"tools" json:"tools,omitzero"`

	// MaxTurns limits the agent loop turns (0 = unlimited).
	MaxTurns int `yaml:"max_turns" json:"max_turns,omitempty"`

	// TimeoutSec is the max execution time in seconds (0 = default).
	TimeoutSec int `yaml:"timeout_sec" json:"timeout_sec,omitempty"`

	// SessionMode controls session isolation ("isolated" or "shared").
	SessionMode string `yaml:"session_mode" json:"session_mode,omitempty"`

	// Escalation configures when/how the agent escalates to the main agent.
	Escalation *EscalationConfig `yaml:"escalation" json:"escalation,omitempty"`

	// Channels limits which channels this agent can be triggered from.
	Channels []string `yaml:"channels" json:"channels,omitempty"`
}

type AgentRegistrar interface {
	AddProfile(p any)
}

type AgentToolProfile struct {
	// Allow lists tools the agent can use (empty = all available).
	Allow []string `yaml:"allow" json:"allow,omitempty"`

	// Deny lists tools the agent cannot use.
	Deny []string `yaml:"deny" json:"deny,omitempty"`
}

type ChannelDef struct {
	// Name is the channel name.
	Name string `yaml:"name" json:"name"`

	// Handler is a Go symbol name for the channel implementation.
	Handler string `yaml:"handler" json:"handler"`
}

type ChannelRegistrar interface {
	Register(ch any) error
}

type Config = PluginsConfig

type EscalationConfig struct {
	// Enabled turns escalation on/off.
	Enabled bool `yaml:"enabled" json:"enabled"`

	// Keywords are phrases that trigger automatic escalation.
	Keywords []string `yaml:"keywords" json:"keywords,omitempty"`

	// MaxTurns triggers escalation after this many turns without resolution.
	MaxTurns int `yaml:"max_turns" json:"max_turns,omitempty"`

	// OnFailure controls behavior on escalation failure ("retry", "drop").
	OnFailure string `yaml:"on_failure" json:"on_failure,omitempty"`

	// ExplicitOnly when true, only escalates via explicit escalate_to_main tool call.
	ExplicitOnly bool `yaml:"explicit_only" json:"explicit_only,omitempty"`
}

type FollowupEnqueuer interface {
	Enqueue(sessionID, content, channel, chatID string)
}

type HookDef struct {
	// Name is the hook identifier.
	Name string `yaml:"name" json:"name"`

	// Description explains the hook's purpose.
	Description string `yaml:"description" json:"description,omitempty"`

	// Events lists the events this hook listens to.
	Events []string `yaml:"events" json:"events"`

	// Priority controls execution order (lower = earlier, default: 100).
	Priority int `yaml:"priority" json:"priority,omitempty"`

	// Handler is a Go symbol name for native hook handlers.
	Handler string `yaml:"handler" json:"handler,omitempty"`

	// Script is inline bash script for script-based hook handlers.
	Script string `yaml:"script" json:"script,omitempty"`
}

type HookRegistrar interface {
	RegisterPluginHook(pluginID string, events []string, priority int, handler func(event string, data map[string]any)) error
}

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

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

type Plugin interface {
	Name() string
	Version() string
	Init(ctx context.Context, config map[string]any) error
	Shutdown() error
}

type PluginAgentSummary struct {
	PluginID    string
	AgentID     string
	Name        string
	Description string
	Triggers    []string
}

type PluginConfigField struct {
	// Key is the configuration key (used in resolved config map).
	Key string `yaml:"key" json:"key"`

	// Name is the human-readable field name.
	Name string `yaml:"name" json:"name"`

	// Description explains the field's purpose.
	Description string `yaml:"description" json:"description,omitempty"`

	// Type is the field type ("string", "int", "bool", "secret").
	Type string `yaml:"type" json:"type"`

	// Required indicates whether the field must be provided.
	Required bool `yaml:"required" json:"required,omitempty"`

	// Default is the default value if not provided.
	Default any `yaml:"default" json:"default,omitempty"`

	// EnvVar is the environment variable to read the value from.
	EnvVar string `yaml:"env_var" json:"env_var,omitempty"`

	// VaultKey is the vault key to read the value from.
	VaultKey string `yaml:"vault_key" json:"vault_key,omitempty"`
}

type PluginConfigSchema struct {
	// Fields is the list of configuration fields.
	Fields []PluginConfigField `yaml:"fields" json:"fields,omitempty"`
}

type PluginInfo struct {
	ID          string      `json:"id"`
	Name        string      `json:"name"`
	Version     string      `json:"version"`
	Description string      `json:"description"`
	Author      string      `json:"author"`
	State       PluginState `json:"state"`
	Enabled     bool        `json:"enabled"`
	ErrorMsg    string      `json:"error,omitempty"`
	Dir         string      `json:"dir"`

	Tools    []string `json:"tools,omitempty"`
	Hooks    []string `json:"hooks,omitempty"`
	Agents   []string `json:"agents,omitempty"`
	Channels []string `json:"channels,omitempty"`
	Skills   []string `json:"skills,omitempty"`

	// UI configuration for the settings panel.
	UI *PluginUIConfig `json:"ui,omitempty"`

	// ConfigSchema describes the plugin's configurable fields (for form generation).
	ConfigSchema *PluginConfigSchema `json:"config_schema,omitempty"`

	// ConfigValues holds the current resolved config values (secrets redacted).
	ConfigValues map[string]any `json:"config_values,omitempty"`

	LoadedAt  time.Time `json:"loaded_at"`
	StartedAt time.Time `json:"started_at,omitzero"`
}

type PluginInstallResult struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	Version string `json:"version"`
	Source  string `json:"source"`
	Path    string `json:"path"`
	IsNew   bool   `json:"is_new"`
}

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

type PluginInstance struct {
	// Manifest is the parsed plugin.yaml.
	Manifest *PluginManifest

	// Provider is the unified interface for this plugin.
	Provider PluginProvider

	// Dir is the plugin directory path.
	Dir string

	// State is the current lifecycle state.
	State PluginState

	// Enabled indicates whether the plugin is enabled.
	Enabled bool

	// ErrorMsg holds the error message when State == StateError.
	ErrorMsg string

	// Config is the resolved configuration (after merging defaults, env, vault, overrides).
	Config map[string]any

	// RegisteredTools tracks the names of tools registered by this plugin.
	RegisteredTools []string

	// RegisteredHooks tracks the names of hooks registered by this plugin.
	RegisteredHooks []string

	// RegisteredAgents tracks the IDs of agents registered by this plugin.
	RegisteredAgents []string

	// RegisteredChannels tracks the names of channels registered by this plugin.
	RegisteredChannels []string

	// RegisteredSkills tracks the names of skills registered by this plugin.
	RegisteredSkills []string

	// LoadedAt is when the plugin was loaded.
	LoadedAt time.Time

	// StartedAt is when the plugin services were started.
	StartedAt time.Time
	// contains filtered or unexported fields
}

type PluginManifest struct {
	// ID is the unique plugin identifier (used for namespacing).
	ID string `yaml:"id" json:"id"`

	// Name is the human-readable plugin name.
	Name string `yaml:"name" json:"name"`

	// Version is the plugin version (semver recommended).
	Version string `yaml:"version" json:"version"`

	// Description is a short description of the plugin.
	Description string `yaml:"description" json:"description"`

	// Author is the plugin author or organization.
	Author string `yaml:"author" json:"author"`

	// License is the plugin license (e.g. "MIT", "Apache-2.0").
	License string `yaml:"license" json:"license,omitempty"`

	// MinDevclaw is the minimum DevClaw version required.
	MinDevclaw string `yaml:"min_devclaw" json:"min_devclaw,omitempty"`

	// Requires specifies external requirements (binaries, env vars, OS).
	Requires *PluginRequirements `yaml:"requires" json:"requires,omitempty"`

	// Config defines the plugin's configuration schema.
	Config *PluginConfigSchema `yaml:"config" json:"config,omitempty"`

	// Agents defines plugin-provided agent definitions.
	Agents []AgentDef `yaml:"agents" json:"agents,omitempty"`

	// Tools defines plugin-provided tool definitions.
	Tools []ToolDef `yaml:"tools" json:"tools,omitempty"`

	// Hooks defines plugin-provided hook definitions.
	Hooks []HookDef `yaml:"hooks" json:"hooks,omitempty"`

	// Services defines plugin-provided HTTP service endpoints.
	Services []ServiceDef `yaml:"services" json:"services,omitempty"`

	// Channels defines plugin-provided channel implementations.
	Channels []ChannelDef `yaml:"channels" json:"channels,omitempty"`

	// Skills defines plugin-provided skill definitions.
	Skills []SkillDef `yaml:"skills" json:"skills,omitempty"`

	// UI defines the plugin's settings panel layout (optional).
	UI *PluginUIConfig `yaml:"ui" json:"ui,omitempty"`

	// NativeLib is the path to an optional native .so library (relative to plugin dir).
	NativeLib string `yaml:"native_lib" json:"native_lib,omitempty"`
}

type PluginMetadata struct {
	Name        string `json:"name"`
	Version     string `json:"version"`
	Description string `json:"description"`
	Author      string `json:"author"`
	License     string `json:"license,omitempty"`
}

type PluginProvider interface {
	// Identity.
	ID() string
	Metadata() PluginMetadata

	// Configuration schema for UI generation.
	ConfigSchema() *PluginConfigSchema

	// UI configuration for the settings panel (nil = no custom UI).
	UIConfig() *PluginUIConfig

	// Capabilities — what the plugin provides.
	Tools() []ToolDef
	Hooks() []HookDef
	Agents() []AgentDef
	Skills() []SkillDef
	Channels() []ChannelDef
	Services() []ServiceDef

	// Lifecycle.
	Init(ctx context.Context, config map[string]any) error
	Shutdown() error
}

type PluginRequirements struct {
	// Bins lists required binaries that must be in PATH (all required).
	Bins []string `yaml:"bins" json:"bins,omitempty"`

	// AnyBins lists binaries where at least one must be in PATH.
	AnyBins []string `yaml:"any_bins" json:"any_bins,omitempty"`

	// Env lists required environment variables.
	Env []string `yaml:"env" json:"env,omitempty"`

	// OS lists supported operating systems (e.g. "linux", "darwin").
	OS []string `yaml:"os" json:"os,omitempty"`
}

type PluginState string

type PluginUIConfig struct {
	// Icon is a Lucide icon name for the plugin card (e.g. "bot", "globe", "zap").
	Icon string `yaml:"icon" json:"icon,omitempty"`

	// Category groups the plugin in the UI (e.g. "communication", "productivity").
	Category string `yaml:"category" json:"category,omitempty"`

	// Color is a hex accent color for the plugin card (e.g. "#3B82F6").
	Color string `yaml:"color" json:"color,omitempty"`

	// Sections defines the configuration form layout.
	// Each section references config field keys by name.
	Sections []UISection `yaml:"sections" json:"sections,omitempty"`

	// Actions defines quick-action buttons shown in the plugin detail view.
	Actions []UIAction `yaml:"actions" json:"actions,omitempty"`
}

type PluginsConfig struct {
	// Dirs lists directories to scan for plugins (YAML-based).
	Dirs []string `yaml:"dirs"`

	// Dir is the legacy single-directory config (for backward compatibility with .so loader).
	Dir string `yaml:"dir"`

	// Enabled lists plugin IDs to load (empty = load all found).
	Enabled []string `yaml:"enabled"`

	// Disabled lists plugin IDs to skip.
	Disabled []string `yaml:"disabled"`

	// Overrides maps plugin ID to config overrides.
	Overrides map[string]map[string]any `yaml:"overrides"`
}

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

type ServiceDef struct {
	// ID is the service identifier.
	ID string `yaml:"id" json:"id"`

	// Name is the human-readable service name.
	Name string `yaml:"name" json:"name"`

	// Description explains the service's purpose.
	Description string `yaml:"description" json:"description,omitempty"`

	// Handler is a Go symbol name for native service handlers.
	Handler string `yaml:"handler" json:"handler,omitempty"`

	// Path is the HTTP path prefix (e.g. "/webhooks/myplugin").
	Path string `yaml:"path" json:"path,omitempty"`

	// Method is the HTTP method (GET, POST, etc.).
	Method string `yaml:"method" json:"method,omitempty"`
}

type SkillDef struct {
	// Name is the skill name.
	Name string `yaml:"name" json:"name"`

	// Description explains the skill's purpose.
	Description string `yaml:"description" json:"description,omitempty"`

	// SkillMD is the relative path to the SKILL.md file within the plugin directory.
	SkillMD string `yaml:"skill_md" json:"skill_md"`
}

type SkillRegistrar interface {
	Register(name, description, skillMDPath string) error
}

type SubagentSpawner interface {
	SpawnPluginAgent(ctx context.Context, executor any, llmClient any, prompt, task string, params any) (string, error)
}

type ToolDef struct {
	// Name is the tool name (will be namespaced as pluginID_name).
	Name string `yaml:"name" json:"name"`

	// Description explains what the tool does.
	Description string `yaml:"description" json:"description"`

	// Parameters is the JSON Schema for the tool's parameters.
	Parameters map[string]any `yaml:"parameters" json:"parameters,omitempty"`

	// Permission is the required access level ("owner", "admin", "user").
	Permission string `yaml:"permission" json:"permission,omitempty"`

	// Hidden excludes the tool from the LLM tool schema.
	Hidden bool `yaml:"hidden" json:"hidden,omitempty"`

	// Handler is a Go symbol name for native tool handlers (requires NativeLib).
	Handler string `yaml:"handler" json:"handler,omitempty"`

	// Endpoint is the HTTP URL for HTTP-based tool handlers.
	Endpoint string `yaml:"endpoint" json:"endpoint,omitempty"`

	// Method is the HTTP method (GET, POST, etc.) for HTTP-based tools.
	Method string `yaml:"method" json:"method,omitempty"`

	// Headers are additional HTTP headers for HTTP-based tools.
	Headers map[string]string `yaml:"headers" json:"headers,omitempty"`

	// Script is inline bash script for script-based tool handlers.
	Script string `yaml:"script" json:"script,omitempty"`
}

type ToolHandlerFunc func(ctx context.Context, args map[string]any) (any, error)

type ToolRegistrar interface {
	RegisterPluginTool(reg ToolRegistration)
	UnregisterTool(name string) bool
}

type ToolRegistration struct {
	Name        string
	Description string
	Parameters  json.RawMessage
	Hidden      bool
	Permission  string
	Handler     func(ctx context.Context, args map[string]any) (any, error)
}

type TriggerMatch struct {
	PluginID string
	AgentID  string
	Score    float64
}

type UIAction struct {
	// Label is the button text.
	Label string `yaml:"label" json:"label"`

	// Description is shown as a tooltip.
	Description string `yaml:"description" json:"description,omitempty"`

	// Tool is the namespaced tool name to invoke (e.g. "hello-world_greet").
	Tool string `yaml:"tool" json:"tool"`

	// Confirm shows a confirmation dialog before executing.
	Confirm bool `yaml:"confirm" json:"confirm,omitempty"`

	// Icon is a Lucide icon name for the button.
	Icon string `yaml:"icon" json:"icon,omitempty"`
}

type UISection struct {
	// Title is the section heading.
	Title string `yaml:"title" json:"title"`

	// Description is an optional subtitle.
	Description string `yaml:"description" json:"description,omitempty"`

	// Fields references config field keys (from config.fields[].key).
	Fields []string `yaml:"fields" json:"fields"`

	// Collapsible makes the section collapsible in the UI.
	Collapsible bool `yaml:"collapsible" json:"collapsible,omitempty"`
}

type VaultReader interface {
	Get(key string) (string, error)
	Has(key string) bool
}