fix(broadcasting): Citation event broadcasting (#927)

Author: sixlive

composer.json

@@ -45,7 +45,7 @@
     "symplify/rule-doc-generator-contracts": "^11.2",
     "phpstan/phpdoc-parser": "^2.0",
     "spatie/laravel-ray": "^1.39",
-    "laravel/mcp": "^0.5.2"
+    "laravel/mcp": "^0.6.0"
   },
   "autoload-dev": {
     "psr-4": {

src/Events/Broadcasting/CitationBroadcast.php

@@ -0,0 +1,7 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Prism\Prism\Events\Broadcasting;
+
+class CitationBroadcast extends StreamEventBroadcast {}

src/Streaming/Adapters/BroadcastAdapter.php

@@ -10,6 +10,7 @@
 use Illuminate\Support\Collection;
 use InvalidArgumentException;
 use Prism\Prism\Events\Broadcasting\ArtifactBroadcast;
+use Prism\Prism\Events\Broadcasting\CitationBroadcast;
 use Prism\Prism\Events\Broadcasting\ErrorBroadcast;
 use Prism\Prism\Events\Broadcasting\ProviderToolEventBroadcast;
 use Prism\Prism\Events\Broadcasting\StepFinishBroadcast;
@@ -26,6 +27,7 @@
 use Prism\Prism\Events\Broadcasting\ToolCallDeltaBroadcast;
 use Prism\Prism\Events\Broadcasting\ToolResultBroadcast;
 use Prism\Prism\Streaming\Events\ArtifactEvent;
+use Prism\Prism\Streaming\Events\CitationEvent;
 use Prism\Prism\Streaming\Events\ErrorEvent;
 use Prism\Prism\Streaming\Events\ProviderToolEvent;
 use Prism\Prism\Streaming\Events\StepFinishEvent;
@@ -86,6 +88,7 @@ protected function broadcastEvent(StreamEvent $event): ShouldBroadcast
             ToolCallDeltaEvent::class => new ToolCallDeltaBroadcast($event, $this->channels),
             ToolResultEvent::class => new ToolResultBroadcast($event, $this->channels),
             ArtifactEvent::class => new ArtifactBroadcast($event, $this->channels),
+            CitationEvent::class => new CitationBroadcast($event, $this->channels),
             ProviderToolEvent::class => new ProviderToolEventBroadcast($event, $this->channels),
             ErrorEvent::class => new ErrorBroadcast($event, $this->channels),
             StepFinishEvent::class => new StepFinishBroadcast($event, $this->channels),

src/Testing/PrismFake.php

@@ -18,6 +18,7 @@
 use Prism\Prism\Images\Request as ImageRequest;
 use Prism\Prism\Images\Response as ImageResponse;
 use Prism\Prism\Moderation\Response as ModerationResponse;
+use Prism\Prism\Prism;
 use Prism\Prism\Providers\Provider;
 use Prism\Prism\Streaming\EventID;
 use Prism\Prism\Streaming\Events\StepFinishEvent;
@@ -153,7 +154,7 @@ public function speechToText(SpeechToTextRequest $request): AudioTextResponse
      *
      * Behavior:
      *  1. Records the incoming {@link TextRequest}
-     *  2. Pulls the next fixture from the list supplied to {@see \Prism\Prism\Prism::fake()}.
+     *  2. Pulls the next fixture from the list supplied to {@see Prism::fake()}.
      *  3. Yields an appropriate stream of events.
      *
      * Supported fixture type:

tests/Streaming/Adapters/BroadcastAdapterTest.php

@@ -5,7 +5,9 @@
 use Illuminate\Broadcasting\Channel;
 use Illuminate\Broadcasting\PrivateChannel;
 use Illuminate\Support\Facades\Event;
+use Prism\Prism\Enums\Citations\CitationSourceType;
 use Prism\Prism\Enums\FinishReason;
+use Prism\Prism\Events\Broadcasting\CitationBroadcast;
 use Prism\Prism\Events\Broadcasting\ErrorBroadcast;
 use Prism\Prism\Events\Broadcasting\ProviderToolEventBroadcast;
 use Prism\Prism\Events\Broadcasting\StreamEndBroadcast;
@@ -20,6 +22,7 @@
 use Prism\Prism\Events\Broadcasting\ToolCallDeltaBroadcast;
 use Prism\Prism\Events\Broadcasting\ToolResultBroadcast;
 use Prism\Prism\Streaming\Adapters\BroadcastAdapter;
+use Prism\Prism\Streaming\Events\CitationEvent;
 use Prism\Prism\Streaming\Events\ErrorEvent;
 use Prism\Prism\Streaming\Events\ProviderToolEvent;
 use Prism\Prism\Streaming\Events\StreamEndEvent;
@@ -34,6 +37,7 @@
 use Prism\Prism\Streaming\Events\ToolCallDeltaEvent;
 use Prism\Prism\Streaming\Events\ToolCallEvent;
 use Prism\Prism\Streaming\Events\ToolResultEvent;
+use Prism\Prism\ValueObjects\Citation;
 use Prism\Prism\ValueObjects\ToolCall;
 use Prism\Prism\ValueObjects\ToolResult;
 use Prism\Prism\ValueObjects\Usage;
@@ -345,6 +349,42 @@ function createBroadcastEventGenerator(array $events): Generator
     });
 });
 
+it('broadcasts citation events correctly', function (): void {
+    $citation = new Citation(
+        sourceType: CitationSourceType::Document,
+        source: 0,
+        sourceText: 'The quick brown fox',
+        sourceTitle: 'Test Document',
+    );
+
+    $event = new CitationEvent(
+        id: 'evt-123',
+        timestamp: 1640995200,
+        citation: $citation,
+        messageId: 'msg-456',
+        blockIndex: 0,
+    );
+    $channel = new Channel('test-channel');
+
+    $adapter = new BroadcastAdapter($channel);
+    ($adapter)(createBroadcastEventGenerator([$event]));
+
+    Event::assertDispatched(CitationBroadcast::class, function ($broadcastEvent) use ($channel): bool {
+        expect($broadcastEvent->broadcastAs())->toBe('citation');
+        expect($broadcastEvent->broadcastOn())->toBe([$channel]);
+
+        $data = $broadcastEvent->broadcastWith();
+        expect($data['id'])->toBe('evt-123');
+        expect($data['message_id'])->toBe('msg-456');
+        expect($data['block_index'])->toBe(0);
+        expect($data['citation']['source_type'])->toBe('document');
+        expect($data['citation']['source_text'])->toBe('The quick brown fox');
+        expect($data['citation']['source_title'])->toBe('Test Document');
+
+        return true;
+    });
+});
+
 it('validates broadcast event structure for multiple event types', function (): void {
     $usage = new Usage(promptTokens: 10, completionTokens: 5);
     $events = [

tests/Tools/LaravelMcpToolTest.php

@@ -64,9 +64,9 @@ public function schema(JsonSchema $schema): array
 
     $result = $tool->handle();
 
-    expect($result)->toContain('"status": "success"')
-        ->and($result)->toContain('"id": 123')
-        ->and($result)->toContain('"name": "Test"');
+    expect($result)->toContain('"status":"success"')
+        ->and($result)->toContain('"id":123')
+        ->and($result)->toContain('"name":"Test"');
 });
 
 it('can handle a tool that returns a ResponseFactory from Response::make()', function (): void {