Authoring a plugin

A plugin declares a static contract graph and supplies behavior through one factory for each runtime tier.

Package shape

A plugin uses one npm package. The package can contain app, server, and host artifacts. Each tier stays in its own runtime plane. A contracts module contains only types, tokens, and contract declarations.

acme-github/
├── package.json
├── bb.plugin.jsonc
├── src/
│   ├── contracts.ts
│   ├── app.tsx
│   ├── server.ts
│   ├── host.ts
│   ├── components/
│   │   └── index.ts
│   └── server-utils/
│       └── index.ts
├── skills/
│   └── github-review/SKILL.md
├── assets/
│   └── icon.svg
└── dist/
    ├── app.mjs
    ├── app.css
    ├── server.mjs
    ├── host.mjs
    ├── contracts.mjs
    ├── contract.json
    └── artifact.json

The source package has these author-visible files.

At least one runtime artifact must exist. A server and its host artifact form one plugin commit. The kernel loads all artifacts from the same plugin version and generation.

The manifest

The manifest supplies the complete static graph. The kernel reads it without plugin execution. The build validates the manifest and generated contract.json as one unit.

// bb.plugin.jsonc
{
  "$schema": "https://getbb.app/schemas/plugin-v2.schema.json",
  "schemaVersion": 2,
  "id": "acme.github",
  "version": "2.0.0",
  "name": "GitHub",
  "description": "Issues, pull requests, and review tools.",
  "category": "integrations",
  "engines": { "bb": "^2.0.0", "sdk": "^2.0.0" },

  // A fork uses a new ID and records its source revision.
  // "fork": { "parent": "bb.github", "parentRevision": "1.4.2" },

  "claims": [
    { "surface": "bb.layout.sidebar", "version": "^1.0.0" },
    { "surface": "bb.thread-ui.sidePanels", "version": "^1.0.0", "order": 40 },
    { "surface": "bb.thread-ui.timeline.item", "version": "^1.0.0", "key": "acme.github.pr" },
    { "service": "bb.agents.tool", "key": "github_search_issues", "version": "^1" },
    { "service": "acme.github.issueCache", "version": "^1" }
  ],

  "surfaces": [
    {
      "id": "acme.github.prView.actions",
      "version": "1.0.0",
      "kind": "list",
      "replaceable": false,
      "props": "./src/contracts.ts#PullRequestActionProps",
      "stability": "experimental"
    }
  ],

  "services": [
    {
      "id": "acme.github.issueCache",
      "kind": "single",
      "version": "1.2.0",
      "contract": "./src/contracts.ts#issueCache",
      "replaceable": true,
      "defaultProvider": "acme.github",
      "stability": "stable"
    }
  ],

  "requires": [
    { "service": "bb.threads", "range": "^1" },
    { "service": "bb.agents.tool", "range": "^1" }
  ],
  "optional": [
    { "service": "bb.workspace", "range": "^1" }
  ],
  "watched": [
    { "service": "bb.providers", "range": "^1" }
  ],

  "hostRoles": [
    {
      "name": "git",
      "contract": "./src/contracts.ts#gitRole",
      "scope": "host",
      "launch": { "kind": "module", "export": "git" }
    }
  ],

  "exports": {
    "./contracts": "./dist/contracts.mjs",
    "./components": "./dist/components.mjs",
    "./server-utils": "./dist/server-utils.mjs"
  },

  "artifacts": {
    "app": "./dist/app.mjs",
    "server": "./dist/server.mjs",
    "host": "./dist/host.mjs"
  }
}

Manifest records

Contract IDs use bb.<plugin>.<contract> for first-party contracts. Other owners use <pluginId>.<contract>. The loader matches service contracts by the ID and a semver range. It never uses JavaScript object identity.

A winning implementation can render its declared child surfaces. Those children exist only under the active winner. The kernel supplies only bb.app.root without a plugin.

Build artifacts

The build writes all outputs into a staging directory. It swaps the directory only after every check succeeds.

