@vesta-analytics/sdk 0.1.0

package/dist/adapters/mcpOfficial.js

@@ -0,0 +1,40 @@
+/**
+ * McpAdapter — instruments the official `@modelcontextprotocol/sdk`.
+ *
+ * Covers both shapes a customer uses:
+ *   - the low-level `Server` (`server/index.js`), and
+ *   - the high-level `McpServer` (`server/mcp.js`), which wraps a low-level
+ *     `Server` reachable via `.server`.
+ *
+ * Both expose the same `_requestHandlers` map, so the shared
+ * `installLowlevelWrap` handles them identically.
+ *
+ * Importing this module never hard-requires `@modelcontextprotocol/sdk`; it is
+ * an optional peer dependency. Detection is purely structural.
+ */
+import { installLowlevelWrap, isLowlevelServer, lowlevelHandlers } from './lowlevel.js';
+function lowlevelOf(server) {
+    if (isLowlevelServer(server))
+        return server;
+    if (server !== null && typeof server === 'object') {
+        const inner = server['server'];
+        if (isLowlevelServer(inner))
+            return inner;
+    }
+    return null;
+}
+export class McpAdapter {
+    name = 'mcp';
+    owns(server) {
+        return lowlevelOf(server) !== null;
+    }
+    wrap(server, onInvocation) {
+        const low = lowlevelOf(server);
+        if (low === null)
+            return;
+        // The official Server exposes the negotiated clientInfo via getClientVersion()
+        // — read per call so each span is attributable to its app, not just initialize.
+        const getClientInfo = () => low.getClientVersion?.();
+        installLowlevelWrap(lowlevelHandlers(low), 'mcp', onInvocation, undefined, getClientInfo);
+    }
+}

package/dist/capture.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Pure attribute builders. Keys match the vesta_core OTel translator exactly
+ * — this is the wire-format parity seam with the Python SDK's `capture.py`.
+ *
+ * No OTel-SDK or framework imports here. `export.ts` turns these dicts into a
+ * real OTel span. Every value is a wire-safe scalar (string / number /
+ * boolean); payloads are JSON-encoded into string attributes, which the
+ * ingest translator decodes structurally (so JS-vs-Python JSON spacing is
+ * irrelevant to parity).
+ */
+export type AttrValue = string | number | boolean;
+export interface SpanAttributesInput {
+    surfaceId: string;
+    toolName: string;
+    toolArguments: unknown;
+    toolResult: unknown;
+    sessionId: string | null;
+    sdkVersion: string;
+    dimensions: Record<string, unknown>;
+    userId: string | null;
+    linkedTraceId: string | null;
+    linkedSpanId: string | null;
+    method?: string;
+    extraAttributes?: Record<string, unknown> | null;
+    redactionCount?: number | null;
+    redactionPaths?: string[] | null;
+}
+export declare function spanAttributes(input: SpanAttributesInput): Record<string, AttrValue>;
+export declare function resourceAttributes(input: {
+    agentRuntime: string;
+    agentRuntimeVersion: string;
+    transport?: string;
+}): Record<string, string>;
+/** Which client app drove this call, from the connection's MCP `clientInfo`
+ * (an Implementation = name + version: "claude-ai", "Cursor", ...). Stamped on
+ * EVERY span (not just the handshake) so each call is attributable to its app
+ * without joining back to initialize — the high-coverage identity signal,
+ * unlike the model (see `baggageModelAttrs`). Mirror of Python
+ * `client_identity_attrs`; emits the same `mcp.client.*` keys the initialize
+ * extractor uses, so both promote through the one translator path. Fail-safe. */
+export declare function clientIdentityAttrs(clientInfo: any): Record<string, AttrValue>;
+/** Model identity an instrumented client propagated in trace `baggage`. `meta`
+ * is the request's `_meta` object (where MCP carries propagated context — see
+ * propagation.ts). Promotes OTel-canonical `gen_ai.request.model` /
+ * `gen_ai.provider.name` onto the span (the translator maps them to the
+ * model_id / model_provider columns). `{}` when baggage is absent or carries no
+ * model keys — the common case, since most third-party clients don't propagate
+ * this. Mirror of Python `baggage_model_attrs`. */
+export declare function baggageModelAttrs(meta: unknown): Record<string, AttrValue>;
+/** Shape of a tools/call result, without its content: the MCP `isError` flag
+ * (tool-reported failure, distinct from a transport/protocol error), whether
+ * `structuredContent` was returned, and the set of content block types. `{}`
+ * for anything that isn't tool-result-shaped. */
+export declare function resultShapeAttrs(result: any): Record<string, AttrValue>;
+/** Privacy-safe summary of a call's arguments: sorted top-level keys, count,
+ * and emptiness. Keys only — never values. Non-object args yield `{}`. */
+export declare function argumentShapeAttrs(args: unknown): Record<string, AttrValue>;
+/** The negotiated contract from initialize: which capabilities each side
+ * advertised, and whether the server shipped natural-language `instructions`
+ * (its 'how to use me' to agents — an editable lever). The text is already in
+ * the (redaction-bypassed) initialize payload, so only presence + length here. */
+export declare function handshakeContractAttrs(params: any, result: any): Record<string, AttrValue>;
+/** Server-side identity from the request's validated access token (TS SDK:
+ * `extra.authInfo`). Where the verifier exposes a subject claim, emit a
+ * pseudonymous, issuer-qualified `user_id = hash(iss, sub)` (never the raw
+ * subject, never the token). Always capture `scopes` + `client_id` when present.
+ * No subject → no user id. A service/client-credentials token frequently carries
+ * `sub === client_id` (no human principal); don't mint a "user" from an app
+ * identity — emit a user id only for a subject distinct from the client. */
+export declare function authIdentityAttrs(authInfo: any): Record<string, AttrValue>;

