@autter/runtime-node 1.8.0 → 1.9.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, I as IgnoreErrorPattern, B as BreadcrumbInput } from './sinks-CIdlmYwy.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, J as redactText, K as toClientError } from './sinks-CIdlmYwy.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, I as IgnoreErrorPattern, i as CaptureLoggedErrorsOption, B as BreadcrumbInput } from './sinks-CLtQFPnn.cjs';
+export { j as Breadcrumb, k as BreadcrumbLevel, l as BreadcrumbType, n as CODE_PATTERN, o as ClientErrorBody, p as ConsoleSinkOptions, L as LoggedErrorSource, O as OtlpSinkOptions, q as RuntimeError, r as RuntimeErrorCatalog, s as RuntimeErrorDefinition, t as RuntimeErrorExtras, u as RuntimeErrorFactory, v as RuntimeErrorLike, w as RuntimeErrorOptions, R as RuntimeEvent, x as RuntimeLogContextValue, y as RuntimeSinkContext, z as consoleSink, A as defineRuntimeErrors, D as errorAttributes, E as fileSink, G as isRuntimeErrorLike, H as otlpSink, J as redactAttributes, K as redactText, N as toClientError } from './sinks-CLtQFPnn.cjs';
 import { Attributes } from '@opentelemetry/api';
 
 /**
@@ -23,6 +23,37 @@ interface RelayOptions {
      * `false` to disable (e.g. when a WAF already rate-limits).
      */
     perIpRateLimit?: number | false;
+    /**
+     * How the per-client rate limit finds the visitor's address. A caller can
+     * write anything into `X-Forwarded-For`, so the relay never takes its
+     * first (leftmost) entry unless told to.
+     *
+     * - `"auto"` (default): works behind any load balancer, CDN or platform
+     *   proxy without setup. Proxies append the address they saw to the right
+     *   of the header (or overwrite it), so the relay reads it right to left
+     *   and takes the first public address, skipping private and loopback
+     *   hops. The Node handler only does this when the connection itself came
+     *   from a private address (a proxy on your network); a public peer is the
+     *   visitor and its header is ignored. On Cloudflare Workers it uses
+     *   `CF-Connecting-IP`.
+     * - a number `n`: exactly `n` proxies you control sit in front; use the
+     *   entry `n` from the right (Express `trust proxy` semantics). Use `1`
+     *   for a Node origin behind Cloudflare with no load balancer.
+     * - `true`: every proxy in front is yours and strips client values; use
+     *   the leftmost entry.
+     * - `false`: never read the header. The Node handler keys the socket peer;
+     *   the fetch handler keys one shared bucket for the route.
+     *
+     * Strings from environment variables are read too (`"auto"`, `"true"`,
+     * `"false"`, `"0"`, `"2"`); anything else falls back to `"auto"`.
+     */
+    trustProxy?: boolean | "auto" | number | string;
+    /**
+     * Return the visitor's address yourself (Deno's `info.remoteAddr`, Bun's
+     * `server.requestIP`, a header your edge sets). Wins over `trustProxy`
+     * when it returns a non-empty string.
+     */
+    clientIp?: (request: Request | IncomingMessage) => string | null | undefined;
     /** Called when the async forward fails (default: console.warn). */
     onError?: (err: unknown) => void;
     /**
@@ -167,6 +198,19 @@ declare const runtimeContext: {
     warn(message: string, attributes?: RuntimeLogContext): void;
     /** Log an error and attach it (code/why/fix) to the current summary. */
     error(error: unknown, attributes?: RuntimeLogContext): void;
+    /**
+     * The app caught `error` and chose to continue on a fallback (RF-02):
+     *
+     *   } catch (err) {
+     *     runtimeContext.degraded(err, "pricing service down, using cached prices");
+     *   }
+     *
+     * Recorded as an occurrence at `warning` severity, marked
+     * `autter.handling = "deliberate"` with the reason (grouped by its code
+     * when the error has one), never an incident. The current request or
+     * operation ends "degraded" unless it failed or set its outcome.
+     */
+    degraded(error: unknown, reason: string, attributes?: RuntimeLogContext): void;
     /** Current operation id. */
     readonly id: string | undefined;
     /** Current request id (inherited by child operations and forks). */
