@autter/runtime-node 1.5.0 → 1.6.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { IncomingMessage, ServerResponse } from 'node:http';
-import { b as RedactOptions, c as Redactor$1, d as RuntimeLogLevel, e as RuntimeOperationKind, f as RuntimeSink, F as FileSinkOptions, g as RuntimeLogContext, a as RuntimeOutcome, h as RuntimeCarrier } from './sinks-RFV76lF1.cjs';
-export { i as CODE_PATTERN, j as ClientErrorBody, k as ConsoleSinkOptions, O as OtlpSinkOptions, l as RuntimeError, n as RuntimeErrorCatalog, o as RuntimeErrorDefinition, p as RuntimeErrorExtras, q as RuntimeErrorFactory, r as RuntimeErrorLike, s as RuntimeErrorOptions, R as RuntimeEvent, t as RuntimeLogContextValue, u as RuntimeSinkContext, v as consoleSink, w as defineRuntimeErrors, x as errorAttributes, y as fileSink, z as isRuntimeErrorLike, A as otlpSink, B as redactAttributes, D as redactText, E as toClientError } from './sinks-RFV76lF1.cjs';
+import { b as RedactOptions, c as Redactor$1, d as RuntimeLogLevel, e as RuntimeOperationKind, f as RuntimeSink, F as FileSinkOptions, g as RuntimeLogContext, a as RuntimeOutcome, h as RuntimeCarrier, B as BreadcrumbInput } from './sinks-CPGDyfU8.cjs';
+export { i as Breadcrumb, j as BreadcrumbLevel, k as BreadcrumbType, l as CODE_PATTERN, n as ClientErrorBody, o as ConsoleSinkOptions, O as OtlpSinkOptions, p as RuntimeError, q as RuntimeErrorCatalog, r as RuntimeErrorDefinition, s as RuntimeErrorExtras, t as RuntimeErrorFactory, u as RuntimeErrorLike, v as RuntimeErrorOptions, R as RuntimeEvent, w as RuntimeLogContextValue, x as RuntimeSinkContext, y as consoleSink, z as defineRuntimeErrors, A as errorAttributes, D as fileSink, E as isRuntimeErrorLike, G as otlpSink, H as redactAttributes, I as redactText, J as toClientError } from './sinks-CPGDyfU8.cjs';
 import { Attributes } from '@opentelemetry/api';
 
 /**
@@ -242,8 +242,23 @@ interface AutterServerOptions {
     metricIntervalMs?: number;
     /** Collect RSS, heap, limit, and GC signals per process instance. Default true. */
     memoryMetrics?: boolean;
-    /** Capture crashing exceptions via process.uncaughtExceptionMonitor (default true). */
+    /**
+     * Capture crashing exceptions via process.uncaughtExceptionMonitor, and
+     * unhandled promise rejections (see `captureUnhandledRejections`).
+     * Default true; false turns both off.
+     */
     captureGlobalErrors?: boolean;
+    /**
+     * Record unhandled promise rejections as errors (severity "error",
+     * `autter.unhandled_rejection: true`). Never changes whether the process
+     * crashes: when Node would have crashed (the default
+     * `--unhandled-rejections=throw` mode and no other `unhandledRejection`
+     * listener), the rejection is rethrown on the next tick, so the process
+     * still exits with code 1 and the crash is recorded as fatal like any
+     * other. False restores 1.5.0 behaviour: a rejection is only seen when it
+     * crashes the process. Default true.
+     */
+    captureUnhandledRejections?: boolean;
     /**
      * Flush all exporters when the process exits (`beforeExit`, SIGINT,
      * SIGTERM) so a forgotten `shutdown()` doesn't silently drop buffered
@@ -344,7 +359,12 @@ interface TrackedLlmCall extends LlmCallInfo, LlmUsage {
     error?: unknown;
 }
 interface AutterServer {
-    /** Report a handled exception. Always recorded (never sampled out). */
+    /**
+     * Report a handled exception. Always recorded (never sampled out).
+     * `attributes.fingerprint` (a string or up to 10 strings) groups every
+     * error that carries it into one issue (ingester 1.6.0+); it is sent as
+     * `autter.fingerprint` on the exception event, not as a span attribute.
+     */
     captureException(error: unknown, attributes?: Attributes): void;
     /**
      * Report a warning (or info) without an exception — deprecated code
@@ -566,6 +586,17 @@ interface RuntimeRequestOptions {
     /** Receives the log flush promise after the response (serverless `waitUntil`). */
     waitUntil?: (promise: Promise<unknown>) => void;
 }
