Tools & Plugins / Plugins

Plugin SDK migration

Genesis has moved from a broad backwards-compatibility layer to a modern plugin architecture with focused, documented imports. If your plugin was built before the new architecture, this guide helps you migrate.

What is changing

The old plugin system provided two wide-open surfaces that let plugins import anything they needed from a single entry point:

• genesis/plugin-sdk/compat — a single import that re-exported dozens of helpers. It was introduced to keep older hook-based plugins working while the new plugin architecture was being built.
• genesis/extension-api — a bridge that gave plugins direct access to host-side helpers like the embedded agent runner.
• api.registerEmbeddedExtensionFactory(...) — a removed Pi-only bundled extension hook that could observe embedded-runner events such as tool_result.

The broad import surfaces are now deprecated. They still work at runtime, but new plugins must not use them, and existing plugins should migrate before the next major release removes them. The Pi-only embedded extension factory registration API has been removed; use tool-result middleware instead.

Genesis does not remove or reinterpret documented plugin behavior in the same change that introduces a replacement. Breaking contract changes must first go through a compatibility adapter, diagnostics, docs, and a deprecation window. That applies to SDK imports, manifest fields, setup APIs, hooks, and runtime registration behavior.

Why this changed

The old approach caused problems:

• Slow startup — importing one helper loaded dozens of unrelated modules
• Circular dependencies — broad re-exports made it easy to create import cycles
• Unclear API surface — no way to tell which exports were stable vs internal

The modern plugin SDK fixes this: each import path (genesis/plugin-sdk/\<subpath\>) is a small, self-contained module with a clear purpose and documented contract.

Legacy provider convenience seams for bundled channels are also gone. Imports such as genesis/plugin-sdk/slack, genesis/plugin-sdk/discord, genesis/plugin-sdk/signal, genesis/plugin-sdk/whatsapp, channel-branded helper seams, and genesis/plugin-sdk/telegram-core were private mono-repo shortcuts, not stable plugin contracts. Use narrow generic SDK subpaths instead. Inside the bundled plugin workspace, keep provider-owned helpers in that plugin's own api.ts or runtime-api.ts.

Current bundled provider examples:

• Anthropic keeps Claude-specific stream helpers in its own api.ts / contract-api.ts seam
• OpenAI keeps provider builders, default-model helpers, and realtime provider builders in its own api.ts
• OpenRouter keeps provider builder and onboarding/config helpers in its own api.ts

Compatibility policy

For external plugins, compatibility work follows this order:

1. add the new contract
2. keep the old behavior wired through a compatibility adapter
3. emit a diagnostic or warning that names the old path and replacement
4. cover both paths in tests
5. document the deprecation and migration path
6. remove only after the announced migration window, usually in a major release

If a manifest field is still accepted, plugin authors can keep using it until the docs and diagnostics say otherwise. New code should prefer the documented replacement, but existing plugins should not break during ordinary minor releases.

How to migrate

Migrate Pi tool-result extensions to middleware

Bundled plugins must replace Pi-only api.registerEmbeddedExtensionFactory(...) tool-result handlers with runtime-neutral middleware.

// Pi and Codex runtime dynamic tools
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["pi", "codex"],
});

Update the plugin manifest at the same time:

{
  "contracts": {
    "agentToolResultMiddleware": ["pi", "codex"]
  }
}

External plugins cannot register tool-result middleware because it can rewrite high-trust tool output before the model sees it.

Migrate approval-native handlers to capability facts

Approval-capable channel plugins now expose native approval behavior through approvalCapability.nativeRuntime plus the shared runtime-context registry.

Key changes:

• Replace approvalCapability.handler.loadRuntime(...) with approvalCapability.nativeRuntime
• Move approval-specific auth/delivery off legacy plugin.auth / plugin.approvals wiring and onto approvalCapability
• ChannelPlugin.approvals has been removed from the public channel-plugin contract; move delivery/native/render fields onto approvalCapability
• plugin.auth remains for channel login/logout flows only; approval auth hooks there are no longer read by core
• Register channel-owned runtime objects such as clients, tokens, or Bolt apps through genesis/plugin-sdk/channel-runtime-context
• Do not send plugin-owned reroute notices from native approval handlers; core now owns routed-elsewhere notices from actual delivery results
• When passing channelRuntime into createChannelManager(...), provide a real createPluginRuntime().channel surface. Partial stubs are rejected.

See /plugins/sdk-channel-plugins for the current approval capability layout.

Audit Windows wrapper fallback behavior

If your plugin uses genesis/plugin-sdk/windows-spawn, unresolved Windows .cmd/.bat wrappers now fail closed unless you explicitly pass allowShellFallback: true.

// Before
const program = applyWindowsSpawnProgramPolicy({ candidate });

// After
const program = applyWindowsSpawnProgramPolicy({
  candidate,
  // Only set this for trusted compatibility callers that intentionally
  // accept shell-mediated fallback.
  allowShellFallback: true,
});

