@pie-players/pie-assessment-toolkit 0.3.74 → 1.0.0-beta.0

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

@@ -3,9 +3,17 @@
  *
  * Centralized registry for managing tool providers.
  * Handles initialization, authentication, and lazy loading.
- *
- * 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);
+/** The `backend` a provider config names, for telemetry payloads. */
+function telemetryBackend(value) {
+    const backend = value && typeof value === "object"
+        ? value.backend
+        : undefined;
+    return typeof backend === "string" && backend ? backend : "unknown";
+}
 /**
  * Tool Provider Registry
  *
@@ -13,14 +21,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 +41,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 +61,31 @@ export class ToolProviderRegistry {
      * Register a tool provider
      *
      * Adds a provider to the registry. If lazy is false, initializes immediately.
-     *
-     * @param providerId Unique provider identifier
-     * @param config Provider configuration
-     * @throws Error if provider with same ID already registered
+     * 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.
      */
-    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})`);
-        // Initialize immediately if not lazy
+        logger.debug(`${replaced ? "Replaced" : "Registered"} provider "${toolId}" (${config.provider.providerName})`);
         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);
             });
         }
     }
@@ -77,123 +94,120 @@ 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
-     * @returns Promise that resolves when initialization complete
-     * @throws Error if provider not registered or initialization fails
+     * Throws when the provider is not registered or its initialization fails.
      */
-    async initialize(providerId) {
-        // Already initialized
-        if (this.initialized.get(providerId)) {
+    async initialize(toolId) {
+        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) {
+            // When a registration replaced the provider mid-start, this caller
+            // gets the replacement, so the old start's failure is dropped.
+            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 providerInitStartedAt = Date.now();
         await this.emitTelemetry(config, "pie-tool-init-start", {
-            toolId: providerId,
-            providerId,
-            backend: deriveBackend(providerConfig),
+            toolId,
+            backend: telemetryBackend(providerConfig),
             operation: "provider-initialize",
         });
-        // Fetch auth if needed
         if (provider.requiresAuth && config.authFetcher) {
             const authFetchStartedAt = Date.now();
             await this.emitTelemetry(config, "pie-tool-backend-call-start", {
-                toolId: providerId,
-                providerId,
-                backend: deriveBackend(providerConfig),
+                toolId,
+                backend: telemetryBackend(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,
-                    backend: deriveBackend(providerConfig),
+                    toolId,
+                    backend: telemetryBackend(providerConfig),
                     operation: "auth-fetch",
                     duration: Date.now() - authFetchStartedAt,
                 });
             }
             catch (error) {
                 await this.emitTelemetry(config, "pie-tool-backend-call-error", {
-                    toolId: providerId,
-                    providerId,
-                    backend: deriveBackend(providerConfig),
+                    toolId,
+                    backend: telemetryBackend(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,
-                backend: deriveBackend(providerConfig),
+                toolId,
+                backend: telemetryBackend(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,
-                backend: deriveBackend(providerConfig),
+                toolId,
+                backend: telemetryBackend(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;
         }
     }
@@ -201,87 +215,55 @@ export class ToolProviderRegistry {
      * Get a provider instance
      *
      * Retrieves a registered provider. If autoInitialize is true and provider
-     * is not initialized, initializes it first.
-     *
-     * @param providerId Provider identifier
-     * @param autoInitialize Auto-initialize if not ready (default: true)
-     * @returns Provider instance
-     * @throws Error if provider not registered
+     * is not initialized, initializes it first. Throws when the provider is 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
-     *
-     * @param category Tool category to filter by
-     * @returns Array of provider IDs in the category
-     */
+    /** The ids of the tools whose provider is in `category`. */
     getProvidersByCategory(category) {
         return Array.from(this.providers.entries())
             .filter(([_, provider]) => provider.category === category)
             .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());
     }
-    /**
-     * Check if provider is registered
-     *
-     * @param providerId Provider identifier
-     * @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
-     * @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
-     * @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
+     * Removes the provider from the registry and calls its destroy method,
+     * after any start in progress settles.
      */
-    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 +271,17 @@ 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();
-            // 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.destroyProvider(toolId, provider);
+            this.providers.delete(toolId);
+            this.configs.delete(toolId);
+            this.initialized.delete(toolId);
+            this.initializationPromises.delete(toolId);
+            logger.debug(`Unregistered provider "${toolId}"`);
         }
     }
     /**
@@ -306,8 +290,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

@@ -19,6 +19,7 @@
  * Core names no capability. The requester supplies the tool id, which is why the
  * pairing of a selection action to a dictionary lives in the composition layer.
  */
+import type { ToolFailurePhase } from "./tool-failure.js";
 import type { ToolPlacementLevel } from "./tools-config-normalizer.js";
 /** Level a request resolves against when the requester names none. */
 export declare const DEFAULT_TOOL_REQUEST_LEVEL: ToolPlacementLevel;
@@ -42,17 +43,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;
     /**
@@ -70,8 +80,11 @@ export interface ToolRequestTarget {
  * earlier one is still mounted does not displace it.
  */
 export declare class ToolRequestRegistry {
+    private readonly onTargetFailure;
     private readonly targets;
     private readonly changeListeners;
+    /** `onTargetFailure` receives a target's throw, which the registry recovers from. */
+    constructor(onTargetFailure?: (toolId: string, phase: ToolFailurePhase, error: unknown) => void);
     registerTarget(target: ToolRequestTarget): () => void;
     /**
      * Whether a request for this tool would reach a toolbar.
@@ -80,16 +93,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 +116,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

@@ -28,15 +28,20 @@ export const DEFAULT_TOOL_REQUEST_LEVEL = "section";
  * earlier one is still mounted does not displace it.
  */
 export class ToolRequestRegistry {
+    onTargetFailure;
     targets = new Set();
     changeListeners = new Set();
+    /** `onTargetFailure` receives a target's throw, which the registry recovers from. */
+    constructor(onTargetFailure = (toolId, phase, error) => console.error(`[ToolRequestRegistry] "${toolId}" ${phase} failed:`, error)) {
+        this.onTargetFailure = onTargetFailure;
+    }
     registerTarget(target) {
         this.targets.add(target);
-        this.notifyChange();
+        this.notifyTargetsChange();
         return () => {
             if (!this.targets.delete(target))
                 return;
-            this.notifyChange();
+            this.notifyTargetsChange();
         };
     }
     /**
@@ -46,30 +51,31 @@ 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 {
             target.open(request.toolId, request.params);
         }
         catch (error) {
-            console.error(`[ToolRequestRegistry] Target failed to open "${request.toolId}":`, error);
+            this.onTargetFailure(request.toolId, "tool-request-open", error);
             return false;
         }
         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 +90,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;
         }
@@ -110,11 +120,16 @@ export class ToolRequestRegistry {
             return target.hostsTool(toolId) === true;
         }
         catch (error) {
-            console.warn(`[ToolRequestRegistry] Target at level "${target.level}" failed the host check for "${toolId}":`, error);
+            this.onTargetFailure(toolId, "tool-request-host-check", error);
             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,16 @@
+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;
+    parameters?: Record<string, unknown>;
+}
+/**
+ * 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,29 @@
+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,
+            parameters: entry.parameters,
+        }));
+        if (last?.renderVersion === renderVersion &&
+            structurallyEqual(last.tools, tools)) {
+            return last.tools;
+        }
+        last = { renderVersion, tools };
+        return tools;
+    };
+}