@get-bb/plugin-sdk 0.4.10 → 0.4.12

package/dist/app.js

@@ -22,6 +22,7 @@ var experimental_useSidebarThreads = runtime.experimental_useSidebarThreads;
 var experimental_useSidebarThreadActions = runtime.experimental_useSidebarThreadActions;
 var experimental_useSidebarThreadPullRequest = runtime.experimental_useSidebarThreadPullRequest;
 var experimental_useSidebarThreadSplit = runtime.experimental_useSidebarThreadSplit;
+var experimental_useProviders = runtime.experimental_useProviders;
 export {
   Markdown,
   ThreadChat,
@@ -33,6 +34,7 @@ export {
   experimental_UrlLink,
   experimental_useAppPanel,
   experimental_useFixedTabTarget,
+  experimental_useProviders,
   experimental_useSidebarThreadActions,
   experimental_useSidebarThreadPullRequest,
   experimental_useSidebarThreadSplit,

package/dist/internal/host-policy.js

@@ -256,7 +256,7 @@ function validateProviderLiteralArray(args) {
   }
   return Object.freeze(normalized);
 }
-function normalizeProviderBridgeOptions(providerId, value) {
+function normalizeProviderBridgeOptions(providerId, value, label = "experimental_bridgeOptions") {
   const active = /* @__PURE__ */ new Set();
   function visit(current, path) {
     if (current === null || typeof current === "string" || typeof current === "boolean") {
@@ -265,14 +265,14 @@ function normalizeProviderBridgeOptions(providerId, value) {
     if (typeof current === "number") {
       if (!Number.isFinite(current)) {
         throw new Error(
-          `provider "${providerId}" experimental_bridgeOptions${path} must be finite JSON`
+          `provider "${providerId}" ${label}${path} must be finite JSON`
         );
       }
       return current;
     }
     if (typeof current !== "object") {
       throw new Error(
-        `provider "${providerId}" experimental_bridgeOptions${path} must be JSON`
+        `provider "${providerId}" ${label}${path} must be JSON`
       );
     }
     if (active.has(current)) {
@@ -292,7 +292,7 @@ function normalizeProviderBridgeOptions(providerId, value) {
       const prototype = Object.getPrototypeOf(current);
       if (prototype !== Object.prototype && prototype !== null) {
         throw new Error(
-          `provider "${providerId}" experimental_bridgeOptions${path} must contain only plain JSON objects`
+          `provider "${providerId}" ${label}${path} must contain only plain JSON objects`
         );
       }
       const normalized2 = Object.fromEntries(
@@ -310,16 +310,329 @@ function normalizeProviderBridgeOptions(providerId, value) {
   const normalized = visit(value, "");
   if (normalized === null || Array.isArray(normalized) || typeof normalized !== "object") {
     throw new Error(
-      `provider "${providerId}" experimental_bridgeOptions must be an object`
+      `provider "${providerId}" ${label} must be an object`
     );
   }
   if (Buffer.byteLength(JSON.stringify(normalized), "utf8") > PLUGIN_PROVIDER_BRIDGE_OPTIONS_MAX_BYTES) {
     throw new Error(
-      `provider "${providerId}" experimental_bridgeOptions exceeds ${PLUGIN_PROVIDER_BRIDGE_OPTIONS_MAX_BYTES} bytes`
+      `provider "${providerId}" ${label} exceeds ${PLUGIN_PROVIDER_BRIDGE_OPTIONS_MAX_BYTES} bytes`
     );
   }
   return normalized;
 }
+var PROVIDER_STRING_MAX_CHARS = 512;
+var PROVIDER_EXTENSION_KIND_NAME_PATTERN = /^[a-z0-9-]+$/u;
+var PROVIDER_EXTENSION_KINDS_MAX = 32;
+function requireNonBlankString(args) {
+  const { providerId, field, value } = args;
+  if (typeof value !== "string" || value.trim().length === 0 || value.length > PROVIDER_STRING_MAX_CHARS) {
+    throw new Error(
+      `provider "${providerId}" ${field} must be a non-blank string of at most ${PROVIDER_STRING_MAX_CHARS} characters`
+    );
+  }
+  return value;
+}
+function validateProviderStrings(providerId, value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(
+      `provider "${providerId}" experimental_strings must be an object`
+    );
+  }
+  const record = Object.fromEntries(
+    Object.entries(value)
+  );
+  const required = (field) => requireNonBlankString({
+    providerId,
+    field: `experimental_strings.${field}`,
+    value: record[field]
+  });
+  const optional = (field) => record[field] === void 0 ? void 0 : requireNonBlankString({
+    providerId,
+    field: `experimental_strings.${field}`,
+    value: record[field]
+  });
+  let iconTint;
+  if (record.iconTint !== void 0) {
+    const tint = record.iconTint;
+    if (typeof tint !== "object" || tint === null || Array.isArray(tint)) {
+      throw new Error(
+        `provider "${providerId}" experimental_strings.iconTint must be { light, dark }`
+      );
+    }
+    const tintRecord = Object.fromEntries(
+      Object.entries(tint)
+    );
+    iconTint = Object.freeze({
+      light: requireNonBlankString({
+        providerId,
+        field: "experimental_strings.iconTint.light",
+        value: tintRecord.light
+      }),
+      dark: requireNonBlankString({
+        providerId,
+        field: "experimental_strings.iconTint.dark",
+        value: tintRecord.dark
+      })
+    });
+  }
+  const brandPrefix = optional("brandPrefix");
+  const planModeCopy = optional("planModeCopy");
+  return Object.freeze({
+    signInHint: required("signInHint"),
+    expiredHint: required("expiredHint"),
+    installUrl: required("installUrl"),
+    ...brandPrefix === void 0 ? {} : { brandPrefix },
+    ...planModeCopy === void 0 ? {} : { planModeCopy },
+    ...iconTint === void 0 ? {} : { iconTint }
+  });
+}
+function validateProviderOptionDescriptors(args) {
+  const { providerId, field, value } = args;
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error(
+      `provider "${providerId}" ${field} must be a non-empty array of { id, label, description? }`
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const normalized = value.map(
+    (entry, index) => {
+      if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+        throw new Error(
+          `provider "${providerId}" ${field}[${index}] must be { id, label, description? }`
+        );
+      }
+      const record = Object.fromEntries(
+        Object.entries(entry)
+      );
+      const id = requireNonBlankString({
+        providerId,
+        field: `${field}[${index}].id`,
+        value: record.id
+      });
+      if (seen.has(id)) {
+        throw new Error(
+          `provider "${providerId}" ${field} id ${JSON.stringify(id)} is duplicated`
+        );
+      }
+      seen.add(id);
+      const label = requireNonBlankString({
+        providerId,
+        field: `${field}[${index}].label`,
+        value: record.label
+      });
+      const description = record.description === void 0 ? void 0 : requireNonBlankString({
+        providerId,
+        field: `${field}[${index}].description`,
+        value: record.description
+      });
+      return Object.freeze({
+        id,
+        label,
+        ...description === void 0 ? {} : { description }
+      });
+    }
+  );
+  return Object.freeze(normalized);
+}
+function validateProviderExtensionKinds(providerId, value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(
+      `provider "${providerId}" experimental_extensionKinds must be an object keyed by kind name`
+    );
+  }
+  const entries = Object.entries(value);
+  if (entries.length > PROVIDER_EXTENSION_KINDS_MAX) {
+    throw new Error(
+      `provider "${providerId}" experimental_extensionKinds declares more than ${PROVIDER_EXTENSION_KINDS_MAX} kinds`
+    );
+  }
+  const normalized = {};
+  for (const [name, declaration] of entries) {
+    if (!PROVIDER_EXTENSION_KIND_NAME_PATTERN.test(name)) {
+      throw new Error(
+        `provider "${providerId}" experimental_extensionKinds name ${JSON.stringify(name)} must match ${PROVIDER_EXTENSION_KIND_NAME_PATTERN}`
+      );
+    }
+    if (typeof declaration !== "object" || declaration === null || Array.isArray(declaration)) {
+      throw new Error(
+        `provider "${providerId}" experimental_extensionKinds.${name} must be { item?, state? }`
+      );
+    }
+    const item = Reflect.get(declaration, "item");
+    const state = Reflect.get(declaration, "state");
+    if (item === void 0 && state === void 0) {
+      throw new Error(
+        `provider "${providerId}" experimental_extensionKinds.${name} must declare an item schema, a state schema, or both`
+      );
+    }
+    if (item !== void 0 && !isStandardSchema(item)) {
+      throw new Error(
+        `provider "${providerId}" experimental_extensionKinds.${name}.item must be a Standard Schema v1 validator`
+      );
+    }
+    if (state !== void 0 && !isStandardSchema(state)) {
+      throw new Error(
+        `provider "${providerId}" experimental_extensionKinds.${name}.state must be a Standard Schema v1 validator`
+      );
+    }
+    normalized[name] = Object.freeze({
+      ...item === void 0 ? {} : { item },
+      ...state === void 0 ? {} : { state }
+    });
+  }
+  return Object.freeze(normalized);
+}
+var PROVIDER_FALLBACK_MODELS_MAX = 64;
+var PROVIDER_ENV_PASSTHROUGH_MAX = 32;
+var PROVIDER_ENV_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/u;
+function validateProviderEnvPassthrough(providerId, value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(
+      `provider "${providerId}" experimental_env must be { passthrough: [...] }`
+    );
+  }
+  const passthrough = Reflect.get(value, "passthrough");
+  if (!Array.isArray(passthrough)) {
+    throw new Error(
+      `provider "${providerId}" experimental_env.passthrough must be an array of variable names`
+    );
+  }
+  if (passthrough.length > PROVIDER_ENV_PASSTHROUGH_MAX) {
+    throw new Error(
+      `provider "${providerId}" experimental_env.passthrough names more than ${PROVIDER_ENV_PASSTHROUGH_MAX} variables`
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const name of passthrough) {
+    if (typeof name !== "string" || !PROVIDER_ENV_NAME_PATTERN.test(name)) {
+      throw new Error(
+        `provider "${providerId}" experimental_env.passthrough entries must match ${PROVIDER_ENV_NAME_PATTERN}`
+      );
+    }
+    if (seen.has(name)) {
+      throw new Error(
+        `provider "${providerId}" experimental_env.passthrough repeats ${JSON.stringify(name)}`
+      );
+    }
+    seen.add(name);
+  }
+  return Object.freeze([...seen]);
+}
+function validateProviderFallbackModels(providerId, value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(
+      `provider "${providerId}" experimental_models must be { fallback: [...] }`
+    );
+  }
+  const fallback = Reflect.get(value, "fallback");
+  if (!Array.isArray(fallback)) {
+    throw new Error(
+      `provider "${providerId}" experimental_models.fallback must be an array`
+    );
+  }
+  if (fallback.length > PROVIDER_FALLBACK_MODELS_MAX) {
+    throw new Error(
+      `provider "${providerId}" experimental_models.fallback lists more than ${PROVIDER_FALLBACK_MODELS_MAX} models`
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  let defaults = 0;
+  const normalized = fallback.map((entry, index) => {
+    const field = `experimental_models.fallback[${index}]`;
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+      throw new Error(`provider "${providerId}" ${field} must be an object`);
+    }
+    const record = Object.fromEntries(
+      Object.entries(entry)
+    );
+    const id = requireNonBlankString({
+      providerId,
+      field: `${field}.id`,
+      value: record.id
+    });
+    if (seen.has(id)) {
+      throw new Error(
+        `provider "${providerId}" experimental_models.fallback id ${JSON.stringify(id)} is duplicated`
+      );
+    }
+    seen.add(id);
+    const displayName = requireNonBlankString({
+      providerId,
+      field: `${field}.displayName`,
+      value: record.displayName
+    });
+    const description = requireNonBlankString({
+      providerId,
+      field: `${field}.description`,
+      value: record.description
+    });
+    const efforts = record.supportedReasoningEfforts;
+    if (!Array.isArray(efforts) || efforts.length === 0) {
+      throw new Error(
+        `provider "${providerId}" ${field}.supportedReasoningEfforts must be a non-empty array`
+      );
+    }
+    const levels = /* @__PURE__ */ new Set();
+    const supportedReasoningEfforts = efforts.map(
+      (effort, effortIndex) => {
+        if (typeof effort !== "object" || effort === null || Array.isArray(effort)) {
+          throw new Error(
+            `provider "${providerId}" ${field}.supportedReasoningEfforts[${effortIndex}] must be { reasoningEffort, description }`
+          );
+        }
+        const reasoningEffort = Reflect.get(effort, "reasoningEffort");
+        if (typeof reasoningEffort !== "string" || !PLUGIN_PROVIDER_REASONING_LEVEL_VALUES.includes(
+          reasoningEffort
+        )) {
+          throw new Error(
+            `provider "${providerId}" ${field}.supportedReasoningEfforts[${effortIndex}].reasoningEffort must be one of ${PLUGIN_PROVIDER_REASONING_LEVEL_VALUES.join(", ")}`
+          );
+        }
+        const level = reasoningEffort;
+        if (levels.has(level)) {
+          throw new Error(
+            `provider "${providerId}" ${field}.supportedReasoningEfforts repeats ${JSON.stringify(level)}`
+          );
+        }
+        levels.add(level);
+        return Object.freeze({
+          reasoningEffort: level,
+          description: requireNonBlankString({
+            providerId,
+            field: `${field}.supportedReasoningEfforts[${effortIndex}].description`,
+            value: Reflect.get(effort, "description")
+          })
+        });
+      }
+    );
+    const defaultReasoningEffort = record.defaultReasoningEffort;
+    if (typeof defaultReasoningEffort !== "string" || !levels.has(defaultReasoningEffort)) {
+      throw new Error(
+        `provider "${providerId}" ${field}.defaultReasoningEffort must be one of its supportedReasoningEfforts`
+      );
+    }
+    if (typeof record.isDefault !== "boolean") {
+      throw new Error(
+        `provider "${providerId}" ${field}.isDefault must be a boolean`
+      );
+    }
+    if (record.isDefault) defaults += 1;
+    return Object.freeze({
+      id,
+      displayName,
+      description,
+      supportedReasoningEfforts: Object.freeze(supportedReasoningEfforts),
+      defaultReasoningEffort,
+      isDefault: record.isDefault
+    });
+  });
+  if (normalized.length > 0 && defaults !== 1) {
+    throw new Error(
+      `provider "${providerId}" experimental_models.fallback must mark exactly one model isDefault (found ${defaults})`
+    );
+  }
+  return Object.freeze(normalized);
+}
 function validatePluginProviderDeclaration(declaration) {
   if (typeof declaration !== "object" || declaration === null) {
     throw new Error("provider declaration must be an object");
@@ -330,6 +643,12 @@ function validatePluginProviderDeclaration(declaration) {
       `invalid provider id ${JSON.stringify(id)} \u2014 use 2-64 lowercase letters, digits, and "-", starting with a letter or digit`
     );
   }
+  const family = declaration.experimental_family;
+  if (family !== void 0 && (typeof family !== "string" || !PROVIDER_ID_PATTERN.test(family))) {
+    throw new Error(
+      `provider "${id}" experimental_family must use the provider id grammar (2-64 lowercase letters, digits, and "-")`
+    );
+  }
   const displayName = typeof declaration.displayName === "string" ? declaration.displayName.trim() : "";
   if (displayName.length === 0 || displayName.length > PLUGIN_PROVIDER_DISPLAY_NAME_MAX_CHARS) {
     throw new Error(
@@ -380,8 +699,7 @@ function validatePluginProviderDeclaration(declaration) {
     "supportsNativeUserQuestion",
     "supportsManualCompaction",
     "supportsThreadArchive",
-    "supportsThreadRename",
-    "supportsWorkflows"
+    "supportsThreadRename"
   ];
   for (const field of booleanCapabilityFields) {
     if (typeof capabilities[field] !== "boolean") {
@@ -405,7 +723,6 @@ function validatePluginProviderDeclaration(declaration) {
     supportsManualCompaction: capabilities.supportsManualCompaction,
     supportsThreadArchive: capabilities.supportsThreadArchive,
     supportsThreadRename: capabilities.supportsThreadRename,
-    supportsWorkflows: capabilities.supportsWorkflows,
     permissionModes: validateProviderLiteralArray({
       providerId: id,
       field: "capabilities.permissionModes",
@@ -443,16 +760,57 @@ function validatePluginProviderDeclaration(declaration) {
       `provider "${id}" experimental_visibility "installed" requires experimental_providerHealth`
     );
   }
+  const strings = declaration.experimental_strings === void 0 ? void 0 : validateProviderStrings(id, declaration.experimental_strings);
+  const serviceTiers = declaration.experimental_serviceTiers === void 0 ? void 0 : validateProviderOptionDescriptors({
+    providerId: id,
+    field: "experimental_serviceTiers",
+    value: declaration.experimental_serviceTiers
+  });
+  const reasoningLevels = declaration.experimental_reasoningLevels === void 0 ? void 0 : validateProviderOptionDescriptors({
+    providerId: id,
+    field: "experimental_reasoningLevels",
+    value: declaration.experimental_reasoningLevels
+  });
+  const extensionKinds = declaration.experimental_extensionKinds === void 0 ? void 0 : validateProviderExtensionKinds(
+    id,
+    declaration.experimental_extensionKinds
+  );
+  const fallbackModels = declaration.experimental_models === void 0 ? void 0 : validateProviderFallbackModels(id, declaration.experimental_models);
+  const envPassthrough = declaration.experimental_env === void 0 ? void 0 : validateProviderEnvPassthrough(id, declaration.experimental_env);
+  const deriveProviderOptions = declaration.experimental_deriveProviderOptions;
+  if (deriveProviderOptions !== void 0 && typeof deriveProviderOptions !== "function") {
+    throw new Error(
+      `provider "${id}" experimental_deriveProviderOptions must be a function (context) => providerOptions`
+    );
+  }
   return Object.freeze({
     id,
     displayName,
+    ...family === void 0 ? {} : { experimental_family: family },
     ...icon === void 0 ? {} : { icon },
     ...bridgeOptions === void 0 ? {} : { experimental_bridgeOptions: bridgeOptions },
     experimental_visibility: visibility,
     capabilities: normalizedCapabilities,
-    composerActions
+    composerActions,
+    ...strings === void 0 ? {} : { experimental_strings: strings },
+    ...serviceTiers === void 0 ? {} : { experimental_serviceTiers: serviceTiers },
+    ...reasoningLevels === void 0 ? {} : { experimental_reasoningLevels: reasoningLevels },
+    ...extensionKinds === void 0 ? {} : { experimental_extensionKinds: extensionKinds },
+    ...fallbackModels === void 0 ? {} : { experimental_models: Object.freeze({ fallback: fallbackModels }) },
+    ...envPassthrough === void 0 ? {} : { experimental_env: Object.freeze({ passthrough: envPassthrough }) },
+    ...deriveProviderOptions === void 0 ? {} : { experimental_deriveProviderOptions: deriveProviderOptions }
   });
 }
+function deriveValidatedProviderOptions(args) {
+  const hook = args.declaration.experimental_deriveProviderOptions;
+  if (hook === void 0) return Object.freeze({});
+  const result = hook(args.context);
+  return normalizeProviderBridgeOptions(
+    args.declaration.id,
+    result,
+    "experimental_deriveProviderOptions result"
+  );
+}
 function isStandardSchema(value) {
   if (typeof value !== "object" || value === null) return false;
   const standard = Reflect.get(value, "~standard");
@@ -723,6 +1081,7 @@ export {
   SETTING_KEY_PATTERN,
   adoptHttpRouteResponse,
   assertNoRecursiveJsonSchemaReferences,
+  deriveValidatedProviderOptions,
   enforcePluginCliOutputLimit,
   isPluginMentionTrigger,
   isStandardSchema,