Provider plugin API

Target state (42 decisions, 2026-08-20), the morph plan, and the verification and guardrail program. Nothing here describes today's code.

Principles

1. Zero first-party privilege. First-party providers use only the public API. Every special case becomes a public primitive or is deleted.
2. Each fact lives in one place. A capability is declared or reported, never both. Presentation comes from the bridge, never from core tables.
3. Core understands a small semantic vocabulary. Everything else is an extension kind with mandatory declarative presentation.
4. Every client renders everything without plugin code. Plugin renderers are an upgrade on web; mobile renders the declarative base.

1. Registration plugin server code

bb.providers.register({
  id: string,                      // flat; first registration wins; no reservation table
  displayName: string,
  family?: string,                 // grouping only; replaces the acp- prefix
  icon: { glyph: string } | { asset: string },
  strings: {
    signInHint: string, expiredHint: string, installUrl: string,
    brandPrefix?: string, planModeCopy?: string,
    iconTint?: { light: string, dark: string },
  },
  permissionModes: ("accept-edits" | "auto" | "full")[],   // closed core enum (policy)
  reasoningLevels: { id, label, description? }[],          // fallback; model/list is precise
  serviceTiers?: { id, label, description? }[],            // fallback; model/list is precise
  fork: "none" | "tip" | "checkpoint",                     // exact per instance
  supportsNativeUserQuestion: boolean,
  supportsManualCompaction: boolean,
  maintenance: { health: boolean, usage: boolean, installation: boolean },
  composerActions: ({ kind: "plan" } | { name, trigger, description })[],
  extensionKinds: { [name: string]: { item?: Schema, state?: Schema } },
  models: { fallback?: Model[] },                          // cold-cache placeholder only
  env: { passthrough: string[] },                          // daemon env the bridge may read
  deriveProviderOptions(ctx: {
    threadId, projectId, model, permissionMode, promptMode?, settings,
  }): JsonValue,                                           // called on every command
}) => { dispose(): void }

• One plugin registers N providers. User-configured instances are rows in the plugin's own settings that produce registrations at runtime.
• The plugin learns per-instance truth itself: probe through its host RPC, register conservatively while the host is offline, re-register on connect.
• Picker order and default provider are user settings. The initial default is plugin install order.
• Capabilities project to exactly one client shape, ProviderInfo.
• Third-party ACP agents (Amp) register the same way, with a bridge built from the published ACP kit.

2. Bridge plugin bb.host artifact, runs on the host

export const providerBridge = defineProviderBridge({ handleLine, start?, onClose? })

// Handshake — reported per session, never declared
initialize → {
  grammarVersions: [min, max],
  sessionRestore, threadArchive, threadRename: boolean,
  approvalEnforcedBy: "runtime" | "provider",
  steerMode: "inject" | "queue",
}

// Runtime → bridge
model/list · thread/{start,resume,fork,stop,discard,archive,unarchive,name/set}
turn/{start,steer} · skills/configure {roots: Root[]} · skills/scanRoots {cwd}
provider/{health,usage,installation/status,installation/run}

// Execution options on every command — no provider-named field
{ model, serviceTier, reasoningLevel, promptMode?: "plan", instructions,
  providerOptions: JsonValue } & PermissionPolicy
// Tool definitions handed to the bridge carry `presentation`

// Bridge → runtime
thread/delta {deltas}          // one streaming dialect, one usage dialect
provider/recovery { kind: "sessionArchived" | "authRequired" | "restartRecommended"
                        | "staleTurn" | "rateLimited", message, retryable }
session/replaced
item/tool/call · interaction/request

• One process per provider artifact. The bridge supervises any children. The runtime never scopes processes per thread and never matches error text.
• The assembler stays in the daemon, is generic for extension kinds, and ships with the conformance kit and JSON-RPC harness as @get-bb/plugin-sdk/provider-bridge/testing.
• The ACP bridge ships as @get-bb/plugin-sdk/provider-bridge/acp; the first-party ACP plugin consumes the same kit.

3. Vocabulary thread/delta v3 → domain events

// Core item kinds — the kinds core acts on
message · reasoning · command · fileChange · fileRead · search · webSearch · webFetch
imageView · delegation · planSteps · compaction · tool

// Extension item kinds — plugin-declared schema, validated at server ingest
"<pluginId>/<name>"  { payload: JsonValue }

// Thread state (core): usage · contextWindow · rateLimits · modelFallback · contextCleared
// Extension state: "<pluginId>/<name>", latest snapshot wins per kind

// Delegation — one kind, replaces three encodings and thread/openWork
delegation { childRef, label, status, background: boolean, summary? }   // child turns link by parentRef

// Presentation — on EVERY item, attached by the bridge at item.open, persisted with the event
presentation: {
  label: { pending: string, completed: string },
  icon: { glyph: string } | { asset: string },
  title?: string,          // row headline
  detail?: string,         // short markdown summary, capped
  suppress?: boolean,      // low-value rows (TodoWrite, ToolSearch)
  tint?: { light: string, dark: string },
}

