Plugin internals

Documentation Index

Fetch the complete documentation index at: https://docs.fluffbuzz.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Public capability model

​

External compatibility stance

​

Plugin shapes

• plain-capability: registers exactly one capability type (for example a provider-only plugin like mistral).
• hybrid-capability: registers multiple capability types (for example openai owns text inference, speech, media understanding, and image generation).
• hook-only: registers only hooks (typed or custom), no capabilities, tools, commands, or services.
• non-capability: registers tools, commands, services, or routes but no capabilities.

​

Legacy hooks

• keep it working
• document it as legacy
• prefer before_model_resolve for model/provider override work
• prefer before_prompt_build for prompt mutation work
• remove only after real usage drops and fixture coverage proves migration safety

​

Compatibility signals

​

Architecture overview

1. Manifest + discovery FluffBuzz finds candidate plugins from configured paths, workspace roots, global plugin roots, and bundled plugins. Discovery reads native fluffbuzz.plugin.json manifests plus supported bundle manifests first.
2. Enablement + validation Core decides whether a discovered plugin is enabled, disabled, blocked, or selected for an exclusive slot such as memory.
3. Runtime loading Native FluffBuzz plugins are loaded in-process via jiti and register capabilities into a central registry. Compatible bundles are normalized into registry records without importing runtime code.
4. Surface consumption The rest of FluffBuzz reads the registry to expose tools, channels, provider setup, hooks, HTTP routes, CLI commands, and services.

• parse-time metadata comes from registerCli(..., { descriptors: [...] })
• the real plugin CLI module can stay lazy and register on first invocation

• discovery + config validation should work from manifest/schema metadata without executing plugin code
• native runtime behavior comes from the plugin module’s register(api) path

​

Channel plugins and the shared message tool

• core owns the shared message tool host, prompt wiring, session/thread bookkeeping, and execution dispatch
• channel plugins own scoped action discovery, capability discovery, and any channel-specific schema fragments
• channel plugins own provider-specific session conversation grammar, such as how conversation ids encode thread ids or inherit from parent conversations
• channel plugins execute the final action through their action adapter

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• trusted inbound requesterSenderId

• outbound.sendPoll is the shared baseline for channels that fit the common poll model
• actions.handleAction("poll") is the preferred path for channel-specific poll semantics or extra poll parameters

​

Capability ownership model

• a company plugin should usually own all of that company’s FluffBuzz-facing surfaces
• a feature plugin should usually own the full feature surface it introduces
• channels should consume shared core capabilities instead of re-implementing provider behavior ad hoc

• OpenAI lives in one plugin even if it spans text models, speech, images, and future video
• another vendor can do the same for its own surface area
• channels do not care which vendor plugin owns the provider; they consume the shared capability contract exposed by core

• plugin = ownership boundary
• capability = core contract that multiple plugins can implement or consume

1. define the missing capability in core
2. expose it through the plugin API/runtime in a typed way
3. wire channels/features against that capability
4. let vendor plugins register implementations

​

Capability layering

• core capability layer: shared orchestration, policy, fallback, config merge rules, delivery semantics, and typed contracts
• vendor plugin layer: vendor-specific APIs, auth, model catalogs, speech synthesis, image generation, future video backends, usage endpoints
• channel/feature plugin layer: Slack/Discord/voice-call/etc. integration that consumes core capabilities and presents them on a surface

• core owns reply-time TTS policy, fallback order, prefs, and channel delivery
• openai, elevenlabs, and microsoft own synthesis implementations
• voice-call consumes the telephony TTS runtime helper

​

Multi-capability company plugin example

import type { FluffBuzzPluginDefinition } from "fluffbuzz/plugin-sdk/plugin-entry";
import {
  describeImageWithModel,
  transcribeOpenAiCompatibleAudio,
} from "fluffbuzz/plugin-sdk/media-understanding";

