@get-bb/plugin-sdk 0.4.48 → 0.4.50

package/dist/testing/index.js

@@ -12,7 +12,7 @@ var PLUGIN_INTERACTION_MAX_TITLE_LENGTH = 160;
 var PLUGIN_INTERACTION_MAX_PAYLOAD_BYTES = 64 * 1024;
 
 // src/internal/host-policy.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 
 // ../domain/src/plugin-icon.ts
 function isPluginOwnedIconPath(icon) {
@@ -83,37 +83,54 @@ function isRelativeProviderSkillRootPath(value) {
   return !normalized.startsWith("/") && !/^[a-zA-Z]:\//u.test(normalized) && normalized.split("/").every((segment) => segment !== "" && segment !== "." && segment !== "..");
 }
 
-// ../domain/src/native-roots.ts
+// ../domain/src/json-value.ts
 import { z as z2 } from "zod";
+var jsonValueSchema = z2.lazy(
+  () => z2.union([
+    z2.string(),
+    z2.number(),
+    z2.boolean(),
+    z2.null(),
+    z2.array(jsonValueSchema),
+    z2.record(z2.string(), jsonValueSchema)
+  ])
+);
+var jsonObjectSchema = z2.record(
+  z2.string(),
+  jsonValueSchema
+);
+
+// ../domain/src/native-roots.ts
+import { z as z3 } from "zod";
 var PROVIDER_NATIVE_ROOTS_MAX = 32;
 var PROVIDER_NATIVE_ROOT_NAME_PREFIX_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,62}:$/u;
