@librechat/agents 3.3.8 → 3.3.9

package/src/specs/langfuse-callbacks.test.ts

@@ -385,6 +385,462 @@ describe('Langfuse callback composition', () => {
     );
   });
 
+  it('keeps callback spans on their own run when a foreign run scope is active', async () => {
+    const { createLangfuseHandler } = await import('@/langfuse');
+    const { initializeLangfuseTracing } = await import('@/instrumentation');
+    const { withLangfuseRuntimeScope } = await import('@/langfuseRuntimeScope');
+    const tenantA = {
+      publicKey: 'pk-tenant-a',
+      secretKey: 'sk-tenant-a',
+      baseUrl: 'https://langfuse.tenant-a',
+      deterministicTraceId: true,
+    };
+    const tenantB = {
+      publicKey: 'pk-tenant-b',
+      secretKey: 'sk-tenant-b',
+      baseUrl: 'https://langfuse.tenant-b',
+      deterministicTraceId: true,
+    };
+    initializeLangfuseTracing(tenantA);
+    initializeLangfuseTracing(tenantB);
+    const handlerB = createLangfuseHandler({
+      langfuse: tenantB,
+      traceIdSeed: 'run-b',
+      runId: 'run-b',
+    });
+
+    // LangChain's background callback queue (`consumeCallback`) executes
+    // non-awaited callbacks inside whichever concurrent run's async context
+    // the queue drain happens to be on — here, tenant-A's. A scope stamped
+    // with a different run must never reroute tenant-B's spans.
+    await withLangfuseRuntimeScope(
+      { langfuse: tenantA, traceIdSeed: 'run-a', runId: 'run-a' },
+      () =>
+        handlerB?.handleChainStart(
+          { lc: 1, type: 'not_implemented', id: ['ForeignScopedChain'] },
+          { input: 'foreign scoped' },
+          'lc-foreign-run'
+        )
+    );
+
+    expect(mockProcessorStarts).toContainEqual(
+      expect.objectContaining({
+        params: expect.objectContaining({
+          publicKey: 'pk-tenant-b',
+          secretKey: 'sk-tenant-b',
+          baseUrl: 'https://langfuse.tenant-b',
+        }),
+        traceId: traceIdFromSeed('run-b'),
+      })
+    );
+    expect(
+      mockProcessorStarts.filter(
+        (record) =>
+          (record.params as { publicKey?: string }).publicKey ===
+            'pk-tenant-a' || record.traceId === traceIdFromSeed('run-a')
+      )
+    ).toHaveLength(0);
+  });
+
+  it('adopts an agent overlay scope stamped with the handler run', async () => {
+    const { createLangfuseHandler } = await import('@/langfuse');
+    const { initializeLangfuseTracing } = await import('@/instrumentation');
+    const { withLangfuseRuntimeScope } = await import('@/langfuseRuntimeScope');
+    const runLangfuse = {
+      publicKey: 'pk-run',
+      secretKey: 'sk-run',
+      baseUrl: 'https://langfuse.run',
+      deterministicTraceId: true,
+    };
+    const agentLangfuse = {
+      publicKey: 'pk-agent',
+      secretKey: 'sk-agent',
+      baseUrl: 'https://langfuse.agent',
+      deterministicTraceId: true,
+    };
+    initializeLangfuseTracing(runLangfuse);
+    initializeLangfuseTracing(agentLangfuse);
+    const streamHandler = createLangfuseHandler({
+      langfuse: runLangfuse,
+      traceIdSeed: 'run-seed',
+      runId: 'run-1',
+    });
+
+    await withLangfuseRuntimeScope(
+      { langfuse: agentLangfuse, traceIdSeed: 'agent-seed', runId: 'run-1' },
+      () =>
+        streamHandler?.handleChainStart(
+          { lc: 1, type: 'not_implemented', id: ['SameRunOverlayChain'] },
+          { input: 'same run overlay' },
+          'lc-overlay-run'
+        )
+    );
+
+    expect(mockProcessorStarts).toContainEqual(
+      expect.objectContaining({
+        params: expect.objectContaining({
+          publicKey: 'pk-agent',
+          secretKey: 'sk-agent',
+          baseUrl: 'https://langfuse.agent',
+        }),
+        traceId: traceIdFromSeed('agent-seed'),
+      })
+    );
+  });
+
+  it('scopes agent overlays to the callback agent in parallel fan-out', async () => {
+    const { createLangfuseHandler } = await import('@/langfuse');
+    const { initializeLangfuseTracing } = await import('@/instrumentation');
+    const { withLangfuseRuntimeScope } = await import('@/langfuseRuntimeScope');
+    const runLangfuse = {
+      publicKey: 'pk-run',
+      secretKey: 'sk-run',
+      baseUrl: 'https://langfuse.run',
+      deterministicTraceId: true,
+    };
+    const agentBLangfuse = {
+      publicKey: 'pk-agent-b',
+      secretKey: 'sk-agent-b',
+      baseUrl: 'https://langfuse.agent-b',
+      deterministicTraceId: true,
+    };
+    initializeLangfuseTracing(runLangfuse);
+    initializeLangfuseTracing(agentBLangfuse);
+    const streamHandler = createLangfuseHandler({
+      langfuse: runLangfuse,
+      traceIdSeed: 'run-seed',
+      runId: 'run-1',
+    });
+
+    // Agent B's overlay scope is ambient (the background callback queue can
+    // interleave concurrent fan-out agents), but this callback reports agent
+    // A via inherited langgraph metadata — a sibling's overlay must not
+    // capture it.
+    await withLangfuseRuntimeScope(
+      {
+        langfuse: agentBLangfuse,
+        traceIdSeed: 'agent-b-seed',
+        runId: 'run-1',
+        agentId: 'agent-b',
+      },
+      () =>
+        streamHandler?.handleChainStart(
+          { lc: 1, type: 'not_implemented', id: ['SiblingAgentChain'] },
+          { input: 'sibling agent' },
+          'lc-sibling-run',
+          undefined,
+          undefined,
+          { langgraph_node: 'agent=agent-a' }
+        )
+    );
+
+    expect(mockProcessorStarts).toContainEqual(
+      expect.objectContaining({
+        params: expect.objectContaining({ publicKey: 'pk-run' }),
+        traceId: traceIdFromSeed('run-seed'),
+      })
+    );
+
+    // The SAME agent's overlay scope is still adopted.
+    await withLangfuseRuntimeScope(
+      {
+        langfuse: agentBLangfuse,
+        traceIdSeed: 'agent-b-seed',
+        runId: 'run-1',
+        agentId: 'agent-b',
+      },
+      () =>
+        streamHandler?.handleChainStart(
+          { lc: 1, type: 'not_implemented', id: ['OwnAgentChain'] },
+          { input: 'own agent' },
+          'lc-own-agent-run',
+          undefined,
+          undefined,
+          { langgraph_node: 'agent=agent-b' }
+        )
+    );
+
+    expect(mockProcessorStarts).toContainEqual(
+      expect.objectContaining({
+        params: expect.objectContaining({ publicKey: 'pk-agent-b' }),
+        traceId: traceIdFromSeed('agent-b-seed'),
+      })
+    );
+
+    // Explicit `agentId` metadata (stamped by the graph's model path and
+    // ToolNode) beats node-name parsing: agent `research`'s inner node is
+    // named `agent=research`, indistinguishable by name from a sibling
+    // literally named `agent=research` — the explicit identity disambiguates.
+    await withLangfuseRuntimeScope(
+      {
+        langfuse: agentBLangfuse,
+        traceIdSeed: 'prefixed-sibling-seed',
+        runId: 'run-1',
+        agentId: 'agent=research',
+      },
+      () =>
+        streamHandler?.handleChainStart(
+          { lc: 1, type: 'not_implemented', id: ['AmbiguousNodeChain'] },
+          { input: 'ambiguous node' },
+          'lc-ambiguous-node-run',
+          undefined,
+          undefined,
+          { langgraph_node: 'agent=research', agentId: 'research' }
+        )
+    );
+
+    expect(mockProcessorStarts).toContainEqual(
+      expect.objectContaining({
+        params: expect.objectContaining({ publicKey: 'pk-run' }),
+        traceId: traceIdFromSeed('run-seed'),
+      })
+    );
+
+    // An agent id that itself begins with an internal node prefix is carried
+    // VERBATIM by its outer workflow node — still recognized as its own scope.
+    await withLangfuseRuntimeScope(
+      {
+        langfuse: agentBLangfuse,
+        traceIdSeed: 'prefixed-agent-seed',
+        runId: 'run-1',
+        agentId: 'agent=research',
+      },
+      () =>
+        streamHandler?.handleChainStart(
+          { lc: 1, type: 'not_implemented', id: ['PrefixedAgentChain'] },
+          { input: 'prefixed agent' },
+          'lc-prefixed-agent-run',
+          undefined,
+          undefined,
+          { langgraph_node: 'agent=research' }
+        )
+    );
+
+    expect(mockProcessorStarts).toContainEqual(
+      expect.objectContaining({
+        params: expect.objectContaining({ publicKey: 'pk-agent-b' }),
+        traceId: traceIdFromSeed('prefixed-agent-seed'),
+      })
+    );
+  });
+
+  it('rejects a sibling agent overlay for tool callbacks', async () => {
+    const { createLangfuseHandler } = await import('@/langfuse');
+    const { initializeLangfuseTracing } = await import('@/instrumentation');
+    const { withLangfuseRuntimeScope } = await import('@/langfuseRuntimeScope');
+    const runLangfuse = {
+      publicKey: 'pk-run',
+      secretKey: 'sk-run',
+      baseUrl: 'https://langfuse.run',
+      deterministicTraceId: true,
+    };
+    const agentBLangfuse = {
+      publicKey: 'pk-agent-b',
+      secretKey: 'sk-agent-b',
+      baseUrl: 'https://langfuse.agent-b',
+      deterministicTraceId: true,
+    };
+    initializeLangfuseTracing(runLangfuse);
+    initializeLangfuseTracing(agentBLangfuse);
+    const streamHandler = createLangfuseHandler({
+      langfuse: runLangfuse,
+      traceIdSeed: 'run-seed',
+      runId: 'run-1',
+    });
+
+    // Tool supersteps stamp their scope with the executing agent; a tool
+    // callback reporting a different agent via `tools=<id>` metadata must
+    // not adopt the sibling's overlay.
+    await withLangfuseRuntimeScope(
+      {
+        langfuse: agentBLangfuse,
+        traceIdSeed: 'agent-b-seed',
+        runId: 'run-1',
+        agentId: 'agent-b',
+      },
+      () =>
+        streamHandler?.handleToolStart(
+          { lc: 1, type: 'not_implemented', id: ['SiblingTool'] },
+          'sibling tool input',
+          'lc-sibling-tool-run',
+          undefined,
+          undefined,
+          { langgraph_node: 'tools=agent-a' }
+        )
+    );
+
+    expect(mockProcessorStarts).toContainEqual(
+      expect.objectContaining({
+        params: expect.objectContaining({ publicKey: 'pk-run' }),
+        traceId: traceIdFromSeed('run-seed'),
+      })
+    );
+    expect(
+      mockProcessorStarts.filter(
+        (record) =>
+          (record.params as { publicKey?: string }).publicKey === 'pk-agent-b'
+      )
+    ).toHaveLength(0);
+  });
+
+  it('replaces foreign propagated identity attributes with its own', async () => {
+    const { createLangfuseHandler } = await import('@/langfuse');
+    const { initializeLangfuseTracing } = await import('@/instrumentation');
+    const { withLangfuseRuntimeScope } = await import('@/langfuseRuntimeScope');
+    const { propagateAttributes } = await import('@langfuse/tracing');
+    const { getPropagatedAttributesFromContext } = await import(
+      '@langfuse/core'
+    );
+    const tenantA = {
+      publicKey: 'pk-tenant-a',
+      secretKey: 'sk-tenant-a',
+      baseUrl: 'https://langfuse.tenant-a',
+    };
+    const tenantB = {
+      publicKey: 'pk-tenant-b',
+      secretKey: 'sk-tenant-b',
+      baseUrl: 'https://langfuse.tenant-b',
+    };
+    initializeLangfuseTracing(tenantA);
+    initializeLangfuseTracing(tenantB);
+    const handlerB = createLangfuseHandler({
+      langfuse: tenantB,
+      userId: 'user-b',
+      runId: 'run-b',
+    });
+
+    let observedAttributes: Record<string, unknown> | undefined;
+    mockStartActiveSpan.mockImplementationOnce(
+      (_name, _options, activeContext, callback) => {
+        observedAttributes = getPropagatedAttributesFromContext(
+          otelContext.active()
+        ) as Record<string, unknown>;
+        return callback(
+          createMockSpan(otelTrace.getSpanContext(activeContext)?.traceId)
+        );
+      }
+    );
+
+    // Run A's propagated identity (user, session) is ambient; B's spans must
+    // carry B's identity — and NOT retain A's session where B has none.
+    await propagateAttributes(
+      { userId: 'user-a', sessionId: 'session-a' },
+      async () =>
+        withLangfuseRuntimeScope({ langfuse: tenantA, runId: 'run-a' }, () =>
+          handlerB?.handleChainStart(
+            { lc: 1, type: 'not_implemented', id: ['IdentityChain'] },
+            { input: 'identity' },
+            'lc-identity-run'
+          )
+        )
+    );
+
+    expect(observedAttributes?.['user.id']).toBe('user-b');
+    expect(observedAttributes?.['session.id']).toBeUndefined();
+  });
+
+  it('clears a foreign scope for env-credential runs instead of inheriting it', async () => {
+    const { createLangfuseHandler } = await import('@/langfuse');
+    const { initializeLangfuseTracing } = await import('@/instrumentation');
+    const { withLangfuseRuntimeScope } = await import('@/langfuseRuntimeScope');
+    process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';
+    process.env.LANGFUSE_SECRET_KEY = 'sk-env';
+    const tenantA = {
+      publicKey: 'pk-tenant-a',
+      secretKey: 'sk-tenant-a',
+      baseUrl: 'https://langfuse.tenant-a',
+      deterministicTraceId: true,
+    };
+    initializeLangfuseTracing(tenantA);
+    initializeLangfuseTracing();
+    // Run B has no explicit config or seed of its own — it relies on env
+    // credentials. Rejecting a foreign scope must CLEAR the foreign values
+    // rather than let merge inheritance re-adopt them through `undefined`.
+    const handlerB = createLangfuseHandler({ runId: 'run-b' });
+
+    await withLangfuseRuntimeScope(
+      { langfuse: tenantA, traceIdSeed: 'run-a', runId: 'run-a' },
+      () =>
+        handlerB?.handleChainStart(
+          { lc: 1, type: 'not_implemented', id: ['EnvCredentialChain'] },
+          { input: 'env credentials' },
+          'lc-env-run'
+        )
+    );
+
+    expect(mockProcessorStarts).toContainEqual(
+      expect.objectContaining({
+        params: expect.objectContaining({
+          publicKey: 'pk-env',
+          secretKey: 'sk-env',
+        }),
+      })
+    );
+    expect(
+      mockProcessorStarts.filter(
+        (record) =>
+          (record.params as { publicKey?: string }).publicKey ===
+            'pk-tenant-a' || record.traceId === traceIdFromSeed('run-a')
+      )
+    ).toHaveLength(0);
+  });
+
+  it('applies its own tool-output policy inside a foreign run scope', async () => {
+    const { createLangfuseHandler } = await import('@/langfuse');
+    const { initializeLangfuseTracing } = await import('@/instrumentation');
+    const { withLangfuseRuntimeScope } = await import('@/langfuseRuntimeScope');
+    const { resolveToolOutputTracingConfig } = await import('@/langfuseConfig');
+    const { getLangfuseRuntimeToolOutputTracingConfig } = await import(
+      '@/langfuseRuntimeContext'
+    );
+    const tenantA = {
+      publicKey: 'pk-tenant-a',
+      secretKey: 'sk-tenant-a',
+      baseUrl: 'https://langfuse.tenant-a',
+      toolOutputTracing: { enabled: true },
+    };
+    const tenantB = {
+      publicKey: 'pk-tenant-b',
+      secretKey: 'sk-tenant-b',
+      baseUrl: 'https://langfuse.tenant-b',
+      toolOutputTracing: { enabled: false },
+    };
+    initializeLangfuseTracing(tenantA);
+    initializeLangfuseTracing(tenantB);
+    const handlerB = createLangfuseHandler({
+      langfuse: tenantB,
+      runId: 'run-b',
+    });
+
+    let observedPolicy: { enabled: boolean } | undefined;
+    mockStartActiveSpan.mockImplementationOnce(
+      (_name, _options, activeContext, callback) => {
+        observedPolicy = getLangfuseRuntimeToolOutputTracingConfig();
+        return callback(
+          createMockSpan(otelTrace.getSpanContext(activeContext)?.traceId)
+        );
+      }
+    );
+
+    // Tenant A permits tool output; tenant B redacts. B's callback running
+    // inside A's scope must not inherit A's permissive policy.
+    await withLangfuseRuntimeScope(
+      {
+        langfuse: tenantA,
+        runId: 'run-a',
+        toolOutputTracing: resolveToolOutputTracingConfig(tenantA),
+      },
+      () =>
+        handlerB?.handleToolStart(
+          { lc: 1, type: 'not_implemented', id: ['SensitiveTool'] },
+          'sensitive input',
+          'lc-tool-run'
+        )
+    );
+
+    expect(observedPolicy?.enabled).toBe(false);
+  });
+
   it('attaches configured trace attributes to Langfuse callback spans', async () => {
     const { createLangfuseHandler } = await import('@/langfuse');
     const { initializeLangfuseTracing } = await import('@/instrumentation');

package/src/specs/langfuse-routing.integration.test.ts

@@ -256,7 +256,9 @@ function expectChildSpanParentName({
   const children = starts.filter((record) => record.name === childName);
   expect(children).not.toHaveLength(0);
   for (const child of children) {
-    const parent = starts.find((record) => record.spanId === child.parentSpanId);
+    const parent = starts.find(
+      (record) => record.spanId === child.parentSpanId
+    );
     expect(parent?.name.startsWith(parentNamePrefix)).toBe(true);
   }
 }
@@ -560,6 +562,141 @@ describe('Langfuse per-run routing integration', () => {
     }
   });
 
+  it('detaches root observations from foreign ambient spans', async () => {
+    const tenantId = 'tenant-ambient';
+    const foreignTraceId = 'f0e1d2c3b4a5968778695a4b3c2d1e0f';
+    const foreignSpanId = 'a1b2c3d4e5f60718';
+    initializeLangfuseTracing(tenantLangfuse(tenantId));
+
+    // Simulates a host running agent code inside its own OpenTelemetry span
+    // (HTTP server auto-instrumentation on the global provider): the span is
+    // never exported to Langfuse, so inheriting it would orphan the trace
+    // root, merge concurrent runs in one request into a single trace, and
+    // bypass deterministic trace ids.
+    const foreignSpan = otelTrace.wrapSpanContext({
+      traceId: foreignTraceId,
+      spanId: foreignSpanId,
+      traceFlags: 1,
+    });
+    await otelContext.with(
+      otelTrace.setSpan(otelContext.active(), foreignSpan),
+      () => runTenantFlow(tenantId)
+    );
+
+    const starts = startsForTenant(tenantId);
+    expect(starts).not.toHaveLength(0);
+    expect(
+      starts.filter(
+        (record) =>
+          record.traceId === foreignTraceId ||
+          record.parentSpanId === foreignSpanId
+      )
+    ).toHaveLength(0);
+
+    const agentRoot = starts.find(
+      (record) => record.name === `LibreChat Agent: Parent ${tenantId}`
+    );
+    expect(agentRoot?.traceId).toBe(traceIdFromSeed(`routing-${tenantId}`));
+    expect(agentRoot?.parentSpanId).toBeUndefined();
+
+    const titleRoot = starts.find(
+      (record) => record.name === `LibreChat Title: Parent ${tenantId}`
+    );
+    expect(titleRoot?.traceId).toBe(
+      traceIdFromSeed(`title-routing-${tenantId}`)
+    );
+    expect(titleRoot?.parentSpanId).toBeUndefined();
+  });
+
+  it('keeps root observations nested under Langfuse-managed ambient spans', async () => {
+    const tenantId = 'tenant-managed';
+    const langfuse = tenantLangfuse(tenantId);
+    initializeLangfuseTracing(langfuse);
+
+    let hostSpan: MockSpan | undefined;
+    await withLangfuseRuntimeScope({ langfuse }, async () => {
+      hostSpan = createMockSpan('host-group');
+      await otelContext.with(
+        otelTrace.setSpan(otelContext.active(), hostSpan as never),
+        () => runTenantFlow(tenantId)
+      );
+    });
+
+    const hostSpanContext = hostSpan?.spanContext() as {
+      traceId: string;
+      spanId: string;
+    };
+    const agentRoot = startsForTenant(tenantId).find(
+      (record) => record.name === `LibreChat Agent: Parent ${tenantId}`
+    );
+    expect(agentRoot?.traceId).toBe(hostSpanContext.traceId);
+    expect(agentRoot?.parentSpanId).toBe(hostSpanContext.spanId);
+  });
+
+  it('detaches root observations from managed ambient spans of another destination', async () => {
+    const hostTenantId = 'tenant-managed-a';
+    const runTenantId = 'tenant-managed-b';
+    const hostLangfuse = tenantLangfuse(hostTenantId);
+    initializeLangfuseTracing(hostLangfuse);
+    initializeLangfuseTracing(tenantLangfuse(runTenantId));
+
+    let hostSpan: MockSpan | undefined;
+    await withLangfuseRuntimeScope({ langfuse: hostLangfuse }, async () => {
+      hostSpan = createMockSpan('host-group');
+    });
+
+    // A managed span is only a safe parent for runs exporting to the SAME
+    // destination; nesting tenant-B under tenant-A's span would leave B's
+    // trace dangling in B's project with A's trace id.
+    await otelContext.with(
+      otelTrace.setSpan(otelContext.active(), hostSpan as never),
+      () => runTenantFlow(runTenantId)
+    );
+
+    const hostSpanContext = hostSpan?.spanContext() as {
+      traceId: string;
+      spanId: string;
+    };
+    const agentRoot = startsForTenant(runTenantId).find(
+      (record) => record.name === `LibreChat Agent: Parent ${runTenantId}`
+    );
+    expect(agentRoot?.traceId).toBe(traceIdFromSeed(`routing-${runTenantId}`));
+    expect(agentRoot?.traceId).not.toBe(hostSpanContext.traceId);
+    expect(agentRoot?.parentSpanId).toBeUndefined();
+  });
+
+  it('generates a scope stamp for directly-constructed graphs without a run id', async () => {
+    const { StandardGraph } = await import('@/graphs/Graph');
+    const buildGraph = (): { langfuseScopeRunId: string } =>
+      new StandardGraph({
+        agents: [createAgent('stampless')],
+        langfuse: tenantLangfuse('stampless'),
+      }) as unknown as { langfuseScopeRunId: string };
+
+    const graphA = buildGraph();
+    const graphB = buildGraph();
+    expect(graphA.langfuseScopeRunId).toEqual(expect.stringMatching(/^graph:/));
+    expect(graphB.langfuseScopeRunId).toEqual(expect.stringMatching(/^graph:/));
+    expect(graphA.langfuseScopeRunId).not.toBe(graphB.langfuseScopeRunId);
+  });
+
+  it('stamps concurrent executions of the same public run id distinctly', async () => {
+    const { StandardGraph } = await import('@/graphs/Graph');
+    const buildGraph = (): { langfuseScopeRunId: string } =>
+      new StandardGraph({
+        runId: 'duplicate-run',
+        agents: [createAgent('duplicate')],
+        langfuse: tenantLangfuse('duplicate'),
+      }) as unknown as { langfuseScopeRunId: string };
+
+    const first = buildGraph();
+    const second = buildGraph();
+    expect(first.langfuseScopeRunId).toEqual(
+      expect.stringMatching(/^duplicate-run:/)
+    );
+    expect(first.langfuseScopeRunId).not.toBe(second.langfuseScopeRunId);
+  });
+
   it('routes spans from captured OTel context after ALS scope exits', () => {
     const langfuse = tenantLangfuse('tenant-otel');
     initializeLangfuseTracing(langfuse);

package/src/specs/langfuse-span-registry.test.ts

@@ -0,0 +1,70 @@
+import type { Span } from '@opentelemetry/api';
+import type * as t from '@/types';
+import {
+  getLangfuseManagedSpanDestination,
+  registerLangfuseManagedSpan,
+  resolveLangfuseDestinationKey,
+} from '@/langfuseSpanRegistry';
+
+const ORIGINAL_ENV = { ...process.env };
+
+function tenantConfig(
+  overrides: Partial<t.LangfuseConfig> = {}
+): t.LangfuseConfig {
+  return {
+    enabled: true,
+    publicKey: 'pk-registry',
+    secretKey: 'sk-registry',
+    baseUrl: 'https://langfuse.registry',
+    ...overrides,
+  };
+}
+
+describe('Langfuse span registry', () => {
+  afterEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+  });
+
+  it('tracks managed spans by destination', () => {
+    const span = { name: 'managed' } as unknown as Span;
+    const key = resolveLangfuseDestinationKey(tenantConfig());
+    expect(key).toBeDefined();
+    registerLangfuseManagedSpan(span, key as string);
+    expect(getLangfuseManagedSpanDestination(span)).toBe(key);
+
+    const untracked = { name: 'foreign' } as unknown as Span;
+    expect(getLangfuseManagedSpanDestination(untracked)).toBeUndefined();
+  });
+
+  it('treats processor policy as irrelevant to destination identity', () => {
+    const base = resolveLangfuseDestinationKey(tenantConfig());
+    const redacting = resolveLangfuseDestinationKey(
+      tenantConfig({ toolOutputTracing: { enabled: false } })
+    );
+    expect(redacting).toBe(base);
+  });
+
+  it('separates destinations by credentials, endpoint, and environment', () => {
+    const base = resolveLangfuseDestinationKey(tenantConfig());
+    expect(
+      resolveLangfuseDestinationKey(tenantConfig({ publicKey: 'pk-other' }))
+    ).not.toBe(base);
+    expect(
+      resolveLangfuseDestinationKey(
+        tenantConfig({ baseUrl: 'https://langfuse.other' })
+      )
+    ).not.toBe(base);
+    expect(
+      resolveLangfuseDestinationKey(tenantConfig({ environment: 'staging' }))
+    ).not.toBe(base);
+  });
+
+  it('resolves no destination without credentials', () => {
+    delete process.env.LANGFUSE_PUBLIC_KEY;
+    delete process.env.LANGFUSE_SECRET_KEY;
+    expect(resolveLangfuseDestinationKey(undefined)).toBeUndefined();
+    expect(
+      resolveLangfuseDestinationKey(tenantConfig({ enabled: false }))
+    ).toBeUndefined();
+  });
+});