@glasstrace/sdk 1.5.1 → 1.6.0

package/README.md

@@ -349,6 +349,114 @@ body data. If your account enables the flag but a span never carries
 the internal attribute (no adapter set it), the public attribute is
 still absent. The default is "off, twice".
 
+## Capturing error evidence
+
+For server-side errors, the SDK promotes a curated set of OTel
+attributes into the `glasstrace.error.*` family so product
+consumers can render bounded, sanitized error evidence without
+having to parse raw stack traces or framework HTML themselves.
+
+### Bounded stack capture
+
+When an OTel `recordException()` event (or a span attribute carrying
+`exception.stacktrace`) is observed on a failed span, the SDK
+emits the stack as `glasstrace.error.stack` with two sibling
+booleans:
+
+| Attribute | Meaning |
+|---|---|
+| `glasstrace.error.stack` | The bounded stack string (sanitized, then truncated). Treat this as input for product-side `StackSummary` parsing, not as a final agent-facing artifact. |
+| `glasstrace.error.stack.truncated` | `true` if the original exceeded the byte budget and `...[stack truncated]` was appended. |
+| `glasstrace.error.stack.redacted` | `true` if at least one sanitization rule modified the stack content (path normalization, URL query stripping, or credential redaction). |
+
+Sanitization runs **before** truncation so credentials straddling
+the truncation boundary are still removed from the visible portion.
+The sanitizer:
+
+- **Normalizes absolute paths.** A frame like
+  `at handler (/Users/erik/proj/src/api/handler.ts:5:1)` becomes
+  `at handler (<path>/src/api/handler.ts:5:1)`. The keep-from
+  marker set is `node_modules`, `.next`, `.glasstrace`, `src`,
+  `dist`, `build`, `lib`, `app`, `pages` (priority order). When no
+  marker matches, the path collapses to its basename so
+  `/var/private/secret/data.js` becomes `<path>/data.js`.
+- **Strips URL query strings and fragments.**
+  `https://api.example.com/users?token=secret` becomes
+  `https://api.example.com/users`.
+- **Redacts credentials** using the same pattern set as
+  response-body capture: `Bearer …`, JWT-shaped tokens,
+  Glasstrace API key prefixes (`gt_dev_*` / `gt_anon_*`), AWS
+  access keys (`AKIA…` / `ASIA…`), and `apikey`/`secret`/
+  `password`/`token` key-value pairs.
+
+The byte budget is 8192 UTF-8 bytes. Truncation respects codepoint
+boundaries so multi-byte characters are never split mid-sequence.
+
+### Source provenance
+
+When the exporter emits any of the new
+`glasstrace.error.{message,code,stack,original_path,fallback_route}`
+attributes, it also sets `glasstrace.error.source` to name the
+surface that supplied the facts:
+
+| Value | Source |
+|---|---|
+| `otel_exception` | OTel `recordException()` event (event name `"exception"`). |
+| `otel_event` | An OTel-shape `exception.*` attribute set on the span itself instead of on an event. |
+| `glasstrace_attribute` | A `glasstrace.error.*` attribute set explicitly by an adapter or user code. |
+| `framework_runtime` | Reserved for a future framework-runtime probe. |
+| `framework_fallback` | The framework rewrote the route to a fallback (e.g., `/_error`); see below. |
+| `response_body` | Reserved for cases where the response body is the only error-bearing surface. |
+
+Product consumers use the source to decide how to render
+evidence (an `otel_exception` source can show the raw type and
+message; `framework_fallback` is a softer signal that benefits
+from the original-path context).
+
+### Framework fallback markers
+
+When a request reaches a framework fallback route — Next.js
+`/_error`, `/_not-found`, `/_404`, `/_500` — the SDK preserves
+the originally requested path so product consumers don't lose the
+URL the user actually hit. Three additional attributes land on
+the span:
+
+| Attribute | Example |
+|---|---|
+| `glasstrace.error.original_path` | `/api/storage/missing/avatar.png` (path-only; no query, no fragment) |
+| `glasstrace.error.fallback_route` | `/_error` |
+| `glasstrace.error.framework.kind` | `"fallback"` |
+
+The existing `glasstrace.route` attribute continues to carry
+whatever the framework instrumentation reported (typically the
+fallback route itself), so existing consumers are unaffected.
+Product-side projection should prefer `glasstrace.error.original_path`
+when present and fall back to `glasstrace.route` otherwise. The
+markers fire only when the SDK observed a different requested URL
+than the route — a real visit to `/_error` (an app could have a
+real such page) is not flagged.
+
+### What the SDK does NOT do
+
+For agent-facing protection, several things are explicitly *not*
+emitted from the SDK side:
+
+- **No raw `exception.stacktrace`.** The string is always
+  sanitized before promotion to `glasstrace.error.stack`, and the
+  source-attribute path that bypassed enrichment never appears in
+  agent-facing MCP output (product ingestion projects only the
+  `glasstrace.*` family).
+- **No fabricated stack frames** when `exception.stacktrace` was
+  not observed. Missing stack evidence stays missing; the
+  `glasstrace.error.stack*` attributes are simply absent.
+- **No compile-diagnostic capture** in this version. If the SDK
+  cannot observe a Next.js compile error in the running mode, no
+  diagnostic is fabricated from the route name or status code.
+  Compile-diagnostic capture is a future feature gated on a
+  separate account capture-policy class.
+- **No structured application logs.** Application logs are
+  outside the trace-evidence contract.
+
 ## Capturing side-effect evidence
 
 When debugging a bug whose root cause is which side-effect operation

