host

package
v0.68.2 Latest Latest
Warning

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

 Go to latest Published: Sep 7, 2026 License: AGPL-3.0 Imports: 21 Imported by: 0

Documentation

Overview

Package host is the process-wide plugin platform. Static Go registrations are validated and sealed at startup, after which only the dynamic desired-state surface stays open; a plugin reaches a host port only through a declared RequiredCapability that was checked against an injected backing service.

It also owns StateStore, the pg-backed durable state a plugin sees through its scoped StateStore capability.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultCatalogBundledSkillSpecs 

func DefaultCatalogBundledSkillSpecs() ([]pkgplugins.BundledSkillSpec, error)

DefaultCatalogBundledSkillSpecs loads the default plugin catalog into a throw-away host and returns all registered bundled skill specs, sorted by skill name then plugin ID.

func NewAuthService 

func NewAuthService(store pluginAuthStore) pkgplugins.Auth

func NewScopedStateStore 

func NewScopedStateStore(store StateStoreBackend, pluginID string) pkgplugins.StateStore

NewScopedStateStore wraps a StateStoreBackend as a pkgplugins.StateStore whose calls are namespaced to the given pluginID. Used by gateway wiring for built-in subsystems (e.g. reflect) that need a state store but don't run inside the plugin runtime.

Types

type ChannelPlatform 

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

ChannelPlatform is a mutable host extension bag for managed channel runtimes.

func NewChannelRuntimeServices 

func NewChannelRuntimeServices() *ChannelPlatform

func (*ChannelPlatform) Handler 

func (s *ChannelPlatform) Handler() pkgchannel.Handler

func (*ChannelPlatform) Notifications 

func (s *ChannelPlatform) Notifications() pkgplugins.ChannelRegistry

func (*ChannelPlatform) ParentContext 

func (s *ChannelPlatform) ParentContext() context.Context

func (*ChannelPlatform) Set 

func (s *ChannelPlatform) Set(parent context.Context, handler pkgchannel.Handler, notifications pkgplugins.ChannelRegistry)

type ConfigBackend 

type ConfigBackend interface {
	Get(ctx context.Context, pluginID string) (pkgplugins.PluginState, error)
	Set(ctx context.Context, pluginID string, config map[string]any) error
	SetEnabled(ctx context.Context, pluginID string, enabled bool) error
}

ConfigBackend is the host-owned unscoped plugin config backend.

type Host 

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

func New 

func New(store config.Store, opts ...Option) *Host

func (*Host) AddAdmin 

func (h *Host) AddAdmin(reg pkgplugins.AdminSpec)

func (*Host) AddAfterToolResult 

func (h *Host) AddAfterToolResult(reg pkgplugins.AfterToolResultSpec)

func (*Host) AddBeforeRun 

func (h *Host) AddBeforeRun(reg pkgplugins.BeforeRunSpec)

func (*Host) AddBeforeToolCall 

func (h *Host) AddBeforeToolCall(reg pkgplugins.BeforeToolCallSpec)

func (*Host) AddBundledSkill 

func (h *Host) AddBundledSkill(spec pkgplugins.BundledSkillSpec)

func (*Host) AddChannel 

func (h *Host) AddChannel(reg pkgplugins.ChannelSpec)

func (*Host) AddHook 

func (h *Host) AddHook(reg pkgplugins.HookSpec)

func (*Host) AddPromptInventory 

func (h *Host) AddPromptInventory(reg pkgplugins.PromptInventorySpec)

func (*Host) AddRuntime 

func (h *Host) AddRuntime(reg pkgplugins.RuntimeSpec)

func (*Host) AddSessionEnv 

func (h *Host) AddSessionEnv(spec pkgplugins.SessionEnvSpec)

func (*Host) AddSystemPrompt 

func (h *Host) AddSystemPrompt(reg pkgplugins.SystemPromptSpec)

func (*Host) AddTool 

func (h *Host) AddTool(reg pkgplugins.ToolSpec)

func (*Host) AfterToolResult 