@@ -268,6 +312,20 @@ interface AutterServerOptions {
      * Default true; false turns both off.
      */
     captureGlobalErrors?: boolean;
+    /**
+     * Errors the app caught and logged count (RF-01): an `Error` passed to
+     * `console.error`, pino, winston, bunyan or `runtimeLogger.error` becomes
+     * an occurrence at `error` severity, marked `autter.handled` /
+     * `autter.handling: "caught"`, with the log line as context
+     * (`autter.log.source`, `autter.log.message`). Log lines without an error
+     * object are untouched; an error also passed to `captureException` in
+     * the same tick is reported once; a burst limit per error type and throw
+     * site keeps ten at once, then one every ten seconds (the count left out
+     * is reported). It never fails a request on its own. `false` turns it
+     * off; an object turns single loggers off, e.g. `{ console: false }`.
+     * Default true.
+     */
+    captureLoggedErrors?: CaptureLoggedErrorsOption;
     /**
      * Record unhandled promise rejections as errors (severity "error",
      * `autter.unhandled_rejection: true`). Never changes whether the process
@@ -617,6 +675,18 @@ interface RuntimeRequestOptions {
     ignore?: string[];
     /** Receives the log flush promise after the response (serverless `waitUntil`). */
     waitUntil?: (promise: Promise<unknown>) => void;
+    /**
+     * Report thrown errors (default true): `false`, or a predicate per error.
+     * An error it turns down is rethrown untouched and does not fail the
+     * summary (Next.js `redirect()` / `notFound()` signals).
+     */
+    capture?: boolean | ((error: unknown) => boolean);
+    /**
+     * Answer a thrown error with `toClientError` JSON and the error's own
+     * 4xx/5xx status (else 500) instead of rethrowing it, so a thrown 4xx is
+     * recorded with its stack and still answered as a 4xx. Default false.
+     */
+    errorResponse?: boolean | ((error: unknown) => boolean);
 }
 /**
  * Report an error that reached a request boundary — a framework error hook,
@@ -806,6 +876,8 @@ interface AutterLoggingOptions {
     sampleRate?: number;
     /** Same semantics as initAutterServer: errors never reported (type or message). */
     ignoreErrors?: IgnoreErrorPattern[];
+    /** Same semantics as initAutterServer: errors logged through console.error, pino, winston, bunyan or runtimeLogger.error are occurrences. Default true. */
+    captureLoggedErrors?: CaptureLoggedErrorsOption;
 }
 interface AutterLogging {
     captureException(error: unknown, attributes?: Attributes): void;
@@ -988,4 +1060,4 @@ declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;
  */
 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 };
+export { type AutoFlushHandle, type AutoFlushOptions, type AutterErrorHandlerOptions, type AutterErrorResponseOptions, type AutterLogging, type AutterLoggingOptions, type AutterRequestsOptions, type AutterServer, type AutterServerOptions, type AutterSeverity, BreadcrumbInput, COMPAT_MANIFEST, CaptureLoggedErrorsOption, 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, I as IgnoreErrorPattern, B as BreadcrumbInput } from './sinks-CIdlmYwy.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, J as redactText, K as toClientError } from './sinks-CIdlmYwy.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, I as IgnoreErrorPattern, i as CaptureLoggedErrorsOption, B as BreadcrumbInput } from './sinks-CLtQFPnn.js';
+export { j as Breadcrumb, k as BreadcrumbLevel, l as BreadcrumbType, n as CODE_PATTERN, o as ClientErrorBody, p as ConsoleSinkOptions, L as LoggedErrorSource, O as OtlpSinkOptions, q as RuntimeError, r as RuntimeErrorCatalog, s as RuntimeErrorDefinition, t as RuntimeErrorExtras, u as RuntimeErrorFactory, v as RuntimeErrorLike, w as RuntimeErrorOptions, R as RuntimeEvent, x as RuntimeLogContextValue, y as RuntimeSinkContext, z as consoleSink, A as defineRuntimeErrors, D as errorAttributes, E as fileSink, G as isRuntimeErrorLike, H as otlpSink, J as redactAttributes, K as redactText, N as toClientError } from './sinks-CLtQFPnn.js';
 import { Attributes } from '@opentelemetry/api';
 
 /**
@@ -23,6 +23,37 @@ interface RelayOptions {
      * `false` to disable (e.g. when a WAF already rate-limits).
      */
     perIpRateLimit?: number | false;
