plugins

type AdminContext struct {
	Platform Platform
	State    PluginState
}

type AdminSpec struct {
	PluginID      string
	DefaultConfig func() map[string]any
	Schema        map[string]any
	Validate      func(raw map[string]any) error
	Redact        func(raw map[string]any) map[string]any
	Status        func(ctx context.Context, build AdminContext) (any, error)
}

type AfterToolResult struct {
	Result  *string `json:"result,omitempty"`
	IsError *bool   `json:"is_error,omitempty"`
}

type AfterToolResultContext struct {
	Platform   Platform
	State      PluginState
	SessionID  string
	Channel    string
	UserID     int64
	AgentID    string
	ToolName   string
	ToolCallID string
	Arguments  map[string]any
	Result     string
	IsError    bool
	Duration   time.Duration
}

type AfterToolResultSpec struct {
	PluginID string
	Name     string
	Order    int
	Required bool
	Run      func(ctx context.Context, build AfterToolResultContext) (AfterToolResult, error)
}

type Auth interface {
	GetUser(ctx context.Context, userID int64) (UserInfo, error)
	ListUserIdentities(ctx context.Context, userID int64) ([]LinkedIdentity, error)
	GetIdentityByPlatform(ctx context.Context, platform, externalID string) (LinkedIdentity, error)
}

type BeforeRunContext struct {
	Platform     Platform
	State        PluginState
	SessionID    string
	Channel      string
	UserID       int64
	AgentID      string
	Model        string
	MessageText  string
	SystemPrompt string
	History      []ai.Message
}

type BeforeRunResult struct {
	SystemPrompt string `json:"system_prompt,omitempty"`
}

type BeforeRunSpec struct {
	PluginID string
	Name     string
	Order    int
	Required bool
	Run      func(ctx context.Context, build BeforeRunContext) (BeforeRunResult, error)
}

type BeforeToolCallContext struct {
	Platform   Platform
	State      PluginState
	SessionID  string
	Channel    string
	UserID     int64
	AgentID    string
	ToolName   string
	ToolCallID string
	Arguments  map[string]any
}

type BeforeToolCallResult struct {
	Arguments    map[string]any `json:"arguments,omitempty"`
	Block        bool           `json:"block,omitempty"`
	BlockMessage string         `json:"block_message,omitempty"`
}

type BeforeToolCallSpec struct {
	PluginID string
	Name     string
	Order    int
	Required bool
	Run      func(ctx context.Context, build BeforeToolCallContext) (BeforeToolCallResult, error)
}

type BinaryAsset struct {
	File      string // may contain {version} and {tag} placeholders
	RawBinary bool   // true if the asset IS the binary (no archive to extract)
}

type BinarySpec struct {
	PluginID       string
	Name           string                 // binary name on disk, e.g. "tap"
	Repo           string                 // "owner/repo" on GitHub
	Version        string                 // pinned version string, or "" for latest
	AssetTemplates map[string]BinaryAsset // platform key e.g. "darwin-arm64"
	PostInstall    func(ctx context.Context, binPath, annaHome string, logger *slog.Logger)
}

type BotRuntimeDeps[T any] struct {
	Parent               context.Context
	Handler              pkgchannel.Handler
	Notifier             ChannelRegistry
	Log                  *slog.Logger
	Now                  func() time.Time
	Platform             string
	DecodeConfig         func(map[string]any) (T, error)
	ConfigureConfig      func(T, PluginState) T
	ValidateConfig       func(T) string
	NotificationsEnabled func(T) bool
	NewChannel           func(T, pkgchannel.Handler) (pkgchannel.Channel, error)
	Snapshot             func(time.Time, RuntimeState, string, T) RuntimeStatus
}

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

type ChannelContext struct {
	Platform Platform
	State    PluginState
	Handler  channel.Handler
}

type ChannelPlatform interface {
	ParentContext() context.Context
	Handler() pkgchannel.Handler
	Notifications() ChannelRegistry
}

type ChannelRegistry interface {
	Register(pkgchannel.Channel)
	Unregister(name string)
}

