Providers

bb.providers owns provider choice, the provider bridge protocol, and shared provider host control.

Purpose

The plugin gives each provider ID one replaceable implementation. It gives consumers one registry for models, health, usage, and maintenance.

The plugin also owns the typed server-to-host bridge. Provider plugins translate their native agent protocol into this common protocol.

The kernel still owns host transport and process isolation. bb.providers owns provider sessions, request control, recovery, and maintenance above those kernel ports.

Built-in provider plugins

The built-in provider plugins use the same contracts as all other provider plugins.

Each plugin claims bb.providers.provider, keyed by provider ID. Each plugin supplies its own keyed bb.providers.bridge host-role implementation and bridge artifacts.

These plugins have no special privilege. A marketplace provider claims the same contract and uses the same winner rules.

A fork claims the same keys and enters the normal winner selection. A provider plugin fork follows the same rules as any other plugin fork.

Surfaces

Services

bb.providers

This service is the registry and control plane. Read methods use the current winner for each provider key.

export interface ProvidersService {
  list(query?: ProviderListQuery): Promise<readonly ProviderRecord[]>;
  get(providerId: string): Promise<ProviderRecord | null>;
  resolve(providerId: string): Promise<Provider>;
  watch(listener: (event: ProviderRegistryEvent) => void): Unsubscribe;
  models(providerId: string, context: ProviderHostContext): Promise<ModelCatalog>;
  health(providerId: string, context: ProviderHostContext): Promise<ProviderHealth>;
  usage(providerId: string, context: ProviderHostContext): Promise<ProviderUsage>;
  installationStatus(
    providerId: string,
    context: ProviderHostContext,
  ): Promise<ProviderInstallationStatus>;
  runInstallation(
    providerId: string,
    context: ProviderHostContext,
    action: "install" | "update",
  ): Promise<ProviderInstallationRunResult>;
}

export interface ProviderRecord {
  providerId: string;
  declaration: ProviderDeclaration;
  winner: { pluginId: string; generation: number; isDefault: boolean };
  claimants: readonly { pluginId: string; version: string; state: ProviderClaimState }[];
  availability: "ready" | "unavailable" | "degraded" | "failed";
  lastFailure?: ProviderFailure;
}

export type ProviderRegistryEvent =
  | { kind: "added" | "changed"; record: ProviderRecord }
  | { kind: "winner-changed"; providerId: string; previousPluginId: string; record: ProviderRecord }
  | { kind: "removed"; providerId: string }
  | { kind: "health-changed"; providerId: string; health: ProviderHealth };

A keyed winner change uses the backend replacement transaction. The candidate must become ready before cutover.

The runtime drains old calls to a deadline. It then restarts required dependents in graph order.

The first claim for a new key must declare itself as that key's default. A later replacement claim cannot change this fallback.

bb.providers.provider

Each claim implements one provider ID. The declaration is static, but the methods can use settings and host state.

export interface Provider {
  declaration(): ProviderDeclaration;
  deriveOptions(context: ProviderOptionsContext): Promise<JsonObject>;
  models(context: ProviderHostContext): Promise<ModelCatalog>;
  health(context: ProviderHostContext): Promise<ProviderHealth>;
  usage(context: ProviderHostContext): Promise<ProviderUsage>;
  installationStatus(context: ProviderHostContext): Promise<ProviderInstallationStatus>;
  runInstallation(
    context: ProviderHostContext,
    action: "install" | "update",
  ): Promise<ProviderInstallationRunResult>;
  resolveNativeRoots(context: NativeRootsContext): Promise<ProviderResolvedNativeRoots>;
  openSession(context: ProviderSessionContext): Promise<ProviderSession>;
}

export interface ProviderSession {
  start(input: ThreadStartRequest): Promise<ThreadIdentityResult>;
  resume(input: ThreadResumeRequest): Promise<ThreadIdentityResult>;
  fork(input: ThreadForkRequest): Promise<ThreadIdentityResult>;
  stop(input: ThreadStopRequest): Promise<void>;
  discard(input: ThreadIdentityRequest): Promise<void>;
  archive(input: ThreadIdentityRequest): Promise<void>;
  unarchive(input: ThreadIdentityRequest): Promise<void>;
  setName(input: ThreadNameSetRequest): Promise<void>;
  clearGoal(input: ThreadIdentityRequest): Promise<void>;
  startTurn(input: TurnStartRequest): Promise<void>;
  steerTurn(input: TurnSteerRequest): Promise<void>;
  configureSkills(input: SkillsConfigureRequest): Promise<void>;
  close(): Promise<void>;
}

Provider declaration

