@get-bb/plugin-sdk 0.4.14 → 0.4.16

package/dist/internal/host-policy.js

@@ -1,10 +1,25 @@
 // src/internal/host-policy.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 
 // ../domain/src/plugin-icon.ts
 function isPluginOwnedIconPath(icon) {
   return icon.startsWith("./");
 }
+var PLUGIN_ICON_MAX_BYTES = 32 * 1024;
+var NAMESPACED_GLYPH_PATTERN = /^[a-z0-9-]+\/[a-z0-9][a-z0-9-]*$/u;
+function isNamespacedGlyph(glyph) {
+  return NAMESPACED_GLYPH_PATTERN.test(glyph);
+}
+function parseNamespacedGlyph(glyph) {
+  if (!isNamespacedGlyph(glyph)) {
+    return null;
+  }
+  const separator = glyph.indexOf("/");
+  return {
+    pluginId: glyph.slice(0, separator),
+    name: glyph.slice(separator + 1)
+  };
+}
 
 // ../domain/src/plugin-cli.ts
 var RESERVED_BB_CLI_COMMANDS = [
@@ -26,6 +41,213 @@ import { z } from "zod";
 var PROVIDER_FORK_VALUES = ["none", "tip", "checkpoint"];
 var providerForkSchema = z.enum(PROVIDER_FORK_VALUES);
 
+// ../domain/src/provider-skill-roots.ts
+function isAbsoluteProviderSkillRootPath(value) {
+  if (value.length === 0) {
+    return false;
+  }
+  const normalized = value.replaceAll("\\", "/");
+  const drive = /^[a-zA-Z]:\//u.exec(normalized);
+  const rest = drive ? normalized.slice(drive[0].length) : normalized.slice(1);
+  if (!drive && !normalized.startsWith("/")) {
+    return false;
+  }
+  return rest.split("/").every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}
+function isRelativeProviderSkillRootPath(value) {
+  if (value.length === 0) {
+    return false;
+  }
+  const normalized = value.replaceAll("\\", "/");
+  return !normalized.startsWith("/") && !/^[a-zA-Z]:\//u.test(normalized) && normalized.split("/").every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}
+
+// ../domain/src/native-roots.ts
+import { z as z2 } 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(
+  (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(
+  isRelativeProviderSkillRootPath,
+  "A manifest marker is a relative path without dot segments"
+);
+var relativeNativeRootPathSchema = z2.string().min(1).refine(
+  isRelativeProviderSkillRootPath,
+  "Roots must be relative paths without dot segments"
+);
+var absoluteNativeRootPathSchema = z2.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),
+    /** Skills nest in subdirectories (the agent scans recursively). */
+    recursive: z2.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(),
+    /**
+     * Prepended to every name under the root, a vendor plugin's
+     * `plugin-name:`; a prefixed root is listed as a plugin root.
+     */
+    namePrefix: nativeRootNamePrefixSchema.optional(),
+    /**
+     * A file, relative to a skill directory under this root, that marks the
+     * directory as a vendor plugin rather than a skill (Claude's
+     * `.claude-plugin/plugin.json`): bb skips such a directory. The plugin
+     * that knows the vendor layout declares it; core names no vendor path.
+     */
+    skipIfManifest: nativeRootManifestPathSchema.optional()
+  }).strict()
+]);
+var providerNativeRootsInputSchema = z2.object({
+  user: z2.array(providerNativeRootInputSchema).optional(),
+  project: z2.array(providerNativeRootInputSchema).optional()
+}).strict();
+var providerNativeRootSchema = z2.object({
+  path: z2.string().min(1),
+  recursive: z2.boolean(),
+  ancestors: z2.boolean(),
+  namePrefix: nativeRootNamePrefixSchema,
+  /** Absent: every skill-shaped directory under the root is a skill. */
+  skipIfManifest: nativeRootManifestPathSchema.optional()
+}).strict();
+function uniqueByPath(roots) {
+  return new Set(roots.map((root) => root.path)).size === roots.length;
+}
+function nativeRootSideSchema(side) {
+  return z2.array(
+    providerNativeRootSchema.extend({ path: relativeNativeRootPathSchema }).superRefine((root, context) => {
+      if (root.ancestors && side !== "project") {
+        context.addIssue({
+          code: "custom",
+          message: "Only project roots may walk ancestors"
+        });
+      }
+    })
+  ).max(PROVIDER_NATIVE_ROOTS_MAX).refine(uniqueByPath, "Roots must not repeat a path");
+}
+var providerNativeRootsSchema = z2.object({
+  user: nativeRootSideSchema("user"),
+  project: nativeRootSideSchema("project")
+}).strict();
+var EMPTY_PROVIDER_NATIVE_ROOTS = Object.freeze({
+  user: Object.freeze([]),
+  project: Object.freeze([])
+});
+function normalizeProviderNativeRoot(entry) {
+  if (typeof entry === "string") {
+    return { path: entry, recursive: false, ancestors: false, namePrefix: "" };
+  }
+  return {
+    path: entry.path,
+    recursive: entry.recursive ?? false,
+    ancestors: entry.ancestors ?? false,
+    namePrefix: entry.namePrefix ?? "",
+    ...entry.skipIfManifest === void 0 ? {} : { skipIfManifest: entry.skipIfManifest }
+  };
+}
+function normalizeProviderNativeRoots(roots) {
+  return {
+    user: (roots?.user ?? []).map(normalizeProviderNativeRoot),
+    project: (roots?.project ?? []).map(normalizeProviderNativeRoot)
+  };
+}
+var providerResolvedNativeRootShapeSchema = z2.enum([
+  "skills",
+  "skill",
+  "skill-file",
+  "commands",
+  "command-file"
+]);
+var resolvedNativeRootFieldsSchema = z2.object({
+  path: absoluteNativeRootPathSchema,
+  origin: z2.enum(["user", "project"]),
+  recursive: z2.boolean(),
+  /** Only with origin `project`, for a path inside the workspace. */
+  ancestors: z2.boolean(),
+  namePrefix: nativeRootNamePrefixSchema,
+  shape: providerResolvedNativeRootShapeSchema,
+  /**
+   * `skill-file` only: the skill name when the file's frontmatter names
+   * 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(),
+  /**
+   * `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
+   * daemon skips such a directory (see the declared root's `skipIfManifest`).
+   */
+  skipIfManifest: nativeRootManifestPathSchema.optional()
+}).strict();
+var providerResolvedNativeRootSchema = resolvedNativeRootFieldsSchema.superRefine((root, context) => {
+  if (root.skipIfManifest !== void 0 && root.shape !== "skills") {
+    context.addIssue({
+      code: "custom",
+      message: "Only a skills root carries a manifest marker"
+    });
+  }
+  if (root.ancestors && root.origin !== "project") {
+    context.addIssue({
+      code: "custom",
+      message: "Only project roots may walk ancestors"
+    });
+  }
+  if (root.fallbackName !== void 0 && root.shape !== "skill-file") {
+    context.addIssue({
+      code: "custom",
+      message: "Only a skill-file root carries a fallback name"
+    });
+  }
+});
+var providerResolvedNativeRootInputSchema = resolvedNativeRootFieldsSchema.partial({
+  recursive: true,
+  ancestors: true,
+  namePrefix: true,
+  shape: true
+});
+var resolvedSkillShapes = /* @__PURE__ */ new Set([
+  "skills",
+  "skill",
+  "skill-file"
+]);
+var resolvedCommandShapes = /* @__PURE__ */ new Set([
+  "commands",
+  "command-file"
+]);
+var PROVIDER_RESOLVED_NATIVE_ROOTS_MAX = 256;
+var providerResolvedNativeRootsSchema = z2.object({
+  skills: z2.array(
+    providerResolvedNativeRootSchema.refine(
+      (root) => resolvedSkillShapes.has(root.shape),
+      "A skills root needs a skill shape"
+    )
+  ).max(PROVIDER_RESOLVED_NATIVE_ROOTS_MAX),
+  commands: z2.array(
+    providerResolvedNativeRootSchema.refine(
+      (root) => resolvedCommandShapes.has(root.shape),
+      "A commands root needs a command shape"
+    )
+  ).max(PROVIDER_RESOLVED_NATIVE_ROOTS_MAX)
+}).strict();
+var EMPTY_PROVIDER_RESOLVED_NATIVE_ROOTS = Object.freeze({
+  skills: Object.freeze([]),
+  commands: Object.freeze([])
+});
+var providerNativeRootSetSchema = z2.object({
+  skills: providerNativeRootsSchema,
+  commands: providerNativeRootsSchema,
+  resolved: providerResolvedNativeRootsSchema
+}).strict();
+
 // src/backend-contract.ts
 var PLUGIN_CLI_OUTPUT_MAX_BYTES = 1024 * 1024;
 
