@foam-ai/node-cliengo 0.1.0-alpha.1

package/dist/node-cliengo/src/logs/winston-format.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Winston format for trace context enrichment (metadata injection only).
+ *
+ * Why this file exists:
+ *   NR correlates logs with traces when log lines contain `trace.id` / `span.id`.
+ *   NR gets logs via stdout forwarding, so the trace context must be in the log
+ *   output. This format injects { traceId, spanId, traceparent } into every
+ *   Winston log entry's metadata. It does NOT send logs anywhere — that's the
+ *   transport's job. It does NOT change the output format (JSON vs text is still
+ *   the service's choice).
+ *
+ * Used by combee, gpt-intentions, and hsm-backend (all Winston).
+ *
+ * Edge cases covered:
+ *   - NR not loaded: getTraceContext returns empty strings. Fields are still
+ *     added (as empty strings) — consistent schema for log parsers.
+ *   - No active NR transaction: same as above.
+ *   - Combined with format.json(): traceId/spanId appear as top-level JSON keys.
+ *   - Combined with format.printf(): fields available on info.traceId etc.
+ *   - Placed first in format.combine() chain so all subsequent formatters have
+ *     access to trace context.
+ *   - getTraceContext is lazy (called at log-write time, not at format creation
+ *     time) so the trace context is always current for the active transaction.
+ *   - If getTraceContext throws for any reason, the log entry passes through
+ *     unmodified — never crashes logging.
+ */
+import type { WinstonFormat } from '../types';
+export declare function createWinstonFormat(): WinstonFormat;

package/dist/node-cliengo/src/logs/winston-format.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Winston format for trace context enrichment (metadata injection only).
+ *
+ * Why this file exists:
+ *   NR correlates logs with traces when log lines contain `trace.id` / `span.id`.
+ *   NR gets logs via stdout forwarding, so the trace context must be in the log
+ *   output. This format injects { traceId, spanId, traceparent } into every
+ *   Winston log entry's metadata. It does NOT send logs anywhere — that's the
+ *   transport's job. It does NOT change the output format (JSON vs text is still
+ *   the service's choice).
+ *
+ * Used by combee, gpt-intentions, and hsm-backend (all Winston).
+ *
+ * Edge cases covered:
+ *   - NR not loaded: getTraceContext returns empty strings. Fields are still
+ *     added (as empty strings) — consistent schema for log parsers.
+ *   - No active NR transaction: same as above.
+ *   - Combined with format.json(): traceId/spanId appear as top-level JSON keys.
+ *   - Combined with format.printf(): fields available on info.traceId etc.
+ *   - Placed first in format.combine() chain so all subsequent formatters have
+ *     access to trace context.
+ *   - getTraceContext is lazy (called at log-write time, not at format creation
+ *     time) so the trace context is always current for the active transaction.
+ *   - If getTraceContext throws for any reason, the log entry passes through
+ *     unmodified — never crashes logging.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWinstonFormat = createWinstonFormat;
+const trace_bridge_1 = require("../trace-bridge");
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment */
+function createWinstonFormat() {
+    return {
+        transform(info) {
+            try {
+                const ctx = (0, trace_bridge_1.getTraceContext)();
+                info.traceId = ctx.traceId;
+                info.spanId = ctx.spanId;
+                info.traceparent = ctx.traceparent;
+            }
+            catch {
+                /* never crash logging */
+            }
+            return info;
+        },
+    };
+}
+/* eslint-enable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment */

package/dist/node-cliengo/src/logs/winston-transport.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Winston transport that delivers every log entry to Foam via the OTLP logs
+ * pipeline (non-global LoggerProvider → BatchLogRecordProcessor → OTLPLogExporter).
+ *
+ * Why this file exists:
+ *   NR gets logs via stdout forwarding (unchanged). Foam needs a separate
+ *   delivery path. This transport converts each Winston log entry into an OTel
+ *   log record with severity mapping and trace context, then emits it through
+ *   our non-global LoggerProvider. No double-logging to the same destination —
+ *   NR gets stdout, Foam gets OTLP.
+ *
+ * Used by combee, gpt-intentions, and hsm-backend.
+ *
+ * Edge cases covered:
+ *   - handleExceptions: false, handleRejections: false — critical. combee
+ *     creates 3-5 Winston loggers, each with existing transports that already
+ *     listen for uncaught events. Adding more would trigger Node's
+ *     MaxListenersExceededWarning. Process exceptions are captured separately
+ *     by init()'s own handlers.
+ *   - objectMode: true — Winston transports receive structured info objects,
+ *     not string chunks.
+ *   - Severity mapping: error→ERROR, warn→WARN, info/http→INFO, verbose/debug→DEBUG,
+ *     silly→TRACE. Unknown levels default to INFO.
+ *   - Unserializable attribute values (circular refs, symbols): silently skipped
+ *     per-key — other attributes still flow.
+ *   - Winston's internal Symbol(level) key is skipped in attribute iteration.
+ *   - Transport callback always called — never blocks the Winston pipeline.
+ */
+import type { LoggerProvider } from '@opentelemetry/sdk-logs';
+import type { WinstonTransport } from '../types';
+export declare function createWinstonTransport(loggerProvider: LoggerProvider, serviceName: string): WinstonTransport;