Genericity rule. Model fallback, context cleared, compaction skipped, and background work stay core. Codex goals and the Codex macos permission profile move to codex extension kinds with read-time conversion of persisted rows.

4. Interactions

command · fileChange
toolUse { tool, presentation }
permissionGrant

userQuestion   // core renderer
planReview     // core renderer
"<pluginId>/<kind>"  // plugin renderer via pendingInteraction slot

5. Projection and rendering

// Server-side thread-view folds every item into one row shape. No tool-name tables.
TimelineRow { kind: string, payload: JsonValue, presentation: Presentation, ... }

// Plugin web renderer — own extension kinds and own generic `tool` items only
app.slots.timelineRenderer({ kind, component })
  component props: { row, payload, presentation, thread, Original }

// Open requests
app.slots.pendingInteraction({ kind, component })   // exists today for plugin interactions

// Directory
app.useProviders() · bb.sdk.providers.list()

• Core kinds always use core renderers, customized through presentation only.
• Provider frontend bundles load lazily on the first thread of that provider, through a manifest flag any plugin can use. They never enter the boot payload.
• Mobile renders the declarative base for every kind, including the extension fallback.

6. Settings and product surfaces

• Core renders a generic provider entry: name, icon, health, usage, install, order, default. The plugin's settings-section slot owns its rich pane.
• Declared strings feed usage banners, pickers, mobile, and the agent guide.
• Plan mode is a bb prompt mode for any provider that declares the plan composer action; each bridge maps it natively.
• model/list is the only live model source; models.fallback is the only placeholder; customModels is a setting of the owning plugin.
• Host AI services (voice, inference) are a generic plugin service registered through host RPC; core routes to the user's chosen service.
• bb provider list prints capabilities; bb thread spawn --reasoning validates against the provider's list.

7. Deleted from core

Workstreams

One gh stack per workstream, landed one layer at a time on main. No toggles. Each workstream is a bb thread in its own worktree; this thread coordinates.

Regression confidence — what makes "no regression" checkable

The plan abandons byte-equivalence with the old translators on purpose, which removes the regression oracle the goldens provide today. The calibration sessions are scripted fakes we wrote, the integration suite runs a fake adapter, and mobile shipped a key-mismatch regression unnoticed. These five additions and two sequencing rules replace the lost oracle with machine checks on real data.

Sequencing rules. (1) Pi stays on its in-process path until the spike proves RPC parity on recordings. (2) The mobile kind-map exhaustiveness test lands in the contract PR, so WS3 cannot add a kind that mobile does not render.

Corpus — Sawyer's real sessions as test cases

Extracted 2026-08-21 from the production bb.db (read-only) into ~/.bb/provider-corpus/. Private by default: it holds real prompts, code, command output, and paths. Tests read it through BB_PROVIDER_CORPUS_DIR and skip when it is absent. A small redacted subset for CI is a separate, explicitly approved step.

Selection

Per provider: the 10 largest threads, 25 random threads with 200–3,000 events, and up to 12 threads per feature. Feature coverage in the corpus: goals 1 (codex has exactly one goal thread), background tasks 12, web/image 24, compaction 15, user questions 12, permission grants 7 (all that exist), non-completed turns 24, model fallback 1 (all that exist), unhandled 24, nested/subagent 24, plan updates 12, errors 24, interrupted 24, turn diffs 12, renames 12, bb tools 19.

What the production profile says about the design

Verification — every layer must pass all of these

V3, V4, and V5 run in CI on every PR. V6 and V7 run on every layer that touches a bridge, the assembler, projection, or a renderer, and again before the stabilization PR for all providers.

Performance — budgets, measured against a committed baseline

Baselines are recorded once on main before the contract PR, on a committed fixture corpus: one 10k-event thread per provider from the calibration recordings, plus a 50-thread project. A budget breach fails CI.

Guardrails — static, enforced in CI, ratcheting toward zero

Risks and rollback

• Rollback unit is one PR. Each layer reverts cleanly. After v3 events are persisted, a revert renders those rows as generic tools until re-applied; the read-time converters stay in place across reverts.
• Pi RPC mode may lack what the SDK path has (tool proxy, model list, OAuth). The spike decides before WS4 schedules the rewrite.
• Goldens will change on purpose. Byte-equivalence with the old translators is abandoned. The coordinator reads every golden diff; V6 live QA is the second line.
• Amp (the only external provider) uses the customAcpAgents config path. The ACP plugin reads it for two minor releases with a deprecation log; a migration issue goes to smsunarto/bb-plugins when the ACP kit ships.
• Enrolled daemons update through the normal protocol bump. Wire changes are batched into as few layers as possible, one bump each.