@get-bb/plugin-sdk 0.4.56 → 0.4.84

package/README.md

@@ -9,18 +9,6 @@ The authoritative contracts are the exported declarations in
 [`src/app-contract.ts`](src/app-contract.ts). Keep author-facing guidance in
 the built-in `bb-plugin-authoring` skill synchronized with those declarations.
 
-## Environment providers
-
-`bb.experimental_environments.register` lets plugins create and remove thread
-workspaces on enrolled machines. The type-only `./environment-provider` entry
-contains the resource-operation contract. Core owns durable launches,
-cancellation, retries, retirement, and teardown. Selections persist non-secret
-inputs alongside `machine: { type: "existing", hostId }`.
-
-The bundled Project checkout, Worktree, and Personal workspace plugins are the
-reference implementations. See the Plugin Guide for registration, availability,
-validation, lifecycle policy, and app inputs controls.
-
 ## Composer customization
 
 Composer UI extensions register through `app.composer.customize(...)`. A

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

@@ -6,7 +6,7 @@
 // and read the real source: https://github.com/get-bb/bb
 
 import * as react from 'react';
-import { ComponentType, ComponentPropsWithoutRef, ReactNode } from 'react';
+import { ComponentType, ComponentPropsWithoutRef, CSSProperties, ReactNode } from 'react';
 import { z } from 'zod';
 
 /**
@@ -330,10 +330,14 @@ declare const createThreadEnvironmentArgsSchema: z.ZodDiscriminatedUnion<[z.ZodO
 }, z.core.$strip>, z.ZodObject<{
     environmentProviderId: z.ZodString;
     inputs: z.ZodDefault<z.ZodNullable<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>>;
-    machine: z.ZodObject<{
+    machine: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
         hostId: z.ZodString;
         type: z.ZodLiteral<"existing">;
-    }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        inputs: z.ZodDefault<z.ZodNullable<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>>;
+        machineProviderId: z.ZodString;
+        type: z.ZodLiteral<"new">;
+    }, z.core.$strip>], "type">>;
     type: z.ZodLiteral<"provider">;
 }, z.core.$strip>], "type">;
 type CreateThreadEnvironmentArgs = z.infer<typeof createThreadEnvironmentArgsSchema>;
@@ -1529,20 +1533,21 @@ interface PluginCommandPaletteActionRegistration {
     run(context: PluginCommandPaletteActionContext): void | Promise<void>;
 }
 /**
- * Supply the inline React mark bb draws for one agent provider.
+ * Supply an inline React mark for a provider. Agent, machine, and environment
+ * icon renderers select the mark by provider kind and id.
+ * Only surfaces using the provider icon renderer consult this slot. Persistent
+ * machine labels use a laptop glyph directly.
  *
- * A manifest `branding.icon` (or a provider's `logoUrl`) is fetched and drawn
- * through `<img>`, a separate document where `currentColor` resolves to black
- * — invisible on dark themes and unreachable from app CSS. A component is
- * rendered inline, so it inherits the app's theme colors and the host's sizing
- * classes. Register a static color logo as a file and a theme-aware mark here.
+ * Provider logo assets use a currentColor mask. Inline components can also
+ * render multiple colors and inherit the app's theme and sizing classes.
  *
- * The host passes only `className` (sizing plus the provider's color class);
+ * The host passes `className` for sizing; color inherits from its wrapper.
  * the component must render an inline SVG (or other inline markup) and must
- * not fetch. One registration per provider id per plugin; when two plugins
- * claim the same provider id the host keeps the first by plugin id and warns.
+ * not fetch. One registration per provider kind and id per plugin; when two
+ * plugins claim the same pair the host keeps the first by plugin id and warns.
  */
 interface PluginProviderIconRegistration {
+    providerKind: "agent" | "environment" | "machine";
     /**
      * The provider this mark is for — the id bb knows the provider by (the
      * provider declaration's id, e.g. `codex` or `acp-cursor`), not the plugin
@@ -1650,10 +1655,13 @@ interface PluginTimelineRendererRegistration {
 interface PluginEnvironmentProviderInputsProps {
     /** Project selected in the composer; null in projectless compose. */
     projectId: string | null;
-    /**
-     * The enrolled machine the selection names; null before one is picked.
-     */
-    hostId: string | null;
+    /** Whether setup uses an existing host or provisions a new host before create. */
+    target: {
+        kind: "existing-host";
+        hostId: string;
+    } | {
+        kind: "new-host";
+    };
     /**
      * The `inputs` value the selection will carry: null until `onChange`
      * supplies one.
@@ -1688,6 +1696,34 @@ interface PluginEnvironmentProviderInputsRegistration {
     environmentProviderId: string;
     component: ComponentType<PluginEnvironmentProviderInputsProps>;
 }
+/**
+ * Props passed to an `experimental_machineProviderInputs` component. Machine
+ * inputs are persisted and readable by every plugin, so they must contain only
+ * non-secret configuration and references to credentials held in plugin
+ * settings.
+ */
+interface PluginMachineProviderInputsProps {
+    /** The value persisted with the machine selection. */
+    value: JsonValue$1 | null;
+    /** Replace the submitted value or block submission with a visible reason. */
+    onChange(next: PluginMachineProviderInputsChange): void;
+}
+type PluginMachineProviderInputsChange = {
+    status: "ready";
+    value: JsonValue$1;
+} | {
+    status: "blocked";
+    reason: string;
+};
+/**
+ * Supply the inputs control for one machine provider registered server-side
+ * through `bb.experimental_machines.register`.
+ */
+interface PluginMachineProviderInputsRegistration {
+    /** The machine provider id this control supplies inputs for. */
+    machineProviderId: string;
+    component: ComponentType<PluginMachineProviderInputsProps>;
+}
 interface PluginAppSlots {
     homepageSection(registration: PluginHomepageSectionRegistration): void;
     settingsSection(registration: PluginSettingsSectionRegistration): void;
@@ -1746,8 +1782,8 @@ interface PluginAppSlots {
      */
     commandPaletteAction(registration: PluginCommandPaletteActionRegistration): void;
     /**
-     * Draw one agent or environment provider's icon with an inline
-     * React component instead of its `<img>`-rendered logo file (see
+     * Draw one agent, environment, or machine provider's icon with an inline
+     * React component instead of its masked logo asset (see
      * {@link PluginProviderIconRegistration}). Experimental: see
      * docs/api_to_audit.md.
      */
@@ -1766,6 +1802,12 @@ interface PluginAppSlots {
      * see docs/api_to_audit.md.
      */
     experimental_environmentProviderInputs(registration: PluginEnvironmentProviderInputsRegistration): void;
+    /**
+     * Supply the non-secret machine inputs control rendered by machine creation
+     * surfaces (see {@link PluginMachineProviderInputsRegistration}).
+     * Experimental: see docs/api_to_audit.md.
+     */
+    experimental_machineProviderInputs(registration: PluginMachineProviderInputsRegistration): void;
 }
 interface PluginAppComposer {
     customize(registration: ComposerCustomization): void;
@@ -1813,7 +1855,63 @@ interface PluginContentScriptRegistration {
 interface PluginAppContentScripts {
     register(registration: PluginContentScriptRegistration): void;
 }
+interface ExperimentalIconProps {
+    name: string;
+    /** Used when the requested name is missing; defaults to the host Zap icon. */
+    fallback?: string;
+    className?: string;
+    style?: CSSProperties;
+    "aria-hidden"?: boolean | "false" | "true";
+    "aria-label"?: string;
+}
+/** Shared agent, machine, or environment artwork without fetching metadata. */
+interface ExperimentalProviderIconProps {
+    /** Keeps same-id agent, machine, and environment providers distinct. */
+    providerKind: PluginProviderIconRegistration["providerKind"];
+    /**
+     * Existing agent, machine, or environment provider record. Reads id, logoUrl, icon and
+     * strings.iconTint; other fields are ignored. An id-only record is sufficient
+     * when only frontend registrations and fallback are needed. Does not fetch.
+     */
+    provider: {
+        id: string;
+        logoUrl?: string | null;
+        /** Agent providers use { glyph }; machine and environment providers use a string. */
+        icon?: {
+            glyph: string;
+        } | string | null;
+        strings?: {
+            iconTint?: {
+                light: string;
+                dark: string;
+            } | null;
+        } | null;
+    };
+    /** Used when no artwork is available; defaults to Code. */
+    fallback?: string;
+    className?: string;
+    "aria-hidden"?: boolean | "false" | "true";
+    "aria-label"?: string;
+}
+interface ExperimentalIconRegistration {
+    /** Shared app name. Namespacing is recommended, but not required. */
+    name: string;
+    /** Inline artwork. Honor className for sizing; use currentColor for tint. */
+    component: ComponentType<{
+        className?: string;
+    }>;
+}
+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.
+     */
+    register(registration: ExperimentalIconRegistration): void;
+}
 interface PluginAppBuilder {
+    experimental_icons: ExperimentalAppIcons;
     slots: PluginAppSlots;
     composer: PluginAppComposer;
     contentScripts: PluginAppContentScripts;
@@ -2538,6 +2636,15 @@ interface BbNavigate {
  * shims the specifier to that object on `globalThis.__bbPluginRuntime`.
  */
 interface PluginSdkApp {
+    experimental_Icon: ComponentType<ExperimentalIconProps>;
+    /**
+     * Render provider slot override, then its logo, then its glyph, then fallback.
+     * Pass a record from agent, machine, or environment provider queries;
+     * an id-only record resolves frontend registrations, without fetching metadata.
+     * Updates on plugin load, reload and unload. Throwing or recursive overrides
+     * fall back to declared artwork. Logo assets render as currentColor masks.
+     */
+    experimental_ProviderIcon: ComponentType<ExperimentalProviderIconProps>;
     definePluginApp(setup: PluginAppSetup): PluginAppDefinition;
     useRpc<Contract extends PluginRpcContract = PluginRpcContract>(): PluginRpcClient<Contract>;
     useRealtime(channel: string, handler: (payload: unknown) => void): void;
@@ -2681,6 +2788,8 @@ interface PluginSdkApp {
     useComposerView(): ComposerView;
 }
 
+declare const experimental_Icon: react.ComponentType<ExperimentalIconProps>;
+declare const experimental_ProviderIcon: react.ComponentType<ExperimentalProviderIconProps>;
 declare const definePluginApp: (setup: PluginAppSetup) => PluginAppDefinition;
 declare const ThreadChat: react.ComponentType<ThreadChatProps>;
 declare const Markdown: react.ComponentType<MarkdownProps>;
@@ -2711,5 +2820,5 @@ declare const experimental_useSidebarThreadSplit: (threadId: string) => PluginSi
 declare const experimental_useProviders: () => PluginProvidersState;
 declare const experimental_useCodeTheme: () => PluginCodeThemeState;
 
-export { Markdown, ThreadChat, UrlLink, definePluginApp, experimental_BranchPicker, experimental_Diff, experimental_FileLink, experimental_NewThreadComposer, experimental_PermissionModePicker, 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, ExperimentalAppOverlayProps, ExperimentalAppOverlayRegistration, ExperimentalAppPanel, ExperimentalAppPanelSurface, ExperimentalComposerSubmitOptions, ExperimentalDiffFileContent, ExperimentalDiffFullFileContents, ExperimentalFileLinkProps, ExperimentalFileLocation, ExperimentalFileOpenOptions, ExperimentalFixedTabTargetContract, ExperimentalFixedTabTargetState, ExperimentalLiveFileTarget, ExperimentalOpenFixedTabOptions, ExperimentalPermissionModePickerProps, ExperimentalPluginFixedTabReference, 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, PluginAppComposer, PluginAppContentScripts, PluginAppDefinition, PluginAppSetup, PluginAppSlots, PluginCodeThemeData, PluginCodeThemeState, PluginCodeThemeTokenRule, PluginCommandPaletteActionContext, PluginCommandPaletteActionRegistration, PluginComposerApi, PluginComposerMention, PluginComposerScope, PluginComposerTextEffect, PluginComposerThreadRowStatus, PluginContentScriptContext, PluginContentScriptDisposer, PluginContentScriptRegistration, PluginDiffRendererProps, PluginDiffRendererRegistration, PluginEnvironmentProviderInputsChange, PluginEnvironmentProviderInputsProps, PluginEnvironmentProviderInputsRegistration, PluginFileOpenerProps, PluginFileOpenerRegistration, PluginFileOpenerSource, PluginFixedTabDeclaration, PluginFixedTabRegistration, 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, PluginSourceCodeRendererProps, PluginSourceCodeRendererRegistration, PluginTargetedPanelActionOpenOptions, PluginThreadHeaderActionProps, PluginThreadHeaderActionRegistration, PluginThreadListProps, PluginThreadListRegistration, PluginThreadPanelActionContext, PluginThreadPanelActionRegistration, PluginThreadPanelProps, PluginTimelineRendererProps, PluginTimelineRendererRegistration, PluginTimelineRendererRow, PluginTimelineRowPresentation, PluginTimelineRowStatus, SourceCodeLineRange, SourceCodeProps, StandardSchemaV1, StandardSchemaV1InferInput, StandardSchemaV1InferOutput, StandardSchemaV1Issue, StandardSchemaV1Result, ThreadChatMessageAction, ThreadChatMessageReference, ThreadChatProps, UrlLinkProps, UseBranchesArgs, UseCheckoutStateArgs };
+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, 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, PluginAppComposer, PluginAppContentScripts, PluginAppDefinition, PluginAppSetup, PluginAppSlots, PluginCodeThemeData, PluginCodeThemeState, PluginCodeThemeTokenRule, PluginCommandPaletteActionContext, PluginCommandPaletteActionRegistration, 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, SourceCodeLineRange, SourceCodeProps, StandardSchemaV1, StandardSchemaV1InferInput, StandardSchemaV1InferOutput, StandardSchemaV1Issue, StandardSchemaV1Result, ThreadChatMessageAction, ThreadChatMessageReference, ThreadChatProps, UrlLinkProps, UseBranchesArgs, UseCheckoutStateArgs };

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

@@ -22,10 +22,14 @@ declare const environmentSchema: z.ZodObject<{
     environmentProviderInstanceKey: z.ZodNullable<z.ZodString>;
     environmentProviderSelection: z.ZodNullable<z.ZodObject<{
         inputs: z.ZodNullable<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, 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, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>;
+            machineProviderId: z.ZodString;
+            type: z.ZodLiteral<"new">;
+        }, z.core.$strip>], "type">;
     }, z.core.$strip>>;
     hostId: z.ZodString;
     id: z.ZodString;
@@ -75,6 +79,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";
@@ -86,6 +113,7 @@ declare const hostSchema: z.ZodObject<{
         disconnected: "disconnected";
     }>;
     type: z.ZodEnum<{
+        ephemeral: "ephemeral";
         persistent: "persistent";
     }>;
     updatedAt: z.ZodNumber;
@@ -166,8 +194,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 ? StandardSchemaV1InferOutput<S> : null;
 /** Attempt-scoped updates; core persists each update before this call returns. */
@@ -251,8 +281,10 @@ interface PluginEnvironmentProviderPolicy {
 interface PluginEnvironmentProviderDefinition<R extends PluginEnvironmentProviderRequirements = PluginEnvironmentProviderRequirements, 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>;

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

@@ -6,7 +6,7 @@
 // and read the real source: https://github.com/get-bb/bb
 
 import { z } from 'zod';
-import { StandardSchemaV1 as StandardSchemaV1$1, PluginEnvironmentProviderRequirements as PluginEnvironmentProviderRequirements$1, StandardSchemaV1InferOutput, PluginEnvironmentValidateDecision, JsonValue as JsonValue$2 } from '@get-bb/plugin-sdk';
+import { StandardSchemaV1 as StandardSchemaV1$1, PluginEnvironmentProviderRequirements as PluginEnvironmentProviderRequirements$1, StandardSchemaV1InferOutput, PluginEnvironmentValidateDecision, JsonValue as JsonValue$2, PluginMachineValidateDecision } from '@get-bb/plugin-sdk';
 
 /** Input-form entry: a path, or a path with options. */
 declare const providerNativeRootInputSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
@@ -74,10 +74,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 +131,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 +165,7 @@ declare const hostSchema: z.ZodObject<{
         disconnected: "disconnected";
     }>;
     type: z.ZodEnum<{
+        ephemeral: "ephemeral";
         persistent: "persistent";
     }>;
     updatedAt: z.ZodNumber;
@@ -492,10 +520,12 @@ 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;
+type InputsValue$1<S> = S extends StandardSchemaV1$1 ? StandardSchemaV1InferOutput<S> : null;
 /** Attempt-scoped updates; core persists each update before this call returns. */
 interface PluginEnvironmentProviderProgress {
     step(text: string): void;
@@ -506,7 +536,7 @@ interface PluginEnvironmentProviderValidateContext<R extends PluginEnvironmentPr
     host: Host;
     projectCheckout: Checkout<R>;
     gitRemote: Fact<R, "gitRemote", string>;
-    inputs: InputsValue<S>;
+    inputs: InputsValue$1<S>;
 }
 interface PluginEnvironmentProviderAvailabilityContext {
     project: Project;
@@ -577,8 +607,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>;
@@ -591,6 +623,80 @@ interface PluginEnvironmentProviderDefinition<R extends PluginEnvironmentProvide
 
 declare const RESERVED_BB_CLI_COMMANDS: readonly string[];
 
+type PluginMachineProviderResource = Exclude<JsonValue$2, null>;
+type PluginMachineProviderInputsSchema = StandardSchemaV1$1 | undefined;
+type InputsValue<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<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>;
+}
+
 /**
  * A value that survives a JSON round trip without coercion or data loss.
  *
@@ -710,6 +816,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>;
+}
 /**
  * Where a thread is going to run, as far as core knows at the checkpoint.
  * Before provisioning attaches an environment this is the start intent the
@@ -726,6 +862,10 @@ type PluginDispatchEnvironmentIntent = {
     machine: {
         type: "existing";
         hostId: string;
+    } | {
+        type: "new";
+        machineProviderId: string;
+        inputs: JsonValue | null;
     };
     inputs: JsonValue | null;
 };
@@ -1279,7 +1419,6 @@ interface ExperimentalPluginProviderEnvEntry {
         serverPath: string;
     };
     reason: string;
-    secret: boolean;
 }
 type PluginMentionTrigger = "!" | "#" | "$" | "@" | "~";
 /**
@@ -1539,13 +1678,24 @@ declare function storePluginHook<K extends PluginHookName>(records: {
 declare function pluginHookAlreadyRegisteredMessage(hook: PluginHookName): string;
 declare const ENVIRONMENT_PROVIDER_ID_PATTERN: RegExp;
 declare const ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS = 80;
+declare const ENVIRONMENT_PROVIDER_DESCRIPTION_MAX_CHARS = 200;
 declare const ENVIRONMENT_PROVIDER_REQUIREMENT_NAMES: readonly ["projectCheckout", "gitCheckout", "gitRemote", "projectless"];
 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;
@@ -1557,7 +1707,25 @@ interface NormalizedPluginEnvironmentProvider {
     policy: PluginEnvironmentProviderPolicy;
 }
 declare function validatePluginEnvironmentProviderDeclaration(declaration: PluginEnvironmentProviderDeclaration): NormalizedPluginEnvironmentProvider;
-declare const MACHINE_PROVIDER_REQUIREMENT_NAMES: readonly ["gitRemote"];
+declare const MACHINE_PROVIDER_DESCRIPTION_MAX_CHARS = 200;
+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"];
+}
+declare function validatePluginMachineProviderDeclaration(declaration: PluginMachineProviderDeclaration): NormalizedPluginMachineProvider;
+declare function validateServerAccessProviderDeclaration(declaration: ServerAccessProviderDeclaration): ServerAccessProviderDeclaration;
 
-export { AGENT_TOOL_NAME_PATTERN, BACKGROUND_NAME_PATTERN, CLI_COMMAND_NAME_PATTERN, ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS, ENVIRONMENT_PROVIDER_ID_PATTERN, ENVIRONMENT_PROVIDER_REQUIREMENT_NAMES, KV_VALUE_MAX_BYTES, MACHINE_PROVIDER_REQUIREMENT_NAMES, 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_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, RPC_METHOD_PATTERN, SERVER_DIRECT_AI_SERVICE_IDS, SETTING_KEY_PATTERN, adoptHttpRouteResponse, agentToolIconRefusalMessage, aiServiceAlreadyRegisteredMessage, assertAiServiceRegistrable, assertNoRecursiveJsonSchemaReferences, deriveValidatedProviderOptions, enforcePluginCliOutputLimit, isPluginMentionTrigger, isStandardSchema, isZodSchemaLike, normalizeMentionProviderTriggers, parsePluginAgentToolPresentation, pluginCliCollisionWarning, pluginHookAlreadyRegisteredMessage, providerAlreadyRegisteredMessage, providerIconRefusalMessage, providerWithoutBridgeMessage, readRpcMethodContract, registerSettingDescriptors, rejectStaleAgentToolFields, storePluginHook, summarizeParseIssues, summarizeStandardIssues, undeclaredIconProblem, validatePluginAiServiceDeclaration, validatePluginEnvironmentProviderDeclaration, validatePluginProviderDeclaration, validatePluginProviderEnvEntries, validateSettingsUpdate, zodSchemaToJsonSchema };
-export type { AiServiceHostBinding, NormalizedPluginEnvironmentProvider, NormalizedPluginEnvironmentProviderRequirements, NormalizedPluginProviderDeclaration };
+export { AGENT_TOOL_NAME_PATTERN, BACKGROUND_NAME_PATTERN, CLI_COMMAND_NAME_PATTERN, 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, 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_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, RPC_METHOD_PATTERN, SERVER_DIRECT_AI_SERVICE_IDS, SETTING_KEY_PATTERN, adoptHttpRouteResponse, agentToolIconRefusalMessage, aiServiceAlreadyRegisteredMessage, assertAiServiceRegistrable, assertNoRecursiveJsonSchemaReferences, deriveValidatedProviderOptions, enforcePluginCliOutputLimit, environmentCompositionSchema, isPluginMentionTrigger, isStandardSchema, isZodSchemaLike, normalizeMentionProviderTriggers, parsePluginAgentToolPresentation, pluginCliCollisionWarning, pluginHookAlreadyRegisteredMessage, providerAlreadyRegisteredMessage, providerIconRefusalMessage, providerWithoutBridgeMessage, readRpcMethodContract, registerSettingDescriptors, rejectStaleAgentToolFields, storePluginHook, summarizeParseIssues, summarizeStandardIssues, undeclaredIconProblem, validatePluginAiServiceDeclaration, validatePluginEnvironmentProviderDeclaration, validatePluginMachineProviderDeclaration, validatePluginProviderDeclaration, validatePluginProviderEnvEntries, validateServerAccessProviderDeclaration, validateSettingsUpdate, zodSchemaToJsonSchema };
+export type { AiServiceHostBinding, NormalizedPluginEnvironmentComposition, NormalizedPluginEnvironmentProvider, NormalizedPluginEnvironmentProviderRequirements, NormalizedPluginMachineProvider, NormalizedPluginProviderDeclaration };