const plugin: FluffBuzzPluginDefinition = {
  id: "exampleai",
  name: "ExampleAI",
  register(api) {
    api.registerProvider({
      id: "exampleai",
      // auth/model catalog/runtime hooks
    });

    api.registerSpeechProvider({
      id: "exampleai",
      // vendor speech config — implement the SpeechProviderPlugin interface directly
    });

    api.registerMediaUnderstandingProvider({
      id: "exampleai",
      capabilities: ["image", "audio", "video"],
      async describeImage(req) {
        return describeImageWithModel({
          provider: "exampleai",
          model: req.model,
          input: req.input,
        });
      },
      async transcribeAudio(req) {
        return transcribeOpenAiCompatibleAudio({
          provider: "exampleai",
          model: req.model,
          input: req.input,
        });
      },
    });

    api.registerWebSearchProvider(
      createPluginBackedWebSearchProvider({
        id: "exampleai-search",
        // credential + fetch logic
      }),
    );
  },
};

export default plugin;

• one plugin owns the vendor surface
• core still owns the capability contracts
• channels and feature plugins consume api.runtime.* helpers, not vendor code
• contract tests can assert that the plugin registered the capabilities it claims to own

​

Capability example: video understanding

1. core defines the media-understanding contract
2. vendor plugins register describeImage, transcribeAudio, and describeVideo as applicable
3. channels and feature plugins consume the shared core behavior instead of wiring directly to vendor code

​

Contracts and enforcement

• plugin authors get one stable internal standard
• core can reject duplicate ownership such as two plugins registering the same provider id
• startup can surface actionable diagnostics for malformed registration
• contract tests can enforce bundled-plugin ownership and prevent silent drift

1. runtime registration enforcement The plugin registry validates registrations as plugins load. Examples: duplicate provider ids, duplicate speech provider ids, and malformed registrations produce plugin diagnostics instead of undefined behavior.
2. contract tests Bundled plugins are captured in contract registries during test runs so FluffBuzz can assert ownership explicitly. Today this is used for model providers, speech providers, web search providers, and bundled registration ownership.

​

What belongs in a contract

• typed
• small
• capability-specific
• owned by core
• reusable by multiple plugins
• consumable by channels/features without vendor knowledge

• vendor-specific policy hidden in core
• one-off plugin escape hatches that bypass the registry
• channel code reaching straight into a vendor implementation
• ad hoc runtime objects that are not part of FluffBuzzPluginApi or api.runtime

​

Execution model

• a native plugin can register tools, network handlers, hooks, and services
• a native plugin bug can crash or destabilize the gateway
• a malicious native plugin is equivalent to arbitrary code execution inside the FluffBuzz process

• plugins.allow trusts plugin ids, not source provenance.
• A workspace plugin with the same id as a bundled plugin intentionally shadows the bundled copy when that workspace plugin is enabled/allowlisted.
• This is normal and useful for local development, patch testing, and hotfixes.
• Bundled-plugin trust is resolved from the source snapshot — the manifest and code on disk at load time — rather than from install metadata. A corrupted or substituted install record cannot silently widen a bundled plugin’s trust surface beyond what the actual source claims.

​

Export boundary

• bundled-plugin-specific helper subpaths
• runtime plumbing subpaths not intended as public API
• vendor-specific convenience helpers
• setup/onboarding helpers that are implementation details

​

Load pipeline

1. discover candidate plugin roots
2. read native or compatible bundle manifests and package metadata
3. reject unsafe candidates
4. normalize plugin config (plugins.enabled, allow, deny, entries, slots, load.paths)
5. decide enablement for each candidate
6. load enabled native modules: built bundled modules use a native loader; unbuilt native plugins use jiti
7. call native register(api) hooks and collect registrations into the plugin registry
8. expose the registry to commands/runtime surfaces

​

Manifest-first behavior

• identify the plugin
• discover declared channels/skills/config schema or bundle capabilities
• validate plugins.entries.<id>.config
• augment Control UI labels/placeholders
• show install/catalog metadata
• preserve cheap activation and setup descriptors without loading plugin runtime

