sap-ai-dev-toolkit 0.9.91 → 0.9.94

package/README.md

@@ -302,7 +302,7 @@ The installer handles VSP provisioning automatically:
 
 Setup detects where it is running. With `H2O_URL` set, it treats the environment as SAP Business Application Studio and opens a checkbox picker for BAS destinations, with no destinations selected by default: every row starts with an empty box `[ ]`. Use **Space** to tick a destination (`[✓]`) and **Enter** to confirm; the line under the list always names the next key to press. Press **a** to toggle all destinations (select all if any are unchecked; otherwise clear the selection). Pressing **Enter** with nothing selected asks for a second **Enter**, because confirming with none selected removes this add-on's managed MCP entries. When the `cf` CLI 8.18 or newer is authenticated to a targeted space, setup first offers an optional import from that space's Destination service; type **y** then **Enter** to include it, or press **Enter** to skip. Accepted CF and BAS destinations appear together in the picker.
 
-Without `H2O_URL`, interactive setup looks for local SAP GUI system configuration on macOS and Windows (for example SAP GUI landscape XML and `saplogon.ini`). SAP GUI landscape files describe SAP GUI/DIAG connectivity, not the ADT HTTP(S) endpoint or a complete ABAP client catalog, so setup asks for the SAP client or comma-separated clients to configure for each selected system (for example `100,200`), proposes an ADT URL from the SAP GUI host and instance when it can, and asks you to confirm or edit that value. Multiple entered clients create separate isolated MCP entries, one per system/client pair. Local SAP GUI MCP server keys use the SAP system ID and client (for example `t4d-100`) instead of the longer SAP GUI description, while `SAP_AI_DEV_TOOLKIT_DESTINATION` still preserves the display name. When the ADT URL uses an IP address, setup automatically inspects the SAP HTTPS certificate, extracts DNS subjectAltName entries, and offers to enable secure TLS self-healing with a simple yes/no confirmation; you do not need to type certificate names. The generated MCP entry uses VS Code input prompts for the SAP user and password at server start; raw SAP credentials are not stored in `mcp.json`. On Windows, setup offers Windows / smart card SSO (the default) instead, which writes `SAP_AUTH_MODE=sso` without username/password prompts. At server start, VSP opens Microsoft Edge on the ADT URL; Edge completes the login the same way it does in your browser (smart card certificate and PIN, Kerberos, or company SAML/Entra login), and the session is cached and refreshed automatically. SSO entries need an ADT URL with a host name, not an IP address. npm may run its install hook without an interactive terminal, even when the shell is interactive; in that case, destination selection is skipped without changing MCP config, and you should run `sap-ai-dev --setup` afterwards.
+Without `H2O_URL`, interactive setup looks for local SAP GUI system configuration on macOS and Windows (for example SAP GUI landscape XML and `saplogon.ini`). SAP GUI landscape files describe SAP GUI/DIAG connectivity, not the ADT HTTP(S) endpoint or a complete ABAP client catalog, so setup asks for the SAP client or comma-separated clients to configure for each selected system (for example `100,200`), proposes an ADT URL from the SAP GUI host and instance when it can, and asks you to confirm or edit that value. Multiple entered clients create separate isolated MCP entries, one per system/client pair. Local SAP GUI MCP server keys use the SAP system ID and client (for example `t4d-100`) instead of the longer SAP GUI description, while `SAP_AI_DEV_TOOLKIT_DESTINATION` still preserves the display name. When the ADT URL uses an IP address, setup automatically inspects the SAP HTTPS certificate, extracts DNS subjectAltName entries, and offers to enable secure TLS self-healing with a simple yes/no confirmation; you do not need to type certificate names. The generated MCP entry uses VS Code input prompts for the SAP user and password at server start; raw SAP credentials are not stored in `mcp.json`. On Windows, setup offers Windows / smart card SSO (the default) instead, which writes `SAP_AUTH_MODE=sso` without username/password prompts. At server start, VSP opens a Microsoft Edge window on the ADT URL whenever no session is cached yet; Edge completes the login the same way it does in your browser (smart card certificate and PIN, Kerberos, or company SAML/Entra login). Keep the MCP server running until the sign-in finishes; the session is then cached and refreshed automatically. SSO entries need an ADT URL with a host name, not an IP address. npm may run its install hook without an interactive terminal, even when the shell is interactive; in that case, destination selection is skipped without changing MCP config, and you should run `sap-ai-dev --setup` afterwards.
 
 ### 🖥️ Local machine SAP GUI support
 
@@ -314,7 +314,7 @@ Supported discovery and runtime behavior:
 - **Client selection:** SAP GUI entries may contain one default client but cannot reliably list every ABAP client available through ADT. Setup asks for one or more 3-digit clients per selected system; enter comma-separated values such as `100,200` to create separate MCP servers for each client.
 - **ADT endpoint derivation:** SAP GUI entries usually contain DIAG/router information, not the HTTP(S) ADT endpoint. Setup derives the common ADT port from the SAP instance when possible, for example instance `00` → `https://host:44300`, and asks for confirmation only when configuring the selected entry.
 - **Credential handling:** username/password local entries use VS Code MCP input prompts (`${input:...}`) at server start. Plain SAP credentials are not written to `mcp.json`.
