test(e2e): Add a cloudflare-flue end-to-end application (#24477)

Stacked on #24476 — review that first.

A `flue init` Cloudflare app with no `instrument()` call anywhere:
registration comes from the build, so any `gen_ai` span here is itself
proof the auto-wiring worked. Covers AI spans, tool-error capture, a
manual span nesting under its tool, and an orchestrion `dataloader` span
in the agent's trace.

Secrets go through `.dev.vars` rather than `--var` because Flue resolves
the provider key inside `pi-ai` at runtime, leaving nothing for Vite to
inline, and `vite preview` is what serves the worker with Flue's
generated Durable Object config.

Two Flue constraints the app works around, both commented in place:
`agents` is imported by Flue's generated worker entry without being
declared, so it only resolves under npm's hoisting and needs declaring
for pnpm; and the `'use agent'` scan parses every source file as plain
JavaScript, so generics and return types fail the build.

_Worth a docs note_: the Sentry wrapper has to be re-exported as
`cloudflare` from the agent module. Defining it elsewhere leaves the
Durable Object unwrapped — the agent runs, turns settle, and nothing is
traced.

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: RulaKhaled

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

@@ -0,0 +1,5 @@
+import { defineConfig } from '@flue/runtime/config';
+
+export default defineConfig({
+  target: 'cloudflare',
+});

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

@@ -0,0 +1,41 @@
+{
+  "name": "cloudflare-flue",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "vite build",
+    "preview": "vite preview --port 4112",
+    "typecheck": "tsc --noEmit",
+    "clean": "npx rimraf node_modules dist .wrangler pnpm-lock.yaml",
+    "test:build": "pnpm install && OPENROUTER_API_KEY=$E2E_OPENROUTER_API_KEY pnpm build",
+    "test:assert": "pnpm test:prod",
+    "test:prod": "TEST_ENV=production OPENROUTER_API_KEY=$E2E_OPENROUTER_API_KEY playwright test"
+  },
+  "dependencies": {
+    "@flue/runtime": "2.0.5",
+    "@sentry/cloudflare": "file:../../packed/sentry-cloudflare-packed.tgz",
+    "agents": "0.20.1",
+    "dataloader": "~2.2.3",
+    "hono": "^4.13.8",
+    "valibot": "~1.5.0"
+  },
+  "devDependencies": {
+    "@cloudflare/vite-plugin": "1.52.0",
+    "@cloudflare/workers-types": "^4.20260426.0",
+    "@flue/cli": "2.0.5",
+    "@flue/vite": "2.0.5",
+    "@playwright/test": "~1.63.0",
+    "@sentry-internal/test-utils": "link:../../../test-utils",
+    "typescript": "^5.5.2",
+    "vite": "7.3.5",
+    "wrangler": "^4.86.0"
+  },
+  "volta": {
+    "node": "24.15.0",
+    "extends": "../../package.json"
+  },
+  "sentryTest": {
+    "optional": true
+  }
+}

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

@@ -0,0 +1,16 @@
+import { getPlaywrightConfig } from '@sentry-internal/test-utils';
+
+const testEnv = process.env.TEST_ENV;
+
+if (!testEnv) {
+  throw new Error('No test env defined');
+}
+
+const config = getPlaywrightConfig(
+  { startCommand: 'pnpm preview', port: 4112 },
+  // Each test drives a real OpenRouter turn and then waits for the spans to flush, which does not
+  // fit the default 30s timeout when the provider is slow.
+  { timeout: 90_000 },
+);
+
+export default config;

dev-packages/e2e-tests/test-applications/cloudflare-flue/src/agents/hello.ts