• CLI loading narrows to plugins that own the requested primary command
• channel setup/plugin resolution narrows to plugins that own the requested channel id
• explicit provider setup/runtime resolution narrows to plugins that own the requested provider id

​

What the loader caches

• discovery results
• manifest registry data
• loaded plugin registries

• Set FLUFFBUZZ_DISABLE_PLUGIN_DISCOVERY_CACHE=1 or FLUFFBUZZ_DISABLE_PLUGIN_MANIFEST_CACHE=1 to disable these caches.
• Tune cache windows with FLUFFBUZZ_PLUGIN_DISCOVERY_CACHE_MS and FLUFFBUZZ_PLUGIN_MANIFEST_CACHE_MS.

​

Registry model

• plugin records (identity, source, origin, status, diagnostics)
• tools
• legacy hooks and typed hooks
• channels
• providers
• gateway RPC handlers
• HTTP routes
• CLI registrars
• background services
• plugin-owned commands

• plugin module -> registry registration
• core runtime -> registry consumption

​

Conversation binding callbacks

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // A binding now exists for this plugin + conversation.
        console.log(event.binding?.conversationId);
        return;
      }

      // The request was denied; clear any local pending state.
      console.log(event.request.conversation.conversationId);
    });
  },
};

• status: "approved" or "denied"
• decision: "allow-once", "allow-always", or "deny"
• binding: the resolved binding for approved requests
• request: the original request summary, detach hint, sender id, and conversation metadata

​

Provider runtime hooks

• Manifest metadata for cheap pre-runtime lookup: providerAuthEnvVars, providerAuthAliases, providerAuthChoices, and channelEnvVars.
• Config-time hooks: catalog (legacy discovery) plus applyConfigDefaults.
• Runtime hooks: 40+ optional hooks covering auth, model resolution, stream wrapping, thinking levels, replay policy, and usage endpoints. See the full list under Hook order and usage.

​

Hook order and usage

​

Provider example

api.registerProvider({
  id: "example-proxy",
  label: "Example Proxy",
  auth: [],
  catalog: {
    order: "simple",
    run: async (ctx) => {
      const apiKey = ctx.resolveProviderApiKey("example-proxy").apiKey;
      if (!apiKey) {
        return null;
      }
      return {
        provider: {
          baseUrl: "https://proxy.example.com/v1",
          apiKey,
          api: "openai-completions",
          models: [{ id: "auto", name: "Auto" }],
        },
      };
    },
  },
  resolveDynamicModel: (ctx) => ({
    id: ctx.modelId,
    name: ctx.modelId,
    provider: "example-proxy",
    api: "openai-completions",
    baseUrl: "https://proxy.example.com/v1",
    reasoning: false,
    input: ["text"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 128000,
    maxTokens: 8192,
  }),
  prepareRuntimeAuth: async (ctx) => {
    const exchanged = await exchangeToken(ctx.apiKey);
    return {
      apiKey: exchanged.token,
      baseUrl: exchanged.baseUrl,
      expiresAt: exchanged.expiresAt,
    };
  },
  resolveUsageAuth: async (ctx) => {
    const auth = await ctx.resolveOAuthToken();
    return auth ? { token: auth.token } : null;
  },
  fetchUsageSnapshot: async (ctx) => {
    return await fetchExampleProxyUsage(ctx.token, ctx.timeoutMs, ctx.fetchFn);
  },
});

​

Built-in examples

​

Runtime helpers

const clip = await api.runtime.tts.textToSpeech({
  text: "Hello from FluffBuzz",
  cfg: api.config,
});

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from FluffBuzz",
  cfg: api.config,
});

const voices = await api.runtime.tts.listVoices({
  provider: "elevenlabs",
  cfg: api.config,
});