package/dist/node-cliengo/src/logs/winston-transport.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Winston transport that delivers every log entry to Foam via the OTLP logs
+ * pipeline (non-global LoggerProvider → BatchLogRecordProcessor → OTLPLogExporter).
+ *
+ * Why this file exists:
+ *   NR gets logs via stdout forwarding (unchanged). Foam needs a separate
+ *   delivery path. This transport converts each Winston log entry into an OTel
+ *   log record with severity mapping and trace context, then emits it through
+ *   our non-global LoggerProvider. No double-logging to the same destination —
+ *   NR gets stdout, Foam gets OTLP.
+ *
+ * Used by combee, gpt-intentions, and hsm-backend.
+ *
+ * Edge cases covered:
+ *   - handleExceptions: false, handleRejections: false — critical. combee
+ *     creates 3-5 Winston loggers, each with existing transports that already
+ *     listen for uncaught events. Adding more would trigger Node's
+ *     MaxListenersExceededWarning. Process exceptions are captured separately
+ *     by init()'s own handlers.
+ *   - objectMode: true — Winston transports receive structured info objects,
+ *     not string chunks.
+ *   - Severity mapping: error→ERROR, warn→WARN, info/http→INFO, verbose/debug→DEBUG,
+ *     silly→TRACE. Unknown levels default to INFO.
+ *   - Unserializable attribute values (circular refs, symbols): silently skipped
+ *     per-key — other attributes still flow.
+ *   - Winston's internal Symbol(level) key is skipped in attribute iteration.
+ *   - Transport callback always called — never blocks the Winston pipeline.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWinstonTransport = createWinstonTransport;
+const api_logs_1 = require("@opentelemetry/api-logs");
+const node_stream_1 = require("node:stream");
+const trace_bridge_1 = require("../trace-bridge");
+const SEVERITY_MAP = {
+    error: api_logs_1.SeverityNumber.ERROR,
+    warn: api_logs_1.SeverityNumber.WARN,
+    info: api_logs_1.SeverityNumber.INFO,
+    http: api_logs_1.SeverityNumber.INFO,
+    verbose: api_logs_1.SeverityNumber.DEBUG,
+    debug: api_logs_1.SeverityNumber.DEBUG,
+    silly: api_logs_1.SeverityNumber.TRACE,
+};
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment */
+function createWinstonTransport(loggerProvider, serviceName) {
+    const otelLogger = loggerProvider.getLogger(serviceName);
+    const stream = new node_stream_1.Writable({
+        objectMode: true,
+        write(info, _encoding, callback) {
+            try {
+                const level = info.level ?? 'info';
+                const message = info.message ?? '';
+                const severity = SEVERITY_MAP[level] ?? api_logs_1.SeverityNumber.INFO;
+                const ctx = (0, trace_bridge_1.getTraceContext)();
+                const attributes = {};
+                if (ctx.traceId) {
+                    attributes['trace.id'] = ctx.traceId;
+                }
+                if (ctx.spanId) {
+                    attributes['span.id'] = ctx.spanId;
+                }
+                for (const [key, val] of Object.entries(info)) {
+                    if (key !== 'level' && key !== 'message' && key !== 'timestamp' && key !== 'Symbol(level)') {
+                        try {
+                            attributes[key] = typeof val === 'string' ? val : JSON.stringify(val);
+                        }
+                        catch {
+                            /* skip unserializable */
+                        }
+                    }
+                }
+                otelLogger.emit({
+                    body: message,
+                    severityNumber: severity,
+                    severityText: level.toUpperCase(),
+                    attributes,
+                });
+            }
+            catch {
+                /* never crash logging */
+            }
+            callback();
+        },
+    });
+    // Winston transport contract: the stream with transport metadata
+    const transport = stream;
+    transport.name = 'foam-otel';
+    transport.level = undefined; // Accept all levels
+    transport.handleExceptions = false;
+    transport.handleRejections = false;
+    return transport;
+}
+/* eslint-enable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment */

