@get-bb/plugin-sdk 0.4.56 → 0.4.87

package/dist/testing/index.js

@@ -1,17 +1,5 @@
-// src/testing/fake-plugin-host.ts
-import { createHash } from "node:crypto";
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import Database from "better-sqlite3";
-import { CronExpressionParser } from "cron-parser";
-import { Hono } from "hono";
-
-// ../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 { createHash } from "node:crypto";
 import { z as z4 } from "zod";
 
 // ../domain/src/plugin-icon.ts
@@ -57,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"];
@@ -286,6 +278,51 @@ var providerNativeRootSetSchema = z3.object({
   resolved: providerResolvedNativeRootsSchema
 }).strict();
 
+// ../domain/src/plugin-metadata.ts
+var PLUGIN_METADATA_MAX_BYTES = 256 * 1024;
+function exceedsPluginMetadataLimit(metadataJson) {
+  return new TextEncoder().encode(metadataJson).byteLength > PLUGIN_METADATA_MAX_BYTES;
+}
+var pluginMetadataSchema = jsonObjectSchema.superRefine(
+  (value, ctx) => {
+    if (exceedsPluginMetadataLimit(JSON.stringify(value))) {
+      ctx.addIssue({
+        code: "custom",
+        message: "pluginMetadata exceeds 256 KiB"
+      });
+    }
+  }
+);
+function assertPlainJsonData(value, seen) {
+  if (value === null || typeof value !== "object") return;
+  if (seen.has(value)) throw new Error("pluginMetadata contains a cycle");
+  const array = Array.isArray(value);
+  if (Object.getPrototypeOf(value) !== (array ? Array.prototype : Object.prototype)) {
+    throw new Error("pluginMetadata must contain plain JSON data");
+  }
+  seen.add(value);
+  for (const child of array ? value : Object.values(value)) {
+    assertPlainJsonData(child, seen);
+  }
+  seen.delete(value);
+}
+function validatePluginMetadata(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("pluginMetadata must be a plain JSON object");
+  }
+  assertPlainJsonData(value, /* @__PURE__ */ new Set());
+  return pluginMetadataSchema.parse(value);
+}
+function deepFreezeJsonValue(value) {
+  if (value === null || typeof value !== "object") return;
+  for (const child of Object.values(value)) deepFreezeJsonValue(child);
+  Object.freeze(value);
+}
+function deepFreezePluginMetadata(metadata) {
+  deepFreezeJsonValue(metadata);
+  return metadata;
+}
+
 // src/backend-contract.ts
 var PLUGIN_CLI_OUTPUT_MAX_BYTES = 1024 * 1024;
 
@@ -319,8 +356,7 @@ var pluginProviderEnvEntrySchema = z4.object({
     z4.string(),
     z4.object({ serverPath: z4.string().startsWith("/") }).strict()
   ]),
