@agentstats/sdk 0.0.0-stage → 0.4.1

package/dist/index.cjs

@@ -0,0 +1,800 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+//#region src/web.ts
+const VISIT_COOKIE = "_al_v";
+/** What Claude in Chrome puts on the page while it's in control (its stop button). */
+const AGENT_CONTROL_MARKER = "#claude-agent-stop-container";
+const LOCATION_CHANGE = "agentstats:locationchange";
+const PATCHED$1 = Symbol.for("agentstats.patched");
+const FILE_TYPES = [
+	"pdf",
+	"xlsx",
+	"docx",
+	"txt",
+	"rtf",
+	"csv",
+	"exe",
+	"key",
+	"pps",
+	"ppt",
+	"pptx",
+	"7z",
+	"pkg",
+	"rar",
+	"gz",
+	"zip",
+	"avi",
+	"mov",
+	"mp4",
+	"mpeg",
+	"wmv",
+	"midi",
+	"mp3",
+	"wav",
+	"wma",
+	"dmg",
+	"iso",
+	"msi"
+];
+function readCookie(name) {
+	try {
+		return document.cookie.match(new RegExp(`(?:^|; )${name}=([\\w-]{8,64})`))?.[1];
+	} catch {
+		return;
+	}
+}
+/** The AI agent browsing this page, if one is: in control right now (Claude in Chrome), or the browser itself is one. */
+function agentInBrowser() {
+	if (typeof document === "undefined" || typeof navigator === "undefined") return null;
+	if (document.querySelector?.("#claude-agent-stop-container")) return {
+		name: "claude-in-chrome",
+		via: "dom"
+	};
+	const ua = String(navigator.userAgent ?? "");
+	if (/\bClaude\/\d/.test(ua)) return {
+		name: "claude-browser",
+		via: "user-agent"
+	};
+	if (readCookie("_al_v")) return {
+		name: "verified-visit",
+		via: "visit"
+	};
+	if (navigator.webdriver === true || /HeadlessChrome/.test(ua)) return {
+		name: "automation",
+		via: "webdriver"
+	};
+	return null;
+}
+/** Announce client-side navigation as a LOCATION_CHANGE event. History is patched once per page, for every client on it. */
+function watchHistory() {
+	if (typeof history === "undefined") return;
+	for (const m of ["pushState", "replaceState"]) {
+		const original = history[m];
+		if (typeof original !== "function" || original[PATCHED$1]) continue;
+		const patched = function(...args) {
+			const r = original.apply(this, args);
+			window.dispatchEvent(new Event(LOCATION_CHANGE));
+			return r;
+		};
+		Object.defineProperty(patched, PATCHED$1, { value: true });
+		history[m] = patched;
+	}
+}
+/** Start recording pageviews; returns `track()` for custom events. Does nothing outside a browser. */
+function webAnalytics(o) {
+	const noop = {
+		pageview() {},
+		track() {},
+		stop() {}
+	};
+	if (typeof window === "undefined" || typeof document === "undefined") return noop;
+	const log = (...a) => o.debug && console.debug("[agentstats]", ...a);
+	const local = /^localhost$|^127(\.\d+){3}$|^\[::1?\]$|\.local$|^$/.test(location.hostname) || location.protocol === "file:";
+	let ignored = false;
+	try {
+		ignored = localStorage.getItem("agentstats_ignore") === "true";
+	} catch {}
+	const send = (name, props) => {
+		if (ignored) return log("ignored: agentstats_ignore is set");
+		if (local && !o.allowLocalhost) return log("ignored on localhost:", name);
+		const body = JSON.stringify({
+			k: o.key,
+			n: name,
+			u: location.href,
+			r: document.referrer || null,
+			w: window.innerWidth,
+			p: props,
+			a: agentInBrowser()?.name,
+			h: o.hashRouting ? 1 : void 0
+		});
+		log("send", name, props ?? "");
+		try {
+			if (navigator.sendBeacon?.(o.endpoint, body)) return;
+		} catch {}
+		fetch(o.endpoint, {
+			method: "POST",
+			body,
+			keepalive: true,
+			headers: { "Content-Type": "text/plain" }
+		}).catch(() => {});
+	};
+	const ctl = new AbortController();
+	const on = { signal: ctl.signal };
+	let last = "";
+	const pageview = () => {
+		if (ctl.signal.aborted) return;
+		const page = location.pathname + (o.hashRouting ? location.hash : "");
+		if (page === last) return;
+		last = page;
+		send("pageview");
+	};
+	const start = () => {
+		if (document.visibilityState !== "prerender") return pageview();
+		document.addEventListener("visibilitychange", function shown() {
+			if (document.visibilityState === "prerender") return;
+			document.removeEventListener("visibilitychange", shown);
+			pageview();
+		}, on);
+	};
+	start();
+	watchHistory();
+	const nav = () => setTimeout(pageview, 0);
+	window.addEventListener(LOCATION_CHANGE, nav, on);
+	window.addEventListener("popstate", nav, on);
+	if (o.hashRouting) window.addEventListener("hashchange", nav, on);
+	if (o.outboundLinks || o.fileDownloads) {
+		const types = Array.isArray(o.fileDownloads) ? o.fileDownloads : o.fileDownloads ? FILE_TYPES : [];
+		const clicked = (e) => {
+			if (e.type === "auxclick" && e.button !== 1) return;
+			const a = e.target?.closest?.("a[href]");
+			if (!a) return;
+			let url;
+			try {
+				url = new URL(a.href, location.href);
+			} catch {
+				return;
+			}
+			const ext = url.pathname.split(".").pop()?.toLowerCase() ?? "";
+			if (types.includes(ext)) send("File Download", { url: url.href.split("?")[0] });
+			else if (o.outboundLinks && /^https?:$/.test(url.protocol) && url.host !== location.host) send("Outbound Link: Click", { url: url.href.split("?")[0] });
+		};
+		document.addEventListener("click", clicked, {
+			capture: true,
+			signal: ctl.signal
+		});
+		document.addEventListener("auxclick", clicked, {
+			capture: true,
+			signal: ctl.signal
+		});
+	}
+	return {
+		pageview,
+		track: (name, props) => send(String(name), props),
+		stop: () => ctl.abort()
+	};
+}
+//#endregion
+//#region src/index.ts
+/**
+* AgentStats SDK — analytics for WebMCP tool calls, and for the people visiting the site.
+*
+* Works in any framework: it patches `document.modelContext.registerTool`
+* (and legacy `provideContext` / `unregisterTool` / `clearContext`) so every
+* tool registered *after* `init()` is instrumented automatically. Tools you
+* register yourself can also be wrapped explicitly with `wrap()`.
+*
+* It also records pageviews (Visitors, see ./web.ts): no cookies, no personal data. Turn that
+* off with `trackPageviews: false`.
+*/
+const SDK_VERSION = "0.4.1";
+const MAX_ARG_BYTES = 8192;
+const MAX_RESULT_CHARS = 2048;
+function uuid() {
+	const c = globalThis.crypto;
+	if (c?.randomUUID) return c.randomUUID();
+	return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (ch) => {
+		const r = Math.random() * 16 | 0;
+		return (ch === "x" ? r : r & 3 | 8).toString(16);
+	});
+}
+function now() {
+	return Date.now();
+}
+function perfNow() {
+	return typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+}
+function isAbortError(err) {
+	return !!err && typeof err === "object" && err.name === "AbortError";
+}
+function redact(value, keys, depth = 0) {
+	if (depth > 6) return "[depth]";
+	if (Array.isArray(value)) return value.slice(0, 100).map((v) => redact(v, keys, depth + 1));
+	if (value && typeof value === "object") {
+		const out = {};
+		for (const [k, v] of Object.entries(value)) {
+			const lk = k.toLowerCase();
+			out[k] = keys.some((rk) => lk.includes(rk)) ? "[redacted]" : redact(v, keys, depth + 1);
+		}
+		return out;
+	}
+	if (typeof value === "string" && value.length > 1e3) return value.slice(0, 1e3) + "…";
+	return value;
+}
+function safeStringify(value, max) {
+	let s;
+	try {
+		s = typeof value === "string" ? value : JSON.stringify(value);
+	} catch {
+		s = String(value);
+	}
+	if (s === void 0) s = "";
+	return s.length > max ? s.slice(0, max) + "…" : s;
+}
+function byteSize(value) {
+	try {
+		return JSON.stringify(value)?.length ?? 0;
+	} catch {
+		return 0;
+	}
+}
+function toDescriptor(tool) {
+	const d = { name: String(tool.name ?? "") };
+	if (tool.title) d.title = String(tool.title);
+	if (tool.description) d.description = String(tool.description);
+	if (tool.inputSchema !== void 0) d.inputSchema = tool.inputSchema;
+	if (tool.annotations) d.annotations = { ...tool.annotations };
+	if (tool.origin) d.origin = String(tool.origin);
+	return d;
+}
+function detectEndpoint() {
+	if (typeof document !== "undefined") {
+		const cs = document.currentScript;
+		if (cs?.src) try {
+			return new URL("/api/ingest", cs.src).toString();
+		} catch {}
+	}
+	return "https://agentstats.io/api/ingest";
+}
+const AI_REFERRER = /(^|\.)(chatgpt\.com|chat\.openai\.com|perplexity\.ai|claude\.ai|gemini\.google\.com|bard\.google\.com|copilot\.microsoft\.com|copilot\.cloud\.microsoft|copilot\.com|meta\.ai|deepseek\.com|grok\.com|chat\.mistral\.ai|you\.com|phind\.com|poe\.com|duck\.ai|chat\.qwen\.ai|kimi\.com|kimi\.ai|doubao\.com)$/i;
+const AI_UTM = /[?&]utm_source=(chatgpt(\.com)?|openai|perplexity(\.ai)?|claude(\.ai)?|gemini|copilot(\.com)?|meta\.?ai|deepseek|grok|mistral|le-?chat)(&|$)/i;
+const PATCHED = Symbol.for("agentstats.patched");
+const WRAPPED = Symbol.for("agentstats.wrapped");
+var AgentStatsClient = class {
+	constructor(opts) {
+		this.queue = [];
+		this.timer = null;
+		this.snapshotTimer = null;
+		this.pollTimer = null;
+		this.sessionId = "";
+		this.lastActivity = 0;
+		this.lastSnapshotHash = "";
+		this.inflight = Promise.resolve();
+		this.web = null;
+		this.agentPage = "";
+		this.controlStarted = 0;
+		if (!opts || !opts.key) throw new Error("[agentstats] `key` is required");
+		this.options = {
+			endpoint: detectEndpoint(),
+			captureArgs: true,
+			captureResults: false,
+			captureErrors: true,
+			redactKeys: [],
+			sessionTimeoutMs: 18e5,
+			flushIntervalMs: 2e3,
+			maxBatchSize: 25,
+			autoInstrument: true,
+			trackAgentBrowsers: true,
+			trackPageviews: true,
+			debug: false,
+			disabled: false,
+			...Object.fromEntries(Object.entries(opts).filter(([, v]) => v !== void 0))
+		};
+		this._fetch = opts.fetch ?? (typeof fetch !== "undefined" ? fetch.bind(globalThis) : (() => Promise.reject(/* @__PURE__ */ new Error("no fetch"))));
+		this.sessionId = this.loadSession();
+		if (!this.options.disabled) {
+			if (this.options.autoInstrument) this.instrument();
+			this.bindLifecycle();
+			this.reportReferral();
+			if (this.options.trackAgentBrowsers) this.watchAgentBrowsers();
+			if (this.options.trackPageviews) {
+				const o = this.options;
+				this.web = webAnalytics({
+					key: o.key,
+					endpoint: `${o.endpoint.replace(/\/+$/, "")}/web`,
+					hashRouting: o.hashRouting,
+					outboundLinks: o.outboundLinks,
+					fileDownloads: o.fileDownloads,
+					allowLocalhost: o.allowLocalhost,
+					debug: o.debug
+				});
+			}
+		}
+		this.log("initialised", {
+			endpoint: this.options.endpoint,
+			session: this.sessionId
+		});
+	}
+	/** Wrap a WebMCP tool definition so its `execute` is tracked. Safe to call on already-wrapped tools. */
+	wrap(tool) {
+		if (!tool || typeof tool.execute !== "function") return tool;
+		if (tool[WRAPPED]) return tool;
+		const original = tool.execute;
+		const name = String(tool.name);
+		const client = this;
+		const wrapped = async function(input, options) {
+			const start = perfNow();
+			const signal = options?.signal;
+			try {
+				const result = await original.call(this, input, options);
+				client.recordCall(name, "success", perfNow() - start, input, result, void 0, signal);
+				return result;
+			} catch (err) {
+				const cancelled = signal?.aborted || isAbortError(err);
+				client.recordCall(name, cancelled ? "cancelled" : "error", perfNow() - start, input, void 0, err, signal);
+				throw err;
+			}
+		};
+		Object.defineProperty(wrapped, WRAPPED, { value: true });
+		const out = Object.assign({}, tool, { execute: wrapped });
+		Object.defineProperty(out, WRAPPED, { value: true });
+		return out;
+	}
+	/**
+	* Track a custom event (e.g. a conversion). It counts for the agent session it happens in, and
+	* as a goal in Visitors when a person does it (string, number and boolean props only there).
+	*/
+	track(name, props) {
+		const clean = props ? redact(props, this.redactKeys()) : void 0;
+		this.enqueue({
+			type: "custom",
+			id: uuid(),
+			ts: now(),
+			name,
+			props: clean,
+			url: this.url()
+		});
+		this.web?.track(name, clean);
+	}
+	/** Record a pageview now, e.g. after a client-side navigation the SDK can't see. Pageviews are otherwise automatic. */
+	pageview() {
+		this.web?.pageview();
+	}
+	/** Take a snapshot of the currently registered tools now (also happens automatically). */
+	async snapshot() {
+		const mc = this.modelContext();
+		if (!mc?.getTools) return [];
+		let tools = [];
+		try {
+			tools = (await mc.getTools() ?? []).map((t) => toDescriptor(t));
+		} catch (err) {
+			this.log("getTools failed", err);
+			return [];
+		}
+		const hash = safeStringify(tools.map((t) => [
+			t.name,
+			t.description,
+			t.inputSchema,
+			t.annotations
+		]), 1e7);
+		if (hash !== this.lastSnapshotHash) {
+			this.lastSnapshotHash = hash;
+			this.enqueue({
+				type: "tools_snapshot",
+				id: uuid(),
+				ts: now(),
+				tools,
+				url: this.url()
+			});
+		}
+		return tools;
+	}
+	/** Send everything queued right now. */
+	flush(useBeacon = false) {
+		if (this.timer) {
+			clearTimeout(this.timer);
+			this.timer = null;
+		}
+		if (!this.queue.length) return this.inflight;
+		const events = this.queue.splice(0, this.queue.length);
+		const payload = {
+			key: this.options.key,
+			sdk: `js/${SDK_VERSION}`,
+			session_id: this.sessionId,
+			sent_at: now(),
+			metadata: this.options.metadata,
+			visit: typeof document !== "undefined" ? readCookie(VISIT_COOKIE) : void 0,
+			client: this.clientHints(),
+			events
+		};
+		const body = JSON.stringify(payload);
+		this.log("flush", events.length, "events");
+		if (useBeacon && typeof navigator !== "undefined" && navigator.sendBeacon) try {
+			if (navigator.sendBeacon(this.options.endpoint, new Blob([body], { type: "text/plain" }))) return Promise.resolve();
+		} catch {}
+		const p = this._fetch(this.options.endpoint, {
+			method: "POST",
+			body,
+			keepalive: true,
+			headers: { "Content-Type": "text/plain" }
+		}).then(async (res) => {
+			if (!res.ok) this.log("ingest responded", res.status);
+		}).catch((err) => {
+			this.log("ingest failed", err);
+		});
+		this.inflight = p;
+		return p;
+	}
+	/** Remove patches and stop timers. */
+	destroy() {
+		if (this.timer) clearTimeout(this.timer);
+		if (this.snapshotTimer) clearTimeout(this.snapshotTimer);
+		if (this.pollTimer) clearInterval(this.pollTimer);
+		this.timer = this.snapshotTimer = this.pollTimer = null;
+		this.web?.stop();
+		this.web = null;
+	}
+	get session() {
+		return this.sessionId;
+	}
+	log(...args) {
+		if (this.options.debug) console.debug("[agentstats]", ...args);
+	}
+	url() {
+		return typeof location !== "undefined" ? location.href : void 0;
+	}
+	redactKeys() {
+		return (this.options.redactKeys ?? []).map((k) => k.toLowerCase()).filter(Boolean);
+	}
+	modelContext() {
+		const g = globalThis;
+		return g.document?.modelContext ?? g.navigator?.modelContext;
+	}
+	captureArgs(tool, input) {
+		const c = this.options.captureArgs;
+		if (c === false) return void 0;
+		let v = typeof c === "function" ? this.callOption("captureArgs", () => c(tool, input)) : redact(input, this.redactKeys());
+		if (v !== void 0 && byteSize(v) > MAX_ARG_BYTES) v = {
+			_truncated: true,
+			preview: safeStringify(v, 1e3)
+		};
+		return v;
+	}
+	captureResult(tool, result) {
+		const c = this.options.captureResults;
+		if (!c || result === void 0) return void 0;
+		const v = typeof c === "function" ? this.callOption("captureResults", () => c(tool, result)) : result;
+		return v === void 0 ? void 0 : safeStringify(v, MAX_RESULT_CHARS);
+	}
+	captureError(tool, err) {
+		const c = this.options.captureErrors;
+		if (c === false) return void 0;
+		const e = err;
+		const message = typeof e?.message === "string" ? e.message : safeStringify(err, 1e3);
+		if (typeof c !== "function") return safeStringify(message, 1e3);
+		const code = typeof e?.code === "string" || typeof e?.code === "number" ? e.code : null;
+		const out = this.callOption("captureErrors", () => c({
+			tool,
+			message,
+			name: typeof e?.name === "string" ? e.name : null,
+			code,
+			error: err
+		}));
+		return typeof out === "string" && out ? safeStringify(out, 1e3) : void 0;
+	}
+	/** Runs a user-supplied capture function. One that throws keeps nothing rather than breaking the tool call. */
+	callOption(option, fn) {
+		try {
+			return fn();
+		} catch (err) {
+			this.log(`${option} threw`, err);
+			return;
+		}
+	}
+	recordCall(tool, status, duration, input, result, err, _signal) {
+		const ev = {
+			type: "tool_call",
+			id: uuid(),
+			ts: now(),
+			tool,
+			status,
+			duration_ms: Math.round(duration * 100) / 100,
+			url: this.url()
+		};
+		const args = this.captureArgs(tool, input);
+		if (args !== void 0) ev.args = args;
+		const res = this.captureResult(tool, result);
+		if (res !== void 0) ev.result = res;
+		if (err !== void 0) {
+			const message = this.captureError(tool, err);
+			if (message !== void 0) ev.error = message;
+			const name = err?.name;
+			if (name) ev.error_name = String(name).slice(0, 100);
+		}
+		this.enqueue(ev);
+	}
+	enqueue(ev) {
+		if (this.options.disabled) return;
+		this.touchSession();
+		this.queue.push(ev);
+		this.log("event", ev.type, ev.tool ?? ev.name ?? "");
+		if (this.queue.length >= this.options.maxBatchSize) this.flush();
+		else if (!this.timer) this.timer = setTimeout(() => void this.flush(), this.options.flushIntervalMs);
+	}
+	scheduleSnapshot(delay = 250) {
+		if (this.snapshotTimer) clearTimeout(this.snapshotTimer);
+		this.snapshotTimer = setTimeout(() => {
+			this.snapshotTimer = null;
+			this.snapshot();
+		}, delay);
+	}
+	instrument() {
+		const tryPatch = () => {
+			const mc = this.modelContext();
+			if (!mc) return false;
+			this.patch(mc);
+			return true;
+		};
+		if (tryPatch()) return;
+		let attempts = 0;
+		this.pollTimer = setInterval(() => {
+			attempts++;
+			if (tryPatch() || attempts > 40) {
+				if (this.pollTimer) clearInterval(this.pollTimer);
+				this.pollTimer = null;
+			}
+		}, 250);
+	}
+	patch(mc) {
+		if (mc[PATCHED]) {
+			this.log("modelContext already patched");
+			this.scheduleSnapshot(0);
+			return;
+		}
+		Object.defineProperty(mc, PATCHED, { value: true });
+		const client = this;
+		if (typeof mc.registerTool === "function") {
+			const orig = mc.registerTool;
+			mc.registerTool = function(tool, options) {
+				const wrapped = client.wrap(tool);
+				client.enqueue({
+					type: "tool_registered",
+					id: uuid(),
+					ts: now(),
+					tool: String(tool?.name),
+					descriptor: toDescriptor(tool),
+					url: client.url()
+				});
+				client.scheduleSnapshot();
+				return orig.call(this, wrapped, options);
+			};
+		}
+		if (typeof mc.provideContext === "function") {
+			const orig = mc.provideContext;
+			mc.provideContext = function(ctx) {
+				const tools = (ctx?.tools ?? []).map((t) => {
+					client.enqueue({
+						type: "tool_registered",
+						id: uuid(),
+						ts: now(),
+						tool: String(t?.name),
+						descriptor: toDescriptor(t),
+						url: client.url()
+					});
+					return client.wrap(t);
+				});
+				client.scheduleSnapshot();
+				return orig.call(this, {
+					...ctx,
+					tools
+				});
+			};
+		}
+		if (typeof mc.unregisterTool === "function") {
+			const orig = mc.unregisterTool;
+			mc.unregisterTool = function(name) {
+				client.enqueue({
+					type: "tool_unregistered",
+					id: uuid(),
+					ts: now(),
+					tool: String(name),
+					url: client.url()
+				});
+				client.scheduleSnapshot();
+				return orig.call(this, name);
+			};
+		}
+		if (typeof mc.clearContext === "function") {
+			const orig = mc.clearContext;
+			mc.clearContext = function() {
+				client.scheduleSnapshot();
+				return orig.call(this);
+			};
+		}
+		if (typeof mc.addEventListener === "function") try {
+			mc.addEventListener("toolchange", () => client.scheduleSnapshot());
+		} catch {}
+		this.log("modelContext patched");
+		this.scheduleSnapshot(0);
+	}
+	bindLifecycle() {
+		if (typeof window === "undefined" || typeof window.addEventListener !== "function") return;
+		const onHide = () => void this.flush(true);
+		window.addEventListener("pagehide", onHide);
+		document.addEventListener("visibilitychange", () => {
+			if (document.visibilityState === "hidden") onHide();
+		});
+	}
+	/** User agent + webdriver flag, so a session can be attributed to an agent that browses with a real browser. */
+	clientHints() {
+		if (typeof navigator === "undefined") return void 0;
+		const ua = String(navigator.userAgent ?? "").slice(0, 1e3);
+		const webdriver = navigator.webdriver === true;
+		return ua || webdriver ? {
+			ua: ua || void 0,
+			webdriver: webdriver || void 0
+		} : void 0;
+	}
+	/** The agent browsing this page, if one is: in control right now (Claude in Chrome), or the browser itself is one. */
+	detectAgentBrowser() {
+		return agentInBrowser();
+	}
+	/** Record agent page views (on load and on client-side navigation) and Claude in Chrome taking and giving back control. */
+	watchAgentBrowsers() {
+		if (typeof document === "undefined" || typeof window === "undefined") return;
+		const pageview = () => {
+			const agent = this.detectAgentBrowser();
+			const url = this.url();
+			if (!agent || url === this.agentPage) return;
+			this.agentPage = url ?? "";
+			this.enqueue({
+				type: "agent_pageview",
+				id: uuid(),
+				ts: now(),
+				name: agent.name,
+				props: { via: agent.via },
+				url
+			});
+		};
+		const ready = () => {
+			pageview();
+			if (typeof MutationObserver === "undefined" || !document.body) return;
+			new MutationObserver(() => {
+				const active = !!document.querySelector(AGENT_CONTROL_MARKER);
+				if (active && !this.controlStarted) {
+					this.controlStarted = perfNow();
+					this.enqueue({
+						type: "agent_control",
+						id: uuid(),
+						ts: now(),
+						name: "claude-in-chrome",
+						props: {
+							via: "dom",
+							phase: "start"
+						},
+						url: this.url()
+					});
+					pageview();
+				} else if (!active && this.controlStarted) {
+					const duration = Math.round(perfNow() - this.controlStarted);
+					this.controlStarted = 0;
+					this.enqueue({
+						type: "agent_control",
+						id: uuid(),
+						ts: now(),
+						name: "claude-in-chrome",
+						props: {
+							via: "dom",
+							phase: "stop",
+							duration_ms: duration
+						},
+						url: this.url()
+					});
+				}
+			}).observe(document.body, { childList: true });
+		};
+		if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", ready, { once: true });
+		else ready();
+		const nav = () => setTimeout(pageview, 0);
+		window.addEventListener("popstate", nav);
+		window.addEventListener(LOCATION_CHANGE, nav);
+		watchHistory();
+	}
+	/** If this page was reached from an AI assistant, tell the server once per session. */
+	reportReferral() {
+		if (typeof document === "undefined" || typeof location === "undefined") return;
+		let refHost = "";
+		try {
+			refHost = document.referrer ? new URL(document.referrer).hostname.replace(/^www\./, "") : "";
+		} catch {}
+		if (!(refHost && AI_REFERRER.test(refHost)) && !AI_UTM.test(location.search)) return;
+		const flag = `__agentstats_ref_${this.sessionId}`;
+		try {
+			if (sessionStorage.getItem(flag)) return;
+			sessionStorage.setItem(flag, "1");
+		} catch {}
+		this.enqueue({
+			type: "referral",
+			id: uuid(),
+			ts: now(),
+			url: this.url() ?? location.href,
+			referrer: refHost ? `https://${refHost}/` : null
+		});
+	}
+	loadSession() {
+		try {
+			const raw = sessionStorage.getItem("__agentstats_session");
+			if (raw) {
+				const parsed = JSON.parse(raw);
+				if (parsed?.id && now() - parsed.last < this.options.sessionTimeoutMs) {
+					this.lastActivity = parsed.last;
+					return parsed.id;
+				}
+			}
+		} catch {}
+		return uuid();
+	}
+	touchSession() {
+		const t = now();
+		if (this.lastActivity && t - this.lastActivity > this.options.sessionTimeoutMs) {
+			this.sessionId = uuid();
+			this.lastSnapshotHash = "";
+			this.log("new session", this.sessionId);
+		}
+		this.lastActivity = t;
+		try {
+			sessionStorage.setItem("__agentstats_session", JSON.stringify({
+				id: this.sessionId,
+				last: t
+			}));
+		} catch {}
+	}
+};
+let instance = null;
+/** Initialise AgentStats. Call once, as early as possible (before registering tools). */
+function init(options) {
+	if (instance) instance.destroy();
+	instance = new AgentStatsClient(options);
+	return instance;
+}
+function getClient() {
+	return instance;
+}
+function track(name, props) {
+	instance?.track(name, props);
+}
+function wrap(tool) {
+	return instance ? instance.wrap(tool) : tool;
+}
+function flush() {
+	return instance?.flush() ?? Promise.resolve();
+}
+function snapshot() {
+	return instance?.snapshot() ?? Promise.resolve([]);
+}
+function pageview() {
+	instance?.pageview();
+}
+const AgentStats = {
+	init,
+	track,
+	pageview,
+	wrap,
+	flush,
+	snapshot,
+	getClient,
+	version: SDK_VERSION
+};
+//#endregion
+exports.AgentStats = AgentStats;
+exports.default = AgentStats;
+exports.AgentStatsClient = AgentStatsClient;
+exports.SDK_VERSION = SDK_VERSION;
+exports.flush = flush;
+exports.getClient = getClient;
+exports.init = init;
+exports.pageview = pageview;
+exports.snapshot = snapshot;
+exports.track = track;
+exports.wrap = wrap;