If your caller does not intentionally rely on shell fallback, do not set allowShellFallback and handle the thrown error instead.

Find deprecated imports

Search your plugin for imports from either deprecated surface:

grep -r "plugin-sdk/compat" my-plugin/
grep -r "genesis/extension-api" my-plugin/

Replace with focused imports

Each export from the old surface maps to a specific modern import path:

// Before (deprecated backwards-compatibility layer)
import {
  createChannelReplyPipeline,
  createPluginRuntimeStore,
  resolveControlCommandGate,
} from "genesis/plugin-sdk/compat";

// After (modern focused imports)
import { createChannelReplyPipeline } from "genesis/plugin-sdk/channel-reply-pipeline";
import { createPluginRuntimeStore } from "genesis/plugin-sdk/runtime-store";
import { resolveControlCommandGate } from "genesis/plugin-sdk/command-auth";

For host-side helpers, use the injected plugin runtime instead of importing directly:

// Before (deprecated extension-api bridge)
import { runEmbeddedPiAgent } from "genesis/extension-api";
const result = await runEmbeddedPiAgent({ sessionId, prompt });

// After (injected runtime)
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });

The same pattern applies to other legacy bridge helpers:

Build and test

pnpm build
pnpm test -- my-plugin/

Import path reference

Common import path table

This table is intentionally the common migration subset, not the full SDK surface. The full list of 200+ entrypoints lives in scripts/lib/plugin-sdk-entrypoints.json.

That list still includes some bundled-plugin helper seams such as plugin-sdk/feishu, plugin-sdk/feishu-setup, plugin-sdk/zalo, plugin-sdk/zalo-setup, and plugin-sdk/matrix*. Those remain exported for bundled-plugin maintenance and compatibility, but they are intentionally omitted from the common migration table and are not the recommended target for new plugin code.

The same rule applies to other bundled-helper families such as:

• browser support helpers: plugin-sdk/browser-cdp, plugin-sdk/browser-config-runtime, plugin-sdk/browser-config-support, plugin-sdk/browser-control-auth, plugin-sdk/browser-node-runtime, plugin-sdk/browser-profiles, plugin-sdk/browser-security-runtime, plugin-sdk/browser-setup-tools, plugin-sdk/browser-support
• Matrix: plugin-sdk/matrix*
• LINE: plugin-sdk/line*
• IRC: plugin-sdk/irc*
• bundled helper/plugin surfaces like plugin-sdk/googlechat, plugin-sdk/zalouser, plugin-sdk/bluebubbles*, plugin-sdk/mattermost*, plugin-sdk/msteams, plugin-sdk/nextcloud-talk, plugin-sdk/nostr, plugin-sdk/tlon, plugin-sdk/twitch, plugin-sdk/github-copilot-login, plugin-sdk/github-copilot-token, plugin-sdk/diagnostics-otel, plugin-sdk/diffs, plugin-sdk/llm-task, plugin-sdk/thread-ownership, and plugin-sdk/voice-call

plugin-sdk/github-copilot-token currently exposes the narrow token-helper surface DEFAULT_COPILOT_API_BASE_URL, deriveCopilotApiBaseUrlFromToken, and resolveCopilotApiToken.

Use the narrowest import that matches the job. If you cannot find an export, check the source at src/plugin-sdk/ or ask in Discord.

Active deprecations

Narrower deprecations that apply across the plugin SDK, provider contract, runtime surface, and manifest. Each one still works today but will be removed in a future major release. The entry below every item maps the old API to its canonical replacement.

command-auth help builders → command-status

Old (genesis/plugin-sdk/command-auth): buildCommandsMessage, buildCommandsMessagePaginated, buildHelpMessage.

New (genesis/plugin-sdk/command-status): same signatures, same exports — just imported from the narrower subpath. command-auth re-exports them as compat stubs.

// Before
import { buildHelpMessage } from "genesis/plugin-sdk/command-auth";

// After
import { buildHelpMessage } from "genesis/plugin-sdk/command-status";

Mention gating helpers → resolveInboundMentionDecision

Old: resolveInboundMentionRequirement({ facts, policy }) and shouldDropInboundForMention(...) from genesis/plugin-sdk/channel-inbound or genesis/plugin-sdk/channel-mention-gating.

New: resolveInboundMentionDecision({ facts, policy }) — returns a single decision object instead of two split calls.

Downstream channel plugins (Slack, Discord, Matrix, MS Teams) have already switched.

Channel runtime shim and channel actions helpers

genesis/plugin-sdk/channel-runtime is a compatibility shim for older channel plugins. Do not import it from new code; use genesis/plugin-sdk/channel-runtime-context for registering runtime objects.