The build rejects a runtime claim that has no static manifest claim. It also rejects a missing runtime claim. The build rejects imports from a wrong tier. The contracts module cannot import app, server, or host code.

One factory for each tier

Each artifact exports one factory result as its default export. The factory receives one concrete api object. The loader stages all registrations during the factory call. It commits them as one atomic plugin generation.

export type Disposer = () => void | Promise<void>;

export interface PluginIdentity {
  readonly id: string;
  readonly version: string;
  readonly generation: number;
  readonly signal: AbortSignal;
}

export type PluginFactory<Api> = (
  api: Api,
) => void | Disposer | Promise<void | Disposer>;

Every API registration has automatic cleanup. A factory can return one disposer for resources outside the API. If a factory throws, the loader discards all staged registrations. The current generation stays active.

The three factory modules use explicit tier names.

The factory helpers preserve types and attach no hidden behavior. The loader owns identity and lifecycle.

App API

The app artifact shares the page, React, and the DOM. It can provide surfaces and app-plane services. It can also register behavior with owner plugins through their typed helpers.

export interface AppPluginApi {
  readonly plugin: PluginIdentity;
  readonly surfaces: AppSurfaceApi;
  readonly services: AppServiceApi;
  readonly commands: AppCommandApi;
  readonly settings: AppSettingsApi;
  readonly storage: AppStorageApi;
  readonly log: PluginLog;
  onDispose(disposer: Disposer): void;
}

export interface AppSurfaceApi {
  provide<P>(id: string, component: SingleSurfaceComponent<P>): void;
  provide<P>(id: string, item: ListSurfaceItem<P>): void;
  provide<P>(id: string, item: KeyedSurfaceItem<P>): void;
  provide<P>(id: string, member: SurfaceChainMember<P>): void;
}

export interface AppServiceApi {
  provide<T>(token: ServiceToken<T>, implementation: T): void;
  use<T>(token: ServiceToken<T>): Promise<T>;
  optional<T>(token: ServiceToken<T>): OptionalService<T>;
  watch<T>(token: ServiceToken<T>, listener: ServiceBindingListener<T>): Disposer;
}

export interface OptionalService<T> {
  current(): T | undefined;
  whenAvailable(): Promise<T>;
}

use accepts only a declared required edge. optional and watch accept their matching declared edge. App services are in-process app objects. A server capability needs an owner-provided app client or an explicit RPC contract.

Full app example

// src/app.tsx
import { definePlugin } from "@get-bb/plugin/app";
import { bbThreads } from "@bb/threads/contracts";
import { GitHubPanel } from "./components/GitHubPanel.js";
import { GitHubSummary } from "./components/GitHubSummary.js";

export default definePlugin(async (api) => {
  const threads = await api.services.use(bbThreads.app);

  api.surfaces.provide("bb.thread-ui.sidePanels", {
    key: "acme.github",
    title: "GitHub",
    component: ({ threadId }) => (
      <GitHubPanel threadId={threadId} threads={threads} />
    ),
  });

  api.surfaces.provide("bb.layout.sidebar", ({ Original, props }) => (
    <Original {...props} footer={<GitHubSummary />} />
  ));

});

The loader remounts each provided surface after a winner change. A surface error boundary uses the declared default. The Original component exists only for a single surface and only in the app plane.

Server API

The server artifact runs in the bb server process. A service handle is the provider's real in-process object. The API also exposes kernel ports and typed helpers from first-party owner plugins.

export interface ServerPluginApi {
  readonly plugin: PluginIdentity;
  readonly services: ServerServiceApi;
  readonly storage: PluginStorage;
  readonly secrets: SecretsPort;
  readonly realtime: RealtimePort;
  readonly http: HttpPort;
  readonly rpc: RpcPort;
  readonly host: ServerHostApi;
  readonly log: PluginLog;
  onDispose(disposer: Disposer): void;
}

