7. Provider bridges — @get-bb/plugin-sdk/bridge

@get-bb/plugin-sdk/bridge is the surface a provider plugin's bridge (host role provider-bridge, a child process) and its server half share. It re-exports @bb/bridge-kit/runtime — defineBridge, BridgeRuntime, runBridge, childEnv, autoDeny, every protocol v3 schema, and the declaration helpers — and adds defineProviderDeclaration and bridgeHostRole. Source: next/packages/plugin-sdk/src/bridge/index.ts. Kernel: next/packages/bridge-kit/src/ (paths below are relative to it unless noted). Spec: 06 §2–§4, §7–§9. Where spec and build differ, the build wins and the row says so. Bridges may be written in any language (06 §4, A11); the kit is a convenience over line-delimited JSON-RPC 2.0 on stdio.

7.1 A provider plugin's anatomy

A provider plugin is an ordinary plugin with three halves: server.ts (hooks), app.tsx (renderers, optional), host.ts (the bridge). Only the declaration and the bridge are mandatory (06 §2; 11c §0).

// host.ts
import { defineHostEntry } from "@get-bb/plugin-sdk/host";
import { defineBridge } from "@get-bb/plugin-sdk/bridge";
export default defineHostEntry({
  roles: { "provider-bridge": { codex: defineBridge(codexBridge) } },
  signals: {}, async dispose() {},
});

Server half (06 §3.1): one ctx.provide(providerHooks, { deriveProviderOptions, bridgeEnv, modelCatalog }, providerFacts(declaration)) per provider. deriveProviderOptions runs once per thread.create|send|fork and becomes ExecutionOptions.providerOptions (2 s timeout; 502 provider_options_failed). bridgeEnv becomes RoleSpec.env for the bridge child (BB_* names rejected with bridge_env_reserved; 502 bridge_env_failed). modelCatalog returns ModelDecl[] | null; null means use the bridge probe. A plugin with no server half gets {} options, {} env, and the probe. As built, the providers plugin and the providerHooks contract are spec-only in next/; providerFacts exists.

7.2 ProviderDeclaration

Every field is required; nothing defaults (06 §3). Validated by the loader without executing code and again by defineProviderDeclaration. As built: declaration.ts.

7.3 defineBridge, runBridge, BridgeRuntime

ProviderBridge is { declarations: ProviderDeclaration[]; initialize(params: InitializeParams, ctx): BridgeCapabilities; methods: BridgeMethods }. Required handlers: thread/start, turn/start, thread/stop, thread/discard, shutdown. Every other method is optional; an advertised method with no handler answers METHOD_NOT_FOUND.

Dispatch (runtime/bridge.ts invoke): parse params (INVALID_PARAMS with data.issues) → pick the declaration by params.providerId (the first declaration when the method carries none; an unknown id is INVALID_PARAMS) → isMethodAdvertised (CAPABILITY_NOT_ADVERTISED) → thread/fork with a non-null sourceCheckpointId needs capabilities.fork === "checkpoint" (FORK_CHECKPOINT_UNSUPPORTED) → the handler → the result is parsed with coreToBridgeSpecs[method].result. Any method before initialize is BRIDGE_ERROR. shutdown is answered {} first; then it, or EOF (which runs the shutdown handler with graceMs: 0), answers every outstanding request with INTERACTION_INTERRUPTED. Core sends the bridge no notifications.

BridgeContext, the ctx every handler receives:

Core → bridge methods (06 §4.3; protocol/requests.ts coreToBridgeRequests). S = {providerId, cwd, bridgeOptions}; Ref = {threadId, providerThreadId}; SP = SessionParams (§7.9).

thread/stop {intent: "interrupt"} expects settlement deltas within the stop grace; release expects none. Compaction is not a method: it is turn/start with actions: ["compact"] and empty input; a refused compaction settles with provider.warning {category: "compaction-skipped"} (06 §4.3).

Bridge → core requests (06 §4.4; bridgeToCoreRequests). Both block until core answers. Keys are provider-native; the host driver maps them through the assembler. requestKey forms the dedupe key <providerId>:<providerThreadId>:<requestKey>.

Notifications, bridge → core (06 §4.5; protocol/notifications.ts bridgeNotifications). thread/delta is strict; the rest are additive.