+    /**
+     * How the per-client rate limit finds the visitor's address. A caller can
+     * write anything into `X-Forwarded-For`, so the relay never takes its
+     * first (leftmost) entry unless told to.
+     *
+     * - `"auto"` (default): works behind any load balancer, CDN or platform
+     *   proxy without setup. Proxies append the address they saw to the right
+     *   of the header (or overwrite it), so the relay reads it right to left
+     *   and takes the first public address, skipping private and loopback
+     *   hops. The Node handler only does this when the connection itself came
+     *   from a private address (a proxy on your network); a public peer is the
+     *   visitor and its header is ignored. On Cloudflare Workers it uses
+     *   `CF-Connecting-IP`.
+     * - a number `n`: exactly `n` proxies you control sit in front; use the
+     *   entry `n` from the right (Express `trust proxy` semantics). Use `1`
+     *   for a Node origin behind Cloudflare with no load balancer.
+     * - `true`: every proxy in front is yours and strips client values; use
+     *   the leftmost entry.
+     * - `false`: never read the header. The Node handler keys the socket peer;
+     *   the fetch handler keys one shared bucket for the route.
+     *
+     * Strings from environment variables are read too (`"auto"`, `"true"`,
+     * `"false"`, `"0"`, `"2"`); anything else falls back to `"auto"`.
+     */
+    trustProxy?: boolean | "auto" | number | string;
+    /**
+     * Return the visitor's address yourself (Deno's `info.remoteAddr`, Bun's
+     * `server.requestIP`, a header your edge sets). Wins over `trustProxy`
+     * when it returns a non-empty string.
+     */
+    clientIp?: (request: Request | IncomingMessage) => string | null | undefined;
     /** Called when the async forward fails (default: console.warn). */
     onError?: (err: unknown) => void;
     /**
@@ -167,6 +198,19 @@ declare const runtimeContext: {
     warn(message: string, attributes?: RuntimeLogContext): void;
     /** Log an error and attach it (code/why/fix) to the current summary. */
     error(error: unknown, attributes?: RuntimeLogContext): void;
+    /**
+     * The app caught `error` and chose to continue on a fallback (RF-02):
+     *
+     *   } catch (err) {
+     *     runtimeContext.degraded(err, "pricing service down, using cached prices");
+     *   }
+     *
+     * Recorded as an occurrence at `warning` severity, marked
+     * `autter.handling = "deliberate"` with the reason (grouped by its code
+     * when the error has one), never an incident. The current request or
+     * operation ends "degraded" unless it failed or set its outcome.
+     */
+    degraded(error: unknown, reason: string, attributes?: RuntimeLogContext): void;
     /** Current operation id. */
     readonly id: string | undefined;
     /** Current request id (inherited by child operations and forks). */
