Migrating from 0.1

If you wrote a plugin against @hivekeep/sdk@0.1 (or against Hivekeep before that, when plugins reached into @/server/... paths), here’s what changed and how to bring it forward to 0.2.

Most of these are mechanical edits: the runtime behaviour is identical or strictly improved. The only “you have to think about it” item is providers (see § Providers).

TL;DR

Area	0.1	0.2
Import path	`from 'ai'`	`from '@hivekeep/sdk'`
`tool()` schema field	`parameters`	`inputSchema`
`PluginContext`	loose `config: any`	`PluginContext<Config>` generic
Vault access	`import { getSecretValue } from '@/server/services/vault'`	`ctx.vault.getSecret(key)`
Hook context	loose `HookContext` (with `[key: string]: unknown`)	`HookPayloadMap[H]` typed per hook
Plugin providers	`{ definition, displayName, capabilities, noApiKey?, apiKeyUrl? }` legacy `ProviderDefinition`	Native `LLMProvider` / `EmbeddingProvider` / `ImageProvider` (same shape as built-ins)
`PluginExports.providers`	`Record<string, PluginProviderRegistration>`	`PluginProvider[]` (flat list of native providers)
Card primitives	`Record<string, unknown>`	Strict `PluginCardPrimitive` discriminated union + `card.*` builders
`manifest.permissions` `http:*`	broken, silently rejected every call	works as a catch-all

Imports

Replace every from 'ai' import with from '@hivekeep/sdk':

import { tool } from 'ai'
import { z } from 'zod'
import { tool, z } from '@hivekeep/sdk'

zod is now re-exported from the SDK so you don’t carry your own dep.

If you reached into Hivekeep internals (from '@/server/channels/adapter', from '@/server/services/vault', etc.), switch those to the SDK as well:

import type { ChannelAdapter, IncomingMessage } from '@/server/channels/adapter'
import type { ChannelAdapter, IncomingMessage } from '@hivekeep/sdk'

@/server/... paths are Hivekeep-internal: only the host can resolve them. Third-party plugins published on npm will fail to load if they import from there.

Tools

The zod schema field on tool() is now inputSchema, not parameters:

tool({
  description: 'Greet someone',
  parameters: z.object({ name: z.string() }),
  inputSchema: z.object({ name: z.string() }),
  execute: async ({ name }) => ({ reply: `Hi ${name}` }),
})

PluginContext<Config>

ctx.config is now generic. Declare your config shape and ctx.config.<field> is typed:

interface MyConfig { apiKey: string; region?: 'eu' | 'us' }

