@qodo/sdk 0.13.4 → 2.0.0-next.0

package/dist/observability/spans.js

@@ -0,0 +1,300 @@
+/**
+ * SDK 2.0 span emission helpers.
+ *
+ * Public-API methods on the client open and close spans through `SpanRecorder`.
+ * The recorder is the single place that knows about the OTel API: when no OTel
+ * is configured, every method returns a no-op `SpanLifecycle` so the call
+ * sites don't branch.
+ *
+ * Span boundaries:
+ *
+ *   - `qar.client.connect`           — wraps `client.connect()` until the WS upgrade resolves.
+ *   - `qar.client.disconnect`        — short-lived; ends when teardown returns.
+ *   - `qar.client.task.start`        — wraps `tasks.start`; ends when the iterator closes.
+ *   - `qar.client.task.continue`     — same shape, distinct name.
+ *   - `qar.client.task.cancel`       — short-lived; ends when `task.done(canceled)` arrives.
+ *   - `qar.client.task.resubscribe`  — wraps `tasks.resubscribe` invocation.
+ *   - `qar.client.tool.respond`      — short-lived; ends when the WS write resolves.
+ *   - `qar.client.tool.handler`      — wraps the inbound `tool.request` → handler invocation.
+ *
+ * Spans inherit from the consumer's currently-active OTel context. Errors
+ * record an exception and set `ERROR` status. Cleanly-terminated spans set
+ * `OK`. Iterator early-termination still records `OK` (cancellation isn't an
+ * error), with an attribute distinguishing terminal vs cancel paths.
+ */
+import { GEN_AI_CONVERSATION_ID, GEN_AI_OPERATION_NAME, GEN_AI_OP_EXECUTE_TOOL, QAR_AGENT_ID, QAR_AGENT_KIND, QAR_GRAPH_DEPTH, QAR_GRAPH_ENTRY, QAR_MESSAGE_ID, QAR_NODE_NAME, QAR_PARENT_MESSAGE_ID, QAR_SESSION_ID, QAR_SKILL_NAME, QAR_TASK_ID, QAR_TOOL_CALL_ID, QAR_TOOL_NAME, QAR_TOOL_ORIGIN, QAR_TOOL_OUTCOME, SERVICE_NAME, SERVICE_NAMESPACE, SERVICE_NAMESPACE_VALUE, SERVICE_NAME_VALUE, SERVICE_VERSION, SPAN_CONNECT, SPAN_DISCONNECT, SPAN_TASK_CANCEL, SPAN_TASK_CONTINUE, SPAN_TASK_RESUBSCRIBE, SPAN_TASK_START, SPAN_TOOL_HANDLER, SPAN_TOOL_RESPOND, TOOL_ORIGIN_SDK_SIDE, TOOL_OUTCOME_DENIED, TOOL_OUTCOME_ERROR, TOOL_OUTCOME_SUCCESS, } from './attributes.js';
+/** Default tracer name. Same as `service.name` so Phoenix groups spans naturally. */
+const TRACER_NAME = SERVICE_NAME_VALUE;
+/**
+ * Span emission entry-point. One instance per `QodoClient`. Methods return a
+ * `SpanLifecycle` the call site closes when the operation completes (or fails).
+ *
+ * A `SpanRecorder` constructed with `otel === undefined` returns a single
+ * shared no-op lifecycle for every method. No allocations, no overhead beyond
+ * a method-call dispatch.
+ */
+export class SpanRecorder {
+    otel;
+    tracer;
+    statusOk;
+    statusError;
+    /** Cached resource attrs stamped on every span so Phoenix groups by service. */
+    resourceAttrs;
+    constructor(otel, sdkVersion) {
+        this.otel = otel;
+        if (otel !== undefined) {
+            this.tracer = otel.trace.getTracer(TRACER_NAME, sdkVersion);
+        }
+        this.statusOk = otel?.SpanStatusCode.OK ?? 1;
+        this.statusError = otel?.SpanStatusCode.ERROR ?? 2;
+        this.resourceAttrs = {
+            [SERVICE_NAME]: SERVICE_NAME_VALUE,
+            [SERVICE_NAMESPACE]: SERVICE_NAMESPACE_VALUE,
+            [SERVICE_VERSION]: sdkVersion,
+        };
+    }
+    /** Whether OTel emission is wired (vs no-op). */
+    get isEnabled() {
+        return this.tracer !== undefined;
+    }
+    /**
+     * Open a `qar.client.task.start` span. The caller is responsible for closing
+     * it — typically via the `TaskSubscription` lifecycle wired in `TaskClient`.
+     */
+    startTaskStartSpan(attrs) {
+        return this.openTaskSpan(SPAN_TASK_START, {
+            ...(attrs.sessionId !== undefined
+                ? {
+                    [QAR_SESSION_ID]: attrs.sessionId,
+                    [GEN_AI_CONVERSATION_ID]: attrs.sessionId,
+                }
+                : {}),
+            [QAR_MESSAGE_ID]: attrs.messageId,
+            ...(attrs.agentId !== undefined ? { [QAR_AGENT_ID]: attrs.agentId } : {}),
+            ...(attrs.skillName !== undefined ? { [QAR_SKILL_NAME]: attrs.skillName } : {}),
+            ...(attrs.operationName !== undefined ? { [GEN_AI_OPERATION_NAME]: attrs.operationName } : {}),
+            ...(attrs.graphEntry !== undefined ? { [QAR_GRAPH_ENTRY]: attrs.graphEntry } : {}),
+            ...(attrs.graphDepth !== undefined ? { [QAR_GRAPH_DEPTH]: attrs.graphDepth } : {}),
+            ...(attrs.agentKind !== undefined ? { [QAR_AGENT_KIND]: attrs.agentKind } : {}),
+        });
+    }
+    /** Open a `qar.client.task.continue` span. */
+    startTaskContinueSpan(attrs) {
+        return this.openTaskSpan(SPAN_TASK_CONTINUE, {
+            ...(attrs.sessionId !== undefined
+                ? {
+                    [QAR_SESSION_ID]: attrs.sessionId,
+                    [GEN_AI_CONVERSATION_ID]: attrs.sessionId,
+                }
+                : {}),
+            [QAR_MESSAGE_ID]: attrs.messageId,
+            [QAR_TASK_ID]: attrs.taskId,
+        });
+    }
+    /** Open a `qar.client.task.cancel` span. */
+    startTaskCancelSpan(attrs) {
+        return this.openSpan(SPAN_TASK_CANCEL, {
+            ...(attrs.sessionId !== undefined
+                ? {
+                    [QAR_SESSION_ID]: attrs.sessionId,
+                    [GEN_AI_CONVERSATION_ID]: attrs.sessionId,
+                }
+                : {}),
+            [QAR_MESSAGE_ID]: attrs.messageId,
+            [QAR_TASK_ID]: attrs.taskId,
+        });
+    }
+    /** Open a `qar.client.task.resubscribe` span. */
+    startTaskResubscribeSpan(attrs) {
+        return this.openTaskSpan(SPAN_TASK_RESUBSCRIBE, {
+            ...(attrs.sessionId !== undefined
+                ? {
+                    [QAR_SESSION_ID]: attrs.sessionId,
+                    [GEN_AI_CONVERSATION_ID]: attrs.sessionId,
+                }
+                : {}),
+            [QAR_MESSAGE_ID]: attrs.messageId,
+            [QAR_TASK_ID]: attrs.taskId,
+            ...(attrs.sinceMessageId !== undefined
+                ? { [QAR_PARENT_MESSAGE_ID]: attrs.sinceMessageId }
+                : {}),
+        });
+    }
+    /**
+     * Open a `qar.client.tool.respond` span — short-lived, ends on WS write.
+     *
+     * Every outbound `tool.response` envelope carries a `node_name` so the
+     * span records it for parallel-graph telemetry routing.
+     */
+    startToolRespondSpan(attrs) {
+        return this.openSpan(SPAN_TOOL_RESPOND, {
+            ...(attrs.sessionId !== undefined
+                ? {
+                    [QAR_SESSION_ID]: attrs.sessionId,
+                    [GEN_AI_CONVERSATION_ID]: attrs.sessionId,
+                }
+                : {}),
+            [QAR_TOOL_CALL_ID]: attrs.toolCallId,
+            [QAR_TOOL_ORIGIN]: TOOL_ORIGIN_SDK_SIDE,
+            [QAR_TOOL_OUTCOME]: attrs.outcome,
+            [QAR_NODE_NAME]: attrs.nodeName,
+            [GEN_AI_OPERATION_NAME]: GEN_AI_OP_EXECUTE_TOOL,
+        });
+    }
+    /**
+     * Open a `qar.client.tool.handler` span around the invocation of a registered
+     * handler for one `ToolCall` from an inbound `tool.request`. Caller updates
+     * `qar.tool_outcome` and closes via `succeed()` / `fail()` based on the
+     * handler's per-call result.
+     *
+     * A parallel-batched `tool.request` carrying N calls opens N sibling
+     * spans (one per call), each tagged with its own
+     * `qar.tool_call_id` and the request's `qar.node_name`. The shared parent
+     * is whatever OTel context was active when the inbound envelope arrived —
+     * typically the task span.
+     */
+    startToolHandlerSpan(attrs) {
+        return this.openSpan(SPAN_TOOL_HANDLER, {
+            ...(attrs.sessionId !== undefined
+                ? {
+                    [QAR_SESSION_ID]: attrs.sessionId,
+                    [GEN_AI_CONVERSATION_ID]: attrs.sessionId,
+                }
+                : {}),
+            [QAR_TOOL_CALL_ID]: attrs.toolCallId,
+            [QAR_TOOL_NAME]: attrs.toolName,
+            [QAR_TOOL_ORIGIN]: TOOL_ORIGIN_SDK_SIDE,
+            [QAR_NODE_NAME]: attrs.nodeName,
+            [GEN_AI_OPERATION_NAME]: GEN_AI_OP_EXECUTE_TOOL,
+        });
+    }
+    /** Open a `qar.client.connect` span. Ends when the WS upgrade resolves. */
+    startConnectSpan() {
+        return this.openSpan(SPAN_CONNECT, {});
+    }
+    /** Open a `qar.client.disconnect` span. */
+    startDisconnectSpan(attrs) {
+        return this.openSpan(SPAN_DISCONNECT, {
+            ...(attrs.sessionId !== undefined ? { [QAR_SESSION_ID]: attrs.sessionId } : {}),
+        });
+    }
+    /**
+     * Internal: open a span as a child of the consumer's currently-active
+     * context, attaching attributes + the resource attrs. Returns a
+     * `SpanLifecycle` the caller closes.
+     */
+    openSpan(name, attrs) {
+        if (this.tracer === undefined)
+            return NOOP_LIFECYCLE;
+        const otel = this.otel;
+        const parentContext = otel.context.active();
+        const span = this.tracer.startSpan(name, { attributes: { ...this.resourceAttrs, ...attrs } }, parentContext);
+        const spanContext = otel.trace.setSpan(parentContext, span);
+        return new RealSpanLifecycle(otel, span, spanContext, this.statusOk, this.statusError);
+    }
+    /**
+     * Internal: open a span and return both the lifecycle and the OTel context
+     * pinning that span — so a caller (e.g. `TaskSubscription`) can re-attach
+     * the context every time it yields an event to the consumer's iterator.
+     */
+    openTaskSpan(name, attrs) {
+        const lifecycle = this.openSpan(name, attrs);
+        return { lifecycle, otelContext: lifecycle.context() };
+    }
+}
+/** Outcome-attribute helper used by `TaskClient`/`ToolClient` call sites. */
+export function toolOutcomeFor(outcome) {
+    switch (outcome) {
+        case 'success':
+            return TOOL_OUTCOME_SUCCESS;
+        case 'error':
+            return TOOL_OUTCOME_ERROR;
+        case 'denied':
+            return TOOL_OUTCOME_DENIED;
+    }
+}
+// ---------------------------------------------------------------------------
+// Lifecycle implementations
+// ---------------------------------------------------------------------------
+/**
+ * Real span — backed by the consumer's OTel TracerProvider. `succeed()` /
+ * `fail()` are idempotent: a second call after close is a no-op so callers
+ * don't need to track close state themselves.
+ */
+class RealSpanLifecycle {
+    otel;
+    span;
+    otelContext;
+    okCode;
+    errorCode;
+    closed = false;
+    constructor(otel, span, otelContext, okCode, errorCode) {
+        this.otel = otel;
+        this.span = span;
+        this.otelContext = otelContext;
+        this.okCode = okCode;
+        this.errorCode = errorCode;
+    }
+    setAttribute(key, value) {
+        if (this.closed)
+            return;
+        try {
+            this.span.setAttribute(key, value);
+        }
+        catch {
+            // Defensive — consumer may have wired an unstable TracerProvider impl.
+            // Telemetry should never crash the SDK's hot path.
+        }
+    }
+    succeed() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            this.span.setStatus({ code: this.okCode });
+            this.span.end();
+        }
+        catch {
+            // see setAttribute()
+        }
+    }
+    fail(err) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            const message = err instanceof Error ? err.message : String(err);
+            this.span.recordException(err instanceof Error ? err : message);
+            this.span.setStatus({ code: this.errorCode, message });
+            this.span.end();
+        }
+        catch {
+            // see setAttribute()
+        }
+    }
+    withContext(fn) {
+        return this.otel.context.with(this.otelContext, fn);
+    }
+    context() {
+        return this.otelContext;
+    }
+}
+/** Shared no-op lifecycle — one instance, no allocations on the hot path. */
+const NOOP_LIFECYCLE = {
+    setAttribute() {
+        /* no-op */
+    },
+    succeed() {
+        /* no-op */
+    },
+    fail() {
+        /* no-op */
+    },
+    withContext(fn) {
+        return fn();
+    },
+    context() {
+        return undefined;
+    },
+};
+//# sourceMappingURL=spans.js.map

