Rebuilding the shipping plugins

All 22 shipping plugins have a direct rebuild path on the 2.0 API.

This page uses the tier counts from the shipping usage inventory. The counts include namespace access items because the inventory records them as old API items. The coverage page and its coverage files map each old item to its new home.

How the move happens

The old API keeps working as a second implementation during the move. Next, bb.sdk becomes a facade over the named services. Members deprecate as first-party and external usage drains.

Built-ins move one plugin at a time on the ordinary path. Each plugin takes the same three steps:

1. Adopt the 2.0 manifest.
2. Replace bb.sdk calls with edges to named data services and kernel ports.
3. Convert slots to claims on the presentation plugin that declares each surface.

Each rebuild section below shows the target shape for that plugin.

Workspace, files, and commands each split into a headless data plugin and a default -ui plugin. Consumers require bb.workspace, bb.files, or bb.commands for data. They claim presentation contracts such as bb.workspace-ui.environmentPage, bb.files-ui.opener, and bb.commands-ui.palette separately. The Workspace page, Files page, and Commands page define these boundaries.

The kernel now owns the fixed bb.preferences port. The presentation-only bb.settings plugin consumes that port and declares settings pages. The Settings page defines this split.

The bb.mentions plugin also ships headless. Mention providers claim keyed service contracts, and the default thread composer declares the mention popover. The Mentions page defines the service and the presentation boundary.

The headless bb.vcs plugin owns the generic version-control contract. The separate bb.vcs-ui plugin supplies its default presentation. The built-in bb.git plugin claims bb.vcs as the declared default provider. It exports separate bb.git.* services for Git-specific work. Plugins for GitHub or another host require bb.vcs. They use optional bb.git.* edges only for Git-specific features. The version-control page defines this boundary.

A leaf UI consumer should move first. inline-vis or pdf-preview can prove the complete build, load, claim, and rollback loop. side-chat should move next because it gives the largest API-workaround reduction. It drops its hand-rolled RPC for the bb.threads service. It also renders the bb.thread-ui.composer surface. Data-heavy plugins follow as their domain services land: tasks, automations, docs, then github. The github move starts after bb.vcs becomes available. Provider plugins move last, after the shared provider host services exist.

First-party core UI moves in the same work. The layout and thread UI decomposition is the largest single step.

The manifest outlines below omit common identity, version, engine, description, and branding fields. Each listed edge uses contract version ^1 unless the plugin needs a narrower range. Kernel ports use the same required, optional, and watched edge rules as domain services. The headless bb.threads, bb.workspace, bb.files, bb.vcs, bb.commands, and bb.mentions plugins supply domain services and declare no surfaces. The headless bb.git plugin claims bb.vcs and supplies Git-specific services. It declares no surfaces. The bb.thread-ui plugin owns every thread surface. Its default view declares the bb.thread-ui.sidePanels child surface. A side-panel claim stays active only while the current view declares that child surface. The UI kit page defines shared module exports, not domain surfaces. The bb.commands.command and bb.commands.cli claims stay on bb.commands because they are service contracts.

App and domain plugins

ask-user-question

This plugin gives an agent a multiple-choice question tool and shows the question in the thread.

Old footprint. Manifest: 5 items. Server: 5 items for one tool, provider configuration, and requestInput(). App: 3 items for the pending-interaction slot.

2.0 shape. It claims bb.agents.tool[AskUserQuestion], bb.agents.configuration, and bb.thread-ui.timeline.item[ask-user-question]. It uses required edges to bb.agents.tool, bb.agents.configuration, and bb.threads. The keyed timeline surface renders both the pending question and the final answer. Its manifest has id: "bb.ask-user-question", app and server artifacts, and the three claims.

Shape change. The pending slot and requestInput() become one durable interaction plus a keyed timeline item. The Threads data page defines interaction history, cancellation, and reconnect behavior. The Thread UI page defines the keyed renderer.

Verdict: fully covered.