export default function (ctx) {
export default function (ctx: PluginContext<MyConfig>) {
  const apiKey = ctx.config.apiKey as string
  const apiKey = ctx.config.apiKey   // typed: string
}

The runtime never validates against the generic. Hivekeep already validated against your manifest’s config schema. The generic is purely for autocomplete.

Vault

If you read secrets via the internal vault module, switch to ctx.vault:

import { getSecretValue } from '@/server/services/vault'
const token = await getSecretValue(cfg.authTokenVaultKey)
const token = await ctx.vault.getSecret(cfg.authTokenVaultKey)

ctx.vault.getSecret(key) is permissive: you read any vault key you know about (typically a key reference Hivekeep persisted from a password-type config field).

ctx.vault.setSecret(key, value) / deleteSecret(key) / listKeys() are scoped to a plugin:<your-name>: namespace. You cannot touch another plugin’s secrets, even by guessing the prefix.

Hooks

HookContext was a loose { agentId, userId?, taskId?, [key: string]: unknown }. It’s now a discriminated union keyed by hook name:

import type { HookHandler } from '@/server/hooks/types'
import type { HookHandler } from '@hivekeep/sdk'

hooks: {
  afterChat: (ctx) => {
    const response = ctx.response as string   // had to cast
  },
  afterChat: (ctx) => {
    // ctx.message, ctx.response, ctx.agentId, ctx.userId — all typed
  },
  afterToolCall: (ctx) => {
    // ctx.toolName, ctx.toolArgs, ctx.toolResult — all typed
  },
}

The four hook names that were declared but never fired in 0.1 (beforeCompacting, afterCompacting, onTaskSpawn, onCronTrigger) have been removed from the type. They never actually ran: handlers registered against them were silently dead. If you had such a handler, delete it.

Providers

Plugin providers used to ship a ProviderDefinition wrapper:

// 0.1 — DELETED
providers: {
  mistral: {
    definition: {
      type: 'mistral',
      testConnection: async (config) => ({ valid: true }),
      listModels: async (config) => [{ id: 'mistral-medium', name: 'Mistral Medium', capability: 'llm' }],
    },
    displayName: 'Mistral',
    capabilities: ['llm'],
    apiKeyUrl: 'https://console.mistral.ai/api-keys',
  },
}

That shape is gone. In 0.2 you implement the same native interfaces as the built-in providers:

// 0.2
import type { LLMProvider, ChatRequest, ChatChunk } from '@hivekeep/sdk'

class MistralProvider implements LLMProvider {
  readonly type = 'mistral'
  readonly displayName = 'Mistral'
  readonly apiKeyUrl = 'https://console.mistral.ai/api-keys'
  readonly configSchema = [
    { key: 'apiKey', type: 'secret', label: 'API Key', required: true },
  ] as const

  async authenticate(config) { return { valid: true } }
  async listModels(config) {
    return [{ id: 'mistral-medium', name: 'Mistral Medium', contextWindow: 32768 }]
  }

  async *chat(model, request: ChatRequest, config): AsyncIterable<ChatChunk> {
    // stream text-delta / tool-use / thinking-delta / thinking-signature,
    // finish with one finish chunk carrying { reason, usage }
  }
}

export default function (ctx) {
  return { providers: [new MistralProvider()] }
}

PluginExports.providers is now a flat array (PluginProvider[]) instead of a Record. The loader detects each provider’s family by inspecting which method it implements (chat → LLM, embed → embedding, generate → image).

Why bother: a native LLMProvider does streaming, prompt caching, thinking, tool calls, the same surface the built-in Anthropic / OpenAI providers use. The legacy { testConnection, listModels } shape only supported basic chat-completions, with no way to declare advanced features.

Cards

If you emitted cards with Record<string, unknown>[] layouts, you can keep doing that: the new PluginCardPrimitive union accepts any object that matches one of the known type discriminants. But you’ll get autocomplete and compile-time validation by switching to the card.* builders:

import { card } from '@hivekeep/sdk'

ctx.cards.emit({
  agentId,
  cardType: 'progress',
  layout: [
    { type: 'header', title: 'Working...' },
    { type: 'progress', indeterminate: true },
    card.header({ title: 'Working...' }),
    card.progress({ indeterminate: true }),
  ],
  initialState: {},
})

Hand-written literals still work: the builders are sugar, not gatekeepers.

Permissions

manifest.permissions: ["http:*"] was silently broken in 0.1: the matcher only recognized exact hosts and *.domain.tld subdomain patterns. In 0.2 the catch-all works:

{
  "permissions": [
    "http:*",                  // any host (use sparingly)
    "http:api.example.com",    // exact
    "http:*.example.com"       // subdomains + apex
  ]
}

ctx.http.fetch() enforces these. A blocked call throws PluginPermissionError (code: 'PLUGIN_PERMISSION_DENIED') with a message that suggests the right declaration. Raw globalThis.fetch() from inside your plugin is not blocked. ctx.http.fetch is opt-in hardening, not a sandbox.

Manifest

Two small ergonomic improvements:

JSON Schema: add the $schema line to your plugin.json and any editor with JSON-Schema support (VSCode, JetBrains) autocompletes the manifest fields and surfaces typos inline.
```
{
  "$schema": "https://unpkg.com/@hivekeep/sdk/schemas/plugin-manifest.schema.json",
  "name": "my-plugin",
  "version": "0.1.0",
```
hivekeep range: declare which Hivekeep host versions your plugin targets so users don’t try to load incompatible builds. >=0.40.0 is the floor for the 0.2 SDK.

Checklist

Done with your migration when:

No from 'ai' left in your plugin’s imports.
No from '@/server/...' left in your plugin’s imports.
tool() calls use inputSchema (not parameters).
Vault access goes through ctx.vault.getSecret(...).
Hook handlers don’t cast away the payload type.
Plugin providers implement LLMProvider / EmbeddingProvider / ImageProvider directly; PluginExports.providers is an array.
plugin.json has a $schema line and an explicit hivekeep range.
bun typecheck passes.

Stuck on something not covered here? Open an issue at https://github.com/MarlBurroW/hivekeep/issues with the plugin’s source. The SDK’s tests run against the hello-agent reference example, so anything matching that shape is guaranteed to load.