@get-bb/plugin-sdk 0.4.9 → 0.4.11

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

@@ -19,7 +19,7 @@ declare const RESERVED_BB_CLI_COMMANDS: readonly string[];
 /**
  * How completely a provider can clone one of its sessions — the single
  * vocabulary shared by the provider declaration
- * (`bb.agents.experimental_registerProvider`), the server→daemon
+ * (`bb.providers.register`), the server→daemon
  * `bridgeLaunch`, and the bridge's `initialize` handshake.
  *
  * - `"none"`: sessions cannot be cloned at all.
@@ -35,6 +35,16 @@ declare const RESERVED_BB_CLI_COMMANDS: readonly string[];
 declare const PROVIDER_FORK_VALUES: readonly ["none", "tip", "checkpoint"];
 type ProviderFork = (typeof PROVIDER_FORK_VALUES)[number];
 
+/**
+ * A value that survives a JSON round trip without coercion or data loss.
+ *
+ * Host boundaries still validate values at runtime because TypeScript cannot
+ * exclude non-finite numbers and plugin bundles can bypass static types.
+ */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+
 /**
  * The validator-neutral subset of Standard Schema v1 used by plugin RPC.
  * Zod 4 schemas implement this interface directly; other validators can do
@@ -98,6 +108,7 @@ type PluginSettingDescriptor = {
     default?: string;
 };
 type PluginSettingDescriptors = Record<string, PluginSettingDescriptor>;
+type PluginSettingValue = string | boolean;
 interface PluginCliOutputLimitError {
     code: "plugin_cli_output_too_large";
     message: string;
@@ -139,10 +150,23 @@ type PluginProviderComposerAction = "goal" | "plan";
  * live session (picker rendering, route gating, cross-plugin tool
  * composition — including with the host offline). Every boolean is a
  * provider-native fact — the provider implements the feature; the flag only
- * tells external consumers it exists. Everything else is a handshake fact the
- * bridge reports at `initialize`, where it cannot drift from behavior.
+ * tells external consumers it exists. Session-behavior facts remain handshake
+ * capabilities reported by the running bridge. Sessionless maintenance
+ * methods are declared here so callers can decide whether to probe without
+ * starting the bridge first.
  */
 interface PluginProviderCapabilities {
+    /** The provider bridge implements the sessionless `provider/health`
+     * request. This is host-local readiness, not a network health check. */
+    experimental_providerHealth: boolean;
+    /** The provider exposes subscription usage through the sessionless
+     * `provider/usage` request. False means callers skip the request and usage
+     * settings omit the provider. A shared bridge that declares true may still
+     * report usage unavailable for one provider id or return no windows. */
+    experimental_providerUsage: boolean;
+    /** The provider bridge implements `provider/installation/status` and
+     * `provider/installation/run` for host-local installation management. */
+    experimental_providerInstallation: boolean;
     /** The provider accepts a fast/priority service-tier choice — shows the
      * service-tier toggle in the picker. */
     supportsServiceTier: boolean;
@@ -167,9 +191,6 @@ interface PluginProviderCapabilities {
     /** The provider stores a thread name of its own, so BB forwards renames to
      * it. */
     supportsThreadRename: boolean;
-    /** The provider can run BB's Workflow tools — gates the workflows opt-in on
-     * new threads. */
-    supportsWorkflows: boolean;
     /** Permission modes the provider can actually run in. Non-empty, no
      * duplicates. */
     permissionModes: readonly PluginProviderPermissionMode[];
@@ -177,20 +198,115 @@ interface PluginProviderCapabilities {
      * {@link PluginProviderReasoningLevel}). Non-empty, no duplicates. */
     reasoningLevels: readonly PluginProviderReasoningLevel[];
 }
+/**
+ * Provider copy core surfaces render from per-provider tables today (usage
+ * banners, sign-in hints, the mobile picker, the agent guide). Declared once
+ * here so no core surface keys copy on a provider id. Mirrors
+ * `ProviderStrings` in `@bb/domain`, which is the client projection.
+ */
+interface PluginProviderStrings {
+    /** How to sign in on the host ("Run `claude` on the machine to sign in."). */
+    signInHint: string;
+    /** Shown when a session's credentials expired. */
+    expiredHint: string;
+    /** Where to install the agent. */
+    installUrl: string;
+    /** Brand prefix stripped from model display names ("Claude "). */
+    brandPrefix?: string;
+    /** Plan-mode banner copy for providers that declare the `plan` action. */
+    planModeCopy?: string;
+    /** Per-theme tint for the provider icon. */
+    iconTint?: {
+        light: string;
+        dark: string;
+    };
+}
+/**
+ * One selectable option for a picker — a service tier or a reasoning level.
+ * `id` is the wire value the bridge receives; `label` is what the picker
+ * shows. Declared lists are the cold-cache fallback; `model/list` is precise
+ * per model.
+ */
+interface PluginProviderOptionDescriptor {
+    id: string;
+    label: string;
+    description?: string;
+}
+/**
+ * Payload schemas for one extension kind this provider emits, keyed by the
+ * kind's local name (the server prefixes the plugin id to form the
+ * namespaced `"<pluginId>/<name>"`). `item` validates `item.open` payloads
+ * with `type: "extension"`, `state` validates `extension.state` payloads;
+ * each is optional so a kind can be item-only or state-only. Schemas are
+ * Standard Schema v1 validators (zod 4 schemas qualify).
+ */
+interface PluginProviderExtensionKindDeclaration {
+    item?: StandardSchemaV1;
+    state?: StandardSchemaV1;
+}
+/**
+ * Per-command context handed to
+ * {@link PluginProviderDeclaration.experimental_deriveProviderOptions}. The
+ * server builds one for every session and turn command it dispatches on a
+ * thread of this provider.
+ */
+interface PluginProviderOptionsContext {
+    threadId: string;
+    projectId: string;
+    /** The resolved model id for this command. */
+    model: string;
+    /** BB's permission mode for this command (already clamped to the host). */
+    permissionMode: PluginProviderPermissionMode;
+    /**
+     * `"plan"` when the prompt entered plan mode through this provider's
+     * declared `plan` composer action. Absent for an ordinary prompt — plan
+     * mode is a BB prompt mode, so the bridge maps it onto whatever the agent
+     * calls it natively.
+     */
+    promptMode?: "plan";
+    /**
+     * This plugin's own settings values (`bb.settings.define`), read at call
+     * time. Secret settings are omitted — provider options ride the daemon
+     * wire and are persisted with the session, so a secret must never be
+     * derived into them.
+     */
+    settings: Readonly<Record<string, PluginSettingValue | undefined>>;
+}
+/**
+ * One cold-cache fallback model. The provider's live `model/list` result is
+ * the only real model source; this list stands in only while no probe has
+ * completed, or when a probe fails transiently, so the picker is not empty.
+ * `id` is the wire model id the bridge receives.
+ */
+interface PluginProviderFallbackModel {
+    id: string;
+    /** Picker display name ("Opus 5 (1M)"). */
+    displayName: string;
+    description: string;
+    /** Reasoning levels this model supports, lowest to highest. Non-empty. */
+    supportedReasoningEfforts: readonly {
+        reasoningEffort: PluginProviderReasoningLevel;
+        description: string;
+    }[];
+    /** Must be one of `supportedReasoningEfforts`. */
+    defaultReasoningEffort: PluginProviderReasoningLevel;
+    /** Exactly one entry in the list is the default. */
+    isDefault: boolean;
+}
 /**
  * One provider this plugin contributes to BB's provider registry.
  *
  * Ids are stable public identifiers — thread rows and routes reference them —
  * and are collision-rejected: a declaration whose id matches another plugin's
- * live registration, or reserves a first-party provider it does not own, is
- * refused. Registrations are replaced wholesale on plugin reload, like every
- * other plugin surface.
+ * live registration is refused; the first registration wins and no id is
+ * reserved ahead of time. Registrations are replaced wholesale on plugin
+ * reload, like every other plugin surface.
  *
- * A declaration is metadata only. The implementation is the plugin's own
- * provider bridge, named by `bb.providerBridge` in the manifest and built into
- * the artifact BB ships to hosts — declaring a provider without one is
- * refused, because the picker entry would exist and no turn on it could ever
- * run.
+ * A declaration owns the provider's static metadata and bridge options. The
+ * executable implementation is the plugin's own provider bridge, named by
+ * `bb.providerBridge` in the manifest and built into the artifact BB ships to
+ * hosts — declaring a provider without one is refused, because the picker
+ * entry would exist and no turn on it could ever run.
  */
 interface PluginProviderDeclaration {
     /** Stable provider id: 2–64 characters of lowercase letters, digits, and
@@ -199,6 +315,12 @@ interface PluginProviderDeclaration {
     id: string;
     /** Picker display name: 1–80 characters, non-blank. */
     displayName: string;
+    /**
+     * Optional grouping key (same grammar as `id`) for providers that share a
+     * family — the ACP agents, for example — so clients can group them without
+     * parsing a prefix out of the id. Grouping only: no policy keys on it.
+     */
+    experimental_family?: string;
     /**
      * Optional picker icon, in the same grammar as `bb.branding.icon`: either a
      * named host glyph (`"Zap"`) or a plugin-relative path starting with `"./"`
@@ -206,12 +328,71 @@ interface PluginProviderDeclaration {
      * — no leading "/", no ".." segments, no backslashes.
      */
     icon?: string;
+    /**
+     * Provider-owned static options passed opaquely to this plugin's bridge on
+     * every sessionless and session request. Core validates that the value is
+     * JSON, but does not interpret its keys. This is intended for immutable
+     * launch metadata shared by every host (for example an ACP command spec),
+     * not user or machine configuration.
+     */
+    experimental_bridgeOptions?: Readonly<Record<string, JsonValue>>;
+    /**
+     * Whether the provider is always listed or only listed on hosts where its
+     * bridge reports it installed. Defaults to `"always"`.
+     */
+    experimental_visibility?: "always" | "installed";
     /** Pre-session capability facts (see the declaration tests on
      * {@link PluginProviderCapabilities}). */
     capabilities: PluginProviderCapabilities;
     /** Composer actions this provider supports. No duplicates; may be empty
      * (the universal skills typeahead is implicit). */
     composerActions: readonly PluginProviderComposerAction[];
+    /** Provider copy for core surfaces ({@link PluginProviderStrings}). */
+    experimental_strings?: PluginProviderStrings;
+    /** Service tiers this provider accepts, as picker options. Non-empty when
+     * present, unique ids. The coarse `capabilities.supportsServiceTier` stays
+     * until WS2a stabilizes. */
+    experimental_serviceTiers?: readonly PluginProviderOptionDescriptor[];
+    /** Reasoning levels as picker options with labels, beside the coarse
+     * `capabilities.reasoningLevels` ladder (ids only). Non-empty when present,
+     * unique ids. WS2a merges the two. */
+    experimental_reasoningLevels?: readonly PluginProviderOptionDescriptor[];
+    /** Extension kinds this provider's bridge may emit, keyed by local name
+     * (`[a-z0-9-]+`). The server validates extension payloads against these
+     * schemas at ingest and persists a `provider/unhandled` on a miss. */
+    experimental_extensionKinds?: Readonly<Record<string, PluginProviderExtensionKindDeclaration>>;
+    /**
+     * Cold-cache fallback models ({@link PluginProviderFallbackModel}). The
+     * server offers them only while a model probe has not completed or failed
+     * transiently; the live `model/list` result always replaces them. Ids must
+     * be unique and exactly one entry must be the default.
+     */
+    experimental_models?: {
+        fallback: readonly PluginProviderFallbackModel[];
+    };
+    /**
+     * Daemon environment variables this provider's bridge may read. Provider
+     * processes are spawned with every inherited `BB_*` variable stripped, so a
+     * bridge that honors an operator override (a CLI path, say) names it here
+     * and the daemon forwards exactly those variables. Names are
+     * `[A-Z_][A-Z0-9_]*`, at most 32.
+     */
+    experimental_env?: {
+        passthrough: readonly string[];
+    };
+    /**
+     * Derive this provider's opaque per-command options. Called synchronously
+     * by the server for every session and turn command on a thread of this
+     * provider, with the command's {@link PluginProviderOptionsContext}; the
+     * returned JSON object reaches this plugin's bridge as
+     * `options.providerOptions`, merged over `experimental_bridgeOptions`. Core
+     * never interprets its keys — this is where a provider's own knobs (memory,
+     * native subagents, a native plan flag) travel instead of on the shared
+     * execution contract. A throw fails the command with the plugin named, so
+     * a buggy hook cannot silently run a turn with default knobs. Must be fast:
+     * it sits on the turn-submit path.
+     */
+    experimental_deriveProviderOptions?: (context: PluginProviderOptionsContext) => Readonly<Record<string, JsonValue>>;
 }
 type PluginMentionTrigger = "!" | "#" | "$" | "@" | "~";
 
@@ -237,6 +418,7 @@ declare const PLUGIN_AGENT_DYNAMIC_INSTRUCTIONS_MAX_CHARS = 4096;
 declare const PLUGIN_AGENT_TOOL_PARAMETERS_MAX_BYTES: number;
 declare const MENTION_PROVIDER_ID_PATTERN: RegExp;
 declare const PROVIDER_ID_PATTERN: RegExp;
+declare const PLUGIN_PROVIDER_BRIDGE_OPTIONS_MAX_BYTES: number;
 declare const SETTING_KEY_PATTERN: RegExp;
 /**
  * Validate freeform descriptors from plugin code and merge them into the
@@ -254,13 +436,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"];
 /**
- * Validate one `bb.agents.experimental_registerProvider` declaration. Plugin
+ * Validate one `bb.providers.register` declaration. Plugin
  * sources are untyped at runtime, so every field is checked; the production
  * host and the fake host both call this, so they accept and reject provider
  * declarations identically. Throws a descriptive error on the first problem;
  * returns a normalized, deeply frozen copy carrying only contract fields.
  */
 declare function validatePluginProviderDeclaration(declaration: PluginProviderDeclaration): PluginProviderDeclaration;
+/**
+ * Run a declaration's `experimental_deriveProviderOptions` hook for one
+ * command and validate its result as a bounded, plain-JSON object — the same
+ * rules as `experimental_bridgeOptions`, because the result rides the same
+ * wire slot. Shared by the real host and the fake so a hook that works in
+ * tests works in production.
+ */
+declare function deriveValidatedProviderOptions(args: {
+    declaration: PluginProviderDeclaration;
+    context: Parameters<NonNullable<PluginProviderDeclaration["experimental_deriveProviderOptions"]>>[0];
+}): Readonly<Record<string, JsonValue>>;
 declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
 declare function readRpcMethodContract(method: string, value: unknown): PluginRpcMethodContract;
 /** Duck-typed zod detection: plugin sources may carry their own zod copy,
@@ -290,4 +483,4 @@ declare function enforcePluginCliOutputLimit(result: Omit<PluginCliExecutionResu
  */
 declare function adoptHttpRouteResponse(value: unknown): Response;
 
-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_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, SETTING_KEY_PATTERN, adoptHttpRouteResponse, assertNoRecursiveJsonSchemaReferences, enforcePluginCliOutputLimit, isPluginMentionTrigger, isStandardSchema, isZodSchemaLike, normalizeMentionProviderTriggers, readRpcMethodContract, registerSettingDescriptors, summarizeParseIssues, 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, SETTING_KEY_PATTERN, adoptHttpRouteResponse, assertNoRecursiveJsonSchemaReferences, deriveValidatedProviderOptions, enforcePluginCliOutputLimit, isPluginMentionTrigger, isStandardSchema, isZodSchemaLike, normalizeMentionProviderTriggers, readRpcMethodContract, registerSettingDescriptors, summarizeParseIssues, validatePluginProviderDeclaration, validateSettingsUpdate };