@nekuda/webmcp-sdk 0.4.0-dev.7.3

package/dist/register.d.ts

@@ -0,0 +1,80 @@
+import type { AnyWebMCPTool } from "./define.js";
+import { type ModelContextLike } from "./spec.js";
+import { type TrackingOptions } from "./tracking.js";
+/**
+ * Per-tool outcome of a `registerTools` call:
+ *   - `registered`   — live on the page's WebMCP surface
+ *   - `unsupported`  — this browser has no WebMCP surface; nothing was registered
+ *   - `aborted`      — the registration's lifetime ended before/while registering
+ *   - `failed`       — the native surface rejected (e.g. duplicate name)
+ */
+export type ToolRegistrationState = "registered" | "unsupported" | "aborted" | "failed";
+export interface ToolRegistrationResult {
+    stableKey: string;
+    name: string;
+    state: ToolRegistrationState;
+    error?: unknown;
+}
+export interface RegisterToolsOptions {
+    /**
+     * External lifetime for the registration (e.g. a component's unmount signal).
+     * Aborting it unregisters every tool in this batch, same as `unregister()`.
+     */
+    signal?: AbortSignal;
+    /** Injectable surface for tests; defaults to the page's `document.modelContext`. */
+    modelContext?: ModelContextLike;
+    /**
+     * Configures anonymous tool-call tracking for this batch. Default-silent: with
+     * neither `apiKey` nor `otel` set — including an empty `tracking: {}` — nothing
+     * is built at all, so omitting it means zero tracking and no behavior change.
+     * Once an output is enabled, each tool invocation emits a `tool_call_request`
+     * event before its handler runs and a `tool_call_response` event after.
+     * `disabled: true` is this channel's consent gate; it does not narrow the
+     * default-on telemetry channel below, which resolves no identity and touches no
+     * storage. An `apiKey` set here is also sent as `x-api-key` on that channel's
+     * beacons, which only attributes them to this tenant.
+     */
+    tracking?: TrackingOptions;
+    /**
+     * Opt out of the default-on usage telemetry (`src/telemetry.ts`): `telemetry: false`
+     * means no `tool_registration` and no `tool_call` for this batch, and it cancels the
+     * page's one `sdk_init` outright — that event describes the page load, so it is
+     * cancelled page-wide and irreversibly. Unlike `tracking` this channel needs no
+     * `apiKey`.
+     *
+     * The other two events are per-batch, so the option is read per call: a *later*
+     * `registerTools` that omits it reports its own batch and calls. Cancelling
+     * `sdk_init` also requires winning the race with its deferred flush — a batch
+     * registered at module scope does, one registered from a mount effect or a consent
+     * callback may not. A site that wants the whole page silent regardless of where its
+     * `registerTools` calls come from (generated code, a CDN snippet) should use a
+     * page-level lever instead: `globalThis.__WEBMCP_TELEMETRY__ = false` — strictly
+     * `false`, so a truthy `"0"` does not opt out — or Global Privacy Control
+     * (`navigator.globalPrivacyControl === true`), both of which are read at emit time
+     * and so cover every event. With no `document` in scope the channel is silent
+     * anyway, so SSR never beacons.
+     */
+    telemetry?: boolean;
+}
+export interface ToolRegistration {
+    /**
+     * Settles when every tool's native registration settles. Never rejects — per-tool
+     * outcomes (including failures) are reported in the results, so one bad tool
+     * cannot mask the rest.
+     */
+    ready: Promise<ToolRegistrationResult[]>;
+    /** Unregister every tool in this batch. Idempotent. */
+    unregister(): void;
+    /** The signal carrying this registration's lifetime (aborted once unregistered). */
+    signal: AbortSignal;
+}
+/**
+ * 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.
+ */
+export declare function registerTools(tools: readonly AnyWebMCPTool[], options?: RegisterToolsOptions): ToolRegistration;