+/**
+ * Report an error that reached a request boundary — a framework error hook,
+ * an exception filter, Next.js `onRequestError`. Unlike `captureException`
+ * it reports each error once (an error a handler or another hook already
+ * captured is skipped), and it records the exception, with its stack, on the
+ * request's HTTP server span even when a child span is active, so the failed
+ * request and its exception stay one issue. When the error was already
+ * captured (e.g. by `withRuntimeRequest`), `attributes` still go on the
+ * request span, without a second exception.
+ */
+declare function captureRequestError(error: unknown, attributes?: Attributes): void;
 /**
  * Express / Connect middleware. Mount it early (before routers; after body
  * parsers is fine too):
@@ -605,6 +636,101 @@ declare function autterFastify(fastify: FastifyLikeInstance, options: AutterRequ
  */
 declare function withRuntimeRequest<A extends unknown[]>(handler: (request: Request, ...rest: A) => Response | Promise<Response>, options?: RuntimeRequestOptions): (request: Request, ...rest: A) => Promise<Response>;
 
+/**
+ * Server error hooks for Express, Fastify and Koa. Each records the error,
+ * with its stack, on the request's span through `captureException`, then
+ * lets the framework carry on exactly as before (same error, same response).
+ * Without them a thrown error only reaches Autter as the 500 the framework
+ * answers with: a stackless `HttpServerError` grouped by route.
+ *
+ * No framework is a dependency: the request/reply shapes are structural.
+ */
+interface AutterErrorHandlerOptions {
+    /**
+     * Which errors to report. Default: errors with status ≥ 500 (or no
+     * status), RuntimeErrors and any error with a valid code — so 4xx errors
+     * such as `ctx.throw(404)` or validation failures stay out of your issues.
+     * `true` reports every error; a predicate decides per error.
+     */
+    capture?: boolean | ((error: unknown) => boolean);
+}
+/**
+ * Express (4/5) / Connect error middleware that reports the error and calls
+ * `next(err)` unchanged. Mount it after your routes and before your own
+ * error handlers:
+ *
+ *   app.use(autterErrorHandler());
+ *   app.use((err, req, res, next) => res.status(500).send("…"));   // yours
+ *
+ * (`autterErrorResponse()` reports too, and also answers the request.)
+ */
+declare function autterErrorHandler(options?: AutterErrorHandlerOptions): (error: unknown, req: IncomingMessage, _res: ServerResponse, next: (error?: unknown) => void) => void;
+interface FastifyHookInstance {
+    addHook(name: string, hook: (...args: never[]) => unknown): unknown;
+}
+/**
+ * Fastify (4/5) `onError` hook that reports the error; Fastify's error
+ * handler still builds the response. Register it as a plugin, or call it on
+ * the instance directly:
+ *
+ *   app.register(autterFastifyErrors);            // or: autterFastifyErrors(app)
+ *   app.register(autterFastifyErrors, { capture: true });
+ *
+ * It skips plugin encapsulation, so it covers every route. `autterFastify`
+ * (request summaries) already includes the same hook; you don't need both.
+ */
+declare function autterFastifyErrors(fastify: FastifyHookInstance, options?: AutterErrorHandlerOptions, done?: (error?: Error) => void): void;
+interface KoaContextLike {
+    req?: IncomingMessage;
+}
+/**
+ * Koa (2/3) middleware that reports errors thrown downstream and rethrows
+ * them, so Koa's own error handling (and `app.on("error")`) is unchanged.
+ * Mount it first:
+ *
+ *   app.use(autterKoa());
+ */
+declare function autterKoa(options?: AutterErrorHandlerOptions): (ctx: KoaContextLike, next: () => Promise<unknown>) => Promise<void>;
+
+/**
+ * Unhandled promise rejections, recorded without changing whether the
+ * process crashes.
+ *
+ * Node's `--unhandled-rejections` mode decides what an unhandled rejection
+ * does, and most modes behave differently once ANY `unhandledRejection`
+ * listener exists:
+ *
+ *   mode                   no listener                      with a listener
+ *   throw (default)        crash (uncaught exception)        listener only — no crash
+ *   strict                 crash, then the listener          same
+ *   warn                   warning                           listener + warning
+ *   warn-with-error-code   warning + exit code 1             listener only
+ *   none                   nothing                           listener only
+ *
+ * Adding our listener would therefore silently stop the default crash. So
+ * when ours is the only listener we do what Node would have done:
+ *
+ *   - throw: rethrow the reason (or Node's `UnhandledPromiseRejection`
+ *     wrapper for a non-error reason) on the next tick. The process crashes
+ *     with exit code 1 as before, and `uncaughtExceptionMonitor` records it
+ *     as a crash (fatal), exactly as it did without this listener. The one
+ *     visible difference: `uncaughtException` listeners and the monitor
+ *     receive origin `"uncaughtException"` instead of `"unhandledRejection"`.
+ *   - warn-with-error-code: print Node's warning and set `process.exitCode = 1`.
+ *   - strict: no listener at all — Node raises the rejection as an uncaught
+ *     exception first, which the crash monitor already records.
+ *
+ * Everything else — the app has its own listener (it decides what happens),
+ * or the mode never crashes — is recorded as an error (severity "error", not
+ * fatal) with `autter.unhandled_rejection: true`.
+ */
+type UnhandledRejectionsMode = "throw" | "strict" | "warn" | "warn-with-error-code" | "none";
+/**
+ * Node's effective `--unhandled-rejections` mode: `NODE_OPTIONS` first, then
+ * the command line (which wins), last occurrence wins. Default `"throw"`.
+ */
+declare function unhandledRejectionsMode(execArgv?: readonly string[], nodeOptions?: string | undefined): UnhandledRejectionsMode;
+
 /**
  * Logger-only mode: requests, operations, coded errors, sinks and enrichers
  * WITHOUT starting the OpenTelemetry NodeSDK. For apps that already run
@@ -629,8 +755,12 @@ interface AutterLoggingOptions {
     logging?: RuntimeLoggingOptions;
     /** Same semantics as initAutterServer. Default true. */
     redactAttributes?: boolean | RedactOptions;