export const codexBridge = defineBridge({
  declarations: [codexDeclaration],
  initialize: () => ({ sessionRestore: true, threadArchive: false, threadRename: false, threadGoal: true,
    fork: "checkpoint", approvalEnforcedBy: "runtime", steer: "native" }),
  methods: {
    "thread/start": async (p, ctx) => {
      ctx.emitForSession(p.threadId, { method: "thread/identity", params: { providerThreadId: id, sessionRestorable: true } });
      ctx.sendThreadDeltas(p.threadId, [{ kind: "session.reset" }]);
      return { providerThreadId: id, sessionRestorable: true };
    },
    "turn/start": async (p, ctx) => { /* input.accepted, turn.open, items…, turn.boundary */ return {}; },
    "thread/stop": async () => ({}), "thread/discard": async () => ({}), shutdown: async () => ({}),
  },
});

7.4 Handshake and capabilities

initialize carries {protocol: {min, max}, client: {name: "bb", version}, plugin: {id, version}, providerIds} and answers {protocol, capabilities} (06 §4.2; protocol/handshake.ts). The runtime picks the highest version in both ranges; no intersection is PROTOCOL_UNSUPPORTED with {core, bridge} in error.data. It then parses the bridge's capabilities and checks every declaration with capabilityWidens. A second initialize is BRIDGE_ERROR. Versioning rule: the delta grammar is strict and enters persistence, so any grammar change bumps max; requests and results are looseObject (// additive-wire) and may gain fields without a bump.

7.5 The delta grammar

thread/delta {threadId, deltas} is strict (protocol/deltas.ts deltaSchema; 06 §4.6). Scoping is explicit: the eight kinds in SCOPED_DELTA_KINDS carry scope: "turn", turnKey or scope: "thread" (scopeSchema), with no default. turnKey is z.string().min(1).nullable(); null means the bridge's current open turn, and a non-null key must be one this bridge opened. The "04 event" column is what the host assembler emits; the bridge never sees it.

Rules a bridge must hold (06 §4.6, §5.2): a turn-scoped delta with no open turn is never dropped — it becomes a thread-scoped provider.unhandled (turnless/unhandled); an unrequested turn.open (no handed-in turn id) takes the same path (turn/bound-to-requested); scope: "thread" is for a task that finishes after its turn or a compaction between turns; an item's scope is fixed at open. The driver enforces GRAMMAR_RULE_IDS live (grammar/rules.ts): events/schema-valid, scope/explicit, item/presentation-present, item/extension-kind-declared, turn/vouched-keys-only, item/opens-before-delta, item/settles-once; The driver drops a delta that breaks a rule and logs bridge/log warn naming the rule.

7.6 Items

An item key (itemKeySchema, 06 §4.6/§4.10) is {providerItemId, channel, parentRef}, each string | null, at least one non-null, no part containing U+001F (ITEM_KEY_SEPARATOR). The key string is the parts joined by U+001F; parentRef names a parent by its key string or its providerItemId and becomes parentItemId. providerItemId is copied into payload.providerItemId by the assembler for correlation and is never the stored id (R4). itemStatusSchema is pending | completed | failed | interrupted; denied is approval, not a status. Payloads are strict (protocol/items.ts coreItemSchema), snake_case (R27; D11 built wins).

detachesMessage(kind) is true for command, tool, file_change, task, and every extension kind: their item.open closes the open message stream in the same scope (message/auto-detach). extensionKindNameSchema enforces EXTENSION_KIND_PATTERN. Delegation is task {role: "delegation"} with child items nested through parentRef; todo is a fact, not an item (06 §4.7).

7.7 Presentation and render intents

presentationSchema (06 §4.7, I16; protocol/common.ts): {label (min 1), icon (min 1), title?, detail?, suppress?, tint?: neutral|info|success|warning|danger}. The optionals are the only optionals in the grammar; omission means "no such line". Presentation is required on item.open and item.close, nullable on item.progress, persisted per event; the row shows the latest. label is a verb phrase for the current status ("Running tests" → "Ran tests"); the pending/completed pair is expressed by sending a new presentation on close. renderIntentSchema is generic | terminal | diff | search | read | list | web | image; it lives on command.intent, tool.intent, and DynamicTool.presentation.intent, and replaces every tool-name classifier in the UI. approvalStateSchema is "waiting" | "denied" | null.

7.8 Approvals, questions, interactions

interactionRequestSchema (06 §4.4; protocol/interactions.ts) is one of: {kind: "approval", subject: ApprovalSubject, reason \| null, decisions: ApprovalDecision[] (min 1)}, {kind: "question", questions: Question[] (1–4, unique ids)}, or {kind: "<pluginId>/<kind>", title (≤ 200), data: JsonValue} for a kind declared in contributes.interactionKinds. Subjects are closed and snake_case (R27):

