Group pipeline runs into Langfuse sessions, tagged by trigger source

Each pipeline invocation (runAsync/searchAsync) now gets a fresh
sessionId, wrapped via the new Tracer.runWithSession() (implemented
with @langfuse/tracing's propagateAttributes, since v5 has no direct
sessionId/tags option on startObservation) so it shows up in
Langfuse's Sessions view. The session is also tagged with what
triggered the run: "cron", "api-list", "api-trigger", "api-search".

Verified: full test suite (79/79) passing, tsc/eslint clean, real
docker compose build + container smoke test against /health.

test/app/controllers/RecommendationsController.test.ts

@@ -17,7 +17,7 @@ describe('RecommendationsController', () => {
 
     const res = await app.inject({ method: 'GET', url: '/recommendations' });
     expect(res.statusCode).toBe(200);
-    expect(runAsync).toHaveBeenCalledWith({ count: 10, useLlm: true });
+    expect(runAsync).toHaveBeenCalledWith({ count: 10, useLlm: true }, { trigger: 'api-list' });
   });
 
   it('GET /recommendations?count= and force_llm/force_tmdb override config', async () => {
@@ -25,7 +25,7 @@ describe('RecommendationsController', () => {
     const app = makeApp({ RECOMMEND_COUNT: 10, LLM_ENABLED: false }, { runAsync } as unknown as RecommendationPipeline);
 
     await app.inject({ method: 'GET', url: '/recommendations?count=3&force_llm=true' });
-    expect(runAsync).toHaveBeenCalledWith({ count: 3, useLlm: true });
+    expect(runAsync).toHaveBeenCalledWith({ count: 3, useLlm: true }, { trigger: 'api-list' });
   });
 
   it('falls back to the configured count for a malformed or non-positive count query param', async () => {
@@ -33,13 +33,13 @@ describe('RecommendationsController', () => {
     const app = makeApp({ RECOMMEND_COUNT: 10, LLM_ENABLED: true }, { runAsync } as unknown as RecommendationPipeline);
 
     await app.inject({ method: 'GET', url: '/recommendations?count=abc' });
-    expect(runAsync).toHaveBeenCalledWith({ count: 10, useLlm: true });
+    expect(runAsync).toHaveBeenCalledWith({ count: 10, useLlm: true }, { trigger: 'api-list' });
 
     await app.inject({ method: 'GET', url: '/recommendations?count=-5' });
-    expect(runAsync).toHaveBeenCalledWith({ count: 10, useLlm: true });
+    expect(runAsync).toHaveBeenCalledWith({ count: 10, useLlm: true }, { trigger: 'api-list' });
 
     await app.inject({ method: 'GET', url: '/recommendations?count=0' });
-    expect(runAsync).toHaveBeenCalledWith({ count: 10, useLlm: true });
+    expect(runAsync).toHaveBeenCalledWith({ count: 10, useLlm: true }, { trigger: 'api-list' });
   });
 
   it('POST /recommendations/trigger auto-requests via Radarr when enabled', async () => {
@@ -75,6 +75,6 @@ describe('RecommendationsController', () => {
       payload: { query: 'sci-fi like Blade Runner' },
     });
     expect(res.statusCode).toBe(200);
-    expect(searchAsync).toHaveBeenCalledWith('sci-fi like Blade Runner', 10);
+    expect(searchAsync).toHaveBeenCalledWith('sci-fi like Blade Runner', 10, 'api-search');
   });
 });

test/app/pipelines/RecommendationPipeline.test.ts

@@ -25,6 +25,7 @@ function makeTracer() {
   const tracer = {
     startTrace: vi.fn().mockReturnValue(trace),
     flush: vi.fn().mockResolvedValue(undefined),
+    runWithSession: vi.fn().mockImplementation((_session: unknown, fn: () => unknown) => fn()),
   } as unknown as Tracer;
   return tracer;
 }

test/core/langfuse/LangfuseTracer.test.ts

@@ -1,23 +1,33 @@
 import { describe, expect, it, vi } from 'vitest';
 
-const { forceFlush, shutdown, sdkStart, sdkShutdown, generationUpdate, generationEnd, childStartObservation, startObservation } =
-  vi.hoisted(() => {
-    const generationUpdate = vi.fn();
-    const generationEnd = vi.fn();
-    const generation = { update: generationUpdate, end: generationEnd };
-    const childStartObservation = vi.fn().mockReturnValue(generation);
-    const rootSpan = { traceId: 'lf-trace-1', startObservation: childStartObservation };
-    return {
-      forceFlush: vi.fn().mockResolvedValue(undefined),
-      shutdown: vi.fn().mockResolvedValue(undefined),
-      sdkStart: vi.fn(),
-      sdkShutdown: vi.fn().mockResolvedValue(undefined),
-      generationUpdate,
-      generationEnd,
-      childStartObservation,
-      startObservation: vi.fn().mockReturnValue(rootSpan),
-    };
-  });
+const {
+  forceFlush,
+  shutdown,
+  sdkStart,
+  sdkShutdown,
+  generationUpdate,
+  generationEnd,
+  childStartObservation,
+  startObservation,
+  propagateAttributes,
+} = vi.hoisted(() => {
+  const generationUpdate = vi.fn();
+  const generationEnd = vi.fn();
+  const generation = { update: generationUpdate, end: generationEnd };
+  const childStartObservation = vi.fn().mockReturnValue(generation);
+  const rootSpan = { traceId: 'lf-trace-1', startObservation: childStartObservation };
+  return {
+    forceFlush: vi.fn().mockResolvedValue(undefined),
+    shutdown: vi.fn().mockResolvedValue(undefined),
+    sdkStart: vi.fn(),
+    sdkShutdown: vi.fn().mockResolvedValue(undefined),
+    generationUpdate,
+    generationEnd,
+    childStartObservation,
+    startObservation: vi.fn().mockReturnValue(rootSpan),
+    propagateAttributes: vi.fn().mockImplementation((_attrs: unknown, fn: () => unknown) => fn()),
+  };
+});
 
 vi.mock('@langfuse/otel', () => ({
   LangfuseSpanProcessor: vi.fn().mockImplementation(() => ({ forceFlush, shutdown })),
@@ -27,7 +37,7 @@ vi.mock('@opentelemetry/sdk-node', () => ({
   NodeSDK: vi.fn().mockImplementation(() => ({ start: sdkStart, shutdown: sdkShutdown })),
 }));
 
-vi.mock('@langfuse/tracing', () => ({ startObservation }));
+vi.mock('@langfuse/tracing', () => ({ startObservation, propagateAttributes }));
 
 import { LangfuseTracer } from '../../../src/core/langfuse/LangfuseTracer';
 
@@ -74,4 +84,14 @@ describe('LangfuseTracer', () => {
     await tracer.shutdown();
     expect(sdkShutdown).toHaveBeenCalledTimes(1);
   });
+
+  it('runWithSession propagates sessionId/tags to the callback via propagateAttributes and returns its result', async () => {
+    const tracer = new LangfuseTracer({ publicKey: 'pk', secretKey: 'sk', baseUrl: 'http://lf' });
+    const fn = vi.fn().mockResolvedValue('done');
+
+    const result = await tracer.runWithSession({ sessionId: 'session-1', tags: ['cron'] }, fn);
+
+    expect(propagateAttributes).toHaveBeenCalledWith({ sessionId: 'session-1', tags: ['cron'] }, fn);
+    expect(result).toBe('done');
+  });
 });

test/core/llm/LlmPipeline.test.ts

@@ -23,24 +23,44 @@ class ThrowingPipeline extends LlmPipeline<void, void> {
 function makeTracer(trace: TraceHandle) {
   const flush = vi.fn().mockResolvedValue(undefined);
   const startTrace = vi.fn().mockReturnValue(trace);
-  const tracer = { startTrace, flush } as unknown as Tracer;
-  return { tracer, startTrace, flush };
+  const runWithSession = vi.fn().mockImplementation((_session: unknown, fn: () => unknown) => fn());
+  const tracer = { startTrace, flush, runWithSession } as unknown as Tracer;
+  return { tracer, startTrace, flush, runWithSession };
 }
 
 describe('LlmPipeline', () => {
-  it('opens one trace, runs runInternal with it, and flushes afterward', async () => {
+  it('runs the whole call inside a session scoped to a fresh session id, opens one trace, runs runInternal, and flushes afterward', async () => {
     const trace = { id: 'trace-1', startGeneration: vi.fn() } as unknown as TraceHandle;
-    const { tracer, startTrace, flush } = makeTracer(trace);
+    const { tracer, startTrace, flush, runWithSession } = makeTracer(trace);
     const logger = {} as unknown as Logger;
 
     const pipeline = new SumPipeline(tracer, logger);
     const result = await pipeline.runAsync([1, 2, 3]);
 
     expect(result).toBe(6);
-    expect(startTrace).toHaveBeenCalledWith('sum-pipeline');
+    expect(runWithSession).toHaveBeenCalledWith(
+      expect.objectContaining({ sessionId: expect.any(String), tags: undefined }),
+      expect.any(Function)
+    );
+    expect(startTrace).toHaveBeenCalledWith('sum-pipeline', { trigger: undefined });
     expect(flush).toHaveBeenCalledTimes(1);
   });
 
+  it('tags the session with the given trigger', async () => {
+    const trace = { id: 'trace-1', startGeneration: vi.fn() } as unknown as TraceHandle;
+    const { tracer, startTrace, runWithSession } = makeTracer(trace);
+    const logger = {} as unknown as Logger;
+
+    const pipeline = new SumPipeline(tracer, logger);
+    await pipeline.runAsync([1, 2, 3], { trigger: 'cron' });
+
+    expect(runWithSession).toHaveBeenCalledWith(
+      expect.objectContaining({ tags: ['cron'] }),
+      expect.any(Function)
+    );
+    expect(startTrace).toHaveBeenCalledWith('sum-pipeline', { trigger: 'cron' });
+  });
+
   it('still flushes the trace when runInternal throws', async () => {
     const trace = { id: 'trace-2', startGeneration: vi.fn() } as unknown as TraceHandle;
     const { tracer, flush } = makeTracer(trace);