@nekuda/webmcp-sdk 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,90 @@
 # Changelog
 
+## 0.6.0 — 2026-09-18
+
+Five additive changes, no breaking change. The wire schema stays at `2`. Four of them
+are opt-in options — `builtWith`, `pages`, `sessionId` and `createCallTracker` — each
+silent when unset, so **an npm consumer who sets none of them sends exactly the bytes
+0.5.0 sent**. The fifth is a non-enumerable mark this SDK writes on the tool objects it
+registers under a batch that is already posting to the collect edge; it is invisible to
+enumeration and to `JSON` and never reaches the wire, so it changes no bytes either.
+
+One behaviour is **CDN-build-only**. Page-level telemetry sampling is switched on by a
+`bun build --define`, which only `infra/deploy-snippet.sh` passes when it builds the CDN
+snippet; neither publish lane passes it, so **an npm install is unsampled** and sends
+every page-level event, exactly as before.
+
+### Page-level telemetry sampling — CDN builds only
+
+- A build may sample the two page-level telemetry events (`sdk_init`,
+  `tool_registration`) with `--define '__WEBMCP_TELEMETRY_SAMPLE_RATE__="0.1"'`. The
+  decision is one coin per page load from the `sessionId`, so a page's events are kept
+  or dropped together, and every kept event carries `sampleRate` for weighting.
+  `tool_call` is never sampled. Unset, or anything outside (0, 1), sends everything,
+  which is the npm default and the previous behaviour byte for byte. The CDN snippet
+  builds at `0.1`: installed sites had reached five million page-level beacons a day.
+
+### `tracking.builtWith`
+
+- **`TrackingOptions.builtWith`** names what generated the integration, as
+  `<tool>[/<path>]@<version>` (`webmcp-kit/implement@<plugin version>`,
+  `webmcp-kit/connect-existing-tools@<plugin version>`), and is reported verbatim
+  as `config.builtWith` on `tool_registration`. Additive and optional: unset emits
+  exactly the bytes it did before. It exists so kit-built sites are countable on
+  the default-on channel without a Connect. Dropped, never truncated, when empty
+  or over 64 characters.
+
+### Page-scoped tools
+
+- `defineTool({ pages })` filters registration on load and SPA navigation; `matchPage`
+  and `currentPageKey` expose the fixture-pinned matching rule. SDK metadata stays off
+  the native tool object. `ready` covers the initial filtered set; `current()` and
+  `onChange` expose live names. Unregistration uses native abort signals, with legacy
+  `unregisterTool` support and explicit retention on surfaces supporting neither.
+
+### A host may own the session and track its own tools
+
+Two additive `tracking`-channel surfaces for a host that owns the page it runs on
+(the CDN snippet). Nothing existing changes: both are opt-in, both are silent
+under the same `trackingOutputs` gate as everything else on this channel, and a
+consumer that sets neither emits exactly the bytes it did before.
+
+- **`TrackingOptions.sessionId`** reports under a session identity the host
+  already has — a tab session that predates any `registerTools` call, or a
+  Journey runner's synthetic `syn_…` id — instead of the one this channel mints
+  in `sessionStorage` under an `apiKey`-derived namespace, which would split one
+  visit into two sessions the pipeline cannot rejoin. Supplying it means no
+  `sessionStorage` read or write at all for that batch, `last_seen` included, so
+  the 30-minute inactivity boundary becomes the host's to enforce; `visitorId` is
+  untouched. Validated like a stored id (non-empty, ≤ 64 chars, a string) —
+  anything else falls back to the minted session, because identity fields skip the
+  truncation ladder.
+- **`createCallTracker(tool, tracking)`** emits the request/response pair for a
+  tool the host registered on `document.modelContext` itself, in the same bytes an
+  SDK-registered tool's call produces — same event names, same correlated `callId`,
+  same anonymous identity — so the projection reads one shape rather than two. The
+  host owns the rest: one tracker per invocation, `tool_call_request` before the
+  handler and `tool_call_response` after, and the `duration_ms` it reports. The
+  tool's `name` is its `stableKey`, since a host-wrapped tool has no
+  developer-authored durable identity to carry — and that rule is applied *over*
+  the caller's object, so a `stableKey` riding in on a tool descriptor from a page
+  the host does not control cannot key that tool differently from every other
+  reader of the same page.
+
+### A tracked tool says so, for a host that owns the surface
+
+- A tool registered by a batch that posts to the collect edge now carries the registry
+  symbol `Symbol.for("webmcp.sdk.tracked")` (non-enumerable, value `true`) on the object
+  handed to `registerTool`. It exists for a host that owns the page's WebMCP surface and
+  wraps what it finds there — the CDN snippet's coexistence gate — which could not
+  otherwise tell a tool whose calls this SDK already reports from a merchant's bare one,
+  and reported every such invocation a second time. Nothing else changes: the mark is
+  written only when the channel really is posting (an unkeyed batch, an empty
+  `tracking: {}`, a closed consent gate and an otel-only batch carry none), it is
+  invisible to enumeration and to `JSON`, and no export is added. It is the one change
+  here that is not an option a consumer sets — but being non-enumerable it reaches
+  neither the wire nor `JSON.stringify`, so no bytes move.
+
 ## 0.5.0 — 2026-08-24 — usage telemetry schema 2 (breaking wire format)
 
 The usage-telemetry channel emits **three events instead of two**, carrying