automations

This plugin schedules recurring and one-shot agent or script work.

Old footprint. Manifest: 6 items. Server: 30 items across storage, RPC, events, background work, CLI, realtime, and five SDK domains. App: 8 items for one panel, navigation, transport hooks, and provider controls.

2.0 shape. It claims bb.layout.panels[automations] and bb.commands.cli[automations]. It uses required edges to bb.storage, bb.rpc, bb.background, bb.commands.cli, bb.workspace, bb.files, and bb.threads. It uses watched edges to bb.providers and bb.realtime for availability and invalidation. The panel surface renders the list, detail view, and run history. Its manifest has id: "bb.automations", app and server artifacts, the two claims, and a skills root.

Shape change. Named services replace the broad bb.sdk object, while the typed RPC port remains the app boundary. The Authoring page makes server calls direct and keeps app-to-server transport explicit.

Verdict: fully covered.

connect

This plugin provides remote access and shared port tunnels.

Old footprint. Manifest: 5 items. Server: 24 items across KV storage, host tunnels, RPC, instructions, background work, realtime, and CLI. App: 7 items for settings and a sidebar footer action.

2.0 shape. It claims bb.settings.pages[connect], bb.layout.statusbar[connect], bb.agents.configuration, and bb.commands.cli[connect]. It declares the private bb.connect.host.tunnel role with its shared ports. It uses required edges to bb.storage, bb.http, bb.rpc, bb.background, bb.preferences, bb.workspace, and bb.commands.cli. It uses a watched edge to bb.realtime. The settings page renders enrollment and share controls. The status entry renders remote-access state. Its manifest has id: "bb.connect", app, server, and host artifacts, the four claims, and one host role.

Shape change. loopbackBaseUrl becomes bb.http.url(), and port declarations move into host-role manifest data. The Kernel page makes every host tunnel explicit and inspectable.

Verdict: fully covered.

custom-instructions

This plugin stores custom instructions and adds them to agent tasks.

Old footprint. Manifest: 5 items. Server: 10 items across KV storage, RPC, agent instructions, and CLI. App: 4 items for one settings section and RPC.

2.0 shape. It claims bb.settings.pages[custom-instructions], bb.agents.configuration, and bb.commands.cli[custom-instructions]. It uses required edges to bb.storage, bb.rpc, bb.agents.configuration, and bb.commands.cli. The settings page renders the editor. Its manifest has id: "bb.custom-instructions", app and server artifacts, the three claims, and a settings schema.

Shape change. The instruction callback becomes an ordered agent-configuration contribution. The Agents page gives all instruction contributors one contract and one lifecycle.

Verdict: fully covered.

docs

This plugin creates and edits Markdown documents across connected hosts.

Old footprint. Manifest: 6 items. Server: 29 items across storage, files, workspace data, threads, realtime, RPC, HTTP, CLI, mentions, and watches. App: 10 items across panels, a file opener, a directive, navigation, and transport hooks.

2.0 shape. It claims bb.layout.panels[docs], bb.files-ui.opener[md], and bb.files-ui.opener[markdown]. It claims the bb.mentions.provider[@] keyed service contract and bb.commands.cli[docs]. It also claims bb.thread-ui.sidePanels[docs] and bb.thread-ui.timeline.item[docs]. It uses required edges to bb.storage, bb.files, bb.workspace, bb.threads, bb.rpc, bb.http, bb.background, and bb.commands.cli. It uses a watched edge to bb.realtime. The claims render the Docs panel, thread launcher, Markdown editor, and document directive. Its manifest has id: "bb.docs", app and server artifacts, the claims, and a skills root.

Shape change. The plugin stops resolving raw host paths and uses scoped file targets plus bb.files.watch(). The Files page owns confinement, revisions, previews, and loss-aware watches. The Thread UI page owns the side-panel and timeline surfaces.

Verdict: fully covered.

github

This plugin browses GitHub issues and pull requests and sends work to agents.