approvalDecisionSchema is allow_once | allow_for_session | deny. grantProfileSchema is {network: {enabled: boolean | null} | null, fileSystem: {read: string[], write: string[]} | null}. commandActionSchema is read {command, name, path} | listFiles {command, path | null} | search {command, query | null, path | null} | unknown {command}. questionSchema is {id, prompt, shortLabel | null, multiSelect, options: {value, label, description | null}[] (≤ 4, unique), allowFreeText} with options empty only when allowFreeText; answerSchema is {selected: string[] (≤ 4), freeText: string | null (≤ 4096, non-blank)}. interactionResolutionSchema is {kind: "approval", decision: allow_once|allow_for_session, granted: GrantProfile | null}, {kind: "approval", decision: "deny", granted: null}, {kind: "answer", answers: Record<questionId, Answer>}, {kind: "submitted", data}, or {kind: "interrupted"}. A tool_use subject is not core; a provider declares <providerId>/tool_use as an open kind (R27).

Flow (06 §8): core validates and dedupes, then auto-denies an approval when policy.escalation === "deny" and approvalEnforcedBy === "runtime" (actor system:auto-deny); a provider-enforcing bridge applies autoDeny() itself. Questions and open kinds are never auto-denied. Otherwise a pending_interactions row opens and the JSON-RPC id waits for interaction.resolve. Interrupt, bridge exit, or host disconnect answers outstanding ids with INTERACTION_INTERRUPTED and marks rows interrupted. allow_for_session grants persist on the thread and reach the bridge again only through providerOptions if the plugin's deriveProviderOptions opts in.

7.9 Execution options and prompt input

