@get-bb/plugin-sdk 0.4.55 → 0.4.84

package/dist/testing/index.js

@@ -1,16 +1,3 @@
-// src/testing/fake-plugin-host.ts
-import { createHash } from "node:crypto";
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import Database from "better-sqlite3";
-import { CronExpressionParser } from "cron-parser";
-import { Hono } from "hono";
-
-// ../domain/src/plugin-interaction-limits.ts
-var PLUGIN_INTERACTION_MAX_TITLE_LENGTH = 160;
-var PLUGIN_INTERACTION_MAX_PAYLOAD_BYTES = 64 * 1024;
-
 // src/internal/host-policy.ts
 import { z as z4 } from "zod";
 
@@ -286,6 +273,10 @@ var providerNativeRootSetSchema = z3.object({
   resolved: providerResolvedNativeRootsSchema
 }).strict();
 
+// ../domain/src/plugin-interaction-limits.ts
+var PLUGIN_INTERACTION_MAX_TITLE_LENGTH = 160;
+var PLUGIN_INTERACTION_MAX_PAYLOAD_BYTES = 64 * 1024;
+
 // src/backend-contract.ts
 var PLUGIN_CLI_OUTPUT_MAX_BYTES = 1024 * 1024;
 
@@ -319,8 +310,7 @@ var pluginProviderEnvEntrySchema = z4.object({
     z4.string(),
     z4.object({ serverPath: z4.string().startsWith("/") }).strict()
   ]),
