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

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,25 +16,27 @@
  * - 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('desmos-calculator', {
- *   provider: new DesmosToolProvider(),
+ * registry.register('calculator', {
+ *   provider: new ExampleToolProvider(),
  *   config: {},
  *   lazy: true,
  *   authFetcher: async () => {
- *     const response = await fetch('/api/desmos/token');
+ *     const response = await fetch('/api/example/token');
  *     return response.json();
  *   },
  * });
  *
  * // Get provider (auto-initializes if lazy)
- * const desmosProvider = await registry.getProvider('desmos-calculator');
+ * 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,44 +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) {
-        console.log("[ToolProviderRegistry] getProvider called", {
-            providerId,
-            autoInitialize,
-            isRegistered: this.providers.has(providerId),
-            isInitialized: this.initialized.get(providerId),
-            allProviderIds: Array.from(this.providers.keys()),
-        });
-        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);
         }
-        console.log("[ToolProviderRegistry] Returning provider:", {
-            providerId,
-            providerName: provider.providerName,
-            isReady: provider.isReady(),
-        });
         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())
@@ -248,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());
@@ -258,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;
@@ -301,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}"`);
         }
     }
     /**
@@ -318,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-providers/index.d.ts

@@ -6,14 +6,5 @@
  *
  * Part of PIE Assessment Toolkit.
  */
-export type { ToolProviderApi, ToolCategory, ToolProviderCapabilities, } from "./ToolProviderApi.js";
 export { ToolProviderRegistry } from "./ToolProviderRegistry.js";
-export type { ToolProviderConfig } from "./ToolProviderRegistry.js";
-export { DesmosToolProvider } from "./DesmosToolProvider.js";
-export type { DesmosToolProviderConfig } from "./DesmosToolProvider.js";
-export { CortexToolProvider } from "./CortexToolProvider.js";
-export type { CortexToolProviderConfig } from "./CortexToolProvider.js";
-export { GeoGebraToolProvider } from "./GeoGebraToolProvider.js";
-export type { GeoGebraToolProviderConfig } from "./GeoGebraToolProvider.js";
 export { TTSToolProvider } from "./TTSToolProvider.js";
-export type { TTSToolProviderConfig, TTSBackend, } from "./TTSToolProvider.js";

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

@@ -8,8 +8,6 @@
  */
 // Registry
 export { ToolProviderRegistry } from "./ToolProviderRegistry.js";
-// Concrete providers
-export { DesmosToolProvider } from "./DesmosToolProvider.js";
-export { CortexToolProvider } from "./CortexToolProvider.js";
-export { GeoGebraToolProvider } from "./GeoGebraToolProvider.js";
+// Concrete providers. The calculator adapters live in the composition layer,
+// `@pie-players/pie-default-tool-loaders`, which owns the engine imports.
 export { TTSToolProvider } from "./TTSToolProvider.js";

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;
 }

package/dist/services/tool-request.js

@@ -32,11 +32,11 @@ export class ToolRequestRegistry {
     changeListeners = new Set();
     registerTarget(target) {
         this.targets.add(target);
-        this.notifyChange();
+        this.notifyTargetsChange();
         return () => {
             if (!this.targets.delete(target))
                 return;
-            this.notifyChange();
+            this.notifyTargetsChange();
         };
     }
     /**
@@ -46,12 +46,12 @@ export class ToolRequestRegistry {
      * nothing is worse than an absent one, and availability moves with policy —
      * hence {@link onTargetsChange}.
      */
-    canRequest(toolId, level) {
-        return this.findTarget(toolId, level) !== null;
+    canRequest(toolId, level, scopeId) {
+        return this.findTarget(toolId, level, scopeId) !== null;
     }
     /** Returns whether a target claimed the request. */
     request(request) {
-        const target = this.findTarget(request.toolId, request.level);
+        const target = this.findTarget(request.toolId, request.level, request.scopeId);
         if (!target)
             return false;
         try {
@@ -64,12 +64,13 @@ export class ToolRequestRegistry {
         return true;
     }
     /**
-     * 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) {
         this.changeListeners.add(listener);
@@ -84,22 +85,26 @@ export class ToolRequestRegistry {
      * and still have a section-scoped gateway reach it. Requesting a level explicitly
      * does not fall back, because a requester that named one meant it.
      */
-    findTarget(toolId, level) {
-        const preferred = this.findTargetAtLevel(toolId, level ?? DEFAULT_TOOL_REQUEST_LEVEL);
+    findTarget(toolId, level, scopeId) {
+        const preferred = this.findTargetAtLevel(toolId, level ?? DEFAULT_TOOL_REQUEST_LEVEL, scopeId);
         if (preferred || level !== undefined)
             return preferred;
         for (const target of this.targets) {
             if (target.level === DEFAULT_TOOL_REQUEST_LEVEL)
                 continue;
+            if (scopeId !== undefined && target.scopeId !== scopeId)
+                continue;
             if (this.hostsTool(target, toolId))
                 return target;
         }
         return null;
     }
-    findTargetAtLevel(toolId, level) {
+    findTargetAtLevel(toolId, level, scopeId) {
         for (const target of this.targets) {
             if (target.level !== level)
                 continue;
+            if (scopeId !== undefined && target.scopeId !== scopeId)
+                continue;
             if (this.hostsTool(target, toolId))
                 return target;
         }
@@ -114,7 +119,12 @@ export class ToolRequestRegistry {
             return false;
         }
     }
-    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() {
         for (const listener of this.changeListeners) {
             try {
                 listener();

package/dist/services/toolbar-decided-tools.d.ts

@@ -0,0 +1,15 @@
+import type { ToolPolicyDecision } from "../policy/core/decision-types.js";
+/** What a toolbar renders from in a policy decision, per visible tool. */
+export interface DecidedToolbarTool {
+    toolId: string;
+    required: boolean;
+    alwaysAvailable: boolean;
+}
+/**
+ * A toolbar's decided tools across re-decisions. The tracker returns its
+ * previous list while `renderVersion` is unchanged and the decision shows the
+ * same tools, so a re-decision that changes nothing the toolbar renders from
+ * keeps the rendered tools: rendering swaps in fresh tool elements, whose state
+ * starts over. A new `renderVersion` always yields a new list.
+ */
+export declare function createDecidedToolsTracker(): (decision: ToolPolicyDecision | null, renderVersion: number) => readonly DecidedToolbarTool[] | null;

package/dist/services/toolbar-decided-tools.js

@@ -0,0 +1,28 @@
+import { structurallyEqual } from "../utils/structural-equality.js";
+/**
+ * A toolbar's decided tools across re-decisions. The tracker returns its
+ * previous list while `renderVersion` is unchanged and the decision shows the
+ * same tools, so a re-decision that changes nothing the toolbar renders from
+ * keeps the rendered tools: rendering swaps in fresh tool elements, whose state
+ * starts over. A new `renderVersion` always yields a new list.
+ */
+export function createDecidedToolsTracker() {
+    let last = null;
+    return (decision, renderVersion) => {
+        if (!decision) {
+            last = null;
+            return null;
+        }
+        const tools = decision.visibleTools.map((entry) => ({
+            toolId: entry.toolId,
+            required: entry.required,
+            alwaysAvailable: entry.alwaysAvailable,
+        }));
+        if (last?.renderVersion === renderVersion &&
+            structurallyEqual(last.tools, tools)) {
+            return last.tools;
+        }
+        last = { renderVersion, tools };
+        return tools;
+    };
+}