package/dist/observability/spans.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spans.js","sourceRoot":"","sources":["../../src/observability/spans.ts"],"names":[],"mappings":"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"}

package/dist/observability/traceContext.d.ts

@@ -0,0 +1,51 @@
+/**
+ * W3C Trace Context provider.
+ *
+ * Reads the consumer's currently-active OTel `Context` and serializes the
+ * active span's `SpanContext` into a W3C `traceparent` header value
+ * (`00-<trace_id>-<span_id>-<trace_flags>`). The `tracestate` arm carries any
+ * vendor-specific propagation data attached upstream.
+ *
+ * Without an `OTelAPI` (or with an OTel API but no active recording span), the
+ * provider falls back to the per-envelope filler — a fresh, valid 55-char
+ * `traceparent` per call. The QAR server tolerates the synthetic value; what it
+ * doesn't tolerate is an empty string (the schema enforces the regex).
+ */
+import type { OTelAPI } from '../tracing/types.js';
+/** Concrete `trace_context` value the SDK writes onto every outbound envelope. */
+export interface TraceContextValue {
+    /** Always present, always 55 chars (`00-<32hex>-<16hex>-<2hex>`). */
+    readonly traceparent: string;
+    /** Optional, only when the active context has a non-empty tracestate. */
+    readonly tracestate?: string;
+}
+/** Build a W3C `traceparent` from the components of a SpanContext. */
+export declare function formatTraceparent(traceId: string, spanId: string, traceFlags: number): string;
+/**
+ * Provider for the per-envelope `trace_context`. Stateless — every call reads
+ * the live OTel context anew. Cheap; no caching needed (a hot envelope path
+ * does ~1 read per send).
+ */
+export declare class TraceContextProvider {
+    private readonly otel;
+    /**
+     * @param otel  Optional OTel API. When `undefined`, every `current()` call
+     *              returns a fresh random traceparent.
+     */
+    constructor(otel: OTelAPI | undefined);
+    /**
+     * Resolve the active SpanContext (if any) and return the wire `trace_context`.
+     *
+     * Order of preference:
+     *   1. The currently-active OTel span — its trace-id/span-id are written into
+     *      `traceparent`, its `traceState.serialize()` (when non-empty) into
+     *      `tracestate`. This is what stitches the SDK's outbound envelope into
+     *      the consumer's trace.
+     *   2. Filler — a fresh random 55-char `traceparent` per call. The server
+     *      doesn't reject it; the trace just doesn't continue past the SDK.
+     */
+    current(): TraceContextValue;
+    /** The currently-active recording span, or `undefined` if no OTel / no span. */
+    private activeSpan;
+}
+//# sourceMappingURL=traceContext.d.ts.map

