lael-labs/executor

apps/cloud/src/observability/index.ts+29−11

 import type * as Tracer from "effect/Tracer";
 import { ErrorCapture } from "@executor-js/api";
-import { stableGroupingFingerprint, type GroupingEvent } from "@executor-js/sdk/sentry-grouping";
+import { withStableGroupingFingerprint } from "@executor-js/sdk/sentry-grouping";
 // Drizzle/postgres-js include the failing SQL (params + bound values) in
 // their error message. For OpenAPI source inserts that's 1MB+ of spec
 };
 /**
+ * The single `beforeSend` the worker and its Durable Objects install.
+ *
  * The worker ships as content-hashed chunks and its frames are not resolved
  * back to source, so Sentry's default grouping keys on names like
  * `execution-rate-limit-<hash>` and re-opens every issue on the next deploy.
- * Pin a fingerprint with the hash normalized out; events with no hashed
+ * `withStableGroupingFingerprint` pins a key with the hash normalized out;
- * grouping input are left on the default algorithm.
+ * events with no hashed grouping input are left on the default algorithm.
- */
-export const withStableGroupingFingerprint = <T extends GroupingEvent>(event: T): T => {
-  const fingerprint = stableGroupingFingerprint(event);
-  return fingerprint ? { ...event, fingerprint: [...fingerprint] } : event;
-};
-/**
- * The single `beforeSend` the worker and its Durable Objects install.
  *
  * The two stages are independent and compose in this order: the capture-owner
  * pass decides WHETHER the event is reported at all (a cause the Durable
   return reported === null ? null : withStableGroupingFingerprint(reported);
 };
+/**
+ * The Sentry options the worker and every Durable Object install. It lives
+ * beside the `beforeSend` it wires so the composition is covered by
+ * observability.test.ts; `server.ts` only passes this through.
+ *
+ * NOTE: do NOT enable `instrumentPrototypeMethods`. It walks the DO prototype
+ * and reads every property — including accessors — to find methods to wrap,
+ * which invokes the `sessionId` getter with `this` bound to the prototype
+ * (where `ctx` is undefined) and throws during construction, 500ing every
+ * session create / cold restore. The DO captures its own errors via the
+ * `captureCause` seam (→ Sentry) instead.
+ */
+export const cloudSentryOptions = (env: Env) => ({
+  dsn: env.SENTRY_DSN,
+  tracesSampleRate: 0,
+  enableLogs: true,
+  sendDefaultPii: true,
+  skipOpenTelemetrySetup: true,
+  beforeSend: (event: ErrorEvent) =>
+    beforeSendCloudEvent(event, {
+      logPayload: !env.SENTRY_DSN || env.SENTRY_OTEL_LOG_PAYLOAD === "true",
+    }),
+});
 export const addCurrentOtelCorrelationTags = <
   T extends { readonly tags?: Record<string, unknown> },
 >(

apps/cloud/src/observability/observability.test.ts+20−2

   addCurrentOtelCorrelationTags,
   beforeSendCloudEvent,
   beforeSendWithOtelCorrelation,
+  cloudSentryOptions,
   DO_CAUSE_OWNER_TAG,
   DO_CAUSE_OWNER_VALUE,
   OTEL_SPAN_ID_TAG,
 });
 // Grouping keys are decided inside the Sentry SDK and never appear on any
-// product surface, so the e2e harness cannot observe them; the running
+// product surface, so the e2e harness cannot observe them. The split is:
-// beforeSend itself is covered by e2e/cloud/sentry-otel-correlation.test.ts.
+// e2e/cloud/sentry-otel-correlation.test.ts proves the worker really installs
+// `cloudSentryOptions.beforeSend` (its correlation payload only exists if that
+// hook ran), and the tests here prove the hook it installs fingerprints.
 describe("Sentry grouping", () => {
   // The worker bundle ships as content-hashed chunks, so the only module name
   // Sentry ever sees for a given frame changes on every deploy.
     expect(sent).not.toBeNull();
     expect(sent?.fingerprint).toBeUndefined();
   });