executionOptionsSchema (06 §7.1; protocol/common.ts): {model, reasoningLevel: string | null, serviceTier: string | null, permission: PermissionPolicy, instructions, providerOptions: Record<string, JsonValue>}. It rides every thread/* and turn/* command; the bridge reconciles and announces a rebuild with session/replaced. permissionPolicySchema is the three product presets: {mode: "accept-edits", scope: "workspace", reviewer: "user", escalation: ask|deny}, {mode: "auto", scope: "workspace", reviewer: "automatic", escalation: ask|deny}, {mode: "full", scope: "full", reviewer: null, escalation: null}; permissionModeSchema is the mode enum. Resolution order, clamps, and ResolvedExecutionOptions provenance are server-side (06 §7.2) and never cross the wire (README BK-8).

promptInputSchema (06 §4.3) is text {text, mentions: PromptMention[], visibility}, image {url, visibility}, localImage {path, visibility}, or localFile {path, name | null, sizeBytes | null, mimeType | null, visibility}. promptVisibilitySchema is "user" | "agent-only"; agent-only reaches the provider and is omitted from the user-message row; the bridge only forwards it. promptMentionSchema is {start, end, resource: {kind, label, …}} (loose; the composer owns resources).

sessionParamsSchema: {threadId, providerId, cwd, workspace: {root, writeRoots}, env, options: ExecutionOptions, tools: DynamicTool[], disallowedTools: string[], instructionMode: "append" | "replace", actions: string[], bridgeOptions}. workspace and env are filled by the host driver, never by core; env is the ambient BB_* set (BB_CLI, BB_SERVER_URL, BB_THREAD_ID, BB_PROJECT_ID, BB_ENVIRONMENT_ID, BB_THREAD_STORAGE, BB_HOST_ID, plus threads/agent-config names); pass it to agent shells through childEnv. turnParamsSchema is {threadId, providerThreadId, turnId, input: PromptInput[], clientRequestId, options, actions} as core sends the driver; turnStartParamsSchema omits turnId (no provider key exists yet) and turnSteerParamsSchema keeps it holding the provider's own key (README "Notes"; 06 §4.3). There is no expectedTurnId. threadRefSchema is {threadId, providerThreadId}; sessionIdentitySchema is {providerThreadId, sessionRestorable}. dynamicToolSchema is {name, description, inputSchema: JsonObject, presentation: {label: {pending, completed}, icon, intent, suppress}}; the bridge exposes these to the agent and answers calls through ctx.toolCall.

7.10 Recovery, errors, warnings

recoveryHintSchema (06 §4.5): restart-process (account restart), resume-fresh (session file gone), reauthenticate, reinstall, none. Send it with ctx.recovery; the providers plugin acts and records provider.warning {category: "recovery"}. errorCategorySchema (persisted, snake_case): context_window_exceeded, billing, budget_exceeded, internal, max_output_tokens, max_turns, overloaded, policy, rate_limit, sandbox, stream_disconnected, structured_output_retries, thread_rollback_failed, too_many_failed_attempts, unauthorized, unknown. A quota failure is provider.error {category: "rate_limit", settlesTurn: true} plus provider.rateLimits with resetsAt set; provider-retry keys on exactly those two. warningCategorySchema: deprecation, config, general, compaction-skipped, turn-watchdog, session-replaced, recovery. rateLimitStateSchema: {status: allowed|warning|blocked|unknown, kind: subscription-window|credits|spend-control|unknown, windows: {providerKey | null, label | null, status, resetsAtMs | null}[], resetsAt: number | null, reachedReason | null, overageStatus: allowed|warning|rejected|unavailable | null, overageReason | null}.

7.11 Usage, maintenance, skills, models

Usage rides the usage delta: tokenBreakdownSchema is {totalTokens, inputTokens, cachedInputTokens, outputTokens, reasoningOutputTokens}; send total: null to let the assembler accumulate, or the provider's exact totals (06 §4.8 "one delta"). Maintenance methods are sessionless and run on a maintenance bridge instance in the host's scratch environment (06 §14.1). providerHealthSchema: {status: ready|not_installed|unauthenticated|expired|unsupported_version|unknown, statusMessage | null, accountEmail | null, planLabel | null, installedVersion | null, minimumSupportedVersion | null, canInstall, canUpdate, loginCommand | null}. providerUsageSchema: {status: "ok", accountEmail | null, planLabel | null, windows: UsageWindow[]} or {status: not_installed|unauthenticated|expired} or {status: "error", message, planLabel | null, accountEmail | null}; usageWindowSchema is {label, usedPercent, resetsAt: string | null, cost: {usedUsdCents, limitUsdCents} | null}. installationStatusSchema: {executableName, executablePath | null, installed, installSource: notInstalled|npmGlobal|external, currentVersion | null, latestVersion | null, minimumSupportedVersion | null, npmPackageName | null, npmGlobalPackageVersion | null, installAction: {kind: install|update, label: Install|Update, command} | null, needsUpdate, versionUnsupported}. installCommandSchema is {command, args: string[] (≤ 64), displayCommand}; installVerificationSchema is {kind: "installed"} | {kind: "version_changed", previousVersion} | {kind: "version_at_least", version}; core runs the command and verifies.

Skills (06 §9): injection is skills/configure {threadId, roots} with skillRootSchema {id, path, label} — staged SKILL.md directories the bridge converts to its native form. Discovery is declarative: skillScanRootSchema {scope: user|project, path, format: skill-md|claude-plugin|codex-plugin-cache, walkParents, recursive, label | null} expanded on the host (~, $CODEX_HOME, $OPENCODE_CONFIG_DIR); layouts that need code set skills.discover: true and answer skills/discover with discoveredSkillSchema {name, description, path, scope: user|project, source}. Models (06 §14.1): modelDeclSchema is {id, label, description, reasoningLevels: string[], defaultReasoningLevel | null, serviceTiers: string[], isDefault}; model/list runs only for models.catalog: "bridge", cached per (providerId, hostId, cwd) for 10 min; the provider default is the isDefault model and its defaultReasoningLevel.

7.12 Helpers and constants

The assembler (assembler/assembler.ts; 06 §5) runs on the host, one instance per (bridge process, thread), and the bridge never sees it: the driver feeds it thread/delta and it emits section 04 events synchronously, one delta → one event, with no timers. It binds turn keys FIFO to core-minted turnIds, mints itemIds as <entropy>-<serial>, copies key.providerItemId into payload.providerItemId, validates extension kinds against their JSON schemas (createExtensionKinds), settles zero-work turns, routes turnless deltas to provider.unhandled, and buffers unknown-key output up to 256 KiB. Its rule ids (ASSEMBLER_RULE_IDS, 06 §5.2): ids/minted-centrally, turn/bound-to-requested, turn/opens-only-explicitly, turn/accepted-input-queues, turn/zero-work-settles, item/opens-before-delta, item/close-shape-wins, item/settles-once, item/scope-fixed-at-open, message/auto-detach, stateless/one-delta-one-event, usage/accumulate, turnless/unhandled, settle/error, session/reset-flushes, fallback/dedup. The conformance kit (06 §10; 33 rule ids) and record mode (06 §11) live in @bb/bridge-kit/conformance; the spec's @get-bb/plugin-sdk/bridge/conformance subpath is not in the SDK's package.json#exports as built.

7.13 Schema index

7.14 Differences from the old tree's docs/provider-plugin-api.md