-    /** Capture crashes via process.uncaughtExceptionMonitor. Default true. */
+    /** Capture crashes via process.uncaughtExceptionMonitor, and unhandled
+     * rejections (`captureUnhandledRejections`). Default true. */
     captureGlobalErrors?: boolean;
+    /** Same semantics as initAutterServer: record unhandled rejections as
+     * errors without changing whether the process crashes. Default true. */
+    captureUnhandledRejections?: boolean;
     /** Flush records on beforeExit/SIGINT/SIGTERM. Default true. */
     autoFlush?: boolean;
     debug?: boolean;
@@ -679,7 +809,9 @@ declare function enrichDeployment(env?: Record<string, string | undefined>): Run
  * Adding a feature: append an entry to compat-manifest.json with the first
  * ingester release that handles it, the migrations it writes to, its route
  * (if it has its own), and the first SDK release that emits it. The
- * consistency test in compat.test.ts checks ids, migrations and routes.
+ * consistency test in compat.test.ts checks ids, migrations and routes, and
+ * that no version is ahead of its package's package.json: a feature for the
+ * next release bumps the packages it names in the same change.
  */
 interface CompatFeature {
     id: string;
@@ -811,4 +943,13 @@ interface DoctorReport {
 }
 declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;
 
-export { type AutoFlushHandle, type AutoFlushOptions, type AutterErrorResponseOptions, type AutterLogging, type AutterLoggingOptions, type AutterRequestsOptions, type AutterServer, type AutterServerOptions, type AutterSeverity, COMPAT_MANIFEST, type CompatIssue, type DoctorOptions, type DoctorReport, FileSinkOptions, type FlushTarget, INGESTER_VERSION_HEADER, type IngesterCompatInfo, type InstrumentLlmOptions, type LlmCallHandle, type LlmCallInfo, type LlmUsage, RedactOptions, type RelayOptions, RuntimeCarrier, type RuntimeContextHandle, type RuntimeEnrichContext, type RuntimeEnrichEvent, type RuntimeEnricher, RuntimeLogContext, RuntimeLogLevel, type RuntimeLoggingOptions, type RuntimeOperation, RuntimeOperationKind, type RuntimeOperationOptions, RuntimeOutcome, type RuntimeRequestOptions, RuntimeSink, SDK_IDENTITY, type SafeCapture, type SdkIdentity, type TrackedLlmCall, autterErrorResponse, autterFastify, autterRequests, captureException, captureMessage, createBrowserRelayFetchHandler, createBrowserRelayHandler, createRuntimeLogger, emitLlmSelftestTrace, enrichDeployment, enrichEdgeGeo, enrichRequestSize, enrichUserAgent, evaluateCompat, fetchIngesterCompat, flushRuntimeLogs, initAutterLogging, initAutterServer, installAutterAutoFlush, instrumentLlmClient, makeSafeCapture, reportOutcome, runDoctor, runInBackground, runtimeContext, runtimeLogStats, runtimeLogger, sanitizeBrowserPayload, startCaughtExceptionSampler, trackLlmCall, withLlmCall, withProcessSpan, withRuntimeOperation, withRuntimeRequest };
+/**
+ * Record a step (type "custom" unless you say otherwise) on the current
+ * request. The next exception captured in it carries the last 30. Message
+ * and data are scrubbed with your `redact` settings. Never throws.
+ *
+ *   addBreadcrumb({ message: "Loaded cart", data: { items: 3 } });
+ */
+declare function addBreadcrumb(input: BreadcrumbInput): void;
+
+export { type AutoFlushHandle, type AutoFlushOptions, type AutterErrorHandlerOptions, type AutterErrorResponseOptions, type AutterLogging, type AutterLoggingOptions, type AutterRequestsOptions, type AutterServer, type AutterServerOptions, type AutterSeverity, BreadcrumbInput, COMPAT_MANIFEST, type CompatIssue, type DoctorOptions, type DoctorReport, FileSinkOptions, type FlushTarget, INGESTER_VERSION_HEADER, type IngesterCompatInfo, type InstrumentLlmOptions, type LlmCallHandle, type LlmCallInfo, type LlmUsage, RedactOptions, type RelayOptions, RuntimeCarrier, type RuntimeContextHandle, type RuntimeEnrichContext, type RuntimeEnrichEvent, type RuntimeEnricher, RuntimeLogContext, RuntimeLogLevel, type RuntimeLoggingOptions, type RuntimeOperation, RuntimeOperationKind, type RuntimeOperationOptions, RuntimeOutcome, type RuntimeRequestOptions, RuntimeSink, SDK_IDENTITY, type SafeCapture, type SdkIdentity, type TrackedLlmCall, type UnhandledRejectionsMode, addBreadcrumb, autterErrorHandler, autterErrorResponse, autterFastify, autterFastifyErrors, autterKoa, autterRequests, captureException, captureMessage, captureRequestError, createBrowserRelayFetchHandler, createBrowserRelayHandler, createRuntimeLogger, emitLlmSelftestTrace, enrichDeployment, enrichEdgeGeo, enrichRequestSize, enrichUserAgent, evaluateCompat, fetchIngesterCompat, flushRuntimeLogs, initAutterLogging, initAutterServer, installAutterAutoFlush, instrumentLlmClient, makeSafeCapture, reportOutcome, runDoctor, runInBackground, runtimeContext, runtimeLogStats, runtimeLogger, sanitizeBrowserPayload, startCaughtExceptionSampler, trackLlmCall, unhandledRejectionsMode, withLlmCall, withProcessSpan, withRuntimeOperation, withRuntimeRequest };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { IncomingMessage, ServerResponse } from 'node:http';
-import { b as RedactOptions, c as Redactor$1, d as RuntimeLogLevel, e as RuntimeOperationKind, f as RuntimeSink, F as FileSinkOptions, g as RuntimeLogContext, a as RuntimeOutcome, h as RuntimeCarrier } from './sinks-RFV76lF1.js';
-export { i as CODE_PATTERN, j as ClientErrorBody, k as ConsoleSinkOptions, O as OtlpSinkOptions, l as RuntimeError, n as RuntimeErrorCatalog, o as RuntimeErrorDefinition, p as RuntimeErrorExtras, q as RuntimeErrorFactory, r as RuntimeErrorLike, s as RuntimeErrorOptions, R as RuntimeEvent, t as RuntimeLogContextValue, u as RuntimeSinkContext, v as consoleSink, w as defineRuntimeErrors, x as errorAttributes, y as fileSink, z as isRuntimeErrorLike, A as otlpSink, B as redactAttributes, D as redactText, E as toClientError } from './sinks-RFV76lF1.js';
+import { b as RedactOptions, c as Redactor$1, d as RuntimeLogLevel, e as RuntimeOperationKind, f as RuntimeSink, F as FileSinkOptions, g as RuntimeLogContext, a as RuntimeOutcome, h as RuntimeCarrier, B as BreadcrumbInput } from './sinks-CPGDyfU8.js';
+export { i as Breadcrumb, j as BreadcrumbLevel, k as BreadcrumbType, l as CODE_PATTERN, n as ClientErrorBody, o as ConsoleSinkOptions, O as OtlpSinkOptions, p as RuntimeError, q as RuntimeErrorCatalog, r as RuntimeErrorDefinition, s as RuntimeErrorExtras, t as RuntimeErrorFactory, u as RuntimeErrorLike, v as RuntimeErrorOptions, R as RuntimeEvent, w as RuntimeLogContextValue, x as RuntimeSinkContext, y as consoleSink, z as defineRuntimeErrors, A as errorAttributes, D as fileSink, E as isRuntimeErrorLike, G as otlpSink, H as redactAttributes, I as redactText, J as toClientError } from './sinks-CPGDyfU8.js';
 import { Attributes } from '@opentelemetry/api';
 
 /**
@@ -242,8 +242,23 @@ interface AutterServerOptions {
     metricIntervalMs?: number;
     /** Collect RSS, heap, limit, and GC signals per process instance. Default true. */
     memoryMetrics?: boolean;
-    /** Capture crashing exceptions via process.uncaughtExceptionMonitor (default true). */
+    /**
+     * Capture crashing exceptions via process.uncaughtExceptionMonitor, and
+     * unhandled promise rejections (see `captureUnhandledRejections`).
+     * Default true; false turns both off.
+     */
     captureGlobalErrors?: boolean;
+    /**
+     * Record unhandled promise rejections as errors (severity "error",
+     * `autter.unhandled_rejection: true`). Never changes whether the process
+     * crashes: when Node would have crashed (the default
+     * `--unhandled-rejections=throw` mode and no other `unhandledRejection`
+     * listener), the rejection is rethrown on the next tick, so the process
+     * still exits with code 1 and the crash is recorded as fatal like any
+     * other. False restores 1.5.0 behaviour: a rejection is only seen when it
+     * crashes the process. Default true.
+     */
+    captureUnhandledRejections?: boolean;
     /**
      * Flush all exporters when the process exits (`beforeExit`, SIGINT,
      * SIGTERM) so a forgotten `shutdown()` doesn't silently drop buffered
@@ -344,7 +359,12 @@ interface TrackedLlmCall extends LlmCallInfo, LlmUsage {
     error?: unknown;
 }
 interface AutterServer {
-    /** Report a handled exception. Always recorded (never sampled out). */
+    /**
+     * Report a handled exception. Always recorded (never sampled out).
+     * `attributes.fingerprint` (a string or up to 10 strings) groups every
+     * error that carries it into one issue (ingester 1.6.0+); it is sent as
+     * `autter.fingerprint` on the exception event, not as a span attribute.
+     */
     captureException(error: unknown, attributes?: Attributes): void;
     /**
      * Report a warning (or info) without an exception — deprecated code
@@ -566,6 +586,17 @@ interface RuntimeRequestOptions {
     /** Receives the log flush promise after the response (serverless `waitUntil`). */
     waitUntil?: (promise: Promise<unknown>) => void;
 }
