@get-bb/plugin-sdk 0.4.56 → 0.4.87

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';
 
 /**
@@ -18,6 +18,14 @@ import { z } from 'zod';
 type JsonValue$1 = string | number | boolean | null | JsonValue$1[] | {
     [key: string]: JsonValue$1;
 };
+/**
+ * A `JsonValue` that is read-only at every depth. BB uses it for JSON
+ * snapshots it deep-freezes before handing them to a plugin, where any write
+ * throws at runtime.
+ */
+type ReadonlyJsonValue = string | number | boolean | null | readonly ReadonlyJsonValue[] | {
+    readonly [key: string]: ReadonlyJsonValue;
+};
 
 /** A JSON-safe path segment reported by a Standard Schema validation issue. */
 type PluginRpcIssuePathSegment = string | number;
@@ -330,10 +338,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 +1541,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 +1663,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 +1704,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 +1790,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 +1810,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 +1863,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 +2644,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 +2796,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 +2828,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, ReadonlyJsonValue, 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>;