export interface ServerServiceApi {
  provide<T>(token: ServiceToken<T>, implementation: T): void;
  provide<T>(token: ListServiceToken<T>, item: { key: string; implementation: T }): void;
  provide<K extends string, T>(token: KeyedServiceToken<K, T>, item: { key: K; implementation: T }): void;
  provide<T>(token: ChainServiceToken<T>, member: ServiceChainMember<T>): void;
  use<T>(token: ServiceToken<T>): Promise<T>;
  optional<T>(token: ServiceToken<T>): OptionalService<T>;
  watch<T>(token: ServiceToken<T>, listener: ServiceBindingListener<T>): Disposer;
}

export interface ServerHostApi {
  use<C extends HostRoleContract>(
    name: string,
    contract: C,
    target: HostTarget,
  ): Promise<HostRoleClient<C>>;
}

The storage, secrets, realtime, HTTP, and RPC members are stable kernel ports. Their detailed contracts belong to the kernel page. Domain helpers can extend this API through modules. For example, @bb/agents/server supplies typed tool registration.

Full server example

// src/server.ts
import { defineServerPlugin } from "@get-bb/plugin/server";
import { bbThreads } from "@bb/threads/contracts";
import { bbWorkspace } from "@bb/workspace/contracts";
import { bbProviders } from "@bb/providers/contracts";
import { bbAgentTools } from "@bb/agents/server";
import { gitRole, issueCache } from "./contracts.js";
import { createIssueCache } from "./server-utils/index.js";

export default defineServerPlugin(async (api) => {
  const threads = await api.services.use(bbThreads.server);
  const workspace = api.services.optional(bbWorkspace.server);

  const cache = createIssueCache({
    storage: api.storage,
    threads,
    workspace,
    readRepository: async (input, options) => {
      const git = await api.host.use("git", gitRole, {
        kind: "environment",
        environmentId: input.environmentId,
      });
      return git.call("readRepository", input, options);
    },
  });

  await cache.ready();
  api.services.provide(issueCache, cache);

  bbAgentTools(api).provide({
    key: "github_search_issues",
    title: "Search GitHub issues",
    input: issueCache.methods.search.input,
    run: (input) => cache.search(input),
  });

  api.services.watch(bbProviders.server, (change) => {
    if (change.kind === "available") cache.setProviders(change.service);
    if (change.kind === "unavailable") cache.setProviders(undefined);
  });

  return () => cache.close();
});

The loader waits for this factory before commit. A failed ready() call cannot affect the current provider. The server has no Original service handle. Arbitration returns to the declared default provider after a failure.

Host API

The host artifact runs in the daemon on the user's machine. It fulfills private roles for its server artifact. A host role uses typed verbs for every server-to-host operation.

export interface HostPluginApi {
  readonly plugin: PluginIdentity;
  readonly roles: HostRoleApi;
  readonly log: PluginLog;
  onDispose(disposer: Disposer): void;
}

export interface HostRoleApi {
  provide<C extends HostRoleContract>(
    name: string,
    contract: C,
    handlers: HostRoleHandlers<C>,
  ): void;
}

export interface HostRoleContext<C extends HostRoleContract> {
  readonly signal: AbortSignal;
  readonly target: HostTarget;
  readonly paths: HostPaths;
  readonly fs: HostFileSystem;
  readonly exec: HostExec;
  readonly watch: HostWatch;
  emitSignal<N extends keyof C["signals"]>(name: N, payload: SignalOutput<C, N>): void;
  retain(reason: string): Disposer;
}

Each handler receives HostRoleContext. The context supplies paths, machine ports, signals, and retention.

Full host example

// src/host.ts
import { defineHostPlugin } from "@get-bb/plugin/host";
import { gitRole } from "./contracts.js";