Old footprint. Manifest: 5 items. Server: 27 items across settings, storage, workspace, threads, RPC, realtime, background work, status, CLI, and mentions. App: 10 items for a panel, thread action, navigation, transport hooks, and shared UI.

2.0 shape. It keeps its bb.layout.panels[github] and bb.thread-ui.sidePanels[github] claims for issue and pull-request views. It also claims the bb.mentions.provider[@] and bb.mentions.provider[#] keyed service contracts. It also claims bb.commands.cli[github]. It uses required edges to bb.storage, bb.preferences, bb.vcs, bb.workspace, bb.threads, bb.rpc, bb.background, and bb.commands.cli. It uses optional edges to bb.git.staging, bb.git.worktrees, and bb.git.stash. It uses a watched edge to bb.realtime. The panel and side-panel surfaces render issue, pull request, and linked-thread views. The mention provider combines GitHub issues and pull requests under each trigger winner. Its manifest has id: "bb.github", app and server artifacts, the listed claims, and a settings schema.

Shape change. The required bb.vcs edge supplies repository identity, status, heads, commits, and diffs. The optional bb.git.* edges supply Git-only features when bb.git owns the selected repository. The plugin keeps GitHub authentication and the GitHub APIs for issues, pull requests, checks, and reviews. The Git page defines the local Git and GitHub boundary. The Workspace page still supplies project and environment lookup. The Thread UI page owns the linked-thread side panel.

Verdict: fully covered.

inline-vis

This plugin renders a workspace HTML file inside a thread message.

Old footprint. Manifest: 6 items. Server: 6 items for RPC, file reads, and thread lookup. App: 4 items for one message directive and RPC.

2.0 shape. It claims bb.thread-ui.timeline.item[inline-vis]. It uses required edges to bb.files, bb.threads, and bb.rpc. The keyed timeline item renders a sandboxed preview lease. Its manifest has id: "bb.inline-vis", app and server artifacts, the timeline claim, and a skills root.

Shape change. The plugin stops building an internal preview URL and requests a scoped preview lease. The Files page defines the lease, size limit, caller binding, and cleanup. The Thread UI page owns the preview renderer claim.

Verdict: fully covered.

keep-awake

This plugin keeps selected macOS hosts awake.

Old footprint. Manifest: 6 items. Server: 14 items across storage, host clients, workspace data, subscriptions, RPC, background work, and CLI. App: 4 items for one settings page. Host: 2 experimental entry and worker-lifetime items.

2.0 shape. It claims bb.settings.pages[keep-awake] and bb.commands.cli[keep-awake]. It declares the private bb.keep-awake.host.keepAwake role at host scope. It uses required edges to bb.storage, bb.rpc, bb.background, bb.workspace, and bb.commands.cli. It uses a watched edge to bb.realtime for host state. The settings page renders host selection and active leases. Its manifest has id: "bb.keep-awake", app, server, and host artifacts, both claims, and one host role.

Shape change. The retained worker becomes a typed host role with automatic leases and shutdown. The Kernel page replaces experimental worker control with one role lifecycle.

Verdict: fully covered.

memory

This plugin provides durable, provider-independent agent memory.

Old footprint. Manifest: 6 items. Server: 10 items across SQLite storage, RPC, agent instructions, and CLI. App: 4 items for one settings page and RPC.

2.0 shape. It claims bb.settings.pages[memory], bb.agents.configuration, and bb.commands.cli[memory]. It uses required edges to bb.storage, bb.rpc, bb.agents.configuration, and bb.commands.cli. The settings page renders memory controls and policy. Its manifest has id: "bb.memory", app and server artifacts, the three claims, and a skills root.

Shape change. Provider-independent memory stays plugin-owned, while agent context uses the shared configuration list. The Agents page keeps contributions ordered and removes provider-specific setup.

Verdict: fully covered.

monaco-editor

This plugin opens editable workspace files with Monaco.

Old footprint. Manifest: 5 items. Server: 11 items across RPC, workspace lookup, file operations, and system settings. App: 6 items for the file opener, one command, RPC, and the code-theme hook.

2.0 shape. It claims keyed bb.files-ui.opener[extension] contracts for each supported extension. It also claims bb.commands.command[bb.monaco-editor.open]. It uses required edges to the headless bb.files service, bb.workspace, bb.preferences, and bb.rpc. It uses a watched edge to bb.layout.themes. The opener surface renders Monaco. The command opens the same surface. Its manifest has id: "bb.monaco-editor", app and server artifacts, keyed claims, and exported editor helpers.

Shape change. The keyed claim moves from bb.files to the presentation owner bb.files-ui. Scoped file targets replace repeated project, environment, and host path resolution. The Files page also adds revision guards for safe editor writes.

Verdict: fully covered.

pdf-preview

This plugin displays PDF files with the browser viewer.

Old footprint. Manifest: 5 items. App: 6 items for the keyed file opener, its source, path, and Original fallback. The declared server artifact uses no old server API.

2.0 shape. It claims the keyed bb.files-ui.preview[pdf] contract and requires the headless bb.files service. The preview renders the browser viewer from the scoped lease that the default opener supplies. Its manifest has id: "bb.pdf-preview", one app artifact, one surface claim, and one required service edge.

Shape change. The rebuild removes the empty server artifact and the manual Original test. The Files page routes only the pdf preview key here and keeps the * fallback separate.

Verdict: fully covered.

plugin-api-docs

This plugin displays an annotated map of the BB plugin API.

Old footprint. Manifest: 6 items. Server: 3 items for logging and one mention provider. App: 4 items for a navigation panel and route navigation.

2.0 shape. It claims bb.layout.panels[plugin-api-docs] and the bb.mentions.provider[@] keyed service contract. It requires no mention service edge because it provides the keyed contract. The panel renders the guide. The mention provider links directly to guide entries. Its manifest has id: "bb.plugin-api-docs", app and server artifacts, the two claims, and a skills root.

Shape change. The old mention callback becomes a keyed mention service claim. The Mentions page gives search and resolution one typed contract.

Verdict: fully covered.

plugin-api-tester

This plugin gives developers a panel that exercises app plugin surfaces.

Old footprint. Manifest: 5 items. App: 3 items for one navigation panel. The declared server artifact uses no old server API.

2.0 shape. It claims bb.layout.panels[plugin-api-tester] and renders its test catalog there. It has no required server edge. Its manifest has id: "bb.plugin-api-tester", one app artifact, and one panel claim.

Shape change. The rebuild removes the empty server artifact and tests claims through the standard loader. The Authoring page supplies fixtures, test hosts, and contract assertions.

Verdict: fully covered.

provider-retry

This plugin resumes a turn after a provider subscription limit ends.

Old footprint. Manifest: 5 items. Server: 23 items across settings, thread history, environments, events, RPC, realtime, background work, disposal, and CLI. App: 9 items for composer customization, provider state, and transport hooks.

2.0 shape. It claims bb.thread-ui.composer.actions[provider-retry] and bb.commands.cli[provider-retry]. It uses required edges to bb.preferences, bb.threads, bb.workspace, bb.background, bb.rpc, and bb.commands.cli. It uses watched edges to bb.providers and bb.realtime. The composer action renders retry state and the next retry time. Its manifest has id: "bb.provider-retry", app and server artifacts, both claims, and a settings schema.

Shape change. The plugin reads durable thread events from the bb.threads service instead of scanning raw SDK history. The Threads data page separates durable history from live invalidation. The Thread UI page owns the retry action surface.

Verdict: fully covered.

secrets

This plugin requests credentials and writes them to dotenv files.

Old footprint. Manifest: 5 items. Server: 8 items across CLI, files, threads, and requestInput(). App: 3 items for the pending-interaction slot. Bridge: 1 secret interaction type.

2.0 shape. It claims bb.thread-ui.timeline.item[secret-request] and bb.commands.cli[secrets]. It uses required edges to bb.threads, bb.files, and bb.commands.cli. The keyed timeline item renders the secret form without exposing the value in thread data. Its manifest has id: "bb.secrets", app and server artifacts, and the two claims.

Shape change. The secret request becomes a durable thread interaction, while bb.files performs the controlled dotenv write. The Threads data page stores the interaction without its secret value. The Thread UI page owns the secret form renderer.

Verdict: fully covered.

side-chat

This plugin opens hidden side-chat forks inside thread panels.

Old footprint. Manifest: 5 items. Server: 18 items across scheduled cleanup, KV storage, RPC, thread forks, queues, timelines, and archive. App: 7 items across message actions, thread panels, RPC, ThreadChat, and Markdown.

2.0 shape. It claims bb.thread-ui.sidePanels[side-chat] and bb.thread-ui.view. It uses required edges to bb.threads, bb.storage, and bb.background. The side panel renders ThreadChat and the bb.thread-ui.composer surface. The view claim wraps Original, adds typed message actions, and declares the bb.thread-ui.sidePanels child surface. Its manifest has id: "bb.side-chat", app and server artifacts, both claims, and a dependency on @bb/thread-ui exports.

Shape change. The rebuild removes its hand-written RPC envelope and calls the live bb.threads service. The Threads data page exposes fork, queue, timeline, and archive contracts. The Thread UI page exports ThreadChat and owns the composer surface.

Verdict: fully covered.

tasks

This plugin plans work, tracks tasks, and delegates tasks to agents.

Old footprint. Manifest: 6 items. Server: 30 items across storage, files, workspace, threads, providers, RPC, HTTP, mentions, events, realtime, background work, and CLI. App: 12 items across a panel, side panel, directives, navigation, provider controls, and transport hooks.

2.0 shape. It claims bb.layout.panels[tasks], the bb.mentions.provider[@] keyed service contract, and bb.commands.cli[tasks]. It also claims bb.thread-ui.sidePanels[tasks] and bb.thread-ui.timeline.item[tasks]. It uses required edges to bb.storage, bb.files, bb.workspace, bb.threads, bb.providers, bb.rpc, bb.http, bb.background, and bb.commands.cli. It uses a watched edge to bb.realtime. The surfaces render the task project, thread task view, and task directives. Its manifest has id: "bb.tasks", app and server artifacts, the five claims, and a skills root.

Shape change. File uploads use staged upload references, and thread reconciliation uses durable service events. The Files page and Threads data page define both data paths. The Thread UI page owns the task panel and timeline claims.

Verdict: fully covered.

workflows

This plugin runs durable, provider-independent agent workflows.

Old footprint. Manifest: 6 items. Server: 35 items across agent tools, settings, storage, threads, files, providers, RPC, events, realtime, background work, status, and CLI. App: 11 items across composer actions, a thread panel, directives, navigation, and transport hooks.

2.0 shape. It claims its bb.agents.tool keys, bb.agents.configuration, and bb.commands.cli[workflows]. It claims bb.thread-ui.composer.actions[workflows] and bb.thread-ui.sidePanels[workflows]. It also claims bb.thread-ui.timeline.item[workflow]. It uses required edges to bb.agents.tool, bb.agents.configuration, bb.preferences, bb.storage, bb.threads, bb.files, bb.providers, bb.rpc, bb.background, and bb.commands.cli. It uses a watched edge to bb.realtime. The thread surfaces render workflow actions, run state, and structured results. Its manifest has id: "bb.workflows", app and server artifacts, the claims, a settings schema, and a skills root.

Shape change. Worker creation and structured output use the named thread execution service. The Threads data page supplies spawn, send, output, defaults, and durable events through one edge. The Thread UI page owns the workflow action, side-panel, and timeline claims.

Verdict: fully covered.

Provider plugins

All four provider rebuilds ship as ordinary built-in plugins. Their IDs are bb.acp, bb.claude-code, bb.codex, and bb.pi.

All four provider rebuilds use the same public contract and host-role model. Each server artifact claims bb.providers.provider[key]. Each host artifact claims bb.providers.bridge[key] and optional bb.providers.nativeRoots[key]. The Providers page joins these claims in one inspector record.

provider-acp

This plugin finds ACP agents and registers them as BB providers.

Old footprint. Manifest: 6 items. Server: 10 items across provider registration, settings, host access, background work, RPC schemas, host listing, and data storage. Host: 5 native-root and entry items. Bridge: 4 ACP probe and adapter items.

2.0 shape. It claims discovered bb.providers.provider[acp:*] keys and matching bridge and native-root role keys. It uses required edges to bb.providers, bb.providers.host.supervisor, bb.providers.host.declarations, bb.preferences, bb.storage, and bb.background. It uses a watched edge to bb.workspace for host changes. It renders no app surface. Its manifest has id: "bb.acp", server and host artifacts, provider claims, host-role claims, and a settings schema.

Shape change. The shared declaration service applies one atomic ACP declaration diff. The Providers page removes disposer maps and repeated declaration polls.

Verdict: fully covered.

provider-claude-code

This plugin runs BB threads with Claude Code.

Old footprint. Manifest: 5 items. Server: 2 registration and settings items. Host: 5 provider-bridge and native-root items. Bridge: 7 transport, request, delta, raw-event, and presentation items.

2.0 shape. It claims bb.providers.provider[claude-code], bb.providers.bridge[claude-code], and bb.providers.nativeRoots[claude-code]. It uses required edges to bb.providers, bb.providers.host.supervisor, bb.providers.host.requests, and bb.providers.host.maintenance. It uses an optional edge to the kernel bb.preferences port. It renders no app surface. Its manifest has id: "bb.claude-code", server and host artifacts, the three claims, and a settings schema.

Shape change. The common bridge supplies turn identity, request control, maintenance, and normalized timeline deltas. The Providers page replaces the plugin's private transport lifecycle.

Verdict: fully covered.

provider-codex

This plugin runs BB threads with Codex and provides helper AI services.

Old footprint. Manifest: 5 items. Server: 4 items for provider registration, AI services, settings, and RPC schema definition. Host: 6 provider, native-root, AI-host, and entry items. Bridge: 6 transport, request, child-I/O, delta, and presentation items.

2.0 shape. It claims bb.providers.provider[codex], bb.providers.bridge[codex], bb.providers.nativeRoots[codex], and its bb.agents.ai keys. It uses required edges to bb.providers, bb.agents.ai, bb.providers.host.supervisor, bb.providers.host.requests, and bb.providers.host.maintenance. It uses an optional edge to the kernel bb.preferences port. It renders no app surface. Its manifest has id: "bb.codex", server and host artifacts, provider and AI claims, and a settings schema.

Shape change. Helper inference becomes a replaceable keyed AI service beside the provider contract. The Agents page separates helper AI calls from agent sessions.

Verdict: fully covered.

provider-pi

This plugin runs BB threads with Pi.

Old footprint. Manifest: 5 items. Server: 2 provider registration and disposal items. Host: 4 provider-bridge and entry items. Bridge: 6 transport, request, raw-event, and presentation items.

2.0 shape. It claims bb.providers.provider[pi] and bb.providers.bridge[pi]. It uses required edges to bb.providers, bb.providers.host.supervisor, bb.providers.host.requests, and bb.providers.host.maintenance. It renders no app surface. Its manifest has id: "bb.pi", server and host artifacts, and the two claims.

Shape change. Factory cleanup and the host supervisor replace the direct onDispose() bridge shutdown path. The Authoring page gives host resources automatic cleanup after the atomic plugin commit.

Verdict: fully covered.