Provider plugins: one API for Codex, Claude Code, pi, and ACP agents (#2325)

## What was wrong

Providers (Codex, Claude Code, pi, and every ACP agent) were wired into
core with per-provider carve-outs: a provider table and
provider-specific skill/command scanning in the daemon,
provider-specific recovery regexes and session branches in the runtime,
provider-id branches in the server and clients, and a narrower ACP-only
path for third-party agents. Adding or changing a provider meant
touching core in many places.

## What changed

Providers are plugins behind one API with zero first-party privilege:
the built-in providers use the same `bb.providers.register` declaration,
bridge protocol, and SDK a third party uses.

- Bridge protocol v3: items carry a declarative `presentation` (label,
glyph, tint, detail); web renders from it, plugins may add React
renderers for their own kinds, mobile renders the declarative base.
- `bb.providers.register` declares strings, icon, models, reasoning
levels, service tiers, permission modes, native skill/command roots,
maintenance, and AI services; one `ProviderInfo` shape everywhere.
- Interactions: closed approvals with `toolUse`, open plugin-defined
requests, one lifecycle event; the server stays the policy owner.
- Runtime and daemon: typed recovery hints replace regexes; one bridge
process per provider artifact with per-thread lanes; the daemon scans
declared roots only and resolves host-only roots through
`resolveNativeRoots`; the ACP tier is deleted and the ACP plugin owns
its agents through a published ACP bridge kit.
- pi moves from a built-in runtime to a plugin over `pi --mode rpc` with
an install gate.
- Plugin icons: `bb.branding.experimental_icons` (name → SVG),
namespaced glyphs, strict SVG validation, `nosniff` + CSP; `bb plugin
build` checks logos for script vectors.
- Stabilization: `experimental_` dropped where audited; provider-literal
ratchet 209 → 18 allowlisted references; cross-plugin duplicates folded
into `experimental_` SDK helpers; eleven published `provider-bridge`
exports kept under "Scheduled removals".
- Wire: `HOST_DAEMON_PROTOCOL_VERSION` 153 → 164; `@get-bb/plugin-sdk`
0.4.16; `bb plugin build` inlines SDK subpaths so packaged installs load
provider plugins.
- Older mobile builds are not supported (the app ships with the server):
the timeline wire serves grammar v3 only — no capability header, no
`activityIntents` on tool rows, no `ProviderInfo` maintenance aliases.
- Docs: `docs/provider-plugin-api.md`, `docs/api_to_audit.md`, the
plugin-authoring skill, the bb guide, CLI surfaces.

Built as reviewed layers and squashed into one commit, then
adversarially reviewed (51 findings; every confirmed one fixed with a
failing-first test and an independent re-check — the commit message
lists them).

## How you verified

- Typecheck 76/76; full test sweep; CI build + lint; `smoke:tarball`;
SDK version guards.
- Parity harness: 39 recorded bridge cells replayed through the
pre-migration main and this branch, zero diffs outside the named
allowlist.
- Provider corpus: 340 real threads / 94,365 rows, every changed row in
a named class, 0 unclassified.
- Permission matrix 134 cells identical; native-roots goldens 22/22;
every bridge's conformance kit green; real-provider integration suite
(Codex, Claude Code, pi, ACP agents) 64 tests.
- Live QA: Codex, Claude Code, Cursor and grok (ACP), the echo example
plugin, and pi each ran a tool turn.

> AGENT GENERATED: by Claude Opus 5

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: SawyerHood

apps/app/.ladle/model-picker-query-provider.tsx

@@ -51,12 +51,11 @@ const STORY_COMPOSER_ACTIONS_BY_PROVIDER: Record<
 const STORY_PROVIDER_INFOS: ProviderInfo[] = STORY_PROVIDER_OPTIONS.map(
   (provider) => ({
     id: provider.value,
+    pluginId: `provider-${provider.value}`,
     displayName: provider.label,
     logoUrl: null,
     available: true,
-    experimental_providerHealth: true,
-    experimental_providerUsage: true,
-    experimental_providerInstallation: true,
+    maintenance: { health: true, usage: true, installation: true },
     composerActions: [
       ...(STORY_COMPOSER_ACTIONS_BY_PROVIDER[provider.value] ?? []),
     ],
@@ -67,6 +66,7 @@ const STORY_PROVIDER_INFOS: ProviderInfo[] = STORY_PROVIDER_OPTIONS.map(
       supportsNativeUserQuestion: true,
       supportsFork: true,
       supportsSessionRewind: true,
+      modelCatalogScope: "workspace",
       permissionModes: [...permissionModes],
     },
   }),

apps/app/.ladle/settings-story-fixtures.tsx

@@ -1,16 +1,10 @@
 import { useState, type ReactNode } from "react";
 import { useNavigate } from "react-router-dom";
 import { QueryClientProvider } from "@tanstack/react-query";
-import {
-  PERSONAL_PROJECT_ID,
-  defaultAppSettings,
-  defaultAppTheme,
-  defaultExperiments,
-} from "@bb/domain";
+import { PERSONAL_PROJECT_ID } from "@bb/domain";
 import { UPDATE_ACTION_ICON } from "@bb/domain/update-state";
 import type {
   SidebarBootstrapResponse,
-  SystemConfigResponse,
   SystemVersionResponse,
 } from "@bb/server-contract";
 import type { ProviderCliStatusResponse } from "@bb/host-daemon-contract";
@@ -28,6 +22,7 @@ import {
   type UpdateInventoryMachine,
 } from "../src/hooks/useUpdateInventory";
 import { createAppQueryClient } from "../src/lib/query-client";
+import { makeSystemConfig } from "../src/test/fixtures/system-config";
 import { getSettingsRoutePath } from "../src/lib/route-paths";
 import {
   BbAppUpdateRows,
@@ -129,24 +124,12 @@ const sidebarNavigation = {
   },
 } satisfies SidebarBootstrapResponse;
 
-const systemConfig = {
-  generalSettings: defaultAppSettings,
-  keybindings: [],
-  defaultKeybindings: [],
-  keybindingOverrides: [],
-  experiments: defaultExperiments,
-  appearance: defaultAppTheme,
-  customThemes: [],
-  pluginThemes: [],
-  featureFlags: { placeholder: false, timelineWindowEventBudget: 1_500 },
-  hostDaemonPort: null,
-  localHelperPorts: [],
-  serverUrl: "http://localhost:38886",
+const systemConfig = makeSystemConfig({
   primaryHostId: HOST_IDS.local,
   primaryHostPlatform: "darwin",
   voiceTranscriptionEnabled: true,
   dataDir: "/Users/michael/.bb",
-} satisfies SystemConfigResponse;
+});
 
 const systemVersion = {
   currentVersion: "0.39.0",

apps/app/.ladle/story-fixtures.ts

@@ -12,9 +12,7 @@ import type {
   ProviderCliStatus,
 } from "@bb/host-daemon-contract";
 import type { ProjectResponse } from "@bb/server-contract";
-import { ClaudeIcon } from "../src/components/icons/ClaudeIcon";
-import { OpenAiIcon } from "../src/components/icons/OpenAiIcon";
-import { PiIcon } from "../src/components/icons/PiIcon";
+import { getProviderIconInfo } from "../src/lib/provider-icon";
 import type { PickerOption } from "../src/components/pickers/OptionPicker";
 import type { ModelPickerOption } from "../src/components/pickers/model-picker-option";
 import type { ProjectSelectorOption } from "../src/components/pickers/ProjectSelector";
@@ -114,10 +112,21 @@ export function makeAttachmentsConfig(
 // need to pre-format.
 // ---------------------------------------------------------------------------
 
+// Core vendors no brand marks (they come from the provider plugins' declared
+// logos), so stories draw each provider through a declared host glyph.
+function storyProviderIcon(providerId: string, glyph: string) {
+  return getProviderIconInfo(providerId, { logoUrl: null, icon: { glyph } })
+    ?.icon;
+}
+
 export const STORY_PROVIDER_OPTIONS: readonly PickerOption<string>[] = [
-  { value: "codex", label: "Codex", icon: OpenAiIcon },
-  { value: "claude-code", label: "Claude Code", icon: ClaudeIcon },
-  { value: "pi", label: "Pi", icon: PiIcon },
+  { value: "codex", label: "Codex", icon: storyProviderIcon("codex", "Code") },
+  {
+    value: "claude-code",
+    label: "Claude Code",
+    icon: storyProviderIcon("claude-code", "Sparkles"),
+  },
+  { value: "pi", label: "Pi", icon: storyProviderIcon("pi", "Zap") },
 ];
 
 export const STORY_CODEX_MODELS: readonly PickerOption<string>[] = [

apps/app/src/components/code/DiffHost.test.tsx

@@ -14,6 +14,7 @@ import {
   setPluginSlotRegistrations,
 } from "@/lib/plugin-slots";
 import { resetAllCrashedPluginSlotsForTest } from "@/components/plugin/PluginSlotMount";
+import { resetDeprecatedAliasWarningsForTests } from "@/lib/plugin-sdk-deprecated-aliases";
 import { parseGitDiffFiles } from "@/components/git-diff/git-diff-parsing";
 import { PluginDiff } from "@/components/plugin/PluginDiff";
 import {
@@ -112,6 +113,7 @@ beforeEach(() => {
   bbDiff.lastProps = null;
   receivedProps.length = 0;
   resetPluginSlotStoreForTest();
+  resetDeprecatedAliasWarningsForTests();
   applyResolvedCodeTheme(defaultResolvedCodeTheme);
 });
 
@@ -203,7 +205,7 @@ describe("DiffHost", () => {
   });
 
   it("loads BB's renderer only when the replacement delegates", async () => {
-    registerDiffRenderer(({ path, experimental_Original: Original }) =>
+    registerDiffRenderer(({ path, Original }) =>
       path.endsWith(".ts") ? <Original /> : <div>plugin diff</div>,
     );
 
@@ -378,3 +380,63 @@ describe("experimental_Diff", () => {
     expect(bbDiff.loaded).toBe(false);
   });
 });
+
+/**
+ * A bundle built against an SDK before 0.4.16 reads `experimental_Original`
+ * (renamed `Original` in 0.4.16). The host passes both for one release.
+ */
+describe("DiffHost experimental_Original alias", () => {
+  it("delegates to BB's renderer through the alias and warns once across renders", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    let renders = 0;
+    registerDiffRenderer(({ experimental_Original: LegacyOriginal }) => {
+      renders += 1;
+      return LegacyOriginal === undefined ? (
+        <div>alias missing</div>
+      ) : (
+        <LegacyOriginal />
+      );
+    });
+
+    const { rerender } = render(
+      <DiffHost
+        file={parseFixture()}
+        patchText={PATCH}
+        fullFileContents={null}
+      />,
+    );
+    expect(await screen.findByTestId("bb-diff")).toBeDefined();
+    expect(bbDiff.lastProps?.view).toBe("unified");
+
+    rerender(
+      <DiffHost
+        file={parseFixture()}
+        patchText={PATCH}
+        fullFileContents={null}
+        view="split"
+      />,
+    );
+    expect(await screen.findByText("bb diff split/scroll")).toBeDefined();
+    expect(renders).toBe(2);
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn).toHaveBeenCalledWith(
+      "experimental_Original is deprecated; use Original. Removed in bb 0.42",
+    );
+  });
+
+  it("never warns for a renderer that reads Original", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    registerDiffRenderer(({ Original }) => <Original />);
+
+    render(
+      <DiffHost
+        file={parseFixture()}
+        patchText={PATCH}
+        fullFileContents={null}
+      />,
+    );
+
+    expect(await screen.findByTestId("bb-diff")).toBeDefined();
+    expect(warn).not.toHaveBeenCalled();
+  });
+});

apps/app/src/components/code/DiffHost.tsx

@@ -1,6 +1,7 @@
 import { Suspense, lazy, useMemo, type ReactNode } from "react";
 import type { ExperimentalDiffFullFileContents } from "@get-bb/plugin-sdk";
 import { PluginReplacementSlot } from "@/components/plugin/PluginReplacementSlot";
+import { deprecatedOriginalAlias } from "@/lib/plugin-sdk-deprecated-aliases";
 import type { ParsedGitDiffFile } from "@/components/git-diff/git-diff-parsing";
 import { buildFileDiffPatchText } from "@/components/git-diff/git-diff-patch-text";
 import { useDiffRendererReplacement } from "./codeRendererProvider";
@@ -47,7 +48,7 @@ interface DiffHostProps extends Partial<DiffPresentation> {
  * actually mounts.
  *
  * BB's own renderer sits behind `lazy()`. A plugin replacement that never
- * delegates therefore never downloads it, and `experimental_Original` costs
+ * delegates therefore never downloads it, and `Original` costs
  * nothing until it is actually rendered.
  */
 export function DiffHost({
@@ -100,7 +101,8 @@ export function DiffHost({
             overflow={overflow}
             showLineNumbers={showLineNumbers}
             experimental_fullFileContents={fullFileContents}
-            experimental_Original={BoundOriginal}
+            Original={BoundOriginal}
+            experimental_Original={deprecatedOriginalAlias(BoundOriginal)}
           />
         </div>
       )}

apps/app/src/components/code/SourceCodeHost.test.tsx

@@ -8,6 +8,7 @@ import {
   setPluginSlotRegistrations,
 } from "@/lib/plugin-slots";
 import { resetAllCrashedPluginSlotsForTest } from "@/components/plugin/PluginSlotMount";
+import { resetDeprecatedAliasWarningsForTests } from "@/lib/plugin-sdk-deprecated-aliases";
 import { PluginSourceCode } from "@/components/plugin/PluginSourceCode";
 import { SourceCodeHost } from "./SourceCodeHost";
 
@@ -54,6 +55,7 @@ beforeEach(() => {
   bbSourceCode.lastProps = null;
   received.length = 0;
   resetPluginSlotStoreForTest();
+  resetDeprecatedAliasWarningsForTests();
 });
 
 afterEach(() => {
@@ -109,7 +111,7 @@ describe("SourceCodeHost", () => {
   });
 
   it("loads BB's renderer only when the replacement delegates", async () => {
-    registerSourceCodeRenderer(({ path, experimental_Original: Original }) =>
+    registerSourceCodeRenderer(({ path, Original }) =>
       path.endsWith(".md") ? <div>plugin source</div> : <Original />,
     );
 
@@ -165,3 +167,51 @@ describe("experimental_SourceCode", () => {
     expect(bbSourceCode.loaded).toBe(false);
   });
 });
+
+/**
+ * A bundle built against an SDK before 0.4.16 reads `experimental_Original`
+ * (renamed `Original` in 0.4.16). The host passes both for one release.
+ */
+describe("SourceCodeHost experimental_Original alias", () => {
+  it("delegates to BB's renderer through the alias and warns once across renders", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    let renders = 0;
+    registerSourceCodeRenderer(({ experimental_Original: LegacyOriginal }) => {
+      renders += 1;
+      return LegacyOriginal === undefined ? (
+        <div>alias missing</div>
+      ) : (
+        <LegacyOriginal />
+      );
+    });
+
+    const { rerender } = render(
+      <SourceCodeHost content={CONTENT} path="src/app.ts" />,
+    );
+    expect(await screen.findByTestId("bb-source-code")).toBeDefined();
+    expect(bbSourceCode.lastProps?.overflow).toBe("scroll");
+
+    rerender(
+      <SourceCodeHost content={CONTENT} path="src/app.ts" overflow="wrap" />,
+    );
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(bbSourceCode.lastProps?.overflow).toBe("wrap");
+    expect(renders).toBe(2);
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn).toHaveBeenCalledWith(
+      "experimental_Original is deprecated; use Original. Removed in bb 0.42",
+    );
+  });
+
+  it("never warns for a renderer that reads Original", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    registerSourceCodeRenderer(({ Original }) => <Original />);
+
+    render(<SourceCodeHost content={CONTENT} path="src/app.ts" />);
+
+    expect(await screen.findByTestId("bb-source-code")).toBeDefined();
+    expect(warn).not.toHaveBeenCalled();
+  });
+});

apps/app/src/components/code/SourceCodeHost.tsx

@@ -1,5 +1,6 @@
 import { Suspense, lazy, type ReactNode } from "react";
 import { PluginReplacementSlot } from "@/components/plugin/PluginReplacementSlot";
+import { deprecatedOriginalAlias } from "@/lib/plugin-sdk-deprecated-aliases";
 import { useSourceCodeRendererReplacement } from "./codeRendererProvider";
 import {
   DEFAULT_CODE_OVERFLOW,
@@ -71,7 +72,8 @@ export function SourceCodeHost({
             path={path}
             overflow={overflow}
             highlightedLines={highlightedLines}
-            experimental_Original={BoundOriginal}
+            Original={BoundOriginal}
+            experimental_Original={deprecatedOriginalAlias(BoundOriginal)}
           />
         </div>
       )}

apps/app/src/components/dialogs/AddMachineDialog.test.tsx

@@ -77,6 +77,8 @@ function connectPlugin(
     app: { hasApp: false, bundle: null },
     logoUrl: null,
     logoDarkUrl: null,
+    providerIds: [],
+    icons: {},
     ...overrides,
   };
 }