• textToSpeech returns the normal core TTS output payload for file/voice-note surfaces.
• Uses core messages.tts configuration and provider selection.
• Returns PCM audio buffer + sample rate. Plugins must resample/encode for providers.
• listVoices is optional per provider. Use it for vendor-owned voice pickers or setup flows.
• Voice listings can include richer metadata such as locale, gender, and personality tags for provider-aware pickers.
• OpenAI and ElevenLabs support telephony today. Microsoft does not.

api.registerSpeechProvider({
  id: "acme-speech",
  label: "Acme Speech",
  isConfigured: ({ config }) => Boolean(config.messages?.tts),
  synthesize: async (req) => {
    return {
      audioBuffer: Buffer.from([]),
      outputFormat: "mp3",
      fileExtension: ".mp3",
      voiceCompatible: false,
    };
  },
});

• Keep TTS policy, fallback, and reply delivery in core.
• Use speech providers for vendor-owned synthesis behavior.
• Legacy Microsoft edge input is normalized to the microsoft provider id.
• The preferred ownership model is company-oriented: one vendor plugin can own text, speech, image, and future media providers as FluffBuzz adds those capability contracts.

api.registerMediaUnderstandingProvider({
  id: "google",
  capabilities: ["image", "audio", "video"],
  describeImage: async (req) => ({ text: "..." }),
  transcribeAudio: async (req) => ({ text: "..." }),
  describeVideo: async (req) => ({ text: "..." }),
});

• Keep orchestration, fallback, config, and channel wiring in core.
• Keep vendor behavior in the provider plugin.
• Additive expansion should stay typed: new optional methods, new optional result fields, new optional capabilities.
• Video generation already follows the same pattern:
  • core owns the capability contract and runtime helper
  • vendor plugins register api.registerVideoGenerationProvider(...)
  • feature/channel plugins consume api.runtime.videoGeneration.*

const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

const video = await api.runtime.mediaUnderstanding.describeVideoFile({
  filePath: "/tmp/inbound-video.mp4",
  cfg: api.config,
});

const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // Optional when MIME cannot be inferred reliably:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* is the preferred shared surface for image/audio/video understanding.
• Uses core media-understanding audio configuration (tools.media.audio) and provider fallback order.
• Returns { text: undefined } when no transcription output is produced (for example skipped/unsupported input).
• api.runtime.stt.transcribeAudioFile(...) remains as a compatibility alias.

const result = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "Expand this query into focused follow-up searches.",
  provider: "openai",
  model: "gpt-4.1-mini",
  deliver: false,
});

• provider and model are optional per-run overrides, not persistent session changes.
• FluffBuzz only honors those override fields for trusted callers.
• For plugin-owned fallback runs, operators must opt in with plugins.entries.<id>.subagent.allowModelOverride: true.
• Use plugins.entries.<id>.subagent.allowedModels to restrict trusted plugins to specific canonical provider/model targets, or "*" to allow any target explicitly.
• Untrusted plugin subagent runs still work, but override requests are rejected instead of silently falling back.

const providers = api.runtime.webSearch.listProviders({
  config: api.config,
});

const result = await api.runtime.webSearch.search({
  config: api.config,
  args: {
    query: "FluffBuzz plugin runtime helpers",
    count: 5,
  },
});

• Keep provider selection, credential resolution, and shared request semantics in core.
• Use web-search providers for vendor-specific search transports.
• api.runtime.webSearch.* is the preferred shared surface for feature/channel plugins that need search behavior without depending on the agent tool wrapper.

​

api.runtime.imageGeneration

const result = await api.runtime.imageGeneration.generate({
  config: api.config,
  args: { prompt: "A friendly puppy mascot", size: "1024x1024" },
});

const providers = api.runtime.imageGeneration.listProviders({
  config: api.config,
});

• generate(...): generate an image using the configured image-generation provider chain.
• listProviders(...): list available image-generation providers and their capabilities.

​

Gateway HTTP routes

api.registerHttpRoute({
  path: "/acme/webhook",
  auth: "plugin",
  match: "exact",
  handler: async (_req, res) => {
    res.statusCode = 200;
    res.end("ok");
    return true;
  },
});

