API reference

The public surface of @get-bb/plugin-sdk 0.4.16 that a provider plugin uses, by subpath. Names are given exactly as exported; a member that still carries experimental_ is listed that way. Types are listed by name; their JSDoc in the published .d.ts bundle is the contract.

Subpath map #

@get-bb/plugin-sdk (server side) #

bb.providers.register(declaration): { dispose(): void }

Register an agent provider this plugin contributes. The declaration is validated at call time; the provider joins the registry when the plugin load commits and appears in listings as exactly one client shape, ProviderInfo. Ids are flat and collision-rejected (first live registration wins; a later one from another plugin fails that plugin's load). A plugin may register several providers and may re-register after dispose(); registrations are replaced wholesale on reload. Declaring a provider without a bb.host entry fails the load.

const registration = bb.providers.register({ id: "echo-agent", displayName: "Echo", /* … */ });
// later, for a settings-driven re-declaration:
registration.dispose();
bb.providers.register(nextDeclaration);

bb.experimental_aiServices.register({ id, displayName, kinds }): { dispose(): void } experimental

Register an AI service served from the plugin's host entry; kinds is a list of "inference" | "voice". Throws on an id another live plugin serves; refuses reserved ids; requires a bb.host entry. A declared entry that failed to build is not refused at the call: the service is staged unbound, carrying the build problem, the load fails on that problem after the factory runs, the same plugin's providers are retained as unavailable with it, and the unbound service is neither listed nor callable.

bb.agents.registerTool({ name, description, parameters, presentation?, instructions?, execute })

A native dynamic tool. presentation?: { label?: { pending, completed }, icon?: { glyph }, suppress?, tint? } says how calls read as a timeline row; the server fills what you leave out (a generic Running <name> / Ran <name> label, the plugin's bb.branding.icon when it is a host glyph name, then Toolbox) and hands one complete presentation to the bridge with the tool definition. Labels are capped at 80 characters. icon.glyph is a host glyph ("Workflow") or one of this plugin's own declared icons as "<pluginId>/<name>" (below); a namespaced glyph that names another plugin or an undeclared name rejects the tool registration.

defineRpcContract({ method: { input, output } })

Builds the Standard Schema contract shared by a plugin's server and host entries. Spread published contracts into your own to serve several at once:

import { defineRpcContract } from "@get-bb/plugin-sdk";
import { experimental_aiServicesHostContract } from "@get-bb/plugin-sdk/ai-services";
import { experimental_nativeRootsHostContract } from "@get-bb/plugin-sdk/host";

export const hostContract = defineRpcContract({
  ...experimental_aiServicesHostContract,
  ...experimental_nativeRootsHostContract,
  probeAgent: { input: z.object({ command: z.string() }).strict(), output: probeSchema },
});

bb.hosts.experimental_client({ contract, experimental_signals? }) experimental

A typed client for the plugin's own host entry: call(method, input, { hostId, signal? }), experimental_onWorkerExit(handler), experimental_onSignal(name, handler). Call methods only after registration completes (from a handler, background service or timer), never at factory time. The ACP and Pi plugins use it to probe agents and read settings on each connected host.

Types

PluginProviderDeclaration, PluginProviderCapabilities, PluginProviderStrings, PluginProviderOptionDescriptor, PluginProviderExtensionKindDeclaration, PluginProviderOptionsContext, PluginProviderFallbackModel, PluginProviderMaintenance, PluginProviderNativeRoots, PluginProviderNativeRootEntry, PluginProviderPermissionMode, PluginProviderReasoningLevel, PluginProviderComposerAction, PluginProviderModelCatalogScope, PluginProviders, PluginAiServiceDeclaration, PluginAiServiceKind, PluginAiServices, PluginAgentToolPresentation, PluginAgentToolLabels, ProviderInfo.

Declaration field table #

What clients see. ProviderInfo is { id, pluginId, displayName, family?, icon?: { glyph }, logoUrl: string | null, maintenance: { health, usage, installation }, capabilities, composerActions, available, strings?, serviceTiers?, reasoningLevels?, extensionKinds? }. A path-shaped or declared-icon icon arrives as logoUrl (/api/v1/system/providers/<id>/logo, bytes snapshotted at registration) with no icon.glyph; a host glyph name arrives as icon.glyph with a null logoUrl. maintenance is the only maintenance shape on the row: the experimental_providerHealth, experimental_providerUsage and experimental_providerInstallation booleans 0.4.15 served are gone with no alias, so a typed read of them no longer compiles and the served row has no such key (see Compatibility).

Plugin icons: manifest, route, glyph forms experimental #

The plugin's own icon vocabulary, declared in the manifest and referenced by name. The semantics (ingest rule, resolution order, fallback, the validator's reasons) are in Concepts; this is the shape.

Manifest field

Where a namespaced glyph is accepted

Grammar: a namespaced glyph matches ^[a-z0-9-]+/[a-z0-9][a-z0-9-]*$, the same split as an extension kind; host glyph names are PascalCase without a /, so the two cannot collide. The helpers that implement the grammar (isNamespacedGlyph, parseNamespacedGlyph, the PLUGIN_ICON_* caps) live in bb's domain package and are not exported by any @get-bb/plugin-sdk subpath; build the string yourself, as the echo does with `${ECHO_PLUGIN_ID}/receipt`.

The icon route

Conformance

Rule presentation/icon-namespaced-declared ("every namespaced presentation glyph names one of the plugin's declared icons"), enabled by the session fixture's icons: { pluginId, names }; no result when the field is omitted, skipped when no item carried a presentation, and a server: "bb" tool row is exempt. See Testing.

@get-bb/plugin-sdk/host #

import os from "node:os";
import { experimental_defineHostEntry, experimental_nativeRootsHostContract,
         experimental_filterResolvedNativeRoots } from "@get-bb/plugin-sdk/host";

export default experimental_defineHostEntry({
  contract: experimental_nativeRootsHostContract,
  handlers: {
    resolveNativeRoots: ({ providerId, cwd }) => {
      const skills = [{ path: `${os.homedir()}/.myagent/skills`, origin: "user", shape: "skills" }];
      return experimental_filterResolvedNativeRoots({ skills }, { warn: console.warn }).answer;
    },
  },
});

A resolver that lists the vendor plugins installed on the host reads them with the kit and answers the directory's own roots beside them, so both agree on where the config directory is:

import os from "node:os";
import { experimental_filterResolvedNativeRoots, experimental_resolveClaudePluginRoots }
  from "@get-bb/plugin-sdk/host";

resolveNativeRoots: async ({ cwd }) => {
  const plugins = await experimental_resolveClaudePluginRoots({ cwd, homeDir: os.homedir(), env: process.env });
  return experimental_filterResolvedNativeRoots({
    skills: [{ path: `${plugins.claudeDir}/skills`, origin: "user", shape: "skills" }, ...plugins.skills],
    commands: [{ path: `${plugins.claudeDir}/commands`, origin: "user", shape: "commands" }, ...plugins.commands],
  }, { warn: console.warn }).answer;
},

An answer lists each path once per side: the readers keep the first root per path in answer order, and bb scans each absolute path once per provider across the declared and resolved roots (declared skills, project then user; declared commands; then the resolved skills and commands, each in the order given), so a resolved root that repeats a declared one is listed under the declared root's identity.

Types: ExperimentalHostEntry, ExperimentalHostPaths, ExperimentalHostRpcContext, ExperimentalHostRpcHandlers, ExperimentalHostSignalContract, ExperimentalHostSignals, ExperimentalHostWatch*, ExperimentalHostWorkerLease, ExperimentalNativeRootsHostContract, ExperimentalNativeRootsResolveInput, ExperimentalNativeRootsResolveOutput, ExperimentalNativeRootsResolveAnswer (the input form a handler writes), ExperimentalDroppedNativeRoot, ExperimentalFilteredNativeRoots, ExperimentalVendorPlugin, ExperimentalVendorPluginRoots, ExperimentalVendorPluginRootsArgs, ExperimentalClaudePluginRoots, ExperimentalClaudePluginRootsArgs. (ExperimentalResolvedNativeRoot is gone; a resolved root is ExperimentalNativeRootsResolveOutput["skills"][number].)

@get-bb/plugin-sdk/provider-bridge #

Curated by hand, named exports only. Grouped the way a bridge consumes it.

1. The bridge entry contract

2. Protocol constants and schemas

Types: BridgeCapabilities, BridgeExecutionOptions, BridgeGrammarVersions, BridgeSteerMode, InitializeResult, ThreadDelta, ThreadDeltaKind, ThreadDeltaNotificationParams, DeltaItemShape, DeltaItemShapeType, DeltaItemKey, DeltaPresentation, DeltaFileChange, DeltaFileReadShape, DeltaSearchShape, DeltaDelegationShape, DeltaPlanStepsShape, DeltaExtensionShape, DeltaBackgroundTaskShape, DeltaProgressSnapshot, DeltaTextChannel, DeltaOutputChannel, DeltaNoTurnFallback, ProviderRecoveryHint, ProviderRecoveryNotification, BridgeErrorData, ProviderHealth, ProviderHealthResult, ProviderUsage, ProviderUsageWindow, ProviderUsageResult, ProviderMaintenanceParams, ProviderInstallation*.

Bridge methods (runtime → bridge) #

Session fields on start/resume/fork: threadId, cwd, options (BridgeExecutionOptions), dynamicTools? (each with its resolved presentation), disallowedTools?, instructionMode. Execution options: { model?, serviceTier?, reasoningLevel?, promptMode?, instructions?, envVars?, providerOptions? } intersected with the runtime permission policy (permissionMode, permissionScope, approvalReviewer, permissionEscalation).

Notifications and bridge requests (bridge → runtime) #

Error codes #

Any error response may carry data: { recovery: { kind, message, retryable } } (bridgeErrorDataSchema).

3. The bridge kit #

Types: BoundedLineReaderArgs, NpmGlobalPackageProbe, BridgeJsonRpcResponse, BridgeSendError, BridgeToolCallRequest, BuildInteractiveResponseArgs, DecodedInteractiveRequest, JsonRpcMessage, PreparedProviderCommandDispatch, ProviderInboundRequest, ProviderPostInitializeRequest, ProviderRawEventCoverage, ProviderRawEventDescription, ProviderRuntimeEvent, ProviderVisibilityMetadata.

4. Domain vocabulary

Re-exported from bb's domain package and inlined into the bundle: the reasoning-effort constants (LOW_REASONING_EFFORT … MAX_REASONING_EFFORT, ULTRACODE_REASONING_EFFORT), reasoningLevelSchema/reasoningLevelValues/reasoningEffortsForLevels, permissionEscalationValues, runtimePermissionScopeValues, instructionModeValues, dynamicToolSchema, jsonValueSchema, extensionKindSchema/isExtensionKind, threadEventItemPresentationSchema, threadEventSearchModeSchema, providerRawEventSchema, providerRecoveryKindSchema/providerRecoveryKindValues, the interaction schemas (interactionRequestPayloadSchema, pendingInteractionResolutionSchema, approvalInteractionOutcomeSchema, userQuestionInteractionOutcomeSchema, providerInteractionOutcomeSchema, the permission-profile schemas, the is* guards), USER_QUESTION_MAX_OPTIONS/USER_QUESTION_MAX_QUESTIONS, removeCommandMentionsFromPromptInput, isStandaloneBuiltinCompactCommand, the background-task status helpers, the ACP CLI schemas (acpReasoningCliSchema, acpNativeReasoningSchema, acpPermissionCliSchema), and toPositiveNumber. Types include PromptInput, DynamicTool, AvailableModel, PendingInteractionPayload, PendingInteractionResolution, RuntimePermissionPolicy, PermissionMode, ReasoningLevel, ServiceTier, ThreadEventItemStatus, ThreadEventTurnStatus, ThreadEventPlanStep, ThreadEventTokenUsageBreakdown, ThreadEventContextWindowUsage, ThreadEventItemPresentation, ClientTurnRequestId, JsonValue, JsonObject, and the workflow snapshot types.

Fifteen unprefixed values and two types of this subpath are scheduled for removal at the next major version (unreferenced by any first-party plugin; kept because 0.4.x published them). Eleven of the names above: acpNativeReasoningSchema, acpPermissionCliSchema, acpReasoningCliSchema, extensionKindSchema, interactionRequestPayloadSchema, isExtensionKind, isUserQuestionPendingInteractionPayload, isUserQuestionPendingInteractionResolution, providerRecoveryKindValues, threadEventItemPresentationSchema, threadEventSearchModeSchema. And four 0.4.15 exports whose definitions moved out of core, restored in 0.4.16 as aliases so a bridge built against 0.4.15 rebuilds: hostDaemonAcpLaunchSpecSchema and normalizeHostDaemonAcpLaunchSpec (the ACP kit's experimental_acpLaunchSpecSchema and its normalizer, which a plugin that declares an ACP agent should import from /provider-bridge/acp), claudeTaskToolNameSchema and claudeTaskToolOutputSchema (the Claude Code task-tool names and outputs as shipped; nothing in bb reads them and there is no replacement), with the types HostDaemonAcpLaunchSpec and ClaudeTaskToolOutput. See Compatibility.

@get-bb/plugin-sdk/provider-bridge/acp #

The Agent Client Protocol is one wire protocol spoken by many agents, so bb runs all of them through one generic bridge. The agent to launch arrives per command in the provider options, and nothing in the bridge is bb-first-party; the bundled ACP plugin is a list of agents anyone could have written. Every value export is experimental; see Compatibility for the open questions.

The launch spec

Wrapping an ACP agent

This is the whole plugin for an agent called Amp that speaks ACP over amp acp. No bridge code is written; the host artifact re-exports the kit's bridge, and the declaration carries the launch spec.

export { experimental_acpProviderBridge as experimental_providerBridge }
  from "@get-bb/plugin-sdk/provider-bridge/acp";

import type { BbPluginApi } from "@get-bb/plugin-sdk";
import { experimental_acpLaunchSpecSchema } from "@get-bb/plugin-sdk/provider-bridge/acp";

const launch = experimental_acpLaunchSpecSchema.parse({
  displayName: "Amp",
  command: "amp",
  args: ["acp"],
  env: {},
  nativeSkillRoots: { user: [".agents/skills"], project: [".agents/skills"] },
});

export default function plugin(bb: BbPluginApi) {
  bb.providers.register({
    id: "amp",
    displayName: "Amp",
    family: "acp",
    icon: "./icons/amp.svg",
    strings: {
      signInHint: "Run `amp login` on the machine to sign in.",
      expiredHint: "Your Amp session expired. Run `amp login`, then reload.",
      installUrl: "https://agentclientprotocol.com",
    },
    experimental_bridgeOptions: { acpLaunchSpec: launch, acpDialect: "generic" },
    experimental_nativeSkillRoots: launch.nativeSkillRoots,
    models: { scope: "host" },
    maintenance: { health: true, usage: false, installation: false },
    capabilities: {
      supportsServiceTier: false,
      supportsNativeUserQuestion: false,
      supportsManualCompaction: false,
      supportsThreadArchive: false,
      supportsThreadRename: false,
      fork: "none",                       // declare "tip" only if the agent advertises session/fork
      permissionModes: ["accept-edits", "full"],
      reasoningLevels: ["low", "medium", "high"],
    },
    composerActions: [],
  });
}

The bundled ACP plugin does the same thing per agent from a definition list, re-registers when its customAgents setting changes, and runs a background service that probes each connected host with experimental_probeAcpAgent to narrow a declared fork the agent turns out not to support. Its manifest bb.host entry re-exports the bridge and default-exports a host entry serving probeAgent and resolveNativeRoots. A user can also add an agent without any plugin at all, through that plugin's customAgents setting (a JSON array of { id, displayName, command, args?, env?, cwd?, dialect?, modelCli?, reasoningCli?, nativeReasoning?, nativeSkillRoots?, permissionCli?, supportsManualCompaction? }); the provider id becomes acp-<id>.

@get-bb/plugin-sdk/provider-bridge/testing #

Framework-agnostic; nothing imports a test runner. The Testing page shows each in use.

Types: BridgeConformanceTransport, ConformanceCheckResult, ConformanceReport, ConformanceSessionFixture, RunBridgeConformanceOptions, DeltaAssembler, CreateDeltaAssemblerOptions, AssembleDeltasArgs, BridgeDeltaEventCollector, BridgeJsonRpcTestHarness, CapturedBridgeJsonRpcOutput, CapturedBridgeNotification, RecordedCellReplay, RecordedConformanceCell, BridgeRecording, BridgeRecordingManifest, BridgeRecordingEntry, BridgeRecordingDirection, RecordedCell, ParityRun, ParityComparison, ParityAllowlistEntry, ReplayProviderProfile, ReplayDialect ("json-rpc" | "claude-cli" | "pi-rpc"), and the canonical event types ThreadEvent, ThreadEventItem, ThreadEventItemPresentation and the named item kinds.

@get-bb/plugin-sdk/ai-services #

Types: ExperimentalAiServicesHostContract, ExperimentalAiInferenceCompleteInput/Output, ExperimentalAiVoiceTranscribeInput/Output, ExperimentalAiServiceErrorCode. (experimental_aiServiceKindSchema, ExperimentalAiServiceKind and ExperimentalAiJsonValue are gone; the declaration's kinds are typed by PluginAiServiceKind on the root entry.)

@get-bb/plugin-sdk/app #

import { definePluginApp, experimental_useProviders } from "@get-bb/plugin-sdk/app";

export default definePluginApp((app) => {
  app.slots.experimental_timelineRenderer({
    kind: "echo-provider/receipt",
    component: ({ payload, presentation, Original }) => (
      <div>
        <Original />
        <pre>{JSON.stringify(payload, null, 2)}</pre>
      </div>
    ),
  });
});

@get-bb/plugin-sdk/testing and /testing/host #