test(e2e): Add a node-flue end-to-end application (#24377)

Stacked on #24266 — review that first, this is the e2e app only.

The node-integration-test calls `__flueBindAgentModule` by hand,
standing in for what `@flue/vite` does from the `'use agent'` directive,
so it can't show whether a scaffolded app actually works. This is `flue
init` output, built and served the way a user runs it, against a real
provider.

Covered, in both dev and prod and in both the base and orchestrion
variants:

- `invoke_agent` / `chat` / `execute_tool` with usage and cost
- a thrown tool error becoming an issue
- a manual span inside a tool nesting under `execute_tool`
- an orchestrion-instrumented `dataloader` span landing in the agent's
trace
- the provider's `http.client` call nesting inside `chat`

The loader runs inside a tool rather than a route so its span shares the
agent's trace. No build externals are needed unlike `node-eve` — a Flue
node build leaves dependencies as bare specifiers, so `dataloader` stays
a real module for the transform to hook. `@flue/*` is pinned because the
internal registry proxy 403s on releases it hasn't scanned.

_Found_: a thrown tool error produced an errored span and no issue at
all, since Flue catches the throw and hands it back to the model as a
tool result. Fixed in #24265.

---------

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

Author: RulaKhaled

dev-packages/e2e-tests/test-applications/node-flue/.gitignore

@@ -0,0 +1,7 @@
+node_modules
+dist
+.flue
+*.tsbuildinfo
+results.junit.xml
+test-results
+playwright-report

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

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

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

@@ -0,0 +1,50 @@
+{
+  "name": "node-flue",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "NODE_OPTIONS='--import=@sentry/node/import' vite dev --port 3030",
+    "build": "vite build",
+    "start": "NODE_OPTIONS='--import=@sentry/node/import' PORT=3030 node dist/server.mjs",
+    "clean": "npx rimraf node_modules dist pnpm-lock.yaml",
+    "test:build": "pnpm install && pnpm build",
+    "test:build-latest": "pnpm install && pnpm add @flue/runtime@latest @flue/vite@latest @flue/cli@latest && pnpm build",
+    "test:assert": "pnpm test:prod && pnpm test:dev",
+    "test:prod": "OPENROUTER_API_KEY=$E2E_OPENROUTER_API_KEY TEST_ENV=production playwright test",
+    "test:dev": "OPENROUTER_API_KEY=$E2E_OPENROUTER_API_KEY TEST_ENV=development playwright test"
+  },
+  "dependencies": {
+    "@flue/runtime": "2.0.5",
+    "@sentry/node": "file:../../packed/sentry-node-packed.tgz",
+    "dataloader": "^2.2.3",
+    "hono": "^4.7.0",
+    "valibot": "^1.5.0"
+  },
+  "devDependencies": {
+    "@flue/cli": "2.0.5",
+    "@flue/vite": "2.0.5",
+    "@playwright/test": "~1.56.0",
+    "@sentry-internal/test-utils": "link:../../../test-utils",
+    "@sentry/core": "file:../../packed/sentry-core-packed.tgz",
+    "@types/node": "24.x",
+    "typescript": "~5.9.0",
+    "vite": "^8.0.14"
+  },
+  "engines": {
+    "node": "24.x"
+  },
+  "volta": {
+    "node": "24.15.0",
+    "extends": "../../package.json"
+  },
+  "sentryTest": {
+    "optional": true,
+    "optionalVariants": [
+      {
+        "build-command": "pnpm test:build-latest",
+        "label": "node-flue (latest)"
+      }
+    ]
+  }
+}

dev-packages/e2e-tests/test-applications/node-flue/playwright.config.mjs

@@ -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: testEnv === 'development' ? 'pnpm dev' : 'pnpm start' },
+  // Each test drives a real OpenRouter tool-calling 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/node-flue/sentry-init.ts

@@ -0,0 +1,13 @@
+import { instrument } from '@flue/runtime';
+import * as Sentry from '@sentry/node';
+
+// Imported for its side effects as the first line of `src/app.ts`, which is how a Flue app sets
+// Sentry up: there is no framework-owned instrumentation hook to auto-discover.
+Sentry.init({
+  environment: 'qa',
+  dsn: process.env.E2E_TEST_DSN,
+  tunnel: 'http://localhost:3031/', // proxy server
+  tracesSampleRate: 1.0,
+});
+
+instrument(Sentry.createFlueInstrumentation());

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

@@ -0,0 +1,53 @@
+'use agent';
+import { useModel, useTool } from '@flue/runtime';
+import * as Sentry from '@sentry/node';
+import * as v from 'valibot';
+import DataLoader from 'dataloader';
+
+// The `'use agent'` directive is how `@flue/vite` finds this module and binds an identity to it at
+// build time. That binding is the part a hand-written scenario cannot reproduce, so it is the main
+// reason this app exists alongside the node-integration-test suite.
+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', 'weather.city': city } },
+        () => {
+          return `It is 21 degrees and sunny in ${city}.`;
+        },
+      ),
+  });
+
+  // Called from inside a tool on purpose: the dataloader span then lands under `execute_tool` in
+  // the agent's trace, which is what "captured alongside the AI spans" has to mean.
+  useTool({
+    name: 'count_items',
+    description: 'Count items by loading them. Call this when the user asks to count items.',
+    input: v.object({}),
+    // Constructed per execution, like node-eve does: a module-level loader caches its keys, so a
+    // second call would skip the batch function and emit no span.
+    run: async () => {
+      const loader = new DataLoader<number, number>(async keys => keys.map(key => key * 2));
+      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/node-flue/src/app.ts

@@ -0,0 +1,10 @@
+import '../sentry-init.ts';
+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/node-flue/start-event-proxy.mjs

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

dev-packages/e2e-tests/test-applications/node-flue/tests/dataloader.test.ts

@@ -0,0 +1,38 @@
+import { expect, test } from '@playwright/test';
+import { collectStreamedSpans, getSpanOp } from '@sentry-internal/test-utils';
+import { newConversationId, runAgentTurn } from './utils';
+
+const APP = 'node-flue';
+
+const isDataloaderSpan = (span: { attributes?: Record<string, { value?: unknown }> }): boolean =>
+  span.attributes?.['sentry.origin']?.value === 'auto.db.dataloader';
+
+/**
+ * `dataloader` is instrumented through orchestrion, a module transform, so it only produces spans
+ * with the loader registered at process start. A Flue node build needs no externals config for
+ * that: dependencies stay bare specifiers, so `dataloader` is still a real module to hook. If Flue
+ * ever switches to a bundled server output, this is what catches it.
+ *
+ * The loader is called from inside a tool so its span lands in the agent's trace, beside the AI
+ * spans, rather than in a trace of its own.
+ */
+test('captures orchestrion-instrumented dataloader spans in the same trace as the AI spans', async ({ baseURL }) => {
+  const spansPromise = collectStreamedSpans(
+    APP,
+    spansOfTrace =>
+      spansOfTrace.some(span => span.attributes?.['gen_ai.tool.name']?.value === 'count_items') &&
+      spansOfTrace.some(isDataloaderSpan),
+  );
+
+  await runAgentTurn(baseURL!, newConversationId('dataloader'), 'Please call count_items to count the items.');
+
+  const spans = await spansPromise;
+  const dataloaderSpan = spans.find(isDataloaderSpan);
+  const toolSpan = spans.find(span => span.attributes?.['gen_ai.tool.name']?.value === 'count_items');
+
+  // Sharing the trace is the point: the orchestrion span is captured alongside the AI spans rather
+  // than in a trace of its own. Not asserting the exact parent — the model may call the tool more
+  // than once, and the span that ran the loader is not reliably the one found here.
+  expect(getSpanOp(dataloaderSpan!)).toBe('cache.get');
+  expect(dataloaderSpan?.trace_id).toBe(toolSpan?.trace_id);
+});

dev-packages/e2e-tests/test-applications/node-flue/tests/errors.test.ts

@@ -0,0 +1,24 @@
+import { expect, test } from '@playwright/test';
+import { collectStreamedSpans, waitForError } from '@sentry-internal/test-utils';
+import { newConversationId, runAgentTurn } from './utils';
+
+const APP = 'node-flue';
+
+test('captures an error thrown inside a Flue tool and marks its span errored', async ({ baseURL }) => {
+  const errorPromise = waitForError(
+    APP,
+    event => event.exception?.values?.[0]?.value === 'Intentional flue tool failure',
+  );
+  const spansPromise = collectStreamedSpans(APP, spansOfTrace =>
+    spansOfTrace.some(span => span.attributes?.['gen_ai.tool.name']?.value === 'fail_now'),
+  );
+
+  await runAgentTurn(baseURL!, newConversationId('failure'), 'Please call fail_now to trigger a failure.');
+
+  const error = await errorPromise;
+  expect(error.exception?.values?.[0]?.value).toBe('Intentional flue tool failure');
+
+  const spans = await spansPromise;
+  const executeTool = spans.find(span => span.attributes?.['gen_ai.tool.name']?.value === 'fail_now');
+  expect(executeTool?.status).toBe('error');
+});