@get-bb/plugin-sdk 0.5.15 → 0.5.23

package/bundled-types/bb-plugin-sdk-internal-host-policy.d.ts

@@ -1677,26 +1677,71 @@ interface PluginMentionProviderRegistration {
         experimental_images?: readonly ExperimentalPluginMentionImage[];
     }>;
 }
+/** Options for one `complete` call. */
+interface PluginAiCompleteOptions {
+    /**
+     * Aborted when bb stops waiting: the task timed out (5 seconds for titles
+     * and commit messages) or the request was cancelled. Pass it to `fetch`.
+     */
+    readonly signal: AbortSignal;
+}
+/** Options for one `transcribe` call. */
+interface PluginAiTranscribeOptions {
+    /** Aborted when bb stops waiting (10 seconds) or the request was cancelled. */
+    readonly signal: AbortSignal;
+    /**
+     * Vocabulary the speaker is likely to use (names, identifiers), for
+     * services that accept a transcription prompt; `null` when there is none.
+     */
+    readonly hint: string | null;
+}
 /**
- * What a plugin's AI service does. `inference` answers bb's server-side helper
- * completions (thread titles, commit messages: a prompt and a JSON Schema in,
- * a structured value out); `voice` transcribes recorded speech.
+ * Whether a service can answer right now. `message` is shown to the user
+ * beside the service ("Sign in to your bb account") and should say how to
+ * make it ready.
  */
-type PluginAiServiceKind = "inference" | "voice";
+type PluginAiServiceStatus = {
+    readonly ready: true;
+} | {
+    readonly ready: false;
+    readonly message: string;
+};
 /**
- * An AI service a plugin offers from its `bb.host` entry, which implements
- * `experimental_aiServicesHostContract` (`@get-bb/plugin-sdk/ai-services`).
- * The user selects it with `BB_INFERENCE` / `BB_TRANSCRIPTION` set to
- * `<id>/<model>`; core calls the plugin's host entry on the primary host with
- * the `id` on every request, so one entry can serve several services.
+ * An AI service bb can use for its helper tasks: thread titles and commit
+ * messages (`complete`) and voice input (`transcribe`). The user picks a
+ * service per task in Settings → AI services or with
+ * `bb settings ai-services set`. The functions run in the plugin's server
+ * process; a plugin that needs host-local state (a login file, a local model)
+ * reaches its own `bb.host` entry through `bb.hosts.experimental_client`.
+ *
+ * bb owns the prompts and cleans up replies (think blocks, quotes, labels,
+ * extra lines), so a service returns the model's text as-is. The plugin owns
+ * everything behind the function: which model, which API, any retries.
+ * Failure is a rejected promise.
  */
 interface PluginAiServiceDeclaration {
-    /** The `<serviceId>` segment of the user's setting; stable, lowercase. */
+    /**
+     * Stable, lowercase id, unique within this plugin. bb identifies a service
+     * by plugin id and service id, so another plugin may use the same id.
+     * `automatic` and `off` are reserved.
+     */
     readonly id: string;
-    /** Shown beside the id wherever the setting's options are listed. */
+    /** Shown in the picker; 1-64 characters. */
     readonly displayName: string;
-    /** Which kinds this service answers; a kind it lacks is not offered. */
-    readonly kinds: readonly PluginAiServiceKind[];
+    /**
+     * Answer one prompt with plain text. Offered for thread titles and commit
+     * messages. Declare `complete`, `transcribe`, or both.
+     */
+    readonly complete?: (prompt: string, options: PluginAiCompleteOptions) => Promise<string>;
+    /** Transcribe recorded speech to text. Offered for voice input. */
+    readonly transcribe?: (audio: File, options: PluginAiTranscribeOptions) => Promise<string>;
+    /**
+     * Report whether the service can answer. bb calls it for the picker's
+     * status line and to decide whether Automatic skips the service and
+     * whether the microphone shows; results are cached for a few seconds.
+     * Omit it when the service is always ready.
+     */
+    readonly status?: () => Promise<PluginAiServiceStatus>;
 }
 
 declare function pluginCliCollisionWarning(pluginId: string, commandName: string): string | null;
