plugins

package
v0.22.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 6, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package plugins defines the shared plugin-facing contracts for Anna's unified plugin host.

Index

Constants

View Source 
const (
	CapabilityChannel   = "channel"
	CapabilityRuntime   = "runtime"
	CapabilityLifecycle = "lifecycle"
	CapabilityConfig    = "config"
	CapabilityStatus    = "status"
	CapabilityTool      = "tool"
	CapabilityPrompt    = "prompt"
	CapabilityProvider  = "provider"
	CapabilityHook      = "hook"
	CapabilityMemory    = "memory"
)
View Source 
const (
	ReflectModelTierStrong = "strong"
	ReflectModelTierFast   = "fast"
)
View Source 
const (
	StateScopeGlobal  = "global"
	StateScopeUser    = "user"
	StateScopeAgent   = "agent"
	StateScopeSession = "session"
)
View Source 
const SkillMainFile = "SKILL.md"

Variables

This section is empty.

Functions

func Names 

func Names() []string

Names returns all plugin IDs from the process-wide default catalog in sorted order.

func NewBotManagedRuntime 

func NewBotManagedRuntime[T any](deps BotRuntimeDeps[T]) *botManagedRuntime[T]

func Register 

func Register(id string, plugin Plugin)

Register stores a plugin in the process-wide default catalog.

func RegisterManagedChannelPlugin 

func RegisterManagedChannelPlugin(host Host, reg ManagedChannelPluginRegistration)

func ResolveBinary added in v0.16.0 

func ResolveBinary(binDir, name string) string

ResolveBinary returns the path to a named binary, checking binDir first, then $PATH. Returns empty string if not found. Plugins receive binDir via their context (e.g. HookContext.ToolsBinDir).

Types

type AdminContext 

type AdminContext struct {
	Platform Platform
	State    PluginState
}

AdminContext is the narrow build context for plugin admin/status behavior.

type AdminSpec 

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)
}

AdminSpec declares plugin-owned admin behavior: config defaults, schema, validation, redaction, and status.

func (AdminSpec) Defaults 

func (r AdminSpec) Defaults() map[string]any

Defaults returns a defensive copy of the registered default config.

func (AdminSpec) Redacted 

func (r AdminSpec) Redacted(raw map[string]any) map[string]any

Redacted returns a redacted copy of raw config, or a cloned copy when no redactor is set.

func (AdminSpec) SchemaDefinition 

func (r AdminSpec) SchemaDefinition() map[string]any

SchemaDefinition returns a defensive deep copy of the registered config schema.

type AfterToolResult 

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

AfterToolResult is the mutable post-execution output from tool lifecycle plugins.

type AfterToolResultContext 

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
}

AfterToolResultContext is the narrow post-tool lifecycle context exposed to plugins.

type AfterToolResultSpec 

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

AfterToolResultSpec declares a post-tool lifecycle hook owned by a plugin.

type Auth 

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)
}

Auth exposes narrow user and identity lookups without leaking auth internals.

type BeforeRunContext 

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

BeforeRunContext is the narrow per-run lifecycle context exposed to plugins.

type BeforeRunResult 

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

BeforeRunResult is the mutable per-run output from lifecycle plugins.

type BeforeRunSpec 

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

BeforeRunSpec declares a dynamic per-run lifecycle hook owned by a plugin.

type BeforeToolCallContext 

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

BeforeToolCallContext is the narrow per-tool-call lifecycle context exposed to plugins.

type BeforeToolCallResult 

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

BeforeToolCallResult is the mutable pre-execution output from tool lifecycle plugins.

type BeforeToolCallSpec 

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

BeforeToolCallSpec declares a pre-tool lifecycle hook owned by a plugin.

type BotRuntimeDeps 

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 added in v0.16.0 

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

BundledSkillSpec declares a builtin system skill owned by a plugin and the build-time sync function that generates or updates it.

type BundledSkillSyncContext added in v0.16.0 

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

BundledSkillSyncContext is the build-time context for syncing a bundled skill into internal/resources.

type Catalog 

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

Catalog stores plugins by plugin ID.

func NewCatalog 

func NewCatalog() *Catalog

NewCatalog creates an empty plugin catalog.

func (*Catalog) Get 

func (c *Catalog) Get(id string) (Plugin, bool)

Get resolves a plugin by ID.

func (*Catalog) Names 

func (c *Catalog) Names() []string

Names returns all registered plugin IDs in sorted order.

func (*Catalog) Register 

func (c *Catalog) Register(id string, plugin Plugin)

Register stores a plugin by canonical plugin ID. It panics for invalid registrations because plugin init-time registration is a programmer error.

type ChannelContext 

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

ChannelContext is the narrow build context for channel capabilities.

type ChannelPlatform 

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

ChannelPlatform exposes the narrow platform services needed by managed channel runtimes.

type ChannelRegistry 

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

ChannelRegistry exposes channel registration needed by managed channel runtimes.

type ChannelSpec 

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

ChannelSpec declares a channel capability owned by a plugin.