The contract uses the liked 1.0 declaration shape. It makes static choices reviewable before code starts.

export interface ProviderDeclaration {
  id: string;
  displayName: string;
  family?: string;
  icon?: string;
  visibility: "always" | "installed";
  capabilities: ProviderCapabilities;
  composerActions: readonly ("plan" | "goal")[];
  strings?: ProviderStrings;
  serviceTiers?: readonly ProviderOption[];
  reasoningLevels?: readonly ProviderOption[];
  maintenance?: ProviderMaintenance;
  extensionKinds?: Readonly<Record<string, ProviderExtensionKind>>;
  models?: {
    fallback?: readonly ProviderFallbackModel[];
    scope?: "host" | "workspace";
  };
  env?: { passthrough: readonly string[] };
  bridgeOptions?: JsonObject;
  nativeRoots?: {
    skills?: readonly ProviderNativeRoot[];
    commands?: readonly ProviderNativeRoot[];
    resolveOnHost?: boolean;
  };
}

export interface ProviderCapabilities {
  supportsServiceTier: boolean;
  supportsNativeUserQuestion: boolean;
  fork: "none" | "thread" | "checkpoint";
  supportsManualCompaction: boolean;
  supportsThreadArchive: boolean;
  supportsThreadRename: boolean;
  permissionModes: readonly ("accept-edits" | "auto" | "full")[];
  reasoningLevels: readonly string[];
}

export interface ProviderStrings {
  signInHint: string;
  expiredHint: string;
  installUrl: string;
  brandPrefix?: string;
  planModeCopy?: string;
  iconTint?: { light: string; dark: string };
}

export interface ProviderOptionsContext {
  threadId: string;
  projectId: string;
  model: string;
  permissionMode: "accept-edits" | "auto" | "full";
  promptMode?: "plan";
  settings: Readonly<Record<string, string | boolean | undefined>>;
}

export interface ProviderFallbackModel {
  id: string;
  displayName: string;
  description: string;
  supportedReasoningEfforts: readonly {
    reasoningEffort: string;
    description: string;
  }[];
  defaultReasoningEffort: string;
  isDefault: boolean;
}

export interface ProviderOption {
  id: string;
  label: string;
  description?: string;
}

export interface ProviderExtensionKind {
  item?: StandardSchemaV1;
  state?: StandardSchemaV1;
}

export interface ProviderNativeRoot {
  id: string;
  path: string;
}

The build checks each extension item and state schema. The runtime rejects an undeclared extension kind.

Bridge protocol

bb.providers.bridge uses newline-delimited JSON-RPC 2.0. The handshake selects a thread-delta grammar in the supported range.

The public module is @bb/providers/bridge. It contains schemas, types, a bridge factory, and a conformance kit.

Transport and entry

export interface ProviderBridgeEntry {
  apiVersion: 1;
  definition: ProviderBridgeDefinition;
}

export interface ProviderBridgeDefinition {
  start?(context: ProviderBridgeContext): void | Promise<void>;
  handleLine(line: string): void;
  onClose?(): void | Promise<void>;
  onSigterm?(): void | Promise<void>;
  onSigint?(): void | Promise<void>;
}

export interface ProviderBridgeContext {
  pluginId: string;
  providerId: string;
  dataDir: string;
  tempDir: string;
  signal: AbortSignal;
}

export function defineProviderBridge(
  definition: ProviderBridgeDefinition,
): ProviderBridgeEntry;

One line has a 64 MiB limit. An overflow closes the bridge with a protocol error.

Handshake

export interface BridgeCapabilities {
  sessionRestore: boolean;
  threadArchive: boolean;
  threadRename: boolean;
  threadGoalClear: boolean;
  fork: "none" | "thread" | "checkpoint";
  approvalEnforcedBy: "runtime" | "provider";
  grammarVersions: readonly [minimum: number, maximum: number];
  steerMode: "inject" | "queue";
  skills: { configure: boolean };
}

The runtime chooses the highest common grammar. A bridge cannot report a capability wider than its static declaration.

Runtime requests

export interface BridgeExecutionOptions {
  model?: string;
  serviceTier?: string;
  reasoningLevel?: string;
  promptMode?: "plan";
  instructions?: string;
  envVars?: Readonly<Record<string, string>>;
  providerOptions?: JsonObject;
}

Bridge requests and notifications

The bridge can request one tool call or one user interaction. The shared request service tracks both request types.

export type PendingInteractionPayload =
  | ApprovalInteraction
  | QuestionInteraction
  | SecretInteraction
  | OpenInteraction;

export interface SecretInteraction {
  kind: "secret";
  requestKey: string;
  title: string;
  prompt: string;
  secretName: string;
}