package/dist/observability/traceContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceContext.d.ts","sourceRoot":"","sources":["../../src/observability/traceContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,OAAO,EAA6B,MAAM,qBAAqB,CAAC;AAE9E,kFAAkF;AAClF,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAaD,sEAAsE;AACtE,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GACjB,MAAM,CAKR;AAED;;;;GAIG;AACH,qBAAa,oBAAoB;IAKnB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJjC;;;OAGG;gBAC0B,IAAI,EAAE,OAAO,GAAG,SAAS;IAEtD;;;;;;;;;;OAUG;IACI,OAAO,IAAI,iBAAiB;IA8BnC,gFAAgF;IAChF,OAAO,CAAC,UAAU;CAiBnB"}

package/dist/observability/traceContext.js

@@ -0,0 +1,151 @@
+/**
+ * W3C Trace Context provider.
+ *
+ * Reads the consumer's currently-active OTel `Context` and serializes the
+ * active span's `SpanContext` into a W3C `traceparent` header value
+ * (`00-<trace_id>-<span_id>-<trace_flags>`). The `tracestate` arm carries any
+ * vendor-specific propagation data attached upstream.
+ *
+ * Without an `OTelAPI` (or with an OTel API but no active recording span), the
+ * provider falls back to the per-envelope filler — a fresh, valid 55-char
+ * `traceparent` per call. The QAR server tolerates the synthetic value; what it
+ * doesn't tolerate is an empty string (the schema enforces the regex).
+ */
+/** Hex characters per W3C trace_id field. */
+const TRACE_ID_HEX_LEN = 32;
+/** Hex characters per W3C span_id field. */
+const SPAN_ID_HEX_LEN = 16;
+/**
+ * The "invalid" trace-id and span-id values defined by the W3C spec — used to
+ * detect a noop / non-recording SpanContext. Treated as if no active span.
+ */
+const INVALID_TRACE_ID = '0'.repeat(TRACE_ID_HEX_LEN);
+const INVALID_SPAN_ID = '0'.repeat(SPAN_ID_HEX_LEN);
+/** Build a W3C `traceparent` from the components of a SpanContext. */
+export function formatTraceparent(traceId, spanId, traceFlags) {
+    // W3C: trace_flags is 1 byte = 2 lowercase hex chars. Mask to the low byte
+    // so an SDK that hands us a wider int doesn't break the header shape.
+    const flagsHex = (traceFlags & 0xff).toString(16).padStart(2, '0');
+    return `00-${traceId}-${spanId}-${flagsHex}`;
+}
+/**
+ * Provider for the per-envelope `trace_context`. Stateless — every call reads
+ * the live OTel context anew. Cheap; no caching needed (a hot envelope path
+ * does ~1 read per send).
+ */
+export class TraceContextProvider {
+    otel;
+    /**
+     * @param otel  Optional OTel API. When `undefined`, every `current()` call
+     *              returns a fresh random traceparent.
+     */
+    constructor(otel) {
+        this.otel = otel;
+    }
+    /**
+     * Resolve the active SpanContext (if any) and return the wire `trace_context`.
+     *
+     * Order of preference:
+     *   1. The currently-active OTel span — its trace-id/span-id are written into
+     *      `traceparent`, its `traceState.serialize()` (when non-empty) into
+     *      `tracestate`. This is what stitches the SDK's outbound envelope into
+     *      the consumer's trace.
+     *   2. Filler — a fresh random 55-char `traceparent` per call. The server
+     *      doesn't reject it; the trace just doesn't continue past the SDK.
+     */
+    current() {
+        const span = this.activeSpan();
+        if (span === undefined)
+            return fillerTraceContext();
+        let ctx;
+        try {
+            ctx = span.spanContext();
+        }
+        catch {
+            // Defensive — shouldn't happen with a real OTel implementation, but a
+            // user-supplied fake might mis-shape spanContext(). Falling back to the
+            // filler keeps outbound envelopes valid rather than throwing on the
+            // emit path.
+            return fillerTraceContext();
+        }
+        if (typeof ctx.traceId !== 'string' ||
+            typeof ctx.spanId !== 'string' ||
+            ctx.traceId.length !== TRACE_ID_HEX_LEN ||
+            ctx.spanId.length !== SPAN_ID_HEX_LEN ||
+            ctx.traceId === INVALID_TRACE_ID ||
+            ctx.spanId === INVALID_SPAN_ID) {
+            // Non-recording / noop span — its SpanContext carries the all-zero ids
+            // and isn't meaningful to propagate. Filler.
+            return fillerTraceContext();
+        }
+        const traceparent = formatTraceparent(ctx.traceId, ctx.spanId, ctx.traceFlags);
+        const tracestate = serializeTraceState(ctx.traceState);
+        return tracestate !== undefined ? { traceparent, tracestate } : { traceparent };
+    }
+    /** The currently-active recording span, or `undefined` if no OTel / no span. */
+    activeSpan() {
+        const otel = this.otel;
+        if (otel === undefined)
+            return undefined;
+        const span = otel.trace.getActiveSpan();
+        if (span === undefined)
+            return undefined;
+        // A non-recording span carries the noop SpanContext (all zeros). Skip it
+        // here so we fall into the filler arm and emit a valid traceparent.
+        try {
+            if (typeof span.isRecording === 'function' && !span.isRecording()) {
+                return undefined;
+            }
+        }
+        catch {
+            // Defensive — see `current()`.
+            return undefined;
+        }
+        return span;
+    }
+}
+/** Serialize a TraceState object to its header form. Returns `undefined` for missing/empty. */
+function serializeTraceState(ts) {
+    if (ts === undefined)
+        return undefined;
+    let serialized;
+    try {
+        serialized = ts.serialize();
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof serialized !== 'string' || serialized.length === 0)
+        return undefined;
+    return serialized;
+}
+/**
+ * Build a fresh, valid 55-char `traceparent`. Used when no OTel API or no
+ * active span — keeps QAR's schema validator happy and ensures every envelope
+ * carries a syntactically well-formed header.
+ *
+ * The flags byte is `00` (not sampled): the trace doesn't continue past the
+ * SDK in the absence of a TracerProvider, so opting in to sampling would be
+ * misleading.
+ */
+function fillerTraceContext() {
+    const traceId = randomHex(16);
+    const spanId = randomHex(8);
+    return { traceparent: formatTraceparent(traceId, spanId, 0) };
+}
+/**
+ * Random lowercase-hex of `byteCount` bytes, isomorphic between Node and
+ * browser. Reads from `globalThis.crypto.getRandomValues` — present on Node
+ * 19+ and every modern browser. Output shape (length, alphabet) matches the
+ * pre-2.0 `randomBytes(N).toString('hex')` exactly so wire emission is
+ * byte-identical.
+ */
+function randomHex(byteCount) {
+    const bytes = new Uint8Array(byteCount);
+    globalThis.crypto.getRandomValues(bytes);
+    let hex = '';
+    for (const b of bytes)
+        hex += b.toString(16).padStart(2, '0');
+    return hex;
+}
+//# sourceMappingURL=traceContext.js.map

