@get-bb/plugin-sdk 0.4.47 → 0.4.50

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

@@ -7,7 +7,7 @@
 
 import { ReactNode, ComponentType } from 'react';
 import { RenderResult } from '@testing-library/react';
-import { ExperimentalSidebarFooterItemRegistration, PluginHomepageSectionRegistration, PluginSettingsSectionRegistration, ExperimentalAppOverlayRegistration, PluginNavPanelRegistration, PluginThreadPanelActionRegistration, PluginNewThreadPanelActionRegistration, ComposerCustomization, PluginPendingInteractionRegistration, PluginSidebarFooterActionRegistration, ExperimentalSidebarNavigationRegistration, PluginThreadListRegistration, PluginThreadHeaderActionRegistration, PluginFileOpenerRegistration, PluginSourceCodeRendererRegistration, PluginDiffRendererRegistration, PluginMessageDirectiveRegistration, PluginMessageActionRegistration, PluginProviderIconRegistration, PluginTimelineRendererRegistration, PluginContentScriptRegistration, PluginComposerScope, PluginComposerTextEffect, PluginComposerMention, PluginComposerThreadRowStatus, ExperimentalOpenFixedTabOptions, JsonValue, BbNavigate, ExperimentalFileOpenOptions, PluginAppDefinition, PluginRpcContract, StandardSchemaV1InferInput, PluginRpcResult, PluginRealtimeConnectionState, PluginSidebarThreadsState, PluginProvidersState, PluginCodeThemeState, PluginSidebarPullRequest, PluginSidebarThreadActions } from '@get-bb/plugin-sdk';
+import { ExperimentalSidebarFooterItemRegistration, PluginHomepageSectionRegistration, PluginSettingsSectionRegistration, ExperimentalAppOverlayRegistration, PluginNavPanelRegistration, PluginThreadPanelActionRegistration, PluginNewThreadPanelActionRegistration, ComposerCustomization, PluginPendingInteractionRegistration, PluginSidebarFooterActionRegistration, ExperimentalSidebarNavigationRegistration, PluginThreadListRegistration, PluginThreadHeaderActionRegistration, PluginFileOpenerRegistration, PluginSourceCodeRendererRegistration, PluginDiffRendererRegistration, PluginMessageDirectiveRegistration, PluginMessageActionRegistration, PluginProviderIconRegistration, PluginTimelineRendererRegistration, PluginEnvironmentProviderInputsRegistration, PluginContentScriptRegistration, PluginComposerScope, PluginComposerTextEffect, PluginComposerMention, PluginComposerThreadRowStatus, ExperimentalOpenFixedTabOptions, JsonValue, BbNavigate, ExperimentalFileOpenOptions, PluginAppDefinition, PluginRpcContract, StandardSchemaV1InferInput, PluginRpcResult, PluginRealtimeConnectionState, PluginSidebarThreadsState, PluginProvidersState, PluginCodeThemeState, BranchesState, CheckoutState, PluginSidebarPullRequest, PluginSidebarThreadActions } from '@get-bb/plugin-sdk';
 
 type ExperimentalSidebarFooterCommandKind = "close" | "open" | "toggle";
 interface ExperimentalSidebarFooterRuntimeSnapshot {
@@ -152,6 +152,7 @@ interface CapturedPluginApp {
     messageActions: PluginMessageActionRegistration[];
     providerIcons: PluginProviderIconRegistration[];
     timelineRenderers: PluginTimelineRendererRegistration[];
+    environmentProviderInputs: PluginEnvironmentProviderInputsRegistration[];
     contentScripts: PluginContentScriptRegistration[];
 }
 type PluginAppModule = {
@@ -239,6 +240,9 @@ interface RenderSlotOptions<Contract extends PluginRpcContract = PluginRpcContra
      * mode with no resolved document, the state a plugin sees on first paint.
      */
     codeTheme?: Partial<PluginCodeThemeState>;
+    branchesState?: Partial<BranchesState>;
+    /** Checkout facts `experimental_useCheckoutState()` reports. */
+    checkoutState?: Partial<CheckoutState>;
     /**
      * Pull requests `experimental_useSidebarThreadPullRequest()` reports, keyed
      * by thread id. Omitted → every thread reports none.

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

@@ -6,7 +6,7 @@
 // and read the real source: https://github.com/get-bb/bb
 
 import { z } from 'zod';
-import { BbPluginApi, PluginSettingValue as PluginSettingValue$1, PluginSharedPortTunnelIdentity, PluginAgentToolPresentation, PluginAgentToolContext, PluginAgentToolResult, PluginCliCommandInfo, PluginCliContext, PluginCliResult, PluginHttpAuthMode, PluginHttpHandler, PluginMentionTrigger, PluginMentionSearchContext, PluginMentionItem, JsonValue as JsonValue$1, PluginCliExecutionResult, PluginThreadEventName, PluginThreadEventPayloads, PluginAgentConfigurationContext, ExperimentalPluginProviderEnvContext, ExperimentalPluginProviderEnvEntry, ExperimentalPluginProviderEnvHealthContext, ExperimentalPluginProviderEnvHealth, PluginSettingDescriptors, ExperimentalPluginWebSocketHandler, PluginAgentConfiguration, PluginHookName, PluginHookHandler, PluginAiServiceDeclaration, PluginInteractionRequest, MessageDispatchHookContext } from '@get-bb/plugin-sdk';
+import { StandardSchemaV1 as StandardSchemaV1$1, PluginEnvironmentProviderRequirements as PluginEnvironmentProviderRequirements$1, StandardSchemaV1InferOutput, PluginEnvironmentValidateDecision, JsonValue as JsonValue$2, BbPluginApi, PluginSettingValue as PluginSettingValue$1, PluginSharedPortTunnelIdentity, PluginAgentToolPresentation, PluginAgentToolContext, PluginAgentToolResult, PluginCliCommandInfo, PluginCliContext, PluginCliResult, PluginHttpAuthMode, PluginHttpHandler, PluginMentionTrigger, PluginMentionSearchContext, PluginMentionItem, PluginCliExecutionResult, PluginThreadEventName, PluginThreadEventPayloads, PluginAgentConfigurationContext, ExperimentalPluginProviderEnvContext, ExperimentalPluginProviderEnvEntry, ExperimentalPluginProviderEnvHealthContext, ExperimentalPluginProviderEnvHealth, PluginSettingDescriptors, ExperimentalPluginWebSocketHandler, PluginAgentConfiguration, PluginHookName, PluginHookHandler, PluginAiServiceDeclaration, PluginInteractionRequest, MessageDispatchHookContext } from '@get-bb/plugin-sdk';
 
 /** Input-form entry: a path, or a path with options. */
 declare const providerNativeRootInputSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
@@ -60,9 +60,264 @@ 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>;
+    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 PROVIDER_FORK_VALUES: readonly ["none", "tip", "checkpoint"];
 type ProviderFork = (typeof PROVIDER_FORK_VALUES)[number];
 
+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$1 = 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$1;
+    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>;
+}
+
 /**
  * A value that survives a JSON round trip without coercion or data loss.
  *
@@ -103,6 +358,38 @@ interface StandardSchemaV1Issue {
 }
 
 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>;
 /**
  * Permission modes a provider can run a session in — BB's own permission
  * vocabulary, ordered least ("accept-edits") to most ("full") privileged.
@@ -471,6 +758,23 @@ type NormalizedPluginProviderDeclaration = Omit<PluginProviderDeclaration, "expe
         readonly scope: PluginProviderModelCatalogScope;
     };
 };
+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;
+}
 
 type BbSdk = BbPluginApi["sdk"];
 /**
@@ -652,6 +956,7 @@ interface FakePluginRegistrations {
     hooks: {
         [K in PluginHookName]: PluginHookHandler<K> | null;
     };
+    environmentProviders: ReadonlyMap<string, NormalizedPluginEnvironmentProvider>;
     mentionProviders: FakeMentionProviderRecord[];
     /** Live provider registrations from `bb.providers.register`
      * (normalized declarations, registration order; dispose removes). */
@@ -696,7 +1001,7 @@ interface FakePluginBehaviorDrivers {
     experimental_emitHostWorkerExit(hostId: string): Promise<void>;
     /** Deliver a host signal through its registered payload schema. */
     experimental_emitHostSignal(hostId: string, signal: string, payload: unknown): Promise<void>;
-    submitInteraction(id: string, value: JsonValue$1): void;
+    submitInteraction(id: string, value: JsonValue$2): void;
     cancelInteraction(id: string): void;
     /**
      * Apply a settings update the way the host's settings save does:
@@ -938,4 +1243,4 @@ interface PublicSdkOnlyScan {
 declare function scanPublicSdkOnly(packageRoot: string, options?: PublicSdkOnlyScanOptions): PublicSdkOnlyScan;
 
 export { PluginContextStaleError, createFakePluginHost, createFakeSdk, scanPublicSdkOnly as experimental_scanPublicSdkOnly, makeMessageDispatchHookContext, makePluginAgentConfigurationContext, makeQueueEntry, makeThreadResponse, makeTurnFailedEvent };
-export type { CreateFakePluginHostOptions, FakeAgentToolRecord, FakeCliRecord, FakeHttpRouteRecord, FakeLogEntry, FakeLogLevel, FakeMentionProviderRecord, FakePluginBehaviorDrivers, FakePluginHarness, FakePluginHost, FakePluginInspectionState, FakePluginLifecycleControls, FakePluginRegistrations, FakeRealtimeSignal, FakeScheduleRecord, FakeSdkCall, FakeSdkHarness, FakeSdkOverrides, FakeServiceRecord, PublicSdkOnlyScan, PublicSdkOnlyScanOptions, PublicSdkOnlyViolation };
+export type { CreateFakePluginHostOptions, ExperimentalFakeHostRpcCall, FakeAgentToolRecord, FakeCliRecord, FakeHttpRouteRecord, FakeLogEntry, FakeLogLevel, FakeMentionProviderRecord, FakePluginBehaviorDrivers, FakePluginHarness, FakePluginHost, FakePluginInspectionState, FakePluginLifecycleControls, FakePluginRegistrations, FakeRealtimeSignal, FakeScheduleRecord, FakeSdkCall, FakeSdkHarness, FakeSdkOverrides, FakeServiceRecord, PublicSdkOnlyScan, PublicSdkOnlyScanOptions, PublicSdkOnlyViolation };