@get-bb/plugin-sdk 0.4.99 → 0.4.104

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.
@@ -1618,10 +1631,6 @@ interface PluginCommandRegistration {
      */
     run(context: PluginCommandContext): void | Promise<void>;
 }
-/** @deprecated Use PluginCommandContext. */
-type PluginCommandPaletteActionContext = PluginCommandContext;
-/** @deprecated Use PluginCommandRegistration. */
-type PluginCommandPaletteActionRegistration = PluginCommandRegistration;
 /** Registers commands for bb's command palette. */
 interface PluginAppCommands {
     /** Register a command. IDs are unique within this plugin, including legacy slot registrations. */
@@ -1990,6 +1999,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 +2014,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 +2103,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 +2157,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;
     /**
@@ -2250,6 +2268,82 @@ interface PluginComposerApi {
      * Experimental: see docs/api_to_audit.md.
      */
     experimental_submit(options: ExperimentalComposerSubmitOptions): Promise<void>;
+    /**
+     * Set this composer's pickers as if each value had been picked by hand.
+     *
+     * Every field is optional. An omitted field is left alone. A field this
+     * composer has no picker for is ignored rather than rejected: a thread
+     * composer has no project or environment; a provider without service tiers
+     * has no tier; a fork draft locks its project, provider and environment.
+     * Values travel through the same paths the pickers use, so in the
+     * new-thread composer they become the remembered defaults for the next
+     * thread and are reported as the user's explicit choices, and in a thread
+     * composer a provider change starts the same handoff the picker starts:
+     * the handoff block is prepended to the draft and the next send creates a
+     * new thread. A same-provider model change in a thread does not start a
+     * handoff, exactly like the picker.
+     *
+     * In the new-thread composer the project is switched first and awaited
+     * (attachments are copied to the new project), then the environment and
+     * machine are applied to the new project, then provider, model, reasoning
+     * level, service tier and permission mode. A provider change reloads the
+     * model catalog before the model and reasoning level are applied to it.
+     * Because the project switch remounts plugin surfaces, the returned
+     * promise is owned by the composer and still resolves after the calling
+     * component has unmounted.
+     *
+     * Resolves with the composer's own selection once it has settled: the
+     * applied values have committed and the model catalog for the selected
+     * provider and machine has finished loading, so model, reasoning level and
+     * permission mode have reconciled against it. The catalog wait is bounded;
+     * if it has not finished after 15 seconds the promise resolves with the
+     * selection as it stands. The result carries only the fields this composer
+     * has, so a missing key means "no such picker here" and a value that
+     * differs from the one passed was reconciled (a reasoning level the model
+     * does not support, a permission mode above the machine's ceiling, a model
+     * the provider does not list). A provider the composer does not list is
+     * ignored together with the model and reasoning level meant for it, so the
+     * stored provider preference never names something the picker could not
+     * have chosen. `environment` is absent while the composer
+     * has no submittable environment; `providerId` and `model` are absent
+     * while nothing is selected; `serviceTier` is present only when the
+     * selected provider has tiers and one is chosen.
+     *
+     * Rejects, with a message safe to show to the user, in a composer with no
+     * pickers at all (a queued-message editor, a side chat, a plugin surface
+     * mounted outside any composer), when the calling surface is no longer
+     * active, and when a value is not a known reasoning level, service tier or
+     * permission mode.
+     *
+     * Experimental: see docs/api_to_audit.md.
+     */
+    experimental_setSelection(selection: ExperimentalComposerSelection): Promise<ExperimentalComposerSelection>;
+}
+/**
+ * Picker values for `experimental_setSelection`, and the shape it resolves
+ * with. Field names match `NewThreadRequest` and the `default*` props of
+ * `experimental_NewThreadComposer`, so one routed decision can feed the
+ * composer, the embedded composer and `bb.sdk.threads.spawn` alike.
+ */
+interface ExperimentalComposerSelection {
+    /** New-thread composers only. BB's personal-project id means "Don't work in a project". */
+    projectId?: string;
+    /**
+     * New-thread composers only. `{ type: "project-default" }` and a `host`
+     * environment without a `hostId` seed nothing and are ignored. Provider
+     * `inputs` are not applied; the provider's own inputs control keeps its
+     * value, and the result reports what the composer would submit.
+     */
+    environment?: CreateThreadEnvironmentArgs;
+    /** A provider the composer does not list is ignored, and `model` and `reasoningLevel` with it. */
+    providerId?: string;
+    /** Applied only when the composer ends up on the requested provider (or none was requested). */
+    model?: string;
+    /** Applied only when the composer ends up on the requested provider (or none was requested). */
+    reasoningLevel?: ReasoningLevel;
+    /** Ignored by a provider with no service tiers. */
+    serviceTier?: ServiceTier;
+    permissionMode?: PermissionMode;
 }
 /**
  * What `experimental_submit` does differently from pressing Enter.
@@ -2276,8 +2370,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.
@@ -2931,4 +3024,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, 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 };
+export type { BbContext, BbNavigate, BranchPickerProps, BranchesState, CheckoutState, CodeOverflowMode, ComposerCustomization, ComposerPlusMenuItem, ComposerRichTextSpec, ComposerStructuredDraft, ComposerView, DiffProps, DiffViewMode, ExperimentalAppIcons, ExperimentalAppOverlayProps, ExperimentalAppOverlayRegistration, ExperimentalAppPanel, ExperimentalAppPanelSurface, ExperimentalComposerSelection, 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, 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-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;
 }
 /**
@@ -1077,6 +1107,23 @@ interface PluginCliContext {
     /** Aborted when the invoking CLI HTTP request disconnects. */
     signal?: AbortSignal;
 }
