sap-ai-dev-toolkit 0.9.92 → 0.9.97

package/README.md

@@ -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: 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.
+- **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.
@@ -338,7 +338,7 @@ Some current npm versions also require install hooks to be approved. If npm repo
 
 The setup report uses icons and terminal colors; set `NO_COLOR=1` to disable ANSI colors. Long-running steps (BAS destination discovery, ADT probes, VSP runtime provisioning, `--doctor` checks) show an animated progress line so the terminal never looks stuck; it appears only on interactive terminals and is disabled automatically on CI — set `SAP_AI_DEV_TOOLKIT_DISABLE_SCAN_ANIMATION=true` to turn it off. The table is a weather report, not a bouncer: green **PASS** means the ADT probe responded, red **FAIL** means it failed, and yellow **SKIPPED** means it was skipped. Probe failures do not block MCP registration or startup for destinations you select.
 
-Run `sap-ai-dev --setup` later to change the destination selection or remove generated destination entries. Run `sap-ai-dev --setup --tools` to also choose optional companion tools. Generated destination entries use the global `sap-ai-dev` command when it is on `PATH`; otherwise (for example after a pure npx setup) they automatically launch the pinned package version through `npx`, routed through `cmd /c npx` on Windows so every MCP host can spawn them. Pass `--npx` to force the npx launcher even when a global command exists; companion tools already use `npx` with their own npm packages.
+Run `sap-ai-dev --setup` later to change the destination selection or remove generated destination entries. Run `sap-ai-dev --setup --tools` to also choose optional companion tools. Generated destination entries use the global `sap-ai-dev` command when it is on `PATH` and is the same package version as the setup that writes them; otherwise (for example after a pure npx setup, or when an older global install is still on `PATH`) they automatically launch the pinned package version through `npx`, routed through `cmd /c npx` on Windows so every MCP host can spawn them. Setup warns when it skips a global install of another version. Pass `--npx` to force the npx launcher even when a global command exists; companion tools already use `npx` with their own npm packages.
 
 If a setup step is skipped or fails, rerun it from an interactive terminal:
 