@@ -1733,57 +1778,24 @@ declare const PLUGIN_PROVIDER_PERMISSION_MODE_VALUES: readonly ["accept-edits",
 declare const PLUGIN_PROVIDER_REASONING_LEVEL_VALUES: readonly ["none", "low", "medium", "high", "xhigh", "ultracode", "max", "ultra"];
 declare const PLUGIN_PROVIDER_COMPOSER_ACTION_VALUES: readonly ["plan", "goal"];
 /**
- * AI-service ids the server serves itself: `openai` transcription and the
- * builtin inference providers (pi-ai 0.84). A plugin cannot register one —
- * it would capture the user's prompts and audio. This list is the one source
- * for both the fake host and production (`isServerDirectAiServiceId`);
- * apps/server/test/services/plugins/plugin-ai-services.test.ts pins it to
- * pi-ai's provider registry, so a pi-ai bump must move it in the same change.
+ * A validated `bb.experimental_aiServices.register` declaration. Absent
+ * functions are `null` so hosts never have to distinguish missing from
+ * undefined.
  */
-declare const SERVER_DIRECT_AI_SERVICE_IDS: readonly string[];
+interface NormalizedPluginAiService {
+    readonly id: string;
+    readonly displayName: string;
+    readonly complete: NonNullable<PluginAiServiceDeclaration["complete"]> | null;
+    readonly transcribe: NonNullable<PluginAiServiceDeclaration["transcribe"]> | null;
+    readonly status: NonNullable<PluginAiServiceDeclaration["status"]> | null;
+}
 /**
  * Validate one `bb.experimental_aiServices.register` declaration the same
  * way in the production host and the fake host. Throws on the first problem;
  * returns a normalized, frozen copy carrying only contract fields.
  */
-declare function validatePluginAiServiceDeclaration(declaration: PluginAiServiceDeclaration): PluginAiServiceDeclaration;
-/**
- * What an AI service binds to, decided at the
- * `bb.experimental_aiServices.register` call: the plugin's built `bb.host`
- * artifact, or — when the plugin declares an entry that failed to build —
- * nothing yet, with the build problem. An unbound service is staged so the
- * factory completes; the load then fails on that problem before the staged
- * registrations flush, so the service never goes live, while a provider the
- * same factory declared can still be retained as unavailable.
- */
-type AiServiceHostBinding<THostArtifact> = {
-    readonly artifact: THostArtifact;
-    readonly problem: null;
-} | {
-    readonly artifact: null;
-    readonly problem: string;
-};
-/**
- * The refusals a host makes at `bb.experimental_aiServices.register` before
- * it stages the declaration: a reserved server-direct id, and a plugin with
- * no `bb.host` entry for the service to run on. A plugin whose declared
- * entry failed to build is not refused here: the service is staged unbound,
- * carrying the build problem, so the load fails on that problem — the
- * actionable one — after the factory instead of at this call, and a
- * provider the same factory declares is listed as unavailable rather than
- * lost. Returns what the service binds to. The production host and the fake
- * host both call this, so they refuse identically;
- * apps/server/test/services/plugins/plugin-ai-services.test.ts pins the
- * messages.
- */
-declare function assertAiServiceRegistrable<THostArtifact>(args: {
-    id: string;
-    /** The plugin's built `bb.host` artifact, or null when it has none. */
-    hostArtifact: THostArtifact | null;
-    /** Why the artifact is missing when the plugin declared an entry that failed to build. */
-    hostArtifactProblem: string | null;
-}): AiServiceHostBinding<THostArtifact>;
-/** The collision a second registration of a live AI-service id raises. */
+declare function validatePluginAiServiceDeclaration(declaration: PluginAiServiceDeclaration): NormalizedPluginAiService;
+/** The collision a plugin's second registration of one AI-service id raises. */
 declare function aiServiceAlreadyRegisteredMessage(id: string): string;
 /** The collision a second registration of a live provider id raises. */
 declare function providerAlreadyRegisteredMessage(id: string): string;
@@ -2069,5 +2081,5 @@ declare function normalizePluginAgentConfiguration(args: {
 declare function validateRpcValue(schema: StandardSchemaV1, value: unknown, phase: "input" | "output", fail: (error: PluginRpcError) => never): Promise<unknown>;
 declare function normalizeRpcJsonResult(value: unknown, fail: (error: PluginRpcError) => never): JsonValue;
 
-export { ENVIRONMENT_PROVIDER_DESCRIPTION_MAX_CHARS, ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS, ENVIRONMENT_PROVIDER_ID_PATTERN, ENVIRONMENT_PROVIDER_REQUIREMENT_NAMES, KV_VALUE_MAX_BYTES, MACHINE_PROVIDER_DESCRIPTION_MAX_CHARS, PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS, PLUGIN_MENTION_TRIGGER_VALUES, PLUGIN_PROVIDER_BRIDGE_OPTIONS_MAX_BYTES, PLUGIN_PROVIDER_COMPOSER_ACTION_VALUES, PLUGIN_PROVIDER_DISPLAY_NAME_MAX_CHARS, PLUGIN_PROVIDER_ENV_MAX_ENTRIES, PLUGIN_PROVIDER_ENV_NAME_PATTERN, PLUGIN_PROVIDER_PERMISSION_MODE_VALUES, PLUGIN_PROVIDER_REASONING_LEVEL_VALUES, PROVIDER_ID_PATTERN, RESERVED_AGENT_TOOL_NAMES, RESERVED_BB_CLI_COMMANDS, SERVER_DIRECT_AI_SERVICE_IDS, SETTING_KEY_PATTERN, adoptHttpRouteResponse, aiServiceAlreadyRegisteredMessage, assertAiServiceRegistrable, coerceStoredPluginSettingValue, deriveValidatedProviderOptions, enforcePluginCliOutputLimit, environmentCompositionSchema, isPluginMentionTrigger, isStandardSchema, normalizeAgentToolRegistration, normalizeCliRegistration, normalizeHttpRouteRegistration, normalizeInteractionRequest, normalizeMentionProviderRegistration, normalizePluginAgentConfiguration, normalizeRealtimePayload, normalizeRpcJsonResult, normalizeRpcRegistration, normalizeWebSocketRouteRegistration, parsePluginRowPresentation, pluginCliCollisionWarning, pluginHookAlreadyRegisteredMessage, providerAlreadyRegisteredMessage, providerIconRefusalMessage, providerWithoutBridgeMessage, publishRpcMethod, readRpcPublicationOptions, registerSettingDescriptors, runPluginStorageMigrations, storePluginHook, summarizeStandardIssues, undeclaredIconProblem, validateBackgroundServiceRegistration, validatePluginAiServiceDeclaration, validatePluginEnvironmentProviderDeclaration, validatePluginMachineProviderDeclaration, validatePluginProviderDeclaration, validatePluginProviderEnvEntries, validateProviderEnvContribution, validateRpcValue, validateScheduleRegistration, validateServerAccessProviderDeclaration, validateSettingsUpdate };
-export type { AiServiceHostBinding, NormalizedPluginEnvironmentComposition, NormalizedPluginEnvironmentProvider, NormalizedPluginEnvironmentProviderRequirements, NormalizedPluginInteractionRequest, NormalizedPluginMachineProvider, NormalizedPluginProviderDeclaration };
+export { ENVIRONMENT_PROVIDER_DESCRIPTION_MAX_CHARS, ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS, ENVIRONMENT_PROVIDER_ID_PATTERN, ENVIRONMENT_PROVIDER_REQUIREMENT_NAMES, KV_VALUE_MAX_BYTES, MACHINE_PROVIDER_DESCRIPTION_MAX_CHARS, PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS, PLUGIN_MENTION_TRIGGER_VALUES, PLUGIN_PROVIDER_BRIDGE_OPTIONS_MAX_BYTES, PLUGIN_PROVIDER_COMPOSER_ACTION_VALUES, PLUGIN_PROVIDER_DISPLAY_NAME_MAX_CHARS, PLUGIN_PROVIDER_ENV_MAX_ENTRIES, PLUGIN_PROVIDER_ENV_NAME_PATTERN, PLUGIN_PROVIDER_PERMISSION_MODE_VALUES, PLUGIN_PROVIDER_REASONING_LEVEL_VALUES, PROVIDER_ID_PATTERN, RESERVED_AGENT_TOOL_NAMES, RESERVED_BB_CLI_COMMANDS, SETTING_KEY_PATTERN, adoptHttpRouteResponse, aiServiceAlreadyRegisteredMessage, coerceStoredPluginSettingValue, deriveValidatedProviderOptions, enforcePluginCliOutputLimit, environmentCompositionSchema, isPluginMentionTrigger, isStandardSchema, normalizeAgentToolRegistration, normalizeCliRegistration, normalizeHttpRouteRegistration, normalizeInteractionRequest, normalizeMentionProviderRegistration, normalizePluginAgentConfiguration, normalizeRealtimePayload, normalizeRpcJsonResult, normalizeRpcRegistration, normalizeWebSocketRouteRegistration, parsePluginRowPresentation, pluginCliCollisionWarning, pluginHookAlreadyRegisteredMessage, providerAlreadyRegisteredMessage, providerIconRefusalMessage, providerWithoutBridgeMessage, publishRpcMethod, readRpcPublicationOptions, registerSettingDescriptors, runPluginStorageMigrations, storePluginHook, summarizeStandardIssues, undeclaredIconProblem, validateBackgroundServiceRegistration, validatePluginAiServiceDeclaration, validatePluginEnvironmentProviderDeclaration, validatePluginMachineProviderDeclaration, validatePluginProviderDeclaration, validatePluginProviderEnvEntries, validateProviderEnvContribution, validateRpcValue, validateScheduleRegistration, validateServerAccessProviderDeclaration, validateSettingsUpdate };
+export type { NormalizedPluginAiService, NormalizedPluginEnvironmentComposition, NormalizedPluginEnvironmentProvider, NormalizedPluginEnvironmentProviderRequirements, NormalizedPluginInteractionRequest, NormalizedPluginMachineProvider, NormalizedPluginProviderDeclaration };

package/bundled-types/bb-plugin-sdk-provider-bridge.d.ts

@@ -1657,6 +1657,7 @@ declare const BRIDGE_JSON_RPC_ERRORS: {
     readonly NO_ACTIVE_TURN: -32001;
     readonly SESSION_NOT_RESTORABLE: -32002;
     readonly FORK_CHECKPOINT_UNSUPPORTED: -32003;
+    readonly MISSING_EXECUTABLE: -32004;
 };
 declare const providerRecoveryHintSchema: z.ZodObject<{
     kind: z.ZodEnum<{

package/bundled-types/bb-plugin-sdk-testing-app.d.ts

@@ -35,11 +35,11 @@ type CollectedPluginProviderIconRegistration = Omit<PluginProviderIconRegistrati
  *
  * - {@link installTestPluginRuntime} fills `globalThis.__bbPluginRuntime.
  *   pluginSdkApp` with a test implementation of the `@get-bb/plugin-sdk/app`
- *   surface (the same seam `bb plugin build` shims to the real app). It must
- *   run BEFORE the plugin's `app.tsx` module evaluates, because that module
- *   binds the runtime at import time — so import `app.tsx` through
- *   {@link loadPluginApp}'s thunk form, or call the installer from a vitest
- *   setup file when you prefer static imports.
+ *   surface (the same seam `bb plugin build` shims to the real app). The
+ *   `@get-bb/plugin-sdk/app` exports look the runtime up when they are called
+ *   or rendered, so import order does not matter: install the runtime any time
+ *   before the first hook runs ({@link loadPluginApp} and {@link renderSlot}
+ *   install it for you).
  * - {@link loadPluginApp} runs the definition's setup against a validating
  *   collector (ported from the BB app's interpreter, same error messages)
  *   and returns the typed slot registrations.
@@ -161,9 +161,11 @@ interface SidebarNavigationCall {
     openInSplit?: boolean;
 }
 /**
- * Install the test runtime at `globalThis.__bbPluginRuntime.pluginSdkApp`.
- * Idempotent per module instance; must run before the plugin's `app.tsx`
- * (and therefore `@get-bb/plugin-sdk/app`) is imported.
+ * Install the test runtime at `globalThis.__bbPluginRuntime.pluginSdkApp`,
+ * plus the React the `@get-bb/plugin-sdk/app` components render through.
+ * Idempotent per module instance. Call it before the first SDK hook runs or
+ * SDK component renders; when the plugin's modules are imported does not
+ * matter.
  */
 declare function installTestPluginRuntime(): void;
 interface CapturedPluginApp {
@@ -200,9 +202,8 @@ type PluginAppModule = {
 type PluginAppSource = PluginAppDefinition | PluginAppModule | (() => Promise<PluginAppDefinition | PluginAppModule>);
 /**
  * Install the test runtime, resolve the plugin app definition, and capture
- * its slot registrations. Pass a thunk (`() => import("../app.tsx")`) so the
- * plugin module evaluates after the runtime is installed — a static import
- * would bind `definePluginApp` before the installer runs.
+ * its slot registrations. Pass the imported module, its default export, or a
+ * thunk (`() => import("../app.tsx")`).
  */
 declare function loadPluginApp(source: PluginAppSource): Promise<CapturedPluginApp>;
 interface ContentScriptTestMountOptions {
@@ -256,6 +257,8 @@ interface RenderSlotOptions<Contract extends PluginRpcContract = PluginRpcContra
         projectId?: string | null;
         threadId?: string | null;
     };
+    /** `experimental_usePluginId()` value; defaults to `test-plugin`. */
+    pluginId?: string;
     /** Initial `useRealtimeConnectionState()` value; defaults to `connected`. */
     realtimeConnectionState?: PluginRealtimeConnectionState;
     /** Initial state for this render's isolated composer scope and view. */

package/bundled-types/bb-plugin-sdk-testing.d.ts

@@ -1371,10 +1371,8 @@ interface CreateFakePluginHostOptions {
     sharedPortTunnelIdentities?: Record<string, PluginSharedPortTunnelIdentity>;
     /**
      * Whether the plugin's manifest declares a `bb.host` entry. Production
-     * refuses `bb.providers.register` (the provider would have no bridge to
-     * run on) and `experimental_aiServices.register` (the service would have
-     * nothing to run on) without one; the fake applies the same rules.
-     * Defaults to true.
+     * refuses `bb.providers.register` without one (the provider would have no
+     * bridge to run on); the fake applies the same rule. Defaults to true.
      */
     experimental_hostEntry?: boolean;
     /**