@@ -0,0 +1,50 @@
+'use agent';
+import { useModel, useTool } from '@flue/runtime';
+import * as Sentry from '@sentry/cloudflare';
+import * as v from 'valibot';
+import { createItemLoader } from '../loaders.ts';
+
+// Flue applies the agent's Durable Object wrapper from this re-export.
+export { cloudflare } from '../sentry.ts';
+
+// The `'use agent'` directive is how `@flue/vite` binds an identity to this module at build time.
+export function Hello() {
+  useModel('openrouter/anthropic/claude-haiku-4.5');
+
+  useTool({
+    name: 'get_weather',
+    description: 'Get the current weather for a city.',
+    input: v.object({ city: v.string() }),
+    // Wrapped in a manual span: Flue runs the tool while the SDK's `execute_tool` span is active,
+    // so this should nest directly under it rather than landing beside it.
+    run: ({ city }) =>
+      Sentry.startSpan({ name: 'resolve-weather', attributes: { 'weather.source': 'static-table' } }, () => {
+        return `It is 21 degrees and sunny in ${city}.`;
+      }),
+  });
+
+  // Called from inside a tool so the dataloader span lands in the agent's trace beside the AI
+  // spans. Constructed per execution: a module-level loader caches its keys, so a second call
+  // would skip the batch function and emit no span.
+  useTool({
+    name: 'count_items',
+    description: 'Count items by loading them. Call this when the user asks to count items.',
+    input: v.object({}),
+    run: async () => {
+      const loader = createItemLoader();
+      const doubled = await Promise.all([loader.load(1), loader.load(2), loader.load(3)]);
+      return `Loaded ${doubled.length} items: ${doubled.join(', ')}.`;
+    },
+  });
+
+  useTool({
+    name: 'fail_now',
+    description: 'Always throws an error. Call this when the user asks to trigger a failure.',
+    input: v.object({}),
+    run: () => {
+      throw new Error('Intentional flue tool failure');
+    },
+  });
+
+  return 'You are a helpful assistant. Use get_weather when asked about weather, count_items when asked to count items, and fail_now when asked to fail.';
+}

dev-packages/e2e-tests/test-applications/cloudflare-flue/src/app.ts

@@ -0,0 +1,9 @@
+import { createAgentRouter } from '@flue/runtime/routing';
+import { Hono } from 'hono';
+import { Hello } from './agents/hello.ts';
+
+const app = new Hono();
+
+app.route('/agents/hello', createAgentRouter(Hello));
+
+export default app;

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

@@ -0,0 +1,4 @@
+// Worker-level Cloudflare code would live here; the Sentry wrapper is in `src/sentry.ts` and is
+// re-exported from the agent module, which is how Flue applies it to the agent's Durable Object.
+
+export {};

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

@@ -0,0 +1,4 @@
+interface Env {
+  E2E_TEST_DSN: string;
+  OPENROUTER_API_KEY: string;
+}

dev-packages/e2e-tests/test-applications/cloudflare-flue/src/loaders.ts

@@ -0,0 +1,13 @@
+import DataLoader from 'dataloader';
+
+/**
+ * Built per call, not shared: a module-level loader caches its keys, so a second `count_items` would
+ * skip the batch function and emit no span.
+ *
+ * Deliberately free of type annotations and generics. Flue's build scans every source file looking
+ * for `'use agent'` modules and parses them as plain JavaScript, so a return type or a
+ * `new DataLoader<number, number>(…)` fails the build with a parse error pointing at this file.
+ */
+export function createItemLoader() {
+  return new DataLoader(async keys => keys.map(key => Number(key) * 2));
+}

dev-packages/e2e-tests/test-applications/cloudflare-flue/src/sentry.ts

@@ -0,0 +1,21 @@
+import { extend } from '@flue/runtime/cloudflare';
+import * as Sentry from '@sentry/cloudflare';
+
+// Each Flue agent runs in its own Durable Object, so the DO class is what has to be wrapped for
+// `Sentry.init` to run and spans to be flushed. The agent module re-exports this as `cloudflare`,
+// which is how Flue picks it up — defining it here alone does nothing.
+//
+// There is deliberately no `instrument()` call in this app: registering the Flue instrumentation is
+// what `@sentry/cloudflare/vite` does at build time, and these tests exist to prove it.
+export const cloudflare = extend({
+  wrap: Final =>
+    Sentry.instrumentDurableObjectWithSentry(
+      (env: Env) => ({
+        dsn: env.E2E_TEST_DSN,
+        environment: 'qa',
+        tunnel: 'http://localhost:3031/', // proxy server
+        tracesSampleRate: 1.0,
+      }),
+      Final,
+    ),
+});

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

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