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     string
	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 string) (UserInfo, error)
	ListUserIdentities(ctx context.Context, userID string) ([]LinkedIdentity, error)
	GetIdentityByPlatform(ctx context.Context, platform, externalID string) (LinkedIdentity, error)
}

type BeforeRunContext struct {
	Platform     Platform
	State        PluginState
	SessionID    string
	Channel      string
	UserID       string
	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     string
	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 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
	NewChannel      func(T, pkgchannel.Handler) (pkgchannel.Channel, error)
	Snapshot        func(time.Time, RuntimeState, string, T) RuntimeStatus
}

type BundledSkillSpec struct {
	PluginID string
	Name     string
	Sync     func(ctx context.Context, build BundledSkillSyncContext) error
}

type BundledSkillSyncContext struct {
	WorkDir string
	GOOS    string
	GOARCH  string
	Params  map[string]string
}

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
	Configured 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)
	AddRuntime(RuntimeSpec)
	AddPromptInventory(PromptInventorySpec)
	AddSystemPrompt(SystemPromptSpec)
	AddBeforeRun(BeforeRunSpec)
	AddBeforeToolCall(BeforeToolCallSpec)
	AddAfterToolResult(AfterToolResultSpec)
	AddSessionEnv(SessionEnvSpec)
	AddBundledSkill(BundledSkillSpec)
}

type KnowledgeEntry struct {
	ID            string
	Name          string
	Description   string
	Content       string // the actual knowledge text (from SKILL.md)
	KnowledgeType KnowledgeType
	Status        string // draft | active | deprecated
	CreatedAt     time.Time
	UpdatedAt     time.Time
}

type KnowledgeStore interface {
	// ListKnowledge returns active knowledge entries. When types is empty, all knowledge
	// types are returned. Pass KnowledgeTypeFact or KnowledgeTypeContext to filter.
	ListKnowledge(ctx context.Context, vc SkillViewContext, types ...KnowledgeType) ([]KnowledgeEntry, error)

	// ExpireKnowledgeDraftsByType deprecates draft knowledge entries of the given type
	// whose created-at timestamp is before the cutoff.
	ExpireKnowledgeDraftsByType(ctx context.Context, knowledgeType KnowledgeType, before time.Time) error
}

type KnowledgeType string

type LinkedIdentity struct {
	ID         string
	UserID     string
	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
	RuntimeFactory func(rc RuntimeContext) (Runtime, error)
}

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

type Platform interface {
	Logger() *slog.Logger
	ConfigStore() ConfigStore
	StateStore() StateStore
	Scheduler() Scheduler
	Notifier() Notifier
	Auth() Auth
	RuntimeLookup() RuntimeLookup
	ChannelPlatform() ChannelPlatform
	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"`
}

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 RegisteredPlugin struct {
	Info         PluginInfo
	Kind         string
	Name         string
	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(ctx context.Context, runtimeID string, runtimeName string) (RuntimeHandle, bool)
	Lookup(ctx context.Context, runtimeID 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 SessionEnvSource string

type SessionEnvSpec struct {
	PluginID        string
	EnvVar          string
	Source          SessionEnvSource
	Value           string // used only when Source == SessionEnvSourceStatic
	Required        bool   // if true, session creation fails when this env cannot be resolved
	OAuthProviderID string // set when source is oauth.*; identifies which provider bundle to load
}

type SessionPluginView struct {
	RegisteredPluginIDs []string
	EnabledPluginIDs    []string
	SessionEnvSpecs     []SessionEnvSpec
}

type Skill struct {
	ID                     string
	Scope                  string // system | agent | user | project (project is filesystem-only)
	UserID                 string
	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)

	// ListByScope returns every skill in exactly one scope/owner bucket,
	// including drafts and disabled skills, for exact management lookups.
	ListByScope(ctx context.Context, scope, userID, agentID string) ([]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)

	// ListFiles returns all file paths for a skill (no content).
	ListFiles(ctx context.Context, skillID 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  string
	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
	StellaHome    string
	HomeDir       string
	AgentRoot     string
	ProjectRoot   string
	UserID        string
	AgentID       string
	UserRoot      string
	WorkspaceRoot string
	// SkillStore is a direct shortcut for callers that have a SkillStore but no Platform.
	// BuildPromptSection uses this when Platform is nil.
	SkillStore SkillStore
	// RegisteredPluginIDs and EnabledPluginIDs describe plugin visibility for
	// prompt builders that need plugin-state-aware output such as skill catalogs.
	RegisteredPluginIDs []string
	EnabledPluginIDs    []string
}

type SystemPromptSection struct {
	Title   string `json:"title"`
	Content string `json:"content"`
	Inline  bool   `json:"inline,omitempty"`
}

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

type ToolBuildContext struct {
	Paths   ToolPaths
	Runtime sandbox.Session
}

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

type ToolPaths struct {
	UserRoot      string
	WorkspaceRoot string
	ToolsBinDir   string
	StellaHome    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               string
	Username         string
	Role             string
	IsActive         bool
	DefaultAgentID   string
	NotifyIdentityID *string
	CreatedAt        time.Time
	UpdatedAt        time.Time
}