Kernlift

Agent plugins

Build an agent capability as a plugin: it joins the one workbench composer, adds its own cards, panels and operations, and switches on and off at runtime without host changes.

An agent plugin is one folder under src/plugins/<id>/ with two entry points: plugin.server.ts for the agent host and plugin.ts for the browser. The host code contains no plugin names. It reads what each switched-on plugin declares (a scene, a Skill, cards, panels, operations) and validates every value before it reaches the reader. It is a plugin of the console kernel described in Plugins, with kind: "agent". The image agent is a small plugin. scripts/validate/fixtures/agent-plugin-fixture is a reference plugin that uses every join point, and the validator runs it.

Before you begin

  • The agent starter installed and runnable.
  • An OpenSpec change for the plugin: openspec-cn new change "<id>-plugin".
  • A plugin id: a lower-case slug that is also its module key. Every key the plugin declares starts with it.

What the reader sees

There is one workbench at /app/agent and one composer. Beside it, a picker lists Auto, General and every switched-on agent plugin.

  • Picking an agent swaps in its composer controls and keeps the typed text. The choice travels inside the message, so retrying an old message runs the agent it was sent to.
  • On Auto the server routes the request. The start response and the thread snapshot name the plugin the Run went to, and the workbench uses that plugin for the rest of the thread.
  • A plugin's cards render in the transcript and its workspace opens as a tab beside it. Several plugins' Runs can share one thread.
  • Switching a plugin off in Settings → Plugins removes it from the picker on the next focus, rejects its new Runs and operations, and shows its old cards by their summary. Switching it back on restores them.

A plugin page such as /app/image is a shortcut into the same workbench with that agent picked.

Choose the join points

Declare only what the plugin needs.

The plugin needs toDeclareWhere
Be picked and routed toscenes, capabilityRoutes (words, file types or both), skillsserver
Show its own composer controls and landingagent with a lazily loaded capabilitybrowser
Put structured, interactive content in the transcriptcards (payload schema) / cardRenderersboth
Open panels beside the threadsurfaces / surfacesboth
Let the reader act without a model turnoperations (input, Run state, timeout)server
Bind a confirmation to the content the reader sawvalidateUserAnswer (guards, approvals)server
Fix a Run policy on the serverhostPinnedContextserver
Store a kind of result of its ownartifactKinds / artifactRenderers (<id>.<kind>)both
Serve downloads or previews over HTTPapi.routes under /api/plugins/<id>/server

Rules every plugin follows

  1. Namespaced keys. Card, panel, operation and artifact-kind keys are <id>.<name>. The registry rejects another plugin's prefix, a duplicate, and <id>.workspace, which the host opens for the plugin's workspace.
  2. Checked on both sides. Payload and input schemas live in the plugin's browser-safe contracts.ts. The server validates before writing or running. The browser validates a card's payload again before rendering it.
  3. Readable without the plugin. Every card carries a plain-text summary. With the plugin switched off or uninstalled, cards show it and artifacts of the plugin's kind are offered for download.
  4. Isolated. Cards and panels render inside an error boundary. An operation has a timeout, and one operation or answer runs per Run at a time.

Keep plugin.server.ts free of React and icons, because the agent service bundles it. Load the capability, cards and panels with import() so the workbench bundle does not grow with every plugin.

Build the plugin

The examples use a plugin with the id storyboard. Copy the layout of scripts/validate/fixtures/agent-plugin-fixture and keep only the join points you chose above.

Contracts and manifest

contracts.ts holds what both halves agree on: keys and zod schemas, with no React and no server imports.

src/plugins/storyboard/contracts.ts
import { z } from "zod";

export const STORYBOARD_PLUGIN_ID = "storyboard";
export const STORYBOARD_SCENE_KEY = "agent.storyboard";
export const STORYBOARD_SKILL_PACKAGE_ID = "platform.storyboard";
export const STORYBOARD_SKILL_DIRECTORY = "src/plugins/storyboard/skills/storyboard-studio";
export const STORYBOARD_CARD_KEY = `${STORYBOARD_PLUGIN_ID}.summary`;
export const STORYBOARD_CARD_SCHEMA_VERSION = 1;

export const StoryboardSummaryPayload = z
  .object({ shots: z.number().int().min(0).max(100) })
  .strict();
src/plugins/storyboard/manifest.ts
import { defineManifest } from "../kernel/types";

export const storyboardManifest = defineManifest({
  id: "storyboard",
  version: "0.1.0",
  kind: "agent",
  requires: ["agent-starter"],
});

Add routes when the plugin owns pages under /app or /admin.

Server half

Declare the AgentHostExtension and contribute it to agent.host. Use relative imports, because the agent service bundles this file and cannot resolve @/ aliases.

src/plugins/storyboard/server/extension.ts
import type { AgentHostExtension } from "../../../server/agent-extensions/types";
import {
  STORYBOARD_CARD_KEY,
  STORYBOARD_CARD_SCHEMA_VERSION,
  STORYBOARD_SCENE_KEY,
  STORYBOARD_SKILL_DIRECTORY,
  STORYBOARD_SKILL_PACKAGE_ID,
  StoryboardSummaryPayload,
} from "../contracts";