• path: route path under the gateway HTTP server.
• auth: required. Use "gateway" to require normal gateway auth, or "plugin" for plugin-managed auth/webhook verification.
• match: optional. "exact" (default) or "prefix".
• replaceExisting: optional. Allows the same plugin to replace its own existing route registration.
• handler: return true when the route handled the request.

• api.registerHttpHandler(...) was removed and will cause a plugin-load error. Use api.registerHttpRoute(...) instead.
• Plugin routes must declare auth explicitly.
• Exact path + match conflicts are rejected unless replaceExisting: true, and one plugin cannot replace another plugin’s route.
• Overlapping routes with different auth levels are rejected. Keep exact/prefix fallthrough chains on the same auth level only.
• auth: "plugin" routes do not receive operator runtime scopes automatically. They are for plugin-managed webhooks/signature verification, not privileged Gateway helper calls.
• auth: "gateway" routes run inside a Gateway request runtime scope, but that scope is intentionally conservative:
  • shared-secret bearer auth (gateway.auth.mode = "token" / "password") keeps plugin-route runtime scopes pinned to operator.write, even if the caller sends x-fluffbuzz-scopes
  • trusted identity-bearing HTTP modes (for example trusted-proxy or gateway.auth.mode = "none" on a private ingress) honor x-fluffbuzz-scopes only when the header is explicitly present
  • if x-fluffbuzz-scopes is absent on those identity-bearing plugin-route requests, runtime scope falls back to operator.write
• Practical rule: do not assume a gateway-auth plugin route is an implicit admin surface. If your route needs admin-only behavior, require an identity-bearing auth mode and document the explicit x-fluffbuzz-scopes header contract.

​

Plugin SDK import paths

• index.js — bundled plugin entry
• api.js — helper/types barrel
• runtime-api.js — runtime-only barrel
• setup-entry.js — setup plugin entry

​

Message tool schemas

• presentation for semantic presentation blocks (text, context, divider, buttons, select)
• delivery-pin for pinned-delivery requests

​

Channel target resolution

• messaging.inferTargetChatType({ to }) decides whether a normalized target should be treated as direct, group, or channel before directory lookup.
• messaging.targetResolver.looksLikeId(raw, normalized) tells core whether an input should skip straight to id-like resolution instead of directory search.
• messaging.targetResolver.resolveTarget(...) is the plugin fallback when core needs a final provider-owned resolution after normalization or after a directory miss.
• messaging.resolveOutboundSessionRoute(...) owns provider-specific session route construction once a target is resolved.

• Use inferTargetChatType for category decisions that should happen before searching peers/groups.
• Use looksLikeId for “treat this as an explicit/native target id” checks.
• Use resolveTarget for provider-specific normalization fallback, not for broad directory search.
• Keep provider-native ids like chat ids, thread ids, JIDs, handles, and room ids inside target values or provider-specific params, not in generic SDK fields.

​

Config-backed directories

• allowlist-driven DM peers
• configured channel/group maps
• account-scoped static directory fallbacks

• query filtering
• limit application
• deduping/normalization helpers
• building ChannelDirectoryEntry[]

​

Provider catalogs

• { provider } for one provider entry
• { providers } for multiple provider entries

• simple: plain API-key or env-driven providers
• profile: providers that appear when auth profiles exist
• paired: providers that synthesize multiple related provider entries
• late: last pass, after other implicit providers

• discovery still works as a legacy alias
• if both catalog and discovery are registered, FluffBuzz uses catalog

​

Read-only channel inspection

• resolveAccount(...) is the runtime path. It is allowed to assume credentials are fully materialized and can fail fast when required secrets are missing.
• Read-only command paths such as fluffbuzz status, fluffbuzz status --all, fluffbuzz channels status, fluffbuzz channels resolve, and doctor/config repair flows should not need to materialize runtime credentials just to describe configuration.