-  reason: z4.string(),
-  secret: z4.boolean()
+  reason: z4.string()
 }).strict();
 var pluginProviderEnvEntriesSchema = z4.array(pluginProviderEnvEntrySchema).max(PLUGIN_PROVIDER_ENV_MAX_ENTRIES).superRefine((entries, context) => {
   const names = /* @__PURE__ */ new Set();
@@ -1769,12 +1759,23 @@ function pluginHookAlreadyRegisteredMessage(hook) {
 }
 var ENVIRONMENT_PROVIDER_ID_PATTERN = /^[a-z0-9][a-z0-9-]{1,63}$/;
 var ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS = 80;
+var ENVIRONMENT_PROVIDER_DESCRIPTION_MAX_CHARS = 200;
 var ENVIRONMENT_PROVIDER_REQUIREMENT_NAMES = [
   "projectCheckout",
   "gitCheckout",
   "gitRemote",
   "projectless"
 ];
+var environmentCompositionSchema = z4.object({
+  id: z4.string().regex(ENVIRONMENT_PROVIDER_ID_PATTERN),
+  displayName: z4.string().trim().min(1).max(ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS),
+  description: z4.string().trim().min(1).max(ENVIRONMENT_PROVIDER_DESCRIPTION_MAX_CHARS).optional().transform((value) => value ?? null),
+  icon: z4.string().trim().min(1).transform(
+    (icon) => isPluginOwnedIconPath(icon) ? validateProviderRelativePath(icon, "Composition icon") : icon
+  ).optional().transform((value) => value ?? null),
+  machineProviderId: z4.string().regex(ENVIRONMENT_PROVIDER_ID_PATTERN),
+  environmentProviderId: z4.string().regex(ENVIRONMENT_PROVIDER_ID_PATTERN)
+}).strict();
 function validatePluginEnvironmentProviderDeclaration(declaration) {
   if (typeof declaration !== "object" || declaration === null) {
     throw new Error("environment provider declaration must be an object");
@@ -1791,17 +1792,14 @@ function validatePluginEnvironmentProviderDeclaration(declaration) {
       `environment provider "${id}" needs a displayName of 1-${ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS} characters`
     );
   }
-  const icon = declaration.icon === void 0 ? null : z4.string().min(1).parse(declaration.icon).trim();
-  if (icon !== null) {
-    if (isPluginOwnedIconPath(icon))
-      validateProviderRelativePath(icon, `"${id}" icon`);
-    else if (!isNamespacedGlyph(icon) && /[/\\]/u.test(icon))
-      throw new Error(
-        `environment provider "${id}" icon must be a glyph, declared icon, or plugin-relative path`
-      );
-  }
-  if (icon !== null && icon.length === 0) {
-    throw new Error(`environment provider "${id}" declares an empty icon`);
+  const description = z4.string().trim().min(1).max(ENVIRONMENT_PROVIDER_DESCRIPTION_MAX_CHARS).optional().transform((value) => value ?? null).parse(declaration.description);
+  const icon = z4.string().trim().min(1).optional().transform((value) => value ?? null).parse(declaration.icon);
+  if (icon !== null && isPluginOwnedIconPath(icon)) {
+    validateProviderRelativePath(icon, `"${id}" icon`);
+  } else if (icon !== null && !isNamespacedGlyph(icon) && /[/\\]/u.test(icon)) {
+    throw new Error(
+      `environment provider "${id}" icon must be a glyph, declared icon, or plugin-relative path`
+    );
   }
   const requires = normalizeEnvironmentProviderRequirements(id, declaration);
   const inputs = normalizeEnvironmentProviderInputs(id, declaration);
@@ -1823,6 +1821,7 @@ function validatePluginEnvironmentProviderDeclaration(declaration) {
   return {
     id,
     displayName,
+    description,
     icon,
     requires,
     inputs: inputs === null ? null : inputs.schema,
@@ -1891,6 +1890,115 @@ var environmentProviderPolicySchema = z4.object({
   retireGraceMs: z4.number().int().nonnegative().nullable().default(3e5),
   pathKeys: z4.enum(["per-thread", "per-attempt"]).default("per-thread")
 }).strict();
+var MACHINE_PROVIDER_DESCRIPTION_MAX_CHARS = 200;
+function validatePluginMachineProviderDeclaration(declaration) {
+  if (typeof declaration !== "object" || declaration === null) {
+    throw new Error("machine provider declaration must be an object");
+  }
+  const id = declaration.id;
+  if (typeof id !== "string" || !ENVIRONMENT_PROVIDER_ID_PATTERN.test(id)) {
+    throw new Error(
+      `invalid machine provider id ${JSON.stringify(id)} \u2014 use 2-64 lowercase letters, digits, or "-", starting with a letter or digit`
+    );
+  }
+  const displayName = typeof declaration.displayName === "string" ? declaration.displayName.trim() : "";
+  if (displayName.length === 0 || displayName.length > ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS) {
+    throw new Error(
+      `machine provider "${id}" needs a displayName of 1-${ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS} characters`
+    );
+  }
+  const description = z4.string().trim().min(1).max(MACHINE_PROVIDER_DESCRIPTION_MAX_CHARS).parse(declaration.description);
+  const icon = z4.string().trim().min(1).parse(declaration.icon);
+  if (isPluginOwnedIconPath(icon)) {
+    validateProviderRelativePath(icon, `"${id}" icon`);
+  } else if (!isNamespacedGlyph(icon) && /[/\\]/u.test(icon)) {
+    throw new Error(
+      `machine provider "${id}" icon must be a glyph, declared icon, or plugin-relative path`
+    );
+  }
+  const ephemeral = z4.boolean().default(false).parse(declaration.ephemeral);
+  const inputs = normalizeMachineProviderInputs(id, declaration);
+  if (typeof declaration.create !== "function" || typeof declaration.reconcileCleanup !== "function" || typeof declaration.remove !== "function") {
+    throw new Error(
+      `machine provider "${id}" must declare create, reconcileCleanup and remove functions`
+    );
+  }
+  const hasSuspend = typeof declaration.suspend === "function";
+  const hasResume = typeof declaration.resume === "function";
+  if (hasSuspend !== hasResume) {
+    throw new Error(
+      `machine provider "${id}" must declare suspend and resume together`
+    );
+  }
+  if (declaration.validate !== void 0 && typeof declaration.validate !== "function") {
+    throw new Error(
+      `machine provider "${id}" declares a validate that is not a function`
+    );
+  }
+  if (declaration.availability !== void 0 && typeof declaration.availability !== "function") {
+    throw new Error(
+      `machine provider "${id}" declares availability that is not a function`
+    );
+  }
+  return {
+    id,
+    displayName,
+    description,
+    icon,
+    ephemeral,
+    inputs: inputs === null ? null : inputs.schema,
+    inputsJsonSchema: inputs === null ? null : inputs.jsonSchema,
+    availability: declaration.availability ?? null,
+    validate: declaration.validate ?? null,
+    reconcileCleanup: declaration.reconcileCleanup,
+    create: declaration.create,
+    suspend: declaration.suspend ?? null,
+    resume: declaration.resume ?? null,
+    remove: declaration.remove
+  };
+}
+function normalizeMachineProviderInputs(id, declaration) {
+  const inputs = declaration.inputs;
+  if (inputs === void 0) return null;
+  if (!isStandardSchema(inputs)) {
+    throw new Error(
+      `machine provider "${id}" declares an inputs that is not a Standard Schema v1 validator`
+    );
+  }
+  let converted;
+  try {
+    converted = JSON.parse(JSON.stringify(standardSchemaToJsonSchema(inputs)));
+  } catch (error) {
+    throw new Error(
+      `machine provider "${id}" declares an inputs validator that cannot be published as JSON Schema (${error instanceof Error ? error.message : String(error)}) \u2014 declare it with zod 4 or a validator exposing toJSONSchema()`
+    );
+  }
+  const jsonSchema = jsonValueSchema.safeParse(converted);
+  if (!jsonSchema.success) {
+    throw new Error(
+      `machine provider "${id}" declares an inputs schema whose JSON Schema is not JSON-serializable`
+    );
+  }
+  return { schema: inputs, jsonSchema: jsonSchema.data };
+}
+function validateServerAccessProviderDeclaration(declaration) {
+  if (typeof declaration !== "object" || declaration === null)
+    throw new Error("Invalid server access provider declaration");
+  if (typeof declaration.id !== "string" || !/^[a-z][a-z0-9-]*$/u.test(declaration.id) || declaration.id === "direct")
+    throw new Error("Invalid or reserved server access provider id");
+  if (typeof declaration.displayName !== "string" || !declaration.displayName.trim() || typeof declaration.description !== "string" || !declaration.description.trim() || typeof declaration.availability !== "function" || typeof declaration.acquire !== "function" || typeof declaration.release !== "function")
+    throw new Error("Invalid server access provider declaration");
+  return declaration;
+}
+
+// src/testing/fake-plugin-host.ts
+import { createHash } from "node:crypto";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import Database from "better-sqlite3";
+import { CronExpressionParser } from "cron-parser";
+import { Hono } from "hono";
 
 // src/testing/fake-sdk.ts
 function withSpawnAttribution(pluginId, args) {
@@ -2920,6 +3028,8 @@ function createFakePluginHostInternal(options, sharedState) {
     overrides: options.sdk
   });
   const threadEventHandlers = {
+    "experimental_thread.events": [],
+    "experimental_terminal.input": [],
     "thread.created": [],
     "thread.active": [],
     "thread.idle": [],
@@ -2936,7 +3046,10 @@ function createFakePluginHostInternal(options, sharedState) {
   const hooks = {
     "message.dispatch": null
   };
+  const environmentCompositions = /* @__PURE__ */ new Map();
   const environmentProviders = /* @__PURE__ */ new Map();
+  const machineProviders = /* @__PURE__ */ new Map();
+  const serverAccessProviders = /* @__PURE__ */ new Map();
   const disposeHooks = [];
   const serviceControllers = [];
   let nextInteractionId = 1;
@@ -3206,6 +3319,26 @@ function createFakePluginHostInternal(options, sharedState) {
   const experimental_environments = {
     register(declaration) {
       assertLive();
+      if ("machineProviderId" in declaration) {
+        const composition = environmentCompositionSchema.parse(declaration);
+        const problem2 = composition.icon === null ? null : undeclaredIconProblem(
+          pluginId,
+          declaredIconNames,
+          composition.icon
+        );
+        if (problem2 !== null)
+          throw new Error(providerIconRefusalMessage(composition.id, problem2));
+        if (environmentProviders.has(composition.id))
+          throw new Error(
+            "Environment ID is already registered as a concrete provider"
+          );
+        environmentCompositions.set(composition.id, composition);
+        return;
+      }
+      if (environmentCompositions.has(declaration.id))
+        throw new Error(
+          "Environment ID is already registered as a composition"
+        );
       const target = validatePluginEnvironmentProviderDeclaration(declaration);
       const problem = target.icon === null ? null : undeclaredIconProblem(pluginId, declaredIconNames, target.icon);
       if (problem !== null)
@@ -3217,6 +3350,29 @@ function createFakePluginHostInternal(options, sharedState) {
       requestedDrains += 1;
     }
   };
+  const unavailableMachineBootstrap = () => {
+    throw new Error(
+      "Configure machineBootstrap in createFakePluginHost to exercise machine bootstrap"
+    );
+  };
+  const experimental_machines = {
+    async getResource(hostId) {
+      assertLive();
+      return options.machineResource ? options.machineResource(hostId) : null;
+    },
+    ...options.machineBootstrap ?? {
+      bootstrap: unavailableMachineBootstrap
+    },
+    register(declaration) {
+      assertLive();
+      const target = validatePluginMachineProviderDeclaration(declaration);
+      const problem = target.icon === null ? null : undeclaredIconProblem(pluginId, declaredIconNames, target.icon);
+      if (problem !== null) {
+        throw new Error(providerIconRefusalMessage(target.id, problem));
+      }
+      machineProviders.set(target.id, target);
+    }
+  };
   const bb = {
     pluginId,
     log,
@@ -3233,6 +3389,22 @@ function createFakePluginHostInternal(options, sharedState) {
     events,
     experimental_hooks,
     experimental_environments,
+    experimental_machines,
+    experimental_serverAccess: {
+      register(declaration) {
+        assertLive();
+        validateServerAccessProviderDeclaration(declaration);
+        if (serverAccessProviders.has(declaration.id))
+          throw new Error(
+            `Server access provider "${declaration.id}" is already registered`
+          );
+        serverAccessProviders.set(declaration.id, declaration);
+      },
+      recheck() {
+        assertLive();
+        requestedDrains += 1;
+      }
+    },
     status,
     server,
     hosts,
@@ -3320,6 +3492,8 @@ function createFakePluginHostInternal(options, sharedState) {
       },
       get threadEventHandlers() {
         return {
+          "experimental_thread.events": threadEventHandlers["experimental_thread.events"].length,
+          "experimental_terminal.input": threadEventHandlers["experimental_terminal.input"].length,
           "thread.created": threadEventHandlers["thread.created"].length,
           "thread.active": threadEventHandlers["thread.active"].length,
           "thread.idle": threadEventHandlers["thread.idle"].length,
@@ -3337,9 +3511,18 @@ function createFakePluginHostInternal(options, sharedState) {
       get hooks() {
         return { ...hooks };
       },
+      get environmentCompositions() {
+        return new Map(environmentCompositions);
+      },
       get environmentProviders() {
         return new Map(environmentProviders);
       },
+      get serverAccessProviders() {
+        return new Map(serverAccessProviders);
+      },
+      get machineProviders() {
+        return new Map(machineProviders);
+      },
       mentionProviders,
       providerRegistrations,
       providerEnvResolvers,
@@ -3765,8 +3948,16 @@ function makeHostResponse(overrides = {}) {
   return {
     id: "host-1",
     name: "Test host",
-    status: "connected",
     type: "persistent",
+    status: "connected",
+    machineProviderId: null,
+    lifecycle: {
+      phase: "active",
+      suspendedAt: null,
+      message: null,
+      pendingLog: "",
+      teardown: null
+    },
     maxPermissionMode: "full",
     lastSeenAt: null,
     lastRejectedProtocolVersion: null,
@@ -3910,8 +4101,16 @@ function makeMessageDispatchHookContext(overrides = {}) {
   const hostDefaults = {
     id: "host-1",
     name: "Test host",
-    status: "connected",
     type: "persistent",
+    status: "connected",
+    machineProviderId: null,
+    lifecycle: {
+      phase: "active",
+      suspendedAt: null,
+      message: null,
+      pendingLog: "",
+      teardown: null
+    },
     maxPermissionMode: "full",
     lastSeenAt: null,
     lastRejectedProtocolVersion: null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@get-bb/plugin-sdk",
-  "version": "0.4.55",
+  "version": "0.4.84",
   "homepage": "https://github.com/get-bb/bb#readme",
   "bugs": {
     "url": "https://github.com/get-bb/bb/issues"
@@ -56,6 +56,12 @@
       "import": "./dist/environment-provider.js",
       "default": "./dist/environment-provider.js"
     },
+    "./machine-provider": {
+      "source": "./src/machine-provider.ts",
+      "types": "./bundled-types/bb-plugin-sdk-machine-provider.d.ts",
+      "import": "./dist/machine-provider.js",
+      "default": "./dist/machine-provider.js"
+    },
     "./app": {
       "source": "./src/app.ts",
       "types": "./bundled-types/bb-plugin-sdk-app.d.ts",