@nekuda/webmcp-sdk 0.4.0 → 0.6.0-dev.17.1

package/dist/index.js

@@ -1,11 +1,3 @@
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined")
-    return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
-
 // src/define.ts
 var NAME_PATTERN = /^[A-Za-z0-9_.-]{1,128}$/;
 var STABLE_KEY_PATTERN = /^[a-z0-9_]+(\.[a-z0-9_]+)+$/;
@@ -57,22 +49,97 @@ function defineTool(definition) {
       fail(field, `must be one of ${allowed.join(" | ")} when present (got ${JSON.stringify(value)})`);
     }
   }
+  if (definition.pages !== undefined && (!Array.isArray(definition.pages) || definition.pages.some((page) => typeof page !== "string"))) {
+    fail("pages", "must be an array of strings when present");
+  }
   if (typeof execute !== "function") {
     fail("execute", "must be a function");
   }
   return Object.freeze({ ...definition, name });
 }
+// src/pages.ts
+function pageKey(value) {
+  const [path = "", hash = ""] = value.split("#", 2);
+  const key = path.split("?", 1)[0] + (hash.startsWith("/") ? `#${hash.split("?", 1)[0]}` : "");
+  return `/${key}`.replace(/\/+/g, "/").replace(/\/$/, "");
+}
+function matchPage(patterns, location) {
+  if (!patterns?.length)
+    return true;
+  const key = pageKey(location);
+  return patterns.some((pattern) => {
+    if (!pattern)
+      return true;
+    const expression = pageKey(pattern).split("/").slice(1).map((segment) => segment === "**" ? "(?:/[^/]+)*" : `/${segment.split("*").map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("[^/]*")}`).join("");
+    return new RegExp(`^${expression}$`).test(key);
+  });
+}
+function currentPageKey() {
+  try {
+    const location = globalThis.location;
+    return location ? `${location.pathname}${location.search ?? ""}${location.hash ?? ""}` : undefined;
+  } catch {
+    return;
+  }
+}
+var ROUTES = Symbol.for("webmcp.sdk.page-routes");
+function onPageChange(listener) {
+  if (typeof globalThis.addEventListener !== "function" || !globalThis.history)
+    return () => {};
+  const history = globalThis.history;
+  let routes = history[ROUTES];
+  if (!routes) {
+    const listeners = new Set;
+    routes = {
+      listeners,
+      notify: () => {
+        for (const run of listeners) {
+          try {
+            run();
+          } catch {}
+        }
+      }
+    };
+    const { notify } = routes;
+    let patched = false;
+    try {
+      history[ROUTES] = routes;
+      for (const method of ["pushState", "replaceState"]) {
+        const original = history[method];
+        history[method] = function(...args) {
+          const result = original.apply(this, args);
+          if (patched)
+            notify();
+          return result;
+        };
+      }
+      patched = true;
+    } catch {}
+  }
+  const { listeners, notify } = routes;
+  if (listeners.size === 0) {
+    globalThis.addEventListener("popstate", notify);
+    globalThis.addEventListener("hashchange", notify);
+  }
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+    if (listeners.size === 0) {
+      globalThis.removeEventListener("popstate", notify);
+      globalThis.removeEventListener("hashchange", notify);
+    }
+  };
+}
 // src/spec.ts
