Skip to main content

​
Plugin Entry Points

Every plugin exports a default entry object. The SDK provides three helpers for creating them.
Looking for a walkthrough? See Channel Plugins or Provider Plugins for step-by-step guides.

​
definePluginEntry

Import: fluffbuzz/plugin-sdk/plugin-entry For provider plugins, tool plugins, hook plugins, and anything that is not a messaging channel. 
import { definePluginEntry } from "fluffbuzz/plugin-sdk/plugin-entry";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Short summary",
  register(api) {
    api.registerProvider({
      /* ... */
    });
    api.registerTool({
      /* ... */
    });
  },
});
FieldTypeRequiredDefault
idstringYes—
namestringYes—
descriptionstringYes—
kindstringNo—
configSchemaFluffBuzzPluginConfigSchema | () => FluffBuzzPluginConfigSchemaNoEmpty object schema
register(api: FluffBuzzPluginApi) => voidYes—
  • id must match your fluffbuzz.plugin.json manifest.
  • kind is for exclusive slots: "memory" or "context-engine".
  • configSchema can be a function for lazy evaluation.

​
defineChannelPluginEntry

Import: fluffbuzz/plugin-sdk/core Wraps definePluginEntry with channel-specific wiring. Automatically calls api.registerChannel({ plugin }) and gates registerFull on registration mode. 
import { defineChannelPluginEntry } from "fluffbuzz/plugin-sdk/core";

export default defineChannelPluginEntry({
  id: "my-channel",
  name: "My Channel",
  description: "Short summary",
  plugin: myChannelPlugin,
  setRuntime: setMyRuntime,
  registerFull(api) {
    api.registerCli(/* ... */);
    api.registerGatewayMethod(/* ... */);
  },
});
FieldTypeRequiredDefault
idstringYes—
namestringYes—
descriptionstringYes—
pluginChannelPluginYes—
configSchemaFluffBuzzPluginConfigSchema | () => FluffBuzzPluginConfigSchemaNoEmpty object schema
setRuntime(runtime: PluginRuntime) => voidNo—
registerFull(api: FluffBuzzPluginApi) => voidNo—
  • setRuntime is called during registration so you can store the runtime reference (typically via createPluginRuntimeStore).
  • registerFull only runs when api.registrationMode === "full". It is skipped during setup-only loading.

​
defineSetupPluginEntry

Import: fluffbuzz/plugin-sdk/core For the lightweight setup-entry.ts file. Returns just { plugin } with no runtime or CLI wiring. 
import { defineSetupPluginEntry } from "fluffbuzz/plugin-sdk/core";

export default defineSetupPluginEntry(myChannelPlugin);
FluffBuzz loads this instead of the full entry when a channel is disabled, unconfigured, or when deferred loading is enabled. See Setup and Config for when this matters.

​
Registration mode

api.registrationMode tells your plugin how it was loaded:
ModeWhenWhat to register
"full"Normal gateway startupEverything
"setup-only"Disabled/unconfigured channelChannel registration only
"setup-runtime"Setup flow with runtime availableChannel + lightweight runtime
defineChannelPluginEntry handles this split automatically. If you use definePluginEntry directly for a channel, check mode yourself: 
register(api) {
  api.registerChannel({ plugin: myPlugin });
  if (api.registrationMode !== "full") return;

  // Heavy runtime-only registrations
  api.registerCli(/* ... */);
  api.registerService(/* ... */);
}

​
Plugin shapes

FluffBuzz classifies loaded plugins by their registration behavior:
ShapeDescription
plain-capabilityOne capability type (e.g. provider-only)
hybrid-capabilityMultiple capability types (e.g. provider + speech)
hook-onlyOnly hooks, no capabilities
non-capabilityTools/commands/services but no capabilities
Use fluffbuzz plugins inspect <id> to see a plugin’s shape.