@get-bb/plugin-sdk 0.4.56 → 0.4.87

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

@@ -6,7 +6,8 @@
 // and read the real source: https://github.com/get-bb/bb
 
 import { z } from 'zod';
-import { StandardSchemaV1 as StandardSchemaV1$1, PluginEnvironmentProviderRequirements as PluginEnvironmentProviderRequirements$1, StandardSchemaV1InferOutput, PluginEnvironmentValidateDecision, JsonValue as JsonValue$2 } from '@get-bb/plugin-sdk';
+import { StandardSchemaV1 as StandardSchemaV1$1, PluginEnvironmentProviderRequirements as PluginEnvironmentProviderRequirements$1, StandardSchemaV1InferOutput, PluginEnvironmentValidateDecision, JsonValue as JsonValue$2, PluginMachineValidateDecision } from '@get-bb/plugin-sdk';
+import Database from 'better-sqlite3';
 
 /** Input-form entry: a path, or a path with options. */
 declare const providerNativeRootInputSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
@@ -74,10 +75,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 +132,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 +166,7 @@ declare const hostSchema: z.ZodObject<{
         disconnected: "disconnected";
     }>;
     type: z.ZodEnum<{
+        ephemeral: "ephemeral";
         persistent: "persistent";
     }>;
     updatedAt: z.ZodNumber;
@@ -492,10 +521,12 @@ type Checkout<R> = R extends {
     gitCheckout: true;
 } ? {
     path: string;
+    experimental_ownsPath: boolean;
 } : {
     path: string;
+    experimental_ownsPath: boolean;
 } | null;