@@ -268,6 +312,20 @@ interface AutterServerOptions {
      * Default true; false turns both off.
      */
     captureGlobalErrors?: boolean;
+    /**
+     * Errors the app caught and logged count (RF-01): an `Error` passed to
+     * `console.error`, pino, winston, bunyan or `runtimeLogger.error` becomes
+     * an occurrence at `error` severity, marked `autter.handled` /
+     * `autter.handling: "caught"`, with the log line as context
+     * (`autter.log.source`, `autter.log.message`). Log lines without an error
+     * object are untouched; an error also passed to `captureException` in
+     * the same tick is reported once; a burst limit per error type and throw
+     * site keeps ten at once, then one every ten seconds (the count left out
+     * is reported). It never fails a request on its own. `false` turns it
+     * off; an object turns single loggers off, e.g. `{ console: false }`.
+     * Default true.
+     */
+    captureLoggedErrors?: CaptureLoggedErrorsOption;
     /**
      * Record unhandled promise rejections as errors (severity "error",
      * `autter.unhandled_rejection: true`). Never changes whether the process
@@ -617,6 +675,18 @@ interface RuntimeRequestOptions {
     ignore?: string[];
     /** Receives the log flush promise after the response (serverless `waitUntil`). */
     waitUntil?: (promise: Promise<unknown>) => void;
+    /**
+     * Report thrown errors (default true): `false`, or a predicate per error.
+     * An error it turns down is rethrown untouched and does not fail the
+     * summary (Next.js `redirect()` / `notFound()` signals).
+     */
+    capture?: boolean | ((error: unknown) => boolean);
+    /**
+     * Answer a thrown error with `toClientError` JSON and the error's own
+     * 4xx/5xx status (else 500) instead of rethrowing it, so a thrown 4xx is
+     * recorded with its stack and still answered as a 4xx. Default false.
+     */
+    errorResponse?: boolean | ((error: unknown) => boolean);
 }
 /**
  * Report an error that reached a request boundary — a framework error hook,
@@ -806,6 +876,8 @@ interface AutterLoggingOptions {
     sampleRate?: number;
     /** Same semantics as initAutterServer: errors never reported (type or message). */
     ignoreErrors?: IgnoreErrorPattern[];
+    /** Same semantics as initAutterServer: errors logged through console.error, pino, winston, bunyan or runtimeLogger.error are occurrences. Default true. */
+    captureLoggedErrors?: CaptureLoggedErrorsOption;
 }
 interface AutterLogging {
     captureException(error: unknown, attributes?: Attributes): void;
@@ -988,4 +1060,4 @@ declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;
  */
 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 };