@@ -811,6 +811,7 @@ The response contains a `tools` array. A `RunQuery` entry resembles this excerpt
 | `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. |
@@ -823,6 +824,7 @@ The response contains a `tools` array. A `RunQuery` entry resembles this excerpt
 | `SAP_AI_DEV_TOOLKIT_BINARY_URL` | Alternate VSP binary download URL (checksum-verified). Legacy `BAS_VSP_BINARY_URL` still works. |
 | `SAP_AI_DEV_TOOLKIT_RELEASE_BASE_URL` | Override the base URL that VSP release binaries are downloaded from. |
 | `SAP_AI_DEV_TOOLKIT_CACHE_DIR` | Binary cache directory. Legacy `BAS_VSP_CACHE_DIR` still works. |
+| `SAP_AI_DEV_TOOLKIT_VERSION` | Written by setup into each destination entry: the toolkit version that configured it. An older `sap-ai-dev` started from that entry hands off to this version through `npx` (see Self-healing modes). |
 | `BAS_CF_SPACE_GUID`, `BAS_CF_DESTINATION_INSTANCE_GUID`, `BAS_CF_DESTINATION_INSTANCE`, `BAS_CF_DESTINATION_KEY`, `BAS_CF_DESTINATION_NAME`, `BAS_CF_CONNECTIVITY_INSTANCE_GUID`, `BAS_CF_CONNECTIVITY_INSTANCE`, `BAS_CF_CONNECTIVITY_KEY` | Written into generated Cloud Foundry destination entries; they reference service instances and key **names** (never credentials). |
 | `GO_BINARY` | Explicit Go executable for the repository-only `build:vsp` script; not used during installation. |
 | `SAP_AI_DEV_TOOLKIT_SKIP_PROBE=true` | Skip destination probes; useful for controlled diagnostics or fixtures. |
@@ -833,6 +835,7 @@ The response contains a `tools` array. A `RunQuery` entry resembles this excerpt
 
 VSP children connect to each configured destination URL directly. BAS destination authentication remains selected through VSP's `--proxy-auth` path; Cloud Foundry on-premise destinations continue through the separate Connectivity proxy.
 Child crash recovery restarts a failed VSP child, re-initializes it, re-registers tools, and retries the interrupted `tools/call` once before surfacing an error. State-changing tools are not retried.
+Stale launcher recovery: when an MCP entry starts a `sap-ai-dev` older than the `SAP_AI_DEV_TOOLKIT_VERSION` setup recorded in it (for example an outdated global install left on `PATH`), the launcher logs a warning and hands off to that version through `npx` on the same stdio, so the host never runs the stale launcher or VSP binary. A source checkout (`npm link`) always runs as-is.
 Existing installs that still set the previous `BAS_VSP_*` environment variables remain supported. The setup wizard writes new MCP entries with the `SAP_AI_DEV_TOOLKIT_*` names.
 
 #### Server logging

package/dist/checksums.txt

@@ -1,5 +1,5 @@
-40bba6b57e0656249b3de91f70504b49e56c4a72cd418de47d5b3c4ff5b78466  vsp-linux-x64
-86b1ecdf0f6af6778750b44caef6cc1e7f4ab9efc1cfe202f26766b85c48cbf4  vsp-linux-arm64
-9ee2823cea8fc456f2fcd249abe8ffbd72e7ca52a3731ee228efbabe7099b455  vsp-darwin-x64
-9148037eb23f6e80f03bb0080d3a12e5c73f25f8d2d9c262273b870ed0716782  vsp-darwin-arm64
-5494267d5c47bed9155507cf5b156932933ce0f6aaf7999c6c60afe1ecc6367f  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.92",
+  "version": "0.9.97",
   "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..715c0e9 100755
+index 5007935..3b1fdd8 100755
 --- a/cmd/vsp/main.go
 +++ b/cmd/vsp/main.go
 @@ -100,6 +100,7 @@ func init() {
@@ -89,7 +89,7 @@ index 5007935..715c0e9 100755
  	if !ssoRequested(cmd) {
  		return nil
  	}
-@@ -626,22 +657,27 @@ func processSSOAuth(cmd *cobra.Command) error {
+@@ -626,22 +657,28 @@ func processSSOAuth(cmd *cobra.Command) error {
  	}
  
  	onExpiry := stringOpt("sso-on-expiry", "SSO_ON_EXPIRY")
@@ -113,6 +113,7 @@ index 5007935..715c0e9 100755
 +		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,
@@ -127,7 +128,7 @@ index 5007935..715c0e9 100755
  	if err != nil {
  		return fmt.Errorf("browser SSO: %w", err)
  	}
-@@ -657,6 +693,9 @@ func processSSOAuth(cmd *cobra.Command) error {
+@@ -657,6 +694,9 @@ func processSSOAuth(cmd *cobra.Command) error {
  }
  
  func processSAMLAuth(cmd *cobra.Command) error {
@@ -137,7 +138,7 @@ index 5007935..715c0e9 100755
  	samlAuth, _ := cmd.Flags().GetBool("saml-auth")
  	if !samlAuth && !viper.GetBool("SAML_AUTH") {
  		return nil
-@@ -752,6 +791,9 @@ func processSAMLAuth(cmd *cobra.Command) error {
+@@ -752,6 +792,9 @@ func processSAMLAuth(cmd *cobra.Command) error {
  }
  
  func processCookieAuth(cmd *cobra.Command) error {
@@ -312,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
@@ -549,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
  }
  
@@ -575,10 +601,66 @@ 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
@@ -660,10 +742,20 @@ index 0000000..c851021
 +	}
 +}
 diff --git a/pkg/adt/sso_provider.go b/pkg/adt/sso_provider.go
-index 8e5bed4..6977a33 100644
+index 8e5bed4..544b873 100644
 --- a/pkg/adt/sso_provider.go
 +++ b/pkg/adt/sso_provider.go
-@@ -180,6 +180,27 @@ func (p *SSOProvider) Login(ctx context.Context) (map[string]string, error) {
+@@ -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)
  }
  
@@ -691,3 +783,11 @@ index 8e5bed4..6977a33 100644
  // 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

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
 import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import { isIP } from 'node:net';
 import { dirname, join } from 'node:path';
@@ -8,10 +9,11 @@ import { discoverDestinations, remediation, slugifyDestination, statusRows } fro
 import { adtBaseUrl, adtPort, detectAdtUrl, discoverSapGuiSystems, hasExplicitPort, hasPathPrefix } from './local-sap-gui.mjs';
 import { binaryTarget, cacheDirectory, downloadBinary, findBinary } from './binary.mjs';
 import { MCPProxy } from './mcp-proxy.mjs';
-import { installMcpConfig, npxMcpLauncher, repairManagedMcpConfig } from './mcp-config.mjs';
+import { configuredVersionHandoff, installMcpConfig, npxPackageLauncher, repairManagedMcpConfig } from './mcp-config.mjs';
 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';
@@ -267,6 +269,33 @@ function noProxyEnv(env, host) {
   return { NO_PROXY: noProxy, no_proxy: noProxy };
 }
 
+// Runs a child on this process's stdio and mirrors its exit; rejects only when it cannot start.
+async function runOnOwnStdio(command, commandArgs, env) {
+  const child = spawn(command, commandArgs, { env, stdio: 'inherit' });
+  process.once('SIGINT', () => child.kill('SIGINT'));
+  process.once('SIGTERM', () => child.kill('SIGTERM'));
+  const [code, signal] = await new Promise((resolve, reject) => {
+    child.once('error', reject);
+    child.once('exit', (exitCode, exitSignal) => resolve([exitCode, exitSignal]));
+  });
+  if (signal) process.kill(process.pid, signal);
+  process.exitCode = code ?? 1;
+}
+
+// A source checkout runs as-is: its developer chose that code.
+async function handOffToConfiguredVersion() {
+  const handoff = existsSync(join(root, '.git')) ? null : configuredVersionHandoff(runtimeEnv, pkg.version);
+  if (!handoff) return false;
+  logLine(`[sap-ai-dev] sap-ai-dev-toolkit ${pkg.version} is older than ${handoff.version}, which configured this MCP entry; self-healing: handing off to sap-ai-dev-toolkit@${handoff.version} through npx. Run "npm install -g sap-ai-dev-toolkit@${handoff.version}" to update the global install.`);
+  try {
+    await runOnOwnStdio(handoff.command, handoff.args, { ...runtimeEnv, SAP_AI_DEV_TOOLKIT_HANDOFF: pkg.version });
+    return true;
+  } catch (error) {
+    logLine(`[sap-ai-dev] handoff to sap-ai-dev-toolkit@${handoff.version} could not start (${error.message}); continuing with ${pkg.version}`);
+    return false;
+  }
+}
+
 async function discoverForCommand() {
   const env = { ...runtimeEnv };
   if (env.SAP_AI_DEV_TOOLKIT_DESTINATION_SOURCE === 'cloud-foundry') env.SAP_AI_DEV_TOOLKIT_DESTINATION = '';
@@ -301,6 +330,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,9 +339,10 @@ async function configuredLocalSapGuiDestination(env) {
       client,
       systemId,
       authentication: 'SSO',
+      ssoBrowsers,
       // SAP_SAML_AUTH survives sanitizeChildEnv and would make VSP demand SAML credentials.
       // 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', ...direct },
+      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
     };
   }
@@ -345,6 +377,7 @@ async function main() {
     process.stdout.write(usage());
     return;
   }
+  if (!setup && !check && !list && !doctor && !demo && await handOffToConfiguredVersion()) return;
   if (doctor && demo) throw new Error('Use either --doctor or --demo, not both.');
   if (demo) {
     await runOfflineDemo();
@@ -379,14 +412,8 @@ async function main() {
       detectAdtUrl: detectLocalAdtUrl
     };
     if (hasFlag('--npx')) {
-      // Windows has no npx.exe, so generated entries there launch through
-      // `cmd /c npx`; other platforms use npx directly.
-      const launcher = npxMcpLauncher();
-      setupOptions.install = (selected, options) => installMcpConfig(selected, {
-        ...options,
-        command: launcher.command,
-        args: [...launcher.prefixArgs, '--yes', '--ignore-scripts', `--package=sap-ai-dev-toolkit@${pkg.version}`, 'sap-ai-dev']
-      });
+      const launcher = npxPackageLauncher(pkg.version);
+      setupOptions.install = (selected, options) => installMcpConfig(selected, { ...options, ...launcher });
     }
     await runSetup(setupOptions);
     return;
@@ -446,15 +473,7 @@ async function main() {
       : (/\.(?:cmd|bat)$/i.test(binary)
         ? { command: 'cmd', prefixArgs: ['/c', binary] }
         : { command: binary, prefixArgs: [] });
-    const child = spawn(spawnTarget.command, [...spawnTarget.prefixArgs, ...process.argv.slice(2)], { env: runtimeEnv, stdio: 'inherit' });
-    process.once('SIGINT', () => child.kill('SIGINT'));
-    process.once('SIGTERM', () => child.kill('SIGTERM'));
-    const [code, signal] = await new Promise((resolve, reject) => {
-      child.once('error', reject);
-      child.once('exit', (exitCode, exitSignal) => resolve([exitCode, exitSignal]));
-    });
-    if (signal) process.kill(process.pid, signal);
-    process.exitCode = code ?? 1;
+    await runOnOwnStdio(spawnTarget.command, [...spawnTarget.prefixArgs, ...process.argv.slice(2)], runtimeEnv);
     return;
   }
 

package/src/mcp-config.mjs

@@ -131,6 +131,26 @@ export function npxMcpLauncher(platform = process.platform) {
     : { command: 'npx', prefixArgs: [] };
 }
 
+export function npxPackageLauncher(version, platform = process.platform) {
+  const { command, prefixArgs } = npxMcpLauncher(platform);
+  return { command, args: [...prefixArgs, '--yes', '--ignore-scripts', `--package=sap-ai-dev-toolkit${version ? `@${version}` : ''}`, 'sap-ai-dev'] };
+}
+
+function isOlderVersion(version, other) {
+  const parts = value => Array.from({ length: 3 }, (_, index) => Number.parseInt(String(value).split('.')[index], 10) || 0);
+  const [current, target] = [parts(version), parts(other)];
+  const index = current.findIndex((part, position) => part !== target[position]);
+  return index >= 0 && current[index] < target[index];
+}
+
+// Setup pins its version into each entry, so a stale sap-ai-dev on PATH can hand off
+// to that version through npx instead of running old code; the handoff happens once.
+export function configuredVersionHandoff(env, runningVersion, platform = process.platform) {
+  const configured = brandedEnvValue(env, 'VERSION');
+  if (!configured || brandedEnvValue(env, 'HANDOFF') || !isOlderVersion(runningVersion, configured)) return null;
+  return { version: configured, ...npxPackageLauncher(configured, platform) };
+}
+
 // Normalizes the argument list of npx-launched entries, whether written as
 // `npx ...` or the Windows `cmd /c npx ...` form; returns null when the entry
 // is not npx-launched.
@@ -146,17 +166,36 @@ function npxLaunchArgs(entry) {
   return null;
 }
 
+// The package version a PATH sap-ai-dev starts, found through npm's global
+// layouts (Unix bin symlink, Windows .cmd shim); null when the layout is unknown.
+async function commandPackageVersion(command) {
+  const target = await realpath(command).catch(() => command);
+  for (const manifest of [join(dirname(dirname(target)), 'package.json'), join(dirname(command), 'node_modules', 'sap-ai-dev-toolkit', 'package.json')]) {
+    try {
+      const pkg = JSON.parse(await readFile(manifest, 'utf8'));
+      if (pkg.name === 'sap-ai-dev-toolkit') return pkg.version;
+    } catch {
+      // Try the other layout.
+    }
+  }
+  return null;
+}
+
 // Resolves how generated destination entries launch the toolkit: the global
-// sap-ai-dev command when it is on PATH, otherwise the pinned package
-// through npx (routed through cmd /c on Windows) so entries written by a
-// pure `npx sap-ai-dev-toolkit --setup` run still start on every host.
+// sap-ai-dev command when it is on PATH and is this version, otherwise the
+// pinned package through npx (routed through cmd /c on Windows) so entries
+// written by a pure `npx sap-ai-dev-toolkit --setup` run still start on every host.
 async function resolveLauncherInstallCommand(env) {
   const resolved = await resolveMcpServerCommand(env);
-  if (resolved !== 'sap-ai-dev') return { command: resolved, args: null };
-  const { command, prefixArgs } = npxMcpLauncher();
   const selfVersion = await runningPackageVersion();
-  const packageSpec = selfVersion ? `sap-ai-dev-toolkit@${selfVersion}` : 'sap-ai-dev-toolkit';
-  return { command, args: [...prefixArgs, '--yes', '--ignore-scripts', `--package=${packageSpec}`, 'sap-ai-dev'] };
+  let warning;
+  if (resolved !== 'sap-ai-dev') {
+    const installed = await commandPackageVersion(resolved);
+    if (installed === null || !selfVersion || installed === selfVersion) return { command: resolved, args: null };
+    // A stale global install would keep starting the old launcher and VSP binary.
+    warning = `${resolved} is sap-ai-dev-toolkit ${installed}, not ${selfVersion}; MCP entries start sap-ai-dev-toolkit@${selfVersion} through npx instead. Run "npm install -g sap-ai-dev-toolkit@${selfVersion}" to use the global command.`;
+  }
+  return { ...npxPackageLauncher(selfVersion), warning };
 }
 
 export async function resolveMcpConfigPath(env = process.env) {
@@ -576,12 +615,14 @@ export async function installMcpConfig(destinationsOrOptions, options = {}) {
     const resolved = await resolveLauncherInstallCommand(env);
     launcherCommand = resolved.command;
     launcherArgs = resolved.args;
+    if (resolved.warning) installWarnings.push(resolved.warning);
   }
   if (launcherCommand) {
     for (const entry of Object.values(generated)) {
       if (isCompanionServer(entry)) continue;
       entry.command = launcherCommand;
       if (launcherArgs?.length) entry.args = [...launcherArgs];
+      if (selfVersion) entry.env.SAP_AI_DEV_TOOLKIT_VERSION = selfVersion;
     }
   }
   const servers = Object.create(null);

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');
@@ -531,21 +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`);
-      // VSP answers initialize only after its browser sign-in, which waits on a person.
-      const signIn = entry.destination.authentication === 'SSO'
-        ? setInterval(() => this.eventSink(`[${entry.destination.name}] still waiting for the SSO sign-in (${Math.round((Date.now() - startedAt) / 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(`[${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);
@@ -561,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;
@@ -822,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;
+}