Plugin SDK Overview The plugin SDK is the typed contract between plugins and core. This page is the
reference for what to import and what you can register .
Looking for a how-to guide? Import convention Always import from a specific subpath:
import { definePluginEntry } from "fluffbuzz/plugin-sdk/plugin-entry" ; import { defineChannelPluginEntry } from "fluffbuzz/plugin-sdk/core" ; // Deprecated — will be removed in the next major release import { definePluginEntry } from "fluffbuzz/plugin-sdk" ;
Each subpath is a small, self-contained module. This keeps startup fast and
prevents circular dependency issues.
Subpath reference The most commonly used subpaths, grouped by purpose. The full list of 100+
subpaths is in scripts/lib/plugin-sdk-entrypoints.json.
Plugin entry Subpath Key exports plugin-sdk/plugin-entrydefinePluginEntryplugin-sdk/coredefineChannelPluginEntry, createChatChannelPlugin, createChannelPluginBase, defineSetupPluginEntry, buildChannelConfigSchema
Subpath Key exports plugin-sdk/channel-setupcreateOptionalChannelSetupSurfaceplugin-sdk/channel-pairingcreateChannelPairingControllerplugin-sdk/channel-reply-pipelinecreateChannelReplyPipelineplugin-sdk/channel-config-helperscreateHybridChannelConfigAdapterplugin-sdk/channel-config-schemaChannel config schema types plugin-sdk/channel-policyresolveChannelGroupRequireMentionplugin-sdk/channel-lifecyclecreateAccountStatusSinkplugin-sdk/channel-inboundDebounce, mention matching, envelope helpers plugin-sdk/channel-send-resultReply result types plugin-sdk/channel-actionscreateMessageToolButtonsSchema, createMessageToolCardSchemaplugin-sdk/channel-targetsTarget parsing/matching helpers plugin-sdk/channel-contractChannel contract types plugin-sdk/channel-feedbackFeedback/reaction wiring
Subpath Key exports plugin-sdk/provider-authcreateProviderApiKeyAuthMethod, ensureApiKeyFromOptionEnvOrPrompt, upsertAuthProfileplugin-sdk/provider-modelsnormalizeModelCompatplugin-sdk/provider-catalogCatalog type re-exports plugin-sdk/provider-usagefetchClaudeUsage and similarplugin-sdk/provider-streamStream wrapper types plugin-sdk/provider-onboardOnboarding config patch helpers
Auth and security subpaths
Subpath Key exports plugin-sdk/command-authresolveControlCommandGateplugin-sdk/allow-fromformatAllowFromLowercaseplugin-sdk/secret-inputSecret input parsing helpers plugin-sdk/webhook-ingressWebhook request/target helpers
Runtime and storage subpaths
Subpath Key exports plugin-sdk/runtime-storecreatePluginRuntimeStoreplugin-sdk/config-runtimeConfig load/write helpers plugin-sdk/infra-runtimeSystem event/heartbeat helpers plugin-sdk/agent-runtimeAgent dir/identity/workspace helpers plugin-sdk/directory-runtimeConfig-backed directory query/dedup plugin-sdk/keyed-async-queueKeyedAsyncQueue
Capability and testing subpaths
Subpath Key exports plugin-sdk/image-generationImage generation provider types plugin-sdk/media-understandingMedia understanding provider types plugin-sdk/speechSpeech provider types plugin-sdk/testinginstallCommonResolveTargetErrorCases, shouldAckReaction
Registration API The register(api) callback receives an FluffBuzzPluginApi object with these
methods:
Capability registration Method What it registers api.registerProvider(...)Text inference (LLM) api.registerChannel(...)Messaging channel api.registerSpeechProvider(...)Text-to-speech / STT synthesis api.registerMediaUnderstandingProvider(...)Image/audio/video analysis api.registerImageGenerationProvider(...)Image generation api.registerWebSearchProvider(...)Web search
Method What it registers api.registerTool(tool, opts?)Agent tool (required or { optional: true }) api.registerCommand(def)Custom command (bypasses the LLM)
Infrastructure Method What it registers api.registerHook(events, handler, opts?)Event hook api.registerHttpRoute(params)Gateway HTTP endpoint api.registerGatewayMethod(name, handler)Gateway RPC method api.registerCli(registrar, opts?)CLI subcommand api.registerService(service)Background service api.registerInteractiveHandler(registration)Interactive handler
Exclusive slots Method What it registers api.registerContextEngine(id, factory)Context engine (one active at a time) api.registerMemoryPromptSection(builder)Memory prompt section builder
Events and lifecycle Method What it does api.on(hookName, handler, opts?)Typed lifecycle hook api.onConversationBindingResolved(handler)Conversation binding callback
API object fields Field Type Description api.idstringPlugin id api.namestringDisplay name api.versionstring?Plugin version (optional) api.descriptionstring?Plugin description (optional) api.sourcestringPlugin source path api.rootDirstring?Plugin root directory (optional) api.configFluffBuzzConfigCurrent config snapshot api.pluginConfigRecord<string, unknown>Plugin-specific config from plugins.entries.<id>.config api.runtimePluginRuntimeRuntime helpers api.loggerPluginLoggerScoped logger (debug, info, warn, error) api.registrationModePluginRegistrationMode"full", "setup-only", or "setup-runtime"api.resolvePath(input)(string) => stringResolve path relative to plugin root
Internal module convention Within your plugin, use local barrel files for internal imports:
my-plugin/ api.ts # Public exports for external consumers runtime-api.ts # Internal-only runtime exports index.ts # Plugin entry point setup-entry.ts # Lightweight setup-only entry (optional)
Never import your own plugin through fluffbuzz/plugin-sdk/<your-plugin>
from production code. Route internal imports through ./api.ts or
./runtime-api.ts. The SDK path is the external contract only.