package/dist/observability/traceContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceContext.js","sourceRoot":"","sources":["../../src/observability/traceContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAYH,6CAA6C;AAC7C,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAC5B,4CAA4C;AAC5C,MAAM,eAAe,GAAG,EAAE,CAAC;AAC3B;;;GAGG;AACH,MAAM,gBAAgB,GAAG,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;AACtD,MAAM,eAAe,GAAG,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;AAEpD,sEAAsE;AACtE,MAAM,UAAU,iBAAiB,CAC/B,OAAe,EACf,MAAc,EACd,UAAkB;IAElB,2EAA2E;IAC3E,sEAAsE;IACtE,MAAM,QAAQ,GAAG,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACnE,OAAO,MAAM,OAAO,IAAI,MAAM,IAAI,QAAQ,EAAE,CAAC;AAC/C,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,oBAAoB;IAKF;IAJ7B;;;OAGG;IACH,YAA6B,IAAyB;QAAzB,SAAI,GAAJ,IAAI,CAAqB;IAAG,CAAC;IAE1D;;;;;;;;;;OAUG;IACI,OAAO;QACZ,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QAC/B,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,kBAAkB,EAAE,CAAC;QACpD,IAAI,GAAoB,CAAC;QACzB,IAAI,CAAC;YACH,GAAG,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,sEAAsE;YACtE,wEAAwE;YACxE,oEAAoE;YACpE,aAAa;YACb,OAAO,kBAAkB,EAAE,CAAC;QAC9B,CAAC;QACD,IACE,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;YAC/B,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;YAC9B,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,gBAAgB;YACvC,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,eAAe;YACrC,GAAG,CAAC,OAAO,KAAK,gBAAgB;YAChC,GAAG,CAAC,MAAM,KAAK,eAAe,EAC9B,CAAC;YACD,uEAAuE;YACvE,6CAA6C;YAC7C,OAAO,kBAAkB,EAAE,CAAC;QAC9B,CAAC;QACD,MAAM,WAAW,GAAG,iBAAiB,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;QAC/E,MAAM,UAAU,GAAG,mBAAmB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACvD,OAAO,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;IAClF,CAAC;IAED,gFAAgF;IACxE,UAAU;QAChB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACvB,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACzC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC;QACxC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACzC,yEAAyE;QACzE,oEAAoE;QACpE,IAAI,CAAC;YACH,IAAI,OAAO,IAAI,CAAC,WAAW,KAAK,UAAU,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;gBAClE,OAAO,SAAS,CAAC;YACnB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,+BAA+B;YAC/B,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAED,+FAA+F;AAC/F,SAAS,mBAAmB,CAC1B,EAA6C;IAE7C,IAAI,EAAE,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACvC,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,UAAU,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAChF,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,kBAAkB;IACzB,MAAM,OAAO,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC;IAC9B,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IAC5B,OAAO,EAAE,WAAW,EAAE,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC;AAChE,CAAC;AAED;;;;;;GAMG;AACH,SAAS,SAAS,CAAC,SAAiB;IAClC,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,SAAS,CAAC,CAAC;IACxC,UAAU,CAAC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IACzC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,CAAC,IAAI,KAAK;QAAE,GAAG,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC9D,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/observability/transportMetrics.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Wire-level transport counters for the SDK's reconnect + replay path.
+ *
+ * Three counters expose the contract `task.resubscribe` flow has with
+ * QAR's per-session replay buffer: how many resubscribes the SDK has
+ * sent, how many replayed envelopes have come back, and how often the
+ * anchor `since_message_id` rotated out before the SDK could
+ * re-anchor.
+ *
+ * The counters are wire-agnostic — they live next to the spans the SDK
+ * already emits (`src/observability/spans.ts`) rather than inside the
+ * connection itself so consumers can read them off `client.transportMetrics`
+ * without holding a reference to the WS layer.
+ *
+ * Backing storage is in-memory. The SDK does NOT shovel these into an OTel
+ * meter — consumers wanting Prometheus/StatsD scrape paths read the values
+ * via {@link TransportMetrics.snapshot} and forward them through their own
+ * exporter. (OTel's metrics API is a heavier surface than the SDK's tracing
+ * peer-dependency posture wants to pull in for three counters.)
+ */
+/**
+ * Snapshot of every counter at a point in time. Counter names are
+ * wire-aligned with QAR's runtime documentation: `*_total` suffix per the
+ * OpenMetrics convention, even though the SDK doesn't ship them through an
+ * OTel meter — the suffix is part of the published name so consumers
+ * forwarding to Prometheus get the canonical metric name without renames.
+ */
+export interface TransportMetricsSnapshot {
+    /** Envelopes received via `task.resubscribe` replay (descendants of an anchor). */
+    readonly replay_envelopes_received_total: number;
+    /** `task.resubscribe` envelopes emitted by the SDK (auto-replay + manual). */
+    readonly resubscribes_sent_total: number;
+    /** Inbound `error { code: "replay_anchor_missing" }` envelopes from QAR. */
+    readonly replay_anchor_missing_total: number;
+}
+/**
+ * In-memory counter store. One instance per `QodoClient` — survives
+ * reconnects so the counters accumulate across the client's lifetime.
+ *
+ * The store is intentionally minimal: three monotonic counters + a
+ * `snapshot()` reader. No reset, no labels, no histograms. Consumers
+ * wanting label dimensionality (per-session, per-task) read the per-event
+ * span attributes instead — the counters are the aggregate roll-up.
+ */
+export declare class TransportMetrics {
+    private replayEnvelopesReceived;
+    private resubscribesSent;
+    private replayAnchorMissing;
+    /** Increment per inbound envelope that arrived via a `task.resubscribe` replay window. */
+    recordReplayEnvelopeReceived(): void;
+    /** Increment per outbound `task.resubscribe` envelope written to the wire. */
+    recordResubscribeSent(): void;
+    /** Increment per inbound `error { code: 'replay_anchor_missing' }` envelope. */
+    recordReplayAnchorMissing(): void;
+    /** Read every counter atomically — single-threaded JS, so this is a copy. */
+    snapshot(): TransportMetricsSnapshot;
+}
+//# sourceMappingURL=transportMetrics.d.ts.map