package/dist/{chunk-YLY7AGLC.js → chunk-3PJP5Y3U.js}

@@ -5,10 +5,10 @@ import {
   isDevApiKey,
   readEnvLocalApiKey,
   writeAndFsyncTempSync
-} from "./chunk-MFYOQOD7.js";
+} from "./chunk-WL6BXEJ5.js";
 import {
   AnonApiKeySchema
-} from "./chunk-4WI7B5FQ.js";
+} from "./chunk-P45NZR4J.js";
 import {
   NEXT_CONFIG_NAMES
 } from "./chunk-NB7GJE4S.js";
@@ -917,4 +917,4 @@ export {
   writeShutdownMarker,
   runUninit
 };
-//# sourceMappingURL=chunk-YLY7AGLC.js.map
+//# sourceMappingURL=chunk-3PJP5Y3U.js.map

package/dist/{chunk-Q42BY5BA.js → chunk-H57MQGNU.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-DQ25VOKK.js";
 import {
   GLASSTRACE_ATTRIBUTE_NAMES
-} from "./chunk-4WI7B5FQ.js";
+} from "./chunk-P45NZR4J.js";
 
 // src/errors.ts
 var SdkError = class extends Error {
@@ -102,4 +102,4 @@ export {
   GlasstraceSpanProcessor,
   captureCorrelationId
 };
-//# sourceMappingURL=chunk-Q42BY5BA.js.map
+//# sourceMappingURL=chunk-H57MQGNU.js.map

package/dist/{chunk-TANUWTFO.js → chunk-M2TLX6NM.js}

@@ -2,12 +2,12 @@ import {
   atomicWriteFile,
   refreshGenericMcpConfigAtRuntime,
   resolveEffectiveMcpCredential
-} from "./chunk-MFYOQOD7.js";
+} from "./chunk-WL6BXEJ5.js";
 import {
   DEFAULT_CAPTURE_CONFIG,
   SdkCachedConfigSchema,
   SdkInitResponseSchema
-} from "./chunk-4WI7B5FQ.js";
+} from "./chunk-P45NZR4J.js";
 import {
   __require
 } from "./chunk-NSBPE2FW.js";
@@ -692,4 +692,4 @@ export {
   didLastInitSucceed,
   verifyInitReachable
 };
-//# sourceMappingURL=chunk-TANUWTFO.js.map
+//# sourceMappingURL=chunk-M2TLX6NM.js.map

package/dist/{chunk-MMKFFF2L.js → chunk-NN5YCETI.js}

@@ -1,6 +1,6 @@
 import {
   createBuildHash
-} from "./chunk-4WI7B5FQ.js";
+} from "./chunk-P45NZR4J.js";
 
 // src/import-graph.ts
 import * as fs from "node:fs/promises";
@@ -175,4 +175,4 @@ export {
   extractImports,
   buildImportGraph
 };
-//# sourceMappingURL=chunk-MMKFFF2L.js.map
+//# sourceMappingURL=chunk-NN5YCETI.js.map

package/dist/{chunk-4WI7B5FQ.js → chunk-P45NZR4J.js}

@@ -13850,6 +13850,26 @@ var GLASSTRACE_ATTRIBUTE_NAMES = {
   ERROR_CODE: "glasstrace.error.code",
   ERROR_CATEGORY: "glasstrace.error.category",
   ERROR_FIELD: "glasstrace.error.field",
+  // Error evidence v1 (SDK-041 / DISC-1535).
+  // Additive to the existing `glasstrace.error.*` family. Bounded
+  // stacktrace input for the product-side StackSummary parser
+  // (SCHEMA-033); plus framework-fallback markers so the original
+  // request path is preserved when Next.js (or another framework)
+  // rewrites the route to a fallback like `/_error` or `/_not-found`;
+  // plus a source-provenance enum so product can tell which surface
+  // emitted each error fact (`exception.message` event vs span attr
+  // vs response body vs framework runtime).
+  //
+  // Wire keys remain in `glasstrace.error.*` for namespace consistency
+  // with the Tier-1 `error.message` / `error.code` / `error.category`
+  // attributes already in this registry.
+  ERROR_STACK: "glasstrace.error.stack",
+  ERROR_STACK_TRUNCATED: "glasstrace.error.stack.truncated",
+  ERROR_STACK_REDACTED: "glasstrace.error.stack.redacted",
+  ERROR_SOURCE: "glasstrace.error.source",
+  ERROR_FRAMEWORK_KIND: "glasstrace.error.framework.kind",
+  ERROR_ORIGINAL_PATH: "glasstrace.error.original_path",
+  ERROR_FALLBACK_ROUTE: "glasstrace.error.fallback_route",
   ORM_PROVIDER: "glasstrace.orm.provider",
   ORM_MODEL: "glasstrace.orm.model",
   ORM_OPERATION: "glasstrace.orm.operation",
@@ -14238,4 +14258,4 @@ export {
   SIDE_EFFECT_OPERATION_STATUSES,
   SIDE_EFFECT_OPERATION_PHASES
 };
-//# sourceMappingURL=chunk-4WI7B5FQ.js.map
+//# sourceMappingURL=chunk-P45NZR4J.js.map