export type PendingInteractionResolution =
  | { kind: "approval"; decision: "allow_once" | "allow_for_session" | "deny" }
  | { kind: "answer"; answers: readonly string[] }
  | { kind: "secret"; stored: boolean }
  | { kind: "submitted"; data: JsonValue }
  | { kind: "interrupted"; reason: string };

The secret value never enters a delta or a server log. The kernel secrets port stores it.

Thread deltas

A thread/delta notification contains one ordered ThreadDelta[]. Each item event uses a stable DeltaItemKey.

export interface DeltaItemKey {
  providerItemId?: string;
  channel?: string;
  parentRef?: string;
}

export type DeltaItem =
  | CommandItem | FileChangeItem | ToolItem | CompactionItem
  | AgentMessageItem | ReasoningItem | PlanItem
  | WebSearchItem | WebFetchItem | ImageViewItem
  | BackgroundTaskItem | FileReadItem | SearchItem
  | DelegationItem | PlanStepsItem | ExtensionItem;

export type ThreadDelta =
  | InputAcceptedDelta | InputProviderDelta
  | TurnOpenDelta | TurnBoundaryDelta | TurnDiffDelta
  | ItemOpenDelta | ItemCloseDelta | ItemProgressDelta
  | TextDelta | TextCloseDelta | OutputDelta | CommandOutputSnapshotDelta
  | UsageDelta | ContextWindowDelta | ContextCompactedDelta | ContextClearedDelta
  | ThreadStartedDelta | ThreadIdentityDelta | ThreadNameDelta
  | ExtensionStateDelta | ProviderRateLimitsDelta | ProviderErrorDelta
  | ProviderModelFallbackDelta | ProviderWarningDelta | UnhandledDelta
  | SessionEndedDelta | SessionResetDelta;

Item close events repeat the full item. This rule makes event replay independent from bridge memory.

The grammar accepts text channels agentMessage, reasoningSummary, reasoningText, and plan. It accepts output channels command and fileChange.

Unknown events use ProviderRawEvent. A coverage value of noise permits a drop after diagnostics.

Item contracts

All item variants have a type field. An extension item also has a declared schema.

export interface DeltaFileChange {
  path: string;
  kind: "add" | "update" | "delete";
  movePath?: string;
  diff?: string;
  oldText?: string;
  newText?: string;
}

export interface BackgroundTaskItem {
  type: "backgroundTask";
  familyId: string;
  taskType: string;
  description: string;
  status: string;
  taskStatus: string;
  skipTranscript: boolean;
  workflowName?: string;
  workflow?: JsonValue;
  usage?: ProviderTokenUsage;
  summary?: string;
  error?: string;
  outputFile?: string;
}

export interface DelegationItem {
  type: "delegation";
  childRef: string;
  label: string;
  background: boolean;
  summary?: string;
}

export interface PlanStepsItem {
  type: "planSteps";
  steps: readonly ThreadPlanStep[];
  explanation?: string;
}

export interface ExtensionItem {
  type: "extension";
  kind: string;
  payload: JsonValue;
}

Maintenance, health, and usage

export interface ProviderMaintenance {
  health?: boolean;
  usage?: boolean;
  installation?: boolean;
}

export interface ProviderHealth {
  status: "ok" | "not_installed" | "unauthenticated" | "expired" | "unsupported" | "error";
  statusMessage?: string;
  accountEmail?: string;
  planLabel?: string;
  installedVersion?: string;
  minimumSupportedVersion?: string;
  canInstall: boolean;
  canUpdate: boolean;
  loginCommand?: string;
}

export type ProviderUsage =
  | { status: "ok"; accountEmail?: string; planLabel?: string; windows: readonly ProviderUsageWindow[] }
  | { status: "not_installed" | "unauthenticated" | "expired" }
  | { status: "error"; message: string; accountEmail?: string; planLabel?: string };

export interface ProviderUsageWindow {
  label: string;
  usedPercent: number;
  resetsAt: string | null;
  cost?: { usedUsdCents: number; limitUsdCents: number };
}

export interface ProviderInstallationStatus {
  executableName: string;
  executablePath: string | null;
  installed: boolean;
  installSource: "npm-global" | "path" | "download" | "unknown";
  currentVersion: string | null;
  latestVersion: string | null;
  minimumSupportedVersion: string | null;
  npmPackageName?: string;
  npmGlobalPackageVersion?: string | null;
  installAction?: ProviderInstallationAction;
  needsUpdate: boolean;
  versionUnsupported: boolean;
}

export interface ProviderInstallationCommand {
  command: string;
  args: readonly string[];
  displayCommand: string;
}