+/**
+ * Report an error that reached a request boundary — a framework error hook,
+ * an exception filter, Next.js `onRequestError`. Unlike `captureException`
+ * it reports each error once (an error a handler or another hook already
+ * captured is skipped), and it records the exception, with its stack, on the
+ * request's HTTP server span even when a child span is active, so the failed
+ * request and its exception stay one issue. When the error was already
+ * captured (e.g. by `withRuntimeRequest`), `attributes` still go on the
+ * request span, without a second exception.
+ */
+declare function captureRequestError(error: unknown, attributes?: Attributes): void;
 /**
  * Express / Connect middleware. Mount it early (before routers; after body
  * parsers is fine too):
@@ -605,6 +636,101 @@ declare function autterFastify(fastify: FastifyLikeInstance, options: AutterRequ
  */
 declare function withRuntimeRequest<A extends unknown[]>(handler: (request: Request, ...rest: A) => Response | Promise<Response>, options?: RuntimeRequestOptions): (request: Request, ...rest: A) => Promise<Response>;
 
+/**
+ * Server error hooks for Express, Fastify and Koa. Each records the error,
+ * with its stack, on the request's span through `captureException`, then
+ * lets the framework carry on exactly as before (same error, same response).
+ * Without them a thrown error only reaches Autter as the 500 the framework
+ * answers with: a stackless `HttpServerError` grouped by route.
+ *
+ * No framework is a dependency: the request/reply shapes are structural.
+ */
+interface AutterErrorHandlerOptions {
+    /**
+     * Which errors to report. Default: errors with status ≥ 500 (or no
+     * status), RuntimeErrors and any error with a valid code — so 4xx errors
+     * such as `ctx.throw(404)` or validation failures stay out of your issues.
+     * `true` reports every error; a predicate decides per error.
+     */
+    capture?: boolean | ((error: unknown) => boolean);
+}
+/**
+ * Express (4/5) / Connect error middleware that reports the error and calls
+ * `next(err)` unchanged. Mount it after your routes and before your own
+ * error handlers:
+ *
+ *   app.use(autterErrorHandler());
+ *   app.use((err, req, res, next) => res.status(500).send("…"));   // yours
+ *
+ * (`autterErrorResponse()` reports too, and also answers the request.)
+ */
+declare function autterErrorHandler(options?: AutterErrorHandlerOptions): (error: unknown, req: IncomingMessage, _res: ServerResponse, next: (error?: unknown) => void) => void;
+interface FastifyHookInstance {
+    addHook(name: string, hook: (...args: never[]) => unknown): unknown;
+}
+/**
+ * Fastify (4/5) `onError` hook that reports the error; Fastify's error
+ * handler still builds the response. Register it as a plugin, or call it on
+ * the instance directly:
+ *
+ *   app.register(autterFastifyErrors);            // or: autterFastifyErrors(app)
+ *   app.register(autterFastifyErrors, { capture: true });
+ *
+ * It skips plugin encapsulation, so it covers every route. `autterFastify`
+ * (request summaries) already includes the same hook; you don't need both.
+ */
+declare function autterFastifyErrors(fastify: FastifyHookInstance, options?: AutterErrorHandlerOptions, done?: (error?: Error) => void): void;
+interface KoaContextLike {
+    req?: IncomingMessage;
+}
+/**
+ * Koa (2/3) middleware that reports errors thrown downstream and rethrows
+ * them, so Koa's own error handling (and `app.on("error")`) is unchanged.
+ * Mount it first:
+ *
+ *   app.use(autterKoa());
+ */
+declare function autterKoa(options?: AutterErrorHandlerOptions): (ctx: KoaContextLike, next: () => Promise<unknown>) => Promise<void>;
+
+/**
+ * Unhandled promise rejections, recorded without changing whether the
+ * process crashes.
+ *
+ * Node's `--unhandled-rejections` mode decides what an unhandled rejection
+ * does, and most modes behave differently once ANY `unhandledRejection`
+ * listener exists:
+ *
+ *   mode                   no listener                      with a listener
+ *   throw (default)        crash (uncaught exception)        listener only — no crash
+ *   strict                 crash, then the listener          same
+ *   warn                   warning                           listener + warning
+ *   warn-with-error-code   warning + exit code 1             listener only
+ *   none                   nothing                           listener only
+ *
+ * Adding our listener would therefore silently stop the default crash. So
+ * when ours is the only listener we do what Node would have done:
+ *
+ *   - throw: rethrow the reason (or Node's `UnhandledPromiseRejection`
+ *     wrapper for a non-error reason) on the next tick. The process crashes
+ *     with exit code 1 as before, and `uncaughtExceptionMonitor` records it
+ *     as a crash (fatal), exactly as it did without this listener. The one
+ *     visible difference: `uncaughtException` listeners and the monitor
+ *     receive origin `"uncaughtException"` instead of `"unhandledRejection"`.
+ *   - warn-with-error-code: print Node's warning and set `process.exitCode = 1`.
+ *   - strict: no listener at all — Node raises the rejection as an uncaught
+ *     exception first, which the crash monitor already records.
+ *
+ * Everything else — the app has its own listener (it decides what happens),
+ * or the mode never crashes — is recorded as an error (severity "error", not
+ * fatal) with `autter.unhandled_rejection: true`.
+ */
+type UnhandledRejectionsMode = "throw" | "strict" | "warn" | "warn-with-error-code" | "none";
+/**
+ * Node's effective `--unhandled-rejections` mode: `NODE_OPTIONS` first, then
+ * the command line (which wins), last occurrence wins. Default `"throw"`.
+ */
+declare function unhandledRejectionsMode(execArgv?: readonly string[], nodeOptions?: string | undefined): UnhandledRejectionsMode;
+
 /**
  * Logger-only mode: requests, operations, coded errors, sinks and enrichers
  * WITHOUT starting the OpenTelemetry NodeSDK. For apps that already run
@@ -629,8 +755,12 @@ interface AutterLoggingOptions {
     logging?: RuntimeLoggingOptions;
     /** Same semantics as initAutterServer. Default true. */
     redactAttributes?: boolean | RedactOptions;
