@siteverb/webmcp 0.1.0-rc.0

package/dist/browser.js

@@ -0,0 +1,841 @@
+// src/fingerprint.ts
+function canonicalize(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalize).join(",")}]`;
+  return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalize(value[key])}`).join(",")}}`;
+}
+function fallbackHash(value) {
+  let hash = 0xcbf29ce484222325n;
+  for (const byte of new TextEncoder().encode(value)) {
+    hash ^= BigInt(byte);
+    hash = BigInt.asUintN(64, hash * 0x100000001b3n);
+  }
+  return `fnv1a64:${hash.toString(16).padStart(16, "0")}`;
+}
+async function schemaFingerprint(schema) {
+  const canonical = canonicalize(schema ?? {});
+  const fallback = fallbackHash(canonical);
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) return fallback;
+  try {
+    const digest = await subtle.digest("SHA-256", new TextEncoder().encode(canonical));
+    return `sha256:${Array.from(
+      new Uint8Array(digest),
+      (byte) => byte.toString(16).padStart(2, "0")
+    ).join("")}`;
+  } catch {
+    return fallback;
+  }
+}
+
+// src/id.ts
+var fallbackSequence = 0;
+function randomId() {
+  if (typeof globalThis.crypto?.randomUUID === "function") return globalThis.crypto.randomUUID();
+  if (typeof globalThis.crypto?.getRandomValues === "function") {
+    const bytes = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(bytes);
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  }
+  fallbackSequence += 1;
+  return `fallback-${Date.now().toString(36)}-${fallbackSequence.toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+
+// src/transport.ts
+function validateEndpoint(value) {
+  if (value.length === 0 || value.length > 2e3 || value !== value.trim() || /[\u0000-\u001f\u007f]/.test(value)) {
+    throw new TypeError("Telemetry endpoint must be a bounded URL without controls.");
+  }
+  if (value.startsWith("/") && !value.startsWith("//")) {
+    const base = "https://siteverb.invalid";
+    const resolved = new URL(value, base);
+    if (resolved.origin !== base || value.includes("?") || value.includes("#")) {
+      throw new TypeError("Telemetry endpoint must not contain query or fragment data.");
+    }
+    return value;
+  }
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new TypeError("Telemetry endpoint must be a relative, HTTPS, or loopback HTTP URL.");
+  }
+  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback) || url.username || url.password || url.search || url.hash) {
+    throw new TypeError(
+      "Telemetry endpoint must use HTTPS or loopback HTTP without credentials, query, or fragment data."
+    );
+  }
+  return url.href;
+}
+function createFetchTelemetryTransport(options) {
+  if (typeof options.endpoint !== "string")
+    throw new TypeError("A telemetry endpoint is required.");
+  const endpoint = validateEndpoint(options.endpoint);
+  const fetcher = options.fetch ?? globalThis.fetch?.bind(globalThis);
+  return Object.freeze({
+    async send(batch, _reason) {
+      const body = JSON.stringify(batch);
+      if (!fetcher) throw new Error("fetch is unavailable for the telemetry transport.");
+      const response = await fetcher(endpoint, {
+        body,
+        credentials: "omit",
+        headers: { "content-type": "application/json" },
+        keepalive: true,
+        method: "POST"
+      });
+      if (!response.ok) throw new Error(`Telemetry endpoint returned HTTP ${response.status}.`);
+    }
+  });
+}
+
+// src/version.ts
+var SITEVERB_WEBMCP_VERSION = "0.1.0-rc.0";
+
+// src/telemetry.ts
+function resolveSessionId(siteId) {
+  const key = `__siteverb_session:${siteId}`;
+  try {
+    const existing = globalThis.sessionStorage?.getItem(key);
+    if (existing) return existing;
+    const created = randomId();
+    globalThis.sessionStorage?.setItem(key, created);
+    return created;
+  } catch {
+    return randomId();
+  }
+}
+function resolveRouteTemplate(route) {
+  try {
+    return typeof route === "function" ? route() : route;
+  } catch {
+    return void 0;
+  }
+}
+function boundedLabel(value, name, maxLength) {
+  if (value === void 0) return void 0;
+  if (value.length === 0 || value.length > maxLength || /[\u0000-\u001f\u007f]/.test(value)) {
+    throw new TypeError(`${name} must contain 1-${maxLength} characters without controls.`);
+  }
+  return value;
+}
+function safeRouteTemplate(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > 500 || !value.startsWith("/") || value.startsWith("//") || /[?#\u0000-\u001f\u007f]/.test(value)) {
+    return void 0;
+  }
+  return value;
+}
+function positiveInteger(value, fallback, name) {
+  if (value === void 0) return fallback;
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError(`${name} must be a positive integer.`);
+  }
+  return value;
+}
+function report(options, diagnostic2) {
+  try {
+    options.onDiagnostic?.(diagnostic2);
+  } catch {
+  }
+}
+function disabledManager() {
+  return Object.freeze({
+    enabled: false,
+    emit: () => void 0,
+    flush: async () => void 0,
+    nextSequence: () => 0,
+    status: () => ({
+      autoRetryPaused: false,
+      consecutiveFailures: 0,
+      droppedEvents: 0,
+      enabled: false,
+      pendingEvents: 0
+    }),
+    dispose: () => void 0
+  });
+}
+function createTelemetryManager(options, webmcpSupported) {
+  if (!options.telemetry) return disabledManager();
+  const siteId = boundedLabel(options.siteId, "siteId", 128);
+  if (!siteId) throw new TypeError("siteId is required when telemetry is enabled.");
+  const environment = boundedLabel(options.environment, "environment", 64);
+  const release = boundedLabel(options.release, "release", 200);
+  const telemetry = options.telemetry;
+  const transport = telemetry.transport ?? (telemetry.endpoint ? createFetchTelemetryTransport({ endpoint: telemetry.endpoint }) : (() => {
+    throw new TypeError("telemetry requires either a transport or endpoint.");
+  })());
+  const flushIntervalMs = positiveInteger(
+    telemetry.flushIntervalMs,
+    5e3,
+    "telemetry.flushIntervalMs"
+  );
+  const maxBatchSize = positiveInteger(telemetry.maxBatchSize, 20, "telemetry.maxBatchSize");
+  const maxQueueSize = positiveInteger(telemetry.maxQueueSize, 1e3, "telemetry.maxQueueSize");
+  const maxRetryAttempts = positiveInteger(
+    telemetry.maxRetryAttempts,
+    5,
+    "telemetry.maxRetryAttempts"
+  );
+  const retryMaxDelayMs = positiveInteger(
+    telemetry.retryMaxDelayMs,
+    6e4,
+    "telemetry.retryMaxDelayMs"
+  );
+  if (maxBatchSize > maxQueueSize) {
+    throw new TypeError("telemetry.maxBatchSize cannot exceed telemetry.maxQueueSize.");
+  }
+  const pageSessionId = resolveSessionId(siteId);
+  let queue = [];
+  let pendingBatch;
+  let inFlight;
+  let timer;
+  let disposed = false;
+  let autoRetryPaused = false;
+  let consecutiveFailures = 0;
+  let droppedEvents = 0;
+  let eventIndex = 0;
+  let sequenceIndex = 0;
+  let invalidRouteTemplateReported = false;
+  const schedule = (delayMs = flushIntervalMs) => {
+    if (disposed || autoRetryPaused || timer || queue.length === 0 && !pendingBatch) return;
+    timer = setTimeout(() => {
+      timer = void 0;
+      void flush("interval").catch(() => void 0);
+    }, delayMs);
+  };
+  const emit = (event, fields = {}) => {
+    if (disposed) return;
+    if (queue.length + (pendingBatch?.events.length ?? 0) >= maxQueueSize) {
+      droppedEvents += 1;
+      report(options, {
+        code: "telemetry-dropped",
+        message: "A Siteverb telemetry event was dropped because the bounded queue is full.",
+        severity: "warning"
+      });
+      return;
+    }
+    const candidateRouteTemplate = resolveRouteTemplate(options.routeTemplate);
+    const routeTemplate = safeRouteTemplate(candidateRouteTemplate);
+    if (candidateRouteTemplate !== void 0 && routeTemplate === void 0 && !invalidRouteTemplateReported) {
+      invalidRouteTemplateReported = true;
+      report(options, {
+        code: "telemetry-route-template-invalid",
+        message: "Siteverb omitted an invalid route template; use a bounded pathname template without query or fragment data.",
+        severity: "warning"
+      });
+    }
+    queue.push(
+      Object.freeze({
+        dataClass: "production",
+        event,
+        eventId: randomId(),
+        eventIndex: eventIndex++,
+        occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
+        pageSessionId,
+        ...environment === void 0 ? {} : { environment },
+        ...release === void 0 ? {} : { release },
+        ...routeTemplate === void 0 ? {} : { routeTemplate },
+        ...fields
+      })
+    );
+    if (queue.length >= maxBatchSize) void flush("size").catch(() => void 0);
+    else schedule();
+  };
+  const flush = async (reason = "manual") => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = void 0;
+    }
+    if (inFlight) {
+      await inFlight;
+      if ((reason === "manual" || reason === "lifecycle") && queue.length > 0) {
+        return flush(reason);
+      }
+      return;
+    }
+    if (!pendingBatch && queue.length === 0) return;
+    if (reason === "manual" || reason === "lifecycle") autoRetryPaused = false;
+    const batch = pendingBatch ?? Object.freeze({
+      batchId: randomId(),
+      events: Object.freeze(queue.splice(0, maxBatchSize)),
+      protocolVersion: 1,
+      sdkVersion: SITEVERB_WEBMCP_VERSION,
+      sentAt: (/* @__PURE__ */ new Date()).toISOString(),
+      siteId
+    });
+    pendingBatch = batch;
+    const attempt = (async () => {
+      try {
+        await transport.send(batch, reason);
+        if (pendingBatch?.batchId === batch.batchId) pendingBatch = void 0;
+        consecutiveFailures = 0;
+        autoRetryPaused = false;
+      } catch (cause) {
+        consecutiveFailures += 1;
+        autoRetryPaused = consecutiveFailures >= maxRetryAttempts;
+        report(options, {
+          cause,
+          code: "telemetry-send-failed",
+          message: autoRetryPaused ? "Siteverb paused automatic telemetry retries; call flush() to retry the retained batch." : "Siteverb could not deliver a telemetry batch; the same batch will be retried.",
+          severity: "warning"
+        });
+        if (!autoRetryPaused) {
+          schedule(
+            Math.min(flushIntervalMs * 2 ** Math.max(0, consecutiveFailures - 1), retryMaxDelayMs)
+          );
+        }
+        throw cause;
+      }
+    })();
+    let trackedAttempt;
+    trackedAttempt = attempt.finally(() => {
+      if (inFlight === trackedAttempt) inFlight = void 0;
+    });
+    inFlight = trackedAttempt;
+    await trackedAttempt;
+    if ((reason === "manual" || reason === "lifecycle") && queue.length > 0) {
+      return flush(reason);
+    }
+    schedule();
+  };
+  const lifecycleFlush = () => {
+    void flush("lifecycle").catch(() => void 0);
+  };
+  const visibilityFlush = () => {
+    if (typeof document !== "undefined" && document.visibilityState === "hidden") lifecycleFlush();
+  };
+  globalThis.addEventListener?.("pagehide", lifecycleFlush);
+  globalThis.document?.addEventListener?.("visibilitychange", visibilityFlush);
+  const manager = {
+    enabled: true,
+    emit,
+    flush,
+    nextSequence: () => sequenceIndex++,
+    status: () => ({
+      autoRetryPaused,
+      consecutiveFailures,
+      droppedEvents,
+      enabled: true,
+      pendingEvents: queue.length + (pendingBatch?.events.length ?? 0)
+    }),
+    dispose: () => {
+      if (disposed) return;
+      disposed = true;
+      if (timer) clearTimeout(timer);
+      timer = void 0;
+      globalThis.removeEventListener?.("pagehide", lifecycleFlush);
+      globalThis.document?.removeEventListener?.("visibilitychange", visibilityFlush);
+      lifecycleFlush();
+    }
+  };
+  emit("surface_loaded", { webmcpSupported });
+  return Object.freeze(manager);
+}
+function classifyTelemetryError(error, signal) {
+  if (signal.aborted || error instanceof DOMException && error.name === "AbortError")
+    return "abort";
+  const name = error instanceof Error ? error.name.toLowerCase().replaceAll(/[-_]/g, "") : "";
+  if (name === "timeouterror") return "timeout";
+  if (name === "networkerror") return "network";
+  if (name === "notfounderror") return "not-found";
+  if (name === "notallowederror" || name === "securityerror") return "permission";
+  if (name === "validationerror" || name === "invalidstateerror") return "validation";
+  return "unknown";
+}
+
+// src/validation.ts
+var DEFINED_TOOL = /* @__PURE__ */ Symbol("siteverb.defined-tool");
+var STABLE_ID_PATTERN = /^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)+$/;
+var TOOL_NAME_PATTERN = /^[A-Za-z0-9_.-]{1,128}$/;
+function diagnostic(code, message, path, severity) {
+  return { code, message, path, severity };
+}
+function inspectParameterDescriptions(value, path, diagnostics) {
+  if (value === null || typeof value !== "object") return;
+  if (Array.isArray(value)) {
+    value.forEach(
+      (entry, index) => inspectParameterDescriptions(entry, `${path}[${index}]`, diagnostics)
+    );
+    return;
+  }
+  const record = value;
+  if (typeof record.description === "string" && record.description.length > 150) {
+    diagnostics.push(
+      diagnostic(
+        "parameter-description-budget",
+        "Parameter descriptions should stay within 150 characters for current agent clients.",
+        `${path}.description`,
+        "warning"
+      )
+    );
+  }
+  for (const [key, entry] of Object.entries(record)) {
+    inspectParameterDescriptions(entry, `${path}.${key}`, diagnostics);
+  }
+}
+function inspectAnnotations(annotations, diagnostics) {
+  if (annotations === void 0) return;
+  if (annotations.readOnlyHint !== void 0 && typeof annotations.readOnlyHint !== "boolean" || annotations.untrustedContentHint !== void 0 && typeof annotations.untrustedContentHint !== "boolean") {
+    diagnostics.push(
+      diagnostic(
+        "invalid-annotations",
+        "WebMCP annotation hints must be booleans.",
+        "annotations",
+        "error"
+      )
+    );
+  }
+}
+function cloneSchema(schema) {
+  if (schema === void 0) return void 0;
+  const serialized = JSON.stringify(schema);
+  if (serialized === void 0) {
+    throw new TypeError("inputSchema must be JSON serializable.");
+  }
+  return JSON.parse(serialized);
+}
+function deepFreeze(value) {
+  if (value === null || typeof value !== "object" || Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const nested of Object.values(value)) deepFreeze(nested);
+  return value;
+}
+function inspectToolDefinition(definition) {
+  const diagnostics = [];
+  if (typeof definition.id !== "string" || definition.id.length > 128 || !STABLE_ID_PATTERN.test(definition.id)) {
+    diagnostics.push(
+      diagnostic(
+        "invalid-stable-id",
+        'id must be a dot-namespaced stable key such as "catalog.search-products".',
+        "id",
+        "error"
+      )
+    );
+  }
+  if (typeof definition.name !== "string" || !TOOL_NAME_PATTERN.test(definition.name)) {
+    diagnostics.push(
+      diagnostic(
+        "invalid-tool-name",
+        "name must contain 1-128 ASCII letters, digits, underscores, hyphens, or periods.",
+        "name",
+        "error"
+      )
+    );
+  } else if (definition.name.length > 30) {
+    diagnostics.push(
+      diagnostic(
+        "tool-name-budget",
+        "Tool names should stay within 30 characters for current agent clients.",
+        "name",
+        "warning"
+      )
+    );
+  }
+  if (typeof definition.description !== "string" || definition.description.trim() === "") {
+    diagnostics.push(
+      diagnostic(
+        "invalid-description",
+        "description must be a non-empty string.",
+        "description",
+        "error"
+      )
+    );
+  } else if (definition.description.length > 500) {
+    diagnostics.push(
+      diagnostic(
+        "description-budget",
+        "Tool descriptions should stay within 500 characters for current agent clients.",
+        "description",
+        "warning"
+      )
+    );
+  }
+  if (definition.title !== void 0 && typeof definition.title !== "string") {
+    diagnostics.push(
+      diagnostic("invalid-title", "title must be a string when provided.", "title", "error")
+    );
+  }
+  if (typeof definition.execute !== "function") {
+    diagnostics.push(
+      diagnostic("invalid-execute", "execute must be a function.", "execute", "error")
+    );
+  }
+  if (definition.inputSchema !== void 0 && (definition.inputSchema === null || typeof definition.inputSchema !== "object" || Array.isArray(definition.inputSchema))) {
+    diagnostics.push(
+      diagnostic(
+        "invalid-input-schema",
+        "inputSchema must be a JSON Schema object when provided.",
+        "inputSchema",
+        "error"
+      )
+    );
+  } else if (definition.inputSchema !== void 0) {
+    try {
+      const serialized = JSON.stringify(definition.inputSchema);
+      if (serialized === void 0) throw new TypeError("Schema serialized to undefined.");
+      inspectParameterDescriptions(definition.inputSchema, "inputSchema", diagnostics);
+    } catch {
+      diagnostics.push(
+        diagnostic(
+          "invalid-input-schema",
+          "inputSchema must be JSON serializable.",
+          "inputSchema",
+          "error"
+        )
+      );
+    }
+  }
+  inspectAnnotations(definition.annotations, diagnostics);
+  return Object.freeze(diagnostics);
+}
+function defineTool(definition) {
+  const diagnostics = inspectToolDefinition(definition);
+  const errors = diagnostics.filter((entry) => entry.severity === "error");
+  if (errors.length > 0) {
+    throw new TypeError(errors.map((entry) => `${entry.path}: ${entry.message}`).join("\n"));
+  }
+  const tool = {
+    ...definition,
+    ...definition.inputSchema === void 0 ? {} : { inputSchema: deepFreeze(cloneSchema(definition.inputSchema)) },
+    ...definition.annotations === void 0 ? {} : { annotations: Object.freeze({ ...definition.annotations }) }
+  };
+  Object.defineProperty(tool, DEFINED_TOOL, {
+    enumerable: false,
+    value: true
+  });
+  return Object.freeze(tool);
+}
+function isDefinedTool(value) {
+  return Boolean(
+    value && typeof value === "object" && value[DEFINED_TOOL] === true
+  );
+}
+
+// src/client.ts
+function defaultModelContext() {
+  if (typeof document === "undefined") return void 0;
+  return document.modelContext;
+}
+function resolveModelContext(options) {
+  if (typeof options.modelContext === "function") return options.modelContext();
+  return options.modelContext ?? defaultModelContext();
+}
+function nativeTool(tool, telemetry, identity) {
+  return {
+    name: tool.name,
+    ...tool.title === void 0 ? {} : { title: tool.title },
+    description: tool.description,
+    ...tool.inputSchema === void 0 ? {} : { inputSchema: tool.inputSchema },
+    ...tool.annotations === void 0 ? {} : { annotations: tool.annotations },
+    execute: async (input, executionOptions) => {
+      const signal = executionOptions?.signal ?? new AbortController().signal;
+      const invocationId = randomId();
+      const sequenceIndex = telemetry.nextSequence();
+      const telemetryIdentity = await identity;
+      const startedAt = globalThis.performance?.now() ?? Date.now();
+      telemetry.emit("tool_call_started", {
+        invocationId,
+        sequenceIndex,
+        tool: telemetryIdentity
+      });
+      try {
+        if (signal.aborted) throw abortReason(signal.reason);
+        const result = await tool.execute(input, {
+          signal,
+          invocationId
+        });
+        telemetry.emit("tool_call_completed", {
+          durationMs: Math.max(
+            0,
+            Math.round((globalThis.performance?.now() ?? Date.now()) - startedAt)
+          ),
+          invocationId,
+          sequenceIndex,
+          tool: telemetryIdentity
+        });
+        return result;
+      } catch (error) {
+        const errorClass = classifyTelemetryError(error, signal);
+        telemetry.emit(errorClass === "abort" ? "tool_call_cancelled" : "tool_call_failed", {
+          durationMs: Math.max(
+            0,
+            Math.round((globalThis.performance?.now() ?? Date.now()) - startedAt)
+          ),
+          errorClass,
+          invocationId,
+          sequenceIndex,
+          tool: telemetryIdentity
+        });
+        throw error;
+      }
+    }
+  };
+}
+function abortReason(reason) {
+  if (reason !== void 0) return reason;
+  return new DOMException("The Siteverb registration was removed.", "AbortError");
+}
+function createSiteverb(options = {}) {
+  const registrationsById = /* @__PURE__ */ new Map();
+  const registrationsByName = /* @__PURE__ */ new Map();
+  const telemetry = createTelemetryManager(options, Boolean(resolveModelContext(options)));
+  const registerTool = (definition, registerOptions = {}) => {
+    const tool = isDefinedTool(definition) ? definition : defineTool(definition);
+    if (registrationsById.has(tool.id)) {
+      throw new TypeError(`A Siteverb tool with id "${tool.id}" is already registered.`);
+    }
+    if (registrationsByName.has(tool.name)) {
+      throw new TypeError(`A WebMCP tool with name "${tool.name}" is already registered.`);
+    }
+    const controller = new AbortController();
+    const identity = schemaFingerprint(tool.inputSchema).then((schemaHash) => ({
+      schemaHash,
+      stableKey: tool.id,
+      wireName: tool.name
+    }));
+    let resolvedIdentity;
+    void identity.then((value) => {
+      resolvedIdentity = value;
+    });
+    let externalAbort;
+    let emittedRegistration = false;
+    const mutable = {};
+    const unregister = (reason) => {
+      if (mutable.status === "unregistered") return;
+      controller.abort(abortReason(reason));
+      if (emittedRegistration) {
+        if (resolvedIdentity) telemetry.emit("tool_unregistered", { tool: resolvedIdentity });
+        else {
+          void identity.then(
+            (toolIdentity) => telemetry.emit("tool_unregistered", { tool: toolIdentity })
+          );
+        }
+        emittedRegistration = false;
+      }
+      mutable.status = "unregistered";
+      registrationsById.delete(tool.id);
+      registrationsByName.delete(tool.name);
+      if (externalAbort) registerOptions.signal?.removeEventListener("abort", externalAbort);
+    };
+    const handle = {
+      id: tool.id,
+      name: tool.name,
+      get status() {
+        return mutable.status;
+      },
+      signal: controller.signal,
+      unregister
+    };
+    mutable.handle = handle;
+    mutable.status = "pending";
+    registrationsById.set(tool.id, mutable);
+    registrationsByName.set(tool.name, mutable);
+    if (registerOptions.signal) {
+      externalAbort = () => unregister(registerOptions.signal?.reason);
+      if (registerOptions.signal.aborted) externalAbort();
+      else registerOptions.signal.addEventListener("abort", externalAbort, { once: true });
+    }
+    const ready = (async () => {
+      if (controller.signal.aborted) throw controller.signal.reason;
+      const context = resolveModelContext(options);
+      if (controller.signal.aborted) throw controller.signal.reason;
+      if (!context) {
+        mutable.status = "unsupported";
+        return { id: tool.id, name: tool.name, status: "unsupported" };
+      }
+      try {
+        await context.registerTool(nativeTool(tool, telemetry, identity), {
+          signal: controller.signal,
+          ...registerOptions.exposedTo === void 0 ? {} : { exposedTo: [...registerOptions.exposedTo] }
+        });
+        if (controller.signal.aborted) throw controller.signal.reason;
+        resolvedIdentity = await identity;
+        if (controller.signal.aborted) throw controller.signal.reason;
+        mutable.status = "registered";
+        emittedRegistration = true;
+        telemetry.emit("tool_registered", { tool: resolvedIdentity });
+        return { id: tool.id, name: tool.name, status: "registered" };
+      } catch (error) {
+        if (mutable.status !== "unregistered") mutable.status = "failed";
+        registrationsById.delete(tool.id);
+        registrationsByName.delete(tool.name);
+        const errorClass = classifyTelemetryError(error, controller.signal);
+        telemetry.emit(
+          errorClass === "abort" ? "tool_registration_cancelled" : "tool_registration_failed",
+          {
+            errorClass,
+            tool: await identity
+          }
+        );
+        throw error;
+      }
+    })();
+    handle.ready = ready;
+    void ready.catch(() => void 0);
+    return handle;
+  };
+  const registerTools = (definitions, registerOptions = {}) => {
+    const definitionsById = /* @__PURE__ */ new Set();
+    const definitionsByName = /* @__PURE__ */ new Set();
+    const tools = definitions.map(
+      (definition) => isDefinedTool(definition) ? definition : defineTool(definition)
+    );
+    for (const tool of tools) {
+      if (definitionsById.has(tool.id) || registrationsById.has(tool.id)) {
+        throw new TypeError(`A Siteverb tool with id "${tool.id}" is already registered.`);
+      }
+      if (definitionsByName.has(tool.name) || registrationsByName.has(tool.name)) {
+        throw new TypeError(`A WebMCP tool with name "${tool.name}" is already registered.`);
+      }
+      definitionsById.add(tool.id);
+      definitionsByName.add(tool.name);
+    }
+    const controller = new AbortController();
+    const handles = [];
+    const atomic = registerOptions.atomic ?? true;
+    let externalAbort;
+    const unregister = (reason) => {
+      controller.abort(abortReason(reason));
+      for (const handle of handles) handle.unregister(reason);
+      if (externalAbort) registerOptions.signal?.removeEventListener("abort", externalAbort);
+    };
+    if (registerOptions.signal) {
+      externalAbort = () => unregister(registerOptions.signal?.reason);
+      if (registerOptions.signal.aborted) externalAbort();
+      else registerOptions.signal.addEventListener("abort", externalAbort, { once: true });
+    }
+    try {
+      for (const definition of tools) {
+        handles.push(
+          registerTool(definition, {
+            signal: controller.signal,
+            ...registerOptions.exposedTo === void 0 ? {} : { exposedTo: registerOptions.exposedTo }
+          })
+        );
+      }
+    } catch (error) {
+      if (atomic) unregister(error);
+      throw error;
+    }
+    const ready = Promise.all(handles.map((handle) => handle.ready)).catch((error) => {
+      if (atomic) unregister(error);
+      throw error;
+    });
+    void ready.catch(() => void 0);
+    return Object.freeze({
+      handles: Object.freeze(handles),
+      ready,
+      signal: controller.signal,
+      unregister
+    });
+  };
+  const snapshot = () => {
+    const tools = Array.from(registrationsById.values(), ({ handle, status }) => ({
+      id: handle.id,
+      name: handle.name,
+      status
+    })).sort((left, right) => left.id.localeCompare(right.id));
+    return {
+      ...options.environment === void 0 ? {} : { environment: options.environment },
+      ...options.release === void 0 ? {} : { release: options.release },
+      ...options.siteId === void 0 ? {} : { siteId: options.siteId },
+      supported: Boolean(resolveModelContext(options)),
+      telemetry: telemetry.status(),
+      tools
+    };
+  };
+  const coverage = async () => {
+    const context = resolveModelContext(options);
+    const instrumented = Array.from(registrationsByName.keys()).sort();
+    if (!context?.getTools) {
+      return {
+        completeness: null,
+        discovered: [],
+        instrumented,
+        inventoryOnly: [],
+        missing: [],
+        status: "unavailable"
+      };
+    }
+    let discovered;
+    try {
+      discovered = Array.from(new Set((await context.getTools()).map((tool) => tool.name))).sort();
+    } catch (cause) {
+      options.onDiagnostic?.({
+        cause,
+        code: "coverage-unavailable",
+        message: "The native WebMCP inventory could not be read.",
+        severity: "warning"
+      });
+      return {
+        completeness: null,
+        discovered: [],
+        instrumented,
+        inventoryOnly: [],
+        missing: [],
+        status: "unavailable"
+      };
+    }
+    const discoveredSet = new Set(discovered);
+    const instrumentedSet = new Set(instrumented);
+    const inventoryOnly = discovered.filter((name) => !instrumentedSet.has(name));
+    const missing = instrumented.filter((name) => !discoveredSet.has(name));
+    return {
+      completeness: discovered.length === 0 ? instrumented.length === 0 ? null : 0 : (discovered.length - inventoryOnly.length) / discovered.length,
+      discovered,
+      instrumented,
+      inventoryOnly,
+      missing,
+      status: "available"
+    };
+  };
+  const dispose = (reason) => {
+    for (const registration of Array.from(registrationsById.values())) {
+      registration.handle.unregister(reason);
+    }
+    telemetry.dispose();
+  };
+  return Object.freeze({
+    get supported() {
+      return Boolean(resolveModelContext(options));
+    },
+    get telemetry() {
+      return telemetry.status();
+    },
+    registerTool,
+    registerTools,
+    coverage,
+    dispose,
+    flush: () => telemetry.flush("manual"),
+    snapshot
+  });
+}
+
+// src/evals/index.ts
+function toWebMcpEvalsSchema(tools) {
+  const names = /* @__PURE__ */ new Set();
+  const exported = tools.map((candidate) => {
+    const tool = isDefinedTool(candidate) ? candidate : defineTool(candidate);
+    if (names.has(tool.name)) {
+      throw new TypeError(`Cannot export duplicate WebMCP tool name "${tool.name}".`);
+    }
+    names.add(tool.name);
+    return Object.freeze({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema ?? null,
+      outputSchema: null,
+      ...tool.annotations === void 0 ? {} : { annotations: tool.annotations }
+    });
+  });
+  return Object.freeze({ tools: Object.freeze(exported) });
+}
+export {
+  SITEVERB_WEBMCP_VERSION,
+  createFetchTelemetryTransport,
+  createSiteverb,
+  defineTool,
+  inspectToolDefinition,
+  isDefinedTool,
+  toWebMcpEvalsSchema
+};