+export { type AutoFlushHandle, type AutoFlushOptions, type AutterErrorHandlerOptions, type AutterErrorResponseOptions, type AutterLogging, type AutterLoggingOptions, type AutterRequestsOptions, type AutterServer, type AutterServerOptions, type AutterSeverity, BreadcrumbInput, COMPAT_MANIFEST, CaptureLoggedErrorsOption, 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.js

@@ -21,10 +21,12 @@ import {
   fingerprintEventAttributes,
   fingerprintValues,
   flushRuntimeLogs,
+  isCaptured,
   isError,
   isRuntimeErrorLike,
   local,
   makeRedactor,
+  markCaptured,
   normalizeRoutePath,
   noteOperationError,
   notifyException,
@@ -42,14 +44,17 @@ import {
   runtimeLogStats,
   runtimeLogger,
   sanitizeBreadcrumbs,
+  setHandledCapture,
   shutdownRuntimeLogger,
   splitFingerprint,
+  startLoggedErrorCapture,
+  stopLoggedErrorCapture,
   toClientError,
   withRuntimeOperation
-} from "./chunk-QKY2OQSO.js";
+} from "./chunk-HHKQ3UCH.js";
 import {
   runDoctor
-} from "./chunk-UC3QH4PC.js";
+} from "./chunk-JSGGUWRD.js";
 import {
   COMPAT_MANIFEST,
   CountingExporter,
@@ -71,7 +76,7 @@ import {
   sharedSlot,
   telemetryStats,
   unregisterFlushTargets
-} from "./chunk-B5ZMOCEM.js";
+} from "./chunk-ZKM76SDP.js";
 
 // src/relay.ts
 var IpWindow = class {
@@ -96,6 +101,112 @@ function firstForwardedFor(value) {
   const raw = Array.isArray(value) ? value[0] : value;
   return raw ? (raw.split(",")[0] ?? "").trim() : "";
 }
+var TRUST_AUTO = { mode: "auto" };
+var warnedTrustProxy = false;
+function resolveTrustProxy(value) {
+  if (value === void 0 || value === null || value === "auto") return TRUST_AUTO;
+  if (value === true) return { mode: "all" };
+  if (value === false || value === 0) return { mode: "never" };
+  if (typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 100) {
+    return { mode: "hops", hops: value };
+  }
+  if (typeof value === "string") {
+    const v = value.trim().toLowerCase();
+    if (v === "" || v === "auto") return TRUST_AUTO;
+    if (v === "false" || v === "0" || v === "no" || v === "off") return { mode: "never" };
+    if (v === "true" || v === "yes" || v === "on") return { mode: "all" };
+    if (/^[1-9][0-9]?$/.test(v)) return { mode: "hops", hops: Number(v) };
+  }
+  if (!warnedTrustProxy) {
+    warnedTrustProxy = true;
+    console.warn(
+      `[autter-runtime] relay: trustProxy ${JSON.stringify(value)} is not recognised; using "auto".`
+    );
+  }
+  return TRUST_AUTO;
+}
+var IPV4_RE = /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
+function normalizeAddress(entry) {
+  if (!entry) return null;
+  let a = entry.trim();
+  if (!a || a.length > 64) return null;
+  const bracketed = /^\[([0-9A-Fa-f:.]+)\](?::\d{1,5})?$/.exec(a);
+  if (bracketed) a = bracketed[1] ?? "";
+  else if (/^[\d.]+:\d{1,5}$/.test(a)) a = a.slice(0, a.lastIndexOf(":"));
+  a = a.toLowerCase();
+  if (a.startsWith("::ffff:") && IPV4_RE.test(a.slice(7))) a = a.slice(7);
+  if (IPV4_RE.test(a)) return a;
+  if (/^[0-9a-f:]+(:(\d{1,3}\.){3}\d{1,3})?$/.test(a) && a.includes(":") && a.split(":").length <= 9) {
+    return a;
+  }
+  return null;
+}
+function isPrivateAddress(a) {
+  if (IPV4_RE.test(a)) {
+    const [x, y] = a.split(".").map(Number);
+    return x === 10 || x === 127 || x === 0 || x === 169 && y === 254 || x === 172 && y >= 16 && y <= 31 || x === 192 && y === 168 || x === 100 && y >= 64 && y <= 127;
+  }
+  return a === "::1" || a === "::" || /^f[cd]/.test(a) || /^fe[89ab]/.test(a);
+}
+function forwardedEntries(value) {
+  const raw = Array.isArray(value) ? value.join(",") : value;
+  if (!raw) return [];
+  const out = [];
+  for (const part of raw.split(",")) {
+    const a = normalizeAddress(part);
+    if (a) out.push(a);
+  }
+  return out;
+}
+function rightmostPublic(entries) {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const a = entries[i];
+    if (a && !isPrivateAddress(a)) return a;
+  }
+  return null;
+}
+function fromCustom(opts, request) {
+  if (!opts.clientIp) return null;
+  try {
+    const v = opts.clientIp(request);
+    return typeof v === "string" && v.trim() ? v.trim().slice(0, 64) : null;
+  } catch {
+    return null;
+  }
+}
+function fetchClientKey(request, opts) {
+  const custom = fromCustom(opts, request);
+  if (custom) return custom;
+  const trust = resolveTrustProxy(opts.trustProxy);
+  if (trust.mode === "never") return "shared";
+  const header = request.headers.get("x-forwarded-for");
+  if (trust.mode === "all") return firstForwardedFor(header) || "shared";
+  const entries = forwardedEntries(header);
+  if (trust.mode === "hops") {
+    return entries[Math.max(0, entries.length - trust.hops)] ?? "shared";
+  }
+  const cf = request.cf;
+  if (cf !== null && typeof cf === "object") {
+    const viaCf = normalizeAddress(request.headers.get("cf-connecting-ip"));
+    if (viaCf) return viaCf;
+  }
+  return rightmostPublic(entries) ?? entries[entries.length - 1] ?? "shared";
+}
+function nodeClientKey(req, opts) {
+  const custom = fromCustom(opts, req);
+  if (custom) return custom;
+  const trust = resolveTrustProxy(opts.trustProxy);
+  const peer = normalizeAddress(req.socket?.remoteAddress);
+  if (trust.mode === "never") return peer ?? "unknown";
+  const header = req.headers["x-forwarded-for"];
+  if (trust.mode === "all") return firstForwardedFor(header) || peer || "unknown";
+  const entries = forwardedEntries(header);
+  if (trust.mode === "hops") {
+    return entries[Math.max(0, entries.length - trust.hops)] ?? peer ?? "unknown";
+  }
+  if (peer && !isPrivateAddress(peer)) return peer;
+  return rightmostPublic(entries) ?? peer ?? entries[entries.length - 1] ?? "unknown";
+}
 var DEFAULT_ENDPOINT = "https://otlp.autter.dev";
 var DEFAULT_MAX_BODY = 64 * 1024;
 var MAX_EVENTS = 50;
