bb Plugin API 2.0 design overview

The 2.0 API gives app, server, and host plugins one contract model, one winner model, and one authoring flow.

Start here

This page gives the model and the page map. It does not define final method signatures. The settled design record defines the decisions behind this site.

The research starts at the 2026-08-26 research index. The allocation brief defines the page roster and the old API ownership. The frontend synthesis and backend synthesis provide the evidence.

The model in brief

A plugin is a package with static declarations and separate artifacts for the app, server, and host tiers. The manifest declares claims, new contracts, dependencies, exports, lineage, and artifact paths. The build adds contract.json with full method and type schemas. The kernel validates both files before it loads code.

The headless rule

This rule is a first-party design principle.

A domain service ships headless whenever it has consumers beyond its own UI. Its default presentation is a separate -ui plugin. Presentation-only affordances are child surfaces declared by the default implementation that renders them, never by the domain.

The first-party roster applies this rule to threads, workspace, files, version control, and commands. A data plugin declares no surfaces. Its UI plugin requires the data service and owns the default presentation.

The bb.vcs plugin owns the generic version-control contract. The bb.vcs-ui plugin renders only that contract.

The bb.git plugin claims bb.vcs as its declared default provider. It also exports bb.git.* services for Git-only work.

Presentation-only surfaces follow the implementation that renders them. For example, the default thread view declares bb.thread-ui.sidePanels. A replacement view can omit that child surface without changing bb.threads.

Contracts

A contract is a named, typed, versioned capability. A UI region is a surface contract. A server capability is a service contract. A private server-to-host capability is a host role. All contracts use owner-namespaced IDs:

type FirstPartyContractId = `bb.${string}.${string}`;
type PluginContractId = `${string}.${string}`;

interface ContractDeclaration {
  id: string;
  kind: "single" | "list" | "keyed" | "chain";
  version: string;
  stability: "stable" | "experimental";
  replaceable?: boolean;
}

The kernel seeds bb.app.root as a single surface. A winning surface can declare typed child surfaces. A service owner declares its default provider when the service can fall back after a failure.

Use a contract when the user can replace the capability or when another plugin needs the current winner. Use a module import when the consumer needs one exact implementation.

import { Surface } from "@get-bb/plugin/app";
import { Composer } from "@bb/thread-ui/components";

// The current winner follows the user's choice.
<Surface id="bb.thread-ui.composer" props={{ threadId }} />;

// This import always uses this concrete module.
<Composer threadId={threadId} />;

Service tokens use the same rule on the server. A service consumer gets a live in-process object, and a host call uses an explicit typed host role.

Four kinds

The kind states how a contract combines claims. The same four kinds apply to app surfaces and backend services.

A non-replaceable collision fails at load with a clear error. A list does not have a winner conflict. A chain has visible order. A keyed contract has one winner per key.

Winners and defaults

The kernel stores one global winner for each replaceable single contract and each replaceable keyed key. A fresh install selects the first-party claimant or the declared default provider. A second claimant does not change the active result without a user choice.

The frontend winner of a single surface receives the typed Original component. Original always means the built-in default. It never means another claimant. The backend has no Original handle. A replaceable backend contract declares a default provider instead.

A surface failure reaches a per-surface error boundary. The host shows a notice and uses Original or the default claimant. A service failure uses the declared default provider. Safe mode disables overrides and keeps kernel recovery, defaults, and ports available.

Forks

A fork is a new plugin ID. Its manifest records the parent ID and parent revision:

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

The fork claims each parent contract that it still implements. The install checks those claims against the parent's contract.json. The fork receives fresh service storage. Consumers keep the same contract ID across a winner change.

The normal fork path is short:

1. Resolve the active contract and its source.
2. Copy the parent into a new plugin package.
3. Record the parent ID and revision.
4. Edit the package and build its artifacts.
5. Install the fork and choose it in the winner picker.
6. Merge parent updates from the recorded revision.

Three tiers

The app, server, and host tiers have separate runtime planes. App code shares the browser page, React, and the DOM. Server code runs in the bb server process. Host code runs in the machine daemon. Server code reaches host code only through an explicit typed host role.

One package can provide one or more tiers. The loader stages each factory and commits registrations as one atomic plugin unit. A failed candidate does not affect the active generation.

Required, optional, and watched edges define service dependencies:

On a winner change, the new provider becomes ready before cutover. Old calls drain to a deadline. Surfaces remount. Required dependents restart with fresh handles. Optional and watched consumers stay live.

First-party roster

The kernel is not a plugin. Seventeen core plugins ship on the ordinary path.

The shipping provider plugins are ordinary built-in plugins. They are bb.claude-code, bb.codex, bb.pi, and bb.acp.

Each provider claims bb.providers.provider and ships its own host role and bridge artifacts. Marketplace providers claim the same contract.

The built-in github plugin requires bb.vcs. It uses optional bb.git.* edges only for Git-specific features.

How the pages divide the work

The pages use the same order as the new API. Read pages 03–14 for first-party contracts.

Page 15 contains coverage. Page 16 contains complete rebuild stories.

Reference links

• The full settled design record
• Allocation brief and fixed roster
• Inventory index and gap list
• Frontend synthesis
• Backend synthesis
• Current frontend API report
• Current backend API report
• 1.0 author guide
• 1.0 author reference