@get-bb/plugin-sdk 0.4.9 → 0.4.10

package/README.md

@@ -21,6 +21,42 @@ Any mounted plugin component can use
 same plugin's registered thread-panel actions; it returns false when the
 current surface has no thread side panel.
 
+Use `experimental_UrlLink` for a real anchor that applies BB's current
+in-app/external-browser preference on ordinary HTTP(S) activation, or
+`useBbNavigate().experimental_openUrl(url)` for a button or menu. Internal app
+routes, modifier clicks, explicit anchor targets, and unsupported schemes stay
+browser-owned. A `_blank` or named target preserves supplied `rel` tokens but
+adds `noopener noreferrer` unless `rel` explicitly contains `opener`, so a
+newly opened page cannot control BB by accident. The frontend harness records
+both forms in `navigateCalls` and accepts an `openUrl` behavior option.
+
+Use `experimental_FileLink` for an explicit live workspace, host, or
+thread-storage file. Ordinary activation opens the shared BB preview and its
+context menu exposes built-in/plugin viewers, preferred external opening, and
+copy actions. Valid targets expose an encoded, scheme-safe anchor href so
+modifier clicks, downloads, and copied links cannot reinterpret a file name as
+an external URL scheme. Malformed runtime targets—including traversal paths
+and ill-formed Unicode—have no active href and cannot record a preview in the
+frontend harness. Buttons and menus can call
+`experimental_openFilePreview({ target, location })` or
+`experimental_openFileExternally({ target, location })`; both return whether
+the current host accepted the intent. Targets never infer an ambient workspace.
+The frontend harness records both methods and accepts `openFilePreview` and
+`openFileExternally` behavior options.
+
+A nav panel's `experimental_fixedTabs` entries must include the containing nav
+panel's `id` as `panelId`; each entry is also a stable reference to that
+plugin's own tab. Give a targeted tab an `experimental_target.validate` type guard, call
+`experimental_useAppPanel().openFixedTab({ surface: { kind:
+"current" }, tab, target })`, and read the in-memory state inside the tab with
+`experimental_useFixedTabTarget(tab)`. The target survives tab, panel, and
+route remounts for the current app session; call `clear()` when the tab returns
+to its untargeted state. The host validates JSON before the owner's type guard,
+persists only selection, and returns false for an unavailable tab or invalid
+target. The frontend harness records accepted requests in
+`experimental_fixedTabOpenCalls`, accepts an `experimental_openFixedTab`
+behavior, and can seed `experimental_fixedTabTarget` state.
+
 Every panel-open entry point reports the same way: `openThreadPanel` and the
 `openPanel` handed to `threadPanelAction`, `experimental_newThreadPanelAction`,
 and `messageAction` `run` callbacks all return `boolean` — true when the host
@@ -45,8 +81,13 @@ reload, disable, removal, failed replacement, and app-window teardown. The old
 generation is disposed before candidate mounts, so generations never overlap.
 Content scripts are trusted same-origin page code, not a sandbox.
 
-Static styles should stay in the normal imported `app.css`; scripts may own
-dynamic DOM/style nodes when their disposer removes them. See the
+Static styles should stay in the normal imported `app.css`. The host keeps
+that stylesheet active while the plugin has rendered slot, panel-header, or
+portal UI, and for the full lifetime of any active content-script generation;
+it is not an app-wide stylesheet hook. Use manifest `bb.themes` entries for
+app-wide selectable palette CSS. Styling or decorating existing app-shell DOM
+belongs in a content script, and scripts may own dynamic DOM/style nodes only
+when their disposer removes them. See the
 [`content-script` reference plugin](../../examples/plugins/content-script/README.md)
 for a cleanup-safe editor enhancement.
 

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

@@ -6,9 +6,19 @@
 // and read the real source: https://github.com/get-bb/bb
 
 import * as react from 'react';
-import { ComponentType, ReactNode } from 'react';
+import { ComponentType, ComponentPropsWithoutRef, ReactNode } from 'react';
 import { z } from 'zod';
 
