@get-bb/plugin-sdk 0.4.48 → 0.4.50

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

@@ -0,0 +1,266 @@
+// 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 { z } from 'zod';
+import { PluginEnvironmentProviderRequirements, StandardSchemaV1, StandardSchemaV1InferOutput, JsonValue as JsonValue$1, PluginEnvironmentValidateDecision } from '@get-bb/plugin-sdk';
+
+interface JsonObject {
+    [key: string]: JsonValue;
+}
+type JsonValue = string | number | boolean | null | JsonValue[] | JsonObject;
+
+declare const environmentSchema: z.ZodObject<{
+    baseBranch: z.ZodNullable<z.ZodString>;
+    branchName: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodNumber;
+    defaultBranch: z.ZodNullable<z.ZodString>;
+    environmentProviderId: z.ZodNullable<z.ZodString>;
+    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<{
+            hostId: z.ZodString;
+            type: z.ZodLiteral<"existing">;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    hostId: z.ZodString;
+    id: z.ZodString;
+    isGitRepo: z.ZodBoolean;
+    isWorktree: z.ZodBoolean;
+    lifecycle: z.ZodObject<{
+        phase: z.ZodEnum<{
+            active: "active";
+            destroyed: "destroyed";
+            retiring: "retiring";
+            teardown: "teardown";
+        }>;
+        retireAt: z.ZodNullable<z.ZodNumber>;
+        teardown: z.ZodNullable<z.ZodObject<{
+            attempt: z.ZodNumber;
+            message: z.ZodOptional<z.ZodString>;
+            status: z.ZodEnum<{
+                failed: "failed";
+                removed: "removed";
+                running: "running";
+            }>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    managed: z.ZodBoolean;
+    mergeBaseBranch: z.ZodNullable<z.ZodString>;
+    name: z.ZodNullable<z.ZodString>;
+    path: z.ZodNullable<z.ZodString>;
+    projectId: z.ZodString;
+    status: z.ZodEnum<{
+        destroyed: "destroyed";
+        error: "error";
+        provisioning: "provisioning";
+        ready: "ready";
+    }>;
+    updatedAt: z.ZodNumber;
+    workspaceProvisionType: z.ZodNullable<z.ZodEnum<{
+        "managed-worktree": "managed-worktree";
+        personal: "personal";
+        unmanaged: "unmanaged";
+    }>>;
+}, z.core.$strip>;
+type Environment = z.infer<typeof environmentSchema>;
+
+declare const hostSchema: z.ZodObject<{
+    createdAt: z.ZodNumber;
+    id: z.ZodString;
+    lastRejectedProtocolVersion: z.ZodNullable<z.ZodNumber>;
+    lastSeenAt: z.ZodNullable<z.ZodNumber>;
+    maxPermissionMode: z.ZodEnum<{
+        "accept-edits": "accept-edits";
+        auto: "auto";
+        full: "full";
+    }>;
+    name: z.ZodString;
+    status: z.ZodEnum<{
+        connected: "connected";
+        disconnected: "disconnected";
+    }>;
+    type: z.ZodEnum<{
+        persistent: "persistent";
+    }>;
+    updatedAt: z.ZodNumber;
+}, z.core.$strip>;
+type Host = z.infer<typeof hostSchema>;
+
+declare const projectSchema: z.ZodObject<{
+    createdAt: z.ZodNumber;
+    gitRemoteUrl: z.ZodNullable<z.ZodString>;
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        personal: "personal";
+        standard: "standard";
+    }>;
+    name: z.ZodString;
+    updatedAt: z.ZodNumber;
+}, z.core.$strip>;
+type Project = z.infer<typeof projectSchema>;
+
+declare const threadResponseSchema: z.ZodObject<{
+    activeBackgroundAgentCount: z.ZodNumber;
+    archivedAt: z.ZodNullable<z.ZodNumber>;
+    canSpawnChild: z.ZodBoolean;
+    createdAt: z.ZodNumber;
+    deletedAt: z.ZodNullable<z.ZodNumber>;
+    environmentId: z.ZodNullable<z.ZodString>;
+    id: z.ZodString;
+    lastReadAt: z.ZodNullable<z.ZodNumber>;
+    latestAttentionAt: z.ZodNumber;
+    originKind: z.ZodNullable<z.ZodEnum<{
+        fork: "fork";
+    }>>;
+    originPluginId: z.ZodNullable<z.ZodString>;
+    parentThreadId: z.ZodNullable<z.ZodString>;
+    pinnedAt: z.ZodNullable<z.ZodNumber>;
+    projectId: z.ZodString;
+    providerId: z.ZodString;
+    queuedMessageCount: z.ZodNumber;
+    runtime: z.ZodObject<{
+        displayStatus: z.ZodEnum<{
+            "host-reconnecting": "host-reconnecting";
+            "waiting-for-host": "waiting-for-host";
+            active: "active";
+            error: "error";
+            idle: "idle";
+            pending: "pending";
+            provisioning: "provisioning";
+            starting: "starting";
+            stopping: "stopping";
+        }>;
+        hostReconnectGraceExpiresAt: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    sectionId: z.ZodNullable<z.ZodString>;
+    sourceThreadId: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<{
+        active: "active";
+        error: "error";
+        idle: "idle";
+        pending: "pending";
+        starting: "starting";
+        stopping: "stopping";
+    }>;
+    title: z.ZodNullable<z.ZodString>;
+    titleFallback: z.ZodNullable<z.ZodString>;
+    updatedAt: z.ZodNumber;
+    visibility: z.ZodEnum<{
+        hidden: "hidden";
+        visible: "visible";
+    }>;
+}, z.core.$strip>;
+type ThreadResponse = z.infer<typeof threadResponseSchema>;
+
+type PluginEnvironmentProviderInputsSchema = StandardSchemaV1 | undefined;
+type Fact<R, K extends PropertyKey, T> = R extends Record<K, true> ? T : T | null;
+type Checkout<R> = R extends {
+    projectCheckout: true;
+} | {
+    gitCheckout: true;
+} ? {
+    path: string;
+} : {
+    path: string;
+} | null;
+type InputsValue<S> = S extends StandardSchemaV1 ? StandardSchemaV1InferOutput<S> : null;
+/** Attempt-scoped updates; core persists each update before this call returns. */
+interface PluginEnvironmentProviderProgress {
+    step(text: string): void;
+    log(text: string): void;
+}
+interface PluginEnvironmentProviderValidateContext<R extends PluginEnvironmentProviderRequirements = PluginEnvironmentProviderRequirements, S extends PluginEnvironmentProviderInputsSchema = PluginEnvironmentProviderInputsSchema> {
+    project: Project;
+    host: Host;
+    projectCheckout: Checkout<R>;
+    gitRemote: Fact<R, "gitRemote", string>;
+    inputs: InputsValue<S>;
+}
+interface PluginEnvironmentProviderAvailabilityContext {
+    project: Project;
+    host: Host | null;
+    projectCheckout: {
+        path: string;
+    } | null;
+    gitRemote: string | null;
+}
+type PluginEnvironmentProviderAvailability = {
+    status: "available";
+} | {
+    status: "setup-required";
+    message: string;
+} | {
+    status: "unavailable";
+    message: string;
+};
+interface PluginEnvironmentProviderCreateContext<R extends PluginEnvironmentProviderRequirements = PluginEnvironmentProviderRequirements, S extends PluginEnvironmentProviderInputsSchema = PluginEnvironmentProviderInputsSchema> extends PluginEnvironmentProviderValidateContext<R, S> {
+    thread: ThreadResponse;
+    suggestedBranchName: string;
+    attempt: number;
+    pathKey: string;
+    rebuild: boolean;
+    experimental_claimPath(path: string): Promise<boolean>;
+    /** Resource is private to this provider; null after completed removal. */
+    previous: {
+        environment: Environment;
+        resource: JsonValue$1 | null;
+    } | null;
+    report: PluginEnvironmentProviderProgress;
+    signal: AbortSignal;
+}
+type PluginEnvironmentProviderCreateResult = {
+    status: "created";
+    path: string;
+    ownsPath: boolean;
+    mergeBaseBranch?: string;
+    resource?: JsonValue$1;
+} | {
+    status: "failed";
+    failure: "terminal" | "transient";
+    message: string;
+};
+interface PluginEnvironmentProviderRemoveContext {
+    environment: Environment | null;
+    hostId: string | null;
+    path: string | null;
+    pathKey: string;
+    resource: JsonValue$1 | null;
+    attempt: number;
+    report: PluginEnvironmentProviderProgress;
+    signal: AbortSignal;
+}
+type PluginEnvironmentProviderRemoveResult = {
+    status: "removed";
+} | {
+    status: "failed";
+    message: string;
+};
+/** Core normalizes omitted policy members once at registration. */
+interface PluginEnvironmentProviderPolicy {
+    /** Default five minutes; null keeps the environment indefinitely. */
+    retireGraceMs: number | null;
+    /** Default per-thread; rebuilds use a fresh key to avoid dead paths. */
+    pathKeys: "per-attempt" | "per-thread";
+}
+/** Resource operations only. Core owns durable launches, retries and retirement. */
+interface PluginEnvironmentProviderDefinition<R extends PluginEnvironmentProviderRequirements = PluginEnvironmentProviderRequirements, S extends PluginEnvironmentProviderInputsSchema = PluginEnvironmentProviderInputsSchema> {
+    id: string;
+    displayName: string;
+    /** Host glyph, plugin-relative icon path, or this plugin’s declared namespaced icon. */
+    icon?: string;
+    requires?: R;
+    inputs?: S;
+    policy?: Partial<PluginEnvironmentProviderPolicy>;
+    /** Experimental: see docs/api_to_audit.md. */
+    availability?(context: PluginEnvironmentProviderAvailabilityContext): PluginEnvironmentProviderAvailability | Promise<PluginEnvironmentProviderAvailability>;
+    validate?(context: PluginEnvironmentProviderValidateContext<R, S>): PluginEnvironmentValidateDecision | Promise<PluginEnvironmentValidateDecision>;
+    create(context: PluginEnvironmentProviderCreateContext<R, S>): Promise<PluginEnvironmentProviderCreateResult>;
+    remove(context: PluginEnvironmentProviderRemoveContext): Promise<PluginEnvironmentProviderRemoveResult>;
+}
+
+export type { PluginEnvironmentProviderAvailability, PluginEnvironmentProviderAvailabilityContext, PluginEnvironmentProviderCreateContext, PluginEnvironmentProviderCreateResult, PluginEnvironmentProviderDefinition, PluginEnvironmentProviderInputsSchema, PluginEnvironmentProviderPolicy, PluginEnvironmentProviderProgress, PluginEnvironmentProviderRemoveContext, PluginEnvironmentProviderRemoveResult, PluginEnvironmentProviderValidateContext };

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

@@ -6,6 +6,8 @@
 // and read the real source: https://github.com/get-bb/bb
 
 import { z } from 'zod';
+import { ChildProcess } from 'node:child_process';
+import { Readable } from 'node:stream';
 
 /**
  * The validator-neutral subset of Standard Schema v1 used by plugin contracts.
@@ -597,5 +599,34 @@ declare function experimental_resolveVendorPluginRoots(args: ExperimentalVendorP
  */
 declare function experimental_resolveClaudePluginRoots(args: ExperimentalClaudePluginRootsArgs): Promise<ExperimentalClaudePluginRoots>;
 
-export { experimental_defineHostEntry, experimental_filterResolvedNativeRoots, experimental_nativeRootsHostContract, experimental_nativeRootsResolveInputSchema, experimental_nativeRootsResolveOutputSchema, experimental_resolveClaudePluginRoots, experimental_resolveVendorPluginRoots };
-export type { ExperimentalClaudePluginRoots, ExperimentalClaudePluginRootsArgs, ExperimentalDroppedNativeRoot, ExperimentalFilteredNativeRoots, ExperimentalHostEntry, ExperimentalHostPaths, ExperimentalHostRpcContext, ExperimentalHostRpcHandlers, ExperimentalHostSignalContract, ExperimentalHostSignals, ExperimentalHostWatchChange, ExperimentalHostWatchChangeType, ExperimentalHostWatchEvent, ExperimentalHostWatchListener, ExperimentalHostWatchOptions, ExperimentalHostWatchSubscription, ExperimentalHostWorkerLease, ExperimentalNativeRootsHostContract, ExperimentalNativeRootsResolveAnswer, ExperimentalNativeRootsResolveInput, ExperimentalNativeRootsResolveOutput, ExperimentalVendorPlugin, ExperimentalVendorPluginRoots, ExperimentalVendorPluginRootsArgs };
+type PortableChildProcess = ChildProcess;
+interface PortablePipedSpawnRequest {
+    command: string;
+    args: string[];
+    cwd?: string;
+    detached?: boolean;
+    env?: NodeJS.ProcessEnv;
+}
+interface PortableOutputChildProcess extends PortableChildProcess {
+    stdin: null;
+    stdout: Readable;
+    stderr: Readable;
+}
+interface ProcessWithCwd {
+    pid: number;
+    cwd: string;
+}
+interface KillProcessesWithCwdUnderArgs {
+    directory: string;
+    graceMs?: number;
+}
+interface SanitizeInheritedChildProcessEnvArgs {
+    env: NodeJS.ProcessEnv;
+    shellPath?: string;
+}
+declare function spawnPortableOutputProcess(request: PortablePipedSpawnRequest): PortableOutputChildProcess;
+declare function killProcessesWithCwdUnder(args: KillProcessesWithCwdUnderArgs): Promise<ProcessWithCwd[]>;
+declare function sanitizeInheritedChildProcessEnv(args: SanitizeInheritedChildProcessEnvArgs): NodeJS.ProcessEnv;
+
+export { experimental_defineHostEntry, experimental_filterResolvedNativeRoots, killProcessesWithCwdUnder as experimental_killProcessesWithCwdUnder, experimental_nativeRootsHostContract, experimental_nativeRootsResolveInputSchema, experimental_nativeRootsResolveOutputSchema, experimental_resolveClaudePluginRoots, experimental_resolveVendorPluginRoots, sanitizeInheritedChildProcessEnv as experimental_sanitizeInheritedChildProcessEnv, spawnPortableOutputProcess as experimental_spawnPortableOutputProcess };
+export type { ExperimentalClaudePluginRoots, ExperimentalClaudePluginRootsArgs, ExperimentalDroppedNativeRoot, ExperimentalFilteredNativeRoots, ExperimentalHostEntry, ExperimentalHostPaths, ExperimentalHostRpcContext, ExperimentalHostRpcHandlers, ExperimentalHostSignalContract, ExperimentalHostSignals, ExperimentalHostWatchChange, ExperimentalHostWatchChangeType, ExperimentalHostWatchEvent, ExperimentalHostWatchListener, ExperimentalHostWatchOptions, ExperimentalHostWatchSubscription, ExperimentalHostWorkerLease, ExperimentalNativeRootsHostContract, ExperimentalNativeRootsResolveAnswer, ExperimentalNativeRootsResolveInput, ExperimentalNativeRootsResolveOutput, SanitizeInheritedChildProcessEnvArgs as ExperimentalSanitizeInheritedChildProcessEnvArgs, ExperimentalVendorPlugin, ExperimentalVendorPluginRoots, ExperimentalVendorPluginRootsArgs };

package/bundled-types/bb-plugin-sdk-internal-composer-customization-validation.d.ts

@@ -16,6 +16,7 @@ type RejectionReporter = (reason: string) => void;
  */
 declare function normalizePluginThreadRowStatus(value: unknown, onRejected: RejectionReporter): PluginComposerThreadRowStatus | null | undefined;
 declare function requireSlotId(kind: string, value: unknown): string;
+declare function requireEnvironmentProviderId(kind: string, value: unknown): string;
 /**
  * Provider ids follow the same character rules as slot ids, but they name a
  * provider the host knows (`codex`, `acp-cursor`), not a per-plugin slot.
@@ -41,4 +42,4 @@ declare function requireUniqueId(kind: string, seen: Set<string>, id: string): v
  */
 declare function collectComposerCustomization(registration: unknown, seenIds: Set<string>, onRejected: RejectionReporter): ComposerCustomization | null;
 
-export { PLUGIN_SLOT_ID_PATTERN, PLUGIN_TIMELINE_RENDERER_KIND_PATTERN, collectComposerCustomization, normalizePluginThreadRowStatus, requireComponent, requireMessageDirectiveId, requireNonEmptyString, requireOptionalString, requireProviderId, requireSlotId, requireTimelineRendererKind, requireUniqueId };
+export { PLUGIN_SLOT_ID_PATTERN, PLUGIN_TIMELINE_RENDERER_KIND_PATTERN, collectComposerCustomization, normalizePluginThreadRowStatus, requireComponent, requireEnvironmentProviderId, requireMessageDirectiveId, requireNonEmptyString, requireOptionalString, requireProviderId, requireSlotId, requireTimelineRendererKind, requireUniqueId };

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

@@ -6,8 +6,7 @@
 // and read the real source: https://github.com/get-bb/bb
 
 import { z } from 'zod';
-
-declare const RESERVED_BB_CLI_COMMANDS: readonly string[];
+import { StandardSchemaV1 as StandardSchemaV1$1, PluginEnvironmentProviderRequirements as PluginEnvironmentProviderRequirements$1, StandardSchemaV1InferOutput, PluginEnvironmentValidateDecision, JsonValue as JsonValue$2 } 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<{
@@ -61,15 +60,47 @@ interface ProviderNativeRootsInputLike {
     readonly project?: readonly ProviderNativeRootInput[];
 }
 
+interface JsonObject {
+    [key: string]: JsonValue$1;
+}
+type JsonValue$1 = string | number | boolean | null | JsonValue$1[] | JsonObject;
+
 declare const environmentSchema: z.ZodObject<{
     baseBranch: z.ZodNullable<z.ZodString>;
     branchName: z.ZodNullable<z.ZodString>;
     createdAt: z.ZodNumber;
     defaultBranch: z.ZodNullable<z.ZodString>;
+    environmentProviderId: z.ZodNullable<z.ZodString>;
+    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<{
+            hostId: z.ZodString;
+            type: z.ZodLiteral<"existing">;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
     hostId: z.ZodString;
     id: z.ZodString;
     isGitRepo: z.ZodBoolean;
     isWorktree: z.ZodBoolean;
+    lifecycle: z.ZodObject<{
+        phase: z.ZodEnum<{
+            active: "active";
+            destroyed: "destroyed";
+            retiring: "retiring";
+            teardown: "teardown";
+        }>;
+        retireAt: z.ZodNullable<z.ZodNumber>;
+        teardown: z.ZodNullable<z.ZodObject<{
+            attempt: z.ZodNumber;
+            message: z.ZodOptional<z.ZodString>;
+            status: z.ZodEnum<{
+                failed: "failed";
+                removed: "removed";
+                running: "running";
+            }>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
     managed: z.ZodBoolean;
     mergeBaseBranch: z.ZodNullable<z.ZodString>;
     name: z.ZodNullable<z.ZodString>;
@@ -77,18 +108,16 @@ declare const environmentSchema: z.ZodObject<{
     projectId: z.ZodString;
     status: z.ZodEnum<{
         destroyed: "destroyed";
-        destroying: "destroying";
         error: "error";
         provisioning: "provisioning";
         ready: "ready";
-        retiring: "retiring";
     }>;
     updatedAt: z.ZodNumber;
-    workspaceProvisionType: z.ZodEnum<{
+    workspaceProvisionType: z.ZodNullable<z.ZodEnum<{
         "managed-worktree": "managed-worktree";
         personal: "personal";
         unmanaged: "unmanaged";
-    }>;
+    }>>;
 }, z.core.$strip>;
 type Environment = z.infer<typeof environmentSchema>;
 
@@ -327,6 +356,11 @@ declare const threadQueuedMessageSchema: z.ZodObject<{
     failureReason: z.ZodNullable<z.ZodString>;
     groupWithNext: z.ZodBoolean;
     id: z.ZodString;
+    initiator: z.ZodEnum<{
+        agent: "agent";
+        system: "system";
+        user: "user";
+    }>;
     model: z.ZodString;
     payload: z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"inline">;
@@ -352,6 +386,7 @@ declare const threadQueuedMessageSchema: z.ZodObject<{
         xhigh: "xhigh";
     }>;
     sendAt: z.ZodNullable<z.ZodNumber>;
+    senderThreadId: z.ZodNullable<z.ZodString>;
     serviceTier: z.ZodEnum<{
         default: "default";
         fast: "fast";
@@ -448,6 +483,114 @@ declare const threadResponseSchema: z.ZodObject<{
 }, z.core.$strip>;
 type ThreadResponse = z.infer<typeof threadResponseSchema>;
 
+type PluginEnvironmentProviderInputsSchema = StandardSchemaV1$1 | undefined;
+type Fact<R, K extends PropertyKey, T> = R extends Record<K, true> ? T : T | null;
+type Checkout<R> = R extends {
+    projectCheckout: true;
+} | {
+    gitCheckout: true;
+} ? {
+    path: string;
+} : {
+    path: string;
+} | null;
+type InputsValue<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;
+    log(text: string): void;
+}
+interface PluginEnvironmentProviderValidateContext<R extends PluginEnvironmentProviderRequirements$1 = PluginEnvironmentProviderRequirements$1, S extends PluginEnvironmentProviderInputsSchema = PluginEnvironmentProviderInputsSchema> {
+    project: Project;
+    host: Host;
+    projectCheckout: Checkout<R>;
+    gitRemote: Fact<R, "gitRemote", string>;
+    inputs: InputsValue<S>;
+}
+interface PluginEnvironmentProviderAvailabilityContext {
+    project: Project;
+    host: Host | null;
+    projectCheckout: {
+        path: string;
+    } | null;
+    gitRemote: string | null;
+}
+type PluginEnvironmentProviderAvailability = {
+    status: "available";
+} | {
+    status: "setup-required";
+    message: string;
+} | {
+    status: "unavailable";
+    message: string;
+};
+interface PluginEnvironmentProviderCreateContext<R extends PluginEnvironmentProviderRequirements$1 = PluginEnvironmentProviderRequirements$1, S extends PluginEnvironmentProviderInputsSchema = PluginEnvironmentProviderInputsSchema> extends PluginEnvironmentProviderValidateContext<R, S> {
+    thread: ThreadResponse;
+    suggestedBranchName: string;
+    attempt: number;
+    pathKey: string;
+    rebuild: boolean;
+    experimental_claimPath(path: string): Promise<boolean>;
+    /** Resource is private to this provider; null after completed removal. */
+    previous: {
+        environment: Environment;
+        resource: JsonValue$2 | null;
+    } | null;
+    report: PluginEnvironmentProviderProgress;
+    signal: AbortSignal;
+}
+type PluginEnvironmentProviderCreateResult = {
+    status: "created";
+    path: string;
+    ownsPath: boolean;
+    mergeBaseBranch?: string;
+    resource?: JsonValue$2;
+} | {
+    status: "failed";
+    failure: "terminal" | "transient";
+    message: string;
+};
+interface PluginEnvironmentProviderRemoveContext {
+    environment: Environment | null;
+    hostId: string | null;
+    path: string | null;
+    pathKey: string;
+    resource: JsonValue$2 | null;
+    attempt: number;
+    report: PluginEnvironmentProviderProgress;
+    signal: AbortSignal;
+}
+type PluginEnvironmentProviderRemoveResult = {
+    status: "removed";
+} | {
+    status: "failed";
+    message: string;
+};
+/** Core normalizes omitted policy members once at registration. */
+interface PluginEnvironmentProviderPolicy {
+    /** Default five minutes; null keeps the environment indefinitely. */
+    retireGraceMs: number | null;
+    /** Default per-thread; rebuilds use a fresh key to avoid dead paths. */
+    pathKeys: "per-attempt" | "per-thread";
+}
+/** Resource operations only. Core owns durable launches, retries and retirement. */
+interface PluginEnvironmentProviderDefinition<R extends PluginEnvironmentProviderRequirements$1 = PluginEnvironmentProviderRequirements$1, S extends PluginEnvironmentProviderInputsSchema = PluginEnvironmentProviderInputsSchema> {
+    id: string;
+    displayName: string;
+    /** Host glyph, plugin-relative icon path, or this plugin’s declared namespaced icon. */
+    icon?: string;
+    requires?: R;
+    inputs?: S;
+    policy?: Partial<PluginEnvironmentProviderPolicy>;
+    /** Experimental: see docs/api_to_audit.md. */
+    availability?(context: PluginEnvironmentProviderAvailabilityContext): PluginEnvironmentProviderAvailability | Promise<PluginEnvironmentProviderAvailability>;
+    validate?(context: PluginEnvironmentProviderValidateContext<R, S>): PluginEnvironmentValidateDecision | Promise<PluginEnvironmentValidateDecision>;
+    create(context: PluginEnvironmentProviderCreateContext<R, S>): Promise<PluginEnvironmentProviderCreateResult>;
+    remove(context: PluginEnvironmentProviderRemoveContext): Promise<PluginEnvironmentProviderRemoveResult>;
+}
+
+declare const RESERVED_BB_CLI_COMMANDS: readonly string[];
+
 /**
  * A value that survives a JSON round trip without coercion or data loss.
  *
@@ -536,6 +679,57 @@ type PluginSettingDescriptor = {
 };
 type PluginSettingDescriptors = Record<string, PluginSettingDescriptor>;
 type PluginSettingValue = string | number | boolean;
+/**
+ * The facts this provider consumes, in one declaration. Every member is
+ * something core can evaluate before the thread exists and supply to
+ * `create`, so it is also the whole of what decides where the provider is
+ * offered, and the picker needs to know no provider by name. Every member
+ * defaults to false.
+ *
+ * - `projectCheckout` — the provider works from this project's directory on
+ *   that machine, git or not, so core refuses a machine with no checkout of
+ *   the project at create time and `context.projectCheckout` is non-null.
+ * - `gitCheckout` — that directory must also be a git repository with at
+ *   least one commit. The picker greys the row out where it is not, and core
+ *   rejects an explicit selection using the same machine inspection before
+ *   creating the thread. Implies `projectCheckout`.
+ * - `gitRemote` — the provider clones the project itself, so it is greyed out
+ *   in a project with no git remote and an explicit selection is rejected.
+ * - `projectless` — this provider serves only threads that have no project,
+ *   so it is offered for those and nowhere else. It cannot be combined with
+ *   `projectCheckout`, `gitCheckout` or `gitRemote`, which need a project.
+ */
+interface PluginEnvironmentProviderRequirements {
+    projectCheckout?: boolean;
+    gitCheckout?: boolean;
+    gitRemote?: boolean;
+    projectless?: boolean;
+}
+/**
+ * Resource operations for one place a thread can run. Core persists progress,
+ * retries, cancellation and retirement. Operations must be idempotent for the
+ * supplied pathKey. Provider ids are unique across running plugins.
+ */
+type PluginEnvironmentProviderDeclaration<Requires extends PluginEnvironmentProviderRequirements = PluginEnvironmentProviderRequirements, Inputs extends PluginEnvironmentProviderInputsSchema = PluginEnvironmentProviderInputsSchema> = PluginEnvironmentProviderDefinition<Requires, Inputs>;
+/**
+ * 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
+ * thread was created with; afterwards it is the environment itself.
+ */
+type PluginDispatchEnvironmentIntent = {
+    kind: "environment";
+    environmentId: string;
+}
+/** Ask a registered environment provider for the environment. */
+ | {
+    kind: "provider";
+    environmentProviderId: string;
+    machine: {
+        type: "existing";
+        hostId: string;
+    };
+    inputs: JsonValue | null;
+};
 /**
  * What a `message.dispatch` hook answers.
  *
@@ -637,6 +831,13 @@ interface MessageDispatchHookContext {
      * about to occupy. Null only when neither names a machine.
      */
     host: Host | null;
+    /**
+     * What kind of environment the thread will run in, so a policy can tell a
+     * worktree on this machine from a cloud sandbox from an attached directory
+     * before any of them exists. Null only for a thread with neither an
+     * environment nor a start intent.
+     */
+    environmentIntent: PluginDispatchEnvironmentIntent | null;
     input: PluginDispatchInput;
     requestedExecution: PluginDispatchExecution;
     /** Where each execution value came from. */
@@ -1278,6 +1479,7 @@ declare function rejectStaleAgentToolFields(toolName: string, tool: object): voi
  */
 declare function parsePluginAgentToolPresentation(toolName: string, value: unknown): PluginAgentToolPresentation | null;
 /** Compact issue summary from a (possibly foreign-instance) zod error. */
+declare function summarizeStandardIssues(issues: readonly StandardSchemaV1Issue[]): string;
 declare function summarizeParseIssues(error: unknown): string;
 declare function enforcePluginCliOutputLimit(result: Omit<PluginCliExecutionResult, "error">, jsonOutput: boolean): PluginCliExecutionResult;
 /**
@@ -1336,6 +1538,27 @@ declare function storePluginHook<K extends PluginHookName>(records: {
 }, hook: K, handler: PluginHookHandler<K>): void;
 /** The refusal a second handler for one hook from one plugin gets. */
 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_REQUIREMENT_NAMES: readonly ["projectCheckout", "gitCheckout", "gitRemote", "projectless"];
+type NormalizedPluginEnvironmentProviderRequirements = {
+    [K in (typeof ENVIRONMENT_PROVIDER_REQUIREMENT_NAMES)[number]]: boolean;
+};
+interface NormalizedPluginEnvironmentProvider {
+    id: string;
+    displayName: string;
+    icon: string | null;
+    requires: NormalizedPluginEnvironmentProviderRequirements;
+    inputs: StandardSchemaV1 | null;
+    inputsJsonSchema: JsonValue | null;
+    availability: NonNullable<PluginEnvironmentProviderDeclaration["availability"]> | null;
+    validate: NonNullable<PluginEnvironmentProviderDeclaration["validate"]> | null;
+    create: PluginEnvironmentProviderDeclaration["create"];
+    remove: PluginEnvironmentProviderDeclaration["remove"];
+    policy: PluginEnvironmentProviderPolicy;
+}
+declare function validatePluginEnvironmentProviderDeclaration(declaration: PluginEnvironmentProviderDeclaration): NormalizedPluginEnvironmentProvider;
+declare const MACHINE_PROVIDER_REQUIREMENT_NAMES: readonly ["gitRemote"];
 
-export { AGENT_TOOL_NAME_PATTERN, BACKGROUND_NAME_PATTERN, CLI_COMMAND_NAME_PATTERN, KV_VALUE_MAX_BYTES, MENTION_PROVIDER_ID_PATTERN, PLUGIN_AGENT_DYNAMIC_INSTRUCTIONS_MAX_CHARS, PLUGIN_AGENT_SELECTION_MAX_IDS, PLUGIN_AGENT_STATIC_INSTRUCTIONS_MAX_CHARS, PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS, PLUGIN_AGENT_TOOL_PARAMETERS_MAX_BYTES, PLUGIN_HTTP_METHODS, PLUGIN_MENTION_TRIGGER_VALUES, PLUGIN_PROVIDER_BRIDGE_OPTIONS_MAX_BYTES, PLUGIN_PROVIDER_COMPOSER_ACTION_VALUES, PLUGIN_PROVIDER_DISPLAY_NAME_MAX_CHARS, PLUGIN_PROVIDER_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, undeclaredIconProblem, validatePluginAiServiceDeclaration, validatePluginProviderDeclaration, validatePluginProviderEnvEntries, validateSettingsUpdate, zodSchemaToJsonSchema };
-export type { AiServiceHostBinding, NormalizedPluginProviderDeclaration };
+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 };

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, 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, PluginTimelineRendererRegistration, PluginEnvironmentProviderInputsRegistration, PluginContentScriptRegistration, PluginAppDefinition } from '@get-bb/plugin-sdk';
 
 type ExperimentalSidebarFooterCommandKind = "close" | "open" | "toggle";
 interface ExperimentalSidebarFooterRuntimeSnapshot {
@@ -59,6 +59,7 @@ interface CollectedPluginAppRegistrations {
     commandPaletteActions: PluginCommandPaletteActionRegistration[];
     providerIcons: PluginProviderIconRegistration[];
     timelineRenderers: PluginTimelineRendererRegistration[];
+    environmentProviderInputs: PluginEnvironmentProviderInputsRegistration[];
     contentScripts: PluginContentScriptRegistration[];
 }
 declare function getCollectedSidebarFooterItems(registrations: object): readonly CollectedSidebarFooterItem[] | null;