@get-bb/plugin-sdk 0.4.17 → 0.4.18

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

@@ -9,8 +9,8 @@ import { z } from 'zod';
 
 /**
  * Core `bb` CLI top-level command names (plus commander's built-in help).
- * Plugin CLI commands may not shadow these. Maintained by hand and checked
- * against the real Commander program by
+ * Core commands win these names; plugin scaffolding rejects them. Maintained
+ * by hand and checked against the real Commander program by
  * apps/cli/src/__tests__/plugin-cli-proxy.test.ts.
  *
  * "automation" and "connect" are intentionally absent: builtin plugins own
@@ -583,6 +583,7 @@ interface PluginAiServiceDeclaration {
     readonly kinds: readonly PluginAiServiceKind[];
 }
 
+declare function pluginCliCollisionWarning(pluginId: string, commandName: string): string | null;
 /**
  * Built-in dynamic tool names plugins may not shadow. Maintained by hand —
  * kept in sync with the built-in tools in
@@ -789,5 +790,5 @@ declare function agentToolIconRefusalMessage(toolName: string, problem: string):
  */
 declare function providerWithoutBridgeMessage(providerId: string): string;
 
-export { AGENT_TOOL_NAME_PATTERN, BACKGROUND_NAME_PATTERN, CLI_COMMAND_NAME_PATTERN, KV_VALUE_MAX_BYTES, MENTION_PROVIDER_ID_PATTERN, PLUGIN_AGENT_DYNAMIC_INSTRUCTIONS_MAX_CHARS, PLUGIN_AGENT_SELECTION_MAX_IDS, PLUGIN_AGENT_STATIC_INSTRUCTIONS_MAX_CHARS, PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS, PLUGIN_AGENT_TOOL_PARAMETERS_MAX_BYTES, PLUGIN_HTTP_METHODS, PLUGIN_MENTION_TRIGGER_VALUES, PLUGIN_PROVIDER_BRIDGE_OPTIONS_MAX_BYTES, PLUGIN_PROVIDER_COMPOSER_ACTION_VALUES, PLUGIN_PROVIDER_DISPLAY_NAME_MAX_CHARS, PLUGIN_PROVIDER_PERMISSION_MODE_VALUES, PLUGIN_PROVIDER_REASONING_LEVEL_VALUES, PROVIDER_ID_PATTERN, RESERVED_AGENT_TOOL_NAMES, RESERVED_BB_CLI_COMMANDS, RPC_METHOD_PATTERN, SERVER_DIRECT_AI_SERVICE_IDS, SETTING_KEY_PATTERN, adoptHttpRouteResponse, agentToolIconRefusalMessage, aiServiceAlreadyRegisteredMessage, assertAiServiceRegistrable, assertNoRecursiveJsonSchemaReferences, deriveValidatedProviderOptions, enforcePluginCliOutputLimit, isPluginMentionTrigger, isStandardSchema, isZodSchemaLike, normalizeMentionProviderTriggers, parsePluginAgentToolPresentation, providerAlreadyRegisteredMessage, providerIconRefusalMessage, providerWithoutBridgeMessage, readRpcMethodContract, registerSettingDescriptors, rejectStaleAgentToolFields, summarizeParseIssues, undeclaredIconProblem, validatePluginAiServiceDeclaration, validatePluginProviderDeclaration, validateSettingsUpdate };
+export { AGENT_TOOL_NAME_PATTERN, BACKGROUND_NAME_PATTERN, CLI_COMMAND_NAME_PATTERN, KV_VALUE_MAX_BYTES, MENTION_PROVIDER_ID_PATTERN, PLUGIN_AGENT_DYNAMIC_INSTRUCTIONS_MAX_CHARS, PLUGIN_AGENT_SELECTION_MAX_IDS, PLUGIN_AGENT_STATIC_INSTRUCTIONS_MAX_CHARS, PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS, PLUGIN_AGENT_TOOL_PARAMETERS_MAX_BYTES, PLUGIN_HTTP_METHODS, PLUGIN_MENTION_TRIGGER_VALUES, PLUGIN_PROVIDER_BRIDGE_OPTIONS_MAX_BYTES, PLUGIN_PROVIDER_COMPOSER_ACTION_VALUES, PLUGIN_PROVIDER_DISPLAY_NAME_MAX_CHARS, PLUGIN_PROVIDER_PERMISSION_MODE_VALUES, PLUGIN_PROVIDER_REASONING_LEVEL_VALUES, PROVIDER_ID_PATTERN, RESERVED_AGENT_TOOL_NAMES, RESERVED_BB_CLI_COMMANDS, RPC_METHOD_PATTERN, SERVER_DIRECT_AI_SERVICE_IDS, SETTING_KEY_PATTERN, adoptHttpRouteResponse, agentToolIconRefusalMessage, aiServiceAlreadyRegisteredMessage, assertAiServiceRegistrable, assertNoRecursiveJsonSchemaReferences, deriveValidatedProviderOptions, enforcePluginCliOutputLimit, isPluginMentionTrigger, isStandardSchema, isZodSchemaLike, normalizeMentionProviderTriggers, parsePluginAgentToolPresentation, pluginCliCollisionWarning, providerAlreadyRegisteredMessage, providerIconRefusalMessage, providerWithoutBridgeMessage, readRpcMethodContract, registerSettingDescriptors, rejectStaleAgentToolFields, summarizeParseIssues, undeclaredIconProblem, validatePluginAiServiceDeclaration, validatePluginProviderDeclaration, validateSettingsUpdate };
 export type { AiServiceHostBinding, NormalizedPluginProviderDeclaration };

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

