feat: add optional extensionId hint to registerEnvironmentManager/registerPackageManager (microsoft#1436)

Fixes microsoft#378

## Context

When a third-party extension (e.g., `flying-sheep.hatch`) calls
`api.registerEnvironmentManager(manager)`, the python-environments
extension uses `getCallingExtension()` to determine who's calling by
walking the call stack and matching file paths against known extension
IDs.

This works in production because installed extensions have predictable
paths like
`~/.vscode/extensions/flying-sheep.hatch-1.0.0/dist/extension.js` — the
extension ID appears directly in the path.

During **F5 debugging**, the path is something like
`Z:\source\hatch-code\dist\extension.js`. There's no extension ID in
that path, so detection fails and falls back to `ms-python.python`. This
causes the manager to register as `ms-python.python:hatch` instead of
`flying-sheep.hatch:hatch`, breaking settings, package manager linking,
and anything downstream that uses the manager ID.

## Fix

Add an optional `options` parameter with an `extensionId` field to
`registerEnvironmentManager()` and `registerPackageManager()`:

```typescript
api.registerEnvironmentManager(manager, { extensionId: 'flying-sheep.hatch' });
```

## How third-party extensions use this

```typescript
// Works in both production and F5 debugging:
api.registerEnvironmentManager(manager, { extensionId: 'flying-sheep.hatch' });
api.registerPackageManager(pkgManager, { extensionId: 'flying-sheep.hatch' });
```

In production, the stack-walk succeeds and the hint is ignored. During
debugging, the hint provides the correct ID.

## Changes

- **`src/common/utils/frameUtils.ts`** — `getCallingExtension()` accepts
an optional `extensionIdHint` parameter, used as a last-resort fallback
before defaulting to `ms-python.python`. Validated against
`allExtensions()`.
- **`src/features/envManagers.ts`** — `generateId()`,
`registerEnvironmentManager()`, and `registerPackageManager()` pass the
hint through.
- **`src/features/pythonApi.ts`** — API impl forwards the `options`
parameter.
- **`src/internal.api.ts`** — `EnvironmentManagers` interface updated.
- **`src/api.ts`**, **`pythonEnvironmentsApi/src/main.ts`**,
**`examples/sample1/src/api.ts`** — Public API type definitions updated.

## Backward compatibility

This is a **non-breaking** addition. The new parameter is optional — all
existing callers (internal managers, tests, third-party extensions)
continue to work without changes. The public API has had optional
parameters added before (e.g., `CreateEnvironmentOptions` was added to
`createEnvironment()`).

Author: StellaHuang95

examples/sample1/src/api.ts

@@ -818,10 +818,14 @@ export interface PythonEnvironmentManagerRegistrationApi {
      * Register an environment manager implementation.
      *
      * @param manager Environment Manager implementation to register.
+     * @param options Optional registration options.
+     * @param options.extensionId The extension ID of the calling extension. This is used as a fallback when
+     * automatic extension detection fails, such as during F5 debugging where the extension's file path
+     * does not contain its marketplace ID. If automatic detection succeeds, this value is ignored.
      * @returns A disposable that can be used to unregister the environment manager.
      * @see {@link EnvironmentManager}
      */
-    registerEnvironmentManager(manager: EnvironmentManager): Disposable;
+    registerEnvironmentManager(manager: EnvironmentManager, options?: { extensionId?: string }): Disposable;
 }
 
 export interface PythonEnvironmentItemApi {
@@ -922,10 +926,14 @@ export interface PythonPackageManagerRegistrationApi {
      * Register a package manager implementation.
      *
      * @param manager Package Manager implementation to register.
+     * @param options Optional registration options.
+     * @param options.extensionId The extension ID of the calling extension. This is used as a fallback when
+     * automatic extension detection fails, such as during F5 debugging where the extension's file path
+     * does not contain its marketplace ID. If automatic detection succeeds, this value is ignored.
      * @returns A disposable that can be used to unregister the package manager.
      * @see {@link PackageManager}
      */
-    registerPackageManager(manager: PackageManager): Disposable;
+    registerPackageManager(manager: PackageManager, options?: { extensionId?: string }): Disposable;
 }
 
 export interface PythonPackageGetterApi {

pythonEnvironmentsApi/src/main.ts

@@ -842,10 +842,14 @@ export interface PythonEnvironmentManagerRegistrationApi {
      * Register an environment manager implementation.
      *
      * @param manager Environment Manager implementation to register.
+     * @param options Optional registration options.
+     * @param options.extensionId The extension ID of the calling extension. This is used as a fallback when
+     * automatic extension detection fails, such as during F5 debugging where the extension's file path
+     * does not contain its marketplace ID. If automatic detection succeeds, this value is ignored.
      * @returns A disposable that can be used to unregister the environment manager.
      * @see {@link EnvironmentManager}
      */
-    registerEnvironmentManager(manager: EnvironmentManager): Disposable;
+    registerEnvironmentManager(manager: EnvironmentManager, options?: { extensionId?: string }): Disposable;
 }
 
 export interface PythonEnvironmentItemApi {
@@ -947,10 +951,14 @@ export interface PythonPackageManagerRegistrationApi {
      * Register a package manager implementation.
      *
      * @param manager Package Manager implementation to register.
+     * @param options Optional registration options.
+     * @param options.extensionId The extension ID of the calling extension. This is used as a fallback when
+     * automatic extension detection fails, such as during F5 debugging where the extension's file path
+     * does not contain its marketplace ID. If automatic detection succeeds, this value is ignored.
      * @returns A disposable that can be used to unregister the package manager.
      * @see {@link PackageManager}
      */
-    registerPackageManager(manager: PackageManager): Disposable;
+    registerPackageManager(manager: PackageManager, options?: { extensionId?: string }): Disposable;
 }
 
 export interface PythonPackageGetterApi {

src/api.ts

@@ -836,10 +836,14 @@ export interface PythonEnvironmentManagerRegistrationApi {
      * Register an environment manager implementation.
      *
      * @param manager Environment Manager implementation to register.
+     * @param options Optional registration options.
+     * @param options.extensionId The extension ID of the calling extension. This is used as a fallback when
+     * automatic extension detection fails, such as during F5 debugging where the extension's file path
+     * does not contain its marketplace ID. If automatic detection succeeds, this value is ignored.
      * @returns A disposable that can be used to unregister the environment manager.
      * @see {@link EnvironmentManager}
      */
-    registerEnvironmentManager(manager: EnvironmentManager): Disposable;
+    registerEnvironmentManager(manager: EnvironmentManager, options?: { extensionId?: string }): Disposable;
 }
 
 export interface PythonEnvironmentItemApi {
@@ -941,10 +945,14 @@ export interface PythonPackageManagerRegistrationApi {
      * Register a package manager implementation.
      *
      * @param manager Package Manager implementation to register.
+     * @param options Optional registration options.
+     * @param options.extensionId The extension ID of the calling extension. This is used as a fallback when
+     * automatic extension detection fails, such as during F5 debugging where the extension's file path
+     * does not contain its marketplace ID. If automatic detection succeeds, this value is ignored.
      * @returns A disposable that can be used to unregister the package manager.
      * @see {@link PackageManager}
      */
-    registerPackageManager(manager: PackageManager): Disposable;
+    registerPackageManager(manager: PackageManager, options?: { extensionId?: string }): Disposable;
 }
 
 export interface PythonPackageGetterApi {

src/common/utils/frameUtils.ts

@@ -28,7 +28,7 @@ function getPathFromFrame(frame: FrameData): string {
     return frame.filePath;
 }
 
-export function getCallingExtension(): string {
+export function getCallingExtension(extensionIdHint?: string): string {
     const pythonExts = [ENVS_EXTENSION_ID, PYTHON_EXTENSION_ID];
     const extensions = allExtensions();
     const otherExts = extensions.filter((ext) => !pythonExts.includes(ext.id));
@@ -94,6 +94,19 @@ export function getCallingExtension(): string {
         }
     }
 
+    // Use the provided extensionId hint as a fallback (e.g., during F5 debugging where
+    // stack-based detection fails because the file path doesn't contain the extension ID).
+    // Only accept the hint if it matches an actually loaded extension for safety.
+    if (extensionIdHint) {
+        const hintExt = extensions.find((ext) => ext.id === extensionIdHint);
+        if (hintExt) {
+            traceVerbose(`Using provided extensionId hint: ${extensionIdHint}`);
+            extensionIdCache.set(cacheKey, extensionIdHint);
+            return extensionIdHint;
+        }
+        traceWarn(`Provided extensionId hint '${extensionIdHint}' not found in loaded extensions, ignoring`);
+    }
+
     // Fallback - we're likely being called from Python extension or built-in managers
     traceWarn(
         `Could not determine calling extension from stack frames. ` +

src/features/envManagers.ts

@@ -40,12 +40,12 @@ import {
     setAllManagerSettings,
 } from './settings/settingHelpers';
 
-function generateId(name: string): string {
+function generateId(name: string, extensionId?: string): string {
     const newName = name.toLowerCase().replace(/[^a-zA-Z0-9-_]/g, '_');
     if (name !== newName) {
         traceVerbose(`Environment manager name "${name}"  was normalized to "${newName}"`);
     }
-    return `${getCallingExtension()}:${newName}`;
+    return `${getCallingExtension(extensionId)}:${newName}`;
 }
 
 export class PythonEnvironmentManagers implements EnvironmentManagers {
@@ -71,9 +71,9 @@ export class PythonEnvironmentManagers implements EnvironmentManagers {
 
     constructor(private readonly pm: PythonProjectManager) {}
 
-    public registerEnvironmentManager(manager: EnvironmentManager): Disposable {
+    public registerEnvironmentManager(manager: EnvironmentManager, options?: { extensionId?: string }): Disposable {
         const registrationStopWatch = new StopWatch();
-        const managerId = generateId(manager.name);
+        const managerId = generateId(manager.name, options?.extensionId);
         if (this._environmentManagers.has(managerId)) {
             const ex = new EnvironmentManagerAlreadyRegisteredError(
                 `Environment manager with id ${managerId} already registered`,
@@ -119,8 +119,8 @@ export class PythonEnvironmentManagers implements EnvironmentManagers {
         });
     }
 
-    public registerPackageManager(manager: PackageManager): Disposable {
-        const managerId = generateId(manager.name);
+    public registerPackageManager(manager: PackageManager, options?: { extensionId?: string }): Disposable {
+        const managerId = generateId(manager.name, options?.extensionId);
         if (this._packageManagers.has(managerId)) {
             const ex = new PackageManagerAlreadyRegisteredError(
                 `Package manager with id ${managerId} already registered`,

src/features/pythonApi.ts

@@ -82,9 +82,9 @@ class PythonEnvironmentApiImpl implements PythonEnvironmentApi {
         );
     }
 
-    registerEnvironmentManager(manager: EnvironmentManager): Disposable {
+    registerEnvironmentManager(manager: EnvironmentManager, options?: { extensionId?: string }): Disposable {
         const disposables: Disposable[] = [];
-        disposables.push(this.envManagers.registerEnvironmentManager(manager));
+        disposables.push(this.envManagers.registerEnvironmentManager(manager, options));
         if (manager.onDidChangeEnvironments) {
             disposables.push(manager.onDidChangeEnvironments((e) => this._onDidChangeEnvironments.fire(e)));
         }
@@ -233,9 +233,9 @@ class PythonEnvironmentApiImpl implements PythonEnvironmentApi {
         return await handlePythonPath(context, this.envManagers.managers, projectEnvManagers);
     }
 
-    registerPackageManager(manager: PackageManager): Disposable {
+    registerPackageManager(manager: PackageManager, options?: { extensionId?: string }): Disposable {
         const disposables: Disposable[] = [];
-        disposables.push(this.envManagers.registerPackageManager(manager));
+        disposables.push(this.envManagers.registerPackageManager(manager, options));
         if (manager.onDidChangePackages) {
             disposables.push(manager.onDidChangePackages((e) => this._onDidChangePackages.fire(e)));
         }

src/internal.api.ts

@@ -76,8 +76,8 @@ export interface InternalDidChangeEnvironmentsEventArgs {
 }
 
 export interface EnvironmentManagers extends Disposable {
-    registerEnvironmentManager(manager: EnvironmentManager): Disposable;
-    registerPackageManager(manager: PackageManager): Disposable;
+    registerEnvironmentManager(manager: EnvironmentManager, options?: { extensionId?: string }): Disposable;
+    registerPackageManager(manager: PackageManager, options?: { extensionId?: string }): Disposable;
 
     /**
      * This event is fired when any environment manager changes its collection of environments.