package/dist/node-cliengo/src/metrics/instruments.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Pre-built OTel metric instruments for queue processing, plus factories
+ * for service-specific custom metrics.
+ *
+ * Why this file exists:
+ *   Provides three auto-recorded instruments that wrapSqsConsumer and
+ *   wrapJobConsumer populate automatically:
+ *   - messageProcessingDuration (histogram, ms): how long each message takes
+ *   - messageProcessingErrors (counter): how many processing attempts fail
+ *   - messagesProcessed (counter): total messages processed (success + error)
+ *
+ *   Also provides customHistogram/customCounter/customGauge factories for
+ *   service-specific domain metrics (LLM duration in gpt-intentions, webhook
+ *   processing time in cb-proxy, automation duration in kori).
+ *
+ * Edge cases covered:
+ *   - Custom instrument idempotency: calling customHistogram('llm.duration', ...)
+ *     twice returns the same Histogram instance (cached by name). OTel SDKs
+ *     already handle duplicate instrument creation, but caching avoids the
+ *     overhead of repeated createHistogram calls in hot paths.
+ *   - MeterProvider is non-global — our metrics never conflict with NR's
+ *     internal metrics or any other OTel MeterProvider in the process.
+ *   - PeriodicExportingMetricReader (configured in init.ts) exports every 60s
+ *     by default. If no exporter is configured (non-production), no reader is
+ *     attached and no timer runs.
+ */
+import type { MeterProvider } from '@opentelemetry/sdk-metrics';
+import type { BridgeMetrics } from '../types';
+export declare function createBridgeMetrics(meterProvider: MeterProvider, serviceName: string): BridgeMetrics;

package/dist/node-cliengo/src/metrics/instruments.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Pre-built OTel metric instruments for queue processing, plus factories
+ * for service-specific custom metrics.
+ *
+ * Why this file exists:
+ *   Provides three auto-recorded instruments that wrapSqsConsumer and
+ *   wrapJobConsumer populate automatically:
+ *   - messageProcessingDuration (histogram, ms): how long each message takes
+ *   - messageProcessingErrors (counter): how many processing attempts fail
+ *   - messagesProcessed (counter): total messages processed (success + error)
+ *
+ *   Also provides customHistogram/customCounter/customGauge factories for
+ *   service-specific domain metrics (LLM duration in gpt-intentions, webhook
+ *   processing time in cb-proxy, automation duration in kori).
+ *
+ * Edge cases covered:
+ *   - Custom instrument idempotency: calling customHistogram('llm.duration', ...)
+ *     twice returns the same Histogram instance (cached by name). OTel SDKs
+ *     already handle duplicate instrument creation, but caching avoids the
+ *     overhead of repeated createHistogram calls in hot paths.
+ *   - MeterProvider is non-global — our metrics never conflict with NR's
+ *     internal metrics or any other OTel MeterProvider in the process.
+ *   - PeriodicExportingMetricReader (configured in init.ts) exports every 60s
+ *     by default. If no exporter is configured (non-production), no reader is
+ *     attached and no timer runs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBridgeMetrics = createBridgeMetrics;
+function createBridgeMetrics(meterProvider, serviceName) {
+    const meter = meterProvider.getMeter(serviceName);
+    const messageProcessingDuration = meter.createHistogram('messaging.process.duration', {
+        description: 'Time to process a queue message',
+        unit: 'ms',
+    });
+    const messageProcessingErrors = meter.createCounter('messaging.process.errors', {
+        description: 'Number of queue message processing errors',
+    });
+    const messagesProcessed = meter.createCounter('messaging.process.count', {
+        description: 'Number of queue messages processed',
+    });
+    const instrumentCache = new Map();
+    return {
+        messageProcessingDuration,
+        messageProcessingErrors,
+        messagesProcessed,
+        customHistogram(name, description, unit) {
+            const key = `histogram:${name}`;
+            const existing = instrumentCache.get(key);
+            if (existing) {
+                return existing;
+            }
+            const h = meter.createHistogram(name, { description, unit });
+            instrumentCache.set(key, h);
+            return h;
+        },
+        customCounter(name, description, unit) {
+            const key = `counter:${name}`;
+            const existing = instrumentCache.get(key);
+            if (existing) {
+                return existing;
+            }
+            const c = meter.createCounter(name, { description, unit });
+            instrumentCache.set(key, c);
+            return c;
+        },
+        customGauge(name, description, unit) {
+            const key = `gauge:${name}`;
+            const existing = instrumentCache.get(key);
+            if (existing) {
+                return existing;
+            }
+            const g = meter.createObservableGauge(name, { description, unit });
+            instrumentCache.set(key, g);
+            return g;
+        },
+    };
+}

