@autter/runtime-node 1.3.1 → 1.3.3

package/README.md

@@ -1,5 +1,11 @@
 # @autter/runtime-node
 
+The server tracker exports per-instance RSS, heap, memory limit, and GC
+metrics by default. See [memory pressure incidents](../../docs/MEMORY-PRESSURE.md)
+for ECS/Kubernetes OOM event forwarding and optional heap profiles. Set
+`memoryMetrics: false` only if another exporter already emits equivalent
+process metrics.
+
 Autter Runtime for Node.js — two halves in one package:
 
 1. **Same-origin browser relay** for `@autter/runtime-browser`
@@ -187,6 +193,9 @@ engine — keep secrets out of attributes in the first place.
 
 ## 3. LLM tracing
 
+For the field contract, manual reporting patterns, and provider-agnostic
+OpenTelemetry setup, see the dedicated [LLM instrumentation guide](../../docs/LLM-INSTRUMENTATION.md).
+
 `initAutterServer` initialises LLM tracing automatically: any GenAI span —
 `gen_ai.*` semconv attributes or the Vercel AI SDK's `ai.*` spans — bypasses
 head sampling, so **every** model call is recorded with model, tokens,

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -30,7 +40,9 @@ __export(index_exports, {
   instrumentLlmClient: () => instrumentLlmClient,
   makeSafeCapture: () => makeSafeCapture,
   redactAttributes: () => redactAttributes,
+  reportOutcome: () => reportOutcome,
   sanitizeBrowserPayload: () => sanitizeBrowserPayload,
+  startCaughtExceptionSampler: () => startCaughtExceptionSampler,
   trackLlmCall: () => trackLlmCall,
   withLlmCall: () => withLlmCall,
   withProcessSpan: () => withProcessSpan
@@ -68,7 +80,10 @@ var EVENT_TYPES = /* @__PURE__ */ new Set([
   "unhandled_rejection",
   "message",
   "session_start",
-  "track_event"
+  "track_event",
+  "outcome",
+  "request_failure",
+  "timing"
 ]);
 var SEVERITIES = /* @__PURE__ */ new Set(["fatal", "error", "warning", "info"]);
 function sanitizeBrowserPayload(raw) {
@@ -90,6 +105,7 @@ function sanitizeBrowserPayload(raw) {
       ...typeof e.severity === "string" && SEVERITIES.has(e.severity) ? { severity: e.severity } : {},
       message: typeof e.message === "string" ? e.message.slice(0, 4e3) : "",
       ...typeof e.name === "string" ? { name: e.name.slice(0, 200) } : {},
+      ...typeof e.durationMs === "number" && Number.isFinite(e.durationMs) ? { durationMs: Math.max(0, Math.min(12e4, e.durationMs)) } : {},
       ...typeof e.stack === "string" ? { stack: e.stack.slice(0, 32e3) } : {},
       ...typeof e.errorType === "string" ? { errorType: e.errorType.slice(0, 200) } : {},
       ...typeof e.filename === "string" ? { filename: e.filename.split("?")[0].slice(0, 1e3) } : {},
@@ -239,7 +255,7 @@ function createBrowserRelayHandler(opts) {
 // src/server.ts
 var import_node_http = require("http");
 var import_node_crypto = require("crypto");
-var import_api = require("@opentelemetry/api");
+var import_api2 = require("@opentelemetry/api");
 var import_core2 = require("@opentelemetry/core");
 var import_exporter_metrics_otlp_http = require("@opentelemetry/exporter-metrics-otlp-http");
 var import_exporter_trace_otlp_http = require("@opentelemetry/exporter-trace-otlp-http");
@@ -323,6 +339,7 @@ function installAutterAutoFlush(options = {}) {
   const warnOnUnflushedExit = options.warnOnUnflushedExit !== false;
   const timeoutMs = Math.max(100, options.timeoutMs ?? 3e3);
   const signals = options.signals ?? DEFAULT_SIGNALS;
+  const flushOnUncaughtException = options.flushOnUncaughtException !== false;
   let disposed = false;
   let inFlight = null;
   const doFlush = async () => {
@@ -368,6 +385,19 @@ function installAutterAutoFlush(options = {}) {
     return inFlight;
   };
   const signalCounts = /* @__PURE__ */ new Map();
+  let handlingUncaughtException = false;
+  const onUncaughtException = (error) => {
+    if (process.listenerCount("uncaughtException") > 1) return;
+    if (handlingUncaughtException) return;
+    handlingUncaughtException = true;
+    logger.error(error instanceof Error ? error.stack ?? error.message : String(error));
+    const keepAlive = setTimeout(() => {
+    }, timeoutMs + 50);
+    void flush("uncaughtException").finally(() => {
+      clearTimeout(keepAlive);
+      process.exit(1);
+    });
+  };
   const onSignal = (signal) => {
     const count = (signalCounts.get(signal) ?? 0) + 1;
     signalCounts.set(signal, count);
@@ -407,6 +437,9 @@ function installAutterAutoFlush(options = {}) {
   };
   const signalHandlers = /* @__PURE__ */ new Map();
   process.on("beforeExit", onBeforeExit);
+  if (flushOnUncaughtException) {
+    process.on("uncaughtException", onUncaughtException);
+  }
   for (const signal of signals) {
     const handler = () => onSignal(signal);
     signalHandlers.set(signal, handler);
@@ -418,6 +451,7 @@ function installAutterAutoFlush(options = {}) {
     dispose() {
       disposed = true;
       process.removeListener("beforeExit", onBeforeExit);
+      process.removeListener("uncaughtException", onUncaughtException);
       process.removeListener("exit", onExit);
       for (const [signal, handler] of signalHandlers) {
         process.removeListener(signal, handler);
@@ -673,6 +707,51 @@ function makeRedactor(options) {
   return (attributes) => redactWith(attributes, r);
 }
 
+// src/memory.ts
+var import_node_perf_hooks = require("perf_hooks");
+var import_node_v8 = require("v8");
+var import_api = require("@opentelemetry/api");
+function startMemoryMetrics() {
+  const meter = import_api.metrics.getMeter("autter-process-memory");
+  const rss = meter.createObservableGauge("autter.process.memory.rss", { unit: "By" });
+  const heapUsed = meter.createObservableGauge("autter.process.memory.heap.used", { unit: "By" });
+  const heapLimit = meter.createObservableGauge("autter.process.memory.heap.limit", { unit: "By" });
+  const containerLimit = meter.createObservableGauge("autter.process.memory.limit", { unit: "By" });
+  const afterGc = meter.createObservableGauge("autter.process.memory.heap.after_gc", { unit: "By" });
+  const gcCount = meter.createObservableCounter("autter.process.gc.count", { unit: "{collection}" });
+  const gcDuration = meter.createObservableCounter("autter.process.gc.duration", { unit: "ms" });
+  let collections = 0;
+  let durationMs = 0;
+  let lastAfterGc = null;
+  const callbacks = [
+    [rss, (result) => result.observe(process.memoryUsage().rss)],
+    [heapUsed, (result) => result.observe(process.memoryUsage().heapUsed)],
+    [heapLimit, (result) => result.observe((0, import_node_v8.getHeapStatistics)().heap_size_limit)],
+    [containerLimit, (result) => {
+      const constrained = process.constrainedMemory?.() ?? 0;
+      if (constrained > 0) result.observe(constrained);
+    }],
+    [afterGc, (result) => {
+      if (lastAfterGc !== null) result.observe(lastAfterGc);
+    }],
+    [gcCount, (result) => result.observe(collections)],
+    [gcDuration, (result) => result.observe(durationMs)]
+  ];
+  for (const [instrument, callback] of callbacks) instrument.addCallback(callback);
+  const observer = new import_node_perf_hooks.PerformanceObserver((list) => {
+    for (const entry of list.getEntries()) {
+      collections++;
+      durationMs += entry.duration;
+      lastAfterGc = process.memoryUsage().heapUsed;
+    }
+  });
+  observer.observe({ entryTypes: ["gc"] });
+  return () => {
+    observer.disconnect();
+    for (const [instrument, callback] of callbacks) instrument.removeCallback(callback);
+  };
+}
+
 // src/server.ts
 var LLM_MARKER_ATTRIBUTES = [
   "gen_ai.operation.name",
@@ -735,14 +814,14 @@ var RETENTION_MAX_BUFFERED_SPANS = 5e3;
 var RETENTION_SWEEP_INTERVAL_MS = 1e4;
 var RETENTION_TRACE_TTL_MS = 3e4;
 function spanIndicatesError(span) {
-  if (span.status.code === import_api.SpanStatusCode.ERROR) return true;
+  if (span.status.code === import_api2.SpanStatusCode.ERROR) return true;
   return span.events.some((event) => event.name === "exception");
 }
 var TAIL_RETAINED_ATTR = "autter.tail_retained";
 function withSampledFlag(span) {
   const spanContext = {
     ...span.spanContext(),
-    traceFlags: span.spanContext().traceFlags | import_api.TraceFlags.SAMPLED
+    traceFlags: span.spanContext().traceFlags | import_api2.TraceFlags.SAMPLED
   };
   return {
     name: span.name,
@@ -782,11 +861,11 @@ var ErrorTraceRetentionProcessor = class {
   }
   onEnd(span) {
     const ctx = span.spanContext();
-    if ((ctx.traceFlags & import_api.TraceFlags.SAMPLED) !== 0) return;
+    if ((ctx.traceFlags & import_api2.TraceFlags.SAMPLED) !== 0) return;
     const entry = this.entryFor(ctx.traceId);
     if (entry.retained) {
       this.forward(span);
-    } else if (this.retainErrors && spanIndicatesError(span) || this.slowThresholdMs > 0 && span.kind === import_api.SpanKind.SERVER && span.duration[0] * 1e3 + span.duration[1] / 1e6 >= this.slowThresholdMs) {
+    } else if (this.retainErrors && spanIndicatesError(span) || this.slowThresholdMs > 0 && span.kind === import_api2.SpanKind.SERVER && span.duration[0] * 1e3 + span.duration[1] / 1e6 >= this.slowThresholdMs) {
       entry.retained = true;
       this.flush(entry);
       this.forward(span);
@@ -801,8 +880,8 @@ var ErrorTraceRetentionProcessor = class {
   }
   /** Promote the active trace, if any — called on captured errors. */
   retainActiveTrace() {
-    const active2 = import_api.trace.getActiveSpan()?.spanContext();
-    if (!active2 || (active2.traceFlags & import_api.TraceFlags.SAMPLED) !== 0) return;
+    const active2 = import_api2.trace.getActiveSpan()?.spanContext();
+    if (!active2 || (active2.traceFlags & import_api2.TraceFlags.SAMPLED) !== 0) return;
     const entry = this.entryFor(active2.traceId);
     if (entry.retained) return;
     entry.retained = true;
@@ -891,7 +970,7 @@ function usageAttributes(usage) {
 }
 async function runLlmSpan(tracer, info, fn) {
   const span = tracer.startSpan(`${info.operation ?? "chat"} ${info.model}`, {
-    kind: import_api.SpanKind.CLIENT,
+    kind: import_api2.SpanKind.CLIENT,
     attributes: llmBaseAttributes(info)
   });
   const setResponseModel = (model) => span.setAttribute("gen_ai.response.model", model);
@@ -903,11 +982,11 @@ async function runLlmSpan(tracer, info, fn) {
     setAttributes: (attributes) => span.setAttributes(attributes)
   };
   try {
-    const result = await import_api.context.with(
-      import_api.trace.setSpan(import_api.context.active(), span),
+    const result = await import_api2.context.with(
+      import_api2.trace.setSpan(import_api2.context.active(), span),
       () => fn(handle)
     );
-    span.setStatus({ code: import_api.SpanStatusCode.OK });
+    span.setStatus({ code: import_api2.SpanStatusCode.OK });
     return result;
   } catch (err) {
     if (err instanceof Error) {
@@ -915,7 +994,7 @@ async function runLlmSpan(tracer, info, fn) {
       span.setAttribute("error.type", err.name);
     }
     span.setStatus({
-      code: import_api.SpanStatusCode.ERROR,
+      code: import_api2.SpanStatusCode.ERROR,
       message: err instanceof Error ? err.message : String(err)
     });
     throw err;
@@ -930,7 +1009,7 @@ function recordLlmCall(tracer, call) {
   const span = tracer.startSpan(
     `${call.operation ?? "chat"} ${call.model}`,
     {
-      kind: import_api.SpanKind.CLIENT,
+      kind: import_api2.SpanKind.CLIENT,
       startTime,
       attributes: { ...llmBaseAttributes(call), ...usageAttributes(call) }
     }
@@ -941,27 +1020,27 @@ function recordLlmCall(tracer, call) {
       span.setAttribute("error.type", call.error.name);
     }
     span.setStatus({
-      code: import_api.SpanStatusCode.ERROR,
+      code: import_api2.SpanStatusCode.ERROR,
       message: call.error instanceof Error ? call.error.message : String(call.error)
     });
   } else {
-    span.setStatus({ code: import_api.SpanStatusCode.OK });
+    span.setStatus({ code: import_api2.SpanStatusCode.OK });
   }
   span.end(endTime);
 }
 async function runWithSpan(tracer, name, fn, attributes) {
   const span = tracer.startSpan(name, { attributes });
   try {
-    const result = await import_api.context.with(
-      import_api.trace.setSpan(import_api.context.active(), span),
+    const result = await import_api2.context.with(
+      import_api2.trace.setSpan(import_api2.context.active(), span),
       fn
     );
-    span.setStatus({ code: import_api.SpanStatusCode.OK });
+    span.setStatus({ code: import_api2.SpanStatusCode.OK });
     return result;
   } catch (err) {
     if (err instanceof Error) span.recordException(err);
     span.setStatus({
-      code: import_api.SpanStatusCode.ERROR,
+      code: import_api2.SpanStatusCode.ERROR,
       message: err instanceof Error ? err.message : String(err)
     });
     throw err;
@@ -979,7 +1058,7 @@ function expressRouteOf(req) {
 }
 function captureExpressRoute(_span, response) {
   if (!(response instanceof import_node_http.ServerResponse)) return;
-  const rpcMetadata = (0, import_core2.getRPCMetadata)(import_api.context.active());
+  const rpcMetadata = (0, import_core2.getRPCMetadata)(import_api2.context.active());
   if (rpcMetadata?.type !== import_core2.RPCType.HTTP) return;
   const setRoute = () => {
     if (rpcMetadata.route) return;
@@ -1005,7 +1084,7 @@ function initAutterServer(options) {
   activeRedactor = makeRedactor(options.redactAttributes ?? true);
   const resource = new import_resources.Resource({
     [import_semantic_conventions.ATTR_SERVICE_NAME]: options.service,
-    "service.instance.id": (0, import_node_crypto.randomUUID)(),
+    "service.instance.id": (options.instanceId || process.env.AUTTER_RUNTIME_INSTANCE_ID || (0, import_node_crypto.randomUUID)()).slice(0, 128),
     ...options.release ? { [import_semantic_conventions.ATTR_SERVICE_VERSION]: options.release } : {},
     "deployment.environment": environment,
     // Tells the ingester request metrics arrive on the metrics pipe, so
@@ -1070,6 +1149,7 @@ function initAutterServer(options) {
     ]
   });
   sdk.start();
+  const stopMemoryMetrics = options.memoryMetrics === false ? null : startMemoryMetrics();
   const alwaysOnProvider = new import_sdk_trace_base.BasicTracerProvider({
     resource,
     sampler: new import_sdk_trace_base.AlwaysOnSampler(),
@@ -1091,21 +1171,32 @@ function initAutterServer(options) {
     const isError = error instanceof Error;
     const message = isError ? error.message : String(error);
     const redacted = activeRedactor(attributes);
-    const activeSpan = import_api.trace.getActiveSpan();
+    const activeSpan = import_api2.trace.getActiveSpan();
     const reuseActive = activeSpan?.isRecording() === true;
     const span = reuseActive ? activeSpan : errorTracer.startSpan(isError ? error.name : "Error");
     span.setAttributes({ "autter.severity": "error", ...redacted });
     if (isError && error.stack) {
-      span.recordException(error);
+      if (redacted["autter.handled"] === true) {
+        span.addEvent("exception", {
+          "exception.type": error.name,
+          "exception.message": message,
+          "exception.stacktrace": error.stack,
+          "autter.handled": true,
+          "autter.sampled": redacted["autter.sampled"] === true
+        });
+      } else {
+        span.recordException(error);
+      }
     } else {
       const stack = new Error().stack?.split("\n").filter((line, i) => i === 0 || !line.includes("captureException")).join("\n");
       span.addEvent("exception", {
         "exception.type": isError ? error.name : "Error",
         "exception.message": message,
-        ...stack ? { "exception.stacktrace": stack } : {}
+        ...stack ? { "exception.stacktrace": stack } : {},
+        ...redacted["autter.handled"] === true ? { "autter.handled": true, "autter.sampled": redacted["autter.sampled"] === true } : {}
       });
     }
-    span.setStatus({ code: import_api.SpanStatusCode.ERROR, message });
+    span.setStatus({ code: import_api2.SpanStatusCode.ERROR, message });
     if (!reuseActive) span.end();
   }
   function captureMessage2(message, severity = "warning", attributes) {
@@ -1123,18 +1214,31 @@ function initAutterServer(options) {
       ...stack ? { "exception.stacktrace": stack } : {},
       "autter.severity": severity
     });
-    span.setStatus({ code: import_api.SpanStatusCode.ERROR, message });
+    span.setStatus({ code: import_api2.SpanStatusCode.ERROR, message });
     span.end();
   }
+  function reportOutcome2(name, message, attributes) {
+    errorTraceBuffer?.retainActiveTrace();
+    telemetryStats.markCaptured();
+    const activeSpan = import_api2.trace.getActiveSpan();
+    const reuseActive = activeSpan?.isRecording() === true;
+    const span = reuseActive ? activeSpan : errorTracer.startSpan("OutcomeFailure");
+    const safeOutcome = activeRedactor({ "autter.outcome.name": name.slice(0, 200), "autter.outcome.message": message.slice(0, 1e3) });
+    const safeName = String(safeOutcome["autter.outcome.name"] ?? "operation");
+    const safeMessage = String(safeOutcome["autter.outcome.message"] ?? "failed");
+    span.addEvent("autter.outcome", {
+      ...activeRedactor(attributes),
+      "autter.outcome.status": "error",
+      "autter.outcome.name": safeName,
+      "autter.outcome.message": safeMessage
+    });
+    span.setStatus({ code: import_api2.SpanStatusCode.ERROR, message: safeMessage });
+    if (!reuseActive) span.end();
+  }
   if (options.captureGlobalErrors !== false) {
     process.on("uncaughtExceptionMonitor", (err) => {
       captureException2(err, { "autter.unhandled": true });
-      void flushTarget.forceFlush();
-    });
-    process.on("unhandledRejection", (reason) => {
-      captureException2(reason, {
-        "autter.unhandled": true,
-        ...reason instanceof Error ? {} : { "autter.severity": "warning" }
+      if (options.autoFlush === false) void Promise.resolve(flushTarget.forceFlush()).catch(() => {
       });
     });
   }
@@ -1162,10 +1266,12 @@ function initAutterServer(options) {
   const server = {
     captureException: captureException2,
     captureMessage: captureMessage2,
+    reportOutcome: reportOutcome2,
     withProcessSpan: (name, fn, attributes) => runWithSpan(processTracer, name, fn, activeRedactor(attributes)),
     withLlmCall: (info, fn) => runLlmSpan(llmTracer, info, fn),
     trackLlmCall: (call) => recordLlmCall(llmTracer, call),
     shutdown: async () => {
+      stopMemoryMetrics?.();
       active = null;
       activeAlwaysOnProvider = null;
       autoFlushHandle?.dispose();
@@ -1184,35 +1290,35 @@ function captureException(error, attributes) {
     active.captureException(error, attributes);
     return;
   }
-  const span = import_api.trace.getTracer("autter-errors").startSpan(error instanceof Error ? error.name : "Error", { attributes });
+  const span = import_api2.trace.getTracer("autter-errors").startSpan(error instanceof Error ? error.name : "Error", { attributes });
   if (error instanceof Error) span.recordException(error);
   span.setStatus({
-    code: import_api.SpanStatusCode.ERROR,
+    code: import_api2.SpanStatusCode.ERROR,
     message: error instanceof Error ? error.message : String(error)
   });
   span.end();
 }
 function withProcessSpan(name, fn, attributes) {
   if (active) return active.withProcessSpan(name, fn, attributes);
-  return runWithSpan(import_api.trace.getTracer("autter-processes"), name, fn, attributes);
+  return runWithSpan(import_api2.trace.getTracer("autter-processes"), name, fn, attributes);
 }
 function withLlmCall(info, fn) {
   if (active) return active.withLlmCall(info, fn);
-  return runLlmSpan(import_api.trace.getTracer("autter-llm"), info, fn);
+  return runLlmSpan(import_api2.trace.getTracer("autter-llm"), info, fn);
 }
 function trackLlmCall(call) {
   if (active) {
     active.trackLlmCall(call);
     return;
   }
-  recordLlmCall(import_api.trace.getTracer("autter-llm"), call);
+  recordLlmCall(import_api2.trace.getTracer("autter-llm"), call);
 }
 function captureMessage(message, severity = "warning", attributes) {
   if (active) {
     active.captureMessage(message, severity, attributes);
     return;
   }
-  const span = import_api.trace.getTracer("autter-errors").startSpan("Message", {
+  const span = import_api2.trace.getTracer("autter-errors").startSpan("Message", {
     attributes: { "autter.severity": severity, ...attributes }
   });
   span.addEvent("exception", {
@@ -1220,7 +1326,22 @@ function captureMessage(message, severity = "warning", attributes) {
     "exception.message": message,
     "autter.severity": severity
   });
-  span.setStatus({ code: import_api.SpanStatusCode.ERROR, message });
+  span.setStatus({ code: import_api2.SpanStatusCode.ERROR, message });
+  span.end();
+}
+function reportOutcome(name, message, attributes) {
+  if (active) return active.reportOutcome(name, message, attributes);
+  const span = import_api2.trace.getTracer("autter-outcomes").startSpan("OutcomeFailure");
+  const safeOutcome = redactAttributes({ "autter.outcome.name": name.slice(0, 200), "autter.outcome.message": message.slice(0, 1e3) });
+  const safeName = String(safeOutcome["autter.outcome.name"] ?? "operation");
+  const safeMessage = String(safeOutcome["autter.outcome.message"] ?? "failed");
+  span.addEvent("autter.outcome", {
+    ...redactAttributes(attributes),
+    "autter.outcome.status": "error",
+    "autter.outcome.name": safeName,
+    "autter.outcome.message": safeMessage
+  });
+  span.setStatus({ code: import_api2.SpanStatusCode.ERROR, message: safeMessage });
   span.end();
 }
 function makeSafeCapture(options) {
@@ -1231,7 +1352,7 @@ function makeSafeCapture(options) {
   };
 }
 function alwaysOnTracer(name) {
-  return activeAlwaysOnProvider ? activeAlwaysOnProvider.getTracer(name) : import_api.trace.getTracer(name);
+  return activeAlwaysOnProvider ? activeAlwaysOnProvider.getTracer(name) : import_api2.trace.getTracer(name);
 }
 function autterLlmTracer() {
   return alwaysOnTracer("autter-llm");
@@ -1251,7 +1372,7 @@ async function emitLlmSelftestTrace() {
       attributes: { "autter.selftest": true }
     },
     (llm) => {
-      traceId = import_api.trace.getActiveSpan()?.spanContext().traceId ?? "";
+      traceId = import_api2.trace.getActiveSpan()?.spanContext().traceId ?? "";
       llm.setUsage({ inputTokens: 1, outputTokens: 1 });
       llm.setCost(0);
     }
@@ -1261,7 +1382,7 @@ async function emitLlmSelftestTrace() {
 }
 
 // src/llm-instrument.ts
-var import_api2 = require("@opentelemetry/api");
+var import_api3 = require("@opentelemetry/api");
 var CALL_METHODS = /* @__PURE__ */ new Set([
   "create",
   // openai chat/completions/embeddings/responses, anthropic messages
@@ -1319,7 +1440,7 @@ function applyUsage(span, usage) {
 function endWithError(span, err) {
   if (err instanceof Error) span.recordException(err);
   span.setStatus({
-    code: import_api2.SpanStatusCode.ERROR,
+    code: import_api3.SpanStatusCode.ERROR,
     message: err instanceof Error ? err.message : String(err)
   });
   span.end();
@@ -1339,7 +1460,7 @@ function wrapStream(stream, span) {
     if (err !== void 0) {
       endWithError(span, err);
     } else {
-      span.setStatus({ code: import_api2.SpanStatusCode.OK });
+      span.setStatus({ code: import_api3.SpanStatusCode.OK });
       span.end();
     }
   };
@@ -1394,7 +1515,7 @@ function instrumentLlmClient(client, options) {
     const operation = /embed/i.test(callPath) ? "embeddings" : "chat";
     const userId = resolveUserId();
     const span = autterLlmTracer().startSpan(`${operation} ${request.model}`, {
-      kind: import_api2.SpanKind.CLIENT,
+      kind: import_api3.SpanKind.CLIENT,
       attributes: {
         "gen_ai.operation.name": operation,
         "gen_ai.provider.name": provider,
@@ -1416,7 +1537,7 @@ function instrumentLlmClient(client, options) {
         return wrapStream(result, span);
       }
       applyUsage(span, extractUsage(result));
-      span.setStatus({ code: import_api2.SpanStatusCode.OK });
+      span.setStatus({ code: import_api3.SpanStatusCode.OK });
       span.end();
       return result;
     }
@@ -1426,7 +1547,7 @@ function instrumentLlmClient(client, options) {
           return wrapStream(resolved, span);
         }
         applyUsage(span, extractUsage(resolved));
-        span.setStatus({ code: import_api2.SpanStatusCode.OK });
+        span.setStatus({ code: import_api3.SpanStatusCode.OK });
         span.end();
         return resolved;
       },
@@ -1472,6 +1593,50 @@ function instrumentLlmClient(client, options) {
   }
   return deepProxy(client);
 }
+
+// src/caught-exceptions.ts
+var import_node_inspector = __toESM(require("inspector"), 1);
+function startCaughtExceptionSampler(options = {}) {
+  const rate = Math.max(0, Math.min(1, options.sampleRate ?? 0.01));
+  const cap = Math.max(1, Math.min(100, options.maxPerMinute ?? 10));
+  const session = new import_node_inspector.default.Session();
+  let active2 = true;
+  let minute = 0;
+  let sent = 0;
+  session.connect();
+  session.on("Debugger.paused", (message) => {
+    session.post("Debugger.resume", () => {
+    });
+    if (!active2 || message.params.reason !== "exception") return;
+    const nowMinute = Math.floor(Date.now() / 6e4);
+    if (nowMinute !== minute) {
+      minute = nowMinute;
+      sent = 0;
+    }
+    if (sent >= cap || Math.random() >= rate) return;
+    sent++;
+    const frames = message.params.callFrames.slice(0, 8).filter((frame) => frame.url && !frame.url.startsWith("node:")).map((frame) => `    at ${frame.functionName || "anonymous"} (${frame.url.split("?")[0]}:${frame.location.lineNumber + 1}:${(frame.location.columnNumber ?? 0) + 1})`);
+    if (!frames.length) return;
+    const error = new Error("Sampled caught exception");
+    error.name = "CaughtException";
+    error.stack = `${error.name}: ${error.message}
+${frames.join("\n")}`;
+    queueMicrotask(() => {
+      if (active2) captureException(error, { "autter.handled": true, "autter.sampled": true });
+    });
+  });
+  session.post("Debugger.enable", (error) => {
+    if (!error && active2) session.post("Debugger.setPauseOnExceptions", { state: "all" }, () => {
+    });
+  });
+  return { stop() {
+    if (!active2) return;
+    active2 = false;
+    session.post("Debugger.setPauseOnExceptions", { state: "none" }, () => {
+      session.post("Debugger.disable", () => session.disconnect());
+    });
+  } };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   captureException,
@@ -1484,7 +1649,9 @@ function instrumentLlmClient(client, options) {
   instrumentLlmClient,
   makeSafeCapture,
   redactAttributes,
+  reportOutcome,
   sanitizeBrowserPayload,
+  startCaughtExceptionSampler,
   trackLlmCall,
   withLlmCall,
   withProcessSpan

package/dist/index.d.cts

@@ -100,6 +100,8 @@ interface AutterServerOptions {
     /** Ingester base URL. Default: https://otlp.autter.dev */
     endpoint?: string;
     service: string;
+    /** Stable for this process lifetime; use an ECS task/container ID or pod UID plus restart count to correlate platform events. */
+    instanceId?: string;
     environment?: string;
     /** e.g. a git SHA. Maps to service.version / release. */
     release?: string;
@@ -119,6 +121,8 @@ interface AutterServerOptions {
     retainTracesAboveMs?: number;
     /** Metric export interval. Default 60_000 ms. */
     metricIntervalMs?: number;
+    /** Collect RSS, heap, limit, and GC signals per process instance. Default true. */
+    memoryMetrics?: boolean;
     /** Capture crashing exceptions via process.uncaughtExceptionMonitor (default true). */
     captureGlobalErrors?: boolean;
     /**
@@ -206,6 +210,8 @@ interface AutterServer {
      * errors with a lower severity so aggregations can slice one dataset.
      */
     captureMessage(message: string, severity?: AutterSeverity, attributes?: Attributes): void;
+    /** Report a failed result from code that returned normally. Name must be stable. */
+    reportOutcome(name: string, message: string, attributes?: Attributes): void;
     /**
      * Wrap a named unit of work — a background job, queue consumer, cron
      * tick, or DB-heavy call — in an always-recorded span. Unlike regular
@@ -264,6 +270,8 @@ declare function withLlmCall<T>(info: LlmCallInfo, fn: (llm: LlmCallHandle) => T
 declare function trackLlmCall(call: TrackedLlmCall): void;
 /** Module-level convenience for warnings/info — see AutterServer.captureMessage. */
 declare function captureMessage(message: string, severity?: AutterSeverity, attributes?: Attributes): void;
+/** Portable OTLP `autter.outcome` event for failed results without exceptions. */
+declare function reportOutcome(name: string, message: string, attributes?: Attributes): void;
 /** Capture surface with guaranteed redaction, regardless of how the host app
  * configured initAutterServer — for library authors whose calls must never
  * forward PII even when the host disabled it. Routes to the active server
@@ -322,6 +330,8 @@ interface AutoFlushOptions {
      * signals, proceeding to exit anyway). Default 3000 ms.
      */
     timeoutMs?: number;
+    /** Flush after a fatal uncaught exception, then exit with Node's crash code. Default true. */
+    flushOnUncaughtException?: boolean;
     /** Signals handled besides the defaults. Default ["SIGINT", "SIGTERM"]. */
     signals?: string[];
 }
@@ -342,6 +352,8 @@ interface AutoFlushHandle {
  *     concurrently and let your handler decide the exit — installing this
  *     never changes an existing graceful-shutdown path. A second signal
  *     always exits immediately.
+ *   - uncaughtException — delays Node's fatal exit only for the same bounded
+ *     flush, then exits with its default crash status (1).
  *
  * Idempotent per options object; `initAutterServer` installs it by default
  * (`autoFlush: false` opts out).
@@ -375,4 +387,12 @@ interface InstrumentLlmOptions {
 }
 declare function instrumentLlmClient<T extends object>(client: T, options?: InstrumentLlmOptions): T;
 
-export { type AutoFlushHandle, type AutoFlushOptions, type AutterServer, type AutterServerOptions, type AutterSeverity, type FlushTarget, type InstrumentLlmOptions, type LlmCallHandle, type LlmCallInfo, type LlmUsage, type RedactOptions, type RelayOptions, type SafeCapture, type TrackedLlmCall, captureException, captureMessage, createBrowserRelayFetchHandler, createBrowserRelayHandler, emitLlmSelftestTrace, initAutterServer, installAutterAutoFlush, instrumentLlmClient, makeSafeCapture, redactAttributes, sanitizeBrowserPayload, trackLlmCall, withLlmCall, withProcessSpan };
+/** Opt-in diagnostic hook. V8 pauses briefly for every throw, including handled throws. */
+declare function startCaughtExceptionSampler(options?: {
+    sampleRate?: number;
+    maxPerMinute?: number;
+}): {
+    stop(): void;
+};
+
+export { type AutoFlushHandle, type AutoFlushOptions, type AutterServer, type AutterServerOptions, type AutterSeverity, type FlushTarget, type InstrumentLlmOptions, type LlmCallHandle, type LlmCallInfo, type LlmUsage, type RedactOptions, type RelayOptions, type SafeCapture, type TrackedLlmCall, captureException, captureMessage, createBrowserRelayFetchHandler, createBrowserRelayHandler, emitLlmSelftestTrace, initAutterServer, installAutterAutoFlush, instrumentLlmClient, makeSafeCapture, redactAttributes, reportOutcome, sanitizeBrowserPayload, startCaughtExceptionSampler, trackLlmCall, withLlmCall, withProcessSpan };

package/dist/index.d.ts

@@ -100,6 +100,8 @@ interface AutterServerOptions {
     /** Ingester base URL. Default: https://otlp.autter.dev */
     endpoint?: string;
     service: string;
+    /** Stable for this process lifetime; use an ECS task/container ID or pod UID plus restart count to correlate platform events. */
+    instanceId?: string;
     environment?: string;
     /** e.g. a git SHA. Maps to service.version / release. */
     release?: string;
@@ -119,6 +121,8 @@ interface AutterServerOptions {
     retainTracesAboveMs?: number;
     /** Metric export interval. Default 60_000 ms. */
     metricIntervalMs?: number;
+    /** Collect RSS, heap, limit, and GC signals per process instance. Default true. */
+    memoryMetrics?: boolean;
     /** Capture crashing exceptions via process.uncaughtExceptionMonitor (default true). */
     captureGlobalErrors?: boolean;
     /**
@@ -206,6 +210,8 @@ interface AutterServer {
      * errors with a lower severity so aggregations can slice one dataset.
      */
     captureMessage(message: string, severity?: AutterSeverity, attributes?: Attributes): void;
+    /** Report a failed result from code that returned normally. Name must be stable. */
+    reportOutcome(name: string, message: string, attributes?: Attributes): void;
     /**
      * Wrap a named unit of work — a background job, queue consumer, cron
      * tick, or DB-heavy call — in an always-recorded span. Unlike regular
@@ -264,6 +270,8 @@ declare function withLlmCall<T>(info: LlmCallInfo, fn: (llm: LlmCallHandle) => T
 declare function trackLlmCall(call: TrackedLlmCall): void;
 /** Module-level convenience for warnings/info — see AutterServer.captureMessage. */
 declare function captureMessage(message: string, severity?: AutterSeverity, attributes?: Attributes): void;
+/** Portable OTLP `autter.outcome` event for failed results without exceptions. */
+declare function reportOutcome(name: string, message: string, attributes?: Attributes): void;
 /** Capture surface with guaranteed redaction, regardless of how the host app
  * configured initAutterServer — for library authors whose calls must never
  * forward PII even when the host disabled it. Routes to the active server
@@ -322,6 +330,8 @@ interface AutoFlushOptions {
      * signals, proceeding to exit anyway). Default 3000 ms.
      */
     timeoutMs?: number;
+    /** Flush after a fatal uncaught exception, then exit with Node's crash code. Default true. */
+    flushOnUncaughtException?: boolean;
     /** Signals handled besides the defaults. Default ["SIGINT", "SIGTERM"]. */
     signals?: string[];
 }
@@ -342,6 +352,8 @@ interface AutoFlushHandle {
  *     concurrently and let your handler decide the exit — installing this
  *     never changes an existing graceful-shutdown path. A second signal
  *     always exits immediately.
+ *   - uncaughtException — delays Node's fatal exit only for the same bounded
+ *     flush, then exits with its default crash status (1).
  *
  * Idempotent per options object; `initAutterServer` installs it by default
  * (`autoFlush: false` opts out).
@@ -375,4 +387,12 @@ interface InstrumentLlmOptions {
 }
 declare function instrumentLlmClient<T extends object>(client: T, options?: InstrumentLlmOptions): T;
 
-export { type AutoFlushHandle, type AutoFlushOptions, type AutterServer, type AutterServerOptions, type AutterSeverity, type FlushTarget, type InstrumentLlmOptions, type LlmCallHandle, type LlmCallInfo, type LlmUsage, type RedactOptions, type RelayOptions, type SafeCapture, type TrackedLlmCall, captureException, captureMessage, createBrowserRelayFetchHandler, createBrowserRelayHandler, emitLlmSelftestTrace, initAutterServer, installAutterAutoFlush, instrumentLlmClient, makeSafeCapture, redactAttributes, sanitizeBrowserPayload, trackLlmCall, withLlmCall, withProcessSpan };
+/** Opt-in diagnostic hook. V8 pauses briefly for every throw, including handled throws. */
+declare function startCaughtExceptionSampler(options?: {
+    sampleRate?: number;
+    maxPerMinute?: number;
+}): {
+    stop(): void;
+};
+
+export { type AutoFlushHandle, type AutoFlushOptions, type AutterServer, type AutterServerOptions, type AutterSeverity, type FlushTarget, type InstrumentLlmOptions, type LlmCallHandle, type LlmCallInfo, type LlmUsage, type RedactOptions, type RelayOptions, type SafeCapture, type TrackedLlmCall, captureException, captureMessage, createBrowserRelayFetchHandler, createBrowserRelayHandler, emitLlmSelftestTrace, initAutterServer, installAutterAutoFlush, instrumentLlmClient, makeSafeCapture, redactAttributes, reportOutcome, sanitizeBrowserPayload, startCaughtExceptionSampler, trackLlmCall, withLlmCall, withProcessSpan };

package/dist/index.js

@@ -29,7 +29,10 @@ var EVENT_TYPES = /* @__PURE__ */ new Set([
   "unhandled_rejection",
   "message",
   "session_start",
-  "track_event"
+  "track_event",
+  "outcome",
+  "request_failure",
+  "timing"
 ]);
 var SEVERITIES = /* @__PURE__ */ new Set(["fatal", "error", "warning", "info"]);
 function sanitizeBrowserPayload(raw) {
@@ -51,6 +54,7 @@ function sanitizeBrowserPayload(raw) {
       ...typeof e.severity === "string" && SEVERITIES.has(e.severity) ? { severity: e.severity } : {},
       message: typeof e.message === "string" ? e.message.slice(0, 4e3) : "",
       ...typeof e.name === "string" ? { name: e.name.slice(0, 200) } : {},
+      ...typeof e.durationMs === "number" && Number.isFinite(e.durationMs) ? { durationMs: Math.max(0, Math.min(12e4, e.durationMs)) } : {},
       ...typeof e.stack === "string" ? { stack: e.stack.slice(0, 32e3) } : {},
       ...typeof e.errorType === "string" ? { errorType: e.errorType.slice(0, 200) } : {},
       ...typeof e.filename === "string" ? { filename: e.filename.split("?")[0].slice(0, 1e3) } : {},
@@ -303,6 +307,7 @@ function installAutterAutoFlush(options = {}) {
   const warnOnUnflushedExit = options.warnOnUnflushedExit !== false;
   const timeoutMs = Math.max(100, options.timeoutMs ?? 3e3);
   const signals = options.signals ?? DEFAULT_SIGNALS;
+  const flushOnUncaughtException = options.flushOnUncaughtException !== false;
   let disposed = false;
   let inFlight = null;
   const doFlush = async () => {
@@ -348,6 +353,19 @@ function installAutterAutoFlush(options = {}) {
     return inFlight;
   };
   const signalCounts = /* @__PURE__ */ new Map();
+  let handlingUncaughtException = false;
+  const onUncaughtException = (error) => {
+    if (process.listenerCount("uncaughtException") > 1) return;
+    if (handlingUncaughtException) return;
+    handlingUncaughtException = true;
+    logger.error(error instanceof Error ? error.stack ?? error.message : String(error));
+    const keepAlive = setTimeout(() => {
+    }, timeoutMs + 50);
+    void flush("uncaughtException").finally(() => {
+      clearTimeout(keepAlive);
+      process.exit(1);
+    });
+  };
   const onSignal = (signal) => {
     const count = (signalCounts.get(signal) ?? 0) + 1;
     signalCounts.set(signal, count);
@@ -387,6 +405,9 @@ function installAutterAutoFlush(options = {}) {
   };
   const signalHandlers = /* @__PURE__ */ new Map();
   process.on("beforeExit", onBeforeExit);
+  if (flushOnUncaughtException) {
+    process.on("uncaughtException", onUncaughtException);
+  }
   for (const signal of signals) {
     const handler = () => onSignal(signal);
     signalHandlers.set(signal, handler);
@@ -398,6 +419,7 @@ function installAutterAutoFlush(options = {}) {
     dispose() {
       disposed = true;
       process.removeListener("beforeExit", onBeforeExit);
+      process.removeListener("uncaughtException", onUncaughtException);
       process.removeListener("exit", onExit);
       for (const [signal, handler] of signalHandlers) {
         process.removeListener(signal, handler);
@@ -653,6 +675,51 @@ function makeRedactor(options) {
   return (attributes) => redactWith(attributes, r);
 }
 
+// src/memory.ts
+import { PerformanceObserver } from "perf_hooks";
+import { getHeapStatistics } from "v8";
+import { metrics } from "@opentelemetry/api";
+function startMemoryMetrics() {
+  const meter = metrics.getMeter("autter-process-memory");
+  const rss = meter.createObservableGauge("autter.process.memory.rss", { unit: "By" });
+  const heapUsed = meter.createObservableGauge("autter.process.memory.heap.used", { unit: "By" });
+  const heapLimit = meter.createObservableGauge("autter.process.memory.heap.limit", { unit: "By" });
+  const containerLimit = meter.createObservableGauge("autter.process.memory.limit", { unit: "By" });
+  const afterGc = meter.createObservableGauge("autter.process.memory.heap.after_gc", { unit: "By" });
+  const gcCount = meter.createObservableCounter("autter.process.gc.count", { unit: "{collection}" });
+  const gcDuration = meter.createObservableCounter("autter.process.gc.duration", { unit: "ms" });
+  let collections = 0;
+  let durationMs = 0;
+  let lastAfterGc = null;
+  const callbacks = [
+    [rss, (result) => result.observe(process.memoryUsage().rss)],
+    [heapUsed, (result) => result.observe(process.memoryUsage().heapUsed)],
+    [heapLimit, (result) => result.observe(getHeapStatistics().heap_size_limit)],
+    [containerLimit, (result) => {
+      const constrained = process.constrainedMemory?.() ?? 0;
+      if (constrained > 0) result.observe(constrained);
+    }],
+    [afterGc, (result) => {
+      if (lastAfterGc !== null) result.observe(lastAfterGc);
+    }],
+    [gcCount, (result) => result.observe(collections)],
+    [gcDuration, (result) => result.observe(durationMs)]
+  ];
+  for (const [instrument, callback] of callbacks) instrument.addCallback(callback);
+  const observer = new PerformanceObserver((list) => {
+    for (const entry of list.getEntries()) {
+      collections++;
+      durationMs += entry.duration;
+      lastAfterGc = process.memoryUsage().heapUsed;
+    }
+  });
+  observer.observe({ entryTypes: ["gc"] });
+  return () => {
+    observer.disconnect();
+    for (const [instrument, callback] of callbacks) instrument.removeCallback(callback);
+  };
+}
+
 // src/server.ts
 var LLM_MARKER_ATTRIBUTES = [
   "gen_ai.operation.name",
@@ -985,7 +1052,7 @@ function initAutterServer(options) {
   activeRedactor = makeRedactor(options.redactAttributes ?? true);
   const resource = new Resource({
     [ATTR_SERVICE_NAME]: options.service,
-    "service.instance.id": randomUUID(),
+    "service.instance.id": (options.instanceId || process.env.AUTTER_RUNTIME_INSTANCE_ID || randomUUID()).slice(0, 128),
     ...options.release ? { [ATTR_SERVICE_VERSION]: options.release } : {},
     "deployment.environment": environment,
     // Tells the ingester request metrics arrive on the metrics pipe, so
@@ -1050,6 +1117,7 @@ function initAutterServer(options) {
     ]
   });
   sdk.start();
+  const stopMemoryMetrics = options.memoryMetrics === false ? null : startMemoryMetrics();
   const alwaysOnProvider = new BasicTracerProvider({
     resource,
     sampler: new AlwaysOnSampler(),
@@ -1076,13 +1144,24 @@ function initAutterServer(options) {
     const span = reuseActive ? activeSpan : errorTracer.startSpan(isError ? error.name : "Error");
     span.setAttributes({ "autter.severity": "error", ...redacted });
     if (isError && error.stack) {
-      span.recordException(error);
+      if (redacted["autter.handled"] === true) {
+        span.addEvent("exception", {
+          "exception.type": error.name,
+          "exception.message": message,
+          "exception.stacktrace": error.stack,
+          "autter.handled": true,
+          "autter.sampled": redacted["autter.sampled"] === true
+        });
+      } else {
+        span.recordException(error);
+      }
     } else {
       const stack = new Error().stack?.split("\n").filter((line, i) => i === 0 || !line.includes("captureException")).join("\n");
       span.addEvent("exception", {
         "exception.type": isError ? error.name : "Error",
         "exception.message": message,
-        ...stack ? { "exception.stacktrace": stack } : {}
+        ...stack ? { "exception.stacktrace": stack } : {},
+        ...redacted["autter.handled"] === true ? { "autter.handled": true, "autter.sampled": redacted["autter.sampled"] === true } : {}
       });
     }
     span.setStatus({ code: SpanStatusCode.ERROR, message });
@@ -1106,15 +1185,28 @@ function initAutterServer(options) {
     span.setStatus({ code: SpanStatusCode.ERROR, message });
     span.end();
   }
+  function reportOutcome2(name, message, attributes) {
+    errorTraceBuffer?.retainActiveTrace();
+    telemetryStats.markCaptured();
+    const activeSpan = trace.getActiveSpan();
+    const reuseActive = activeSpan?.isRecording() === true;
+    const span = reuseActive ? activeSpan : errorTracer.startSpan("OutcomeFailure");
+    const safeOutcome = activeRedactor({ "autter.outcome.name": name.slice(0, 200), "autter.outcome.message": message.slice(0, 1e3) });
+    const safeName = String(safeOutcome["autter.outcome.name"] ?? "operation");
+    const safeMessage = String(safeOutcome["autter.outcome.message"] ?? "failed");
+    span.addEvent("autter.outcome", {
+      ...activeRedactor(attributes),
+      "autter.outcome.status": "error",
+      "autter.outcome.name": safeName,
+      "autter.outcome.message": safeMessage
+    });
+    span.setStatus({ code: SpanStatusCode.ERROR, message: safeMessage });
+    if (!reuseActive) span.end();
+  }
   if (options.captureGlobalErrors !== false) {
     process.on("uncaughtExceptionMonitor", (err) => {
       captureException2(err, { "autter.unhandled": true });
-      void flushTarget.forceFlush();
-    });
-    process.on("unhandledRejection", (reason) => {
-      captureException2(reason, {
-        "autter.unhandled": true,
-        ...reason instanceof Error ? {} : { "autter.severity": "warning" }
+      if (options.autoFlush === false) void Promise.resolve(flushTarget.forceFlush()).catch(() => {
       });
     });
   }
@@ -1142,10 +1234,12 @@ function initAutterServer(options) {
   const server = {
     captureException: captureException2,
     captureMessage: captureMessage2,
+    reportOutcome: reportOutcome2,
     withProcessSpan: (name, fn, attributes) => runWithSpan(processTracer, name, fn, activeRedactor(attributes)),
     withLlmCall: (info, fn) => runLlmSpan(llmTracer, info, fn),
     trackLlmCall: (call) => recordLlmCall(llmTracer, call),
     shutdown: async () => {
+      stopMemoryMetrics?.();
       active = null;
       activeAlwaysOnProvider = null;
       autoFlushHandle?.dispose();
@@ -1203,6 +1297,21 @@ function captureMessage(message, severity = "warning", attributes) {
   span.setStatus({ code: SpanStatusCode.ERROR, message });
   span.end();
 }
+function reportOutcome(name, message, attributes) {
+  if (active) return active.reportOutcome(name, message, attributes);
+  const span = trace.getTracer("autter-outcomes").startSpan("OutcomeFailure");
+  const safeOutcome = redactAttributes({ "autter.outcome.name": name.slice(0, 200), "autter.outcome.message": message.slice(0, 1e3) });
+  const safeName = String(safeOutcome["autter.outcome.name"] ?? "operation");
+  const safeMessage = String(safeOutcome["autter.outcome.message"] ?? "failed");
+  span.addEvent("autter.outcome", {
+    ...redactAttributes(attributes),
+    "autter.outcome.status": "error",
+    "autter.outcome.name": safeName,
+    "autter.outcome.message": safeMessage
+  });
+  span.setStatus({ code: SpanStatusCode.ERROR, message: safeMessage });
+  span.end();
+}
 function makeSafeCapture(options) {
   const clean = (attributes) => attributes ? { ...redactAttributes(attributes, options) } : void 0;
   return {
@@ -1455,6 +1564,50 @@ function instrumentLlmClient(client, options) {
   }
   return deepProxy(client);
 }
+
+// src/caught-exceptions.ts
+import inspector from "inspector";
+function startCaughtExceptionSampler(options = {}) {
+  const rate = Math.max(0, Math.min(1, options.sampleRate ?? 0.01));
+  const cap = Math.max(1, Math.min(100, options.maxPerMinute ?? 10));
+  const session = new inspector.Session();
+  let active2 = true;
+  let minute = 0;
+  let sent = 0;
+  session.connect();
+  session.on("Debugger.paused", (message) => {
+    session.post("Debugger.resume", () => {
+    });
+    if (!active2 || message.params.reason !== "exception") return;
+    const nowMinute = Math.floor(Date.now() / 6e4);
+    if (nowMinute !== minute) {
+      minute = nowMinute;
+      sent = 0;
+    }
+    if (sent >= cap || Math.random() >= rate) return;
+    sent++;
+    const frames = message.params.callFrames.slice(0, 8).filter((frame) => frame.url && !frame.url.startsWith("node:")).map((frame) => `    at ${frame.functionName || "anonymous"} (${frame.url.split("?")[0]}:${frame.location.lineNumber + 1}:${(frame.location.columnNumber ?? 0) + 1})`);
+    if (!frames.length) return;
+    const error = new Error("Sampled caught exception");
+    error.name = "CaughtException";
+    error.stack = `${error.name}: ${error.message}
+${frames.join("\n")}`;
+    queueMicrotask(() => {
+      if (active2) captureException(error, { "autter.handled": true, "autter.sampled": true });
+    });
+  });
+  session.post("Debugger.enable", (error) => {
+    if (!error && active2) session.post("Debugger.setPauseOnExceptions", { state: "all" }, () => {
+    });
+  });
+  return { stop() {
+    if (!active2) return;
+    active2 = false;
+    session.post("Debugger.setPauseOnExceptions", { state: "none" }, () => {
+      session.post("Debugger.disable", () => session.disconnect());
+    });
+  } };
+}
 export {
   captureException,
   captureMessage,
@@ -1466,7 +1619,9 @@ export {
   instrumentLlmClient,
   makeSafeCapture,
   redactAttributes,
+  reportOutcome,
   sanitizeBrowserPayload,
+  startCaughtExceptionSampler,
   trackLlmCall,
   withLlmCall,
   withProcessSpan

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@autter/runtime-node",
-	"version": "1.3.1",
+	"version": "1.3.3",
 	"description": "Autter Runtime for Node.js: same-origin browser relay handler + curated OpenTelemetry server tracker",
 	"license": "MIT",
 	"type": "module",