@vesta-analytics/sdk 0.1.0

package/dist/instrument.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Public entry point. Detect framework -> wire pipeline -> wrap server.
+ *
+ * Idempotent. Fail-open everywhere: nothing here may raise into the customer's
+ * request path. The only exception thrown is at install time for an
+ * unsupported framework — a developer error, surfaced loudly before any
+ * traffic.
+ */
+import type { SessionContext } from './dimensions.js';
+import type { InstrumentHandle } from './lifecycle.js';
+import { RedactionConfig } from './redaction.js';
+export declare const SDK_VERSION = "0.0.1";
+export declare const AGENT_RUNTIME = "vesta-sdk-js";
+export interface InstrumentOptions {
+    apiKey: string;
+    endpoint?: string;
+    sessionContext?: SessionContext;
+    args?: RedactionConfig;
+    responses?: RedactionConfig;
+    transport?: string;
+    verbose?: boolean;
+}
+export declare function instrument(server: unknown, options: InstrumentOptions): InstrumentHandle;

package/dist/instrument.js

@@ -0,0 +1,183 @@
+/**
+ * Public entry point. Detect framework -> wire pipeline -> wrap server.
+ *
+ * Idempotent. Fail-open everywhere: nothing here may raise into the customer's
+ * request path. The only exception thrown is at install time for an
+ * unsupported framework — a developer error, surfaced loudly before any
+ * traffic.
+ */
+import { SpanStatusCode } from '@opentelemetry/api';
+import { resourceAttributes, spanAttributes } from './capture.js';
+import { sdkLogger, setVerbose } from './diagnostics.js';
+import { DimensionResolver } from './dimensions.js';
+import { CircuitBreaker, buildTracerProvider } from './export.js';
+import { ShutdownManager, makeHandle, NOOP_HANDLE, flushDeadlineMs, resolveTransport, } from './lifecycle.js';
+import { extractUpstream } from './propagation.js';
+import { RedactionConfig, redactPayload } from './redaction.js';
+import { FastMcpAdapter } from './adapters/fastmcp.js';
+import { McpAdapter } from './adapters/mcpOfficial.js';
+export const SDK_VERSION = '0.0.1';
+// The runtime identity stamped on every span (resource service.name ->
+// agent_runtime in the warehouse). Distinct from the Python SDK's "vesta-sdk"
+// so a row's producing SDK is queryable directly on the agent_runtime column,
+// following the existing `vesta-<runtime>` convention (cf. "vesta-shopper").
+// Wire format, payload encoding, and source_kind="sdk" stay identical to the
+// Python SDK — only the runtime label differs.
+export const AGENT_RUNTIME = 'vesta-sdk-js';
+const log = sdkLogger('instrument');
+const ADAPTERS = [new McpAdapter(), new FastMcpAdapter()];
+const DEFAULT_ENDPOINT = 'https://ingest.vesta-analytics.ai/v1/traces';
+const DEFAULT_ARGS = new RedactionConfig({ default: 'redact' });
+const DEFAULT_RESPONSES = new RedactionConfig({ default: 'redact' });
+// Methods whose payload is non-PII handshake/metadata by construction —
+// redaction is bypassed so the captured payload survives intact for analyses
+// that need clientInfo/serverInfo/protocolVersion/capabilities.
+const REDACTION_BYPASS_METHODS = new Set(['initialize']);
+const INSTRUMENTED = Symbol.for('vesta.instrumented');
+function emitSpan(tracer, spanName, attrs, opts) {
+    let span = null;
+    try {
+        span =
+            opts.startTime !== undefined
+                ? tracer.startSpan(spanName, { startTime: opts.startTime })
+                : tracer.startSpan(spanName);
+        for (const [k, v] of Object.entries(attrs)) {
+            span.setAttribute(k, v);
+        }
+        if (opts.isError) {
+            span.setStatus({ code: SpanStatusCode.ERROR });
+        }
+    }
+    finally {
+        if (span !== null) {
+            if (opts.startTime !== undefined && opts.durationMs !== undefined) {
+                span.end(opts.startTime + opts.durationMs);
+            }
+            else {
+                span.end();
+            }
+        }
+    }
+}
+export function instrument(server, options) {
+    const target = server;
+    if (target && target[INSTRUMENTED]) {
+        log.warn('server already instrumented by vesta; ignoring second call');
+        return NOOP_HANDLE;
+    }
+    if (options.verbose) {
+        setVerbose(true);
+    }
+    else {
+        setVerbose(false);
+    }
+    const adapter = ADAPTERS.find((a) => a.owns(server));
+    if (adapter === undefined) {
+        const ctor = server?.constructor?.name ?? typeof server;
+        throw new Error(`unsupported MCP server: no Vesta adapter owns ${ctor}. ` +
+            'Supported: the official @modelcontextprotocol/sdk (low-level Server and ' +
+            'high-level McpServer) and the community fastmcp package.');
+    }
+    const argsCfg = options.args ?? DEFAULT_ARGS;
+    const respCfg = options.responses ?? DEFAULT_RESPONSES;
+    const dims = new DimensionResolver(options.sessionContext);
+    const breaker = new CircuitBreaker();
+    let tracer;
+    let manager;
+    try {
+        const provider = buildTracerProvider({
+            endpoint: options.endpoint ?? DEFAULT_ENDPOINT,
+            apiKey: options.apiKey,
+            resourceAttrs: resourceAttributes({
+                agentRuntime: AGENT_RUNTIME,
+                agentRuntimeVersion: SDK_VERSION,
+                transport: resolveTransport(options.transport),
+            }),
+        });
+        tracer = provider.getTracer('vesta-sdk');
+        manager = new ShutdownManager(provider, { deadlineMs: flushDeadlineMs() });
+        manager.install();
+    }
+    catch {
+        log.warn('vesta exporter setup failed; instrumentation disabled');
+        return NOOP_HANDLE;
+    }
+    const onInvocation = (inv) => {
+        try {
+            if (breaker.isOpen())
+                return;
+            const up = extractUpstream(inv.params);
+            // Pass inv.sessionId directly — a falsy/null id means no stable
+            // per-session identity, so dimensions resolve fresh rather than share a
+            // cache entry across unrelated sessions (cross-user leak fix).
+            const sessionDims = dims.forSession(inv.sessionId, { request: inv.request });
+            const userId = sessionDims['user_id'] ?? null;
+            delete sessionDims['user_id'];
+            let scrubbedArgs;
+            let scrubbedResult;
+            let totalCount = 0;
+            let mergedPaths = [];
+            if (REDACTION_BYPASS_METHODS.has(inv.method)) {
+                scrubbedArgs = inv.arguments;
+                scrubbedResult = inv.result;
+            }
+            else {
+                const a = redactPayload(inv.arguments, { toolName: inv.toolName, method: inv.method, config: argsCfg });
+                const r = redactPayload(inv.result, { toolName: inv.toolName, method: inv.method, config: respCfg });
+                scrubbedArgs = a.scrubbed;
+                scrubbedResult = r.scrubbed;
+                totalCount = a.count + r.count;
+                mergedPaths = [...a.paths.map((p) => `args:${p}`), ...r.paths.map((p) => `result:${p}`)];
+            }
+            const attrs = spanAttributes({
+                surfaceId: surfaceId(inv),
+                toolName: inv.toolName,
+                toolArguments: scrubbedArgs,
+                toolResult: scrubbedResult,
+                sessionId: inv.sessionId,
+                sdkVersion: SDK_VERSION,
+                dimensions: sessionDims,
+                userId,
+                linkedTraceId: up.traceId,
+                linkedSpanId: up.spanId,
+                method: inv.method,
+                extraAttributes: inv.extraAttributes ?? null,
+                redactionCount: totalCount,
+                redactionPaths: mergedPaths,
+            });
+            const spanName = inv.toolName ? `${inv.method} ${inv.toolName}` : inv.method;
+            emitSpan(tracer, spanName, attrs, {
+                startTime: inv.startTime,
+                durationMs: inv.durationMs,
+                isError: inv.isError,
+            });
+            breaker.recordSuccess();
+        }
+        catch (err) {
+            breaker.recordFailure();
+            log.debug('vesta onInvocation swallowed an exception', err);
+        }
+    };
+    adapter.wrap(server, onInvocation);
+    if (target) {
+        try {
+            Object.defineProperty(target, INSTRUMENTED, {
+                value: true,
+                enumerable: false,
+                configurable: true,
+                writable: true,
+            });
+        }
+        catch {
+            log.debug('vesta could not set instrumentation marker; idempotency protection unavailable');
+        }
+    }
+    log.debug(`vesta instrumented ${typeof server} via ${adapter.name}`);
+    return makeHandle(manager);
+}
+function surfaceId(_inv) {
+    // surface_id is issued manually in v0 and resolved via api-key->surface
+    // mapping at ingest. The SDK stamps a placeholder the ingest static map
+    // authorises.
+    return 'surf_dev';
+}