-  reason: z4.string(),
-  secret: z4.boolean()
+  reason: z4.string()
 }).strict();
 var pluginProviderEnvEntriesSchema = z4.array(pluginProviderEnvEntrySchema).max(PLUGIN_PROVIDER_ENV_MAX_ENTRIES).superRefine((entries, context) => {
   const names = /* @__PURE__ */ new Set();
@@ -528,6 +564,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 = [
   "@",
   "#",
@@ -1769,79 +1821,64 @@ function pluginHookAlreadyRegisteredMessage(hook) {
 }
 var ENVIRONMENT_PROVIDER_ID_PATTERN = /^[a-z0-9][a-z0-9-]{1,63}$/;
 var ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS = 80;
+var ENVIRONMENT_PROVIDER_DESCRIPTION_MAX_CHARS = 200;
 var ENVIRONMENT_PROVIDER_REQUIREMENT_NAMES = [
   "projectCheckout",
   "gitCheckout",
   "gitRemote",
   "projectless"
 ];
-function validatePluginEnvironmentProviderDeclaration(declaration) {
+var environmentCompositionSchema = z4.object({
+  id: z4.string().regex(ENVIRONMENT_PROVIDER_ID_PATTERN),
+  displayName: z4.string().trim().min(1).max(ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS),
+  description: z4.string().trim().min(1).max(ENVIRONMENT_PROVIDER_DESCRIPTION_MAX_CHARS).optional().transform((value) => value ?? null),
+  icon: z4.string().trim().min(1).transform(
+    (icon) => isPluginOwnedIconPath(icon) ? validateProviderRelativePath(icon, "Composition icon") : icon
+  ).optional().transform((value) => value ?? null),
+  machineProviderId: z4.string().regex(ENVIRONMENT_PROVIDER_ID_PATTERN),
+  environmentProviderId: z4.string().regex(ENVIRONMENT_PROVIDER_ID_PATTERN)
+}).strict();
+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`
-    );
-  }
-  const icon = declaration.icon === void 0 ? null : z4.string().min(1).parse(declaration.icon).trim();
-  if (icon !== null) {
-    if (isPluginOwnedIconPath(icon))
-      validateProviderRelativePath(icon, `"${id}" icon`);
-    else if (!isNamespacedGlyph(icon) && /[/\\]/u.test(icon))
-      throw new Error(
-        `environment provider "${id}" icon must be a glyph, declared icon, or plugin-relative path`
-      );
-  }
-  if (icon !== null && icon.length === 0) {
-    throw new Error(`environment provider "${id}" declares an empty icon`);
-  }
-  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`
+      `${noun} "${id}" needs a displayName of 1-${ENVIRONMENT_PROVIDER_DISPLAY_NAME_MAX_CHARS} characters`
     );
   }
-  if (declaration.validate !== void 0 && typeof declaration.validate !== "function") {
+  return { id, displayName };
+}
+function assertProviderIconShape(noun, id, icon) {
+  if (isPluginOwnedIconPath(icon)) {
+    validateProviderRelativePath(icon, `"${id}" icon`);
+  } 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,
-    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;
@@ -1849,17 +1886,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)) {
@@ -1891,226 +1976,519 @@ var environmentProviderPolicySchema = z4.object({
   retireGraceMs: z4.number().int().nonnegative().nullable().default(3e5),
   pathKeys: z4.enum(["per-thread", "per-attempt"]).default("per-thread")
 }).strict();
-
-// src/testing/fake-sdk.ts
-function withSpawnAttribution(pluginId, args) {
-  const [first, ...rest] = args;
-  if (typeof first !== "object" || first === null) return args;
-  const spawnArgs = first;
-  const origin = spawnArgs.origin ?? "plugin";
-  return [
-    {
-      ...spawnArgs,
-      origin,
-      ...origin === "plugin" ? { originPluginId: spawnArgs.originPluginId ?? pluginId } : {}
-    },
-    ...rest
-  ];
-}
-function createFakeSdk(options) {
-  const calls = [];
-  const stubs = /* @__PURE__ */ new Map();
-  function addOverrides(prefix, value) {
-    if (typeof value === "function") {
-      stubs.set(prefix, value);
-      return;
-    }
-    if (typeof value !== "object" || value === null) return;
-    for (const [key, child] of Object.entries(value)) {
-      addOverrides(prefix.length === 0 ? key : `${prefix}.${key}`, child);
-    }
-  }
-  addOverrides("", options.overrides ?? {});
-  function invoke(path, rawArgs) {
-    const args = path === "threads.spawn" ? withSpawnAttribution(options.pluginId, rawArgs) : rawArgs;
-    calls.push({ path, args });
-    const stub = stubs.get(path);
-    if (!stub) {
-      throw new Error(
-        `bb.sdk.${path} is not stubbed \u2014 pass an implementation via createFakePluginHost({ sdk: { ... } }) or harness.sdk.stub("${path}", fn)`
-      );
-    }
-    return stub(...args);
+var MACHINE_PROVIDER_DESCRIPTION_MAX_CHARS = 200;
+function validatePluginMachineProviderDeclaration(declaration) {
+  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);
+  assertProviderIconShape("machine provider", id, icon);
+  const ephemeral = z4.boolean().default(false).parse(declaration.ephemeral);
+  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`
+    );
   }
-  const nodes = /* @__PURE__ */ new Map();
-  function node(path) {
-    const cached = nodes.get(path);
-    if (cached) return cached;
-    const created = new Proxy(function() {
-    }, {
-      get(_target, prop) {
-        if (typeof prop !== "string" || prop === "then") return void 0;
-        return node(path === "" ? prop : `${path}.${prop}`);
-      },
-      apply(_target, _thisArg, args) {
-        return invoke(path, args);
-      }
-    });
-    nodes.set(path, created);
-    return created;
+  const hasSuspend = typeof declaration.suspend === "function";
+  const hasResume = typeof declaration.resume === "function";
+  if (hasSuspend !== hasResume) {
+    throw new Error(
+      `machine provider "${id}" must declare suspend and resume together`
+    );
   }
-  const harness = {
-    calls,
-    callsTo(path) {
-      return calls.filter((call) => call.path === path).map((call) => call.args);
-    },
-    stub(path, implementation) {
-      stubs.set(path, implementation);
-    }
+  assertOptionalFunction(
+    "machine provider",
+    id,
+    declaration.validate,
+    "a validate"
+  );
+  assertOptionalFunction(
+    "machine provider",
+    id,
+    declaration.availability,
+    "availability"
+  );
+  return {
+    id,
+    displayName,
+    description,
+    icon,
+    ephemeral,
+    inputs: inputs === null ? null : inputs.schema,
+    inputsJsonSchema: inputs === null ? null : inputs.jsonSchema,
+    availability: declaration.availability ?? null,
+    validate: declaration.validate ?? null,
+    reconcileCleanup: declaration.reconcileCleanup,
+    create: declaration.create,
+    suspend: declaration.suspend ?? null,
+    resume: declaration.resume ?? null,
+    remove: declaration.remove
   };
-  return { sdk: node(""), harness };
 }
-
-// src/testing/fake-plugin-host.ts
+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");
 }
-var PluginContextStaleError = class extends Error {
-  constructor(pluginId) {
-    super(
-      `plugin "${pluginId}" used a stale API handle \u2014 it was reloaded or disabled; re-entry happens via a fresh factory call`
+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(
+      `invalid http method "${String(method)}" \u2014 use one of: ${[...PLUGIN_HTTP_METHODS].join(", ")}`
     );
-    this.name = "PluginContextStaleError";
   }
-};
-function readSettingsValues(descriptors, stored) {
-  const values = {};
-  for (const [key, descriptor] of Object.entries(descriptors)) {
-    let value = stored.get(key);
-    if (descriptor.type === "number" && typeof value === "string") {
-      const legacyNumber = Number(value.trim());
-      value = value.trim().length > 0 && Number.isFinite(legacyNumber) ? legacyNumber : void 0;
+  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 "_"`
+      );
     }
-    if (descriptor.type === "number" && typeof value === "number" && !Number.isFinite(value)) {
-      value = void 0;
+    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`);
     }
-    const expected = descriptor.type === "boolean" ? "boolean" : descriptor.type === "number" ? "number" : "string";
-    if (typeof value !== expected) value = void 0;
-    if (descriptor.type === "select" && typeof value === "string" && !descriptor.options.includes(value)) {
-      value = void 0;
+    if (registered.has(name)) {
+      throw new Error(`rpc method "${name}" is already registered`);
     }
-    values[key] = value ?? descriptor.default;
+    pending.push([
+      name,
+      {
+        inputSchema: methodContract.input,
+        outputSchema: methodContract.output,
+        handler
+      }
+    ]);
   }
-  return values;
-}
-function isNeedsConfigurationError(error) {
-  return error instanceof Error && error.name === "NeedsConfigurationError";
+  return pending;
 }
-function errorMessage(error) {
-  return error instanceof Error ? error.message : String(error);
-}
-function jsonRoundTrip(value, what) {
-  if (value === void 0) return void 0;
+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 {
-    json = JSON.stringify(value);
+    json = JSON.stringify(payload);
   } catch {
     json = void 0;
   }
   if (json === void 0) {
-    throw new Error(`${what} is not JSON-serializable`);
+    throw new Error(
+      `realtime payload for channel "${channel}" is not JSON-serializable`
+    );
   }
   return JSON.parse(json);
 }
-function normalizeRpcIssues(issues) {
-  return issues.map((issue) => {
-    const rawPath = issue.path;
-    const segments = rawPath === void 0 ? [] : Array.isArray(rawPath) ? rawPath : [rawPath];
-    const path = segments.map((segment) => {
-      const key = typeof segment === "object" && segment !== null ? Reflect.get(segment, "key") : segment;
-      return typeof key === "number" ? key : String(key);
-    });
-    return {
-      message: issue.message,
-      ...path.length > 0 ? { path } : {}
-    };
-  });
+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 throwRpcError(error) {
-  const thrown = new Error(error.message);
-  Reflect.set(thrown, "code", error.code);
-  if (error.issues !== void 0) Reflect.set(thrown, "issues", error.issues);
-  throw thrown;
-}
-async function validateRpcValue(schema, value, phase) {
-  let result;
+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 {
-    result = await schema["~standard"].validate(value);
+    parseCron(String(cron));
   } catch (error) {
-    const message = errorMessage(error);
-    return throwRpcError({
-      code: phase === "input" ? "invalid_input" : "invalid_output",
-      message: `rpc ${phase} validator failed: ${message}`,
-      issues: [{ message }]
-    });
+    throw new Error(
+      `invalid cron ${JSON.stringify(cron)} for schedule "${name}": ${error instanceof Error ? error.message : String(error)}`
+    );
   }
-  if (result.issues !== void 0) {
-    return throwRpcError({
-      code: phase === "input" ? "invalid_input" : "invalid_output",
-      message: `rpc ${phase} validation failed`,
-      issues: normalizeRpcIssues(result.issues)
-    });
+  if (typeof fn !== "function") {
+    throw new Error(`schedule "${name}" must provide a function`);
   }
-  return result.value;
+  return { name, cron: String(cron), fn };
 }
-function normalizeRpcJsonResult(value) {
-  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 throwRpcError({
-          code: "non_json_result",
-          message: `rpc result at ${path} contains a non-finite number`
-        });
-      }
-      return current;
+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(
+      `invalid cli command name ${JSON.stringify(name)} \u2014 use lowercase letters, digits, and "-"`
+    );
+  }
+  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 }`
+      );
     }
-    if (typeof current !== "object") {
-      return throwRpcError({
-        code: "non_json_result",
-        message: `rpc result at ${path} is not a JSON value (${typeof current})`
-      });
+    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 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 (ancestors.has(current)) {
-      return throwRpcError({
-        code: "non_json_result",
-        message: `rpc result at ${path} is cyclic`
-      });
+  }
+  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`
+      );
     }
-    ancestors.add(current);
+    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 {
-      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 throwRpcError({
-          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 throwRpcError({
-          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);
+      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");
   }
-  return visit(value, "$result");
+  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, resolve2, 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 resolve2 !== "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 normalizeAgentToolSelections(args) {
+function normalizePluginAgentToolSelections(args) {
   if (!Array.isArray(args.value)) {
     throw new Error("configure() output.tools must be an array");
   }
@@ -2137,7 +2515,7 @@ function normalizeAgentToolSelections(args) {
         );
       }
       name = typed.name;
-      parameters = normalizeAgentToolParameters({
+      parameters = normalizePluginAgentToolParameters({
         index,
         value: typed.parameters
       });
@@ -2167,50 +2545,13 @@ function normalizeAgentToolSelections(args) {
   }
   return { toolIds, parameterOverrides };
 }
-function normalizeAgentToolParameters(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 normalizeAgentConfigurationIds(args) {
+function normalizePluginAgentSelectionIds(args) {
   if (!Array.isArray(args.value)) {
-    throw new Error(`configure() output.${args.field} must be an array`);
+    throw new Error("configure() output.skills must be an array");
   }
   if (args.value.length > PLUGIN_AGENT_SELECTION_MAX_IDS) {
     throw new Error(
-      `configure() output.${args.field} exceeds the ${PLUGIN_AGENT_SELECTION_MAX_IDS}-id limit`
+      `configure() output.skills exceeds the ${PLUGIN_AGENT_SELECTION_MAX_IDS}-id limit`
     );
   }
   const selected = [];
@@ -2219,12 +2560,12 @@ function normalizeAgentConfigurationIds(args) {
     const id = args.value[index];
     if (typeof id !== "string" || id.length === 0) {
       throw new Error(
-        `configure() output.${args.field}[${index}] must be a non-empty string`
+        `configure() output.skills[${index}] must be a non-empty string`
       );
     }
     if (seen.has(id)) {
       throw new Error(
-        `configure() output.${args.field} contains duplicate id ${JSON.stringify(id)}`
+        `configure() output.skills contains duplicate id ${JSON.stringify(id)}`
       );
     }
     if (!args.knownIds.has(id)) {
@@ -2237,7 +2578,7 @@ function normalizeAgentConfigurationIds(args) {
   }
   return selected;
 }
-function normalizeAgentConfiguration(args) {
+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 }"
@@ -2253,25 +2594,281 @@ function normalizeAgentConfiguration(args) {
   if (output.instructions !== void 0 && typeof output.instructions !== "string") {
     throw new Error("configure() output.instructions must be a string");
   }
-  const toolSelections = normalizeAgentToolSelections({
-    knownIds: args.knownToolIds,
-    pluginId: args.pluginId,
-    value: output.tools
-  });
-  return {
-    toolIds: toolSelections.toolIds,
-    toolParameterOverrides: toolSelections.parameterOverrides,
-    skillIds: normalizeAgentConfigurationIds({
-      field: "skills",
-      knownIds: args.knownSkillIds,
-      pluginId: args.pluginId,
-      value: output.skills
-    }),
-    instructions: typeof output.instructions === "string" && output.instructions.trim().length > 0 ? output.instructions.slice(
-      0,
-      PLUGIN_AGENT_DYNAMIC_INSTRUCTIONS_MAX_CHARS
-    ) : null
-  };
+  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");
+}
+
+// src/testing/fake-plugin-host.ts
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import Database from "better-sqlite3";
+import { CronExpressionParser } from "cron-parser";
+import { Hono } from "hono";
+
+// src/testing/fake-sdk.ts
+function withThreadAttribution(pluginId, args) {
+  const [first, ...rest] = args;
+  if (typeof first !== "object" || first === null) return args;
+  const threadArgs = first;
+  if (threadArgs.pluginMetadata !== void 0) {
+    return [
+      {
+        ...threadArgs,
+        pluginMetadata: validatePluginMetadata(threadArgs.pluginMetadata),
+        origin: "plugin",
+        originPluginId: pluginId
+      },
+      ...rest
+    ];
+  }
+  const origin = threadArgs.origin ?? "plugin";
+  return [
+    {
+      ...threadArgs,
+      origin,
+      ...origin === "plugin" ? { originPluginId: threadArgs.originPluginId ?? pluginId } : {}
+    },
+    ...rest
+  ];
+}
+function withPluginMetadataTarget(pluginId, args, validateSet) {
+  const [first, ...rest] = args;
+  if (typeof first !== "object" || first === null) return args;
+  const input = first;
+  return [
+    {
+      ...input,
+      pluginId: input.pluginId ?? pluginId,
+      ...validateSet && input.set !== void 0 ? { set: validatePluginMetadata(input.set) } : {}
+    },
+    ...rest
+  ];
+}
+function normalizeCallArgs(pluginId, path, args) {
+  switch (path) {
+    case "threads.spawn":
+    case "threads.fork":
+      return withThreadAttribution(pluginId, args);
+    case "threads.getPluginMetadata":
+      return withPluginMetadataTarget(pluginId, args, false);
+    case "threads.updatePluginMetadata":
+      return withPluginMetadataTarget(pluginId, args, true);
+    default:
+      return args;
+  }
+}
+function createFakeSdk(options) {
+  const calls = [];
+  const stubs = /* @__PURE__ */ new Map();
+  function addOverrides(prefix, value) {
+    if (typeof value === "function") {
+      stubs.set(prefix, value);
+      return;
+    }
+    if (typeof value !== "object" || value === null) return;
+    for (const [key, child] of Object.entries(value)) {
+      addOverrides(prefix.length === 0 ? key : `${prefix}.${key}`, child);
+    }
+  }
+  addOverrides("", options.overrides ?? {});
+  function invoke(path, rawArgs) {
+    let args;
+    try {
+      args = normalizeCallArgs(options.pluginId, path, rawArgs);
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    calls.push({ path, args });
+    const stub = stubs.get(path);
+    if (!stub) {
+      throw new Error(
+        `bb.sdk.${path} is not stubbed \u2014 pass an implementation via createFakePluginHost({ sdk: { ... } }) or harness.sdk.stub("${path}", fn)`
+      );
+    }
+    return stub(...args);
+  }
+  const nodes = /* @__PURE__ */ new Map();
+  function node(path) {
+    const cached = nodes.get(path);
+    if (cached) return cached;
+    const created = new Proxy(function() {
+    }, {
+      get(_target, prop) {
+        if (typeof prop !== "string" || prop === "then") return void 0;
+        return node(path === "" ? prop : `${path}.${prop}`);
+      },
+      apply(_target, _thisArg, args) {
+        return invoke(path, args);
+      }
+    });
+    nodes.set(path, created);
+    return created;
+  }
+  const harness = {
+    calls,
+    callsTo(path) {
+      return calls.filter((call) => call.path === path).map((call) => call.args);
+    },
+    stub(path, implementation) {
+      stubs.set(path, implementation);
+    }
+  };
+  return { sdk: node(""), harness };
+}
+
+// src/testing/fake-plugin-host.ts
+var PluginContextStaleError = class extends Error {
+  constructor(pluginId) {
+    super(
+      `plugin "${pluginId}" used a stale API handle \u2014 it was reloaded or disabled; re-entry happens via a fresh factory call`
+    );
+    this.name = "PluginContextStaleError";
+  }
+};
+function readSettingsValues(descriptors, stored) {
+  const values = {};
+  for (const [key, descriptor] of Object.entries(descriptors)) {
+    values[key] = coerceStoredPluginSettingValue(descriptor, stored.get(key));
+  }
+  return values;
+}
+function isNeedsConfigurationError(error) {
+  return error instanceof Error && error.name === "NeedsConfigurationError";
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function jsonRoundTrip(value, what) {
+  if (value === void 0) return void 0;
+  let json;
+  try {
+    json = JSON.stringify(value);
+  } catch {
+    json = void 0;
+  }
+  if (json === void 0) {
+    throw new Error(`${what} is not JSON-serializable`);
+  }
+  return JSON.parse(json);
+}
+function throwRpcError(error) {
+  const thrown = new Error(error.message);
+  Reflect.set(thrown, "code", error.code);
+  if (error.issues !== void 0) Reflect.set(thrown, "issues", error.issues);
+  throw thrown;
 }
 var fakeHostDisposers = /* @__PURE__ */ new WeakMap();
 function createFakePluginHost(options = {}) {
@@ -2353,49 +2950,7 @@ function createFakePluginHostInternal(options, sharedState) {
     },
     migrate(database, statements) {
       assertLive();
-      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]);
-        });
-      })();
+      runPluginStorageMigrations(database, statements);
     }
   };
   const settingsDescriptors = {};
@@ -2468,107 +3023,35 @@ function createFakePluginHostInternal(options, sharedState) {
   const http = {
     route(method, path, handler, opts) {
       assertLive();
-      const normalizedMethod = String(method).toUpperCase();
-      if (!PLUGIN_HTTP_METHODS.has(normalizedMethod)) {
-        throw new Error(
-          `invalid http method "${String(method)}" \u2014 use one of: ${[...PLUGIN_HTTP_METHODS].join(", ")}`
-        );
-      }
-      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 (httpRoutes.some(
-        (route) => route.method === normalizedMethod && route.path === path
-      )) {
-        throw new Error(
-          `http route ${normalizedMethod} ${path} is already registered`
-        );
-      }
-      httpRoutes.push({ method: normalizedMethod, path, auth, handler });
+      const route = normalizeHttpRouteRegistration(
+        method,
+        path,
+        handler,
+        opts,
+        httpRoutes
+      );
+      httpRoutes.push({ ...route, handler });
     },
     experimental_websocket(path, handler, opts) {
       assertLive();
-      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 (websocketRoutes.some((route) => route.path === path)) {
-        throw new Error(`websocket route ${path} is already registered`);
-      }
-      websocketRoutes.push({ path, auth, handler });
+      const route = normalizeWebSocketRouteRegistration(
+        path,
+        handler,
+        opts,
+        websocketRoutes
+      );
+      websocketRoutes.push({ ...route, handler });
     }
   };
   const rpcHandlers = /* @__PURE__ */ new Map();
   const rpc = {
     register(contract, handlers) {
       assertLive();
-      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, contractValue] 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, contractValue);
-        const handler = Reflect.get(handlers, name);
-        if (typeof handler !== "function") {
-          throw new Error(
-            `rpc method "${name}" must provide a handler function`
-          );
-        }
-        if (rpcHandlers.has(name)) {
-          throw new Error(`rpc method "${name}" is already registered`);
-        }
-        pending.push([
-          name,
-          {
-            inputSchema: methodContract.input,
-            outputSchema: methodContract.output,
-            handler
-          }
-        ]);
-      }
-      for (const [name, record] of pending) {
+      for (const [name, record] of normalizeRpcRegistration(
+        contract,
+        handlers,
+        rpcHandlers
+      )) {
         rpcHandlers.set(name, record);
       }
     }
@@ -2577,14 +3060,10 @@ function createFakePluginHostInternal(options, sharedState) {
   const realtime = {
     publish(channel, payload) {
       assertLive();
-      if (typeof channel !== "string" || channel.length === 0) {
-        throw new Error("realtime channel must be a non-empty string");
-      }
-      const normalized = payload === void 0 ? null : jsonRoundTrip(
-        payload,
-        `realtime payload for channel "${channel}"`
-      ) ?? null;
-      realtimeSignals.push({ channel, payload: normalized });
+      realtimeSignals.push({
+        channel,
+        payload: normalizeRealtimePayload(channel, payload)
+      });
     }
   };
   const services = [];
@@ -2592,42 +3071,23 @@ function createFakePluginHostInternal(options, sharedState) {
   const background = {
     service(name, service) {
       assertLive();
-      if (typeof name !== "string" || !BACKGROUND_NAME_PATTERN.test(name)) {
-        throw new Error(
-          `invalid service name ${JSON.stringify(name)} \u2014 use letters, digits, "-" and "_"`
-        );
-      }
-      if (services.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`
-        );
-      }
-      services.push({ name, start: service.start.bind(service) });
+      services.push(
+        validateBackgroundServiceRegistration(name, service, services)
+      );
     },
     schedule(name, cron, fn) {
       assertLive();
-      if (typeof name !== "string" || !BACKGROUND_NAME_PATTERN.test(name)) {
-        throw new Error(
-          `invalid schedule name ${JSON.stringify(name)} \u2014 use letters, digits, "-" and "_"`
-        );
-      }
-      if (schedules.some((record) => record.name === name)) {
-        throw new Error(`schedule "${name}" is already registered`);
-      }
-      try {
-        CronExpressionParser.parse(String(cron));
-      } catch (error) {
-        throw new Error(
-          `invalid cron ${JSON.stringify(cron)} for schedule "${name}": ${errorMessage(error)}`
-        );
-      }
-      if (typeof fn !== "function") {
-        throw new Error(`schedule "${name}" must provide a function`);
-      }
-      schedules.push({ name, cron: String(cron), fn });
+      schedules.push(
+        validateScheduleRegistration(
+          name,
+          cron,
+          fn,
+          schedules,
+          (expression) => {
+            CronExpressionParser.parse(expression);
+          }
+        )
+      );
     }
   };
   const cliRecord = {
@@ -2636,46 +3096,12 @@ function createFakePluginHostInternal(options, sharedState) {
   const cli = {
     register(registration) {
       assertLive();
-      if (cliRecord.registration !== null) {
-        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(
-          `invalid cli command name ${JSON.stringify(name)} \u2014 use lowercase letters, digits, and "-"`
-        );
-      }
-      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`
-        );
-      }
-      cliRecord.registration = {
-        name,
-        summary: registration.summary,
-        commands: validatedCommands,
-        run: registration.run.bind(registration)
-      };
-      const warning = pluginCliCollisionWarning(pluginId, name);
+      const record = normalizeCliRegistration(
+        registration,
+        cliRecord.registration !== null
+      );
+      cliRecord.registration = record;
+      const warning = pluginCliCollisionWarning(pluginId, record.name);
       if (warning) emitLog("warn", warning);
     }
   };
@@ -2761,93 +3187,13 @@ function createFakePluginHostInternal(options, sharedState) {
     },
     registerTool(tool) {
       assertLive();
-      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 (${errorMessage(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`
-      );
-      const record = {
-        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)
-      };
-      if (agentTools.some((existing) => existing.name === name)) {
-        throw new Error(`tool "${name}" is already registered`);
+      const record = normalizeAgentToolRegistration({
+        pluginId,
+        declaredIconNames,
+        tool
+      });
+      if (agentTools.some((existing) => existing.name === record.name)) {
+        throw new Error(`tool "${record.name}" is already registered`);
       }
       agentTools.push(record);
     }
@@ -2857,35 +3203,9 @@ function createFakePluginHostInternal(options, sharedState) {
     requestInput,
     registerMentionProvider(provider) {
       assertLive();
-      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 (mentionProviders.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`
-        );
-      }
-      mentionProviders.push({
-        id,
-        label: provider.label.trim(),
-        triggers: normalizeMentionProviderTriggers(id, provider.triggers),
-        search: provider.search.bind(provider),
-        resolve: provider.resolve.bind(provider)
-      });
+      mentionProviders.push(
+        normalizeMentionProviderRegistration(provider, mentionProviders)
+      );
     }
   };
   let requestedDrains = 0;
@@ -2920,6 +3240,8 @@ function createFakePluginHostInternal(options, sharedState) {
     overrides: options.sdk
   });
   const threadEventHandlers = {
+    "experimental_thread.events": [],
+    "experimental_terminal.input": [],
     "thread.created": [],
     "thread.active": [],
     "thread.idle": [],
@@ -2936,54 +3258,20 @@ function createFakePluginHostInternal(options, sharedState) {
   const hooks = {
     "message.dispatch": null
   };
+  const environmentCompositions = /* @__PURE__ */ new Map();
   const environmentProviders = /* @__PURE__ */ new Map();
+  const machineProviders = /* @__PURE__ */ new Map();
+  const serverAccessProviders = /* @__PURE__ */ new Map();
   const disposeHooks = [];
   const serviceControllers = [];
   let nextInteractionId = 1;
   const pendingInteractions = /* @__PURE__ */ new Map();
   function requestInput(request, requestOptions) {
     assertLive();
-    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") > 64 * 1024) {
-        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"
-      );
-    }
+    const normalized = normalizeInteractionRequest(request);
     const normalizedRequest = {
       ...request,
-      title: request.title.trim(),
-      payload,
-      timeoutMs
+      ...normalized
     };
     const id = `fake-interaction-${nextInteractionId++}`;
     return new Promise((resolve2) => {
@@ -3000,7 +3288,7 @@ function createFakePluginHostInternal(options, sharedState) {
       const timer = setTimeout(() => {
         pendingInteractions.delete(id);
         resolve2({ outcome: "cancelled", reason: "timeout" });
-      }, timeoutMs);
+      }, normalized.timeoutMs);
       pendingInteractions.set(id, {
         request: normalizedRequest,
         resolve: resolve2,
@@ -3032,7 +3320,13 @@ function createFakePluginHostInternal(options, sharedState) {
             });
           }
           const validatedInput = normalizeRpcJsonResult(
-            await validateRpcValue(methodContract.input, input, "input")
+            await validateRpcValue(
+              methodContract.input,
+              input,
+              "input",
+              throwRpcError
+            ),
+            throwRpcError
           );
           const call = {
             method: String(method),
@@ -3050,9 +3344,13 @@ function createFakePluginHostInternal(options, sharedState) {
           const validatedOutput = await validateRpcValue(
             methodContract.output,
             rawOutput,
-            "output"
+            "output",
+            throwRpcError
+          );
+          return normalizeRpcJsonResult(
+            validatedOutput,
+            throwRpcError
           );
-          return normalizeRpcJsonResult(validatedOutput);
         },
         experimental_onWorkerExit(handler) {
           assertLive();
@@ -3154,40 +3452,22 @@ function createFakePluginHostInternal(options, sharedState) {
     },
     experimental_contributeEnv(providerId, resolve2) {
       assertLive();
-      if (typeof providerId !== "string" || providerId.trim().length === 0) {
-        throw new Error(
-          "provider environment contribution requires a provider id"
-        );
-      }
-      if (providerEnvResolvers.has(providerId)) {
-        throw new Error(
-          `provider environment contribution for "${providerId}" is already registered`
-        );
-      }
-      if (typeof resolve2 !== "function") {
-        throw new Error(
-          "provider environment contribution requires a resolver function"
-        );
-      }
+      validateProviderEnvContribution(
+        "provider environment contribution",
+        providerId,
+        resolve2,
+        providerEnvResolvers
+      );
       providerEnvResolvers.set(providerId, resolve2);
     },
     experimental_contributeEnvHealth(providerId, resolve2) {
       assertLive();
-      if (typeof providerId !== "string" || providerId.trim().length === 0) {
-        throw new Error(
-          "provider environment health contribution requires a provider id"
-        );
-      }
-      if (providerEnvHealthResolvers.has(providerId)) {
-        throw new Error(
-          `provider environment health contribution for "${providerId}" is already registered`
-        );
-      }
-      if (typeof resolve2 !== "function") {
-        throw new Error(
-          "provider environment health contribution requires a resolver function"
-        );
-      }
+      validateProviderEnvContribution(
+        "provider environment health contribution",
+        providerId,
+        resolve2,
+        providerEnvHealthResolvers
+      );
       providerEnvHealthResolvers.set(providerId, resolve2);
     }
   };
@@ -3206,6 +3486,26 @@ function createFakePluginHostInternal(options, sharedState) {
   const experimental_environments = {
     register(declaration) {
       assertLive();
+      if ("machineProviderId" in declaration) {
+        const composition = environmentCompositionSchema.parse(declaration);
+        const problem2 = composition.icon === null ? null : undeclaredIconProblem(
+          pluginId,
+          declaredIconNames,
+          composition.icon
+        );
+        if (problem2 !== null)
+          throw new Error(providerIconRefusalMessage(composition.id, problem2));
+        if (environmentProviders.has(composition.id))
+          throw new Error(
+            "Environment ID is already registered as a concrete provider"
+          );
+        environmentCompositions.set(composition.id, composition);
+        return;
+      }
+      if (environmentCompositions.has(declaration.id))
+        throw new Error(
+          "Environment ID is already registered as a composition"
+        );
       const target = validatePluginEnvironmentProviderDeclaration(declaration);
       const problem = target.icon === null ? null : undeclaredIconProblem(pluginId, declaredIconNames, target.icon);
       if (problem !== null)
@@ -3217,6 +3517,29 @@ function createFakePluginHostInternal(options, sharedState) {
       requestedDrains += 1;
     }
   };
+  const unavailableMachineBootstrap = () => {
+    throw new Error(
+      "Configure machineBootstrap in createFakePluginHost to exercise machine bootstrap"
+    );
+  };
+  const experimental_machines = {
+    async getResource(hostId) {
+      assertLive();
+      return options.machineResource ? options.machineResource(hostId) : null;
+    },
+    ...options.machineBootstrap ?? {
+      bootstrap: unavailableMachineBootstrap
+    },
+    register(declaration) {
+      assertLive();
+      const target = validatePluginMachineProviderDeclaration(declaration);
+      const problem = target.icon === null ? null : undeclaredIconProblem(pluginId, declaredIconNames, target.icon);
+      if (problem !== null) {
+        throw new Error(providerIconRefusalMessage(target.id, problem));
+      }
+      machineProviders.set(target.id, target);
+    }
+  };
   const bb = {
     pluginId,
     log,
@@ -3233,6 +3556,22 @@ function createFakePluginHostInternal(options, sharedState) {
     events,
     experimental_hooks,
     experimental_environments,
+    experimental_machines,
+    experimental_serverAccess: {
+      register(declaration) {
+        assertLive();
+        validateServerAccessProviderDeclaration(declaration);
+        if (serverAccessProviders.has(declaration.id))
+          throw new Error(
+            `Server access provider "${declaration.id}" is already registered`
+          );
+        serverAccessProviders.set(declaration.id, declaration);
+      },
+      recheck() {
+        assertLive();
+        requestedDrains += 1;
+      }
+    },
     status,
     server,
     hosts,
@@ -3320,6 +3659,8 @@ function createFakePluginHostInternal(options, sharedState) {
       },
       get threadEventHandlers() {
         return {
+          "experimental_thread.events": threadEventHandlers["experimental_thread.events"].length,
+          "experimental_terminal.input": threadEventHandlers["experimental_terminal.input"].length,
           "thread.created": threadEventHandlers["thread.created"].length,
           "thread.active": threadEventHandlers["thread.active"].length,
           "thread.idle": threadEventHandlers["thread.idle"].length,
@@ -3337,9 +3678,18 @@ function createFakePluginHostInternal(options, sharedState) {
       get hooks() {
         return { ...hooks };
       },
+      get environmentCompositions() {
+        return new Map(environmentCompositions);
+      },
       get environmentProviders() {
         return new Map(environmentProviders);
       },
+      get serverAccessProviders() {
+        return new Map(serverAccessProviders);
+      },
+      get machineProviders() {
+        return new Map(machineProviders);
+      },
       mentionProviders,
       providerRegistrations,
       providerEnvResolvers,
@@ -3408,12 +3758,19 @@ function createFakePluginHostInternal(options, sharedState) {
       );
       for (const subscription of subscriptions) {
         const normalized = normalizeRpcJsonResult(
-          await validateRpcValue(subscription.payloadSchema, payload, "input")
+          await validateRpcValue(
+            subscription.payloadSchema,
+            payload,
+            "input",
+            throwRpcError
+          ),
+          throwRpcError
         );
         const parsed = await validateRpcValue(
           subscription.payloadSchema,
           normalized,
-          "input"
+          "input",
+          throwRpcError
         );
         await subscription.handler({ hostId, payload: parsed });
       }
@@ -3447,7 +3804,8 @@ function createFakePluginHostInternal(options, sharedState) {
       const validatedInput = await validateRpcValue(
         record.inputSchema,
         parsedInput,
-        "input"
+        "input",
+        throwRpcError
       );
       let result;
       try {
@@ -3461,9 +3819,10 @@ function createFakePluginHostInternal(options, sharedState) {
       const validatedOutput = await validateRpcValue(
         record.outputSchema,
         result,
-        "output"
+        "output",
+        throwRpcError
       );
-      return normalizeRpcJsonResult(validatedOutput);
+      return normalizeRpcJsonResult(validatedOutput, throwRpcError);
     },
     async runCli(argv, ctx = {}) {
       const registration = cliRecord.registration;
@@ -3714,12 +4073,15 @@ function createFakePluginHostInternal(options, sharedState) {
           instructions: null
         };
       }
+      const pluginMetadata = deepFreezePluginMetadata(
+        validatePluginMetadata(context.pluginMetadata ?? {})
+      );
       try {
-        const normalized = normalizeAgentConfiguration({
+        const normalized = normalizePluginAgentConfiguration({
           knownSkillIds: new Set(agentSkillIds),
           knownToolIds: new Set(agentTools.map((tool) => tool.name)),
           pluginId,
-          value: agentConfigurationProvider(context)
+          value: agentConfigurationProvider({ ...context, pluginMetadata })
         });
         const selectedTools = new Set(normalized.toolIds);
         return {
@@ -3765,8 +4127,16 @@ function makeHostResponse(overrides = {}) {
   return {
     id: "host-1",
     name: "Test host",
-    status: "connected",
     type: "persistent",
+    status: "connected",
+    machineProviderId: null,
+    lifecycle: {
+      phase: "active",
+      suspendedAt: null,
+      message: null,
+      pendingLog: "",
+      teardown: null
+    },
     maxPermissionMode: "full",
     lastSeenAt: null,
     lastRejectedProtocolVersion: null,
@@ -3806,6 +4176,7 @@ function makeThreadResponse(overrides = {}) {
 }
 function makePluginAgentConfigurationContext(overrides = {}) {
   const context = {
+    pluginMetadata: {},
     thread: {
       id: "thread-test",
       title: null,
@@ -3834,6 +4205,7 @@ function makePluginAgentConfigurationContext(overrides = {}) {
     origin: { kind: null, pluginId: null }
   };
   return {
+    pluginMetadata: overrides.pluginMetadata ?? context.pluginMetadata,
     thread: { ...context.thread, ...overrides.thread },
     project: { ...context.project, ...overrides.project },
     environment: { ...context.environment, ...overrides.environment },
@@ -3907,17 +4279,7 @@ function makeMessageDispatchHookContext(overrides = {}) {
     createdAt: 0,
     updatedAt: 0
   };
-  const hostDefaults = {
-    id: "host-1",
-    name: "Test host",
-    status: "connected",
-    type: "persistent",
-    maxPermissionMode: "full",
-    lastSeenAt: null,
-    lastRejectedProtocolVersion: null,
-    createdAt: 0,
-    updatedAt: 0
-  };
+  const hostDefaults = makeHostResponse();
   const project = { ...context.project, ...overrides.project };
   const host = overrides.host === void 0 ? context.host : overrides.host === null ? null : { ...hostDefaults, ...overrides.host };
   const environment = overrides.environment === void 0 ? context.environment : overrides.environment === null ? null : {