• Return descriptive account state only.
• Preserve enabled and configured.
• Include credential source/status fields when relevant, such as:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• You do not need to return raw token values just to report read-only availability. Returning tokenStatus: "available" (and the matching source field) is enough for status-style commands.
• Use configured_unavailable when a credential is configured via SecretRef but unavailable in the current command path.

​

Package packs

{
  "name": "my-pack",
  "fluffbuzz": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"],
    "setupEntry": "./src/setup-entry.ts"
  }
}

• channel registration itself
• any HTTP routes that must be available before the gateway starts listening
• any gateway methods, tools, or services that must exist during that same window

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

{
  "name": "@scope/my-channel",
  "fluffbuzz": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}

​

Channel catalog metadata

{
  "name": "@fluffbuzz/nextcloud-talk",
  "fluffbuzz": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@fluffbuzz/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

• detailLabel: secondary label for richer catalog/status surfaces
• docsLabel: override link text for the docs link
• preferOver: lower-priority plugin/channel ids this catalog entry should outrank
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: selection-surface copy controls
• markdownCapable: marks the channel as markdown-capable for outbound formatting decisions
• exposure.configured: hide the channel from configured-channel listing surfaces when set to false
• exposure.setup: hide the channel from interactive setup/configure pickers when set to false
• exposure.docs: mark the channel as internal/private for docs navigation surfaces
• showConfigured / showInSetup: legacy aliases still accepted for compatibility; prefer exposure
• quickstartAllowFrom: opt the channel into the standard quickstart allowFrom flow
• forceAccountBinding: require explicit account binding even when only one account exists
• preferSessionLookupForAnnounceTarget: prefer session lookup when resolving announce targets

• ~/.fluffbuzz/mpm/plugins.json
• ~/.fluffbuzz/mpm/catalog.json
• ~/.fluffbuzz/plugins/catalog.json

​

Context engine plugins

import { buildMemorySystemPromptAddition } from "fluffbuzz/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("lossless-claw", () => ({
    info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

import {
  buildMemorySystemPromptAddition,
  delegateCompactionToRuntime,
} from "fluffbuzz/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("my-memory-engine", () => ({
    info: {
      id: "my-memory-engine",
      name: "My Memory Engine",
      ownsCompaction: false,
    },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

Adding a new capability

1. define the core contract Decide what shared behavior core should own: policy, fallback, config merge, lifecycle, channel-facing semantics, and runtime helper shape.
2. add typed plugin registration/runtime surfaces Extend FluffBuzzPluginApi and/or api.runtime with the smallest useful typed capability surface.
3. wire core + channel/feature consumers Channels and feature plugins should consume the new capability through core, not by importing a vendor implementation directly.
4. register vendor implementations Vendor plugins then register their backends against the capability.
5. add contract coverage Add tests so ownership and registration shape stay explicit over time.

​

Capability checklist

• core contract types in src/<capability>/types.ts
• core runner/runtime helper in src/<capability>/runtime.ts
• plugin API registration surface in src/plugins/types.ts
• plugin registry wiring in src/plugins/registry.ts
• plugin runtime exposure in src/plugins/runtime/* when feature/channel plugins need to consume it
• capture/test helpers in src/test-utils/plugin-registration.ts
• ownership/contract assertions in src/plugins/contracts/registry.ts
• operator/plugin docs in docs/

​

Capability template

// core contract
export type VideoGenerationProviderPlugin = {
  id: string;
  label: string;
  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;
};

// plugin API
api.registerVideoGenerationProvider({
  id: "openai",
  label: "OpenAI",
  async generateVideo(req) {
    return await generateOpenAiVideo(req);
  },
});

// shared runtime helper for feature/channel plugins
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);

• core owns the capability contract + orchestration
• vendor plugins own vendor implementations
• feature/channel plugins consume runtime helpers
• contract tests keep ownership explicit

​

Related

• Building plugins
• Plugin SDK setup
• Plugin manifest