+  // The wiring check: this is the exact object handed to `Sentry.withSentry`
+  // and `instrumentDurableObjectWithSentry` in server.ts. If the normalizer is
+  // ever dropped from the hook the worker installs, this fails.
+  it("the options the worker and DOs install carry the fingerprinting hook", () => {
+    const options = cloudSentryOptions({ SENTRY_DSN: "https://public@example.invalid/1" } as Env);
+    const sent = options.beforeSend(workerEvent("BAuwphPA"));
+    expect(sent?.fingerprint).toEqual([
+      "GateCheckTimeoutError",
+      "timeoutOrElse@execution-rate-limit",
+    ]);
+    // Same source, next deploy, new chunk hash — one issue, not two.
+    expect(options.beforeSend(workerEvent("DkcPBbWe"))?.fingerprint).toEqual(sent?.fingerprint);
+  });
 });
 describe("Sentry OTel correlation", () => {

apps/cloud/src/server.ts+3−26

 import { DurableObject } from "cloudflare:workers";
 import { SpanKind, SpanStatusCode, context, trace, type SpanContext } from "@opentelemetry/api";
-import type { ErrorEvent } from "@sentry/cloudflare";
 import {
   ATTR_HTTP_REQUEST_METHOD,
   ATTR_HTTP_RESPONSE_STATUS_CODE,
 import { parseTraceparent } from "./mcp/traceparent";
 import { McpSessionDOSqlite as McpSessionDOBase } from "./mcp/session-durable-object";
 import {
-  beforeSendCloudEvent,
+  cloudSentryOptions,
   captureCause,
   otelCorrelationContextFromOpenTelemetrySpan,
   SENTRY_EVENT_ID_ATTRIBUTE,
 import { browserTracesResponse } from "./observability/browser-traces";
 import { flushTracerProvider, installTracerProvider } from "./observability/telemetry";
-// ---------------------------------------------------------------------------
-// Sentry config
-// ---------------------------------------------------------------------------
-const sentryOptions = (env: Env) => ({
-  dsn: env.SENTRY_DSN,
-  tracesSampleRate: 0,
-  enableLogs: true,
-  sendDefaultPii: true,
-  skipOpenTelemetrySetup: true,
-  beforeSend: (event: ErrorEvent) =>
-    beforeSendCloudEvent(event, {
-      logPayload: !env.SENTRY_DSN || env.SENTRY_OTEL_LOG_PAYLOAD === "true",
-    }),
-  // NOTE: do NOT enable `instrumentPrototypeMethods`. It walks the DO prototype
-  // and reads every property — including accessors — to find methods to wrap,
-  // which invokes the `sessionId` getter with `this` bound to the prototype
-  // (where `ctx` is undefined) and throws during construction, 500ing every
-  // session create / cold restore. The DO captures its own errors via the
-  // `captureCause` seam (→ Sentry) instead.
-});
 // ---------------------------------------------------------------------------
 // Durable Object — wrapped with Sentry so DO errors land in Sentry (inits the
 // client inside the DO isolate, which plain `Sentry.captureException` cannot
 // ---------------------------------------------------------------------------
 export const McpSessionDOSqlite = Sentry.instrumentDurableObjectWithSentry(
-  sentryOptions,
+  cloudSentryOptions,
   McpSessionDOBase,
 );
   },
 };
-export default Sentry.withSentry(sentryOptions, cloudflareHandler);
+export default Sentry.withSentry(cloudSentryOptions, cloudflareHandler);

apps/desktop/src/main/crash-fingerprint.test.ts+25−2

@@ -1,11 +1,19 @@
1	import { expect, test } from "@effect/vitest";	1	import { expect, test } from "@effect/vitest";
2		2
3	import { crashReportFingerprint, type CrashEvent } from "./crash-fingerprint";	3	import {
		4	crashReportFingerprint,
		5	withCrashReportFingerprint,
		6	type CrashEvent,
		7	} from "./crash-fingerprint";
		8
		9	/** A crash event as Sentry hands it to `beforeSend` — with the grouping key
		10	* slot the hook is allowed to fill. */
		11	type SentCrashEvent = CrashEvent & { readonly fingerprint?: readonly string[] \| undefined };
4		12
5	// Chromium's soft-assert path (`NOTREACHED()`/`DCHECK`) dumps and keeps	13	// Chromium's soft-assert path (`NOTREACHED()`/`DCHECK`) dumps and keeps
6	// running. Sentry titles each one with the faulting load address, so one	14	// running. Sentry titles each one with the faulting load address, so one
7	// condition arrives as a new issue every time the address moves.	15	// condition arrives as a new issue every time the address moves.
8	const softAssertEvent = (address: string): CrashEvent => ({	16	const softAssertEvent = (address: string): SentCrashEvent => ({
9	exception: {	17	exception: {
10	values: [	18	values: [
11	{	19	{
@@ -86,6 +94,21 @@ test("renderer chunk hashes are normalized out of the fingerprint", () => { · 74 unmodified lines
86	expect(release1).toEqual(release2);	94	expect(release1).toEqual(release2);
87	});	95	});
88		96
		97	// `withCrashReportFingerprint` is the function object diagnostics.ts installs
		98	// as its `beforeSend`, so these assertions cover the main-process wiring and
		99	// not just the classifier behind it.
		100	test("the main-process beforeSend pins the key and forwards the event", () => {
		101	const collapsed = withCrashReportFingerprint(softAssertEvent("0x00000001a2b3c4d5"));
		102	expect(collapsed.fingerprint).toEqual(["chromium-dump-without-crashing"]);
		103	// Nothing else about the event is touched — this is grouping only.
		104	expect(collapsed.exception?.values?.[0]?.value).toBe("Simulated Exception / 0x00000001a2b3c4d5");
		105
		106	const untouched: SentCrashEvent = {
		107	exception: { values: [{ type: "EXC_CRASH", stacktrace: { frames: [{ function: "abort" }] } }] },
		108	};
		109	expect(withCrashReportFingerprint(untouched)).toBe(untouched);
		110	});
		111
89	test("events with no volatile grouping input are left alone", () => {	112	test("events with no volatile grouping input are left alone", () => {
90	expect(crashReportFingerprint({})).toBeUndefined();	113	expect(crashReportFingerprint({})).toBeUndefined();
91	expect(	114	expect(

apps/desktop/src/main/crash-fingerprint.ts+13−0

@@ -16,6 +16,7 @@ · 15 unmodified lines
16		16
17	import {	17	import {
18	stableGroupingFingerprint,	18	stableGroupingFingerprint,
		19	withStableGroupingFingerprint,
19	type GroupingEvent,	20	type GroupingEvent,
20	type GroupingFrame,	21	type GroupingFrame,
21	} from "@executor-js/sdk/sentry-grouping";	22	} from "@executor-js/sdk/sentry-grouping";
@@ -37,3 +38,15 @@ export const crashReportFingerprint = (event: CrashEvent): readonly string[] \| u · 15 unmodified lines
37	if (frames.some(isSoftAssertFrame)) return [CHROMIUM_SOFT_ASSERT_FINGERPRINT];	38	if (frames.some(isSoftAssertFrame)) return [CHROMIUM_SOFT_ASSERT_FINGERPRINT];
38	return stableGroupingFingerprint(event);	39	return stableGroupingFingerprint(event);
39	};	40	};
		41
		42	/**
		43	* The `beforeSend` the Electron main process installs. Grouping only — an
		44	* event with no volatile grouping input is forwarded unchanged.
		45	*/
		46	export const withCrashReportFingerprint = <T extends CrashEvent>(event: T): T => {
		47	const frames = (event.exception?.values ?? []).flatMap((value) => value.stacktrace?.frames ?? []);
		48	if (frames.some(isSoftAssertFrame)) {
		49	return { ...event, fingerprint: [CHROMIUM_SOFT_ASSERT_FINGERPRINT] };
		50	}
		51	return withStableGroupingFingerprint(event);
		52	};

apps/desktop/src/main/diagnostics.ts+2−5

 import { app, crashReporter, dialog, shell } from "electron";
 import log from "electron-log/main.js";
 import * as Sentry from "@sentry/electron/main";
-import { crashReportFingerprint } from "./crash-fingerprint";
+import { withCrashReportFingerprint } from "./crash-fingerprint";
 import { getServerSettings } from "./settings";
 const sentryDsn = __EXECUTOR_SENTRY_DSN__;
         },
       },
       // Grouping only — the event is forwarded untouched otherwise.
-      beforeSend: (event) => {
+      beforeSend: withCrashReportFingerprint,
-        const fingerprint = crashReportFingerprint(event);
-        return fingerprint ? { ...event, fingerprint: [...fingerprint] } : event;
-      },
     });
   } else {
     // No DSN baked in — keep native crash dumps local so a user-reported

packages/app/src/crash-reporting.ts+2−5

  * once initialized — no reporter rewiring needed.
  */
-import { stableGroupingFingerprint } from "@executor-js/sdk/sentry-grouping";
+import { withStableGroupingFingerprint } from "@executor-js/sdk/sentry-grouping";
 interface CrashReportingConfig {
   readonly dsn: string;
         // `atoms-<hash>` and one bug re-groups on every release. Pin a
         // fingerprint with the hash normalized out; the event itself keeps its
         // hashed filenames so sourcemap resolution is unaffected.
-        beforeSend: (event) => {
+        beforeSend: withStableGroupingFingerprint,
-          const fingerprint = stableGroupingFingerprint(event);
-          return fingerprint ? { ...event, fingerprint: [...fingerprint] } : event;
-        },
       });
     } catch {
       // Reporting failures stay silent — there is nowhere left to report them.

packages/core/sdk/src/sentry-grouping.test.ts+87−19

@@ -4,6 +4,7 @@ import { · 3 unmodified lines
4	containsContentHash,	4	containsContentHash,
5	stableGroupingFingerprint,	5	stableGroupingFingerprint,
6	stripContentHashes,	6	stripContentHashes,
		7	withStableGroupingFingerprint,
7	type GroupingEvent,	8	type GroupingEvent,
8	} from "./sentry-grouping";	9	} from "./sentry-grouping";
9		10
@@ -65,6 +66,30 @@ test("stripContentHashes keeps genuinely different modules distinct", () => { · 55 unmodified lines
65	);	66	);
66	});	67	});
67		68
		69	// Merging two unrelated bugs into one issue is unrecoverable, so the "is this
		70	// a hash?" threshold is pinned from both sides: a segment needs two of the
		71	// three hash signals (uppercase, uppercase+digit, digits) before it is eaten.
		72	// Loosening it to one signal — the tempting fix for the word-shaped hashes
		73	// this deliberately misses — silently collapses real chunk names.
		74	test("a name segment one signal short of a hash is left in place", () => {
		75	// One capital, no digits.
		76	expect(stripContentHashes("/assets/connections-Settings.js")).toBe(
		77	"/assets/connections-Settings.js",
		78	);
		79	// One digit, no capitals.
		80	expect(stripContentHashes("/assets/storage-s3client.js")).toBe("/assets/storage-s3client.js");
		81	// ...and neither may be mistaken for the chunk it would collapse onto.
		82	expect(stripContentHashes("/assets/connections-Settings.js")).not.toBe(
		83	stripContentHashes("/assets/connections-BAuwphPA.js"),
		84	);
		85	});
		86
		87	test("a segment with two hash signals is eaten", () => {
		88	expect(stripContentHashes("/assets/chunk-AbcdefgH.js")).toBe("/assets/chunk.js");
		89	expect(stripContentHashes("/assets/chunk-Abcdefg1.js")).toBe("/assets/chunk.js");
		90	expect(stripContentHashes("/assets/chunk-abcdef12.js")).toBe("/assets/chunk.js");
		91	});
		92
68	test("containsContentHash detects only hashed paths", () => {	93	test("containsContentHash detects only hashed paths", () => {
69	expect(containsContentHash("/assets/atoms-Yemn7yhP.js")).toBe(true);	94	expect(containsContentHash("/assets/atoms-Yemn7yhP.js")).toBe(true);
70	expect(containsContentHash("apps/cloud/src/engine/execution-gate.ts")).toBe(false);	95	expect(containsContentHash("apps/cloud/src/engine/execution-gate.ts")).toBe(false);
@@ -126,27 +151,41 @@ test("minified single-letter frame functions are left out of the fingerprint", ( · 55 unmodified lines
126	expect(stableGroupingFingerprint(atoms("U", "Yemn7yhP"))).toEqual(["TypeError", "atoms"]);	151	expect(stableGroupingFingerprint(atoms("U", "Yemn7yhP"))).toEqual(["TypeError", "atoms"]);
127	});	152	});
128		153
129	test("two vendor chunks sharing a name stay apart on their callers", () => {	154	// A single build emits many `dist-<hash>.js` chunks from unrelated packages,
130	// A single build emits many `dist-<hash>.js` chunks from unrelated packages,	155	// so the crashing frame alone is not a safe key — two different bugs would
131	// so the top frame alone is not a safe key.	156	// land in one issue. Frames are oldest-first, so the shared chunk is last.
132	const vendorEvent = (caller: string, hash: string): GroupingEvent => ({	157	const vendorEvent = (caller: string, hash: string): GroupingEvent => ({
133	exception: {	158	exception: {
134	values: [	159	values: [
135	{	160	{
136	type: "TypeError",	161	type: "TypeError",
137	stacktrace: {	162	stacktrace: {
138	frames: [	163	frames: [
139	{ module: `${caller}-${hash}`, function: caller, in_app: true },	164	{ module: `${caller}-${hash}`, function: caller, in_app: true },
140	{ module: `dist-${hash}`, function: "x", in_app: false },	165	{ module: `dist-${hash}`, function: "throwHelper", in_app: true },
141	],	166	],
142	},
143	},	167	},
144	],	168	},
145	},	169	],
146	});	170	},
		171	});
		172
		173	test("two vendor chunks sharing a name stay apart on their callers", () => {
		174	const upload = stableGroupingFingerprint(vendorEvent("uploadArtifact", "BQZkXWT2"));
		175	const render = stableGroupingFingerprint(vendorEvent("renderMarkdown", "BQZkXWT2"));
147		176
148	expect(stableGroupingFingerprint(vendorEvent("uploadArtifact", "BQZkXWT2"))).not.toEqual(	177	// The crashing frame is identical in both — only the caller chain separates
149	stableGroupingFingerprint(vendorEvent("renderMarkdown", "BQZkXWT2")),	178	// them, so a fingerprint built from the top frame alone would over-merge.
		179	expect(upload?.slice(0, 2)).toEqual(["TypeError", "throwHelper@dist"]);
		180	expect(render?.slice(0, 2)).toEqual(upload?.slice(0, 2));
		181	expect(upload).not.toEqual(render);
		182	expect(upload).toEqual(["TypeError", "throwHelper@dist", "uploadArtifact@uploadArtifact"]);
		183	});
		184
		185	test("the caller chain is itself deploy-stable", () => {
		186	// Every frame in the chain must lose its hash, not just the crashing one.
		187	expect(stableGroupingFingerprint(vendorEvent("uploadArtifact", "BQZkXWT2"))).toEqual(
		188	stableGroupingFingerprint(vendorEvent("uploadArtifact", "Yemn7yhP")),
150	);	189	);
151	});	190	});
152		191
@@ -186,6 +225,35 @@ test("a hashed culprit alone is enough to pin the fingerprint", () => { · 33 unmodified lines
186	]);	225	]);
187	});	226	});
188		227
		228	// The wrapper every process installs as its `beforeSend`. `fingerprint` and
		229	// `tags` stand in for the fields a real Sentry event carries around it.
		230	type SentEvent = GroupingEvent & {
		231	readonly fingerprint?: readonly string[] \| undefined;
		232	readonly tags?: Record<string, string> \| undefined;
		233	};
		234
		235	test("withStableGroupingFingerprint pins the key and changes nothing else", () => {
		236	const input: SentEvent = { ...workerEvent("BAuwphPA"), tags: { a: "b" } };
		237	const hashed = withStableGroupingFingerprint(input);
		238	expect(hashed.fingerprint).toEqual([
		239	"GateCheckTimeoutError",
		240	"timeoutOrElse@execution-rate-limit",
		241	]);
		242	// The event still carries its hashed filename, or server-side sourcemap
		243	// resolution would stop finding the release's artifacts.
		244	expect(hashed.exception?.values?.[0]?.stacktrace?.frames?.[0]?.filename).toBe(
		245	"/assets/execution-rate-limit-BAuwphPA.js",
		246	);
		247	expect(hashed.tags).toEqual({ a: "b" });
		248	});
		249
		250	test("withStableGroupingFingerprint forwards an unhashed event untouched", () => {
		251	const plain: SentEvent = { culprit: "checkExecutionBalance(execution-gate.ts)" };
		252	const out = withStableGroupingFingerprint(plain);
		253	expect(out).toBe(plain);
		254	expect("fingerprint" in out).toBe(false);
		255	});
		256
