@get-bb/plugin-sdk 0.4.97 → 0.4.101

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

@@ -192,6 +192,7 @@ declare const promptInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             }>;
             trigger: z.ZodEnum<{
                 "/": "/";
+                $: "$";
             }>;
         }, z.core.$strip>, z.ZodObject<{
             icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -258,6 +259,7 @@ declare const providerInfoSchema: z.ZodObject<{
         kind: z.ZodLiteral<"skills">;
         trigger: z.ZodEnum<{
             "/": "/";
+            $: "$";
         }>;
     }, z.core.$strip>, z.ZodObject<{
         command: z.ZodObject<{
@@ -265,6 +267,7 @@ declare const providerInfoSchema: z.ZodObject<{
             trailingText: z.ZodString;
             trigger: z.ZodEnum<{
                 "/": "/";
+                $: "$";
             }>;
         }, z.core.$strip>;
         kind: z.ZodLiteral<"plan">;
@@ -274,6 +277,7 @@ declare const providerInfoSchema: z.ZodObject<{
             trailingText: z.ZodString;
             trigger: z.ZodEnum<{
                 "/": "/";
+                $: "$";
             }>;
         }, z.core.$strip>;
         kind: z.ZodLiteral<"goal">;
@@ -579,6 +583,34 @@ interface PluginThreadHeaderActionProps {
      */
     isCompactViewport: boolean;
 }
+/** JavaScript world a Browser page expression runs in. */
+type ExperimentalPluginBrowserPageWorld = "isolated" | "main";
+interface ExperimentalPluginBrowserPageEvaluateOptions {
+    /**
+     * `isolated` (default) runs in a BB-owned world that shares the page DOM but
+     * not page globals, and binds `bb.postMessage(data)`. `main` runs beside the
+     * page's own scripts, where `bb` is `null`.
+     */
+    world?: ExperimentalPluginBrowserPageWorld;
+}
+/**
+ * Script access to the top-level document of one Browser tab. Independent of
+ * CDP control leases: it never attaches a debugger or shows a control banner.
+ */
+interface ExperimentalPluginBrowserPage {
+    /**
+     * Evaluate a JavaScript expression and resolve its JSON-serialized value.
+     * Promises are awaited and `undefined` resolves to `null`. The expression
+     * can reference `bb`. Rejects when the tab is gone or the expression throws.
+     * Anything the expression installs is lost when the document navigates.
+     */
+    evaluate(expression: string, options?: ExperimentalPluginBrowserPageEvaluateOptions): Promise<JsonValue$1>;
+    /**
+     * Subscribe to values this plugin's isolated-world scripts in this tab send
+     * with `bb.postMessage(data)`. Returns the unsubscribe function.
+     */
+    onMessage(listener: (data: JsonValue$1) => void): () => void;
+}
 interface ExperimentalPluginBrowserToolbarActionProps {
     /** Thread that owns the Browser tab. */
     threadId: string;
@@ -588,6 +620,8 @@ interface ExperimentalPluginBrowserToolbarActionProps {
     url: string;
     /** True when the Browser chrome needs compact controls. */
     isCompactViewport: boolean;
+    /** Script access to this tab's page; `null` outside the desktop app. */
+    experimental_page: ExperimentalPluginBrowserPage | null;
 }
 /**
  * Where a file being opened by a `fileOpener` lives. `path` semantics follow
@@ -821,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
@@ -845,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";
@@ -857,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>;
@@ -941,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>;
     /**
@@ -981,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`. */
@@ -1026,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
@@ -1046,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 {
@@ -1524,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.
@@ -1956,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;
@@ -1966,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;
 }
@@ -2054,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);
@@ -2108,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;
     /**
@@ -2178,6 +2234,13 @@ interface PluginComposerApi {
      * content should be fetched fresh when the message is sent.
      */
     insertMention(mention: PluginComposerMention): void;
+    /** Remove this plugin's matching mention pills and their text from the current draft. */
+    experimental_removeMention(mention: {
+        provider: string;
+        id: string;
+    }): void;
+    /** Subscribe to successful local submissions in this composer scope, including accepted queued messages. Failed sends and draft clearing do not notify. Dispose on unmount. */
+    experimental_onSubmitted(listener: () => void): () => void;
     /** Focus the composer caret at the end of the draft. */
     focus(): void;
     /**
@@ -2235,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.
@@ -2890,4 +2952,4 @@ declare const experimental_useProviders: () => PluginProvidersState;
 declare const experimental_useCodeTheme: () => PluginCodeThemeState;
 
 export { Markdown, ThreadChat, UrlLink, definePluginApp, experimental_BranchPicker, experimental_Diff, experimental_FileLink, experimental_Icon, experimental_NewThreadComposer, experimental_PermissionModePicker, experimental_ProviderIcon, experimental_ProviderModelPicker, experimental_SourceCode, experimental_useAppPanel, experimental_useBranches, experimental_useCheckoutState, experimental_useCodeTheme, experimental_useFixedTabTarget, experimental_useProviders, experimental_useSidebarThreadActions, experimental_useSidebarThreadPullRequest, experimental_useSidebarThreadSplit, experimental_useSidebarThreads, useBbContext, useBbNavigate, useComposer, useComposerView, useRealtime, useRealtimeConnectionState, useRpc, useSettings };
-export type { BbContext, BbNavigate, BranchPickerProps, BranchesState, CheckoutState, CodeOverflowMode, ComposerCustomization, ComposerPlusMenuItem, ComposerRichTextSpec, ComposerStructuredDraft, ComposerView, DiffProps, DiffViewMode, ExperimentalAppIcons, ExperimentalAppOverlayProps, ExperimentalAppOverlayRegistration, ExperimentalAppPanel, ExperimentalAppPanelSurface, ExperimentalComposerSubmitOptions, ExperimentalDiffFileContent, ExperimentalDiffFullFileContents, ExperimentalFileLinkProps, ExperimentalFileLocation, ExperimentalFileOpenOptions, ExperimentalFixedTabTargetContract, ExperimentalFixedTabTargetState, ExperimentalIconProps, ExperimentalIconRegistration, ExperimentalLiveFileTarget, ExperimentalOpenFixedTabOptions, ExperimentalPermissionModePickerProps, ExperimentalPluginBrowserToolbarActionProps, ExperimentalPluginBrowserToolbarActionRegistration, ExperimentalPluginFixedTabReference, ExperimentalProviderIconProps, ExperimentalProviderModelPickerProps, ExperimentalProviderModelPickerRouting, ExperimentalProviderModelPickerValue, ExperimentalSidebarFooter, ExperimentalSidebarFooterActionContext, ExperimentalSidebarFooterActionRegistration, ExperimentalSidebarFooterDisclosureController, ExperimentalSidebarFooterDisclosureProps, ExperimentalSidebarFooterDisclosureRegistration, ExperimentalSidebarFooterItemBase, ExperimentalSidebarFooterItemRegistration, ExperimentalSidebarNavigationAction, ExperimentalSidebarNavigationActivationOptions, ExperimentalSidebarNavigationIcon, ExperimentalSidebarNavigationItem, ExperimentalSidebarNavigationProps, ExperimentalSidebarNavigationRegistration, ExperimentalSidebarNavigationShortcut, JsonValue$1 as JsonValue, MarkdownProps, NewThreadComposerProps, NewThreadRequest, PluginAppBuilder, PluginAppCommands, PluginAppComposer, PluginAppContentScripts, PluginAppDefinition, PluginAppSetup, PluginAppSlots, PluginCodeThemeData, PluginCodeThemeState, PluginCodeThemeTokenRule, PluginCommandContext, PluginCommandPaletteActionContext, PluginCommandPaletteActionRegistration, PluginCommandRegistration, PluginCommandShortcut, PluginComposerApi, PluginComposerMention, PluginComposerScope, PluginComposerTextEffect, PluginComposerThreadRowStatus, PluginContentScriptContext, PluginContentScriptDisposer, PluginContentScriptRegistration, PluginDiffRendererProps, PluginDiffRendererRegistration, PluginEnvironmentProviderInputsChange, PluginEnvironmentProviderInputsProps, PluginEnvironmentProviderInputsRegistration, PluginFileOpenerProps, PluginFileOpenerRegistration, PluginFileOpenerSource, PluginFixedTabDeclaration, PluginFixedTabRegistration, PluginHomepageSectionProps, PluginHomepageSectionRegistration, PluginMachineProviderInputsChange, PluginMachineProviderInputsProps, PluginMachineProviderInputsRegistration, PluginMessageActionContext, PluginMessageActionRegistration, PluginMessageDirectiveMessage, PluginMessageDirectiveOpenWorkspaceFile, PluginMessageDirectiveProps, PluginMessageDirectiveRegistration, PluginNavPanelProps, PluginNavPanelRegistration, PluginNewThreadPanelActionContext, PluginNewThreadPanelActionRegistration, PluginNewThreadPanelProps, PluginPanelActionOpenOptions, PluginPendingInteractionProps, PluginPendingInteractionRegistration, PluginPendingInteractionView, PluginProviderIconRegistration, PluginProvidersState, PluginRealtimeConnectionState, PluginRpcCallArgs, PluginRpcClient, PluginRpcContract, PluginRpcError, PluginRpcErrorCode, PluginRpcHandlers, PluginRpcIssuePathSegment, PluginRpcMethodContract, PluginRpcResult, PluginRpcValidationIssue, PluginSdkApp, PluginSettingsSectionProps, PluginSettingsSectionRegistration, PluginSettingsState, PluginSidebarFooterActionContext, PluginSidebarFooterActionProps, PluginSidebarFooterActionRegistration, PluginSidebarProject, PluginSidebarPullRequest, PluginSidebarSplitPane, PluginSidebarThread, PluginSidebarThreadActions, PluginSidebarThreadActivity, PluginSidebarThreadIndicator, PluginSidebarThreadPullRequestState, PluginSidebarThreadSplit, PluginSidebarThreadsState, PluginSourceCodeRendererProps, PluginSourceCodeRendererRegistration, PluginTargetedPanelActionOpenOptions, PluginThreadHeaderActionProps, PluginThreadHeaderActionRegistration, PluginThreadListProps, PluginThreadListRegistration, PluginThreadPanelActionContext, PluginThreadPanelActionRegistration, PluginThreadPanelProps, PluginTimelineRendererProps, PluginTimelineRendererRegistration, PluginTimelineRendererRow, PluginTimelineRowPresentation, PluginTimelineRowStatus, ReadonlyJsonValue, SourceCodeLineRange, SourceCodeProps, StandardSchemaV1, StandardSchemaV1InferInput, StandardSchemaV1InferOutput, StandardSchemaV1Issue, StandardSchemaV1Result, ThreadChatMessageAction, ThreadChatMessageReference, ThreadChatProps, UrlLinkProps, UseBranchesArgs, UseCheckoutStateArgs };
+export type { BbContext, BbNavigate, BranchPickerProps, BranchesState, CheckoutState, CodeOverflowMode, ComposerCustomization, ComposerPlusMenuItem, ComposerRichTextSpec, ComposerStructuredDraft, ComposerView, DiffProps, DiffViewMode, ExperimentalAppIcons, ExperimentalAppOverlayProps, ExperimentalAppOverlayRegistration, ExperimentalAppPanel, ExperimentalAppPanelSurface, ExperimentalComposerSubmitOptions, ExperimentalDiffFileContent, ExperimentalDiffFullFileContents, ExperimentalFileLinkProps, ExperimentalFileLocation, ExperimentalFileOpenOptions, ExperimentalFixedTabTargetContract, ExperimentalFixedTabTargetState, ExperimentalIconProps, ExperimentalIconRegistration, ExperimentalLiveFileTarget, ExperimentalOpenFixedTabOptions, ExperimentalPermissionModePickerProps, ExperimentalPluginBrowserPage, ExperimentalPluginBrowserPageEvaluateOptions, ExperimentalPluginBrowserPageWorld, ExperimentalPluginBrowserToolbarActionProps, ExperimentalPluginBrowserToolbarActionRegistration, ExperimentalPluginFixedTabReference, ExperimentalProviderIconProps, ExperimentalProviderModelPickerProps, ExperimentalProviderModelPickerRouting, ExperimentalProviderModelPickerValue, ExperimentalSidebarFooter, ExperimentalSidebarFooterActionContext, ExperimentalSidebarFooterActionRegistration, ExperimentalSidebarFooterDisclosureController, ExperimentalSidebarFooterDisclosureProps, ExperimentalSidebarFooterDisclosureRegistration, ExperimentalSidebarFooterItemBase, ExperimentalSidebarFooterItemRegistration, ExperimentalSidebarNavigationAction, ExperimentalSidebarNavigationActivationOptions, ExperimentalSidebarNavigationIcon, ExperimentalSidebarNavigationItem, ExperimentalSidebarNavigationProps, ExperimentalSidebarNavigationRegistration, ExperimentalSidebarNavigationShortcut, JsonValue$1 as JsonValue, MarkdownProps, NewThreadComposerProps, NewThreadRequest, PluginAppBuilder, PluginAppCommands, PluginAppComposer, PluginAppContentScripts, PluginAppDefinition, PluginAppSetup, PluginAppSlots, PluginCodeThemeData, PluginCodeThemeState, PluginCodeThemeTokenRule, PluginCommandContext, PluginCommandPaletteActionContext, PluginCommandPaletteActionRegistration, PluginCommandRegistration, PluginCommandShortcut, PluginComposerApi, PluginComposerMention, PluginComposerScope, PluginComposerTextEffect, PluginComposerThreadRowStatus, PluginContentScriptContext, PluginContentScriptDisposer, PluginContentScriptRegistration, PluginDiffRendererProps, PluginDiffRendererRegistration, PluginEnvironmentProviderInputsChange, PluginEnvironmentProviderInputsProps, PluginEnvironmentProviderInputsRegistration, PluginFileOpenerProps, PluginFileOpenerRegistration, PluginFileOpenerSource, PluginFixedTabDeclaration, PluginFixedTabRegistration, PluginHomepageSectionProps, PluginHomepageSectionRegistration, PluginMachineProviderInputsChange, PluginMachineProviderInputsProps, PluginMachineProviderInputsRegistration, PluginMessageActionContext, PluginMessageActionRegistration, PluginMessageDirectiveMessage, PluginMessageDirectiveOpenWorkspaceFile, PluginMessageDirectiveProps, PluginMessageDirectiveRegistration, PluginNavPanelProps, PluginNavPanelRegistration, PluginNewThreadPanelActionContext, PluginNewThreadPanelActionRegistration, PluginNewThreadPanelProps, PluginPanelActionOpenOptions, PluginPendingInteractionProps, PluginPendingInteractionRegistration, PluginPendingInteractionView, PluginProviderIconRegistration, PluginProvidersState, PluginRealtimeConnectionState, PluginRpcCallArgs, PluginRpcClient, PluginRpcContract, PluginRpcError, PluginRpcErrorCode, PluginRpcHandlers, PluginRpcIssuePathSegment, PluginRpcMethodContract, PluginRpcResult, PluginRpcValidationIssue, PluginSdkApp, PluginSettingsSectionProps, PluginSettingsSectionRegistration, PluginSettingsState, PluginSidebarFooterActionContext, PluginSidebarFooterActionProps, PluginSidebarFooterActionRegistration, PluginSidebarProject, PluginSidebarPullRequest, PluginSidebarSplitPane, PluginSidebarThread, PluginSidebarThreadActions, PluginSidebarThreadActivity, PluginSidebarThreadIndicator, PluginSidebarThreadPullRequestState, PluginSidebarThreadSplit, PluginSidebarThreadsState, PluginSourceCodeRendererProps, PluginSourceCodeRendererRegistration, PluginTargetedPanelActionOpenOptions, PluginThreadHeaderActionProps, PluginThreadHeaderActionRegistration, PluginThreadListProps, PluginThreadListRegistration, PluginThreadPanelActionContext, PluginThreadPanelActionRegistration, PluginThreadPanelProps, PluginTimelineRendererProps, PluginTimelineRendererRegistration, PluginTimelineRendererRow, PluginTimelineRowPresentation, PluginTimelineRowStatus, ReadonlyJsonValue, SourceCodeLineRange, SourceCodeProps, StandardSchemaV1, StandardSchemaV1InferInput, StandardSchemaV1InferOutput, StandardSchemaV1Issue, StandardSchemaV1Result, ThreadChatMessageAction, ThreadChatMessageReference, ThreadChatProps, UrlLinkProps, UseBranchesArgs, UseCheckoutStateArgs };

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

@@ -143,6 +143,7 @@ declare const threadResponseSchema: z.ZodObject<{
     id: z.ZodString;
     lastReadAt: z.ZodNullable<z.ZodNumber>;
     latestAttentionAt: z.ZodNumber;
+    lifecycleOwnerThreadId: z.ZodNullable<z.ZodString>;
     originKind: z.ZodNullable<z.ZodEnum<{
         fork: "fork";
     }>>;

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

@@ -252,6 +252,7 @@ declare const promptInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             }>;
             trigger: z.ZodEnum<{
                 "/": "/";
+                $: "$";
             }>;
         }, z.core.$strip>, z.ZodObject<{
             icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -299,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<{
@@ -344,6 +360,7 @@ declare const threadQueuedMessageSchema: z.ZodObject<{
                 }>;
                 trigger: z.ZodEnum<{
                     "/": "/";
+                    $: "$";
                 }>;
             }, z.core.$strip>, z.ZodObject<{
                 icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -392,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<{
@@ -446,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>;
@@ -472,6 +481,7 @@ declare const threadResponseSchema: z.ZodObject<{
     id: z.ZodString;
     lastReadAt: z.ZodNullable<z.ZodNumber>;
     latestAttentionAt: z.ZodNumber;
+    lifecycleOwnerThreadId: z.ZodNullable<z.ZodString>;
     originKind: z.ZodNullable<z.ZodEnum<{
         fork: "fork";
     }>>;
@@ -1013,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
@@ -1022,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
@@ -1033,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;
 }
 /**
@@ -1546,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-provider-bridge-testing.d.ts

@@ -3286,6 +3286,7 @@ declare const threadEventSchema: z.ZodPipe<z.ZodUnknown, z.ZodUnion<readonly [z.
             core: z.ZodEnum<{
                 "machine-environment": "machine-environment";
                 "machine-git": "machine-git";
+                "project-environment": "project-environment";
             }>;
         }, z.core.$strict>]>;
         value: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
@@ -3445,6 +3446,7 @@ declare const threadEventSchema: z.ZodPipe<z.ZodUnknown, z.ZodUnion<readonly [z.
                 }>;
                 trigger: z.ZodEnum<{
                     "/": "/";
+                    $: "$";
                 }>;
             }, z.core.$strip>, z.ZodObject<{
                 icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -3526,6 +3528,7 @@ declare const threadEventSchema: z.ZodPipe<z.ZodUnknown, z.ZodUnion<readonly [z.
                 }>;
                 trigger: z.ZodEnum<{
                     "/": "/";
+                    $: "$";
                 }>;
             }, z.core.$strip>, z.ZodObject<{
                 icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -4065,6 +4068,7 @@ declare const promptInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             }>;
             trigger: z.ZodEnum<{
                 "/": "/";
+                $: "$";
             }>;
         }, z.core.$strip>, z.ZodObject<{
             icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;

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

@@ -1375,6 +1375,7 @@ declare const permissionEscalationSchema: z.ZodEnum<{
 type PermissionEscalation = z.infer<typeof permissionEscalationSchema>;
 declare const promptMentionCommandTriggerSchema: z.ZodEnum<{
     "/": "/";
+    $: "$";
 }>;
 type PromptMentionCommandTrigger = z.infer<typeof promptMentionCommandTriggerSchema>;
 declare const promptInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -1421,6 +1422,7 @@ declare const promptInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             }>;
             trigger: z.ZodEnum<{
                 "/": "/";
+                $: "$";
             }>;
         }, z.core.$strip>, z.ZodObject<{
             icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -4538,6 +4540,7 @@ declare const threadStartParamsSchema: z.ZodObject<{
                 }>;
                 trigger: z.ZodEnum<{
                     "/": "/";
+                    $: "$";
                 }>;
             }, z.core.$strip>, z.ZodObject<{
                 icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -4864,6 +4867,7 @@ declare const turnStartParamsSchema: z.ZodObject<{
                 }>;
                 trigger: z.ZodEnum<{
                     "/": "/";
+                    $: "$";
                 }>;
             }, z.core.$strip>, z.ZodObject<{
                 icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -4993,6 +4997,7 @@ declare const turnSteerParamsSchema: z.ZodObject<{
                 }>;
                 trigger: z.ZodEnum<{
                     "/": "/";
+                    $: "$";
                 }>;
             }, z.core.$strip>, z.ZodObject<{
                 icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;

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

@@ -274,6 +274,7 @@ declare const threadResponseSchema: z.ZodObject<{
     id: z.ZodString;
     lastReadAt: z.ZodNullable<z.ZodNumber>;
     latestAttentionAt: z.ZodNumber;
+    lifecycleOwnerThreadId: z.ZodNullable<z.ZodString>;
     originKind: z.ZodNullable<z.ZodEnum<{
         fork: "fork";
     }>>;
@@ -1401,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;
@@ -1409,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()`