package/dist/lifecycle.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Process-shutdown lifecycle for the SDK exporter.
+ *
+ * Node has no atexit and BasicTracerProvider registers no exit flush, so for a
+ * stdio MCP subprocess the entire delivery path is a bounded flush on shutdown.
+ * This module owns the provider instrument() builds, hooks the shutdown
+ * triggers, and bounds exit (the OTLP exporter's own timeout does not bound
+ * wall-clock). Fail-open throughout: nothing here throws into the host or
+ * blocks exit past the deadline.
+ */
+export declare const DEFAULT_DEADLINE_MS = 2000;
+export interface ShutdownProvider {
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export interface ProcessLike {
+    on(event: string, listener: (...a: unknown[]) => void): unknown;
+    listenerCount(event: string): number;
+    exit(code?: number): void;
+    stdin: {
+        once(event: string, listener: (...a: unknown[]) => void): unknown;
+    };
+}
+export declare class ShutdownManager {
+    private readonly provider;
+    private readonly deadlineMs;
+    private readonly proc;
+    private shutdownStarted;
+    private installed;
+    constructor(provider: ShutdownProvider, opts?: {
+        deadlineMs?: number;
+        proc?: ProcessLike;
+    });
+    /** Deadline-bounded forceFlush. No-op (true) once shutdown started. Never throws. */
+    flush(timeoutMs?: number): Promise<boolean>;
+    /** Bounded flush then provider shutdown, run once. Never throws. */
+    shutdown(): Promise<void>;
+    /** Register shutdown hooks. Idempotent; fail-open per hook. */
+    install(): void;
+    private tryReg;
+    /** stdin closed (EOF) — the common stdio session end. Always flush + exit. */
+    handleEof(): Promise<void>;
+    /** SIGTERM/SIGINT — flush, then exit only if we are the sole listener (a
+     *  stdio process with nothing to defer to). Otherwise leave termination to
+     *  the other handler (e.g. an HTTP framework's graceful drain). */
+    handleSignal(sig: string): Promise<void>;
+    /** Run fn raced against a timer. Resolves true if fn settled within the
+     *  deadline without rejecting, false if it rejected or the deadline won. */
+    private bounded;
+}
+export interface InstrumentHandle {
+    /** Bounded force-flush. True if completed within the deadline. Never throws. */
+    flush(timeoutMs?: number): Promise<boolean>;
+    /** Bounded flush then shutdown. Idempotent. Never throws. */
+    shutdown(): Promise<void>;
+}
+export declare function makeHandle(mgr: ShutdownManager): InstrumentHandle;
+/** Returned by instrument() when instrumentation is disabled (already-instrumented
+ *  or exporter-setup failure), so the return type stays non-nullable. */
+export declare const NOOP_HANDLE: InstrumentHandle;
+export declare function flushDeadlineMs(): number;
+/** Best-effort transport label for vesta.transport. Label only; a wrong value
+ *  is harmless. Heuristic returns 'stdio' or 'unknown', never 'http'. */
+export declare function resolveTransport(explicit?: string): string;

package/dist/lifecycle.js

@@ -0,0 +1,131 @@
+/**
+ * Process-shutdown lifecycle for the SDK exporter.
+ *
+ * Node has no atexit and BasicTracerProvider registers no exit flush, so for a
+ * stdio MCP subprocess the entire delivery path is a bounded flush on shutdown.
+ * This module owns the provider instrument() builds, hooks the shutdown
+ * triggers, and bounds exit (the OTLP exporter's own timeout does not bound
+ * wall-clock). Fail-open throughout: nothing here throws into the host or
+ * blocks exit past the deadline.
+ */
+import { sdkLogger } from './diagnostics.js';
+const log = sdkLogger('lifecycle');
+export const DEFAULT_DEADLINE_MS = 2000;
+export class ShutdownManager {
+    provider;
+    deadlineMs;
+    proc;
+    shutdownStarted = false;
+    installed = false;
+    constructor(provider, opts = {}) {
+        this.provider = provider;
+        this.deadlineMs = opts.deadlineMs ?? DEFAULT_DEADLINE_MS;
+        this.proc = opts.proc ?? process;
+    }
+    /** Deadline-bounded forceFlush. No-op (true) once shutdown started. Never throws. */
+    async flush(timeoutMs) {
+        if (this.shutdownStarted)
+            return true;
+        return this.bounded(() => this.provider.forceFlush(), timeoutMs ?? this.deadlineMs);
+    }
+    /** Bounded flush then provider shutdown, run once. Never throws. */
+    async shutdown() {
+        if (this.shutdownStarted)
+            return;
+        this.shutdownStarted = true;
+        await this.bounded(() => this.provider.forceFlush(), this.deadlineMs);
+        await this.bounded(() => this.provider.shutdown(), this.deadlineMs);
+    }
+    /** Register shutdown hooks. Idempotent; fail-open per hook. */
+    install() {
+        if (this.installed)
+            return;
+        this.installed = true;
+        this.tryReg(() => this.proc.stdin.once('end', () => void this.handleEof()));
+        this.tryReg(() => this.proc.on('SIGTERM', () => void this.handleSignal('SIGTERM')));
+        this.tryReg(() => this.proc.on('SIGINT', () => void this.handleSignal('SIGINT')));
+    }
+    tryReg(fn) {
+        try {
+            fn();
+        }
+        catch (err) {
+            log.debug('vesta: shutdown hook registration failed', err);
+        }
+    }
+    /** stdin closed (EOF) — the common stdio session end. Always flush + exit. */
+    async handleEof() {
+        await this.shutdown();
+        this.proc.exit(0);
+    }
+    /** SIGTERM/SIGINT — flush, then exit only if we are the sole listener (a
+     *  stdio process with nothing to defer to). Otherwise leave termination to
+     *  the other handler (e.g. an HTTP framework's graceful drain). */
+    async handleSignal(sig) {
+        // Snapshot co-listener state at signal time, before the await: another
+        // handler must not be able to deregister and flip the sole-listener test.
+        const sole = this.proc.listenerCount(sig) === 1;
+        await this.shutdown();
+        if (sole)
+            this.proc.exit(0);
+    }
+    /** Run fn raced against a timer. Resolves true if fn settled within the
+     *  deadline without rejecting, false if it rejected or the deadline won. */
+    async bounded(fn, deadlineMs) {
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(false), deadlineMs);
+        });
+        const run = fn().then(() => true, (err) => {
+            log.debug('vesta bounded shutdown op rejected', err);
+            return false;
+        });
+        const ok = await Promise.race([run, timeout]);
+        if (timer !== undefined)
+            clearTimeout(timer);
+        // When the deadline wins, `run` (and its in-flight OTLP socket) is left
+        // unsettled by design — the caller exits the process immediately after,
+        // which reaps it. Do not "fix" this by awaiting `run`; that reintroduces
+        // the unbounded hang this race exists to prevent.
+        return ok;
+    }
+}
+export function makeHandle(mgr) {
+    return {
+        flush: (timeoutMs) => mgr.flush(timeoutMs),
+        shutdown: () => mgr.shutdown(),
+    };
+}
+/** Returned by instrument() when instrumentation is disabled (already-instrumented
+ *  or exporter-setup failure), so the return type stays non-nullable. */
+export const NOOP_HANDLE = {
+    flush: () => Promise.resolve(true),
+    shutdown: () => Promise.resolve(),
+};
+export function flushDeadlineMs() {
+    const raw = process.env.VESTA_FLUSH_DEADLINE_MS;
+    if (raw === undefined || raw === '')
+        return DEFAULT_DEADLINE_MS;
+    const value = Number.parseInt(raw, 10);
+    if (Number.isFinite(value) && value > 0)
+        return value;
+    log.debug(`invalid VESTA_FLUSH_DEADLINE_MS=${raw}; using default`);
+    return DEFAULT_DEADLINE_MS;
+}
+/** Best-effort transport label for vesta.transport. Label only; a wrong value
+ *  is harmless. Heuristic returns 'stdio' or 'unknown', never 'http'. */
+export function resolveTransport(explicit) {
+    if (explicit)
+        return explicit;
+    const env = process.env.VESTA_TRANSPORT;
+    if (env)
+        return env;
+    try {
+        if (!process.stdin.isTTY)
+            return 'stdio';
+    }
+    catch {
+        /* fall through to unknown */
+    }
+    return 'unknown';
+}