export default defineHostPlugin((api) => {
  api.roles.provide("git", gitRole, {
    async readRepository(input, context) {
      const result = await context.exec.run(
        ["git", "-C", input.path, "status", "--short"],
        { signal: context.signal, cwd: input.path },
      );
      return { stdout: result.stdout, exitCode: result.exitCode };
    },

    async watchRepository(input, context) {
      const release = context.retain(`watch:${input.path}`);
      const stop = await context.watch.path(input.path, () => {
        context.emitSignal("repositoryChanged", { path: input.path });
      });
      return async () => {
        await stop();
        await release();
      };
    },
  });
});

The public service token stays on the server. Consumers do not depend on the private host role. The inspector joins the public service, the server provider, and the host role into one status record.

The four contract kinds

One kind system defines conflict behavior on the app and server planes.

These TypeScript shapes show the four app forms.

type SingleSurfaceComponent<P> = React.ComponentType<{
  props: P;
  Original: React.ComponentType<P>;
}>;

interface ListSurfaceItem<P> {
  key: string;
  title?: string;
  component: React.ComponentType<P>;
}

interface KeyedSurfaceItem<P> {
  key: string;
  component: React.ComponentType<P>;
}

interface SurfaceChainMember<P> {
  key: string;
  wrap(next: React.ComponentType<P>): React.ComponentType<P>;
}

A non-replaceable single or keyed collision fails at load. A list claim never creates a winner conflict. A chain always has a visible order. The kernel does not use plugin load order as policy. The winner store has global scope. A contract or keyed contract key has one current winner for all users.

Sharing rule

Authors use one of three mechanisms. Each mechanism has one meaning.

Use a module import for a concrete building block.

import { Composer } from "@bb/thread-ui/components";

export const FixedComposer = () => <Composer threadId="thr_1" />;

Use a surface for the user's current app choice.

import { Surface } from "@get-bb/plugin/app";

export const SelectedComposer = () => (
  <Surface id="bb.thread-ui.composer" props={{ threadId: "thr_1" }} />
);

Use a service for the user's current server choice.

import { bbThreads } from "@bb/threads/contracts";

export default defineServerPlugin(async (api) => {
  const threads = await api.services.use(bbThreads.server);
  await threads.get("thr_1");
});

The rule is: use a contract for a replaceable thing, and import a module for exact code.

Service edges

Every service use must have one static edge. The loader rejects undeclared access.

export type ServiceBindingChange<T> =
  | { kind: "available"; service: T; providerPluginId: string; generation: number }
  | { kind: "unavailable"; previousProviderPluginId?: string };

export type ServiceBindingListener<T> = (
  change: ServiceBindingChange<T>,
) => void | Promise<void>;

A required edge returns a real in-process object. The consumer must not keep it after its generation stops. The loader blocks new calls during cutover. It drains current calls to a bounded deadline and cancels the remainder.

Forks and lineage

A fork is a normal plugin with a new ID. It records the parent ID and the copied parent revision.

{
  "id": "sawyer.github",
  "version": "1.0.0",
  "fork": {
    "parent": "bb.github",
    "parentRevision": "1.4.2"
  },
  "claims": [
    { "surface": "bb.thread-ui.sidePanels" },
    { "service": "bb.github.issueCache", "version": "^1" }
  ]
}

The fork can claim parent-owned contract IDs that it still implements. The build checks these claims against the parent contract.json. The fork receives fresh storage. It can share data only through an exported service.

The winner picker groups the fork with its parent. Installation does not change the active winner without a user choice. The recorded revision gives an agent the merge base for a later parent update.

Module exports do not follow lineage. Importing @bb/thread-ui/components still imports the parent package's exact module. Consumers that must follow the selected fork use a surface or a service.

Stability tiers

Every declared contract has one stability tier.

An experimental runtime API member starts with experimental_. An experimental contract also carries the manifest marker. The generated contract file repeats this stability value. Inspectors and build errors show it.

A stable claimant must satisfy the declared semver range. A fork cannot weaken the owner's stable contract. An experimental consumer must accept that a parent update can require source changes.

Module exports

Module exports share exact code. They do not participate in arbitration. The manifest and package.json map each public subpath to a built module.

