feat(cloudflare): Instrument Agents automatically

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/.gitignore

@@ -0,0 +1,4 @@
+dist
+.wrangler
+test-results
+pnpm-lock.yaml

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/package.json

@@ -0,0 +1,38 @@
+{
+ "name": "cloudflare-autoinstrument",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "dev": "vite dev",
+ "build": "vite build",
+ "preview": "wrangler dev --var \"E2E_TEST_DSN:$E2E_TEST_DSN\" --log-level=$(test $CI && echo 'none' || echo 'log')",
+ "test": "playwright test",
+ "typecheck": "tsc --noEmit",
+ "test:build": "pnpm install && pnpm build",
+ "test:assert": "pnpm typecheck && pnpm test"
+ },
+ "dependencies": {
+ "@cloudflare/ai-chat": "^0.10.0",
+ "@sentry/cloudflare": "file:../../packed/sentry-cloudflare-packed.tgz",
+ "agents": "^0.20.0"
+ },
+ "devDependencies": {
+ "@babel/core": "^8.0.1",
+ "@babel/plugin-proposal-decorators": "^8.0.2",
+ "@cloudflare/vite-plugin": "^1.47.0",
+ "@cloudflare/workers-types": "^5.20260727.1",
+ "@playwright/test": "~1.56.0",
+ "@sentry-internal/test-utils": "link:../../../test-utils",
+ "@types/node": "^26.1.2",
+ "@types/ws": "^8.18.1",
+ "typescript": "~6.0.3",
+ "vite": "^8.1.5",
+ "wrangler": "^4.114.0",
+ "ws": "^8.21.1"
+ },
+ "volta": {
+ "node": "24.15.0",
+ "extends": "../../package.json"
+ }
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/playwright.config.ts

@@ -0,0 +1,16 @@
+import { getPlaywrightConfig } from '@sentry-internal/test-utils';
+
+// `vite build` runs the Sentry auto-instrument transform over the worker entry;
+// `pnpm preview` (`wrangler dev`, following the vite plugin's `.wrangler/deploy`
+// redirect) serves the built output. The tests therefore assert on the wrapping
+// the plugin injected at build time, not on anything in the source entry.
+export default getPlaywrightConfig(
+ {
+ startCommand: 'pnpm preview',
+ port: 8787,
+ },
+ {
+ workers: '100%',
+ retries: 0,
+ },
+);

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/base.ts

@@ -0,0 +1,12 @@
+import { Agent } from 'agents';
+
+/**
+ * An Agent base class living outside the worker entry. `DerivedAgent` in
+ * `index.ts` extends this, so the plugin only learns it is an Agent by
+ * following the import into this module and resolving `MyBase -> Agent`.
+ */
+export class MyBase extends Agent<Env> {
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'derived' });
+ }
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/env.d.ts

@@ -0,0 +1,7 @@
+interfaceEnv{
+E2E_TEST_DSN: string;
+MyAgent: DurableObjectNamespace;
+MyChatAgent: DurableObjectNamespace;
+DerivedAgent: DurableObjectNamespace;
+PlainDO: DurableObjectNamespace;
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/index.ts

@@ -0,0 +1,73 @@
+import { AIChatAgent } from '@cloudflare/ai-chat';
+import { Agent, callable, routeAgentRequest } from 'agents';
+import { DurableObject } from 'cloudflare:workers';
+import { MyBase } from './base';
+
+// NOTE: this file deliberately contains NO `Sentry.*` calls and no import of
+// `@sentry/cloudflare`. Everything below is wrapped at build time by
+// `sentryCloudflareVitePlugin({ _experimental: { autoInstrumentation: true } })`,
+// which reads wrangler.jsonc, wraps the default export with `withSentry`, and
+// picks a wrapper per class: `instrumentAgentWithSentry` for the three Agents,
+// `instrumentDurableObjectWithSentry` for the plain Durable Object.
+//
+// Options come from `instrument.server.ts` next to this entry.
+
+/** Agent whose base class (`Agent`) is imported directly into the entry. */
+export class MyAgent extends Agent<Env> {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from MyAgent)`;
+ }
+
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'plain' });
+ }
+}
+
+/** Chat agent — `AIChatAgent` extends `Agent` inside `@cloudflare/ai-chat`. */
+export class MyChatAgent extends AIChatAgent<Env> {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from MyChatAgent)`;
+ }
+
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'chat' });
+ }
+}
+
+/** Agent whose base class lives in `./base` — resolvable only across modules. */
+export class DerivedAgent extends MyBase {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from DerivedAgent)`;
+ }
+}
+
+/**
+ * A genuine Durable Object. Configured identically to the Agents above, so it
+ * proves detection discriminates rather than upgrading every DO binding.
+ */
+export class PlainDO extends DurableObject<Env> {
+ async fetch(): Promise<Response> {
+ return Response.json({ durableObject: true });
+ }
+}
+
+export default {
+ async fetch(request: Request, env: Env): Promise<Response> {
+ const url = new URL(request.url);
+
+ if (url.pathname === '/plain-do') {
+ const stub = env.PlainDO.get(env.PlainDO.idFromName('do-instance'));
+ return stub.fetch(request);
+ }
+
+ const agentResponse = await routeAgentRequest(request, env);
+ if (agentResponse) {
+ return agentResponse;
+ }
+
+ return new Response('Not found', { status: 404 });
+ },
+} satisfies ExportedHandler<Env>;

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/instrument.server.ts

@@ -0,0 +1,14 @@
+// The auto-instrument plugin picks this file up by convention (it sits next to
+// the worker entry named in wrangler's `main`) and imports its default export as
+// the options callback for every wrapper it injects.
+export default (env: Env) => ({
+ traceLifecycle: 'static' as const,
+ dsn: env.E2E_TEST_DSN,
+ environment: 'qa',
+ tunnel: 'http://localhost:3031/',
+ tracesSampleRate: 1.0,
+ enableRpcTracePropagation: true,
+ transportOptions: {
+ bufferSize: 1000,
+ },
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/start-event-proxy.mjs

@@ -0,0 +1,6 @@
+import{startEventProxyServer}from'@sentry-internal/test-utils';
+
+startEventProxyServer({
+port: 3031,
+proxyServerName: 'cloudflare-autoinstrument',
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tests/agent-socket.ts

@@ -0,0 +1,46 @@
+import WebSocket from 'ws';
+
+type AgentReply = { type?: string; id?: string; done?: boolean; result?: unknown };
+
+/**
+ * Opens a WebSocket to `/agents/<binding>/<instance>`, sends one RPC frame, and
+ * resolves with the reply's `result` — the method's return value — once it arrives.
+ */
+export function callRpc(
+ baseURL: string,
+ options: { binding: string; instance: string; method: string; args: unknown[] },
+): Promise<unknown> {
+ const id = `rpc-${options.method}`;
+ const frame = { type: 'rpc', id, method: options.method, args: options.args };
+ const wsUrl = `${baseURL.replace(/^http/, 'ws')}/agents/${options.binding}/${options.instance}`;
+
+ return new Promise<unknown>((resolveSocket, rejectSocket) => {
+ const socket = new WebSocket(wsUrl);
+ const timeout = setTimeout(() => {
+ socket.close();
+ rejectSocket(new Error(`Timed out waiting for RPC reply to "${options.method}"`));
+ }, 15_000);
+
+ socket.on('open', () => {
+ socket.send(JSON.stringify(frame));
+ });
+
+ socket.on('message', data => {
+ try {
+ const parsed = JSON.parse(data.toString()) as AgentReply;
+ if (parsed.type === 'rpc' && parsed.id === id && parsed.done) {
+ clearTimeout(timeout);
+ socket.close();
+ resolveSocket(parsed.result);
+ }
+ } catch {
+ // Ignore non-JSON / unrelated frames.
+ }
+ });
+
+ socket.on('error', err => {
+ clearTimeout(timeout);
+ rejectSocket(err);
+ });
+ });
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tests/autoinstrument.test.ts

@@ -0,0 +1,99 @@
+import { expect, test } from '@playwright/test';
+import { waitForTransaction } from '@sentry-internal/test-utils';
+import { callRpc } from './agent-socket';
+
+// The worker entry (`src/index.ts`) contains no Sentry calls at all — every
+// wrapper below was injected by the Vite auto-instrument plugin at build time.
+// Any transaction arriving here therefore proves the injection happened.
+
+test('wraps the default export with withSentry (options from instrument.server.ts)', async ({ baseURL }) => {
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return event.contexts?.trace?.op === 'http.server' && (event.request?.url ?? '').includes('/plain-do');
+ });
+
+ const res = await fetch(`${baseURL}/plain-do`);
+ expect(res.status).toBe(200);
+ await expect(res.json()).resolves.toEqual({ durableObject: true });
+
+ const transaction = await transactionPromise;
+
+ expect(transaction.contexts?.trace?.origin).toBe('auto.http.cloudflare');
+ // `environment: 'qa'` is only set in `instrument.server.ts`, so seeing it here
+ // proves the plugin sourced its options callback from that file rather than
+ // falling back to reading configuration off `env`.
+ expect(transaction.environment).toBe('qa');
+});
+
+// Each of these three classes is registered in wrangler.jsonc exactly like the
+// plain Durable Object below — only the base-class chain marks them as Agents.
+// An `rpc` span with origin `auto.faas.cloudflare.agents` is produced solely by
+// `instrumentAgentWithSentry`, so its presence is what distinguishes a correct
+// agent upgrade from a plain `instrumentDurableObjectWithSentry` wrap.
+for (const { title, binding, agentClass } of [
+ {
+ title: 'an Agent subclass declared in the entry',
+ binding: 'my-agent',
+ agentClass: 'MyAgent',
+ },
+ {
+ title: 'an AIChatAgent subclass declared in the entry',
+ binding: 'my-chat-agent',
+ agentClass: 'MyChatAgent',
+ },
+ {
+ title: 'an Agent subclass whose base class lives in another module',
+ binding: 'derived-agent',
+ agentClass: 'DerivedAgent',
+ },
+]) {
+ test(`applies agent instrumentation to ${title}`, async ({ baseURL }) => {
+ const instance = `${binding}-instance`;
+
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return (
+ event.transaction === 'webSocketMessage' &&
+ (event.spans ?? []).some(span => span.op === 'rpc' && span.description === 'greet')
+ );
+ });
+
+ // Each agent's greet() returns a string naming its class, so the reply
+ // identifies exactly which class handled the call.
+ const reply = await callRpc(baseURL!, { binding, instance, method: 'greet', args: ['World'] });
+ expect(reply).toBe(`Hello, World! (from ${agentClass})`);
+
+ const transaction = await transactionPromise;
+ const rpcSpan = (transaction.spans ?? []).find(span => span.op === 'rpc' && span.description === 'greet');
+
+ expect(rpcSpan).toEqual(
+ expect.objectContaining({
+ op: 'rpc',
+ description: 'greet',
+ origin: 'auto.faas.cloudflare.agents',
+ data: expect.objectContaining({
+ // Read back off the instance at runtime (`_ParentClass.name`), so it
+ // confirms the wrapper landed on the user's real class. Matched loosely
+ // because the transform renames the class it wraps to
+ // `__SENTRY_ORIGINAL_<name>__` and the bundler infers that name.
+ 'cloudflare.agent.class': expect.stringContaining(agentClass),
+ 'cloudflare.agent.name': instance,
+ }),
+ }),
+ );
+ });
+}
+
+test('applies plain Durable Object instrumentation to a non-Agent class', async ({ baseURL }) => {
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return event.contexts?.trace?.op === 'http.server' && (event.request?.url ?? '').includes('/plain-do');
+ });
+
+ const res = await fetch(`${baseURL}/plain-do`);
+ expect(res.status).toBe(200);
+
+ const transaction = await transactionPromise;
+
+ // A plain Durable Object must NOT pick up agent instrumentation: detection has
+ // to discriminate, not blanket-upgrade every `durable_objects` binding.
+ const agentSpans = (transaction.spans ?? []).filter(span => span.origin === 'auto.faas.cloudflare.agents');
+ expect(agentSpans).toEqual([]);
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tsconfig.json

@@ -0,0 +1,16 @@
+{
+ "compilerOptions": {
+ "target": "es2023",
+ "lib": ["es2023"],
+ "module": "es2022",
+ "moduleResolution": "bundler",
+ "types": ["@cloudflare/workers-types", "node"],
+ "skipLibCheck": true,
+ "noEmit": true,
+ "isolatedModules": true,
+ "allowSyntheticDefaultImports": true,
+ "forceConsistentCasingInFileNames": true,
+ "strict": true
+ },
+ "include": ["src/**/*", "vite.config.ts"]
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/vite.config.ts

@@ -0,0 +1,19 @@
+import { cloudflare } from '@cloudflare/vite-plugin';
+import { sentryCloudflareVitePlugin } from '@sentry/cloudflare/vite';
+import agents from 'agents/vite';
+import { defineConfig } from 'vite';
+
+// `agents()` supplies the TC39 decorator transform that `@callable()` needs.
+// `autoInstrumentation` is the plugin under test: it rewrites `src/index.ts` at
+// build time so the entry itself contains no Sentry calls.
+export default defineConfig({
+ plugins: [
+ agents(),
+ cloudflare(),
+ sentryCloudflareVitePlugin({
+ _experimental: {
+ autoInstrumentation: true,
+ },
+ }),
+ ],
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/wrangler.jsonc

@@ -0,0 +1,32 @@
+{
+"$schema": "node_modules/wrangler/config-schema.json",
+"name": "cloudflare-autoinstrument",
+"main": "src/index.ts",
+"compatibility_date": "2026-05-20",
+"compatibility_flags": ["nodejs_compat"],
+
+// Every class below is registered the same way — as a Durable Object binding.
+// An `agents` Agent *is* a Durable Object, so wrangler offers no way to say
+// "this one is an Agent". Only the base-class chain distinguishes them, which
+// is exactly what the plugin's detection has to work out at build time:
+//
+// MyAgent -> extends Agent (entry-local) => agent
+// MyChatAgent -> extends AIChatAgent (entry-local) => agent
+// DerivedAgent -> extends ./base#MyBase -> Agent => agent
+// PlainDO -> extends DurableObject => durableObject
+"durable_objects": {
+"bindings": [
+ { "name": "MyAgent", "class_name": "MyAgent" },
+ { "name": "MyChatAgent", "class_name": "MyChatAgent" },
+ { "name": "DerivedAgent", "class_name": "DerivedAgent" },
+ { "name": "PlainDO", "class_name": "PlainDO" },
+ ],
+ },
+
+"migrations": [
+ {
+"tag": "v1",
+"new_sqlite_classes": ["MyAgent", "MyChatAgent", "DerivedAgent", "PlainDO"],
+ },
+ ],
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/.gitignore

@@ -0,0 +1,4 @@
+dist
+.wrangler
+test-results
+pnpm-lock.yaml

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/package.json

@@ -0,0 +1,38 @@
+{
+ "name": "cloudflare-autoinstrument",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "dev": "vite dev",
+ "build": "vite build",
+ "preview": "wrangler dev --var \"E2E_TEST_DSN:$E2E_TEST_DSN\" --log-level=$(test $CI && echo 'none' || echo 'log')",
+ "test": "playwright test",
+ "typecheck": "tsc --noEmit",
+ "test:build": "pnpm install && pnpm build",
+ "test:assert": "pnpm typecheck && pnpm test"
+ },
+ "dependencies": {
+ "@cloudflare/ai-chat": "^0.10.0",
+ "@sentry/cloudflare": "file:../../packed/sentry-cloudflare-packed.tgz",
+ "agents": "^0.20.0"
+ },
+ "devDependencies": {
+ "@babel/core": "^8.0.1",
+ "@babel/plugin-proposal-decorators": "^8.0.2",
+ "@cloudflare/vite-plugin": "^1.47.0",
+ "@cloudflare/workers-types": "^5.20260727.1",
+ "@playwright/test": "~1.56.0",
+ "@sentry-internal/test-utils": "link:../../../test-utils",
+ "@types/node": "^26.1.2",
+ "@types/ws": "^8.18.1",
+ "typescript": "~6.0.3",
+ "vite": "^8.1.5",
+ "wrangler": "^4.114.0",
+ "ws": "^8.21.1"
+ },
+ "volta": {
+ "node": "24.15.0",
+ "extends": "../../package.json"
+ }
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/playwright.config.ts

@@ -0,0 +1,16 @@
+import { getPlaywrightConfig } from '@sentry-internal/test-utils';
+
+// `vite build` runs the Sentry auto-instrument transform over the worker entry;
+// `pnpm preview` (`wrangler dev`, following the vite plugin's `.wrangler/deploy`
+// redirect) serves the built output. The tests therefore assert on the wrapping
+// the plugin injected at build time, not on anything in the source entry.
+export default getPlaywrightConfig(
+ {
+ startCommand: 'pnpm preview',
+ port: 8787,
+ },
+ {
+ workers: '100%',
+ retries: 0,
+ },
+);

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/base.ts

@@ -0,0 +1,12 @@
+import { Agent } from 'agents';
+
+/**
+ * An Agent base class living outside the worker entry. `DerivedAgent` in
+ * `index.ts` extends this, so the plugin only learns it is an Agent by
+ * following the import into this module and resolving `MyBase -> Agent`.
+ */
+export class MyBase extends Agent<Env> {
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'derived' });
+ }
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/env.d.ts

@@ -0,0 +1,7 @@
+interfaceEnv{
+E2E_TEST_DSN: string;
+MyAgent: DurableObjectNamespace;
+MyChatAgent: DurableObjectNamespace;
+DerivedAgent: DurableObjectNamespace;
+PlainDO: DurableObjectNamespace;
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/index.ts

@@ -0,0 +1,73 @@
+import { AIChatAgent } from '@cloudflare/ai-chat';
+import { Agent, callable, routeAgentRequest } from 'agents';
+import { DurableObject } from 'cloudflare:workers';
+import { MyBase } from './base';
+
+// NOTE: this file deliberately contains NO `Sentry.*` calls and no import of
+// `@sentry/cloudflare`. Everything below is wrapped at build time by
+// `sentryCloudflareVitePlugin({ _experimental: { autoInstrumentation: true } })`,
+// which reads wrangler.jsonc, wraps the default export with `withSentry`, and
+// picks a wrapper per class: `instrumentAgentWithSentry` for the three Agents,
+// `instrumentDurableObjectWithSentry` for the plain Durable Object.
+//
+// Options come from `instrument.server.ts` next to this entry.
+
+/** Agent whose base class (`Agent`) is imported directly into the entry. */
+export class MyAgent extends Agent<Env> {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from MyAgent)`;
+ }
+
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'plain' });
+ }
+}
+
+/** Chat agent — `AIChatAgent` extends `Agent` inside `@cloudflare/ai-chat`. */
+export class MyChatAgent extends AIChatAgent<Env> {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from MyChatAgent)`;
+ }
+
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'chat' });
+ }
+}
+
+/** Agent whose base class lives in `./base` — resolvable only across modules. */
+export class DerivedAgent extends MyBase {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from DerivedAgent)`;
+ }
+}
+
+/**
+ * A genuine Durable Object. Configured identically to the Agents above, so it
+ * proves detection discriminates rather than upgrading every DO binding.
+ */
+export class PlainDO extends DurableObject<Env> {
+ async fetch(): Promise<Response> {
+ return Response.json({ durableObject: true });
+ }
+}
+
+export default {
+ async fetch(request: Request, env: Env): Promise<Response> {
+ const url = new URL(request.url);
+
+ if (url.pathname === '/plain-do') {
+ const stub = env.PlainDO.get(env.PlainDO.idFromName('do-instance'));
+ return stub.fetch(request);
+ }
+
+ const agentResponse = await routeAgentRequest(request, env);
+ if (agentResponse) {
+ return agentResponse;
+ }
+
+ return new Response('Not found', { status: 404 });
+ },
+} satisfies ExportedHandler<Env>;

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/instrument.server.ts