-- **Login methods:** local entries use either username/password or Windows / smart card SSO. SSO sets `SAP_SSO=true` for the VSP runtime, which drives Microsoft Edge for the login and re-opens an Edge window only when the cached session can no longer be refreshed silently.
+- **Login methods:** local entries use either username/password or Windows / smart card SSO. SSO sets `SAP_SSO=true` for the VSP runtime, which drives Microsoft Edge for the login: the first sign-in opens an Edge window immediately, and an expired session is refreshed without a window for up to 15 seconds before Edge opens again. While a sign-in is pending, the MCP server output repeats a reminder every 15 seconds. If a sign-in fails — the browser cannot start, its window is closed, or the sign-in times out — the server retries with the next Chromium-based browser it finds (Microsoft Edge, Google Chrome, Brave, Vivaldi, Chromium, including per-user installs and Windows App Paths registrations), or once more with the only one, and logs each attempt with its reason.
 - **IP-address HTTPS self-healing:** if the confirmed ADT URL is `https://<ip>:<port>` and the certificate is issued to DNS names, setup reads the certificate DNS SANs automatically and stores them as `SAP_TLS_SERVER_NAMES`. At runtime a loopback proxy dials the IP address but verifies TLS against those discovered DNS names, trying them one by one. Certificate verification stays enabled; there is no `--insecure` mode.
 - **Private CAs:** if the SAP HTTPS certificate chains to an internal CA that is not trusted by the local Node runtime, set `SAP_TLS_CA_FILE` or `SAP_AI_DEV_TOOLKIT_TLS_CA_FILE` to a PEM CA bundle. This adds trust roots for the self-healing proxy without disabling certificate validation.
 - **Redirect and request safety:** local loopback proxies reject cross-origin forward-form requests and rewrite same-origin SAP redirects back through the loopback listener, so VSP stays on the safe route.
@@ -809,6 +809,9 @@ The response contains a `tools` array. A `RunQuery` entry resembles this excerpt
 | `SAP_AI_DEV_TOOLKIT_MODE` | VSP child mode (`expert` by default; `focused` omits `ActivateMultiple`, `GetUserTransports`, and `GetTransportInfo`). The proxy exposes its curated tool subset and local workflow tools, including `LintABAP`. |
 | `SAP_ALLOW_TRANSPORTABLE_EDITS` | Generated MCP entries set this to `true` to permit source edits in transportable packages; VSP safety checks and SAP authorizations still apply. |
 | `SAP_AUTH_MODE=sso` | Local SAP GUI entry mode for Windows / smart card SSO. Runtime starts VSP with `SAP_SSO=true`, which signs in through Microsoft Edge and caches the session per system and client. Older `windows-sso`, `browser-saml`, and `saml-password` entries are treated as `sso`. |
+| `SAP_SSO_FIRST_LOGIN` | Local SSO entries default to `window`: with no cached session, VSP opens the Edge sign-in window at once. Set `silent` to try a hidden browser first. |
+| `SAP_SSO_SILENT_TIMEOUT` | How long a hidden SSO refresh may run before the Edge window opens, as a Go duration. Local SSO entries default to `15s`; VSP's own default is `45s`. |
+| `SAP_BROWSER_EXEC` | Full path of the Chromium-based browser for SSO sign-in. It is tried first; the other browsers found on the machine remain fallbacks. |
 | `SAP_TLS_SERVER_NAMES` / `SAP_AI_DEV_TOOLKIT_TLS_SERVER_NAMES` | Comma-separated local SAP GUI TLS self-healing names, normally auto-discovered during setup from the SAP HTTPS certificate when `SAP_URL` uses an IP address. Runtime tries them one by one while keeping certificate validation enabled. |
 | `SAP_TLS_SERVER_NAME` / `SAP_AI_DEV_TOOLKIT_TLS_SERVER_NAME` | Single-name compatibility form of the local SAP GUI TLS self-healing override. Prefer the auto-discovered plural variable written by setup. |
 | `SAP_TLS_CA_FILE` / `SAP_AI_DEV_TOOLKIT_TLS_CA_FILE` | Optional PEM CA bundle for the local TLS self-healing proxy when the SAP HTTPS certificate chains to a private CA that is not in the OS/Node trust store. Certificate verification remains enabled. |

package/dist/checksums.txt

@@ -1,5 +1,5 @@
-02831a47fa28a1807d94f6b8485c21f1221c7b3aa0a2b9b7bf0682ab4fb5618f  vsp-linux-x64
-4398dac4c9d304d63e03abbb86523b61e5180b5b355dd1a2ed0d2405454cc8f7  vsp-linux-arm64
-356a10913b7a46a8ed67132e9b15ea7ff92b8adeb1c799111866e9af176e85fe  vsp-darwin-x64
-fb5e72a59618578187eb8e4374571b32baab34397766fc6ea8ab328c6cea849b  vsp-darwin-arm64
-50d5c74194063bc9bcc641fb580f1c1232cce0c1577cdad6dc503f41efd3344c  vsp-win32-x64.exe
+0be30e23546799f11b2632cb77cb1eac9f5d6f1ed900f6d8c6843b8909827341  vsp-linux-x64
+6fab2480c6cf8b9600ae5ba28155ada86f43a2968ef6a324c93b544c13748d8d  vsp-linux-arm64
+63f889fda4cc529f9cd3eeb4b106bd070cffa9295ee4a781e80a8a23f268a9b1  vsp-darwin-x64
+715f5e58f34908eb0357db456c43878361cc8c94e39e39427100326a30fb85a2  vsp-darwin-arm64
+e8b61a148451758ecaca81789d182c22f43582d394dd846de5afc8939f94e082  vsp-win32-x64.exe

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sap-ai-dev-toolkit",
-  "version": "0.9.91",
+  "version": "0.9.94",
   "description": "SAP AI development toolkit for BAS, ABAP, RAP, CAP, HANA Cloud, Fiori, UI5, and MCP",
   "author": "Gurkan Yilmaz",
   "type": "module",

package/patches/vsp-bas-proxy-auth.patch