189	test("the outermost exception drives the fingerprint", () => {	257	test("the outermost exception drives the fingerprint", () => {
190	// Sentry orders `values` innermost-first; the last entry is the one whose	258	// Sentry orders `values` innermost-first; the last entry is the one whose
191	// type the issue is titled with.	259	// type the issue is titled with.

packages/core/sdk/src/sentry-grouping.ts+12−0

@@ -155,3 +155,15 @@ export const stableGroupingFingerprint = (event: GroupingEvent): readonly string · 154 unmodified lines
155	if (keys.length > 0) return [type, ...keys];	155	if (keys.length > 0) return [type, ...keys];
156	return culprit ? [type, stripContentHashes(culprit)] : undefined;	156	return culprit ? [type, stripContentHashes(culprit)] : undefined;
157	};	157	};
		158
		159	/**
		160	* The whole `beforeSend` contract: pin the deploy-stable fingerprint when the
		161	* event has a volatile grouping input, and forward the event untouched when it
		162	* does not. Every call site (cloud worker/DO, desktop main, desktop renderer)
		163	* installs this one symbol rather than its own copy, so the wiring is covered
		164	* by the tests below instead of being retyped per process.
		165	*/
		166	export const withStableGroupingFingerprint = <T extends GroupingEvent>(event: T): T => {
		167	const fingerprint = stableGroupingFingerprint(event);
		168	return fingerprint ? { ...event, fingerprint: [...fingerprint] } : event;
		169	};