@@ -0,0 +1,14 @@
+// The auto-instrument plugin picks this file up by convention (it sits next to
+// the worker entry named in wrangler's `main`) and imports its default export as
+// the options callback for every wrapper it injects.
+export default (env: Env) => ({
+ traceLifecycle: 'static' as const,
+ dsn: env.E2E_TEST_DSN,
+ environment: 'qa',
+ tunnel: 'http://localhost:3031/',
+ tracesSampleRate: 1.0,
+ enableRpcTracePropagation: true,
+ transportOptions: {
+ bufferSize: 1000,
+ },
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/start-event-proxy.mjs

@@ -0,0 +1,6 @@
+import{startEventProxyServer}from'@sentry-internal/test-utils';
+
+startEventProxyServer({
+port: 3031,
+proxyServerName: 'cloudflare-autoinstrument',
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tests/agent-socket.ts

@@ -0,0 +1,46 @@
+import WebSocket from 'ws';
+
+type AgentReply = { type?: string; id?: string; done?: boolean; result?: unknown };
+
+/**
+ * Opens a WebSocket to `/agents/<binding>/<instance>`, sends one RPC frame, and
+ * resolves with the reply's `result` — the method's return value — once it arrives.
+ */
+export function callRpc(
+ baseURL: string,
+ options: { binding: string; instance: string; method: string; args: unknown[] },
+): Promise<unknown> {
+ const id = `rpc-${options.method}`;
+ const frame = { type: 'rpc', id, method: options.method, args: options.args };
+ const wsUrl = `${baseURL.replace(/^http/, 'ws')}/agents/${options.binding}/${options.instance}`;
+
+ return new Promise<unknown>((resolveSocket, rejectSocket) => {
+ const socket = new WebSocket(wsUrl);
+ const timeout = setTimeout(() => {
+ socket.close();
+ rejectSocket(new Error(`Timed out waiting for RPC reply to "${options.method}"`));
+ }, 15_000);
+
+ socket.on('open', () => {
+ socket.send(JSON.stringify(frame));
+ });
+
+ socket.on('message', data => {
+ try {
+ const parsed = JSON.parse(data.toString()) as AgentReply;
+ if (parsed.type === 'rpc' && parsed.id === id && parsed.done) {
+ clearTimeout(timeout);
+ socket.close();
+ resolveSocket(parsed.result);
+ }
+ } catch {
+ // Ignore non-JSON / unrelated frames.
+ }
+ });
+
+ socket.on('error', err => {
+ clearTimeout(timeout);
+ rejectSocket(err);
+ });
+ });
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tests/autoinstrument.test.ts

@@ -0,0 +1,99 @@
+import { expect, test } from '@playwright/test';
+import { waitForTransaction } from '@sentry-internal/test-utils';
+import { callRpc } from './agent-socket';
+
+// The worker entry (`src/index.ts`) contains no Sentry calls at all — every
+// wrapper below was injected by the Vite auto-instrument plugin at build time.
+// Any transaction arriving here therefore proves the injection happened.
+
+test('wraps the default export with withSentry (options from instrument.server.ts)', async ({ baseURL }) => {
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return event.contexts?.trace?.op === 'http.server' && (event.request?.url ?? '').includes('/plain-do');
+ });
+
+ const res = await fetch(`${baseURL}/plain-do`);
+ expect(res.status).toBe(200);
+ await expect(res.json()).resolves.toEqual({ durableObject: true });
+
+ const transaction = await transactionPromise;
+
+ expect(transaction.contexts?.trace?.origin).toBe('auto.http.cloudflare');
+ // `environment: 'qa'` is only set in `instrument.server.ts`, so seeing it here
+ // proves the plugin sourced its options callback from that file rather than
+ // falling back to reading configuration off `env`.
+ expect(transaction.environment).toBe('qa');
+});
+
+// Each of these three classes is registered in wrangler.jsonc exactly like the
+// plain Durable Object below — only the base-class chain marks them as Agents.
+// An `rpc` span with origin `auto.faas.cloudflare.agents` is produced solely by
+// `instrumentAgentWithSentry`, so its presence is what distinguishes a correct
+// agent upgrade from a plain `instrumentDurableObjectWithSentry` wrap.
+for (const { title, binding, agentClass } of [
+ {
+ title: 'an Agent subclass declared in the entry',
+ binding: 'my-agent',
+ agentClass: 'MyAgent',
+ },
+ {
+ title: 'an AIChatAgent subclass declared in the entry',
+ binding: 'my-chat-agent',
+ agentClass: 'MyChatAgent',
+ },
+ {
+ title: 'an Agent subclass whose base class lives in another module',
+ binding: 'derived-agent',
+ agentClass: 'DerivedAgent',
+ },
+]) {
+ test(`applies agent instrumentation to ${title}`, async ({ baseURL }) => {
+ const instance = `${binding}-instance`;
+
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return (
+ event.transaction === 'webSocketMessage' &&
+ (event.spans ?? []).some(span => span.op === 'rpc' && span.description === 'greet')
+ );
+ });
+
+ // Each agent's greet() returns a string naming its class, so the reply
+ // identifies exactly which class handled the call.
+ const reply = await callRpc(baseURL!, { binding, instance, method: 'greet', args: ['World'] });
+ expect(reply).toBe(`Hello, World! (from ${agentClass})`);
+
+ const transaction = await transactionPromise;
+ const rpcSpan = (transaction.spans ?? []).find(span => span.op === 'rpc' && span.description === 'greet');
+
+ expect(rpcSpan).toEqual(
+ expect.objectContaining({
+ op: 'rpc',
+ description: 'greet',
+ origin: 'auto.faas.cloudflare.agents',
+ data: expect.objectContaining({
+ // Read back off the instance at runtime (`_ParentClass.name`), so it
+ // confirms the wrapper landed on the user's real class. Matched loosely
+ // because the transform renames the class it wraps to
+ // `__SENTRY_ORIGINAL_<name>__` and the bundler infers that name.
+ 'cloudflare.agent.class': expect.stringContaining(agentClass),
+ 'cloudflare.agent.name': instance,
+ }),
+ }),
+ );
+ });
+}
+
+test('applies plain Durable Object instrumentation to a non-Agent class', async ({ baseURL }) => {
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return event.contexts?.trace?.op === 'http.server' && (event.request?.url ?? '').includes('/plain-do');
+ });
+
+ const res = await fetch(`${baseURL}/plain-do`);
+ expect(res.status).toBe(200);
+
+ const transaction = await transactionPromise;
+
+ // A plain Durable Object must NOT pick up agent instrumentation: detection has
+ // to discriminate, not blanket-upgrade every `durable_objects` binding.
+ const agentSpans = (transaction.spans ?? []).filter(span => span.origin === 'auto.faas.cloudflare.agents');
+ expect(agentSpans).toEqual([]);
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tsconfig.json

@@ -0,0 +1,16 @@
+{
+ "compilerOptions": {
+ "target": "es2023",
+ "lib": ["es2023"],
+ "module": "es2022",
+ "moduleResolution": "bundler",
+ "types": ["@cloudflare/workers-types", "node"],
+ "skipLibCheck": true,
+ "noEmit": true,
+ "isolatedModules": true,
+ "allowSyntheticDefaultImports": true,
+ "forceConsistentCasingInFileNames": true,
+ "strict": true
+ },
+ "include": ["src/**/*", "vite.config.ts"]
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/vite.config.ts

@@ -0,0 +1,19 @@
+import { cloudflare } from '@cloudflare/vite-plugin';
+import { sentryCloudflareVitePlugin } from '@sentry/cloudflare/vite';
+import agents from 'agents/vite';
+import { defineConfig } from 'vite';
+
+// `agents()` supplies the TC39 decorator transform that `@callable()` needs.
+// `autoInstrumentation` is the plugin under test: it rewrites `src/index.ts` at
+// build time so the entry itself contains no Sentry calls.
+export default defineConfig({
+ plugins: [
+ agents(),
+ cloudflare(),
+ sentryCloudflareVitePlugin({
+ _experimental: {
+ autoInstrumentation: true,
+ },
+ }),
+ ],
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/wrangler.jsonc

@@ -0,0 +1,32 @@
+{
+"$schema": "node_modules/wrangler/config-schema.json",
+"name": "cloudflare-autoinstrument",
+"main": "src/index.ts",
+"compatibility_date": "2026-05-20",
+"compatibility_flags": ["nodejs_compat"],
+
+// Every class below is registered the same way — as a Durable Object binding.
+// An `agents` Agent *is* a Durable Object, so wrangler offers no way to say
+// "this one is an Agent". Only the base-class chain distinguishes them, which
+// is exactly what the plugin's detection has to work out at build time:
+//
+// MyAgent -> extends Agent (entry-local) => agent
+// MyChatAgent -> extends AIChatAgent (entry-local) => agent
+// DerivedAgent -> extends ./base#MyBase -> Agent => agent
+// PlainDO -> extends DurableObject => durableObject
+"durable_objects": {
+"bindings": [
+ { "name": "MyAgent", "class_name": "MyAgent" },
+ { "name": "MyChatAgent", "class_name": "MyChatAgent" },
+ { "name": "DerivedAgent", "class_name": "DerivedAgent" },
+ { "name": "PlainDO", "class_name": "PlainDO" },
+ ],
+ },
+
+"migrations": [
+ {
+"tag": "v1",
+"new_sqlite_classes": ["MyAgent", "MyChatAgent", "DerivedAgent", "PlainDO"],
+ },
+ ],
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/.gitignore

@@ -0,0 +1,4 @@
+dist
+.wrangler
+test-results
+pnpm-lock.yaml

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/package.json

@@ -0,0 +1,38 @@
+{
+ "name": "cloudflare-autoinstrument",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "dev": "vite dev",
+ "build": "vite build",
+ "preview": "wrangler dev --var \"E2E_TEST_DSN:$E2E_TEST_DSN\" --log-level=$(test $CI && echo 'none' || echo 'log')",
+ "test": "playwright test",
+ "typecheck": "tsc --noEmit",
+ "test:build": "pnpm install && pnpm build",
+ "test:assert": "pnpm typecheck && pnpm test"
+ },
+ "dependencies": {
+ "@cloudflare/ai-chat": "^0.10.0",
+ "@sentry/cloudflare": "file:../../packed/sentry-cloudflare-packed.tgz",
+ "agents": "^0.20.0"
+ },
+ "devDependencies": {
+ "@babel/core": "^8.0.1",
+ "@babel/plugin-proposal-decorators": "^8.0.2",
+ "@cloudflare/vite-plugin": "^1.47.0",
+ "@cloudflare/workers-types": "^5.20260727.1",
+ "@playwright/test": "~1.56.0",
+ "@sentry-internal/test-utils": "link:../../../test-utils",
+ "@types/node": "^26.1.2",
+ "@types/ws": "^8.18.1",
+ "typescript": "~6.0.3",
+ "vite": "^8.1.5",
+ "wrangler": "^4.114.0",
+ "ws": "^8.21.1"
+ },
+ "volta": {
+ "node": "24.15.0",
+ "extends": "../../package.json"
+ }
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/playwright.config.ts

@@ -0,0 +1,16 @@
+import { getPlaywrightConfig } from '@sentry-internal/test-utils';
+
+// `vite build` runs the Sentry auto-instrument transform over the worker entry;
+// `pnpm preview` (`wrangler dev`, following the vite plugin's `.wrangler/deploy`
+// redirect) serves the built output. The tests therefore assert on the wrapping
+// the plugin injected at build time, not on anything in the source entry.
+export default getPlaywrightConfig(
+ {
+ startCommand: 'pnpm preview',
+ port: 8787,
+ },
+ {
+ workers: '100%',
+ retries: 0,
+ },
+);

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/base.ts

@@ -0,0 +1,12 @@
+import { Agent } from 'agents';
+
+/**
+ * An Agent base class living outside the worker entry. `DerivedAgent` in
+ * `index.ts` extends this, so the plugin only learns it is an Agent by
+ * following the import into this module and resolving `MyBase -> Agent`.
+ */
+export class MyBase extends Agent<Env> {
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'derived' });
+ }
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/env.d.ts

@@ -0,0 +1,7 @@
+interfaceEnv{
+E2E_TEST_DSN: string;
+MyAgent: DurableObjectNamespace;
+MyChatAgent: DurableObjectNamespace;
+DerivedAgent: DurableObjectNamespace;
+PlainDO: DurableObjectNamespace;
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/index.ts

@@ -0,0 +1,73 @@
+import { AIChatAgent } from '@cloudflare/ai-chat';
+import { Agent, callable, routeAgentRequest } from 'agents';
+import { DurableObject } from 'cloudflare:workers';
+import { MyBase } from './base';
+
+// NOTE: this file deliberately contains NO `Sentry.*` calls and no import of
+// `@sentry/cloudflare`. Everything below is wrapped at build time by
+// `sentryCloudflareVitePlugin({ _experimental: { autoInstrumentation: true } })`,
+// which reads wrangler.jsonc, wraps the default export with `withSentry`, and
+// picks a wrapper per class: `instrumentAgentWithSentry` for the three Agents,
+// `instrumentDurableObjectWithSentry` for the plain Durable Object.
+//
+// Options come from `instrument.server.ts` next to this entry.
+
+/** Agent whose base class (`Agent`) is imported directly into the entry. */
+export class MyAgent extends Agent<Env> {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from MyAgent)`;
+ }
+
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'plain' });
+ }
+}
+
+/** Chat agent — `AIChatAgent` extends `Agent` inside `@cloudflare/ai-chat`. */
+export class MyChatAgent extends AIChatAgent<Env> {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from MyChatAgent)`;
+ }
+
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'chat' });
+ }
+}
+
+/** Agent whose base class lives in `./base` — resolvable only across modules. */
+export class DerivedAgent extends MyBase {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from DerivedAgent)`;
+ }
+}
+
+/**
+ * A genuine Durable Object. Configured identically to the Agents above, so it
+ * proves detection discriminates rather than upgrading every DO binding.
+ */
+export class PlainDO extends DurableObject<Env> {
+ async fetch(): Promise<Response> {
+ return Response.json({ durableObject: true });
+ }
+}
+
+export default {
+ async fetch(request: Request, env: Env): Promise<Response> {
+ const url = new URL(request.url);
+
+ if (url.pathname === '/plain-do') {
+ const stub = env.PlainDO.get(env.PlainDO.idFromName('do-instance'));
+ return stub.fetch(request);
+ }
+
+ const agentResponse = await routeAgentRequest(request, env);
+ if (agentResponse) {
+ return agentResponse;
+ }
+
+ return new Response('Not found', { status: 404 });
+ },
+} satisfies ExportedHandler<Env>;

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/instrument.server.ts

@@ -0,0 +1,14 @@
+// The auto-instrument plugin picks this file up by convention (it sits next to
+// the worker entry named in wrangler's `main`) and imports its default export as
+// the options callback for every wrapper it injects.
+export default (env: Env) => ({
+ traceLifecycle: 'static' as const,
+ dsn: env.E2E_TEST_DSN,
+ environment: 'qa',
+ tunnel: 'http://localhost:3031/',
+ tracesSampleRate: 1.0,
+ enableRpcTracePropagation: true,
+ transportOptions: {
+ bufferSize: 1000,
+ },
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/start-event-proxy.mjs

@@ -0,0 +1,6 @@
+import{startEventProxyServer}from'@sentry-internal/test-utils';
+
+startEventProxyServer({
+port: 3031,
+proxyServerName: 'cloudflare-autoinstrument',
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tests/agent-socket.ts

@@ -0,0 +1,46 @@
+import WebSocket from 'ws';
+
+type AgentReply = { type?: string; id?: string; done?: boolean; result?: unknown };
+
+/**
+ * Opens a WebSocket to `/agents/<binding>/<instance>`, sends one RPC frame, and
+ * resolves with the reply's `result` — the method's return value — once it arrives.
+ */
+export function callRpc(
+ baseURL: string,
+ options: { binding: string; instance: string; method: string; args: unknown[] },
+): Promise<unknown> {
+ const id = `rpc-${options.method}`;
+ const frame = { type: 'rpc', id, method: options.method, args: options.args };
+ const wsUrl = `${baseURL.replace(/^http/, 'ws')}/agents/${options.binding}/${options.instance}`;
+
+ return new Promise<unknown>((resolveSocket, rejectSocket) => {
+ const socket = new WebSocket(wsUrl);
+ const timeout = setTimeout(() => {
+ socket.close();
+ rejectSocket(new Error(`Timed out waiting for RPC reply to "${options.method}"`));
+ }, 15_000);
+
+ socket.on('open', () => {
+ socket.send(JSON.stringify(frame));
+ });
+
+ socket.on('message', data => {
+ try {
+ const parsed = JSON.parse(data.toString()) as AgentReply;
+ if (parsed.type === 'rpc' && parsed.id === id && parsed.done) {
+ clearTimeout(timeout);
+ socket.close();
+ resolveSocket(parsed.result);
+ }
+ } catch {
+ // Ignore non-JSON / unrelated frames.
+ }
+ });
+
+ socket.on('error', err => {
+ clearTimeout(timeout);
+ rejectSocket(err);
+ });
+ });
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tests/autoinstrument.test.ts

@@ -0,0 +1,99 @@
+import { expect, test } from '@playwright/test';
+import { waitForTransaction } from '@sentry-internal/test-utils';
+import { callRpc } from './agent-socket';
+
+// The worker entry (`src/index.ts`) contains no Sentry calls at all — every
+// wrapper below was injected by the Vite auto-instrument plugin at build time.
+// Any transaction arriving here therefore proves the injection happened.
+
+test('wraps the default export with withSentry (options from instrument.server.ts)', async ({ baseURL }) => {
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return event.contexts?.trace?.op === 'http.server' && (event.request?.url ?? '').includes('/plain-do');
+ });
+
+ const res = await fetch(`${baseURL}/plain-do`);
+ expect(res.status).toBe(200);
+ await expect(res.json()).resolves.toEqual({ durableObject: true });
+
+ const transaction = await transactionPromise;
+
+ expect(transaction.contexts?.trace?.origin).toBe('auto.http.cloudflare');
+ // `environment: 'qa'` is only set in `instrument.server.ts`, so seeing it here
+ // proves the plugin sourced its options callback from that file rather than
+ // falling back to reading configuration off `env`.
+ expect(transaction.environment).toBe('qa');
+});
+
+// Each of these three classes is registered in wrangler.jsonc exactly like the
+// plain Durable Object below — only the base-class chain marks them as Agents.
+// An `rpc` span with origin `auto.faas.cloudflare.agents` is produced solely by
+// `instrumentAgentWithSentry`, so its presence is what distinguishes a correct
+// agent upgrade from a plain `instrumentDurableObjectWithSentry` wrap.
+for (const { title, binding, agentClass } of [
+ {
+ title: 'an Agent subclass declared in the entry',
+ binding: 'my-agent',
+ agentClass: 'MyAgent',
+ },
+ {
+ title: 'an AIChatAgent subclass declared in the entry',
+ binding: 'my-chat-agent',
+ agentClass: 'MyChatAgent',
+ },
+ {
+ title: 'an Agent subclass whose base class lives in another module',
+ binding: 'derived-agent',
+ agentClass: 'DerivedAgent',
+ },
+]) {
+ test(`applies agent instrumentation to ${title}`, async ({ baseURL }) => {
+ const instance = `${binding}-instance`;
+
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return (
+ event.transaction === 'webSocketMessage' &&
+ (event.spans ?? []).some(span => span.op === 'rpc' && span.description === 'greet')
+ );
+ });
+
+ // Each agent's greet() returns a string naming its class, so the reply
+ // identifies exactly which class handled the call.
+ const reply = await callRpc(baseURL!, { binding, instance, method: 'greet', args: ['World'] });
+ expect(reply).toBe(`Hello, World! (from ${agentClass})`);
+
+ const transaction = await transactionPromise;
+ const rpcSpan = (transaction.spans ?? []).find(span => span.op === 'rpc' && span.description === 'greet');
+
+ expect(rpcSpan).toEqual(
+ expect.objectContaining({
+ op: 'rpc',
+ description: 'greet',
+ origin: 'auto.faas.cloudflare.agents',
+ data: expect.objectContaining({
+ // Read back off the instance at runtime (`_ParentClass.name`), so it
+ // confirms the wrapper landed on the user's real class. Matched loosely
+ // because the transform renames the class it wraps to
+ // `__SENTRY_ORIGINAL_<name>__` and the bundler infers that name.
+ 'cloudflare.agent.class': expect.stringContaining(agentClass),
+ 'cloudflare.agent.name': instance,
+ }),
+ }),
+ );
+ });
+}
+
+test('applies plain Durable Object instrumentation to a non-Agent class', async ({ baseURL }) => {
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return event.contexts?.trace?.op === 'http.server' && (event.request?.url ?? '').includes('/plain-do');
+ });
+
+ const res = await fetch(`${baseURL}/plain-do`);
+ expect(res.status).toBe(200);
+
+ const transaction = await transactionPromise;
+
+ // A plain Durable Object must NOT pick up agent instrumentation: detection has
+ // to discriminate, not blanket-upgrade every `durable_objects` binding.
+ const agentSpans = (transaction.spans ?? []).filter(span => span.origin === 'auto.faas.cloudflare.agents');
+ expect(agentSpans).toEqual([]);
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tsconfig.json

@@ -0,0 +1,16 @@
+{
+ "compilerOptions": {
+ "target": "es2023",
+ "lib": ["es2023"],
+ "module": "es2022",
+ "moduleResolution": "bundler",
+ "types": ["@cloudflare/workers-types", "node"],
+ "skipLibCheck": true,
+ "noEmit": true,
+ "isolatedModules": true,
+ "allowSyntheticDefaultImports": true,
+ "forceConsistentCasingInFileNames": true,
+ "strict": true
+ },
+ "include": ["src/**/*", "vite.config.ts"]
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/vite.config.ts

@@ -0,0 +1,19 @@
+import { cloudflare } from '@cloudflare/vite-plugin';
+import { sentryCloudflareVitePlugin } from '@sentry/cloudflare/vite';
+import agents from 'agents/vite';
+import { defineConfig } from 'vite';
+
+// `agents()` supplies the TC39 decorator transform that `@callable()` needs.
+// `autoInstrumentation` is the plugin under test: it rewrites `src/index.ts` at
+// build time so the entry itself contains no Sentry calls.
+export default defineConfig({
+ plugins: [
+ agents(),
+ cloudflare(),
+ sentryCloudflareVitePlugin({
+ _experimental: {
+ autoInstrumentation: true,
+ },
+ }),
+ ],
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/wrangler.jsonc

@@ -0,0 +1,32 @@
+{
+"$schema": "node_modules/wrangler/config-schema.json",
+"name": "cloudflare-autoinstrument",
+"main": "src/index.ts",
+"compatibility_date": "2026-05-20",
+"compatibility_flags": ["nodejs_compat"],
+
+// Every class below is registered the same way — as a Durable Object binding.
+// An `agents` Agent *is* a Durable Object, so wrangler offers no way to say
+// "this one is an Agent". Only the base-class chain distinguishes them, which
+// is exactly what the plugin's detection has to work out at build time:
+//
+// MyAgent -> extends Agent (entry-local) => agent
+// MyChatAgent -> extends AIChatAgent (entry-local) => agent
+// DerivedAgent -> extends ./base#MyBase -> Agent => agent
+// PlainDO -> extends DurableObject => durableObject
+"durable_objects": {
+"bindings": [
+ { "name": "MyAgent", "class_name": "MyAgent" },
+ { "name": "MyChatAgent", "class_name": "MyChatAgent" },
+ { "name": "DerivedAgent", "class_name": "DerivedAgent" },
+ { "name": "PlainDO", "class_name": "PlainDO" },
+ ],
+ },
+
+"migrations": [
+ {
+"tag": "v1",
+"new_sqlite_classes": ["MyAgent", "MyChatAgent", "DerivedAgent", "PlainDO"],
+ },
+ ],
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/.gitignore

@@ -0,0 +1,4 @@
+dist
+.wrangler
+test-results
+pnpm-lock.yaml

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/package.json

@@ -0,0 +1,38 @@
+{
+ "name": "cloudflare-autoinstrument",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "dev": "vite dev",
+ "build": "vite build",
+ "preview": "wrangler dev --var \"E2E_TEST_DSN:$E2E_TEST_DSN\" --log-level=$(test $CI && echo 'none' || echo 'log')",
+ "test": "playwright test",
+ "typecheck": "tsc --noEmit",
+ "test:build": "pnpm install && pnpm build",
+ "test:assert": "pnpm typecheck && pnpm test"
+ },
+ "dependencies": {
+ "@cloudflare/ai-chat": "^0.10.0",
+ "@sentry/cloudflare": "file:../../packed/sentry-cloudflare-packed.tgz",
+ "agents": "^0.20.0"
+ },
+ "devDependencies": {
+ "@babel/core": "^8.0.1",
+ "@babel/plugin-proposal-decorators": "^8.0.2",
+ "@cloudflare/vite-plugin": "^1.47.0",
+ "@cloudflare/workers-types": "^5.20260727.1",
+ "@playwright/test": "~1.56.0",
+ "@sentry-internal/test-utils": "link:../../../test-utils",
+ "@types/node": "^26.1.2",
+ "@types/ws": "^8.18.1",
+ "typescript": "~6.0.3",
+ "vite": "^8.1.5",
+ "wrangler": "^4.114.0",
+ "ws": "^8.21.1"
+ },
+ "volta": {
+ "node": "24.15.0",
+ "extends": "../../package.json"
+ }
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/playwright.config.ts

@@ -0,0 +1,16 @@
+import { getPlaywrightConfig } from '@sentry-internal/test-utils';
+
+// `vite build` runs the Sentry auto-instrument transform over the worker entry;
+// `pnpm preview` (`wrangler dev`, following the vite plugin's `.wrangler/deploy`
+// redirect) serves the built output. The tests therefore assert on the wrapping
+// the plugin injected at build time, not on anything in the source entry.
+export default getPlaywrightConfig(
+ {
+ startCommand: 'pnpm preview',
+ port: 8787,
+ },
+ {
+ workers: '100%',
+ retries: 0,
+ },
+);

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/base.ts

@@ -0,0 +1,12 @@
+import { Agent } from 'agents';
+
+/**
+ * An Agent base class living outside the worker entry. `DerivedAgent` in
+ * `index.ts` extends this, so the plugin only learns it is an Agent by
+ * following the import into this module and resolving `MyBase -> Agent`.
+ */
+export class MyBase extends Agent<Env> {
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'derived' });
+ }
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/env.d.ts

@@ -0,0 +1,7 @@
+interfaceEnv{
+E2E_TEST_DSN: string;
+MyAgent: DurableObjectNamespace;
+MyChatAgent: DurableObjectNamespace;
+DerivedAgent: DurableObjectNamespace;
+PlainDO: DurableObjectNamespace;
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/index.ts

@@ -0,0 +1,73 @@
+import { AIChatAgent } from '@cloudflare/ai-chat';
+import { Agent, callable, routeAgentRequest } from 'agents';
+import { DurableObject } from 'cloudflare:workers';
+import { MyBase } from './base';
+
+// NOTE: this file deliberately contains NO `Sentry.*` calls and no import of
+// `@sentry/cloudflare`. Everything below is wrapped at build time by
+// `sentryCloudflareVitePlugin({ _experimental: { autoInstrumentation: true } })`,
+// which reads wrangler.jsonc, wraps the default export with `withSentry`, and
+// picks a wrapper per class: `instrumentAgentWithSentry` for the three Agents,
+// `instrumentDurableObjectWithSentry` for the plain Durable Object.
+//
+// Options come from `instrument.server.ts` next to this entry.
+
+/** Agent whose base class (`Agent`) is imported directly into the entry. */
+export class MyAgent extends Agent<Env> {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from MyAgent)`;
+ }
+
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'plain' });
+ }
+}
+
+/** Chat agent — `AIChatAgent` extends `Agent` inside `@cloudflare/ai-chat`. */
+export class MyChatAgent extends AIChatAgent<Env> {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from MyChatAgent)`;
+ }
+
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'chat' });
+ }
+}
+
+/** Agent whose base class lives in `./base` — resolvable only across modules. */
+export class DerivedAgent extends MyBase {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from DerivedAgent)`;
+ }
+}
+
+/**
+ * A genuine Durable Object. Configured identically to the Agents above, so it
+ * proves detection discriminates rather than upgrading every DO binding.
+ */
+export class PlainDO extends DurableObject<Env> {
+ async fetch(): Promise<Response> {
+ return Response.json({ durableObject: true });
+ }
+}
+
+export default {
+ async fetch(request: Request, env: Env): Promise<Response> {
+ const url = new URL(request.url);
+
+ if (url.pathname === '/plain-do') {
+ const stub = env.PlainDO.get(env.PlainDO.idFromName('do-instance'));
+ return stub.fetch(request);
+ }
+
+ const agentResponse = await routeAgentRequest(request, env);
+ if (agentResponse) {
+ return agentResponse;
+ }
+
+ return new Response('Not found', { status: 404 });
+ },
+} satisfies ExportedHandler<Env>;

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/instrument.server.ts

