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

package/dist/services/ToolkitCoordinator.d.ts

@@ -14,7 +14,7 @@
  * Part of PIE Assessment Toolkit.
  */
 import type { AccessibilityCatalog, AssessmentEntity, AssessmentItemRef } from "@pie-players/pie-players-shared/types";
-import { type CanonicalToolsConfig, type ToolPlacementConfig, type ToolPlacementLevel, type ToolPolicyConfig, type ToolProviderConfig, type ToolProvidersConfig } from "./tools-config-normalizer.js";
+import { type CanonicalToolsConfig, type ToolPlacementConfig, type ToolPlacementLevel, type ToolPolicyConfig, type TextToSpeechToolProviderConfig, type ToolProviderConfig, type ToolProvidersConfig, type ToolsConfigInput } from "./tools-config-normalizer.js";
 import { type ToolConfigStrictness } from "./tool-config-validation.js";
 import { AccessibilityCatalogResolver } from "./AccessibilityCatalogResolver.js";
 import type { CatalogChangeListener } from "./AccessibilityCatalogResolver.js";
@@ -28,7 +28,6 @@ import { type TTSRuntimeSettings } from "./tts-runtime-config.js";
 import type { SREMathSpeechOptions } from "./tts/math-speech.js";
 import { ToolProviderRegistry } from "./tool-providers/index.js";
 import type { ToolProviderApi } from "./tool-providers/ToolProviderApi.js";
-import type { TTSToolProviderConfig } from "./tool-providers/index.js";
 import { ToolRegistry } from "./ToolRegistry.js";
 import type { ResolvedToolContext, ToolContextResolver, ToolContextResolverContext, ToolContextResolverMap } from "./ToolRegistry.js";
 import type { ToolOpenRequest, ToolRequestTarget } from "./tool-request.js";
