@frontmcp/observability 1.1.2 → 1.2.1

package/esm/index.mjs

@@ -319,7 +319,7 @@ var init_otlp_sink = __esm({
 });
 
 // libs/observability/src/plugin/observability.plugin.ts
-import { trace as trace5 } from "@opentelemetry/api";
+import { trace as trace6 } from "@opentelemetry/api";
 import {
   AgentCallHook,
   DynamicPlugin,
@@ -770,43 +770,6 @@ import {
   trace as trace4
 } from "@opentelemetry/api";
 
-// libs/observability/src/otel/trace-context-bridge.ts
-import {
-  TraceFlags,
-  trace,
-  context as otelContext
-} from "@opentelemetry/api";
-function frontmcpToOTelSpanContext(tc) {
-  return {
-    traceId: tc.traceId,
-    spanId: tc.parentId,
-    traceFlags: tc.traceFlags & TraceFlags.SAMPLED ? TraceFlags.SAMPLED : TraceFlags.NONE,
-    isRemote: true
-  };
-}
-function otelToFrontmcpContext(sc) {
-  const flags = sc.traceFlags.toString(16).padStart(2, "0");
-  return {
-    traceId: sc.traceId,
-    parentId: sc.spanId,
-    traceFlags: sc.traceFlags,
-    raw: `00-${sc.traceId}-${sc.spanId}-${flags}`
-  };
-}
-function createOTelContextFromTrace(tc) {
-  const spanContext = frontmcpToOTelSpanContext(tc);
-  const span = trace.wrapSpanContext(spanContext);
-  return trace.setSpan(otelContext.active(), span);
-}
-
-// libs/observability/src/plugin/observability.hooks.ts
-import {
-  context as otelContext3,
-  SpanKind as SpanKind11,
-  trace as trace3
-} from "@opentelemetry/api";
-import { sha256Hex } from "@frontmcp/utils";
-
 // libs/observability/src/otel/otel.types.ts
 var McpAttributes = {
   /** MCP protocol method name (e.g., "tools/call", "resources/read") */
@@ -920,6 +883,43 @@ var EnduserAttributes = {
   SCOPE: "enduser.scope"
 };
 
+// libs/observability/src/otel/trace-context-bridge.ts
+import {
+  TraceFlags,
+  trace,
+  context as otelContext
+} from "@opentelemetry/api";
+function frontmcpToOTelSpanContext(tc) {
+  return {
+    traceId: tc.traceId,
+    spanId: tc.parentId,
+    traceFlags: tc.traceFlags & TraceFlags.SAMPLED ? TraceFlags.SAMPLED : TraceFlags.NONE,
+    isRemote: true
+  };
+}
+function otelToFrontmcpContext(sc) {
+  const flags = sc.traceFlags.toString(16).padStart(2, "0");
+  return {
+    traceId: sc.traceId,
+    parentId: sc.spanId,
+    traceFlags: sc.traceFlags,
+    raw: `00-${sc.traceId}-${sc.spanId}-${flags}`
+  };
+}
+function createOTelContextFromTrace(tc) {
+  const spanContext = frontmcpToOTelSpanContext(tc);
+  const span = trace.wrapSpanContext(spanContext);
+  return trace.setSpan(otelContext.active(), span);
+}
+
+// libs/observability/src/plugin/observability.hooks.ts
+import {
+  context as otelContext3,
+  SpanKind as SpanKind11,
+  trace as trace3
+} from "@opentelemetry/api";
+import { sha256Hex } from "@frontmcp/utils";
+
 // libs/observability/src/otel/spans/auth.span.ts
 import { SpanKind as SpanKind2 } from "@opentelemetry/api";
 
@@ -1698,6 +1698,97 @@ function reportStartup(data) {
   emitStartupReport(tracer, data);
 }
 
+// libs/observability/src/telemetry/telemetry.counters.ts
+import { metrics } from "@opentelemetry/api";
+function snapshotKey(name, attributes) {
+  const keys = Object.keys(attributes).sort();
+  if (keys.length === 0) return name;
+  const tail = keys.map((k) => `${k}=${attributes[k]}`).join(",");
+  return `${name}{${tail}}`;
+}
+var snapshotStore = /* @__PURE__ */ new Map();
+var TelemetryCounterImpl = class {
+  constructor(name, otelCounter) {
+    this.name = name;
+    this.otelCounter = otelCounter;
+  }
+  inc(by = 1, attributes = {}) {
+    if (!Number.isFinite(by) || by < 0) {
+      return;
+    }
+    try {
+      this.otelCounter.add(by, attributes);
+    } catch {
+    }
+    const key = snapshotKey(this.name, attributes);
+    const existing = snapshotStore.get(key);
+    if (existing) {
+      existing.count += by;
+    } else {
+      snapshotStore.set(key, { name: this.name, count: by, attributes: { ...attributes } });
+    }
+  }
+};
+var METER_NAME = "@frontmcp/observability";
+var counterCache = /* @__PURE__ */ new Map();
+function createCounter(name, description) {
+  const existing = counterCache.get(name);
+  if (existing) return existing;
+  const meter = metrics.getMeter(METER_NAME);
+  const otelCounter = meter.createCounter(name, description ? { description } : void 0);
+  const counter = new TelemetryCounterImpl(name, otelCounter);
+  counterCache.set(name, counter);
+  return counter;
+}
+function getMetricSnapshot() {
+  return Array.from(snapshotStore.values()).map((entry) => ({
+    name: entry.name,
+    count: entry.count,
+    attributes: { ...entry.attributes }
+  }));
+}
+function getCounterTotal(name) {
+  let sum = 0;
+  for (const entry of snapshotStore.values()) {
+    if (entry.name === name) sum += entry.count;
+  }
+  return sum;
+}
+function resetMetricSnapshot() {
+  snapshotStore.clear();
+}
+function resetTelemetrySnapshotForTesting() {
+  snapshotStore.clear();
+}
+function resetCounterCacheForTesting() {
+  counterCache.clear();
+}
+var KNOWN_BUNDLE_SOURCES = ["static", "npm", "saas-pull", "webhook", "filesystem", "unknown"];
+function normalizeBundleSource(value) {
+  if (typeof value !== "string") return "unknown";
+  return KNOWN_BUNDLE_SOURCES.includes(value) ? value : "unknown";
+}
+var KNOWN_ERROR_REASONS = ["network", "timeout", "invalid_response", "parse_error", "unknown"];
+function normalizeErrorReason(err) {
+  if (!err) return "unknown";
+  const name = err instanceof Error ? err.name : "";
+  const message = err instanceof Error ? err.message : typeof err === "string" ? err : "";
+  const haystack = `${name} ${message}`.toLowerCase();
+  if (name === "TimeoutError" || haystack.includes("timeout") || haystack.includes("timed out")) {
+    return "timeout";
+  }
+  if (name === "NetworkError" || name === "FetchError" || haystack.includes("network") || haystack.includes("econnrefused") || haystack.includes("econnreset") || haystack.includes("enotfound") || haystack.includes("socket") || haystack.includes("dns")) {
+    return "network";
+  }
+  if (name === "SyntaxError" || haystack.includes("parse") || haystack.includes("json")) {
+    return "parse_error";
+  }
+  if (name === "TypeError" || name === "RangeError" || haystack.includes("invalid") || haystack.includes("malformed") || haystack.includes("schema")) {
+    return "invalid_response";
+  }
+  return "unknown";
+}
+
 // libs/observability/src/telemetry/telemetry.accessor.ts
 var TelemetrySpan = class {
   constructor(span) {
@@ -1855,6 +1946,20 @@ var TelemetryAccessor = class {
       activeSpan.setAttributes(attrs);
     }
   }
+  /**
+   * Create (or retrieve cached) a named counter.
+   *
+   * Counter increments are exported through the global OTel MeterProvider
+   * when one is configured, and are always recorded in an in-memory snapshot
+   * store (`getMetricSnapshot()` from `@frontmcp/observability`) so tests can
+   * assert behavior without standing up a full OTel pipeline.
+   *
+   * @param name        - OTel-style snake_case name, e.g. `frontmcp_skills_bundle_pulls_total`
+   * @param description - human-readable description
+   */
+  createCounter(name, description) {
+    return createCounter(name, description);
+  }
   /**
    * Get the trace ID of the current request.
    * Useful for including in external API calls or logs.
@@ -1870,8 +1975,55 @@ var TelemetryAccessor = class {
   }
 };
 
+// libs/observability/src/telemetry/telemetry.factory.ts
+import { SpanStatusCode as SpanStatusCode3, trace as trace5 } from "@opentelemetry/api";
+var TelemetryFactory = class {
+  constructor(tracerName = "@frontmcp/observability") {
+    this.tracer = trace5.getTracer(tracerName);
+  }
+  /**
+   * Create (or retrieve cached) a named counter. Increments propagate to
+   * the OTel meter (when configured) and to the in-memory snapshot store.
+   *
+   * @param name        - OTel-style snake_case name with `_total` suffix.
+   * @param description - human-readable description (deduped: subsequent
+   *                      calls with a different description return the
+   *                      cached counter unchanged).
+   */
+  createCounter(name, description) {
+    return createCounter(name, description);
+  }
+  /**
+   * Start a span. Caller is responsible for calling `end()` /
+   * `endWithError()`. The span parents to the currently-active OTel
+   * context; if none is active it becomes a root span.
+   */
+  startSpan(name, attributes, parent) {
+    const opts = attributes ? { attributes } : void 0;
+    const span = parent ? this.tracer.startSpan(name, opts, parent) : this.tracer.startSpan(name, opts);
+    return new TelemetrySpan(span);
+  }
+  /**
+   * Convenience wrapper — start a span, run `fn` with it, end on success
+   * or error. Same lifecycle as `TelemetryAccessor.withSpan` but without
+   * the per-request base attributes.
+   */
+  async withSpan(name, fn, attributes) {
+    const span = this.startSpan(name, attributes);
+    try {
+      const result = await fn(span);
+      span.end();
+      return result;
+    } catch (err) {
+      span.endWithError(err instanceof Error ? err : String(err));
+      throw err;
+    }
+  }
+};
+
 // libs/observability/src/telemetry/telemetry.tokens.ts
 var TELEMETRY_ACCESSOR = /* @__PURE__ */ Symbol.for("frontmcp:observability:telemetry-accessor");
+var TELEMETRY_FACTORY = /* @__PURE__ */ Symbol.for("frontmcp:observability:telemetry-factory");
 
 // libs/observability/src/plugin/observability.plugin.ts
 var PromptHook = FlowHooksOf("prompts:get-prompt");
@@ -2305,7 +2457,7 @@ ObservabilityPlugin.dynamicProviders = (input) => {
     providers.push({
       name: "observability:tracer",
       provide: OTEL_TRACER,
-      useValue: trace5.getTracer("@frontmcp/observability")
+      useValue: trace6.getTracer("@frontmcp/observability")
     });
     providers.push({
       name: "observability:config",
@@ -2319,6 +2471,11 @@ ObservabilityPlugin.dynamicProviders = (input) => {
       inject: () => [FRONTMCP_CONTEXT],
       useFactory: (ctx) => new TelemetryAccessor(ctx)
     });
+    providers.push({
+      name: "observability:telemetry-factory",
+      provide: TELEMETRY_FACTORY,
+      useValue: new TelemetryFactory()
+    });
   }
   if (options.logging !== false) {
     const loggingOpts = options.logging;
@@ -2756,12 +2913,12 @@ function resolveRequestLogOptions(input) {
 
 // libs/observability/src/otel/context-propagator.ts
 import {
-  trace as trace6
+  trace as trace7
 } from "@opentelemetry/api";
 var TRACEPARENT_HEADER = "traceparent";
 var FrontMcpPropagator = class {
   inject(context, carrier, setter) {
-    const span = trace6.getSpan(context);
+    const span = trace7.getSpan(context);
     if (!span) return;
     const sc = span.spanContext();
     if (!sc || !isValidSpanContext(sc)) return;
@@ -2781,8 +2938,8 @@ var FrontMcpPropagator = class {
       traceFlags: parsed.traceFlags,
       isRemote: true
     };
-    const span = trace6.wrapSpanContext(spanContext);
-    return trace6.setSpan(context, span);
+    const span = trace7.wrapSpanContext(spanContext);
+    return trace7.setSpan(context, span);
   }
   fields() {
     return [TRACEPARENT_HEADER];
@@ -2877,7 +3034,7 @@ function startHookSpan(tracer, options) {
 }
 
 // libs/observability/src/otel/spans/pretty-span-exporter.ts
-import { SpanKind as SpanKind14, SpanStatusCode as SpanStatusCode3 } from "@opentelemetry/api";
+import { SpanKind as SpanKind14, SpanStatusCode as SpanStatusCode4 } from "@opentelemetry/api";
 var RESET = "\x1B[0m";
 var DIM = "\x1B[2m";
 var BOLD = "\x1B[1m";
@@ -2929,7 +3086,7 @@ var PrettySpanExporter = class {
     const traceShort = span.spanContext().traceId.slice(0, 8);
     const durationMs = (span.duration[0] * 1e3 + span.duration[1] / 1e6).toFixed(1);
     const kind = KIND_LABELS[span.kind] ?? "UNKNOWN";
-    const statusOk = span.status.code !== SpanStatusCode3.ERROR;
+    const statusOk = span.status.code !== SpanStatusCode4.ERROR;
     const attrs = Object.entries(span.attributes).filter(([k]) => SHOW_ATTRS.has(k)).map(([k, v]) => {
       const short = k.replace("frontmcp.", "").replace("mcp.", "");
       return `${short}=${v}`;
@@ -3013,6 +3170,8 @@ export {
   FrontMcpAttributes,
   FrontMcpPropagator,
   HttpAttributes,
+  KNOWN_BUNDLE_SOURCES,
+  KNOWN_ERROR_REASONS,
   LOG_LEVEL_TO_OTEL_SEVERITY,
   McpAttributes,
   OTEL_CONFIG,
@@ -3027,11 +3186,14 @@ export {
   StdoutSink,
   StructuredLogTransport,
   TELEMETRY_ACCESSOR,
+  TELEMETRY_FACTORY,
   TelemetryAccessor,
+  TelemetryFactory,
   TelemetrySpan,
   WinstonSink,
   assertSpanAttribute,
   assertSpanExists,
+  createCounter,
   createOTelContextFromTrace,
   createSink,
   createSinks,
@@ -3042,11 +3204,18 @@ export {
   findSpan,
   findSpansByAttribute,
   frontmcpToOTelSpanContext,
+  getCounterTotal,
   getFinishedSpans,
+  getMetricSnapshot,
+  normalizeBundleSource,
+  normalizeErrorReason,
   otelToFrontmcpContext,
   recordHookEvent,
   redactFields,
   reportStartup,
+  resetCounterCacheForTesting,
+  resetMetricSnapshot,
+  resetTelemetrySnapshotForTesting,
   sessionTracingId,
   setAuthMode,
   setAuthResult,

package/esm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/observability",
-  "version": "1.1.2",
+  "version": "1.2.1",
   "description": "OpenTelemetry instrumentation, structured JSON logging, and request log objects for FrontMCP",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -51,8 +51,8 @@
     "@opentelemetry/api": "^1.9.0"
   },
   "peerDependencies": {
-    "@frontmcp/sdk": "1.1.2",
-    "@frontmcp/utils": "1.1.2",
+    "@frontmcp/sdk": "1.2.1",
+    "@frontmcp/utils": "1.2.1",
     "@opentelemetry/sdk-trace-base": "^1.25.0",
     "@opentelemetry/sdk-node": "^0.52.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.52.0",

package/index.d.ts

@@ -4,7 +4,8 @@ export { McpAttributes, FrontMcpAttributes, HttpAttributes, RpcAttributes, Endus
 export type { TracingOptions, OTelSetupOptions, TraceContextLike, StartSpanOptions, HttpServerSpanOptions, RpcSpanOptions, ToolSpanOptions, ResourceSpanOptions, PromptSpanOptions, HookSpanOptions, FetchSpanOptions, TransportSpanOptions, AuthSpanOptions, StartupTelemetryData, } from './otel';
 export { StructuredLogTransport, LOG_LEVEL_TO_OTEL_SEVERITY, StdoutSink, ConsoleSink, WinstonSink, PinoSink, CallbackSink, OtlpSink, createSink, createSinks, redactFields, } from './logging';
 export type { StructuredLogEntry, StructuredLogError, StructuredLogTransportOptions, LogSink, SinkConfig, StdoutSinkConfig, ConsoleSinkConfig, WinstonSinkConfig, PinoSinkConfig, CallbackSinkConfig, OtlpSinkConfig, OtlpSinkOptions, WinstonLike, PinoLike, ContextAccessor, ContextSnapshot, } from './logging';
-export { TelemetryAccessor, TelemetrySpan, TELEMETRY_ACCESSOR } from './telemetry';
+export { TelemetryAccessor, TelemetrySpan, TelemetryFactory, TELEMETRY_ACCESSOR, TELEMETRY_FACTORY, createCounter, getMetricSnapshot, getCounterTotal, resetMetricSnapshot, resetTelemetrySnapshotForTesting, resetCounterCacheForTesting, normalizeBundleSource, normalizeErrorReason, KNOWN_BUNDLE_SOURCES, KNOWN_ERROR_REASONS, } from './telemetry';
+export type { TelemetryCounter, CounterSnapshotEntry, KnownBundleSource, KnownErrorReason } from './telemetry';
 export { createTestTracer, getFinishedSpans, assertSpanExists, assertSpanAttribute, findSpan, findSpansByAttribute, } from './testing';
 export type { TestTracer } from './testing';
 export { RequestLogCollector, REQUEST_LOG_COLLECTOR } from './request-log';

package/index.js

@@ -322,6 +322,8 @@ __export(index_exports, {
   FrontMcpAttributes: () => FrontMcpAttributes,
   FrontMcpPropagator: () => FrontMcpPropagator,
   HttpAttributes: () => HttpAttributes,
+  KNOWN_BUNDLE_SOURCES: () => KNOWN_BUNDLE_SOURCES,
+  KNOWN_ERROR_REASONS: () => KNOWN_ERROR_REASONS,
   LOG_LEVEL_TO_OTEL_SEVERITY: () => LOG_LEVEL_TO_OTEL_SEVERITY,
   McpAttributes: () => McpAttributes,
   OTEL_CONFIG: () => OTEL_CONFIG,
@@ -336,11 +338,14 @@ __export(index_exports, {
   StdoutSink: () => StdoutSink,
   StructuredLogTransport: () => StructuredLogTransport,
   TELEMETRY_ACCESSOR: () => TELEMETRY_ACCESSOR,
+  TELEMETRY_FACTORY: () => TELEMETRY_FACTORY,
   TelemetryAccessor: () => TelemetryAccessor,
+  TelemetryFactory: () => TelemetryFactory,
   TelemetrySpan: () => TelemetrySpan,
   WinstonSink: () => WinstonSink,
   assertSpanAttribute: () => assertSpanAttribute,
   assertSpanExists: () => assertSpanExists,
+  createCounter: () => createCounter,
   createOTelContextFromTrace: () => createOTelContextFromTrace,
   createSink: () => createSink,
   createSinks: () => createSinks,
@@ -351,11 +356,18 @@ __export(index_exports, {
   findSpan: () => findSpan,
   findSpansByAttribute: () => findSpansByAttribute,
   frontmcpToOTelSpanContext: () => frontmcpToOTelSpanContext,
+  getCounterTotal: () => getCounterTotal,
   getFinishedSpans: () => getFinishedSpans,
+  getMetricSnapshot: () => getMetricSnapshot,
+  normalizeBundleSource: () => normalizeBundleSource,
+  normalizeErrorReason: () => normalizeErrorReason,
   otelToFrontmcpContext: () => otelToFrontmcpContext,
   recordHookEvent: () => recordHookEvent,
   redactFields: () => redactFields,
   reportStartup: () => reportStartup,
+  resetCounterCacheForTesting: () => resetCounterCacheForTesting,
+  resetMetricSnapshot: () => resetMetricSnapshot,
+  resetTelemetrySnapshotForTesting: () => resetTelemetrySnapshotForTesting,
   sessionTracingId: () => sessionTracingId,
   setAuthMode: () => setAuthMode,
   setAuthResult: () => setAuthResult,
@@ -378,7 +390,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // libs/observability/src/plugin/observability.plugin.ts
-var import_api14 = require("@opentelemetry/api");
+var import_api16 = require("@opentelemetry/api");
 var import_sdk2 = require("@frontmcp/sdk");
 
 // libs/observability/src/logging/sinks/stdout.sink.ts
@@ -810,36 +822,7 @@ var RequestLogCollector = class {
 var REQUEST_LOG_COLLECTOR = /* @__PURE__ */ Symbol.for("frontmcp:observability:request-log-collector");
 
 // libs/observability/src/telemetry/telemetry.accessor.ts
-var import_api13 = require("@opentelemetry/api");
-
-// libs/observability/src/otel/trace-context-bridge.ts
-var import_api = require("@opentelemetry/api");
-function frontmcpToOTelSpanContext(tc) {
-  return {
-    traceId: tc.traceId,
-    spanId: tc.parentId,
-    traceFlags: tc.traceFlags & import_api.TraceFlags.SAMPLED ? import_api.TraceFlags.SAMPLED : import_api.TraceFlags.NONE,
-    isRemote: true
-  };
-}
-function otelToFrontmcpContext(sc) {
-  const flags = sc.traceFlags.toString(16).padStart(2, "0");
-  return {
-    traceId: sc.traceId,
-    parentId: sc.spanId,
-    traceFlags: sc.traceFlags,
-    raw: `00-${sc.traceId}-${sc.spanId}-${flags}`
-  };
-}
-function createOTelContextFromTrace(tc) {
-  const spanContext = frontmcpToOTelSpanContext(tc);
-  const span = import_api.trace.wrapSpanContext(spanContext);
-  return import_api.trace.setSpan(import_api.context.active(), span);
-}
-
-// libs/observability/src/plugin/observability.hooks.ts
-var import_api12 = require("@opentelemetry/api");
-var import_utils = require("@frontmcp/utils");
+var import_api14 = require("@opentelemetry/api");
 
 // libs/observability/src/otel/otel.types.ts
 var McpAttributes = {
@@ -954,6 +937,35 @@ var EnduserAttributes = {
   SCOPE: "enduser.scope"
 };
 
+// libs/observability/src/otel/trace-context-bridge.ts
+var import_api = require("@opentelemetry/api");
+function frontmcpToOTelSpanContext(tc) {
+  return {
+    traceId: tc.traceId,
+    spanId: tc.parentId,
+    traceFlags: tc.traceFlags & import_api.TraceFlags.SAMPLED ? import_api.TraceFlags.SAMPLED : import_api.TraceFlags.NONE,
+    isRemote: true
+  };
+}
+function otelToFrontmcpContext(sc) {
+  const flags = sc.traceFlags.toString(16).padStart(2, "0");
+  return {
+    traceId: sc.traceId,
+    parentId: sc.spanId,
+    traceFlags: sc.traceFlags,
+    raw: `00-${sc.traceId}-${sc.spanId}-${flags}`
+  };
+}
+function createOTelContextFromTrace(tc) {
+  const spanContext = frontmcpToOTelSpanContext(tc);
+  const span = import_api.trace.wrapSpanContext(spanContext);
+  return import_api.trace.setSpan(import_api.context.active(), span);
+}
+
+// libs/observability/src/plugin/observability.hooks.ts
+var import_api12 = require("@opentelemetry/api");
+var import_utils = require("@frontmcp/utils");
+
 // libs/observability/src/otel/spans/auth.span.ts
 var import_api3 = require("@opentelemetry/api");
 
@@ -1727,6 +1739,97 @@ function reportStartup(data) {
   emitStartupReport(tracer, data);
 }
 
+// libs/observability/src/telemetry/telemetry.counters.ts
+var import_api13 = require("@opentelemetry/api");
+function snapshotKey(name, attributes) {
+  const keys = Object.keys(attributes).sort();
+  if (keys.length === 0) return name;
+  const tail = keys.map((k) => `${k}=${attributes[k]}`).join(",");
+  return `${name}{${tail}}`;
+}
+var snapshotStore = /* @__PURE__ */ new Map();
+var TelemetryCounterImpl = class {
+  constructor(name, otelCounter) {
+    this.name = name;
+    this.otelCounter = otelCounter;
+  }
+  inc(by = 1, attributes = {}) {
+    if (!Number.isFinite(by) || by < 0) {
+      return;
+    }
+    try {
+      this.otelCounter.add(by, attributes);
+    } catch {
+    }
+    const key = snapshotKey(this.name, attributes);
+    const existing = snapshotStore.get(key);
+    if (existing) {
+      existing.count += by;
+    } else {
+      snapshotStore.set(key, { name: this.name, count: by, attributes: { ...attributes } });
+    }
+  }
+};
+var METER_NAME = "@frontmcp/observability";
+var counterCache = /* @__PURE__ */ new Map();
+function createCounter(name, description) {
+  const existing = counterCache.get(name);
+  if (existing) return existing;
+  const meter = import_api13.metrics.getMeter(METER_NAME);
+  const otelCounter = meter.createCounter(name, description ? { description } : void 0);
+  const counter = new TelemetryCounterImpl(name, otelCounter);
+  counterCache.set(name, counter);
+  return counter;
+}
+function getMetricSnapshot() {
+  return Array.from(snapshotStore.values()).map((entry) => ({
+    name: entry.name,
+    count: entry.count,
+    attributes: { ...entry.attributes }
+  }));
+}
+function getCounterTotal(name) {
+  let sum = 0;
+  for (const entry of snapshotStore.values()) {
+    if (entry.name === name) sum += entry.count;
+  }
+  return sum;
+}
+function resetMetricSnapshot() {
+  snapshotStore.clear();
+}
+function resetTelemetrySnapshotForTesting() {
+  snapshotStore.clear();
+}
+function resetCounterCacheForTesting() {
+  counterCache.clear();
+}
+var KNOWN_BUNDLE_SOURCES = ["static", "npm", "saas-pull", "webhook", "filesystem", "unknown"];
+function normalizeBundleSource(value) {
+  if (typeof value !== "string") return "unknown";
+  return KNOWN_BUNDLE_SOURCES.includes(value) ? value : "unknown";
+}
+var KNOWN_ERROR_REASONS = ["network", "timeout", "invalid_response", "parse_error", "unknown"];
+function normalizeErrorReason(err) {
+  if (!err) return "unknown";
+  const name = err instanceof Error ? err.name : "";
+  const message = err instanceof Error ? err.message : typeof err === "string" ? err : "";
+  const haystack = `${name} ${message}`.toLowerCase();
+  if (name === "TimeoutError" || haystack.includes("timeout") || haystack.includes("timed out")) {
+    return "timeout";
+  }
+  if (name === "NetworkError" || name === "FetchError" || haystack.includes("network") || haystack.includes("econnrefused") || haystack.includes("econnreset") || haystack.includes("enotfound") || haystack.includes("socket") || haystack.includes("dns")) {
+    return "network";
+  }
+  if (name === "SyntaxError" || haystack.includes("parse") || haystack.includes("json")) {
+    return "parse_error";
+  }
+  if (name === "TypeError" || name === "RangeError" || haystack.includes("invalid") || haystack.includes("malformed") || haystack.includes("schema")) {
+    return "invalid_response";
+  }
+  return "unknown";
+}
+
 // libs/observability/src/telemetry/telemetry.accessor.ts
 var TelemetrySpan = class {
   constructor(span) {
@@ -1751,14 +1854,14 @@ var TelemetrySpan = class {
   /** Record an error on this span */
   recordError(error) {
     this.span.recordException(error);
-    this.span.setStatus({ code: import_api13.SpanStatusCode.ERROR, message: error.message });
+    this.span.setStatus({ code: import_api14.SpanStatusCode.ERROR, message: error.message });
     this.hasError = true;
     return this;
   }
   /** End the span (preserves ERROR status if already set) */
   end() {
     if (!this.hasError) {
-      this.span.setStatus({ code: import_api13.SpanStatusCode.OK });
+      this.span.setStatus({ code: import_api14.SpanStatusCode.OK });
     }
     this.span.end();
   }
@@ -1766,7 +1869,7 @@ var TelemetrySpan = class {
   endWithError(error) {
     const msg = typeof error === "string" ? error : error.message;
     if (error instanceof Error) this.span.recordException(error);
-    this.span.setStatus({ code: import_api13.SpanStatusCode.ERROR, message: msg });
+    this.span.setStatus({ code: import_api14.SpanStatusCode.ERROR, message: msg });
     this.span.end();
   }
   /** Get the underlying OTel span (escape hatch) */
@@ -1777,7 +1880,7 @@ var TelemetrySpan = class {
 var TelemetryAccessor = class {
   constructor(ctx) {
     this.ctx = ctx;
-    this.tracer = import_api13.trace.getTracer("@frontmcp/observability");
+    this.tracer = import_api14.trace.getTracer("@frontmcp/observability");
     this.fallbackContext = createOTelContextFromTrace(ctx.traceContext);
     this.sessionHash = sessionTracingId(ctx.sessionId);
     this.baseAttributes = {
@@ -1813,7 +1916,7 @@ var TelemetryAccessor = class {
     const span = this.tracer.startSpan(
       name,
       {
-        kind: import_api13.SpanKind.INTERNAL,
+        kind: import_api14.SpanKind.INTERNAL,
         attributes: { ...this.baseAttributes, ...attributes }
       },
       this.getActiveContext()
@@ -1862,11 +1965,11 @@ var TelemetryAccessor = class {
     } else {
       const span = this.tracer.startSpan(
         name,
-        { kind: import_api13.SpanKind.INTERNAL, attributes: this.baseAttributes },
+        { kind: import_api14.SpanKind.INTERNAL, attributes: this.baseAttributes },
         this.fallbackContext
       );
       if (attributes) span.addEvent(name, attributes);
-      span.setStatus({ code: import_api13.SpanStatusCode.OK });
+      span.setStatus({ code: import_api14.SpanStatusCode.OK });
       span.end();
     }
   }
@@ -1884,12 +1987,26 @@ var TelemetryAccessor = class {
       activeSpan.setAttributes(attrs);
     }
   }
+  /**
+   * Create (or retrieve cached) a named counter.
+   *
+   * Counter increments are exported through the global OTel MeterProvider
+   * when one is configured, and are always recorded in an in-memory snapshot
+   * store (`getMetricSnapshot()` from `@frontmcp/observability`) so tests can
+   * assert behavior without standing up a full OTel pipeline.
+   *
+   * @param name        - OTel-style snake_case name, e.g. `frontmcp_skills_bundle_pulls_total`
+   * @param description - human-readable description
+   */
+  createCounter(name, description) {
+    return createCounter(name, description);
+  }
   /**
    * Get the trace ID of the current request.
    * Useful for including in external API calls or logs.
    */
   get traceId() {
-    return import_api13.trace.getSpan(this.fallbackContext)?.spanContext().traceId ?? "";
+    return import_api14.trace.getSpan(this.fallbackContext)?.spanContext().traceId ?? "";
   }
   /**
    * Get the session tracing ID (privacy-safe hash).
@@ -1899,8 +2016,55 @@ var TelemetryAccessor = class {
   }
 };
 
+// libs/observability/src/telemetry/telemetry.factory.ts
+var import_api15 = require("@opentelemetry/api");
+var TelemetryFactory = class {
+  constructor(tracerName = "@frontmcp/observability") {
+    this.tracer = import_api15.trace.getTracer(tracerName);
+  }
+  /**
+   * Create (or retrieve cached) a named counter. Increments propagate to
+   * the OTel meter (when configured) and to the in-memory snapshot store.
+   *
+   * @param name        - OTel-style snake_case name with `_total` suffix.
+   * @param description - human-readable description (deduped: subsequent
+   *                      calls with a different description return the
+   *                      cached counter unchanged).
+   */
+  createCounter(name, description) {
+    return createCounter(name, description);
+  }
+  /**
+   * Start a span. Caller is responsible for calling `end()` /
+   * `endWithError()`. The span parents to the currently-active OTel
+   * context; if none is active it becomes a root span.
+   */
+  startSpan(name, attributes, parent) {
+    const opts = attributes ? { attributes } : void 0;
+    const span = parent ? this.tracer.startSpan(name, opts, parent) : this.tracer.startSpan(name, opts);
+    return new TelemetrySpan(span);
+  }
+  /**
+   * Convenience wrapper — start a span, run `fn` with it, end on success
+   * or error. Same lifecycle as `TelemetryAccessor.withSpan` but without
+   * the per-request base attributes.
+   */
+  async withSpan(name, fn, attributes) {
+    const span = this.startSpan(name, attributes);
+    try {
+      const result = await fn(span);
+      span.end();
+      return result;
+    } catch (err) {
+      span.endWithError(err instanceof Error ? err : String(err));
+      throw err;
+    }
+  }
+};
+
 // libs/observability/src/telemetry/telemetry.tokens.ts
 var TELEMETRY_ACCESSOR = /* @__PURE__ */ Symbol.for("frontmcp:observability:telemetry-accessor");
+var TELEMETRY_FACTORY = /* @__PURE__ */ Symbol.for("frontmcp:observability:telemetry-factory");
 
 // libs/observability/src/plugin/observability.plugin.ts
 var PromptHook = (0, import_sdk2.FlowHooksOf)("prompts:get-prompt");
@@ -2334,7 +2498,7 @@ ObservabilityPlugin.dynamicProviders = (input) => {
     providers.push({
       name: "observability:tracer",
       provide: OTEL_TRACER,
-      useValue: import_api14.trace.getTracer("@frontmcp/observability")
+      useValue: import_api16.trace.getTracer("@frontmcp/observability")
     });
     providers.push({
       name: "observability:config",
@@ -2348,6 +2512,11 @@ ObservabilityPlugin.dynamicProviders = (input) => {
       inject: () => [import_sdk2.FRONTMCP_CONTEXT],
       useFactory: (ctx) => new TelemetryAccessor(ctx)
     });
+    providers.push({
+      name: "observability:telemetry-factory",
+      provide: TELEMETRY_FACTORY,
+      useValue: new TelemetryFactory()
+    });
   }
   if (options.logging !== false) {
     const loggingOpts = options.logging;
@@ -2784,11 +2953,11 @@ function resolveRequestLogOptions(input) {
 }
 
 // libs/observability/src/otel/context-propagator.ts
-var import_api15 = require("@opentelemetry/api");
+var import_api17 = require("@opentelemetry/api");
 var TRACEPARENT_HEADER = "traceparent";
 var FrontMcpPropagator = class {
   inject(context, carrier, setter) {
-    const span = import_api15.trace.getSpan(context);
+    const span = import_api17.trace.getSpan(context);
     if (!span) return;
     const sc = span.spanContext();
     if (!sc || !isValidSpanContext(sc)) return;
@@ -2808,8 +2977,8 @@ var FrontMcpPropagator = class {
       traceFlags: parsed.traceFlags,
       isRemote: true
     };
-    const span = import_api15.trace.wrapSpanContext(spanContext);
-    return import_api15.trace.setSpan(context, span);
+    const span = import_api17.trace.wrapSpanContext(spanContext);
+    return import_api17.trace.setSpan(context, span);
   }
   fields() {
     return [TRACEPARENT_HEADER];
@@ -2877,7 +3046,7 @@ function setupOTel(options) {
 }
 
 // libs/observability/src/otel/spans/hook.span.ts
-var import_api16 = require("@opentelemetry/api");
+var import_api18 = require("@opentelemetry/api");
 function recordHookEvent(parentSpan, stage, owner) {
   const attributes = {};
   if (owner) {
@@ -2897,14 +3066,14 @@ function startHookSpan(tracer, options) {
   }
   return startSpan(tracer, {
     name: `hook ${options.stage}`,
-    kind: import_api16.SpanKind.INTERNAL,
+    kind: import_api18.SpanKind.INTERNAL,
     attributes,
     parentContext: options.parentContext
   });
 }
 
 // libs/observability/src/otel/spans/pretty-span-exporter.ts
-var import_api17 = require("@opentelemetry/api");
+var import_api19 = require("@opentelemetry/api");
 var RESET = "\x1B[0m";
 var DIM = "\x1B[2m";
 var BOLD = "\x1B[1m";
@@ -2913,11 +3082,11 @@ var GREEN = "\x1B[32m";
 var RED = "\x1B[31m";
 var YELLOW = "\x1B[33m";
 var KIND_LABELS = {
-  [import_api17.SpanKind.INTERNAL]: "INTERNAL",
-  [import_api17.SpanKind.SERVER]: "SERVER",
-  [import_api17.SpanKind.CLIENT]: "CLIENT",
-  [import_api17.SpanKind.PRODUCER]: "PRODUCER",
-  [import_api17.SpanKind.CONSUMER]: "CONSUMER"
+  [import_api19.SpanKind.INTERNAL]: "INTERNAL",
+  [import_api19.SpanKind.SERVER]: "SERVER",
+  [import_api19.SpanKind.CLIENT]: "CLIENT",
+  [import_api19.SpanKind.PRODUCER]: "PRODUCER",
+  [import_api19.SpanKind.CONSUMER]: "CONSUMER"
 };
 var SHOW_ATTRS = /* @__PURE__ */ new Set([
   "rpc.system",
@@ -2956,7 +3125,7 @@ var PrettySpanExporter = class {
     const traceShort = span.spanContext().traceId.slice(0, 8);
     const durationMs = (span.duration[0] * 1e3 + span.duration[1] / 1e6).toFixed(1);
     const kind = KIND_LABELS[span.kind] ?? "UNKNOWN";
-    const statusOk = span.status.code !== import_api17.SpanStatusCode.ERROR;
+    const statusOk = span.status.code !== import_api19.SpanStatusCode.ERROR;
     const attrs = Object.entries(span.attributes).filter(([k]) => SHOW_ATTRS.has(k)).map(([k, v]) => {
       const short = k.replace("frontmcp.", "").replace("mcp.", "");
       return `${short}=${v}`;
@@ -2965,7 +3134,7 @@ var PrettySpanExporter = class {
     const eventSummary = eventCount > 0 ? ` (${eventCount} events)` : "";
     if (this.useAnsi) {
       const statusColor = statusOk ? GREEN : RED;
-      const kindColor = span.kind === import_api17.SpanKind.SERVER ? CYAN : DIM;
+      const kindColor = span.kind === import_api19.SpanKind.SERVER ? CYAN : DIM;
       return [
         `${DIM}\u21B3${RESET}`,
         `${BOLD}${statusColor}SPAN${RESET}`,
@@ -3037,6 +3206,8 @@ function findSpansByAttribute(spans, key, value) {
   FrontMcpAttributes,
   FrontMcpPropagator,
   HttpAttributes,
+  KNOWN_BUNDLE_SOURCES,
+  KNOWN_ERROR_REASONS,
   LOG_LEVEL_TO_OTEL_SEVERITY,
   McpAttributes,
   OTEL_CONFIG,
@@ -3051,11 +3222,14 @@ function findSpansByAttribute(spans, key, value) {
   StdoutSink,
   StructuredLogTransport,
   TELEMETRY_ACCESSOR,
+  TELEMETRY_FACTORY,
   TelemetryAccessor,
+  TelemetryFactory,
   TelemetrySpan,
   WinstonSink,
   assertSpanAttribute,
   assertSpanExists,
+  createCounter,
   createOTelContextFromTrace,
   createSink,
   createSinks,
@@ -3066,11 +3240,18 @@ function findSpansByAttribute(spans, key, value) {
   findSpan,
   findSpansByAttribute,
   frontmcpToOTelSpanContext,
+  getCounterTotal,
   getFinishedSpans,
+  getMetricSnapshot,
+  normalizeBundleSource,
+  normalizeErrorReason,
   otelToFrontmcpContext,
   recordHookEvent,
   redactFields,
   reportStartup,
+  resetCounterCacheForTesting,
+  resetMetricSnapshot,
+  resetTelemetrySnapshotForTesting,
   sessionTracingId,
   setAuthMode,
   setAuthResult,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/observability",
-  "version": "1.1.2",
+  "version": "1.2.1",
   "description": "OpenTelemetry instrumentation, structured JSON logging, and request log objects for FrontMCP",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -51,8 +51,8 @@
     "@opentelemetry/api": "^1.9.0"
   },
   "peerDependencies": {
-    "@frontmcp/sdk": "1.1.2",
-    "@frontmcp/utils": "1.1.2",
+    "@frontmcp/sdk": "1.2.1",
+    "@frontmcp/utils": "1.2.1",
     "@opentelemetry/sdk-trace-base": "^1.25.0",
     "@opentelemetry/sdk-node": "^0.52.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.52.0",

package/telemetry/index.d.ts

@@ -1,3 +1,6 @@
-export { TelemetryAccessor, TelemetrySpan } from './telemetry.accessor';
-export { TELEMETRY_ACCESSOR } from './telemetry.tokens';
 import './telemetry.context-extension';
+export { TelemetryAccessor, TelemetrySpan } from './telemetry.accessor';
+export { TELEMETRY_ACCESSOR, TELEMETRY_FACTORY } from './telemetry.tokens';
+export { TelemetryFactory } from './telemetry.factory';
+export { createCounter, getMetricSnapshot, getCounterTotal, resetMetricSnapshot, resetTelemetrySnapshotForTesting, resetCounterCacheForTesting, normalizeBundleSource, normalizeErrorReason, KNOWN_BUNDLE_SOURCES, KNOWN_ERROR_REASONS, } from './telemetry.counters';
+export type { TelemetryCounter, CounterSnapshotEntry, KnownBundleSource, KnownErrorReason } from './telemetry.counters';

package/telemetry/telemetry.accessor.d.ts

@@ -33,6 +33,7 @@
  */
 import { type Span } from '@opentelemetry/api';
 import { type TraceContextLike } from '../otel/trace-context-bridge';
+import { type TelemetryCounter } from './telemetry.counters';
 /**
  * Minimal context shape — avoids tight coupling to FrontMcpContext.
  */
@@ -138,6 +139,18 @@ export declare class TelemetryAccessor {
      * @param attrs — key-value attributes
      */
     setAttributes(attrs: Record<string, string | number | boolean>): void;
+    /**
+     * Create (or retrieve cached) a named counter.
+     *
+     * Counter increments are exported through the global OTel MeterProvider
+     * when one is configured, and are always recorded in an in-memory snapshot
+     * store (`getMetricSnapshot()` from `@frontmcp/observability`) so tests can
+     * assert behavior without standing up a full OTel pipeline.
+     *
+     * @param name        - OTel-style snake_case name, e.g. `frontmcp_skills_bundle_pulls_total`
+     * @param description - human-readable description
+     */
+    createCounter(name: string, description?: string): TelemetryCounter;
     /**
      * Get the trace ID of the current request.
      * Useful for including in external API calls or logs.

package/telemetry/telemetry.counters.d.ts

@@ -0,0 +1,139 @@
+/**
+ * TelemetryCounter — minimal counter abstraction for FrontMCP.
+ *
+ * Backed by `@opentelemetry/api` `metrics.getMeter(...)` so installations
+ * that wire up an OTel MeterProvider get real counter exports. Independently,
+ * every increment is also recorded in an in-memory snapshot store so tests
+ * (and operators without a configured meter provider) can introspect counter
+ * activity without standing up a full OTel pipeline.
+ *
+ * IMPORTANT: ObservabilityPlugin does NOT register a `MeterProvider` — it only
+ * wires up tracing. To export counters to a real metrics backend (Prometheus,
+ * OTLP, etc.) the host application must call `metrics.setGlobalMeterProvider()`
+ * with its own configured `MeterProvider`. Without that step, counters are
+ * observable only via `getMetricSnapshot()` / `getCounterTotal()`.
+ *
+ * Naming convention follows OTel-style snake_case with a `_total` suffix:
+ *   - `frontmcp_skills_bundle_pulls_total`
+ *   - `frontmcp_skills_signature_failures_total`
+ *   - `frontmcp_skills_signature_verifications_total`
+ *   - `frontmcp_skills_replay_rejects_total`
+ *   - `frontmcp_skills_replay_checks_total`
+ *
+ * Attributes should be lowercase snake_case and bounded cardinality
+ * (e.g. `status`, `source`, `reason`).
+ *
+ * Bounded vocabularies (enforced by helpers below):
+ *   - `source`: 'static' | 'npm' | 'saas-pull' | 'filesystem' | 'unknown'
+ *   - `reason` (errors): 'network' | 'timeout' | 'invalid_response' |
+ *                        'parse_error' | 'unknown'
+ *   - `status`: 'ok' | 'error'
+ *
+ * Anything outside the whitelist coerces to `'unknown'` (or `'other'` for
+ * subsystem-specific reason classifiers like `classifyReason()` in
+ * bundle-signature.ts) so untrusted input cannot create unbounded label
+ * cardinality.
+ */
+/**
+ * Public counter handle — increments propagate to both the OTel meter
+ * (when configured) and the in-memory snapshot store.
+ */
+export interface TelemetryCounter {
+    /**
+     * Increment the counter.
+     *
+     * @param by - amount to add (default 1, must be >= 0)
+     * @param attributes - bounded-cardinality labels
+     */
+    inc(by?: number, attributes?: Record<string, string>): void;
+    /** The metric name, useful for diagnostics/snapshot keys. */
+    readonly name: string;
+}
+/**
+ * Create (or retrieve cached) named counter.
+ *
+ * Counters with the same name are de-duped — subsequent calls return the
+ * same handle. This prevents accidentally exporting two counters with the
+ * same name but slightly different descriptions.
+ */
+export declare function createCounter(name: string, description?: string): TelemetryCounter;
+/**
+ * Snapshot of all counters recorded since process start (or last reset).
+ * Useful for assertions in tests.
+ *
+ * Each entry is a (name, attributes, count) tuple. Counters with attributes
+ * are reported per unique attribute combination.
+ */
+export interface CounterSnapshotEntry {
+    name: string;
+    count: number;
+    attributes: Record<string, string>;
+}
+/**
+ * Read a snapshot of every counter increment recorded so far. Returned
+ * array is a fresh copy — mutating it does not affect the store.
+ */
+export declare function getMetricSnapshot(): CounterSnapshotEntry[];
+/**
+ * Lookup helper — sum of all increments for a given counter name (across
+ * every attribute combination).
+ */
+export declare function getCounterTotal(name: string): number;
+/**
+ * Test helper — clear the in-memory snapshot store. Does not reset the
+ * underlying OTel meter (which has its own lifecycle).
+ *
+ * @deprecated Prefer {@link resetTelemetrySnapshotForTesting}, which is
+ * spelled to make its test-only intent explicit. Kept for backwards
+ * compatibility.
+ */
+export declare function resetMetricSnapshot(): void;
+/**
+ * Test helper — clear the in-memory snapshot store between specs to prevent
+ * cross-test leakage. The snapshot store is process-global; without an
+ * explicit reset between tests, counter increments from one spec can show
+ * up in another's assertions.
+ *
+ * @internal Test-only API. Production code MUST NOT call this.
+ */
+export declare function resetTelemetrySnapshotForTesting(): void;
+/**
+ * Test helper — clear the counter cache. Used only by tests that need to
+ * exercise the create-path repeatedly.
+ *
+ * @internal Test-only API. Production code MUST NOT call this.
+ */
+export declare function resetCounterCacheForTesting(): void;
+/**
+ * @deprecated Use {@link resetCounterCacheForTesting} instead. The leading
+ * underscore violates project naming conventions (CLAUDE.md). Kept temporarily
+ * for backwards compatibility with existing specs.
+ */
+export declare const _resetCounterCacheForTesting: typeof resetCounterCacheForTesting;
+/**
+ * Bounded vocabulary for the `source` counter attribute. Anything outside
+ * this set is coerced to `'unknown'` to prevent cardinality explosions when
+ * upstream callers pass URLs, tenant IDs, or other unbounded strings.
+ */
+export declare const KNOWN_BUNDLE_SOURCES: readonly ["static", "npm", "saas-pull", "webhook", "filesystem", "unknown"];
+export type KnownBundleSource = (typeof KNOWN_BUNDLE_SOURCES)[number];
+/**
+ * Coerce a free-text source label to the bounded `KnownBundleSource` set.
+ * Unknown / undefined / non-string inputs map to `'unknown'`.
+ */
+export declare function normalizeBundleSource(value: unknown): KnownBundleSource;
+/**
+ * Bounded vocabulary for `reason` counter attributes derived from generic
+ * errors. Subsystem-specific classifiers (e.g. signature/replay) MAY define
+ * their own narrower vocabularies, but should use this one for catch-all
+ * "an Error was thrown" paths.
+ */
+export declare const KNOWN_ERROR_REASONS: readonly ["network", "timeout", "invalid_response", "parse_error", "unknown"];
+export type KnownErrorReason = (typeof KNOWN_ERROR_REASONS)[number];
+/**
+ * Map an arbitrary error to a low-cardinality `reason` label. Inspects the
+ * error name and a small substring of the message — never echoes the raw
+ * message back as a label, which would let untrusted error sources spawn
+ * unbounded timeseries.
+ */
+export declare function normalizeErrorReason(err: unknown): KnownErrorReason;

package/telemetry/telemetry.factory.d.ts

@@ -0,0 +1,51 @@
+/**
+ * TelemetryFactory — SCOPE-scoped helper for creating counters and spans
+ * without requiring an active request context.
+ *
+ * `TelemetryAccessor` is CONTEXT-scoped (one per request) so it can read
+ * the active flow span and attach base attributes (request ID, session ID,
+ * etc). That's correct for tool/resource/prompt code paths but the wrong
+ * lifetime for scope-lifetime singletons:
+ *
+ *   - `BundleStore` is constructed at scope-init and lives for the life
+ *     of the scope. Its `swap()` may be invoked from a source's onChange
+ *     callback (no request context) or from a meta-tool call (request
+ *     context). Either way it just needs counters that work, and spans
+ *     parented to whatever active OTel context is on the stack.
+ *
+ * The factory wraps the same process-global `createCounter` exported from
+ * this package, plus a tracer so callers can start spans. `startSpan`
+ * uses `trace.setSpan(context.active(), ...)` semantics implicitly via
+ * `tracer.startSpan` so callers nest correctly when a parent span exists.
+ *
+ * @see TELEMETRY_FACTORY
+ */
+import { type Context as OTelContext } from '@opentelemetry/api';
+import { TelemetrySpan } from './telemetry.accessor';
+import { type TelemetryCounter } from './telemetry.counters';
+export declare class TelemetryFactory {
+    private readonly tracer;
+    constructor(tracerName?: string);
+    /**
+     * Create (or retrieve cached) a named counter. Increments propagate to
+     * the OTel meter (when configured) and to the in-memory snapshot store.
+     *
+     * @param name        - OTel-style snake_case name with `_total` suffix.
+     * @param description - human-readable description (deduped: subsequent
+     *                      calls with a different description return the
+     *                      cached counter unchanged).
+     */
+    createCounter(name: string, description?: string): TelemetryCounter;
+    /**
+     * Start a span. Caller is responsible for calling `end()` /
+     * `endWithError()`. The span parents to the currently-active OTel
+     * context; if none is active it becomes a root span.
+     */
+    startSpan(name: string, attributes?: Record<string, string | number | boolean>, parent?: OTelContext): TelemetrySpan;
+    /**
+     * Convenience wrapper — start a span, run `fn` with it, end on success
+     * or error. Same lifecycle as `TelemetryAccessor.withSpan` but without
+     * the per-request base attributes.
+     */
+    withSpan<T>(name: string, fn: (span: TelemetrySpan) => Promise<T>, attributes?: Record<string, string | number | boolean>): Promise<T>;
+}

package/telemetry/telemetry.tokens.d.ts

@@ -5,3 +5,14 @@
  * Registered by ObservabilityPlugin when tracing is enabled.
  */
 export declare const TELEMETRY_ACCESSOR: unique symbol;
+/**
+ * DI token for the SCOPE-level TelemetryFactory.
+ *
+ * Unlike `TELEMETRY_ACCESSOR` (CONTEXT-scoped), this factory is resolvable
+ * at scope-init time without an active request context. It's intended for
+ * scope-lifetime singletons (e.g. `BundleStore`, security guards) that need
+ * to create process-global counters / spans before any request arrives.
+ *
+ * Registered by ObservabilityPlugin when tracing is enabled.
+ */
+export declare const TELEMETRY_FACTORY: unique symbol;