@wp-typia/project-tools 0.22.0 → 0.22.2

package/dist/runtime/cli-add-workspace-ai-source-emitters.js

@@ -1,6 +1,6 @@
 import { quoteTsString } from "./cli-add-shared.js";
 import { buildAiFeatureEndpointManifest } from "./ai-feature-artifacts.js";
-import { OPTIONAL_WORDPRESS_AI_CLIENT_COMPATIBILITY, renderScaffoldCompatibilityConfig, resolveScaffoldCompatibilityPolicy, } from "./scaffold-compatibility.js";
+import { OPTIONAL_WORDPRESS_AI_CLIENT_COMPATIBILITY, createScaffoldCompatibilityConfig, renderScaffoldCompatibilityConfig, resolveScaffoldCompatibilityPolicy, } from "./scaffold-compatibility.js";
 import { toPascalCase, toTitleCase } from "./string-case.js";
 function indentMultiline(source, prefix) {
     return source
@@ -79,6 +79,45 @@ export interface ${pascalCase}AiFeatureResponse {
 \tresult: ${pascalCase}AiFeatureResult;
 \ttelemetry: ${pascalCase}AiFeatureTelemetry;
 }
+
+export type ${pascalCase}AiFeatureSupportProbeMode = 'request-time';
+
+export type ${pascalCase}AiFeatureUnavailableErrorCode =
+\t'ai_client_unavailable';
+
+export type ${pascalCase}AiFeatureUnavailableReasonCode =
+\t| 'missing-wordpress-ai-client'
+\t| 'request-time-support-probe';
+
+export interface ${pascalCase}AiFeatureSupportReason {
+\tcode: ${pascalCase}AiFeatureUnavailableReasonCode;
+\tlabel: string & tags.MinLength< 1 > & tags.MaxLength< 160 >;
+\tmessage: string & tags.MinLength< 1 > & tags.MaxLength< 4000 >;
+}
+
+export interface ${pascalCase}AiFeatureSupportMetadata {
+\tfeatureLabel: string & tags.MinLength< 1 > & tags.MaxLength< 160 >;
+\tfeatureSlug: string & tags.MinLength< 1 > & tags.MaxLength< 160 >;
+\tcompatibility: {
+\t\thardMinimums: {
+\t\t\tphp?: string;
+\t\t\twordpress?: string;
+\t\t};
+\t\tmode: 'baseline' | 'optional' | 'required';
+\t\toptionalFeatureIds: string[];
+\t\toptionalFeatures: string[];
+\t\trequiredFeatureIds: string[];
+\t\trequiredFeatures: string[];
+\t\truntimeGates: string[];
+\t};
+\tsupportProbe: {
+\t\tendpointMethod: 'POST';
+\t\tendpointPath: string & tags.MinLength< 1 > & tags.MaxLength< 200 >;
+\t\tmode: ${pascalCase}AiFeatureSupportProbeMode;
+\t\tunavailableErrorCode: ${pascalCase}AiFeatureUnavailableErrorCode;
+\t};
+\tunavailableReasons: ${pascalCase}AiFeatureSupportReason[];
+}
 `;
 }
 /**
@@ -120,6 +159,8 @@ export const apiValidators = {
  */
 export function buildAiFeatureApiSource(aiFeatureSlug) {
     const pascalCase = toPascalCase(aiFeatureSlug);
+    const compatibility = createScaffoldCompatibilityConfig(resolveScaffoldCompatibilityPolicy(OPTIONAL_WORDPRESS_AI_CLIENT_COMPATIBILITY));
+    const title = toTitleCase(aiFeatureSlug);
     return `import {
 \tcallEndpoint,
 \tresolveRestRouteUrl,
@@ -127,6 +168,7 @@ export function buildAiFeatureApiSource(aiFeatureSlug) {
 
 import type {
 \t${pascalCase}AiFeatureRequest,
+\t${pascalCase}AiFeatureSupportMetadata,
 } from './api-types';
 import {
 \trun${pascalCase}AiFeatureEndpoint,
@@ -153,6 +195,14 @@ function resolveRestNonce( fallback?: string ): string | undefined {
 \t\t: undefined;
 }
 
+function isPlainObject( value: unknown ): value is Record< string, unknown > {
+\treturn (
+\t\t!! value &&
+\t\ttypeof value === 'object' &&
+\t\t! Array.isArray( value )
+\t);
+}
+
 export const aiFeatureRunEndpoint = {
 \t...run${pascalCase}AiFeatureEndpoint,
 \tbuildRequestOptions: () => {
@@ -168,6 +218,63 @@ export const aiFeatureRunEndpoint = {
 \t},
 };
 
+export const aiFeatureSupportMetadata = {
+\tcompatibility: ${JSON.stringify(compatibility, null, "\t")},
+\tfeatureLabel: ${quoteTsString(title)},
+\tfeatureSlug: ${quoteTsString(aiFeatureSlug)},
+\tsupportProbe: {
+\t\tendpointMethod: 'POST',
+\t\tendpointPath: aiFeatureRunEndpoint.path,
+\t\tmode: 'request-time',
+\t\tunavailableErrorCode: 'ai_client_unavailable',
+\t},
+\tunavailableReasons: [
+\t\t{
+\t\t\tcode: 'missing-wordpress-ai-client',
+\t\t\tlabel: 'WordPress AI Client unavailable',
+\t\t\tmessage:
+\t\t\t\t'This AI feature stays disabled until the WordPress AI Client is available on the site.',
+\t\t},
+\t\t{
+\t\t\tcode: 'request-time-support-probe',
+\t\t\tlabel: 'Support is checked at request time',
+\t\t\tmessage:
+\t\t\t\t'Support is verified when the feature runs, so editor and admin UIs should degrade gracefully when the site rejects the request.',
+\t\t},
+\t],
+} satisfies ${pascalCase}AiFeatureSupportMetadata;
+
+export function getAiFeatureSupportHintLines() {
+\treturn aiFeatureSupportMetadata.unavailableReasons.map(
+\t\t( reason ) => reason.message
+\t);
+}
+
+export function isAiFeatureSupportUnavailableError( error: unknown ) {
+\tif ( ! isPlainObject( error ) ) {
+\t\treturn false;
+\t}
+
+\tconst data = isPlainObject( error.data ) ? error.data : undefined;
+\treturn (
+\t\terror.code === aiFeatureSupportMetadata.supportProbe.unavailableErrorCode ||
+\t\tdata?.status === 501
+\t);
+}
+
+export function resolveAiFeatureUnavailableMessage( error: unknown ) {
+\tif (
+\t\tisPlainObject( error ) &&
+\t\ttypeof error.message === 'string' &&
+\t\terror.message.length > 0
+\t) {
+\t\treturn error.message;
+\t}
+
+\treturn aiFeatureSupportMetadata.unavailableReasons[ 0 ]?.message ??
+\t\t'This AI feature is currently unavailable.';
+}
+
 export function runAiFeature( request: ${pascalCase}AiFeatureRequest ) {
 \treturn callEndpoint( aiFeatureRunEndpoint, request );
 }
@@ -189,6 +296,10 @@ import type {
 } from './api-types';
 import {
 \taiFeatureRunEndpoint,
+\taiFeatureSupportMetadata,
+\tgetAiFeatureSupportHintLines,
+\tisAiFeatureSupportUnavailableError,
+\tresolveAiFeatureUnavailableMessage,
 } from './api';
 
 export type UseRun${pascalCase}AiFeatureMutationOptions =
@@ -203,6 +314,13 @@ export function useRun${pascalCase}AiFeatureMutation(
 ) {
 \treturn useEndpointMutation( aiFeatureRunEndpoint, options );
 }
+
+export {
+\taiFeatureSupportMetadata,
+\tgetAiFeatureSupportHintLines,
+\tisAiFeatureSupportUnavailableError,
+\tresolveAiFeatureUnavailableMessage,
+};
 `;
 }
 /**

package/dist/runtime/cli-add-workspace-ai.js

@@ -18,18 +18,40 @@ function buildAiFeaturePhpSource(aiFeatureSlug, namespace, phpPrefix, textDomain
     const normalizeSchemaFunctionName = `${phpPrefix}_${aiFeaturePhpId}_sanitize_ai_feature_schema`;
     const validatePayloadFunctionName = `${phpPrefix}_${aiFeaturePhpId}_validate_ai_feature_payload`;
     const canManageFunctionName = `${phpPrefix}_${aiFeaturePhpId}_can_manage_ai_feature`;
+    const normalizePromptPayloadFunctionName = `${phpPrefix}_${aiFeaturePhpId}_normalize_ai_feature_prompt_payload`;
     const buildPromptFunctionName = `${phpPrefix}_${aiFeaturePhpId}_build_ai_feature_prompt`;
+    const resolvePromptOptionsFunctionName = `${phpPrefix}_${aiFeaturePhpId}_resolve_ai_feature_prompt_options`;
     const normalizeProviderTypeFunctionName = `${phpPrefix}_${aiFeaturePhpId}_normalize_provider_type`;
     const buildTelemetryFunctionName = `${phpPrefix}_${aiFeaturePhpId}_build_ai_feature_telemetry`;
+    const resolveUnavailableMessageFunctionName = `${phpPrefix}_${aiFeaturePhpId}_resolve_ai_feature_unavailable_message`;
     const isSupportedFunctionName = `${phpPrefix}_${aiFeaturePhpId}_is_ai_feature_supported`;
     const adminNoticeFunctionName = `${phpPrefix}_${aiFeaturePhpId}_ai_feature_admin_notice`;
     const handlerFunctionName = `${phpPrefix}_${aiFeaturePhpId}_handle_run_ai_feature`;
     const registerRoutesFunctionName = `${phpPrefix}_${aiFeaturePhpId}_register_ai_feature_routes`;
+    const permissionFilterHook = `${phpPrefix}_${aiFeaturePhpId}_ai_feature_permission`;
+    const promptPayloadFilterHook = `${phpPrefix}_${aiFeaturePhpId}_ai_feature_prompt_payload`;
+    const promptFilterHook = `${phpPrefix}_${aiFeaturePhpId}_ai_feature_prompt`;
+    const promptOptionsFilterHook = `${phpPrefix}_${aiFeaturePhpId}_ai_feature_prompt_options`;
+    const adminNoticeMessageFilterHook = `${phpPrefix}_${aiFeaturePhpId}_ai_feature_admin_notice_message`;
+    const unavailableMessageFilterHook = `${phpPrefix}_${aiFeaturePhpId}_ai_feature_unavailable_message`;
+    const telemetryFilterHook = `${phpPrefix}_${aiFeaturePhpId}_ai_feature_telemetry`;
     return `<?php
 if ( ! defined( 'ABSPATH' ) ) {
 \treturn;
 }
 
+/*
+ * Customization hooks for the ${aiFeatureTitle} AI feature:
+ *
+ * - ${quotePhpString(permissionFilterHook)} filters the default current_user_can( 'edit_posts' ) capability check.
+ * - ${quotePhpString(promptPayloadFilterHook)} filters the validated request payload array before prompt serialization.
+ * - ${quotePhpString(promptFilterHook)} filters the final prompt string after payload normalization.
+ * - ${quotePhpString(promptOptionsFilterHook)} filters prompt options with \`temperature\` and \`modelPreference\` keys.
+ * - ${quotePhpString(adminNoticeMessageFilterHook)} filters the wp-admin notice shown when AI support is unavailable.
+ * - ${quotePhpString(unavailableMessageFilterHook)} filters REST-facing unavailable messages by reason code.
+ * - ${quotePhpString(telemetryFilterHook)} filters the response telemetry array before schema validation. Return a schema-compatible array.
+ */
+
 if ( ! function_exists( '${loadSchemaFunctionName}' ) ) {
 \tfunction ${loadSchemaFunctionName}( $schema_name ) {
 \t\t$project_root = dirname( __DIR__, 2 );
@@ -96,17 +118,111 @@ if ( ! function_exists( '${validatePayloadFunctionName}' ) ) {
 }
 
 if ( ! function_exists( '${canManageFunctionName}' ) ) {
-\tfunction ${canManageFunctionName}() {
-\t\treturn current_user_can( 'edit_posts' );
+\tfunction ${canManageFunctionName}( WP_REST_Request $request = null ) {
+\t\t$permission = apply_filters(
+\t\t\t${quotePhpString(permissionFilterHook)},
+\t\t\tcurrent_user_can( 'edit_posts' ),
+\t\t\t$request
+\t\t);
+\t\tif ( is_wp_error( $permission ) ) {
+\t\t\treturn $permission;
+\t\t}
+\t\treturn (bool) $permission;
+\t}
+}
+
+if ( ! function_exists( '${normalizePromptPayloadFunctionName}' ) ) {
+\tfunction ${normalizePromptPayloadFunctionName}( array $payload ) {
+\t\t$normalized_payload = apply_filters(
+\t\t\t${quotePhpString(promptPayloadFilterHook)},
+\t\t\t$payload
+\t\t);
+\t\treturn is_array( $normalized_payload ) ? $normalized_payload : $payload;
 \t}
 }
 
 if ( ! function_exists( '${buildPromptFunctionName}' ) ) {
 \tfunction ${buildPromptFunctionName}( array $payload ) {
-\t\treturn sprintf(
+\t\t$normalized_payload = ${normalizePromptPayloadFunctionName}( $payload );
+\t\t$prompt = sprintf(
 \t\t\t'You are helping with the %1$s AI workflow. Read the JSON request payload and return JSON that matches the provided schema. Request payload: %2$s',
 \t\t\t${quotePhpString(aiFeatureTitle)},
-\t\t\twp_json_encode( $payload )
+\t\t\twp_json_encode( $normalized_payload )
+\t\t);
+\t\t$filtered_prompt = apply_filters(
+\t\t\t${quotePhpString(promptFilterHook)},
+\t\t\t$prompt,
+\t\t\t$normalized_payload,
+\t\t\t$payload
+\t\t);
+\t\treturn is_string( $filtered_prompt ) && '' !== $filtered_prompt ? $filtered_prompt : $prompt;
+\t}
+}
+
+if ( ! function_exists( '${resolvePromptOptionsFunctionName}' ) ) {
+\tfunction ${resolvePromptOptionsFunctionName}( array $payload = array() ) {
+\t\t$options = apply_filters(
+\t\t\t${quotePhpString(promptOptionsFilterHook)},
+\t\t\tarray(
+\t\t\t\t'modelPreference' => array(),
+\t\t\t\t'temperature'     => 0.2,
+\t\t\t),
+\t\t\t$payload
+\t\t);
+\t\tif ( ! is_array( $options ) ) {
+\t\t\t$options = array();
+\t\t}
+
+\t\t$temperature = 0.2;
+\t\tif ( array_key_exists( 'temperature', $options ) ) {
+\t\t\tif ( null === $options['temperature'] ) {
+\t\t\t\t$temperature = null;
+\t\t\t} elseif ( is_numeric( $options['temperature'] ) ) {
+\t\t\t\t$temperature = (float) $options['temperature'];
+\t\t\t}
+\t\t}
+
+\t\t$model_preferences = array();
+\t\tif ( isset( $options['modelPreference'] ) ) {
+\t\t\t$raw_model_preferences = $options['modelPreference'];
+\t\t\tif ( is_string( $raw_model_preferences ) && '' !== $raw_model_preferences ) {
+\t\t\t\t$model_preferences = array( $raw_model_preferences );
+\t\t\t} elseif ( is_array( $raw_model_preferences ) ) {
+\t\t\t\t$model_preferences = array_values(
+\t\t\t\t\tarray_filter(
+\t\t\t\t\t\tarray_map(
+\t\t\t\t\t\t\tstatic function ( $candidate ) {
+\t\t\t\t\t\t\t\tif ( is_string( $candidate ) && '' !== $candidate ) {
+\t\t\t\t\t\t\t\t\treturn $candidate;
+\t\t\t\t\t\t\t\t}
+\t\t\t\t\t\t\t\tif ( ! is_array( $candidate ) ) {
+\t\t\t\t\t\t\t\t\treturn null;
+\t\t\t\t\t\t\t\t}
+
+\t\t\t\t\t\t\t\t$normalized = array_values(
+\t\t\t\t\t\t\t\t\tarray_filter(
+\t\t\t\t\t\t\t\t\t\t$candidate,
+\t\t\t\t\t\t\t\t\t\tstatic function ( $value ) {
+\t\t\t\t\t\t\t\t\t\t\treturn is_string( $value ) && '' !== $value;
+\t\t\t\t\t\t\t\t\t\t}
+\t\t\t\t\t\t\t\t\t)
+\t\t\t\t\t\t\t\t);
+
+\t\t\t\t\t\t\t\treturn count( $normalized ) > 0 ? $normalized : null;
+\t\t\t\t\t\t\t},
+\t\t\t\t\t\t\t$raw_model_preferences
+\t\t\t\t\t\t),
+\t\t\t\t\t\tstatic function ( $candidate ) {
+\t\t\t\t\t\t\treturn null !== $candidate;
+\t\t\t\t\t\t}
+\t\t\t\t\t)
+\t\t\t\t);
+\t\t\t}
+\t\t}
+
+\t\treturn array(
+\t\t\t'modelPreference' => $model_preferences,
+\t\t\t'temperature'     => $temperature,
 \t\t);
 \t}
 }
@@ -122,7 +238,7 @@ if ( ! function_exists( '${normalizeProviderTypeFunctionName}' ) ) {
 }
 
 if ( ! function_exists( '${buildTelemetryFunctionName}' ) ) {
-\tfunction ${buildTelemetryFunctionName}( $result ) {
+\tfunction ${buildTelemetryFunctionName}( $result, array $payload = array(), array $normalized_result = array() ) {
 \t\tif (
 \t\t\t! is_object( $result ) ||
 \t\t\t! method_exists( $result, 'getId' ) ||
@@ -182,47 +298,95 @@ if ( ! function_exists( '${buildTelemetryFunctionName}' ) ) {
 \t\t\t}
 \t\t}
 
-\t\treturn $telemetry;
+\t\t$filtered_telemetry = apply_filters(
+\t\t\t${quotePhpString(telemetryFilterHook)},
+\t\t\t$telemetry,
+\t\t\t$result,
+\t\t\t$payload,
+\t\t\t$normalized_result
+\t\t);
+\t\treturn is_array( $filtered_telemetry ) ? $filtered_telemetry : $telemetry;
+\t}
+}
+
+if ( ! function_exists( '${resolveUnavailableMessageFunctionName}' ) ) {
+\tfunction ${resolveUnavailableMessageFunctionName}( $message, $reason, array $context = array() ) {
+\t\t$filtered_message = apply_filters(
+\t\t\t${quotePhpString(unavailableMessageFilterHook)},
+\t\t\t$message,
+\t\t\t$reason,
+\t\t\t$context
+\t\t);
+\t\treturn is_string( $filtered_message ) && '' !== $filtered_message ? $filtered_message : $message;
 \t}
 }
 
 if ( ! function_exists( '${isSupportedFunctionName}' ) ) {
-\tfunction ${isSupportedFunctionName}() {
+\tfunction ${isSupportedFunctionName}( array $payload = array(), $cache_result = true ) {
 \t\tstatic $is_supported = null;
-\t\tif ( null !== $is_supported ) {
+\t\t$use_cache = $cache_result && count( $payload ) === 0;
+\t\tif ( $use_cache && null !== $is_supported ) {
 \t\t\treturn $is_supported;
 \t\t}
 
 \t\tif ( ! function_exists( 'wp_ai_client_prompt' ) ) {
-\t\t\t$is_supported = false;
-\t\t\treturn $is_supported;
+\t\t\tif ( $use_cache ) {
+\t\t\t\t$is_supported = false;
+\t\t\t}
+\t\t\treturn false;
 \t\t}
 
 \t\t$schema = ${loadAiSchemaFunctionName}();
 \t\tif ( ! is_array( $schema ) ) {
-\t\t\t$is_supported = false;
-\t\t\treturn $is_supported;
+\t\t\tif ( $use_cache ) {
+\t\t\t\t$is_supported = false;
+\t\t\t}
+\t\t\treturn false;
 \t\t}
 
 \t\t$prompt = wp_ai_client_prompt( 'AI feature support probe.' );
 \t\tif ( ! is_object( $prompt ) || ! method_exists( $prompt, 'as_json_response' ) ) {
-\t\t\t$is_supported = false;
-\t\t\treturn $is_supported;
+\t\t\tif ( $use_cache ) {
+\t\t\t\t$is_supported = false;
+\t\t\t}
+\t\t\treturn false;
+\t\t}
+\t\t$prompt_options = ${resolvePromptOptionsFunctionName}( $payload );
+\t\tif (
+\t\t\tarray_key_exists( 'temperature', $prompt_options ) &&
+\t\t\tnull !== $prompt_options['temperature'] &&
+\t\t\tmethod_exists( $prompt, 'using_temperature' )
+\t\t) {
+\t\t\t$prompt = $prompt->using_temperature( $prompt_options['temperature'] );
+\t\t}
+\t\tif (
+\t\t\t! empty( $prompt_options['modelPreference'] ) &&
+\t\t\tmethod_exists( $prompt, 'using_model_preference' )
+\t\t) {
+\t\t\t$prompt = $prompt->using_model_preference( ...$prompt_options['modelPreference'] );
 \t\t}
 
 \t\t$structured_prompt = $prompt->as_json_response( $schema );
 \t\tif ( ! is_object( $structured_prompt ) ) {
-\t\t\t$is_supported = false;
-\t\t\treturn $is_supported;
+\t\t\tif ( $use_cache ) {
+\t\t\t\t$is_supported = false;
+\t\t\t}
+\t\t\treturn false;
 \t\t}
 
 \t\tif ( method_exists( $structured_prompt, 'is_supported_for_text_generation' ) ) {
-\t\t\t$is_supported = (bool) $structured_prompt->is_supported_for_text_generation();
-\t\t\treturn $is_supported;
+\t\t\t$supported = (bool) $structured_prompt->is_supported_for_text_generation();
+\t\t\tif ( $use_cache ) {
+\t\t\t\t$is_supported = $supported;
+\t\t\t}
+\t\t\treturn $supported;
 \t\t}
 
-\t\t$is_supported = method_exists( $structured_prompt, 'generate_text_result' );
-\t\treturn $is_supported;
+\t\t$supported = method_exists( $structured_prompt, 'generate_text_result' );
+\t\tif ( $use_cache ) {
+\t\t\t$is_supported = $supported;
+\t\t}
+\t\treturn $supported;
 \t}
 }
 
@@ -237,6 +401,18 @@ if ( ! function_exists( '${adminNoticeFunctionName}' ) ) {
 \t\t\t__( 'The %s AI feature is optional and remains disabled until the WordPress AI Client is available with structured text generation support for the generated schema.', ${quotePhpString(textDomain)} ),
 \t\t\t${quotePhpString(aiFeatureTitle)}
 \t\t);
+\t\t$filtered_message = apply_filters(
+\t\t\t${quotePhpString(adminNoticeMessageFilterHook)},
+\t\t\t$message,
+\t\t\tarray(
+\t\t\t\t'featureSlug'  => ${quotePhpString(aiFeatureSlug)},
+\t\t\t\t'featureTitle' => ${quotePhpString(aiFeatureTitle)},
+\t\t\t\t'namespace'    => ${quotePhpString(namespace)},
+\t\t\t)
+\t\t);
+\t\tif ( is_string( $filtered_message ) && '' !== $filtered_message ) {
+\t\t\t$message = $filtered_message;
+\t\t}
 \t\tprintf( '<div class="notice notice-warning"><p>%s</p></div>', esc_html( $message ) );
 \t}
 }
@@ -248,10 +424,16 @@ if ( ! function_exists( '${handlerFunctionName}' ) ) {
 \t\t\treturn $payload;
 \t\t}
 
-\t\tif ( ! ${isSupportedFunctionName}() ) {
+\t\tif ( ! ${isSupportedFunctionName}( $payload, false ) ) {
 \t\t\treturn new WP_Error(
 \t\t\t\t'ai_client_unavailable',
-\t\t\t\t'The WordPress AI Client is unavailable or does not support this feature endpoint.',
+\t\t\t\t${resolveUnavailableMessageFunctionName}(
+\t\t\t\t\t'The WordPress AI Client is unavailable or does not support this feature endpoint.',
+\t\t\t\t\t'support_probe_failed',
+\t\t\t\t\tarray(
+\t\t\t\t\t\t'featureSlug' => ${quotePhpString(aiFeatureSlug)},
+\t\t\t\t\t)
+\t\t\t\t),
 \t\t\t\tarray( 'status' => 501 )
 \t\t\t);
 \t\t}
@@ -265,22 +447,45 @@ if ( ! function_exists( '${handlerFunctionName}' ) ) {
 \t\t\t);
 \t\t}
 
+\t\t$prompt_options = ${resolvePromptOptionsFunctionName}( $payload );
 \t\t$prompt = wp_ai_client_prompt( ${buildPromptFunctionName}( $payload ) );
 \t\tif ( ! is_object( $prompt ) ) {
 \t\t\treturn new WP_Error(
 \t\t\t\t'ai_client_unavailable',
-\t\t\t\t'The WordPress AI Client prompt builder is unavailable on this site.',
+\t\t\t\t${resolveUnavailableMessageFunctionName}(
+\t\t\t\t\t'The WordPress AI Client prompt builder is unavailable on this site.',
+\t\t\t\t\t'prompt_builder_missing',
+\t\t\t\t\tarray(
+\t\t\t\t\t\t'featureSlug' => ${quotePhpString(aiFeatureSlug)},
+\t\t\t\t\t)
+\t\t\t\t),
 \t\t\t\tarray( 'status' => 501 )
 \t\t\t);
 \t\t}
 
-\t\tif ( method_exists( $prompt, 'using_temperature' ) ) {
-\t\t\t$prompt = $prompt->using_temperature( 0.2 );
+\t\tif (
+\t\t\tarray_key_exists( 'temperature', $prompt_options ) &&
+\t\t\tnull !== $prompt_options['temperature'] &&
+\t\t\tmethod_exists( $prompt, 'using_temperature' )
+\t\t) {
+\t\t\t$prompt = $prompt->using_temperature( $prompt_options['temperature'] );
+\t\t}
+\t\tif (
+\t\t\t! empty( $prompt_options['modelPreference'] ) &&
+\t\t\tmethod_exists( $prompt, 'using_model_preference' )
+\t\t) {
+\t\t\t$prompt = $prompt->using_model_preference( ...$prompt_options['modelPreference'] );
 \t\t}
 \t\tif ( ! method_exists( $prompt, 'as_json_response' ) ) {
 \t\t\treturn new WP_Error(
 \t\t\t\t'ai_client_unavailable',
-\t\t\t\t'The current WordPress AI Client does not expose as_json_response().',
+\t\t\t\t${resolveUnavailableMessageFunctionName}(
+\t\t\t\t\t'The current WordPress AI Client does not expose as_json_response().',
+\t\t\t\t\t'as_json_response_missing',
+\t\t\t\t\tarray(
+\t\t\t\t\t\t'featureSlug' => ${quotePhpString(aiFeatureSlug)},
+\t\t\t\t\t)
+\t\t\t\t),
 \t\t\t\tarray( 'status' => 501 )
 \t\t\t);
 \t\t}
@@ -289,7 +494,13 @@ if ( ! function_exists( '${handlerFunctionName}' ) ) {
 \t\tif ( ! is_object( $structured_prompt ) ) {
 \t\t\treturn new WP_Error(
 \t\t\t\t'ai_client_unavailable',
-\t\t\t\t'The current WordPress AI Client could not prepare a structured-output prompt.',
+\t\t\t\t${resolveUnavailableMessageFunctionName}(
+\t\t\t\t\t'The current WordPress AI Client could not prepare a structured-output prompt.',
+\t\t\t\t\t'structured_prompt_missing',
+\t\t\t\t\tarray(
+\t\t\t\t\t\t'featureSlug' => ${quotePhpString(aiFeatureSlug)},
+\t\t\t\t\t)
+\t\t\t\t),
 \t\t\t\tarray( 'status' => 501 )
 \t\t\t);
 \t\t}
@@ -300,14 +511,26 @@ if ( ! function_exists( '${handlerFunctionName}' ) ) {
 \t\t) {
 \t\t\treturn new WP_Error(
 \t\t\t\t'ai_client_unavailable',
-\t\t\t\t'The current WordPress AI Client provider or model does not support this structured-output feature.',
+\t\t\t\t${resolveUnavailableMessageFunctionName}(
+\t\t\t\t\t'The current WordPress AI Client provider or model does not support this structured-output feature.',
+\t\t\t\t\t'text_generation_unsupported',
+\t\t\t\t\tarray(
+\t\t\t\t\t\t'featureSlug' => ${quotePhpString(aiFeatureSlug)},
+\t\t\t\t\t)
+\t\t\t\t),
 \t\t\t\tarray( 'status' => 501 )
 \t\t\t);
 \t\t}
 \t\tif ( ! method_exists( $structured_prompt, 'generate_text_result' ) ) {
 \t\t\treturn new WP_Error(
 \t\t\t\t'ai_client_unavailable',
-\t\t\t\t'The current WordPress AI Client does not expose generate_text_result() after as_json_response().',
+\t\t\t\t${resolveUnavailableMessageFunctionName}(
+\t\t\t\t\t'The current WordPress AI Client does not expose generate_text_result() after as_json_response().',
+\t\t\t\t\t'generate_text_result_missing',
+\t\t\t\t\tarray(
+\t\t\t\t\t\t'featureSlug' => ${quotePhpString(aiFeatureSlug)},
+\t\t\t\t\t)
+\t\t\t\t),
 \t\t\t\tarray( 'status' => 501 )
 \t\t\t);
 \t\t}
@@ -342,7 +565,7 @@ if ( ! function_exists( '${handlerFunctionName}' ) ) {
 \t\t\t);
 \t\t}
 
-\t\t$telemetry = ${buildTelemetryFunctionName}( $result );
+\t\t$telemetry = ${buildTelemetryFunctionName}( $result, $payload, $normalized_result );
 \t\tif ( is_wp_error( $telemetry ) ) {
 \t\t\treturn $telemetry;
 \t\t}

package/dist/runtime/package-versions.d.ts

@@ -24,6 +24,21 @@ export declare const DEFAULT_WORDPRESS_CORE_DATA_VERSION = "^7.44.0";
 export declare const DEFAULT_WORDPRESS_DATA_VERSION = "^9.28.0";
 export declare const DEFAULT_WORDPRESS_DATAVIEWS_VERSION = "^14.1.0";
 export declare const DEFAULT_WP_TYPIA_DATAVIEWS_VERSION = "^0.1.0";
+/**
+ * Resolve a managed package version range from linked workspace packages first,
+ * then installed package manifests, while preserving the shared normalization
+ * and manifest fingerprinting rules used by `getPackageVersions()`.
+ *
+ * @param packageName npm package whose manifest version should be consulted.
+ * @param fallback Canonical range to use when no usable manifest version exists.
+ * @param workspacePackageDirName Optional sibling monorepo package directory name.
+ * @returns A normalized semver range suitable for generated dependency entries.
+ */
+export declare function resolveManagedPackageVersionRange(options: {
+    fallback: string;
+    packageName: string;
+    workspacePackageDirName?: string;
+}): string;
 /**
  * Clears the in-memory cache used by `getPackageVersions()`.
  *