package/dist/node-cliengo/src/nr.d.ts

@@ -0,0 +1,35 @@
+/**
+ * New Relic agent detection and lazy resolution.
+ *
+ * Why this file exists:
+ *   The library must NEVER call `require('newrelic')` directly — doing so would
+ *   start the NR agent in services that explicitly disable it (hsm-backend uses
+ *   a conditional `NEW_RELIC_LOG_ENABLED` check). Instead, we detect NR via
+ *   `require.cache` — if the service already loaded NR, we reuse that instance.
+ *   If not, all NR calls silently no-op via the NOOP_NR stub.
+ *
+ * Resolution strategy:
+ *   1. Explicit: `init('svc', token, { newrelic: nrInstance })` — used by
+ *      kori (ESM + pnpm, where require.cache detection is unreliable) and
+ *      hsm-backend (conditional NR loading).
+ *   2. Module cache: `require.cache[require.resolve('newrelic')]` — works for
+ *      CJS services (combee, gpt-intentions, cb-proxy) where NR is loaded at
+ *      the top of the entry file before the bridge initializes.
+ *   3. Fallback: NOOP_NR stub that returns empty trace metadata and calls
+ *      handler functions directly without creating background transactions.
+ *
+ * Edge cases covered:
+ *   - `require.resolve('newrelic')` throws if newrelic is not installed at all.
+ *     Caught silently — returns NOOP_NR.
+ *   - NR's stub API (agent disabled via config) returns `{ traceId: '', spanId: '' }`
+ *     from `getTraceMetadata()` — our code treats empty strings as "no trace,"
+ *     so buildTraceparent() returns undefined. No crash.
+ *   - `startBackgroundTransaction` in the stub just calls the handler directly
+ *     and returns its result, preserving async/await flow.
+ *   - Once resolved, the NR instance is cached so subsequent calls to `getNr()`
+ *     don't re-probe the module cache.
+ */
+import type { NewRelicAgent } from './types';
+export declare function resolveNewRelic(explicit?: NewRelicAgent): NewRelicAgent;
+export declare function getNr(): NewRelicAgent;
+export declare function isNrLoaded(): boolean;