package/dist/observability/transportMetrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transportMetrics.d.ts","sourceRoot":"","sources":["../../src/observability/transportMetrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,wBAAwB;IACvC,mFAAmF;IACnF,QAAQ,CAAC,+BAA+B,EAAE,MAAM,CAAC;IACjD,8EAA8E;IAC9E,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IACzC,4EAA4E;IAC5E,QAAQ,CAAC,2BAA2B,EAAE,MAAM,CAAC;CAC9C;AAED;;;;;;;;GAQG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,uBAAuB,CAAK;IACpC,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,mBAAmB,CAAK;IAEhC,0FAA0F;IACnF,4BAA4B,IAAI,IAAI;IAI3C,8EAA8E;IACvE,qBAAqB,IAAI,IAAI;IAIpC,gFAAgF;IACzE,yBAAyB,IAAI,IAAI;IAIxC,6EAA6E;IACtE,QAAQ,IAAI,wBAAwB;CAO5C"}

package/dist/observability/transportMetrics.js

@@ -0,0 +1,55 @@
+/**
+ * Wire-level transport counters for the SDK's reconnect + replay path.
+ *
+ * Three counters expose the contract `task.resubscribe` flow has with
+ * QAR's per-session replay buffer: how many resubscribes the SDK has
+ * sent, how many replayed envelopes have come back, and how often the
+ * anchor `since_message_id` rotated out before the SDK could
+ * re-anchor.
+ *
+ * The counters are wire-agnostic — they live next to the spans the SDK
+ * already emits (`src/observability/spans.ts`) rather than inside the
+ * connection itself so consumers can read them off `client.transportMetrics`
+ * without holding a reference to the WS layer.
+ *
+ * Backing storage is in-memory. The SDK does NOT shovel these into an OTel
+ * meter — consumers wanting Prometheus/StatsD scrape paths read the values
+ * via {@link TransportMetrics.snapshot} and forward them through their own
+ * exporter. (OTel's metrics API is a heavier surface than the SDK's tracing
+ * peer-dependency posture wants to pull in for three counters.)
+ */
+/**
+ * In-memory counter store. One instance per `QodoClient` — survives
+ * reconnects so the counters accumulate across the client's lifetime.
+ *
+ * The store is intentionally minimal: three monotonic counters + a
+ * `snapshot()` reader. No reset, no labels, no histograms. Consumers
+ * wanting label dimensionality (per-session, per-task) read the per-event
+ * span attributes instead — the counters are the aggregate roll-up.
+ */
+export class TransportMetrics {
+    replayEnvelopesReceived = 0;
+    resubscribesSent = 0;
+    replayAnchorMissing = 0;
+    /** Increment per inbound envelope that arrived via a `task.resubscribe` replay window. */
+    recordReplayEnvelopeReceived() {
+        this.replayEnvelopesReceived += 1;
+    }
+    /** Increment per outbound `task.resubscribe` envelope written to the wire. */
+    recordResubscribeSent() {
+        this.resubscribesSent += 1;
+    }
+    /** Increment per inbound `error { code: 'replay_anchor_missing' }` envelope. */
+    recordReplayAnchorMissing() {
+        this.replayAnchorMissing += 1;
+    }
+    /** Read every counter atomically — single-threaded JS, so this is a copy. */
+    snapshot() {
+        return {
+            replay_envelopes_received_total: this.replayEnvelopesReceived,
+            resubscribes_sent_total: this.resubscribesSent,
+            replay_anchor_missing_total: this.replayAnchorMissing,
+        };
+    }
+}
+//# sourceMappingURL=transportMetrics.js.map

package/dist/observability/transportMetrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transportMetrics.js","sourceRoot":"","sources":["../../src/observability/transportMetrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAkBH;;;;;;;;GAQG;AACH,MAAM,OAAO,gBAAgB;IACnB,uBAAuB,GAAG,CAAC,CAAC;IAC5B,gBAAgB,GAAG,CAAC,CAAC;IACrB,mBAAmB,GAAG,CAAC,CAAC;IAEhC,0FAA0F;IACnF,4BAA4B;QACjC,IAAI,CAAC,uBAAuB,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,8EAA8E;IACvE,qBAAqB;QAC1B,IAAI,CAAC,gBAAgB,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,gFAAgF;IACzE,yBAAyB;QAC9B,IAAI,CAAC,mBAAmB,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,6EAA6E;IACtE,QAAQ;QACb,OAAO;YACL,+BAA+B,EAAE,IAAI,CAAC,uBAAuB;YAC7D,uBAAuB,EAAE,IAAI,CAAC,gBAAgB;YAC9C,2BAA2B,EAAE,IAAI,CAAC,mBAAmB;SACtD,CAAC;IACJ,CAAC;CACF"}