-type InputsValue<S> = S extends StandardSchemaV1$1 ? StandardSchemaV1InferOutput<S> : null;
+type InputsValue$1<S> = S extends StandardSchemaV1$1 ? StandardSchemaV1InferOutput<S> : null;
 /** Attempt-scoped updates; core persists each update before this call returns. */
 interface PluginEnvironmentProviderProgress {
     step(text: string): void;
@@ -506,7 +537,7 @@ interface PluginEnvironmentProviderValidateContext<R extends PluginEnvironmentPr
     host: Host;
     projectCheckout: Checkout<R>;
     gitRemote: Fact<R, "gitRemote", string>;
-    inputs: InputsValue<S>;
+    inputs: InputsValue$1<S>;
 }
 interface PluginEnvironmentProviderAvailabilityContext {
     project: Project;
@@ -577,8 +608,10 @@ interface PluginEnvironmentProviderPolicy {
 interface PluginEnvironmentProviderDefinition<R extends PluginEnvironmentProviderRequirements$1 = PluginEnvironmentProviderRequirements$1, S extends PluginEnvironmentProviderInputsSchema = PluginEnvironmentProviderInputsSchema> {
     id: string;
     displayName: string;
+    /** Short explanation shown in environment choices. */
+    description: string;
     /** Host glyph, plugin-relative icon path, or this plugin’s declared namespaced icon. */
-    icon?: string;
+    icon: string;
     requires?: R;
     inputs?: S;
     policy?: Partial<PluginEnvironmentProviderPolicy>;
@@ -591,6 +624,80 @@ interface PluginEnvironmentProviderDefinition<R extends PluginEnvironmentProvide
 
 declare const RESERVED_BB_CLI_COMMANDS: readonly string[];
 
+type PluginMachineProviderResource = Exclude<JsonValue$2, null>;
+type PluginMachineProviderInputsSchema = StandardSchemaV1$1 | undefined;
+type InputsValue<S> = S extends StandardSchemaV1$1 ? StandardSchemaV1InferOutput<S> : null;
+interface PluginMachineProviderProgress {
+    step(text: string): void;
+    log(text: string): void;
+}
+type PluginMachineProviderAvailability = {
+    status: "available";
+} | {
+    status: "setup-required";
+    message: string;
+} | {
+    status: "unavailable";
+    message: string;
+};
+type PluginMachineProviderValidateContext<S extends PluginMachineProviderInputsSchema = PluginMachineProviderInputsSchema> = {
+    inputs: InputsValue<S>;
+};
+interface PluginMachineProviderLifecycleContext {
+    checkpoint(resource: PluginMachineProviderResource): Promise<void>;
+    report: PluginMachineProviderProgress;
+    signal: AbortSignal;
+}
+type PluginMachineProviderCreateContext<S extends PluginMachineProviderInputsSchema = PluginMachineProviderInputsSchema> = PluginMachineProviderValidateContext<S> & PluginMachineProviderLifecycleContext & {
+    key: string;
+    attempt: number;
+};
+type PluginMachineProviderCreateResult = {
+    status: "created";
+    name: string;
+    resource: PluginMachineProviderResource;
+} | {
+    status: "failed";
+    message: string;
+};
+type PluginMachineProviderResourceLifecycleContext = PluginMachineProviderLifecycleContext & {
+    hostId: string;
+    resource: PluginMachineProviderResource;
+};
+type PluginMachineProviderRemoveContext = Omit<PluginMachineProviderResourceLifecycleContext, "checkpoint">;
+interface PluginMachineProviderResourceResult {
+    resource: PluginMachineProviderResource;
+}
+type PluginMachineProviderRemoveResult = {
+    status: "removed";
+} | {
+    status: "failed";
+    message: string;
+};
+interface PluginMachineProviderDefinition<S extends PluginMachineProviderInputsSchema = PluginMachineProviderInputsSchema> {
+    id: string;
+    displayName: string;
+    /** One line telling a user what choosing this provider gets them, shown wherever a machine is added. */
+    description: string;
+    /** Provider glyph, declared icon, or plugin-relative icon path. */
+    icon: string;
+    ephemeral?: boolean;
+    /** Persisted and readable by every plugin. Store secret references, never secrets. */
+    inputs?: S;
+    availability?(): PluginMachineProviderAvailability | Promise<PluginMachineProviderAvailability>;
+    validate?(context: PluginMachineProviderValidateContext<S>): PluginMachineValidateDecision | Promise<PluginMachineValidateDecision>;
+    create(context: PluginMachineProviderCreateContext<S>): Promise<PluginMachineProviderCreateResult>;
+    /** Reconcile and remove an uncertain allocation by durable key without creating or bootstrapping. Return failed while allocation intent remains unresolved. */
+    reconcileCleanup(context: {
+        key: string;
+        report: PluginMachineProviderProgress;
+        signal: AbortSignal;
+    }): Promise<PluginMachineProviderRemoveResult>;
+    suspend?(context: PluginMachineProviderResourceLifecycleContext): Promise<PluginMachineProviderResourceResult>;
+    resume?(context: PluginMachineProviderResourceLifecycleContext): Promise<PluginMachineProviderResourceResult>;
+    remove(context: PluginMachineProviderRemoveContext): Promise<PluginMachineProviderRemoveResult>;
+}
+
 /**
  * A value that survives a JSON round trip without coercion or data loss.
  *
@@ -601,6 +708,21 @@ type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
 
+/** A JSON-safe path segment reported by a Standard Schema validation issue. */
+type PluginRpcIssuePathSegment = string | number;
+/** Validator-neutral validation detail carried by an RPC error envelope. */
+interface PluginRpcValidationIssue {
+    message: string;
+    path?: PluginRpcIssuePathSegment[];
+}
+/** Stable wire error categories for plugin RPC. */
+type PluginRpcErrorCode = "handler_error" | "invalid_input" | "invalid_json" | "invalid_output" | "non_json_result" | "unknown_method";
+/** Structured RPC failure returned as `{ ok: false, error }`. */
+interface PluginRpcError {
+    code: PluginRpcErrorCode;
+    message: string;
+    issues?: PluginRpcValidationIssue[];
+}
 /**
  * The validator-neutral subset of Standard Schema v1 used by plugin contracts.
  * Zod 4 schemas implement this interface directly; other validators can do
@@ -629,10 +751,6 @@ interface StandardSchemaV1Issue {
         readonly key: PropertyKey;
     })[];
 }
-interface PluginRpcMethodContract<InputSchema extends StandardSchemaV1 = StandardSchemaV1, OutputSchema extends StandardSchemaV1 = StandardSchemaV1> {
-    readonly input: InputSchema;
-    readonly output: OutputSchema;
-}
 
 type PluginSettingDescriptor = {
     type: "string";
@@ -710,6 +828,36 @@ interface PluginEnvironmentProviderRequirements {
  * supplied pathKey. Provider ids are unique across running plugins.
  */
 type PluginEnvironmentProviderDeclaration<Requires extends PluginEnvironmentProviderRequirements = PluginEnvironmentProviderRequirements, Inputs extends PluginEnvironmentProviderInputsSchema = PluginEnvironmentProviderInputsSchema> = PluginEnvironmentProviderDefinition<Requires, Inputs>;
+type PluginMachineProviderDeclaration<Inputs extends PluginMachineProviderInputsSchema = PluginMachineProviderInputsSchema> = PluginMachineProviderDefinition<Inputs>;
+interface ServerAccessGrant {
+    id: string;
+    serverUrl: string;
+    headers?: Record<string, string>;
+}
+interface ServerAccessProviderDeclaration {
+    id: string;
+    displayName: string;
+    description: string;
+    availability(): (PluginMachineProviderAvailability & {
+        serverUrl?: string;
+    }) | Promise<PluginMachineProviderAvailability & {
+        serverUrl?: string;
+    }>;
+    acquire(context: {
+        key: string;
+        hostId: string;
+        signal: AbortSignal;
+    }): Promise<ServerAccessGrant | {
+        status: "failed";
+        message: string;
+    }>;
+    release(context: {
+        key: string;
+        hostId: string;
+        /** Null when acquisition was interrupted before a grant was returned. Reconcile using key and hostId. */
+        grantId: string | null;
+    }): Promise<void>;
+}
 /**
  * Where a thread is going to run, as far as core knows at the checkpoint.
  * Before provisioning attaches an environment this is the start intent the
@@ -726,6 +874,10 @@ type PluginDispatchEnvironmentIntent = {
     machine: {
         type: "existing";
         hostId: string;
+    } | {
+        type: "new";
+        machineProviderId: string;
+        inputs: JsonValue | null;
     };
     inputs: JsonValue | null;
 };
@@ -881,6 +1033,33 @@ interface PluginHookSignatures {
 }
 type PluginHookName = keyof PluginHookSignatures;
 type PluginHookHandler<K extends PluginHookName> = (context: PluginHookSignatures[K]["context"]) => PluginHookSignatures[K]["decision"] | Promise<PluginHookSignatures[K]["decision"]>;
+type PluginHttpAuthMode = "local" | "none" | "token";
+interface PluginCliCommandInfo {
+    name: string;
+    summary: string;
+    usage: string;
+}
+/** Context forwarded from the invoking CLI when known; all fields optional. */
+interface PluginCliContext {
+    cwd?: string;
+    threadId?: string;
+    projectId?: string;
+    /** Aborted when the invoking CLI HTTP request disconnects. */
+    signal?: AbortSignal;
+}
+interface PluginInteractionRequest {
+    threadId: string;
+    rendererId: string;
+    title: string;
+    payload: JsonValue;
+    /** Defaults to ten minutes; capped at one hour. */
+    timeoutMs?: number;
+}
+interface PluginCliResult {
+    exitCode: number;
+    stdout?: string;
+    stderr?: string;
+}
 interface PluginCliOutputLimitError {
     code: "plugin_cli_output_too_large";
     message: string;
@@ -896,6 +1075,39 @@ interface PluginCliExecutionResult {
     stderr: string;
     error?: PluginCliOutputLimitError;
 }
+interface PluginCliRegistration {
+    /** Preferred top-level command name (`bb <name> …`): lowercase [a-z0-9-]+.
+     * A core collision logs an activation warning and remains available through
+     * `bb plugin run <plugin-id>`. */
+    name: string;
+    summary: string;
+    /** Subcommand metadata rendered in help and the plugin-commands skill
+     * without executing plugin code. Parsing argv is plugin-owned. */
+    commands?: PluginCliCommandInfo[];
+    run(argv: string[], ctx: PluginCliContext): PluginCliResult | Promise<PluginCliResult>;
+}
+/** Per-turn context handed to bb.agents context providers (design §4.4). */
+/** MCP-style content parts a native tool may return (design §4.4). */
+type PluginAgentToolContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+type PluginAgentToolResult = string | {
+    content: PluginAgentToolContentPart[];
+    isError?: boolean;
+};
+/** Per-call context handed to a native tool's execute (design §4.4). */
+interface PluginAgentToolContext {
+    threadId: string;
+    projectId: string;
+    /** The tool-call request's abort signal (aborts if the daemon round-trip
+     * is torn down mid-call). */
+    signal: AbortSignal;
+}
 /**
  * The row title of a plugin tool call while it is pending and once it
  * settled. Each label is capped at 80 characters and rendered as plain text.
@@ -1279,9 +1491,54 @@ interface ExperimentalPluginProviderEnvEntry {
         serverPath: string;
     };
     reason: string;
-    secret: boolean;
 }
 type PluginMentionTrigger = "!" | "#" | "$" | "@" | "~";
+/** Search context handed to a mention provider (design §4.9). `projectId`/
+ * `threadId` are null when the composer has not committed one yet. */
+interface PluginMentionSearchContext {
+    trigger: PluginMentionTrigger;
+    query: string;
+    projectId: string | null;
+    threadId: string | null;
+}
+/** One row a mention provider returns from `search`. `id` is the provider's
+ * own item id — the host namespaces it before it reaches the wire. */
+interface PluginMentionItem {
+    id: string;
+    title: string;
+    subtitle?: string;
+    icon?: string;
+}
+interface PluginMentionProviderRegistration {
+    /** Unique within this plugin: [a-zA-Z0-9_-]+ (no ":" — the host composes
+     * wire item ids as "<providerId>:<itemId>"). */
+    id: string;
+    /** Section label shown above this provider's rows in the mention menu. */
+    label: string;
+    /**
+     * Composer trigger characters this provider should answer. Omit to use the
+     * default `@` mention trigger. Valid triggers are `@`, `#`, `$`, `!`, and `~`.
+     */
+    triggers?: readonly PluginMentionTrigger[];
+    /**
+     * Runs server-side as the user types after one of this provider's triggers
+     * in the composer. Each call is time-boxed (2s) and failure-isolated: a slow
+     * or throwing provider contributes an empty list — it can never break the
+     * mention menu.
+     */
+    search(ctx: PluginMentionSearchContext): PluginMentionItem[] | Promise<PluginMentionItem[]>;
+    /**
+     * Resolves one picked item into agent context, called once per unique
+     * item at message send time. The returned `context` is attached to the
+     * message as an agent-visible (user-hidden) prompt input. Throwing blocks
+     * the send with a visible error.
+     */
+    resolve(itemId: string): {
+        context: string;
+    } | Promise<{
+        context: string;
+    }>;
+}
 /**
  * What a plugin's AI service does. `inference` answers bb's server-side helper
  * completions (thread titles, commit messages: a prompt and a JSON Schema in,
@@ -1314,21 +1571,11 @@ declare function pluginCliCollisionWarning(pluginId: string, commandName: string
 declare const RESERVED_AGENT_TOOL_NAMES: readonly string[];
 /** JSON values ≤256KB; larger writes are rejected with a clear error. */
 declare const KV_VALUE_MAX_BYTES: number;
-declare const PLUGIN_HTTP_METHODS: ReadonlySet<string>;
-declare const RPC_METHOD_PATTERN: RegExp;
-declare const BACKGROUND_NAME_PATTERN: RegExp;
-declare const CLI_COMMAND_NAME_PATTERN: RegExp;
-declare const AGENT_TOOL_NAME_PATTERN: RegExp;
 declare const PLUGIN_PROVIDER_ENV_NAME_PATTERN: RegExp;
 declare const PLUGIN_PROVIDER_ENV_MAX_ENTRIES = 32;
 declare function validatePluginProviderEnvEntries(value: unknown): ExperimentalPluginProviderEnvEntry[];
-declare const PLUGIN_AGENT_STATIC_INSTRUCTIONS_MAX_CHARS = 4096;
 /** Status labels ride on every tool-call event and share one timeline row. */
 declare const PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS = 80;
-declare const PLUGIN_AGENT_SELECTION_MAX_IDS = 256;
-declare const PLUGIN_AGENT_DYNAMIC_INSTRUCTIONS_MAX_CHARS = 4096;
-declare const PLUGIN_AGENT_TOOL_PARAMETERS_MAX_BYTES: number;
-declare const MENTION_PROVIDER_ID_PATTERN: RegExp;
 declare const PROVIDER_ID_PATTERN: RegExp;
 declare const PLUGIN_PROVIDER_BRIDGE_OPTIONS_MAX_BYTES: number;
 declare const SETTING_KEY_PATTERN: RegExp;
@@ -1340,9 +1587,9 @@ declare const SETTING_KEY_PATTERN: RegExp;
 declare function registerSettingDescriptors(target: PluginSettingDescriptors, added: Record<string, unknown>): PluginSettingDescriptors;
 /** Validate a settings update. `null` means unset. */
 declare function validateSettingsUpdate(descriptors: PluginSettingDescriptors, values: Record<string, unknown>): string[];
+declare function coerceStoredPluginSettingValue(descriptor: PluginSettingDescriptor, value: unknown): PluginSettingValue | undefined;
 declare const PLUGIN_MENTION_TRIGGER_VALUES: readonly ["@", "#", "$", "!", "~"];
 declare function isPluginMentionTrigger(value: unknown): value is PluginMentionTrigger;
-declare function normalizeMentionProviderTriggers(providerId: string, triggers: unknown): readonly PluginMentionTrigger[];
 declare const PLUGIN_PROVIDER_DISPLAY_NAME_MAX_CHARS = 80;
 declare const PLUGIN_PROVIDER_PERMISSION_MODE_VALUES: readonly ["accept-edits", "auto", "full"];
 declare const PLUGIN_PROVIDER_REASONING_LEVEL_VALUES: readonly ["none", "low", "medium", "high", "xhigh", "ultracode", "max", "ultra"];
@@ -1444,30 +1691,6 @@ declare function deriveValidatedProviderOptions(args: {
     context: Parameters<NonNullable<PluginProviderDeclaration["deriveProviderOptions"]>>[0];
 }): Readonly<Record<string, JsonValue>>;
 declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
-declare function readRpcMethodContract(method: string, value: unknown): PluginRpcMethodContract;
-/** Duck-typed zod detection: plugin sources may carry their own zod copy,
- * so instanceof is useless — anything with safeParse is treated as zod. */
-type ZodSchemaLike = {
-    safeParse: z.ZodType["safeParse"];
-    toJSONSchema?: z.ZodType["toJSONSchema"];
-};
-declare function isZodSchemaLike(value: unknown): value is ZodSchemaLike;
-declare function zodSchemaToJsonSchema(schema: ZodSchemaLike): unknown;
-/**
- * Reject recursive local references before a tool schema reaches a provider.
- * Some providers reject the complete tool list when any one schema contains a
- * recursive `$ref`, so this is a shared production/fake-host boundary rule.
- */
-declare function assertNoRecursiveJsonSchemaReferences(schema: unknown, subject: string): void;
-/**
- * Reject the fields a registration never reads. Renamed fields get the
- * message above; any other `experimental_` field is unknown (the same
- * rule configure() output follows in the plugin service). The production
- * host and the fake host both call this before parsing `presentation`, so
- * a registration built against an older SDK fails a plugin's own unit test
- * with the message bb would give it.
- */
-declare function rejectStaleAgentToolFields(toolName: string, tool: object): void;
 /**
  * The declared shape of `presentation`, copied field by field so
  * a plugin's object cannot smuggle prototypes or extra markup into the
@@ -1479,7 +1702,6 @@ 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;
 /**
  * Adopt the value a plugin HTTP route handler returned.
@@ -1511,8 +1733,6 @@ declare function adoptHttpRouteResponse(value: unknown): Response;
 declare function undeclaredIconProblem(pluginId: string, declaredIconNames: ReadonlySet<string>, glyph: string): string | null;
 /** `bb.providers.register` refusal for an icon {@link undeclaredIconProblem} rejects. */
 declare function providerIconRefusalMessage(providerId: string, problem: string): string;
-/** `bb.agents.registerTool` refusal for a glyph {@link undeclaredIconProblem} rejects. */
-declare function agentToolIconRefusalMessage(toolName: string, problem: string): string;
 /**
  * `bb.providers.register` refusal for a plugin whose manifest declares no
  * `bb.host` entry: a declaration is metadata, and the bridge it runs on is
@@ -1539,13 +1759,24 @@ declare function storePluginHook<K extends PluginHookName>(records: {
 declare function pluginHookAlreadyRegisteredMessage(hook: PluginHookName): string;
 declare const ENVIRONMENT_PROVIDER_ID_PATTERN: RegExp;
 declare const ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS = 80;
+declare const ENVIRONMENT_PROVIDER_DESCRIPTION_MAX_CHARS = 200;
 declare const ENVIRONMENT_PROVIDER_REQUIREMENT_NAMES: readonly ["projectCheckout", "gitCheckout", "gitRemote", "projectless"];
 type NormalizedPluginEnvironmentProviderRequirements = {
     [K in (typeof ENVIRONMENT_PROVIDER_REQUIREMENT_NAMES)[number]]: boolean;
 };
+declare const environmentCompositionSchema: z.ZodObject<{
+    description: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | null, string | undefined>>;
+    displayName: z.ZodString;
+    environmentProviderId: z.ZodString;
+    icon: z.ZodPipe<z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>, z.ZodTransform<string | null, string | undefined>>;
+    id: z.ZodString;
+    machineProviderId: z.ZodString;
+}, z.core.$strict>;
+type NormalizedPluginEnvironmentComposition = z.infer<typeof environmentCompositionSchema>;
 interface NormalizedPluginEnvironmentProvider {
     id: string;
     displayName: string;
+    description: string | null;
     icon: string | null;
     requires: NormalizedPluginEnvironmentProviderRequirements;
     inputs: StandardSchemaV1 | null;
@@ -1557,7 +1788,130 @@ interface NormalizedPluginEnvironmentProvider {
     policy: PluginEnvironmentProviderPolicy;
 }
 declare function validatePluginEnvironmentProviderDeclaration(declaration: PluginEnvironmentProviderDeclaration): NormalizedPluginEnvironmentProvider;
-declare const MACHINE_PROVIDER_REQUIREMENT_NAMES: readonly ["gitRemote"];
+declare const MACHINE_PROVIDER_DESCRIPTION_MAX_CHARS = 200;
+interface NormalizedPluginMachineProvider {
+    id: string;
+    displayName: string;
+    description: string;
+    icon: string;
+    ephemeral: boolean;
+    inputs: StandardSchemaV1 | null;
+    inputsJsonSchema: JsonValue | null;
+    availability: NonNullable<PluginMachineProviderDeclaration["availability"]> | null;
+    validate: NonNullable<PluginMachineProviderDeclaration["validate"]> | null;
+    reconcileCleanup: PluginMachineProviderDeclaration["reconcileCleanup"];
+    create: PluginMachineProviderDeclaration["create"];
+    suspend: NonNullable<PluginMachineProviderDeclaration["suspend"]> | null;
+    resume: NonNullable<PluginMachineProviderDeclaration["resume"]> | null;
+    remove: PluginMachineProviderDeclaration["remove"];
+}
+declare function validatePluginMachineProviderDeclaration(declaration: PluginMachineProviderDeclaration): NormalizedPluginMachineProvider;
+declare function validateServerAccessProviderDeclaration(declaration: ServerAccessProviderDeclaration): ServerAccessProviderDeclaration;
+declare function runPluginStorageMigrations(database: Database.Database, statements: string[]): void;
+declare function normalizeHttpRouteRegistration(method: string, path: string, handler: unknown, opts: {
+    auth?: PluginHttpAuthMode;
+} | undefined, existingRoutes: readonly {
+    method: string;
+    path: string;
+}[]): {
+    method: string;
+    path: string;
+    auth: PluginHttpAuthMode;
+};
+declare function normalizeWebSocketRouteRegistration(path: string, handler: unknown, opts: {
+    auth?: PluginHttpAuthMode;
+} | undefined, existingRoutes: readonly {
+    path: string;
+}[]): {
+    path: string;
+    auth: PluginHttpAuthMode;
+};
+type RpcRegistrationRecord = {
+    inputSchema: StandardSchemaV1;
+    outputSchema: StandardSchemaV1;
+    handler: (input: unknown) => unknown;
+};
+declare function normalizeRpcRegistration(contract: unknown, handlers: unknown, registered: ReadonlyMap<string, unknown>): Array<[string, RpcRegistrationRecord]>;
+declare function normalizeRealtimePayload(channel: string, payload: unknown): unknown;
+declare function validateBackgroundServiceRegistration(name: string, service: {
+    start(signal: AbortSignal): void | Promise<void>;
+}, existing: readonly {
+    name: string;
+}[]): {
+    name: string;
+    start: (signal: AbortSignal) => void | Promise<void>;
+};
+declare function validateScheduleRegistration(name: string, cron: string, fn: () => void | Promise<void>, existing: readonly {
+    name: string;
+}[], parseCron: (cron: string) => void): {
+    name: string;
+    cron: string;
+    fn: () => void | Promise<void>;
+};
+declare function normalizeCliRegistration(registration: PluginCliRegistration, alreadyRegistered: boolean): {
+    name: string;
+    summary: string;
+    commands: PluginCliCommandInfo[];
+    run: PluginCliRegistration["run"];
+};
+type AgentToolExecute = (params: unknown, ctx: PluginAgentToolContext) => PluginAgentToolResult | Promise<PluginAgentToolResult>;
+type AgentToolParse = (input: unknown) => {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+declare function normalizeAgentToolRegistration(args: {
+    pluginId: string;
+    declaredIconNames: ReadonlySet<string>;
+    tool: {
+        name: string;
+        description: string;
+        instructions?: string;
+        presentation?: PluginAgentToolPresentation;
+        parameters: unknown;
+        execute(params: never, ctx: PluginAgentToolContext): PluginAgentToolResult | Promise<PluginAgentToolResult>;
+    };
+}): {
+    name: string;
+    description: string;
+    presentation: PluginAgentToolPresentation | null;
+    instructions: string | null;
+    inputSchema: unknown;
+    parse: AgentToolParse;
+    execute: AgentToolExecute;
+};
+declare function normalizeMentionProviderRegistration(provider: PluginMentionProviderRegistration, existing: readonly {
+    id: string;
+}[]): {
+    id: string;
+    label: string;
+    triggers: readonly PluginMentionTrigger[];
+    search: PluginMentionProviderRegistration["search"];
+    resolve: PluginMentionProviderRegistration["resolve"];
+};
+declare function normalizeInteractionRequest(request: PluginInteractionRequest): {
+    threadId: string;
+    rendererId: string;
+    title: string;
+    payload: JsonValue;
+    timeoutMs: number;
+};
+declare function validateProviderEnvContribution(label: "provider environment contribution" | "provider environment health contribution", providerId: string, resolve: unknown, registered: ReadonlyMap<string, unknown>): void;
+declare function normalizePluginAgentConfiguration(args: {
+    knownSkillIds: ReadonlySet<string>;
+    knownToolIds: ReadonlySet<string>;
+    pluginId: string;
+    value: unknown;
+}): {
+    toolIds: string[];
+    toolParameterOverrides: Map<string, Record<string, unknown>>;
+    skillIds: string[];
+    instructions: string | null;
+};
+declare function validateRpcValue(schema: StandardSchemaV1, value: unknown, phase: "input" | "output", fail: (error: PluginRpcError) => never): Promise<unknown>;
+declare function normalizeRpcJsonResult(value: unknown, fail: (error: PluginRpcError) => never): JsonValue;
 
-export { AGENT_TOOL_NAME_PATTERN, BACKGROUND_NAME_PATTERN, CLI_COMMAND_NAME_PATTERN, ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS, ENVIRONMENT_PROVIDER_ID_PATTERN, ENVIRONMENT_PROVIDER_REQUIREMENT_NAMES, KV_VALUE_MAX_BYTES, MACHINE_PROVIDER_REQUIREMENT_NAMES, MENTION_PROVIDER_ID_PATTERN, PLUGIN_AGENT_DYNAMIC_INSTRUCTIONS_MAX_CHARS, PLUGIN_AGENT_SELECTION_MAX_IDS, PLUGIN_AGENT_STATIC_INSTRUCTIONS_MAX_CHARS, PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS, PLUGIN_AGENT_TOOL_PARAMETERS_MAX_BYTES, PLUGIN_HTTP_METHODS, PLUGIN_MENTION_TRIGGER_VALUES, PLUGIN_PROVIDER_BRIDGE_OPTIONS_MAX_BYTES, PLUGIN_PROVIDER_COMPOSER_ACTION_VALUES, PLUGIN_PROVIDER_DISPLAY_NAME_MAX_CHARS, PLUGIN_PROVIDER_ENV_MAX_ENTRIES, PLUGIN_PROVIDER_ENV_NAME_PATTERN, PLUGIN_PROVIDER_PERMISSION_MODE_VALUES, PLUGIN_PROVIDER_REASONING_LEVEL_VALUES, PROVIDER_ID_PATTERN, RESERVED_AGENT_TOOL_NAMES, RESERVED_BB_CLI_COMMANDS, RPC_METHOD_PATTERN, SERVER_DIRECT_AI_SERVICE_IDS, SETTING_KEY_PATTERN, adoptHttpRouteResponse, agentToolIconRefusalMessage, aiServiceAlreadyRegisteredMessage, assertAiServiceRegistrable, assertNoRecursiveJsonSchemaReferences, deriveValidatedProviderOptions, enforcePluginCliOutputLimit, isPluginMentionTrigger, isStandardSchema, isZodSchemaLike, normalizeMentionProviderTriggers, parsePluginAgentToolPresentation, pluginCliCollisionWarning, pluginHookAlreadyRegisteredMessage, providerAlreadyRegisteredMessage, providerIconRefusalMessage, providerWithoutBridgeMessage, readRpcMethodContract, registerSettingDescriptors, rejectStaleAgentToolFields, storePluginHook, summarizeParseIssues, summarizeStandardIssues, undeclaredIconProblem, validatePluginAiServiceDeclaration, validatePluginEnvironmentProviderDeclaration, validatePluginProviderDeclaration, validatePluginProviderEnvEntries, validateSettingsUpdate, zodSchemaToJsonSchema };
-export type { AiServiceHostBinding, NormalizedPluginEnvironmentProvider, NormalizedPluginEnvironmentProviderRequirements, NormalizedPluginProviderDeclaration };
+export { ENVIRONMENT_PROVIDER_DESCRIPTION_MAX_CHARS, ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS, ENVIRONMENT_PROVIDER_ID_PATTERN, ENVIRONMENT_PROVIDER_REQUIREMENT_NAMES, KV_VALUE_MAX_BYTES, MACHINE_PROVIDER_DESCRIPTION_MAX_CHARS, PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS, 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, SERVER_DIRECT_AI_SERVICE_IDS, SETTING_KEY_PATTERN, adoptHttpRouteResponse, aiServiceAlreadyRegisteredMessage, assertAiServiceRegistrable, coerceStoredPluginSettingValue, deriveValidatedProviderOptions, enforcePluginCliOutputLimit, environmentCompositionSchema, isPluginMentionTrigger, isStandardSchema, normalizeAgentToolRegistration, normalizeCliRegistration, normalizeHttpRouteRegistration, normalizeInteractionRequest, normalizeMentionProviderRegistration, normalizePluginAgentConfiguration, normalizeRealtimePayload, normalizeRpcJsonResult, normalizeRpcRegistration, normalizeWebSocketRouteRegistration, parsePluginAgentToolPresentation, pluginCliCollisionWarning, pluginHookAlreadyRegisteredMessage, providerAlreadyRegisteredMessage, providerIconRefusalMessage, providerWithoutBridgeMessage, registerSettingDescriptors, runPluginStorageMigrations, storePluginHook, summarizeStandardIssues, undeclaredIconProblem, validateBackgroundServiceRegistration, validatePluginAiServiceDeclaration, validatePluginEnvironmentProviderDeclaration, validatePluginMachineProviderDeclaration, validatePluginProviderDeclaration, validatePluginProviderEnvEntries, validateProviderEnvContribution, validateRpcValue, validateScheduleRegistration, validateServerAccessProviderDeclaration, validateSettingsUpdate };
+export type { AiServiceHostBinding, NormalizedPluginEnvironmentComposition, NormalizedPluginEnvironmentProvider, NormalizedPluginEnvironmentProviderRequirements, NormalizedPluginMachineProvider, 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, PluginEnvironmentProviderInputsRegistration, 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, ExperimentalIconRegistration, PluginTimelineRendererRegistration, PluginEnvironmentProviderInputsRegistration, PluginMachineProviderInputsRegistration, PluginContentScriptRegistration, PluginAppDefinition } from '@get-bb/plugin-sdk';
 
 type ExperimentalSidebarFooterCommandKind = "close" | "open" | "toggle";
 interface ExperimentalSidebarFooterRuntimeSnapshot {
@@ -36,6 +36,9 @@ interface CollectedCompatibilitySidebarFooterItem {
 }
 type CollectedSidebarFooterItem = CollectedCompatibilitySidebarFooterItem | CollectedManagedSidebarFooterItem;
 declare function adaptSidebarFooterAction(registration: PluginSidebarFooterActionRegistration): CollectedCompatibilitySidebarFooterItem;
+type CollectedPluginProviderIconRegistration = Omit<PluginProviderIconRegistration, "providerKind"> & {
+    providerKind: PluginProviderIconRegistration["providerKind"] | "all";
+};
 /** Validated registrations produced by one plugin app setup execution. */
 interface CollectedPluginAppRegistrations {
     homepageSections: PluginHomepageSectionRegistration[];
@@ -57,9 +60,11 @@ interface CollectedPluginAppRegistrations {
     messageDirectives: PluginMessageDirectiveRegistration[];
     messageActions: PluginMessageActionRegistration[];
     commandPaletteActions: PluginCommandPaletteActionRegistration[];
-    providerIcons: PluginProviderIconRegistration[];
+    providerIcons: CollectedPluginProviderIconRegistration[];
+    icons: ExperimentalIconRegistration[];
     timelineRenderers: PluginTimelineRendererRegistration[];
     environmentProviderInputs: PluginEnvironmentProviderInputsRegistration[];
+    machineProviderInputs: PluginMachineProviderInputsRegistration[];
     contentScripts: PluginContentScriptRegistration[];
 }
 declare function getCollectedSidebarFooterItems(registrations: object): readonly CollectedSidebarFooterItem[] | null;
@@ -72,4 +77,4 @@ declare function getCollectedSidebarFooterItems(registrations: object): readonly
 declare function collectPluginAppRegistrations(definition: PluginAppDefinition, onComposerCustomizationRejected?: (reason: string) => void): CollectedPluginAppRegistrations;
 
 export { adaptSidebarFooterAction, collectPluginAppRegistrations, getCollectedSidebarFooterItems };
-export type { CollectedCompatibilitySidebarFooterItem, CollectedExperimentalSidebarFooterItem, CollectedManagedSidebarFooterItem, CollectedPluginAppRegistrations, CollectedSidebarFooterItem, ExperimentalSidebarFooterCommandKind, ExperimentalSidebarFooterItemRuntime, ExperimentalSidebarFooterRuntimeSnapshot };
+export type { CollectedCompatibilitySidebarFooterItem, CollectedExperimentalSidebarFooterItem, CollectedManagedSidebarFooterItem, CollectedPluginAppRegistrations, CollectedPluginProviderIconRegistration, CollectedSidebarFooterItem, ExperimentalSidebarFooterCommandKind, ExperimentalSidebarFooterItemRuntime, ExperimentalSidebarFooterRuntimeSnapshot };