package/dist/node-cliengo/src/nr.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * New Relic agent detection and lazy resolution.
+ *
+ * Why this file exists:
+ *   The library must NEVER call `require('newrelic')` directly — doing so would
+ *   start the NR agent in services that explicitly disable it (hsm-backend uses
+ *   a conditional `NEW_RELIC_LOG_ENABLED` check). Instead, we detect NR via
+ *   `require.cache` — if the service already loaded NR, we reuse that instance.
+ *   If not, all NR calls silently no-op via the NOOP_NR stub.
+ *
+ * Resolution strategy:
+ *   1. Explicit: `init('svc', token, { newrelic: nrInstance })` — used by
+ *      kori (ESM + pnpm, where require.cache detection is unreliable) and
+ *      hsm-backend (conditional NR loading).
+ *   2. Module cache: `require.cache[require.resolve('newrelic')]` — works for
+ *      CJS services (combee, gpt-intentions, cb-proxy) where NR is loaded at
+ *      the top of the entry file before the bridge initializes.
+ *   3. Fallback: NOOP_NR stub that returns empty trace metadata and calls
+ *      handler functions directly without creating background transactions.
+ *
+ * Edge cases covered:
+ *   - `require.resolve('newrelic')` throws if newrelic is not installed at all.
+ *     Caught silently — returns NOOP_NR.
+ *   - NR's stub API (agent disabled via config) returns `{ traceId: '', spanId: '' }`
+ *     from `getTraceMetadata()` — our code treats empty strings as "no trace,"
+ *     so buildTraceparent() returns undefined. No crash.
+ *   - `startBackgroundTransaction` in the stub just calls the handler directly
+ *     and returns its result, preserving async/await flow.
+ *   - Once resolved, the NR instance is cached so subsequent calls to `getNr()`
+ *     don't re-probe the module cache.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveNewRelic = resolveNewRelic;
+exports.getNr = getNr;
+exports.isNrLoaded = isNrLoaded;
+const NOOP_NR = {
+    getTransaction: () => null,
+    startBackgroundTransaction: (_name, _group, handler) => typeof handler === 'function' ? handler() : undefined,
+    getTraceMetadata: () => ({ traceId: '', spanId: '' }),
+    acceptDistributedTraceHeaders: () => undefined,
+};
+let cachedNr = null;
+function resolveNewRelic(explicit) {
+    if (explicit) {
+        cachedNr = explicit;
+        return explicit;
+    }
+    if (cachedNr) {
+        return cachedNr;
+    }
+    try {
+        /* eslint-disable @typescript-eslint/no-require-imports */
+        const resolved = require.resolve('newrelic');
+        if (require.cache[resolved]) {
+            cachedNr = require('newrelic');
+            return cachedNr;
+        }
+        /* eslint-enable @typescript-eslint/no-require-imports */
+    }
+    catch {
+        // NR not available
+    }
+    return NOOP_NR;
+}
+function getNr() {
+    return cachedNr ?? NOOP_NR;
+}
+function isNrLoaded() {
+    return cachedNr !== null && cachedNr !== NOOP_NR;
+}

package/dist/node-cliengo/src/sns.d.ts

@@ -0,0 +1,19 @@
+/**
+ * SNS message attribute injection for trace propagation.
+ *
+ * Why this file exists:
+ *   combee publishes to the `cliengo-events` SNS topic with MessageAttributes
+ *   (triggerType, category, companyId, channel). To propagate trace context
+ *   across the SNS → SQS boundary, we need to add a `traceparent` attribute
+ *   alongside the existing ones. This function spread-merges it in.
+ *
+ * Edge cases covered:
+ *   - No active NR transaction (buildTraceparent returns undefined): the
+ *     original attributes are returned unchanged — no traceparent key added.
+ *   - Empty attrs {}: returns just { traceparent: ... } if NR is active,
+ *     or {} if not. Never crashes.
+ *   - Existing traceparent in attrs: overwritten with the current value
+ *     (spread puts our key last).
+ */
+import type { SnsMessageAttributeValue } from './types';
+export declare function injectSnsAttributes(attrs: Record<string, SnsMessageAttributeValue>): Record<string, SnsMessageAttributeValue>;

package/dist/node-cliengo/src/sns.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * SNS message attribute injection for trace propagation.
+ *
+ * Why this file exists:
+ *   combee publishes to the `cliengo-events` SNS topic with MessageAttributes
+ *   (triggerType, category, companyId, channel). To propagate trace context
+ *   across the SNS → SQS boundary, we need to add a `traceparent` attribute
+ *   alongside the existing ones. This function spread-merges it in.
+ *
+ * Edge cases covered:
+ *   - No active NR transaction (buildTraceparent returns undefined): the
+ *     original attributes are returned unchanged — no traceparent key added.
+ *   - Empty attrs {}: returns just { traceparent: ... } if NR is active,
+ *     or {} if not. Never crashes.
+ *   - Existing traceparent in attrs: overwritten with the current value
+ *     (spread puts our key last).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.injectSnsAttributes = injectSnsAttributes;
+const trace_bridge_1 = require("./trace-bridge");
+function injectSnsAttributes(attrs) {
+    const tp = (0, trace_bridge_1.buildTraceparent)();
+    if (!tp) {
+        return attrs;
+    }
+    return {
+        ...attrs,
+        traceparent: { DataType: 'String', StringValue: tp },
+    };
+}

package/dist/node-cliengo/src/sqs.d.ts

