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.

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

Update the plugin manifest at the same time:

```json
{
  "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`.

```typescript
// 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:

```bash
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:

```typescript
// 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:

```typescript
// 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:

| Old import | Modern equivalent |
| --- | --- |
| `resolveAgentDir` | `api.runtime.agent.resolveAgentDir` |
| `resolveAgentWorkspaceDir` | `api.runtime.agent.resolveAgentWorkspaceDir` |
| `resolveAgentIdentity` | `api.runtime.agent.resolveAgentIdentity` |
| `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` |
| `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` |
| `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` |
| session store helpers | `api.runtime.agent.session.*` |

Build and test

```bash
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.

```typescript
// 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:

| Old alias                 | New type                  |
| ------------------------- | ------------------------- |
| `ProviderDiscoveryOrder`  | `ProviderCatalogOrder`    |
| `ProviderDiscoveryContext`| `ProviderCatalogContext`  |
| `ProviderDiscoveryResult` | `ProviderCatalogResult`   |
| `ProviderPluginDiscovery` | `ProviderPluginCatalog`   |

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.

```json
{
  "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`:

| Old                           | New                             |
| ----------------------------- | ------------------------------- |
| `SubagentReadSessionParams`   | `SubagentGetSessionMessagesParams` |
| `SubagentReadSessionResult`   | `SubagentGetSessionMessagesResult` |

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.

```typescript
// 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.

```typescript
// 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