-    /** Capture crashes via process.uncaughtExceptionMonitor. Default true. */
+    /** Capture crashes via process.uncaughtExceptionMonitor, and unhandled
+     * rejections (`captureUnhandledRejections`). Default true. */
     captureGlobalErrors?: boolean;
+    /** Same semantics as initAutterServer: record unhandled rejections as
+     * errors without changing whether the process crashes. Default true. */
+    captureUnhandledRejections?: boolean;
     /** Flush records on beforeExit/SIGINT/SIGTERM. Default true. */
     autoFlush?: boolean;
     debug?: boolean;
@@ -679,7 +809,9 @@ declare function enrichDeployment(env?: Record<string, string | undefined>): Run
  * Adding a feature: append an entry to compat-manifest.json with the first
  * ingester release that handles it, the migrations it writes to, its route
  * (if it has its own), and the first SDK release that emits it. The
- * consistency test in compat.test.ts checks ids, migrations and routes.
+ * consistency test in compat.test.ts checks ids, migrations and routes, and
+ * that no version is ahead of its package's package.json: a feature for the
+ * next release bumps the packages it names in the same change.
  */
 interface CompatFeature {
     id: string;
@@ -811,4 +943,13 @@ interface DoctorReport {
 }
 declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;
 
-export { type AutoFlushHandle, type AutoFlushOptions, type AutterErrorResponseOptions, type AutterLogging, type AutterLoggingOptions, type AutterRequestsOptions, type AutterServer, type AutterServerOptions, type AutterSeverity, COMPAT_MANIFEST, type CompatIssue, type DoctorOptions, type DoctorReport, FileSinkOptions, type FlushTarget, INGESTER_VERSION_HEADER, type IngesterCompatInfo, type InstrumentLlmOptions, type LlmCallHandle, type LlmCallInfo, type LlmUsage, RedactOptions, type RelayOptions, RuntimeCarrier, type RuntimeContextHandle, type RuntimeEnrichContext, type RuntimeEnrichEvent, type RuntimeEnricher, RuntimeLogContext, RuntimeLogLevel, type RuntimeLoggingOptions, type RuntimeOperation, RuntimeOperationKind, type RuntimeOperationOptions, RuntimeOutcome, type RuntimeRequestOptions, RuntimeSink, SDK_IDENTITY, type SafeCapture, type SdkIdentity, type TrackedLlmCall, autterErrorResponse, autterFastify, autterRequests, captureException, captureMessage, createBrowserRelayFetchHandler, createBrowserRelayHandler, createRuntimeLogger, emitLlmSelftestTrace, enrichDeployment, enrichEdgeGeo, enrichRequestSize, enrichUserAgent, evaluateCompat, fetchIngesterCompat, flushRuntimeLogs, initAutterLogging, initAutterServer, installAutterAutoFlush, instrumentLlmClient, makeSafeCapture, reportOutcome, runDoctor, runInBackground, runtimeContext, runtimeLogStats, runtimeLogger, sanitizeBrowserPayload, startCaughtExceptionSampler, trackLlmCall, withLlmCall, withProcessSpan, withRuntimeOperation, withRuntimeRequest };
+/**
+ * Record a step (type "custom" unless you say otherwise) on the current
+ * request. The next exception captured in it carries the last 30. Message
+ * and data are scrubbed with your `redact` settings. Never throws.
+ *
+ *   addBreadcrumb({ message: "Loaded cart", data: { items: 3 } });
+ */
+declare function addBreadcrumb(input: BreadcrumbInput): void;
+
+export { type AutoFlushHandle, type AutoFlushOptions, type AutterErrorHandlerOptions, type AutterErrorResponseOptions, type AutterLogging, type AutterLoggingOptions, type AutterRequestsOptions, type AutterServer, type AutterServerOptions, type AutterSeverity, BreadcrumbInput, COMPAT_MANIFEST, type CompatIssue, type DoctorOptions, type DoctorReport, FileSinkOptions, type FlushTarget, INGESTER_VERSION_HEADER, type IngesterCompatInfo, type InstrumentLlmOptions, type LlmCallHandle, type LlmCallInfo, type LlmUsage, RedactOptions, type RelayOptions, RuntimeCarrier, type RuntimeContextHandle, type RuntimeEnrichContext, type RuntimeEnrichEvent, type RuntimeEnricher, RuntimeLogContext, RuntimeLogLevel, type RuntimeLoggingOptions, type RuntimeOperation, RuntimeOperationKind, type RuntimeOperationOptions, RuntimeOutcome, type RuntimeRequestOptions, RuntimeSink, SDK_IDENTITY, type SafeCapture, type SdkIdentity, type TrackedLlmCall, type UnhandledRejectionsMode, addBreadcrumb, autterErrorHandler, autterErrorResponse, autterFastify, autterFastifyErrors, autterKoa, autterRequests, captureException, captureMessage, captureRequestError, createBrowserRelayFetchHandler, createBrowserRelayHandler, createRuntimeLogger, emitLlmSelftestTrace, enrichDeployment, enrichEdgeGeo, enrichRequestSize, enrichUserAgent, evaluateCompat, fetchIngesterCompat, flushRuntimeLogs, initAutterLogging, initAutterServer, installAutterAutoFlush, instrumentLlmClient, makeSafeCapture, reportOutcome, runDoctor, runInBackground, runtimeContext, runtimeLogStats, runtimeLogger, sanitizeBrowserPayload, startCaughtExceptionSampler, trackLlmCall, unhandledRejectionsMode, withLlmCall, withProcessSpan, withRuntimeOperation, withRuntimeRequest };