package/dist/spec.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The pinned WebMCP spec surface — the ONLY module that knows the raw browser API.
+ *
+ * Pinned against the WebMCP editor's draft as of 2026-07
+ * (https://webmachinelearning.github.io/webmcp/):
+ *
+ *   - `document.modelContext` is the surface (Chrome 150+). `navigator.modelContext`
+ *     is deprecated but is the only surface on Chrome 149, so resolution reads
+ *     `document` first and falls back — `??` picks exactly one object, so a browser
+ *     exposing both never double-registers.
+ *   - `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.
+ *   - Tool names: 1–128 chars of [A-Za-z0-9_\-.].
+ *   - `annotations.readOnlyHint` / `annotations.untrustedContentHint`.
+ *
+ * The draft breaks monthly; absorbing that churn is this module's job (R23). All
+ * other modules — and all plugin-generated code — target `ModelContextLike`, never
+ * the raw API.
+ */
+export interface ToolAnnotations {
+    /** The tool does not modify page or user state. */
+    readOnlyHint?: boolean;
+    /** The tool's output can contain untrusted (user or third-party) data. */
+    untrustedContentHint?: boolean;
+}
+/** The tool shape `registerTool` accepts (`ModelContextTool` in the draft IDL). */
+export interface SpecTool {
+    name: string;
+    title?: string;
+    description: string;
+    inputSchema?: Record<string, unknown>;
+    annotations?: ToolAnnotations;
+    execute(input: Record<string, unknown>): Promise<unknown>;
+}
+export interface RegisterToolOptions {
+    /** Aborting unregisters the tool — the spec's only unregistration mechanism. */
+    signal?: AbortSignal;
+}
+/**
+ * The slice of the native surface the SDK uses, typed to the draft contract:
+ * `registerTool` returns a promise. Pre-draft surfaces that return nothing are a
+ * runtime concern only — the SDK normalizes via `Promise.resolve` at the call
+ * site, never by widening this type.
+ */
+export interface ModelContextLike {
+    registerTool(tool: SpecTool, options?: RegisterToolOptions): Promise<void>;
+}
+/**
+ * Resolve the page's WebMCP surface; `undefined` on non-supporting browsers.
+ * Injectable global scope for tests.
+ */
+export declare function resolveModelContext(g?: object): ModelContextLike | undefined;

package/dist/telemetry-context.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Derived page and client context for the telemetry events (`src/telemetry.ts`):
+ * a route *template* instead of a URL, a referrer *class* instead of a referrer,
+ * a form factor instead of a screen size, a language subtag instead of a locale.
+ * Every function here exists so the event can carry the signal without carrying
+ * the identifying string it was derived from — no `url`, `referrer`, `title`,
+ * `screen`, or full UA string ever leaves the page. It also holds what the events
+ * report about the page's WebMCP surface, the navigation clock, and the in-memory
+ * session ID that joins them.
+ *
+ * Two properties hold throughout. First, nothing throws: every browser global is
+ * optional in a non-DOM runtime and page-script- and extension-writable in a real
+ * one, so each read goes through a guard and an unreadable value simply means the
+ * field is **omitted** — never sent as `null`. Second, every input is bounded:
+ * a pathname, referrer, or UA string is caller-controlled, and the truncation
+ * ladder in `src/tracking.ts` does not reach a derived field, so the cap has to
+ * happen here.
+ */
+/**
+ * Prefix of a page-controlled string any derived field will even look at: a
+ * pathname, a referrer, an error message. All come from values page script can set
+ * to a megabyte-long one, and a regex scan over that is main-thread cost on the
+ * tool-call path. Real URLs and messages live well under 2 KB.
+ *
+ * What slicing first costs: templating only ever shortens and never moves a
+ * character earlier, so the *first* bytes of a derived value are unaffected — this
+ * prefix is an order of magnitude above every output cap ({@link MAX_ROUTE_BYTES},
+ * `MAX_ERROR_SIGNATURE_BYTES`). What it does drop is the tail of an input whose
+ * middle would have collapsed to nothing: a message that is two megabytes of digits
+ * between `order ` and ` not found` clusters as `order *`, without the trailing
+ * words. That is the accepted trade — the alternative is scanning a page-controlled
+ * megabyte on the tool-call path.
+ */
+export declare const MAX_INPUT_CHARS = 4096;
+/**
+ * Whether a run reads as an opaque blob rather than as words. Shared with
+ * `errorSignature` in `src/telemetry.ts`, which needs the same distinction on a
+ * message's long runs; it lives here because this module is the leaf of the two.
+ *
+ * Counted by index rather than by code point so the share is measured against the
+ * same unit as `length` — a route segment can hold any Unicode, and only ASCII
+ * capitals are evidence of an encoding.
+ */
+export declare function uppercaseHeavy(run: string): boolean;
+/**
+ * A `location.pathname` reduced to a low-cardinality route template
+ * (`/products/12345` → `/products/:id`). Query and fragment are dropped whole —
+ * they carry search terms, session tokens, and ad parameters. A non-string
+ * pathname is omitted; any string yields a rooted template, so the root path is
+ * `"/"`.
+ */
+export declare function routeTemplate(pathname?: unknown): string | undefined;
+/**
+ * Non-empty segments in a pathname, emitted alongside {@link routeTemplate}. It
+ * is the check on the templating: a route reported as `/` with a segment count of
+ * 4, or a count above {@link MAX_ROUTE_SEGMENTS}, says the template lost
+ * something — which is invisible from the template alone.
+ */
+export declare function segmentCount(pathname?: unknown): number | undefined;
+/** How the visitor arrived, as a class rather than a referrer URL. */
+export type ReferrerClass = "internal" | "ai_assistant" | "search" | "social" | "direct" | "other";
+/**
+ * Classify `document.referrer` against the page's own origin. An empty referrer
+ * is `direct` — that is what a typed URL, a bookmark, and a stripped
+ * cross-origin referrer all look like. An unparseable one is `other`, since it
+ * was *something*; conflating it with `direct` would inflate the direct bucket.
+ */
+export declare function referrerClass(referrer?: unknown, origin?: unknown): ReferrerClass;
+/** Device class, at the only granularity that stays non-identifying. */
+export type FormFactor = "mobile" | "desktop";
+/**
+ * Mobile vs desktop, from the narrowest signal that answers it: UA-Client-Hints
+ * `mobile` is a boolean the browser computes and survives UA reduction, so it
+ * wins; a coarse pointer with no hover is the CSS-level answer for browsers
+ * without UA-CH; screen width is the last resort, and the only one a desktop
+ * window resize can fool. Omitted when none of the three is readable.
+ */
+export declare function formFactor(scope?: object): FormFactor | undefined;
+/**
+ * The primary language subtag only (`en`, not `en-US`). The region half is a
+ * coarse location signal and adds nothing to the "what language do these tools
+ * get called in" question. An unrecognized tag (`x-private`, `""`) is omitted.
+ */
+export declare function languageSubtag(scope?: object): string | undefined;
+/** What is driving the page, as far as the page can tell. */
+export type AgentRuntime = "chatgpt" | "claude" | "perplexity" | "headless" | "browser" | "unknown";
+/**
+ * Best-effort runtime identification. Deliberately weak, and known to be: real
+ * AI crawlers fetch server-side and never run this code, so the browser almost
+ * always sees `browser` or `headless`. The edge is authoritative — it reads the
+ * beacon's own `User-Agent` header, which no body field may carry. The one signal
+ * only the client has is `navigator.webdriver`, folded into `headless` here.
+ *
+ * `unknown` rather than omitted when there is no UA at all: "we looked and could
+ * not tell" is a different fact from "this field was not collected".
+ */
+export declare function agentRuntime(scope?: object): AgentRuntime;
+/** Whether the SDK is running in the top-level document or inside a frame. */
+export type FrameContext = "top" | "iframe";
+/**
+ * Top document or embedded frame. Reading `top` from a cross-origin frame can
+ * throw, and the throw *is* the answer: only an embedded document can be denied
+ * access to its own top. Omitted when there is no `self` to compare against,
+ * which means no browser at all.
+ */
+export declare function frameContext(scope?: object): FrameContext | undefined;
+/** `document.visibilityState`, restricted to the values the spec defines. */
+export type PageVisibility = "visible" | "hidden" | "prerender";
+/**
+ * Whether the page was in the foreground when the event was assembled — a
+ * prerendered or background page is where "the SDK loaded but nothing happened"
+ * comes from. An unrecognized state is omitted rather than coerced.
+ */
+export declare function visibility(scope?: object): PageVisibility | undefined;
+/** Where the page's WebMCP surface came from. */
+export type SurfaceProvenance = "native" | "polyfill" | "extension" | "none";
+/** Which global carries the surface — the spec's own, or its deprecated predecessor. */
+export type SurfaceGlobal = "document.modelContext" | "navigator.modelContext";
+/** What `sdk_init` reports about the WebMCP surface it found (or didn't). */
+export interface SurfaceInfo {
+    available: boolean;
+    provenance: SurfaceProvenance;
+    /** Absent when no surface was found. */
+    global?: SurfaceGlobal;
+    /** Absent unless the surface declares one. */
+    specVersion?: string;
+}
+/**
+ * The WebMCP surface as `registerTools` sees it. Availability comes from
+ * {@link resolveModelContext} itself rather than a second lookup, so what this
+ * event reports can never disagree with what registration actually used — the
+ * `document`-first, `navigator`-fallback precedence lives in exactly one place
+ * (`src/spec.ts`), and a browser exposing both is reported as the one that wins.
+ *
+ * A surface that is present but not the native API is worth separating: a
+ * polyfill's failure modes are its own, and an extension-injected surface means
+ * tools registered on a browser that has no WebMCP of its own.
+ */
+export declare function surfaceInfo(scope?: object): SurfaceInfo;
+/**
+ * Milliseconds from navigation start to now, the basis of `timeToInitMs` and
+ * `timeSinceInitMs`. `performance.now()` is already relative to
+ * `performance.timeOrigin` and monotonic, so it is the primary reading;
+ * `Date.now() - timeOrigin` is the fallback for a surface that exposes the origin
+ * but not a usable clock. `undefined` when neither is usable — a shimmed `now()`
+ * returning `NaN` or a negative value must not become a nonsense duration on the
+ * event.
+ */
+export declare function timeSinceNavigation(scope?: object): number | undefined;
+/**
+ * The init mark itself, reported as `sdk_init.timeToInitMs`. Deliberately not
+ * scope-injectable: reading it fresh when the deferred flush assembles the event
+ * would measure the flush hop instead of module load, and the three events would
+ * no longer share one baseline.
+ */
+export declare function initAt(): number | undefined;
+/**
+ * Milliseconds from SDK init to now. Both readings are navigation-relative, so
+ * their difference is the page time elapsed between them. Clamped at `0`: a
+ * shimmed clock that runs backwards must not report a negative age.
+ */
+export declare function timeSinceInit(scope?: object): number | undefined;
+/** The in-memory session ID for this module instance; see {@link SESSION_ID}. */
+export declare function sessionId(): string;

package/dist/telemetry-events.d.ts

@@ -0,0 +1,224 @@
+/**
+ * The three telemetry events as explicit types — the wire contract `src/telemetry.ts`
+ * assembles and `/v1/telemetry` ingests. They live in their own leaf module so the
+ * shape can be read and diffed without the builders around it, and so the builders,
+ * the allowlist (`src/telemetry-fields.ts`), and `docs/telemetry-schema.md` all
+ * answer to one declaration.
+ *
+ * Two rules hold across every interface here:
+ *
+ * - **A field that can be absent is `?`, never `| null`.** Every builder omits an
+ *   underivable field rather than sending a null, so a `null` on the wire is a bug
+ *   and not a value. The one exception is `tool_call.errorClass`: "we looked and
+ *   there was no error" is a different fact from "this event does not carry that
+ *   field", and only the success path can state the former.
+ * - **No index signatures.** The v1 event type was open (`[key: string]: unknown`),
+ *   which let a field reach the wire with nothing declaring it. Exact interfaces are
+ *   what let the pinning tests and the allowlist disagree with a builder.
+ *
+ * Type-only imports throughout: this module contributes one constant and no runtime
+ * behavior, so nothing here pulls another module into a consumer's bundle.
+ */
+import type { ToolIntent, ToolSource } from "./define.js";
+import type { ToolRegistrationState } from "./register.js";
+import type { ToolAnnotations } from "./spec.js";
+import type { AgentRuntime, FormFactor, FrameContext, PageVisibility, ReferrerClass, SurfaceInfo } from "./telemetry-context.js";
+import type { ToolShapeMetrics } from "./tool-metrics.js";
+/**
+ * Wire-format version carried by every event as `schema`. `2` is a clean break from
+ * v1 — different event names, different field set, no storage-backed identity — and
+ * nothing is deployed against v1, so no compatibility shim exists.
+ */
+export declare const TELEMETRY_SCHEMA_VERSION = 2;
+/** The discriminant: which of the three events this is. */
+export type TelemetryEventName = "sdk_init" | "tool_registration" | "tool_call";
+/**
+ * What every event carries. `sessionId` is in-memory only (`sessionId()` in
+ * `src/telemetry-context.ts`) and is the sole join key between the three: arrival
+ * order is not guaranteed, so nothing downstream may assume `sdk_init` lands first.
+ */
+export interface TelemetryEnvelope {
+    schema: typeof TELEMETRY_SCHEMA_VERSION;
+    event: TelemetryEventName;
+    /** Event time as an ISO-8601 string. */
+    ts: string;
+    sessionId: string;
+}
+/** How the SDK reached the page — a build-time fact, not an observed one. */
+export type InstallMode = "npm" | "cdn_snippet";
+/** `sdk.*` — which build of which package emitted the event. */
+export interface SdkInfo {
+    name: string;
+    version: string;
+    installMode: InstallMode;
+}
+/**
+ * `page.*` — the page as derived signals rather than strings. `referrerClass` is
+ * always present because an absent referrer is itself a class (`direct`); the rest
+ * are omitted when the global they come from is missing or unreadable.
+ */
+export interface PageContext {
+    routeTemplate?: string;
+    segmentCount?: number;
+    referrerClass: ReferrerClass;
+    frameContext?: FrameContext;
+    visibility?: PageVisibility;
+}
+/**
+ * `client.*` — who is driving the page. `agentRuntime` is always present because
+ * "we looked and could not tell" is reported as `unknown` rather than by omission;
+ * see the accuracy caveat on `agentRuntime` in `src/telemetry-context.ts`.
+ */
+export interface ClientContext {
+    agentRuntime: AgentRuntime;
+    browser?: string;
+    browserMajor?: number;
+    formFactor?: FormFactor;
+    language?: string;
+}
+/**
+ * `sdk_init` — once per page load, at import time via a deferred flush. It fires
+ * 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 {
+    event: "sdk_init";
+    sdk: SdkInfo;
+    surface: SurfaceInfo;
+    page: PageContext;
+    client: ClientContext;
+    /** Milliseconds from navigation start; absent when the clock is unusable. */
+    timeToInitMs?: number;
+}
+/** What caused this `registerTools` call, inferred from module state. */
+export type RegistrationTrigger = "initial" | "spa_navigation" | "re_register";
+/**
+ * How one tool's registration settled. The registration states plus `pending`,
+ * which only telemetry can report: the batch emits on a timeout rather than wait
+ * forever on a surface whose `registerTool` never settles. Derived from
+ * {@link ToolRegistrationState} so the two can never drift apart.
+ */
+export type ToolRegistrationOutcome = ToolRegistrationState | "pending";
+/**
+ * `config.*` — what the authenticated `tracking` channel is actually doing on this
+ * page, moved here from `sdk_init` because it is per-batch information and at
+ * `sdk_init` flush time no batch may have run.
+ */
+export interface TrackingConfigInfo {
+    trackingEnabled: boolean;
+    otelEnabled: boolean;
+    customEndpoint: boolean;
+}
+/**
+ * One tool in a `tool_registration` batch. The shape metrics are inherited as
+ * optional because they and `schemaHash` are derived from `inputSchema` together:
+ * an entry carries both or neither, matching `shapeMetrics`/`schemaHash`.
+ */
+export interface RegisteredToolEntry extends Partial<ToolShapeMetrics> {
+    name: string;
+    stableKey: string;
+    version?: string;
+    schemaHash?: string;
+    source?: ToolSource;
+    intent?: ToolIntent;
+    outcome: ToolRegistrationOutcome;
+    /** Templated failure message; absent unless `outcome` is `failed`. */
+    failureSignature?: string;
+    descriptionLength: number;
+    /** Absent when the tool declares none — an empty object would say the same thing
+     * at the cost of a key on every entry. */
+    annotations?: ToolAnnotations;
+}
+/**
+ * What an entry degrades to on the truncation ladder's first `tools` rung (schema
+ * §"Size bound and truncation order", step 1): identity and outcome, the two things
+ * the event exists for. Declared rather than left implicit because the ladder runs
+ * *after* assembly, so a consumer typing against {@link ToolRegistrationEvent} would
+ * otherwise read `descriptionLength` as always-present on a beacon that has none.
+ */
+export type StrippedToolEntry = Pick<RegisteredToolEntry, "name" | "stableKey" | "outcome" | "schemaHash" | "source" | "intent">;
+/**
+ * What `tools` degrades to on the ladder's second rung (step 2) when stripping the
+ * entries still leaves the batch over the 64 KB bound: the count, which answers "did
+ * this site register tools" where an event dropped whole answers nothing.
+ */
+export interface TruncatedTools {
+    __truncated: true;
+    /** Serialized bytes the entries occupied; `0` when they could not be serialized. */
+    originalBytes: number;
+    /** The `tools` array's own length, so it survives unserializable entries. */
+    toolCount: number;
+}
+/**
+ * `tool_registration` — once per `registerTools` call, carrying the per-tool
+ * 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 {
+    event: "tool_registration";
+    /** 1-based position of this batch within the page load. */
+    registrationIndex: number;
+    trigger: RegistrationTrigger;
+    routeTemplate?: string;
+    timeSinceInitMs?: number;
+    /** Milliseconds from the call to the batch settling (or to the timeout). */
+    settleMs: number;
+    config: TrackingConfigInfo;
+    /**
+     * One entry per tool in the batch — unless the batch could not be sent whole, in
+     * which case the truncation ladder degrades this field in two ordered steps. Narrow
+     * with `Array.isArray` before reading entries.
+     */
+    tools: RegisteredToolEntry[] | StrippedToolEntry[] | TruncatedTools;
+}
+/** How a tool invocation settled. */
+export type ToolCallOutcome = "success" | "error";
+/** `tool.*` on `tool_call` — identity and the two fields worth joining calls on. */
+export interface ToolCallToolInfo {
+    stableKey: string;
+    schemaHash?: string;
+    intent?: ToolIntent;
+}
+/**
+ * `response.*` — the handler's result as measurements, never as content. Absent
+ * when there is no result to measure (the error path, or a handler returning
+ * nothing).
+ */
+export interface ToolCallResponseMetrics {
+    bytes: number;
+    contentBlocks: number;
+    /** The normalized result's own `isError` flag — a handler-reported failure that
+     * did not throw, so `outcome` alone cannot see it. */
+    isError: boolean;
+}
+/**
+ * `tool_call` — once per settled invocation, derived signals only. No raw `input`,
+ * `response`, or error message: the reliability question is answered by `outcome`,
+ * `durationMs`, and the error *class* and *signature*, none of which carry merchant
+ * or visitor content.
+ */
+export interface ToolCallEvent extends TelemetryEnvelope {
+    event: "tool_call";
+    /** Per-call random ID — deduplicates a retried beacon, joins nothing else. */
+    callId: string;
+    /** 1-based position among all tool calls in this page load. */
+    callIndex: number;
+    /** 1-based position among calls to *this* tool. */
+    toolCallIndex: number;
+    /** `stableKey` of the previously called tool; absent on the first call. */
+    precededBy?: string;
+    routeTemplate?: string;
+    agentRuntime: AgentRuntime;
+    timeSinceInitMs?: number;
+    tool: ToolCallToolInfo;
+    outcome: ToolCallOutcome;
+    /** Client-measured elapsed milliseconds. */
+    durationMs: number;
+    response?: ToolCallResponseMetrics;
+    /** Explicitly `null` on the success path — see the module doc. */
+    errorClass: string | null;
+    /** Templated error message; absent unless `outcome` is `error`. */
+    errorSignature?: string;
+}
+/** Any event the channel emits, discriminated on `event`. */
+export type TelemetryEvent = SdkInitEvent | ToolRegistrationEvent | ToolCallEvent;

package/dist/telemetry-fields.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Field allowlist for the default-on usage-telemetry channel
+ * (`src/telemetry.ts`). Every field an event may carry is listed here, and nothing
+ * is emitted unless its entry is `true`. `pruneByAllowlist` applies both maps on
+ * the way out, so flipping an entry to `false` and releasing is the single change
+ * needed to stop collecting a field — no builder can leak it.
+ *
+ * **Two maps, because one event field is an array.** `tool_registration.tools` is a
+ * list of per-tool entries: a dotted path cannot address the third entry's
+ * `schemaHash`, and per-index paths would mean a different allowlist per batch size.
+ * {@link TELEMETRY_TOOL_FIELDS} is keyed by the per-entry field name and gates it
+ * across every entry at once. The same map gates `tool_call.tool`, whose keys are a
+ * subset of an entry's — one decision covers both places a tool is described. The
+ * two namespaces are independent on purpose: `outcome` is the *call's* outcome at
+ * the event level and the *tool's registration* outcome inside an entry.
+ *
+ * `tools` and `tool` also appear in {@link TELEMETRY_FIELDS} as whole-key gates, so
+ * dropping either collection outright does not mean disabling every per-entry field.
+ *
+ * Event-level keys are the paths as they appear on the wire, at most two levels
+ * deep — the full extent of the event schemas. `routeTemplate` and `timeSinceInitMs`
+ * are listed once each and gate both events that carry them; `page.routeTemplate` and
+ * `client.agentRuntime` are separate keys because `sdk_init` nests them.
+ *
+ * **What is missing is missing by design.** The v1 fields that carried PII or
+ * unbounded cardinality (`fullUserAgent`, `screen`, `timezone`, `platform`, `url`,
+ * `path`, `referrer`, `title`, raw `input`/`response`/`error`, storage-backed
+ * `visitorId`/`sessionId`) are not listed as `false` — they are gone, replaced by
+ * derived signals, so no allowlist entry can bring them back.
+ *
+ * The envelope (`schema`, `event`, `ts`, `sessionId`) is listed like everything
+ * else, but it is what the backend routes, versions, and joins on: turning one of
+ * those off would emit unroutable payloads, so treat them as fixed in practice.
+ *
+ * This module is pure data — no imports, no side effects at import time.
+ */
+/** Event-level fields, keyed by their dotted path on the wire. */
+export declare const TELEMETRY_FIELDS: {
+    readonly schema: true;
+    readonly event: true;
+    readonly ts: true;
+    readonly sessionId: true;
+    readonly "sdk.name": true;
+    readonly "sdk.version": true;
+    readonly "sdk.installMode": true;
+    readonly "surface.available": true;
+    readonly "surface.provenance": true;
+    readonly "surface.global": true;
+    readonly "surface.specVersion": true;
+    readonly "page.routeTemplate": true;
+    readonly "page.segmentCount": true;
+    readonly "page.referrerClass": true;
+    readonly "page.frameContext": true;
+    readonly "page.visibility": true;
+    readonly "client.agentRuntime": true;
+    readonly "client.browser": true;
+    readonly "client.browserMajor": true;
+    readonly "client.formFactor": true;
+    readonly "client.language": true;
+    readonly timeToInitMs: true;
+    readonly registrationIndex: true;
+    readonly trigger: true;
+    readonly settleMs: true;
+    readonly "config.trackingEnabled": true;
+    readonly "config.otelEnabled": true;
+    readonly "config.customEndpoint": true;
+    readonly tools: true;
+    readonly callId: true;
+    readonly callIndex: true;
+    readonly toolCallIndex: true;
+    readonly precededBy: true;
+    readonly tool: true;
+    readonly outcome: true;
+    readonly durationMs: true;
+    readonly "response.bytes": true;
+    readonly "response.contentBlocks": true;
+    readonly "response.isError": true;
+    readonly errorClass: true;
+    readonly errorSignature: true;
+    readonly routeTemplate: true;
+    readonly timeSinceInitMs: true;
+    readonly agentRuntime: true;
+};
+/**
+ * Per-entry fields inside `tool_registration.tools[]` and on `tool_call.tool`.
+ * `annotations` gates the whole sub-object: its two booleans are one declaration by
+ * the tool author, and splitting them would be a third level of allowlist for no
+ * decision anyone needs to make separately.
+ */
+export declare const TELEMETRY_TOOL_FIELDS: {
+    readonly name: true;
+    readonly stableKey: true;
+    readonly version: true;
+    readonly schemaHash: true;
+    readonly source: true;
+    readonly intent: true;
+    readonly outcome: true;
+    readonly failureSignature: true;
+    readonly descriptionLength: true;
+    readonly annotations: true;
+    readonly paramCount: true;
+    readonly requiredCount: true;
+    readonly freeTextParamCount: true;
+    readonly enumParamCount: true;
+    readonly maxDepth: true;
+    readonly describedParamCount: true;
+};
+/**
+ * Every event-level field name, as a dotted event path. Derived from the map above
+ * so the field list exists in exactly one place — adding a field is one line, and
+ * it cannot be half-added.
+ */
+export type TelemetryField = keyof typeof TELEMETRY_FIELDS;
+/** Field name → collected. A `false` entry is pruned from every event. */
+export type TelemetryFieldMap = Readonly<Record<TelemetryField, boolean>>;
+/** Every per-entry field name, derived from {@link TELEMETRY_TOOL_FIELDS}. */
+export type TelemetryToolField = keyof typeof TELEMETRY_TOOL_FIELDS;
+/** Per-entry field name → collected. A `false` entry is pruned from every entry. */
+export type TelemetryToolFieldMap = Readonly<Record<TelemetryToolField, boolean>>;