@autter/runtime-node 1.3.0 → 1.3.2

package/README.md

@@ -187,6 +187,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) } : {},
@@ -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);
@@ -1096,13 +1130,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: import_api.SpanStatusCode.ERROR, message });
@@ -1126,15 +1171,28 @@ function initAutterServer(options) {
     span.setStatus({ code: import_api.SpanStatusCode.ERROR, message });
     span.end();
   }
+  function reportOutcome2(name, message, attributes) {
+    errorTraceBuffer?.retainActiveTrace();
+    telemetryStats.markCaptured();
+    const activeSpan = import_api.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_api.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,6 +1220,7 @@ 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),
@@ -1223,6 +1282,21 @@ function captureMessage(message, severity = "warning", attributes) {
   span.setStatus({ code: import_api.SpanStatusCode.ERROR, message });
   span.end();
 }
+function reportOutcome(name, message, attributes) {
+  if (active) return active.reportOutcome(name, message, attributes);
+  const span = import_api.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_api.SpanStatusCode.ERROR, message: safeMessage });
+  span.end();
+}
 function makeSafeCapture(options) {
   const clean = (attributes) => attributes ? { ...redactAttributes(attributes, options) } : void 0;
   return {
@@ -1472,6 +1546,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 +1602,9 @@ function instrumentLlmClient(client, options) {
   instrumentLlmClient,
   makeSafeCapture,
   redactAttributes,
+  reportOutcome,
   sanitizeBrowserPayload,
+  startCaughtExceptionSampler,
   trackLlmCall,
   withLlmCall,
   withProcessSpan

package/dist/index.d.cts

@@ -206,6 +206,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 +266,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 +326,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 +348,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 +383,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

@@ -206,6 +206,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 +266,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 +326,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 +348,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 +383,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);
@@ -1076,13 +1098,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 +1139,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,6 +1188,7 @@ 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),
@@ -1203,6 +1250,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 +1517,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 +1572,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.0",
+	"version": "1.3.2",
 	"description": "Autter Runtime for Node.js: same-origin browser relay handler + curated OpenTelemetry server tracker",
 	"license": "MIT",
 	"type": "module",