package/dist/capture.js

@@ -0,0 +1,266 @@
+/**
+ * Pure attribute builders. Keys match the vesta_core OTel translator exactly
+ * — this is the wire-format parity seam with the Python SDK's `capture.py`.
+ *
+ * No OTel-SDK or framework imports here. `export.ts` turns these dicts into a
+ * real OTel span. Every value is a wire-safe scalar (string / number /
+ * boolean); payloads are JSON-encoded into string attributes, which the
+ * ingest translator decodes structurally (so JS-vs-Python JSON spacing is
+ * irrelevant to parity).
+ */
+import { createHash } from 'node:crypto';
+/** JSON encoder mirroring Python's `json.dumps(x, default=str)`: BigInt and
+ * other non-JSON scalars fall back to their string form rather than throwing. */
+function jsonEncode(value) {
+    return JSON.stringify(value, (_key, v) => {
+        if (typeof v === 'bigint')
+            return v.toString();
+        if (typeof v === 'function' || typeof v === 'symbol')
+            return String(v);
+        return v;
+    });
+}
+export function spanAttributes(input) {
+    const { surfaceId, toolName, toolArguments, toolResult, sessionId, sdkVersion, dimensions, userId, linkedTraceId, linkedSpanId, method = 'tools/call', extraAttributes, redactionCount, redactionPaths, } = input;
+    const attrs = {
+        'vesta.surface_id': surfaceId,
+        'mcp.tool': toolName,
+        'mcp.method.name': method,
+        'vesta.sdk_version': sdkVersion,
+    };
+    // SemConv-canonical primary-id key, per method. Dual-write alongside mcp.tool.
+    if (method === 'tools/call' && toolName) {
+        attrs['gen_ai.tool.name'] = toolName;
+    }
+    else if (method === 'prompts/get' && toolName) {
+        attrs['gen_ai.prompt.name'] = toolName;
+    }
+    else if (method === 'resources/read' && toolName) {
+        attrs['mcp.resource.uri'] = toolName;
+    }
+    if (toolArguments !== null && toolArguments !== undefined) {
+        attrs['gen_ai.tool.call.arguments'] = jsonEncode(toolArguments);
+    }
+    if (toolResult !== null && toolResult !== undefined) {
+        attrs['gen_ai.tool.call.result'] = jsonEncode(toolResult);
+    }
+    if (sessionId !== null && sessionId !== undefined) {
+        attrs['mcp.session.id'] = sessionId;
+    }
+    if (userId !== null && userId !== undefined) {
+        attrs['vesta.dim.user_id'] = userId;
+    }
+    for (const [k, v] of Object.entries(dimensions ?? {})) {
+        if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
+            attrs[`vesta.dim.${k}`] = v;
+        }
+        else if (v !== null && v !== undefined) {
+            attrs[`vesta.dim.${k}`] = String(v);
+        }
+    }
+    if (linkedTraceId && linkedSpanId) {
+        attrs['vesta.linked'] = true;
+        attrs['vesta.linked_trace_id'] = linkedTraceId;
+        attrs['vesta.linked_span_id'] = linkedSpanId;
+    }
+    else {
+        attrs['vesta.linked'] = false;
+    }
+    if (redactionCount !== null && redactionCount !== undefined) {
+        attrs['vesta.redaction.count'] = Math.trunc(redactionCount);
+    }
+    if (redactionPaths !== null && redactionPaths !== undefined) {
+        attrs['vesta.redaction.paths'] = jsonEncode(redactionPaths);
+    }
+    // Method-specific extras (handshake fields on initialize, etc.). Merged last
+    // with set-if-absent semantics so they cannot clobber a load-bearing core
+    // attribute (parity with Python's setdefault).
+    if (extraAttributes) {
+        for (const [k, v] of Object.entries(extraAttributes)) {
+            if (k in attrs)
+                continue;
+            if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
+                attrs[k] = v;
+            }
+        }
+    }
+    return attrs;
+}
+export function resourceAttributes(input) {
+    return {
+        'service.name': input.agentRuntime,
+        'service.version': input.agentRuntimeVersion,
+        'vesta.transport': input.transport ?? 'unknown',
+    };
+}
+/** Which client app drove this call, from the connection's MCP `clientInfo`
+ * (an Implementation = name + version: "claude-ai", "Cursor", ...). Stamped on
+ * EVERY span (not just the handshake) so each call is attributable to its app
+ * without joining back to initialize — the high-coverage identity signal,
+ * unlike the model (see `baggageModelAttrs`). Mirror of Python
+ * `client_identity_attrs`; emits the same `mcp.client.*` keys the initialize
+ * extractor uses, so both promote through the one translator path. Fail-safe. */
+export function clientIdentityAttrs(clientInfo) {
+    if (clientInfo === null || clientInfo === undefined)
+        return {};
+    const attrs = {};
+    if (clientInfo.name)
+        attrs['mcp.client.name'] = String(clientInfo.name);
+    if (clientInfo.version)
+        attrs['mcp.client.version'] = String(clientInfo.version);
+    return attrs;
+}
+// OTel-canonical GenAI keys. MCP's own SemConv omits model identity from MCP
+// spans (the server is downstream of the model), so these are read from W3C
+// baggage an instrumented client *opts in* to propagate — sparse by nature.
+const BAGGAGE_MODEL_KEY = 'gen_ai.request.model';
+const BAGGAGE_PROVIDER_KEY = 'gen_ai.provider.name';
+/** Parse a W3C `baggage` header value (`k=v,k2=v2`). Per-member `;properties`
+ * are stripped and values percent-decoded. Permissive: members without `=` are
+ * skipped, never throwing. */
+function parseBaggage(raw) {
+    const out = {};
+    for (const member of raw.split(',')) {
+        const idx = member.indexOf('=');
+        if (idx < 0)
+            continue;
+        const key = member.slice(0, idx).trim();
+        const value = member.slice(idx + 1).split(';', 1)[0].trim(); // drop member-properties
+        if (!key)
+            continue;
+        try {
+            out[key] = decodeURIComponent(value);
+        }
+        catch {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+/** Model identity an instrumented client propagated in trace `baggage`. `meta`
+ * is the request's `_meta` object (where MCP carries propagated context — see
+ * propagation.ts). Promotes OTel-canonical `gen_ai.request.model` /
+ * `gen_ai.provider.name` onto the span (the translator maps them to the
+ * model_id / model_provider columns). `{}` when baggage is absent or carries no
+ * model keys — the common case, since most third-party clients don't propagate
+ * this. Mirror of Python `baggage_model_attrs`. */
+export function baggageModelAttrs(meta) {
+    if (meta === null || typeof meta !== 'object')
+        return {};
+    const raw = meta['baggage'];
+    if (typeof raw !== 'string')
+        return {};
+    const bag = parseBaggage(raw);
+    const attrs = {};
+    if (bag[BAGGAGE_MODEL_KEY])
+        attrs[BAGGAGE_MODEL_KEY] = bag[BAGGAGE_MODEL_KEY];
+    if (bag[BAGGAGE_PROVIDER_KEY])
+        attrs[BAGGAGE_PROVIDER_KEY] = bag[BAGGAGE_PROVIDER_KEY];
+    return attrs;
+}
+// ---------------------------------------------------------------------------
+// Privacy-safe shape signals (capture-liberally, T1/T2) — the TS mirror of
+// Python capture.py. Keys, counts, types, presence/length; NEVER values. They
+// land in raw_attributes; `JSON.stringify` is compact, byte-matching Python's
+// `_compact` (separators without spaces) so a TS- and a Python-emitted row for
+// the same call are identical. Sorted arrays match Python's `sorted`.
+// ---------------------------------------------------------------------------
+const SERVER_CAP_FIELDS = ['experimental', 'logging', 'prompts', 'resources', 'tools', 'completions', 'tasks'];
+const CLIENT_CAP_FIELDS = ['experimental', 'sampling', 'elicitation', 'roots', 'tasks'];
+function offeredCapabilities(caps, fields) {
+    const out = [];
+    for (const f of fields) {
+        const v = caps == null ? undefined : caps[f];
+        if (v !== undefined && v !== null)
+            out.push(f);
+    }
+    return out.sort();
+}
+/** Shape of a tools/call result, without its content: the MCP `isError` flag
+ * (tool-reported failure, distinct from a transport/protocol error), whether
+ * `structuredContent` was returned, and the set of content block types. `{}`
+ * for anything that isn't tool-result-shaped. */
+export function resultShapeAttrs(result) {
+    const isObj = result !== null && typeof result === 'object';
+    const hasContent = isObj && 'content' in result;
+    const hasIsError = isObj && 'isError' in result;
+    if (!(hasContent || hasIsError))
+        return {};
+    const content = Array.isArray(result.content) ? result.content : [];
+    const types = Array.from(new Set(content.map((c) => c?.type).filter((t) => t !== null && t !== undefined))).sort();
+    return {
+        'mcp.tool.is_error': Boolean(result.isError),
+        'mcp.tool.result.structured': result.structuredContent !== null && result.structuredContent !== undefined,
+        'mcp.tool.result.content_count': content.length,
+        'mcp.tool.result.content_types': JSON.stringify(types),
+    };
+}
+/** Privacy-safe summary of a call's arguments: sorted top-level keys, count,
+ * and emptiness. Keys only — never values. Non-object args yield `{}`. */
+export function argumentShapeAttrs(args) {
+    if (args === null || args === undefined) {
+        return { 'vesta.args.keys': JSON.stringify([]), 'vesta.args.count': 0, 'vesta.args.empty': true };
+    }
+    if (typeof args !== 'object' || Array.isArray(args))
+        return {};
+    const keys = Object.keys(args).map(String).sort();
+    return {
+        'vesta.args.keys': JSON.stringify(keys),
+        'vesta.args.count': keys.length,
+        'vesta.args.empty': keys.length === 0,
+    };
+}
+/** The negotiated contract from initialize: which capabilities each side
+ * advertised, and whether the server shipped natural-language `instructions`
+ * (its 'how to use me' to agents — an editable lever). The text is already in
+ * the (redaction-bypassed) initialize payload, so only presence + length here. */
+export function handshakeContractAttrs(params, result) {
+    const attrs = {
+        'mcp.client.capabilities': JSON.stringify(offeredCapabilities(params?.capabilities, CLIENT_CAP_FIELDS)),
+        'mcp.server.capabilities': JSON.stringify(offeredCapabilities(result?.capabilities, SERVER_CAP_FIELDS)),
+    };
+    const instructions = result?.instructions;
+    attrs['mcp.server.instructions.present'] = Boolean(instructions);
+    if (instructions)
+        attrs['mcp.server.instructions.length'] = String(instructions).length;
+    return attrs;
+}
+// Must match Python `_hash_subject` byte-for-byte so the same OAuth subject maps
+// to the same pseudonymous user_id across SDKs. The no-issuer form is unchanged;
+// the issuer-qualified form binds (iss, sub) with a unit-separator that cannot
+// appear in an issuer URL or opaque subject. Secret-keyed HMAC is a deliberate
+// follow-up (see playbook/research/agent-session-identification.md) — it needs a
+// process-stable per-customer key a random salt cannot provide.
+const USER_HASH_NAMESPACE = 'vesta:user:';
+const ISS_SUB_SEP = '\x1f';
+function hashSubject(sub, iss) {
+    const material = iss ? `${iss}${ISS_SUB_SEP}${sub}` : sub;
+    return 'u_' + createHash('sha256').update(USER_HASH_NAMESPACE + material).digest('hex').slice(0, 24);
+}
+/** Server-side identity from the request's validated access token (TS SDK:
+ * `extra.authInfo`). Where the verifier exposes a subject claim, emit a
+ * pseudonymous, issuer-qualified `user_id = hash(iss, sub)` (never the raw
+ * subject, never the token). Always capture `scopes` + `client_id` when present.
+ * No subject → no user id. A service/client-credentials token frequently carries
+ * `sub === client_id` (no human principal); don't mint a "user" from an app
+ * identity — emit a user id only for a subject distinct from the client. */
+export function authIdentityAttrs(authInfo) {
+    if (authInfo === null || authInfo === undefined)
+        return {};
+    const attrs = {};
+    // The official TS AuthInfo carries verifier claims under `extra`; some
+    // verifiers expose a `claims` object. Check both for `sub` and `iss`.
+    const sub = authInfo.extra?.sub ?? authInfo.claims?.sub ?? authInfo.extra?.claims?.sub;
+    const iss = authInfo.extra?.iss ?? authInfo.claims?.iss ?? authInfo.extra?.claims?.iss;
+    const clientId = authInfo.clientId ?? authInfo.client_id;
+    if (sub && sub !== clientId) {
+        attrs['vesta.dim.user_id'] = hashSubject(String(sub), iss ? String(iss) : null);
+    }
+    const scopes = authInfo.scopes;
+    if (Array.isArray(scopes) && scopes.length > 0) {
+        attrs['vesta.auth.scopes'] = JSON.stringify(scopes.map(String).sort());
+    }
+    if (clientId)
+        attrs['vesta.auth.client_id'] = String(clientId);
+    return attrs;
+}

package/dist/diagnostics.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Silent-by-default internal logger with a verbose toggle.
+ *
+ * Mirrors the Python SDK's diagnostics: warnings always surface (they are
+ * meant to be seen — "already instrumented", "circuit opened", "exporter
+ * setup failed"); debug is suppressed unless verbose. The OpenTelemetry JS
+ * `diag` API is a no-op by default, so OTel export noise stays silent until
+ * `verbose` wires a console diag logger — the analog of the Python SDK
+ * silencing the `opentelemetry` logger family.
+ */
+export interface SdkLogger {
+    debug(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+}
+export declare function setVerbose(on: boolean): void;
+export declare function isVerbose(): boolean;
+export declare function sdkLogger(name: string): SdkLogger;

package/dist/diagnostics.js

@@ -0,0 +1,41 @@
+/**
+ * Silent-by-default internal logger with a verbose toggle.
+ *
+ * Mirrors the Python SDK's diagnostics: warnings always surface (they are
+ * meant to be seen — "already instrumented", "circuit opened", "exporter
+ * setup failed"); debug is suppressed unless verbose. The OpenTelemetry JS
+ * `diag` API is a no-op by default, so OTel export noise stays silent until
+ * `verbose` wires a console diag logger — the analog of the Python SDK
+ * silencing the `opentelemetry` logger family.
+ */
+import { DiagConsoleLogger, DiagLogLevel, diag } from '@opentelemetry/api';
+let _verbose = false;
+export function setVerbose(on) {
+    _verbose = on;
+    if (on) {
+        // Restore OTel diagnostics so export failures surface (analog of
+        // silence_third_party(on_silent=False) in the Python SDK).
+        diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG);
+    }
+    else {
+        diag.disable();
+    }
+}
+export function isVerbose() {
+    return _verbose;
+}
+export function sdkLogger(name) {
+    const prefix = `[vesta:${name}]`;
+    return {
+        debug(...args) {
+            if (_verbose) {
+                // eslint-disable-next-line no-console
+                console.error(prefix, ...args);
+            }
+        },
+        warn(...args) {
+            // eslint-disable-next-line no-console
+            console.warn(prefix, ...args);
+        },
+    };
+}

package/dist/dimensions.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `sessionContext` closure resolution. Session scope only.
+ *
+ * Called once per session id, result cached. Fail-open: any exception in the
+ * customer's closure drops dimensions for that session and is logged
+ * internally — the customer's request is never affected.
+ */
+export type SessionContext = (request: unknown) => Record<string, unknown>;
+export declare class DimensionResolver {
+    private readonly closure;
+    private readonly cache;
+    constructor(closure: SessionContext | undefined);
+    forSession(sessionId: string | null, opts: {
+        request: unknown;
+    }): Record<string, unknown>;
+    private resolve;
+}

package/dist/dimensions.js

@@ -0,0 +1,62 @@
+/**
+ * `sessionContext` closure resolution. Session scope only.
+ *
+ * Called once per session id, result cached. Fail-open: any exception in the
+ * customer's closure drops dimensions for that session and is logged
+ * internally — the customer's request is never affected.
+ */
+import { sdkLogger } from './diagnostics.js';
+const log = sdkLogger('dimensions');
+export class DimensionResolver {
+    closure;
+    cache = new Map();
+    constructor(closure) {
+        this.closure = closure;
+    }
+    forSession(sessionId, opts) {
+        // Privacy invariant: a falsy/null session id means no stable per-session
+        // identity is available. Never share a cache entry in that case — doing so
+        // would leak one user's dimensions into an unrelated user's spans. Resolve
+        // fresh every call instead.
+        if (!sessionId) {
+            return this.resolve(opts.request);
+        }
+        const cached = this.cache.get(sessionId);
+        if (cached !== undefined)
+            return cached;
+        const resolved = this.resolve(opts.request);
+        this.cache.set(sessionId, resolved);
+        return resolved;
+    }
+    resolve(request) {
+        if (this.closure === undefined)
+            return {};
+        let raw;
+        try {
+            raw = this.closure(request);
+        }
+        catch {
+            log.debug('session_context closure raised; dropping dimensions');
+            return {};
+        }
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+            log.debug('session_context returned non-object; dropping');
+            return {};
+        }
+        const out = {};
+        for (const [k, v] of Object.entries(raw)) {
+            if (v === null ||
+                v === undefined ||
+                typeof v === 'string' ||
+                typeof v === 'number' ||
+                typeof v === 'boolean') {
+                out[String(k)] = v ?? null;
+            }
+            else {
+                out[String(k)] = String(v).replace(/\n/g, ' ');
+                log.debug(`coerced non-scalar dimension ${k} to str`);
+            }
+        }
+        return out;
+    }
+}

package/dist/export.d.ts

@@ -0,0 +1,40 @@
+/**
+ * OTel-SDK export wiring + Vesta reliability primitives.
+ *
+ * Async ship-and-forget via BatchSpanProcessor. The customer's handler never
+ * waits on Vesta and never sees a Vesta exception. The circuit breaker drops
+ * silently after consecutive export failures so a dead ingest endpoint can't
+ * back up unbounded work in the customer's process.
+ */
+import { BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
+export interface CircuitBreakerOptions {
+    threshold?: number;
+    cooldownS?: number;
+    now?: () => number;
+}
+export declare class CircuitBreaker {
+    private readonly threshold;
+    private readonly cooldown;
+    private readonly now;
+    private failures;
+    private openedAt;
+    constructor(opts?: CircuitBreakerOptions);
+    recordFailure(): void;
+    recordSuccess(): void;
+    isOpen(): boolean;
+}
+export interface BuildProviderOptions {
+    endpoint: string;
+    apiKey: string;
+    resourceAttrs: Record<string, string>;
+    maxQueueSize?: number;
+    maxExportBatchSize?: number;
+    scheduleDelayMs?: number;
+}
+/**
+ * Standard OTel exporter, gzip protobuf, bounded queue. BatchSpanProcessor's
+ * queue is hard-capped (maxQueueSize); when full it drops newest spans rather
+ * than growing unbounded — the bounded-memory guarantee carried over from the
+ * Python SDK.
+ */
+export declare function buildTracerProvider(opts: BuildProviderOptions): BasicTracerProvider;

package/dist/export.js

@@ -0,0 +1,68 @@
+/**
+ * OTel-SDK export wiring + Vesta reliability primitives.
+ *
+ * Async ship-and-forget via BatchSpanProcessor. The customer's handler never
+ * waits on Vesta and never sees a Vesta exception. The circuit breaker drops
+ * silently after consecutive export failures so a dead ingest endpoint can't
+ * back up unbounded work in the customer's process.
+ */
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
+import { Resource } from '@opentelemetry/resources';
+import { BasicTracerProvider, BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { sdkLogger } from './diagnostics.js';
+const log = sdkLogger('export');
+export class CircuitBreaker {
+    threshold;
+    cooldown;
+    now;
+    failures = 0;
+    openedAt = null;
+    constructor(opts = {}) {
+        this.threshold = opts.threshold ?? 10;
+        this.cooldown = opts.cooldownS ?? 60.0;
+        this.now = opts.now ?? (() => Date.now() / 1000);
+    }
+    recordFailure() {
+        this.failures += 1;
+        if (this.failures >= this.threshold && this.openedAt === null) {
+            this.openedAt = this.now();
+            log.warn(`export circuit opened after ${this.failures} failures`);
+        }
+    }
+    recordSuccess() {
+        this.failures = 0;
+        this.openedAt = null;
+    }
+    isOpen() {
+        if (this.openedAt === null)
+            return false;
+        if (this.now() - this.openedAt >= this.cooldown) {
+            this.failures = 0;
+            this.openedAt = null;
+            return false;
+        }
+        return true;
+    }
+}
+/**
+ * Standard OTel exporter, gzip protobuf, bounded queue. BatchSpanProcessor's
+ * queue is hard-capped (maxQueueSize); when full it drops newest spans rather
+ * than growing unbounded — the bounded-memory guarantee carried over from the
+ * Python SDK.
+ */
+export function buildTracerProvider(opts) {
+    const exporter = new OTLPTraceExporter({
+        url: opts.endpoint,
+        headers: { Authorization: `Bearer ${opts.apiKey}` },
+    });
+    const processor = new BatchSpanProcessor(exporter, {
+        maxQueueSize: opts.maxQueueSize ?? 2048,
+        maxExportBatchSize: opts.maxExportBatchSize ?? 100,
+        scheduledDelayMillis: opts.scheduleDelayMs ?? 5000,
+    });
+    const provider = new BasicTracerProvider({
+        resource: new Resource(opts.resourceAttrs),
+    });
+    provider.addSpanProcessor(processor);
+    return provider;
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @vesta-analytics/sdk — instrument an MCP server with one call.
+ *
+ * ```ts
+ * import { instrument } from '@vesta-analytics/sdk';
+ * instrument(server, { apiKey: 'vsk_...' });
+ * ```
+ *
+ * Runs inside the customer's process — minimal footprint, fail-open, never
+ * breaks the host server. Ships behavioural data to Vesta over OTLP/HTTP, the
+ * same wire format as the Python SDK.
+ */
+export declare const version = "0.0.1";
+export { instrument } from './instrument.js';
+export type { InstrumentOptions } from './instrument.js';
+export type { InstrumentHandle } from './lifecycle.js';
+export { RedactionConfig, Field, Tool, Prompt, Resource, Method } from './redaction.js';
+export type { ActionName, Rule, Predicate, RedactionConfigInit } from './redaction.js';
+export type { SessionContext } from './dimensions.js';

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * @vesta-analytics/sdk — instrument an MCP server with one call.
+ *
+ * ```ts
+ * import { instrument } from '@vesta-analytics/sdk';
+ * instrument(server, { apiKey: 'vsk_...' });
+ * ```
+ *
+ * Runs inside the customer's process — minimal footprint, fail-open, never
+ * breaks the host server. Ships behavioural data to Vesta over OTLP/HTTP, the
+ * same wire format as the Python SDK.
+ */
+export const version = '0.0.1';
+export { instrument } from './instrument.js';
+export { RedactionConfig, Field, Tool, Prompt, Resource, Method } from './redaction.js';