+/**
+ * A value that survives a JSON round trip without coercion or data loss.
+ *
+ * Host boundaries still validate values at runtime because TypeScript cannot
+ * exclude non-finite numbers and plugin bundles can bypass static types.
+ */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+
 /** A JSON-safe path segment reported by a Standard Schema validation issue. */
 type PluginRpcIssuePathSegment = string | number;
 /** Validator-neutral validation detail carried by an RPC error envelope. */
@@ -227,16 +237,6 @@ declare const createExecutionInputSourcesSchema: z.ZodObject<{
 }, z.core.$strict>;
 type CreateExecutionInputSources = z.infer<typeof createExecutionInputSourcesSchema>;
 
-/**
- * A value that survives a JSON round trip without coercion or data loss.
- *
- * Host boundaries still validate values at runtime because TypeScript cannot
- * exclude non-finite numbers and plugin bundles can bypass static types.
- */
-type JsonValue = string | number | boolean | null | JsonValue[] | {
-    [key: string]: JsonValue;
-};
-
 /**
  * The `@get-bb/plugin-sdk/app` contract (plugin design §5.2) — pure types with no
  * side effects. The BB app imports these to keep its real implementation in
@@ -376,6 +376,13 @@ interface PluginFileOpenerSource {
     threadId: string | null;
     environmentId: string | null;
     projectId: string | null;
+    /**
+     * Explicit host selected for a project-backed workspace file. Omitted when
+     * the source is resolved by its environment/thread or the primary host.
+     *
+     * @experimental Audit before relying on this as a stable contract.
+     */
+    experimental_hostId?: string;
 }
 /** Props passed to a `fileOpener` component (rendered as a panel file tab). */
 interface PluginFileOpenerProps {
@@ -529,6 +536,38 @@ interface PluginSettingsSectionRegistration {
     description?: string;
     component: ComponentType<PluginSettingsSectionProps>;
 }
+/**
+ * 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
+ * selecting the tab or delivering the target.
+ */
+interface ExperimentalFixedTabTargetContract<Target extends JsonValue> {
+    validate(value: JsonValue): value is Target;
+}
+/** Stable, owner-scoped reference used by the app-panel controller. */
+type ExperimentalPluginFixedTabReference<Target extends JsonValue = never> = {
+    /** The owning `navPanel` id; validated against the containing registration. */
+    readonly panelId: string;
+    /** Unique within the owning nav panel; letters, digits, `-`, `_`. */
+    readonly id: string;
+} & ([Target] extends [never] ? {
+    /** An untargeted tab cannot be opened with a target. */
+    readonly experimental_target?: never;
+} : {
+    /** Owner validation required before the host delivers a target. */
+    readonly experimental_target: ExperimentalFixedTabTargetContract<Target>;
+});
+/** A fixed tab declared by a plugin nav panel. */
+type ExperimentalPluginFixedTabRegistration<Target extends JsonValue = never> = ExperimentalPluginFixedTabReference<Target> & {
+    title: string;
+    /** Icon hint (BB icon name); unknown names fall back to a generic icon. */
+    icon: string;
+    component: ComponentType<PluginNavPanelProps>;
+    /** `flush` lets the component own padding and scrolling. */
+    layout?: "flush" | "padded";
+};
+/** A fixed tab with either no target or an owner-validated JSON target. */
+type ExperimentalPluginFixedTabDeclaration = ExperimentalPluginFixedTabRegistration | ExperimentalPluginFixedTabRegistration<JsonValue>;
 interface PluginNavPanelRegistration {
     /** Unique within the plugin; letters, digits, `-`, `_`. */
     id: string;
@@ -541,22 +580,14 @@ interface PluginNavPanelRegistration {
     /**
      * Ordered, non-closable tabs shown in this page's host-owned right panel.
      * BB owns selection and persistence and always includes its native Browser
-     * and Terminal tools beside them. Components mount only while their tab is
-     * active and the panel is open, and receive the same `subPath` as the page
-     * component.
+     * and Terminal tools beside them. One tab is active in each visible split
+     * pane, so multiple fixed-tab components can be mounted concurrently. A
+     * component mounts only while its tab is active in a visible pane and the
+     * panel is open, and receives the same `subPath` as the page component.
      *
      * Experimental: see docs/api_to_audit.md.
      */
-    experimental_fixedTabs?: readonly {
-        /** Unique within this nav panel; letters, digits, `-`, `_`. */
-        id: string;
-        title: string;
-        /** Icon hint (BB icon name); unknown names fall back to a generic icon. */
-        icon: string;
-        component: ComponentType<PluginNavPanelProps>;
-        /** `flush` lets the component own padding and scrolling. */
-        layout?: "flush" | "padded";
-    }[];
+    experimental_fixedTabs?: readonly ExperimentalPluginFixedTabDeclaration[];
     /**
      * Optional presentational component rendered at the trailing edge of this
      * panel's sidebar row. It receives no props so it can own a narrow live
@@ -1200,7 +1231,10 @@ interface PluginContentScriptRegistration {
     id: string;
     /**
      * Install behavior into the bb app shell. The host awaits a returned
-     * promise, contains failures, and calls the returned disposer exactly once.
+     * promise, retains the plugin's imported frontend stylesheet for this
+     * generation, contains failures, and calls the returned disposer exactly
+     * once. Styling or decorating existing app-shell DOM belongs here rather
+     * than in an always-on frontend stylesheet.
      */
     mount(context: PluginContentScriptContext): void | PluginContentScriptDisposer | Promise<void | PluginContentScriptDisposer>;
 }
@@ -1631,6 +1665,78 @@ interface MarkdownProps {
     content: string;
     className?: string;
 }
+/**
+ * Props for BB's semantic URL link. The host owns ordinary activation while
+ * retaining browser-owned anchor behavior for app routes, modifiers, explicit
+ * targets, copying, and unsupported schemes. New top-level targets preserve
+ * supplied `rel` tokens and receive safe defaults unless `opener` is explicit.
+ * Experimental: see docs/api_to_audit.md.
+ */
+interface ExperimentalUrlLinkProps extends Omit<ComponentPropsWithoutRef<"a">, "href"> {
+    href: string;
+}
+/** A live file whose identity is complete without ambient route context. */
+type ExperimentalLiveFileTarget = {
+    kind: "workspace";
+    environmentId: string;
+    path: string;
+} | {
+    kind: "host";
+    hostId: string;
+    path: string;
+} | {
+    kind: "thread-storage";
+    threadId: string;
+    path: string;
+};
+/** One-based location to reveal after a live file opens. */
+type ExperimentalFileLocation = {
+    kind: "line";
+    line: number;
+    column: number | null;
+} | {
+    kind: "range";
+    startLine: number;
+    endLine: number;
+};
+/** Options shared by BB's preview and preferred-external file intents. */
+interface ExperimentalFileOpenOptions {
+    target: ExperimentalLiveFileTarget;
+    location: ExperimentalFileLocation | null;
+}
+/**
+ * Props for BB's host-rendered semantic file link. Valid targets receive a
+ * scheme-safe anchor href; traversal paths, ill-formed Unicode, and other
+ * malformed runtime targets remain inert.
+ */
+interface ExperimentalFileLinkProps extends Omit<ComponentPropsWithoutRef<"a">, "href" | "target"> {
+    target: ExperimentalLiveFileTarget;
+    location?: ExperimentalFileLocation | null;
+}
+/** The panel surface resolved by the component making the request. */
+type ExperimentalAppPanelSurface = {
+    kind: "current";
+};
+/**
+ * The owning fixed tab's current memory-only target. It survives tab, panel,
+ * and route remounts during the current app session, but is never persisted
+ * across a refresh. Call `clear` when the owner returns to its untargeted state.
+ */
+interface ExperimentalFixedTabTargetState<Target extends JsonValue> {
+    readonly sequence: number;
+    readonly target: Target;
+    clear(): void;
+}
+type ExperimentalOpenFixedTabOptions<Target extends JsonValue> = {
+    surface: ExperimentalAppPanelSurface;
+    tab: ExperimentalPluginFixedTabReference<Target>;
+    /** Omit to select the tab without replacing its current session target. */
+    target?: NoInfer<Target>;
+};
+/** Surface-aware controller for selecting owner-scoped fixed tabs. */
+interface ExperimentalAppPanel {
+    openFixedTab<Target extends JsonValue = never>(options: ExperimentalOpenFixedTabOptions<Target>): boolean;
+}
 /** Current app selection, derived from the route. */
 interface BbContext {
     projectId: string | null;
@@ -1665,6 +1771,16 @@ interface BbNavigate {
      * the action is unavailable.
      */
     openThreadPanel(options: PluginTargetedPanelActionOpenOptions): boolean;
+    /**
+     * Open an HTTP(S) URL using this client's BB browser preference. Returns
+     * false for schemes the host does not own. Experimental: see
+     * docs/api_to_audit.md.
+     */
+    experimental_openUrl(url: string): boolean;
+    /** Open a live file in this surface's shared BB preview panel. */
+    experimental_openFilePreview(options: ExperimentalFileOpenOptions): boolean;
+    /** Open a live file in this client's preferred external file target. */
+    experimental_openFileExternally(options: ExperimentalFileOpenOptions): boolean;
 }
 /**
  * Everything `@get-bb/plugin-sdk/app` resolves to at runtime. The BB app builds
@@ -1685,6 +1801,10 @@ interface PluginSdkApp {
     useSettings(): PluginSettingsState;
     useBbContext(): BbContext;
     useBbNavigate(): BbNavigate;
+    /** Select one of this plugin's eligible fixed tabs on the current surface. */
+    experimental_useAppPanel(): ExperimentalAppPanel;
+    /** Read or clear the owning tab's validated, session-scoped target. */
+    experimental_useFixedTabTarget<Target extends JsonValue>(tab: ExperimentalPluginFixedTabReference<Target>): ExperimentalFixedTabTargetState<Target> | null;
     useComposer(): PluginComposerApi;
     /**
      * The sidebar's live thread view (see {@link PluginSidebarThreadsState}).
@@ -1735,6 +1855,13 @@ interface PluginSdkApp {
      * {@link MarkdownProps}).
      */
     Markdown: ComponentType<MarkdownProps>;
+    /**
+     * A real anchor whose ordinary HTTP(S) activation uses BB's URL preference.
+     * Experimental: see docs/api_to_audit.md.
+     */
+    experimental_UrlLink: ComponentType<ExperimentalUrlLinkProps>;
+    /** Host-rendered live-file link backed by the shared navigation controller. */
+    experimental_FileLink: ComponentType<ExperimentalFileLinkProps>;
     /**
      * The host-owned new-thread compose surface (see
      * {@link NewThreadComposerProps}). Experimental: see
@@ -1762,6 +1889,8 @@ interface PluginSdkApp {
 declare const definePluginApp: (setup: PluginAppSetup) => PluginAppDefinition;
 declare const ThreadChat: react.ComponentType<ThreadChatProps>;
 declare const Markdown: react.ComponentType<MarkdownProps>;
+declare const experimental_FileLink: react.ComponentType<ExperimentalFileLinkProps>;
+declare const experimental_UrlLink: react.ComponentType<ExperimentalUrlLinkProps>;
 declare const experimental_NewThreadComposer: react.ComponentType<NewThreadComposerProps>;
 declare const experimental_SourceCode: react.ComponentType<SourceCodeProps>;
 declare const experimental_Diff: react.ComponentType<DiffProps>;
@@ -1771,6 +1900,8 @@ declare const useRealtimeConnectionState: () => PluginRealtimeConnectionState;
 declare const useSettings: () => PluginSettingsState;
 declare const useBbContext: () => BbContext;
 declare const useBbNavigate: () => BbNavigate;
+declare const experimental_useAppPanel: () => ExperimentalAppPanel;
+declare const experimental_useFixedTabTarget: <Target extends JsonValue>(tab: ExperimentalPluginFixedTabReference<Target>) => ExperimentalFixedTabTargetState<Target> | null;
 declare const useComposer: () => PluginComposerApi;
 declare const useComposerView: () => ComposerView;
 declare const experimental_useSidebarThreads: () => PluginSidebarThreadsState;
@@ -1778,5 +1909,5 @@ declare const experimental_useSidebarThreadActions: () => PluginSidebarThreadAct
 declare const experimental_useSidebarThreadPullRequest: (threadId: string) => PluginSidebarThreadPullRequestState;
 declare const experimental_useSidebarThreadSplit: (threadId: string) => PluginSidebarThreadSplit;
 
-export { Markdown, ThreadChat, definePluginApp, experimental_Diff, experimental_NewThreadComposer, experimental_SourceCode, 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, 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_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 };

package/bundled-types/bb-plugin-sdk-internal-file-navigation-validation.d.ts

@@ -0,0 +1,42 @@
+// Portable type declarations for `@get-bb/plugin-sdk`. Unpublished BB
+// workspace contracts are flattened; public subpaths may reuse the
+// package root without requiring any other @bb/* package.
+//
+// Confused by the API, or need a symbol that isn't here? Clone the BB repo
+// and read the real source: https://github.com/get-bb/bb
+
+/** A live file whose identity is complete without ambient route context. */
+type ExperimentalLiveFileTarget = {
+    kind: "workspace";
+    environmentId: string;
+    path: string;
+} | {
+    kind: "host";
+    hostId: string;
+    path: string;
+} | {
+    kind: "thread-storage";
+    threadId: string;
+    path: string;
+};
+/** One-based location to reveal after a live file opens. */
+type ExperimentalFileLocation = {
+    kind: "line";
+    line: number;
+    column: number | null;
+} | {
+    kind: "range";
+    startLine: number;
+    endLine: number;
+};
+/** Options shared by BB's preview and preferred-external file intents. */
+interface ExperimentalFileOpenOptions {
+    target: ExperimentalLiveFileTarget;
+    location: ExperimentalFileLocation | null;
+}
+
+declare function normalizeExperimentalLiveFileTarget(value: unknown): ExperimentalLiveFileTarget | null;
+declare function normalizeExperimentalFileLocation(value: unknown): ExperimentalFileLocation | null | undefined;
+declare function normalizeExperimentalFileOpenOptions(value: unknown): ExperimentalFileOpenOptions | null;
+
+export { normalizeExperimentalFileLocation, normalizeExperimentalFileOpenOptions, normalizeExperimentalLiveFileTarget };

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

@@ -35,6 +35,16 @@ declare const RESERVED_BB_CLI_COMMANDS: readonly string[];
 declare const PROVIDER_FORK_VALUES: readonly ["none", "tip", "checkpoint"];
 type ProviderFork = (typeof PROVIDER_FORK_VALUES)[number];
 
+/**
+ * A value that survives a JSON round trip without coercion or data loss.
+ *
+ * Host boundaries still validate values at runtime because TypeScript cannot
+ * exclude non-finite numbers and plugin bundles can bypass static types.
+ */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+
 /**
  * The validator-neutral subset of Standard Schema v1 used by plugin RPC.
  * Zod 4 schemas implement this interface directly; other validators can do
@@ -139,10 +149,23 @@ type PluginProviderComposerAction = "goal" | "plan";
  * live session (picker rendering, route gating, cross-plugin tool
  * composition — including with the host offline). Every boolean is a
  * provider-native fact — the provider implements the feature; the flag only
- * tells external consumers it exists. Everything else is a handshake fact the
- * bridge reports at `initialize`, where it cannot drift from behavior.
+ * tells external consumers it exists. Session-behavior facts remain handshake
+ * capabilities reported by the running bridge. Sessionless maintenance
+ * methods are declared here so callers can decide whether to probe without
+ * starting the bridge first.
  */
 interface PluginProviderCapabilities {
+    /** The provider bridge implements the sessionless `provider/health`
+     * request. This is host-local readiness, not a network health check. */
+    experimental_providerHealth: boolean;
+    /** The provider exposes subscription usage through the sessionless
+     * `provider/usage` request. False means callers skip the request and usage
+     * settings omit the provider. A shared bridge that declares true may still
+     * report usage unavailable for one provider id or return no windows. */
+    experimental_providerUsage: boolean;
+    /** The provider bridge implements `provider/installation/status` and
+     * `provider/installation/run` for host-local installation management. */
+    experimental_providerInstallation: boolean;
     /** The provider accepts a fast/priority service-tier choice — shows the
      * service-tier toggle in the picker. */
     supportsServiceTier: boolean;
@@ -186,11 +209,11 @@ interface PluginProviderCapabilities {
  * refused. Registrations are replaced wholesale on plugin reload, like every
  * other plugin surface.
  *
- * A declaration is metadata only. The implementation is the plugin's own
- * provider bridge, named by `bb.providerBridge` in the manifest and built into
- * the artifact BB ships to hosts — declaring a provider without one is
- * refused, because the picker entry would exist and no turn on it could ever
- * run.
+ * A declaration owns the provider's static metadata and bridge options. The
+ * executable implementation is the plugin's own provider bridge, named by
+ * `bb.providerBridge` in the manifest and built into the artifact BB ships to
+ * hosts — declaring a provider without one is refused, because the picker
+ * entry would exist and no turn on it could ever run.
  */
 interface PluginProviderDeclaration {
     /** Stable provider id: 2–64 characters of lowercase letters, digits, and
@@ -206,6 +229,19 @@ interface PluginProviderDeclaration {
      * — no leading "/", no ".." segments, no backslashes.
      */
     icon?: string;
+    /**
+     * Provider-owned static options passed opaquely to this plugin's bridge on
+     * every sessionless and session request. Core validates that the value is
+     * JSON, but does not interpret its keys. This is intended for immutable
+     * launch metadata shared by every host (for example an ACP command spec),
+     * not user or machine configuration.
+     */
+    experimental_bridgeOptions?: Readonly<Record<string, JsonValue>>;
+    /**
+     * Whether the provider is always listed or only listed on hosts where its
+     * bridge reports it installed. Defaults to `"always"`.
+     */
+    experimental_visibility?: "always" | "installed";
     /** Pre-session capability facts (see the declaration tests on
      * {@link PluginProviderCapabilities}). */
     capabilities: PluginProviderCapabilities;
@@ -237,6 +273,7 @@ declare const PLUGIN_AGENT_DYNAMIC_INSTRUCTIONS_MAX_CHARS = 4096;
 declare const PLUGIN_AGENT_TOOL_PARAMETERS_MAX_BYTES: number;
 declare const MENTION_PROVIDER_ID_PATTERN: RegExp;
 declare const PROVIDER_ID_PATTERN: RegExp;
+declare const PLUGIN_PROVIDER_BRIDGE_OPTIONS_MAX_BYTES: number;
 declare const SETTING_KEY_PATTERN: RegExp;
 /**
  * Validate freeform descriptors from plugin code and merge them into the
@@ -290,4 +327,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_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, enforcePluginCliOutputLimit, isPluginMentionTrigger, isStandardSchema, isZodSchemaLike, normalizeMentionProviderTriggers, readRpcMethodContract, registerSettingDescriptors, summarizeParseIssues, validatePluginProviderDeclaration, validateSettingsUpdate };