@get-bb/plugin-sdk 0.4.10 → 0.4.12

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

@@ -181,6 +181,80 @@ declare const promptInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>], "type">;
 type PromptInput = z.infer<typeof promptInputSchema>;
 
+declare const providerInfoSchema: z.ZodObject<{
+    available: z.ZodBoolean;
+    capabilities: z.ZodObject<{
+        permissionModes: z.ZodArray<z.ZodEnum<{
+            "accept-edits": "accept-edits";
+            auto: "auto";
+            full: "full";
+        }>>;
+        supportsFork: z.ZodBoolean;
+        supportsNativeUserQuestion: z.ZodBoolean;
+        supportsServiceTier: z.ZodBoolean;
+        supportsSessionRewind: z.ZodBoolean;
+        supportsThreadArchive: z.ZodBoolean;
+        supportsThreadRename: z.ZodBoolean;
+    }, z.core.$strip>;
+    composerActions: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"skills">;
+        trigger: z.ZodEnum<{
+            "/": "/";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        command: z.ZodObject<{
+            name: z.ZodString;
+            trailingText: z.ZodString;
+            trigger: z.ZodEnum<{
+                "/": "/";
+            }>;
+        }, z.core.$strip>;
+        kind: z.ZodLiteral<"plan">;
+    }, z.core.$strip>, z.ZodObject<{
+        command: z.ZodObject<{
+            name: z.ZodString;
+            trailingText: z.ZodString;
+            trigger: z.ZodEnum<{
+                "/": "/";
+            }>;
+        }, z.core.$strip>;
+        kind: z.ZodLiteral<"goal">;
+    }, z.core.$strip>], "kind">>;
+    displayName: z.ZodString;
+    experimental_providerHealth: z.ZodBoolean;
+    experimental_providerInstallation: z.ZodBoolean;
+    experimental_providerUsage: z.ZodBoolean;
+    extensionKinds: z.ZodOptional<z.ZodRecord<z.ZodString & z.ZodType<`${string}/${string}`, string, z.core.$ZodTypeInternals<`${string}/${string}`, string>>, z.ZodObject<{
+        item: z.ZodBoolean;
+        state: z.ZodBoolean;
+    }, z.core.$strip>>>;
+    family: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    logoUrl: z.ZodNullable<z.ZodString>;
+    reasoningLevels: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>>;
+    serviceTiers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>>;
+    strings: z.ZodOptional<z.ZodObject<{
+        brandPrefix: z.ZodOptional<z.ZodString>;
+        expiredHint: z.ZodString;
+        iconTint: z.ZodOptional<z.ZodObject<{
+            dark: z.ZodString;
+            light: z.ZodString;
+        }, z.core.$strip>>;
+        installUrl: z.ZodString;
+        planModeCopy: z.ZodOptional<z.ZodString>;
+        signInHint: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type ProviderInfo = z.infer<typeof providerInfoSchema>;
+
 declare const createThreadEnvironmentArgsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     environmentId: z.ZodString;
     type: z.ZodLiteral<"reuse">;
@@ -405,6 +479,18 @@ interface SourceCodeLineRange {
     start: number;
     end: number;
 }
+/** One complete text side of a diff, resolved by the caller. */
+interface ExperimentalDiffFileContent {
+    /** File path for this side. May differ between `old` and `new` for a rename. */
+    path: string;
+    /** Complete UTF-8 file contents, including unchanged lines outside the patch. */
+    content: string;
+}
+/** Complete text contents for both sides of a diff. */
+interface ExperimentalDiffFullFileContents {
+    old: ExperimentalDiffFileContent;
+    new: ExperimentalDiffFileContent;
+}
 /**
  * Props of the host-owned `experimental_SourceCode` component — BB's source
  * viewer. The host owns syntax highlighting, gutters, wrapping, line-selection
@@ -430,8 +516,9 @@ interface SourceCodeProps {
  * Props of the host-owned `experimental_Diff` component — BB's diff viewer.
  * The host owns patch normalization (a patch without a `diff --git` header is
  * completed from `path`), syntax highlighting, unified/split presentation,
- * gutters, line-selection presentation, and the live BB code theme. Content
- * that cannot be parsed as a patch degrades to plain monospace text.
+ * gutters, line-selection presentation, optional full-file context expansion,
+ * and the live BB code theme. Content that cannot be parsed as a patch
+ * degrades to plain monospace text.
  */
 interface DiffProps {
     /** Unified patch text for exactly ONE file. */
@@ -448,6 +535,12 @@ interface DiffProps {
     overflow?: CodeOverflowMode;
     /** Whether the gutter shows line numbers. Defaults to `true`. */
     showLineNumbers?: boolean;
+    /**
+     * Complete text for both file sides. When present and consistent with the
+     * patch, BB enables expand-context controls between hunks. The caller owns
+     * loading these contents; omit the field to render from the patch alone.
+     */
+    experimental_fullFileContents?: ExperimentalDiffFullFileContents;
     /** Applied to the renderer's root element. */
     className?: string;
 }
@@ -470,7 +563,8 @@ interface PluginSourceCodeRendererProps {
 }
 /**
  * Props passed to an `experimental_diffRenderer` component. `patch` is always
- * a complete single-file unified patch, whatever shape the caller supplied.
+ * a complete single-file unified patch, whatever shape the caller supplied,
+ * and optional full-file context is resolved to an object or `null`.
  */
 interface PluginDiffRendererProps {
     patch: string;
@@ -478,6 +572,14 @@ interface PluginDiffRendererProps {
     view: DiffViewMode;
     overflow: CodeOverflowMode;
     showLineNumbers: boolean;
+    /**
+     * Caller-resolved text for both sides, or `null` when the caller supplied
+     * only the patch. A replacement can use this to implement context expansion,
+     * but must verify that the paths and hunk lines agree with `patch` before
+     * treating the contents as complete. BB's original renderer performs that
+     * verification when it mounts.
+     */
+    experimental_fullFileContents: ExperimentalDiffFullFileContents | null;
     /**
      * BB's diff renderer, bound to this request. Render it to delegate
      * conditionally without re-entering plugin replacement resolution.
@@ -787,7 +889,8 @@ interface PluginSidebarThread {
     originKind: "fork" | null;
     /** The plugin that spawned it, or null for non-plugin origins. */
     originPluginId: string | null;
-    /** The agent provider this thread runs on, e.g. "codex", "claude-code". */
+    /** The agent provider this thread runs on; resolve it through
+     * {@link PluginSdkApp.experimental_useProviders} for a name and icon. */
     providerId: string;
     /** The agent is blocked on the user: an approval or a question. */
     hasPendingInteraction: boolean;
@@ -857,6 +960,17 @@ interface PluginSidebarThreadsState {
     threads: readonly PluginSidebarThread[];
     projects: readonly PluginSidebarProject[];
 }
+/**
+ * The provider directory (see {@link PluginSdkApp.experimental_useProviders}):
+ * every registered agent provider in picker order, as the same `ProviderInfo`
+ * the host's own pickers read. `logoUrl` is server-relative
+ * (`/api/v1/system/providers/<id>/logo`) or null when the provider declared a
+ * glyph or no icon; `strings` carries the provider's declared copy.
+ */
+interface PluginProvidersState {
+    status: "error" | "loading" | "ready";
+    providers: readonly ProviderInfo[];
+}
 /**
  * Act on threads from a plugin surface. Every method routes to the host's own
  * flow, so optimistic updates, toasts, dialogs, pane closing, and route repair
@@ -1844,6 +1958,13 @@ interface PluginSdkApp {
      * Experimental: see docs/api_to_audit.md.
      */
     experimental_useSidebarThreadSplit(threadId: string): PluginSidebarThreadSplit;
+    /**
+     * The provider directory (see {@link PluginProvidersState}). Reads the
+     * host's own cached provider roster, so a plugin that shows a thread's
+     * provider never re-vendors provider names, icons, or copy. Experimental:
+     * see docs/api_to_audit.md.
+     */
+    experimental_useProviders(): PluginProvidersState;
     /**
      * The host-owned chat component (see {@link ThreadChatProps}). Together
      * with `Markdown`, the only components the SDK ships — everything else
@@ -1877,8 +1998,9 @@ interface PluginSdkApp {
     experimental_SourceCode: ComponentType<SourceCodeProps>;
     /**
      * The host-owned diff viewer (see {@link DiffProps}). Renders supplied patch
-     * content with BB's normalization, syntax highlighting, unified/split
-     * presentation, and live code theme, and honours an active
+     * content with BB's normalization, optional full-file context expansion,
+     * syntax highlighting, unified/split presentation, and live code theme, and
+     * honours an active
      * `experimental_diffRenderer` replacement. Experimental: see
      * docs/api_to_audit.md.
      */
@@ -1908,6 +2030,7 @@ declare const experimental_useSidebarThreads: () => PluginSidebarThreadsState;
 declare const experimental_useSidebarThreadActions: () => PluginSidebarThreadActions;
 declare const experimental_useSidebarThreadPullRequest: (threadId: string) => PluginSidebarThreadPullRequestState;
 declare const experimental_useSidebarThreadSplit: (threadId: string) => PluginSidebarThreadSplit;
+declare const experimental_useProviders: () => PluginProvidersState;
 
-export { Markdown, ThreadChat, definePluginApp, experimental_Diff, experimental_FileLink, experimental_NewThreadComposer, experimental_SourceCode, experimental_UrlLink, experimental_useAppPanel, experimental_useFixedTabTarget, experimental_useSidebarThreadActions, experimental_useSidebarThreadPullRequest, experimental_useSidebarThreadSplit, experimental_useSidebarThreads, useBbContext, useBbNavigate, useComposer, useComposerView, useRealtime, useRealtimeConnectionState, useRpc, useSettings };
-export type { BbContext, BbNavigate, CodeOverflowMode, ComposerCustomization, ComposerPlusMenuItem, ComposerRichTextSpec, ComposerStructuredDraft, ComposerView, DiffProps, DiffViewMode, ExperimentalAppPanel, ExperimentalAppPanelSurface, ExperimentalFileLinkProps, ExperimentalFileLocation, ExperimentalFileOpenOptions, ExperimentalFixedTabTargetContract, ExperimentalFixedTabTargetState, ExperimentalLiveFileTarget, ExperimentalOpenFixedTabOptions, ExperimentalPluginFixedTabDeclaration, ExperimentalPluginFixedTabReference, ExperimentalPluginFixedTabRegistration, ExperimentalUrlLinkProps, JsonValue, MarkdownProps, NewThreadComposerProps, NewThreadRequest, PluginAppBuilder, PluginAppComposer, PluginAppContentScripts, PluginAppDefinition, PluginAppSetup, PluginAppSlots, PluginComposerApi, PluginComposerMention, PluginComposerScope, PluginComposerTextEffect, PluginComposerThreadRowStatus, PluginContentScriptContext, PluginContentScriptDisposer, PluginContentScriptRegistration, PluginDiffRendererProps, PluginDiffRendererRegistration, PluginFileOpenerProps, PluginFileOpenerRegistration, PluginFileOpenerSource, PluginHomepageSectionProps, PluginHomepageSectionRegistration, PluginMessageActionContext, PluginMessageActionRegistration, PluginMessageDirectiveMessage, PluginMessageDirectiveOpenWorkspaceFile, PluginMessageDirectiveProps, PluginMessageDirectiveRegistration, PluginNavPanelProps, PluginNavPanelRegistration, PluginNewThreadPanelActionContext, PluginNewThreadPanelActionRegistration, PluginNewThreadPanelProps, PluginPanelActionOpenOptions, PluginPendingInteractionProps, PluginPendingInteractionRegistration, PluginPendingInteractionView, PluginProviderIconRegistration, 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, PluginSidebarWorkspaceKind, PluginSourceCodeRendererProps, PluginSourceCodeRendererRegistration, PluginTargetedPanelActionOpenOptions, PluginThreadHeaderActionProps, PluginThreadHeaderActionRegistration, PluginThreadListProps, PluginThreadListRegistration, PluginThreadPanelActionContext, PluginThreadPanelActionRegistration, PluginThreadPanelProps, SourceCodeLineRange, SourceCodeProps, StandardSchemaV1, StandardSchemaV1InferInput, StandardSchemaV1InferOutput, StandardSchemaV1Issue, StandardSchemaV1Result, ThreadChatMessageAction, ThreadChatMessageReference, ThreadChatProps };
+export { Markdown, ThreadChat, definePluginApp, experimental_Diff, experimental_FileLink, experimental_NewThreadComposer, experimental_SourceCode, experimental_UrlLink, experimental_useAppPanel, experimental_useFixedTabTarget, experimental_useProviders, experimental_useSidebarThreadActions, experimental_useSidebarThreadPullRequest, experimental_useSidebarThreadSplit, experimental_useSidebarThreads, useBbContext, useBbNavigate, useComposer, useComposerView, useRealtime, useRealtimeConnectionState, useRpc, useSettings };
+export type { BbContext, BbNavigate, CodeOverflowMode, ComposerCustomization, ComposerPlusMenuItem, ComposerRichTextSpec, ComposerStructuredDraft, ComposerView, DiffProps, DiffViewMode, ExperimentalAppPanel, ExperimentalAppPanelSurface, ExperimentalDiffFileContent, ExperimentalDiffFullFileContents, ExperimentalFileLinkProps, ExperimentalFileLocation, ExperimentalFileOpenOptions, ExperimentalFixedTabTargetContract, ExperimentalFixedTabTargetState, ExperimentalLiveFileTarget, ExperimentalOpenFixedTabOptions, ExperimentalPluginFixedTabDeclaration, ExperimentalPluginFixedTabReference, ExperimentalPluginFixedTabRegistration, ExperimentalUrlLinkProps, JsonValue, MarkdownProps, NewThreadComposerProps, NewThreadRequest, PluginAppBuilder, PluginAppComposer, PluginAppContentScripts, PluginAppDefinition, PluginAppSetup, PluginAppSlots, PluginComposerApi, PluginComposerMention, PluginComposerScope, PluginComposerTextEffect, PluginComposerThreadRowStatus, PluginContentScriptContext, PluginContentScriptDisposer, PluginContentScriptRegistration, PluginDiffRendererProps, PluginDiffRendererRegistration, PluginFileOpenerProps, PluginFileOpenerRegistration, PluginFileOpenerSource, PluginHomepageSectionProps, PluginHomepageSectionRegistration, 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, PluginSidebarWorkspaceKind, PluginSourceCodeRendererProps, PluginSourceCodeRendererRegistration, PluginTargetedPanelActionOpenOptions, PluginThreadHeaderActionProps, PluginThreadHeaderActionRegistration, PluginThreadListProps, PluginThreadListRegistration, PluginThreadPanelActionContext, PluginThreadPanelActionRegistration, PluginThreadPanelProps, SourceCodeLineRange, SourceCodeProps, StandardSchemaV1, StandardSchemaV1InferInput, StandardSchemaV1InferOutput, StandardSchemaV1Issue, StandardSchemaV1Result, ThreadChatMessageAction, ThreadChatMessageReference, ThreadChatProps };

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

@@ -19,7 +19,7 @@ declare const RESERVED_BB_CLI_COMMANDS: readonly string[];
 /**
  * How completely a provider can clone one of its sessions — the single
  * vocabulary shared by the provider declaration
- * (`bb.agents.experimental_registerProvider`), the server→daemon
+ * (`bb.providers.register`), the server→daemon
  * `bridgeLaunch`, and the bridge's `initialize` handshake.
  *
  * - `"none"`: sessions cannot be cloned at all.
@@ -108,6 +108,7 @@ type PluginSettingDescriptor = {
     default?: string;
 };
 type PluginSettingDescriptors = Record<string, PluginSettingDescriptor>;
+type PluginSettingValue = string | boolean;
 interface PluginCliOutputLimitError {
     code: "plugin_cli_output_too_large";
     message: string;
@@ -190,9 +191,6 @@ interface PluginProviderCapabilities {
     /** The provider stores a thread name of its own, so BB forwards renames to
      * it. */
     supportsThreadRename: boolean;
-    /** The provider can run BB's Workflow tools — gates the workflows opt-in on
-     * new threads. */
-    supportsWorkflows: boolean;
     /** Permission modes the provider can actually run in. Non-empty, no
      * duplicates. */
     permissionModes: readonly PluginProviderPermissionMode[];
@@ -200,14 +198,109 @@ interface PluginProviderCapabilities {
      * {@link PluginProviderReasoningLevel}). Non-empty, no duplicates. */
     reasoningLevels: readonly PluginProviderReasoningLevel[];
 }
+/**
+ * Provider copy core surfaces render from per-provider tables today (usage
+ * banners, sign-in hints, the mobile picker, the agent guide). Declared once
+ * here so no core surface keys copy on a provider id. Mirrors
+ * `ProviderStrings` in `@bb/domain`, which is the client projection.
+ */
+interface PluginProviderStrings {
+    /** How to sign in on the host ("Run `claude` on the machine to sign in."). */
+    signInHint: string;
+    /** Shown when a session's credentials expired. */
+    expiredHint: string;
+    /** Where to install the agent. */
+    installUrl: string;
+    /** Brand prefix stripped from model display names ("Claude "). */
+    brandPrefix?: string;
+    /** Plan-mode banner copy for providers that declare the `plan` action. */
+    planModeCopy?: string;
+    /** Per-theme tint for the provider icon. */
+    iconTint?: {
+        light: string;
+        dark: string;
+    };
+}
+/**
+ * One selectable option for a picker — a service tier or a reasoning level.
+ * `id` is the wire value the bridge receives; `label` is what the picker
+ * shows. Declared lists are the cold-cache fallback; `model/list` is precise
+ * per model.
+ */
+interface PluginProviderOptionDescriptor {
+    id: string;
+    label: string;
+    description?: string;
+}
+/**
+ * Payload schemas for one extension kind this provider emits, keyed by the
+ * kind's local name (the server prefixes the plugin id to form the
+ * namespaced `"<pluginId>/<name>"`). `item` validates `item.open` payloads
+ * with `type: "extension"`, `state` validates `extension.state` payloads;
+ * each is optional so a kind can be item-only or state-only. Schemas are
+ * Standard Schema v1 validators (zod 4 schemas qualify).
+ */
+interface PluginProviderExtensionKindDeclaration {
+    item?: StandardSchemaV1;
+    state?: StandardSchemaV1;
+}
+/**
+ * Per-command context handed to
+ * {@link PluginProviderDeclaration.experimental_deriveProviderOptions}. The
+ * server builds one for every session and turn command it dispatches on a
+ * thread of this provider.
+ */
+interface PluginProviderOptionsContext {
+    threadId: string;
+    projectId: string;
+    /** The resolved model id for this command. */
+    model: string;
+    /** BB's permission mode for this command (already clamped to the host). */
+    permissionMode: PluginProviderPermissionMode;
+    /**
+     * `"plan"` when the prompt entered plan mode through this provider's
+     * declared `plan` composer action. Absent for an ordinary prompt — plan
+     * mode is a BB prompt mode, so the bridge maps it onto whatever the agent
+     * calls it natively.
+     */
+    promptMode?: "plan";
+    /**
+     * This plugin's own settings values (`bb.settings.define`), read at call
+     * time. Secret settings are omitted — provider options ride the daemon
+     * wire and are persisted with the session, so a secret must never be
+     * derived into them.
+     */
+    settings: Readonly<Record<string, PluginSettingValue | undefined>>;
+}
+/**
+ * One cold-cache fallback model. The provider's live `model/list` result is
+ * the only real model source; this list stands in only while no probe has
+ * completed, or when a probe fails transiently, so the picker is not empty.
+ * `id` is the wire model id the bridge receives.
+ */
+interface PluginProviderFallbackModel {
+    id: string;
+    /** Picker display name ("Opus 5 (1M)"). */
+    displayName: string;
+    description: string;
+    /** Reasoning levels this model supports, lowest to highest. Non-empty. */
+    supportedReasoningEfforts: readonly {
+        reasoningEffort: PluginProviderReasoningLevel;
+        description: string;
+    }[];
+    /** Must be one of `supportedReasoningEfforts`. */
+    defaultReasoningEffort: PluginProviderReasoningLevel;
+    /** Exactly one entry in the list is the default. */
+    isDefault: boolean;
+}
 /**
  * One provider this plugin contributes to BB's provider registry.
  *
  * Ids are stable public identifiers — thread rows and routes reference them —
  * and are collision-rejected: a declaration whose id matches another plugin's
- * live registration, or reserves a first-party provider it does not own, is
- * refused. Registrations are replaced wholesale on plugin reload, like every
- * other plugin surface.
+ * live registration is refused; the first registration wins and no id is
+ * reserved ahead of time. Registrations are replaced wholesale on plugin
+ * reload, like every other plugin surface.
  *
  * A declaration owns the provider's static metadata and bridge options. The
  * executable implementation is the plugin's own provider bridge, named by
@@ -222,6 +315,12 @@ interface PluginProviderDeclaration {
     id: string;
     /** Picker display name: 1–80 characters, non-blank. */
     displayName: string;
+    /**
+     * Optional grouping key (same grammar as `id`) for providers that share a
+     * family — the ACP agents, for example — so clients can group them without
+     * parsing a prefix out of the id. Grouping only: no policy keys on it.
+     */
+    experimental_family?: string;
     /**
      * Optional picker icon, in the same grammar as `bb.branding.icon`: either a
      * named host glyph (`"Zap"`) or a plugin-relative path starting with `"./"`
@@ -248,6 +347,52 @@ interface PluginProviderDeclaration {
     /** Composer actions this provider supports. No duplicates; may be empty
      * (the universal skills typeahead is implicit). */
     composerActions: readonly PluginProviderComposerAction[];
+    /** Provider copy for core surfaces ({@link PluginProviderStrings}). */
+    experimental_strings?: PluginProviderStrings;
+    /** Service tiers this provider accepts, as picker options. Non-empty when
+     * present, unique ids. The coarse `capabilities.supportsServiceTier` stays
+     * until WS2a stabilizes. */
+    experimental_serviceTiers?: readonly PluginProviderOptionDescriptor[];
+    /** Reasoning levels as picker options with labels, beside the coarse
+     * `capabilities.reasoningLevels` ladder (ids only). Non-empty when present,
+     * unique ids. WS2a merges the two. */
+    experimental_reasoningLevels?: readonly PluginProviderOptionDescriptor[];
+    /** Extension kinds this provider's bridge may emit, keyed by local name
+     * (`[a-z0-9-]+`). The server validates extension payloads against these
+     * schemas at ingest and persists a `provider/unhandled` on a miss. */
+    experimental_extensionKinds?: Readonly<Record<string, PluginProviderExtensionKindDeclaration>>;
+    /**
+     * Cold-cache fallback models ({@link PluginProviderFallbackModel}). The
+     * server offers them only while a model probe has not completed or failed
+     * transiently; the live `model/list` result always replaces them. Ids must
+     * be unique and exactly one entry must be the default.
+     */
+    experimental_models?: {
+        fallback: readonly PluginProviderFallbackModel[];
+    };
+    /**
+     * Daemon environment variables this provider's bridge may read. Provider
+     * processes are spawned with every inherited `BB_*` variable stripped, so a
+     * bridge that honors an operator override (a CLI path, say) names it here
+     * and the daemon forwards exactly those variables. Names are
+     * `[A-Z_][A-Z0-9_]*`, at most 32.
+     */
+    experimental_env?: {
+        passthrough: readonly string[];
+    };
+    /**
+     * Derive this provider's opaque per-command options. Called synchronously
+     * by the server for every session and turn command on a thread of this
+     * provider, with the command's {@link PluginProviderOptionsContext}; the
+     * returned JSON object reaches this plugin's bridge as
+     * `options.providerOptions`, merged over `experimental_bridgeOptions`. Core
+     * never interprets its keys — this is where a provider's own knobs (memory,
+     * native subagents, a native plan flag) travel instead of on the shared
+     * execution contract. A throw fails the command with the plugin named, so
+     * a buggy hook cannot silently run a turn with default knobs. Must be fast:
+     * it sits on the turn-submit path.
+     */
+    experimental_deriveProviderOptions?: (context: PluginProviderOptionsContext) => Readonly<Record<string, JsonValue>>;
 }
 type PluginMentionTrigger = "!" | "#" | "$" | "@" | "~";
 
@@ -291,13 +436,24 @@ declare const PLUGIN_PROVIDER_PERMISSION_MODE_VALUES: readonly ["accept-edits",
 declare const PLUGIN_PROVIDER_REASONING_LEVEL_VALUES: readonly ["none", "low", "medium", "high", "xhigh", "ultracode", "max", "ultra"];
 declare const PLUGIN_PROVIDER_COMPOSER_ACTION_VALUES: readonly ["plan", "goal"];
 /**
- * Validate one `bb.agents.experimental_registerProvider` declaration. Plugin
+ * Validate one `bb.providers.register` declaration. Plugin
  * sources are untyped at runtime, so every field is checked; the production
  * host and the fake host both call this, so they accept and reject provider
  * declarations identically. Throws a descriptive error on the first problem;
  * returns a normalized, deeply frozen copy carrying only contract fields.
  */
 declare function validatePluginProviderDeclaration(declaration: PluginProviderDeclaration): PluginProviderDeclaration;
+/**
+ * Run a declaration's `experimental_deriveProviderOptions` hook for one
+ * command and validate its result as a bounded, plain-JSON object — the same
+ * rules as `experimental_bridgeOptions`, because the result rides the same
+ * wire slot. Shared by the real host and the fake so a hook that works in
+ * tests works in production.
+ */
+declare function deriveValidatedProviderOptions(args: {
+    declaration: PluginProviderDeclaration;
+    context: Parameters<NonNullable<PluginProviderDeclaration["experimental_deriveProviderOptions"]>>[0];
+}): Readonly<Record<string, JsonValue>>;
 declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
 declare function readRpcMethodContract(method: string, value: unknown): PluginRpcMethodContract;
 /** Duck-typed zod detection: plugin sources may carry their own zod copy,
@@ -327,4 +483,4 @@ declare function enforcePluginCliOutputLimit(result: Omit<PluginCliExecutionResu
  */
 declare function adoptHttpRouteResponse(value: unknown): Response;
 
-export { AGENT_TOOL_NAME_PATTERN, BACKGROUND_NAME_PATTERN, CLI_COMMAND_NAME_PATTERN, KV_VALUE_MAX_BYTES, MENTION_PROVIDER_ID_PATTERN, PLUGIN_AGENT_DYNAMIC_INSTRUCTIONS_MAX_CHARS, PLUGIN_AGENT_SELECTION_MAX_IDS, PLUGIN_AGENT_STATIC_INSTRUCTIONS_MAX_CHARS, PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS, PLUGIN_AGENT_TOOL_PARAMETERS_MAX_BYTES, PLUGIN_HTTP_METHODS, PLUGIN_MENTION_TRIGGER_VALUES, PLUGIN_PROVIDER_BRIDGE_OPTIONS_MAX_BYTES, PLUGIN_PROVIDER_COMPOSER_ACTION_VALUES, PLUGIN_PROVIDER_DISPLAY_NAME_MAX_CHARS, PLUGIN_PROVIDER_PERMISSION_MODE_VALUES, PLUGIN_PROVIDER_REASONING_LEVEL_VALUES, PROVIDER_ID_PATTERN, RESERVED_AGENT_TOOL_NAMES, RESERVED_BB_CLI_COMMANDS, RPC_METHOD_PATTERN, SETTING_KEY_PATTERN, adoptHttpRouteResponse, assertNoRecursiveJsonSchemaReferences, enforcePluginCliOutputLimit, isPluginMentionTrigger, isStandardSchema, isZodSchemaLike, normalizeMentionProviderTriggers, readRpcMethodContract, registerSettingDescriptors, summarizeParseIssues, validatePluginProviderDeclaration, validateSettingsUpdate };
+export { AGENT_TOOL_NAME_PATTERN, BACKGROUND_NAME_PATTERN, CLI_COMMAND_NAME_PATTERN, KV_VALUE_MAX_BYTES, MENTION_PROVIDER_ID_PATTERN, PLUGIN_AGENT_DYNAMIC_INSTRUCTIONS_MAX_CHARS, PLUGIN_AGENT_SELECTION_MAX_IDS, PLUGIN_AGENT_STATIC_INSTRUCTIONS_MAX_CHARS, PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS, PLUGIN_AGENT_TOOL_PARAMETERS_MAX_BYTES, PLUGIN_HTTP_METHODS, PLUGIN_MENTION_TRIGGER_VALUES, PLUGIN_PROVIDER_BRIDGE_OPTIONS_MAX_BYTES, PLUGIN_PROVIDER_COMPOSER_ACTION_VALUES, PLUGIN_PROVIDER_DISPLAY_NAME_MAX_CHARS, PLUGIN_PROVIDER_PERMISSION_MODE_VALUES, PLUGIN_PROVIDER_REASONING_LEVEL_VALUES, PROVIDER_ID_PATTERN, RESERVED_AGENT_TOOL_NAMES, RESERVED_BB_CLI_COMMANDS, RPC_METHOD_PATTERN, SETTING_KEY_PATTERN, adoptHttpRouteResponse, assertNoRecursiveJsonSchemaReferences, deriveValidatedProviderOptions, enforcePluginCliOutputLimit, isPluginMentionTrigger, isStandardSchema, isZodSchemaLike, normalizeMentionProviderTriggers, readRpcMethodContract, registerSettingDescriptors, summarizeParseIssues, validatePluginProviderDeclaration, validateSettingsUpdate };