// package.json
{
  "name": "@acme/bb-github",
  "type": "module",
  "exports": {
    "./contracts": {
      "types": "./dist/types/contracts.d.ts",
      "default": "./dist/contracts.js"
    },
    "./components": {
      "types": "./dist/types/components.d.ts",
      "browser": "./dist/components.js"
    },
    "./server-utils": {
      "types": "./dist/types/server-utils.d.ts",
      "node": "./dist/server-utils.js"
    }
  }
}

The build applies these rules.

1. The contracts export can contain tokens, schemas, constants, and types.
2. An app export can import React and other app exports.
3. A server export can import server-safe dependencies.
4. A host export can import host-safe dependencies.
5. A tier cannot import an export for another tier.
6. A plugin cannot register behavior from an imported module at module load time.

First-party packages use short names such as @bb/thread-ui/components and @bb/threads/contracts. External packages use their npm package name. The plugin inspector shows each direct module dependency.

contract.json never replaces the contracts module. The JSON file supports validation and inspection. The module supplies TypeScript inference and runtime token values.

Testing entry

The 2.0 SDK provides one Node-only test root at @get-bb/plugin/testing. Tier subpaths keep browser and host dependencies small.

The product build rejects every import from a /testing subpath.

Server harness

The server harness runs the real loader graph with controlled ports. It stages and commits registrations like production.

export interface ServerHarnessOptions {
  plugin: {
    manifest: PluginManifestSource;
    contract: ContractJson;
    server: ServerPluginDefinition;
    host?: HostPluginDefinition;
  };
  providers?: TestPluginSpec[];
  ports?: Partial<KernelTestPorts>;
  placement?: "inProcess" | "worker";
}

export interface ServerHarness {
  readonly api: ServerPluginApi;
  readonly services: {
    use<T>(token: ServiceToken<T>): Promise<T>;
    stub<T>(token: ServiceToken<T>, implementation: T): ServiceDouble<T>;
  };
  readonly drivers: {
    reload(next?: ServerPluginDefinition): Promise<void>;
    flipWinner(contractId: string, pluginId: string): Promise<void>;
    setSettings(values: Record<string, JsonValue | null>): Promise<void>;
    callRpc(method: string, input?: JsonValue): Promise<JsonValue>;
    runCli(argv: string[]): Promise<CliResult>;
    fetchHttp(method: string, path: string, init?: RequestInit): Promise<Response>;
    runService(name: string): RunningService;
    runSchedule(name: string): Promise<void>;
    emitThreadEvent(event: ThreadEvent): Promise<{ errors: unknown[] }>;
    callAgentTool(name: string, input: unknown): Promise<AgentToolResult>;
    resolveAgentConfiguration(input: AgentConfigurationContext): Promise<AgentConfiguration>;
  };
  readonly inspection: {
    calls: readonly TestCall[];
    callsTo(path: string): readonly TestCall[];
    status(): PluginRuntimeStatus;
    registrations(): readonly ContractRegistration[];
  };
  dispose(): Promise<void>;
}

export function createServerHarness(
  options: ServerHarnessOptions,
): Promise<ServerHarness>;

Service doubles replace the old broad fake SDK. Each double uses a named token and records typed calls. Reload makes prior required service handles stale. Tests can check restart order and winner cutover.

const harness = await createServerHarness({
  plugin: { manifest, contract, server },
  placement: "inProcess",
});

const cache = await harness.services.use(issueCache);
await cache.search({ query: "is:open" });
await harness.drivers.reload();
await expect(cache.search({ query: "is:open" })).rejects.toMatchObject({
  code: "stale_handle",
});

App harness

The app harness loads the real app factory and renders one declared surface. It supplies service doubles, routing, settings, and surface owner props.

export interface RenderSurfaceOptions<P> {
  manifest: PluginManifestSource;
  app: AppPluginDefinition;
  contractId: string;
  key?: string;
  props: P;
  services?: readonly AppServiceDouble[];
  settings?: Record<string, JsonValue>;
  route?: string;
}

