[5.x] Add Laravel AI watcher

[huzaifaarain]

Summary

This pull request adds first-class Telescope monitoring for Laravel AI runs.

It records AI run starts and terminal updates, provider steps, tool invocations, provider failovers, and tool approval checkpoints. The watcher stores safe summaries by default and keeps prompt content, response text, raw provider payloads, tool arguments, and tool results opt-in behind watcher configuration.

Benefit

Applications using Laravel AI can inspect agent activity in Telescope using the same list/detail workflow as other Telescope entry types. This makes it easier to debug model/provider behavior, tool calls, failovers, and approval flows during development.

Compatibility

The integration does not add a hard dependency on laravel/ai. Laravel AI event classes are referenced by string and listeners are only registered when the package is installed.

The watcher remains optional through Telescope's watcher configuration.

Tests

Validated locally with the Laravel AI-compatible stable target:

php8.3 vendor/bin/phpunit tests/Watchers/AiWatcherTest.php tests/Http/RouteTest.php tests/Telescope/TelescopeTest.php --display-deprecations --fail-on-deprecation

Result: 77 tests, 324 assertions.

php8.3 vendor/bin/phpstan analyse src/Watchers/AiWatcher.php src/Http/Controllers/AiController.php --no-progress

Result: no errors.

npm run build

Result: build completed successfully.

[huzaifaarain]

Hi @pushpak1300 , just wanted to flag on the CI failures here — I looked into them and they're not related to this PR. The same 17 errors / 22 failures show up identically on 5.x itself (e.g. the scheduled run and the tests job on #1756's own commit), so it looks like a pre-existing issue on the base branch unrelated to the AI watcher change.

I also double-checked compatibility: the new code sticks to plain PHP 8.0-safe syntax and only touches laravel/ai classes via class_exists() string checks (no hard dependency), so it's a no-op on PHP/Laravel combos where laravel/ai isn't installable and only activates where it is (PHP 8.3+ / Laravel 12+, matching laravel/ai's own requirements).

Is there anything else you'd like me to change or add here, or is this good to move forward as-is?

[huzaifaarain]

Update: found the exact cause — this branch was cut before #1759 ("Test improvements", merged into 5.x a few hours ago) landed, which fixed the test-isolation issue causing those 17 errors / 22 failures. I merged upstream 5.x (including #1759, #1760, #1761) into this branch and confirmed locally: 237/237 tests pass now. Pushed — CI should be green on the next run.

[huzaifaarain]

Hi @taylorotwell, I am really looking forward to your feedback on my PR. This is my first contribution to a Laravel first-party package, so your feedback would be very valuable to me.

If there are any violations or issues, I would appreciate it if you could point them out. I will address them promptly. If any further testing is needed, or if there is anything else I can help with, please let me know.

Thank you so much in advance for reviewing my PR. Regards

[pushpak1300]

Hey @huzaifaarain, I’ll review this shortly. Thanks for all the work you did.