export interface ProviderInstallationAction {
  kind: "install" | "update";
  label: "Install" | "Update";
  command: ProviderInstallationCommand;
}

export type ProviderInstallationVerification =
  | { kind: "installed" }
  | { kind: "version_changed"; previousVersion: string | null }
  | { kind: "version_at_least"; version: string };

export type ProviderInstallationRunResult =
  | { available: false; message: string }
  | {
      available: true;
      command: ProviderInstallationCommand;
      verification: ProviderInstallationVerification;
    };

An install run returns the exact command and a verification rule. Shared maintenance code verifies the result after execution.

Recovery and errors

export type ProviderRecoveryKind =
  | "restart-process"
  | "resume-fresh"
  | "reauthenticate"
  | "reinstall"
  | "none";

export interface ProviderRecoveryHint {
  kind: ProviderRecoveryKind;
  message: string;
  retryable: boolean;
}

export const BRIDGE_JSON_RPC_ERRORS = {
  INVALID_PARAMS: -32602,
  METHOD_NOT_FOUND: -32601,
  BRIDGE_ERROR: -32000,
  NO_ACTIVE_TURN: -32001,
  SESSION_NOT_RESTORABLE: -32002,
  FORK_CHECKPOINT_UNSUPPORTED: -32003,
} as const;

The supervisor rejects pending requests when a process exits. It records the recovery hint with the provider and session state.

Protocol runtime utilities

The bridge module provides a small runtime above the host services. Provider adapters do not write their own JSON-RPC loop.

export interface ProviderRequestClient {
  request<T>(method: string, params: JsonValue, options?: { signal?: AbortSignal }): Promise<T>;
  notify(method: string, params: JsonValue): void;
  handleResponse(response: BridgeJsonRpcResponse): boolean;
  rejectAll(message: string): void;
}

export interface ProviderVisibilityMetadata<TRawEvent> {
  parseRawEvent(input: unknown): TRawEvent | null;
  describeParsedRawEvent(event: TRawEvent): ProviderRawEventDescription;
  describeRawEvent(input: unknown): ProviderRawEventDescription;
}

Exports

Direct imports select exact code. Service and host-role tokens follow the current winner.

export interface ProviderDirectoryState {
  status: "loading" | "ready" | "error";
  providers: readonly ProviderRecord[];
}

export function useProviders(): ProviderDirectoryState;

export interface ProviderIconProps {
  providerId: string;
  className?: string;
}

export const ProviderIcon: ComponentType<ProviderIconProps>;

The provider declaration supplies its icon data. A plugin can export an exact React icon module when the declared asset cannot represent its mark. The 2.0 API drops the global experimental_providerIcon registration slot.

Host roles

export interface ProviderBridgeRole {
  initialize(input: InitializeRequest): Promise<InitializeResult>;
  request<M extends RuntimeBridgeMethod>(
    method: M,
    input: RuntimeBridgeInput<M>,
    options?: { signal?: AbortSignal },
  ): Promise<RuntimeBridgeOutput<M>>;
  toolResult(requestId: string | number, result: BridgeToolCallResult): Promise<void>;
  interactionResult(
    requestId: string | number,
    result: PendingInteractionResolution,
  ): Promise<void>;
  events(listener: (event: ProviderBridgeEvent) => void): Unsubscribe;
  close(reason: string): Promise<void>;
}

export interface ProviderNativeRootsRole {
  resolve(input: { providerId: string; cwd: string | null }): Promise<ProviderResolvedNativeRoots>;
}

The manifest joins both claims by the same provider key. The inspector shows the server generation and host generation in one record.

Shared provider host services

Provider roles use these services. They do not implement process and request control again.

export interface ProviderHostSupervisor {
  spawn(spec: ProviderLaunchSpec): Promise<ProviderProcess>;
  attach(identity: ProviderProcessIdentity): Promise<ProviderProcess>;
  getSession(scope: ProviderSessionScope): ProviderSupervisedSession | null;
  closeSession(scope: ProviderSessionScope, reason: string): Promise<void>;
  closeAll(providerId: string, reason: string): Promise<void>;
  childEnv(input: NodeJS.ProcessEnv, session: Readonly<Record<string, string>>): NodeJS.ProcessEnv;
  recordChildIo(scope: ProviderSessionScope, record: ProviderChildIoRecord): Promise<void>;
  retainWorker(scope: ProviderSessionScope): ProviderWorkerLease;
}