type ConfigStore 

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

ConfigStore exposes plugin-owned config persistence through a narrow interface.

type HookContext 

type HookContext struct {
	Platform    Platform
	State       PluginState
	ToolsBinDir string
}

HookContext is the narrow build context for hook capabilities.

type HookSpec 

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

HookSpec declares a hook capability owned by a plugin.

type Host 

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)
	AddSessionEnv(SessionEnvSpec)
	AddBundledSkill(BundledSkillSpec)
}

Host is the flat registration surface exposed to plugins. Platform services are provided only through capability-specific contexts.

type KnowledgeEntry added in v0.18.0 

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
}

KnowledgeEntry is a fact or context entry derived from the skills table. These entries have DisableModelInvocation=true and never appear in the Skills prompt section. Active entries are injected into the ## Knowledge system prompt section.

type KnowledgeStore added in v0.18.0 

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
}

KnowledgeStore queries knowledge entries (fact/context) from the skills table. Knowledge entries have disable_model_invocation=true and are never exposed via the skills tool. Active entries appear in the ## Knowledge system prompt section.

type KnowledgeType added in v0.18.0 

type KnowledgeType string

KnowledgeType classifies a knowledge entry stored in the skills table. 

const (
	KnowledgeTypeSkill   KnowledgeType = "skill"   // existing behavior
	KnowledgeTypeFact    KnowledgeType = "fact"    // durable project/domain fact
	KnowledgeTypeContext KnowledgeType = "context" // time-bound background info
)

type LinkedIdentity 

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

LinkedIdentity is the host-owned linked identity record exposed to plugins.

type ManagedChannelPluginRegistration 

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(Platform) (Runtime, error)
}

type MemoryContext 

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

MemoryContext is the narrow build context for memory capabilities. DB is a construction-time exception for memory providers, not a general plugin service surface.

type MemorySpec 

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

MemorySpec declares a memory capability owned by a plugin.

type Notifier 

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

Notifier exposes user-visible notification delivery through the host.

type Platform 

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

Platform is the plugin-scoped service surface available during build/runtime work.

type Plugin 

type Plugin interface {
	Register(host Host)
}

Plugin is the ownership unit in the unified plugin host. A plugin may register multiple capabilities against the provided host.

func Get 

func Get(id string) (Plugin, bool)

Get resolves a plugin from the process-wide default catalog.

type PluginFunc 

type PluginFunc func(host Host)

PluginFunc adapts a function to the Plugin interface.

func (PluginFunc) Register 

func (f PluginFunc) Register(host Host)

Register implements Plugin.

type PluginInfo 

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"`
}

PluginInfo is the host discovery metadata registered by a plugin. Capability traits are derived from actual registrations rather than declared here.

func (PluginInfo) Clone 

func (m PluginInfo) Clone() PluginInfo

Clone returns a shallow copy.

type PluginState 

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

PluginState is the canonical plugin-level desired state.

func (PluginState) Clone 

func (s PluginState) Clone() PluginState

Clone returns a shallow copy with an independent config map.

type PromptInventoryContext 

type PromptInventoryContext struct {
	Platform Platform
	State    PluginState
}

PromptInventoryContext is the narrow build context for prompt inventory contributions.

type PromptInventorySpec 

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

PromptInventorySpec declares structured tool inventory contribution.

type PromptToolInfo 

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

PromptToolInfo is a structured tool inventory item contributed to prompt building.

func (PromptToolInfo) Clone 

func (i PromptToolInfo) Clone() PromptToolInfo

Clone returns a shallow copy with independent metadata.

type ProviderContext 

type ProviderContext struct {
	Platform Platform
	State    PluginState
}

ProviderContext is the narrow build context for provider capabilities.

type ProviderMeta 

type ProviderMeta struct {
	Name       string
	DefaultURL string
}

ProviderMeta contains provider display metadata.

type ProviderSpec 

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

ProviderSpec declares a provider capability owned by a plugin.

type ReflectAgent 

type ReflectAgent struct {
	ID string
}

type ReflectPlatform 

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

type ReflectProviderCreds 

type ReflectProviderCreds struct {
	APIKey  string
	BaseURL string
}

type ReflectSnapshot 

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
}

func (*ReflectSnapshot) ResolveModelID 

func (s *ReflectSnapshot) ResolveModelID(tier string) string

func (*ReflectSnapshot) ResolveModelTier 

func (s *ReflectSnapshot) ResolveModelTier(tier string) ai.Model

func (*ReflectSnapshot) ResolveProviderCreds 

func (s *ReflectSnapshot) ResolveProviderCreds(providerID string) ReflectProviderCreds

type ReflectStore 

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

type RegisteredPlugin 

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

RegisteredPlugin is the merged discovery view of registered metadata and persisted state.

func (RegisteredPlugin) Clone 

func (p RegisteredPlugin) Clone() RegisteredPlugin

Clone returns a shallow copy with independent nested maps/slices.

func (RegisteredPlugin) SortedCapabilities 