type ChannelSpec struct {
	PluginID              string
	Name                  string
	SupportsNotifications bool
	Configured            func(raw map[string]any) bool
	NotificationsEnabled  func(raw map[string]any) bool
	Build                 func(ctx ChannelContext) (channel.Channel, error)
}

type ConfigStore interface {
	Get(ctx context.Context) (PluginState, error)
	Set(ctx context.Context, config map[string]any) error
}

type HookContext struct {
	Platform    Platform
	State       PluginState
	ToolsBinDir string
}

type HookSpec struct {
	PluginID string
	Name     string
	Build    func(ctx HookContext) (hooks.HookPlugin, error)
}

type Host interface {
	SetInfo(PluginInfo)
	AddAdmin(AdminSpec)
	AddTool(ToolSpec)
	AddProvider(ProviderSpec)
	AddChannel(ChannelSpec)
	AddHook(HookSpec)
	AddMemory(MemorySpec)
	AddRuntime(RuntimeSpec)
	AddPromptInventory(PromptInventorySpec)
	AddSystemPrompt(SystemPromptSpec)
	AddBeforeRun(BeforeRunSpec)
	AddBeforeToolCall(BeforeToolCallSpec)
	AddAfterToolResult(AfterToolResultSpec)
	AddBinary(BinarySpec)
}

type LinkedIdentity struct {
	ID         int64
	UserID     int64
	Platform   string
	ExternalID string
	Name       string
	LinkedAt   time.Time
}

type ManagedChannelPluginRegistration struct {
	PluginID             string
	RuntimeName          string
	Meta                 PluginInfo
	Info                 PluginInfo
	DefaultConfig        func() map[string]any
	Schema               map[string]any
	Validate             func(raw map[string]any) error
	Redact               func(raw map[string]any) map[string]any
	Configured           func(raw map[string]any) bool
	NotificationsEnabled func(raw map[string]any) bool
	RuntimeFactory       func(Platform) (Runtime, error)
}

type MemoryContext struct {
	Platform     Platform
	State        PluginState
	DB           *sql.DB
	AnnaHome     string
	SummarizerFn func(context.Context, string) (string, error)
}

type MemorySpec struct {
	PluginID string
	Name     string
	Build    func(ctx context.Context, build MemoryContext) (memory.Provider, error)
}

type Notifier interface {
	Notify(ctx context.Context, n pkgchannel.Notification) error
	NotifyUser(ctx context.Context, userID int64, n pkgchannel.Notification) error
}

type Platform interface {
	Logger() *slog.Logger
	ConfigStore() ConfigStore
	StateStore() StateStore
	Scheduler() Scheduler
	Notifier() Notifier
	Auth() Auth
	RuntimeLookup() RuntimeLookup
	ChannelPlatform() ChannelPlatform
	ReflectPlatform() ReflectPlatform
	SkillStore() SkillStore
}

type Plugin interface {
	Register(host Host)
}

type PluginFunc func(host Host)

type PluginInfo struct {
	ID                    string   `json:"id"`
	Kind                  string   `json:"kind,omitempty"`
	Name                  string   `json:"name,omitempty"`
	DisplayName           string   `json:"display_name,omitempty"`
	Description           string   `json:"description,omitempty"`
	Managed               bool     `json:"managed,omitempty"`
	AdminVisible          bool     `json:"admin_visible,omitempty"`
	HasConfig             bool     `json:"has_config,omitempty"`
	HasStatus             bool     `json:"has_status,omitempty"`
	Capabilities          []string `json:"capabilities,omitempty"`
	SupportsNotifications bool     `json:"supports_notifications,omitempty"`
}

type PluginState struct {
	ID      string         `json:"id"`
	Enabled bool           `json:"enabled"`
	Config  map[string]any `json:"config,omitempty"`
}

type PromptInventoryContext struct {
	Platform Platform
	State    PluginState
}

type PromptInventorySpec struct {
	PluginID string
	Name     string
	GetTools func(ctx context.Context, build PromptInventoryContext) ([]PromptToolInfo, error)
}

