@get-bb/plugin-sdk 0.4.14 → 0.4.16

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

@@ -5,6 +5,8 @@
 // Confused by the API, or need a symbol that isn't here? Clone the BB repo
 // and read the real source: https://github.com/get-bb/bb
 
+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
@@ -16,6 +18,58 @@
  */
 declare const RESERVED_BB_CLI_COMMANDS: readonly string[];
 
+/** Input-form entry: a path, or a path with options. */
+declare const providerNativeRootInputSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    ancestors: z.ZodOptional<z.ZodBoolean>;
+    namePrefix: z.ZodOptional<z.ZodString>;
+    path: z.ZodString;
+    recursive: z.ZodOptional<z.ZodBoolean>;
+    skipIfManifest: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>]>;
+/**
+ * One provider-native root as a plugin declares it: a path, or a path with
+ * options. `recursive`: the agent scans nested skill directories. `ancestors`
+ * (project roots only): scan the same relative directory in every ancestor of
+ * the workspace up to the repository root. `namePrefix`: prepended to every
+ * name under the root, a vendor plugin's `plugin-name:`; a prefixed root is
+ * listed as a plugin root. `skipIfManifest`: a vendor-plugin marker file to
+ * skip by.
+ */
+type ProviderNativeRootInput = z.infer<typeof providerNativeRootInputSchema>;
+/**
+ * Normalized roots: relative to the host home (`user`) or to the workspace
+ * (`project`). The daemon parses this off the wire; the server produces it
+ * from a declaration.
+ */
+declare const providerNativeRootsSchema: z.ZodObject<{
+    project: z.ZodArray<z.ZodObject<{
+        ancestors: z.ZodBoolean;
+        namePrefix: z.ZodString;
+        path: z.ZodString;
+        recursive: z.ZodBoolean;
+        skipIfManifest: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    user: z.ZodArray<z.ZodObject<{
+        ancestors: z.ZodBoolean;
+        namePrefix: z.ZodString;
+        path: z.ZodString;
+        recursive: z.ZodBoolean;
+        skipIfManifest: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type ProviderNativeRoots = z.infer<typeof providerNativeRootsSchema>;
+/**
+ * Provider-native roots as a plugin's frozen declaration holds them: relative
+ * to the target host's home (`user`) or to the workspace (`project`). Paths
+ * are relative without dot segments, unique per side, at most 32 per side. A
+ * root only one host can name — a moved config directory, a settings entry —
+ * is the resolver's answer (`resolveNativeRoots`), never a declared root.
+ */
+interface ProviderNativeRootsInputLike {
+    readonly user?: readonly ProviderNativeRootInput[];
+    readonly project?: readonly ProviderNativeRootInput[];
+}
+
 /**
  * How completely a provider can clone one of its sessions — the single
  * vocabulary shared by the provider declaration
@@ -89,6 +143,11 @@ type PluginSettingDescriptor = {
     description?: string;
     /** Stored in a 0600 file under <dataDir>/plugins/<id>/secrets/, never in the db or sent to the frontend. */
     secret?: true;
+    /**
+     * Render as a multi-line text field; for JSON or lists. Secrets cannot
+     * be multi-line.
+     */
+    experimental_multiline?: boolean;
     default?: string;
 } | {
     type: "boolean";
@@ -124,6 +183,45 @@ interface PluginCliExecutionResult {
     stderr: string;
     error?: PluginCliOutputLimitError;
 }
+/**
+ * The row title of a plugin tool call while it is pending and once it
+ * settled. Each label is capped at 80 characters and rendered as plain text.
+ */
+interface PluginAgentToolLabels {
+    /** Label shown while the tool call is pending. */
+    pending: string;
+    /** Label shown after the tool call completes successfully. */
+    completed: string;
+}
+/**
+ * How calls to a native plugin tool read as a timeline row (grammar v3). Every
+ * field is optional at registration: the server fills what the plugin leaves
+ * out (a generic `Running <name>` / `Ran <name>` label; the plugin's branding
+ * glyph, then `Toolbox`) and hands one complete presentation to the provider
+ * bridge with the tool definition.
+ */
+interface PluginAgentToolPresentation {
+    /** Row title while the call is pending and once it settled. */
+    label?: PluginAgentToolLabels;
+    /**
+     * A named host glyph (`{ glyph: "Workflow" }`), or one of this plugin's
+     * own declared icons by its namespaced glyph (`{ glyph: "<pluginId>/<name>" }`,
+     * an entry of the manifest's `bb.branding.experimental_icons` map). A
+     * namespaced glyph that names another plugin or an undeclared name rejects
+     * the tool registration.
+     */
+    icon?: {
+        glyph: string;
+    };
+    /** Low-value rows clients collapse by default (a question a dedicated
+     * interaction row already shows, a bookkeeping call). */
+    suppress?: boolean;
+    /** Accent colour per theme; omitted rows use the neutral row tint. */
+    tint?: {
+        light: string;
+        dark: string;
+    };
+}
 /**
  * Permission modes a provider can run a session in — BB's own permission
  * vocabulary, ordered least ("accept-edits") to most ("full") privileged.
@@ -156,17 +254,6 @@ type PluginProviderComposerAction = "goal" | "plan";
  * 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;
@@ -246,7 +333,7 @@ interface PluginProviderExtensionKindDeclaration {
 }
 /**
  * Per-command context handed to
- * {@link PluginProviderDeclaration.experimental_deriveProviderOptions}. The
+ * {@link PluginProviderDeclaration.deriveProviderOptions}. The
  * server builds one for every session and turn command it dispatches on a
  * thread of this provider.
  */
@@ -272,6 +359,8 @@ interface PluginProviderOptionsContext {
      */
     settings: Readonly<Record<string, PluginSettingValue | undefined>>;
 }
+/** See {@link PluginProviderDeclaration.models}. */
+type PluginProviderModelCatalogScope = "host" | "workspace";
 /**
  * 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
@@ -293,6 +382,24 @@ interface PluginProviderFallbackModel {
     /** Exactly one entry in the list is the default. */
     isDefault: boolean;
 }
+/**
+ * Which sessionless maintenance requests a provider bridge implements. The
+ * server skips the requests a provider does not declare, and clients omit
+ * the matching surfaces, without starting the bridge first.
+ */
+interface PluginProviderMaintenance {
+    /** `provider/health`: host-local readiness, never a network health check. */
+    health?: boolean;
+    /** `provider/usage`: subscription usage windows. False means usage settings
+     * omit the provider. A shared bridge that declares true may still report
+     * usage unavailable for one provider id or return no windows. */
+    usage?: boolean;
+    /** `provider/installation/status` and `provider/installation/run`:
+     * host-local installation management. */
+    installation?: boolean;
+}
+/** Provider-native roots as a plugin declares them, one list per side. */
+type PluginProviderNativeRoots = ProviderNativeRootsInputLike;
 /**
  * One provider this plugin contributes to BB's provider registry.
  *
@@ -303,10 +410,14 @@ interface PluginProviderFallbackModel {
  * reload, like every other plugin surface.
  *
  * 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.
+ * executable implementation is the plugin's own provider bridge: the
+ * `experimental_providerBridge` export of the `bb.host` artifact the manifest
+ * names (`PROVIDER_BRIDGE_EXPORT_NAME` in the bridge kit), built into the
+ * artifact BB ships to hosts. Declaring a provider in a plugin with no
+ * `bb.host` entry is refused, because the picker entry would exist and no
+ * turn on it could ever run; a `bb.host` entry whose artifact failed to
+ * build still stages the declaration so the provider is listed as
+ * unavailable.
  */
 interface PluginProviderDeclaration {
     /** Stable provider id: 2–64 characters of lowercase letters, digits, and
@@ -320,11 +431,15 @@ interface PluginProviderDeclaration {
      * 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;
+    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 `"./"`
-     * (`"./icons/agent.svg"`). Paths follow the manifest entry-path escape rules
+     * Optional picker icon: a named host glyph (`"Zap"`) or a plugin-relative
+     * path starting with `"./"` (`"./icons/agent.svg"`) — the two forms
+     * `bb.branding.icon` takes — or, unlike `bb.branding.icon`, one of this
+     * plugin's declared icons by its namespaced glyph (`"<pluginId>/<name>"`,
+     * an entry of the manifest's `bb.branding.experimental_icons` map; the
+     * plugin id must be this plugin's and the name must be declared, else the
+     * plugin fails to load). Paths follow the manifest entry-path escape rules
      * — no leading "/", no ".." segments, no backslashes.
      */
     icon?: string;
@@ -341,6 +456,11 @@ interface PluginProviderDeclaration {
      * bridge reports it installed. Defaults to `"always"`.
      */
     experimental_visibility?: "always" | "installed";
+    /**
+     * The sessionless maintenance requests the provider's bridge implements
+     * (docs/provider-plugin-api.md §1). Each defaults to false when omitted.
+     */
+    maintenance?: PluginProviderMaintenance;
     /** Pre-session capability facts (see the declaration tests on
      * {@link PluginProviderCapabilities}). */
     capabilities: PluginProviderCapabilities;
@@ -348,27 +468,44 @@ interface PluginProviderDeclaration {
      * (the universal skills typeahead is implicit). */
     composerActions: readonly PluginProviderComposerAction[];
     /** Provider copy for core surfaces ({@link PluginProviderStrings}). */
-    experimental_strings?: PluginProviderStrings;
+    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[];
+    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[];
+    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>>;
+    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[];
+    models?: {
+        /**
+         * Optional: a provider that only declares a catalog `scope` needs no
+         * fallback list, and an omitted list reads as no fallbacks at all.
+         */
+        fallback?: readonly PluginProviderFallbackModel[];
+        /**
+         * How far one `model/list` answer travels. `"host"` means the catalog is
+         * the same everywhere on a machine — the bridge answers from account or
+         * agent state and ignores the workspace path — so bb probes once per host
+         * and reuses the answer for every environment on it. `"workspace"` (the
+         * default) means project configuration can change the answer, so bb
+         * probes per workspace and sends the path.
+         *
+         * Declaring `"host"` wrongly is a stale catalog in a workspace that
+         * configured its own models; declaring `"workspace"` wrongly costs a
+         * redundant probe. The default is therefore the safe one.
+         */
+        scope?: PluginProviderModelCatalogScope;
     };
     /**
      * Daemon environment variables this provider's bridge may read. Provider
@@ -377,9 +514,38 @@ interface PluginProviderDeclaration {
      * and the daemon forwards exactly those variables. Names are
      * `[A-Z_][A-Z0-9_]*`, at most 32.
      */
-    experimental_env?: {
+    env?: {
         passthrough: readonly string[];
     };
+    /**
+     * Directories this provider's agent reads its own skills from, relative to
+     * the target host's home directory (`user`) or to the workspace
+     * (`project`). An agent with skills of its own — an ACP agent pointed at
+     * `.cursor/skills`, say — names them here so bb can list them beside its
+     * own; core never guesses a provider's skill layout. Paths are relative
+     * and may not contain dot segments; each side holds at most 32 roots. One
+     * declaration is global, so a directory only one host can name (an agent's
+     * settings-configured skills directory, say) is not declared here but
+     * resolved on that host (`experimental_resolvesNativeRoots`).
+     */
+    experimental_nativeSkillRoots?: PluginProviderNativeRoots;
+    /**
+     * Directories this provider's agent reads its own slash commands from —
+     * flat directories of `*.md` prompt files (`.claude/commands`, say) — in
+     * the same two-sided shape as `experimental_nativeSkillRoots`. bb offers
+     * them in the composer beside the agent's skills.
+     */
+    experimental_nativeCommandRoots?: PluginProviderNativeRoots;
+    /**
+     * This plugin's `bb.host` entry implements
+     * `experimental_nativeRootsHostContract` (`@get-bb/plugin-sdk/host`): core
+     * calls `resolveNativeRoots({ cwd })` on the workspace host when it lists
+     * commands or skills, and scans what comes back beside the declared roots.
+     * This is where a provider's host-only knowledge goes — a config-moved
+     * directory, an installed vendor plugin, a config-file entry — including
+     * project-scoped entries, which a global declaration cannot carry.
+     */
+    experimental_resolvesNativeRoots?: boolean;
     /**
      * Derive this provider's opaque per-command options. Called synchronously
      * by the server for every session and turn command on a thread of this
@@ -392,9 +558,30 @@ interface PluginProviderDeclaration {
      * 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>>;
+    deriveProviderOptions?: (context: PluginProviderOptionsContext) => Readonly<Record<string, JsonValue>>;
 }
 type PluginMentionTrigger = "!" | "#" | "$" | "@" | "~";
+/**
+ * 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.
+ */
+type PluginAiServiceKind = "inference" | "voice";
+/**
+ * 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.
+ */
+interface PluginAiServiceDeclaration {
+    /** The `<serviceId>` segment of the user's setting; stable, lowercase. */
+    readonly id: string;
+    /** Shown beside the id wherever the setting's options are listed. */
+    readonly displayName: string;
+    /** Which kinds this service answers; a kind it lacks is not offered. */
+    readonly kinds: readonly PluginAiServiceKind[];
+}
 
 /**
  * Built-in dynamic tool names plugins may not shadow. Maintained by hand —
@@ -435,6 +622,61 @@ declare const PLUGIN_PROVIDER_DISPLAY_NAME_MAX_CHARS = 80;
 declare const PLUGIN_PROVIDER_PERMISSION_MODE_VALUES: readonly ["accept-edits", "auto", "full"];
 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.
+ */
+declare const SERVER_DIRECT_AI_SERVICE_IDS: readonly string[];
+/**
+ * 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 aiServiceAlreadyRegisteredMessage(id: string): string;
+/** The collision a second registration of a live provider id raises. */
+declare function providerAlreadyRegisteredMessage(id: string): string;
 /**
  * Validate one `bb.providers.register` declaration. Plugin
  * sources are untyped at runtime, so every field is checked; the production
@@ -442,9 +684,31 @@ declare const PLUGIN_PROVIDER_COMPOSER_ACTION_VALUES: readonly ["plan", "goal"];
  * 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
+ * A declaration that has been through {@link validatePluginProviderDeclaration}.
+ *
+ * The validator fills the defaults it owns, so a consumer reads one explicit
+ * value rather than re-deciding what an absent field means. Only the fields
+ * the validator GUARANTEES are narrowed here; everything else keeps the
+ * author-facing shape.
+ */
+type NormalizedPluginProviderDeclaration = Omit<PluginProviderDeclaration, "experimental_nativeCommandRoots" | "experimental_nativeSkillRoots" | "experimental_resolvesNativeRoots"> & {
+    readonly experimental_nativeSkillRoots?: ProviderNativeRoots;
+    readonly experimental_nativeCommandRoots?: ProviderNativeRoots;
+    readonly experimental_resolvesNativeRoots: boolean;
+    readonly maintenance: {
+        readonly health: boolean;
+        readonly usage: boolean;
+        readonly installation: boolean;
+    };
+    readonly models: {
+        readonly fallback?: readonly PluginProviderFallbackModel[];
+        readonly scope: PluginProviderModelCatalogScope;
+    };
+};
+declare function validatePluginProviderDeclaration(declaration: PluginProviderDeclaration): NormalizedPluginProviderDeclaration;
+/**
+ * Run a declaration's `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
@@ -452,7 +716,7 @@ declare function validatePluginProviderDeclaration(declaration: PluginProviderDe
  */
 declare function deriveValidatedProviderOptions(args: {
     declaration: PluginProviderDeclaration;
-    context: Parameters<NonNullable<PluginProviderDeclaration["experimental_deriveProviderOptions"]>>[0];
+    context: Parameters<NonNullable<PluginProviderDeclaration["deriveProviderOptions"]>>[0];
 }): Readonly<Record<string, JsonValue>>;
 declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
 declare function readRpcMethodContract(method: string, value: unknown): PluginRpcMethodContract;
@@ -465,6 +729,24 @@ declare function isZodSchemaLike(value: unknown): boolean;
  * recursive `$ref`, so this is a shared production/fake-host boundary rule.
  */
 declare function assertNoRecursiveJsonSchemaReferences(schema: unknown, subject: string): void;
+/**
+ * Reject the fields a registration never reads. Renamed fields get the
+ * message above; any other `experimental_` field is unknown (the same
+ * rule configure() output follows in the plugin service). The production
+ * host and the fake host both call this before parsing `presentation`, so
+ * a registration built against an older SDK fails a plugin's own unit test
+ * with the message bb would give it.
+ */
+declare function rejectStaleAgentToolFields(toolName: string, tool: object): void;
+/**
+ * The declared shape of `presentation`, copied field by field so
+ * a plugin's object cannot smuggle prototypes or extra markup into the
+ * persisted row. Labels share the status-label length cap. The production
+ * host and the fake host both call this, so a presentation that registers
+ * in a plugin unit test registers in bb, and one bb rejects is rejected
+ * with the same message.
+ */
+declare function parsePluginAgentToolPresentation(toolName: string, value: unknown): PluginAgentToolPresentation | null;
 /** Compact issue summary from a (possibly foreign-instance) zod error. */
 declare function summarizeParseIssues(error: unknown): string;
 declare function enforcePluginCliOutputLimit(result: Omit<PluginCliExecutionResult, "error">, jsonOutput: boolean): PluginCliExecutionResult;
@@ -482,5 +764,30 @@ declare function enforcePluginCliOutputLimit(result: Omit<PluginCliExecutionResu
  * with cancellation forwarded to the source, so no full-size buffer is made.
  */
 declare function adoptHttpRouteResponse(value: unknown): Response;
+/**
+ * The one rule for a namespaced glyph (`"<pluginId>/<name>"`) wherever a
+ * plugin may reference its own declared icons — a tool presentation at
+ * `bb.agents.registerTool`, a provider icon at `bb.providers.register`, and a
+ * row presentation at ingest: the plugin id must be the emitting plugin's
+ * and the name must be in its `bb.branding.experimental_icons` map. The
+ * server and the fake plugin host apply it from here, so a registration the
+ * fake accepts is one the server accepts.
+ *
+ * Returns the reason a glyph is refused, always naming the glyph and the
+ * plugin, or null when the glyph is acceptable. A host glyph (no `/`) is
+ * never refused here: whether the client can draw it is the client's call.
+ */
+declare function undeclaredIconProblem(pluginId: string, declaredIconNames: ReadonlySet<string>, glyph: string): string | null;
+/** `bb.providers.register` refusal for an icon {@link undeclaredIconProblem} rejects. */
+declare function providerIconRefusalMessage(providerId: string, problem: string): string;
+/** `bb.agents.registerTool` refusal for a glyph {@link undeclaredIconProblem} rejects. */
+declare function agentToolIconRefusalMessage(toolName: string, problem: string): string;
+/**
+ * `bb.providers.register` refusal for a plugin whose manifest declares no
+ * `bb.host` entry: a declaration is metadata, and the bridge it runs on is
+ * that entry.
+ */
+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, SETTING_KEY_PATTERN, adoptHttpRouteResponse, assertNoRecursiveJsonSchemaReferences, deriveValidatedProviderOptions, 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, 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 type { AiServiceHostBinding, NormalizedPluginProviderDeclaration };

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

@@ -5,7 +5,7 @@
 // Confused by the API, or need a symbol that isn't here? Clone the BB repo
 // and read the real source: https://github.com/get-bb/bb
 
-import { PluginHomepageSectionRegistration, PluginSettingsSectionRegistration, PluginNavPanelRegistration, PluginThreadPanelActionRegistration, PluginNewThreadPanelActionRegistration, ComposerCustomization, PluginPendingInteractionRegistration, PluginSidebarFooterActionRegistration, PluginThreadListRegistration, PluginThreadHeaderActionRegistration, PluginFileOpenerRegistration, PluginSourceCodeRendererRegistration, PluginDiffRendererRegistration, PluginMessageDirectiveRegistration, PluginMessageActionRegistration, PluginCommandPaletteActionRegistration, PluginProviderIconRegistration, PluginContentScriptRegistration, PluginAppDefinition } from '@get-bb/plugin-sdk';
+import { PluginHomepageSectionRegistration, PluginSettingsSectionRegistration, PluginNavPanelRegistration, PluginThreadPanelActionRegistration, PluginNewThreadPanelActionRegistration, ComposerCustomization, PluginPendingInteractionRegistration, PluginSidebarFooterActionRegistration, PluginThreadListRegistration, PluginThreadHeaderActionRegistration, PluginFileOpenerRegistration, PluginSourceCodeRendererRegistration, PluginDiffRendererRegistration, PluginMessageDirectiveRegistration, PluginMessageActionRegistration, PluginCommandPaletteActionRegistration, PluginProviderIconRegistration, PluginTimelineRendererRegistration, PluginContentScriptRegistration, PluginAppDefinition } from '@get-bb/plugin-sdk';
 
 /** Validated registrations produced by one plugin app setup execution. */
 interface CollectedPluginAppRegistrations {
@@ -26,6 +26,7 @@ interface CollectedPluginAppRegistrations {
     messageActions: PluginMessageActionRegistration[];
     commandPaletteActions: PluginCommandPaletteActionRegistration[];
     providerIcons: PluginProviderIconRegistration[];
+    timelineRenderers: PluginTimelineRendererRegistration[];
     contentScripts: PluginContentScriptRegistration[];
 }
 /**