@get-bb/plugin-sdk 0.4.84 → 0.4.87

package/dist/internal/host-policy.js

@@ -1,4 +1,5 @@
 // src/internal/host-policy.ts
+import { createHash } from "node:crypto";
 import { z as z4 } from "zod";
 
 // ../domain/src/plugin-icon.ts
@@ -44,6 +45,10 @@ var RESERVED_BB_CLI_COMMANDS = [
   "voice"
 ];
 
+// ../domain/src/plugin-interaction-limits.ts
+var PLUGIN_INTERACTION_MAX_TITLE_LENGTH = 160;
+var PLUGIN_INTERACTION_MAX_PAYLOAD_BYTES = 64 * 1024;
+
 // ../domain/src/provider-fork.ts
 import { z } from "zod";
 var PROVIDER_FORK_VALUES = ["none", "tip", "checkpoint"];
@@ -514,6 +519,22 @@ function validateSettingsUpdate(descriptors, values) {
   }
   return errors;
 }
+function coerceStoredPluginSettingValue(descriptor, value) {
+  let coerced = value;
+  if (descriptor.type === "number" && typeof coerced === "string") {
+    const legacyNumber = Number(coerced.trim());
+    coerced = coerced.trim().length > 0 && Number.isFinite(legacyNumber) ? legacyNumber : void 0;
+  }
+  if (descriptor.type === "number" && typeof coerced === "number" && !Number.isFinite(coerced)) {
+    coerced = void 0;
+  }
+  const expected = descriptor.type === "boolean" ? "boolean" : descriptor.type === "number" ? "number" : "string";
+  if (typeof coerced !== expected) coerced = void 0;
+  if (descriptor.type === "select" && typeof coerced === "string" && !descriptor.options.includes(coerced)) {
+    coerced = void 0;
+  }
+  return coerced ?? descriptor.default;
+}
 var PLUGIN_MENTION_TRIGGER_VALUES = [
   "@",
   "#",
@@ -1792,71 +1813,47 @@ var environmentCompositionSchema = z4.object({
   machineProviderId: z4.string().regex(ENVIRONMENT_PROVIDER_ID_PATTERN),
   environmentProviderId: z4.string().regex(ENVIRONMENT_PROVIDER_ID_PATTERN)
 }).strict();
-function validatePluginEnvironmentProviderDeclaration(declaration) {
+function requireProviderIdAndDisplayName(noun, declaration) {
   if (typeof declaration !== "object" || declaration === null) {
-    throw new Error("environment provider declaration must be an object");
+    throw new Error(`${noun} declaration must be an object`);
   }
   const id = declaration.id;
   if (typeof id !== "string" || !ENVIRONMENT_PROVIDER_ID_PATTERN.test(id)) {
     throw new Error(
-      `invalid environment provider id ${JSON.stringify(id)} \u2014 use 2-64 lowercase letters, digits, or "-", starting with a letter or digit`
+      `invalid ${noun} id ${JSON.stringify(id)} \u2014 use 2-64 lowercase letters, digits, or "-", starting with a letter or digit`
     );
   }
   const displayName = typeof declaration.displayName === "string" ? declaration.displayName.trim() : "";
   if (displayName.length === 0 || displayName.length > ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS) {
     throw new Error(
-      `environment provider "${id}" needs a displayName of 1-${ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS} characters`
+      `${noun} "${id}" needs a displayName of 1-${ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS} characters`
     );
   }
-  const description = z4.string().trim().min(1).max(ENVIRONMENT_PROVIDER_DESCRIPTION_MAX_CHARS).optional().transform((value) => value ?? null).parse(declaration.description);
-  const icon = z4.string().trim().min(1).optional().transform((value) => value ?? null).parse(declaration.icon);
-  if (icon !== null && isPluginOwnedIconPath(icon)) {
+  return { id, displayName };
+}
+function assertProviderIconShape(noun, id, icon) {
+  if (isPluginOwnedIconPath(icon)) {
     validateProviderRelativePath(icon, `"${id}" icon`);
-  } else if (icon !== null && !isNamespacedGlyph(icon) && /[/\\]/u.test(icon)) {
-    throw new Error(
-      `environment provider "${id}" icon must be a glyph, declared icon, or plugin-relative path`
-    );
-  }
-  const requires = normalizeEnvironmentProviderRequirements(id, declaration);
-  const inputs = normalizeEnvironmentProviderInputs(id, declaration);
-  if (typeof declaration.create !== "function" || typeof declaration.remove !== "function") {
-    throw new Error(
-      `environment provider "${id}" must declare create and remove functions`
-    );
-  }
-  if (declaration.validate !== void 0 && typeof declaration.validate !== "function") {
+  } else if (!isNamespacedGlyph(icon) && /[/\\]/u.test(icon)) {
     throw new Error(
-      `environment provider "${id}" declares a validate that is not a function`
+      `${noun} "${id}" icon must be a glyph, declared icon, or plugin-relative path`
     );
   }
-  if (declaration.availability !== void 0 && typeof declaration.availability !== "function") {
+}
+function assertOptionalFunction(noun, id, value, phrase) {
+  if (value !== void 0 && typeof value !== "function") {
     throw new Error(
-      `environment provider "${id}" declares availability that is not a function`
+      `${noun} "${id}" declares ${phrase} that is not a function`
     );
   }
-  return {
-    id,
-    displayName,
-    description,
-    icon,
-    requires,
-    inputs: inputs === null ? null : inputs.schema,
-    inputsJsonSchema: inputs === null ? null : inputs.jsonSchema,
-    availability: declaration.availability ?? null,
-    validate: declaration.validate ?? null,
-    create: declaration.create,
-    remove: declaration.remove,
-    policy: environmentProviderPolicySchema.parse(declaration.policy ?? {})
-  };
 }
-function normalizeEnvironmentProviderInputs(id, declaration) {
-  const inputs = declaration.inputs;
+function normalizeProviderInputs(noun, id, inputs) {
   if (inputs === void 0) {
     return null;
   }
   if (!isStandardSchema(inputs)) {
     throw new Error(
-      `environment provider "${id}" declares an inputs that is not a Standard Schema v1 validator`
+      `${noun} "${id}" declares an inputs that is not a Standard Schema v1 validator`
     );
   }
   let converted;
@@ -1864,17 +1861,65 @@ function normalizeEnvironmentProviderInputs(id, declaration) {
     converted = JSON.parse(JSON.stringify(standardSchemaToJsonSchema(inputs)));
   } catch (error) {
     throw new Error(
-      `environment provider "${id}" declares an inputs validator that cannot be published as JSON Schema (${error instanceof Error ? error.message : String(error)}) \u2014 declare it with zod 4 or a validator exposing toJSONSchema()`
+      `${noun} "${id}" declares an inputs validator that cannot be published as JSON Schema (${error instanceof Error ? error.message : String(error)}) \u2014 declare it with zod 4 or a validator exposing toJSONSchema()`
     );
   }
   const jsonSchema = jsonValueSchema.safeParse(converted);
   if (!jsonSchema.success) {
     throw new Error(
-      `environment provider "${id}" declares an inputs schema whose JSON Schema is not JSON-serializable`
+      `${noun} "${id}" declares an inputs schema whose JSON Schema is not JSON-serializable`
     );
   }
   return { schema: inputs, jsonSchema: jsonSchema.data };
 }
+function validatePluginEnvironmentProviderDeclaration(declaration) {
+  const { id, displayName } = requireProviderIdAndDisplayName(
+    "environment provider",
+    declaration
+  );
+  const description = z4.string().trim().min(1).max(ENVIRONMENT_PROVIDER_DESCRIPTION_MAX_CHARS).optional().transform((value) => value ?? null).parse(declaration.description);
+  const icon = z4.string().trim().min(1).optional().transform((value) => value ?? null).parse(declaration.icon);
+  if (icon !== null) {
+    assertProviderIconShape("environment provider", id, icon);
+  }
+  const requires = normalizeEnvironmentProviderRequirements(id, declaration);
+  const inputs = normalizeProviderInputs(
+    "environment provider",
+    id,
+    declaration.inputs
+  );
+  if (typeof declaration.create !== "function" || typeof declaration.remove !== "function") {
+    throw new Error(
+      `environment provider "${id}" must declare create and remove functions`
+    );
+  }
+  assertOptionalFunction(
+    "environment provider",
+    id,
+    declaration.validate,
+    "a validate"
+  );
+  assertOptionalFunction(
+    "environment provider",
+    id,
+    declaration.availability,
+    "availability"
+  );
+  return {
+    id,
+    displayName,
+    description,
+    icon,
+    requires,
+    inputs: inputs === null ? null : inputs.schema,
+    inputsJsonSchema: inputs === null ? null : inputs.jsonSchema,
+    availability: declaration.availability ?? null,
+    validate: declaration.validate ?? null,
+    create: declaration.create,
+    remove: declaration.remove,
+    policy: environmentProviderPolicySchema.parse(declaration.policy ?? {})
+  };
+}
 function normalizeEnvironmentProviderRequirements(id, declaration) {
   const requires = declaration.requires ?? {};
   if (typeof requires !== "object" || requires === null || Array.isArray(requires)) {
@@ -1908,32 +1953,19 @@ var environmentProviderPolicySchema = z4.object({
 }).strict();
 var MACHINE_PROVIDER_DESCRIPTION_MAX_CHARS = 200;
 function validatePluginMachineProviderDeclaration(declaration) {
-  if (typeof declaration !== "object" || declaration === null) {
-    throw new Error("machine provider declaration must be an object");
-  }
-  const id = declaration.id;
-  if (typeof id !== "string" || !ENVIRONMENT_PROVIDER_ID_PATTERN.test(id)) {
-    throw new Error(
-      `invalid machine provider id ${JSON.stringify(id)} \u2014 use 2-64 lowercase letters, digits, or "-", starting with a letter or digit`
-    );
-  }
-  const displayName = typeof declaration.displayName === "string" ? declaration.displayName.trim() : "";
-  if (displayName.length === 0 || displayName.length > ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS) {
-    throw new Error(
-      `machine provider "${id}" needs a displayName of 1-${ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS} characters`
-    );
-  }
+  const { id, displayName } = requireProviderIdAndDisplayName(
+    "machine provider",
+    declaration
+  );
   const description = z4.string().trim().min(1).max(MACHINE_PROVIDER_DESCRIPTION_MAX_CHARS).parse(declaration.description);
   const icon = z4.string().trim().min(1).parse(declaration.icon);
-  if (isPluginOwnedIconPath(icon)) {
-    validateProviderRelativePath(icon, `"${id}" icon`);
-  } else if (!isNamespacedGlyph(icon) && /[/\\]/u.test(icon)) {
-    throw new Error(
-      `machine provider "${id}" icon must be a glyph, declared icon, or plugin-relative path`
-    );
-  }
+  assertProviderIconShape("machine provider", id, icon);
   const ephemeral = z4.boolean().default(false).parse(declaration.ephemeral);
-  const inputs = normalizeMachineProviderInputs(id, declaration);
+  const inputs = normalizeProviderInputs(
+    "machine provider",
+    id,
+    declaration.inputs
+  );
   if (typeof declaration.create !== "function" || typeof declaration.reconcileCleanup !== "function" || typeof declaration.remove !== "function") {
     throw new Error(
       `machine provider "${id}" must declare create, reconcileCleanup and remove functions`
@@ -1946,16 +1978,18 @@ function validatePluginMachineProviderDeclaration(declaration) {
       `machine provider "${id}" must declare suspend and resume together`
     );
   }
-  if (declaration.validate !== void 0 && typeof declaration.validate !== "function") {
-    throw new Error(
-      `machine provider "${id}" declares a validate that is not a function`
-    );
-  }
-  if (declaration.availability !== void 0 && typeof declaration.availability !== "function") {
-    throw new Error(
-      `machine provider "${id}" declares availability that is not a function`
-    );
-  }
+  assertOptionalFunction(
+    "machine provider",
+    id,
+    declaration.validate,
+    "a validate"
+  );
+  assertOptionalFunction(
+    "machine provider",
+    id,
+    declaration.availability,
+    "availability"
+  );
   return {
     id,
     displayName,
@@ -1973,56 +2007,691 @@ function validatePluginMachineProviderDeclaration(declaration) {
     remove: declaration.remove
   };
 }
-function normalizeMachineProviderInputs(id, declaration) {
-  const inputs = declaration.inputs;
-  if (inputs === void 0) return null;
-  if (!isStandardSchema(inputs)) {
+function validateServerAccessProviderDeclaration(declaration) {
+  if (typeof declaration !== "object" || declaration === null)
+    throw new Error("Invalid server access provider declaration");
+  if (typeof declaration.id !== "string" || !/^[a-z][a-z0-9-]*$/u.test(declaration.id) || declaration.id === "direct")
+    throw new Error("Invalid or reserved server access provider id");
+  if (typeof declaration.displayName !== "string" || !declaration.displayName.trim() || typeof declaration.description !== "string" || !declaration.description.trim() || typeof declaration.availability !== "function" || typeof declaration.acquire !== "function" || typeof declaration.release !== "function")
+    throw new Error("Invalid server access provider declaration");
+  return declaration;
+}
+var LEGACY_UNKNOWN_MIGRATION_HASH = "legacy-unknown";
+function migrationStatementHash(statement) {
+  return createHash("sha256").update(statement).digest("hex");
+}
+function runPluginStorageMigrations(database, statements) {
+  database.exec(
+    "CREATE TABLE IF NOT EXISTS _bb_migrations (id INTEGER PRIMARY KEY, applied_at INTEGER NOT NULL, statement_hash TEXT)"
+  );
+  const migrationColumns = database.prepare("PRAGMA table_info(_bb_migrations)").all();
+  if (!migrationColumns.some((column) => column.name === "statement_hash")) {
+    database.exec("ALTER TABLE _bb_migrations ADD COLUMN statement_hash TEXT");
+  }
+  const rows = database.prepare(
+    "SELECT id, statement_hash FROM _bb_migrations ORDER BY id"
+  ).all();
+  const applied = /* @__PURE__ */ new Map();
+  for (const row of rows) applied.set(row.id, row.statement_hash);
+  const statementHashes = statements.map(migrationStatementHash);
+  statementHashes.forEach((statementHash, index) => {
+    const recordedHash = applied.get(index);
+    if (recordedHash !== void 0 && recordedHash !== null && recordedHash !== statementHash) {
+      throw new Error(
+        `migration ${index} does not match the recorded statement; append a new migration instead of changing or reusing an index`
+      );
+    }
+  });
+  const adopt = database.prepare(
+    "UPDATE _bb_migrations SET statement_hash = ? WHERE id = ? AND statement_hash IS NULL"
+  );
+  const record = database.prepare(
+    "INSERT INTO _bb_migrations (id, applied_at, statement_hash) VALUES (?, ?, ?)"
+  );
+  database.transaction(() => {
+    for (const row of rows) {
+      if (row.statement_hash !== null) continue;
+      adopt.run(
+        statementHashes[row.id] ?? LEGACY_UNKNOWN_MIGRATION_HASH,
+        row.id
+      );
+    }
+    statements.forEach((statement, index) => {
+      if (applied.has(index)) return;
+      database.exec(statement);
+      record.run(index, Date.now(), statementHashes[index]);
+    });
+  })();
+}
+function normalizeHttpRouteRegistration(method, path, handler, opts, existingRoutes) {
+  const normalizedMethod = String(method).toUpperCase();
+  if (!PLUGIN_HTTP_METHODS.has(normalizedMethod)) {
     throw new Error(
-      `machine provider "${id}" declares an inputs that is not a Standard Schema v1 validator`
+      `invalid http method "${String(method)}" \u2014 use one of: ${[...PLUGIN_HTTP_METHODS].join(", ")}`
     );
   }
-  let converted;
+  if (typeof path !== "string" || !path.startsWith("/")) {
+    throw new Error(
+      `http route path must be a string starting with "/", got ${JSON.stringify(path)}`
+    );
+  }
+  if (typeof handler !== "function") {
+    throw new Error(
+      `http route handler for ${normalizedMethod} ${path} must be a function`
+    );
+  }
+  const auth = opts?.auth ?? "local";
+  if (auth !== "local" && auth !== "token" && auth !== "none") {
+    throw new Error(
+      `invalid auth mode "${String(auth)}" for ${normalizedMethod} ${path} \u2014 use "local", "token", or "none"`
+    );
+  }
+  if (existingRoutes.some(
+    (route) => route.method === normalizedMethod && route.path === path
+  )) {
+    throw new Error(
+      `http route ${normalizedMethod} ${path} is already registered`
+    );
+  }
+  return { method: normalizedMethod, path, auth };
+}
+function normalizeWebSocketRouteRegistration(path, handler, opts, existingRoutes) {
+  if (typeof path !== "string" || !path.startsWith("/")) {
+    throw new Error(
+      `websocket route path must be a string starting with "/", got ${JSON.stringify(path)}`
+    );
+  }
+  if (typeof handler !== "function") {
+    throw new Error(`websocket route handler for ${path} must be a function`);
+  }
+  const auth = opts?.auth ?? "local";
+  if (auth !== "local" && auth !== "token" && auth !== "none") {
+    throw new Error(
+      `invalid auth mode "${String(auth)}" for websocket ${path} \u2014 use "local", "token", or "none"`
+    );
+  }
+  if (existingRoutes.some((route) => route.path === path)) {
+    throw new Error(`websocket route ${path} is already registered`);
+  }
+  return { path, auth };
+}
+function normalizeRpcRegistration(contract, handlers, registered) {
+  if (typeof contract !== "object" || contract === null || Array.isArray(contract)) {
+    throw new Error("rpc.register contract must be an object");
+  }
+  if (typeof handlers !== "object" || handlers === null || Array.isArray(handlers)) {
+    throw new Error("rpc.register handlers must be an object");
+  }
+  const pending = [];
+  const contractEntries = Object.entries(contract);
+  const contractNames = new Set(contractEntries.map(([name]) => name));
+  for (const extraName of Object.keys(handlers)) {
+    if (!contractNames.has(extraName)) {
+      throw new Error(
+        `rpc handler "${extraName}" has no matching contract method`
+      );
+    }
+  }
+  for (const [name, methodContractValue] of contractEntries) {
+    if (!RPC_METHOD_PATTERN.test(name)) {
+      throw new Error(
+        `invalid rpc method name "${name}" \u2014 use dot-separated segments with letters, digits, "-" and "_"`
+      );
+    }
+    const methodContract = readRpcMethodContract(name, methodContractValue);
+    const handler = Reflect.get(handlers, name);
+    if (typeof handler !== "function") {
+      throw new Error(`rpc method "${name}" must provide a handler function`);
+    }
+    if (registered.has(name)) {
+      throw new Error(`rpc method "${name}" is already registered`);
+    }
+    pending.push([
+      name,
+      {
+        inputSchema: methodContract.input,
+        outputSchema: methodContract.output,
+        handler
+      }
+    ]);
+  }
+  return pending;
+}
+function normalizeRealtimePayload(channel, payload) {
+  if (typeof channel !== "string" || channel.length === 0) {
+    throw new Error("realtime channel must be a non-empty string");
+  }
+  if (payload === void 0) return null;
+  let json;
   try {
-    converted = JSON.parse(JSON.stringify(standardSchemaToJsonSchema(inputs)));
+    json = JSON.stringify(payload);
+  } catch {
+    json = void 0;
+  }
+  if (json === void 0) {
+    throw new Error(
+      `realtime payload for channel "${channel}" is not JSON-serializable`
+    );
+  }
+  return JSON.parse(json);
+}
+function validateBackgroundServiceRegistration(name, service, existing) {
+  if (typeof name !== "string" || !BACKGROUND_NAME_PATTERN.test(name)) {
+    throw new Error(
+      `invalid service name ${JSON.stringify(name)} \u2014 use letters, digits, "-" and "_"`
+    );
+  }
+  if (existing.some((record) => record.name === name)) {
+    throw new Error(`background service "${name}" is already registered`);
+  }
+  if (typeof service?.start !== "function") {
+    throw new Error(
+      `background service "${name}" must provide a start(signal) function`
+    );
+  }
+  return { name, start: service.start.bind(service) };
+}
+function validateScheduleRegistration(name, cron, fn, existing, parseCron) {
+  if (typeof name !== "string" || !BACKGROUND_NAME_PATTERN.test(name)) {
+    throw new Error(
+      `invalid schedule name ${JSON.stringify(name)} \u2014 use letters, digits, "-" and "_"`
+    );
+  }
+  if (existing.some((record) => record.name === name)) {
+    throw new Error(`schedule "${name}" is already registered`);
+  }
+  try {
+    parseCron(String(cron));
   } catch (error) {
     throw new Error(
-      `machine provider "${id}" declares an inputs validator that cannot be published as JSON Schema (${error instanceof Error ? error.message : String(error)}) \u2014 declare it with zod 4 or a validator exposing toJSONSchema()`
+      `invalid cron ${JSON.stringify(cron)} for schedule "${name}": ${error instanceof Error ? error.message : String(error)}`
     );
   }
-  const jsonSchema = jsonValueSchema.safeParse(converted);
-  if (!jsonSchema.success) {
+  if (typeof fn !== "function") {
+    throw new Error(`schedule "${name}" must provide a function`);
+  }
+  return { name, cron: String(cron), fn };
+}
+function normalizeCliRegistration(registration, alreadyRegistered) {
+  if (alreadyRegistered) {
+    throw new Error("cli command is already registered");
+  }
+  const name = registration?.name;
+  if (typeof name !== "string" || !CLI_COMMAND_NAME_PATTERN.test(name)) {
     throw new Error(
-      `machine provider "${id}" declares an inputs schema whose JSON Schema is not JSON-serializable`
+      `invalid cli command name ${JSON.stringify(name)} \u2014 use lowercase letters, digits, and "-"`
     );
   }
-  return { schema: inputs, jsonSchema: jsonSchema.data };
+  if (typeof registration.summary !== "string" || registration.summary.trim().length === 0) {
+    throw new Error(`cli command "${name}" must provide a summary`);
+  }
+  const commands = registration.commands ?? [];
+  if (!Array.isArray(commands)) {
+    throw new Error(`cli command "${name}" commands must be an array`);
+  }
+  const validatedCommands = commands.map((command, index) => {
+    if (typeof command?.name !== "string" || !CLI_COMMAND_NAME_PATTERN.test(command.name) || typeof command.summary !== "string" || typeof command.usage !== "string") {
+      throw new Error(
+        `cli command "${name}" commands[${index}] must be { name: [a-z0-9-]+, summary, usage }`
+      );
+    }
+    return {
+      name: command.name,
+      summary: command.summary,
+      usage: command.usage
+    };
+  });
+  if (typeof registration.run !== "function") {
+    throw new Error(
+      `cli command "${name}" must provide a run(argv, ctx) function`
+    );
+  }
+  return {
+    name,
+    summary: registration.summary,
+    commands: validatedCommands,
+    run: registration.run.bind(registration)
+  };
 }
-function validateServerAccessProviderDeclaration(declaration) {
-  if (typeof declaration !== "object" || declaration === null)
-    throw new Error("Invalid server access provider declaration");
-  if (typeof declaration.id !== "string" || !/^[a-z][a-z0-9-]*$/u.test(declaration.id) || declaration.id === "direct")
-    throw new Error("Invalid or reserved server access provider id");
-  if (typeof declaration.displayName !== "string" || !declaration.displayName.trim() || typeof declaration.description !== "string" || !declaration.description.trim() || typeof declaration.availability !== "function" || typeof declaration.acquire !== "function" || typeof declaration.release !== "function")
-    throw new Error("Invalid server access provider declaration");
-  return declaration;
+function normalizeAgentToolRegistration(args) {
+  const { pluginId, declaredIconNames, tool } = args;
+  const name = tool?.name;
+  if (typeof name !== "string" || !AGENT_TOOL_NAME_PATTERN.test(name)) {
+    throw new Error(
+      `invalid tool name ${JSON.stringify(name)} \u2014 use letters, digits, "-" and "_"`
+    );
+  }
+  if (RESERVED_AGENT_TOOL_NAMES.includes(name)) {
+    throw new Error(
+      `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`);
+  }
+  if (tool.instructions !== void 0 && typeof tool.instructions !== "string") {
+    throw new Error(`tool "${name}" instructions must be a string`);
+  }
+  if (typeof tool.instructions === "string" && tool.instructions.length > PLUGIN_AGENT_STATIC_INSTRUCTIONS_MAX_CHARS) {
+    throw new Error(
+      `tool "${name}" instructions exceed the ${PLUGIN_AGENT_STATIC_INSTRUCTIONS_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(
+      `tool "${name}" must provide an execute(params, ctx) function`
+    );
+  }
+  const parameters = tool.parameters;
+  let inputSchema;
+  let parse;
+  if (isZodSchemaLike(parameters)) {
+    try {
+      inputSchema = zodSchemaToJsonSchema(parameters);
+    } catch (error) {
+      throw new Error(
+        `tool "${name}" parameters look like a zod schema but could not be converted to JSON Schema (${error instanceof Error ? error.message : String(error)}) \u2014 use zod 4, or pass a plain JSON-schema object`
+      );
+    }
+    parse = (input) => {
+      const result = parameters.safeParse(input);
+      if (result.success) return { ok: true, value: result.data };
+      return { ok: false, error: summarizeParseIssues(result.error) };
+    };
+  } else if (typeof parameters === "object" && parameters !== null && !Array.isArray(parameters)) {
+    try {
+      inputSchema = JSON.parse(JSON.stringify(parameters));
+    } catch {
+      throw new Error(
+        `tool "${name}" parameters JSON schema is not JSON-serializable`
+      );
+    }
+    parse = (input) => ({ ok: true, value: input });
+  } else {
+    throw new Error(
+      `tool "${name}" parameters must be a zod schema or a JSON-schema object`
+    );
+  }
+  assertNoRecursiveJsonSchemaReferences(
+    inputSchema,
+    `tool "${name}" parameters`
+  );
+  return {
+    name,
+    description: tool.description,
+    presentation,
+    instructions: tool.instructions !== void 0 && tool.instructions.trim().length > 0 ? tool.instructions : null,
+    inputSchema,
+    parse,
+    execute: tool.execute.bind(tool)
+  };
+}
+function normalizeMentionProviderRegistration(provider, existing) {
+  const id = provider?.id;
+  if (typeof id !== "string" || !MENTION_PROVIDER_ID_PATTERN.test(id)) {
+    throw new Error(
+      `invalid mention provider id ${JSON.stringify(id)} \u2014 use letters, digits, "-" and "_"`
+    );
+  }
+  if (existing.some((record) => record.id === id)) {
+    throw new Error(`mention provider "${id}" is already registered`);
+  }
+  if (typeof provider.label !== "string" || provider.label.trim().length === 0) {
+    throw new Error(`mention provider "${id}" must provide a label`);
+  }
+  if (typeof provider.search !== "function") {
+    throw new Error(
+      `mention provider "${id}" must provide a search({ query, projectId, threadId }) function`
+    );
+  }
+  if (typeof provider.resolve !== "function") {
+    throw new Error(
+      `mention provider "${id}" must provide a resolve(itemId) function`
+    );
+  }
+  return {
+    id,
+    label: provider.label.trim(),
+    triggers: normalizeMentionProviderTriggers(id, provider.triggers),
+    search: provider.search.bind(provider),
+    resolve: provider.resolve.bind(provider)
+  };
+}
+function normalizeInteractionRequest(request) {
+  if (!request || typeof request !== "object") {
+    throw new Error("ui.requestInput requires an options object");
+  }
+  if (typeof request.threadId !== "string" || request.threadId.length === 0) {
+    throw new Error("ui.requestInput threadId must be a non-empty string");
+  }
+  if (typeof request.rendererId !== "string" || !/^[a-zA-Z0-9_-]+$/.test(request.rendererId)) {
+    throw new Error(
+      "ui.requestInput rendererId must use letters, digits, '-' or '_'"
+    );
+  }
+  if (typeof request.title !== "string" || request.title.trim().length === 0 || request.title.trim().length > PLUGIN_INTERACTION_MAX_TITLE_LENGTH) {
+    throw new Error(
+      `ui.requestInput title must be 1-${PLUGIN_INTERACTION_MAX_TITLE_LENGTH} characters`
+    );
+  }
+  let payload;
+  try {
+    const json = JSON.stringify(request.payload);
+    if (json === void 0) throw new Error();
+    if (Buffer.byteLength(json, "utf8") > PLUGIN_INTERACTION_MAX_PAYLOAD_BYTES) {
+      throw new Error("ui.requestInput payload exceeds 64 KiB");
+    }
+    payload = JSON.parse(json);
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("64 KiB")) {
+      throw error;
+    }
+    throw new Error("ui.requestInput payload must be JSON-serializable");
+  }
+  const timeoutMs = request.timeoutMs ?? 10 * 60 * 1e3;
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 60 * 60 * 1e3) {
+    throw new Error("ui.requestInput timeoutMs must be between 1 and 3600000");
+  }
+  return {
+    threadId: request.threadId,
+    rendererId: request.rendererId,
+    title: request.title.trim(),
+    payload,
+    timeoutMs
+  };
+}
+function validateProviderEnvContribution(label, providerId, resolve, registered) {
+  if (typeof providerId !== "string" || providerId.trim().length === 0) {
+    throw new Error(`${label} requires a provider id`);
+  }
+  if (registered.has(providerId)) {
+    throw new Error(`${label} for "${providerId}" is already registered`);
+  }
+  if (typeof resolve !== "function") {
+    throw new Error(`${label} requires a resolver function`);
+  }
+}
+function normalizePluginAgentToolParameters(args) {
+  const { index, value } = args;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(
+      `configure() output.tools[${index}].parameters must be a JSON-schema object`
+    );
+  }
+  let serialized;
+  try {
+    serialized = JSON.stringify(value);
+  } catch {
+    throw new Error(
+      `configure() output.tools[${index}].parameters is not JSON-serializable`
+    );
+  }
+  if (serialized === void 0) {
+    throw new Error(
+      `configure() output.tools[${index}].parameters is not JSON-serializable`
+    );
+  }
+  if (Buffer.byteLength(serialized, "utf8") > PLUGIN_AGENT_TOOL_PARAMETERS_MAX_BYTES) {
+    throw new Error(
+      `configure() output.tools[${index}].parameters exceeds the ${PLUGIN_AGENT_TOOL_PARAMETERS_MAX_BYTES}-byte limit`
+    );
+  }
+  const parameters = JSON.parse(serialized);
+  if (parameters.type !== "object") {
+    throw new Error(
+      `configure() output.tools[${index}].parameters must have root type "object"`
+    );
+  }
+  assertNoRecursiveJsonSchemaReferences(
+    parameters,
+    `configure() output.tools[${index}].parameters`
+  );
+  return parameters;
+}
+function normalizePluginAgentToolSelections(args) {
+  if (!Array.isArray(args.value)) {
+    throw new Error("configure() output.tools must be an array");
+  }
+  if (args.value.length > PLUGIN_AGENT_SELECTION_MAX_IDS) {
+    throw new Error(
+      `configure() output.tools exceeds the ${PLUGIN_AGENT_SELECTION_MAX_IDS}-id limit`
+    );
+  }
+  const toolIds = [];
+  const parameterOverrides = /* @__PURE__ */ new Map();
+  const seen = /* @__PURE__ */ new Set();
+  for (let index = 0; index < args.value.length; index += 1) {
+    const entry = args.value[index];
+    let name;
+    let parameters = null;
+    if (typeof entry === "string") {
+      name = entry;
+    } else if (typeof entry === "object" && entry !== null && !Array.isArray(entry)) {
+      const typed = entry;
+      const unknownKeys = Object.keys(typed).filter((key) => !["name", "parameters"].includes(key)).sort();
+      if (unknownKeys.length > 0) {
+        throw new Error(
+          `configure() output.tools[${index}] contains unknown field${unknownKeys.length === 1 ? "" : "s"}: ${unknownKeys.join(", ")}`
+        );
+      }
+      name = typed.name;
+      parameters = normalizePluginAgentToolParameters({
+        index,
+        value: typed.parameters
+      });
+    } else {
+      throw new Error(
+        `configure() output.tools[${index}] must be a tool name or { name, parameters }`
+      );
+    }
+    if (typeof name !== "string" || name.length === 0) {
+      throw new Error(
+        `configure() output.tools[${index}] must ${typeof entry === "string" ? "be" : "name"} a non-empty string`
+      );
+    }
+    if (seen.has(name)) {
+      throw new Error(
+        `configure() output.tools contains duplicate id ${JSON.stringify(name)}`
+      );
+    }
+    if (!args.knownIds.has(name)) {
+      throw new Error(
+        `configure() selected unknown tool id ${JSON.stringify(name)} owned by plugin ${JSON.stringify(args.pluginId)}`
+      );
+    }
+    seen.add(name);
+    toolIds.push(name);
+    if (parameters !== null) parameterOverrides.set(name, parameters);
+  }
+  return { toolIds, parameterOverrides };
+}
+function normalizePluginAgentSelectionIds(args) {
+  if (!Array.isArray(args.value)) {
+    throw new Error("configure() output.skills must be an array");
+  }
+  if (args.value.length > PLUGIN_AGENT_SELECTION_MAX_IDS) {
+    throw new Error(
+      `configure() output.skills exceeds the ${PLUGIN_AGENT_SELECTION_MAX_IDS}-id limit`
+    );
+  }
+  const selected = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (let index = 0; index < args.value.length; index += 1) {
+    const id = args.value[index];
+    if (typeof id !== "string" || id.length === 0) {
+      throw new Error(
+        `configure() output.skills[${index}] must be a non-empty string`
+      );
+    }
+    if (seen.has(id)) {
+      throw new Error(
+        `configure() output.skills contains duplicate id ${JSON.stringify(id)}`
+      );
+    }
+    if (!args.knownIds.has(id)) {
+      throw new Error(
+        `configure() selected unknown skill id ${JSON.stringify(id)} owned by plugin ${JSON.stringify(args.pluginId)}`
+      );
+    }
+    seen.add(id);
+    selected.push(id);
+  }
+  return selected;
+}
+function normalizePluginAgentConfiguration(args) {
+  if (typeof args.value !== "object" || args.value === null || Array.isArray(args.value)) {
+    throw new Error(
+      "configure() must return { tools: string[], skills: string[], instructions?: string }"
+    );
+  }
+  const output = args.value;
+  const unknownKeys = Object.keys(output).filter((key) => !["tools", "skills", "instructions"].includes(key)).sort();
+  if (unknownKeys.length > 0) {
+    throw new Error(
+      `configure() output contains unknown field${unknownKeys.length === 1 ? "" : "s"}: ${unknownKeys.join(", ")}`
+    );
+  }
+  if (output.instructions !== void 0 && typeof output.instructions !== "string") {
+    throw new Error("configure() output.instructions must be a string");
+  }
+  const instructions = typeof output.instructions === "string" && output.instructions.trim().length > 0 ? output.instructions.slice(
+    0,
+    PLUGIN_AGENT_DYNAMIC_INSTRUCTIONS_MAX_CHARS
+  ) : null;
+  const toolSelections = normalizePluginAgentToolSelections({
+    knownIds: args.knownToolIds,
+    pluginId: args.pluginId,
+    value: output.tools
+  });
+  return {
+    toolIds: toolSelections.toolIds,
+    toolParameterOverrides: toolSelections.parameterOverrides,
+    skillIds: normalizePluginAgentSelectionIds({
+      knownIds: args.knownSkillIds,
+      pluginId: args.pluginId,
+      value: output.skills
+    }),
+    instructions
+  };
+}
+function normalizeRpcIssuePath(path) {
+  if (path === void 0) return void 0;
+  const segments = Array.isArray(path) ? path : [path];
+  const normalized = segments.map((segment) => {
+    const key = typeof segment === "object" && segment !== null ? Reflect.get(segment, "key") : segment;
+    return typeof key === "number" ? key : String(key);
+  });
+  return normalized.length > 0 ? normalized : void 0;
+}
+function normalizeRpcIssues(issues) {
+  return issues.map((issue) => {
+    const path = normalizeRpcIssuePath(issue.path);
+    return {
+      message: issue.message,
+      ...path !== void 0 ? { path } : {}
+    };
+  });
+}
+async function validateRpcValue(schema, value, phase, fail) {
+  let result;
+  try {
+    result = await schema["~standard"].validate(value);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return fail({
+      code: phase === "input" ? "invalid_input" : "invalid_output",
+      message: `rpc ${phase} validator failed: ${detail}`,
+      issues: [{ message: detail }]
+    });
+  }
+  if (result.issues !== void 0) {
+    return fail({
+      code: phase === "input" ? "invalid_input" : "invalid_output",
+      message: `rpc ${phase} validation failed`,
+      issues: normalizeRpcIssues(result.issues)
+    });
+  }
+  return result.value;
+}
+function normalizeRpcJsonResult(value, fail) {
+  const ancestors = /* @__PURE__ */ new Set();
+  function visit(current, path) {
+    if (current === null || typeof current === "string" || typeof current === "boolean") {
+      return current;
+    }
+    if (typeof current === "number") {
+      if (!Number.isFinite(current)) {
+        return fail({
+          code: "non_json_result",
+          message: `rpc result at ${path} contains a non-finite number`
+        });
+      }
+      return current;
+    }
+    if (typeof current !== "object") {
+      return fail({
+        code: "non_json_result",
+        message: `rpc result at ${path} is not a JSON value (${typeof current})`
+      });
+    }
+    if (ancestors.has(current)) {
+      return fail({
+        code: "non_json_result",
+        message: `rpc result at ${path} is cyclic`
+      });
+    }
+    ancestors.add(current);
+    try {
+      if (Array.isArray(current)) {
+        return current.map((item, index) => visit(item, `${path}[${index}]`));
+      }
+      const prototype = Object.getPrototypeOf(current);
+      if (prototype !== Object.prototype && prototype !== null) {
+        return fail({
+          code: "non_json_result",
+          message: `rpc result at ${path} must be a plain JSON object`
+        });
+      }
+      if (Reflect.ownKeys(current).some((key) => typeof key === "symbol")) {
+        return fail({
+          code: "non_json_result",
+          message: `rpc result at ${path} contains a symbol key`
+        });
+      }
+      const normalized = {};
+      for (const [key, child] of Object.entries(current)) {
+        normalized[key] = visit(child, `${path}.${key}`);
+      }
+      return normalized;
+    } finally {
+      ancestors.delete(current);
+    }
+  }
+  return visit(value, "$result");
 }
 export {
-  AGENT_TOOL_NAME_PATTERN,
-  BACKGROUND_NAME_PATTERN,
-  CLI_COMMAND_NAME_PATTERN,
   ENVIRONMENT_PROVIDER_DESCRIPTION_MAX_CHARS,
   ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS,
   ENVIRONMENT_PROVIDER_ID_PATTERN,
   ENVIRONMENT_PROVIDER_REQUIREMENT_NAMES,
   KV_VALUE_MAX_BYTES,
   MACHINE_PROVIDER_DESCRIPTION_MAX_CHARS,
-  MENTION_PROVIDER_ID_PATTERN,
-  PLUGIN_AGENT_DYNAMIC_INSTRUCTIONS_MAX_CHARS,
-  PLUGIN_AGENT_SELECTION_MAX_IDS,
-  PLUGIN_AGENT_STATIC_INSTRUCTIONS_MAX_CHARS,
   PLUGIN_AGENT_STATUS_LABEL_MAX_CHARS,
-  PLUGIN_AGENT_TOOL_PARAMETERS_MAX_BYTES,
-  PLUGIN_HTTP_METHODS,
   PLUGIN_MENTION_TRIGGER_VALUES,
   PLUGIN_PROVIDER_BRIDGE_OPTIONS_MAX_BYTES,
   PLUGIN_PROVIDER_COMPOSER_ACTION_VALUES,
@@ -2034,40 +2703,47 @@ export {
   PROVIDER_ID_PATTERN,
   RESERVED_AGENT_TOOL_NAMES,
   RESERVED_BB_CLI_COMMANDS,
-  RPC_METHOD_PATTERN,
   SERVER_DIRECT_AI_SERVICE_IDS,
   SETTING_KEY_PATTERN,
   adoptHttpRouteResponse,
-  agentToolIconRefusalMessage,
   aiServiceAlreadyRegisteredMessage,
   assertAiServiceRegistrable,
-  assertNoRecursiveJsonSchemaReferences,
+  coerceStoredPluginSettingValue,
   deriveValidatedProviderOptions,
   enforcePluginCliOutputLimit,
   environmentCompositionSchema,
   isPluginMentionTrigger,
   isStandardSchema,
-  isZodSchemaLike,
-  normalizeMentionProviderTriggers,
+  normalizeAgentToolRegistration,
+  normalizeCliRegistration,
+  normalizeHttpRouteRegistration,
+  normalizeInteractionRequest,
+  normalizeMentionProviderRegistration,
+  normalizePluginAgentConfiguration,
+  normalizeRealtimePayload,
+  normalizeRpcJsonResult,
+  normalizeRpcRegistration,
+  normalizeWebSocketRouteRegistration,
   parsePluginAgentToolPresentation,
   pluginCliCollisionWarning,
   pluginHookAlreadyRegisteredMessage,
   providerAlreadyRegisteredMessage,
   providerIconRefusalMessage,
   providerWithoutBridgeMessage,
-  readRpcMethodContract,
   registerSettingDescriptors,
-  rejectStaleAgentToolFields,
+  runPluginStorageMigrations,
   storePluginHook,
-  summarizeParseIssues,
   summarizeStandardIssues,
   undeclaredIconProblem,
+  validateBackgroundServiceRegistration,
   validatePluginAiServiceDeclaration,
   validatePluginEnvironmentProviderDeclaration,
   validatePluginMachineProviderDeclaration,
   validatePluginProviderDeclaration,
   validatePluginProviderEnvEntries,
+  validateProviderEnvContribution,
+  validateRpcValue,
+  validateScheduleRegistration,
   validateServerAccessProviderDeclaration,
-  validateSettingsUpdate,
-  zodSchemaToJsonSchema
+  validateSettingsUpdate
 };