AI Client: support checks return the prompt builder instead of false when the wrapped builder throws

[bejignesh]

WP_AI_Client_Prompt_Builder::__call() catches an exception from the wrapped SDK builder, stores it as the error state, and then only special cases the generating methods:

try {
        $callable = $this->get_builder_callable( $name );
        $result   = $callable( ...$arguments );
        ...
} catch ( Exception $e ) {
        $this->error = $this->exception_to_wp_error( $e );

        if ( self::is_generating_method( $name ) ) {
                return $this->error;
        }
        return $this;
}

is_supported() and the seven is_supported_for_*() methods are not generating methods, so they fall through to the fluent return and hand back the WP_AI_Client_Prompt_Builder instance. That object is truthy, so a support check that failed reads as a success:

if ( wp_ai_client_prompt( 'Write a haiku' )->is_supported() ) {
        // Runs even though the support check could not be completed.
}

The class handles this correctly everywhere else. The error state guard at the top of __call() returns false for support checks, and so does the prevented prompt path. Only an exception raised during the support check itself takes the wrong branch.

Steps to reproduce

ModalityEnum::document() is a documented factory on the bundled client, but PromptBuilder::inferCapabilityFromOutputModalities() has no branch for it and throws a RuntimeException in its else. That call sits outside the try block isSupported() uses to swallow InvalidArgumentException, so it reaches the WordPress wrapper.

$result = wp_ai_client_prompt( 'Test text' )
        ->as_output_modalities( ModalityEnum::document() )
        ->is_supported();

var_dump( $result ); // object(WP_AI_Client_Prompt_Builder), expected bool(false)

Any other throw from the wrapped builder during a support check does the same thing. The document modality is just the shortest path to one.

Expected

Support check methods always return a bool. That is what the @method annotations on the class say, and what test_boolean_methods_return_boolean() already asserts ("is_supported_for_text_generation should not return the decorator").

Patch

Return false from support check methods in the catch block, matching what they already return when the builder was in an error state beforehand. The error is still stored, so a later generating call still returns the WP_Error.

Note

This is not the same as #65505. That ticket is about catch ( Exception ) missing Error, and the patch there widens the catch to Throwable while leaving the return logic as is, so this behaviour survives it. The two fixes are independent and touch different lines.

WP_AI_Client_Prompt_Builder::__call() catches an exception from the wrapped SDK builder, stores it as the error state, and then only special cases the generating methods:

} catch ( Exception $e ) {
        $this->error = $this->exception_to_wp_error( $e );

        if ( self::is_generating_method( $name ) ) {
                return $this->error;
        }
        return $this;
}

is_supported() and the seven is_supported_for_*() methods are not generating methods, so they fall through to the fluent return and give back the builder instance. It is truthy, so a support check that failed reads as a success:

if ( wp_ai_client_prompt( 'Write a haiku' )->is_supported() ) {
        // Runs even though the support check could not be completed.
}

Everywhere else in the class this is handled. The error state guard at the top of __call() returns false for support checks, and so does the prevented prompt path. Only an exception raised during the support check itself takes the wrong branch.

## Reproducing it

ModalityEnum::document() is a documented factory, but PromptBuilder::inferCapabilityFromOutputModalities() has no branch for it and throws a RuntimeException in its else. That call is outside the try block isSupported() uses to swallow InvalidArgumentException, so it reaches the wrapper.

$result = wp_ai_client_prompt( 'Test text' )
        ->as_output_modalities( ModalityEnum::document() )
        ->is_supported();

var_dump( $result ); // object(WP_AI_Client_Prompt_Builder), expected bool(false)

Any throw from the wrapped builder during a support check behaves the same way. The document modality is just the shortest route to one.

## Fix

Return false for support check methods from the catch block, so they match what they already return when the builder was in an error state beforehand. The error is still stored, so a later generating call still gets the WP_Error, and the test covers that.

## Not a duplicate of #65505

#65505 is about the catch missing Error. Its patch widens catch ( Exception ) to catch ( Throwable ) and leaves the return logic untouched, so a support check still comes back as the builder after it lands. The two changes are independent and touch different lines.

## Testing

test_support_check_methods_return_false_when_builder_throws() fails on trunk with:

Failed asserting that WP_AI_Client_Prompt_Builder Object (... 'error' => WP_Error ...
  'Output modality "document" is not yet supported.') is of type "bool".

and passes with the patch. The full ai-client group is green, 258 tests. phpcs passes on both changed files.

## Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5
Used for: Reading through the AI client for places where the code disagrees with its own documented behaviour, which is how this turned up, and drafting this description. I confirmed the throw path in the bundled client myself, wrote and ran the test, checked it fails without the patch, ran phpcs, and I take responsibility for the change.

All three applied in 69fc18c.

On the first one, bool|WP_Error was never reachable, including before this patch. Every support check path returns a bool: the error state guard and the prevented prompt branch both return false, the success path returns what the wrapped builder returns, and the catch block returned $this before this change and returns false after it. Nothing in src/ calls is_supported() outside the class, so the annotation was wrong without anything depending on it.

The __call() docblock now reads "returns a WP_Error when a terminate method is called, or false when a support check method is called", and the class docblock notes that support checks return false rather than the error state instance.

phpcs and phpstan are clean and the ai-client group passes at 266 tests.

[gziolo]

In 63298:

Return false from WP AI client support checks when the wrapped builder throws

WP_AI_Client_Prompt_Builder::__call() stored a caught exception as the error
state, but only special-cased generating methods before falling through to the
fluent return. The eight support check methods therefore handed back the builder instance, which is truthy, so a failed support check read as a success.

Return false from support check methods in the catch block, matching what
they already return when the builder is in a pre-existing error state or when
the prompt is prevented by a filter. The error is still recorded, so a later
generating call still receives the WP_Error.

Props bejignesh, irozum, gziolo.
Fixes #65781.