fix(mcptoolset): give each user its own MCP session with Config.Auth - #1755

Two things need to change before this can merge: the per-user session pool needs a bound (and should not multiply sessions for user-independent credentials or retain each user's full first InvocationContext in memory), and perUserClients.Close has to keep the documented concurrency and error-return guarantees of Close.

Must change before merge:

1. Bound the per-user session pool, keep user-independent credentials on one session, and detach the connecting context from the full InvocationContext. forUser inserts a *connectionRefresher for every distinct (appName, userID) before connecting and never removes or evicts entries before Close. Three consequences compound in a long-running service:

   • Unbounded sessions and SSE streams: each connected entry keeps an mcp.ClientSession, its reader goroutine, and (with go-sdk v1.8.0's default streamable transport settings) a standalone SSE GET stream open until Close. ADK does not authenticate UserID (see the CredentialKey doc), so in a multi-user server this grows with every distinct UserID the process ever sees, and entries whose initial Connect failed also remain in the map. You offered an idle limit in the PR description — please add a bound (idle eviction, a size cap, or both) and avoid keeping entries whose initial connect failed.
   • Session multiplication for shared credentials: New switches to perUserClients whenever cfg.Auth != nil, including user-independent providers (auth.StaticToken, auth.APIKey, auth.ADC, auth.ServiceAccount). In a normal agent run (Runner.Run), every invocation carries a Session with the end user's UserID, so 50 users calling a toolset configured with auth.StaticToken open 50 MCP sessions and 50 SSE GET streams on this branch, compared to 1 on main (82ca4c62) and 1 in adk-python, which keys sessions on a hash of the merged headers in _generate_session_key.
   • Pinned first InvocationContext per user: when getSession calls c.client.Connect(ctx, c.transport, nil), go-sdk's StreamableClientTransport.Connect stores xcontext.Detach(ctx) on the connection for the lifetime of the MCP session so the standalone SSE stream and closing DELETE retain context values. Because InvocationContext.Value reads c.params.Session live, detaching the full InvocationContext pins each user's entire first-turn InvocationContext and session.Session in memory until Close (50 of 50 retained across GC cycles in a 50-user test on this branch, versus 1 of 50 on main).

2. Keep the documented concurrent Close behavior in perUserClients.Close. The New doc promises that Close waits for ongoing connection setup and MCP operations to finish and is safe to call concurrently or more than once, which connectionRefresher.Close enforces with closeOnce.Do and closeErr. In perUserClients.Close, the first caller sets p.sessions = nil under p.mu and then blocks closing each session outside the lock. A concurrent second caller sees p.sessions == nil and returns nil immediately while the first is still waiting on in-flight connection setup or DELETE requests, and any subsequent caller gets nil even when the first call returned a close error. Guarding perUserClients.Close with sync.Once and caching the joined closeErr (matching connectionRefresher.Close) fixes both.

Non-blocking note outside the diff: the NewProvider doc comment in auth/gcp/provider.go still says mcptoolset's MCP session and standalone stream are opened on the context of "whichever user connected first". With per-user sessions, each user opens their own session, though that session and its standalone stream stay bound to that user's first-connect context across later invocations.

// In tool/mcptoolset, next to auth_session_test.go (reuses newUserBoundServer and perUserToken).
func TestAuthConcurrentCloseWaits(t *testing.T) {
	inner := newUserBoundServer(t)
	release := make(chan struct{})
	front := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if strings.Contains(r.Header.Get("Authorization"), "token-of-slow") && r.Method == http.MethodPost {
			b, _ := io.ReadAll(r.Body)
			if strings.Contains(string(b), `"initialize"`) {
				<-release // hold the slow user's connection setup open
			}
			r.Body = io.NopCloser(strings.NewReader(string(b)))
		}
		inner.Config.Handler.ServeHTTP(w, r)
	}))
	t.Cleanup(front.Close)
	ts, _ := mcptoolset.New(mcptoolset.Config{Endpoint: front.URL, Auth: perUserToken})
	closer := ts.(interface{ Close() error })
	svc := session.InMemoryService()
	created, _ := svc.Create(t.Context(), &session.CreateRequest{AppName: "app", UserID: "slow"})
	invCtx := icontext.NewInvocationContext(t.Context(), icontext.InvocationContextParams{Session: created.Session})
	go func() { _, _ = ts.Tools(icontext.NewReadonlyContext(invCtx)) }()
	time.Sleep(200 * time.Millisecond)

	first := make(chan struct{})
	go func() { _ = closer.Close(); close(first) }()
	time.Sleep(200 * time.Millisecond)
	_ = closer.Close()
	select {
	case <-first:
	default:
		t.Errorf("second Close returned while the first was still closing sessions")
	}
	close(release)
	<-first
}