-function resolveModelContext(g = globalThis) {
-  const scope = g;
+function resolveModelContext(scope = globalThis) {
   return scope.document?.modelContext ?? scope.navigator?.modelContext;
 }
 
 // src/transport.ts
-var INGEST_BASE = "https://ingest.agentlane.com";
+var INGEST_BASE = "https://ingest.agentlane.dev";
 var DEFAULT_COLLECT_ENDPOINT = `${INGEST_BASE}/v1/collect`;
 var DEFAULT_TELEMETRY_ENDPOINT = `${INGEST_BASE}/v1/telemetry`;
-function tryFetch(scope, url, headers, json) {
+function tryFetch(scope, url, headers, json, onResponse) {
   const f = scope.fetch;
   if (typeof f !== "function")
     return;
@@ -83,11 +150,25 @@ function tryFetch(scope, url, headers, json) {
       headers,
       body: json
     });
-    if (result && typeof result.catch === "function") {
-      result.catch(() => {});
+    if (result && typeof result.then === "function") {
+      Promise.resolve(result).then((response) => onResponse?.(response)).catch(() => {});
     }
   } catch {}
 }
+var HTTP_UNAUTHORIZED = 401;
+var KEY_REJECTED_MESSAGE = "[@nekuda/webmcp-sdk] The configured publishable key was not accepted. " + "Usage is still being recorded, but anonymously. " + "Re-run Connect to restore attributed reporting.";
+var warnedScopes = new WeakSet;
+function warnKeyRejected(scope) {
+  if (warnedScopes.has(scope))
+    return;
+  warnedScopes.add(scope);
+  const write = scope.console?.error;
+  if (typeof write === "function")
+    write.call(scope.console, KEY_REJECTED_MESSAGE);
+}
+function isUnauthorized(response) {
+  return typeof response === "object" && response !== null && response.status === HTTP_UNAUTHORIZED;
+}
 function sendToCollect(event, config, scope = globalThis) {
   try {
     const json = JSON.stringify(event);
@@ -98,16 +179,21 @@ function sendToCollect(event, config, scope = globalThis) {
     tryFetch(scope, url, headers, json);
   } catch {}
 }
+var TELEMETRY_CONTENT_TYPE = "text/plain";
 function sendTelemetry(event, scope = globalThis, endpoint, apiKey) {
   try {
     const json = JSON.stringify(event);
     if (json === undefined)
       return;
     const url = endpoint || DEFAULT_TELEMETRY_ENDPOINT;
-    const headers = { "content-type": "application/json" };
-    if (typeof apiKey === "string" && apiKey.trim().length > 0)
+    const headers = { "content-type": TELEMETRY_CONTENT_TYPE };
+    const authenticated = typeof apiKey === "string" && apiKey.trim().length > 0;
+    if (authenticated)
       headers["x-api-key"] = apiKey;
-    tryFetch(scope, url, headers, json);
+    tryFetch(scope, url, headers, json, authenticated ? (response) => {
+      if (isUnauthorized(response))
+        warnKeyRejected(scope);
+    } : undefined);
   } catch {}
 }
 var OTEL_LOGGER_NAME = "@nekuda/webmcp-sdk";
@@ -281,6 +367,14 @@ function getOrCreateSessionId(namespace) {
     return id;
   return fallbackId(memorySession, namespace, id);
 }
+function resolveSessionId(options, namespace) {
+  try {
+    const supplied = options.sessionId;
+    if (typeof supplied === "string" && usableId(supplied))
+      return supplied;
+  } catch {}
+  return getOrCreateSessionId(namespace);
+}
 function trackingOutputs(options) {
   try {
     if (!options || options.disabled)
@@ -331,9 +425,17 @@ function buildEventPayload(params) {
     eventName: params.eventName,
     ts: new Date().toISOString(),
     ...pageFields(),
-    ...params.data
+    ...params.data,
+    ...isSyntheticTester() ? { syntheticTester: true } : {}
   };
 }
+function isSyntheticTester() {
+  try {
+    return /^nekuda-synthetic-tester\/[0-9]/i.test(globalThis.navigator?.userAgent ?? "");
+  } catch {
+    return false;
+  }
+}
 var MAX_EVENT_BYTES = 64 * 1024;
 var MAX_ERROR_BYTES = 16 * 1024;
 var TRUNCATABLE = ["response", "input", "error"];
@@ -469,7 +571,7 @@ function track(options, eventName, data, sinks = defaultSinks) {
     const namespace = storageNamespace(options.apiKey);
     const event = boundEventPayload(buildEventPayload({
       visitorId: getOrCreateVisitorId(namespace),
-      sessionId: getOrCreateSessionId(namespace),
+      sessionId: resolveSessionId(options, namespace),
       eventName,
       data
     }));
@@ -761,6 +863,7 @@ var TELEMETRY_FIELDS = {
   event: true,
   ts: true,
   sessionId: true,
+  sampleRate: true,
   "sdk.name": true,
   "sdk.version": true,
   "sdk.installMode": true,
@@ -785,6 +888,7 @@ var TELEMETRY_FIELDS = {
   "config.trackingEnabled": true,
   "config.otelEnabled": true,
   "config.customEndpoint": true,
+  "config.builtWith": true,
   tools: true,
   callId: true,
   callIndex: true,
@@ -805,6 +909,8 @@ var TELEMETRY_FIELDS = {
 var TELEMETRY_TOOL_FIELDS = {
   name: true,
   stableKey: true,
+  inventoryToolId: true,
+  contractRevision: true,
   version: true,
   schemaHash: true,
   source: true,
@@ -999,9 +1105,20 @@ function shapeMetrics(inputSchema) {
 
 // src/telemetry.ts
 var SDK_NAME = "@nekuda/webmcp-sdk";
-var SDK_VERSION = "0.4.0";
+var SDK_VERSION = "0.6.0-dev.17.1";
 var INSTALL_MODES = ["npm", "cdn_snippet"];
 var SDK_INSTALL_MODE = INSTALL_MODES.find((mode) => mode === (typeof __WEBMCP_INSTALL_MODE__ === "string" ? __WEBMCP_INSTALL_MODE__ : "")) ?? "npm";
+function parseSampleRate(raw) {
+  const rate = typeof raw === "string" ? Number(raw) : Number.NaN;
+  return Number.isFinite(rate) && rate > 0 && rate < 1 ? rate : 1;
+}
+var SDK_TELEMETRY_SAMPLE_RATE = parseSampleRate(typeof __WEBMCP_TELEMETRY_SAMPLE_RATE__ === "string" ? __WEBMCP_TELEMETRY_SAMPLE_RATE__ : undefined);
+var SAMPLED_EVENTS = new Set(["sdk_init", "tool_registration"]);
+function pageSampled(sessionId, rate = SDK_TELEMETRY_SAMPLE_RATE) {
+  if (rate >= 1)
+    return true;
+  return Number.parseInt(fnv1a(`sample:${sessionId}`), 16) / 4294967296 < rate;
+}
 function isFieldParent(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -1122,12 +1239,15 @@ function buildInitEvent(params = {}) {
 }
 function configFields(tracking) {
   const { toBackend, toOtel } = trackingOutputs(tracking);
+  const builtWith = safe(() => tracking?.builtWith);
   return {
     trackingEnabled: toBackend,
     otelEnabled: toOtel,
-    customEndpoint: Boolean(safe(() => tracking?.endpoint))
+    customEndpoint: Boolean(safe(() => tracking?.endpoint)),
+    ...typeof builtWith === "string" && builtWith.length > 0 && builtWith.length <= MAX_BUILT_WITH_LENGTH ? { builtWith } : {}
   };
 }
+var MAX_BUILT_WITH_LENGTH = 64;
 var MAX_TOOL_FIELD_BYTES = 4 * 1024;
 function toolString(value) {
   return sliceToBytes(value, MAX_TOOL_FIELD_BYTES);
@@ -1135,6 +1255,9 @@ function toolString(value) {
 function toolEnum(allowed, value) {
   return allowed.find((candidate) => candidate === value);
 }
+function toolRevision(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
 var ANNOTATION_HINTS = ["readOnlyHint", "untrustedContentHint"];
 function annotationHints(annotations) {
   const hints = {};
@@ -1156,6 +1279,8 @@ function toolEntry(entry) {
   return {
     name: toolString(tool.name),
     stableKey: toolString(tool.stableKey),
+    ...typeof tool.inventoryToolId === "string" ? { inventoryToolId: toolString(tool.inventoryToolId) } : {},
+    ...toolRevision(tool.contractRevision) !== undefined ? { contractRevision: toolRevision(tool.contractRevision) } : {},
     ...tool.version !== undefined ? { version: toolString(tool.version) } : {},
     ...hash !== undefined ? { schemaHash: hash } : {},
     ...source !== undefined ? { source } : {},
@@ -1253,6 +1378,8 @@ function buildToolCallEvent(params) {
     ...sinceInit !== undefined ? { timeSinceInitMs: sinceInit } : {},
     tool: {
       stableKey: toolString(params.tool.stableKey),
+      ...typeof params.tool.inventoryToolId === "string" ? { inventoryToolId: toolString(params.tool.inventoryToolId) } : {},
+      ...toolRevision(params.tool.contractRevision) !== undefined ? { contractRevision: toolRevision(params.tool.contractRevision) } : {},
       ...hash !== undefined ? { schemaHash: hash } : {},
       ...intent !== undefined ? { intent } : {}
     },
@@ -1334,12 +1461,13 @@ function pruneByAllowlist(event, fields = TELEMETRY_FIELDS, toolFields = TELEMET
   return pruned;
 }
 var defaultSinks2 = {
-  sendTelemetry: (event) => sendTelemetry(event, globalThis, undefined, telemetryApiKey())
+  sendTelemetry: (event) => sendTelemetry(event, globalThis, telemetryEndpoint(), telemetryApiKey())
 };
-function batchTelemetrySinks(apiKey) {
+function batchTelemetrySinks(apiKey, endpoint) {
   const own = batchApiKey(apiKey);
+  const ownEndpoint = telemetryEndpointFrom(endpoint);
   return {
-    sendTelemetry: (event) => sendTelemetry(event, globalThis, undefined, own ?? telemetryApiKey())
+    sendTelemetry: (event) => sendTelemetry(event, globalThis, ownEndpoint ?? telemetryEndpoint(), own ?? telemetryApiKey())
   };
 }
 function batchApiKey(apiKey) {
@@ -1352,16 +1480,24 @@ function telemetryTenantScope(apiKey) {
   const resolved = resolveTelemetryKey(apiKey);
   return resolved === undefined ? "" : fnv1a(resolved);
 }
-function emitTelemetry(build, sinks = defaultSinks2, fields = TELEMETRY_FIELDS, toolFields = TELEMETRY_TOOL_FIELDS) {
+function emitTelemetry(build, sinks = defaultSinks2, fields = TELEMETRY_FIELDS, toolFields = TELEMETRY_TOOL_FIELDS, sampleRate = SDK_TELEMETRY_SAMPLE_RATE) {
   try {
     if (!telemetryEnabled())
       return;
-    sinks.sendTelemetry(boundEventPayload(pruneByAllowlist({ ...build() }, fields, toolFields)));
+    const event = { ...build() };
+    if (SAMPLED_EVENTS.has(String(event.event)) && sampleRate < 1) {
+      if (!pageSampled(String(event.sessionId), sampleRate))
+        return;
+      event.sampleRate = sampleRate;
+    }
+    sinks.sendTelemetry(boundEventPayload(pruneByAllowlist(event, fields, toolFields)));
   } catch {}
 }
 var initCancelled = false;
 var initFlushed = false;
+var cancelInitFallback = () => {};
 var capturedApiKey;
+var capturedEndpoint;
 function captureTelemetryApiKey(apiKey) {
   if (typeof apiKey === "string" && apiKey.trim().length > 0)
     capturedApiKey = apiKey;
@@ -1369,17 +1505,44 @@ function captureTelemetryApiKey(apiKey) {
 function telemetryApiKey() {
   return capturedApiKey;
 }
+function telemetryEndpointFrom(endpoint) {
+  if (typeof endpoint !== "string")
+    return;
+  return safe(() => {
+    const url = new URL(endpoint);
+    if (!["http:", "https:"].includes(url.protocol) || !url.pathname.endsWith("/v1/collect") || url.search !== "" || url.hash !== "") {
+      return;
+    }
+    url.pathname = `${url.pathname.slice(0, -"/v1/collect".length)}/v1/telemetry`;
+    return url.toString();
+  });
+}
+function captureTelemetryEndpoint(endpoint) {
+  const derived = telemetryEndpointFrom(endpoint);
+  if (derived !== undefined)
+    capturedEndpoint = derived;
+}
+function telemetryEndpoint() {
+  return capturedEndpoint;
+}
 function cancelInitEvent() {
   initCancelled = true;
+  cancelInitFallback();
 }
 function flushInitEvent(sinks) {
   if (initFlushed)
     return;
   initFlushed = true;
+  cancelInitFallback();
   if (initCancelled)
     return;
   emitTelemetry(() => buildInitEvent(), sinks);
 }
+function deferInitEventForBatch(sinks) {
+  if (initFlushed || initCancelled)
+    return;
+  afterDelay(() => flushInitEvent(sinks), 0);
+}
 function afterDelay(run, ms) {
   const schedule = safe(() => globalThis.setTimeout);
   if (typeof schedule !== "function")
@@ -1392,7 +1555,8 @@ function afterDelay(run, ms) {
     safe(() => clear.call(globalThis, handle));
   };
 }
-afterDelay(() => flushInitEvent(), 0);
+var INIT_FALLBACK_MS = 1000;
+cancelInitFallback = afterDelay(() => flushInitEvent(), INIT_FALLBACK_MS);
 
 // src/register.ts
 function isContentResult(value) {
@@ -1414,15 +1578,18 @@ function clock() {
   const perf = safe(() => globalThis.performance);
   const now = safe(() => perf?.now);
   if (typeof now === "function") {
-    const read2 = () => safe(() => now.call(perf));
-    const start2 = read2();
-    if (start2 !== undefined)
-      return () => elapsedMs(read2(), start2);
+    const read = () => safe(() => now.call(perf));
+    const start = read();
+    if (start !== undefined)
+      return () => elapsedMs(read(), start);
   }
   const read = () => safe(() => Date.now());
   const start = read();
   return () => elapsedMs(read(), start);
 }
+function createCallTracker(tool, tracking) {
+  return trackerFor({ ...tool, stableKey: tool.name }, tracking);
+}
 function trackerFor(tool, tracking) {
   if (!tracking)
     return;
@@ -1437,9 +1604,24 @@ function trackerFor(tool, tracking) {
   };
   return (eventName, data) => track(tracking, eventName, { ...shared, ...data });
 }
+var TRACKED_TOOL_FLAG = Symbol.for("webmcp.sdk.tracked");
+function markTracked(spec, tracking) {
+  const { toBackend } = trackingOutputs(tracking);
+  if (!toBackend)
+    return spec;
+  try {
+    Object.defineProperty(spec, TRACKED_TOOL_FLAG, {
+      value: true,
+      writable: false,
+      configurable: true,
+      enumerable: false
+    });
+  } catch {}
+  return spec;
+}
 function toSpecTool(tool, channels) {
-  const { tracking, telemetry, telemetrySinks, telemetryKey } = channels;
-  return {
+  const { tracking, telemetry, telemetrySinks, telemetryKey, telemetryEndpoint } = channels;
+  const spec = {
     name: tool.name,
     ...tool.title !== undefined ? { title: tool.title } : {},
     description: tool.description,
@@ -1451,7 +1633,7 @@ function toSpecTool(tool, channels) {
         return normalizeResult(await tool.execute(input));
       const callKey = telemetry ? resolveTelemetryKey(telemetryKey) : undefined;
       const sequence = telemetry ? nextCall(tool.stableKey, telemetryTenantScope(callKey)) : undefined;
-      const callSinks = sequence ? batchTelemetrySinks(callKey) : telemetrySinks;
+      const callSinks = sequence ? batchTelemetrySinks(callKey, telemetryEndpoint) : telemetrySinks;
       const elapsed = clock();
       trackCall?.("tool_call_request", { input });
       try {
@@ -1475,6 +1657,7 @@ function toSpecTool(tool, channels) {
       }
     }
   };
+  return markTracked(spec, tracking);
 }
 var REGISTRATION_TIMEOUT_MS = 2000;
 var PAGEHIDE = "pagehide";
@@ -1490,7 +1673,7 @@ function onPagehide(run) {
     safe(() => remove.call(g, PAGEHIDE, listener));
   };
 }
-function watchRegistration(tools, tracking, sinks) {
+function watchRegistration(tools, tracking, sinks, navigation = false) {
   const entries = tools.map((tool) => ({ tool, outcome: "pending" }));
   const elapsed = clock();
   const { registrationIndex, trigger } = nextRegistration();
@@ -1505,7 +1688,7 @@ function watchRegistration(tools, tracking, sinks) {
     const settleMs = elapsed();
     emitTelemetry(() => buildToolRegistrationEvent({
       registrationIndex,
-      trigger,
+      trigger: navigation ? "spa_navigation" : trigger,
       settleMs,
       tools: entries,
       tracking
@@ -1543,15 +1726,24 @@ function registerTools(tools, options = {}) {
   const tracking = safe(() => options.tracking);
   const telemetryLive = telemetryOption !== undefined && telemetryEnabled(telemetryOption.value);
   const apiKey = telemetryLive ? safe(() => tracking?.apiKey) : undefined;
+  const endpoint = telemetryLive ? safe(() => tracking?.endpoint) : undefined;
+  const telemetrySinks = telemetryLive ? batchTelemetrySinks(apiKey, endpoint) : undefined;
   const channels = {
     tracking,
     telemetry: telemetryLive,
-    ...telemetryLive ? { telemetrySinks: batchTelemetrySinks(apiKey), telemetryKey: apiKey } : {}
+    ...telemetryLive ? {
+      telemetrySinks,
+      telemetryKey: apiKey,
+      telemetryEndpoint: endpoint
+    } : {}
   };
   if (telemetryOption?.value === false)
     cancelInitEvent();
-  if (telemetryLive)
+  if (telemetrySinks) {
     captureTelemetryApiKey(apiKey);
+    captureTelemetryEndpoint(endpoint);
+    deferInitEventForBatch(telemetrySinks);
+  }
   assertUniqueIdentities(tools);
   const controller = new AbortController;
   const external = options.signal;
@@ -1568,32 +1760,89 @@ function registerTools(tools, options = {}) {
     state,
     ...error !== undefined ? { error } : {}
   });
-  const watch = channels.telemetry ? watchRegistration(tools, channels.tracking, channels.telemetrySinks) : undefined;
+  const active = new Map;
+  const current = () => tools.filter((tool) => active.get(tool)?.registered).map((tool) => tool.name);
+  const changed = () => {
+    safe(() => options.onChange?.(current()));
+  };
+  const eligible = (tool) => {
+    const page = currentPageKey();
+    return page === undefined || matchPage(tool.pages, page);
+  };
+  const remove = (tool) => {
+    const entry = active.get(tool);
+    if (!entry?.removable)
+      return;
+    entry.lifetime.abort();
+    safe(() => modelContext?.unregisterTool?.(tool.name));
+    active.delete(tool);
+  };
   const settle = async (tool) => {
     if (!modelContext)
       return result(tool, "unsupported");
     if (controller.signal.aborted)
       return result(tool, "aborted");
+    const entry = {
+      lifetime: tool.pages?.length ? new AbortController : controller,
+      removable: typeof modelContext.unregisterTool === "function",
+      registered: false
+    };
+    active.set(tool, entry);
     try {
       await Promise.resolve(modelContext.registerTool(toSpecTool(tool, channels), {
-        signal: controller.signal
+        get signal() {
+          entry.removable = true;
+          return entry.lifetime.signal;
+        }
       }));
-      return result(tool, "registered");
+      if (entry.lifetime.signal.aborted)
+        return result(tool, "aborted");
+      entry.registered = true;
+      if (!eligible(tool))
+        remove(tool);
+      changed();
+      return result(tool, entry.lifetime.signal.aborted ? "aborted" : "registered");
     } catch (error) {
-      if (controller.signal.aborted)
+      if (active.get(tool) === entry)
+        active.delete(tool);
+      if (entry.lifetime.signal.aborted)
         return result(tool, "aborted");
       return result(tool, "failed", error);
     }
   };
-  const ready = Promise.all(tools.map(async (tool, index) => {
-    const settled = await settle(tool);
-    watch?.record(index, settled);
-    return settled;
-  }));
-  if (watch)
-    ready.then(() => watch.emit());
+  const register = (batch, navigation = false) => {
+    const watch = channels.telemetry ? watchRegistration(batch, channels.tracking, channels.telemetrySinks, navigation) : undefined;
+    const ready = Promise.all(batch.map(async (tool, index) => {
+      const settled = await settle(tool);
+      watch?.record(index, settled);
+      return settled;
+    }));
+    if (watch)
+      ready.then(() => watch.emit());
+    return ready;
+  };
+  const reconcile = () => {
+    if (controller.signal.aborted)
+      return;
+    for (const tool of active.keys())
+      if (!eligible(tool))
+        remove(tool);
+    changed();
+    const added = tools.filter((tool) => eligible(tool) && !active.has(tool));
+    if (added.length)
+      register(added, true);
+  };
+  const stop = !controller.signal.aborted && tools.some((tool) => tool.pages?.length) ? onPageChange(reconcile) : () => {};
+  controller.signal.addEventListener("abort", () => {
+    stop();
+    for (const tool of active.keys())
+      remove(tool);
+    changed();
+  }, { once: true });
+  const ready = register(tools.filter(eligible));
   return {
     ready,
+    current,
     signal: controller.signal,
     unregister() {
       controller.abort();
@@ -1601,7 +1850,10 @@ function registerTools(tools, options = {}) {
   };
 }
 export {
-  resolveModelContext,
+  createCallTracker,
+  currentPageKey,
+  defineTool,
+  matchPage,
   registerTools,
-  defineTool
+  resolveModelContext
 };

package/dist/pages.d.ts

@@ -0,0 +1,6 @@
+/** Match any page pattern; undefined/empty lists (and empty patterns) mean everywhere. */
+export declare function matchPage(patterns: readonly string[] | undefined, location: string): boolean;
+/** No readable location (SSR) means cannot evaluate: register all tools, not a root-page match. */
+export declare function currentPageKey(): string | undefined;
+/** One shared browser listener/History patch, including across duplicated SDK bundles. */
+export declare function onPageChange(listener: () => void): () => void;