@get-bb/plugin-sdk 0.4.99 → 0.4.101

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

@@ -855,6 +855,23 @@ interface ExperimentalAppOverlayRegistration {
     id: string;
     component: ComponentType<ExperimentalAppOverlayProps>;
 }
+/**
+ * A name the host resolves to a glyph, in this order: a name any plugin
+ * registered with `app.experimental_icons.register()`, then a built-in BB icon
+ * name (`"Zap"`), then a namespaced `"<pluginId>/<name>"` glyph naming an
+ * entry of that plugin's manifest `bb.branding.experimental_icons` map. A
+ * registration therefore shadows a built-in, and either shadows a declared
+ * icon of the same name. Names that resolve to none of the three fall back to
+ * the surface's generic icon.
+ *
+ * Declared icons and registrations are one vocabulary here: the same name
+ * works in `experimental_Icon`, in every field below, and — for a declared
+ * icon — in the tool, provider and bridge-row declarations that accept one.
+ * Declared icons need no frontend bundle and survive the plugin being stopped;
+ * registrations can be any React component but live only while the plugin's
+ * app bundle is loaded.
+ */
+type BbIconName = string;
 /**
  * Owner-defined validator for a fixed tab's transient target. The host first
  * verifies that the value is JSON-safe, then calls this validator before
@@ -879,8 +896,7 @@ type ExperimentalPluginFixedTabReference<Target extends JsonValue$1 = never> = {
 /** A fixed tab declared by a plugin nav panel. */
 type PluginFixedTabRegistration<Target extends JsonValue$1 = never> = ExperimentalPluginFixedTabReference<Target> & {
     title: string;
-    /** Icon hint (BB icon name); unknown names fall back to a generic icon. */
-    icon: string;
+    icon: BbIconName;
     component: ComponentType<PluginNavPanelProps>;
     /** `flush` lets the component own padding and scrolling. */
     layout?: "flush" | "padded";
@@ -891,8 +907,7 @@ interface PluginNavPanelRegistration {
     /** Unique within the plugin; letters, digits, `-`, `_`. */
     id: string;
     title: string;
-    /** Icon hint (BB icon name); unknown names fall back to a generic icon. */
-    icon: string;
+    icon: BbIconName;
     /** URL segment under `/plugins/<pluginId>/`; letters, digits, `-`, `_`. */
     path: string;
     component: ComponentType<PluginNavPanelProps>;
@@ -975,10 +990,10 @@ interface PluginThreadPanelActionRegistration {
     /** Label of the action row in the panel's new-tab launcher. */
     title: string;
     /**
-     * Icon hint (BB icon name) used when the plugin ships no logo; the
-     * launcher row and opened tabs prefer the plugin's logo.
+     * Drawn only when the manifest declares no `bb.branding.icon`; the launcher
+     * row and opened tabs prefer that over this hint.
      */
-    icon?: string;
+    icon?: BbIconName;
     /** Rendered inside every panel tab this action opens. */
     component: ComponentType<PluginThreadPanelProps>;
     /**
@@ -1015,8 +1030,8 @@ interface PluginNewThreadPanelActionRegistration {
     id: string;
     /** Label of the action row in the panel's new-tab launcher. */
     title: string;
-    /** Icon hint (BB icon name) used when the plugin ships no logo. */
-    icon?: string;
+    /** Drawn only when the manifest declares no `bb.branding.icon`. */
+    icon?: BbIconName;
     /** Rendered inside every panel tab this action opens. */
     component: ComponentType<PluginNewThreadPanelProps>;
     /** Host framing; matches `threadPanelAction`. */
@@ -1060,8 +1075,8 @@ interface PluginSidebarFooterActionRegistration {
     id: string;
     /** Tooltip and accessible label for the icon button. */
     title: string;
-    /** Icon hint (BB icon name); unknown names fall back to a generic icon. */
-    icon: string;
+    /** Drawn only when the manifest declares no `bb.branding.icon`. */
+    icon: BbIconName;
     /**
      * Runs when the user activates the action (e.g. call `openSettings()`,
      * open a panel via other surfaces, toast). Errors (sync or async) are
@@ -1080,8 +1095,7 @@ interface ExperimentalSidebarFooterItemBase {
     id: string;
     /** Tooltip and accessible label for the host-rendered icon button. */
     label: string;
-    /** BB icon-name hint; unknown names fall back to a generic icon. */
-    icon: string;
+    icon: BbIconName;
 }
 /** A sidebar-footer item that runs a callback when activated. */
 interface ExperimentalSidebarFooterActionRegistration extends ExperimentalSidebarFooterItemBase {
@@ -1558,8 +1572,7 @@ interface PluginMessageActionRegistration {
     id: string;
     /** Tooltip / menu label for the action. */
     title: string;
-    /** Icon hint (BB icon name); unknown names fall back to a generic icon. */
-    icon?: string;
+    icon?: BbIconName;
     /**
      * Runs when the user activates the action. Errors (sync or async) are
      * contained and logged; they never break the timeline.
@@ -1990,6 +2003,11 @@ interface ExperimentalProviderIconProps {
     "aria-hidden"?: boolean | "false" | "true";
     "aria-label"?: string;
 }
+/**
+ * An app icon registered by a plugin. The registry is app-wide: a registered
+ * name is usable wherever a `BbIconName` is — `experimental_Icon`, and every
+ * host-rendered surface that takes one — by this plugin or any other.
+ */
 interface ExperimentalIconRegistration {
     /** Shared app name. Namespacing is recommended, but not required. */
     name: string;
@@ -2000,10 +2018,11 @@ interface ExperimentalIconRegistration {
 }
 interface ExperimentalAppIcons {
     /**
-     * Add or override an app icon during setup. Returns nothing; the host
-     * replaces registrations on reload and removes them on unload. Duplicate
-     * names within a plugin reject setup. Between plugins, the first plugin id
-     * in lexical order wins, independent of bundle load order.
+     * Add or override an app icon during setup. A registered name shadows a
+     * built-in of the same name. Returns nothing; the host replaces
+     * registrations on reload and removes them on unload. Duplicate names within
+     * a plugin reject setup. Between plugins, the first plugin id in lexical
+     * order wins, independent of bundle load order.
      */
     register(registration: ExperimentalIconRegistration): void;
 }
@@ -2088,8 +2107,8 @@ interface ComposerCustomization {
 interface ComposerPlusMenuItem {
     id: string;
     label: string;
-    /** BB icon name; unknown names fall back to the generic plugin icon. */
-    icon?: string;
+    /** Drawn only when the manifest declares no `bb.branding.icon`. */
+    icon?: BbIconName;
     /** Accessible description for the host-rendered row. */
     description?: string;
     disabled?: boolean | ((view: ComposerView) => boolean);
@@ -2142,8 +2161,11 @@ interface PluginComposerTextEffect {
 }
 /** Host-rendered status that temporarily replaces a thread's draft glyph. */
 interface PluginComposerThreadRowStatus {
-    /** BB icon-name hint; unknown names fall back to the generic plugin icon. */
-    icon: string;
+    /**
+     * Always drawn as given: unlike the plugin-badged surfaces, this one has no
+     * preference for the plugin's own `bb.branding.icon`.
+     */
+    icon: BbIconName;
     /** Accessible label for the status glyph. */
     label: string;
     /**
@@ -2276,8 +2298,7 @@ interface ThreadChatMessageAction {
     id: string;
     /** Tooltip / menu label for the action. */
     title: string;
-    /** Icon hint (BB icon name); unknown names fall back to a generic icon. */
-    icon?: string;
+    icon?: BbIconName;
     /**
      * Message roles the action applies to. Omitted = both user and assistant
      * messages.

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

@@ -300,6 +300,21 @@ type CallerExecutionInputSource = z.infer<typeof callerExecutionInputSourceSchem
 declare const PROVIDER_FORK_VALUES: readonly ["none", "tip", "checkpoint"];
 type ProviderFork = (typeof PROVIDER_FORK_VALUES)[number];
 
+declare const threadTurnInitiatorSchema: z.ZodEnum<{
+    agent: "agent";
+    system: "system";
+    user: "user";
+}>;
+type ThreadTurnInitiator = z.infer<typeof threadTurnInitiatorSchema>;
+
+declare const threadCreateOriginSchema: z.ZodEnum<{
+    app: "app";
+    cli: "cli";
+    plugin: "plugin";
+    sdk: "sdk";
+}>;
+type ThreadCreateOrigin = z.infer<typeof threadCreateOriginSchema>;
+
 declare const threadQueuedMessageSchema: z.ZodObject<{
     content: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         mentions: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -394,6 +409,13 @@ declare const threadQueuedMessageSchema: z.ZodObject<{
         user: "user";
     }>;
     model: z.ZodString;
+    origin: z.ZodNullable<z.ZodEnum<{
+        app: "app";
+        cli: "cli";
+        plugin: "plugin";
+        sdk: "sdk";
+    }>>;
+    originPluginId: z.ZodNullable<z.ZodString>;
     payload: z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"inline">;
     }, z.core.$strip>, z.ZodObject<{
@@ -448,22 +470,7 @@ declare const threadQueuedMessageSchema: z.ZodObject<{
 }, z.core.$strip>;
 type ThreadQueuedMessage = z.infer<typeof threadQueuedMessageSchema>;
 
-declare const threadCreateOriginSchema: z.ZodEnum<{
-    app: "app";
-    cli: "cli";
-    plugin: "plugin";
-    sdk: "sdk";
-}>;
-type ThreadCreateOrigin = z.infer<typeof threadCreateOriginSchema>;
 type ExecutionInputFieldSource = CallerExecutionInputSource;
-declare const startedOnBehalfOfSchema: z.ZodObject<{
-    initiator: z.ZodEnum<{
-        agent: "agent";
-        system: "system";
-    }>;
-    senderThreadId: z.ZodString;
-}, z.core.$strip>;
-type StartedOnBehalfOf = z.infer<typeof startedOnBehalfOfSchema>;
 declare const threadResponseSchema: z.ZodObject<{
     activeBackgroundAgentCount: z.ZodNumber;
     archivedAt: z.ZodNullable<z.ZodNumber>;
@@ -1016,8 +1023,26 @@ interface MessageDispatchHookContext {
     /** Whether this attempt starts a turn or joins a running one. */
     attempt: PluginDispatchAttemptKind;
     /**
-     * The queued row this attempt is re-trying, or null when the attempt is
-     * inline and no row has ever existed for it.
+     * The author category shared by this dispatch's messages: `user`, `agent`,
+     * or `system`. `mixed` means the queued messages have different categories.
+     * Different agents still share the `agent` category; read `queuedMessages`
+     * for each message's author. `mixed` is a hook summary, not a turn initiator.
+     */
+    initiator: ThreadTurnInitiator | "mixed";
+    /**
+     * The thread that sent every message in this dispatch: a thread id, null
+     * when none of them has a sender, or the literal `"mixed"` when the rows
+     * disagree. A thread-start names its requesting thread; a message a human
+     * typed and a core-driven retry have no sender. Null therefore still means
+     * "nobody sent this" rather than "bb could not tell", so a handler may key
+     * a human-versus-agent policy on it; `queuedMessages` names each row's own
+     * sender. Thread ids are prefixed, so no id collides with `"mixed"`.
+     */
+    senderThreadId: string | "mixed" | null;
+    /**
+     * All queued rows this attempt is re-trying, in dispatch order. Empty for
+     * an inline attempt. Each row retains its own content, author, and origin; `input`
+     * contains their combined input, and the hook decides for the whole group.
      *
      * This is how a hook tells a fresh send from a re-attempt of something it
      * already decided about — the replacement for the old
@@ -1025,7 +1050,7 @@ interface MessageDispatchHookContext {
      * should treat the two identically; a hook that logs should not
      * double-count.
      */
-    queuedMessage: ThreadQueuedMessage | null;
+    queuedMessages: ThreadQueuedMessage[];
     /**
      * Opaque JSON supplied by a plugin through the composer's
      * `experimental_submit`, paired with that plugin's id. Null for ordinary
@@ -1036,10 +1061,15 @@ interface MessageDispatchHookContext {
         pluginId: string;
         data: JsonValue;
     } | null;
-    /** How the dispatch was requested; null for internal/core-driven sends. */
-    origin: ThreadCreateOrigin | null;
-    originPluginId: string | null;
-    startedOnBehalfOf: StartedOnBehalfOf | null;
+    /**
+     * How the dispatch was requested; null for internal/core-driven sends, which
+     * includes every follow-up, steer and retry. Persisted with the queued row,
+     * so a drained re-attempt reads what its first attempt read. For a grouped
+     * dispatch, each field is its shared value or `"mixed"` when rows differ,
+     * including a value versus null. Each queued row exposes its own origin.
+     */
+    origin: ThreadCreateOrigin | "mixed" | null;
+    originPluginId: string | "mixed" | null;
     parentThreadId: string | null;
 }
 /**
@@ -1549,6 +1579,12 @@ interface PluginMentionItem {
     id: string;
     title: string;
     subtitle?: string;
+    /**
+     * BB icon name: a built-in name, or a name the plugin's app bundle
+     * registered with `app.experimental_icons.register()`. The row prefers the
+     * plugin's own branding icon when it ships one; unknown names fall back to
+     * the generic plugin icon.
+     */
     icon?: string;
 }
 /** Agent-only image context resolved with a plugin mention. */

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

@@ -1402,7 +1402,7 @@ type PluginAgentConfigurationContextOverrides = {
     };
     origin?: Partial<PluginAgentConfigurationContext["origin"]>;
 };
-type MessageDispatchHookContextOverrides = Omit<Partial<MessageDispatchHookContext>, "environment" | "executionSources" | "host" | "input" | "project" | "queuedMessage" | "requestedExecution" | "thread"> & {
+type MessageDispatchHookContextOverrides = Omit<Partial<MessageDispatchHookContext>, "environment" | "executionSources" | "host" | "input" | "project" | "queuedMessages" | "requestedExecution" | "thread"> & {
     thread?: Partial<MessageDispatchHookContext["thread"]>;
     project?: Partial<MessageDispatchHookContext["project"]>;
     environment?: Partial<NonNullable<MessageDispatchHookContext["environment"]>> | null;
@@ -1410,7 +1410,7 @@ type MessageDispatchHookContextOverrides = Omit<Partial<MessageDispatchHookConte
     input?: Partial<MessageDispatchHookContext["input"]>;
     requestedExecution?: Partial<MessageDispatchHookContext["requestedExecution"]>;
     executionSources?: Partial<MessageDispatchHookContext["executionSources"]>;
-    queuedMessage?: Partial<NonNullable<MessageDispatchHookContext["queuedMessage"]>> | null;
+    queuedMessages?: Partial<MessageDispatchHookContext["queuedMessages"][number]>[];
 };
 /**
  * A complete, deterministic host response for faking `bb.sdk.hosts.list()`

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

@@ -98,7 +98,7 @@ declare const appSettingsUpdateSchema: z$1.ZodUnion<readonly [z$1.ZodObject<{
 }, z$1.core.$strict>]>;
 type AppSettingsUpdate = z$1.infer<typeof appSettingsUpdateSchema>;
 
-declare const UI_PREFERENCE_KEYS: readonly ["sidebar.organizationMode", "sidebar.chronologicalSort", "sidebar.sortDirection", "sidebar.sectionOrder", "sidebar.manualSectionOrder", "sidebar.machineSectionOrder", "sidebar.collapsedSections", "sidebar.collapsedProjects", "sidebar.collapsedThreads", "sidebar.collapsedEnvironments", "sidebar.collapsedThreadSections", "sidebar.collapsedMachines", "sidebar.footerOrder", "sidebar.hiddenFooterItems", "sidebar.pluginPanelOrder", "sidebar.visiblePluginPanels", "sidebar.navigationProvider", "sidebar.threadListProvider"];
+declare const UI_PREFERENCE_KEYS: readonly ["sidebar.organizationMode", "sidebar.threadGrouping.environment", "sidebar.chronologicalSort", "sidebar.sortDirection", "sidebar.sectionOrder", "sidebar.manualSectionOrder", "sidebar.machineSectionOrder", "sidebar.collapsedSections", "sidebar.collapsedProjects", "sidebar.collapsedThreads", "sidebar.collapsedEnvironments", "sidebar.collapsedThreadSections", "sidebar.collapsedMachines", "sidebar.footerOrder", "sidebar.hiddenFooterItems", "sidebar.pluginPanelOrder", "sidebar.visiblePluginPanels", "sidebar.navigationProvider", "sidebar.threadListProvider"];
 type UiPreferenceKey = (typeof UI_PREFERENCE_KEYS)[number];
 interface UiPreferenceDefinition<Schema extends z$1.ZodTypeAny = z$1.ZodTypeAny> {
     schema: Schema;
@@ -111,6 +111,7 @@ declare const uiPreferenceDefinitions: {
         machine: "machine";
         project: "project";
     }>>;
+    readonly "sidebar.threadGrouping.environment": UiPreferenceDefinition<z$1.ZodUnion<readonly [z$1.ZodLiteral<"auto">, z$1.ZodBoolean]>>;
     readonly "sidebar.chronologicalSort": UiPreferenceDefinition<z$1.ZodEnum<{
         alpha: "alpha";
         created: "created";
@@ -4084,6 +4085,21 @@ type ThreadEventRow = {
     [TType in ThreadEventType]: ThreadEventRowOfType<TType>;
 }[ThreadEventType];
 
+declare const threadTurnInitiatorSchema: z$1.ZodEnum<{
+    agent: "agent";
+    system: "system";
+    user: "user";
+}>;
+type ThreadTurnInitiator = z$1.infer<typeof threadTurnInitiatorSchema>;
+
+declare const threadCreateOriginSchema: z$1.ZodEnum<{
+    app: "app";
+    cli: "cli";
+    plugin: "plugin";
+    sdk: "sdk";
+}>;
+type ThreadCreateOrigin = z$1.infer<typeof threadCreateOriginSchema>;
+
 declare const threadStatusSchema: z$1.ZodEnum<{
     active: "active";
     error: "error";
@@ -4203,6 +4219,13 @@ declare const threadQueuedMessageSchema: z$1.ZodObject<{
         user: "user";
     }>;
     model: z$1.ZodString;
+    origin: z$1.ZodNullable<z$1.ZodEnum<{
+        app: "app";
+        cli: "cli";
+        plugin: "plugin";
+        sdk: "sdk";
+    }>>;
+    originPluginId: z$1.ZodNullable<z$1.ZodString>;
     payload: z$1.ZodDiscriminatedUnion<[z$1.ZodObject<{
         kind: z$1.ZodLiteral<"inline">;
     }, z$1.core.$strip>, z$1.ZodObject<{
@@ -11480,13 +11503,6 @@ interface TimelineTurnRow extends TimelineRowBase {
 type TimelineSourceRow = TimelineConversationRow | TimelineWorkRow | TimelineSystemRow;
 type TimelineRow = TimelineSourceRow | TimelineTurnRow;
 
-declare const threadCreateOriginSchema: z$1.ZodEnum<{
-    app: "app";
-    cli: "cli";
-    plugin: "plugin";
-    sdk: "sdk";
-}>;
-type ThreadCreateOrigin = z$1.infer<typeof threadCreateOriginSchema>;
 type ExecutionInputFieldSource = CallerExecutionInputSource;
 declare const createExecutionInputSourcesSchema: z$1.ZodObject<{
     model: z$1.ZodOptional<z$1.ZodEnum<{
@@ -11511,14 +11527,6 @@ declare const createExecutionInputSourcesSchema: z$1.ZodObject<{
     }>>;
 }, z$1.core.$strict>;
 type CreateExecutionInputSources = z$1.infer<typeof createExecutionInputSourcesSchema>;
-declare const startedOnBehalfOfSchema: z$1.ZodObject<{
-    initiator: z$1.ZodEnum<{
-        agent: "agent";
-        system: "system";
-    }>;
-    senderThreadId: z$1.ZodString;
-}, z$1.core.$strip>;
-type StartedOnBehalfOf = z$1.infer<typeof startedOnBehalfOfSchema>;
 declare const createThreadRequestSchema: z$1.ZodObject<{
     environment: z$1.ZodDiscriminatedUnion<[z$1.ZodObject<{
         environmentId: z$1.ZodString;
@@ -12196,6 +12204,13 @@ declare const sendMessageResponseSchema: z$1.ZodDiscriminatedUnion<[z$1.ZodObjec
             user: "user";
         }>;
         model: z$1.ZodString;
+        origin: z$1.ZodNullable<z$1.ZodEnum<{
+            app: "app";
+            cli: "cli";
+            plugin: "plugin";
+            sdk: "sdk";
+        }>>;
+        originPluginId: z$1.ZodNullable<z$1.ZodString>;
         payload: z$1.ZodDiscriminatedUnion<[z$1.ZodObject<{
             kind: z$1.ZodLiteral<"inline">;
         }, z$1.core.$strip>, z$1.ZodObject<{
@@ -12751,6 +12766,13 @@ declare const sendQueuedMessageResponseSchema: z$1.ZodDiscriminatedUnion<[z$1.Zo
             user: "user";
         }>;
         model: z$1.ZodString;
+        origin: z$1.ZodNullable<z$1.ZodEnum<{
+            app: "app";
+            cli: "cli";
+            plugin: "plugin";
+            sdk: "sdk";
+        }>>;
+        originPluginId: z$1.ZodNullable<z$1.ZodString>;
         payload: z$1.ZodDiscriminatedUnion<[z$1.ZodObject<{
             kind: z$1.ZodLiteral<"inline">;
         }, z$1.core.$strip>, z$1.ZodObject<{
@@ -13645,6 +13667,13 @@ declare const threadQueuedMessageListResponseSchema: z$1.ZodArray<z$1.ZodObject<
         user: "user";
     }>;
     model: z$1.ZodString;
+    origin: z$1.ZodNullable<z$1.ZodEnum<{
+        app: "app";
+        cli: "cli";
+        plugin: "plugin";
+        sdk: "sdk";
+    }>>;
+    originPluginId: z$1.ZodNullable<z$1.ZodString>;
     payload: z$1.ZodDiscriminatedUnion<[z$1.ZodObject<{
         kind: z$1.ZodLiteral<"inline">;
     }, z$1.core.$strip>, z$1.ZodObject<{
@@ -15386,6 +15415,23 @@ interface ExperimentalAppOverlayRegistration {
     id: string;
     component: ComponentType<ExperimentalAppOverlayProps>;
 }
+/**
+ * A name the host resolves to a glyph, in this order: a name any plugin
+ * registered with `app.experimental_icons.register()`, then a built-in BB icon
+ * name (`"Zap"`), then a namespaced `"<pluginId>/<name>"` glyph naming an
+ * entry of that plugin's manifest `bb.branding.experimental_icons` map. A
+ * registration therefore shadows a built-in, and either shadows a declared
+ * icon of the same name. Names that resolve to none of the three fall back to
+ * the surface's generic icon.
+ *
+ * Declared icons and registrations are one vocabulary here: the same name
+ * works in `experimental_Icon`, in every field below, and — for a declared
+ * icon — in the tool, provider and bridge-row declarations that accept one.
+ * Declared icons need no frontend bundle and survive the plugin being stopped;
+ * registrations can be any React component but live only while the plugin's
+ * app bundle is loaded.
+ */
+type BbIconName = string;
 /**
  * Owner-defined validator for a fixed tab's transient target. The host first
  * verifies that the value is JSON-safe, then calls this validator before
@@ -15410,8 +15456,7 @@ type ExperimentalPluginFixedTabReference<Target extends JsonValue = never> = {
 /** A fixed tab declared by a plugin nav panel. */
 type PluginFixedTabRegistration<Target extends JsonValue = never> = ExperimentalPluginFixedTabReference<Target> & {
     title: string;
-    /** Icon hint (BB icon name); unknown names fall back to a generic icon. */
-    icon: string;
+    icon: BbIconName;
     component: ComponentType<PluginNavPanelProps>;
     /** `flush` lets the component own padding and scrolling. */
     layout?: "flush" | "padded";
@@ -15422,8 +15467,7 @@ interface PluginNavPanelRegistration {
     /** Unique within the plugin; letters, digits, `-`, `_`. */
     id: string;
     title: string;
-    /** Icon hint (BB icon name); unknown names fall back to a generic icon. */
-    icon: string;
+    icon: BbIconName;
     /** URL segment under `/plugins/<pluginId>/`; letters, digits, `-`, `_`. */
     path: string;
     component: ComponentType<PluginNavPanelProps>;
@@ -15506,10 +15550,10 @@ interface PluginThreadPanelActionRegistration {
     /** Label of the action row in the panel's new-tab launcher. */
     title: string;
     /**
-     * Icon hint (BB icon name) used when the plugin ships no logo; the
-     * launcher row and opened tabs prefer the plugin's logo.
+     * Drawn only when the manifest declares no `bb.branding.icon`; the launcher
+     * row and opened tabs prefer that over this hint.
      */
-    icon?: string;
+    icon?: BbIconName;
     /** Rendered inside every panel tab this action opens. */
     component: ComponentType<PluginThreadPanelProps>;
     /**
@@ -15546,8 +15590,8 @@ interface PluginNewThreadPanelActionRegistration {
     id: string;
     /** Label of the action row in the panel's new-tab launcher. */
     title: string;
-    /** Icon hint (BB icon name) used when the plugin ships no logo. */
-    icon?: string;
+    /** Drawn only when the manifest declares no `bb.branding.icon`. */
+    icon?: BbIconName;
     /** Rendered inside every panel tab this action opens. */
     component: ComponentType<PluginNewThreadPanelProps>;
     /** Host framing; matches `threadPanelAction`. */
@@ -15591,8 +15635,8 @@ interface PluginSidebarFooterActionRegistration {
     id: string;
     /** Tooltip and accessible label for the icon button. */
     title: string;
-    /** Icon hint (BB icon name); unknown names fall back to a generic icon. */
-    icon: string;
+    /** Drawn only when the manifest declares no `bb.branding.icon`. */
+    icon: BbIconName;
     /**
      * Runs when the user activates the action (e.g. call `openSettings()`,
      * open a panel via other surfaces, toast). Errors (sync or async) are
@@ -15611,8 +15655,7 @@ interface ExperimentalSidebarFooterItemBase {
     id: string;
     /** Tooltip and accessible label for the host-rendered icon button. */
     label: string;
-    /** BB icon-name hint; unknown names fall back to a generic icon. */
-    icon: string;
+    icon: BbIconName;
 }
 /** A sidebar-footer item that runs a callback when activated. */
 interface ExperimentalSidebarFooterActionRegistration extends ExperimentalSidebarFooterItemBase {
@@ -16089,8 +16132,7 @@ interface PluginMessageActionRegistration {
     id: string;
     /** Tooltip / menu label for the action. */
     title: string;
-    /** Icon hint (BB icon name); unknown names fall back to a generic icon. */
-    icon?: string;
+    icon?: BbIconName;
     /**
      * Runs when the user activates the action. Errors (sync or async) are
      * contained and logged; they never break the timeline.
@@ -16521,6 +16563,11 @@ interface ExperimentalProviderIconProps {
     "aria-hidden"?: boolean | "false" | "true";
     "aria-label"?: string;
 }
+/**
+ * An app icon registered by a plugin. The registry is app-wide: a registered
+ * name is usable wherever a `BbIconName` is — `experimental_Icon`, and every
+ * host-rendered surface that takes one — by this plugin or any other.
+ */
 interface ExperimentalIconRegistration {
     /** Shared app name. Namespacing is recommended, but not required. */
     name: string;
@@ -16531,10 +16578,11 @@ interface ExperimentalIconRegistration {
 }
 interface ExperimentalAppIcons {
     /**
-     * Add or override an app icon during setup. Returns nothing; the host
-     * replaces registrations on reload and removes them on unload. Duplicate
-     * names within a plugin reject setup. Between plugins, the first plugin id
-     * in lexical order wins, independent of bundle load order.
+     * Add or override an app icon during setup. A registered name shadows a
+     * built-in of the same name. Returns nothing; the host replaces
+     * registrations on reload and removes them on unload. Duplicate names within
+     * a plugin reject setup. Between plugins, the first plugin id in lexical
+     * order wins, independent of bundle load order.
      */
     register(registration: ExperimentalIconRegistration): void;
 }
@@ -16619,8 +16667,8 @@ interface ComposerCustomization {
 interface ComposerPlusMenuItem {
     id: string;
     label: string;
-    /** BB icon name; unknown names fall back to the generic plugin icon. */
-    icon?: string;
+    /** Drawn only when the manifest declares no `bb.branding.icon`. */
+    icon?: BbIconName;
     /** Accessible description for the host-rendered row. */
     description?: string;
     disabled?: boolean | ((view: ComposerView) => boolean);
@@ -16673,8 +16721,11 @@ interface PluginComposerTextEffect {
 }
 /** Host-rendered status that temporarily replaces a thread's draft glyph. */
 interface PluginComposerThreadRowStatus {
-    /** BB icon-name hint; unknown names fall back to the generic plugin icon. */
-    icon: string;
+    /**
+     * Always drawn as given: unlike the plugin-badged surfaces, this one has no
+     * preference for the plugin's own `bb.branding.icon`.
+     */
+    icon: BbIconName;
     /** Accessible label for the status glyph. */
     label: string;
     /**
@@ -16807,8 +16858,7 @@ interface ThreadChatMessageAction {
     id: string;
     /** Tooltip / menu label for the action. */
     title: string;
-    /** Icon hint (BB icon name); unknown names fall back to a generic icon. */
-    icon?: string;
+    icon?: BbIconName;
     /**
      * Message roles the action applies to. Omitted = both user and assistant
      * messages.
@@ -19751,8 +19801,26 @@ interface MessageDispatchHookContext {
     /** Whether this attempt starts a turn or joins a running one. */
     attempt: PluginDispatchAttemptKind;
     /**
-     * The queued row this attempt is re-trying, or null when the attempt is
-     * inline and no row has ever existed for it.
+     * The author category shared by this dispatch's messages: `user`, `agent`,
+     * or `system`. `mixed` means the queued messages have different categories.
+     * Different agents still share the `agent` category; read `queuedMessages`
+     * for each message's author. `mixed` is a hook summary, not a turn initiator.
+     */
+    initiator: ThreadTurnInitiator | "mixed";
+    /**
+     * The thread that sent every message in this dispatch: a thread id, null
+     * when none of them has a sender, or the literal `"mixed"` when the rows
+     * disagree. A thread-start names its requesting thread; a message a human
+     * typed and a core-driven retry have no sender. Null therefore still means
+     * "nobody sent this" rather than "bb could not tell", so a handler may key
+     * a human-versus-agent policy on it; `queuedMessages` names each row's own
+     * sender. Thread ids are prefixed, so no id collides with `"mixed"`.
+     */
+    senderThreadId: string | "mixed" | null;
+    /**
+     * All queued rows this attempt is re-trying, in dispatch order. Empty for
+     * an inline attempt. Each row retains its own content, author, and origin; `input`
+     * contains their combined input, and the hook decides for the whole group.
      *
      * This is how a hook tells a fresh send from a re-attempt of something it
      * already decided about — the replacement for the old
@@ -19760,7 +19828,7 @@ interface MessageDispatchHookContext {
      * should treat the two identically; a hook that logs should not
      * double-count.
      */
-    queuedMessage: ThreadQueuedMessage | null;
+    queuedMessages: ThreadQueuedMessage[];
     /**
      * Opaque JSON supplied by a plugin through the composer's
      * `experimental_submit`, paired with that plugin's id. Null for ordinary
@@ -19771,10 +19839,15 @@ interface MessageDispatchHookContext {
         pluginId: string;
         data: JsonValue;
     } | null;
-    /** How the dispatch was requested; null for internal/core-driven sends. */
-    origin: ThreadCreateOrigin | null;
-    originPluginId: string | null;
-    startedOnBehalfOf: StartedOnBehalfOf | null;
+    /**
+     * How the dispatch was requested; null for internal/core-driven sends, which
+     * includes every follow-up, steer and retry. Persisted with the queued row,
+     * so a drained re-attempt reads what its first attempt read. For a grouped
+     * dispatch, each field is its shared value or `"mixed"` when rows differ,
+     * including a value versus null. Each queued row exposes its own origin.
+     */
+    origin: ThreadCreateOrigin | "mixed" | null;
+    originPluginId: string | "mixed" | null;
     parentThreadId: string | null;
 }
 /**
@@ -20661,6 +20734,12 @@ interface PluginMentionItem {
     id: string;
     title: string;
     subtitle?: string;
+    /**
+     * BB icon name: a built-in name, or a name the plugin's app bundle
+     * registered with `app.experimental_icons.register()`. The row prefers the
+     * plugin's own branding icon when it ships one; unknown names fall back to
+     * the generic plugin icon.
+     */
     icon?: string;
 }
 /** Agent-only image context resolved with a plugin mention. */

package/dist/testing/index.js

@@ -4340,11 +4340,12 @@ function makeMessageDispatchHookContext(overrides = {}) {
       permissionMode: null
     },
     attempt: "start-turn",
-    queuedMessage: null,
+    initiator: "user",
+    senderThreadId: null,
+    queuedMessages: [],
     experimental_submission: null,
     origin: null,
     originPluginId: null,
-    startedOnBehalfOf: null,
     parentThreadId: null,
     environmentIntent: null
   };
@@ -4401,15 +4402,16 @@ function makeMessageDispatchHookContext(overrides = {}) {
       ...context.executionSources,
       ...overrides.executionSources
     },
-    queuedMessage: overrides.queuedMessage === void 0 ? context.queuedMessage : overrides.queuedMessage === null ? null : makeQueueEntry({
-      threadId: thread.id,
-      ...overrides.queuedMessage
-    })
+    queuedMessages: (overrides.queuedMessages ?? context.queuedMessages).map(
+      (message) => makeQueueEntry({ threadId: thread.id, ...message })
+    )
   };
 }
 function makeQueueEntry(overrides = {}) {
   return {
     id: "queued_1",
+    origin: null,
+    originPluginId: null,
     initiator: "user",
     senderThreadId: null,
     threadId: "thread-1",

package/package.json

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