fix: harden Messenger validation and review feedback

[deepshekhardas]

Harden Messenger validation based on review feedback. Improves input validation and error handling across message processing.

[greptile-apps]

Greptile Summary

• Adds and documents Messenger failover behavior across multiple compatible messaging adapters.
• Strengthens adapter and message type validation in the Messenger wrapper.
• Expands tests for fallback behavior, validation failures, single-adapter usage, and request limits.

Confidence Score: 4/5

The changes are mostly well-scoped, but constructor validation still mishandles valid adapter arrays with preserved non-zero keys.

The review is based on the changed Messenger validation code and focused tests; local runtime confirmation was unavailable because the PHP and Composer binaries were missing in the environment.

src/Utopia/Messaging/Messenger.php

T-Rex Logs

What T-Rex did

• T-Rex attempted to verify Normalize adapter keys by running a focused PHP repro script that constructs Messenger with a single valid Adapter at key 1 and also attempted the Composer-based setup path.
• T-Rex executed the messenger failover harness across multiple scenarios and captured before and after logs, revealing varying outcomes for primary and secondary adapters.
• T-Rex ran the messenger validation harness, comparing pre- and post-checkout states to validate the metadata scenarios, with the head revision showing all scenarios passing.

_{Ran code and verified through T-Rex}

_{Reviews (3): Last reviewed commit: "feat: add Messenger class with failover ..." | Re-trigger Greptile}

[greptile-apps]

The catch clause only intercepts \Exception, so any adapter that throws a subclass of \Error (e.g. \TypeError from a bad API response shape, \ValueError, or an unchecked \AssertionError) will propagate immediately and skip every remaining adapter — silently breaking the failover chain that is the entire purpose of this class. Using \Throwable ensures all adapter failures trigger the fallback path.

Suggested change

	} catch (\Exception $e) {
	$errors[] = $adapter->getName()
	.' (adapter '
	.($index + 1)
	.'): '
	.$e->getMessage();
	}
	} catch (\Throwable $e) {
	$errors[] = $adapter->getName()
	.' (adapter '
	.($index + 1)
	.'): '
	.$e->getMessage();
	}

[greptile-apps]

Index-base inconsistency in error messages

The constructor loop emits "element N" using the raw 0-based key (e.g. "element 1" for the second item), while validateAdapters emits "adapter N" using a 1-based offset ($index + 1). A caller who encounters both errors will see different numbering conventions for what is logically the same position in the array. Choosing one scheme (consistently 0-based or consistently 1-based) would make the messages unambiguous.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[greptile-apps]

Want your agent to iterate on Greptile's feedback? Try greploops.

[greptile-apps]

Normalize adapter keys

The constructor accepts any adapter array, but validateAdapters() reads $adapters[0] directly. PHP arrays preserve caller keys, so a valid list with preserved keys, such as the result of filtering adapters or [1 => $adapter], passes the earlier empty() and instanceof checks and then fails with an undefined key/null dereference instead of constructing a single-adapter messenger. Reindex the array before validation, or explicitly reject non-list arrays, so valid adapter lists do not depend on having key 0.