@pie-players/pie-assessment-toolkit 0.3.74 → 0.3.75

package/dist/services/tool-providers/ToolProviderRegistry.d.ts

@@ -8,13 +8,13 @@
  */
 import type { ToolProviderApi, ToolCategory } from "./ToolProviderApi.js";
 /**
- * Configuration for registering a tool provider
+ * What `register` takes: the provider, its config, and how it starts.
  */
-export interface ToolProviderConfig<TConfig = any> {
+export interface ToolProviderRegistration<TConfig = any> {
     /**
      * Provider instance to register
      */
-    provider: ToolProviderApi<TConfig>;
+    provider: ToolProviderApi;
     /**
      * Configuration for this provider
      * (may include auth credentials, endpoints, etc.)
@@ -54,14 +54,16 @@ export interface ToolProviderConfig<TConfig = any> {
  * - Registration
  * - Lazy initialization
  * - Auth credential fetching
- * - Provider lookup by ID or category
+ * - Provider lookup by tool id or category
+ *
+ * The toolkit coordinator registers each provider under its tool's id.
  *
  * @example
  * ```typescript
  * const registry = new ToolProviderRegistry();
  *
  * // Register a provider with auth fetcher
- * registry.register('example-provider', {
+ * registry.register('calculator', {
  *   provider: new ExampleToolProvider(),
  *   config: {},
  *   lazy: true,
@@ -72,7 +74,7 @@ export interface ToolProviderConfig<TConfig = any> {
  * });
  *
  * // Get provider (auto-initializes if lazy)
- * const provider = await registry.getProvider('example-provider');
+ * const provider = await registry.getProvider('calculator');
  * ```
  */
 export declare class ToolProviderRegistry {
@@ -85,23 +87,28 @@ export declare class ToolProviderRegistry {
      * Register a tool provider
      *
      * Adds a provider to the registry. If lazy is false, initializes immediately.
+     * A registration under an id already registered replaces it: the replaced
+     * provider is destroyed once a start in progress settles, and a caller
+     * waiting on that start gets the replacement.
      *
-     * @param providerId Unique provider identifier
+     * @param toolId Id of the tool the provider serves
      * @param config Provider configuration
-     * @throws Error if provider with same ID already registered
      */
-    register(providerId: string, config: ToolProviderConfig): void;
+    register(toolId: string, config: ToolProviderRegistration): void;
     /**
      * Initialize a provider
      *
      * Fetches auth if needed and initializes the provider.
      * Safe to call multiple times - subsequent calls wait for first initialization.
      *
-     * @param providerId Provider to initialize
+     * @param toolId Tool whose provider to initialize
      * @returns Promise that resolves when initialization complete
      * @throws Error if provider not registered or initialization fails
      */
-    initialize(providerId: string): Promise<void>;
+    initialize(toolId: string): Promise<void>;
+    /** Whether a registration replaced `provider` under `toolId`. */
+    private isReplaced;
+    private destroyProvider;
     /**
      * Internal initialization logic
      */
@@ -112,54 +119,51 @@ export declare class ToolProviderRegistry {
      * Retrieves a registered provider. If autoInitialize is true and provider
      * is not initialized, initializes it first.
      *
-     * @param providerId Provider identifier
+     * @param toolId Id of the tool the provider serves
      * @param autoInitialize Auto-initialize if not ready (default: true)
      * @returns Provider instance
      * @throws Error if provider not registered
      */
-    getProvider<T extends ToolProviderApi = ToolProviderApi>(providerId: string, autoInitialize?: boolean): Promise<T>;
+    getProvider<T extends ToolProviderApi = ToolProviderApi>(toolId: string, autoInitialize?: boolean): Promise<T>;
     /**
-     * Get all providers in a category
+     * The ids of the tools whose provider is in `category`.
      *
      * @param category Tool category to filter by
-     * @returns Array of provider IDs in the category
      */
     getProvidersByCategory(category: ToolCategory): string[];
     /**
-     * Get all registered provider IDs
-     *
-     * @returns Array of all provider IDs
+     * The ids of the tools with a registered provider.
      */
     getProviderIds(): string[];
     /**
      * Check if provider is registered
      *
-     * @param providerId Provider identifier
+     * @param toolId Id of the tool the provider serves
      * @returns true if provider is registered
      */
-    has(providerId: string): boolean;
+    has(toolId: string): boolean;
     /**
      * Check if provider is initialized
      *
-     * @param providerId Provider identifier
+     * @param toolId Id of the tool the provider serves
      * @returns true if provider is initialized
      */
-    isInitialized(providerId: string): boolean;
+    isInitialized(toolId: string): boolean;
     /**
      * Check if provider is currently initializing
      *
-     * @param providerId Provider identifier
+     * @param toolId Id of the tool the provider serves
      * @returns true if initialization in progress
      */
-    isInitializing(providerId: string): boolean;
+    isInitializing(toolId: string): boolean;
     /**
      * Unregister and destroy a provider
      *
      * Removes the provider from the registry and calls its destroy method.
      *
-     * @param providerId Provider to unregister
+     * @param toolId Tool whose provider to unregister
      */
-    unregister(providerId: string): Promise<void>;
+    unregister(toolId: string): Promise<void>;
     /**
      * Clean up all providers
      *

package/dist/services/tool-providers/ToolProviderRegistry.js

@@ -6,6 +6,9 @@
  *
  * Part of PIE Assessment Toolkit.
  */
+import { createPieLogger, isGlobalDebugEnabled, } from "@pie-players/pie-players-shared/pie";
+// Lifecycle lines need `window.PIE_DEBUG = true`, read on each line.
+const logger = createPieLogger("ToolProviderRegistry", isGlobalDebugEnabled);
 /**
  * Tool Provider Registry
  *
@@ -13,14 +16,16 @@
  * - Registration
  * - Lazy initialization
  * - Auth credential fetching
- * - Provider lookup by ID or category
+ * - Provider lookup by tool id or category
+ *
+ * The toolkit coordinator registers each provider under its tool's id.
  *
  * @example
  * ```typescript
  * const registry = new ToolProviderRegistry();
  *
  * // Register a provider with auth fetcher
- * registry.register('example-provider', {
+ * registry.register('calculator', {
  *   provider: new ExampleToolProvider(),
  *   config: {},
  *   lazy: true,
@@ -31,7 +36,7 @@
  * });
  *
  * // Get provider (auto-initializes if lazy)
- * const provider = await registry.getProvider('example-provider');
+ * const provider = await registry.getProvider('calculator');
  * ```
  */
 export class ToolProviderRegistry {
@@ -51,24 +56,35 @@ export class ToolProviderRegistry {
      * Register a tool provider
      *
      * Adds a provider to the registry. If lazy is false, initializes immediately.
+     * A registration under an id already registered replaces it: the replaced
+     * provider is destroyed once a start in progress settles, and a caller
+     * waiting on that start gets the replacement.
      *
-     * @param providerId Unique provider identifier
+     * @param toolId Id of the tool the provider serves
      * @param config Provider configuration
-     * @throws Error if provider with same ID already registered
      */
-    register(providerId, config) {
-        if (this.providers.has(providerId)) {
-            console.warn(`[ToolProviderRegistry] Provider "${providerId}" already registered, skipping`);
-            return;
+    register(toolId, config) {
+        const replaced = this.providers.get(toolId);
+        const replacedStart = this.initializationPromises.get(toolId);
+        this.providers.set(toolId, config.provider);
+        this.configs.set(toolId, config);
+        this.initialized.set(toolId, false);
+        this.initializationPromises.delete(toolId);
+        if (replaced) {
+            if (replacedStart) {
+                void replacedStart
+                    .catch(() => { })
+                    .then(() => this.destroyProvider(toolId, replaced));
+            }
+            else {
+                this.destroyProvider(toolId, replaced);
+            }
         }
-        this.providers.set(providerId, config.provider);
-        this.configs.set(providerId, config);
-        this.initialized.set(providerId, false);
-        console.log(`[ToolProviderRegistry] Registered provider "${providerId}" (${config.provider.providerName})`);
+        logger.debug(`${replaced ? "Replaced" : "Registered"} provider "${toolId}" (${config.provider.providerName})`);
         // Initialize immediately if not lazy
         if (config.lazy === false) {
-            this.initialize(providerId).catch((error) => {
-                console.error(`[ToolProviderRegistry] Failed to initialize provider "${providerId}":`, error);
+            this.initialize(toolId).catch((error) => {
+                console.error(`[ToolProviderRegistry] Failed to initialize provider "${toolId}":`, error);
             });
         }
     }
@@ -78,60 +94,73 @@ export class ToolProviderRegistry {
      * Fetches auth if needed and initializes the provider.
      * Safe to call multiple times - subsequent calls wait for first initialization.
      *
-     * @param providerId Provider to initialize
+     * @param toolId Tool whose provider to initialize
      * @returns Promise that resolves when initialization complete
      * @throws Error if provider not registered or initialization fails
      */
-    async initialize(providerId) {
+    async initialize(toolId) {
         // Already initialized
-        if (this.initialized.get(providerId)) {
+        if (this.initialized.get(toolId)) {
             return;
         }
         // Initialization in progress - wait for it
-        const existingPromise = this.initializationPromises.get(providerId);
+        const existingPromise = this.initializationPromises.get(toolId);
         if (existingPromise) {
             return existingPromise;
         }
         // Start new initialization
-        const initPromise = this._doInitialize(providerId);
-        this.initializationPromises.set(providerId, initPromise);
+        const provider = this.providers.get(toolId);
+        const initPromise = this._doInitialize(toolId);
+        this.initializationPromises.set(toolId, initPromise);
         try {
             await initPromise;
         }
+        catch (error) {
+            if (!this.isReplaced(toolId, provider))
+                throw error;
+        }
         finally {
-            this.initializationPromises.delete(providerId);
+            if (this.initializationPromises.get(toolId) === initPromise) {
+                this.initializationPromises.delete(toolId);
+            }
+        }
+        if (this.isReplaced(toolId, provider)) {
+            return this.initialize(toolId);
+        }
+    }
+    /** Whether a registration replaced `provider` under `toolId`. */
+    isReplaced(toolId, provider) {
+        const current = this.providers.get(toolId);
+        return current !== undefined && current !== provider;
+    }
+    destroyProvider(toolId, provider) {
+        try {
+            provider.destroy();
+        }
+        catch (error) {
+            console.warn(`[ToolProviderRegistry] Failed to destroy provider "${toolId}":`, error);
         }
     }
     /**
      * Internal initialization logic
      */
-    async _doInitialize(providerId) {
-        const provider = this.providers.get(providerId);
-        const config = this.configs.get(providerId);
+    async _doInitialize(toolId) {
+        const provider = this.providers.get(toolId);
+        const config = this.configs.get(toolId);
         if (!provider || !config) {
-            throw new Error(`[ToolProviderRegistry] Provider "${providerId}" not registered`);
+            throw new Error(`[ToolProviderRegistry] Provider "${toolId}" not registered`);
         }
         // Start with base config
         let providerConfig = { ...config.config };
         const deriveBackend = (value) => {
-            if (!value || typeof value !== "object")
-                return "unknown";
-            const typed = value;
-            const direct = typeof typed.backend === "string"
-                ? typed.backend
-                : typeof typed.provider === "string"
-                    ? typed.provider
-                    : typeof typed.serverProvider === "string"
-                        ? typed.serverProvider
-                        : typeof typed.providerId === "string"
-                            ? typed.providerId
-                            : "";
-            return direct || "unknown";
+            const backend = value && typeof value === "object"
+                ? value.backend
+                : undefined;
+            return typeof backend === "string" && backend ? backend : "unknown";
         };
         const providerInitStartedAt = Date.now();
         await this.emitTelemetry(config, "pie-tool-init-start", {
-            toolId: providerId,
-            providerId,
+            toolId,
             backend: deriveBackend(providerConfig),
             operation: "provider-initialize",
         });
@@ -139,18 +168,16 @@ export class ToolProviderRegistry {
         if (provider.requiresAuth && config.authFetcher) {
             const authFetchStartedAt = Date.now();
             await this.emitTelemetry(config, "pie-tool-backend-call-start", {
-                toolId: providerId,
-                providerId,
+                toolId,
                 backend: deriveBackend(providerConfig),
                 operation: "auth-fetch",
             });
-            console.log(`[ToolProviderRegistry] Fetching auth for "${providerId}"...`);
+            logger.debug(`Fetching auth for "${toolId}"...`);
             try {
                 const authData = await config.authFetcher();
                 providerConfig = { ...providerConfig, ...authData };
                 await this.emitTelemetry(config, "pie-tool-backend-call-success", {
-                    toolId: providerId,
-                    providerId,
+                    toolId,
                     backend: deriveBackend(providerConfig),
                     operation: "auth-fetch",
                     duration: Date.now() - authFetchStartedAt,
@@ -158,42 +185,41 @@ export class ToolProviderRegistry {
             }
             catch (error) {
                 await this.emitTelemetry(config, "pie-tool-backend-call-error", {
-                    toolId: providerId,
-                    providerId,
+                    toolId,
                     backend: deriveBackend(providerConfig),
                     operation: "auth-fetch",
                     duration: Date.now() - authFetchStartedAt,
                     errorType: "ProviderAuthFetchError",
                     message: error instanceof Error ? error.message : String(error),
                 });
-                console.error(`[ToolProviderRegistry] Auth fetch failed for "${providerId}":`, error);
-                throw new Error(`Failed to fetch auth credentials for provider "${providerId}"`);
+                console.error(`[ToolProviderRegistry] Auth fetch failed for "${toolId}":`, error);
+                throw new Error(`Failed to fetch auth credentials for provider "${toolId}"`);
             }
         }
         // Initialize provider
         try {
             await provider.initialize(providerConfig);
-            this.initialized.set(providerId, true);
+            if (this.providers.get(toolId) === provider) {
+                this.initialized.set(toolId, true);
+            }
             await this.emitTelemetry(config, "pie-tool-init-success", {
-                toolId: providerId,
-                providerId,
+                toolId,
                 backend: deriveBackend(providerConfig),
                 operation: "provider-initialize",
                 duration: Date.now() - providerInitStartedAt,
             });
-            console.log(`[ToolProviderRegistry] Provider "${providerId}" initialized`);
+            logger.debug(`Provider "${toolId}" initialized`);
         }
         catch (error) {
             await this.emitTelemetry(config, "pie-tool-init-error", {
-                toolId: providerId,
-                providerId,
+                toolId,
                 backend: deriveBackend(providerConfig),
                 operation: "provider-initialize",
                 duration: Date.now() - providerInitStartedAt,
                 errorType: "ProviderInitializationError",
                 message: error instanceof Error ? error.message : String(error),
             });
-            console.error(`[ToolProviderRegistry] Initialization failed for "${providerId}":`, error);
+            console.error(`[ToolProviderRegistry] Initialization failed for "${toolId}":`, error);
             throw error;
         }
     }
@@ -203,32 +229,31 @@ export class ToolProviderRegistry {
      * Retrieves a registered provider. If autoInitialize is true and provider
      * is not initialized, initializes it first.
      *
-     * @param providerId Provider identifier
+     * @param toolId Id of the tool the provider serves
      * @param autoInitialize Auto-initialize if not ready (default: true)
      * @returns Provider instance
      * @throws Error if provider not registered
      */
-    async getProvider(providerId, autoInitialize = true) {
-        const provider = this.providers.get(providerId);
+    async getProvider(toolId, autoInitialize = true) {
+        const provider = this.providers.get(toolId);
         if (!provider) {
             console.error("[ToolProviderRegistry] Provider not found:", {
-                requestedId: providerId,
+                requestedId: toolId,
                 availableProviders: Array.from(this.providers.keys()),
             });
-            throw new Error(`[ToolProviderRegistry] Provider "${providerId}" not registered`);
+            throw new Error(`[ToolProviderRegistry] Provider "${toolId}" not registered`);
         }
         // Auto-initialize if needed
-        if (autoInitialize && !this.initialized.get(providerId)) {
-            console.log("[ToolProviderRegistry] Auto-initializing provider:", providerId);
-            await this.initialize(providerId);
+        if (autoInitialize && !this.initialized.get(toolId)) {
+            logger.debug("Auto-initializing provider:", toolId);
+            await this.initialize(toolId);
         }
         return provider;
     }
     /**
-     * Get all providers in a category
+     * The ids of the tools whose provider is in `category`.
      *
      * @param category Tool category to filter by
-     * @returns Array of provider IDs in the category
      */
     getProvidersByCategory(category) {
         return Array.from(this.providers.entries())
@@ -236,9 +261,7 @@ export class ToolProviderRegistry {
             .map(([id]) => id);
     }
     /**
-     * Get all registered provider IDs
-     *
-     * @returns Array of all provider IDs
+     * The ids of the tools with a registered provider.
      */
     getProviderIds() {
         return Array.from(this.providers.keys());
@@ -246,42 +269,42 @@ export class ToolProviderRegistry {
     /**
      * Check if provider is registered
      *
-     * @param providerId Provider identifier
+     * @param toolId Id of the tool the provider serves
      * @returns true if provider is registered
      */
-    has(providerId) {
-        return this.providers.has(providerId);
+    has(toolId) {
+        return this.providers.has(toolId);
     }
     /**
      * Check if provider is initialized
      *
-     * @param providerId Provider identifier
+     * @param toolId Id of the tool the provider serves
      * @returns true if provider is initialized
      */
-    isInitialized(providerId) {
-        return this.initialized.get(providerId) === true;
+    isInitialized(toolId) {
+        return this.initialized.get(toolId) === true;
     }
     /**
      * Check if provider is currently initializing
      *
-     * @param providerId Provider identifier
+     * @param toolId Id of the tool the provider serves
      * @returns true if initialization in progress
      */
-    isInitializing(providerId) {
-        return this.initializationPromises.has(providerId);
+    isInitializing(toolId) {
+        return this.initializationPromises.has(toolId);
     }
     /**
      * Unregister and destroy a provider
      *
      * Removes the provider from the registry and calls its destroy method.
      *
-     * @param providerId Provider to unregister
+     * @param toolId Tool whose provider to unregister
      */
-    async unregister(providerId) {
-        const provider = this.providers.get(providerId);
+    async unregister(toolId) {
+        const provider = this.providers.get(toolId);
         if (provider) {
             // Wait for any pending initialization
-            const initPromise = this.initializationPromises.get(providerId);
+            const initPromise = this.initializationPromises.get(toolId);
             if (initPromise) {
                 try {
                     await initPromise;
@@ -289,15 +312,18 @@ export class ToolProviderRegistry {
                 catch {
                     // Ignore initialization errors during unregister
                 }
+                // A provider registered meanwhile owns the slot, and register()
+                // already destroys this one once its start settles.
+                if (this.providers.get(toolId) !== provider)
+                    return;
             }
-            // Destroy provider
-            provider.destroy();
+            this.destroyProvider(toolId, provider);
             // Remove from registry
-            this.providers.delete(providerId);
-            this.configs.delete(providerId);
-            this.initialized.delete(providerId);
-            this.initializationPromises.delete(providerId);
-            console.log(`[ToolProviderRegistry] Unregistered provider "${providerId}"`);
+            this.providers.delete(toolId);
+            this.configs.delete(toolId);
+            this.initialized.delete(toolId);
+            this.initializationPromises.delete(toolId);
+            logger.debug(`Unregistered provider "${toolId}"`);
         }
     }
     /**
@@ -306,8 +332,8 @@ export class ToolProviderRegistry {
      * Unregisters and destroys all providers in the registry.
      */
     async destroy() {
-        const providerIds = Array.from(this.providers.keys());
-        await Promise.all(providerIds.map((id) => this.unregister(id)));
-        console.log("[ToolProviderRegistry] Registry destroyed");
+        const toolIds = Array.from(this.providers.keys());
+        await Promise.all(toolIds.map((id) => this.unregister(id)));
+        logger.debug("Registry destroyed");
     }
 }

package/dist/services/tool-request.d.ts

@@ -42,17 +42,26 @@ export interface ToolOpenRequest {
      * to match a placement made elsewhere is a step it has no reason to expect.
      *
      * At `"item"` and `"passage"` a section holds one target per card, and the first
-     * registered one that hosts the tool claims the request. A requester that needs a
-     * particular card's instance cannot express that here, and the gateway PIE ships
-     * does not need to: the strip is a section-scoped singleton acting on passage
-     * selections, so the selection belongs to no card, and what opens is a floating
-     * shell rather than anything rendered inside one.
+     * registered one that hosts the tool claims the request unless `scopeId` names
+     * the card.
      */
     level?: ToolPlacementLevel;
+    /**
+     * Scope of the toolbar that should open the tool: the item's canonical id for
+     * an item toolbar, the section id for a section toolbar. A constraint like
+     * `level`, for a requester that belongs to one card, as an inline control in an
+     * item does. Only a target registered with the same `scopeId` claims it.
+     */
+    scopeId?: string;
 }
 export interface ToolRequestTarget {
     /** The placement level this toolbar renders. */
     level: ToolPlacementLevel;
+    /**
+     * The scope this toolbar renders for, matched against a request's `scopeId`.
+     * A target without one claims only requests that name no scope.
+     */
+    readonly scopeId?: string;
     /** Whether this toolbar currently renders the tool, per its own policy pass. */
     hostsTool: (toolId: string) => boolean;
     /**
@@ -80,16 +89,17 @@ export declare class ToolRequestRegistry {
      * nothing is worse than an absent one, and availability moves with policy —
      * hence {@link onTargetsChange}.
      */
-    canRequest(toolId: string, level?: ToolPlacementLevel): boolean;
+    canRequest(toolId: string, level?: ToolPlacementLevel, scopeId?: string): boolean;
     /** Returns whether a target claimed the request. */
     request(request: ToolOpenRequest): boolean;
     /**
-     * Fires when a toolbar registers or unregisters.
+     * Fires when a toolbar registers or unregisters, and on
+     * {@link notifyTargetsChange}.
      *
-     * Not when a registered toolbar's own visible set changes: `hostsTool` is read
-     * live, so a caller re-asking `canRequest` gets the current answer. A surface
-     * that needs to notice a policy change should also follow the policy signal it
-     * already has.
+     * Not when a policy change moves a registered toolbar's visible set: `hostsTool`
+     * is read live, so a caller re-asking `canRequest` gets the current answer. A
+     * surface that needs to notice a policy change should also follow the policy
+     * signal it already has.
      */
     onTargetsChange(listener: () => void): () => void;
     /**
@@ -102,6 +112,11 @@ export declare class ToolRequestRegistry {
     private findTarget;
     private findTargetAtLevel;
     private hostsTool;
-    private notifyChange;
+    /**
+     * Tell change listeners that what the targets can claim changed. Registration
+     * calls it, and so does the coordinator when a target stops hosting a tool
+     * outside a policy change, as when the tool's module fails to load.
+     */
+    notifyTargetsChange(): void;
     dispose(): void;
 }