@@ -7865,6 +7865,7 @@ declare const pluginCatalogSearchResultSchema: z$1.ZodObject<{
     iconUrl: z$1.ZodNullable<z$1.ZodString>;
     incompatibleReason: z$1.ZodNullable<z$1.ZodString>;
     installed: z$1.ZodBoolean;
+    installs: z$1.ZodDefault<z$1.ZodNullable<z$1.ZodNumber>>;
     marketplace: z$1.ZodString;
     marketplaceDisplayName: z$1.ZodString;
     official: z$1.ZodBoolean;
@@ -15858,8 +15859,9 @@ interface PluginCliExecutionResult {
     error?: PluginCliOutputLimitError;
 }
 interface PluginCliRegistration {
-    /** Top-level command name (`bb <name> …`): lowercase [a-z0-9-]+, and not
-     * a core bb command (see RESERVED_BB_CLI_COMMANDS in the server). */
+    /** Preferred top-level command name (`bb <name> …`): lowercase [a-z0-9-]+.
+     * A core collision logs an activation warning and remains available through
+     * `bb plugin run <plugin-id>`. */
     name: string;
     summary: string;
     /** Subcommand metadata rendered in help and the plugin-commands skill
@@ -15871,7 +15873,7 @@ interface PluginCli {
     /**
      * Register this plugin's `bb` subcommand. One registration per factory
      * execution; a repeated call is rejected. Core bb commands always win
-     * name collisions; reserved names are rejected at registration.
+     * name collisions; the plugin is warned and remains explicitly callable by id.
      */
     register(registration: PluginCliRegistration): void;
 }

package/dist/internal/host-policy.js

@@ -24,16 +24,23 @@ function parseNamespacedGlyph(glyph) {
 // ../domain/src/plugin-cli.ts
 var RESERVED_BB_CLI_COMMANDS = [
   "environment",
+  "file",
   "guide",
   "help",
+  "machine",
   "manager",
+  "marketplace",
   "plugin",
   "project",
   "provider",
+  "settings",
   "skill",
   "status",
+  "terminal",
   "theme",
-  "thread"
+  "thread",
+  "updates",
+  "voice"
 ];
 
 // ../domain/src/provider-fork.ts
@@ -252,6 +259,10 @@ var providerNativeRootSetSchema = z2.object({
 var PLUGIN_CLI_OUTPUT_MAX_BYTES = 1024 * 1024;
 
 // src/internal/host-policy.ts
+function pluginCliCollisionWarning(pluginId, commandName) {
+  if (!RESERVED_BB_CLI_COMMANDS.includes(commandName)) return null;
+  return `CLI command "${commandName}" collides with core command "bb ${commandName}"; core keeps the short form. Use "bb plugin run ${pluginId}" to invoke this plugin.`;
+}
 var RESERVED_AGENT_TOOL_NAMES = [
   "update_environment_directory"
 ];
@@ -1646,6 +1657,7 @@ export {
   isZodSchemaLike,
   normalizeMentionProviderTriggers,
   parsePluginAgentToolPresentation,
+  pluginCliCollisionWarning,
   providerAlreadyRegisteredMessage,
   providerIconRefusalMessage,
   providerWithoutBridgeMessage,

package/dist/provider-bridge-acp.js

@@ -6863,31 +6863,44 @@ function buildAcpModelDiscoveryAgentCommand(launchSpec) {
     ...launchEnvVars(launchSpec)
   };
 }
-function buildAcpModelListParams(launchSpec) {
+function buildAcpModelListParams(launchSpec, options) {
+  const primaryModels = [
+    ...options.primaryModels ?? launchSpec?.modelCli?.primaryModels ?? []
+  ];
+  const reasoningProbePriorityModelIds = [
+    ...options.reasoningProbePriorityModelIds
+  ];
   if (launchSpec === null) {
-    return { primaryModels: [] };
+    return {
+      primaryModels,
+      reasoningProbePriorityModelIds,
+      parameterizedModelPicker: options.parameterizedModelPicker
+    };
   }
   const listCommand = buildAcpModelListCommand(launchSpec);
   const agent = buildAcpModelDiscoveryAgentCommand(launchSpec);
   return {
     ...listCommand !== void 0 ? { listCommand } : {},
     ...agent !== void 0 ? { agent } : {},
-    primaryModels: [...launchSpec.modelCli?.primaryModels ?? []],
+    primaryModels,
+    reasoningProbePriorityModelIds,
+    parameterizedModelPicker: options.parameterizedModelPicker,
     ...launchSpec.reasoningCli !== void 0 ? { reasoningCli: launchSpec.reasoningCli } : {},
     ...launchSpec.nativeReasoning !== void 0 ? { nativeReasoning: launchSpec.nativeReasoning } : {}
   };
 }
-function buildAcpModelSelectionParam(launchSpec, options) {
+function buildAcpModelSelectionParam(launchSpec, options, parameterizedModelPicker) {
   const model = options.model;
   const listCommand = buildAcpModelListCommand(launchSpec);
   if (!model || model === ACP_DEFAULT_MODEL_ID) {
     return {};
   }
-  if (!listCommand || !launchSpec.modelCli?.selectFlag) {
+  if (parameterizedModelPicker || !listCommand || !launchSpec.modelCli?.selectFlag) {
     return {
       modelSelection: {
         modelId: model,
-        ...options.reasoningLevel !== void 0 ? { reasoningLevel: options.reasoningLevel } : {}
+        ...options.reasoningLevel !== void 0 ? { reasoningLevel: options.reasoningLevel } : {},
+        ...parameterizedModelPicker && options.serviceTier !== void 0 ? { serviceTier: options.serviceTier } : {}
       }
     };
   }
@@ -6897,7 +6910,7 @@ function buildAcpModelSelectionParam(launchSpec, options) {
       selectFlag: launchSpec.modelCli.selectFlag,
       model,
       ...options.reasoningLevel !== void 0 ? { reasoningLevel: options.reasoningLevel } : {},
-      // Only "fast" changes resolution; "default" is the catalog's normal id.
+      // Only "fast" changes launch resolution; "default" is the normal id.
       ...options.serviceTier === "fast" ? { serviceTier: options.serviceTier } : {}
     }
   };
@@ -6923,7 +6936,12 @@ function buildAcpSessionParams(args) {
       args: [...launchSpec.args]
     },
     ...args.dialectId === void 0 ? {} : { dialectId: args.dialectId },
-    ...buildAcpModelSelectionParam(launchSpec, options),
+    ...buildAcpModelSelectionParam(
+      launchSpec,
+      options,
+      args.parameterizedModelPicker
+    ),
+    parameterizedModelPicker: args.parameterizedModelPicker,
     ...launchSpec.reasoningCli !== void 0 ? { reasoningCli: launchSpec.reasoningCli } : {},
     ...launchSpec.nativeReasoning !== void 0 ? { nativeReasoning: launchSpec.nativeReasoning } : {},
     ...launchSpec.permissionCli !== void 0 ? { permissionCli: launchSpec.permissionCli } : {},
@@ -8315,6 +8333,13 @@ async function authenticateAcpAgent(args) {
     );
   }
 }
+function acpClientCapabilities(parameterizedModelPicker, fsAccess = false) {
+  return {
+    fs: { readTextFile: fsAccess, writeTextFile: fsAccess },
+    terminal: false,
+    ...parameterizedModelPicker === true ? { _meta: { parameterizedModelPicker: true } } : {}
+  };
+}
 async function loadAgentModelCatalog(listCommand) {
   const stdout = await new Promise((resolveExec, rejectExec) => {
     execFile4(
@@ -8364,8 +8389,12 @@ async function loadAgentModelCatalog(listCommand) {
   cachedModelCatalog = { key, catalog };
   return catalog;
 }
-async function loadSessionDiscoveredModels(agent) {
-  const key = JSON.stringify(agent);
+async function loadSessionDiscoveredModels(agent, reasoningProbePriorityModelIds, parameterizedModelPicker) {
+  const key = JSON.stringify({
+    agent,
+    reasoningProbePriorityModelIds,
+    parameterizedModelPicker
+  });
   if (cachedSessionDiscoveredModels?.key === key && Date.now() - cachedSessionDiscoveredModels.fetchedAt < SESSION_MODEL_DISCOVERY_TTL_MS) {
     return cachedSessionDiscoveredModels.models;
   }
@@ -8406,10 +8435,7 @@ async function loadSessionDiscoveredModels(agent) {
           params: {
             protocolVersion: ACP_PROTOCOL_VERSION,
             clientInfo: { name: "bb", version: "1.0.0" },
-            clientCapabilities: {
-              fs: { readTextFile: false, writeTextFile: false },
-              terminal: false
-            }
+            clientCapabilities: acpClientCapabilities(parameterizedModelPicker)
           },
           resultSchema: acpInitializeResultSchema
         });
@@ -8447,7 +8473,8 @@ async function loadSessionDiscoveredModels(agent) {
     const reasoningByModel = await discoverAcpNativeReasoningByModel({
       connection,
       sessionId: newSession.sessionId,
-      modelOption
+      modelOption,
+      reasoningProbePriorityModelIds
     });
     const models = reasoningByModel === null ? configOptionModels : buildModelCatalogFromConfigOptions(modelOption, reasoningByModel);
     cachedSessionDiscoveredModels = {
@@ -8475,6 +8502,23 @@ async function discoverAcpNativeReasoningByModel(args) {
     return null;
   }
   const modelOption = args.modelOption;
+  const modelByValue = new Map(
+    modelOptions.map((model) => [model.value, model])
+  );
+  const modelsToProbe = [];
+  const addedModels = /* @__PURE__ */ new Set();
+  for (const value of args.reasoningProbePriorityModelIds) {
+    const model = modelByValue.get(value);
+    if (model && !addedModels.has(model.value)) {
+      modelsToProbe.push(model);
+      addedModels.add(model.value);
+    }
+  }
+  for (const model of modelOptions) {
+    if (!addedModels.has(model.value)) {
+      modelsToProbe.push(model);
+    }
+  }
   const supportByModel = /* @__PURE__ */ new Map();
   let timeout;
   const timeoutReached = new Promise((resolve4) => {
@@ -8486,7 +8530,7 @@ async function discoverAcpNativeReasoningByModel(args) {
   try {
     return await Promise.race([
       (async () => {
-        for (const model of modelOptions) {
+        for (const model of modelsToProbe) {
           const configState = await args.connection.request({
             method: "session/set_config_option",
             params: {
@@ -8646,6 +8690,12 @@ async function selectAcpNativeModel(args) {
     modelSelection: selection,
     nativeReasoning: args.nativeReasoning
   });
+  await selectAcpNativeServiceTier({
+    connection: args.connection,
+    sessionId: args.sessionId,
+    configOptions,
+    modelSelection: selection
+  });
 }
 async function selectAcpNativeReasoning(args) {
   const reasoningLevel = args.modelSelection.reasoningLevel;
@@ -8676,6 +8726,28 @@ async function selectAcpNativeReasoning(args) {
   } catch {
   }
 }
+async function selectAcpNativeServiceTier(args) {
+  const serviceTier = args.modelSelection.serviceTier;
+  if (serviceTier === void 0) {
+    return;
+  }
+  const fastOption = (args.configOptions ?? []).find(
+    (option) => option.id === "fast" && option.type === "select"
+  );
+  const value = serviceTier === "fast" ? "true" : "false";
+  if (!fastOption?.options?.some((option) => option.value === value)) {
+    return;
+  }
+  await args.connection.request({
+    method: "session/set_config_option",
+    params: {
+      sessionId: args.sessionId,
+      configId: fastOption.id,
+      value
+    },
+    resultSchema: acpConfigStateResultSchema
+  });
+}
 function buildPromptContentBlocks(session, input) {
   const blocks = [];
   const instructions = session.pendingInstructions;
@@ -9041,10 +9113,10 @@ async function startAgentSession(request) {
       params: {
         protocolVersion: ACP_PROTOCOL_VERSION,
         clientInfo: { name: "bb", version: "1.0.0" },
-        clientCapabilities: {
-          fs: { readTextFile: true, writeTextFile: true },
-          terminal: false
-        }
+        clientCapabilities: acpClientCapabilities(
+          params.parameterizedModelPicker,
+          true
+        )
       },
       resultSchema: acpInitializeResultSchema
     });
@@ -9514,15 +9586,22 @@ async function handleModelList(id, params) {
     );
     return;
   }
-  const sessionDiscoveredModels = params.listCommand === void 0 && params.agent ? await loadSessionDiscoveredModels(params.agent) : null;
+  const sessionDiscoveredModels = params.listCommand === void 0 && params.agent ? await loadSessionDiscoveredModels(
+    params.agent,
+    params.reasoningProbePriorityModelIds,
+    params.parameterizedModelPicker
+  ) : null;
   if (sessionDiscoveredModels) {
-    sendResult(id, {
-      models: applyConfiguredReasoningToModels(sessionDiscoveredModels, {
-        reasoningCli: params.reasoningCli,
-        nativeReasoning: params.nativeReasoning
-      }),
-      selectedOnlyModels: []
-    });
+    sendResult(
+      id,
+      splitPrimaryModels(
+        applyConfiguredReasoningToModels(sessionDiscoveredModels, {
+          reasoningCli: params.reasoningCli,
+          nativeReasoning: params.nativeReasoning
+        }),
+        params.primaryModels
+      )
+    );
     return;
   }
   sendResult(id, {
@@ -9554,8 +9633,24 @@ var acpProviderOptionsSchema = z39.object({
    * the provider, so a third-party registration of a known agent gets the
    * same reporting fidelity a first-party one does.
    */
-  acpDialect: z39.string().min(1).optional()
+  acpDialect: z39.string().min(1).optional(),
+  /** Enables an agent's separate model configuration options. */
+  parameterizedModelPicker: z39.boolean().optional(),
+  /** Bare model ids shown before the collapsed "More models" pool. */
+  primaryModels: z39.array(z39.string().min(1)).optional(),
+  /** Model ids to probe first during bounded native discovery. */
+  reasoningProbePriorityModelIds: z39.array(z39.string().min(1)).optional()
 }).passthrough();
+function decodeAcpModelPickerOptions(providerOptions) {
+  const parsed = acpProviderOptionsSchema.parse(providerOptions ?? {});
+  return {
+    parameterizedModelPicker: parsed.parameterizedModelPicker === true,
+    ...parsed.primaryModels === void 0 ? {} : { primaryModels: [...parsed.primaryModels] },
+    reasoningProbePriorityModelIds: [
+      ...parsed.reasoningProbePriorityModelIds ?? []
+    ]
+  };
+}
 function decodeAdditionalWorkspaceWriteRoots(providerOptions) {
   return acpProviderOptionsSchema.parse(providerOptions ?? {}).additionalWorkspaceWriteRoots ?? [];
 }
@@ -9597,14 +9692,19 @@ async function handleRequest2(request) {
       };
       sendResult(request.id, result);
       return;
-    case "model/list":
+    case "model/list": {
+      const modelPicker = decodeAcpModelPickerOptions(
+        request.params.providerOptions
+      );
       await handleModelList(
         request.id,
         buildAcpModelListParams(
-          decodeLaunchSpec(request.params.providerOptions)
+          decodeLaunchSpec(request.params.providerOptions),
+          modelPicker
         )
       );
       return;
+    }
     case "provider/health": {
       const launchSpec = decodeLaunchSpec(request.params.providerOptions);
       sendResult(
@@ -9683,6 +9783,9 @@ async function handleRequest2(request) {
         );
         return;
       }
+      const modelPicker = decodeAcpModelPickerOptions(
+        params.options.providerOptions
+      );
       const sessionParams = buildAcpSessionParams({
         additionalWorkspaceWriteRoots: decodeAdditionalWorkspaceWriteRoots(
           params.options.providerOptions
@@ -9694,6 +9797,7 @@ async function handleRequest2(request) {
           ...params.options,
           skillRoots: configuredSkillRoots ?? void 0
         },
+        parameterizedModelPicker: modelPicker.parameterizedModelPicker,
         launchSpec,
         providerLabel: launchSpec.displayName,
         threadId: params.threadId

package/dist/testing/index.js

@@ -37,16 +37,23 @@ function parseNamespacedGlyph(glyph) {
 // ../domain/src/plugin-cli.ts
 var RESERVED_BB_CLI_COMMANDS = [
   "environment",
+  "file",
   "guide",
   "help",
+  "machine",
   "manager",
+  "marketplace",
   "plugin",
   "project",
   "provider",
+  "settings",
   "skill",
   "status",
+  "terminal",
   "theme",
-  "thread"
+  "thread",
+  "updates",
+  "voice"
 ];
 
 // ../domain/src/provider-fork.ts
@@ -265,6 +272,10 @@ var providerNativeRootSetSchema = z2.object({
 var PLUGIN_CLI_OUTPUT_MAX_BYTES = 1024 * 1024;
 
 // src/internal/host-policy.ts
+function pluginCliCollisionWarning(pluginId, commandName) {
+  if (!RESERVED_BB_CLI_COMMANDS.includes(commandName)) return null;
+  return `CLI command "${commandName}" collides with core command "bb ${commandName}"; core keeps the short form. Use "bb plugin run ${pluginId}" to invoke this plugin.`;
+}
 var RESERVED_AGENT_TOOL_NAMES = [
   "update_environment_directory"
 ];
@@ -2265,11 +2276,6 @@ function createFakePluginHostInternal(options, sharedState) {
           `invalid cli command name ${JSON.stringify(name)} \u2014 use lowercase letters, digits, and "-"`
         );
       }
-      if (RESERVED_BB_CLI_COMMANDS.includes(name)) {
-        throw new Error(
-          `cli command name "${name}" is reserved by the bb CLI \u2014 pick another name`
-        );
-      }
       if (typeof registration.summary !== "string" || registration.summary.trim().length === 0) {
         throw new Error(`cli command "${name}" must provide a summary`);
       }
@@ -2300,6 +2306,8 @@ function createFakePluginHostInternal(options, sharedState) {
         commands: validatedCommands,
         run: registration.run.bind(registration)
       };
+      const warning = pluginCliCollisionWarning(pluginId, name);
+      if (warning) emitLog("warn", warning);
     }
   };
   const agentTools = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@get-bb/plugin-sdk",
-  "version": "0.4.17",
+  "version": "0.4.18",
   "homepage": "https://github.com/get-bb/bb#readme",
   "bugs": {
     "url": "https://github.com/get-bb/bb/issues"