func (p RegisteredPlugin) SortedCapabilities() []string

SortedCapabilities returns a normalized, sorted copy of the capability list.

type Runtime 

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)
}

Runtime is implemented by plugin-owned long-lived runtime services.

type RuntimeContext 

type RuntimeContext struct {
	Platform Platform
	State    PluginState
}

RuntimeContext is the narrow construction context for runtime capabilities.

type RuntimeHandle 

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

RuntimeHandle exposes status access to a running runtime.

type RuntimeLookup 

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

RuntimeLookup resolves running runtime handles by plugin and runtime capability ID.

type RuntimeSpec 

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

RuntimeSpec declares a managed runtime capability owned by a plugin.

type RuntimeState 

type RuntimeState string

RuntimeState is the shared high-level runtime state used by host orchestration. 

const (
	RuntimeStateUnknown RuntimeState = "unknown"
	RuntimeStateStopped RuntimeState = "stopped"
	RuntimeStateRunning RuntimeState = "running"
	RuntimeStateError   RuntimeState = "error"
)

type RuntimeStatus 

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"`
}

RuntimeStatus is the minimal shared runtime status envelope.

func (RuntimeStatus) Clone 

func (s RuntimeStatus) Clone() RuntimeStatus

Clone returns a shallow copy with independent metadata.

type ScheduledJobRunner 

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

ScheduledJobRunner is implemented by runtimes that can handle plugin-owned scheduled jobs.

type Scheduler 

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)
}

Scheduler exposes plugin-owned scheduled job reconciliation through the host.

type SchedulerJob 

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"`
}

SchedulerJob is the host view of one reconciled plugin-owned scheduled job.

type SchedulerJobSpec 

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"`
}

SchedulerJobSpec is the desired state for one plugin-owned scheduled job.

type SchedulerSchedule 

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

SchedulerSchedule identifies when a plugin-owned job should run.

type SessionEnvSource added in v0.16.0 

type SessionEnvSource string

SessionEnvSource identifies how a session env var is produced. 

const (
	SessionEnvSourceStatic SessionEnvSource = "static"
)

type SessionEnvSpec added in v0.16.0 

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
	OAuthProviderConfigField string // optional plugin config field used to resolve OAuthProviderID dynamically
}

SessionEnvSpec declares one env var contributed to sandbox sessions. Sources are metadata-driven so plugins can declare what they need without depending on runner-owned services such as TokenManager.

type SessionPluginView added in v0.16.0 

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

SessionPluginView is the runner-facing view of enabled plugin-owned session setup plus the plugin visibility state prompt builders may need.

type Skill added in v0.13.0 

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
}

Skill represents a skill row (metadata only, no file content).

type SkillStore added in v0.13.0 

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
}

SkillStore is the persistence interface for skills, available to plugins via Platform. It mirrors internal/skills.Store method-for-method; internal/skills re-exports these types as aliases so both sides remain in sync.

type SkillUpdatePatch added in v0.13.0 

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

SkillUpdatePatch carries optional updates for a skill's metadata fields.

type SkillViewContext added in v0.13.0 

type SkillViewContext struct {
	UserID  int64
	AgentID string
}

SkillViewContext describes who is asking and from where. Empty fields mean no such context (e.g. UserID=0 → only system skills visible).

type StateScope 

type StateScope struct {
	Kind string
	ID   string
}

StateScope identifies the owner of a stored plugin state entry.

func (StateScope) Normalize 

func (s StateScope) Normalize() StateScope

Normalize returns the canonical scope shape used by the host store.

type StateStore 

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
}

StateStore exposes host-owned plugin persistence without leaking DB packages.

type SystemPromptContext 

type SystemPromptContext struct {
	Platform    Platform
	State       PluginState
	AnnaHome    string
	HomeDir     string
	AgentRoot   string
	ProjectRoot string
	UserID      int64
	AgentID     string
	UserRoot    string
	// RegisteredPluginIDs and EnabledPluginIDs describe plugin visibility for
	// prompt builders that need plugin-state-aware output such as skill catalogs.
	RegisteredPluginIDs []string
	EnabledPluginIDs    []string
}

SystemPromptContext is the shared build context for prompt contributions. HomeDir is host-scoped discovery context; UserRoot is the runtime writable root.

type SystemPromptSection 

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

SystemPromptSection is a structured prompt contribution from a plugin.

type SystemPromptSpec 

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

SystemPromptSpec declares prompt contribution owned by a plugin.

type ToolContext 

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

ToolContext is the narrow build context for tool capabilities.

type ToolPaths added in v0.10.1 

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

ToolPaths is the tool-facing session path surface. UserRoot is the writable execution root and process HOME. ProjectRoot is the tool-facing current-project directory; relative paths in project-aware tools resolve against it. AnnaHome and AgentRoot are discovery roots.

type ToolSpec 

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

ToolSpec declares a tool capability owned by a plugin.

type UserInfo 

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

UserInfo is the host-owned user record exposed to plugins.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.