@get-bb/plugin-sdk 0.4.56 → 0.4.87

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

@@ -5,8 +5,82 @@
 // Confused by the API, or need a symbol that isn't here? Clone the BB repo
 // and read the real source: https://github.com/get-bb/bb
 
+import { StandardSchemaV1 as StandardSchemaV1$1, StandardSchemaV1InferOutput, PluginMachineValidateDecision, JsonValue as JsonValue$2, PluginEnvironmentProviderRequirements as PluginEnvironmentProviderRequirements$1, PluginEnvironmentValidateDecision, BbPluginApi, PluginSettingValue as PluginSettingValue$1, PluginSharedPortTunnelIdentity, PluginAgentToolPresentation, PluginAgentToolContext, PluginAgentToolResult, PluginCliCommandInfo, PluginCliContext, PluginCliResult, PluginHttpAuthMode, PluginHttpHandler, PluginMentionTrigger, PluginMentionSearchContext, PluginMentionItem, PluginCliExecutionResult, PluginThreadEventName, PluginThreadEventPayloads, PluginAgentConfigurationContext, ExperimentalPluginProviderEnvContext, ExperimentalPluginProviderEnvEntry, ExperimentalPluginProviderEnvHealthContext, ExperimentalPluginProviderEnvHealth, PluginSettingDescriptors, ExperimentalPluginWebSocketHandler, PluginAgentConfiguration, PluginHookName, PluginHookHandler, PluginAiServiceDeclaration, PluginInteractionRequest, MessageDispatchHookContext } from '@get-bb/plugin-sdk';
 import { z } from 'zod';
