Enable session management v2 by default (#4091)

* Enable session management v2 flag by default

* solve bugs and fix tests

Regenerate aggregator mock to restore alphabetical method order

MergeCapabilities was placed after ProcessPreQueriedCapabilities in the
mock file. Running go generate restores the mockgen-expected alphabetical
order to pass the codegen verification CI check.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Fix composite tool name collision in SMv2 session registration

The v2 session registration path (handleSessionRegistrationV2) was adding
composite tools without checking for name conflicts with backend tools,
unlike the v1 injectCapabilities path which uses validateNoToolConflicts.

- Add GetMultiSession to the SessionManager interface so server.go can
  access the session's resolved backend tool list for conflict validation
- Call validateNoToolConflicts before registering composite SDK tools,
  skipping them (with an error log) if a collision is detected
- Track actual composite tools added for accurate log output

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Fix composite tool routing failure in SMv2 path

Composite tool workflow steps call the shared router which reads
DiscoveredCapabilities from the request context, but the discovery
middleware was short-circuiting for MultiSession sessions and never
injecting them, causing "capabilities not found in context" errors.

- Add GetRoutingTable() to the MultiSession interface and implement it
  on defaultMultiSession (routing table is immutable post-creation)
- Update discovery middleware: instead of skipping context injection for
  MultiSession, build AggregatedCapabilities from the session's routing
  table and inject it — enabling composite tool workflow steps to route
  backend tool calls correctly
- Guard against nil routing table (session initialisation not yet complete)
- Add GetRoutingTable() stub to test fakes in session manager and
  integration tests

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: taskbot <taskbot@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

cmd/thv-operator/controllers/virtualmcpserver_controller.go

@@ -681,8 +681,10 @@ func (r *VirtualMCPServerReconciler) ensureHMACSecret(
 ) error {
 	ctxLogger := log.FromContext(ctx)
 
-	// Only ensure HMAC secret if Session Management V2 is enabled
-	if vmcp.Spec.Config.Operational == nil || !vmcp.Spec.Config.Operational.SessionManagementV2 {
+	// Skip HMAC secret creation only when SessionManagementV2 is explicitly set to false.
+	// nil means "unset" which defaults to true (v2 enabled).
+	op := vmcp.Spec.Config.Operational
+	if op != nil && op.SessionManagementV2 != nil && !*op.SessionManagementV2 {
 		return nil
 	}
 

cmd/thv-operator/controllers/virtualmcpserver_deployment.go

@@ -277,8 +277,10 @@ func (r *VirtualMCPServerReconciler) buildEnvVarsForVmcp(
 	// Mount outgoing auth secrets
 	env = append(env, r.buildOutgoingAuthEnvVars(ctx, vmcp, typedWorkloads)...)
 
-	// Mount HMAC secret for session token binding (Session Management V2)
-	if vmcp.Spec.Config.Operational != nil && vmcp.Spec.Config.Operational.SessionManagementV2 {
+	// Mount HMAC secret when SessionManagementV2 is enabled (nil = unset = default true).
+	// Skip only when explicitly set to false.
+	op := vmcp.Spec.Config.Operational
+	if op == nil || op.SessionManagementV2 == nil || *op.SessionManagementV2 {
 		env = append(env, r.buildHMACSecretEnvVar(vmcp))
 	}
 

cmd/vmcp/app/commands.go

@@ -297,7 +297,10 @@ func discoverBackends(
 //   - Otherwise: logs warning and creates factory with default insecure secret
 //
 // Returns an error only when running in Kubernetes without a secret (fail-fast for production).
-func createSessionFactory(outgoingRegistry vmcpauth.OutgoingAuthRegistry) (vmcpsession.MultiSessionFactory, error) {
+func createSessionFactory(
+	outgoingRegistry vmcpauth.OutgoingAuthRegistry,
+	agg aggregator.Aggregator,
+) (vmcpsession.MultiSessionFactory, error) {
 	const (
 		envKey                  = "VMCP_SESSION_HMAC_SECRET"
 		minRecommendedSecretLen = 32
@@ -319,6 +322,7 @@ func createSessionFactory(outgoingRegistry vmcpauth.OutgoingAuthRegistry) (vmcps
 		return vmcpsession.NewSessionFactory(
 			outgoingRegistry,
 			vmcpsession.WithHMACSecret([]byte(hmacSecret)),
+			vmcpsession.WithAggregator(agg),
 		), nil
 	}
 
@@ -332,7 +336,7 @@ func createSessionFactory(outgoingRegistry vmcpauth.OutgoingAuthRegistry) (vmcps
 
 	// Development mode: use default insecure secret with warning
 	slog.Warn("VMCP_SESSION_HMAC_SECRET not set - using default insecure secret (NOT recommended for production)")
-	return vmcpsession.NewSessionFactory(outgoingRegistry), nil
+	return vmcpsession.NewSessionFactory(outgoingRegistry, vmcpsession.WithAggregator(agg)), nil
 }
 
 // runServe implements the serve command logic
@@ -522,10 +526,12 @@ func runServe(cmd *cobra.Command, _ []string) error {
 		return fmt.Errorf("failed to validate optimizer config: %w", err)
 	}
 
-	// Create session factory only when SessionManagementV2 is enabled
+	// Create session factory only when SessionManagementV2 is enabled.
+	// nil means "unset" which defaults to true; explicit *false opts out.
+	sessionManagementV2 := cfg.Operational.SessionManagementV2 == nil || *cfg.Operational.SessionManagementV2
 	var sessionFactory vmcpsession.MultiSessionFactory
-	if cfg.Operational.SessionManagementV2 {
-		sessionFactory, err = createSessionFactory(outgoingRegistry)
+	if sessionManagementV2 {
+		sessionFactory, err = createSessionFactory(outgoingRegistry, agg)
 		if err != nil {
 			return err
 		}
@@ -547,7 +553,7 @@ func runServe(cmd *cobra.Command, _ []string) error {
 		Watcher:                 backendWatcher,
 		StatusReporter:          statusReporter,
 		OptimizerConfig:         optCfg,
-		SessionManagementV2:     cfg.Operational.SessionManagementV2,
+		SessionManagementV2:     sessionManagementV2,
 		SessionFactory:          sessionFactory,
 	}
 

deploy/charts/operator-crds/files/crds/toolhive.stacklok.dev_virtualmcpservers.yaml

@@ -692,11 +692,12 @@ spec:
                         - debug
                         type: string
                       sessionManagementV2:
+                        default: true
                         description: |-
                           SessionManagementV2 enables session-scoped backend client lifecycle.
                           When true, vMCP creates real backend connections per session via MultiSessionFactory
                           and routes tool calls directly through the session rather than the global router.
-                          Defaults to false; existing behaviour is completely unchanged when disabled.
+                          Defaults to true. Set explicitly to false to opt out.
                         type: boolean
                       timeouts:
                         description: Timeouts configures timeout settings.

deploy/charts/operator-crds/templates/toolhive.stacklok.dev_virtualmcpservers.yaml

@@ -695,11 +695,12 @@ spec:
                         - debug
                         type: string
                       sessionManagementV2:
+                        default: true
                         description: |-
                           SessionManagementV2 enables session-scoped backend client lifecycle.
                           When true, vMCP creates real backend connections per session via MultiSessionFactory
                           and routes tool calls directly through the session rather than the global router.
-                          Defaults to false; existing behaviour is completely unchanged when disabled.
+                          Defaults to true. Set explicitly to false to opt out.
                         type: boolean
                       timeouts:
                         description: Timeouts configures timeout settings.

docs/operator/crd-api.md

@@ -61,6 +61,23 @@ type Aggregator interface {
 	// 2. Resolve conflicts
 	// 3. Merge into final view
 	AggregateCapabilities(ctx context.Context, backends []vmcp.Backend) (*AggregatedCapabilities, error)
+
+	// ProcessPreQueriedCapabilities applies the same aggregation pipeline (overrides,
+	// conflict resolution, advertising filter) to tools that have already been fetched
+	// from live backends. Used by the v2 session management path to reuse aggregator
+	// logic without re-querying backends over HTTP.
+	//
+	// toolsByBackend maps backend WorkloadID → raw tools as returned by the backend.
+	// targets maps backend WorkloadID → the pre-built BackendTarget for that backend.
+	//
+	// Returns the advertised tool list (resolved names, filtered) and a routing table
+	// keyed by resolved name. Each routing table entry has OriginalCapabilityName set
+	// so that GetBackendCapabilityName() translates back to the raw backend name.
+	ProcessPreQueriedCapabilities(
+		ctx context.Context,
+		toolsByBackend map[string][]vmcp.Tool,
+		targets map[string]*vmcp.BackendTarget,
+	) (advertisedTools []vmcp.Tool, toolsRouting map[string]*vmcp.BackendTarget, err error)
 }
 
 // BackendCapabilities contains the raw capabilities from a single backend.

pkg/vmcp/aggregator/aggregator.go

@@ -340,13 +340,15 @@ func (a *defaultAggregator) MergeCapabilities(
 				"backend", resolvedTool.BackendID, "tool", resolvedTool.ResolvedName)
 			routingTable.Tools[resolvedTool.ResolvedName] = &vmcp.BackendTarget{
 				WorkloadID:             resolvedTool.BackendID,
-				OriginalCapabilityName: resolvedTool.OriginalName,
+				OriginalCapabilityName: actualBackendCapabilityName(a.toolConfigMap, resolvedTool.BackendID, resolvedTool.OriginalName),
 			}
 		} else {
 			// Use the backendToTarget helper from registry package
 			target := vmcp.BackendToTarget(backend)
-			// Store the original tool name for forwarding to backend
-			target.OriginalCapabilityName = resolvedTool.OriginalName
+			// Store the actual backend capability name for forwarding to backend.
+			// resolvedTool.OriginalName is the post-override name; reverse the override
+			// to get the name the backend itself uses.
+			target.OriginalCapabilityName = actualBackendCapabilityName(a.toolConfigMap, resolvedTool.BackendID, resolvedTool.OriginalName)
 			routingTable.Tools[resolvedTool.ResolvedName] = target
 		}
 	}
@@ -493,6 +495,85 @@ func (a *defaultAggregator) AggregateCapabilities(
 	return aggregated, nil
 }
 
+// ProcessPreQueriedCapabilities implements Aggregator.ProcessPreQueriedCapabilities.
+// It reuses processBackendTools, ResolveConflicts, and shouldAdvertiseTool so that
+// the v2 session path applies identical transforms to the v1 aggregation path.
+func (a *defaultAggregator) ProcessPreQueriedCapabilities(
+	ctx context.Context,
+	toolsByBackend map[string][]vmcp.Tool,
+	targets map[string]*vmcp.BackendTarget,
+) ([]vmcp.Tool, map[string]*vmcp.BackendTarget, error) {
+	// Step 1: Apply per-backend overrides (renames, description changes).
+	processed := make(map[string]*BackendCapabilities, len(toolsByBackend))
+	for backendID, rawTools := range toolsByBackend {
+		processed[backendID] = &BackendCapabilities{
+			BackendID: backendID,
+			Tools:     processBackendTools(ctx, backendID, rawTools, a.toolConfigMap[backendID]),
+		}
+	}
+
+	// Step 2: Resolve naming conflicts across backends.
+	resolved, err := a.ResolveConflicts(ctx, processed)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	// Step 3: Build advertised list and routing table, applying advertising filter.
+	var advertisedTools []vmcp.Tool
+	routingTable := make(map[string]*vmcp.BackendTarget, len(resolved.Tools))
+
+	for _, rt := range resolved.Tools {
+		target, ok := targets[rt.BackendID]
+		if !ok {
+			slog.Warn("ProcessPreQueriedCapabilities: no target for backend, skipping tool",
+				"backend", rt.BackendID, "tool", rt.ResolvedName)
+			continue
+		}
+		// Clone the target and record the actual backend capability name for call routing.
+		// rt.OriginalName is the post-override name; reverse the override map to get the
+		// actual name the backend itself uses.
+		t := *target
+		t.OriginalCapabilityName = actualBackendCapabilityName(a.toolConfigMap, rt.BackendID, rt.OriginalName)
+		routingTable[rt.ResolvedName] = &t
+
+		if a.shouldAdvertiseTool(rt.BackendID, rt.OriginalName) {
+			advertisedTools = append(advertisedTools, vmcp.Tool{
+				Name:         rt.ResolvedName,
+				Description:  rt.Description,
+				InputSchema:  rt.InputSchema,
+				OutputSchema: rt.OutputSchema,
+				Annotations:  rt.Annotations,
+				BackendID:    rt.BackendID,
+			})
+		}
+	}
+
+	return advertisedTools, routingTable, nil
+}
+
+// actualBackendCapabilityName returns the real capability name the backend uses,
+// reversing any per-backend override rename that processBackendTools may have applied.
+//
+// processBackendTools renames tools when WorkloadToolConfig.Overrides maps an original
+// backend name to a user-visible name. The conflict resolvers receive the post-override
+// name and store it as ResolvedTool.OriginalName. Setting OriginalCapabilityName to that
+// value would forward the overridden (user-visible) name to the backend, which only knows
+// the original name.
+//
+// Returns postOverrideName unchanged when no matching override is configured.
+func actualBackendCapabilityName(toolConfigMap map[string]*config.WorkloadToolConfig, backendID, postOverrideName string) string {
+	wlConfig, ok := toolConfigMap[backendID]
+	if !ok || wlConfig == nil {
+		return postOverrideName
+	}
+	for origName, override := range wlConfig.Overrides {
+		if override != nil && override.Name == postOverrideName {
+			return origName
+		}
+	}
+	return postOverrideName
+}
+
 // shouldAdvertiseTool returns true if a tool from the given backend should be
 // advertised to MCP clients (included in tools/list response).
 //