@get-bb/plugin-sdk 0.4.14 → 0.4.16

package/dist/testing/index.js

@@ -5,18 +5,34 @@ import { join } from "node:path";
 import Database from "better-sqlite3";
 import { CronExpressionParser } from "cron-parser";
 import { Hono } from "hono";
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 
 // ../domain/src/plugin-interaction-limits.ts
 var PLUGIN_INTERACTION_MAX_TITLE_LENGTH = 160;
+var PLUGIN_INTERACTION_MAX_PAYLOAD_BYTES = 64 * 1024;
 
 // src/internal/host-policy.ts
-import { z as 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 = [
@@ -38,6 +54,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;
 
@@ -69,31 +292,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) {
@@ -347,7 +577,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(
@@ -355,12 +585,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;
@@ -368,7 +598,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(
@@ -377,12 +607,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
       })
     });
@@ -449,42 +679,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({
@@ -500,57 +730,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`);
     }
@@ -564,7 +835,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);
@@ -640,11 +911,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");
@@ -655,10 +1068,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() : "";
@@ -671,14 +1092,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;
@@ -688,24 +1111,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",
@@ -726,9 +1154,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,
@@ -767,50 +1192,77 @@ 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,
-    declaration.experimental_extensionKinds
+    "experimental_nativeSkillRoots",
+    declaration.experimental_nativeSkillRoots
   );
-  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 nativeCommandRoots = declaration.experimental_nativeCommandRoots === void 0 ? void 0 : validateProviderNativeRoots(
+    id,
+    "experimental_nativeCommandRoots",
+    declaration.experimental_nativeCommandRoots
+  );
+  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 isStandardSchema(value) {
@@ -978,6 +1430,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) {
@@ -1058,6 +1594,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`;
+}
 
 // src/testing/fake-sdk.ts
 function withSpawnAttribution(pluginId, args) {
@@ -1442,6 +1997,7 @@ function createFakePluginHostInternal(options, sharedState) {
     )
   };
   const pluginId = options.pluginId ?? "test-plugin";
+  const declaredIconNames = new Set(options.experimental_declaredIconNames ?? []);
   const agentSkillIds = [...options.agentSkillIds ?? []];
   if (new Set(agentSkillIds).size !== agentSkillIds.length) {
     throw new Error("agentSkillIds must not contain duplicates");
@@ -1753,10 +2309,15 @@ function createFakePluginHostInternal(options, sharedState) {
   function registerProviderDeclaration(declaration) {
     assertLive();
     const normalized = validatePluginProviderDeclaration(declaration);
+    const iconProblem = normalized.icon === void 0 ? null : undeclaredIconProblem(pluginId, declaredIconNames, normalized.icon);
+    if (iconProblem !== null) {
+      throw new Error(providerIconRefusalMessage(normalized.id, iconProblem));
+    }
+    if (options.experimental_hostEntry === false) {
+      throw new Error(providerWithoutBridgeMessage(normalized.id));
+    }
     if (providerRegistrations.some((existing) => existing.id === normalized.id)) {
-      throw new Error(
-        `Provider "${normalized.id}" is already registered; a plugin cannot shadow an existing provider.`
-      );
+      throw new Error(providerAlreadyRegisteredMessage(normalized.id));
     }
     providerRegistrations.push(normalized);
     let disposed2 = false;
@@ -1769,6 +2330,31 @@ function createFakePluginHostInternal(options, sharedState) {
     disposeHooks.push(dispose);
     return { dispose };
   }
+  const aiServiceRegistrations = [];
+  const experimental_aiServices = {
+    register(declaration) {
+      assertLive();
+      const normalized = validatePluginAiServiceDeclaration(declaration);
+      assertAiServiceRegistrable({
+        id: normalized.id,
+        hostArtifact: options.experimental_hostEntry === false ? null : "declared",
+        hostArtifactProblem: null
+      });
+      if (aiServiceRegistrations.some((existing) => existing.id === normalized.id)) {
+        throw new Error(aiServiceAlreadyRegisteredMessage(normalized.id));
+      }
+      aiServiceRegistrations.push(normalized);
+      let disposed2 = false;
+      const dispose = () => {
+        if (disposed2) return;
+        disposed2 = true;
+        const index = aiServiceRegistrations.indexOf(normalized);
+        if (index !== -1) aiServiceRegistrations.splice(index, 1);
+      };
+      disposeHooks.push(dispose);
+      return { dispose };
+    }
+  };
   const agents = {
     configure(provider) {
       assertLive();
@@ -1794,9 +2380,6 @@ function createFakePluginHostInternal(options, sharedState) {
       }
       instructionProvider = provider;
     },
-    experimental_registerProvider(declaration) {
-      return registerProviderDeclaration(declaration);
-    },
     registerTool(tool) {
       assertLive();
       const name = tool?.name;
@@ -1810,6 +2393,7 @@ function createFakePluginHostInternal(options, sharedState) {
           `tool name "${name}" is a built-in bb tool \u2014 pick another name`
         );
       }
+      rejectStaleAgentToolFields(name, tool);
       if (typeof tool.description !== "string" || tool.description.trim().length === 0) {
         throw new Error(`tool "${name}" must provide a description`);
       }
@@ -1821,16 +2405,19 @@ function createFakePluginHostInternal(options, sharedState) {
           `tool "${name}" instructions exceed the ${PLUGIN_AGENT_STATIC_INSTRUCTIONS_MAX_CHARS}-character limit`
         );
       }
-      const experimentalStatusLabels = tool.experimental_statusLabels;
-      if (experimentalStatusLabels !== void 0 && (typeof experimentalStatusLabels !== "object" || experimentalStatusLabels === null || typeof experimentalStatusLabels.pending !== "string" || typeof experimentalStatusLabels.completed !== "string" || experimentalStatusLabels.pending.trim().length === 0 || experimentalStatusLabels.completed.trim().length === 0)) {
-        throw new Error(
-          `tool "${name}" experimental_statusLabels must provide non-empty pending and completed strings`
-        );
-      }
-      if (experimentalStatusLabels !== void 0 && (experimentalStatusLabels.pending.length > PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS || experimentalStatusLabels.completed.length > PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS)) {
-        throw new Error(
-          `tool "${name}" experimental_statusLabels exceed the ${PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS}-character limit`
+      const presentation = parsePluginAgentToolPresentation(
+        name,
+        tool.presentation
+      );
+      if (presentation?.icon !== void 0) {
+        const problem = undeclaredIconProblem(
+          pluginId,
+          declaredIconNames,
+          presentation.icon.glyph
         );
+        if (problem !== null) {
+          throw new Error(agentToolIconRefusalMessage(name, problem));
+        }
       }
       if (typeof tool.execute !== "function") {
         throw new Error(
@@ -1842,7 +2429,7 @@ function createFakePluginHostInternal(options, sharedState) {
       let parse;
       if (isZodSchemaLike(parameters)) {
         try {
-          inputSchema = z3.toJSONSchema(parameters, {
+          inputSchema = z4.toJSONSchema(parameters, {
             io: "input"
           });
         } catch (error) {
@@ -1876,10 +2463,7 @@ function createFakePluginHostInternal(options, sharedState) {
       const record = {
         name,
         description: tool.description,
-        experimentalStatusLabels: experimentalStatusLabels === void 0 ? null : {
-          pending: experimentalStatusLabels.pending,
-          completed: experimentalStatusLabels.completed
-        },
+        presentation,
         instructions: tool.instructions !== void 0 && tool.instructions.trim().length > 0 ? tool.instructions : null,
         inputSchema,
         parse,
@@ -1937,10 +2521,15 @@ function createFakePluginHostInternal(options, sharedState) {
     }
   };
   const loopbackBaseUrl = options.loopbackBaseUrl ?? "http://127.0.0.1:38886";
+  const dataDir = options.dataDir ?? "/tmp/bb-fake-data-dir";
   const server = {
     get loopbackBaseUrl() {
       assertLive();
       return loopbackBaseUrl;
+    },
+    get experimental_dataDir() {
+      assertLive();
+      return dataDir;
     }
   };
   const { sdk, harness: sdkHarness } = createFakeSdk({
@@ -2004,24 +2593,24 @@ function createFakePluginHostInternal(options, sharedState) {
       timeoutMs
     };
     const id = `fake-interaction-${nextInteractionId++}`;
-    return new Promise((resolve) => {
+    return new Promise((resolve2) => {
       const settleAborted = () => {
         const pending = pendingInteractions.get(id);
         if (!pending) return;
         clearTimeout(pending.timer);
         pendingInteractions.delete(id);
-        resolve({ outcome: "cancelled", reason: "request-aborted" });
+        resolve2({ outcome: "cancelled", reason: "request-aborted" });
       };
       requestOptions?.signal?.addEventListener("abort", settleAborted, {
         once: true
       });
       const timer = setTimeout(() => {
         pendingInteractions.delete(id);
-        resolve({ outcome: "cancelled", reason: "timeout" });
+        resolve2({ outcome: "cancelled", reason: "timeout" });
       }, timeoutMs);
       pendingInteractions.set(id, {
         request: normalizedRequest,
-        resolve,
+        resolve: resolve2,
         timer
       });
     });
@@ -2188,6 +2777,7 @@ function createFakePluginHostInternal(options, sharedState) {
     status,
     server,
     hosts,
+    experimental_aiServices,
     get sdk() {
       assertLive();
       return sdk;
@@ -2273,7 +2863,8 @@ function createFakePluginHostInternal(options, sharedState) {
         };
       },
       mentionProviders,
-      providerRegistrations
+      providerRegistrations,
+      aiServiceRegistrations
     },
     get pendingInteractions() {
       return [...pendingInteractions].map(([id, pending]) => ({
@@ -2580,9 +3171,106 @@ function makeThreadResponse(overrides = {}) {
     ...overrides
   };
 }
+
+// src/testing/public-sdk-only.ts
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join as join2, relative, resolve, sep } from "node:path";
+var SKIPPED_DIRECTORIES = /* @__PURE__ */ new Set(["node_modules", "dist"]);
+var SOURCE_EXTENSIONS = /\.(?:[cm]?[jt]s|tsx)$/u;
+var TEST_FILE_PATTERN = /\.test\.[cm]?[jt]sx?$/u;
+var PRIVATE_PACKAGE_PREFIX = "@bb/";
+var PLUGIN_IMPORT_ALLOWLIST = [
+  /^@get-bb\/plugin-sdk$/u,
+  /^@get-bb\/plugin-sdk\/(?:host|app|ai-services|provider-bridge|provider-bridge\/acp)$/u,
+  /^zod$/u,
+  /^node:/u,
+  /^\.\.?\//u
+];
+var TEST_IMPORT_ALLOWLIST = [
+  /^@get-bb\/plugin-sdk\/(?:testing|testing\/app|testing\/host|provider-bridge\/testing)$/u,
+  /^vitest$/u
+];
+var IMPORT_SPECIFIER_PATTERN = /(?:\bfrom\s*|\bimport\s*\(?\s*|\brequire\s*\(\s*)["']([^"']+)["']/gu;
+var DYNAMIC_SPECIFIER_PATTERN = /\b(?:import|require)\s*\(\s*(?!["'])([^)]+)\)/gu;
+var RELATIVE_SPECIFIER_PATTERN = /^\.\.?\//u;
+function listSourceFiles(directory) {
+  const files = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (!SKIPPED_DIRECTORIES.has(entry.name)) {
+        files.push(...listSourceFiles(join2(directory, entry.name)));
+      }
+      continue;
+    }
+    if (SOURCE_EXTENSIONS.test(entry.name)) {
+      files.push(join2(directory, entry.name));
+    }
+  }
+  return files;
+}
+function importSpecifiers(source) {
+  return [...source.matchAll(IMPORT_SPECIFIER_PATTERN)].map(
+    (match) => match[1] ?? ""
+  );
+}
+function dynamicSpecifiers(source) {
+  return [...source.matchAll(DYNAMIC_SPECIFIER_PATTERN)].map(
+    (match) => (match[1] ?? "").trim()
+  );
+}
+function escapesPackage(packageRoot, file, specifier) {
+  const target = relative(packageRoot, resolve(dirname(file), specifier));
+  return isAbsolute(target) || target === ".." || target.startsWith(`..${sep}`);
+}
+function declaredDependencyNames(packageRoot) {
+  const manifest = JSON.parse(
+    readFileSync(join2(packageRoot, "package.json"), "utf8")
+  );
+  const names = [];
+  for (const field of ["dependencies", "devDependencies"]) {
+    const block = typeof manifest === "object" && manifest !== null && field in manifest ? manifest[field] : void 0;
+    if (typeof block === "object" && block !== null) {
+      names.push(...Object.keys(block));
+    }
+  }
+  return names;
+}
+function scanPublicSdkOnly(packageRoot, options = {}) {
+  const extra = options.allow ?? [];
+  const pluginAllowlist = [...PLUGIN_IMPORT_ALLOWLIST, ...extra];
+  const testAllowlist = [...pluginAllowlist, ...TEST_IMPORT_ALLOWLIST];
+  const files = [];
+  const violations = [];
+  for (const path of listSourceFiles(packageRoot)) {
+    const file = relative(packageRoot, path);
+    files.push(file);
+    const allowlist = TEST_FILE_PATTERN.test(path) ? testAllowlist : pluginAllowlist;
+    const source = readFileSync(path, "utf8");
+    for (const specifier of importSpecifiers(source)) {
+      if (specifier.startsWith(PRIVATE_PACKAGE_PREFIX)) {
+        violations.push({ file, specifier, reason: "private-package" });
+      } else if (RELATIVE_SPECIFIER_PATTERN.test(specifier) && escapesPackage(packageRoot, path, specifier) && !extra.some((pattern) => pattern.test(specifier))) {
+        violations.push({ file, specifier, reason: "outside-package" });
+      } else if (!allowlist.some((pattern) => pattern.test(specifier))) {
+        violations.push({ file, specifier, reason: "outside-allowlist" });
+      }
+    }
+    for (const specifier of dynamicSpecifiers(source)) {
+      violations.push({ file, specifier, reason: "dynamic-specifier" });
+    }
+  }
+  return {
+    files,
+    violations,
+    privateDependencies: declaredDependencyNames(packageRoot).filter(
+      (name) => name.startsWith(PRIVATE_PACKAGE_PREFIX)
+    )
+  };
+}
 export {
   PluginContextStaleError,
   createFakePluginHost,
   createFakeSdk,
+  scanPublicSdkOnly as experimental_scanPublicSdkOnly,
   makeThreadResponse
 };