@get-bb/plugin-sdk 0.4.88 → 0.4.97

package/dist/internal/host-policy.js

@@ -1,6 +1,6 @@
 // src/internal/host-policy.ts
 import { createHash } from "node:crypto";
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 
 // ../domain/src/plugin-icon.ts
 function isPluginOwnedIconPath(icon) {
@@ -54,6 +54,12 @@ import { z } from "zod";
 var PROVIDER_FORK_VALUES = ["none", "tip", "checkpoint"];
 var providerForkSchema = z.enum(PROVIDER_FORK_VALUES);
 
+// ../domain/src/completed-turn-display.ts
+import { z as z2 } from "zod";
+var COMPLETED_TURN_DISPLAY_VALUES = ["collapse", "flat"];
+var completedTurnDisplaySchema = z2.enum(COMPLETED_TURN_DISPLAY_VALUES);
+var DEFAULT_COMPLETED_TURN_DISPLAY = "collapse";
+
 // ../domain/src/provider-skill-roots.ts
 function isAbsoluteProviderSkillRootPath(value) {
   if (value.length === 0) {
@@ -76,53 +82,53 @@ function isRelativeProviderSkillRootPath(value) {
 }
 
 // ../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)
+import { z as z3 } from "zod";
+var jsonValueSchema = z3.lazy(
+  () => z3.union([
+    z3.string(),
+    z3.number(),
+    z3.boolean(),
+    z3.null(),
+    z3.array(jsonValueSchema),
+    z3.record(z3.string(), jsonValueSchema)
   ])
 );
-var jsonObjectSchema = z2.record(
-  z2.string(),
+var jsonObjectSchema = z3.record(
+  z3.string(),
   jsonValueSchema
 );
 
 // ../domain/src/native-roots.ts
-import { z as z3 } from "zod";
+import { z as z4 } 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 = z3.string().refine(
+var nativeRootNamePrefixSchema = z4.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 = z3.string().min(1).refine(
+var nativeRootManifestPathSchema = z4.string().min(1).refine(
   isRelativeProviderSkillRootPath,
   "A manifest marker is a relative path without dot segments"
 );
-var relativeNativeRootPathSchema = z3.string().min(1).refine(
+var relativeNativeRootPathSchema = z4.string().min(1).refine(
   isRelativeProviderSkillRootPath,
   "Roots must be relative paths without dot segments"
 );
-var absoluteNativeRootPathSchema = z3.string().min(1).refine(
+var absoluteNativeRootPathSchema = z4.string().min(1).refine(
   isAbsoluteProviderSkillRootPath,
   "Absolute roots must be absolute paths without dot segments"
 );
-var providerNativeRootInputSchema = z3.union([
-  z3.string().min(1),
-  z3.object({
-    path: z3.string().min(1),
+var providerNativeRootInputSchema = z4.union([
+  z4.string().min(1),
+  z4.object({
+    path: z4.string().min(1),
     /** Skills nest in subdirectories (the agent scans recursively). */
-    recursive: z3.boolean().optional(),
+    recursive: z4.boolean().optional(),
     /**
      * Scan the same relative directory in every ancestor of the workspace
      * up to the repository root (`project` roots only).
      */
-    ancestors: z3.boolean().optional(),
+    ancestors: z4.boolean().optional(),
     /**
      * Prepended to every name under the root, a vendor plugin's
      * `plugin-name:`; a prefixed root is listed as a plugin root.
@@ -137,14 +143,14 @@ var providerNativeRootInputSchema = z3.union([
     skipIfManifest: nativeRootManifestPathSchema.optional()
   }).strict()
 ]);
-var providerNativeRootsInputSchema = z3.object({
-  user: z3.array(providerNativeRootInputSchema).optional(),
-  project: z3.array(providerNativeRootInputSchema).optional()
+var providerNativeRootsInputSchema = z4.object({
+  user: z4.array(providerNativeRootInputSchema).optional(),
+  project: z4.array(providerNativeRootInputSchema).optional()
 }).strict();
-var providerNativeRootSchema = z3.object({
-  path: z3.string().min(1),
-  recursive: z3.boolean(),
-  ancestors: z3.boolean(),
+var providerNativeRootSchema = z4.object({
+  path: z4.string().min(1),
+  recursive: z4.boolean(),
+  ancestors: z4.boolean(),
   namePrefix: nativeRootNamePrefixSchema,
   /** Absent: every skill-shaped directory under the root is a skill. */
   skipIfManifest: nativeRootManifestPathSchema.optional()
@@ -153,7 +159,7 @@ function uniqueByPath(roots) {
   return new Set(roots.map((root) => root.path)).size === roots.length;
 }
 function nativeRootSideSchema(side) {
-  return z3.array(
+  return z4.array(
     providerNativeRootSchema.extend({ path: relativeNativeRootPathSchema }).superRefine((root, context) => {
       if (root.ancestors && side !== "project") {
         context.addIssue({
@@ -164,7 +170,7 @@ function nativeRootSideSchema(side) {
     })
   ).max(PROVIDER_NATIVE_ROOTS_MAX).refine(uniqueByPath, "Roots must not repeat a path");
 }
-var providerNativeRootsSchema = z3.object({
+var providerNativeRootsSchema = z4.object({
   user: nativeRootSideSchema("user"),
   project: nativeRootSideSchema("project")
 }).strict();
@@ -190,19 +196,19 @@ function normalizeProviderNativeRoots(roots) {
     project: (roots?.project ?? []).map(normalizeProviderNativeRoot)
   };
 }
-var providerResolvedNativeRootShapeSchema = z3.enum([
+var providerResolvedNativeRootShapeSchema = z4.enum([
   "skills",
   "skill",
   "skill-file",
   "commands",
   "command-file"
 ]);
-var resolvedNativeRootFieldsSchema = z3.object({
+var resolvedNativeRootFieldsSchema = z4.object({
   path: absoluteNativeRootPathSchema,
-  origin: z3.enum(["user", "project"]),
-  recursive: z3.boolean(),
+  origin: z4.enum(["user", "project"]),
+  recursive: z4.boolean(),
   /** Only with origin `project`, for a path inside the workspace. */
-  ancestors: z3.boolean(),
+  ancestors: z4.boolean(),
   namePrefix: nativeRootNamePrefixSchema,
   shape: providerResolvedNativeRootShapeSchema,
   /**
@@ -210,7 +216,7 @@ var resolvedNativeRootFieldsSchema = z3.object({
    * none. A vendor plugin's root SKILL.md takes the plugin's name; absent
    * means the parent directory's name.
    */
-  fallbackName: z3.string().min(1).optional(),
+  fallbackName: z4.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
@@ -254,14 +260,14 @@ var resolvedCommandShapes = /* @__PURE__ */ new Set([
   "command-file"
 ]);
 var PROVIDER_RESOLVED_NATIVE_ROOTS_MAX = 256;
-var providerResolvedNativeRootsSchema = z3.object({
-  skills: z3.array(
+var providerResolvedNativeRootsSchema = z4.object({
+  skills: z4.array(
     providerResolvedNativeRootSchema.refine(
       (root) => resolvedSkillShapes.has(root.shape),
       "A skills root needs a skill shape"
     )
   ).max(PROVIDER_RESOLVED_NATIVE_ROOTS_MAX),
-  commands: z3.array(
+  commands: z4.array(
     providerResolvedNativeRootSchema.refine(
       (root) => resolvedCommandShapes.has(root.shape),
       "A commands root needs a command shape"
@@ -272,7 +278,7 @@ var EMPTY_PROVIDER_RESOLVED_NATIVE_ROOTS = Object.freeze({
   skills: Object.freeze([]),
   commands: Object.freeze([])
 });
-var providerNativeRootSetSchema = z3.object({
+var providerNativeRootSetSchema = z4.object({
   skills: providerNativeRootsSchema,
   commands: providerNativeRootsSchema,
   resolved: providerResolvedNativeRootsSchema
@@ -305,15 +311,15 @@ 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 = z4.object({
-  name: z4.string().regex(PLUGIN_PROVIDER_ENV_NAME_PATTERN),
-  value: z4.union([
-    z4.string(),
-    z4.object({ serverPath: z4.string().startsWith("/") }).strict()
+var pluginProviderEnvEntrySchema = z5.object({
+  name: z5.string().regex(PLUGIN_PROVIDER_ENV_NAME_PATTERN),
+  value: z5.union([
+    z5.string(),
+    z5.object({ serverPath: z5.string().startsWith("/") }).strict()
   ]),
-  reason: z4.string()
+  reason: z5.string()
 }).strict();
-var pluginProviderEnvEntriesSchema = z4.array(pluginProviderEnvEntrySchema).max(PLUGIN_PROVIDER_ENV_MAX_ENTRIES).superRefine((entries, context) => {
+var pluginProviderEnvEntriesSchema = z5.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;
@@ -348,26 +354,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: z4.string().min(1),
-  description: z4.string().min(1).optional()
+  label: z5.string().min(1),
+  description: z5.string().min(1).optional()
 };
-var stringSettingSchemaSchema = z4.custom(
+var stringSettingSchemaSchema = z5.custom(
   (value) => isStandardSchema(value)
 );
-var booleanSettingSchemaSchema = z4.custom(
+var booleanSettingSchemaSchema = z5.custom(
   (value) => isStandardSchema(value)
 );
-var numberSettingSchemaSchema = z4.custom(
+var numberSettingSchemaSchema = z5.custom(
   (value) => isStandardSchema(value)
 );
-var settingDescriptorSchema = z4.discriminatedUnion("type", [
-  z4.object({
-    type: z4.literal("string"),
+var settingDescriptorSchema = z5.discriminatedUnion("type", [
+  z5.object({
+    type: z5.literal("string"),
     ...settingsBaseFields,
-    secret: z4.literal(true).optional(),
-    experimental_multiline: z4.boolean().optional(),
+    secret: z5.literal(true).optional(),
+    experimental_multiline: z5.boolean().optional(),
     experimental_schema: stringSettingSchemaSchema.optional(),
-    default: z4.string().optional()
+    default: z5.string().optional()
   }).strict().refine(
     (descriptor) => !(descriptor.secret === true && descriptor.experimental_multiline === true),
     {
@@ -375,30 +381,30 @@ var settingDescriptorSchema = z4.discriminatedUnion("type", [
       path: ["experimental_multiline"]
     }
   ),
-  z4.object({
-    type: z4.literal("boolean"),
+  z5.object({
+    type: z5.literal("boolean"),
     ...settingsBaseFields,
     experimental_schema: booleanSettingSchemaSchema.optional(),
-    default: z4.boolean().optional()
+    default: z5.boolean().optional()
   }).strict(),
-  z4.object({
-    type: z4.literal("number"),
+  z5.object({
+    type: z5.literal("number"),
     ...settingsBaseFields,
     experimental_schema: numberSettingSchemaSchema.optional(),
-    default: z4.number().finite().optional()
+    default: z5.number().finite().optional()
   }).strict(),
-  z4.object({
-    type: z4.literal("select"),
+  z5.object({
+    type: z5.literal("select"),
     ...settingsBaseFields,
-    options: z4.array(z4.string().min(1)).min(1),
+    options: z5.array(z5.string().min(1)).min(1),
     experimental_schema: stringSettingSchemaSchema.optional(),
-    default: z4.string().optional()
+    default: z5.string().optional()
   }).strict(),
-  z4.object({
-    type: z4.literal("project"),
+  z5.object({
+    type: z5.literal("project"),
     ...settingsBaseFields,
     experimental_schema: stringSettingSchemaSchema.optional(),
-    default: z4.string().optional()
+    default: z5.string().optional()
   }).strict()
 ]);
 function registerSettingDescriptors(target, added) {
@@ -946,6 +952,18 @@ function validateProviderModelCatalogScope(providerId, value) {
   }
   return value;
 }
+var PROVIDER_COMPLETED_TURN_DISPLAYS = COMPLETED_TURN_DISPLAY_VALUES;
+function validateProviderCompletedTurnDisplay(providerId, value) {
+  if (value === void 0) {
+    return DEFAULT_COMPLETED_TURN_DISPLAY;
+  }
+  if (typeof value !== "string" || !PROVIDER_COMPLETED_TURN_DISPLAYS.includes(value)) {
+    throw new Error(
+      `provider "${providerId}" completedTurnDisplay must be one of ${PROVIDER_COMPLETED_TURN_DISPLAYS.join(", ")}`
+    );
+  }
+  return value;
+}
 function validateProviderFallbackModels(providerId, value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     throw new Error(`provider "${providerId}" models must be an object`);
@@ -1326,6 +1344,10 @@ function validatePluginProviderDeclaration(declaration) {
     allowed: PLUGIN_PROVIDER_COMPOSER_ACTION_VALUES,
     requireNonEmpty: false
   });
+  const completedTurnDisplay = validateProviderCompletedTurnDisplay(
+    id,
+    declaration.completedTurnDisplay
+  );
   const bridgeOptions = declaration.experimental_bridgeOptions === void 0 ? void 0 : normalizeProviderBridgeOptions(
     id,
     declaration.experimental_bridgeOptions
@@ -1391,6 +1413,7 @@ function validatePluginProviderDeclaration(declaration) {
     maintenance: normalizedMaintenance,
     capabilities: normalizedCapabilities,
     composerActions,
+    completedTurnDisplay,
     ...strings === void 0 ? {} : { strings },
     ...serviceTiers === void 0 ? {} : { serviceTiers },
     ...reasoningLevels === void 0 ? {} : { reasoningLevels },
@@ -1421,6 +1444,11 @@ function isStandardSchema(value) {
   const standard = Reflect.get(value, "~standard");
   return typeof standard === "object" && standard !== null && Reflect.get(standard, "version") === 1 && typeof Reflect.get(standard, "vendor") === "string" && typeof Reflect.get(standard, "validate") === "function";
 }
+var rpcDescriptionSchema = z5.string().trim().min(1).max(4096).optional().transform((value) => value ?? null);
+var rpcPublicationOptionsSchema = z5.object({
+  experimental_discoverable: z5.boolean().default(false),
+  experimental_description: rpcDescriptionSchema
+}).strict();
 function readRpcMethodContract(method, value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     throw new Error(
@@ -1439,7 +1467,59 @@ function readRpcMethodContract(method, value) {
       `rpc method "${method}" output must be a Standard Schema v1 validator`
     );
   }
-  return { input, output };
+  const description = rpcDescriptionSchema.parse(
+    Reflect.get(value, "experimental_description")
+  );
+  return description === null ? { input, output } : { input, output, experimental_description: description };
+}
+function readRpcPublicationOptions(value) {
+  return rpcPublicationOptionsSchema.parse(value ?? {});
+}
+function publishedRpcSchema(schema, direction) {
+  const converter = schema["~standard"].jsonSchema;
+  if (converter === void 0 || typeof converter[direction] !== "function") {
+    throw new Error(
+      "discoverable RPC requires Standard JSON Schema export support"
+    );
+  }
+  const serialized = JSON.stringify(
+    converter[direction]({ target: "draft-2020-12" })
+  );
+  if (serialized === void 0 || new TextEncoder().encode(serialized).byteLength > 128 * 1024) {
+    throw new Error("published RPC schema must be JSON and at most 128 KiB");
+  }
+  const result = z5.record(z5.string(), jsonValueSchema).parse(JSON.parse(serialized));
+  const inspect = (value) => {
+    if (value === null || typeof value !== "object") return;
+    if (Array.isArray(value)) {
+      for (const item of value) inspect(item);
+      return;
+    }
+    for (const [key, item] of Object.entries(value)) {
+      if ((key === "$ref" || key === "$dynamicRef") && typeof item === "string" && !item.startsWith("#")) {
+        throw new Error("published RPC schemas must use local references");
+      }
+      inspect(item);
+    }
+  };
+  inspect(result);
+  return result;
+}
+function publishRpcMethod(method, contract, options) {
+  if (!options.experimental_discoverable) return null;
+  try {
+    return {
+      method,
+      registrationDescription: options.experimental_description,
+      methodDescription: contract.experimental_description ?? null,
+      inputSchema: publishedRpcSchema(contract.input, "input"),
+      outputSchema: publishedRpcSchema(contract.output, "output")
+    };
+  } catch (error) {
+    throw new Error(
+      `rpc method "${method}" cannot be published: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
 }
 function isZodSchemaLike(value) {
   return typeof value === "object" && value !== null && typeof value.safeParse === "function";
@@ -1458,7 +1538,7 @@ function zodSchemaToJsonSchema(schema) {
   if (typeof schema.toJSONSchema === "function") {
     return schema.toJSONSchema({ io: "input" });
   }
-  return z4.toJSONSchema(schema, { io: "input" });
+  return z5.toJSONSchema(schema, { io: "input" });
 }
 var SINGLE_SCHEMA_KEYWORDS = [
   "additionalItems",
@@ -1803,15 +1883,15 @@ var ENVIRONMENT_PROVIDER_REQUIREMENT_NAMES = [
   "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(
+var environmentCompositionSchema = z5.object({
+  id: z5.string().regex(ENVIRONMENT_PROVIDER_ID_PATTERN),
+  displayName: z5.string().trim().min(1).max(ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS),
+  description: z5.string().trim().min(1).max(ENVIRONMENT_PROVIDER_DESCRIPTION_MAX_CHARS).optional().transform((value) => value ?? null),
+  icon: z5.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)
+  machineProviderId: z5.string().regex(ENVIRONMENT_PROVIDER_ID_PATTERN),
+  environmentProviderId: z5.string().regex(ENVIRONMENT_PROVIDER_ID_PATTERN)
 }).strict();
 function requireProviderIdAndDisplayName(noun, declaration) {
   if (typeof declaration !== "object" || declaration === null) {
@@ -1877,8 +1957,8 @@ function validatePluginEnvironmentProviderDeclaration(declaration) {
     "environment provider",
     declaration
   );
-  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);
+  const description = z5.string().trim().min(1).max(ENVIRONMENT_PROVIDER_DESCRIPTION_MAX_CHARS).optional().transform((value) => value ?? null).parse(declaration.description);
+  const icon = z5.string().trim().min(1).optional().transform((value) => value ?? null).parse(declaration.icon);
   if (icon !== null) {
     assertProviderIconShape("environment provider", id, icon);
   }
@@ -1947,9 +2027,9 @@ function normalizeEnvironmentProviderRequirements(id, declaration) {
   }
   return normalized;
 }
-var environmentProviderPolicySchema = z4.object({
-  retireGraceMs: z4.number().int().nonnegative().nullable().default(3e5),
-  pathKeys: z4.enum(["per-thread", "per-attempt"]).default("per-thread")
+var environmentProviderPolicySchema = z5.object({
+  retireGraceMs: z5.number().int().nonnegative().nullable().default(3e5),
+  pathKeys: z5.enum(["per-thread", "per-attempt"]).default("per-thread")
 }).strict();
 var MACHINE_PROVIDER_DESCRIPTION_MAX_CHARS = 200;
 function validatePluginMachineProviderDeclaration(declaration) {
@@ -1957,10 +2037,10 @@ function validatePluginMachineProviderDeclaration(declaration) {
     "machine provider",
     declaration
   );
-  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);
+  const description = z5.string().trim().min(1).max(MACHINE_PROVIDER_DESCRIPTION_MAX_CHARS).parse(declaration.description);
+  const icon = z5.string().trim().min(1).parse(declaration.icon);
   assertProviderIconShape("machine provider", id, icon);
-  const ephemeral = z4.boolean().default(false).parse(declaration.ephemeral);
+  const ephemeral = z5.boolean().default(false).parse(declaration.ephemeral);
   const inputs = normalizeProviderInputs(
     "machine provider",
     id,
@@ -2115,13 +2195,14 @@ function normalizeWebSocketRouteRegistration(path, handler, opts, existingRoutes
   }
   return { path, auth };
 }
-function normalizeRpcRegistration(contract, handlers, registered) {
+function normalizeRpcRegistration(contract, handlers, registered, options) {
   if (typeof contract !== "object" || contract === null || Array.isArray(contract)) {
     throw new Error("rpc.register contract must be an object");
   }
   if (typeof handlers !== "object" || handlers === null || Array.isArray(handlers)) {
     throw new Error("rpc.register handlers must be an object");
   }
+  const publicationOptions = readRpcPublicationOptions(options);
   const pending = [];
   const contractEntries = Object.entries(contract);
   const contractNames = new Set(contractEntries.map(([name]) => name));
@@ -2149,6 +2230,7 @@ function normalizeRpcRegistration(contract, handlers, registered) {
     pending.push([
       name,
       {
+        publication: publishRpcMethod(name, methodContract, publicationOptions),
         inputSchema: methodContract.input,
         outputSchema: methodContract.output,
         handler
@@ -2730,6 +2812,8 @@ export {
   providerAlreadyRegisteredMessage,
   providerIconRefusalMessage,
   providerWithoutBridgeMessage,
+  publishRpcMethod,
+  readRpcPublicationOptions,
   registerSettingDescriptors,
   runPluginStorageMigrations,
   storePluginHook,