@@ -57,31 +279,38 @@ 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: z2.string().min(1),
-  description: z2.string().min(1).optional()
+  label: z3.string().min(1),
+  description: z3.string().min(1).optional()
 };
-var settingDescriptorSchema = z2.discriminatedUnion("type", [
-  z2.object({
-    type: z2.literal("string"),
+var settingDescriptorSchema = z3.discriminatedUnion("type", [
+  z3.object({
+    type: z3.literal("string"),
     ...settingsBaseFields,
-    secret: z2.literal(true).optional(),
-    default: z2.string().optional()
-  }).strict(),
-  z2.object({
-    type: z2.literal("boolean"),
+    secret: z3.literal(true).optional(),
+    experimental_multiline: z3.boolean().optional(),
+    default: z3.string().optional()
+  }).strict().refine(
+    (descriptor) => !(descriptor.secret === true && descriptor.experimental_multiline === true),
+    {
+      message: "a secret setting cannot be experimental_multiline",
+      path: ["experimental_multiline"]
+    }
+  ),
+  z3.object({
+    type: z3.literal("boolean"),
     ...settingsBaseFields,
-    default: z2.boolean().optional()
+    default: z3.boolean().optional()
   }).strict(),
-  z2.object({
-    type: z2.literal("select"),
+  z3.object({
+    type: z3.literal("select"),
     ...settingsBaseFields,
-    options: z2.array(z2.string().min(1)).min(1),
-    default: z2.string().optional()
+    options: z3.array(z3.string().min(1)).min(1),
+    default: z3.string().optional()
   }).strict(),
-  z2.object({
-    type: z2.literal("project"),
+  z3.object({
+    type: z3.literal("project"),
     ...settingsBaseFields,
-    default: z2.string().optional()
+    default: z3.string().optional()
   }).strict()
 ]);
 function registerSettingDescriptors(target, added) {
@@ -335,7 +564,7 @@ function requireNonBlankString(args) {
 function validateProviderStrings(providerId, value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     throw new Error(
-      `provider "${providerId}" experimental_strings must be an object`
+      `provider "${providerId}" strings must be an object`
     );
   }
   const record = Object.fromEntries(
@@ -343,12 +572,12 @@ function validateProviderStrings(providerId, value) {
   );
   const required = (field) => requireNonBlankString({
     providerId,
-    field: `experimental_strings.${field}`,
+    field: `strings.${field}`,
     value: record[field]
   });
   const optional = (field) => record[field] === void 0 ? void 0 : requireNonBlankString({
     providerId,
-    field: `experimental_strings.${field}`,
+    field: `strings.${field}`,
     value: record[field]
   });
   let iconTint;
@@ -356,7 +585,7 @@ function validateProviderStrings(providerId, value) {
     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 }`
+        `provider "${providerId}" strings.iconTint must be { light, dark }`
       );
     }
     const tintRecord = Object.fromEntries(
@@ -365,12 +594,12 @@ function validateProviderStrings(providerId, value) {
     iconTint = Object.freeze({
       light: requireNonBlankString({
         providerId,
-        field: "experimental_strings.iconTint.light",
+        field: "strings.iconTint.light",
         value: tintRecord.light
       }),
       dark: requireNonBlankString({
         providerId,
-        field: "experimental_strings.iconTint.dark",
+        field: "strings.iconTint.dark",
         value: tintRecord.dark
       })
     });
@@ -437,42 +666,42 @@ function validateProviderOptionDescriptors(args) {
 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`
+      `provider "${providerId}" 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`
+      `provider "${providerId}" 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}`
+        `provider "${providerId}" 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? }`
+        `provider "${providerId}" 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`
+        `provider "${providerId}" 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`
+        `provider "${providerId}" 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`
+        `provider "${providerId}" extensionKinds.${name}.state must be a Standard Schema v1 validator`
       );
     }
     normalized[name] = Object.freeze({
@@ -488,57 +717,98 @@ 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: [...] }`
+      `provider "${providerId}" 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`
+      `provider "${providerId}" 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`
+      `provider "${providerId}" 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}`
+        `provider "${providerId}" 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)}`
+        `provider "${providerId}" env.passthrough repeats ${JSON.stringify(name)}`
       );
     }
     seen.add(name);
   }
   return Object.freeze([...seen]);
 }
+function validateProviderNativeRoots(providerId, field, value) {
+  const input = providerNativeRootsInputSchema.safeParse(value);
+  if (!input.success) {
+    const issue = input.error.issues[0];
+    const where = issue?.path.length ? `.${issue.path.join(".")}` : "";
+    throw new Error(
+      `provider "${providerId}" ${field}${where} ${issue?.message ?? "is invalid"}`
+    );
+  }
+  const normalized = normalizeProviderNativeRoots(input.data);
+  const wire = providerNativeRootsSchema.safeParse(normalized);
+  if (!wire.success) {
+    const issue = wire.error.issues[0];
+    const where = issue?.path.length ? `.${issue.path.join(".")}` : "";
+    throw new Error(
+      `provider "${providerId}" ${field}${where} ${issue?.message ?? "is invalid"}`
+    );
+  }
+  return Object.freeze({
+    user: Object.freeze(wire.data.user.map((root) => Object.freeze(root))),
+    project: Object.freeze(wire.data.project.map((root) => Object.freeze(root)))
+  });
+}
+var PROVIDER_MODEL_CATALOG_SCOPES = [
+  "host",
+  "workspace"
+];
+function validateProviderModelCatalogScope(providerId, value) {
+  if (value === void 0) {
+    return "workspace";
+  }
+  if (typeof value !== "string" || !PROVIDER_MODEL_CATALOG_SCOPES.includes(value)) {
+    throw new Error(
+      `provider "${providerId}" models.scope must be one of ${PROVIDER_MODEL_CATALOG_SCOPES.join(", ")}`
+    );
+  }
+  return value;
+}
 function validateProviderFallbackModels(providerId, value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     throw new Error(
-      `provider "${providerId}" experimental_models must be { fallback: [...] }`
+      `provider "${providerId}" models must be an object`
     );
   }
   const fallback = Reflect.get(value, "fallback");
+  if (fallback === void 0) {
+    return void 0;
+  }
   if (!Array.isArray(fallback)) {
     throw new Error(
-      `provider "${providerId}" experimental_models.fallback must be an array`
+      `provider "${providerId}" 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`
+      `provider "${providerId}" 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}]`;
+    const field = `models.fallback[${index}]`;
     if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
       throw new Error(`provider "${providerId}" ${field} must be an object`);
     }
@@ -552,7 +822,7 @@ function validateProviderFallbackModels(providerId, value) {
     });
     if (seen.has(id)) {
       throw new Error(
-        `provider "${providerId}" experimental_models.fallback id ${JSON.stringify(id)} is duplicated`
+        `provider "${providerId}" models.fallback id ${JSON.stringify(id)} is duplicated`
       );
     }
     seen.add(id);
@@ -628,11 +898,153 @@ function validateProviderFallbackModels(providerId, value) {
   });
   if (normalized.length > 0 && defaults !== 1) {
     throw new Error(
-      `provider "${providerId}" experimental_models.fallback must mark exactly one model isDefault (found ${defaults})`
+      `provider "${providerId}" models.fallback must mark exactly one model isDefault (found ${defaults})`
     );
   }
   return Object.freeze(normalized);
 }
+var AI_SERVICE_KINDS = /* @__PURE__ */ new Set(["inference", "voice"]);
+var SERVER_DIRECT_AI_SERVICE_IDS = Object.freeze([
+  "openai",
+  "amazon-bedrock",
+  "ant-ling",
+  "anthropic",
+  "azure-openai-responses",
+  "baseten",
+  "cerebras",
+  "cloudflare-ai-gateway",
+  "cloudflare-workers-ai",
+  "deepseek",
+  "fireworks",
+  "github-copilot",
+  "google",
+  "google-vertex",
+  "groq",
+  "huggingface",
+  "kimi-coding",
+  "minimax",
+  "minimax-cn",
+  "mistral",
+  "moonshotai",
+  "moonshotai-cn",
+  "nvidia",
+  "openai-codex",
+  "opencode",
+  "opencode-go",
+  "openrouter",
+  "qwen-token-plan",
+  "qwen-token-plan-cn",
+  "radius",
+  "together",
+  "vercel-ai-gateway",
+  "xai",
+  "xiaomi",
+  "xiaomi-token-plan-ams",
+  "xiaomi-token-plan-cn",
+  "xiaomi-token-plan-sgp",
+  "zai",
+  "zai-coding-cn"
+]);
+function validatePluginAiServiceDeclaration(declaration) {
+  if (typeof declaration !== "object" || declaration === null) {
+    throw new Error("AI service declaration must be an object");
+  }
+  const id = declaration.id;
+  if (typeof id !== "string" || !PROVIDER_ID_PATTERN.test(id)) {
+    throw new Error(
+      `invalid AI service id ${JSON.stringify(id)} \u2014 use 2-64 lowercase letters, digits, and "-", starting with a letter or digit`
+    );
+  }
+  const displayName = typeof declaration.displayName === "string" ? declaration.displayName.trim() : "";
+  if (displayName.length === 0 || displayName.length > 64) {
+    throw new Error(
+      `AI service "${id}" displayName must be 1-64 characters`
+    );
+  }
+  const kinds = declaration.kinds;
+  if (!Array.isArray(kinds) || kinds.length === 0) {
+    throw new Error(`AI service "${id}" must declare at least one kind`);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const kind of kinds) {
+    if (typeof kind !== "string" || !AI_SERVICE_KINDS.has(kind)) {
+      throw new Error(
+        `AI service "${id}" kind ${JSON.stringify(kind)} is not one of: ${[...AI_SERVICE_KINDS].join(", ")}`
+      );
+    }
+    if (seen.has(kind)) {
+      throw new Error(`AI service "${id}" declares kind "${kind}" twice`);
+    }
+    seen.add(kind);
+  }
+  return Object.freeze({
+    id,
+    displayName,
+    kinds: Object.freeze([...seen])
+  });
+}
+function assertAiServiceRegistrable(args) {
+  if (SERVER_DIRECT_AI_SERVICE_IDS.includes(args.id)) {
+    throw new Error(
+      `AI service id "${args.id}" is reserved: the server serves it directly, so a plugin cannot register it`
+    );
+  }
+  if (args.hostArtifact !== null) {
+    return { artifact: args.hostArtifact, problem: null };
+  }
+  if (args.hostArtifactProblem !== null) {
+    return { artifact: null, problem: args.hostArtifactProblem };
+  }
+  throw new Error(
+    `AI service "${args.id}" needs a bb.host entry to run on: this plugin declares none`
+  );
+}
+function aiServiceAlreadyRegisteredMessage(id) {
+  return `AI service "${id}" is already registered; a plugin cannot shadow an existing service.`;
+}
+function providerAlreadyRegisteredMessage(id) {
+  return `Provider "${id}" is already registered; a plugin cannot shadow an existing provider.`;
+}
+var RENAMED_PROVIDER_DECLARATION_FIELDS = Object.freeze({
+  experimental_family: "family",
+  experimental_strings: "strings",
+  experimental_serviceTiers: "serviceTiers",
+  experimental_reasoningLevels: "reasoningLevels",
+  experimental_extensionKinds: "extensionKinds",
+  experimental_models: "models",
+  experimental_env: "env",
+  experimental_deriveProviderOptions: "deriveProviderOptions"
+});
+var MOVED_PROVIDER_CAPABILITY_FIELDS = Object.freeze({
+  experimental_providerHealth: "maintenance.health",
+  experimental_providerUsage: "maintenance.usage",
+  experimental_providerInstallation: "maintenance.installation"
+});
+var READ_EXPERIMENTAL_PROVIDER_DECLARATION_FIELDS = /* @__PURE__ */ new Set([
+  "experimental_bridgeOptions",
+  "experimental_visibility",
+  "experimental_nativeSkillRoots",
+  "experimental_nativeCommandRoots",
+  "experimental_resolvesNativeRoots"
+]);
+var RENAMED_PROVIDER_FIELDS_SDK_VERSION = "0.4.16";
+function rejectStaleExperimentalFields(args) {
+  for (const key of Object.keys(args.value)) {
+    if (!key.startsWith("experimental_") || args.read.has(key)) {
+      continue;
+    }
+    const replacement = Object.hasOwn(args.renamed, key) ? args.renamed[key] : void 0;
+    const field = `${args.scope}${key}`;
+    if (replacement === void 0) {
+      throw new Error(
+        `provider "${args.providerId}": unknown declaration field "${field}"`
+      );
+    }
+    throw new Error(
+      `provider "${args.providerId}": "${field}" was ${args.verb} to "${replacement}" in SDK ${RENAMED_PROVIDER_FIELDS_SDK_VERSION}`
+    );
+  }
+}
 function validatePluginProviderDeclaration(declaration) {
   if (typeof declaration !== "object" || declaration === null) {
     throw new Error("provider declaration must be an object");
@@ -643,10 +1055,18 @@ 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;
+  rejectStaleExperimentalFields({
+    providerId: id,
+    value: declaration,
+    scope: "",
+    read: READ_EXPERIMENTAL_PROVIDER_DECLARATION_FIELDS,
+    renamed: RENAMED_PROVIDER_DECLARATION_FIELDS,
+    verb: "renamed"
+  });
+  const family = declaration.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 "-")`
+      `provider "${id}" family must use the provider id grammar (2-64 lowercase letters, digits, and "-")`
     );
   }
   const displayName = typeof declaration.displayName === "string" ? declaration.displayName.trim() : "";
@@ -659,14 +1079,16 @@ function validatePluginProviderDeclaration(declaration) {
   if (declaration.icon !== void 0) {
     if (typeof declaration.icon !== "string" || declaration.icon.trim() === "") {
       throw new Error(
-        `provider "${id}" icon must be a non-blank string \u2014 a named host glyph ("Zap") or a plugin-relative path ("./icons/agent.svg")`
+        `provider "${id}" icon must be a non-blank string \u2014 a named host glyph ("Zap"), a plugin-relative path ("./icons/agent.svg"), or a declared icon ("<pluginId>/<name>")`
       );
     }
     if (isPluginOwnedIconPath(declaration.icon)) {
       icon = validateProviderRelativePath(declaration.icon, `"${id}" icon`);
+    } else if (isNamespacedGlyph(declaration.icon)) {
+      icon = declaration.icon;
     } else if (/[/\\]/u.test(declaration.icon)) {
       throw new Error(
-        `provider "${id}" icon looks like a path but does not start with "./" \u2014 use "./icons/agent.svg" for a plugin file, or a bare host glyph name like "Zap"`
+        `provider "${id}" icon looks like a path but does not start with "./" \u2014 use "./icons/agent.svg" for a plugin file, "<pluginId>/<name>" for a declared icon, or a bare host glyph name like "Zap"`
       );
     } else {
       icon = declaration.icon;
@@ -676,24 +1098,29 @@ function validatePluginProviderDeclaration(declaration) {
   if (typeof capabilities !== "object" || capabilities === null) {
     throw new Error(`provider "${id}" capabilities must be an object`);
   }
-  const experimentalProviderHealth = capabilities.experimental_providerHealth ?? false;
-  const experimentalProviderUsage = capabilities.experimental_providerUsage ?? false;
-  const experimentalProviderInstallation = capabilities.experimental_providerInstallation ?? false;
-  if (typeof experimentalProviderHealth !== "boolean") {
-    throw new Error(
-      `provider "${id}" capabilities.experimental_providerHealth must be a boolean`
-    );
-  }
-  if (typeof experimentalProviderUsage !== "boolean") {
-    throw new Error(
-      `provider "${id}" capabilities.experimental_providerUsage must be a boolean`
-    );
+  rejectStaleExperimentalFields({
+    providerId: id,
+    value: capabilities,
+    scope: "capabilities.",
+    read: /* @__PURE__ */ new Set(),
+    renamed: MOVED_PROVIDER_CAPABILITY_FIELDS,
+    verb: "moved"
+  });
+  const maintenance = declaration.maintenance ?? {};
+  if (typeof maintenance !== "object" || maintenance === null) {
+    throw new Error(`provider "${id}" maintenance must be an object`);
   }
-  if (typeof experimentalProviderInstallation !== "boolean") {
-    throw new Error(
-      `provider "${id}" capabilities.experimental_providerInstallation must be a boolean`
-    );
+  for (const key of ["health", "usage", "installation"]) {
+    const value = maintenance[key];
+    if (value !== void 0 && typeof value !== "boolean") {
+      throw new Error(`provider "${id}" maintenance.${key} must be a boolean`);
+    }
   }
+  const normalizedMaintenance = Object.freeze({
+    health: maintenance.health ?? false,
+    usage: maintenance.usage ?? false,
+    installation: maintenance.installation ?? false
+  });
   const booleanCapabilityFields = [
     "supportsServiceTier",
     "supportsNativeUserQuestion",
@@ -714,9 +1141,6 @@ function validatePluginProviderDeclaration(declaration) {
     );
   }
   const normalizedCapabilities = Object.freeze({
-    experimental_providerHealth: experimentalProviderHealth,
-    experimental_providerUsage: experimentalProviderUsage,
-    experimental_providerInstallation: experimentalProviderInstallation,
     supportsServiceTier: capabilities.supportsServiceTier,
     supportsNativeUserQuestion: capabilities.supportsNativeUserQuestion,
     fork: capabilities.fork,
@@ -755,60 +1179,87 @@ function validatePluginProviderDeclaration(declaration) {
       `provider "${id}" experimental_visibility must be "always" or "installed"`
     );
   }
-  if (visibility === "installed" && !normalizedCapabilities.experimental_providerHealth) {
+  if (visibility === "installed" && !normalizedMaintenance.health) {
     throw new Error(
-      `provider "${id}" experimental_visibility "installed" requires experimental_providerHealth`
+      `provider "${id}" experimental_visibility "installed" requires maintenance.health`
     );
   }
-  const strings = declaration.experimental_strings === void 0 ? void 0 : validateProviderStrings(id, declaration.experimental_strings);
-  const serviceTiers = declaration.experimental_serviceTiers === void 0 ? void 0 : validateProviderOptionDescriptors({
+  const strings = declaration.strings === void 0 ? void 0 : validateProviderStrings(id, declaration.strings);
+  const serviceTiers = declaration.serviceTiers === void 0 ? void 0 : validateProviderOptionDescriptors({
     providerId: id,
-    field: "experimental_serviceTiers",
-    value: declaration.experimental_serviceTiers
+    field: "serviceTiers",
+    value: declaration.serviceTiers
   });
-  const reasoningLevels = declaration.experimental_reasoningLevels === void 0 ? void 0 : validateProviderOptionDescriptors({
+  const reasoningLevels = declaration.reasoningLevels === void 0 ? void 0 : validateProviderOptionDescriptors({
     providerId: id,
-    field: "experimental_reasoningLevels",
-    value: declaration.experimental_reasoningLevels
+    field: "reasoningLevels",
+    value: declaration.reasoningLevels
   });
-  const extensionKinds = declaration.experimental_extensionKinds === void 0 ? void 0 : validateProviderExtensionKinds(
+  const extensionKinds = declaration.extensionKinds === void 0 ? void 0 : validateProviderExtensionKinds(
+    id,
+    declaration.extensionKinds
+  );
+  const fallbackModels = declaration.models === void 0 ? void 0 : validateProviderFallbackModels(id, declaration.models);
+  const modelCatalogScope = validateProviderModelCatalogScope(
+    id,
+    declaration.models?.scope
+  );
+  const envPassthrough = declaration.env === void 0 ? void 0 : validateProviderEnvPassthrough(id, declaration.env);
+  const nativeSkillRoots = declaration.experimental_nativeSkillRoots === void 0 ? void 0 : validateProviderNativeRoots(
+    id,
+    "experimental_nativeSkillRoots",
+    declaration.experimental_nativeSkillRoots
+  );
+  const nativeCommandRoots = declaration.experimental_nativeCommandRoots === void 0 ? void 0 : validateProviderNativeRoots(
     id,
-    declaration.experimental_extensionKinds
+    "experimental_nativeCommandRoots",
+    declaration.experimental_nativeCommandRoots
   );
-  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;
+  const resolvesNativeRoots = declaration.experimental_resolvesNativeRoots;
+  if (resolvesNativeRoots !== void 0 && typeof resolvesNativeRoots !== "boolean") {
+    throw new Error(
+      `provider "${id}" experimental_resolvesNativeRoots must be a boolean`
+    );
+  }
+  const deriveProviderOptions = declaration.deriveProviderOptions;
   if (deriveProviderOptions !== void 0 && typeof deriveProviderOptions !== "function") {
     throw new Error(
-      `provider "${id}" experimental_deriveProviderOptions must be a function (context) => providerOptions`
+      `provider "${id}" deriveProviderOptions must be a function (context) => providerOptions`
     );
   }
   return Object.freeze({
     id,
     displayName,
-    ...family === void 0 ? {} : { experimental_family: family },
+    ...family === void 0 ? {} : { family },
     ...icon === void 0 ? {} : { icon },
     ...bridgeOptions === void 0 ? {} : { experimental_bridgeOptions: bridgeOptions },
     experimental_visibility: visibility,
+    maintenance: normalizedMaintenance,
     capabilities: normalizedCapabilities,
     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 }
+    ...strings === void 0 ? {} : { strings },
+    ...serviceTiers === void 0 ? {} : { serviceTiers },
+    ...reasoningLevels === void 0 ? {} : { reasoningLevels },
+    ...extensionKinds === void 0 ? {} : { extensionKinds },
+    models: Object.freeze({
+      ...fallbackModels === void 0 ? {} : { fallback: fallbackModels },
+      scope: modelCatalogScope
+    }),
+    ...envPassthrough === void 0 ? {} : { env: Object.freeze({ passthrough: envPassthrough }) },
+    ...nativeSkillRoots === void 0 ? {} : { experimental_nativeSkillRoots: nativeSkillRoots },
+    ...nativeCommandRoots === void 0 ? {} : { experimental_nativeCommandRoots: nativeCommandRoots },
+    experimental_resolvesNativeRoots: resolvesNativeRoots ?? false,
+    ...deriveProviderOptions === void 0 ? {} : { deriveProviderOptions }
   });
 }
 function deriveValidatedProviderOptions(args) {
-  const hook = args.declaration.experimental_deriveProviderOptions;
+  const hook = args.declaration.deriveProviderOptions;
   if (hook === void 0) return Object.freeze({});
   const result = hook(args.context);
   return normalizeProviderBridgeOptions(
     args.declaration.id,
     result,
-    "experimental_deriveProviderOptions result"
+    "deriveProviderOptions result"
   );
 }
 function isStandardSchema(value) {
@@ -976,6 +1427,90 @@ function assertNoRecursiveJsonSchemaReferences(schema, subject) {
   }
   visit(schema);
 }
+var RENAMED_AGENT_TOOL_FIELDS = /* @__PURE__ */ new Map([
+  [
+    "experimental_presentation",
+    '"experimental_presentation" was renamed to "presentation" in SDK 0.4.16'
+  ],
+  [
+    "experimental_statusLabels",
+    '"experimental_statusLabels" was folded into "presentation" (labels) in SDK 0.4.16'
+  ]
+]);
+function rejectStaleAgentToolFields(toolName, tool) {
+  const unknownKeys = [];
+  for (const key of Object.keys(tool).sort()) {
+    const renamed = RENAMED_AGENT_TOOL_FIELDS.get(key);
+    if (renamed !== void 0) {
+      throw new Error(`registerTool: ${renamed} (tool "${toolName}")`);
+    }
+    if (key.startsWith("experimental_")) {
+      unknownKeys.push(key);
+    }
+  }
+  if (unknownKeys.length > 0) {
+    throw new Error(
+      `registerTool: tool "${toolName}" contains unknown field${unknownKeys.length === 1 ? "" : "s"}: ${unknownKeys.join(", ")}`
+    );
+  }
+}
+function parsePluginAgentToolPresentation(toolName, value) {
+  if (value === void 0) {
+    return null;
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(
+      `tool "${toolName}" presentation must be an object`
+    );
+  }
+  const declared = value;
+  const presentation = {};
+  if (declared.label !== void 0) {
+    const label = declared.label;
+    if (typeof label !== "object" || label === null || typeof label.pending !== "string" || typeof label.completed !== "string") {
+      throw new Error(
+        `tool "${toolName}" presentation.label must provide pending and completed strings`
+      );
+    }
+    const { pending, completed } = label;
+    if (pending.trim().length === 0 || completed.trim().length === 0 || pending.length > PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS || completed.length > PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS) {
+      throw new Error(
+        `tool "${toolName}" presentation.label strings must be non-empty and at most ${PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS} characters`
+      );
+    }
+    presentation.label = { pending, completed };
+  }
+  if (declared.icon !== void 0) {
+    const icon = declared.icon;
+    if (typeof icon !== "object" || icon === null || typeof icon.glyph !== "string" || icon.glyph.trim().length === 0) {
+      throw new Error(
+        `tool "${toolName}" presentation.icon must be { glyph: string }`
+      );
+    }
+    presentation.icon = { glyph: icon.glyph };
+  }
+  if (declared.suppress !== void 0) {
+    if (typeof declared.suppress !== "boolean") {
+      throw new Error(
+        `tool "${toolName}" presentation.suppress must be a boolean`
+      );
+    }
+    presentation.suppress = declared.suppress;
+  }
+  if (declared.tint !== void 0) {
+    const tint = declared.tint;
+    if (typeof tint !== "object" || tint === null || typeof tint.light !== "string" || typeof tint.dark !== "string") {
+      throw new Error(
+        `tool "${toolName}" presentation.tint must provide light and dark strings`
+      );
+    }
+    presentation.tint = {
+      light: tint.light,
+      dark: tint.dark
+    };
+  }
+  return presentation;
+}
 function summarizeParseIssues(error) {
   const issues = error?.issues;
   if (Array.isArray(issues) && issues.length > 0) {
@@ -1056,6 +1591,25 @@ function isResponseLike(value) {
   const candidate = value;
   return typeof candidate.status === "number" && typeof candidate.headers === "object" && candidate.headers !== null && typeof candidate.arrayBuffer === "function" && typeof candidate.clone === "function";
 }
+function undeclaredIconProblem(pluginId, declaredIconNames, glyph) {
+  const parsed = parseNamespacedGlyph(glyph);
+  if (parsed === null) {
+    return null;
+  }
+  if (parsed.pluginId !== pluginId || !declaredIconNames.has(parsed.name)) {
+    return `"${glyph}" is not an icon declared by plugin "${pluginId}"`;
+  }
+  return null;
+}
+function providerIconRefusalMessage(providerId, problem) {
+  return `provider "${providerId}" icon ${problem}`;
+}
+function agentToolIconRefusalMessage(toolName, problem) {
+  return `tool "${toolName}" presentation.icon ${problem}`;
+}
+function providerWithoutBridgeMessage(providerId) {
+  return `provider "${providerId}" has no bridge to run on: this plugin declares no "bb.host" entry in its manifest`;
+}
 export {
   AGENT_TOOL_NAME_PATTERN,
   BACKGROUND_NAME_PATTERN,
@@ -1078,8 +1632,12 @@ export {
   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,
@@ -1087,9 +1645,16 @@ export {
   isStandardSchema,
   isZodSchemaLike,
   normalizeMentionProviderTriggers,
+  parsePluginAgentToolPresentation,
+  providerAlreadyRegisteredMessage,
+  providerIconRefusalMessage,
+  providerWithoutBridgeMessage,
   readRpcMethodContract,
   registerSettingDescriptors,
+  rejectStaleAgentToolFields,
   summarizeParseIssues,
+  undeclaredIconProblem,
+  validatePluginAiServiceDeclaration,
   validatePluginProviderDeclaration,
   validateSettingsUpdate
 };