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: velaclaw/plugin-sdk/plugin-entry For provider plugins, tool plugins, hook plugins, and anything that is not a messaging channel.

import { definePluginEntry } from "velaclaw/plugin-sdk/plugin-entry";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Short summary",
  register(api) {
    api.registerProvider({
      /* ... */
    });
    api.registerTool({
      /* ... */
    });
  },
});

Field	Type	Required	Default
`id`	`string`	Yes	—
`name`	`string`	Yes	—
`description`	`string`	Yes	—
`kind`	`string`	No	—
`configSchema`	`VelaclawPluginConfigSchema \| () => VelaclawPluginConfigSchema`	No	Empty object schema
`register`	`(api: VelaclawPluginApi) => void`	Yes	—

id must match your velaclaw.plugin.json manifest.
kind is for exclusive slots: "memory" or "context-engine".
configSchema can be a function for lazy evaluation.
Velaclaw resolves and memoizes that schema on first access, so expensive schema builders only run once.

`defineChannelPluginEntry`

Import: velaclaw/plugin-sdk/channel-core Wraps definePluginEntry with channel-specific wiring. Automatically calls api.registerChannel({ plugin }), exposes an optional root-help CLI metadata seam, and gates registerFull on registration mode.

import { defineChannelPluginEntry } from "velaclaw/plugin-sdk/channel-core";

export default defineChannelPluginEntry({
  id: "my-channel",
  name: "My Channel",
  description: "Short summary",
  plugin: myChannelPlugin,
  setRuntime: setMyRuntime,
  registerCliMetadata(api) {
    api.registerCli(/* ... */);
  },
  registerFull(api) {
    api.registerGatewayMethod(/* ... */);
  },
});

Field	Type	Required	Default
`id`	`string`	Yes	—
`name`	`string`	Yes	—
`description`	`string`	Yes	—
`plugin`	`ChannelPlugin`	Yes	—
`configSchema`	`VelaclawPluginConfigSchema \| () => VelaclawPluginConfigSchema`	No	Empty object schema
`setRuntime`	`(runtime: PluginRuntime) => void`	No	—
`registerCliMetadata`	`(api: VelaclawPluginApi) => void`	No	—
`registerFull`	`(api: VelaclawPluginApi) => void`	No	—

setRuntime is called during registration so you can store the runtime reference (typically via createPluginRuntimeStore). It is skipped during CLI metadata capture.
registerCliMetadata runs during both api.registrationMode === "cli-metadata" and api.registrationMode === "full". Use it as the canonical place for channel-owned CLI descriptors so root help stays non-activating while normal CLI command registration remains compatible with full plugin loads.
registerFull only runs when api.registrationMode === "full". It is skipped during setup-only loading.
Like definePluginEntry, configSchema can be a lazy factory and Velaclaw memoizes the resolved schema on first access.
For plugin-owned root CLI commands, prefer api.registerCli(..., { descriptors: [...] }) when you want the command to stay lazy-loaded without disappearing from the root CLI parse tree. For channel plugins, prefer registering those descriptors from registerCliMetadata(...) and keep registerFull(...) focused on runtime-only work.
If registerFull(...) also registers gateway RPC methods, keep them on a plugin-specific prefix. Reserved core admin namespaces (config.*, exec.approvals.*, wizard.*, update.*) are always coerced to operator.admin.

`defineSetupPluginEntry`

Import: velaclaw/plugin-sdk/channel-core For the lightweight setup-entry.ts file. Returns just { plugin } with no runtime or CLI wiring.

import { defineSetupPluginEntry } from "velaclaw/plugin-sdk/channel-core";

export default defineSetupPluginEntry(myChannelPlugin);

Velaclaw 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. In practice, pair defineSetupPluginEntry(...) with the narrow setup helper families:

velaclaw/plugin-sdk/setup-runtime for runtime-safe setup helpers such as import-safe setup patch adapters, lookup-note output, promptResolvedAllowFrom, splitSetupEntries, and delegated setup proxies
velaclaw/plugin-sdk/channel-setup for optional-install setup surfaces
velaclaw/plugin-sdk/setup-tools for setup/install CLI/archive/docs helpers

Keep heavy SDKs, CLI registration, and long-lived runtime services in the full entry. Bundled workspace channels that split setup and runtime surfaces can use defineBundledChannelSetupEntry(...) from velaclaw/plugin-sdk/channel-entry-contract instead. That contract lets the setup entry keep setup-safe plugin/secrets exports while still exposing a runtime setter:

import { defineBundledChannelSetupEntry } from "velaclaw/plugin-sdk/channel-entry-contract";

export default defineBundledChannelSetupEntry({
  importMetaUrl: import.meta.url,
  plugin: {
    specifier: "./channel-plugin-api.js",
    exportName: "myChannelPlugin",
  },
  runtime: {
    specifier: "./runtime-api.js",
    exportName: "setMyChannelRuntime",
  },
});

Use that bundled contract only when setup flows truly need a lightweight runtime setter before the full channel entry loads.

Registration mode

api.registrationMode tells your plugin how it was loaded:

Mode	When	What to register
`"full"`	Normal gateway startup	Everything
`"setup-only"`	Disabled/unconfigured channel	Channel registration only
`"setup-runtime"`	Setup flow with runtime available	Channel registration plus only the lightweight runtime needed before the full entry loads
`"cli-metadata"`	Root help / CLI metadata capture	CLI descriptors only

defineChannelPluginEntry handles this split automatically. If you use definePluginEntry directly for a channel, check mode yourself:

register(api) {
  if (api.registrationMode === "cli-metadata" || api.registrationMode === "full") {
    api.registerCli(/* ... */);
    if (api.registrationMode === "cli-metadata") return;
  }

  api.registerChannel({ plugin: myPlugin });
  if (api.registrationMode !== "full") return;

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

Treat "setup-runtime" as the window where setup-only startup surfaces must exist without re-entering the full bundled channel runtime. Good fits are channel registration, setup-safe HTTP routes, setup-safe gateway methods, and delegated setup helpers. Heavy background services, CLI registrars, and provider/client SDK bootstraps still belong in "full". For CLI registrars specifically:

use descriptors when the registrar owns one or more root commands and you want Velaclaw to lazy-load the real CLI module on first invocation
make sure those descriptors cover every top-level command root exposed by the registrar
use commands alone only for eager compatibility paths

Plugin shapes

Velaclaw classifies loaded plugins by their registration behavior:

Shape	Description
plain-capability	One capability type (e.g. provider-only)
hybrid-capability	Multiple capability types (e.g. provider + speech)
hook-only	Only hooks, no capabilities
non-capability	Tools/commands/services but no capabilities

Use velaclaw plugins inspect <id> to see a plugin’s shape.

SDK Overview — registration API and subpath reference
Runtime Helpers — api.runtime and createPluginRuntimeStore
Setup and Config — manifest, setup entry, deferred loading
Channel Plugins — building the ChannelPlugin object
Provider Plugins — provider registration and hooks

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

Plugin Entry Points

Plugin Entry Points

`definePluginEntry`

`defineChannelPluginEntry`

`defineSetupPluginEntry`

Registration mode

Plugin shapes

​Plugin Entry Points

​definePluginEntry

​defineChannelPluginEntry

​defineSetupPluginEntry

​Registration mode

​Plugin shapes

​Related

Plugin Entry Points

`definePluginEntry`

`defineChannelPluginEntry`

`defineSetupPluginEntry`

Registration mode

Plugin shapes

Related