export const storyboardExtension: AgentHostExtension = {
  id: "storyboard",
  scenes: [{ sceneKey: STORYBOARD_SCENE_KEY, readinessRequired: false }],
  capabilityRoutes: [{ scene: STORYBOARD_SCENE_KEY, pattern: /\bstoryboard\b/iu }],
  skills: [{ packageId: STORYBOARD_SKILL_PACKAGE_ID, directory: STORYBOARD_SKILL_DIRECTORY }],
  cards: {
    [STORYBOARD_CARD_KEY]: {
      payload: StoryboardSummaryPayload,
      schemaVersion: STORYBOARD_CARD_SCHEMA_VERSION,
    },
  },
};
src/plugins/storyboard/plugin.server.ts
import { defineServerPlugin } from "../kernel/types";
import { storyboardManifest } from "./manifest";
import { storyboardExtension } from "./server/extension";

export const storyboardServerPlugin = defineServerPlugin({
  manifest: storyboardManifest,
  contributes: { "agent.host": [storyboardExtension] },
});

readinessRequired: false keeps a plugin without a configured model from holding up the whole agent service. Add api.routes to the same contributes when the plugin serves HTTP under /api/plugins/storyboard/. Do not check the plugin's own on/off state anywhere. The host rejects its scenes, Skills, operations and API routes while it is switched off.

Browser half

plugin.ts holds only metadata and loaders. The capability, card renderers and panels are imported the first time the workbench needs them.

src/plugins/storyboard/plugin.ts
import { Clapperboard } from "lucide-react";
import { definePlugin } from "../kernel/types";
import {
  STORYBOARD_CARD_KEY,
  STORYBOARD_CARD_SCHEMA_VERSION,
  STORYBOARD_SCENE_KEY,
  STORYBOARD_SKILL_PACKAGE_ID,
} from "./contracts";
import { storyboardManifest } from "./manifest";

export const storyboardPlugin = definePlugin({
  manifest: storyboardManifest,
  contributes: {
    "agent.workbench": [
      {
        id: "storyboard",
        agent: {
          id: "storyboard",
          labelKey: "appConsole.storyboard",
          icon: Clapperboard,
          order: 30,
          scenes: [STORYBOARD_SCENE_KEY],
          skillPackageId: STORYBOARD_SKILL_PACKAGE_ID,
          load: () =>
            import("./workbench/capability").then(({ storyboardCapability }) => storyboardCapability),
        },
        cardRenderers: {
          [STORYBOARD_CARD_KEY]: {
            schemaVersion: STORYBOARD_CARD_SCHEMA_VERSION,
            load: () => import("./workbench/summary-card").then(({ summaryCard }) => summaryCard),
          },
        },
      },
    ],
  },
});

A card or panel acts only through the actions it receives (answer the pending question, open an artifact or panel, quote into the composer, runOperation) or through useWorkbenchOperation from src/components/agent/extension-card.tsx. Add the label key to both dictionaries.

Skill

Put the Skill in the plugin folder, here src/plugins/storyboard/skills/storyboard-studio, with a skill.json and a SKILL.md. In skill.json, list the plugin's scene under scenes and only tools that exist under allowedTools. src/plugins/image-agent/skills/image-studio is a working example. Publish it:

pnpm agent:publish-skills

Because the extension declares the directory in skills, the command publishes it next to the platform Skills, and the Skill is removed when the plugin is removed.

Register

Add the two halves to the installed lists, each inside a // @module:storyboard … // @end-module:storyboard region, with the import in its own region too:

FileEntry
src/plugins/installed.tsstoryboardPlugin
src/plugins/installed.server.tsstoryboardServerPlugin

Dictionary entries go in both messages.ts files inside regions with the same marker.

Ship and validate

Write modules/storyboard/module.json: files with src/plugins/storyboard/**, fragments with the two installed lists and both dictionaries, requires: ["agent-starter"], the same version as the manifest, and docs holding the full address of the plugin's guide. Then add scripts/validate/storyboard.ts, which asserts the plugin's behaviour through the real registries, a validate:storyboard script and a segment in validate:all, and run pnpm registry:build. See Build a module.

Verify

  1. pnpm validate:agent-plugin-contract passes. It also builds the reference plugin and drives every join point through the host.
  2. Your plugin's own validator asserts its behaviour, and pnpm validate:all turns no check red.
  3. In /app/agent, the plugin is listed in the picker; a request that matches its route shows Auto · followed by the plugin's name and opens its workspace tab.
  4. Switch the plugin off in Settings → Plugins: it leaves the picker when the page regains focus, and its cards show their summaries.

Troubleshooting

The registry refuses to start with invalid_extension_key

A key does not start with the plugin id, or names <id>.workspace. Rename it in contracts.ts. Both halves read the same constant.

A card shows only its summary

The plugin is switched off, its renderer's schemaVersion is older than the card's, or the payload fails the renderer's schema. Bump both versions together when the payload changes shape.

A message is refused with plugin_disabled

The picked agent was switched off. The composer keeps the text and returns to Auto. The next message is routed without it.

Next steps