channelActions* helpers in genesis/plugin-sdk/channel-actions are deprecated alongside raw "actions" channel exports. Expose capabilities through the semantic presentation surface instead — channel plugins declare what they render (cards, buttons, selects) rather than which raw action names they accept.

Web search provider tool() helper → createTool() on the plugin

Old: tool() factory from genesis/plugin-sdk/provider-web-search.

New: implement createTool(...) directly on the provider plugin. Genesis no longer needs the SDK helper to register the tool wrapper.

Plaintext channel envelopes → BodyForAgent

Old: formatInboundEnvelope(...) (and ChannelMessageForAgent.channelEnvelope) to build a flat plaintext prompt envelope from inbound channel messages.

New: BodyForAgent plus structured user-context blocks. Channel plugins attach routing metadata (thread, topic, reply-to, reactions) as typed fields instead of concatenating them into a prompt string. The formatAgentEnvelope(...) helper is still supported for synthesized assistant-facing envelopes, but inbound plaintext envelopes are on the way out.

Affected areas: inbound_claim, message_received, and any custom channel plugin that post-processed channelEnvelope text.

Provider discovery types → provider catalog types

Four discovery type aliases are now thin wrappers over the catalog-era types:

Plus the legacy ProviderCapabilities static bag — provider plugins should attach capability facts through the provider runtime contract rather than a static object.

Thinking policy hooks → resolveThinkingProfile

Old (three separate hooks on ProviderThinkingPolicy): isBinaryThinking(ctx), supportsXHighThinking(ctx), and resolveDefaultThinkingLevel(ctx).

New: a single resolveThinkingProfile(ctx) that returns a ProviderThinkingProfile with the canonical id, optional label, and ranked level list. Genesis downgrades stale stored values by profile rank automatically.

Implement one hook instead of three. The legacy hooks keep working during the deprecation window but are not composed with the profile result.

External OAuth provider fallback → contracts.externalAuthProviders

Old: implementing resolveExternalOAuthProfiles(...) without declaring the provider in the plugin manifest.

New: declare contracts.externalAuthProviders in the plugin manifest and implement resolveExternalAuthProfiles(...). The old "auth fallback" path emits a warning at runtime and will be removed.

{
  "contracts": {
    "externalAuthProviders": ["anthropic", "openai"]
  }
}

Provider env-var lookup → setup.providers[].envVars

Old manifest field: providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }.

New: mirror the same env-var lookup into setup.providers[].envVars on the manifest. This consolidates setup/status env metadata in one place and avoids booting the plugin runtime just to answer env-var lookups.

providerAuthEnvVars remains supported through a compatibility adapter until the deprecation window closes.

Memory plugin registration → registerMemoryCapability

Old: three separate calls — api.registerMemoryPromptSection(...), api.registerMemoryFlushPlan(...), api.registerMemoryRuntime(...).

New: one call on the memory-state API — registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime }).

Same slots, single registration call. Additive memory helpers (registerMemoryPromptSupplement, registerMemoryCorpusSupplement, registerMemoryEmbeddingProvider) are not affected.

Subagent session messages types renamed

Two legacy type aliases still exported from src/plugins/runtime/types.ts:

The runtime method readSession is deprecated in favor of getSessionMessages. Same signature; the old method calls through to the new one.

runtime.tasks.flow → runtime.tasks.flows

Old: runtime.tasks.flow (singular) returned a live task-flow accessor.

New: runtime.tasks.flows (plural) returns DTO-based TaskFlow access, which is import-safe and does not require the full task runtime to be loaded.

// Before
const flow = api.runtime.tasks.flow(ctx);
// After
const flows = api.runtime.tasks.flows(ctx);

Embedded extension factories → agent tool-result middleware

Covered in "How to migrate → Migrate Pi tool-result extensions to middleware" above. Included here for completeness: the removed Pi-only api.registerEmbeddedExtensionFactory(...) path is replaced by api.registerAgentToolResultMiddleware(...) with an explicit runtime list in contracts.agentToolResultMiddleware.

GenesisSchemaType alias → GenesisConfig

GenesisSchemaType re-exported from genesis/plugin-sdk is now a one-line alias for GenesisConfig. Prefer the canonical name.

// Before
import type { GenesisSchemaType } from "genesis/plugin-sdk";
// After
import type { GenesisConfig } from "genesis/plugin-sdk/config-schema";

Removal timeline

All core plugins have already been migrated. External plugins should migrate before the next major release.

Suppressing the warnings temporarily

Set these environment variables while you work on migrating:

GENESIS_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 genesis gateway run
GENESIS_SUPPRESS_EXTENSION_API_WARNING=1 genesis gateway run

This is a temporary escape hatch, not a permanent solution.

Related

• Getting Started — build your first plugin
• SDK Overview — full subpath import reference
• Channel Plugins — building channel plugins
• Provider Plugins — building provider plugins
• Plugin Internals — architecture deep dive
• Plugin Manifest — manifest schema reference