package/dist/propagation.d.ts

@@ -0,0 +1,13 @@
+/**
+ * MCP propagates trace context inside `params._meta` of the JSON-RPC body, not
+ * in HTTP headers. The format is in-flight in the MCP spec — parse
+ * permissively, never throw, fall back to Server-only on anything unexpected.
+ */
+export interface Upstream {
+    linked: boolean;
+    traceId: string | null;
+    spanId: string | null;
+}
+/** Read the W3C `traceparent` from `params._meta`. Permissive; fail to
+ * Server-only. `params` is the raw JSON-RPC params object. */
+export declare function extractUpstream(params: unknown): Upstream;

package/dist/propagation.js

@@ -0,0 +1,33 @@
+/**
+ * MCP propagates trace context inside `params._meta` of the JSON-RPC body, not
+ * in HTTP headers. The format is in-flight in the MCP spec — parse
+ * permissively, never throw, fall back to Server-only on anything unexpected.
+ */
+const SERVER_ONLY = { linked: false, traceId: null, spanId: null };
+function isHex(s) {
+    return /^[0-9a-fA-F]+$/.test(s);
+}
+/** Read the W3C `traceparent` from `params._meta`. Permissive; fail to
+ * Server-only. `params` is the raw JSON-RPC params object. */
+export function extractUpstream(params) {
+    try {
+        if (typeof params !== 'object' || params === null)
+            return SERVER_ONLY;
+        const meta = params['_meta'];
+        if (typeof meta !== 'object' || meta === null)
+            return SERVER_ONLY;
+        const tp = meta['traceparent'];
+        if (typeof tp !== 'string')
+            return SERVER_ONLY;
+        const parts = tp.split('-');
+        if (parts.length !== 4 || parts[1].length !== 32 || parts[2].length !== 16) {
+            return SERVER_ONLY;
+        }
+        if (!isHex(parts[1]) || !isHex(parts[2]))
+            return SERVER_ONLY;
+        return { linked: true, traceId: parts[1], spanId: parts[2] };
+    }
+    catch {
+        return SERVER_ONLY;
+    }
+}