-import { StandardSchemaV1 as StandardSchemaV1$1, PluginEnvironmentProviderRequirements as PluginEnvironmentProviderRequirements$1, StandardSchemaV1InferOutput, PluginEnvironmentValidateDecision, JsonValue as JsonValue$2, BbPluginApi, PluginSettingValue as PluginSettingValue$1, PluginSharedPortTunnelIdentity, PluginAgentToolPresentation, PluginAgentToolContext, PluginAgentToolResult, PluginCliCommandInfo, PluginCliContext, PluginCliResult, PluginHttpAuthMode, PluginHttpHandler, PluginMentionTrigger, PluginMentionSearchContext, PluginMentionItem, PluginCliExecutionResult, PluginThreadEventName, PluginThreadEventPayloads, PluginAgentConfigurationContext, ExperimentalPluginProviderEnvContext, ExperimentalPluginProviderEnvEntry, ExperimentalPluginProviderEnvHealthContext, ExperimentalPluginProviderEnvHealth, PluginSettingDescriptors, ExperimentalPluginWebSocketHandler, PluginAgentConfiguration, PluginHookName, PluginHookHandler, PluginAiServiceDeclaration, PluginInteractionRequest, MessageDispatchHookContext } from '@get-bb/plugin-sdk';
+
+type PluginMachineProviderResource = Exclude<JsonValue$2, null>;
+type PluginMachineProviderInputsSchema = StandardSchemaV1$1 | undefined;
+type InputsValue$1<S> = S extends StandardSchemaV1$1 ? StandardSchemaV1InferOutput<S> : null;
+interface PluginMachineProviderProgress {
+    step(text: string): void;
+    log(text: string): void;
+}
+type PluginMachineProviderAvailability = {
+    status: "available";
+} | {
+    status: "setup-required";
+    message: string;
+} | {
+    status: "unavailable";
+    message: string;
+};
+type PluginMachineProviderValidateContext<S extends PluginMachineProviderInputsSchema = PluginMachineProviderInputsSchema> = {
+    inputs: InputsValue$1<S>;
+};
+interface PluginMachineProviderLifecycleContext {
+    checkpoint(resource: PluginMachineProviderResource): Promise<void>;
+    report: PluginMachineProviderProgress;
+    signal: AbortSignal;
+}
+type PluginMachineProviderCreateContext<S extends PluginMachineProviderInputsSchema = PluginMachineProviderInputsSchema> = PluginMachineProviderValidateContext<S> & PluginMachineProviderLifecycleContext & {
+    key: string;
+    attempt: number;
+};
+type PluginMachineProviderCreateResult = {
+    status: "created";
+    name: string;
+    resource: PluginMachineProviderResource;
+} | {
+    status: "failed";
+    message: string;
+};
+type PluginMachineProviderResourceLifecycleContext = PluginMachineProviderLifecycleContext & {
+    hostId: string;
+    resource: PluginMachineProviderResource;
+};
+type PluginMachineProviderRemoveContext = Omit<PluginMachineProviderResourceLifecycleContext, "checkpoint">;
+interface PluginMachineProviderResourceResult {
+    resource: PluginMachineProviderResource;
+}
+type PluginMachineProviderRemoveResult = {
+    status: "removed";
+} | {
+    status: "failed";
+    message: string;
+};
+interface PluginMachineProviderDefinition<S extends PluginMachineProviderInputsSchema = PluginMachineProviderInputsSchema> {
+    id: string;
+    displayName: string;
+    /** One line telling a user what choosing this provider gets them, shown wherever a machine is added. */
+    description: string;
+    /** Provider glyph, declared icon, or plugin-relative icon path. */
+    icon: string;
+    ephemeral?: boolean;
+    /** Persisted and readable by every plugin. Store secret references, never secrets. */
+    inputs?: S;
+    availability?(): PluginMachineProviderAvailability | Promise<PluginMachineProviderAvailability>;
+    validate?(context: PluginMachineProviderValidateContext<S>): PluginMachineValidateDecision | Promise<PluginMachineValidateDecision>;
+    create(context: PluginMachineProviderCreateContext<S>): Promise<PluginMachineProviderCreateResult>;
+    /** Reconcile and remove an uncertain allocation by durable key without creating or bootstrapping. Return failed while allocation intent remains unresolved. */
+    reconcileCleanup(context: {
+        key: string;
+        report: PluginMachineProviderProgress;
+        signal: AbortSignal;
+    }): Promise<PluginMachineProviderRemoveResult>;
+    suspend?(context: PluginMachineProviderResourceLifecycleContext): Promise<PluginMachineProviderResourceResult>;
+    resume?(context: PluginMachineProviderResourceLifecycleContext): Promise<PluginMachineProviderResourceResult>;
+    remove(context: PluginMachineProviderRemoveContext): Promise<PluginMachineProviderRemoveResult>;
+}
 
 /** Input-form entry: a path, or a path with options. */
 declare const providerNativeRootInputSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
