@get-bb/plugin-sdk 0.4.55 → 0.4.84

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

@@ -5,7 +5,7 @@
 // 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
 
-import { ExperimentalSidebarFooterActionContext, ExperimentalSidebarFooterItemRegistration, PluginHomepageSectionRegistration, PluginSettingsSectionRegistration, ExperimentalAppOverlayRegistration, PluginNavPanelRegistration, PluginThreadPanelActionRegistration, PluginNewThreadPanelActionRegistration, ComposerCustomization, PluginPendingInteractionRegistration, PluginSidebarFooterActionRegistration, ExperimentalSidebarNavigationRegistration, PluginThreadListRegistration, PluginThreadHeaderActionRegistration, PluginFileOpenerRegistration, PluginSourceCodeRendererRegistration, PluginDiffRendererRegistration, PluginMessageDirectiveRegistration, PluginMessageActionRegistration, PluginCommandPaletteActionRegistration, PluginProviderIconRegistration, PluginTimelineRendererRegistration, PluginEnvironmentProviderInputsRegistration, PluginContentScriptRegistration, PluginAppDefinition } from '@get-bb/plugin-sdk';
+import { ExperimentalSidebarFooterActionContext, ExperimentalSidebarFooterItemRegistration, PluginHomepageSectionRegistration, PluginSettingsSectionRegistration, ExperimentalAppOverlayRegistration, PluginNavPanelRegistration, PluginThreadPanelActionRegistration, PluginNewThreadPanelActionRegistration, ComposerCustomization, PluginPendingInteractionRegistration, PluginSidebarFooterActionRegistration, ExperimentalSidebarNavigationRegistration, PluginThreadListRegistration, PluginThreadHeaderActionRegistration, PluginFileOpenerRegistration, PluginSourceCodeRendererRegistration, PluginDiffRendererRegistration, PluginMessageDirectiveRegistration, PluginMessageActionRegistration, PluginCommandPaletteActionRegistration, PluginProviderIconRegistration, ExperimentalIconRegistration, PluginTimelineRendererRegistration, PluginEnvironmentProviderInputsRegistration, PluginMachineProviderInputsRegistration, PluginContentScriptRegistration, PluginAppDefinition } from '@get-bb/plugin-sdk';
 
 type ExperimentalSidebarFooterCommandKind = "close" | "open" | "toggle";
 interface ExperimentalSidebarFooterRuntimeSnapshot {
@@ -36,6 +36,9 @@ interface CollectedCompatibilitySidebarFooterItem {
 }
 type CollectedSidebarFooterItem = CollectedCompatibilitySidebarFooterItem | CollectedManagedSidebarFooterItem;
 declare function adaptSidebarFooterAction(registration: PluginSidebarFooterActionRegistration): CollectedCompatibilitySidebarFooterItem;
+type CollectedPluginProviderIconRegistration = Omit<PluginProviderIconRegistration, "providerKind"> & {
+    providerKind: PluginProviderIconRegistration["providerKind"] | "all";
+};
 /** Validated registrations produced by one plugin app setup execution. */
 interface CollectedPluginAppRegistrations {
     homepageSections: PluginHomepageSectionRegistration[];
@@ -57,9 +60,11 @@ interface CollectedPluginAppRegistrations {
     messageDirectives: PluginMessageDirectiveRegistration[];
     messageActions: PluginMessageActionRegistration[];
     commandPaletteActions: PluginCommandPaletteActionRegistration[];
-    providerIcons: PluginProviderIconRegistration[];
+    providerIcons: CollectedPluginProviderIconRegistration[];
+    icons: ExperimentalIconRegistration[];
     timelineRenderers: PluginTimelineRendererRegistration[];
     environmentProviderInputs: PluginEnvironmentProviderInputsRegistration[];
+    machineProviderInputs: PluginMachineProviderInputsRegistration[];
     contentScripts: PluginContentScriptRegistration[];
 }
 declare function getCollectedSidebarFooterItems(registrations: object): readonly CollectedSidebarFooterItem[] | null;
@@ -72,4 +77,4 @@ declare function getCollectedSidebarFooterItems(registrations: object): readonly
 declare function collectPluginAppRegistrations(definition: PluginAppDefinition, onComposerCustomizationRejected?: (reason: string) => void): CollectedPluginAppRegistrations;
 
 export { adaptSidebarFooterAction, collectPluginAppRegistrations, getCollectedSidebarFooterItems };
-export type { CollectedCompatibilitySidebarFooterItem, CollectedExperimentalSidebarFooterItem, CollectedManagedSidebarFooterItem, CollectedPluginAppRegistrations, CollectedSidebarFooterItem, ExperimentalSidebarFooterCommandKind, ExperimentalSidebarFooterItemRuntime, ExperimentalSidebarFooterRuntimeSnapshot };
+export type { CollectedCompatibilitySidebarFooterItem, CollectedExperimentalSidebarFooterItem, CollectedManagedSidebarFooterItem, CollectedPluginAppRegistrations, CollectedPluginProviderIconRegistration, CollectedSidebarFooterItem, ExperimentalSidebarFooterCommandKind, ExperimentalSidebarFooterItemRuntime, ExperimentalSidebarFooterRuntimeSnapshot };

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

@@ -0,0 +1,84 @@
+// 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
+
+import { StandardSchemaV1, StandardSchemaV1InferOutput, JsonValue, PluginMachineValidateDecision } from '@get-bb/plugin-sdk';
+
+type PluginMachineProviderResource = Exclude<JsonValue, null>;
+type PluginMachineProviderInputsSchema = StandardSchemaV1 | undefined;
+type InputsValue<S> = S extends StandardSchemaV1 ? StandardSchemaV1InferOutput<S> : null;
+interface PluginMachineProviderProgress {
+    step(text: string): void;
+    log(text: string): void;
+}
+type PluginMachineProviderAvailability = {
+    status: "available";
+} | {
+    status: "setup-required";
+    message: string;
+} | {
+    status: "unavailable";
+    message: string;
+};
+type PluginMachineProviderValidateContext<S extends PluginMachineProviderInputsSchema = PluginMachineProviderInputsSchema> = {
+    inputs: InputsValue<S>;
+};
+interface PluginMachineProviderLifecycleContext {
+    checkpoint(resource: PluginMachineProviderResource): Promise<void>;
+    report: PluginMachineProviderProgress;
+    signal: AbortSignal;
+}
+type PluginMachineProviderCreateContext<S extends PluginMachineProviderInputsSchema = PluginMachineProviderInputsSchema> = PluginMachineProviderValidateContext<S> & PluginMachineProviderLifecycleContext & {
+    key: string;
+    attempt: number;
+};
+type PluginMachineProviderCreateResult = {
+    status: "created";
+    name: string;
+    resource: PluginMachineProviderResource;
+} | {
+    status: "failed";
+    message: string;
+};
+type PluginMachineProviderResourceLifecycleContext = PluginMachineProviderLifecycleContext & {
+    hostId: string;
+    resource: PluginMachineProviderResource;
+};
+type PluginMachineProviderRemoveContext = Omit<PluginMachineProviderResourceLifecycleContext, "checkpoint">;
+interface PluginMachineProviderResourceResult {
+    resource: PluginMachineProviderResource;
+}
+type PluginMachineProviderRemoveResult = {
+    status: "removed";
+} | {
+    status: "failed";
+    message: string;
+};
+interface PluginMachineProviderDefinition<S extends PluginMachineProviderInputsSchema = PluginMachineProviderInputsSchema> {
+    id: string;
+    displayName: string;
+    /** One line telling a user what choosing this provider gets them, shown wherever a machine is added. */
+    description: string;
+    /** Provider glyph, declared icon, or plugin-relative icon path. */
+    icon: string;
+    ephemeral?: boolean;
+    /** Persisted and readable by every plugin. Store secret references, never secrets. */
+    inputs?: S;
+    availability?(): PluginMachineProviderAvailability | Promise<PluginMachineProviderAvailability>;
+    validate?(context: PluginMachineProviderValidateContext<S>): PluginMachineValidateDecision | Promise<PluginMachineValidateDecision>;
+    create(context: PluginMachineProviderCreateContext<S>): Promise<PluginMachineProviderCreateResult>;
+    /** Reconcile and remove an uncertain allocation by durable key without creating or bootstrapping. Return failed while allocation intent remains unresolved. */
+    reconcileCleanup(context: {
+        key: string;
+        report: PluginMachineProviderProgress;
+        signal: AbortSignal;
+    }): Promise<PluginMachineProviderRemoveResult>;
+    suspend?(context: PluginMachineProviderResourceLifecycleContext): Promise<PluginMachineProviderResourceResult>;
+    resume?(context: PluginMachineProviderResourceLifecycleContext): Promise<PluginMachineProviderResourceResult>;
+    remove(context: PluginMachineProviderRemoveContext): Promise<PluginMachineProviderRemoveResult>;
+}
+
+export type { PluginMachineProviderAvailability, PluginMachineProviderCreateContext, PluginMachineProviderCreateResult, PluginMachineProviderDefinition, PluginMachineProviderInputsSchema, PluginMachineProviderLifecycleContext, PluginMachineProviderProgress, PluginMachineProviderRemoveResult, PluginMachineProviderResource, PluginMachineProviderResourceResult, PluginMachineProviderValidateContext };

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

@@ -3252,6 +3252,11 @@ declare const threadEventSchema: z.ZodPipe<z.ZodUnknown, z.ZodUnion<readonly [z.
         reason: z.ZodOptional<z.ZodString>;
         source: z.ZodUnion<readonly [z.ZodLiteral<"shell">, z.ZodObject<{
             plugin: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            core: z.ZodEnum<{
+                "machine-environment": "machine-environment";
+                "machine-git": "machine-git";
+            }>;
         }, z.core.$strict>]>;
         value: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
             masked: z.ZodLiteral<true>;

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

@@ -7,7 +7,7 @@
 
 import { ReactNode, ComponentType } from 'react';
 import { RenderResult } from '@testing-library/react';
-import { ExperimentalSidebarFooterItemRegistration, PluginHomepageSectionRegistration, PluginSettingsSectionRegistration, ExperimentalAppOverlayRegistration, PluginNavPanelRegistration, PluginThreadPanelActionRegistration, PluginNewThreadPanelActionRegistration, ComposerCustomization, PluginPendingInteractionRegistration, PluginSidebarFooterActionRegistration, ExperimentalSidebarNavigationRegistration, PluginThreadListRegistration, PluginThreadHeaderActionRegistration, PluginFileOpenerRegistration, PluginSourceCodeRendererRegistration, PluginDiffRendererRegistration, PluginMessageDirectiveRegistration, PluginMessageActionRegistration, PluginProviderIconRegistration, PluginTimelineRendererRegistration, PluginEnvironmentProviderInputsRegistration, PluginContentScriptRegistration, PluginComposerScope, PluginComposerTextEffect, PluginComposerMention, PluginComposerThreadRowStatus, ExperimentalOpenFixedTabOptions, JsonValue, BbNavigate, ExperimentalFileOpenOptions, PluginAppDefinition, PluginRpcContract, StandardSchemaV1InferInput, PluginRpcResult, PluginRealtimeConnectionState, PluginSidebarThreadsState, PluginProvidersState, PluginCodeThemeState, BranchesState, CheckoutState, PluginSidebarPullRequest, PluginSidebarThreadActions } from '@get-bb/plugin-sdk';
+import { ExperimentalSidebarFooterItemRegistration, PluginProviderIconRegistration, PluginHomepageSectionRegistration, PluginSettingsSectionRegistration, ExperimentalAppOverlayRegistration, PluginNavPanelRegistration, PluginThreadPanelActionRegistration, PluginNewThreadPanelActionRegistration, ComposerCustomization, PluginPendingInteractionRegistration, PluginSidebarFooterActionRegistration, ExperimentalSidebarNavigationRegistration, PluginThreadListRegistration, PluginThreadHeaderActionRegistration, PluginFileOpenerRegistration, PluginSourceCodeRendererRegistration, PluginDiffRendererRegistration, PluginMessageDirectiveRegistration, PluginMessageActionRegistration, ExperimentalIconRegistration, PluginTimelineRendererRegistration, PluginEnvironmentProviderInputsRegistration, PluginMachineProviderInputsRegistration, PluginContentScriptRegistration, PluginComposerScope, PluginComposerTextEffect, PluginComposerMention, PluginComposerThreadRowStatus, ExperimentalOpenFixedTabOptions, JsonValue, BbNavigate, ExperimentalFileOpenOptions, PluginAppDefinition, PluginRpcContract, StandardSchemaV1InferInput, PluginRpcResult, PluginRealtimeConnectionState, PluginSidebarThreadsState, PluginProvidersState, PluginCodeThemeState, BranchesState, CheckoutState, PluginSidebarPullRequest, PluginSidebarThreadActions } from '@get-bb/plugin-sdk';
 
 type ExperimentalSidebarFooterCommandKind = "close" | "open" | "toggle";
 interface ExperimentalSidebarFooterRuntimeSnapshot {
@@ -24,6 +24,9 @@ interface ExperimentalSidebarFooterItemRuntime {
 type CollectedExperimentalSidebarFooterItem = ExperimentalSidebarFooterItemRegistration & {
     runtime: ExperimentalSidebarFooterItemRuntime;
 };
+type CollectedPluginProviderIconRegistration = Omit<PluginProviderIconRegistration, "providerKind"> & {
+    providerKind: PluginProviderIconRegistration["providerKind"] | "all";
+};
 
 /**
  * `@get-bb/plugin-sdk/testing/app` — the frontend plugin test harness. Tests a
@@ -150,9 +153,11 @@ interface CapturedPluginApp {
     diffRenderers: PluginDiffRendererRegistration[];
     messageDirectives: PluginMessageDirectiveRegistration[];
     messageActions: PluginMessageActionRegistration[];
-    providerIcons: PluginProviderIconRegistration[];
+    providerIcons: CollectedPluginProviderIconRegistration[];
+    icons: ExperimentalIconRegistration[];
     timelineRenderers: PluginTimelineRendererRegistration[];
     environmentProviderInputs: PluginEnvironmentProviderInputsRegistration[];
+    machineProviderInputs: PluginMachineProviderInputsRegistration[];
     contentScripts: PluginContentScriptRegistration[];
 }
 type PluginAppModule = {

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

@@ -5,8 +5,82 @@
 // 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
 
+import { StandardSchemaV1 as StandardSchemaV1$1, StandardSchemaV1InferOutput, PluginMachineValidateDecision, JsonValue as JsonValue$2, PluginEnvironmentProviderRequirements as PluginEnvironmentProviderRequirements$1, PluginEnvironmentValidateDecision, BbPluginApi, PluginSettingValue as PluginSettingValue$1, PluginSharedPortTunnelIdentity, PluginAgentToolPresentation, PluginAgentToolContext, PluginAgentToolResult, PluginCliCommandInfo, PluginCliContext, PluginCliResult, PluginHttpAuthMode, PluginHttpHandler, PluginMentionTrigger, PluginMentionSearchContext, PluginMentionItem, PluginCliExecutionResult, PluginThreadEventName, PluginThreadEventPayloads, PluginAgentConfigurationContext, ExperimentalPluginProviderEnvContext, ExperimentalPluginProviderEnvEntry, ExperimentalPluginProviderEnvHealthContext, ExperimentalPluginProviderEnvHealth, PluginSettingDescriptors, ExperimentalPluginWebSocketHandler, PluginAgentConfiguration, PluginHookName, PluginHookHandler, PluginAiServiceDeclaration, PluginInteractionRequest, MessageDispatchHookContext } from '@get-bb/plugin-sdk';
 import { z } from 'zod';
-import { StandardSchemaV1 as StandardSchemaV1$1, PluginEnvironmentProviderRequirements as PluginEnvironmentProviderRequirements$1, StandardSchemaV1InferOutput, PluginEnvironmentValidateDecision, JsonValue as JsonValue$2, BbPluginApi, PluginSettingValue as PluginSettingValue$1, PluginSharedPortTunnelIdentity, PluginAgentToolPresentation, PluginAgentToolContext, PluginAgentToolResult, PluginCliCommandInfo, PluginCliContext, PluginCliResult, PluginHttpAuthMode, PluginHttpHandler, PluginMentionTrigger, PluginMentionSearchContext, PluginMentionItem, PluginCliExecutionResult, PluginThreadEventName, PluginThreadEventPayloads, PluginAgentConfigurationContext, ExperimentalPluginProviderEnvContext, ExperimentalPluginProviderEnvEntry, ExperimentalPluginProviderEnvHealthContext, ExperimentalPluginProviderEnvHealth, PluginSettingDescriptors, ExperimentalPluginWebSocketHandler, PluginAgentConfiguration, PluginHookName, PluginHookHandler, PluginAiServiceDeclaration, PluginInteractionRequest, MessageDispatchHookContext } from '@get-bb/plugin-sdk';
+
+type PluginMachineProviderResource = Exclude<JsonValue$2, null>;
+type PluginMachineProviderInputsSchema = StandardSchemaV1$1 | undefined;
+type InputsValue$1<S> = S extends StandardSchemaV1$1 ? StandardSchemaV1InferOutput<S> : null;
+interface PluginMachineProviderProgress {
+    step(text: string): void;
+    log(text: string): void;
+}
+type PluginMachineProviderAvailability = {
+    status: "available";
+} | {
+    status: "setup-required";
+    message: string;
+} | {
+    status: "unavailable";
+    message: string;
+};
+type PluginMachineProviderValidateContext<S extends PluginMachineProviderInputsSchema = PluginMachineProviderInputsSchema> = {
+    inputs: InputsValue$1<S>;
+};
+interface PluginMachineProviderLifecycleContext {
+    checkpoint(resource: PluginMachineProviderResource): Promise<void>;
+    report: PluginMachineProviderProgress;
+    signal: AbortSignal;
+}
+type PluginMachineProviderCreateContext<S extends PluginMachineProviderInputsSchema = PluginMachineProviderInputsSchema> = PluginMachineProviderValidateContext<S> & PluginMachineProviderLifecycleContext & {
+    key: string;
+    attempt: number;
+};
+type PluginMachineProviderCreateResult = {
+    status: "created";
+    name: string;
+    resource: PluginMachineProviderResource;
+} | {
+    status: "failed";
+    message: string;
+};
+type PluginMachineProviderResourceLifecycleContext = PluginMachineProviderLifecycleContext & {
+    hostId: string;
+    resource: PluginMachineProviderResource;
+};
+type PluginMachineProviderRemoveContext = Omit<PluginMachineProviderResourceLifecycleContext, "checkpoint">;
+interface PluginMachineProviderResourceResult {
+    resource: PluginMachineProviderResource;
+}
+type PluginMachineProviderRemoveResult = {
+    status: "removed";
+} | {
+    status: "failed";
+    message: string;
+};
+interface PluginMachineProviderDefinition<S extends PluginMachineProviderInputsSchema = PluginMachineProviderInputsSchema> {
+    id: string;
+    displayName: string;
+    /** One line telling a user what choosing this provider gets them, shown wherever a machine is added. */
+    description: string;
+    /** Provider glyph, declared icon, or plugin-relative icon path. */
+    icon: string;
+    ephemeral?: boolean;
+    /** Persisted and readable by every plugin. Store secret references, never secrets. */
+    inputs?: S;
+    availability?(): PluginMachineProviderAvailability | Promise<PluginMachineProviderAvailability>;
+    validate?(context: PluginMachineProviderValidateContext<S>): PluginMachineValidateDecision | Promise<PluginMachineValidateDecision>;
+    create(context: PluginMachineProviderCreateContext<S>): Promise<PluginMachineProviderCreateResult>;
+    /** Reconcile and remove an uncertain allocation by durable key without creating or bootstrapping. Return failed while allocation intent remains unresolved. */
+    reconcileCleanup(context: {
+        key: string;
+        report: PluginMachineProviderProgress;
+        signal: AbortSignal;
+    }): Promise<PluginMachineProviderRemoveResult>;
+    suspend?(context: PluginMachineProviderResourceLifecycleContext): Promise<PluginMachineProviderResourceResult>;
+    resume?(context: PluginMachineProviderResourceLifecycleContext): Promise<PluginMachineProviderResourceResult>;
+    remove(context: PluginMachineProviderRemoveContext): Promise<PluginMachineProviderRemoveResult>;
+}
 
 /** Input-form entry: a path, or a path with options. */
 declare const providerNativeRootInputSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
@@ -74,10 +148,14 @@ declare const environmentSchema: z.ZodObject<{
     environmentProviderInstanceKey: z.ZodNullable<z.ZodString>;
     environmentProviderSelection: z.ZodNullable<z.ZodObject<{
         inputs: z.ZodNullable<z.ZodType<JsonValue$1, unknown, z.core.$ZodTypeInternals<JsonValue$1, unknown>>>;
-        machine: z.ZodObject<{
+        machine: z.ZodDiscriminatedUnion<[z.ZodObject<{
             hostId: z.ZodString;
             type: z.ZodLiteral<"existing">;
-        }, z.core.$strip>;
+        }, z.core.$strip>, z.ZodObject<{
+            inputs: z.ZodNullable<z.ZodType<JsonValue$1, unknown, z.core.$ZodTypeInternals<JsonValue$1, unknown>>>;
+            machineProviderId: z.ZodString;
+            type: z.ZodLiteral<"new">;
+        }, z.core.$strip>], "type">;
     }, z.core.$strip>>;
     hostId: z.ZodString;
     id: z.ZodString;
@@ -127,6 +205,29 @@ declare const hostSchema: z.ZodObject<{
     id: z.ZodString;
     lastRejectedProtocolVersion: z.ZodNullable<z.ZodNumber>;
     lastSeenAt: z.ZodNullable<z.ZodNumber>;
+    lifecycle: z.ZodObject<{
+        message: z.ZodNullable<z.ZodString>;
+        pendingLog: z.ZodString;
+        phase: z.ZodEnum<{
+            active: "active";
+            creating: "creating";
+            destroyed: "destroyed";
+            removing: "removing";
+            resuming: "resuming";
+            suspended: "suspended";
+            suspending: "suspending";
+        }>;
+        suspendedAt: z.ZodNullable<z.ZodNumber>;
+        teardown: z.ZodNullable<z.ZodObject<{
+            attempt: z.ZodNumber;
+            status: z.ZodEnum<{
+                failed: "failed";
+                removed: "removed";
+                running: "running";
+            }>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    machineProviderId: z.ZodNullable<z.ZodString>;
     maxPermissionMode: z.ZodEnum<{
         "accept-edits": "accept-edits";
         auto: "auto";
@@ -138,6 +239,7 @@ declare const hostSchema: z.ZodObject<{
         disconnected: "disconnected";
     }>;
     type: z.ZodEnum<{
+        ephemeral: "ephemeral";
         persistent: "persistent";
     }>;
     updatedAt: z.ZodNumber;
@@ -221,8 +323,10 @@ type Checkout<R> = R extends {
     gitCheckout: true;
 } ? {
     path: string;
+    experimental_ownsPath: boolean;
 } : {
     path: string;
+    experimental_ownsPath: boolean;
 } | null;
 type InputsValue<S> = S extends StandardSchemaV1$1 ? StandardSchemaV1InferOutput<S> : null;
 /** Attempt-scoped updates; core persists each update before this call returns. */
@@ -306,8 +410,10 @@ interface PluginEnvironmentProviderPolicy {
 interface PluginEnvironmentProviderDefinition<R extends PluginEnvironmentProviderRequirements$1 = PluginEnvironmentProviderRequirements$1, S extends PluginEnvironmentProviderInputsSchema = PluginEnvironmentProviderInputsSchema> {
     id: string;
     displayName: string;
+    /** Short explanation shown in environment choices. */
+    description: string;
     /** Host glyph, plugin-relative icon path, or this plugin’s declared namespaced icon. */
-    icon?: string;
+    icon: string;
     requires?: R;
     inputs?: S;
     policy?: Partial<PluginEnvironmentProviderPolicy>;
@@ -318,6 +424,30 @@ interface PluginEnvironmentProviderDefinition<R extends PluginEnvironmentProvide
     remove(context: PluginEnvironmentProviderRemoveContext): Promise<PluginEnvironmentProviderRemoveResult>;
 }
 
+interface MachineExecutorRequest {
+    command: string[];
+    timeoutMs: number;
+    signal: AbortSignal;
+    stdin: string;
+    onOutput: (chunk: string) => void;
+}
+interface MachineExecutor {
+    exec(request: MachineExecutorRequest): Promise<{
+        exitCode: number;
+    }>;
+}
+interface MachineBootstrapRequest {
+    key: string;
+    executor: MachineExecutor;
+    report: PluginMachineProviderProgress;
+    signal: AbortSignal;
+}
+interface MachineBootstrapApi {
+    bootstrap(request: MachineBootstrapRequest): Promise<{
+        hostId: string;
+    }>;
+}
+
 /**
  * A value that survives a JSON round trip without coercion or data loss.
  *
@@ -389,6 +519,36 @@ interface PluginEnvironmentProviderRequirements {
  * supplied pathKey. Provider ids are unique across running plugins.
  */
 type PluginEnvironmentProviderDeclaration<Requires extends PluginEnvironmentProviderRequirements = PluginEnvironmentProviderRequirements, Inputs extends PluginEnvironmentProviderInputsSchema = PluginEnvironmentProviderInputsSchema> = PluginEnvironmentProviderDefinition<Requires, Inputs>;
+type PluginMachineProviderDeclaration<Inputs extends PluginMachineProviderInputsSchema = PluginMachineProviderInputsSchema> = PluginMachineProviderDefinition<Inputs>;
+interface ServerAccessGrant {
+    id: string;
+    serverUrl: string;
+    headers?: Record<string, string>;
+}
+interface ServerAccessProviderDeclaration {
+    id: string;
+    displayName: string;
+    description: string;
+    availability(): (PluginMachineProviderAvailability & {
+        serverUrl?: string;
+    }) | Promise<PluginMachineProviderAvailability & {
+        serverUrl?: string;
+    }>;
+    acquire(context: {
+        key: string;
+        hostId: string;
+        signal: AbortSignal;
+    }): Promise<ServerAccessGrant | {
+        status: "failed";
+        message: string;
+    }>;
+    release(context: {
+        key: string;
+        hostId: string;
+        /** Null when acquisition was interrupted before a grant was returned. Reconcile using key and hostId. */
+        grantId: string | null;
+    }): Promise<void>;
+}
 /**
  * Permission modes a provider can run a session in — BB's own permission
  * vocabulary, ordered least ("accept-edits") to most ("full") privileged.
@@ -761,9 +921,19 @@ declare const ENVIRONMENT_PROVIDER_REQUIREMENT_NAMES: readonly ["projectCheckout
 type NormalizedPluginEnvironmentProviderRequirements = {
     [K in (typeof ENVIRONMENT_PROVIDER_REQUIREMENT_NAMES)[number]]: boolean;
 };
+declare const environmentCompositionSchema: z.ZodObject<{
+    description: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | null, string | undefined>>;
+    displayName: z.ZodString;
+    environmentProviderId: z.ZodString;
+    icon: z.ZodPipe<z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>, z.ZodTransform<string | null, string | undefined>>;
+    id: z.ZodString;
+    machineProviderId: z.ZodString;
+}, z.core.$strict>;
+type NormalizedPluginEnvironmentComposition = z.infer<typeof environmentCompositionSchema>;
 interface NormalizedPluginEnvironmentProvider {
     id: string;
     displayName: string;
+    description: string | null;
     icon: string | null;
     requires: NormalizedPluginEnvironmentProviderRequirements;
     inputs: StandardSchemaV1 | null;
@@ -774,6 +944,22 @@ interface NormalizedPluginEnvironmentProvider {
     remove: PluginEnvironmentProviderDeclaration["remove"];
     policy: PluginEnvironmentProviderPolicy;
 }
+interface NormalizedPluginMachineProvider {
+    id: string;
+    displayName: string;
+    description: string;
+    icon: string;
+    ephemeral: boolean;
+    inputs: StandardSchemaV1 | null;
+    inputsJsonSchema: JsonValue | null;
+    availability: NonNullable<PluginMachineProviderDeclaration["availability"]> | null;
+    validate: NonNullable<PluginMachineProviderDeclaration["validate"]> | null;
+    reconcileCleanup: PluginMachineProviderDeclaration["reconcileCleanup"];
+    create: PluginMachineProviderDeclaration["create"];
+    suspend: NonNullable<PluginMachineProviderDeclaration["suspend"]> | null;
+    resume: NonNullable<PluginMachineProviderDeclaration["resume"]> | null;
+    remove: PluginMachineProviderDeclaration["remove"];
+}
 
 type BbSdk = BbPluginApi["sdk"];
 /**
@@ -955,7 +1141,10 @@ interface FakePluginRegistrations {
     hooks: {
         [K in PluginHookName]: PluginHookHandler<K> | null;
     };
+    environmentCompositions: ReadonlyMap<string, NormalizedPluginEnvironmentComposition>;
     environmentProviders: ReadonlyMap<string, NormalizedPluginEnvironmentProvider>;
+    machineProviders: ReadonlyMap<string, NormalizedPluginMachineProvider>;
+    serverAccessProviders: ReadonlyMap<string, ServerAccessProviderDeclaration>;
     mentionProviders: FakeMentionProviderRecord[];
     /** Live provider registrations from `bb.providers.register`
      * (normalized declarations, registration order; dispose removes). */
@@ -1095,6 +1284,8 @@ interface FakePluginHarness extends FakePluginInspectionState, FakePluginBehavio
     readonly lifecycle: FakePluginLifecycleControls;
 }
 interface CreateFakePluginHostOptions {
+    machineBootstrap?: MachineBootstrapApi;
+    machineResource?: (hostId: string) => Promise<JsonValue$2 | null>;
     /** Defaults to "test-plugin". */
     pluginId?: string;
     /**