@@ -0,0 +1,14 @@
+// The auto-instrument plugin picks this file up by convention (it sits next to
+// the worker entry named in wrangler's `main`) and imports its default export as
+// the options callback for every wrapper it injects.
+export default (env: Env) => ({
+ traceLifecycle: 'static' as const,
+ dsn: env.E2E_TEST_DSN,
+ environment: 'qa',
+ tunnel: 'http://localhost:3031/',
+ tracesSampleRate: 1.0,
+ enableRpcTracePropagation: true,
+ transportOptions: {
+ bufferSize: 1000,
+ },
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/start-event-proxy.mjs

@@ -0,0 +1,6 @@
+import{startEventProxyServer}from'@sentry-internal/test-utils';
+
+startEventProxyServer({
+port: 3031,
+proxyServerName: 'cloudflare-autoinstrument',
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tests/agent-socket.ts

@@ -0,0 +1,46 @@
+import WebSocket from 'ws';
+
+type AgentReply = { type?: string; id?: string; done?: boolean; result?: unknown };
+
+/**
+ * Opens a WebSocket to `/agents/<binding>/<instance>`, sends one RPC frame, and
+ * resolves with the reply's `result` — the method's return value — once it arrives.
+ */
+export function callRpc(
+ baseURL: string,
+ options: { binding: string; instance: string; method: string; args: unknown[] },
+): Promise<unknown> {
+ const id = `rpc-${options.method}`;
+ const frame = { type: 'rpc', id, method: options.method, args: options.args };
+ const wsUrl = `${baseURL.replace(/^http/, 'ws')}/agents/${options.binding}/${options.instance}`;
+
+ return new Promise<unknown>((resolveSocket, rejectSocket) => {
+ const socket = new WebSocket(wsUrl);
+ const timeout = setTimeout(() => {
+ socket.close();
+ rejectSocket(new Error(`Timed out waiting for RPC reply to "${options.method}"`));
+ }, 15_000);
+
+ socket.on('open', () => {
+ socket.send(JSON.stringify(frame));
+ });
+
+ socket.on('message', data => {
+ try {
+ const parsed = JSON.parse(data.toString()) as AgentReply;
+ if (parsed.type === 'rpc' && parsed.id === id && parsed.done) {
+ clearTimeout(timeout);
+ socket.close();
+ resolveSocket(parsed.result);
+ }
+ } catch {
+ // Ignore non-JSON / unrelated frames.
+ }
+ });
+
+ socket.on('error', err => {
+ clearTimeout(timeout);
+ rejectSocket(err);
+ });
+ });
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tests/autoinstrument.test.ts

@@ -0,0 +1,99 @@
+import { expect, test } from '@playwright/test';
+import { waitForTransaction } from '@sentry-internal/test-utils';
+import { callRpc } from './agent-socket';
+
+// The worker entry (`src/index.ts`) contains no Sentry calls at all — every
+// wrapper below was injected by the Vite auto-instrument plugin at build time.
+// Any transaction arriving here therefore proves the injection happened.
+
+test('wraps the default export with withSentry (options from instrument.server.ts)', async ({ baseURL }) => {
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return event.contexts?.trace?.op === 'http.server' && (event.request?.url ?? '').includes('/plain-do');
+ });
+
+ const res = await fetch(`${baseURL}/plain-do`);
+ expect(res.status).toBe(200);
+ await expect(res.json()).resolves.toEqual({ durableObject: true });
+
+ const transaction = await transactionPromise;
+
+ expect(transaction.contexts?.trace?.origin).toBe('auto.http.cloudflare');
+ // `environment: 'qa'` is only set in `instrument.server.ts`, so seeing it here
+ // proves the plugin sourced its options callback from that file rather than
+ // falling back to reading configuration off `env`.
+ expect(transaction.environment).toBe('qa');
+});
+
+// Each of these three classes is registered in wrangler.jsonc exactly like the
+// plain Durable Object below — only the base-class chain marks them as Agents.
+// An `rpc` span with origin `auto.faas.cloudflare.agents` is produced solely by
+// `instrumentAgentWithSentry`, so its presence is what distinguishes a correct
+// agent upgrade from a plain `instrumentDurableObjectWithSentry` wrap.
+for (const { title, binding, agentClass } of [
+ {
+ title: 'an Agent subclass declared in the entry',
+ binding: 'my-agent',
+ agentClass: 'MyAgent',
+ },
+ {
+ title: 'an AIChatAgent subclass declared in the entry',
+ binding: 'my-chat-agent',
+ agentClass: 'MyChatAgent',
+ },
+ {
+ title: 'an Agent subclass whose base class lives in another module',
+ binding: 'derived-agent',
+ agentClass: 'DerivedAgent',
+ },
+]) {
+ test(`applies agent instrumentation to ${title}`, async ({ baseURL }) => {
+ const instance = `${binding}-instance`;
+
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return (
+ event.transaction === 'webSocketMessage' &&
+ (event.spans ?? []).some(span => span.op === 'rpc' && span.description === 'greet')
+ );
+ });
+
+ // Each agent's greet() returns a string naming its class, so the reply
+ // identifies exactly which class handled the call.
+ const reply = await callRpc(baseURL!, { binding, instance, method: 'greet', args: ['World'] });
+ expect(reply).toBe(`Hello, World! (from ${agentClass})`);
+
+ const transaction = await transactionPromise;
+ const rpcSpan = (transaction.spans ?? []).find(span => span.op === 'rpc' && span.description === 'greet');
+
+ expect(rpcSpan).toEqual(
+ expect.objectContaining({
+ op: 'rpc',
+ description: 'greet',
+ origin: 'auto.faas.cloudflare.agents',
+ data: expect.objectContaining({
+ // Read back off the instance at runtime (`_ParentClass.name`), so it
+ // confirms the wrapper landed on the user's real class. Matched loosely
+ // because the transform renames the class it wraps to
+ // `__SENTRY_ORIGINAL_<name>__` and the bundler infers that name.
+ 'cloudflare.agent.class': expect.stringContaining(agentClass),
+ 'cloudflare.agent.name': instance,
+ }),
+ }),
+ );
+ });
+}
+
+test('applies plain Durable Object instrumentation to a non-Agent class', async ({ baseURL }) => {
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return event.contexts?.trace?.op === 'http.server' && (event.request?.url ?? '').includes('/plain-do');
+ });
+
+ const res = await fetch(`${baseURL}/plain-do`);
+ expect(res.status).toBe(200);
+
+ const transaction = await transactionPromise;
+
+ // A plain Durable Object must NOT pick up agent instrumentation: detection has
+ // to discriminate, not blanket-upgrade every `durable_objects` binding.
+ const agentSpans = (transaction.spans ?? []).filter(span => span.origin === 'auto.faas.cloudflare.agents');
+ expect(agentSpans).toEqual([]);
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tsconfig.json

@@ -0,0 +1,16 @@
+{
+ "compilerOptions": {
+ "target": "es2023",
+ "lib": ["es2023"],
+ "module": "es2022",
+ "moduleResolution": "bundler",
+ "types": ["@cloudflare/workers-types", "node"],
+ "skipLibCheck": true,
+ "noEmit": true,
+ "isolatedModules": true,
+ "allowSyntheticDefaultImports": true,
+ "forceConsistentCasingInFileNames": true,
+ "strict": true
+ },
+ "include": ["src/**/*", "vite.config.ts"]
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/vite.config.ts

@@ -0,0 +1,19 @@
+import { cloudflare } from '@cloudflare/vite-plugin';
+import { sentryCloudflareVitePlugin } from '@sentry/cloudflare/vite';
+import agents from 'agents/vite';
+import { defineConfig } from 'vite';
+
+// `agents()` supplies the TC39 decorator transform that `@callable()` needs.
+// `autoInstrumentation` is the plugin under test: it rewrites `src/index.ts` at
+// build time so the entry itself contains no Sentry calls.
+export default defineConfig({
+ plugins: [
+ agents(),
+ cloudflare(),
+ sentryCloudflareVitePlugin({
+ _experimental: {
+ autoInstrumentation: true,
+ },
+ }),
+ ],
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/wrangler.jsonc

@@ -0,0 +1,32 @@
+{
+"$schema": "node_modules/wrangler/config-schema.json",
+"name": "cloudflare-autoinstrument",
+"main": "src/index.ts",
+"compatibility_date": "2026-05-20",
+"compatibility_flags": ["nodejs_compat"],
+
+// Every class below is registered the same way — as a Durable Object binding.
+// An `agents` Agent *is* a Durable Object, so wrangler offers no way to say
+// "this one is an Agent". Only the base-class chain distinguishes them, which
+// is exactly what the plugin's detection has to work out at build time:
+//
+// MyAgent -> extends Agent (entry-local) => agent
+// MyChatAgent -> extends AIChatAgent (entry-local) => agent
+// DerivedAgent -> extends ./base#MyBase -> Agent => agent
+// PlainDO -> extends DurableObject => durableObject
+"durable_objects": {
+"bindings": [
+ { "name": "MyAgent", "class_name": "MyAgent" },
+ { "name": "MyChatAgent", "class_name": "MyChatAgent" },
+ { "name": "DerivedAgent", "class_name": "DerivedAgent" },
+ { "name": "PlainDO", "class_name": "PlainDO" },
+ ],
+ },
+
+"migrations": [
+ {
+"tag": "v1",
+"new_sqlite_classes": ["MyAgent", "MyChatAgent", "DerivedAgent", "PlainDO"],
+ },
+ ],
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/.gitignore

@@ -0,0 +1,4 @@
+dist
+.wrangler
+test-results
+pnpm-lock.yaml

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/package.json

@@ -0,0 +1,38 @@
+{
+ "name": "cloudflare-autoinstrument",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "dev": "vite dev",
+ "build": "vite build",
+ "preview": "wrangler dev --var \"E2E_TEST_DSN:$E2E_TEST_DSN\" --log-level=$(test $CI && echo 'none' || echo 'log')",
+ "test": "playwright test",
+ "typecheck": "tsc --noEmit",
+ "test:build": "pnpm install && pnpm build",
+ "test:assert": "pnpm typecheck && pnpm test"
+ },
+ "dependencies": {
+ "@cloudflare/ai-chat": "^0.10.0",
+ "@sentry/cloudflare": "file:../../packed/sentry-cloudflare-packed.tgz",
+ "agents": "^0.20.0"
+ },
+ "devDependencies": {
+ "@babel/core": "^8.0.1",
+ "@babel/plugin-proposal-decorators": "^8.0.2",
+ "@cloudflare/vite-plugin": "^1.47.0",
+ "@cloudflare/workers-types": "^5.20260727.1",
+ "@playwright/test": "~1.56.0",
+ "@sentry-internal/test-utils": "link:../../../test-utils",
+ "@types/node": "^26.1.2",
+ "@types/ws": "^8.18.1",
+ "typescript": "~6.0.3",
+ "vite": "^8.1.5",
+ "wrangler": "^4.114.0",
+ "ws": "^8.21.1"
+ },
+ "volta": {
+ "node": "24.15.0",
+ "extends": "../../package.json"
+ }
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/playwright.config.ts

@@ -0,0 +1,16 @@
+import { getPlaywrightConfig } from '@sentry-internal/test-utils';
+
+// `vite build` runs the Sentry auto-instrument transform over the worker entry;
+// `pnpm preview` (`wrangler dev`, following the vite plugin's `.wrangler/deploy`
+// redirect) serves the built output. The tests therefore assert on the wrapping
+// the plugin injected at build time, not on anything in the source entry.
+export default getPlaywrightConfig(
+ {
+ startCommand: 'pnpm preview',
+ port: 8787,
+ },
+ {
+ workers: '100%',
+ retries: 0,
+ },
+);

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/base.ts

@@ -0,0 +1,12 @@
+import { Agent } from 'agents';
+
+/**
+ * An Agent base class living outside the worker entry. `DerivedAgent` in
+ * `index.ts` extends this, so the plugin only learns it is an Agent by
+ * following the import into this module and resolving `MyBase -> Agent`.
+ */
+export class MyBase extends Agent<Env> {
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'derived' });
+ }
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/env.d.ts

@@ -0,0 +1,7 @@
+interfaceEnv{
+E2E_TEST_DSN: string;
+MyAgent: DurableObjectNamespace;
+MyChatAgent: DurableObjectNamespace;
+DerivedAgent: DurableObjectNamespace;
+PlainDO: DurableObjectNamespace;
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/index.ts

@@ -0,0 +1,73 @@
+import { AIChatAgent } from '@cloudflare/ai-chat';
+import { Agent, callable, routeAgentRequest } from 'agents';
+import { DurableObject } from 'cloudflare:workers';
+import { MyBase } from './base';
+
+// NOTE: this file deliberately contains NO `Sentry.*` calls and no import of
+// `@sentry/cloudflare`. Everything below is wrapped at build time by
+// `sentryCloudflareVitePlugin({ _experimental: { autoInstrumentation: true } })`,
+// which reads wrangler.jsonc, wraps the default export with `withSentry`, and
+// picks a wrapper per class: `instrumentAgentWithSentry` for the three Agents,
+// `instrumentDurableObjectWithSentry` for the plain Durable Object.
+//
+// Options come from `instrument.server.ts` next to this entry.
+
+/** Agent whose base class (`Agent`) is imported directly into the entry. */
+export class MyAgent extends Agent<Env> {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from MyAgent)`;
+ }
+
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'plain' });
+ }
+}
+
+/** Chat agent — `AIChatAgent` extends `Agent` inside `@cloudflare/ai-chat`. */
+export class MyChatAgent extends AIChatAgent<Env> {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from MyChatAgent)`;
+ }
+
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'chat' });
+ }
+}
+
+/** Agent whose base class lives in `./base` — resolvable only across modules. */
+export class DerivedAgent extends MyBase {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from DerivedAgent)`;
+ }
+}
+
+/**
+ * A genuine Durable Object. Configured identically to the Agents above, so it
+ * proves detection discriminates rather than upgrading every DO binding.
+ */
+export class PlainDO extends DurableObject<Env> {
+ async fetch(): Promise<Response> {
+ return Response.json({ durableObject: true });
+ }
+}
+
+export default {
+ async fetch(request: Request, env: Env): Promise<Response> {
+ const url = new URL(request.url);
+
+ if (url.pathname === '/plain-do') {
+ const stub = env.PlainDO.get(env.PlainDO.idFromName('do-instance'));
+ return stub.fetch(request);
+ }
+
+ const agentResponse = await routeAgentRequest(request, env);
+ if (agentResponse) {
+ return agentResponse;
+ }
+
+ return new Response('Not found', { status: 404 });
+ },
+} satisfies ExportedHandler<Env>;

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/instrument.server.ts

@@ -0,0 +1,14 @@
+// The auto-instrument plugin picks this file up by convention (it sits next to
+// the worker entry named in wrangler's `main`) and imports its default export as
+// the options callback for every wrapper it injects.
+export default (env: Env) => ({
+ traceLifecycle: 'static' as const,
+ dsn: env.E2E_TEST_DSN,
+ environment: 'qa',
+ tunnel: 'http://localhost:3031/',
+ tracesSampleRate: 1.0,
+ enableRpcTracePropagation: true,
+ transportOptions: {
+ bufferSize: 1000,
+ },
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/start-event-proxy.mjs

@@ -0,0 +1,6 @@
+import{startEventProxyServer}from'@sentry-internal/test-utils';
+
+startEventProxyServer({
+port: 3031,
+proxyServerName: 'cloudflare-autoinstrument',
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tests/agent-socket.ts

@@ -0,0 +1,46 @@
+import WebSocket from 'ws';
+
+type AgentReply = { type?: string; id?: string; done?: boolean; result?: unknown };
+
+/**
+ * Opens a WebSocket to `/agents/<binding>/<instance>`, sends one RPC frame, and
+ * resolves with the reply's `result` — the method's return value — once it arrives.
+ */
+export function callRpc(
+ baseURL: string,
+ options: { binding: string; instance: string; method: string; args: unknown[] },
+): Promise<unknown> {
+ const id = `rpc-${options.method}`;
+ const frame = { type: 'rpc', id, method: options.method, args: options.args };
+ const wsUrl = `${baseURL.replace(/^http/, 'ws')}/agents/${options.binding}/${options.instance}`;
+
+ return new Promise<unknown>((resolveSocket, rejectSocket) => {
+ const socket = new WebSocket(wsUrl);
+ const timeout = setTimeout(() => {
+ socket.close();
+ rejectSocket(new Error(`Timed out waiting for RPC reply to "${options.method}"`));
+ }, 15_000);
+
+ socket.on('open', () => {
+ socket.send(JSON.stringify(frame));
+ });
+
+ socket.on('message', data => {
+ try {
+ const parsed = JSON.parse(data.toString()) as AgentReply;
+ if (parsed.type === 'rpc' && parsed.id === id && parsed.done) {
+ clearTimeout(timeout);
+ socket.close();
+ resolveSocket(parsed.result);
+ }
+ } catch {
+ // Ignore non-JSON / unrelated frames.
+ }
+ });
+
+ socket.on('error', err => {
+ clearTimeout(timeout);
+ rejectSocket(err);
+ });
+ });
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tests/autoinstrument.test.ts

@@ -0,0 +1,99 @@
+import { expect, test } from '@playwright/test';
+import { waitForTransaction } from '@sentry-internal/test-utils';
+import { callRpc } from './agent-socket';
+
+// The worker entry (`src/index.ts`) contains no Sentry calls at all — every
+// wrapper below was injected by the Vite auto-instrument plugin at build time.
+// Any transaction arriving here therefore proves the injection happened.
+
+test('wraps the default export with withSentry (options from instrument.server.ts)', async ({ baseURL }) => {
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return event.contexts?.trace?.op === 'http.server' && (event.request?.url ?? '').includes('/plain-do');
+ });
+
+ const res = await fetch(`${baseURL}/plain-do`);
+ expect(res.status).toBe(200);
+ await expect(res.json()).resolves.toEqual({ durableObject: true });
+
+ const transaction = await transactionPromise;
+
+ expect(transaction.contexts?.trace?.origin).toBe('auto.http.cloudflare');
+ // `environment: 'qa'` is only set in `instrument.server.ts`, so seeing it here
+ // proves the plugin sourced its options callback from that file rather than
+ // falling back to reading configuration off `env`.
+ expect(transaction.environment).toBe('qa');
+});
+
+// Each of these three classes is registered in wrangler.jsonc exactly like the
+// plain Durable Object below — only the base-class chain marks them as Agents.
+// An `rpc` span with origin `auto.faas.cloudflare.agents` is produced solely by
+// `instrumentAgentWithSentry`, so its presence is what distinguishes a correct
+// agent upgrade from a plain `instrumentDurableObjectWithSentry` wrap.
+for (const { title, binding, agentClass } of [
+ {
+ title: 'an Agent subclass declared in the entry',
+ binding: 'my-agent',
+ agentClass: 'MyAgent',
+ },
+ {
+ title: 'an AIChatAgent subclass declared in the entry',
+ binding: 'my-chat-agent',
+ agentClass: 'MyChatAgent',
+ },
+ {
+ title: 'an Agent subclass whose base class lives in another module',
+ binding: 'derived-agent',
+ agentClass: 'DerivedAgent',
+ },
+]) {
+ test(`applies agent instrumentation to ${title}`, async ({ baseURL }) => {
+ const instance = `${binding}-instance`;
+
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return (
+ event.transaction === 'webSocketMessage' &&
+ (event.spans ?? []).some(span => span.op === 'rpc' && span.description === 'greet')
+ );
+ });
+
+ // Each agent's greet() returns a string naming its class, so the reply
+ // identifies exactly which class handled the call.
+ const reply = await callRpc(baseURL!, { binding, instance, method: 'greet', args: ['World'] });
+ expect(reply).toBe(`Hello, World! (from ${agentClass})`);
+
+ const transaction = await transactionPromise;
+ const rpcSpan = (transaction.spans ?? []).find(span => span.op === 'rpc' && span.description === 'greet');
+
+ expect(rpcSpan).toEqual(
+ expect.objectContaining({
+ op: 'rpc',
+ description: 'greet',
+ origin: 'auto.faas.cloudflare.agents',
+ data: expect.objectContaining({
+ // Read back off the instance at runtime (`_ParentClass.name`), so it
+ // confirms the wrapper landed on the user's real class. Matched loosely
+ // because the transform renames the class it wraps to
+ // `__SENTRY_ORIGINAL_<name>__` and the bundler infers that name.
+ 'cloudflare.agent.class': expect.stringContaining(agentClass),
+ 'cloudflare.agent.name': instance,
+ }),
+ }),
+ );
+ });
+}
+
+test('applies plain Durable Object instrumentation to a non-Agent class', async ({ baseURL }) => {
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return event.contexts?.trace?.op === 'http.server' && (event.request?.url ?? '').includes('/plain-do');
+ });
+
+ const res = await fetch(`${baseURL}/plain-do`);
+ expect(res.status).toBe(200);
+
+ const transaction = await transactionPromise;
+
+ // A plain Durable Object must NOT pick up agent instrumentation: detection has
+ // to discriminate, not blanket-upgrade every `durable_objects` binding.
+ const agentSpans = (transaction.spans ?? []).filter(span => span.origin === 'auto.faas.cloudflare.agents');
+ expect(agentSpans).toEqual([]);
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tsconfig.json

@@ -0,0 +1,16 @@
+{
+ "compilerOptions": {
+ "target": "es2023",
+ "lib": ["es2023"],
+ "module": "es2022",
+ "moduleResolution": "bundler",
+ "types": ["@cloudflare/workers-types", "node"],
+ "skipLibCheck": true,
+ "noEmit": true,
+ "isolatedModules": true,
+ "allowSyntheticDefaultImports": true,
+ "forceConsistentCasingInFileNames": true,
+ "strict": true
+ },
+ "include": ["src/**/*", "vite.config.ts"]
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/vite.config.ts

@@ -0,0 +1,19 @@
+import { cloudflare } from '@cloudflare/vite-plugin';
+import { sentryCloudflareVitePlugin } from '@sentry/cloudflare/vite';
+import agents from 'agents/vite';
+import { defineConfig } from 'vite';
+
+// `agents()` supplies the TC39 decorator transform that `@callable()` needs.
+// `autoInstrumentation` is the plugin under test: it rewrites `src/index.ts` at
+// build time so the entry itself contains no Sentry calls.
+export default defineConfig({
+ plugins: [
+ agents(),
+ cloudflare(),
+ sentryCloudflareVitePlugin({
+ _experimental: {
+ autoInstrumentation: true,
+ },
+ }),
+ ],
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/wrangler.jsonc

@@ -0,0 +1,32 @@
+{
+"$schema": "node_modules/wrangler/config-schema.json",
+"name": "cloudflare-autoinstrument",
+"main": "src/index.ts",
+"compatibility_date": "2026-05-20",
+"compatibility_flags": ["nodejs_compat"],
+
+// Every class below is registered the same way — as a Durable Object binding.
+// An `agents` Agent *is* a Durable Object, so wrangler offers no way to say
+// "this one is an Agent". Only the base-class chain distinguishes them, which
+// is exactly what the plugin's detection has to work out at build time:
+//
+// MyAgent -> extends Agent (entry-local) => agent
+// MyChatAgent -> extends AIChatAgent (entry-local) => agent
+// DerivedAgent -> extends ./base#MyBase -> Agent => agent
+// PlainDO -> extends DurableObject => durableObject
+"durable_objects": {
+"bindings": [
+ { "name": "MyAgent", "class_name": "MyAgent" },
+ { "name": "MyChatAgent", "class_name": "MyChatAgent" },
+ { "name": "DerivedAgent", "class_name": "DerivedAgent" },
+ { "name": "PlainDO", "class_name": "PlainDO" },
+ ],
+ },
+
+"migrations": [
+ {
+"tag": "v1",
+"new_sqlite_classes": ["MyAgent", "MyChatAgent", "DerivedAgent", "PlainDO"],
+ },
+ ],
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/.gitignore

@@ -0,0 +1,4 @@
+dist
+.wrangler
+test-results
+pnpm-lock.yaml

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/package.json

@@ -0,0 +1,38 @@
+{
+ "name": "cloudflare-autoinstrument",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "dev": "vite dev",
+ "build": "vite build",
+ "preview": "wrangler dev --var \"E2E_TEST_DSN:$E2E_TEST_DSN\" --log-level=$(test $CI && echo 'none' || echo 'log')",
+ "test": "playwright test",
+ "typecheck": "tsc --noEmit",
+ "test:build": "pnpm install && pnpm build",
+ "test:assert": "pnpm typecheck && pnpm test"
+ },
+ "dependencies": {
+ "@cloudflare/ai-chat": "^0.10.0",
+ "@sentry/cloudflare": "file:../../packed/sentry-cloudflare-packed.tgz",
+ "agents": "^0.20.0"
+ },
+ "devDependencies": {
+ "@babel/core": "^8.0.1",
+ "@babel/plugin-proposal-decorators": "^8.0.2",
+ "@cloudflare/vite-plugin": "^1.47.0",
+ "@cloudflare/workers-types": "^5.20260727.1",
+ "@playwright/test": "~1.56.0",
+ "@sentry-internal/test-utils": "link:../../../test-utils",
+ "@types/node": "^26.1.2",
+ "@types/ws": "^8.18.1",
+ "typescript": "~6.0.3",
+ "vite": "^8.1.5",
+ "wrangler": "^4.114.0",
+ "ws": "^8.21.1"
+ },
+ "volta": {
+ "node": "24.15.0",
+ "extends": "../../package.json"
+ }
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/playwright.config.ts

@@ -0,0 +1,16 @@
+import { getPlaywrightConfig } from '@sentry-internal/test-utils';
+
+// `vite build` runs the Sentry auto-instrument transform over the worker entry;
+// `pnpm preview` (`wrangler dev`, following the vite plugin's `.wrangler/deploy`
+// redirect) serves the built output. The tests therefore assert on the wrapping
+// the plugin injected at build time, not on anything in the source entry.
+export default getPlaywrightConfig(
+ {
+ startCommand: 'pnpm preview',
+ port: 8787,
+ },
+ {
+ workers: '100%',
+ retries: 0,
+ },
+);

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/base.ts

@@ -0,0 +1,12 @@
+import { Agent } from 'agents';
+
+/**
+ * An Agent base class living outside the worker entry. `DerivedAgent` in
+ * `index.ts` extends this, so the plugin only learns it is an Agent by
+ * following the import into this module and resolving `MyBase -> Agent`.
+ */
+export class MyBase extends Agent<Env> {
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'derived' });
+ }
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/env.d.ts

@@ -0,0 +1,7 @@
+interfaceEnv{
+E2E_TEST_DSN: string;
+MyAgent: DurableObjectNamespace;
+MyChatAgent: DurableObjectNamespace;
+DerivedAgent: DurableObjectNamespace;
+PlainDO: DurableObjectNamespace;
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/index.ts

@@ -0,0 +1,73 @@
+import { AIChatAgent } from '@cloudflare/ai-chat';
+import { Agent, callable, routeAgentRequest } from 'agents';
+import { DurableObject } from 'cloudflare:workers';
+import { MyBase } from './base';
+
+// NOTE: this file deliberately contains NO `Sentry.*` calls and no import of
+// `@sentry/cloudflare`. Everything below is wrapped at build time by
+// `sentryCloudflareVitePlugin({ _experimental: { autoInstrumentation: true } })`,
+// which reads wrangler.jsonc, wraps the default export with `withSentry`, and
+// picks a wrapper per class: `instrumentAgentWithSentry` for the three Agents,
+// `instrumentDurableObjectWithSentry` for the plain Durable Object.
+//
+// Options come from `instrument.server.ts` next to this entry.
+
+/** Agent whose base class (`Agent`) is imported directly into the entry. */
+export class MyAgent extends Agent<Env> {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from MyAgent)`;
+ }
+
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'plain' });
+ }
+}
+
+/** Chat agent — `AIChatAgent` extends `Agent` inside `@cloudflare/ai-chat`. */
+export class MyChatAgent extends AIChatAgent<Env> {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from MyChatAgent)`;
+ }
+
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'chat' });
+ }
+}
+
+/** Agent whose base class lives in `./base` — resolvable only across modules. */
+export class DerivedAgent extends MyBase {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from DerivedAgent)`;
+ }
+}
+
+/**
+ * A genuine Durable Object. Configured identically to the Agents above, so it
+ * proves detection discriminates rather than upgrading every DO binding.
+ */
+export class PlainDO extends DurableObject<Env> {
+ async fetch(): Promise<Response> {
+ return Response.json({ durableObject: true });
+ }
+}
+
+export default {
+ async fetch(request: Request, env: Env): Promise<Response> {
+ const url = new URL(request.url);
+
+ if (url.pathname === '/plain-do') {
+ const stub = env.PlainDO.get(env.PlainDO.idFromName('do-instance'));
+ return stub.fetch(request);
+ }
+
+ const agentResponse = await routeAgentRequest(request, env);
+ if (agentResponse) {
+ return agentResponse;
+ }
+
+ return new Response('Not found', { status: 404 });
+ },
+} satisfies ExportedHandler<Env>;

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/instrument.server.ts