func (h *Host) AfterToolResult(ctx context.Context, build pkgplugins.AfterToolResultContext) (pkgplugins.AfterToolResult, error)

func (*Host) AllBundledSkillSpecs 

func (h *Host) AllBundledSkillSpecs() []pkgplugins.BundledSkillSpec

func (*Host) AllSessionEnvSpecs 

func (h *Host) AllSessionEnvSpecs() []pkgplugins.SessionEnvSpec

func (*Host) ApplyChannel 

func (h *Host) ApplyChannel(ctx context.Context, channel config.Channel) error

func (*Host) ApplyPlugin 

func (h *Host) ApplyPlugin(ctx context.Context, pluginID string) error

func (*Host) Auth 

func (h *Host) Auth() pkgplugins.Auth

Auth returns the injected auth service, if any.

func (*Host) BeforeRun 

func (h *Host) BeforeRun(ctx context.Context, build pkgplugins.BeforeRunContext) (pkgplugins.BeforeRunResult, error)

func (*Host) BeforeToolCall 

func (h *Host) BeforeToolCall(ctx context.Context, build pkgplugins.BeforeToolCallContext) (pkgplugins.BeforeToolCallResult, error)

func (*Host) BuildEnabledHooks 

func (h *Host) BuildEnabledHooks(ctx context.Context, toolsBinDir string) []hooks.HookPlugin

func (*Host) BuildEnabledTools 

func (h *Host) BuildEnabledTools(ctx context.Context, bc pkgplugins.ToolBuildContext) []tools.Tool

func (*Host) BundledSkillSpecs 

func (h *Host) BundledSkillSpecs(pluginID string) []pkgplugins.BundledSkillSpec

func (*Host) ChannelConfigured 

func (h *Host) ChannelConfigured(ctx context.Context, name string) bool

func (*Host) ChannelInstanceConfigured 

func (h *Host) ChannelInstanceConfigured(channel config.Channel) bool

func (*Host) ChannelRuntime 

func (h *Host) ChannelRuntime() pkgplugins.ChannelPlatform

ChannelRuntime returns the injected channel runtime service extension, if any.

func (*Host) Config 

func (h *Host) Config() ConfigBackend

func (*Host) ConfigSchema 

func (h *Host) ConfigSchema(pluginID string) map[string]any

func (*Host) DesiredState 

func (h *Host) DesiredState(ctx context.Context, pluginID string) (pkgplugins.PluginState, error)

func (*Host) EnabledToolSpecs 

func (h *Host) EnabledToolSpecs(ctx context.Context) []pkgplugins.ToolSpec

EnabledToolSpecs returns metadata for plugin tools that are visible in the current server state. It does not build tools or touch runtime sandboxes.

func (*Host) HasConfig 

func (h *Host) HasConfig(pluginID string) bool

func (*Host) HasRuntime 

func (h *Host) HasRuntime(pluginID string) bool

func (*Host) HasStatus 

func (h *Host) HasStatus(pluginID string) bool

func (*Host) IsConfigurable 

func (h *Host) IsConfigurable(pluginID string) bool

IsConfigurable reports whether the plugin has an admin config schema registered. Used by the admin API to reject writes to plugin IDs that no longer exist in code (orphan plugin rows from old installs) or to typo'd IDs, instead of silently accepting them.

func (*Host) ListAdminVisiblePlugins 

func (h *Host) ListAdminVisiblePlugins(ctx context.Context) ([]pkgplugins.RegisteredPlugin, error)

func (*Host) ListChannelChats added in v0.68.0 

func (h *Host) ListChannelChats(ctx context.Context, channelID string, pageSize int, pageToken string) (pkgchannel.JoinedChatPage, error)

ListChannelChats returns the group chats currently joined by a channel bot.

func (*Host) ListChannels 

func (h *Host) ListChannels(ctx context.Context) ([]config.Channel, error)

func (*Host) ListRegisteredPlugins 

func (h *Host) ListRegisteredPlugins() []pkgplugins.PluginInfo

func (*Host) LoadCatalog 

func (h *Host) LoadCatalog(catalog *pkgplugins.Catalog) error