@@ -0,0 +1,35 @@
+/**
+ * SQS consumer wrapper — creates OTel spans and NR background transactions
+ * for every message processed from an SQS queue.
+ *
+ * Why this file exists:
+ *   SQS consumers (combee whatsapp-status, kori automation-events, hsm-backend
+ *   wa-meta) poll queues in a loop with no NR transaction context. This wrapper
+ *   creates both an NR background transaction (so NR sees the work) and an OTel
+ *   span on our non-global provider (so Foam sees the work). It also records
+ *   metrics (duration, error count, processed count) automatically.
+ *
+ * Dual delivery mode extraction:
+ *   SNS→SQS subscriptions have two modes that put traceparent in different places:
+ *   - RawMessageDelivery=true (kori): traceparent is in the SQS-level
+ *     `msg.MessageAttributes.traceparent.StringValue`
+ *   - RawMessageDelivery=false (combee, hsm-backend): traceparent is inside the
+ *     SNS envelope in `JSON.parse(msg.Body).MessageAttributes.traceparent.Value`
+ *     (note: `Value` not `StringValue` — different key format in SNS envelopes)
+ *   extractTraceparentFromMessage tries both locations.
+ *
+ * Edge cases covered:
+ *   - No traceparent anywhere: consumer creates a fresh trace (new traceId).
+ *     This is expected in Phase 1 when producers haven't been updated yet.
+ *   - Body is not valid JSON (non-SNS message): JSON.parse catch silently
+ *     falls through to return empty string.
+ *   - fn() throws: exception is recorded on the span (exception.type, message,
+ *     stacktrace), error metrics incremented, then error is re-thrown so the
+ *     service's own retry/DLQ logic is unaffected.
+ *   - NR not loaded: execute() runs without startBackgroundTransaction — OTel
+ *     span still created, metrics still recorded.
+ *   - metrics is undefined (inert bridge): all metrics?.xxx calls are no-ops.
+ */
+import { type Tracer } from '@opentelemetry/api';
+import type { BridgeMetrics, SqsMessage } from './types';
+export declare function wrapSqsConsumer(tracer: Tracer, spanName: string, msg: SqsMessage, fn: () => Promise<void>, metrics?: BridgeMetrics): Promise<void>;

package/dist/node-cliengo/src/sqs.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * SQS consumer wrapper — creates OTel spans and NR background transactions
+ * for every message processed from an SQS queue.
+ *
+ * Why this file exists:
+ *   SQS consumers (combee whatsapp-status, kori automation-events, hsm-backend
+ *   wa-meta) poll queues in a loop with no NR transaction context. This wrapper
+ *   creates both an NR background transaction (so NR sees the work) and an OTel
+ *   span on our non-global provider (so Foam sees the work). It also records
+ *   metrics (duration, error count, processed count) automatically.
+ *
+ * Dual delivery mode extraction:
+ *   SNS→SQS subscriptions have two modes that put traceparent in different places:
+ *   - RawMessageDelivery=true (kori): traceparent is in the SQS-level
+ *     `msg.MessageAttributes.traceparent.StringValue`
+ *   - RawMessageDelivery=false (combee, hsm-backend): traceparent is inside the
+ *     SNS envelope in `JSON.parse(msg.Body).MessageAttributes.traceparent.Value`
+ *     (note: `Value` not `StringValue` — different key format in SNS envelopes)
+ *   extractTraceparentFromMessage tries both locations.
+ *
+ * Edge cases covered:
+ *   - No traceparent anywhere: consumer creates a fresh trace (new traceId).
+ *     This is expected in Phase 1 when producers haven't been updated yet.
+ *   - Body is not valid JSON (non-SNS message): JSON.parse catch silently
+ *     falls through to return empty string.
+ *   - fn() throws: exception is recorded on the span (exception.type, message,
+ *     stacktrace), error metrics incremented, then error is re-thrown so the
+ *     service's own retry/DLQ logic is unaffected.
+ *   - NR not loaded: execute() runs without startBackgroundTransaction — OTel
+ *     span still created, metrics still recorded.
+ *   - metrics is undefined (inert bridge): all metrics?.xxx calls are no-ops.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapSqsConsumer = wrapSqsConsumer;
+const api_1 = require("@opentelemetry/api");
+const nr_1 = require("./nr");
+const trace_bridge_1 = require("./trace-bridge");
+function extractTraceparentFromMessage(msg) {
+    // Raw delivery — traceparent in SQS-level MessageAttributes
+    const raw = msg.MessageAttributes?.traceparent?.StringValue;
+    if (raw) {
+        return raw;
+    }
+    // Non-raw (SNS-wrapped) — traceparent inside the SNS envelope in Body
+    if (msg.Body) {
+        try {
+            const body = JSON.parse(msg.Body);
+            const envelope = body.MessageAttributes?.traceparent?.Value;
+            if (envelope) {
+                return envelope;
+            }
+        }
+        catch {
+            // Body is not JSON or doesn't have SNS envelope — no traceparent
+        }
+    }
+    return '';
+}
+async function wrapSqsConsumer(tracer, spanName, msg, fn, metrics) {
+    const nr = (0, nr_1.getNr)();
+    const traceparent = extractTraceparentFromMessage(msg);
+    const parentCtx = traceparent ? (0, trace_bridge_1.extractParentContext)(traceparent) : undefined;
+    const headers = {};
+    if (traceparent) {
+        headers.traceparent = traceparent;
+    }
+    const execute = async () => {
+        nr.acceptDistributedTraceHeaders?.('Queue', headers);
+        const span = tracer.startSpan(spanName, {
+            attributes: {
+                'messaging.system': 'aws.sqs',
+                'messaging.operation': 'process',
+                'messaging.message.id': msg.MessageId ?? '',
+            },
+        }, parentCtx);
+        const start = Date.now();
+        try {
+            await fn();
+            span.setStatus({ code: api_1.SpanStatusCode.OK });
+            metrics?.messagesProcessed.add(1, { queue: spanName, status: 'success' });
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: error.message });
+            span.recordException({
+                name: error.constructor.name,
+                message: error.message,
+                stack: error.stack,
+            });
+            metrics?.messageProcessingErrors.add(1, {
+                queue: spanName,
+                'error.type': error.constructor.name,
+            });
+            metrics?.messagesProcessed.add(1, { queue: spanName, status: 'error' });
+            throw err;
+        }
+        finally {
+            const duration = Date.now() - start;
+            metrics?.messageProcessingDuration.record(duration, { queue: spanName });
+            span.end();
+        }
+    };
+    if (nr.startBackgroundTransaction) {
+        await nr.startBackgroundTransaction(spanName, 'QueueConsumer', execute);
+    }
+    else {
+        await execute();
+    }
+}