@@ -329,7 +440,7 @@ function createBrowserRelayFetchHandler(opts) {
       return new Response(null, { status: 405 });
     }
     if (limiter) {
-      const ip = firstForwardedFor(request.headers.get("x-forwarded-for")) || "unknown";
+      const ip = fetchClientKey(request, opts);
       if (!limiter.allow(ip)) {
         return new Response(JSON.stringify({ error: "rate limit exceeded" }), {
           status: 429
@@ -395,7 +506,7 @@ function createBrowserRelayHandler(opts) {
       return;
     }
     if (limiter) {
-      const ip = firstForwardedFor(req.headers["x-forwarded-for"]) || req.socket?.remoteAddress || "unknown";
+      const ip = nodeClientKey(req, opts);
       if (!limiter.allow(ip)) {
         respond(res, 429, { error: "rate limit exceeded" });
         return;
@@ -746,7 +857,6 @@ import { context, trace } from "@opentelemetry/api";
 import { getRPCMetadata, RPCType } from "@opentelemetry/core";
 var REQUEST_STATE = /* @__PURE__ */ Symbol.for("autter.runtime.request");
 var BOUND = /* @__PURE__ */ Symbol.for("autter.runtime.bound");
-var CAPTURED = sharedSlot("requests", () => ({ captured: /* @__PURE__ */ new WeakSet() })).captured;
 var capturer = () => {
 };
 function setRequestExceptionCapturer(fn) {
@@ -757,8 +867,14 @@ var annotator = () => {
 function setRequestSpanAnnotator(fn) {
   annotator = fn;
 }
-function markCaptured(error) {
-  if (error && typeof error === "object") CAPTURED.add(error);
+function decide(rule, error, fallback) {
+  if (rule === void 0) return fallback;
+  if (typeof rule !== "function") return rule;
+  try {
+    return rule(error) === true;
+  } catch {
+    return false;
+  }
 }
 function expressRouteOf(req) {
   const props = req;
@@ -789,7 +905,7 @@ function captureAtBoundary(error, state, rule = void 0, attributes) {
     wanted = false;
   }
   if (!wanted) return;
-  if (error && typeof error === "object" && CAPTURED.has(error)) return;
+  if (isCaptured(error)) return;
   markCaptured(error);
   try {
     const run = () => onRequestSpan(() => capturer(error, attributes));
@@ -803,7 +919,7 @@ function requestStateOf(req) {
   return req[REQUEST_STATE];
 }
 function captureRequestError(error, attributes) {
-  if (error && typeof error === "object" && CAPTURED.has(error)) {
+  if (isCaptured(error)) {
     if (!attributes) return;
     try {
       onRequestSpan(() => annotator(attributes));
@@ -895,7 +1011,8 @@ function finishRequest(state, input) {
     ...state.error !== void 0 ? { error: state.error } : {},
     ...state.errorThrown ? { thrown: true } : {},
     status: input.status,
-    aborted: input.aborted
+    aborted: input.aborted,
+    ...state.degraded ? { degraded: true } : {}
   });
   const span = trace.getActiveSpan();
   if (span?.isRecording()) span.setAttribute("autter.operation.outcome", state.outcome);
@@ -1120,9 +1237,15 @@ function withRuntimeRequest(handler, options = {}) {
         try {
           return await handler(request, ...rest);
         } catch (error) {
-          noteOperationError(error, true, state);
-          captureAtBoundary(error, state, true);
-          throw error;
+          if (decide(options.capture, error, true)) {
+            noteOperationError(error, true, state);
+            captureAtBoundary(error, state, true);
+          }
+          if (!decide(options.errorResponse, error, false)) throw error;
+          return new Response(JSON.stringify(toClientError(error, requestId)), {
+            status: responseStatusOf(error),
+            headers: { "content-type": "application/json; charset=utf-8" }
+          });
         }
       });
       status = response.status;
@@ -1320,6 +1443,8 @@ var S = sharedSlot("server", () => ({
   alwaysOnProvider: null,
   redactor: makeRedactor(true),
   loggerOnlyCapture: null,
+  handled: null,
+  loggerOnlyHandled: null,
   hookRequests: false
 }));
 var LLM_MARKER_ATTRIBUTES = [
@@ -1896,6 +2021,37 @@ function initAutterServer(options) {
     span.setStatus({ code: SpanStatusCode.ERROR, message: safeMessage });
     if (!reuseActive) span.end();
   }
+  function captureHandled(error, attributes, severity) {
+    const isErr = isError(error);
+    if (!errorFilter({
+      type: isErr ? String(error.name ?? "") : "Error",
+      message: isErr ? String(error.message ?? "") : String(error),
+      severity
+    })) return;
+    if (severity === "error") errorTraceBuffer?.retainActiveTrace();
+    telemetryStats.markCaptured();
+    const message = redactor.text(isErr ? error.message : String(error));
+    const stack = isErr && error.stack ? error.stack : new Error().stack?.split("\n").filter((line, i) => i === 0 || !/captureHandled|report(?:Degraded|LoggedError)/.test(line)).join("\n");
+    const split = splitFingerprint(attributes);
+    const fingerprint = fingerprintEventAttributes(split.fingerprint, redactor.text);
+    const redacted = redactor(split.attributes);
+    const activeSpan = trace2.getActiveSpan();
+    const reuseActive = activeSpan?.isRecording() === true;
+    const span = reuseActive ? activeSpan : errorTracer.startSpan(isErr ? error.name : "Error");
+    markCaptured(error);
+    notifyException(error, { ...redacted, ...fingerprint, "autter.severity": severity });
+    span.addEvent("exception", {
+      ...redacted,
+      "exception.type": isErr ? error.name : "Error",
+      "exception.message": message,
+      ...stack ? { "exception.stacktrace": redactor.text(stack) } : {},
+      "autter.severity": severity,
+      ...errorAttributes(error),
+      ...fingerprint,
+      ...breadcrumbEventAttributes(redactor.text, error)
+    });
+    if (!reuseActive) span.end();
+  }
   configureRuntimeLogger({
     endpoint,
     apiKey: options.apiKey,
@@ -1909,6 +2065,8 @@ function initAutterServer(options) {
     reportOutcome: reportOutcome2
   });
   S.hookRequests = options.logging?.requests === true;
+  S.handled = captureHandled;
+  startLoggedErrorCapture(options.captureLoggedErrors);
   let onCrash = null;
   let uninstallRejections = null;
   if (options.captureGlobalErrors !== false) {
@@ -1955,6 +2113,7 @@ function initAutterServer(options) {
     withLlmCall: (info, fn) => runLlmSpan(llmTracer, info, fn),
     trackLlmCall: (call) => recordLlmCall(llmTracer, call),
     shutdown: async () => {
+      if (S.active === server) stopLoggedErrorCapture();
       const logShutdown = await Promise.allSettled([shutdownRuntimeLogger()]);
       if (onCrash) process.off("uncaughtExceptionMonitor", onCrash);
       uninstallRejections?.();
@@ -1962,6 +2121,7 @@ function initAutterServer(options) {
       if (S.active === server) {
         S.active = null;
         S.alwaysOnProvider = null;
+        S.handled = null;
         S.hookRequests = false;
         S.redactor = makeRedactor(true);
       }
@@ -1997,13 +2157,39 @@ function captureException(error, attributes) {
   recordError(span, error);
   span.end();
 }
-function setLoggerOnlyCapture(fn) {
+function setLoggerOnlyCapture(fn, handled = null) {
   S.loggerOnlyCapture = fn;
+  S.loggerOnlyHandled = handled;
+}
+function captureHandledError(error, attributes, severity) {
+  if (S.active) {
+    S.handled?.(error, attributes, severity);
+    return;
+  }
+  if (S.loggerOnlyHandled) {
+    S.loggerOnlyHandled(error, attributes, severity);
+    return;
+  }
+  markCaptured(error);
+  const split = splitFingerprint(attributes);
+  notifyException(error, { ...split.attributes, "autter.severity": severity });
+  const span = trace2.getTracer("autter-errors").startSpan(isError(error) ? error.name : "Error");
+  span.addEvent("exception", {
+    ...S.redactor(split.attributes),
+    "exception.type": isError(error) ? error.name : "Error",
+    "exception.message": S.redactor.text(isError(error) ? error.message : String(error)),
+    ...isError(error) && error.stack ? { "exception.stacktrace": S.redactor.text(error.stack) } : {},
+    "autter.severity": severity,
+    ...errorAttributes(error),
+    ...fingerprintEventAttributes(split.fingerprint, S.redactor.text)
+  });
+  span.end();
 }
 function serverActive() {
   return S.active !== null;
 }
 setRequestExceptionCapturer((error, attributes) => captureException(error, attributes));
+setHandledCapture(captureHandledError);
 setRequestSpanAnnotator((attributes) => {
   const span = trace2.getActiveSpan();
   if (span?.isRecording()) span.setAttributes(S.redactor(splitFingerprint(attributes).attributes));
@@ -2474,6 +2660,33 @@ function initAutterLogging(options) {
     notifyException(error, { ...redacted, ...fingerprint });
     captureExceptionAsLog(error, { ...redacted, ...fingerprint });
   }
+  function captureHandled(error, attributes, severity) {
+    markCaptured(error);
+    const isErrValue = isError(error);
+    if (!errorFilter({
+      type: isErrValue ? String(error.name ?? "") : "Error",
+      message: isErrValue ? String(error.message ?? "") : String(error),
+      severity
+    })) return;
+    const split = splitFingerprint(attributes);
+    const fingerprint = fingerprintEventAttributes(split.fingerprint, redact.text);
+    const redacted = redact(split.attributes);
+    notifyException(error, { ...redacted, ...fingerprint, "autter.severity": severity });
+    const span = trace3.getActiveSpan();
+    if (mode === "auto" && span?.isRecording()) {
+      span.addEvent("exception", {
+        ...redacted,
+        "exception.type": isErrValue ? error.name : "Error",
+        "exception.message": redact.text(isErrValue ? error.message : String(error)),
+        ...isErrValue && error.stack ? { "exception.stacktrace": redact.text(error.stack) } : {},
+        "autter.severity": severity,
+        ...errorAttributes(error),
+        ...fingerprint
+      });
+      return;
+    }
+    captureExceptionAsLog(error, { ...redacted, ...fingerprint }, severity);
+  }
   const captured = /* @__PURE__ */ new WeakSet();
   configureRuntimeLogger({
     endpoint,
@@ -2498,7 +2711,8 @@ function initAutterLogging(options) {
       captureException2(error);
     }
   });
-  setLoggerOnlyCapture(captureException2);
+  setLoggerOnlyCapture(captureException2, captureHandled);
+  startLoggedErrorCapture(options.captureLoggedErrors);
   const onCrash = (error) => {
     if (recordedAsRejection(error)) return;
     captureException2(error, { "autter.unhandled": true });
@@ -2517,6 +2731,7 @@ function initAutterLogging(options) {
     captureException: captureException2,
     flush: flushRuntimeLogs,
     shutdown: async () => {
+      if (L.active === handle) stopLoggedErrorCapture();
       process.off("uncaughtExceptionMonitor", onCrash);
       uninstallRejections?.();
       uninstallRejections = null;