@@ -50,20 +49,21 @@ export interface ToolConfig {
  *
  * The field set is `TTSRuntimeSettings`, which the runtime resolver owns: the two
  * were declared separately and had already drifted in both directions, so a field
- * the runtime honoured could not be named here. What this adds is the two things
- * only a host-facing config has — a place to stash unrecognised keys, and a
- * callback for fetching provider credentials, neither of which the resolved
- * runtime settings carry.
+ * the runtime honoured could not be named here. What this adds is the one thing
+ * only a host-facing config has — a place to stash unrecognised keys, which the
+ * resolved runtime settings do not carry.
  *
- * An intersection rather than an interface: `ToolConfig.provider` is `unknown`
- * where the runtime settings narrow it to the three provider ids, and an interface
- * cannot inherit a member from two parents that type it differently.
+ * `provider` is typed from the `textToSpeech` tools-config entry instead: a host
+ * gives either a server provider id or a runtime provider object, whose
+ * `runtime.authFetcher` the TTS registration reads, and `TTSRuntimeSettings`
+ * names only the id. The entry is therefore assignable to this type, which is
+ * what `getToolConfig("textToSpeech")` returns.
  */
-export type TTSToolConfig = ToolConfig & TTSRuntimeSettings & {
+export type TTSToolConfig = ToolConfig & Omit<TTSRuntimeSettings, "provider"> & {
+    provider?: TextToSpeechToolProviderConfig["provider"];
     settings?: Record<string, unknown> & {
         mathSpeech?: SREMathSpeechOptions;
     };
-    authFetcher?: () => Promise<Partial<TTSToolProviderConfig>>;
 };
 /**
  * Answer eliminator tool configuration
@@ -89,7 +89,7 @@ export interface ToolkitCoordinatorConfig {
      * Tool availability and configuration.
      * Defaults: all tools enabled with default settings.
      */
-    tools?: Partial<CanonicalToolsConfig>;
+    tools?: ToolsConfigInput;
     /**
      * Validation strictness for tool config contracts.
      * - off: keep diagnostics internal (no warnings or throws)
@@ -100,8 +100,12 @@ export interface ToolkitCoordinatorConfig {
      */
     toolConfigStrictness?: ToolConfigStrictness;
     /**
-     * Optional registry used for tool-config validation and provider descriptor resolution.
-     * Defaults to packaged PIE tools when omitted.
+     * Registry used for tool-config validation and the only source of tool
+     * providers: the coordinator registers one per registration that carries a
+     * provider descriptor. Omitted, the coordinator takes the registry of the
+     * toolkit it is bound to — the section player's, under a section player — and
+     * until then validates nothing and registers no provider. A registry passed
+     * here is never replaced.
      */
     toolRegistry?: ToolRegistry | null;
     /**
@@ -139,6 +143,15 @@ export interface ToolkitCoordinatorConfig {
      * @internal
      */
     deferToolConfigValidation?: boolean;
+    /**
+     * Set by `<pie-assessment-toolkit>` on the coordinator it builds for itself.
+     * That toolkit binds only the `assessment` its host passes, and a section
+     * player passes none, so feature policy reports an unbound assessment only
+     * while PNP enforcement is explicitly `"on"`.
+     *
+     * @internal
+     */
+    assessmentOptional?: boolean;
     /**
      * Optional pre-constructed framework-error bus.
      *
@@ -272,9 +285,13 @@ export interface ToolkitServiceBundle {
  *
  * @example
  * ```typescript
+ * // createPackagedToolRegistry is exported by @pie-players/pie-default-tool-loaders
+ * const toolRegistry = createPackagedToolRegistry();
+ *
  * // Create coordinator with configuration
  * const coordinator = new ToolkitCoordinator({
  *   assessmentId: 'demo-three-questions',
+ *   toolRegistry,
  *   tools: {
  *     providers: {
  *       textToSpeech: { enabled: true, backend: 'browser' },
@@ -287,7 +304,7 @@ export interface ToolkitServiceBundle {
  * });
  *
  * // Pass to section player
- * player.toolkitCoordinator = coordinator;
+ * player.runtime = { ...(player.runtime ?? {}), coordinator };
  *
  * // Access services directly
  * const ttsService = coordinator.ttsService;
@@ -317,7 +334,15 @@ export declare class ToolkitCoordinator {
     private coordinatorReadyPromise?;
     private coordinatorReadyNotified;
     private readonly providerInitPromises;
-    private readonly toolRegistry;
+    private toolRegistry;
+    /** Whether the host passed `toolRegistry`, which then always stands. */
+    private readonly toolRegistrySupplied;
+    /**
+     * Whether the registry is final: supplied at construction, or adopted from
+     * the toolkit this coordinator is bound to. Until then the empty placeholder
+     * reports no missing registry, since the toolkit will supply one.
+     */
+    private toolRegistrySettled;
     private readonly toolContextResolvers;
     private readonly toolContextResolverChangeListeners;
     private readonly toolRequests;
@@ -404,7 +429,31 @@ export declare class ToolkitCoordinator {
      * lifetime for no new information.
      */
     private reportedUnboundFeaturePolicy;
-    private static resolveConfig;
+    /**
+     * Whether {@link _initializeTTS} has already reported a non-browser backend
+     * falling back to browser speech because no `tts` provider is registered.
+     * Once per coordinator: a text-to-speech config change re-runs
+     * initialization, and the missing provider is the same gap each time.
+     */
+    private reportedMissingTTSProvider;
+    /**
+     * The backend of a fallback {@link reportMissingTTSProvider} held back while
+     * the registry was unsettled, reported if the bound toolkit has no registry.
+     */
+    private heldMissingTTSProviderBackend;
+    /**
+     * Whether {@link validateToolsConfig} has already reported validating with
+     * no registry (`tools.registryUnavailable`). Once per coordinator: every
+     * {@link updateToolConfig} and {@link updateToolsPlacement} re-validates, and
+     * the missing registry is the same gap each time.
+     */
+    private reportedRegistryUnavailable;
+    private resolveConfig;
+    /**
+     * `normalizeAndValidateToolsConfig`, except that `tools.registryUnavailable`
+     * is reported once per coordinator, whichever call validates.
+     */
+    private validateToolsConfig;
     constructor(config: ToolkitCoordinatorConfig);
     private assertNotDisposed;
     /**
@@ -472,15 +521,37 @@ export declare class ToolkitCoordinator {
     private resolveSectionPersistence;
     private setupStatePersistenceHooks;
     private ensureStateLoaded;
+    private reportMissingTTSProvider;
+    /**
+     * Take the registry of the toolkit this coordinator is bound to, when the host
+     * constructed it without one: the config is validated against it, its
+     * providers register, and text-to-speech re-initializes through it if it
+     * already started. The toolkit elements call this on binding. A registry
+     * passed at construction stands, and the first call wins; `null` records a
+     * toolkit without one, which reports the registry as missing.
+     *
+     * @returns Whether `registry` was adopted.
+     */
+    adoptToolRegistry(registry: ToolRegistry | null): boolean;
     /**
      * Register tool providers in the registry
      */
     private _registerToolProviders;
     private getProviderDescriptorTools;
+    /**
+     * Register the provider `tool`'s descriptor creates for the tool's current
+     * config, unless the tool is disabled or that provider id is registered. A
+     * descriptor that throws is reported the way a failed registration is.
+     */
     private registerProviderFromTool;
     private createToolTelemetryForwarder;
     private addToolTelemetryReporter;
     private registerProvider;
+    /**
+     * A console warning and a `provider-register` framework error. `providerId`
+     * is null when resolving it is what failed; the warning names the tool then.
+     */
+    private reportProviderRegisterFailure;
     ensureProviderReady(providerId: string): Promise<ToolProviderApi>;
     setHooks(hooks: ToolkitCoordinatorHooks): void;
     subscribeTelemetry(listener: ToolkitTelemetryListener): () => void;
@@ -637,6 +708,7 @@ export declare class ToolkitCoordinator {
      * @param toolId Tool identifier
      * @returns Tool configuration or null if not configured
      */
+    getToolConfig(toolId: "textToSpeech"): TTSToolConfig | null;
     getToolConfig(toolId: string): ToolProviderConfig | null;
     /**
      * Update tool configuration.
@@ -679,6 +751,11 @@ export declare class ToolkitCoordinator {
      * capability it asks about, which is indistinguishable from a student who was
      * properly declined — so without this, forgetting {@link updateAssessment}
      * presents as an accommodation that silently never appears.
+     *
+     * A coordinator built with `assessmentOptional` reports only while PNP
+     * enforcement is explicitly `"on"`. Its toolkit binds whatever assessment the
+     * host gave, usually none, and a host that passes no profile and leaves
+     * enforcement unset or `"off"` has asked for no accommodation.
      */
     decideFeaturePolicy(featureId: string): FeaturePolicyDecision;
     /**
@@ -806,8 +883,23 @@ export declare class ToolkitCoordinator {
     private resolveConfiguredPnpEnforcement;
     /**
      * Apply tool configuration changes to underlying services.
-     * Called after updateToolConfig().
+     * Called after updateToolConfig() with the tool's config before the update.
      */
     private _applyToolConfigChange;
+    /**
+     * Register the provider a tool's updated config names, and unregister the
+     * one its previous config named when the provider id changed, as
+     * {@link _reconfigureTTSProvider} does for `tts`. Registration completes
+     * before this returns, so a check on the policy change the update dispatched
+     * finds the new provider.
+     */
+    private _registerChangedToolProvider;
+    /**
+     * Re-register the `tts` provider for the current config and registry, then
+     * re-initialize unless initialization is lazy. An initialization already
+     * running finishes first: it would otherwise mark its provider ready after
+     * the reset.
+     */
+    private scheduleTTSReconfigure;
     private _reconfigureTTSProvider;
 }