@@ -74,10 +148,14 @@ declare const environmentSchema: z.ZodObject<{
     environmentProviderInstanceKey: z.ZodNullable<z.ZodString>;
     environmentProviderSelection: z.ZodNullable<z.ZodObject<{
         inputs: z.ZodNullable<z.ZodType<JsonValue$1, unknown, z.core.$ZodTypeInternals<JsonValue$1, unknown>>>;
-        machine: z.ZodObject<{
+        machine: z.ZodDiscriminatedUnion<[z.ZodObject<{
             hostId: z.ZodString;
             type: z.ZodLiteral<"existing">;
-        }, z.core.$strip>;
+        }, z.core.$strip>, z.ZodObject<{
+            inputs: z.ZodNullable<z.ZodType<JsonValue$1, unknown, z.core.$ZodTypeInternals<JsonValue$1, unknown>>>;
+            machineProviderId: z.ZodString;
+            type: z.ZodLiteral<"new">;
+        }, z.core.$strip>], "type">;
     }, z.core.$strip>>;
     hostId: z.ZodString;
     id: z.ZodString;
@@ -127,6 +205,29 @@ declare const hostSchema: z.ZodObject<{
     id: z.ZodString;
     lastRejectedProtocolVersion: z.ZodNullable<z.ZodNumber>;
     lastSeenAt: z.ZodNullable<z.ZodNumber>;
+    lifecycle: z.ZodObject<{
+        message: z.ZodNullable<z.ZodString>;
+        pendingLog: z.ZodString;
+        phase: z.ZodEnum<{
+            active: "active";
+            creating: "creating";
+            destroyed: "destroyed";
+            removing: "removing";
+            resuming: "resuming";
+            suspended: "suspended";
+            suspending: "suspending";
+        }>;
+        suspendedAt: z.ZodNullable<z.ZodNumber>;
+        teardown: z.ZodNullable<z.ZodObject<{
+            attempt: z.ZodNumber;
+            status: z.ZodEnum<{
+                failed: "failed";
+                removed: "removed";
+                running: "running";
+            }>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    machineProviderId: z.ZodNullable<z.ZodString>;
     maxPermissionMode: z.ZodEnum<{
         "accept-edits": "accept-edits";
         auto: "auto";
@@ -138,6 +239,7 @@ declare const hostSchema: z.ZodObject<{
         disconnected: "disconnected";
     }>;
     type: z.ZodEnum<{
+        ephemeral: "ephemeral";
         persistent: "persistent";
     }>;
     updatedAt: z.ZodNumber;
@@ -221,8 +323,10 @@ type Checkout<R> = R extends {
     gitCheckout: true;
 } ? {
     path: string;
+    experimental_ownsPath: boolean;
 } : {
     path: string;
+    experimental_ownsPath: boolean;
 } | null;
 type InputsValue<S> = S extends StandardSchemaV1$1 ? StandardSchemaV1InferOutput<S> : null;
 /** Attempt-scoped updates; core persists each update before this call returns. */
@@ -306,8 +410,10 @@ interface PluginEnvironmentProviderPolicy {
 interface PluginEnvironmentProviderDefinition<R extends PluginEnvironmentProviderRequirements$1 = PluginEnvironmentProviderRequirements$1, S extends PluginEnvironmentProviderInputsSchema = PluginEnvironmentProviderInputsSchema> {
     id: string;
     displayName: string;
+    /** Short explanation shown in environment choices. */
+    description: string;
     /** Host glyph, plugin-relative icon path, or this plugin’s declared namespaced icon. */
-    icon?: string;
+    icon: string;
     requires?: R;
     inputs?: S;
     policy?: Partial<PluginEnvironmentProviderPolicy>;
@@ -318,6 +424,30 @@ interface PluginEnvironmentProviderDefinition<R extends PluginEnvironmentProvide
     remove(context: PluginEnvironmentProviderRemoveContext): Promise<PluginEnvironmentProviderRemoveResult>;
 }
 
+interface MachineExecutorRequest {
+    command: string[];
+    timeoutMs: number;
+    signal: AbortSignal;
+    stdin: string;
+    onOutput: (chunk: string) => void;
+}
+interface MachineExecutor {
+    exec(request: MachineExecutorRequest): Promise<{
+        exitCode: number;
+    }>;
+}
+interface MachineBootstrapRequest {
+    key: string;
+    executor: MachineExecutor;
+    report: PluginMachineProviderProgress;
+    signal: AbortSignal;
+}
+interface MachineBootstrapApi {
+    bootstrap(request: MachineBootstrapRequest): Promise<{
+        hostId: string;
+    }>;
+}
+
 /**
  * A value that survives a JSON round trip without coercion or data loss.
  *
@@ -389,6 +519,36 @@ interface PluginEnvironmentProviderRequirements {
  * supplied pathKey. Provider ids are unique across running plugins.
  */
 type PluginEnvironmentProviderDeclaration<Requires extends PluginEnvironmentProviderRequirements = PluginEnvironmentProviderRequirements, Inputs extends PluginEnvironmentProviderInputsSchema = PluginEnvironmentProviderInputsSchema> = PluginEnvironmentProviderDefinition<Requires, Inputs>;
+type PluginMachineProviderDeclaration<Inputs extends PluginMachineProviderInputsSchema = PluginMachineProviderInputsSchema> = PluginMachineProviderDefinition<Inputs>;
+interface ServerAccessGrant {
+    id: string;
+    serverUrl: string;
+    headers?: Record<string, string>;
+}
+interface ServerAccessProviderDeclaration {
+    id: string;
+    displayName: string;
+    description: string;
+    availability(): (PluginMachineProviderAvailability & {
+        serverUrl?: string;
+    }) | Promise<PluginMachineProviderAvailability & {
+        serverUrl?: string;
+    }>;
+    acquire(context: {
+        key: string;
+        hostId: string;
+        signal: AbortSignal;
+    }): Promise<ServerAccessGrant | {
+        status: "failed";
+        message: string;
+    }>;
+    release(context: {
+        key: string;
+        hostId: string;
+        /** Null when acquisition was interrupted before a grant was returned. Reconcile using key and hostId. */
+        grantId: string | null;
+    }): Promise<void>;
+}
 /**
  * Permission modes a provider can run a session in — BB's own permission
  * vocabulary, ordered least ("accept-edits") to most ("full") privileged.
@@ -761,9 +921,19 @@ declare const ENVIRONMENT_PROVIDER_REQUIREMENT_NAMES: readonly ["projectCheckout
 type NormalizedPluginEnvironmentProviderRequirements = {
     [K in (typeof ENVIRONMENT_PROVIDER_REQUIREMENT_NAMES)[number]]: boolean;
 };
+declare const environmentCompositionSchema: z.ZodObject<{
+    description: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | null, string | undefined>>;
+    displayName: z.ZodString;
+    environmentProviderId: z.ZodString;
+    icon: z.ZodPipe<z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>, z.ZodTransform<string | null, string | undefined>>;
+    id: z.ZodString;
+    machineProviderId: z.ZodString;
+}, z.core.$strict>;
+type NormalizedPluginEnvironmentComposition = z.infer<typeof environmentCompositionSchema>;
 interface NormalizedPluginEnvironmentProvider {
     id: string;
     displayName: string;
+    description: string | null;
     icon: string | null;
     requires: NormalizedPluginEnvironmentProviderRequirements;
     inputs: StandardSchemaV1 | null;
@@ -774,14 +944,24 @@ interface NormalizedPluginEnvironmentProvider {
     remove: PluginEnvironmentProviderDeclaration["remove"];
     policy: PluginEnvironmentProviderPolicy;
 }
+interface NormalizedPluginMachineProvider {
+    id: string;
+    displayName: string;
+    description: string;
+    icon: string;
+    ephemeral: boolean;
+    inputs: StandardSchemaV1 | null;
+    inputsJsonSchema: JsonValue | null;
+    availability: NonNullable<PluginMachineProviderDeclaration["availability"]> | null;
+    validate: NonNullable<PluginMachineProviderDeclaration["validate"]> | null;
+    reconcileCleanup: PluginMachineProviderDeclaration["reconcileCleanup"];
+    create: PluginMachineProviderDeclaration["create"];
+    suspend: NonNullable<PluginMachineProviderDeclaration["suspend"]> | null;
+    resume: NonNullable<PluginMachineProviderDeclaration["resume"]> | null;
+    remove: PluginMachineProviderDeclaration["remove"];
+}
 
 type BbSdk = BbPluginApi["sdk"];
-/**
- * Recordable `bb.sdk` stand-in for {@link createFakePluginHost}. Every call
- * through the fake is recorded (post plugin-attribution defaulting, so
- * assertions see what the server would receive); calls without a stubbed
- * implementation throw with a message naming the exact path to stub.
- */
 /** One recorded `bb.sdk` call. `path` is dot-joined, e.g. "threads.spawn". */
 interface FakeSdkCall {
     path: string;
@@ -802,13 +982,24 @@ type FakeSdkOverrideTree<T> = {
 };
 type FakeSdkOverrides = FakeSdkOverrideTree<BbSdk>;
 interface FakeSdkHarness {
-    /** Every `bb.sdk` call in order, including ones whose stub threw. */
+    /**
+     * Every `bb.sdk` call in order, including ones whose stub threw. Calls
+     * rejected by argument validation are not recorded.
+     */
     readonly calls: FakeSdkCall[];
     /** Argument lists of the calls to one dot-joined path. */
     callsTo(path: string): unknown[][];
     /** Add or replace one method's implementation after creation. */
     stub(path: string, implementation: (...args: never[]) => unknown): void;
 }
+/**
+ * Recordable `bb.sdk` stand-in for {@link createFakePluginHost}. Calls are
+ * recorded after the plugin-bound normalization the server applies, so
+ * assertions see what the server would receive. Arguments the real SDK
+ * rejects before sending, such as invalid `pluginMetadata`, return a rejected
+ * promise and are not recorded. Calls without a stubbed implementation throw
+ * with a message naming the exact path to stub.
+ */
 declare function createFakeSdk(options: {
     pluginId: string;
     overrides?: FakeSdkOverrides;
@@ -955,7 +1146,10 @@ interface FakePluginRegistrations {
     hooks: {
         [K in PluginHookName]: PluginHookHandler<K> | null;
     };
+    environmentCompositions: ReadonlyMap<string, NormalizedPluginEnvironmentComposition>;
     environmentProviders: ReadonlyMap<string, NormalizedPluginEnvironmentProvider>;
+    machineProviders: ReadonlyMap<string, NormalizedPluginMachineProvider>;
+    serverAccessProviders: ReadonlyMap<string, ServerAccessProviderDeclaration>;
     mentionProviders: FakeMentionProviderRecord[];
     /** Live provider registrations from `bb.providers.register`
      * (normalized declarations, registration order; dispose removes). */
@@ -1060,7 +1254,10 @@ interface FakePluginBehaviorDrivers {
     callAgentTool(name: string, input: unknown, ctx?: Partial<PluginAgentToolContext>): Promise<PluginAgentToolResult>;
     /** Evaluate `bb.agents.configure` with production validation/fail-closed
      * semantics. With no callback, every registered tool/declared test skill is
-     * selected. Callback failures are logged and return empty selections. */
+     * selected. The callback receives a copy of `context` whose `pluginMetadata`
+     * is a validated, deep-frozen clone; invalid metadata rejects instead of
+     * reaching the callback. Callback failures are logged and return empty
+     * selections. */
     resolveAgentConfiguration(context: PluginAgentConfigurationContext): Promise<{
         tools: FakeAgentToolRecord[];
         skills: string[];
@@ -1095,6 +1292,8 @@ interface FakePluginHarness extends FakePluginInspectionState, FakePluginBehavio
     readonly lifecycle: FakePluginLifecycleControls;
 }
 interface CreateFakePluginHostOptions {
+    machineBootstrap?: MachineBootstrapApi;
+    machineResource?: (hostId: string) => Promise<JsonValue$2 | null>;
     /** Defaults to "test-plugin". */
     pluginId?: string;
     /**
@@ -1156,6 +1355,7 @@ type ThreadResponse = PluginThreadEventPayloads["thread.created"]["thread"];
 type QueueEntry = PluginThreadEventPayloads["message.queued"]["entry"];
 type TurnFailedEvent = PluginThreadEventPayloads["turn.failed"];
 type PluginAgentConfigurationContextOverrides = {
+    pluginMetadata?: PluginAgentConfigurationContext["pluginMetadata"];
     thread?: Partial<PluginAgentConfigurationContext["thread"]>;
     project?: Partial<PluginAgentConfigurationContext["project"]>;
     environment?: Partial<PluginAgentConfigurationContext["environment"]>;