--- FAIL: TestAuthConcurrentCloseWaits (0.41s)
    second Close returned while the first was still closing sessions

Thanks for the quick turnaround — the credentialSessions pool, sync.Once on Close, and identityOnlyContext address the concurrency and memory-retention issues from round 1, and re-running the test and lint battery is clean. Two issues in the new session-pool and context code still need fixing before merge:

Must change before merge:

1. acquire returns a session that evictLocked just evicted when the same credential returns after sessionIdleTimeout. In acquire, s, ok := p.sessions[key] runs before p.evictLocked(now, !ok). When the caller's own session has been idle for at least sessionIdleTimeout and no other caller's acquire has swept it in the meantime (which is always the case for a shared auth.StaticToken session, or when the last user is also the next user to call), evictLocked deletes s from p.sessions and starts s.conn.Close() in the background. acquire then checks the stale if !ok (ok is still true), skips creating a replacement session, and returns the deleted, closing s to the caller. TestAuthEvictsIdleSessions did not hit this because bob's call on line 290 swept alice's idle session before alice called again. Also, if a concurrent burst pushes len(p.sessions) above maxSessions, evictLocked evicts at most one LRU session per new-key acquire, so the pool remains above maxSessions after the burst is idle (contrary to the comments at set.go and client.go). Sweeping expired idle sessions before looking up s, ok := p.sessions[key] and evicting idle LRU sessions in a for len(p.sessions) >= maxSessions loop fixes both.

2. Avoid context.Background() in identityOnlyContext. identityOnlyContext calls base := context.Background() in non-test library code, which AGENTS.md forbids outside main, tests, and examples. A small unexported context.Context type whose Deadline, Done, and Err return zero values and whose Value answers only adkcontext.IdentityKey avoids context.Background() while keeping the invocation detached.

func TestAuthIdleSessionSameUserReturns(t *testing.T) {
	mcptoolset.SetSessionBoundsForTest(t, 30*time.Millisecond, 64)
	server := mcp.NewServer(&mcp.Implementation{Name: "paged_server", Version: "v1.0.0"}, &mcp.ServerOptions{PageSize: 1})
	for _, name := range []string{"tool_a", "tool_b"} {
		mcp.AddTool(server, &mcp.Tool{Name: name, Description: name},
			func(ctx context.Context, req *mcp.CallToolRequest, _ struct{}) (*mcp.CallToolResult, any, error) {
				return &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: "ok"}}}, nil, nil
			})
	}
	httpSrv := httptest.NewServer(mcp.NewStreamableHTTPHandler(func(*http.Request) *mcp.Server { return server }, nil))
	t.Cleanup(httpSrv.Close)

	ts, err := mcptoolset.New(mcptoolset.Config{Endpoint: httpSrv.URL, Auth: perUserToken})
	if err != nil {
		t.Fatal(err)
	}
	t.Cleanup(func() { _ = ts.(io.Closer).Close() })

	alice := icontext.NewReadonlyContext(invocationAs(t, "app", "alice"))
	if _, err := ts.Tools(alice); err != nil {
		t.Fatalf("first Tools(): %v", err)
	}
	time.Sleep(60 * time.Millisecond)

	if _, err := ts.Tools(alice); err != nil {
		t.Fatalf("second Tools() after idle timeout: %v", err)
	}
	if n := mcptoolset.SessionCountForTest(ts); n != 1 {
		t.Fatalf("SessionCountForTest = %d, want 1", n)
	}
}

--- FAIL: TestAuthIdleSessionSameUserReturns (0.07s)
    second Tools() after idle timeout: failed to list MCP tools: connection closed

LGTM, thank you for contribution.