func (*Host) LoadDefaultCatalog 

func (h *Host) LoadDefaultCatalog() error

func (*Host) Logger 

func (h *Host) Logger(pluginID string) *slog.Logger

func (*Host) ManagedPlugins 

func (h *Host) ManagedPlugins() []string

func (*Host) ManifestPluginPrompts 

func (h *Host) ManifestPluginPrompts() []pkgplugins.SystemPromptSection

func (*Host) Notifications 

func (h *Host) Notifications() pkgplugins.Notifier

Notifications returns the injected notification service, if any.

func (*Host) PluginsByKind 

func (h *Host) PluginsByKind(kind string) []string

func (*Host) PromptTools 

func (h *Host) PromptTools(ctx context.Context, pluginID string) ([]pkgplugins.PromptToolInfo, error)

func (*Host) Quiesce 

func (h *Host) Quiesce(ctx context.Context)

Quiesce halts new ingress on managed runtimes (channel pollers) for a graceful drain while preserving already-accepted operations and notifier senders. The runtime table is left intact so a later Stop can fully tear them down.

func (*Host) RedactConfig 

func (h *Host) RedactConfig(pluginID string, raw map[string]any) map[string]any

func (*Host) RegisterManifestPlugins 

func (h *Host) RegisterManifestPlugins(m *manifest.Manifest)

RegisterManifestPlugins registers plugins declared in a manifest. For each enabled plugin:

  • New plugins (not already Go-registered) are fully registered with ID, info, and session envs.
  • Existing plugins (already Go-registered) get manifest session envs registered so the manifest is the single source of truth for env injection. Go code should no longer call AddSessionEnv for manifest-declared env vars.

func (*Host) RegisterPluginID 

func (h *Host) RegisterPluginID(id string)

func (*Host) Runtime 

func (h *Host) Runtime() pkgplugins.RuntimeLookup

func (*Host) Seal 

func (h *Host) Seal() error

Seal validates every static registration and capability binding, then marks the host sealed so no further static composition can occur. Missing capability registrations fail here; duplicate static registrations already fail eagerly at registration time (registerUnique). After Seal, LoadCatalog and the Set* capability binders refuse late changes, while the dynamic desired-state surface (ApplyPlugin/ApplyChannel/SetEnabled/RegisterManifestPlugins/Stop) remains available. Seal is one-shot.

func (*Host) SessionEnvSpecs 

func (h *Host) SessionEnvSpecs(pluginID string) []pkgplugins.SessionEnvSpec

func (*Host) SessionPluginView 

func (h *Host) SessionPluginView(ctx context.Context) (pkgplugins.SessionPluginView, error)

SessionPluginView returns the enabled plugin-owned session env setup used by runner sessions plus the registered/enabled plugin IDs prompt builders may need for visibility-aware output.

func (*Host) SetAuthService 

func (h *Host) SetAuthService(service pkgplugins.Auth)

SetAuthService updates the auth service extension after host construction.

func (*Host) SetChannelRuntimeServices 

func (h *Host) SetChannelRuntimeServices(services pkgplugins.ChannelPlatform)

SetChannelRuntimeServices updates the channel runtime service extension after host construction.

func (*Host) SetEnabled 

func (h *Host) SetEnabled(ctx context.Context, pluginID string, enabled bool) error

func (*Host) SetInfo 

func (h *Host) SetInfo(info pkgplugins.PluginInfo)

func (*Host) SetNotificationService 

func (h *Host) SetNotificationService(service pkgplugins.Notifier)

SetNotificationService updates the notification service extension after host construction.

func (*Host) SetStateStore 

func (h *Host) SetStateStore(store StateStoreBackend)

SetStateStore updates the plugin state backend after host construction.

func (*Host) StateStore 

func (h *Host) StateStore() StateStoreBackend

StateStore returns the injected plugin state backend, if any.

func (*Host) Status 

func (h *Host) Status(ctx context.Context, pluginID string) (any, error)

func (*Host) Stop 

func (h *Host) Stop(ctx context.Context) error

func (*Host) SystemPromptSections 