@@ -0,0 +1,14 @@
+// The auto-instrument plugin picks this file up by convention (it sits next to
+// the worker entry named in wrangler's `main`) and imports its default export as
+// the options callback for every wrapper it injects.
+export default (env: Env) => ({
+ traceLifecycle: 'static' as const,
+ dsn: env.E2E_TEST_DSN,
+ environment: 'qa',
+ tunnel: 'http://localhost:3031/',
+ tracesSampleRate: 1.0,
+ enableRpcTracePropagation: true,
+ transportOptions: {
+ bufferSize: 1000,
+ },
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/start-event-proxy.mjs

@@ -0,0 +1,6 @@
+import{startEventProxyServer}from'@sentry-internal/test-utils';
+
+startEventProxyServer({
+port: 3031,
+proxyServerName: 'cloudflare-autoinstrument',
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tests/agent-socket.ts

@@ -0,0 +1,46 @@
+import WebSocket from 'ws';
+
+type AgentReply = { type?: string; id?: string; done?: boolean; result?: unknown };
+
+/**
+ * Opens a WebSocket to `/agents/<binding>/<instance>`, sends one RPC frame, and
+ * resolves with the reply's `result` — the method's return value — once it arrives.
+ */
+export function callRpc(
+ baseURL: string,
+ options: { binding: string; instance: string; method: string; args: unknown[] },
+): Promise<unknown> {
+ const id = `rpc-${options.method}`;
+ const frame = { type: 'rpc', id, method: options.method, args: options.args };
+ const wsUrl = `${baseURL.replace(/^http/, 'ws')}/agents/${options.binding}/${options.instance}`;
+
+ return new Promise<unknown>((resolveSocket, rejectSocket) => {
+ const socket = new WebSocket(wsUrl);
+ const timeout = setTimeout(() => {
+ socket.close();
+ rejectSocket(new Error(`Timed out waiting for RPC reply to "${options.method}"`));
+ }, 15_000);
+
+ socket.on('open', () => {
+ socket.send(JSON.stringify(frame));
+ });
+
+ socket.on('message', data => {
+ try {
+ const parsed = JSON.parse(data.toString()) as AgentReply;
+ if (parsed.type === 'rpc' && parsed.id === id && parsed.done) {
+ clearTimeout(timeout);
+ socket.close();
+ resolveSocket(parsed.result);
+ }
+ } catch {
+ // Ignore non-JSON / unrelated frames.
+ }
+ });
+
+ socket.on('error', err => {
+ clearTimeout(timeout);
+ rejectSocket(err);
+ });
+ });
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tests/autoinstrument.test.ts

@@ -0,0 +1,99 @@
+import { expect, test } from '@playwright/test';
+import { waitForTransaction } from '@sentry-internal/test-utils';
+import { callRpc } from './agent-socket';
+
+// The worker entry (`src/index.ts`) contains no Sentry calls at all — every
+// wrapper below was injected by the Vite auto-instrument plugin at build time.
+// Any transaction arriving here therefore proves the injection happened.
+
+test('wraps the default export with withSentry (options from instrument.server.ts)', async ({ baseURL }) => {
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return event.contexts?.trace?.op === 'http.server' && (event.request?.url ?? '').includes('/plain-do');
+ });
+
+ const res = await fetch(`${baseURL}/plain-do`);
+ expect(res.status).toBe(200);
+ await expect(res.json()).resolves.toEqual({ durableObject: true });
+
+ const transaction = await transactionPromise;
+
+ expect(transaction.contexts?.trace?.origin).toBe('auto.http.cloudflare');
+ // `environment: 'qa'` is only set in `instrument.server.ts`, so seeing it here
+ // proves the plugin sourced its options callback from that file rather than
+ // falling back to reading configuration off `env`.
+ expect(transaction.environment).toBe('qa');
+});
+
+// Each of these three classes is registered in wrangler.jsonc exactly like the
+// plain Durable Object below — only the base-class chain marks them as Agents.
+// An `rpc` span with origin `auto.faas.cloudflare.agents` is produced solely by
+// `instrumentAgentWithSentry`, so its presence is what distinguishes a correct
+// agent upgrade from a plain `instrumentDurableObjectWithSentry` wrap.
+for (const { title, binding, agentClass } of [
+ {
+ title: 'an Agent subclass declared in the entry',
+ binding: 'my-agent',
+ agentClass: 'MyAgent',
+ },
+ {
+ title: 'an AIChatAgent subclass declared in the entry',
+ binding: 'my-chat-agent',
+ agentClass: 'MyChatAgent',
+ },
+ {
+ title: 'an Agent subclass whose base class lives in another module',
+ binding: 'derived-agent',
+ agentClass: 'DerivedAgent',
+ },
+]) {
+ test(`applies agent instrumentation to ${title}`, async ({ baseURL }) => {
+ const instance = `${binding}-instance`;
+
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return (
+ event.transaction === 'webSocketMessage' &&
+ (event.spans ?? []).some(span => span.op === 'rpc' && span.description === 'greet')
+ );
+ });
+
+ // Each agent's greet() returns a string naming its class, so the reply
+ // identifies exactly which class handled the call.
+ const reply = await callRpc(baseURL!, { binding, instance, method: 'greet', args: ['World'] });
+ expect(reply).toBe(`Hello, World! (from ${agentClass})`);
+
+ const transaction = await transactionPromise;
+ const rpcSpan = (transaction.spans ?? []).find(span => span.op === 'rpc' && span.description === 'greet');
+
+ expect(rpcSpan).toEqual(
+ expect.objectContaining({
+ op: 'rpc',
+ description: 'greet',
+ origin: 'auto.faas.cloudflare.agents',
+ data: expect.objectContaining({
+ // Read back off the instance at runtime (`_ParentClass.name`), so it
+ // confirms the wrapper landed on the user's real class. Matched loosely
+ // because the transform renames the class it wraps to
+ // `__SENTRY_ORIGINAL_<name>__` and the bundler infers that name.
+ 'cloudflare.agent.class': expect.stringContaining(agentClass),
+ 'cloudflare.agent.name': instance,
+ }),
+ }),
+ );
+ });
+}
+
+test('applies plain Durable Object instrumentation to a non-Agent class', async ({ baseURL }) => {
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return event.contexts?.trace?.op === 'http.server' && (event.request?.url ?? '').includes('/plain-do');
+ });
+
+ const res = await fetch(`${baseURL}/plain-do`);
+ expect(res.status).toBe(200);
+
+ const transaction = await transactionPromise;
+
+ // A plain Durable Object must NOT pick up agent instrumentation: detection has
+ // to discriminate, not blanket-upgrade every `durable_objects` binding.
+ const agentSpans = (transaction.spans ?? []).filter(span => span.origin === 'auto.faas.cloudflare.agents');
+ expect(agentSpans).toEqual([]);
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tsconfig.json

@@ -0,0 +1,16 @@
+{
+ "compilerOptions": {
+ "target": "es2023",
+ "lib": ["es2023"],
+ "module": "es2022",
+ "moduleResolution": "bundler",
+ "types": ["@cloudflare/workers-types", "node"],
+ "skipLibCheck": true,
+ "noEmit": true,
+ "isolatedModules": true,
+ "allowSyntheticDefaultImports": true,
+ "forceConsistentCasingInFileNames": true,
+ "strict": true
+ },
+ "include": ["src/**/*", "vite.config.ts"]
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/vite.config.ts

@@ -0,0 +1,19 @@
+import { cloudflare } from '@cloudflare/vite-plugin';
+import { sentryCloudflareVitePlugin } from '@sentry/cloudflare/vite';
+import agents from 'agents/vite';
+import { defineConfig } from 'vite';
+
+// `agents()` supplies the TC39 decorator transform that `@callable()` needs.
+// `autoInstrumentation` is the plugin under test: it rewrites `src/index.ts` at
+// build time so the entry itself contains no Sentry calls.
+export default defineConfig({
+ plugins: [
+ agents(),
+ cloudflare(),
+ sentryCloudflareVitePlugin({
+ _experimental: {
+ autoInstrumentation: true,
+ },
+ }),
+ ],
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/wrangler.jsonc

@@ -0,0 +1,32 @@
+{
+"$schema": "node_modules/wrangler/config-schema.json",
+"name": "cloudflare-autoinstrument",
+"main": "src/index.ts",
+"compatibility_date": "2026-05-20",
+"compatibility_flags": ["nodejs_compat"],
+
+// Every class below is registered the same way — as a Durable Object binding.
+// An `agents` Agent *is* a Durable Object, so wrangler offers no way to say
+// "this one is an Agent". Only the base-class chain distinguishes them, which
+// is exactly what the plugin's detection has to work out at build time:
+//
+// MyAgent -> extends Agent (entry-local) => agent
+// MyChatAgent -> extends AIChatAgent (entry-local) => agent
+// DerivedAgent -> extends ./base#MyBase -> Agent => agent
+// PlainDO -> extends DurableObject => durableObject
+"durable_objects": {
+"bindings": [
+ { "name": "MyAgent", "class_name": "MyAgent" },
+ { "name": "MyChatAgent", "class_name": "MyChatAgent" },
+ { "name": "DerivedAgent", "class_name": "DerivedAgent" },
+ { "name": "PlainDO", "class_name": "PlainDO" },
+ ],
+ },
+
+"migrations": [
+ {
+"tag": "v1",
+"new_sqlite_classes": ["MyAgent", "MyChatAgent", "DerivedAgent", "PlainDO"],
+ },
+ ],
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/.gitignore

@@ -0,0 +1,4 @@
+dist
+.wrangler
+test-results
+pnpm-lock.yaml

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/package.json

@@ -0,0 +1,38 @@
+{
+ "name": "cloudflare-autoinstrument",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "dev": "vite dev",
+ "build": "vite build",
+ "preview": "wrangler dev --var \"E2E_TEST_DSN:$E2E_TEST_DSN\" --log-level=$(test $CI && echo 'none' || echo 'log')",
+ "test": "playwright test",
+ "typecheck": "tsc --noEmit",
+ "test:build": "pnpm install && pnpm build",
+ "test:assert": "pnpm typecheck && pnpm test"
+ },
+ "dependencies": {
+ "@cloudflare/ai-chat": "^0.10.0",
+ "@sentry/cloudflare": "file:../../packed/sentry-cloudflare-packed.tgz",
+ "agents": "^0.20.0"
+ },
+ "devDependencies": {
+ "@babel/core": "^8.0.1",
+ "@babel/plugin-proposal-decorators": "^8.0.2",
+ "@cloudflare/vite-plugin": "^1.47.0",
+ "@cloudflare/workers-types": "^5.20260727.1",
+ "@playwright/test": "~1.56.0",
+ "@sentry-internal/test-utils": "link:../../../test-utils",
+ "@types/node": "^26.1.2",
+ "@types/ws": "^8.18.1",
+ "typescript": "~6.0.3",
+ "vite": "^8.1.5",
+ "wrangler": "^4.114.0",
+ "ws": "^8.21.1"
+ },
+ "volta": {
+ "node": "24.15.0",
+ "extends": "../../package.json"
+ }
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/playwright.config.ts

@@ -0,0 +1,16 @@
+import { getPlaywrightConfig } from '@sentry-internal/test-utils';
+
+// `vite build` runs the Sentry auto-instrument transform over the worker entry;
+// `pnpm preview` (`wrangler dev`, following the vite plugin's `.wrangler/deploy`
+// redirect) serves the built output. The tests therefore assert on the wrapping
+// the plugin injected at build time, not on anything in the source entry.
+export default getPlaywrightConfig(
+ {
+ startCommand: 'pnpm preview',
+ port: 8787,
+ },
+ {
+ workers: '100%',
+ retries: 0,
+ },
+);

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/base.ts

@@ -0,0 +1,12 @@
+import { Agent } from 'agents';
+
+/**
+ * An Agent base class living outside the worker entry. `DerivedAgent` in
+ * `index.ts` extends this, so the plugin only learns it is an Agent by
+ * following the import into this module and resolving `MyBase -> Agent`.
+ */
+export class MyBase extends Agent<Env> {
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'derived' });
+ }
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/env.d.ts

@@ -0,0 +1,7 @@
+interfaceEnv{
+E2E_TEST_DSN: string;
+MyAgent: DurableObjectNamespace;
+MyChatAgent: DurableObjectNamespace;
+DerivedAgent: DurableObjectNamespace;
+PlainDO: DurableObjectNamespace;
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/index.ts

@@ -0,0 +1,73 @@
+import { AIChatAgent } from '@cloudflare/ai-chat';
+import { Agent, callable, routeAgentRequest } from 'agents';
+import { DurableObject } from 'cloudflare:workers';
+import { MyBase } from './base';
+
+// NOTE: this file deliberately contains NO `Sentry.*` calls and no import of
+// `@sentry/cloudflare`. Everything below is wrapped at build time by
+// `sentryCloudflareVitePlugin({ _experimental: { autoInstrumentation: true } })`,
+// which reads wrangler.jsonc, wraps the default export with `withSentry`, and
+// picks a wrapper per class: `instrumentAgentWithSentry` for the three Agents,
+// `instrumentDurableObjectWithSentry` for the plain Durable Object.
+//
+// Options come from `instrument.server.ts` next to this entry.
+
+/** Agent whose base class (`Agent`) is imported directly into the entry. */
+export class MyAgent extends Agent<Env> {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from MyAgent)`;
+ }
+
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'plain' });
+ }
+}
+
+/** Chat agent — `AIChatAgent` extends `Agent` inside `@cloudflare/ai-chat`. */
+export class MyChatAgent extends AIChatAgent<Env> {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from MyChatAgent)`;
+ }
+
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'chat' });
+ }
+}
+
+/** Agent whose base class lives in `./base` — resolvable only across modules. */
+export class DerivedAgent extends MyBase {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from DerivedAgent)`;
+ }
+}
+
+/**
+ * A genuine Durable Object. Configured identically to the Agents above, so it
+ * proves detection discriminates rather than upgrading every DO binding.
+ */
+export class PlainDO extends DurableObject<Env> {
+ async fetch(): Promise<Response> {
+ return Response.json({ durableObject: true });
+ }
+}
+
+export default {
+ async fetch(request: Request, env: Env): Promise<Response> {
+ const url = new URL(request.url);
+
+ if (url.pathname === '/plain-do') {
+ const stub = env.PlainDO.get(env.PlainDO.idFromName('do-instance'));
+ return stub.fetch(request);
+ }
+
+ const agentResponse = await routeAgentRequest(request, env);
+ if (agentResponse) {
+ return agentResponse;
+ }
+
+ return new Response('Not found', { status: 404 });
+ },
+} satisfies ExportedHandler<Env>;

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/instrument.server.ts

@@ -0,0 +1,14 @@
+// The auto-instrument plugin picks this file up by convention (it sits next to
+// the worker entry named in wrangler's `main`) and imports its default export as
+// the options callback for every wrapper it injects.
+export default (env: Env) => ({
+ traceLifecycle: 'static' as const,
+ dsn: env.E2E_TEST_DSN,
+ environment: 'qa',
+ tunnel: 'http://localhost:3031/',
+ tracesSampleRate: 1.0,
+ enableRpcTracePropagation: true,
+ transportOptions: {
+ bufferSize: 1000,
+ },
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/start-event-proxy.mjs

@@ -0,0 +1,6 @@
+import{startEventProxyServer}from'@sentry-internal/test-utils';
+
+startEventProxyServer({
+port: 3031,
+proxyServerName: 'cloudflare-autoinstrument',
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tests/agent-socket.ts

@@ -0,0 +1,46 @@
+import WebSocket from 'ws';
+
+type AgentReply = { type?: string; id?: string; done?: boolean; result?: unknown };
+
+/**
+ * Opens a WebSocket to `/agents/<binding>/<instance>`, sends one RPC frame, and
+ * resolves with the reply's `result` — the method's return value — once it arrives.
+ */
+export function callRpc(
+ baseURL: string,
+ options: { binding: string; instance: string; method: string; args: unknown[] },
+): Promise<unknown> {
+ const id = `rpc-${options.method}`;
+ const frame = { type: 'rpc', id, method: options.method, args: options.args };
+ const wsUrl = `${baseURL.replace(/^http/, 'ws')}/agents/${options.binding}/${options.instance}`;
+
+ return new Promise<unknown>((resolveSocket, rejectSocket) => {
+ const socket = new WebSocket(wsUrl);
+ const timeout = setTimeout(() => {
+ socket.close();
+ rejectSocket(new Error(`Timed out waiting for RPC reply to "${options.method}"`));
+ }, 15_000);
+
+ socket.on('open', () => {
+ socket.send(JSON.stringify(frame));
+ });
+
+ socket.on('message', data => {
+ try {
+ const parsed = JSON.parse(data.toString()) as AgentReply;
+ if (parsed.type === 'rpc' && parsed.id === id && parsed.done) {
+ clearTimeout(timeout);
+ socket.close();
+ resolveSocket(parsed.result);
+ }
+ } catch {
+ // Ignore non-JSON / unrelated frames.
+ }
+ });
+
+ socket.on('error', err => {
+ clearTimeout(timeout);
+ rejectSocket(err);
+ });
+ });
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tests/autoinstrument.test.ts

@@ -0,0 +1,99 @@
+import { expect, test } from '@playwright/test';
+import { waitForTransaction } from '@sentry-internal/test-utils';
+import { callRpc } from './agent-socket';
+
+// The worker entry (`src/index.ts`) contains no Sentry calls at all — every
+// wrapper below was injected by the Vite auto-instrument plugin at build time.
+// Any transaction arriving here therefore proves the injection happened.
+
+test('wraps the default export with withSentry (options from instrument.server.ts)', async ({ baseURL }) => {
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return event.contexts?.trace?.op === 'http.server' && (event.request?.url ?? '').includes('/plain-do');
+ });
+
+ const res = await fetch(`${baseURL}/plain-do`);
+ expect(res.status).toBe(200);
+ await expect(res.json()).resolves.toEqual({ durableObject: true });
+
+ const transaction = await transactionPromise;
+
+ expect(transaction.contexts?.trace?.origin).toBe('auto.http.cloudflare');
+ // `environment: 'qa'` is only set in `instrument.server.ts`, so seeing it here
+ // proves the plugin sourced its options callback from that file rather than
+ // falling back to reading configuration off `env`.
+ expect(transaction.environment).toBe('qa');
+});
+
+// Each of these three classes is registered in wrangler.jsonc exactly like the
+// plain Durable Object below — only the base-class chain marks them as Agents.
+// An `rpc` span with origin `auto.faas.cloudflare.agents` is produced solely by
+// `instrumentAgentWithSentry`, so its presence is what distinguishes a correct
+// agent upgrade from a plain `instrumentDurableObjectWithSentry` wrap.
+for (const { title, binding, agentClass } of [
+ {
+ title: 'an Agent subclass declared in the entry',
+ binding: 'my-agent',
+ agentClass: 'MyAgent',
+ },
+ {
+ title: 'an AIChatAgent subclass declared in the entry',
+ binding: 'my-chat-agent',
+ agentClass: 'MyChatAgent',
+ },
+ {
+ title: 'an Agent subclass whose base class lives in another module',
+ binding: 'derived-agent',
+ agentClass: 'DerivedAgent',
+ },
+]) {
+ test(`applies agent instrumentation to ${title}`, async ({ baseURL }) => {
+ const instance = `${binding}-instance`;
+
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return (
+ event.transaction === 'webSocketMessage' &&
+ (event.spans ?? []).some(span => span.op === 'rpc' && span.description === 'greet')
+ );
+ });
+
+ // Each agent's greet() returns a string naming its class, so the reply
+ // identifies exactly which class handled the call.
+ const reply = await callRpc(baseURL!, { binding, instance, method: 'greet', args: ['World'] });
+ expect(reply).toBe(`Hello, World! (from ${agentClass})`);
+
+ const transaction = await transactionPromise;
+ const rpcSpan = (transaction.spans ?? []).find(span => span.op === 'rpc' && span.description === 'greet');
+
+ expect(rpcSpan).toEqual(
+ expect.objectContaining({
+ op: 'rpc',
+ description: 'greet',
+ origin: 'auto.faas.cloudflare.agents',
+ data: expect.objectContaining({
+ // Read back off the instance at runtime (`_ParentClass.name`), so it
+ // confirms the wrapper landed on the user's real class. Matched loosely
+ // because the transform renames the class it wraps to
+ // `__SENTRY_ORIGINAL_<name>__` and the bundler infers that name.
+ 'cloudflare.agent.class': expect.stringContaining(agentClass),
+ 'cloudflare.agent.name': instance,
+ }),
+ }),
+ );
+ });
+}
+
+test('applies plain Durable Object instrumentation to a non-Agent class', async ({ baseURL }) => {
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return event.contexts?.trace?.op === 'http.server' && (event.request?.url ?? '').includes('/plain-do');
+ });
+
+ const res = await fetch(`${baseURL}/plain-do`);
+ expect(res.status).toBe(200);
+
+ const transaction = await transactionPromise;
+
+ // A plain Durable Object must NOT pick up agent instrumentation: detection has
+ // to discriminate, not blanket-upgrade every `durable_objects` binding.
+ const agentSpans = (transaction.spans ?? []).filter(span => span.origin === 'auto.faas.cloudflare.agents');
+ expect(agentSpans).toEqual([]);
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tsconfig.json

@@ -0,0 +1,16 @@
+{
+ "compilerOptions": {
+ "target": "es2023",
+ "lib": ["es2023"],
+ "module": "es2022",
+ "moduleResolution": "bundler",
+ "types": ["@cloudflare/workers-types", "node"],
+ "skipLibCheck": true,
+ "noEmit": true,
+ "isolatedModules": true,
+ "allowSyntheticDefaultImports": true,
+ "forceConsistentCasingInFileNames": true,
+ "strict": true
+ },
+ "include": ["src/**/*", "vite.config.ts"]
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/vite.config.ts

@@ -0,0 +1,19 @@
+import { cloudflare } from '@cloudflare/vite-plugin';
+import { sentryCloudflareVitePlugin } from '@sentry/cloudflare/vite';
+import agents from 'agents/vite';
+import { defineConfig } from 'vite';
+
+// `agents()` supplies the TC39 decorator transform that `@callable()` needs.
+// `autoInstrumentation` is the plugin under test: it rewrites `src/index.ts` at
+// build time so the entry itself contains no Sentry calls.
+export default defineConfig({
+ plugins: [
+ agents(),
+ cloudflare(),
+ sentryCloudflareVitePlugin({
+ _experimental: {
+ autoInstrumentation: true,
+ },
+ }),
+ ],
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/wrangler.jsonc

@@ -0,0 +1,32 @@
+{
+"$schema": "node_modules/wrangler/config-schema.json",
+"name": "cloudflare-autoinstrument",
+"main": "src/index.ts",
+"compatibility_date": "2026-05-20",
+"compatibility_flags": ["nodejs_compat"],
+
+// Every class below is registered the same way — as a Durable Object binding.
+// An `agents` Agent *is* a Durable Object, so wrangler offers no way to say
+// "this one is an Agent". Only the base-class chain distinguishes them, which
+// is exactly what the plugin's detection has to work out at build time:
+//
+// MyAgent -> extends Agent (entry-local) => agent
+// MyChatAgent -> extends AIChatAgent (entry-local) => agent
+// DerivedAgent -> extends ./base#MyBase -> Agent => agent
+// PlainDO -> extends DurableObject => durableObject
+"durable_objects": {
+"bindings": [
+ { "name": "MyAgent", "class_name": "MyAgent" },
+ { "name": "MyChatAgent", "class_name": "MyChatAgent" },
+ { "name": "DerivedAgent", "class_name": "DerivedAgent" },
+ { "name": "PlainDO", "class_name": "PlainDO" },
+ ],
+ },
+
+"migrations": [
+ {
+"tag": "v1",
+"new_sqlite_classes": ["MyAgent", "MyChatAgent", "DerivedAgent", "PlainDO"],
+ },
+ ],
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/.gitignore

@@ -0,0 +1,4 @@
+dist
+.wrangler
+test-results
+pnpm-lock.yaml

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/package.json

@@ -0,0 +1,38 @@
+{
+ "name": "cloudflare-autoinstrument",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "dev": "vite dev",
+ "build": "vite build",
+ "preview": "wrangler dev --var \"E2E_TEST_DSN:$E2E_TEST_DSN\" --log-level=$(test $CI && echo 'none' || echo 'log')",
+ "test": "playwright test",
+ "typecheck": "tsc --noEmit",
+ "test:build": "pnpm install && pnpm build",
+ "test:assert": "pnpm typecheck && pnpm test"
+ },
+ "dependencies": {
+ "@cloudflare/ai-chat": "^0.10.0",
+ "@sentry/cloudflare": "file:../../packed/sentry-cloudflare-packed.tgz",
+ "agents": "^0.20.0"
+ },
+ "devDependencies": {
+ "@babel/core": "^8.0.1",
+ "@babel/plugin-proposal-decorators": "^8.0.2",
+ "@cloudflare/vite-plugin": "^1.47.0",
+ "@cloudflare/workers-types": "^5.20260727.1",
+ "@playwright/test": "~1.56.0",
+ "@sentry-internal/test-utils": "link:../../../test-utils",
+ "@types/node": "^26.1.2",
+ "@types/ws": "^8.18.1",
+ "typescript": "~6.0.3",
+ "vite": "^8.1.5",
+ "wrangler": "^4.114.0",
+ "ws": "^8.21.1"
+ },
+ "volta": {
+ "node": "24.15.0",
+ "extends": "../../package.json"
+ }
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/playwright.config.ts

@@ -0,0 +1,16 @@
+import { getPlaywrightConfig } from '@sentry-internal/test-utils';
+
+// `vite build` runs the Sentry auto-instrument transform over the worker entry;
+// `pnpm preview` (`wrangler dev`, following the vite plugin's `.wrangler/deploy`
+// redirect) serves the built output. The tests therefore assert on the wrapping
+// the plugin injected at build time, not on anything in the source entry.
+export default getPlaywrightConfig(
+ {
+ startCommand: 'pnpm preview',
+ port: 8787,
+ },
+ {
+ workers: '100%',
+ retries: 0,
+ },
+);

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/base.ts

@@ -0,0 +1,12 @@
+import { Agent } from 'agents';
+
+/**
+ * An Agent base class living outside the worker entry. `DerivedAgent` in
+ * `index.ts` extends this, so the plugin only learns it is an Agent by
+ * following the import into this module and resolving `MyBase -> Agent`.
+ */
+export class MyBase extends Agent<Env> {
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'derived' });
+ }
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/env.d.ts

@@ -0,0 +1,7 @@
+interfaceEnv{
+E2E_TEST_DSN: string;
+MyAgent: DurableObjectNamespace;
+MyChatAgent: DurableObjectNamespace;
+DerivedAgent: DurableObjectNamespace;
+PlainDO: DurableObjectNamespace;
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/index.ts

@@ -0,0 +1,73 @@
+import { AIChatAgent } from '@cloudflare/ai-chat';
+import { Agent, callable, routeAgentRequest } from 'agents';
+import { DurableObject } from 'cloudflare:workers';
+import { MyBase } from './base';
+
+// NOTE: this file deliberately contains NO `Sentry.*` calls and no import of
+// `@sentry/cloudflare`. Everything below is wrapped at build time by
+// `sentryCloudflareVitePlugin({ _experimental: { autoInstrumentation: true } })`,
+// which reads wrangler.jsonc, wraps the default export with `withSentry`, and
+// picks a wrapper per class: `instrumentAgentWithSentry` for the three Agents,
+// `instrumentDurableObjectWithSentry` for the plain Durable Object.
+//
+// Options come from `instrument.server.ts` next to this entry.
+
+/** Agent whose base class (`Agent`) is imported directly into the entry. */
+export class MyAgent extends Agent<Env> {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from MyAgent)`;
+ }
+
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'plain' });
+ }
+}
+
+/** Chat agent — `AIChatAgent` extends `Agent` inside `@cloudflare/ai-chat`. */
+export class MyChatAgent extends AIChatAgent<Env> {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from MyChatAgent)`;
+ }
+
+ async onRequest(): Promise<Response> {
+ return Response.json({ agent: 'chat' });
+ }
+}
+
+/** Agent whose base class lives in `./base` — resolvable only across modules. */
+export class DerivedAgent extends MyBase {
+ @callable()
+ async greet(name: string): Promise<string> {
+ return `Hello, ${name}! (from DerivedAgent)`;
+ }
+}
+
+/**
+ * A genuine Durable Object. Configured identically to the Agents above, so it
+ * proves detection discriminates rather than upgrading every DO binding.
+ */
+export class PlainDO extends DurableObject<Env> {
+ async fetch(): Promise<Response> {
+ return Response.json({ durableObject: true });
+ }
+}
+
+export default {
+ async fetch(request: Request, env: Env): Promise<Response> {
+ const url = new URL(request.url);
+
+ if (url.pathname === '/plain-do') {
+ const stub = env.PlainDO.get(env.PlainDO.idFromName('do-instance'));
+ return stub.fetch(request);
+ }
+
+ const agentResponse = await routeAgentRequest(request, env);
+ if (agentResponse) {
+ return agentResponse;
+ }
+
+ return new Response('Not found', { status: 404 });
+ },
+} satisfies ExportedHandler<Env>;

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/src/instrument.server.ts

@@ -0,0 +1,14 @@
+// The auto-instrument plugin picks this file up by convention (it sits next to
+// the worker entry named in wrangler's `main`) and imports its default export as
+// the options callback for every wrapper it injects.
+export default (env: Env) => ({
+ traceLifecycle: 'static' as const,
+ dsn: env.E2E_TEST_DSN,
+ environment: 'qa',
+ tunnel: 'http://localhost:3031/',
+ tracesSampleRate: 1.0,
+ enableRpcTracePropagation: true,
+ transportOptions: {
+ bufferSize: 1000,
+ },
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/start-event-proxy.mjs

@@ -0,0 +1,6 @@
+import{startEventProxyServer}from'@sentry-internal/test-utils';
+
+startEventProxyServer({
+port: 3031,
+proxyServerName: 'cloudflare-autoinstrument',
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tests/agent-socket.ts

@@ -0,0 +1,46 @@
+import WebSocket from 'ws';
+
+type AgentReply = { type?: string; id?: string; done?: boolean; result?: unknown };
+
+/**
+ * Opens a WebSocket to `/agents/<binding>/<instance>`, sends one RPC frame, and
+ * resolves with the reply's `result` — the method's return value — once it arrives.
+ */
+export function callRpc(
+ baseURL: string,
+ options: { binding: string; instance: string; method: string; args: unknown[] },
+): Promise<unknown> {
+ const id = `rpc-${options.method}`;
+ const frame = { type: 'rpc', id, method: options.method, args: options.args };
+ const wsUrl = `${baseURL.replace(/^http/, 'ws')}/agents/${options.binding}/${options.instance}`;
+
+ return new Promise<unknown>((resolveSocket, rejectSocket) => {
+ const socket = new WebSocket(wsUrl);
+ const timeout = setTimeout(() => {
+ socket.close();
+ rejectSocket(new Error(`Timed out waiting for RPC reply to "${options.method}"`));
+ }, 15_000);
+
+ socket.on('open', () => {
+ socket.send(JSON.stringify(frame));
+ });
+
+ socket.on('message', data => {
+ try {
+ const parsed = JSON.parse(data.toString()) as AgentReply;
+ if (parsed.type === 'rpc' && parsed.id === id && parsed.done) {
+ clearTimeout(timeout);
+ socket.close();
+ resolveSocket(parsed.result);
+ }
+ } catch {
+ // Ignore non-JSON / unrelated frames.
+ }
+ });
+
+ socket.on('error', err => {
+ clearTimeout(timeout);
+ rejectSocket(err);
+ });
+ });
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tests/autoinstrument.test.ts

@@ -0,0 +1,99 @@
+import { expect, test } from '@playwright/test';
+import { waitForTransaction } from '@sentry-internal/test-utils';
+import { callRpc } from './agent-socket';
+
+// The worker entry (`src/index.ts`) contains no Sentry calls at all — every
+// wrapper below was injected by the Vite auto-instrument plugin at build time.
+// Any transaction arriving here therefore proves the injection happened.
+
+test('wraps the default export with withSentry (options from instrument.server.ts)', async ({ baseURL }) => {
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return event.contexts?.trace?.op === 'http.server' && (event.request?.url ?? '').includes('/plain-do');
+ });
+
+ const res = await fetch(`${baseURL}/plain-do`);
+ expect(res.status).toBe(200);
+ await expect(res.json()).resolves.toEqual({ durableObject: true });
+
+ const transaction = await transactionPromise;
+
+ expect(transaction.contexts?.trace?.origin).toBe('auto.http.cloudflare');
+ // `environment: 'qa'` is only set in `instrument.server.ts`, so seeing it here
+ // proves the plugin sourced its options callback from that file rather than
+ // falling back to reading configuration off `env`.
+ expect(transaction.environment).toBe('qa');
+});
+
+// Each of these three classes is registered in wrangler.jsonc exactly like the
+// plain Durable Object below — only the base-class chain marks them as Agents.
+// An `rpc` span with origin `auto.faas.cloudflare.agents` is produced solely by
+// `instrumentAgentWithSentry`, so its presence is what distinguishes a correct
+// agent upgrade from a plain `instrumentDurableObjectWithSentry` wrap.
+for (const { title, binding, agentClass } of [
+ {
+ title: 'an Agent subclass declared in the entry',
+ binding: 'my-agent',
+ agentClass: 'MyAgent',
+ },
+ {
+ title: 'an AIChatAgent subclass declared in the entry',
+ binding: 'my-chat-agent',
+ agentClass: 'MyChatAgent',
+ },
+ {
+ title: 'an Agent subclass whose base class lives in another module',
+ binding: 'derived-agent',
+ agentClass: 'DerivedAgent',
+ },
+]) {
+ test(`applies agent instrumentation to ${title}`, async ({ baseURL }) => {
+ const instance = `${binding}-instance`;
+
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return (
+ event.transaction === 'webSocketMessage' &&
+ (event.spans ?? []).some(span => span.op === 'rpc' && span.description === 'greet')
+ );
+ });
+
+ // Each agent's greet() returns a string naming its class, so the reply
+ // identifies exactly which class handled the call.
+ const reply = await callRpc(baseURL!, { binding, instance, method: 'greet', args: ['World'] });
+ expect(reply).toBe(`Hello, World! (from ${agentClass})`);
+
+ const transaction = await transactionPromise;
+ const rpcSpan = (transaction.spans ?? []).find(span => span.op === 'rpc' && span.description === 'greet');
+
+ expect(rpcSpan).toEqual(
+ expect.objectContaining({
+ op: 'rpc',
+ description: 'greet',
+ origin: 'auto.faas.cloudflare.agents',
+ data: expect.objectContaining({
+ // Read back off the instance at runtime (`_ParentClass.name`), so it
+ // confirms the wrapper landed on the user's real class. Matched loosely
+ // because the transform renames the class it wraps to
+ // `__SENTRY_ORIGINAL_<name>__` and the bundler infers that name.
+ 'cloudflare.agent.class': expect.stringContaining(agentClass),
+ 'cloudflare.agent.name': instance,
+ }),
+ }),
+ );
+ });
+}
+
+test('applies plain Durable Object instrumentation to a non-Agent class', async ({ baseURL }) => {
+ const transactionPromise = waitForTransaction('cloudflare-autoinstrument', event => {
+ return event.contexts?.trace?.op === 'http.server' && (event.request?.url ?? '').includes('/plain-do');
+ });
+
+ const res = await fetch(`${baseURL}/plain-do`);
+ expect(res.status).toBe(200);
+
+ const transaction = await transactionPromise;
+
+ // A plain Durable Object must NOT pick up agent instrumentation: detection has
+ // to discriminate, not blanket-upgrade every `durable_objects` binding.
+ const agentSpans = (transaction.spans ?? []).filter(span => span.origin === 'auto.faas.cloudflare.agents');
+ expect(agentSpans).toEqual([]);
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/tsconfig.json

@@ -0,0 +1,16 @@
+{
+ "compilerOptions": {
+ "target": "es2023",
+ "lib": ["es2023"],
+ "module": "es2022",
+ "moduleResolution": "bundler",
+ "types": ["@cloudflare/workers-types", "node"],
+ "skipLibCheck": true,
+ "noEmit": true,
+ "isolatedModules": true,
+ "allowSyntheticDefaultImports": true,
+ "forceConsistentCasingInFileNames": true,
+ "strict": true
+ },
+ "include": ["src/**/*", "vite.config.ts"]
+}

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/vite.config.ts

@@ -0,0 +1,19 @@
+import { cloudflare } from '@cloudflare/vite-plugin';
+import { sentryCloudflareVitePlugin } from '@sentry/cloudflare/vite';
+import agents from 'agents/vite';
+import { defineConfig } from 'vite';
+
+// `agents()` supplies the TC39 decorator transform that `@callable()` needs.
+// `autoInstrumentation` is the plugin under test: it rewrites `src/index.ts` at
+// build time so the entry itself contains no Sentry calls.
+export default defineConfig({
+ plugins: [
+ agents(),
+ cloudflare(),
+ sentryCloudflareVitePlugin({
+ _experimental: {
+ autoInstrumentation: true,
+ },
+ }),
+ ],
+});

dev-packages/e2e-tests/test-applications/cloudflare-autoinstrument/wrangler.jsonc

@@ -0,0 +1,32 @@
+{
+"$schema": "node_modules/wrangler/config-schema.json",
+"name": "cloudflare-autoinstrument",
+"main": "src/index.ts",
+"compatibility_date": "2026-05-20",
+"compatibility_flags": ["nodejs_compat"],
+
+// Every class below is registered the same way — as a Durable Object binding.
+// An `agents` Agent *is* a Durable Object, so wrangler offers no way to say
+// "this one is an Agent". Only the base-class chain distinguishes them, which
+// is exactly what the plugin's detection has to work out at build time:
+//
+// MyAgent -> extends Agent (entry-local) => agent
+// MyChatAgent -> extends AIChatAgent (entry-local) => agent
+// DerivedAgent -> extends ./base#MyBase -> Agent => agent
+// PlainDO -> extends DurableObject => durableObject
+"durable_objects": {
+"bindings": [
+ { "name": "MyAgent", "class_name": "MyAgent" },
+ { "name": "MyChatAgent", "class_name": "MyChatAgent" },
+ { "name": "DerivedAgent", "class_name": "DerivedAgent" },
+ { "name": "PlainDO", "class_name": "PlainDO" },
+ ],
+ },
+
+"migrations": [
+ {
+"tag": "v1",
+"new_sqlite_classes": ["MyAgent", "MyChatAgent", "DerivedAgent", "PlainDO"],
+ },
+ ],
+}