export interface RenderedSurface {
  readonly element: HTMLElement;
  readonly behavior: {
    emitRealtime(event: RealtimeEvent): Promise<void>;
    setService<T>(token: ServiceToken<T>, service: T | undefined): Promise<void>;
    flipWinner(contractId: string, pluginId: string): Promise<void>;
  };
  readonly inspection: {
    rpcCalls: readonly TestCall[];
    navigationCalls: readonly TestCall[];
    serviceCalls: readonly TestCall[];
    remountCount: number;
  };
  rerender(props: unknown): Promise<void>;
  unmount(): Promise<void>;
}

export function loadAppPlugin(
  source: AppPluginDefinition | string,
): Promise<CapturedAppPlugin>;

export function renderSurface<P>(
  options: RenderSurfaceOptions<P>,
): Promise<RenderedSurface>;

export function installTestAppRuntime(): Disposer;

renderSurface replaces the old slot-specific renderer. It applies single, list, keyed, and chain rules. It can supply a typed Original for a replaceable single surface.

Content-script test mounts do not exist in 2.0. A test renders the surface that owns the behavior. App factory cleanup uses unmount() and the plugin generation signal.

Host harness

The host harness runs role handlers through schema, JSON, signal, cancellation, and lifecycle boundaries.

export interface HostHarnessOptions {
  paths?: { dataDir: string; tempDir: string };
  ports?: Partial<Pick<HostPluginApi, "fs" | "exec" | "watch">>;
}

export interface HostHarness<C extends HostRoleContract> {
  call<N extends keyof C["methods"]>(
    method: N,
    input: HostMethodInput<C, N>,
    options?: { signal?: AbortSignal },
  ): Promise<HostMethodOutput<C, N>>;
  signals(): readonly HostSignalRecord<C>[];
  retainedLeaseCount(): number;
  readonly lifecycleSignal: AbortSignal;
  dispose(): Promise<void>;
}

export function createHostHarness<C extends HostRoleContract>(
  entry: HostPluginDefinition,
  role: C,
  options?: HostHarnessOptions,
): HostHarness<C>;

Shared and domain test exports

The common entry keeps only general plugin author helpers.

export interface Deferred<T> {
  readonly promise: Promise<T>;
  resolve(value: T | PromiseLike<T>): void;
  reject(reason?: unknown): void;
}

export function deferred<T>(): Deferred<T>;

export interface PublicImportViolation {
  file: string;
  specifier: string;
  reason: "private-package" | "outside-allowlist" | "outside-package" | "dynamic-specifier";
}

export function scanPublicImports(
  packageRoot: string,
  options?: { allow?: readonly RegExp[] },
): { files: string[]; violations: PublicImportViolation[]; privateDependencies: string[] };

export function assertContract(
  contract: ContractDeclaration,
  samples?: ContractSamples,
): void;

Domain fixtures move to the plugin that owns their data types.

Process helpers stay in a separate subpath. App, server, and host bundles cannot import this subpath.

import {
  shellQuote,
  waitForMarkerCount,
} from "@get-bb/plugin/testing/process";

Content scripts and the old app entry

The 0.x app API used a builder object and trusted content scripts. The 2.0 API removes both concepts.

A content script had no contract owner. It could mutate any app state or DOM region. This made replacement, failure fallback, winner inspection, and fork compatibility unclear.

In 2.0, the plugin claims the narrowest owner-declared surface or service.

The old definePluginApp(setup) entry becomes definePlugin(factory) from @get-bb/plugin/app. The factory receives AppPluginApi, not PluginAppBuilder or a runtime namespace object.

// Old
export default definePluginApp((app) => {
  app.contentScripts.register({ id: "status", mount: installStatus });
});

// 2.0
export default definePlugin((api) => {
  api.surfaces.provide("bb.thread-ui.timeline.item", {
    key: "acme.github.status",
    component: GitHubStatus,
  });
});

Covers