@@ -65,6 +150,17 @@ unchanged. See `docs/telemetry-schema.md`.
 
 ### Added
 
+- **One `console.error` when a configured publishable key is refused.** The telemetry
+  route now answers `401` for a key that was *sent* and did not resolve; the beacon is
+  still recorded, anonymously, so nothing is lost but the attribution. The SDK reports
+  that at most once per page load — naming the SDK, saying recording continues
+  anonymously before saying what broke, and pointing at re-running Connect. It never
+  echoes the key or anything off the wire. No throw, no retry, no second send, and no
+  change to the send path. Anonymous beacons are never inspected (they have no key to
+  be wrong about), and every other status, a network failure, and an environment with
+  no `console` stay silent as before. This narrows 0.2.0's "the SDK is silent by
+  default": it is the only output the package produces, and only a broken key produces
+  it.
 - **`globalThis.__WEBMCP_TELEMETRY__ = false`** silences the channel page-wide
   without touching a `registerTools` call site — the only lever a site has when the
   calls come from generated code it does not edit. Strictly `false`, like GPC is

package/README.md

@@ -0,0 +1,32 @@
+# @nekuda/webmcp-sdk
+
+Define tools with `defineTool`, then pass them to `registerTools(tools, options)`.
+`ready` resolves with initial per-tool outcomes; `unregister()` or `options.signal`
+ends the batch. Browsers without a WebMCP surface report `unsupported`.
+
+## Page-scoped tools
+
+Set `pages: ["/products/*"]` on a tool definition to register it only on matching
+pages. Missing/empty `pages` means everywhere; lists match any entry. `*` matches
+any characters within one segment (`/products/*`, `/product.html*`), `**` zero or
+more segments; queries and trailing slashes are ignored on both patterns and locations,
+and repeated slashes collapse to one. Hash
+routers use patterns such as `/#/product/*`. With no readable location (SSR),
+all tools are eligible because the page cannot be evaluated.
+
+The SDK reconciles tools on `pushState`, `replaceState`, `popstate`, and
+`hashchange`, sharing one route listener. If History cannot be patched, registration
+still succeeds and navigation detection falls back to `popstate`/`hashchange` only.
+A failing route subscriber never escapes into the merchant's History calls or blocks
+other subscribers. `registration.current()` lists live
+names; `options.onChange(names)` keeps host displays in sync. `ready` covers only
+the initially eligible tools. SDK-only `pages` never reaches native `registerTool`.
+
+The [WebMCP draft](https://webmachinelearning.github.io/webmcp/), checked
+2026-09-10, unregisters via the registration's **AbortSignal**, not
+`unregisterTool`; this works on either resolved modelContext global. Legacy
+surfaces exposing `unregisterTool(name)` are supported too. A surface that neither
+reads the registration signal nor exposes that method keeps a tool once registered;
+the SDK reports it as still live rather than claiming removal. Ending a batch always
+removes its route subscription. Fixtures under `fixtures/` pin matching semantics
+for tests and stay out of the published package.

package/dist/define.d.ts

@@ -1,4 +1,22 @@
 import type { ToolAnnotations } from "./spec.js";
+/**
+ * Spec rule: tool names are 1–128 chars of ASCII alphanumerics, `_`, `-`, `.`.
+ *
+ * Exported for the seam pin only (`tests/tool-key-patterns.test.ts`), not re-exported by
+ * `index.ts`: the platform's catalog CHECKs the same shape, and a widening here that the
+ * database refuses would reject tools this SDK already accepted in the wild.
+ */
+export declare const NAME_PATTERN: RegExp;
+/**
+ * `stableKey` rule: dot-namespaced `domain.action` — two or more `[a-z0-9_]+`
+ * segments joined by `.`. Rejects the common authoring mistake of copying the
+ * wire `name` into `stableKey` (e.g. `search_blog_posts`), which defeats the
+ * field's purpose: a `name` can be renamed freely, but a `stableKey` that is
+ * just a `name` copy renames right along with it.
+ *
+ * Exported for the seam pin only — see {@link NAME_PATTERN}.
+ */
+export declare const STABLE_KEY_PATTERN: RegExp;
 /** How the tool came to exist. Reported on telemetry as `tools[].source`. */
 export type ToolSource = "scanner_generated" | "merchant_authored";
 /** What the tool is for. Reported on telemetry as `tools[].intent`. */
@@ -33,6 +51,8 @@ export interface ToolDefinition<TInput extends Record<string, unknown> = Record<
     /** JSON Schema for `execute`'s input, as a plain object. */
     inputSchema?: Record<string, unknown>;
     annotations?: ToolAnnotations;
+    /** Page patterns where this tool is available; absent/empty means everywhere. SDK-only. */
+    pages?: string[];
     /**
      * Optional per-tool version, surfaced on emitted tracking events as `toolVersion`
      * for drift analytics. Free-form string (e.g. semver or a codegen hash); when
@@ -51,6 +71,25 @@ export interface ToolDefinition<TInput extends Record<string, unknown> = Record<
      * rather than per-batch because one tool answers while another transacts.
      */
     intent?: ToolIntent;
+    /**
+     * The identity the connected platform assigned this tool, if the host knows it —
+     * an opaque string the SDK copies and never interprets.
+     *
+     * `stableKey` is the DEVELOPER's durable identity and survives renames; this is the
+     * server's, handed back once a site is connected. Both are reported because they
+     * answer different questions: a key the developer chose can collide across two
+     * scopes of one site, while the assigned id cannot, and only the developer's key
+     * exists before a site is connected at all. Absent is the ordinary state — a tool
+     * declared in a codebase that has never been connected simply has no such id, and
+     * the SDK never invents one.
+     */
+    inventoryToolId?: string;
+    /**
+     * The contract revision the host believes this tool matches, if it knows one.
+     * Reported so a stale bundle can be told apart from a tool that genuinely changed
+     * shape; never validated here, and never used for anything on the page.
+     */
+    contractRevision?: number;
     /**
      * The page-owned behavior. May return anything JSON-serializable, a plain string,
      * or a ready-made `{ content: [...] }` result — the SDK normalizes for the agent.

package/dist/index.d.ts

@@ -14,8 +14,8 @@
  *    and is never sent to the browser.
  * 3. Registration lifecycle: `registerTools(tools, { signal?, tracking?, telemetry? })`
  *    registers on call
- *    and returns `{ ready, unregister, signal }`. Unregistration happens ONLY via
- *    `unregister()` or the external signal aborting (page teardown / SPA unmount).
+ *    and returns `{ ready, current, unregister, signal }`. Page-scoped tools also
+ *    register/unregister as routes change; `unregister()` or an external abort ends the batch.
  *    Browsers without a WebMCP surface are a graceful no-op (`state: "unsupported"`).
  * 4. "Connect later without rewrite": generated modules only `defineTool` and
  *    EXPORT tools; one entry module calls `registerTools`. Connecting a site to the
@@ -38,7 +38,13 @@
  *    both outputs — but for THIS channel only; the default-on telemetry channel of
  *    point 6 has its own opt-out (`telemetry: false`) and `disabled` does not
  *    narrow it. See `src/tracking.ts`, `src/transport.ts`, and
- *    `examples/add-to-cart.ts`.
+ *    `examples/add-to-cart.ts`. `TrackingOptions.sessionId` lets a host that is
+ *    already the page's session authority report under its own id instead of the
+ *    one this channel mints; `createCallTracker(tool, tracking)` lets that same
+ *    host emit the pair for a tool it registered on the surface *itself*, in the
+ *    same bytes. Both exist for one caller — a host of this SDK that owns the page
+ *    (the CDN snippet) — and neither is part of what plugin codegen targets:
+ *    generated code registers tools and reads nothing here.
  * 6. Anonymous usage telemetry is a SECOND, independent channel: default-ON, so it
  *    reports from every site the SDK runs on, not only from `apiKey` tenants. Three
  *    events (`TelemetryEvent`), all `schema: 2` and joined on an in-memory
@@ -74,7 +80,8 @@
  *    platform stays a config-only change to the entry module (point 4).
  */
 export { type AnyWebMCPTool, type ToolDefinition, type ToolIntent, type ToolSource, type WebMCPTool, defineTool, } from "./define.js";
-export { type RegisterToolsOptions, type ToolRegistration, type ToolRegistrationResult, type ToolRegistrationState, registerTools, } from "./register.js";
+export { currentPageKey, matchPage } from "./pages.js";
+export { type CallTracker, type RegisterToolsOptions, type ToolRegistration, type ToolRegistrationResult, type ToolRegistrationState, type TrackedCall, createCallTracker, registerTools, } from "./register.js";
 export { type ModelContextLike, type RegisterToolOptions, type SpecTool, type ToolAnnotations, resolveModelContext, } from "./spec.js";
 export type { AgentRuntime, FormFactor, FrameContext, PageVisibility, ReferrerClass, SurfaceGlobal, SurfaceInfo, SurfaceProvenance, } from "./telemetry-context.js";
 export type { ClientContext, InstallMode, PageContext, RegisteredToolEntry, RegistrationTrigger, SdkInfo, SdkInitEvent, StrippedToolEntry, TelemetryEnvelope, TelemetryEvent, TelemetryEventName, ToolCallEvent, ToolCallOutcome, ToolCallResponseMetrics, ToolCallToolInfo, ToolRegistrationEvent, ToolRegistrationOutcome, TrackingConfigInfo, TruncatedTools, } from "./telemetry-events.js";

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,14 +49,89 @@ 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;
 }
 