type PromptToolInfo struct {
	Name        string         `json:"name"`
	Description string         `json:"description,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
}

type ProviderContext struct {
	Platform Platform
	State    PluginState
}

type ProviderMeta struct {
	Name       string
	DefaultURL string
}

type ProviderSpec struct {
	PluginID string
	Name     string
	Meta     ProviderMeta
	Build    func(ctx ProviderContext) (providers.ProviderAdapter, error)
}

type ReflectAgent struct {
	ID string
}

type ReflectPlatform interface {
	ParentContext() context.Context
	Memory() memory.Provider
	Store() ReflectStore
	Workspace() string
	BuildProviders(api, apiKey, baseURL string) (*providers.Registry, error)
}

type ReflectProviderCreds struct {
	APIKey  string
	BaseURL string
}

type ReflectSnapshot struct {
	AgentID      string
	Provider     string
	Model        string
	ModelStrong  string
	ModelFast    string
	Workspace    string
	APIKey       string
	BaseURL      string
	SystemPrompt string
	Providers    map[string]ReflectProviderCreds
}

type ReflectStore interface {
	ListEnabledAgents(ctx context.Context) ([]ReflectAgent, error)
	Snapshot(ctx context.Context, agentID string) (*ReflectSnapshot, error)
}

type RegisteredPlugin struct {
	Info                  PluginInfo
	Kind                  string
	Name                  string
	SupportsNotifications bool
	HasConfig             bool
	HasStatus             bool
	Capabilities          []string
	State                 PluginState
	Persisted             bool
	PersistedID           string
}

type Runtime interface {
	Apply(ctx context.Context, desired PluginState) error
	Start(ctx context.Context, desired PluginState) error
	Reconcile(ctx context.Context, desired PluginState) error
	Stop(ctx context.Context) error
	Snapshot(ctx context.Context) (RuntimeStatus, error)
	Status(ctx context.Context) (RuntimeStatus, error)
}

type RuntimeContext struct {
	Platform Platform
	State    PluginState
}

type RuntimeHandle interface {
	Snapshot(ctx context.Context) (RuntimeStatus, error)
	Status(ctx context.Context) (RuntimeStatus, error)
}

type RuntimeLookup interface {
	Get(pluginID string, runtimeName string) (RuntimeHandle, bool)
	Lookup(pluginID string, runtimeName string) (RuntimeHandle, bool)
}

type RuntimeSpec struct {
	PluginID string
	Name     string
	Build    func(ctx RuntimeContext) (Runtime, error)
}

type RuntimeState string

type RuntimeStatus struct {
	State     RuntimeState   `json:"state"`
	Message   string         `json:"message,omitempty"`
	UpdatedAt time.Time      `json:"updated_at"`
	Metadata  map[string]any `json:"metadata,omitempty"`
}

type ScheduledJobRunner interface {
	RunScheduledJob(ctx context.Context, key string, payload map[string]any) error
}

type Scheduler interface {
	ReconcileJobs(ctx context.Context, jobs []SchedulerJobSpec) error
	DeleteJobs(ctx context.Context) error
	DeleteJob(ctx context.Context, key string) error
	ListJobs(ctx context.Context) ([]SchedulerJob, error)
}

type SchedulerJob struct {
	ID          string            `json:"id"`
	PluginID    string            `json:"plugin_id"`
	Key         string            `json:"key"`
	RuntimeName string            `json:"runtime_name"`
	Name        string            `json:"name"`
	Description string            `json:"description,omitempty"`
	Schedule    SchedulerSchedule `json:"schedule"`
	Payload     map[string]any    `json:"payload,omitempty"`
	Enabled     bool              `json:"enabled"`
	CreatedAt   time.Time         `json:"created_at"`
	UpdatedAt   time.Time         `json:"updated_at"`
	LastRunAt   *time.Time        `json:"last_run_at,omitempty"`
	LastError   string            `json:"last_error,omitempty"`
}

type SchedulerJobSpec struct {
	Key         string            `json:"key"`
	RuntimeName string            `json:"runtime_name"`
	Name        string            `json:"name"`
	Description string            `json:"description,omitempty"`
	Schedule    SchedulerSchedule `json:"schedule"`
	Payload     map[string]any    `json:"payload,omitempty"`
	Enabled     bool              `json:"enabled,omitempty"`
}

type SchedulerSchedule struct {
	Cron  string `json:"cron,omitempty"`
	Every string `json:"every,omitempty"`
	At    string `json:"at,omitempty"`
}

type Skill struct {
	ID                     string
	Scope                  string // system | agent | user | project (project is filesystem-only)
	UserID                 int64
	AgentID                string
	Name                   string
	Description            string
	Status                 string // draft | active | deprecated
	DisableModelInvocation bool
	Metadata               json.RawMessage
	CreatedAt              time.Time
	UpdatedAt              time.Time
}

type SkillStore interface {
	// List returns all visible skills for the given context (metadata only, no file content).
	List(ctx context.Context, vc SkillViewContext) ([]Skill, error)

	// Resolve finds the highest-priority visible skill by name.
	// Priority: user > agent > system (project skills are resolved via filesystem).
	Resolve(ctx context.Context, name string, vc SkillViewContext) (*Skill, error)

	// LoadFile fetches a single file by path. Pass SkillMainFile ("SKILL.md") for the body.
	LoadFile(ctx context.Context, skillID, path string) (string, error)

	// Create inserts the skill row and all its files (must include "SKILL.md").
	Create(ctx context.Context, s Skill, files map[string]string) (string, error)

	// Update patches metadata fields. Use UpsertFile to change file content.
	Update(ctx context.Context, id string, patch SkillUpdatePatch) error

	// UpsertFile creates or replaces a single file under a skill.
	UpsertFile(ctx context.Context, skillID, path, content string) error

	DeleteFile(ctx context.Context, skillID, path string) error
	Delete(ctx context.Context, id string) error

	// ExpireDrafts deprecates all draft skills whose created-at timestamp is
	// before the given cutoff.
	ExpireDrafts(ctx context.Context, before time.Time) error
}

type SkillUpdatePatch struct {
	Description            *string
	Status                 *string
	DisableModelInvocation *bool
	Metadata               json.RawMessage // optional; set to overwrite
}

type SkillViewContext struct {
	UserID  int64
	AgentID string
}

type StateScope struct {
	Kind string
	ID   string
}

type StateStore interface {
	Get(ctx context.Context, scope StateScope, key string) (map[string]any, bool, error)
	Set(ctx context.Context, scope StateScope, key string, value map[string]any) error
	Delete(ctx context.Context, scope StateScope, key string) error
}

type SystemPromptContext struct {
	Platform    Platform
	State       PluginState
	AnnaHome    string
	HomeDir     string
	AgentRoot   string
	ProjectRoot string
	UserID      int64
	AgentID     string
	UserRoot    string

	// EnabledBuiltinSkills is the per-agent allowlist of builtin (system-scope)
	// skills that should appear in the prompt catalog. The always-on "anna"
	// skill is visible to every agent regardless of this list.
	EnabledBuiltinSkills []string
}

type SystemPromptSection struct {
	Title   string `json:"title"`
	Content string `json:"content"`
}

type SystemPromptSpec struct {
	PluginID string
	Name     string
	Required bool
	Build    func(ctx context.Context, build SystemPromptContext) (SystemPromptSection, error)
}

type ToolContext struct {
	Platform Platform
	Paths    ToolPaths
	Runtime  sandbox.Session
}

type ToolPaths struct {
	UserRoot    string
	ToolsBinDir string
	AnnaHome    string
	AgentRoot   string
	ProjectRoot string // tool-facing project root for relative path resolution
}

type ToolSpec struct {
	PluginID    string
	Name        string
	Description string
	Required    bool
	Build       func(ctx ToolContext) (tools.Tool, error)
}

type UserInfo struct {
	ID               int64
	Username         string
	Role             string
	IsActive         bool
	DefaultAgentID   string
	NotifyIdentityID *int64
	CreatedAt        time.Time
	UpdatedAt        time.Time
}