@autter/runtime-next 1.8.0 → 1.9.0

package/README.md

@@ -230,6 +230,44 @@ export const POST = withRuntimeRequest(async (request) => {
 }, { name: "checkout" });
 ```
 
+`withAutter(handler)` is `withRuntimeRequest` that also **answers** a thrown
+error: it records it with its stack and replies with the error's own status,
+so a thrown 4xx stays a 4xx (not an anonymous 500), while Next's `redirect()`
+and `notFound()` pass through untouched and are never reported.
+
+```ts
+// app/api/orders/[id]/route.ts
+import { withAutter, RuntimeError } from "@autter/runtime-next";
+
+export const GET = withAutter(async (request, { params }) => {
+  const order = await findOrder(params.id);
+  if (!order) throw new RuntimeError({ status: 404, code: "orders.not_found", message: "No such order" });
+  return Response.json(order);   // a thrown 404 is recorded and answered as 404
+});
+```
+
+Next.js error pages report through Autter too (RF-04). In a client
+`app/error.tsx`, call `useAutterErrorReport(error)`; for
+`app/global-error.tsx`, export the ready `AutterGlobalError`, or call
+`reportNextError(error, { boundary: "global-error" })`. Each reports once per
+error, with the boundary and Next's `digest`, through the browser tracker
+(`@autter/runtime-next/client`):
+
+```tsx
+"use client";
+import { useAutterErrorReport } from "@autter/runtime-next/client";
+export default function Error({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
+  useAutterErrorReport(error);
+  return <button onClick={reset}>Try again</button>;
+}
+```
+
+Caught errors count on the server (`console.error`, pino/winston/bunyan,
+`runtimeLogger.error`) and in the browser (`console.error`) by default, and
+`runtimeContext.degraded(err, reason)` marks a deliberate fallback — see the
+[runtime-node](../runtime-node) and [runtime-browser](../runtime-browser)
+READMEs.
+
 Everything new in `@autter/runtime-node` 1.5.0 (`runtimeContext`,
 `RuntimeError`, `defineRuntimeErrors`, `runInBackground`, `initAutterLogging`,
 enrichers, sinks, …) is re-exported from `@autter/runtime-next` and

package/dist/{chunk-FU5HRQKM.js → chunk-6MFPMECS.js}

@@ -2,13 +2,14 @@
 import {
   createBrowserRelayFetchHandler,
   initAutterServer,
+  runtimeContext,
   withRuntimeRequest as nodeWithRuntimeRequest
 } from "@autter/runtime-node";
 
 // package.json
 var package_default = {
   name: "@autter/runtime-next",
-  version: "1.8.0",
+  version: "1.9.0",
   description: "One-command Autter Runtime for Next.js: server OTel, request wide events, coded errors, browser tracker, relay route, edge middleware and React error boundary",
   license: "MIT",
   type: "module",
@@ -63,9 +64,9 @@ var package_default = {
     test: "npm run build -w @autter/runtime-core && npm run build -w @autter/runtime-node && npm run build -w @autter/runtime-edge && npm run build -w @autter/runtime-browser && npm run build && node --test test/*.test.mjs"
   },
   dependencies: {
-    "@autter/runtime-browser": "^1.7.0",
-    "@autter/runtime-edge": "^1.2.0",
-    "@autter/runtime-node": "^1.8.0"
+    "@autter/runtime-browser": "^1.8.0",
+    "@autter/runtime-edge": "^1.4.0",
+    "@autter/runtime-node": "^1.9.0"
   },
   peerDependencies: {
     react: ">=18"
@@ -94,6 +95,20 @@ var package_default = {
   ]
 };
 
+// src/control-flow.ts
+var CONTROL_FLOW_DIGEST = /^(?:NEXT_REDIRECT|NEXT_NOT_FOUND|NEXT_HTTP_ERROR_FALLBACK|DYNAMIC_SERVER_USAGE|BAILOUT_TO_CLIENT_SIDE_RENDERING)\b/;
+function digestOf(error) {
+  try {
+    const digest = error?.digest;
+    return typeof digest === "string" ? digest : "";
+  } catch {
+    return "";
+  }
+}
+function isNextControlFlow(error) {
+  return CONTROL_FLOW_DIGEST.test(digestOf(error));
+}
+
 // src/server.ts
 import {
   createRuntimeLogger,
@@ -112,7 +127,7 @@ import {
   makeSafeCapture,
   installAutterAutoFlush,
   redactAttributes,
-  runtimeContext,
+  runtimeContext as runtimeContext2,
   runInBackground,
   autterRequests,
   autterFastify,
@@ -178,11 +193,30 @@ function withRuntimeRequest(handler, options = {}) {
     waitUntil: options.waitUntil ?? scheduleAfter
   });
 }
+function withAutter(handler, options = {}) {
+  const rule = options.capture;
+  return withRuntimeRequest(
+    async (request, ...rest) => {
+      try {
+        return await handler(request, ...rest);
+      } catch (error) {
+        if (isNextControlFlow(error)) runtimeContext.outcome("succeeded");
+        throw error;
+      }
+    },
+    {
+      ...options,
+      capture: (error) => !isNextControlFlow(error) && (typeof rule === "function" ? rule(error) === true : rule !== false),
+      errorResponse: (error) => !isNextControlFlow(error)
+    }
+  );
+}
 
 export {
   registerAutter,
   createAutterRelayRoute,
   withRuntimeRequest,
+  withAutter,
   createRuntimeLogger,
   runtimeLogger,
   withRuntimeOperation,
@@ -199,7 +233,7 @@ export {
   makeSafeCapture,
   installAutterAutoFlush,
   redactAttributes,
-  runtimeContext,
+  runtimeContext2 as runtimeContext,
   runInBackground,
   autterRequests,
   autterFastify,

package/dist/{chunk-CL2ENM4A.js → chunk-Q2TA3ACY.js}

@@ -1,5 +1,7 @@
 // src/request-error.ts
 import { captureEdgeException } from "@autter/runtime-edge";
+
+// src/control-flow.ts
 var CONTROL_FLOW_DIGEST = /^(?:NEXT_REDIRECT|NEXT_NOT_FOUND|NEXT_HTTP_ERROR_FALLBACK|DYNAMIC_SERVER_USAGE|BAILOUT_TO_CLIENT_SIDE_RENDERING)\b/;
 function digestOf(error) {
   try {
@@ -9,6 +11,11 @@ function digestOf(error) {
     return "";
   }
 }
+function isNextControlFlow(error) {
+  return CONTROL_FLOW_DIGEST.test(digestOf(error));
+}
+
+// src/request-error.ts
 function shouldReport(error, rule) {
   if (rule === true) return true;
   if (rule === false) return false;
@@ -19,7 +26,7 @@ function shouldReport(error, rule) {
       return false;
     }
   }
-  return !CONTROL_FLOW_DIGEST.test(digestOf(error));
+  return !isNextControlFlow(error);
 }
 function requestErrorAttributes(error, request, context) {
   const out = {};

package/dist/client.cjs

@@ -34,25 +34,28 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 var client_exports = {};
 __export(client_exports, {
   AutterErrorBoundary: () => AutterErrorBoundary,
+  AutterGlobalError: () => AutterGlobalError,
   addBreadcrumb: () => import_breadcrumbs.addBreadcrumb,
-  autterErrorFromResponse: () => import_runtime_browser2.autterErrorFromResponse,
-  captureException: () => import_runtime_browser2.captureException,
-  captureMessage: () => import_runtime_browser2.captureMessage,
-  captureOutcome: () => import_runtime_browser2.captureOutcome,
+  autterErrorFromResponse: () => import_runtime_browser3.autterErrorFromResponse,
+  captureException: () => import_runtime_browser3.captureException,
+  captureMessage: () => import_runtime_browser3.captureMessage,
+  captureOutcome: () => import_runtime_browser3.captureOutcome,
   clearBreadcrumbs: () => import_breadcrumbs.clearBreadcrumbs,
   createFilter: () => import_filters.createFilter,
   disableTracePropagation: () => import_tracing.disableTracePropagation,
   enableBreadcrumbs: () => import_breadcrumbs.enableBreadcrumbs,
   enableTracePropagation: () => import_tracing.enableTracePropagation,
-  flush: () => import_runtime_browser2.flush,
-  initAutterBrowser: () => import_runtime_browser2.initAutterBrowser,
-  setContext: () => import_runtime_browser2.setContext,
-  setUser: () => import_runtime_browser2.setUser,
-  trackEvent: () => import_runtime_browser2.trackEvent,
+  flush: () => import_runtime_browser3.flush,
+  initAutterBrowser: () => import_runtime_browser3.initAutterBrowser,
+  reportNextError: () => reportNextError,
+  setContext: () => import_runtime_browser3.setContext,
+  setUser: () => import_runtime_browser3.setUser,
+  trackEvent: () => import_runtime_browser3.trackEvent,
+  useAutterErrorReport: () => useAutterErrorReport,
   withFilters: () => import_filters.withFilters
 });
 module.exports = __toCommonJS(client_exports);
-var import_runtime_browser2 = require("@autter/runtime-browser");
+var import_runtime_browser3 = require("@autter/runtime-browser");
 var import_breadcrumbs = require("@autter/runtime-browser/breadcrumbs");
 var import_tracing = require("@autter/runtime-browser/tracing");
 var import_filters = require("@autter/runtime-browser/filters");
@@ -84,9 +87,59 @@ var AutterErrorBoundary = class extends React.Component {
     return this.props.children;
   }
 };
+
+// src/error-page.ts
+var React2 = __toESM(require("react"), 1);
+var import_runtime_browser2 = require("@autter/runtime-browser");
+
+// src/control-flow.ts
+function digestOf(error) {
+  try {
+    const digest = error == null ? void 0 : error.digest;
+    return typeof digest === "string" ? digest : "";
+  } catch {
+    return "";
+  }
+}
+
+// src/error-page.ts
+var reported = /* @__PURE__ */ new WeakSet();
+function reportNextError(error, options = {}) {
+  var _a;
+  try {
+    if (error && typeof error === "object") {
+      if (reported.has(error)) return;
+      reported.add(error);
+    }
+    const digest = digestOf(error);
+    (0, import_runtime_browser2.captureException)(error, {
+      ...options.context,
+      "next.error_boundary": (_a = options.boundary) != null ? _a : "error",
+      ...digest ? { "next.digest": digest.slice(0, 100) } : {}
+    });
+  } catch {
+  }
+}
+function useAutterErrorReport(error, options) {
+  reportNextError(error, options);
+}
+function AutterGlobalError({ error, reset }) {
+  useAutterErrorReport(error, { boundary: "global-error" });
+  return React2.createElement(
+    "html",
+    { lang: "en" },
+    React2.createElement(
+      "body",
+      null,
+      React2.createElement("h2", null, "Something went wrong"),
+      reset ? React2.createElement("button", { type: "button", onClick: () => reset() }, "Try again") : null
+    )
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AutterErrorBoundary,
+  AutterGlobalError,
   addBreadcrumb,
   autterErrorFromResponse,
   captureException,
@@ -99,8 +152,10 @@ var AutterErrorBoundary = class extends React.Component {
   enableTracePropagation,
   flush,
   initAutterBrowser,
+  reportNextError,
   setContext,
   setUser,
   trackEvent,
+  useAutterErrorReport,
   withFilters
 });

package/dist/client.d.cts

@@ -29,4 +29,48 @@ declare class AutterErrorBoundary extends React.Component<AutterErrorBoundaryPro
     render(): React.ReactNode;
 }
 
-export { AutterErrorBoundary, type AutterErrorBoundaryProps };
+/**
+ * Next.js error pages report through Autter (RF-04). `app/error.tsx` and
+ * `app/global-error.tsx` receive the error React caught; report it while the
+ * page renders, before React logs it, so it is sent once, with the boundary
+ * and Next's `digest` (which names the server-side error onRequestError
+ * reported, when it came from the server):
+ *
+ *   // app/error.tsx
+ *   "use client";
+ *   import { useAutterErrorReport } from "@autter/runtime-next/client";
+ *   export default function Error({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
+ *     useAutterErrorReport(error);
+ *     return <button onClick={reset}>Try again</button>;
+ *   }
+ *
+ *   // app/global-error.tsx
+ *   "use client";
+ *   export { AutterGlobalError as default } from "@autter/runtime-next/client";
+ */
+interface NextErrorReportOptions {
+    /** Which file caught it: "error" (default) or "global-error". */
+    boundary?: "error" | "global-error";
+    /** Extra context for the event. */
+    context?: Record<string, unknown>;
+}
+/** Report an error a Next.js error page received, once per error object. */
+declare function reportNextError(error: unknown, options?: NextErrorReportOptions): void;
+/**
+ * For `app/error.tsx` (and custom `global-error.tsx` pages): reports the
+ * error during render (once, Strict Mode's double render included).
+ */
+declare function useAutterErrorReport(error: unknown, options?: NextErrorReportOptions): void;
+interface AutterGlobalErrorProps {
+    error: Error & {
+        digest?: string;
+    };
+    reset?: () => void;
+}
+/**
+ * A ready `app/global-error.tsx`: reports the error and renders a minimal
+ * page (it replaces the root layout, so it brings its own `<html>`).
+ */
+declare function AutterGlobalError({ error, reset }: AutterGlobalErrorProps): React.ReactElement;
+
+export { AutterErrorBoundary, type AutterErrorBoundaryProps, AutterGlobalError, type AutterGlobalErrorProps, type NextErrorReportOptions, reportNextError, useAutterErrorReport };

package/dist/client.d.ts

@@ -29,4 +29,48 @@ declare class AutterErrorBoundary extends React.Component<AutterErrorBoundaryPro
     render(): React.ReactNode;
 }
 
-export { AutterErrorBoundary, type AutterErrorBoundaryProps };
+/**
+ * Next.js error pages report through Autter (RF-04). `app/error.tsx` and
+ * `app/global-error.tsx` receive the error React caught; report it while the
+ * page renders, before React logs it, so it is sent once, with the boundary
+ * and Next's `digest` (which names the server-side error onRequestError
+ * reported, when it came from the server):
+ *
+ *   // app/error.tsx
+ *   "use client";
+ *   import { useAutterErrorReport } from "@autter/runtime-next/client";
+ *   export default function Error({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
+ *     useAutterErrorReport(error);
+ *     return <button onClick={reset}>Try again</button>;
+ *   }
+ *
+ *   // app/global-error.tsx
+ *   "use client";
+ *   export { AutterGlobalError as default } from "@autter/runtime-next/client";
+ */
+interface NextErrorReportOptions {
+    /** Which file caught it: "error" (default) or "global-error". */
+    boundary?: "error" | "global-error";
+    /** Extra context for the event. */
+    context?: Record<string, unknown>;
+}
+/** Report an error a Next.js error page received, once per error object. */
+declare function reportNextError(error: unknown, options?: NextErrorReportOptions): void;
+/**
+ * For `app/error.tsx` (and custom `global-error.tsx` pages): reports the
+ * error during render (once, Strict Mode's double render included).
+ */
+declare function useAutterErrorReport(error: unknown, options?: NextErrorReportOptions): void;
+interface AutterGlobalErrorProps {
+    error: Error & {
+        digest?: string;
+    };
+    reset?: () => void;
+}
+/**
+ * A ready `app/global-error.tsx`: reports the error and renders a minimal
+ * page (it replaces the root layout, so it brings its own `<html>`).
+ */
+declare function AutterGlobalError({ error, reset }: AutterGlobalErrorProps): React.ReactElement;
+
+export { AutterErrorBoundary, type AutterErrorBoundaryProps, AutterGlobalError, type AutterGlobalErrorProps, type NextErrorReportOptions, reportNextError, useAutterErrorReport };

package/dist/client.js

@@ -6,7 +6,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 // src/client.ts
 import {
   initAutterBrowser,
-  captureException as captureException2,
+  captureException as captureException3,
   captureOutcome,
   captureMessage,
   trackEvent,
@@ -56,11 +56,61 @@ var AutterErrorBoundary = class extends React.Component {
     return this.props.children;
   }
 };
+
+// src/error-page.ts
+import * as React2 from "react";
+import { captureException as captureException2 } from "@autter/runtime-browser";
+
+// src/control-flow.ts
+function digestOf(error) {
+  try {
+    const digest = error == null ? void 0 : error.digest;
+    return typeof digest === "string" ? digest : "";
+  } catch {
+    return "";
+  }
+}
+
+// src/error-page.ts
+var reported = /* @__PURE__ */ new WeakSet();
+function reportNextError(error, options = {}) {
+  var _a;
+  try {
+    if (error && typeof error === "object") {
+      if (reported.has(error)) return;
+      reported.add(error);
+    }
+    const digest = digestOf(error);
+    captureException2(error, {
+      ...options.context,
+      "next.error_boundary": (_a = options.boundary) != null ? _a : "error",
+      ...digest ? { "next.digest": digest.slice(0, 100) } : {}
+    });
+  } catch {
+  }
+}
+function useAutterErrorReport(error, options) {
+  reportNextError(error, options);
+}
+function AutterGlobalError({ error, reset }) {
+  useAutterErrorReport(error, { boundary: "global-error" });
+  return React2.createElement(
+    "html",
+    { lang: "en" },
+    React2.createElement(
+      "body",
+      null,
+      React2.createElement("h2", null, "Something went wrong"),
+      reset ? React2.createElement("button", { type: "button", onClick: () => reset() }, "Try again") : null
+    )
+  );
+}
 export {
   AutterErrorBoundary,
+  AutterGlobalError,
   addBreadcrumb,
   autterErrorFromResponse,
-  captureException2 as captureException,
+  captureException3 as captureException,
   captureMessage,
   captureOutcome,
   clearBreadcrumbs,
@@ -70,8 +120,10 @@ export {
   enableTracePropagation,
   flush,
   initAutterBrowser,
+  reportNextError,
   setContext,
   setUser,
   trackEvent,
+  useAutterErrorReport,
   withFilters
 };

package/dist/index.cjs

@@ -60,6 +60,7 @@ __export(src_exports, {
   runtimeLogger: () => import_runtime_node2.runtimeLogger,
   toClientError: () => import_runtime_node2.toClientError,
   trackLlmCall: () => import_runtime_node2.trackLlmCall,
+  withAutter: () => withAutter,
   withLlmCall: () => import_runtime_node2.withLlmCall,
   withProcessSpan: () => import_runtime_node2.withProcessSpan,
   withRuntimeOperation: () => import_runtime_node2.withRuntimeOperation,
@@ -73,7 +74,7 @@ var import_runtime_node = require("@autter/runtime-node");
 // package.json
 var package_default = {
   name: "@autter/runtime-next",
-  version: "1.8.0",
+  version: "1.9.0",
   description: "One-command Autter Runtime for Next.js: server OTel, request wide events, coded errors, browser tracker, relay route, edge middleware and React error boundary",
   license: "MIT",
   type: "module",
@@ -128,9 +129,9 @@ var package_default = {
     test: "npm run build -w @autter/runtime-core && npm run build -w @autter/runtime-node && npm run build -w @autter/runtime-edge && npm run build -w @autter/runtime-browser && npm run build && node --test test/*.test.mjs"
   },
   dependencies: {
-    "@autter/runtime-browser": "^1.7.0",
-    "@autter/runtime-edge": "^1.2.0",
-    "@autter/runtime-node": "^1.8.0"
+    "@autter/runtime-browser": "^1.8.0",
+    "@autter/runtime-edge": "^1.4.0",
+    "@autter/runtime-node": "^1.9.0"
   },
   peerDependencies: {
     react: ">=18"
@@ -159,6 +160,20 @@ var package_default = {
   ]
 };
 
+// src/control-flow.ts
+var CONTROL_FLOW_DIGEST = /^(?:NEXT_REDIRECT|NEXT_NOT_FOUND|NEXT_HTTP_ERROR_FALLBACK|DYNAMIC_SERVER_USAGE|BAILOUT_TO_CLIENT_SIDE_RENDERING)\b/;
+function digestOf(error) {
+  try {
+    const digest = error?.digest;
+    return typeof digest === "string" ? digest : "";
+  } catch {
+    return "";
+  }
+}
+function isNextControlFlow(error) {
+  return CONTROL_FLOW_DIGEST.test(digestOf(error));
+}
+
 // src/server.ts
 var import_runtime_node2 = require("@autter/runtime-node");
 function registerAutter(options) {
@@ -201,6 +216,24 @@ function withRuntimeRequest(handler, options = {}) {
     waitUntil: options.waitUntil ?? scheduleAfter
   });
 }
+function withAutter(handler, options = {}) {
+  const rule = options.capture;
+  return withRuntimeRequest(
+    async (request, ...rest) => {
+      try {
+        return await handler(request, ...rest);
+      } catch (error) {
+        if (isNextControlFlow(error)) import_runtime_node.runtimeContext.outcome("succeeded");
+        throw error;
+      }
+    },
+    {
+      ...options,
+      capture: (error) => !isNextControlFlow(error) && (typeof rule === "function" ? rule(error) === true : rule !== false),
+      errorResponse: (error) => !isNextControlFlow(error)
+    }
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CODE_PATTERN,
@@ -243,6 +276,7 @@ function withRuntimeRequest(handler, options = {}) {
   runtimeLogger,
   toClientError,
   trackLlmCall,
+  withAutter,
   withLlmCall,
   withProcessSpan,
   withRuntimeOperation,

package/dist/index.d.cts

@@ -1,2 +1,2 @@
-export { createAutterRelayRoute, registerAutter, withRuntimeRequest } from './server.cjs';
-export { AutoFlushHandle, AutoFlushOptions, AutterErrorHandlerOptions, AutterErrorResponseOptions, AutterLogging, AutterLoggingOptions, AutterRequestsOptions, AutterServer, AutterServerOptions, Breadcrumb, BreadcrumbInput, CODE_PATTERN, ClientErrorBody, ConsoleSinkOptions, FileSinkOptions, FlushTarget, InstrumentLlmOptions, LlmCallHandle, LlmCallInfo, LlmUsage, OtlpSinkOptions, RedactOptions, RelayOptions, RuntimeCarrier, RuntimeContextHandle, RuntimeEnrichContext, RuntimeEnrichEvent, RuntimeEnricher, RuntimeError, RuntimeErrorCatalog, RuntimeErrorDefinition, RuntimeErrorExtras, RuntimeErrorFactory, RuntimeErrorLike, RuntimeErrorOptions, RuntimeEvent, RuntimeLogContext, RuntimeLogContextValue, RuntimeLogLevel, RuntimeLoggingOptions, RuntimeOperation, RuntimeOperationKind, RuntimeOperationOptions, RuntimeOutcome, RuntimeRequestOptions, RuntimeSink, RuntimeSinkContext, SafeCapture, TrackedLlmCall, addBreadcrumb, autterErrorHandler, autterErrorResponse, autterFastify, autterFastifyErrors, autterKoa, autterRequests, captureRequestError, captureException as captureServerException, captureMessage as captureServerMessage, consoleSink, createRuntimeLogger, defineRuntimeErrors, emitLlmSelftestTrace, enrichDeployment, enrichEdgeGeo, enrichRequestSize, enrichUserAgent, errorAttributes, fileSink, flushRuntimeLogs, initAutterLogging, installAutterAutoFlush, instrumentLlmClient, isRuntimeErrorLike, makeSafeCapture, otlpSink, redactAttributes, redactText, reportOutcome as reportServerOutcome, runInBackground, runtimeContext, runtimeLogStats, runtimeLogger, toClientError, trackLlmCall, withLlmCall, withProcessSpan, withRuntimeOperation } from '@autter/runtime-node';
+export { AutterRouteOptions, createAutterRelayRoute, registerAutter, withAutter, withRuntimeRequest } from './server.cjs';
+export { AutoFlushHandle, AutoFlushOptions, AutterErrorHandlerOptions, AutterErrorResponseOptions, AutterLogging, AutterLoggingOptions, AutterRequestsOptions, AutterServer, AutterServerOptions, Breadcrumb, BreadcrumbInput, CODE_PATTERN, CaptureLoggedErrorsOption, ClientErrorBody, ConsoleSinkOptions, FileSinkOptions, FlushTarget, InstrumentLlmOptions, LlmCallHandle, LlmCallInfo, LlmUsage, LoggedErrorSource, OtlpSinkOptions, RedactOptions, RelayOptions, RuntimeCarrier, RuntimeContextHandle, RuntimeEnrichContext, RuntimeEnrichEvent, RuntimeEnricher, RuntimeError, RuntimeErrorCatalog, RuntimeErrorDefinition, RuntimeErrorExtras, RuntimeErrorFactory, RuntimeErrorLike, RuntimeErrorOptions, RuntimeEvent, RuntimeLogContext, RuntimeLogContextValue, RuntimeLogLevel, RuntimeLoggingOptions, RuntimeOperation, RuntimeOperationKind, RuntimeOperationOptions, RuntimeOutcome, RuntimeRequestOptions, RuntimeSink, RuntimeSinkContext, SafeCapture, TrackedLlmCall, addBreadcrumb, autterErrorHandler, autterErrorResponse, autterFastify, autterFastifyErrors, autterKoa, autterRequests, captureRequestError, captureException as captureServerException, captureMessage as captureServerMessage, consoleSink, createRuntimeLogger, defineRuntimeErrors, emitLlmSelftestTrace, enrichDeployment, enrichEdgeGeo, enrichRequestSize, enrichUserAgent, errorAttributes, fileSink, flushRuntimeLogs, initAutterLogging, installAutterAutoFlush, instrumentLlmClient, isRuntimeErrorLike, makeSafeCapture, otlpSink, redactAttributes, redactText, reportOutcome as reportServerOutcome, runInBackground, runtimeContext, runtimeLogStats, runtimeLogger, toClientError, trackLlmCall, withLlmCall, withProcessSpan, withRuntimeOperation } from '@autter/runtime-node';

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { createAutterRelayRoute, registerAutter, withRuntimeRequest } from './server.js';
-export { AutoFlushHandle, AutoFlushOptions, AutterErrorHandlerOptions, AutterErrorResponseOptions, AutterLogging, AutterLoggingOptions, AutterRequestsOptions, AutterServer, AutterServerOptions, Breadcrumb, BreadcrumbInput, CODE_PATTERN, ClientErrorBody, ConsoleSinkOptions, FileSinkOptions, FlushTarget, InstrumentLlmOptions, LlmCallHandle, LlmCallInfo, LlmUsage, OtlpSinkOptions, RedactOptions, RelayOptions, RuntimeCarrier, RuntimeContextHandle, RuntimeEnrichContext, RuntimeEnrichEvent, RuntimeEnricher, RuntimeError, RuntimeErrorCatalog, RuntimeErrorDefinition, RuntimeErrorExtras, RuntimeErrorFactory, RuntimeErrorLike, RuntimeErrorOptions, RuntimeEvent, RuntimeLogContext, RuntimeLogContextValue, RuntimeLogLevel, RuntimeLoggingOptions, RuntimeOperation, RuntimeOperationKind, RuntimeOperationOptions, RuntimeOutcome, RuntimeRequestOptions, RuntimeSink, RuntimeSinkContext, SafeCapture, TrackedLlmCall, addBreadcrumb, autterErrorHandler, autterErrorResponse, autterFastify, autterFastifyErrors, autterKoa, autterRequests, captureRequestError, captureException as captureServerException, captureMessage as captureServerMessage, consoleSink, createRuntimeLogger, defineRuntimeErrors, emitLlmSelftestTrace, enrichDeployment, enrichEdgeGeo, enrichRequestSize, enrichUserAgent, errorAttributes, fileSink, flushRuntimeLogs, initAutterLogging, installAutterAutoFlush, instrumentLlmClient, isRuntimeErrorLike, makeSafeCapture, otlpSink, redactAttributes, redactText, reportOutcome as reportServerOutcome, runInBackground, runtimeContext, runtimeLogStats, runtimeLogger, toClientError, trackLlmCall, withLlmCall, withProcessSpan, withRuntimeOperation } from '@autter/runtime-node';
+export { AutterRouteOptions, createAutterRelayRoute, registerAutter, withAutter, withRuntimeRequest } from './server.js';
+export { AutoFlushHandle, AutoFlushOptions, AutterErrorHandlerOptions, AutterErrorResponseOptions, AutterLogging, AutterLoggingOptions, AutterRequestsOptions, AutterServer, AutterServerOptions, Breadcrumb, BreadcrumbInput, CODE_PATTERN, CaptureLoggedErrorsOption, ClientErrorBody, ConsoleSinkOptions, FileSinkOptions, FlushTarget, InstrumentLlmOptions, LlmCallHandle, LlmCallInfo, LlmUsage, LoggedErrorSource, OtlpSinkOptions, RedactOptions, RelayOptions, RuntimeCarrier, RuntimeContextHandle, RuntimeEnrichContext, RuntimeEnrichEvent, RuntimeEnricher, RuntimeError, RuntimeErrorCatalog, RuntimeErrorDefinition, RuntimeErrorExtras, RuntimeErrorFactory, RuntimeErrorLike, RuntimeErrorOptions, RuntimeEvent, RuntimeLogContext, RuntimeLogContextValue, RuntimeLogLevel, RuntimeLoggingOptions, RuntimeOperation, RuntimeOperationKind, RuntimeOperationOptions, RuntimeOutcome, RuntimeRequestOptions, RuntimeSink, RuntimeSinkContext, SafeCapture, TrackedLlmCall, addBreadcrumb, autterErrorHandler, autterErrorResponse, autterFastify, autterFastifyErrors, autterKoa, autterRequests, captureRequestError, captureException as captureServerException, captureMessage as captureServerMessage, consoleSink, createRuntimeLogger, defineRuntimeErrors, emitLlmSelftestTrace, enrichDeployment, enrichEdgeGeo, enrichRequestSize, enrichUserAgent, errorAttributes, fileSink, flushRuntimeLogs, initAutterLogging, installAutterAutoFlush, instrumentLlmClient, isRuntimeErrorLike, makeSafeCapture, otlpSink, redactAttributes, redactText, reportOutcome as reportServerOutcome, runInBackground, runtimeContext, runtimeLogStats, runtimeLogger, toClientError, trackLlmCall, withLlmCall, withProcessSpan, withRuntimeOperation } from '@autter/runtime-node';

package/dist/index.js

@@ -39,11 +39,12 @@ import {
   runtimeLogger,
   toClientError,
   trackLlmCall,
+  withAutter,
   withLlmCall,
   withProcessSpan,
   withRuntimeOperation,
   withRuntimeRequest
-} from "./chunk-FU5HRQKM.js";
+} from "./chunk-6MFPMECS.js";
 export {
   CODE_PATTERN,
   RuntimeError,
@@ -85,6 +86,7 @@ export {
   runtimeLogger,
   toClientError,
   trackLlmCall,
+  withAutter,
   withLlmCall,
   withProcessSpan,
   withRuntimeOperation,

package/dist/instrumentation-edge.cjs

@@ -27,6 +27,8 @@ module.exports = __toCommonJS(instrumentation_edge_exports);
 
 // src/request-error.ts
 var import_runtime_edge = require("@autter/runtime-edge");
+
+// src/control-flow.ts
 var CONTROL_FLOW_DIGEST = /^(?:NEXT_REDIRECT|NEXT_NOT_FOUND|NEXT_HTTP_ERROR_FALLBACK|DYNAMIC_SERVER_USAGE|BAILOUT_TO_CLIENT_SIDE_RENDERING)\b/;
 function digestOf(error) {
   try {
@@ -36,6 +38,11 @@ function digestOf(error) {
     return "";
   }
 }
+function isNextControlFlow(error) {
+  return CONTROL_FLOW_DIGEST.test(digestOf(error));
+}
+
+// src/request-error.ts
 function shouldReport(error, rule) {
   if (rule === true) return true;
   if (rule === false) return false;
@@ -46,7 +53,7 @@ function shouldReport(error, rule) {
       return false;
     }
   }
-  return !CONTROL_FLOW_DIGEST.test(digestOf(error));
+  return !isNextControlFlow(error);
 }
 function requestErrorAttributes(error, request, context) {
   const out = {};

package/dist/instrumentation-edge.js

@@ -2,7 +2,7 @@ import {
   reportOnEdge,
   requestErrorAttributes,
   shouldReport
-} from "./chunk-CL2ENM4A.js";
+} from "./chunk-Q2TA3ACY.js";
 
 // src/instrumentation-edge.ts
 function autterOnRequestError(options = {}) {

package/dist/instrumentation.cjs

@@ -37,6 +37,8 @@ module.exports = __toCommonJS(instrumentation_exports);
 
 // src/request-error.ts
 var import_runtime_edge = require("@autter/runtime-edge");
+
+// src/control-flow.ts
 var CONTROL_FLOW_DIGEST = /^(?:NEXT_REDIRECT|NEXT_NOT_FOUND|NEXT_HTTP_ERROR_FALLBACK|DYNAMIC_SERVER_USAGE|BAILOUT_TO_CLIENT_SIDE_RENDERING)\b/;
 function digestOf(error) {
   try {
@@ -46,6 +48,11 @@ function digestOf(error) {
     return "";
   }
 }
+function isNextControlFlow(error) {
+  return CONTROL_FLOW_DIGEST.test(digestOf(error));
+}
+
+// src/request-error.ts
 function shouldReport(error, rule) {
   if (rule === true) return true;
   if (rule === false) return false;
@@ -56,7 +63,7 @@ function shouldReport(error, rule) {
       return false;
     }
   }
-  return !CONTROL_FLOW_DIGEST.test(digestOf(error));
+  return !isNextControlFlow(error);
 }
 function requestErrorAttributes(error, request, context) {
   const out = {};

package/dist/instrumentation.js

@@ -2,7 +2,7 @@ import {
   reportOnEdge,
   requestErrorAttributes,
   shouldReport
-} from "./chunk-CL2ENM4A.js";
+} from "./chunk-Q2TA3ACY.js";
 
 // src/instrumentation.ts
 function autterOnRequestError(options = {}) {

package/dist/server.cjs

@@ -60,6 +60,7 @@ __export(server_exports, {
   runtimeLogger: () => import_runtime_node2.runtimeLogger,
   toClientError: () => import_runtime_node2.toClientError,
   trackLlmCall: () => import_runtime_node2.trackLlmCall,
+  withAutter: () => withAutter,
   withLlmCall: () => import_runtime_node2.withLlmCall,
   withProcessSpan: () => import_runtime_node2.withProcessSpan,
   withRuntimeOperation: () => import_runtime_node2.withRuntimeOperation,
@@ -71,7 +72,7 @@ var import_runtime_node = require("@autter/runtime-node");
 // package.json
 var package_default = {
   name: "@autter/runtime-next",
-  version: "1.8.0",
+  version: "1.9.0",
   description: "One-command Autter Runtime for Next.js: server OTel, request wide events, coded errors, browser tracker, relay route, edge middleware and React error boundary",
   license: "MIT",
   type: "module",
@@ -126,9 +127,9 @@ var package_default = {
     test: "npm run build -w @autter/runtime-core && npm run build -w @autter/runtime-node && npm run build -w @autter/runtime-edge && npm run build -w @autter/runtime-browser && npm run build && node --test test/*.test.mjs"
   },
   dependencies: {
-    "@autter/runtime-browser": "^1.7.0",
-    "@autter/runtime-edge": "^1.2.0",
-    "@autter/runtime-node": "^1.8.0"
+    "@autter/runtime-browser": "^1.8.0",
+    "@autter/runtime-edge": "^1.4.0",
+    "@autter/runtime-node": "^1.9.0"
   },
   peerDependencies: {
     react: ">=18"
@@ -157,6 +158,20 @@ var package_default = {
   ]
 };
 
+// src/control-flow.ts
+var CONTROL_FLOW_DIGEST = /^(?:NEXT_REDIRECT|NEXT_NOT_FOUND|NEXT_HTTP_ERROR_FALLBACK|DYNAMIC_SERVER_USAGE|BAILOUT_TO_CLIENT_SIDE_RENDERING)\b/;
+function digestOf(error) {
+  try {
+    const digest = error?.digest;
+    return typeof digest === "string" ? digest : "";
+  } catch {
+    return "";
+  }
+}
+function isNextControlFlow(error) {
+  return CONTROL_FLOW_DIGEST.test(digestOf(error));
+}
+
 // src/server.ts
 var import_runtime_node2 = require("@autter/runtime-node");
 function registerAutter(options) {
@@ -199,6 +214,24 @@ function withRuntimeRequest(handler, options = {}) {
     waitUntil: options.waitUntil ?? scheduleAfter
   });
 }
+function withAutter(handler, options = {}) {
+  const rule = options.capture;
+  return withRuntimeRequest(
+    async (request, ...rest) => {
+      try {
+        return await handler(request, ...rest);
+      } catch (error) {
+        if (isNextControlFlow(error)) import_runtime_node.runtimeContext.outcome("succeeded");
+        throw error;
+      }
+    },
+    {
+      ...options,
+      capture: (error) => !isNextControlFlow(error) && (typeof rule === "function" ? rule(error) === true : rule !== false),
+      errorResponse: (error) => !isNextControlFlow(error)
+    }
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CODE_PATTERN,
@@ -241,6 +274,7 @@ function withRuntimeRequest(handler, options = {}) {
   runtimeLogger,
   toClientError,
   trackLlmCall,
+  withAutter,
   withLlmCall,
   withProcessSpan,
   withRuntimeOperation,

package/dist/server.d.cts

@@ -1,5 +1,5 @@
-import { RelayOptions, AutterServerOptions, AutterServer, RuntimeRequestOptions } from '@autter/runtime-node';
-export { AutoFlushHandle, AutoFlushOptions, AutterErrorHandlerOptions, AutterErrorResponseOptions, AutterLogging, AutterLoggingOptions, AutterRequestsOptions, AutterServer, AutterServerOptions, Breadcrumb, BreadcrumbInput, CODE_PATTERN, ClientErrorBody, ConsoleSinkOptions, FileSinkOptions, FlushTarget, InstrumentLlmOptions, LlmCallHandle, LlmCallInfo, LlmUsage, OtlpSinkOptions, RedactOptions, RelayOptions, RuntimeCarrier, RuntimeContextHandle, RuntimeEnrichContext, RuntimeEnrichEvent, RuntimeEnricher, RuntimeError, RuntimeErrorCatalog, RuntimeErrorDefinition, RuntimeErrorExtras, RuntimeErrorFactory, RuntimeErrorLike, RuntimeErrorOptions, RuntimeEvent, RuntimeLogContext, RuntimeLogContextValue, RuntimeLogLevel, RuntimeLoggingOptions, RuntimeOperation, RuntimeOperationKind, RuntimeOperationOptions, RuntimeOutcome, RuntimeRequestOptions, RuntimeSink, RuntimeSinkContext, SafeCapture, TrackedLlmCall, addBreadcrumb, autterErrorHandler, autterErrorResponse, autterFastify, autterFastifyErrors, autterKoa, autterRequests, captureRequestError, captureException as captureServerException, captureMessage as captureServerMessage, consoleSink, createRuntimeLogger, defineRuntimeErrors, emitLlmSelftestTrace, enrichDeployment, enrichEdgeGeo, enrichRequestSize, enrichUserAgent, errorAttributes, fileSink, flushRuntimeLogs, initAutterLogging, installAutterAutoFlush, instrumentLlmClient, isRuntimeErrorLike, makeSafeCapture, otlpSink, redactAttributes, redactText, reportOutcome as reportServerOutcome, runInBackground, runtimeContext, runtimeLogStats, runtimeLogger, toClientError, trackLlmCall, withLlmCall, withProcessSpan, withRuntimeOperation } from '@autter/runtime-node';
+import { RuntimeRequestOptions, RelayOptions, AutterServerOptions, AutterServer } from '@autter/runtime-node';
+export { AutoFlushHandle, AutoFlushOptions, AutterErrorHandlerOptions, AutterErrorResponseOptions, AutterLogging, AutterLoggingOptions, AutterRequestsOptions, AutterServer, AutterServerOptions, Breadcrumb, BreadcrumbInput, CODE_PATTERN, CaptureLoggedErrorsOption, ClientErrorBody, ConsoleSinkOptions, FileSinkOptions, FlushTarget, InstrumentLlmOptions, LlmCallHandle, LlmCallInfo, LlmUsage, LoggedErrorSource, OtlpSinkOptions, RedactOptions, RelayOptions, RuntimeCarrier, RuntimeContextHandle, RuntimeEnrichContext, RuntimeEnrichEvent, RuntimeEnricher, RuntimeError, RuntimeErrorCatalog, RuntimeErrorDefinition, RuntimeErrorExtras, RuntimeErrorFactory, RuntimeErrorLike, RuntimeErrorOptions, RuntimeEvent, RuntimeLogContext, RuntimeLogContextValue, RuntimeLogLevel, RuntimeLoggingOptions, RuntimeOperation, RuntimeOperationKind, RuntimeOperationOptions, RuntimeOutcome, RuntimeRequestOptions, RuntimeSink, RuntimeSinkContext, SafeCapture, TrackedLlmCall, addBreadcrumb, autterErrorHandler, autterErrorResponse, autterFastify, autterFastifyErrors, autterKoa, autterRequests, captureRequestError, captureException as captureServerException, captureMessage as captureServerMessage, consoleSink, createRuntimeLogger, defineRuntimeErrors, emitLlmSelftestTrace, enrichDeployment, enrichEdgeGeo, enrichRequestSize, enrichUserAgent, errorAttributes, fileSink, flushRuntimeLogs, initAutterLogging, installAutterAutoFlush, instrumentLlmClient, isRuntimeErrorLike, makeSafeCapture, otlpSink, redactAttributes, redactText, reportOutcome as reportServerOutcome, runInBackground, runtimeContext, runtimeLogStats, runtimeLogger, toClientError, trackLlmCall, withLlmCall, withProcessSpan, withRuntimeOperation } from '@autter/runtime-node';
 
 /**
  * Server half of @autter/runtime-next. Safe to import anywhere Node runs:
@@ -35,6 +35,15 @@ export { AutoFlushHandle, AutoFlushOptions, AutterErrorHandlerOptions, AutterErr
  *
  *    The log flush is handed to Next's `after()` automatically.
  *
+ * 4. Route handlers that answer thrown errors (RF-04):
+ *
+ *      import { withAutter, RuntimeError } from "@autter/runtime-next";
+ *      export const GET = withAutter(async (request) => {
+ *        throw new RuntimeError({ status: 404, code: "orders.not_found", message: "No such order" });
+ *      });
+ *
+ *    The thrown 404 is recorded with its stack and answered as a 404.
+ *
  * Browser tracker + error boundary live in `@autter/runtime-next/client`;
  * `middleware.ts` (edge runtime) uses `@autter/runtime-next/edge`.
  */
@@ -51,5 +60,29 @@ declare function createAutterRelayRoute(options: RelayOptions): {
  * `unstable_after` on 14.2) unless you pass your own `waitUntil`.
  */
 declare function withRuntimeRequest<A extends unknown[]>(handler: (request: Request, ...rest: A) => Response | Promise<Response>, options?: RuntimeRequestOptions): (request: Request, ...rest: A) => Promise<Response>;
+interface AutterRouteOptions extends Omit<RuntimeRequestOptions, "capture" | "errorResponse"> {
+    /**
+     * Which thrown errors are reported. Default: every one except Next's
+     * control-flow signals (`redirect()`, `notFound()`, …), which always
+     * pass through to Next untouched.
+     */
+    capture?: boolean | ((error: unknown) => boolean);
+}
+/**
+ * Route handler wrapper (RF-04): a request summary like `withRuntimeRequest`,
+ * and a thrown error is recorded with its stack on the request span, then
+ * answered with `toClientError` JSON and the error's own status, so a thrown
+ * 4xx (a `RuntimeError` with `status: 404`, any error with a 4xx `status`)
+ * stays a 4xx and keeps its stack instead of becoming an anonymous 500.
+ * Next's `redirect()` / `notFound()` signals are rethrown for Next to
+ * answer, and never reported.
+ *
+ *   export const POST = withAutter(async (request) => {
+ *     const order = await findOrder(request);
+ *     if (!order) throw new RuntimeError({ status: 404, code: "orders.not_found", message: "No such order" });
+ *     return Response.json(order);
+ *   });
+ */
+declare function withAutter<A extends unknown[]>(handler: (request: Request, ...rest: A) => Response | Promise<Response>, options?: AutterRouteOptions): (request: Request, ...rest: A) => Promise<Response>;
 
-export { createAutterRelayRoute, registerAutter, withRuntimeRequest };
+export { type AutterRouteOptions, createAutterRelayRoute, registerAutter, withAutter, withRuntimeRequest };

package/dist/server.d.ts

@@ -1,5 +1,5 @@
-import { RelayOptions, AutterServerOptions, AutterServer, RuntimeRequestOptions } from '@autter/runtime-node';
-export { AutoFlushHandle, AutoFlushOptions, AutterErrorHandlerOptions, AutterErrorResponseOptions, AutterLogging, AutterLoggingOptions, AutterRequestsOptions, AutterServer, AutterServerOptions, Breadcrumb, BreadcrumbInput, CODE_PATTERN, ClientErrorBody, ConsoleSinkOptions, FileSinkOptions, FlushTarget, InstrumentLlmOptions, LlmCallHandle, LlmCallInfo, LlmUsage, OtlpSinkOptions, RedactOptions, RelayOptions, RuntimeCarrier, RuntimeContextHandle, RuntimeEnrichContext, RuntimeEnrichEvent, RuntimeEnricher, RuntimeError, RuntimeErrorCatalog, RuntimeErrorDefinition, RuntimeErrorExtras, RuntimeErrorFactory, RuntimeErrorLike, RuntimeErrorOptions, RuntimeEvent, RuntimeLogContext, RuntimeLogContextValue, RuntimeLogLevel, RuntimeLoggingOptions, RuntimeOperation, RuntimeOperationKind, RuntimeOperationOptions, RuntimeOutcome, RuntimeRequestOptions, RuntimeSink, RuntimeSinkContext, SafeCapture, TrackedLlmCall, addBreadcrumb, autterErrorHandler, autterErrorResponse, autterFastify, autterFastifyErrors, autterKoa, autterRequests, captureRequestError, captureException as captureServerException, captureMessage as captureServerMessage, consoleSink, createRuntimeLogger, defineRuntimeErrors, emitLlmSelftestTrace, enrichDeployment, enrichEdgeGeo, enrichRequestSize, enrichUserAgent, errorAttributes, fileSink, flushRuntimeLogs, initAutterLogging, installAutterAutoFlush, instrumentLlmClient, isRuntimeErrorLike, makeSafeCapture, otlpSink, redactAttributes, redactText, reportOutcome as reportServerOutcome, runInBackground, runtimeContext, runtimeLogStats, runtimeLogger, toClientError, trackLlmCall, withLlmCall, withProcessSpan, withRuntimeOperation } from '@autter/runtime-node';
+import { RuntimeRequestOptions, RelayOptions, AutterServerOptions, AutterServer } from '@autter/runtime-node';
+export { AutoFlushHandle, AutoFlushOptions, AutterErrorHandlerOptions, AutterErrorResponseOptions, AutterLogging, AutterLoggingOptions, AutterRequestsOptions, AutterServer, AutterServerOptions, Breadcrumb, BreadcrumbInput, CODE_PATTERN, CaptureLoggedErrorsOption, ClientErrorBody, ConsoleSinkOptions, FileSinkOptions, FlushTarget, InstrumentLlmOptions, LlmCallHandle, LlmCallInfo, LlmUsage, LoggedErrorSource, OtlpSinkOptions, RedactOptions, RelayOptions, RuntimeCarrier, RuntimeContextHandle, RuntimeEnrichContext, RuntimeEnrichEvent, RuntimeEnricher, RuntimeError, RuntimeErrorCatalog, RuntimeErrorDefinition, RuntimeErrorExtras, RuntimeErrorFactory, RuntimeErrorLike, RuntimeErrorOptions, RuntimeEvent, RuntimeLogContext, RuntimeLogContextValue, RuntimeLogLevel, RuntimeLoggingOptions, RuntimeOperation, RuntimeOperationKind, RuntimeOperationOptions, RuntimeOutcome, RuntimeRequestOptions, RuntimeSink, RuntimeSinkContext, SafeCapture, TrackedLlmCall, addBreadcrumb, autterErrorHandler, autterErrorResponse, autterFastify, autterFastifyErrors, autterKoa, autterRequests, captureRequestError, captureException as captureServerException, captureMessage as captureServerMessage, consoleSink, createRuntimeLogger, defineRuntimeErrors, emitLlmSelftestTrace, enrichDeployment, enrichEdgeGeo, enrichRequestSize, enrichUserAgent, errorAttributes, fileSink, flushRuntimeLogs, initAutterLogging, installAutterAutoFlush, instrumentLlmClient, isRuntimeErrorLike, makeSafeCapture, otlpSink, redactAttributes, redactText, reportOutcome as reportServerOutcome, runInBackground, runtimeContext, runtimeLogStats, runtimeLogger, toClientError, trackLlmCall, withLlmCall, withProcessSpan, withRuntimeOperation } from '@autter/runtime-node';
 
 /**
  * Server half of @autter/runtime-next. Safe to import anywhere Node runs:
@@ -35,6 +35,15 @@ export { AutoFlushHandle, AutoFlushOptions, AutterErrorHandlerOptions, AutterErr
  *
  *    The log flush is handed to Next's `after()` automatically.
  *
+ * 4. Route handlers that answer thrown errors (RF-04):
+ *
+ *      import { withAutter, RuntimeError } from "@autter/runtime-next";
+ *      export const GET = withAutter(async (request) => {
+ *        throw new RuntimeError({ status: 404, code: "orders.not_found", message: "No such order" });
+ *      });
+ *
+ *    The thrown 404 is recorded with its stack and answered as a 404.
+ *
  * Browser tracker + error boundary live in `@autter/runtime-next/client`;
  * `middleware.ts` (edge runtime) uses `@autter/runtime-next/edge`.
  */
@@ -51,5 +60,29 @@ declare function createAutterRelayRoute(options: RelayOptions): {
  * `unstable_after` on 14.2) unless you pass your own `waitUntil`.
  */
 declare function withRuntimeRequest<A extends unknown[]>(handler: (request: Request, ...rest: A) => Response | Promise<Response>, options?: RuntimeRequestOptions): (request: Request, ...rest: A) => Promise<Response>;
+interface AutterRouteOptions extends Omit<RuntimeRequestOptions, "capture" | "errorResponse"> {
+    /**
+     * Which thrown errors are reported. Default: every one except Next's
+     * control-flow signals (`redirect()`, `notFound()`, …), which always
+     * pass through to Next untouched.
+     */
+    capture?: boolean | ((error: unknown) => boolean);
+}
+/**
+ * Route handler wrapper (RF-04): a request summary like `withRuntimeRequest`,
+ * and a thrown error is recorded with its stack on the request span, then
+ * answered with `toClientError` JSON and the error's own status, so a thrown
+ * 4xx (a `RuntimeError` with `status: 404`, any error with a 4xx `status`)
+ * stays a 4xx and keeps its stack instead of becoming an anonymous 500.
+ * Next's `redirect()` / `notFound()` signals are rethrown for Next to
+ * answer, and never reported.
+ *
+ *   export const POST = withAutter(async (request) => {
+ *     const order = await findOrder(request);
+ *     if (!order) throw new RuntimeError({ status: 404, code: "orders.not_found", message: "No such order" });
+ *     return Response.json(order);
+ *   });
+ */
+declare function withAutter<A extends unknown[]>(handler: (request: Request, ...rest: A) => Response | Promise<Response>, options?: AutterRouteOptions): (request: Request, ...rest: A) => Promise<Response>;
 
-export { createAutterRelayRoute, registerAutter, withRuntimeRequest };
+export { type AutterRouteOptions, createAutterRelayRoute, registerAutter, withAutter, withRuntimeRequest };

package/dist/server.js

@@ -39,11 +39,12 @@ import {
   runtimeLogger,
   toClientError,
   trackLlmCall,
+  withAutter,
   withLlmCall,
   withProcessSpan,
   withRuntimeOperation,
   withRuntimeRequest
-} from "./chunk-FU5HRQKM.js";
+} from "./chunk-6MFPMECS.js";
 export {
   CODE_PATTERN,
   RuntimeError,
@@ -85,6 +86,7 @@ export {
   runtimeLogger,
   toClientError,
   trackLlmCall,
+  withAutter,
   withLlmCall,
   withProcessSpan,
   withRuntimeOperation,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@autter/runtime-next",
-	"version": "1.8.0",
+	"version": "1.9.0",
 	"description": "One-command Autter Runtime for Next.js: server OTel, request wide events, coded errors, browser tracker, relay route, edge middleware and React error boundary",
 	"license": "MIT",
 	"type": "module",
@@ -55,9 +55,9 @@
 		"test": "npm run build -w @autter/runtime-core && npm run build -w @autter/runtime-node && npm run build -w @autter/runtime-edge && npm run build -w @autter/runtime-browser && npm run build && node --test test/*.test.mjs"
 	},
 	"dependencies": {
-		"@autter/runtime-browser": "^1.7.0",
-		"@autter/runtime-edge": "^1.2.0",
-		"@autter/runtime-node": "^1.8.0"
+		"@autter/runtime-browser": "^1.8.0",
+		"@autter/runtime-edge": "^1.4.0",
+		"@autter/runtime-node": "^1.9.0"
 	},
 	"peerDependencies": {
 		"react": ">=18"