export interface ProviderHostRequests {
  createClient(process: ProviderProcess, options: ProviderRequestOptions): ProviderRequestClient;
  decodeResponse(input: unknown): BridgeJsonRpcResponse | null;
  decodeToolResult(input: unknown): DecodedBridgeToolResult;
  buildToolContent(input: ToolResultInput): readonly BridgeToolCallContent[];
  failScope(scope: ProviderSessionScope, message: string): void;
}

export interface ProviderHostMaintenance {
  resolveExecutable(command: string): Promise<string | null>;
  commandOutput(command: string, args: readonly string[]): Promise<string | null>;
  versionFrom(value: string | null): string | null;
  readCliVersion(command: string): Promise<string | null>;
  compareVersions(left: string, right: string): number;
  npmCommand(): string;
  formatCommand(command: string, args: readonly string[]): string;
  npmInstall(npmPackage: string): ProviderInstallationCommand;
  npmLatest(npmPackage: string): Promise<string | null>;
  npmProbe(npmPackage: string): Promise<NpmGlobalPackageProbe>;
  installSource(input: InstallSourceInput): ProviderInstallationSource;
  installationVerification(
    status: Pick<ProviderInstallationStatus, "currentVersion" | "latestVersion">,
    action: "install" | "update",
  ): ProviderInstallationVerification;
  downloadedInstaller(url: string): ProviderInstallationCommand;
  clampPercent(value: number): number;
}

export interface ProviderHostDeclarations {
  apply(source: string, declarations: readonly ProviderDeclaration[]): Promise<DeclarationDiff>;
  removeSource(source: string): Promise<void>;
  snapshot(): readonly ProviderDeclaration[];
  watch(listener: (diff: DeclarationDiff) => void): Unsubscribe;
  filterNativeRoots(input: ProviderResolvedNativeRootsInput): FilteredNativeRoots;
}

The supervisor gives every session one process identity. It applies timeouts, aborts, exit rejection, and kill escalation.

The declaration service applies one atomic diff. ACP does not need disposer maps or declaration polls in its server half.

Experimental host adapters

The host module exports experimental_resolveClaudePluginRoots and experimental_resolveVendorPluginRoots. Both return normalized native roots.

The ACP module exports these experimental helpers:

• experimental_acpAgentProbeSchema
• experimental_acpLaunchSpecSchema
• experimental_acpProviderBridge
• experimental_probeAcpAgent
• experimental_toolPresentation

These exports keep the experimental stability marker. They use the stable bridge and supervisor contracts underneath.

Example

This provider claims one server key and one host-role key. The user can choose another claimant for acme.

{
  "id": "acme.provider",
  "version": "2.0.0",
  "claims": [
    { "service": "bb.providers.provider", "version": "^1", "key": "acme", "default": true },
    { "hostRole": "bb.providers.bridge", "version": "^1", "key": "acme", "default": true }
  ],
  "requires": [{ "service": "bb.providers", "range": "^1" }],
  "artifacts": {
    "server": "./dist/server.js",
    "host": "./dist/host.js"
  }
}

// server.ts
import { defineServerPlugin } from "@get-bb/plugin/server";
import { bbProvider } from "@bb/providers/contracts";
import { declaration } from "./declaration.js";

export default defineServerPlugin((api) => {
  api.services.provide(bbProvider, {
    declaration: () => declaration,
    deriveOptions: async ({ settings }) => ({ apiBase: settings.apiBase ?? null }),
    models: (context) => api.host.roles.call("bb.providers.bridge", "model/list", context),
    health: (context) => api.host.roles.call("bb.providers.bridge", "provider/health", context),
    usage: (context) => api.host.roles.call("bb.providers.bridge", "provider/usage", context),
    installationStatus: (context) => api.host.roles.call("bb.providers.bridge", "provider/installation/status", context),
    runInstallation: (context, action) => api.host.roles.call("bb.providers.bridge", "provider/installation/run", { ...context, action }),
    resolveNativeRoots: (context) => api.host.roles.call("bb.providers.nativeRoots", "resolve", context),
    openSession: (context) => api.host.roles.session("bb.providers.bridge", context),
  }, { key: "acme" });
});

// host.ts
import { defineHostPlugin } from "@get-bb/plugin/host";
import { bbProviderBridgeRole, bbProviderHostSupervisor } from "@bb/providers/host";
import { createAcmeBridge } from "./acme-bridge.js";

export default defineHostPlugin(async (api) => {
  const supervisor = await api.services.use(bbProviderHostSupervisor);
  api.hostRoles.provide(
    bbProviderBridgeRole,
    createAcmeBridge({ supervisor, declaration }),
    { key: "acme" },
  );
});

The runtime stages both halves before it changes the winner. A failed host candidate cannot remove the current acme provider.

Covers