+/**
+ * What a submitted form leaves in the thread timeline, chosen by the plugin.
+ * bb never stores the form's payload or the submitted value; it stores only
+ * this description, so a plugin decides what the transcript keeps.
+ */
+interface PluginInteractionDescription {
+    /** Row title once submitted; defaults to the presentation's completed label. */
+    title?: string;
+    /** Short Markdown for the expanded row. */
+    detail?: string;
+    /**
+     * Persisted with the row and handed to this plugin's
+     * `experimental_timelineRenderer` registered for `"<pluginId>/<rendererId>"`.
+     * Omit anything the transcript must not keep.
+     */
+    payload?: JsonValue;
+}
 interface PluginInteractionRequest {
     threadId: string;
     rendererId: string;
@@ -1084,6 +1131,19 @@ interface PluginInteractionRequest {
     payload: JsonValue;
     /** Defaults to ten minutes; capped at one hour. */
     timeoutMs?: number;
+    /**
+     * How the form reads as a timeline row while it waits and once it settles,
+     * in the same shape as a native tool's presentation. bb fills what is left
+     * out: "Waiting for <title>" / "Submitted <title>" and the plugin's glyph.
+     */
+    presentation?: PluginRowPresentation;
+    /**
+     * Called once with the submitted value, before the waiting `requestInput`
+     * promise resolves; never for a cancellation, which bb titles itself. Its
+     * return is persisted on the row. A throw or a slow return leaves the row
+     * with its completed label and nothing more.
+     */
+    describeSubmission?(value: JsonValue): PluginInteractionDescription | Promise<PluginInteractionDescription>;
 }
 interface PluginCliResult {
     exitCode: number;
@@ -1114,6 +1174,15 @@ interface PluginCliRegistration {
     /** Subcommand metadata rendered in help and the plugin-commands skill
      * without executing plugin code. Parsing argv is plugin-owned. */
     commands?: PluginCliCommandInfo[];
+    /**
+     * Set when `run` answers `--help` / `-h` itself, at every level, without
+     * executing a command. The `bb` CLI then forwards help requests to the
+     * plugin instead of printing the one-line `usage` from `commands`.
+     * `defineCli` sets it. Leave it unset for a hand-written `run`:
+     * the host cannot know that such a parser will not act on the other
+     * arguments.
+     */
+    rendersHelp?: boolean;
     run(argv: string[], ctx: PluginCliContext): PluginCliResult | Promise<PluginCliResult>;
 }
 /** Per-turn context handed to bb.agents context providers (design §4.4). */
@@ -1134,30 +1203,37 @@ type PluginAgentToolResult = string | {
 interface PluginAgentToolContext {
     threadId: string;
     projectId: string;
-    /** The tool-call request's abort signal (aborts if the daemon round-trip
-     * is torn down mid-call). */
+    /**
+     * Aborts when the tool-call request is cancelled, the thread is stopped or
+     * deleted, or this plugin is disposed. Opening a form with `bb.ui.requestInput`
+     * detaches the call from its request: the agent receives a waiting notice,
+     * and request cancellation no longer aborts this signal. The tool's eventual
+     * result is delivered as a system message (success steers a running turn or
+     * starts a new one; an `isError` result only steers). Thread stop/delete and
+     * plugin disposal still abort the signal after detachment.
+     */
     signal: AbortSignal;
 }
 /**
- * The row title of a plugin tool call while it is pending and once it
+ * The title of a plugin-owned timeline row 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. */
+interface PluginRowLabels {
+    /** Label shown while the row is pending. */
     pending: string;
-    /** Label shown after the tool call completes successfully. */
+    /** Label shown after the row 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.
+ * How something a plugin owns reads as a timeline row (grammar v3): a native
+ * tool's calls, or the row a `bb.ui.requestInput` form leaves behind. Every
+ * field is optional: the server fills what the plugin leaves out (a generic
+ * label; the plugin's branding glyph, then `Toolbox`) and hands one complete
+ * presentation to whatever renders the row.
  */
-interface PluginAgentToolPresentation {
-    /** Row title while the call is pending and once it settled. */
-    label?: PluginAgentToolLabels;
+interface PluginRowPresentation {
+    /** Row title while the row is pending and once it settled. */
+    label?: PluginRowLabels;
     /**
      * A named host glyph (`{ glyph: "Workflow" }`), or one of this plugin's
      * own declared icons by its namespaced glyph (`{ glyph: "<pluginId>/<name>" }`,
@@ -1549,6 +1625,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. */
@@ -1765,7 +1847,7 @@ declare function publishRpcMethod(method: string, contract: PluginRpcMethodContr
  * 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;
+declare function parsePluginRowPresentation(subject: string, value: unknown): PluginRowPresentation | null;
 /** Compact issue summary from a (possibly foreign-instance) zod error. */
 declare function summarizeStandardIssues(issues: readonly StandardSchemaV1Issue[]): string;
 declare function enforcePluginCliOutputLimit(result: Omit<PluginCliExecutionResult, "error">, jsonOutput: boolean): PluginCliExecutionResult;
@@ -1919,6 +2001,7 @@ declare function normalizeCliRegistration(registration: PluginCliRegistration, a
     name: string;
     summary: string;
     commands: PluginCliCommandInfo[];
+    rendersHelp: boolean;
     run: PluginCliRegistration["run"];
 };
 type AgentToolExecute = (params: unknown, ctx: PluginAgentToolContext) => PluginAgentToolResult | Promise<PluginAgentToolResult>;
@@ -1936,14 +2019,14 @@ declare function normalizeAgentToolRegistration(args: {
         name: string;
         description: string;
         instructions?: string;
-        presentation?: PluginAgentToolPresentation;
+        presentation?: PluginRowPresentation;
         parameters: unknown;
         execute(params: never, ctx: PluginAgentToolContext): PluginAgentToolResult | Promise<PluginAgentToolResult>;
     };
 }): {
     name: string;
     description: string;
-    presentation: PluginAgentToolPresentation | null;
+    presentation: PluginRowPresentation | null;
     instructions: string | null;
     inputSchema: unknown;
     parse: AgentToolParse;
@@ -1958,13 +2041,16 @@ declare function normalizeMentionProviderRegistration(provider: PluginMentionPro
     search: PluginMentionProviderRegistration["search"];
     resolve: PluginMentionProviderRegistration["resolve"];
 };
-declare function normalizeInteractionRequest(request: PluginInteractionRequest): {
+interface NormalizedPluginInteractionRequest {
     threadId: string;
     rendererId: string;
     title: string;
     payload: JsonValue;
     timeoutMs: number;
-};
+    presentation: PluginRowPresentation | null;
+    describeSubmission: NonNullable<PluginInteractionRequest["describeSubmission"]> | null;
+}
+declare function normalizeInteractionRequest(request: PluginInteractionRequest): NormalizedPluginInteractionRequest;
 declare function validateProviderEnvContribution(label: "provider environment contribution" | "provider environment health contribution", providerId: string, resolve: unknown, registered: ReadonlyMap<string, unknown>): void;
 declare function normalizePluginAgentConfiguration(args: {
     knownSkillIds: ReadonlySet<string>;
@@ -1980,5 +2066,5 @@ declare function normalizePluginAgentConfiguration(args: {
 declare function validateRpcValue(schema: StandardSchemaV1, value: unknown, phase: "input" | "output", fail: (error: PluginRpcError) => never): Promise<unknown>;
 declare function normalizeRpcJsonResult(value: unknown, fail: (error: PluginRpcError) => never): JsonValue;
 
-export { ENVIRONMENT_PROVIDER_DESCRIPTION_MAX_CHARS, ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS, ENVIRONMENT_PROVIDER_ID_PATTERN, ENVIRONMENT_PROVIDER_REQUIREMENT_NAMES, KV_VALUE_MAX_BYTES, MACHINE_PROVIDER_DESCRIPTION_MAX_CHARS, PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS, PLUGIN_MENTION_TRIGGER_VALUES, PLUGIN_PROVIDER_BRIDGE_OPTIONS_MAX_BYTES, PLUGIN_PROVIDER_COMPOSER_ACTION_VALUES, PLUGIN_PROVIDER_DISPLAY_NAME_MAX_CHARS, PLUGIN_PROVIDER_ENV_MAX_ENTRIES, PLUGIN_PROVIDER_ENV_NAME_PATTERN, PLUGIN_PROVIDER_PERMISSION_MODE_VALUES, PLUGIN_PROVIDER_REASONING_LEVEL_VALUES, PROVIDER_ID_PATTERN, RESERVED_AGENT_TOOL_NAMES, RESERVED_BB_CLI_COMMANDS, SERVER_DIRECT_AI_SERVICE_IDS, SETTING_KEY_PATTERN, adoptHttpRouteResponse, aiServiceAlreadyRegisteredMessage, assertAiServiceRegistrable, coerceStoredPluginSettingValue, deriveValidatedProviderOptions, enforcePluginCliOutputLimit, environmentCompositionSchema, isPluginMentionTrigger, isStandardSchema, normalizeAgentToolRegistration, normalizeCliRegistration, normalizeHttpRouteRegistration, normalizeInteractionRequest, normalizeMentionProviderRegistration, normalizePluginAgentConfiguration, normalizeRealtimePayload, normalizeRpcJsonResult, normalizeRpcRegistration, normalizeWebSocketRouteRegistration, parsePluginAgentToolPresentation, pluginCliCollisionWarning, pluginHookAlreadyRegisteredMessage, providerAlreadyRegisteredMessage, providerIconRefusalMessage, providerWithoutBridgeMessage, publishRpcMethod, readRpcPublicationOptions, registerSettingDescriptors, runPluginStorageMigrations, storePluginHook, summarizeStandardIssues, undeclaredIconProblem, validateBackgroundServiceRegistration, validatePluginAiServiceDeclaration, validatePluginEnvironmentProviderDeclaration, validatePluginMachineProviderDeclaration, validatePluginProviderDeclaration, validatePluginProviderEnvEntries, validateProviderEnvContribution, validateRpcValue, validateScheduleRegistration, validateServerAccessProviderDeclaration, validateSettingsUpdate };
-export type { AiServiceHostBinding, NormalizedPluginEnvironmentComposition, NormalizedPluginEnvironmentProvider, NormalizedPluginEnvironmentProviderRequirements, NormalizedPluginMachineProvider, NormalizedPluginProviderDeclaration };
+export { ENVIRONMENT_PROVIDER_DESCRIPTION_MAX_CHARS, ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS, ENVIRONMENT_PROVIDER_ID_PATTERN, ENVIRONMENT_PROVIDER_REQUIREMENT_NAMES, KV_VALUE_MAX_BYTES, MACHINE_PROVIDER_DESCRIPTION_MAX_CHARS, PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS, PLUGIN_MENTION_TRIGGER_VALUES, PLUGIN_PROVIDER_BRIDGE_OPTIONS_MAX_BYTES, PLUGIN_PROVIDER_COMPOSER_ACTION_VALUES, PLUGIN_PROVIDER_DISPLAY_NAME_MAX_CHARS, PLUGIN_PROVIDER_ENV_MAX_ENTRIES, PLUGIN_PROVIDER_ENV_NAME_PATTERN, PLUGIN_PROVIDER_PERMISSION_MODE_VALUES, PLUGIN_PROVIDER_REASONING_LEVEL_VALUES, PROVIDER_ID_PATTERN, RESERVED_AGENT_TOOL_NAMES, RESERVED_BB_CLI_COMMANDS, SERVER_DIRECT_AI_SERVICE_IDS, SETTING_KEY_PATTERN, adoptHttpRouteResponse, aiServiceAlreadyRegisteredMessage, assertAiServiceRegistrable, coerceStoredPluginSettingValue, deriveValidatedProviderOptions, enforcePluginCliOutputLimit, environmentCompositionSchema, isPluginMentionTrigger, isStandardSchema, normalizeAgentToolRegistration, normalizeCliRegistration, normalizeHttpRouteRegistration, normalizeInteractionRequest, normalizeMentionProviderRegistration, normalizePluginAgentConfiguration, normalizeRealtimePayload, normalizeRpcJsonResult, normalizeRpcRegistration, normalizeWebSocketRouteRegistration, parsePluginRowPresentation, pluginCliCollisionWarning, pluginHookAlreadyRegisteredMessage, providerAlreadyRegisteredMessage, providerIconRefusalMessage, providerWithoutBridgeMessage, publishRpcMethod, readRpcPublicationOptions, registerSettingDescriptors, runPluginStorageMigrations, storePluginHook, summarizeStandardIssues, undeclaredIconProblem, validateBackgroundServiceRegistration, validatePluginAiServiceDeclaration, validatePluginEnvironmentProviderDeclaration, validatePluginMachineProviderDeclaration, validatePluginProviderDeclaration, validatePluginProviderEnvEntries, validateProviderEnvContribution, validateRpcValue, validateScheduleRegistration, validateServerAccessProviderDeclaration, validateSettingsUpdate };
+export type { AiServiceHostBinding, NormalizedPluginEnvironmentComposition, NormalizedPluginEnvironmentProvider, NormalizedPluginEnvironmentProviderRequirements, NormalizedPluginInteractionRequest, NormalizedPluginMachineProvider, NormalizedPluginProviderDeclaration };

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

@@ -3589,6 +3589,7 @@ declare const threadEventSchema: z.ZodPipe<z.ZodUnknown, z.ZodUnion<readonly [z.
         "child-outcome-batch": "child-outcome-batch";
         "ownership-assigned": "ownership-assigned";
         "ownership-removed": "ownership-removed";
+        "tool-result-delivered": "tool-result-delivered";
         unlabeled: "unlabeled";
     }>>;
     systemMessageSubject: z.ZodOptional<z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -3598,6 +3599,10 @@ declare const threadEventSchema: z.ZodPipe<z.ZodUnknown, z.ZodUnion<readonly [z.
     }, z.core.$strip>, z.ZodObject<{
         count: z.ZodNumber;
         kind: z.ZodLiteral<"thread-batch">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"tool-call">;
+        suppress: z.ZodBoolean;
+        toolName: z.ZodString;
     }, z.core.$strip>], "kind">>>;
     target: z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"thread-start">;
@@ -3851,9 +3856,39 @@ declare const threadEventSchema: z.ZodPipe<z.ZodUnknown, z.ZodUnion<readonly [z.
         }, z.core.$strip>;
         payload: z.ZodObject<{
             kind: z.ZodLiteral<"plugin">;
+            presentation: z.ZodOptional<z.ZodObject<{
+                badge: z.ZodOptional<z.ZodObject<{
+                    glyph: z.ZodString;
+                    hint: z.ZodString;
+                    label: z.ZodString;
+                    tone: z.ZodEnum<{
+                        destructive: "destructive";
+                        neutral: "neutral";
+                    }>;
+                }, z.core.$strip>>;
+                detail: z.ZodOptional<z.ZodString>;
+                icon: z.ZodObject<{
+                    glyph: z.ZodString;
+                }, z.core.$strip>;
+                label: z.ZodObject<{
+                    completed: z.ZodString;
+                    pending: z.ZodString;
+                }, z.core.$strip>;
+                suppress: z.ZodOptional<z.ZodBoolean>;
+                tint: z.ZodOptional<z.ZodObject<{
+                    dark: z.ZodString;
+                    light: z.ZodString;
+                }, z.core.$strip>>;
+                title: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
             title: z.ZodString;
         }, z.core.$strip>;
         resolution: z.ZodNullable<z.ZodObject<{
+            description: z.ZodOptional<z.ZodObject<{
+                detail: z.ZodOptional<z.ZodString>;
+                payload: z.ZodOptional<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>;
+                title: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
             kind: z.ZodLiteral<"plugin_submitted">;
         }, z.core.$strip>>;
         status: z.ZodEnum<{