@@ -1,5 +1,5 @@
 diff --git a/cmd/vsp/main.go b/cmd/vsp/main.go
-index 5007935..b2bc6be 100755
+index 5007935..3b1fdd8 100755
 --- a/cmd/vsp/main.go
 +++ b/cmd/vsp/main.go
 @@ -100,6 +100,7 @@ func init() {
@@ -10,7 +10,16 @@ index 5007935..b2bc6be 100755
  	rootCmd.Flags().StringVarP(&cfg.Username, "user", "u", "", "SAP username")
  	rootCmd.Flags().StringVarP(&cfg.Password, "password", "p", "", "SAP password")
  	rootCmd.Flags().StringVar(&cfg.Password, "pass", "", "SAP password (alias for --password)")
-@@ -170,6 +171,7 @@ func init() {
+@@ -126,6 +127,8 @@ func init() {
+ 	rootCmd.Flags().String("sso-profile", "", "Browser profile directory for SSO (a Windows path when running under WSL)")
+ 	rootCmd.Flags().String("sso-helper", "", "Path to the Windows SSO capture helper (vsp-sso.exe), used under WSL")
+ 	rootCmd.Flags().String("sso-on-expiry", "window", "When a silent SSO refresh needs a human: 'window' opens a browser, 'error' reports what to run")
++	rootCmd.Flags().String("sso-first-login", "", "With no cached SSO session: 'window' signs in through a visible browser window at once (default: try silently first)")
++	rootCmd.Flags().String("sso-silent-timeout", "", "Budget for a silent SSO capture, as a Go duration (default 45s)")
+ 	rootCmd.Flags().Bool("saml-auth", false, "Authenticate via programmatic SAML SSO (no browser, no MFA)")
+ 	rootCmd.Flags().String("saml-user", "", "SAML/IAS username (email)")
+ 	rootCmd.Flags().String("saml-password", "", "SAML/IAS password")
+@@ -170,6 +173,7 @@ func init() {
  	rootCmd.PersistentFlags().BoolVarP(&cfg.Verbose, "verbose", "v", false, "Enable verbose output to stderr")
  
  	// Bind flags to viper for environment variable support
@@ -18,7 +27,16 @@ index 5007935..b2bc6be 100755
  	viper.BindPFlag("url", rootCmd.Flags().Lookup("url"))
  	viper.BindPFlag("user", rootCmd.Flags().Lookup("user"))
  	viper.BindPFlag("password", rootCmd.Flags().Lookup("password"))
-@@ -233,6 +235,9 @@ func runServer(cmd *cobra.Command, args []string) error {
+@@ -186,6 +190,8 @@ func init() {
+ 	viper.BindPFlag("sso-profile", rootCmd.Flags().Lookup("sso-profile"))
+ 	viper.BindPFlag("sso-helper", rootCmd.Flags().Lookup("sso-helper"))
+ 	viper.BindPFlag("sso-on-expiry", rootCmd.Flags().Lookup("sso-on-expiry"))
++	viper.BindPFlag("sso-first-login", rootCmd.Flags().Lookup("sso-first-login"))
++	viper.BindPFlag("sso-silent-timeout", rootCmd.Flags().Lookup("sso-silent-timeout"))
+ 	viper.BindPFlag("saml-auth", rootCmd.Flags().Lookup("saml-auth"))
+ 	viper.BindPFlag("saml-user", rootCmd.Flags().Lookup("saml-user"))
+ 	viper.BindPFlag("saml-password", rootCmd.Flags().Lookup("saml-password"))
+@@ -233,6 +239,9 @@ func runServer(cmd *cobra.Command, args []string) error {
  	}
  
  	// Browser-based SSO authentication (must run before processCookieAuth)
@@ -28,7 +46,7 @@ index 5007935..b2bc6be 100755
  	if err := processBrowserAuth(cmd); err != nil {
  		return err
  	}
-@@ -346,6 +351,7 @@ func runServer(cmd *cobra.Command, args []string) error {
+@@ -346,6 +355,7 @@ func runServer(cmd *cobra.Command, args []string) error {
  }
  
  func resolveConfig(cmd *cobra.Command) {
@@ -36,7 +54,7 @@ index 5007935..b2bc6be 100755
  	// Check if cookie auth is explicitly requested via CLI flags OR env vars
  	// If so, we should NOT load user/password from env/.env to avoid conflicts
  	// Cookie auth takes precedence over basic auth since it's more explicit
-@@ -530,6 +536,24 @@ func validateConfig() error {
+@@ -530,6 +540,24 @@ func validateConfig() error {
  	return nil
  }
  
@@ -61,7 +79,7 @@ index 5007935..b2bc6be 100755
  func processBrowserAuth(cmd *cobra.Command) error {
  	browserAuth, _ := cmd.Flags().GetBool("browser-auth")
  	if !browserAuth && !viper.GetBool("BROWSER_AUTH") {
-@@ -599,6 +623,9 @@ func ssoRequested(cmd *cobra.Command) bool {
+@@ -599,6 +627,9 @@ func ssoRequested(cmd *cobra.Command) bool {
  // days will outlive any session it starts with, and the point of the exercise
  // is that nobody has to notice when it does.
  func processSSOAuth(cmd *cobra.Command) error {
@@ -71,7 +89,46 @@ index 5007935..b2bc6be 100755
  	if !ssoRequested(cmd) {
  		return nil
  	}
-@@ -657,6 +684,9 @@ func processSSOAuth(cmd *cobra.Command) error {
+@@ -626,22 +657,28 @@ func processSSOAuth(cmd *cobra.Command) error {
+ 	}
+ 
+ 	onExpiry := stringOpt("sso-on-expiry", "SSO_ON_EXPIRY")
++	silentTimeout, err := parseOptionalDuration(stringOpt("sso-silent-timeout", "SSO_SILENT_TIMEOUT"), "--sso-silent-timeout")
++	if err != nil {
++		return err
++	}
+ 	provider, err := adt.NewSSOProvider(adt.SSOConfig{
+-		System:      stringOpt("sso-system", "SSO_SYSTEM"),
+-		BaseURL:     cfg.BaseURL,
+-		Client:      cfg.Client,
+-		TriggerURL:  stringOpt("sso-trigger-url", "SSO_TRIGGER_URL"),
+-		Profile:     stringOpt("sso-profile", "SSO_PROFILE"),
+-		HelperPath:  stringOpt("sso-helper", "SSO_HELPER"),
+-		Interactive: !strings.EqualFold(onExpiry, "error"),
+-		Insecure:    cfg.InsecureSkipVerify,
+-		Verbose:     cfg.Verbose,
++		System:        stringOpt("sso-system", "SSO_SYSTEM"),
++		BaseURL:       cfg.BaseURL,
++		Client:        cfg.Client,
++		TriggerURL:    stringOpt("sso-trigger-url", "SSO_TRIGGER_URL"),
++		Profile:       stringOpt("sso-profile", "SSO_PROFILE"),
++		HelperPath:    stringOpt("sso-helper", "SSO_HELPER"),
++		BrowserPath:   stringOpt("browser-exec", "BROWSER_EXEC"),
++		Interactive:   !strings.EqualFold(onExpiry, "error"),
++		SilentTimeout: silentTimeout,
++		Insecure:      cfg.InsecureSkipVerify,
++		Verbose:       cfg.Verbose,
+ 	})
+ 	if err != nil {
+ 		return err
+ 	}
+ 
+-	cookies, err := provider.Cookies(cmd.Context())
++	cookies, err := provider.Start(cmd.Context(), strings.EqualFold(stringOpt("sso-first-login", "SSO_FIRST_LOGIN"), "window"))
+ 	if err != nil {
+ 		return fmt.Errorf("browser SSO: %w", err)
+ 	}
+@@ -657,6 +694,9 @@ func processSSOAuth(cmd *cobra.Command) error {
  }
  
  func processSAMLAuth(cmd *cobra.Command) error {
@@ -81,7 +138,7 @@ index 5007935..b2bc6be 100755
  	samlAuth, _ := cmd.Flags().GetBool("saml-auth")
  	if !samlAuth && !viper.GetBool("SAML_AUTH") {
  		return nil
-@@ -752,6 +782,9 @@ func processSAMLAuth(cmd *cobra.Command) error {
+@@ -752,6 +792,9 @@ func processSAMLAuth(cmd *cobra.Command) error {
  }
  
  func processCookieAuth(cmd *cobra.Command) error {
@@ -256,6 +313,19 @@ index dd433d6..5553b7f 100644
  			),
  		), s.handleActivateMultiple)
  	}
+diff --git a/pkg/adt/browser_auth.go b/pkg/adt/browser_auth.go
+index ea3c1a9..5bc7a01 100644
+--- a/pkg/adt/browser_auth.go
++++ b/pkg/adt/browser_auth.go
+@@ -86,6 +86,8 @@ func friendlyBrowserName(path string) string {
+ 		return "Microsoft Edge"
+ 	case strings.Contains(lower, "brave"):
+ 		return "Brave"
++	case strings.Contains(lower, "vivaldi"):
++		return "Vivaldi"
+ 	case strings.Contains(lower, "chromium"):
+ 		return "Chromium"
+ 	default:
 diff --git a/pkg/adt/client.go b/pkg/adt/client.go
 index 979e908..c7e9501 100755
 --- a/pkg/adt/client.go
@@ -493,19 +563,31 @@ index 0000000..80741da
 +}
 +
 diff --git a/pkg/adt/sso.go b/pkg/adt/sso.go
-index d67c4e8..4e9dc45 100644
+index d67c4e8..a03f740 100644
 --- a/pkg/adt/sso.go
 +++ b/pkg/adt/sso.go
-@@ -155,7 +155,7 @@ func CaptureSSOCookies(ctx context.Context, opts SSOOptions) (map[string]string,
+@@ -7,6 +7,7 @@ import (
+ 	"net/url"
+ 	"os"
+ 	"path/filepath"
++	"strings"
+ 	"time"
+ 
+ 	"github.com/chromedp/cdproto/network"
+@@ -154,8 +155,11 @@ func CaptureSSOCookies(ctx context.Context, opts SSOOptions) (map[string]string,
+ 	// regardless, so a navigation error here is not fatal — the cookie poll
  	// below is the real verdict.
  	if err := chromedp.Run(timeoutCtx, chromedp.Navigate(opts.TriggerURL)); err != nil {
++		if chromedp.FromContext(timeoutCtx).Browser == nil {
++			return nil, browserStartFailure(opts.Headless, browserName, execPath, err)
++		}
  		if timeoutCtx.Err() != nil {
 -			return nil, fmt.Errorf("SSO capture timed out after %s", timeout)
 +			return nil, navigationTimeout(opts.Headless, timeout)
  		}
  		if opts.Verbose {
  			fmt.Fprintf(os.Stderr, "[SSO] navigation reported %v (normal during SSO)\n", err)
-@@ -174,6 +174,17 @@ func CaptureSSOCookies(ctx context.Context, opts SSOOptions) (map[string]string,
+@@ -174,6 +178,26 @@ func CaptureSSOCookies(ctx context.Context, opts SSOOptions) (map[string]string,
  	return cookies, nil
  }
  
@@ -519,10 +601,124 @@ index d67c4e8..4e9dc45 100644
 +	}
 +	return fmt.Errorf("SSO capture timed out after %s", timeout)
 +}
++
++// browserStartFailure ends a capture whose browser never came up; a silent one still escalates to a window.
++func browserStartFailure(headless bool, name, path string, err error) error {
++	detail := strings.Join(strings.Fields(err.Error()), " ")
++	if headless {
++		return fmt.Errorf("%w: %s did not start without a window (%s): %s", ErrSSOInteractiveRequired, name, path, detail)
++	}
++	return fmt.Errorf("%s could not be started from %s: %s", name, path, detail)
++}
 +
  // DefaultSSOProfileDir returns a per-host browser profile directory under the
  // user's cache location. Keeping one profile per host means a silent refresh
  // for one system is never disturbed by a login to another.
+diff --git a/pkg/adt/sso_browser_start_test.go b/pkg/adt/sso_browser_start_test.go
+new file mode 100644
+index 0000000..88a9dbe
+--- /dev/null
++++ b/pkg/adt/sso_browser_start_test.go
+@@ -0,0 +1,41 @@
++package adt
++
++import (
++	"context"
++	"errors"
++	"os"
++	"path/filepath"
++	"runtime"
++	"strings"
++	"testing"
++	"time"
++)
++
++func TestBrowserThatCannotStartFailsFast(t *testing.T) {
++	if runtime.GOOS == "windows" {
++		t.Skip("the stand-in browser is a shell script")
++	}
++	browser := filepath.Join(t.TempDir(), "blocked-browser")
++	if err := os.WriteFile(browser, []byte("#!/bin/sh\necho 'blocked by policy' >&2\nexit 3\n"), 0o755); err != nil {
++		t.Fatal(err)
++	}
++	for _, headless := range []bool{true, false} {
++		started := time.Now()
++		_, err := CaptureSSOCookies(context.Background(), SSOOptions{
++			TriggerURL:  "https://sap.example/sap/bc/adt/",
++			BrowserPath: browser,
++			Headless:    headless,
++			Timeout:     45 * time.Second,
++		})
++		if elapsed := time.Since(started); elapsed > 15*time.Second {
++			t.Fatalf("headless=%v waited %v; a browser that never starts must not wait out the budget", headless, elapsed)
++		}
++		if err == nil || !strings.Contains(err.Error(), browser) || !strings.Contains(err.Error(), "blocked by policy") {
++			t.Fatalf("headless=%v err = %v, want the browser path and its output", headless, err)
++		}
++		// A silent start failure must still escalate to a visible window.
++		if errors.Is(err, ErrSSOInteractiveRequired) != headless {
++			t.Fatalf("headless=%v err = %v, want ErrSSOInteractiveRequired only when silent", headless, err)
++		}
++	}
++}
+diff --git a/pkg/adt/sso_first_login_test.go b/pkg/adt/sso_first_login_test.go
+new file mode 100644
+index 0000000..f8efda4
+--- /dev/null
++++ b/pkg/adt/sso_first_login_test.go
+@@ -0,0 +1,52 @@
++package adt
++
++import (
++	"context"
++	"os"
++	"testing"
++)
++
++func TestStartWithWindowFirstReusesACachedSession(t *testing.T) {
++	t.Setenv("HOME", t.TempDir())
++	p, err := NewSSOProvider(SSOConfig{System: "devsys", BaseURL: "https://sap.example"})
++	if err != nil {
++		t.Fatal(err)
++	}
++	if err := SaveSSOSession(p.CachePath(), "sap.example", map[string]string{"SAP_SESSIONID_X": "live"}); err != nil {
++		t.Fatal(err)
++	}
++	// A browser launch here would fail the test on a build machine.
++	got, err := p.Start(context.Background(), true)
++	if err != nil {
++		t.Fatalf("Start: %v", err)
++	}
++	if got["SAP_SESSIONID_X"] != "live" {
++		t.Errorf("cookies = %v, want the cached session", got)
++	}
++}
++
++func TestHasSessionDecidesWhetherTheFirstSignInNeedsAWindow(t *testing.T) {
++	t.Setenv("HOME", t.TempDir())
++	p, err := NewSSOProvider(SSOConfig{System: "devsys", BaseURL: "https://sap.example"})
++	if err != nil {
++		t.Fatal(err)
++	}
++	if p.hasSession() {
++		t.Fatal("an empty cache must send the first sign-in to a window")
++	}
++	if err := SaveSSOSession(p.CachePath(), "sap.example", map[string]string{"SAP_SESSIONID_X": "live"}); err != nil {
++		t.Fatal(err)
++	}
++	if !p.hasSession() {
++		t.Fatal("a cached session must be reused, not replaced by a window")
++	}
++	if err := os.Remove(p.CachePath()); err != nil {
++		t.Fatal(err)
++	}
++	if err := os.Mkdir(p.CachePath(), 0700); err != nil {
++		t.Fatal(err)
++	}
++	if !p.hasSession() {
++		t.Fatal("an unreadable cache must reach Cookies, which reports the read error")
++	}
++}
 diff --git a/pkg/adt/sso_navigation_test.go b/pkg/adt/sso_navigation_test.go
 new file mode 100644
 index 0000000..c851021
@@ -545,3 +741,53 @@ index 0000000..c851021
 +		t.Fatalf("headed timeout = %v, must not ask for yet another window", err)
 +	}
 +}
+diff --git a/pkg/adt/sso_provider.go b/pkg/adt/sso_provider.go
+index 8e5bed4..544b873 100644
+--- a/pkg/adt/sso_provider.go
++++ b/pkg/adt/sso_provider.go
+@@ -42,6 +42,9 @@ type SSOConfig struct {
+ 	// HelperPath points at the Windows capture helper. Empty auto-discovers it.
+ 	HelperPath string
+ 
++	// BrowserPath is the Chromium-based browser to drive. Empty auto-detects one.
++	BrowserPath string
++
+ 	// Interactive permits escalating to a visible browser window when a silent
+ 	// capture cannot finish. Off means such a case is reported as an error
+ 	// naming the command to run, which is the right behaviour where no one is
+@@ -180,6 +183,27 @@ func (p *SSOProvider) Login(ctx context.Context) (map[string]string, error) {
+ 	return p.acquire(ctx, true)
+ }
+ 
++// Start returns the session a server begins with; windowFirst skips the silent attempt when nothing is cached.
++func (p *SSOProvider) Start(ctx context.Context, windowFirst bool) (map[string]string, error) {
++	if windowFirst && !p.hasSession() {
++		fmt.Fprintf(os.Stderr, "[SSO] no cached session — opening a browser window to sign in\n")
++		return p.Login(ctx)
++	}
++	return p.Cookies(ctx)
++}
++
++// hasSession counts an unreadable cache as present so Cookies can report why.
++func (p *SSOProvider) hasSession() bool {
++	p.mu.Lock()
++	held := len(p.current) > 0
++	p.mu.Unlock()
++	if held {
++		return true
++	}
++	sess, err := LoadSSOSession(p.cachePath)
++	return err != nil || sess != nil
++}
++
+ // Clear removes the cached session, so the next call captures a fresh one.
+ func (p *SSOProvider) Clear() error {
+ 	p.mu.Lock()
+@@ -240,6 +264,7 @@ func (p *SSOProvider) capture(ctx context.Context, trigger string, headed bool)
+ 	return CaptureSSOCookies(ctx, SSOOptions{
+ 		TriggerURL:  trigger,
+ 		UserDataDir: p.cfg.Profile,
++		BrowserPath: p.cfg.BrowserPath,
+ 		Headless:    !headed,
+ 		Timeout:     p.timeout(headed),
+ 		Insecure:    p.cfg.Insecure,

package/src/launcher.mjs

@@ -12,6 +12,7 @@ import { installMcpConfig, npxMcpLauncher, repairManagedMcpConfig } from './mcp-
 import { runSetup } from './setup.mjs';
 import { resolveConfiguredCloudFoundryDestination } from './cf-destination.mjs';
 import { createTlsServerNameAdtProxy } from './tls-adt-proxy.mjs';
+import { findSsoBrowsers } from './sso-browsers.mjs';
 import { withBrandedEnvironment } from './branding.mjs';
 import { redactText } from './redact.mjs';
 import { startProgress } from './terminal-ui.mjs';
@@ -301,6 +302,8 @@ async function configuredLocalSapGuiDestination(env) {
   if (sso) {
     const cacheKey = `${systemId || new URL(configuredUrl).hostname}-${client}`.toLowerCase().replace(/[^a-z0-9.-]+/g, '-');
     if (isIP(new URL(adt.url).hostname.replace(/^\[(.*)\]$/, '$1'))) logLine(`[sap-ai-dev] ${name}: SSO is configured for an IP address; Kerberos and the browser certificate check need the DNS host name`);
+    const ssoBrowsers = await findSsoBrowsers({ env });
+    logLine(`[sap-ai-dev] ${name}: ${ssoBrowsers.length ? `SSO browsers: ${ssoBrowsers.map(browser => `${browser.name} (${browser.path})`).join(', ')}` : 'no Chromium-based browser found for SSO; install Microsoft Edge or set SAP_BROWSER_EXEC'}`);
     return {
       source: 'sap-gui-local',
       name,
@@ -308,8 +311,10 @@ async function configuredLocalSapGuiDestination(env) {
       client,
       systemId,
       authentication: 'SSO',
+      ssoBrowsers,
       // SAP_SAML_AUTH survives sanitizeChildEnv and would make VSP demand SAML credentials.
-      childEnv: { SAP_SSO: 'true', SAP_SSO_SYSTEM: cacheKey, SAP_SAML_AUTH: '', ...direct },
+      // A first sign-in has no session a hidden browser could renew, so its window opens at once.
+      childEnv: { SAP_SSO: 'true', SAP_SSO_SYSTEM: cacheKey, SAP_SAML_AUTH: '', SAP_SSO_FIRST_LOGIN: env.SAP_SSO_FIRST_LOGIN || 'window', SAP_SSO_SILENT_TIMEOUT: env.SAP_SSO_SILENT_TIMEOUT || '15s', ...(ssoBrowsers.length ? { SAP_BROWSER_EXEC: ssoBrowsers[0].path } : {}), ...direct },
       probe
     };
   }
@@ -408,12 +413,14 @@ async function main() {
   }
 
   if (['cloud-foundry', 'sap-gui-local'].includes(runtimeEnv.SAP_AI_DEV_TOOLKIT_DESTINATION_SOURCE)) {
+    logLine(`[sap-ai-dev] sap-ai-dev-toolkit v${pkg.version} (node ${process.version}, pid ${process.pid})`);
     const destination = runtimeEnv.SAP_AI_DEV_TOOLKIT_DESTINATION_SOURCE === 'cloud-foundry'
       ? await resolveConfiguredCloudFoundryDestination({ env: runtimeEnv })
       : await configuredLocalSapGuiDestination(runtimeEnv);
     let proxy;
     try {
       const binary = await binaryOrError();
+      logLine(`[sap-ai-dev] VSP binary: ${binary}`);
       proxy = new MCPProxy({ binary, destinations: [destination], env: runtimeEnv, log: logLine, version: pkg.version });
       const shutdown = signal => { void proxy.close().finally(() => process.exit(signal === 'SIGINT' ? 130 : 143)); };
       process.once('SIGINT', () => shutdown('SIGINT'));

package/src/mcp-proxy.mjs

@@ -228,8 +228,11 @@ class Child {
     this.process.stdout.on('data', chunk => this.onData(chunk));
     this.process.stderr.setEncoding('utf8');
     this.process.stderr.on('data', chunk => {
-      if (options.log) options.log(`[${destination.name}] ${redactText(chunk).trimEnd()}`);
+      const text = redactText(chunk).trimEnd();
+      this.lastError = text.split(/\r?\n/).filter(line => line.startsWith('Error: ')).pop()?.slice(7) ?? this.lastError;
+      if (options.log) options.log(`[${destination.name}] ${text}`);
     });
+    this.stderrClosed = once(this.process.stderr, 'close').catch(() => {});
     // A write racing child death surfaces as an EPIPE 'error' event on stdin.
     // Without a listener that is an uncaught exception that kills the whole
     // MCP server — exactly the crash window self-healing is meant to cover.
@@ -324,6 +327,14 @@ class Child {
     try { this.process.stdin.write(`${JSON.stringify({ jsonrpc: JSONRPC, method, ...(params === undefined ? {} : { params })})}\n`); } catch {}
   }
 
+  // VSP's own "Error:" line explains an exit, and stderr can still be draining when 'exit' fires.
+  async stopReason(waitMs = 1000) {
+    let timer;
+    await Promise.race([this.stderrClosed, new Promise(resolve => { timer = setTimeout(resolve, waitMs); })]);
+    clearTimeout(timer);
+    return this.lastError;
+  }
+
   async initialize(params) {
     const response = await this.request('initialize', params);
     this.notify('notifications/initialized');
@@ -387,7 +398,7 @@ class Child {
 }
 
 export class MCPProxy {
-  constructor({ binary, destinations, env = process.env, spawn = nodeSpawn, childArgs, log = message => console.error(message), output = line => process.stdout.write(`${line}\n`), version = '0.0.0' }) {
+  constructor({ binary, destinations, env = process.env, spawn = nodeSpawn, childArgs, log = message => console.error(message), output = line => process.stdout.write(`${line}\n`), version = '0.0.0', ssoHeartbeatMs = 15_000 }) {
     this.binary = binary;
     this.destinations = destinations;
     this.env = env;
@@ -396,6 +407,7 @@ export class MCPProxy {
     this.log = log;
     this.output = output;
     this.version = version;
+    this.ssoHeartbeatMs = ssoHeartbeatMs;
     this.requestTimeoutMs = requestTimeoutMs(env);
     this.children = [];
     this.started = false;
@@ -530,17 +542,33 @@ export class MCPProxy {
     // Children initialize concurrently; healthy entries keep destination
     // order so tool naming stays deterministic.
     const initialized = await Promise.all(this.children.map(async entry => {
+      const { destination } = entry;
       const startedAt = Date.now();
-      this.eventSink(`[${entry.destination.name}] initializing VSP MCP session`);
-      try {
-        entry.server = await entry.child.initialize(params);
-        this.eventSink(`[${entry.destination.name}] VSP MCP session initialized (${Date.now() - startedAt}ms)`);
-        return entry;
-      } catch (error) {
-        this.eventSink(`[${entry.destination.name}] initialization failed: ${diagnosticText(error.message)}`, 'error');
-        await entry.child.close();
-        await closeDestinationRoute(entry.destination);
-        return null;
+      this.eventSink(`[${destination.name}] initializing VSP MCP session`);
+      for (let attempt = 1; ; attempt += 1) {
+        const attemptStartedAt = Date.now();
+        // VSP answers initialize only after its browser sign-in, which waits on a person.
+        const signIn = destination.authentication === 'SSO'
+          ? setInterval(() => this.eventSink(`[${destination.name}] still waiting for the SSO sign-in (${Math.round((Date.now() - attemptStartedAt) / 1000)} s): finish it in the browser window (it may be behind other windows); restarting the server cancels it`), this.ssoHeartbeatMs)
+          : undefined;
+        try {
+          entry.server = await entry.child.initialize(params).finally(() => clearInterval(signIn));
+          this.eventSink(`[${destination.name}] VSP MCP session initialized (${Date.now() - startedAt}ms)`);
+          return entry;
+        } catch (error) {
+          const reason = await entry.child.stopReason();
+          const failure = `${diagnosticText(error.message)}${reason ? `: ${diagnosticText(reason)}` : ''}`;
+          const next = this.signInRetry(destination, attempt, reason);
+          await entry.child.close();
+          if (!next) {
+            this.eventSink(`[${destination.name}] initialization failed: ${failure}`, 'error');
+            await closeDestinationRoute(destination);
+            return null;
+          }
+          this.eventSink(`[${destination.name}] SSO sign-in failed (${failure}); self-healing: retrying with ${next.name} (attempt ${attempt + 1} of ${next.attempts})`, 'warning');
+          destination.childEnv = { ...destination.childEnv, SAP_BROWSER_EXEC: next.path };
+          entry.child = new Child(this.binary, destination, this.childSpawnOptions(destination));
+        }
       }
     }));
     const healthy = initialized.filter(Boolean);
@@ -556,6 +584,15 @@ export class MCPProxy {
     return healthy;
   }
 
+  // A failed browser sign-in moves on to the next discovered browser, or tries the only one once more.
+  signInRetry(destination, attempt, reason) {
+    // A client that hung up gets no new sign-in windows.
+    if (destination.authentication !== 'SSO' || !/browser SSO/i.test(String(reason)) || this.inputEnded || this.shuttingDown) return null;
+    const browsers = destination.ssoBrowsers || [];
+    const plan = browsers.length === 1 ? [browsers[0], browsers[0]] : browsers;
+    return attempt < plan.length ? { ...plan[attempt], attempts: plan.length } : null;
+  }
+
   toolsCacheValid() {
     const cached = this.toolsCache;
     if (!cached) return false;
@@ -817,6 +854,7 @@ export class MCPProxy {
     input.on('data', onData);
     try {
       await once(input, 'end');
+      this.inputEnded = true;
       await Promise.allSettled([...inFlight]);
     } finally {
       input.off('data', onData);

package/src/sso-browsers.mjs

@@ -0,0 +1,90 @@
+import { execFile } from 'node:child_process';
+import { access, constants } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { posix, win32 } from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+// Edge leads: Entra device-based Conditional Access only completes in a browser bridged to the Windows account broker.
+const BROWSERS = [
+  { windows: 'Microsoft\\Edge\\Application\\msedge.exe', appPath: 'msedge.exe', mac: 'Microsoft Edge', linux: ['microsoft-edge', 'microsoft-edge-stable'] },
+  { windows: 'Google\\Chrome\\Application\\chrome.exe', appPath: 'chrome.exe', mac: 'Google Chrome', linux: ['google-chrome', 'google-chrome-stable'] },
+  { windows: 'BraveSoftware\\Brave-Browser\\Application\\brave.exe', appPath: 'brave.exe', mac: 'Brave Browser', linux: ['brave-browser'] },
+  { windows: 'Vivaldi\\Application\\vivaldi.exe', appPath: 'vivaldi.exe', mac: 'Vivaldi', linux: ['vivaldi'] },
+  { windows: 'Chromium\\Application\\chrome.exe', mac: 'Chromium', linux: ['chromium', 'chromium-browser'] }
+];
+
+function envValue(env, name) {
+  if (env[name] !== undefined) return env[name];
+  const key = Object.keys(env).find(candidate => candidate.toLowerCase() === name.toLowerCase());
+  return key === undefined ? undefined : env[key];
+}
+
+export function ssoBrowserName(path) {
+  const lower = String(path).toLowerCase();
+  if (lower.includes('edge')) return 'Microsoft Edge';
+  if (lower.includes('brave')) return 'Brave';
+  if (lower.includes('vivaldi')) return 'Vivaldi';
+  if (lower.includes('chromium')) return 'Chromium';
+  if (lower.includes('chrome')) return 'Google Chrome';
+  return 'browser';
+}
+
+// Localized Windows names the default value "(Standard)" and the like, so it is found by its type.
+export function parseAppPath(output, env = {}) {
+  const value = /REG_(?:EXPAND_)?SZ\s+(.+?)\s*$/m.exec(String(output))?.[1];
+  if (!value) return '';
+  return value.replace(/^"(.*)"$/, '$1').replace(/%([^%]+)%/g, (match, name) => envValue(env, name) ?? match);
+}
+
+async function registeredAppPaths(exe, env) {
+  const found = await Promise.all(['HKLM', 'HKCU'].map(async hive => {
+    try {
+      const { stdout } = await execFileAsync('reg', ['query', `${hive}\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths\\${exe}`, '/ve'], { windowsHide: true, timeout: 5000 });
+      return parseAppPath(stdout, env);
+    } catch {
+      return '';
+    }
+  }));
+  return found.filter(Boolean);
+}
+
+async function fileExists(path) {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Every Chromium-based browser VSP can drive, best first; SAP_BROWSER_EXEC pins one ahead of the rest.
+export async function findSsoBrowsers({ env = process.env, platform = process.platform, exists = fileExists, appPaths = registeredAppPaths } = {}) {
+  const candidates = [];
+  const pinned = envValue(env, 'SAP_BROWSER_EXEC');
+  if (pinned) candidates.push(pinned);
+  if (platform === 'win32') {
+    const roots = [envValue(env, 'ProgramFiles') || 'C:\\Program Files', envValue(env, 'ProgramFiles(x86)') || 'C:\\Program Files (x86)', envValue(env, 'LOCALAPPDATA')].filter(Boolean);
+    const registered = await Promise.all(BROWSERS.map(browser => (browser.appPath ? appPaths(browser.appPath, env) : [])));
+    BROWSERS.forEach((browser, index) => candidates.push(...roots.map(root => win32.join(root, browser.windows)), ...registered[index]));
+  } else if (platform === 'darwin') {
+    const home = envValue(env, 'HOME') || homedir();
+    for (const browser of BROWSERS) {
+      for (const root of ['/Applications', posix.join(home, 'Applications')]) candidates.push(posix.join(root, `${browser.mac}.app`, 'Contents', 'MacOS', browser.mac));
+    }
+  } else {
+    const directories = String(envValue(env, 'PATH') || '').split(':').filter(Boolean);
+    for (const browser of BROWSERS) for (const command of browser.linux) candidates.push(...directories.map(directory => posix.join(directory, command)));
+  }
+  const seen = new Set();
+  const browsers = [];
+  for (const path of candidates) {
+    const key = platform === 'win32' ? path.toLowerCase() : path;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    // A pinned browser is kept even when missing, so its failure shows up in the log.
+    if (path === pinned || await exists(path)) browsers.push({ name: ssoBrowserName(path), path });
+  }
+  return browsers;
+}