-var nativeRootNamePrefixSchema = z2.string().refine(
+var nativeRootNamePrefixSchema = z3.string().refine(
   (value) => value === "" || PROVIDER_NATIVE_ROOT_NAME_PREFIX_PATTERN.test(value),
   "A root name prefix is a plugin-name-like token ending in ':'"
 );
-var nativeRootManifestPathSchema = z2.string().min(1).refine(
+var nativeRootManifestPathSchema = z3.string().min(1).refine(
   isRelativeProviderSkillRootPath,
   "A manifest marker is a relative path without dot segments"
 );
-var relativeNativeRootPathSchema = z2.string().min(1).refine(
+var relativeNativeRootPathSchema = z3.string().min(1).refine(
   isRelativeProviderSkillRootPath,
   "Roots must be relative paths without dot segments"
 );
-var absoluteNativeRootPathSchema = z2.string().min(1).refine(
+var absoluteNativeRootPathSchema = z3.string().min(1).refine(
   isAbsoluteProviderSkillRootPath,
   "Absolute roots must be absolute paths without dot segments"
 );
-var providerNativeRootInputSchema = z2.union([
-  z2.string().min(1),
-  z2.object({
-    path: z2.string().min(1),
+var providerNativeRootInputSchema = z3.union([
+  z3.string().min(1),
+  z3.object({
+    path: z3.string().min(1),
     /** Skills nest in subdirectories (the agent scans recursively). */
-    recursive: z2.boolean().optional(),
+    recursive: z3.boolean().optional(),
     /**
      * Scan the same relative directory in every ancestor of the workspace
      * up to the repository root (`project` roots only).
      */
-    ancestors: z2.boolean().optional(),
+    ancestors: z3.boolean().optional(),
     /**
      * Prepended to every name under the root, a vendor plugin's
      * `plugin-name:`; a prefixed root is listed as a plugin root.
@@ -128,14 +145,14 @@ var providerNativeRootInputSchema = z2.union([
     skipIfManifest: nativeRootManifestPathSchema.optional()
   }).strict()
 ]);
-var providerNativeRootsInputSchema = z2.object({
-  user: z2.array(providerNativeRootInputSchema).optional(),
-  project: z2.array(providerNativeRootInputSchema).optional()
+var providerNativeRootsInputSchema = z3.object({
+  user: z3.array(providerNativeRootInputSchema).optional(),
+  project: z3.array(providerNativeRootInputSchema).optional()
 }).strict();
-var providerNativeRootSchema = z2.object({
-  path: z2.string().min(1),
-  recursive: z2.boolean(),
-  ancestors: z2.boolean(),
+var providerNativeRootSchema = z3.object({
+  path: z3.string().min(1),
+  recursive: z3.boolean(),
+  ancestors: z3.boolean(),
   namePrefix: nativeRootNamePrefixSchema,
   /** Absent: every skill-shaped directory under the root is a skill. */
   skipIfManifest: nativeRootManifestPathSchema.optional()
@@ -144,7 +161,7 @@ function uniqueByPath(roots) {
   return new Set(roots.map((root) => root.path)).size === roots.length;
 }
 function nativeRootSideSchema(side) {
-  return z2.array(
+  return z3.array(
     providerNativeRootSchema.extend({ path: relativeNativeRootPathSchema }).superRefine((root, context) => {
       if (root.ancestors && side !== "project") {
         context.addIssue({
@@ -155,7 +172,7 @@ function nativeRootSideSchema(side) {
     })
   ).max(PROVIDER_NATIVE_ROOTS_MAX).refine(uniqueByPath, "Roots must not repeat a path");
 }
-var providerNativeRootsSchema = z2.object({
+var providerNativeRootsSchema = z3.object({
   user: nativeRootSideSchema("user"),
   project: nativeRootSideSchema("project")
 }).strict();
@@ -181,19 +198,19 @@ function normalizeProviderNativeRoots(roots) {
     project: (roots?.project ?? []).map(normalizeProviderNativeRoot)
   };
 }
-var providerResolvedNativeRootShapeSchema = z2.enum([
+var providerResolvedNativeRootShapeSchema = z3.enum([
   "skills",
   "skill",
   "skill-file",
   "commands",
   "command-file"
 ]);
-var resolvedNativeRootFieldsSchema = z2.object({
+var resolvedNativeRootFieldsSchema = z3.object({
   path: absoluteNativeRootPathSchema,
-  origin: z2.enum(["user", "project"]),
-  recursive: z2.boolean(),
+  origin: z3.enum(["user", "project"]),
+  recursive: z3.boolean(),
   /** Only with origin `project`, for a path inside the workspace. */
-  ancestors: z2.boolean(),
+  ancestors: z3.boolean(),
   namePrefix: nativeRootNamePrefixSchema,
   shape: providerResolvedNativeRootShapeSchema,
   /**
@@ -201,7 +218,7 @@ var resolvedNativeRootFieldsSchema = z2.object({
    * none. A vendor plugin's root SKILL.md takes the plugin's name; absent
    * means the parent directory's name.
    */
-  fallbackName: z2.string().min(1).optional(),
+  fallbackName: z3.string().min(1).optional(),
   /**
    * `skills` only: a file, relative to a skill directory under this root,
    * that marks the directory as a vendor plugin rather than a skill; the
@@ -245,14 +262,14 @@ var resolvedCommandShapes = /* @__PURE__ */ new Set([
   "command-file"
 ]);
 var PROVIDER_RESOLVED_NATIVE_ROOTS_MAX = 256;
-var providerResolvedNativeRootsSchema = z2.object({
-  skills: z2.array(
+var providerResolvedNativeRootsSchema = z3.object({
+  skills: z3.array(
     providerResolvedNativeRootSchema.refine(
       (root) => resolvedSkillShapes.has(root.shape),
       "A skills root needs a skill shape"
     )
   ).max(PROVIDER_RESOLVED_NATIVE_ROOTS_MAX),
-  commands: z2.array(
+  commands: z3.array(
     providerResolvedNativeRootSchema.refine(
       (root) => resolvedCommandShapes.has(root.shape),
       "A commands root needs a command shape"
@@ -263,7 +280,7 @@ var EMPTY_PROVIDER_RESOLVED_NATIVE_ROOTS = Object.freeze({
   skills: Object.freeze([]),
   commands: Object.freeze([])
 });
-var providerNativeRootSetSchema = z2.object({
+var providerNativeRootSetSchema = z3.object({
   skills: providerNativeRootsSchema,
   commands: providerNativeRootsSchema,
   resolved: providerResolvedNativeRootsSchema
@@ -296,16 +313,16 @@ var CLI_COMMAND_NAME_PATTERN = /^[a-z0-9-]+$/;
 var AGENT_TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
 var PLUGIN_PROVIDER_ENV_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
 var PLUGIN_PROVIDER_ENV_MAX_ENTRIES = 32;
-var pluginProviderEnvEntrySchema = z3.object({
-  name: z3.string().regex(PLUGIN_PROVIDER_ENV_NAME_PATTERN),
-  value: z3.union([
-    z3.string(),
-    z3.object({ serverPath: z3.string().startsWith("/") }).strict()
+var pluginProviderEnvEntrySchema = z4.object({
+  name: z4.string().regex(PLUGIN_PROVIDER_ENV_NAME_PATTERN),
+  value: z4.union([
+    z4.string(),
+    z4.object({ serverPath: z4.string().startsWith("/") }).strict()
   ]),
-  reason: z3.string(),
-  secret: z3.boolean()
+  reason: z4.string(),
+  secret: z4.boolean()
 }).strict();
-var pluginProviderEnvEntriesSchema = z3.array(pluginProviderEnvEntrySchema).max(PLUGIN_PROVIDER_ENV_MAX_ENTRIES).superRefine((entries, context) => {
+var pluginProviderEnvEntriesSchema = z4.array(pluginProviderEnvEntrySchema).max(PLUGIN_PROVIDER_ENV_MAX_ENTRIES).superRefine((entries, context) => {
   const names = /* @__PURE__ */ new Set();
   for (let index = 0; index < entries.length; index += 1) {
     const name = entries[index]?.name;
@@ -340,26 +357,26 @@ var PROVIDER_ID_PATTERN = /^[a-z0-9][a-z0-9-]{1,63}$/;
 var PLUGIN_PROVIDER_BRIDGE_OPTIONS_MAX_BYTES = 64 * 1024;
 var SETTING_KEY_PATTERN = /^[a-zA-Z0-9_-]+$/;
 var settingsBaseFields = {
-  label: z3.string().min(1),
-  description: z3.string().min(1).optional()
+  label: z4.string().min(1),
+  description: z4.string().min(1).optional()
 };
-var stringSettingSchemaSchema = z3.custom(
+var stringSettingSchemaSchema = z4.custom(
   (value) => isStandardSchema(value)
 );
-var booleanSettingSchemaSchema = z3.custom(
+var booleanSettingSchemaSchema = z4.custom(
   (value) => isStandardSchema(value)
 );
-var numberSettingSchemaSchema = z3.custom(
+var numberSettingSchemaSchema = z4.custom(
   (value) => isStandardSchema(value)
 );
-var settingDescriptorSchema = z3.discriminatedUnion("type", [
-  z3.object({
-    type: z3.literal("string"),
+var settingDescriptorSchema = z4.discriminatedUnion("type", [
+  z4.object({
+    type: z4.literal("string"),
     ...settingsBaseFields,
-    secret: z3.literal(true).optional(),
-    experimental_multiline: z3.boolean().optional(),
+    secret: z4.literal(true).optional(),
+    experimental_multiline: z4.boolean().optional(),
     experimental_schema: stringSettingSchemaSchema.optional(),
-    default: z3.string().optional()
+    default: z4.string().optional()
   }).strict().refine(
     (descriptor) => !(descriptor.secret === true && descriptor.experimental_multiline === true),
     {
@@ -367,30 +384,30 @@ var settingDescriptorSchema = z3.discriminatedUnion("type", [
       path: ["experimental_multiline"]
     }
   ),
-  z3.object({
-    type: z3.literal("boolean"),
+  z4.object({
+    type: z4.literal("boolean"),
     ...settingsBaseFields,
     experimental_schema: booleanSettingSchemaSchema.optional(),
-    default: z3.boolean().optional()
+    default: z4.boolean().optional()
   }).strict(),
-  z3.object({
-    type: z3.literal("number"),
+  z4.object({
+    type: z4.literal("number"),
     ...settingsBaseFields,
     experimental_schema: numberSettingSchemaSchema.optional(),
-    default: z3.number().finite().optional()
+    default: z4.number().finite().optional()
   }).strict(),
-  z3.object({
-    type: z3.literal("select"),
+  z4.object({
+    type: z4.literal("select"),
     ...settingsBaseFields,
-    options: z3.array(z3.string().min(1)).min(1),
+    options: z4.array(z4.string().min(1)).min(1),
     experimental_schema: stringSettingSchemaSchema.optional(),
-    default: z3.string().optional()
+    default: z4.string().optional()
   }).strict(),
-  z3.object({
-    type: z3.literal("project"),
+  z4.object({
+    type: z4.literal("project"),
     ...settingsBaseFields,
     experimental_schema: stringSettingSchemaSchema.optional(),
-    default: z3.string().optional()
+    default: z4.string().optional()
   }).strict()
 ]);
 function registerSettingDescriptors(target, added) {
@@ -1410,11 +1427,21 @@ function readRpcMethodContract(method, value) {
 function isZodSchemaLike(value) {
   return typeof value === "object" && value !== null && typeof value.safeParse === "function";
 }
+function standardSchemaToJsonSchema(schema) {
+  if (isZodSchemaLike(schema)) {
+    return zodSchemaToJsonSchema(schema);
+  }
+  const convertible = schema;
+  if (typeof convertible.toJSONSchema === "function") {
+    return convertible.toJSONSchema();
+  }
+  throw new Error("the validator exposes no JSON Schema conversion");
+}
 function zodSchemaToJsonSchema(schema) {
   if (typeof schema.toJSONSchema === "function") {
     return schema.toJSONSchema({ io: "input" });
   }
-  return z3.toJSONSchema(schema, { io: "input" });
+  return z4.toJSONSchema(schema, { io: "input" });
 }
 var SINGLE_SCHEMA_KEYWORDS = [
   "additionalItems",
@@ -1740,6 +1767,130 @@ function storePluginHook(records, hook, handler) {
 function pluginHookAlreadyRegisteredMessage(hook) {
   return `a "${hook}" hook handler is already registered by this plugin`;
 }
+var ENVIRONMENT_PROVIDER_ID_PATTERN = /^[a-z0-9][a-z0-9-]{1,63}$/;
+var ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS = 80;
+var ENVIRONMENT_PROVIDER_REQUIREMENT_NAMES = [
+  "projectCheckout",
+  "gitCheckout",
+  "gitRemote",
+  "projectless"
+];
+function validatePluginEnvironmentProviderDeclaration(declaration) {
+  if (typeof declaration !== "object" || declaration === null) {
+    throw new Error("environment provider declaration must be an object");
+  }
+  const id = declaration.id;
+  if (typeof id !== "string" || !ENVIRONMENT_PROVIDER_ID_PATTERN.test(id)) {
+    throw new Error(
+      `invalid environment 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(
+      `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 requires = normalizeEnvironmentProviderRequirements(id, declaration);
+  const inputs = normalizeEnvironmentProviderInputs(id, declaration);
+  if (typeof declaration.create !== "function" || typeof declaration.remove !== "function") {
+    throw new Error(
+      `environment provider "${id}" must declare create and remove functions`
+    );
+  }
+  if (declaration.validate !== void 0 && typeof declaration.validate !== "function") {
+    throw new Error(
+      `environment provider "${id}" declares a validate that is not a function`
+    );
+  }
+  if (declaration.availability !== void 0 && typeof declaration.availability !== "function") {
+    throw new Error(
+      `environment provider "${id}" declares availability that is not a function`
+    );
+  }
+  return {
+    id,
+    displayName,
+    icon,
+    requires,
+    inputs: inputs === null ? null : inputs.schema,
+    inputsJsonSchema: inputs === null ? null : inputs.jsonSchema,
+    availability: declaration.availability ?? null,
+    validate: declaration.validate ?? null,
+    create: declaration.create,
+    remove: declaration.remove,
+    policy: environmentProviderPolicySchema.parse(declaration.policy ?? {})
+  };
+}
+function normalizeEnvironmentProviderInputs(id, declaration) {
+  const inputs = declaration.inputs;
+  if (inputs === void 0) {
+    return null;
+  }
+  if (!isStandardSchema(inputs)) {
+    throw new Error(
+      `environment 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(
+      `environment 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(
+      `environment provider "${id}" declares an inputs schema whose JSON Schema is not JSON-serializable`
+    );
+  }
+  return { schema: inputs, jsonSchema: jsonSchema.data };
+}
+function normalizeEnvironmentProviderRequirements(id, declaration) {
+  const requires = declaration.requires ?? {};
+  if (typeof requires !== "object" || requires === null || Array.isArray(requires)) {
+    throw new Error(
+      `environment provider "${id}" declares a requires that is not an object`
+    );
+  }
+  const normalized = {};
+  for (const name of ENVIRONMENT_PROVIDER_REQUIREMENT_NAMES) {
+    const value = requires[name];
+    if (value !== void 0 && typeof value !== "boolean") {
+      throw new Error(
+        `environment provider "${id}" declares a requires.${name} that is not a boolean`
+      );
+    }
+    normalized[name] = value === true;
+  }
+  if (normalized.gitCheckout) {
+    normalized.projectCheckout = true;
+  }
+  if (normalized.projectless && (normalized.projectCheckout || normalized.gitRemote)) {
+    throw new Error(
+      `environment provider "${id}" declares requires.projectless together with a project requirement \u2014 a projectless thread has no checkout or remote`
+    );
+  }
+  return normalized;
+}
+var environmentProviderPolicySchema = z4.object({
+  retireGraceMs: z4.number().int().nonnegative().nullable().default(3e5),
+  pathKeys: z4.enum(["per-thread", "per-attempt"]).default("per-thread")
+}).strict();
 
 // src/testing/fake-sdk.ts
 function withSpawnAttribution(pluginId, args) {
@@ -2778,11 +2929,14 @@ function createFakePluginHostInternal(options, sharedState) {
     "interaction.pending": [],
     "message.queued": [],
     "message.dispatched": [],
-    "turn.failed": []
+    "turn.failed": [],
+    "message.cancelled": [],
+    "thread.unarchived": []
   };
   const hooks = {
     "message.dispatch": null
   };
+  const environmentProviders = /* @__PURE__ */ new Map();
   const disposeHooks = [];
   const serviceControllers = [];
   let nextInteractionId = 1;
@@ -3049,6 +3203,20 @@ function createFakePluginHostInternal(options, sharedState) {
       requestedDrains += 1;
     }
   };
+  const experimental_environments = {
+    register(declaration) {
+      assertLive();
+      const target = validatePluginEnvironmentProviderDeclaration(declaration);
+      const problem = target.icon === null ? null : undeclaredIconProblem(pluginId, declaredIconNames, target.icon);
+      if (problem !== null)
+        throw new Error(providerIconRefusalMessage(target.id, problem));
+      environmentProviders.set(target.id, target);
+    },
+    async recheck() {
+      assertLive();
+      requestedDrains += 1;
+    }
+  };
   const bb = {
     pluginId,
     log,
@@ -3064,6 +3232,7 @@ function createFakePluginHostInternal(options, sharedState) {
     ui,
     events,
     experimental_hooks,
+    experimental_environments,
     status,
     server,
     hosts,
@@ -3160,12 +3329,17 @@ function createFakePluginHostInternal(options, sharedState) {
           "interaction.pending": threadEventHandlers["interaction.pending"].length,
           "message.queued": threadEventHandlers["message.queued"].length,
           "message.dispatched": threadEventHandlers["message.dispatched"].length,
-          "turn.failed": threadEventHandlers["turn.failed"].length
+          "turn.failed": threadEventHandlers["turn.failed"].length,
+          "message.cancelled": threadEventHandlers["message.cancelled"].length,
+          "thread.unarchived": threadEventHandlers["thread.unarchived"].length
         };
       },
       get hooks() {
         return { ...hooks };
       },
+      get environmentProviders() {
+        return new Map(environmentProviders);
+      },
       mentionProviders,
       providerRegistrations,
       providerEnvResolvers,
@@ -3634,8 +3808,8 @@ function makePluginAgentConfigurationContext(overrides = {}) {
       id: "environment-test",
       name: null,
       path: "/tmp/test",
-      workspaceProvisionType: "unmanaged",
-      branchName: null
+      branchName: null,
+      workspaceProvisionType: null
     },
     host: { id: "host-test", name: "Test host" },
     provider: {
@@ -3694,7 +3868,8 @@ function makeMessageDispatchHookContext(overrides = {}) {
     origin: null,
     originPluginId: null,
     startedOnBehalfOf: null,
-    parentThreadId: null
+    parentThreadId: null,
+    environmentIntent: null
   };
   const environmentDefaults = {
     id: "environment-1",
@@ -3702,14 +3877,18 @@ function makeMessageDispatchHookContext(overrides = {}) {
     projectId: "project-1",
     hostId: "host-1",
     path: "/tmp/test",
-    managed: true,
     isGitRepo: true,
     isWorktree: false,
-    workspaceProvisionType: "unmanaged",
     branchName: "main",
     baseBranch: null,
     defaultBranch: "main",
     mergeBaseBranch: null,
+    environmentProviderId: null,
+    environmentProviderSelection: null,
+    environmentProviderInstanceKey: null,
+    lifecycle: { phase: "active", retireAt: null, teardown: null },
+    managed: false,
+    workspaceProvisionType: null,
     status: "ready",
     createdAt: 0,
     updatedAt: 0
@@ -3717,8 +3896,8 @@ function makeMessageDispatchHookContext(overrides = {}) {
   const hostDefaults = {
     id: "host-1",
     name: "Test host",
-    type: "persistent",
     status: "connected",
+    type: "persistent",
     maxPermissionMode: "full",
     lastSeenAt: null,
     lastRejectedProtocolVersion: null,
@@ -3764,6 +3943,8 @@ function makeMessageDispatchHookContext(overrides = {}) {
 function makeQueueEntry(overrides = {}) {
   return {
     id: "queued_1",
+    initiator: "user",
+    senderThreadId: null,
     threadId: "thread-1",
     content: [{ type: "text", text: "Queued turn", mentions: [] }],
     model: "test-model",

package/package.json

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