@@ -72,7 +139,7 @@ function resolveModelContext(g = globalThis) {
 var INGEST_BASE = "https://ingest.agentlane.com";
 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);
@@ -105,9 +186,13 @@ function sendTelemetry(event, scope = globalThis, endpoint, apiKey) {
       return;
     const url = endpoint || DEFAULT_TELEMETRY_ENDPOINT;
     const headers = { "content-type": "application/json" };
-    if (typeof apiKey === "string" && apiKey.trim().length > 0)
+    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 +366,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 +424,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 +570,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 +862,7 @@ var TELEMETRY_FIELDS = {
   event: true,
   ts: true,
   sessionId: true,
+  sampleRate: true,
   "sdk.name": true,
   "sdk.version": true,
   "sdk.installMode": true,
@@ -785,6 +887,7 @@ var TELEMETRY_FIELDS = {
   "config.trackingEnabled": true,
   "config.otelEnabled": true,
   "config.customEndpoint": true,
+  "config.builtWith": true,
   tools: true,
   callId: true,
   callIndex: true,
@@ -805,6 +908,8 @@ var TELEMETRY_FIELDS = {
 var TELEMETRY_TOOL_FIELDS = {
   name: true,
   stableKey: true,
+  inventoryToolId: true,
+  contractRevision: true,
   version: true,
   schemaHash: true,
   source: true,
@@ -999,9 +1104,20 @@ function shapeMetrics(inputSchema) {
 
 // src/telemetry.ts
 var SDK_NAME = "@nekuda/webmcp-sdk";
-var SDK_VERSION = "0.5.0";
+var SDK_VERSION = "0.6.0";
 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 +1238,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 +1254,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 +1278,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 +1377,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 } : {}
     },
@@ -1353,11 +1479,17 @@ 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;
@@ -1445,15 +1577,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;
@@ -1468,9 +1603,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, telemetryEndpoint: telemetryEndpoint2 } = channels;
-  return {
+  const { tracking, telemetry, telemetrySinks, telemetryKey, telemetryEndpoint } = channels;
+  const spec = {
     name: tool.name,
     ...tool.title !== undefined ? { title: tool.title } : {},
     description: tool.description,
@@ -1482,7 +1632,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, telemetryEndpoint2) : telemetrySinks;
+      const callSinks = sequence ? batchTelemetrySinks(callKey, telemetryEndpoint) : telemetrySinks;
       const elapsed = clock();
       trackCall?.("tool_call_request", { input });
       try {
@@ -1506,6 +1656,7 @@ function toSpecTool(tool, channels) {
       }
     }
   };
+  return markTracked(spec, tracking);
 }
 var REGISTRATION_TIMEOUT_MS = 2000;
 var PAGEHIDE = "pagehide";
@@ -1521,7 +1672,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();
@@ -1536,7 +1687,7 @@ function watchRegistration(tools, tracking, sinks) {
     const settleMs = elapsed();
     emitTelemetry(() => buildToolRegistrationEvent({
       registrationIndex,
-      trigger,
+      trigger: navigation ? "spa_navigation" : trigger,
       settleMs,
       tools: entries,
       tracking
@@ -1608,32 +1759,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();
@@ -1641,7 +1849,10 @@ function registerTools(tools, options = {}) {
   };
 }
 export {
+  createCallTracker,
+  currentPageKey,
   defineTool,
+  matchPage,
   registerTools,
   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;

package/dist/register.d.ts

@@ -16,6 +16,8 @@ export interface ToolRegistrationResult {
     error?: unknown;
 }
 export interface RegisterToolsOptions {
+    /** Called after the live name set changes, including initial registration and navigation. */
+    onChange?: (names: string[]) => void;
     /**
      * External lifetime for the registration (e.g. a component's unmount signal).
      * Aborting it unregisters every tool in this batch, same as `unregister()`.
@@ -64,18 +66,55 @@ export interface ToolRegistration {
      * cannot mask the rest.
      */
     ready: Promise<ToolRegistrationResult[]>;
+    /** Currently registered names, in declaration order; `ready` covers only the initial page. */
+    current(): string[];
     /** Unregister every tool in this batch. Idempotent. */
     unregister(): void;
     /** The signal carrying this registration's lifetime (aborted once unregistered). */
     signal: AbortSignal;
 }
+/**
+ * Emits one invocation's authenticated-channel events. The `callId` correlating a
+ * `tool_call_request` with its `tool_call_response` is closed over, so one tracker
+ * is one call — never one tool, never one page.
+ */
+export type CallTracker = (eventName: string, data: Record<string, unknown>) => void;
+/**
+ * A tool a host observes but did not register through {@link registerTools} — the
+ * only identity it can offer is the wire `name` the agent surface already knows.
+ */
+export interface TrackedCall {
+    name: string;
+    /** Optional per-tool version, surfaced on the events as `toolVersion`. */
+    version?: string;
+}
+/**
+ * Emitter for a call on a tool this SDK did not register, or `undefined` when the
+ * authenticated channel has no live output — the same `trackingOutputs` answer
+ * {@link registerTools} gates its own per-call emitter on, so the two cannot
+ * disagree about whether the channel is live.
+ *
+ * This exists for one caller shape: a host that owns the page's WebMCP surface and
+ * wraps tools registered on it directly (the CDN snippet's coexistence path). Those
+ * calls must land on `/v1/collect` as the same bytes an SDK-registered tool's do —
+ * same event names, same correlated pair, same anonymous identity — so the
+ * projection reads one shape rather than two. Everything else the host must do
+ * itself: call it once per invocation (a reused tracker collapses two calls into
+ * one `callId`), emit `tool_call_request` before the handler and
+ * `tool_call_response` after, and measure the `duration_ms` it reports.
+ *
+ * `stableKey` is the tool's `name`: a host-wrapped tool has no developer-authored
+ * durable identity to carry, and inventing one would key the same tool differently
+ * from every other reader of the same page.
+ */
+export declare function createCallTracker(tool: TrackedCall, tracking: TrackingOptions): CallTracker | undefined;
 /**
  * Register a batch of `defineTool` tools on the page's WebMCP surface.
  *
- * Lifecycle: registration starts immediately; the tools stay live until
- * `unregister()` is called or the external `options.signal` aborts (both funnel
- * into one internal `AbortController`, the spec's only unregistration mechanism).
- * On browsers without a WebMCP surface this is a graceful no-op — generated code
- * can run unconditionally on every page.
+ * Registration starts immediately, filtered by `pages`; `ready` covers that initial set.
+ * Route changes reconcile scoped tools using per-tool signals (or legacy unregisterTool).
+ * A legacy surface that never reads the signal and has no unregister method retains a
+ * tool once registered. `unregister()`/external abort also removes the route subscription.
+ * Without a readable location (SSR), all tools are eligible; without a surface, no-op.
  */
 export declare function registerTools(tools: readonly AnyWebMCPTool[], options?: RegisterToolsOptions): ToolRegistration;

package/dist/spec.d.ts

@@ -11,9 +11,9 @@
  *   - `registerTool(tool, { signal })` returns a promise that settles when the
  *     registration completes; it rejects on a duplicate name, an invalid tool, an
  *     inactive document, or an abort.
- *   - Unregistration happens ONLY by aborting the `AbortSignal` passed at
- *     registration. `unregisterTool()` and `provideContext()` are dead APIs and are
- *     never referenced.
+ *   - Current unregistration is the `AbortSignal` passed at registration (also
+ *     verified against the 2026-09-10 draft). Legacy surfaces may instead expose
+ *     `unregisterTool(name)`; a surface supporting neither retains registered tools.
  *   - Tool names: 1–128 chars of [A-Za-z0-9_\-.].
  *   - `annotations.readOnlyHint` / `annotations.untrustedContentHint`.
  *
@@ -48,9 +48,20 @@ export interface RegisterToolOptions {
  */
 export interface ModelContextLike {
     registerTool(tool: SpecTool, options?: RegisterToolOptions): Promise<void>;
+    /** Pre-draft compatibility only; current native surfaces use the registration signal. */
+    unregisterTool?(name: string): void;
+}
+interface GlobalWithModelContext {
+    document?: {
+        modelContext?: ModelContextLike;
+    };
+    navigator?: {
+        modelContext?: ModelContextLike;
+    };
 }
 /**
  * Resolve the page's WebMCP surface; `undefined` on non-supporting browsers.
  * Injectable global scope for tests.
  */
-export declare function resolveModelContext(g?: object): ModelContextLike | undefined;
+export declare function resolveModelContext(scope?: GlobalWithModelContext): ModelContextLike | undefined;
+export {};

package/dist/telemetry-events.d.ts

@@ -81,7 +81,17 @@ export interface ClientContext {
  * even when nobody ever calls `registerTools`: a site that loads the SDK and never
  * registers is a broken integration, and this event is the only way to see it.
  */
-export interface SdkInitEvent extends TelemetryEnvelope {
+/**
+ * Present only when a build sampled the page-level events: the rate this page was kept
+ * at, strictly between 0 and 1. Absent means every such event on the page was sent. A
+ * consumer counting page loads weights each sampled event by `1 / sampleRate`. Not on
+ * the envelope, because `tool_call` never carries it — sampling is per page, and a
+ * tool invocation is not a page-level fact.
+ */
+export interface SampledEvent {
+    sampleRate?: number;
+}
+export interface SdkInitEvent extends TelemetryEnvelope, SampledEvent {
     event: "sdk_init";
     sdk: SdkInfo;
     surface: SurfaceInfo;
@@ -108,6 +118,8 @@ export interface TrackingConfigInfo {
     trackingEnabled: boolean;
     otelEnabled: boolean;
     customEndpoint: boolean;
+    /** `TrackingOptions.builtWith`, verbatim, when set and within its length cap. */
+    builtWith?: string;
 }
 /**
  * One tool in a `tool_registration` batch. The shape metrics are inherited as
@@ -117,6 +129,14 @@ export interface TrackingConfigInfo {
 export interface RegisteredToolEntry extends Partial<ToolShapeMetrics> {
     name: string;
     stableKey: string;
+    /**
+     * The connected platform's own id for this tool, when the host supplied one. Opaque
+     * and optional: a tool declared in a codebase that has never been connected has none,
+     * and its absence is the honest reading rather than a degraded one.
+     */
+    inventoryToolId?: string;
+    /** The contract revision the host believed this tool matched, when it knew one. */
+    contractRevision?: number;
     version?: string;
     schemaHash?: string;
     source?: ToolSource;
@@ -154,7 +174,7 @@ export interface TruncatedTools {
  * outcomes v1 computed and threw away. A site where 3 of 8 tools fail on a
  * duplicate name is the failure mode this event exists to make visible.
  */
-export interface ToolRegistrationEvent extends TelemetryEnvelope {
+export interface ToolRegistrationEvent extends TelemetryEnvelope, SampledEvent {
     event: "tool_registration";
     /** 1-based position of this batch within the page load. */
     registrationIndex: number;
@@ -176,6 +196,10 @@ export type ToolCallOutcome = "success" | "error";
 /** `tool.*` on `tool_call` — identity and the two fields worth joining calls on. */
 export interface ToolCallToolInfo {
     stableKey: string;
+    /** The connected platform's own id, when the host supplied one. See the registration
+     * entry's field of the same name — same value, same optionality, same opacity. */
+    inventoryToolId?: string;
+    contractRevision?: number;
     schemaHash?: string;
     intent?: ToolIntent;
 }

package/dist/telemetry-fields.d.ts

@@ -40,6 +40,7 @@ export declare const TELEMETRY_FIELDS: {
     readonly event: true;
     readonly ts: true;
     readonly sessionId: true;
+    readonly sampleRate: true;
     readonly "sdk.name": true;
     readonly "sdk.version": true;
     readonly "sdk.installMode": true;
@@ -64,6 +65,7 @@ export declare const TELEMETRY_FIELDS: {
     readonly "config.trackingEnabled": true;
     readonly "config.otelEnabled": true;
     readonly "config.customEndpoint": true;
+    readonly "config.builtWith": true;
     readonly tools: true;
     readonly callId: true;
     readonly callIndex: true;
@@ -90,6 +92,8 @@ export declare const TELEMETRY_FIELDS: {
 export declare const TELEMETRY_TOOL_FIELDS: {
     readonly name: true;
     readonly stableKey: true;
+    readonly inventoryToolId: true;
+    readonly contractRevision: true;
     readonly version: true;
     readonly schemaHash: true;
     readonly source: true;

package/dist/telemetry.d.ts

@@ -43,6 +43,22 @@ export declare const SDK_VERSION: string;
  * the overwhelming majority rather than emit a value no consumer can read.
  */
 export declare const SDK_INSTALL_MODE: InstallMode;
+/**
+ * Parse a sampling rate. Anything that is not a number strictly between 0 and 1 means
+ * "send everything": an unset define is how every npm build reaches a page, and a
+ * mistyped one must degrade to complete data rather than to silence.
+ */
+export declare function parseSampleRate(raw: unknown): number;
+/** The rate this build samples page-level events at; `1` sends everything. */
+export declare const SDK_TELEMETRY_SAMPLE_RATE: number;
+/**
+ * Whether this page load is in the sample. Decided from the session id, which every
+ * event on the page shares, so `sdk_init` and the `tool_registration`s beside it are
+ * kept or dropped together — a sampled page is a complete page, never half of one. The
+ * hash is the same FNV-1a the channel already uses for `schemaHash`; its top 32 bits
+ * over 2^32 is a uniform enough coin for a rate that only has to hold on average.
+ */
+export declare function pageSampled(sessionId: string, rate?: number): boolean;
 /**
  * Read a value that may not exist, collapsing both an absent property and a
  * throwing getter to `undefined`. Every browser global this module touches is
@@ -173,6 +189,9 @@ export declare function buildInitEvent(params?: InitEventParams): SdkInitEvent;
 export interface RegisteredTelemetryTool {
     name: string;
     stableKey: string;
+    /** The connected platform's own id for this tool; opaque, copied, never interpreted. */
+    inventoryToolId?: string;
+    contractRevision?: number;
     version?: string;
     description?: string;
     inputSchema?: unknown;
@@ -187,6 +206,12 @@ export interface RegisteredToolParams {
     /** What the surface rejected with; templated into `failureSignature` when `failed`. */
     error?: unknown;
 }
+/**
+ * Cap on `config.builtWith`, in characters. Sized for `<tool>@<semver-with-prerelease>`
+ * with room to spare; it is the one caller-supplied string on `tool_registration`
+ * that is not copied off a tool, so the per-entry byte cap below does not cover it.
+ */
+export declare const MAX_BUILT_WITH_LENGTH = 64;
 /** Where a batch sits in the page load, and what caused it. */
 export interface RegistrationSequence {
     /** 1-based position among the batches this page load reports. */
@@ -278,6 +303,9 @@ export declare function nextCall(stableKey: string, tenantScope?: string): ToolC
 /** What `tool_call` reads off a tool — the two fields worth joining calls on. */
 export interface CalledTelemetryTool {
     stableKey: string;
+    /** The connected platform's own id for this tool; opaque, copied, never interpreted. */
+    inventoryToolId?: string;
+    contractRevision?: number;
     /** Reported as a hash only; the schema itself never leaves the page. */
     inputSchema?: unknown;
     intent?: ToolIntent;
@@ -421,7 +449,7 @@ export declare function telemetryTenantScope(apiKey: unknown): string;
  * global the builders read is guarded individually too; this is the backstop that
  * keeps the guarantee true of assembly as a whole, not of each read in turn.
  */
-export declare function emitTelemetry(build: () => TelemetryEvent, sinks?: TelemetrySinks, fields?: TelemetryFieldMap, toolFields?: TelemetryToolFieldMap): void;
+export declare function emitTelemetry(build: () => TelemetryEvent, sinks?: TelemetrySinks, fields?: TelemetryFieldMap, toolFields?: TelemetryToolFieldMap, sampleRate?: number): void;
 /**
  * Record the `apiKey` of a `registerTools` call so the deferred `sdk_init` flush —
  * which runs with no batch in hand, and may run before any batch exists — can

package/dist/tracking.d.ts

@@ -81,8 +81,39 @@ export declare function getOrCreateSessionId(namespace: string): string;
 export interface TrackingOptions {
     /** Presence (non-empty) enables the backend transport and namespaces storage. */
     apiKey?: string;
+    /**
+     * What generated this integration, as `<tool>[/<path>]@<version>` —
+     * `webmcp-kit/implement@<plugin version>` for the plugin's codegen,
+     * `webmcp-kit/connect-existing-tools@<plugin version>` for its migration of
+     * hand-written tools. Reported once per batch as `config.builtWith` on the
+     * default-on channel so kit-built sites are countable without a Connect; a
+     * hand-written integration leaves it unset. Free text under {@link MAX_BUILT_WITH_LENGTH}
+     * characters; anything else is dropped rather than truncated, because a partial
+     * `<tool>@<vers` is a wrong answer, not a shorter one.
+     */
+    builtWith?: string;
     /** Override the collect endpoint; ignored without `apiKey`. */
     endpoint?: string;
+    /**
+     * Report under a session identity the host already owns, verbatim, instead of
+     * the one this module mints in `sessionStorage`. For a host that is itself the
+     * page's session authority — the CDN snippet, whose tab session predates any
+     * `registerTools` call, or a Journey runner replaying under a synthetic `syn_…`
+     * id — the storage-minted id would split one visit into two sessions the
+     * pipeline cannot rejoin, because it lives in an `apiKey`-derived namespace the
+     * host does not share.
+     *
+     * Supplying it takes this module out of the session business entirely for that
+     * batch: nothing is read from or written to `sessionStorage`, including
+     * `last_seen`, so the 30-minute inactivity boundary is the host's to enforce.
+     * The `visitorId` is unaffected — a different lifetime, still this module's.
+     *
+     * Validated like a stored id ({@link MAX_ID_LENGTH}), because identity fields are
+     * copied onto every event without passing through the truncation ladder: an
+     * empty, oversized or non-string value falls back to the minted session rather
+     * than breaking `boundEventPayload`'s fit guarantee.
+     */
+    sessionId?: string;
     /** Emit each event as an OTEL LogRecord via the global `LoggerProvider`. */
     otel?: boolean;
     /**

package/dist/transport.d.ts

@@ -23,6 +23,11 @@
  * pages that never key the authenticated one, so a keyless send is the normal
  * case, not a failure — the backend attributes those by CORS `Origin` instead.
  *
+ * That path has exactly one observable failure signal, and it is a `console.error`,
+ * never a throw or a retry: a *keyed* beacon whose key the backend cannot resolve
+ * is still recorded (anonymously) and answered `401`, so a site shipping a broken
+ * key is otherwise indistinguishable from a working one. See {@link warnKeyRejected}.
+ *
  * The second, independent output is OTEL (`emitOtelLog`): each event becomes a
  * LogRecord on the global `LoggerProvider` via the optional peer dep
  * `@opentelemetry/api-logs`. The host app owns exporters and processing; a
@@ -65,6 +70,13 @@ export declare function sendToCollect(event: TrackingEvent, config: CollectConfi
  * wire. Note that adding the header makes the request non-simple under CORS, so
  * an authenticated beacon costs a preflight the anonymous one does not.
  *
+ * A `401` on this path means the key that WAS sent resolved to nothing; the beacon
+ * itself was still recorded, anonymously. That is reported through
+ * {@link warnKeyRejected} and nothing else — no throw, no retry, no second send.
+ * The response is only inspected for an authenticated beacon: an anonymous one has
+ * no key to be wrong about, so a `401` there would be a backend fault the developer
+ * can do nothing with, and blaming their key for it is worse than silence.
+ *
  * The event stays a bare `object` here so this module never has to import the
  * assembled shape from `telemetry.ts` (which imports this function).
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nekuda/webmcp-sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Phase-1 WebMCP SDK: a thin wrapper over document.modelContext that plugin-generated code targets — defineTool + register/unregister lifecycle. This package pins the plugin↔SDK seam; anonymous tool-call tracking (backend transport via apiKey, OTEL LogRecords via otel) is opt-in through registerTools and default-silent, while anonymous usage telemetry is a separate unauthenticated channel that is on by default (opt out with telemetry: false).",
   "main": "./dist/index.js",