func (h *Host) SystemPromptSections(ctx context.Context, build pkgplugins.SystemPromptContext) ([]pkgplugins.SystemPromptSection, error)

func (*Host) ValidateConfig 

func (h *Host) ValidateConfig(pluginID string, raw map[string]any) error

func (*Host) ValidateRegistrations 

func (h *Host) ValidateRegistrations() error

type Option 

type Option func(*Host)

func WithAuthService 

func WithAuthService(service pkgplugins.Auth) Option

WithAuthService injects the narrow auth directory available to plugins.

func WithChannelRuntimeServices 

func WithChannelRuntimeServices(services pkgplugins.ChannelPlatform) Option

WithChannelRuntimeServices injects the narrow services used by managed channel runtimes.

func WithNotificationService 

func WithNotificationService(service pkgplugins.Notifier) Option

WithNotificationService injects the narrow notification service available to plugins.

func WithStateStore 

func WithStateStore(store StateStoreBackend) Option

WithStateStore injects the host plugin state backend available to plugins.

type RuntimeHost 

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

RuntimeHost owns the map of managed runtime instances.

func NewRuntimeHost 

func NewRuntimeHost(host *Host) *RuntimeHost

func (*RuntimeHost) ApplyChannel 

func (h *RuntimeHost) ApplyChannel(ctx context.Context, channel config.Channel) error

func (*RuntimeHost) ApplyPlugin 

func (h *RuntimeHost) ApplyPlugin(ctx context.Context, pluginID string) error

func (*RuntimeHost) Get 

func (h *RuntimeHost) Get(_ context.Context, runtimeID string, runtimeName string) (pkgplugins.RuntimeHandle, bool)

Get resolves a managed runtime.

func (*RuntimeHost) ListChannelChats added in v0.68.0 

func (h *RuntimeHost) ListChannelChats(ctx context.Context, channelID string, pageSize int, pageToken string) (pkgchannel.JoinedChatPage, error)

ListChannelChats reads the optional joined-chat capability from a running channel instance. Runtime selection stays in the plugin host so transport code never imports a concrete channel plugin.

func (*RuntimeHost) Lookup 

func (h *RuntimeHost) Lookup(ctx context.Context, runtimeID string, runtimeName string) (pkgplugins.RuntimeHandle, bool)

Lookup is an alias for Get to match the pkgplugins.RuntimeLookup interface.

func (*RuntimeHost) Quiesce 

func (h *RuntimeHost) Quiesce(ctx context.Context)

Quiesce invokes the optional ingress-quiescer on every managed runtime that implements it, without clearing the runtime table: the subsequent Stop still needs the entries to tear them down fully. This is the drain-phase counterpart to Stop — it halts new ingress while preserving accepted work.

func (*RuntimeHost) Snapshot 

func (h *RuntimeHost) Snapshot(ctx context.Context, runtimeID string, runtimeName string) (pkgplugins.RuntimeStatus, error)

func (*RuntimeHost) Stop 

func (h *RuntimeHost) Stop(ctx context.Context) error

Stop tears down every managed runtime permanently. It prevents any later Apply, which keeps a graceful drain from admitting new ingress. Entries are removed before Stop is called so no lock is held while runtime teardown runs.

type StateStore 

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

func NewStateStore 

func NewStateStore(db *pgxpool.Pool) *StateStore

func (*StateStore) Delete 

func (s *StateStore) Delete(ctx context.Context, pluginID string, scope pkgplugins.StateScope, key string) error

func (*StateStore) Get 

func (s *StateStore) Get(ctx context.Context, pluginID string, scope pkgplugins.StateScope, key string) (map[string]any, bool, error)

func (*StateStore) Set 

func (s *StateStore) Set(ctx context.Context, pluginID string, scope pkgplugins.StateScope, key string, value map[string]any) error

type StateStoreBackend 

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

StateStoreBackend is the host-owned unscoped plugin state backend.

Source Files

View all Source files

Directories

Path Synopsis
Package catalogimports registers every plugin included in Stella's default catalog.
 Package catalogimports registers every plugin included in Stella's default catalog.

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.