package/dist/redaction.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Redaction engine. Pure — no framework or OTel imports.
+ *
+ * Precedence: field rules > subject rules (tool/prompt/resource) > method
+ * rules > default + denylist. Within field rules: exact path beats glob;
+ * among globs, the longer pattern wins. The shipped denylist behaves as
+ * implicit lowest-precedence field redacts, only relevant when
+ * default === "capture". This is a 1:1 port of the Python SDK's `redaction.py`.
+ */
+export type ActionName = 'capture' | 'redact' | 'hash' | 'truncate';
+export declare const REDACTED = "<REDACTED>";
+export declare const DEFAULT_DENYLIST: ReadonlySet<string>;
+interface Action {
+    name: ActionName;
+    n?: number;
+}
+/**
+ * Render a scalar the way Python's `repr()` does, so the `hash` action
+ * produces the same digest across the Python and TypeScript SDKs for the
+ * common scalar cases (string, integer, float-with-fraction, bool, null).
+ * Exotic types are a documented divergence — `_leaves` only ever hands us
+ * scalars, so this covers redaction in practice.
+ */
+export declare function pyRepr(value: unknown): string;
+type RuleLevel = 'field' | 'tool' | 'prompt' | 'resource' | 'method';
+export type Predicate = (path: string, value: unknown) => string;
+export interface Rule {
+    level: RuleLevel;
+    pattern: string;
+    action: Action | null;
+    predicate: Predicate | null;
+    rx: RegExp;
+    /** exact (no glob char) beats glob; then longer pattern wins. */
+    specificity: [number, number];
+}
+declare class Builder {
+    private readonly level;
+    private readonly pattern;
+    constructor(level: RuleLevel, pattern: string);
+    private mk;
+    capture(): Rule;
+    redact(): Rule;
+    hash(): Rule;
+    truncate(n: number): Rule;
+    check(predicate: Predicate): Rule;
+}
+export declare function Field(pattern: string): Builder;
+/** Match by tool name. Implicitly scoped to method=tools/call. */
+export declare function Tool(pattern: string): Builder;
+/** Match by prompt name. Scoped to method=prompts/get. */
+export declare function Prompt(pattern: string): Builder;
+/** Match by resource URI glob. Scoped to method=resources/read. */
+export declare function Resource(pattern: string): Builder;
+/** Match by MCP method name (`tools/list`, `prompts/*`, …). */
+export declare function Method(pattern: string): Builder;
+export interface RedactionConfigInit {
+    default?: string;
+    rules?: Rule[];
+}
+export declare class RedactionConfig {
+    readonly default: string;
+    readonly rules: Rule[];
+    readonly defaultAction: Action;
+    readonly fieldRules: Rule[];
+    readonly subjectRules: Record<string, Rule[]>;
+    readonly methodRules: Rule[];
+    constructor(init?: RedactionConfigInit);
+}
+export interface RedactResult {
+    scrubbed: unknown;
+    count: number;
+    paths: string[];
+}
+export interface RedactOptions {
+    toolName: string;
+    config: RedactionConfig;
+    method?: string;
+}
+export declare function redactPayload(payload: unknown, opts: RedactOptions): RedactResult;
+export {};