package/dist/node-cliengo/src/trace-bridge.d.ts

@@ -0,0 +1,39 @@
+/**
+ * W3C trace context bridge between New Relic and OpenTelemetry.
+ *
+ * Why this file exists:
+ *   NR owns the active trace (it creates transactions via http monkey-patching),
+ *   but our OTel spans need to share the same traceId so Foam and NR traces
+ *   correlate. This module reads NR's trace metadata and converts it to/from
+ *   W3C traceparent format (`00-{traceId}-{spanId}-{flags}`).
+ *
+ * Functions:
+ *   - buildTraceparent(): reads NR's active traceId/spanId, returns a W3C
+ *     traceparent string. Used by producers to inject into SNS attributes or
+ *     BullMQ/Bull job data. Returns undefined when NR is not loaded or no
+ *     active transaction exists.
+ *   - extractParentContext(): parses a traceparent string into an OTel Context
+ *     with a remote SpanContext. Used by consumers to link their OTel spans
+ *     back to the producer's trace. Returns ROOT_CONTEXT on malformed input.
+ *   - getTraceContext(): returns { traceId, spanId, traceparent } for log
+ *     enrichment. Called lazily at log-write time (not at format creation time)
+ *     so the trace context is always current.
+ *
+ * Edge cases covered:
+ *   - NR not loaded: getTraceMetadata() returns undefined — we default to
+ *     empty strings, buildTraceparent returns undefined, getTraceContext
+ *     returns empty strings. No crash.
+ *   - NR loaded but no active transaction: traceId/spanId are empty strings.
+ *     buildTraceparent returns undefined. Consumers create a fresh trace.
+ *   - Malformed traceparent (wrong number of parts, wrong hex lengths):
+ *     extractParentContext returns ROOT_CONTEXT — consumer creates a fresh
+ *     trace instead of crashing.
+ *   - Flags field always set to 01 (sampled) on buildTraceparent because we
+ *     want all async boundary crossings traced.
+ */
+import { type Context } from '@opentelemetry/api';
+import type { TraceContext } from './types';
+export declare function buildTraceparent(): string | undefined;
+export declare function extractParentContext(traceparent: string): Context;
+export declare function getTraceContext(): TraceContext;
+export declare function getActiveContext(): Context;