refactor: add typed Claude stream event collection

Author: Dariusz Debowczyk

.beads/issues.jsonl

@@ -263,7 +263,7 @@
 {"id":"instructor-php-s8g.1","title":"State change: status → in_progress","description":"Set status to in_progress\n\nReason: Started InferenceExecutionId migration after completing InferenceAttemptId","status":"closed","priority":4,"issue_type":"event","created_at":"2026-02-21T19:28:23.902257+01:00","created_by":"Dariusz Debowczyk","updated_at":"2026-02-21T19:32:09.359861+01:00","closed_at":"2026-02-21T19:32:09.359861+01:00","close_reason":"Housekeeping: close state-change event beads after parent task completion","dependencies":[{"issue_id":"instructor-php-s8g.1","depends_on_id":"instructor-php-s8g","type":"parent-child","created_at":"2026-02-21T19:28:23.902815+01:00","created_by":"Dariusz Debowczyk"}]}
 {"id":"instructor-php-t5y","title":"Introduce InferenceResponseId value object and migrate polyglot response identity","description":"Create InferenceResponseId and migrate inference response identity usage and serialization.","acceptance_criteria":"- Introduce the new XxxId value object as a thin wrapper delegating UUID generation/validation to Cognesy\\Utils\\Uuid.\\n- Refactor the target bounded context to use the typed ID internally (entities, state objects, repositories/stores, serializers).\\n- Do boundary normalization in one place only; avoid scattering XxxId|string across domain internals and store contracts.\\n- Remove temporary normalization helpers made obsolete by full typing.\\n- Update/adjust tests and ensure relevant test suites pass.\\n- Update package docs under ./packages/*/docs and root ./examples to reflect typed IDs and migration usage patterns.","status":"closed","priority":2,"issue_type":"task","owner":"ddebowczyk@guidewire.com","created_at":"2026-02-21T10:34:22.65846+01:00","created_by":"Dariusz Debowczyk","updated_at":"2026-02-21T19:31:02.091732+01:00","closed_at":"2026-02-21T19:31:02.091732+01:00","close_reason":"Completed InferenceResponseId migration with typed response identity, serialization boundary, docs update, and passing polyglot tests","labels":["status:in_progress"]}
 {"id":"instructor-php-t5y.1","title":"State change: status → in_progress","description":"Set status to in_progress\n\nReason: Started InferenceResponseId migration after completing InferenceExecutionId","status":"closed","priority":4,"issue_type":"event","created_at":"2026-02-21T19:30:07.485849+01:00","created_by":"Dariusz Debowczyk","updated_at":"2026-02-21T19:32:19.3989+01:00","closed_at":"2026-02-21T19:32:19.3989+01:00","close_reason":"Housekeeping: close state-change event beads after parent task completion","dependencies":[{"issue_id":"instructor-php-t5y.1","depends_on_id":"instructor-php-t5y","type":"parent-child","created_at":"2026-02-21T19:30:07.486428+01:00","created_by":"Dariusz Debowczyk"}]}
-{"id":"instructor-php-tpq","title":"DecodedObject is too generic - needs semantic structure","description":"DecodedObject is just array\u003cstring,mixed\u003e wrapper with no semantic meaning. Should create typed DTOs for Claude CLI response structure (messages, cost, duration, tool calls, etc.) instead of generic array access. Current design loses type safety benefits.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-02T03:43:14.818957549+01:00","updated_at":"2025-12-02T03:43:14.818957549+01:00"}
+{"id":"instructor-php-tpq","title":"DecodedObject is too generic - needs semantic structure","description":"DecodedObject is just array\u003cstring,mixed\u003e wrapper with no semantic meaning. Should create typed DTOs for Claude CLI response structure (messages, cost, duration, tool calls, etc.) instead of generic array access. Current design loses type safety benefits.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-02T03:43:14.818957549+01:00","updated_at":"2026-02-21T21:04:40.536616+01:00","closed_at":"2026-02-21T21:04:40.536616+01:00","close_reason":"Replaced generic Claude decoded-object usage with semantic typed stream-event collection in ClaudeResponse/ResponseParser and bridge consumption, while retaining decoded raw data for compatibility."}
 {"id":"instructor-php-u3x","title":"Introduce ExecutionId value object and fully migrate execution identity","description":"Create ExecutionId and migrate execution identity across execution state, serialization, and orchestration usage.","acceptance_criteria":"- Introduce the new XxxId value object as a thin wrapper delegating UUID generation/validation to Cognesy\\Utils\\Uuid.\\n- Refactor the target bounded context to use the typed ID internally (entities, state objects, repositories/stores, serializers).\\n- Do boundary normalization in one place only; avoid scattering XxxId|string across domain internals and store contracts.\\n- Remove temporary normalization helpers made obsolete by full typing.\\n- Update/adjust tests and ensure relevant test suites pass.\\n- Update package docs under ./packages/*/docs and root ./examples to reflect typed IDs and migration usage patterns.","status":"closed","priority":2,"issue_type":"task","owner":"ddebowczyk@guidewire.com","created_at":"2026-02-21T10:34:18.881884+01:00","created_by":"Dariusz Debowczyk","updated_at":"2026-02-21T10:44:07.76599+01:00","closed_at":"2026-02-21T10:44:07.76599+01:00","close_reason":"ExecutionId migration completed","labels":["status:in_progress"]}
 {"id":"instructor-php-u3x.1","title":"State change: status → in_progress","description":"Set status to in_progress\n\nReason: Started ExecutionId migration after completing AgentId","status":"closed","priority":4,"issue_type":"event","created_at":"2026-02-21T10:42:03.403783+01:00","created_by":"Dariusz Debowczyk","updated_at":"2026-02-21T19:32:09.343842+01:00","closed_at":"2026-02-21T19:32:09.343842+01:00","close_reason":"Housekeeping: close state-change event beads after parent task completion","dependencies":[{"issue_id":"instructor-php-u3x.1","depends_on_id":"instructor-php-u3x","type":"parent-child","created_at":"2026-02-21T10:42:03.405052+01:00","created_by":"Dariusz Debowczyk"}]}
 {"id":"instructor-php-xsh","title":"Move REFACTORING_PLAN.md to tmp/","description":"Move REFACTORING_PLAN.md from root to tmp/REFACTORING_PLAN.md since it's active WIP documentation, not permanent internal docs.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-11-28T12:26:19.820866135+01:00","updated_at":"2025-11-28T12:40:02.058807122+01:00","closed_at":"2025-11-28T12:40:02.058807122+01:00","dependencies":[{"issue_id":"instructor-php-xsh","depends_on_id":"instructor-php-ypb","type":"parent-child","created_at":"2025-11-28T12:26:37.799098689+01:00","created_by":"daemon","metadata":"{}"}]}

packages/agent-ctrl/src/Bridge/ClaudeCodeBridge.php

@@ -182,9 +182,8 @@ public function executeStreaming(string $prompt, ?StreamHandler $handler): Agent
 
         if ($collectedText === '' && $handler === null) {
             $extractStart = microtime(true);
-            foreach ($response->decoded()->all() as $event) {
+            foreach ($response->events()->all() as $streamEvent) {
                 $eventCount++;
-                $streamEvent = StreamEvent::fromArray($event->data());
                 if ($streamEvent instanceof MessageEvent) {
                     foreach ($streamEvent->message->textContent() as $textContent) {
                         $collectedText .= $textContent->text;

packages/agent-ctrl/src/ClaudeCode/Application/Dto/ClaudeEventCollection.php

@@ -0,0 +1,44 @@
+<?php declare(strict_types=1);
+
+namespace Cognesy\AgentCtrl\ClaudeCode\Application\Dto;
+
+use Cognesy\AgentCtrl\ClaudeCode\Domain\Dto\StreamEvent\StreamEvent;
+
+final readonly class ClaudeEventCollection
+{
+    /** @var list<StreamEvent> */
+    private array $items;
+
+    /**
+     * @param list<StreamEvent> $items
+     */
+    private function __construct(array $items) {
+        $this->items = array_values($items);
+    }
+
+    public static function empty() : self {
+        return new self([]);
+    }
+
+    /**
+     * @param list<StreamEvent> $items
+     */
+    public static function of(array $items) : self {
+        return new self($items);
+    }
+
+    /**
+     * @return list<StreamEvent>
+     */
+    public function all() : array {
+        return $this->items;
+    }
+
+    public function count() : int {
+        return count($this->items);
+    }
+
+    public function isEmpty() : bool {
+        return $this->count() === 0;
+    }
+}

packages/agent-ctrl/src/ClaudeCode/Application/Dto/ClaudeResponse.php

@@ -7,10 +7,15 @@
 
 final readonly class ClaudeResponse
 {
+    private ClaudeEventCollection $events;
+
     public function __construct(
         private ExecResult $result,
         private DecodedObjectCollection $decoded,
-    ) {}
+        ?ClaudeEventCollection $events = null,
+    ) {
+        $this->events = $events ?? ClaudeEventCollection::empty();
+    }
 
     public function result() : ExecResult {
         return $this->result;
@@ -19,4 +24,8 @@ public function result() : ExecResult {
     public function decoded() : DecodedObjectCollection {
         return $this->decoded;
     }
+
+    public function events() : ClaudeEventCollection {
+        return $this->events;
+    }
 }

packages/agent-ctrl/src/ClaudeCode/Application/Parser/ResponseParser.php

@@ -3,6 +3,8 @@
 namespace Cognesy\AgentCtrl\ClaudeCode\Application\Parser;
 
 use Cognesy\AgentCtrl\ClaudeCode\Application\Dto\ClaudeResponse;
+use Cognesy\AgentCtrl\ClaudeCode\Application\Dto\ClaudeEventCollection;
+use Cognesy\AgentCtrl\ClaudeCode\Domain\Dto\StreamEvent\StreamEvent;
 use Cognesy\AgentCtrl\ClaudeCode\Domain\Enum\OutputFormat;
 use Cognesy\AgentCtrl\Common\Collection\DecodedObjectCollection;
 use Cognesy\AgentCtrl\Common\Value\DecodedObject;
@@ -24,12 +26,18 @@ private function fromJson(ExecResult $result) : ClaudeResponse {
             return new ClaudeResponse($result, DecodedObjectCollection::empty());
         }
         $items = [];
+        $events = [];
         foreach ($this->normalizeToList($decoded) as $entry) {
             if (is_array($entry)) {
                 $items[] = new DecodedObject($entry);
+                $events[] = StreamEvent::fromArray($entry);
             }
         }
-        return new ClaudeResponse($result, DecodedObjectCollection::of($items));
+        return new ClaudeResponse(
+            result: $result,
+            decoded: DecodedObjectCollection::of($items),
+            events: ClaudeEventCollection::of($events),
+        );
     }
 
     private function fromStreamJson(ExecResult $result) : ClaudeResponse {
@@ -38,6 +46,7 @@ private function fromStreamJson(ExecResult $result) : ClaudeResponse {
             return new ClaudeResponse($result, DecodedObjectCollection::empty());
         }
         $items = [];
+        $events = [];
         foreach ($lines as $line) {
             $trimmed = trim($line);
             if ($trimmed === '') {
@@ -46,9 +55,14 @@ private function fromStreamJson(ExecResult $result) : ClaudeResponse {
             $decoded = json_decode($trimmed, true);
             if (is_array($decoded)) {
                 $items[] = new DecodedObject($decoded);
+                $events[] = StreamEvent::fromArray($decoded);
             }
         }
-        return new ClaudeResponse($result, DecodedObjectCollection::of($items));
+        return new ClaudeResponse(
+            result: $result,
+            decoded: DecodedObjectCollection::of($items),
+            events: ClaudeEventCollection::of($events),
+        );
     }
 
     /**

packages/agent-ctrl/tests/Unit/ClaudeCode/ClaudeCodeCliResponseParserTest.php

@@ -3,6 +3,7 @@
 declare(strict_types=1);
 
 use Cognesy\AgentCtrl\ClaudeCode\Application\Parser\ResponseParser;
+use Cognesy\AgentCtrl\ClaudeCode\Domain\Dto\StreamEvent\UnknownEvent;
 use Cognesy\AgentCtrl\ClaudeCode\Domain\Enum\OutputFormat;
 use Cognesy\Sandbox\Data\ExecResult;
 
@@ -15,6 +16,8 @@
     expect($response->decoded()->count())->toBe(2);
     $first = $response->decoded()->all()[0]->data();
     expect($first['text'])->toBe('hi');
+    expect($response->events()->count())->toBe(2);
+    expect($response->events()->all()[0])->toBeInstanceOf(UnknownEvent::class);
 });
 
 it('parses stream-json output line by line', function () {
@@ -26,6 +29,8 @@
     expect($response->decoded()->count())->toBe(2);
     $last = $response->decoded()->all()[1]->data();
     expect($last['event'])->toBe('final');
+    expect($response->events()->count())->toBe(2);
+    expect($response->events()->all()[1])->toBeInstanceOf(UnknownEvent::class);
 });
 
 it('returns empty collection on invalid json', function () {
@@ -34,4 +39,5 @@
     $response = (new ResponseParser())->parse($result, OutputFormat::Json);
 
     expect($response->decoded()->isEmpty())->toBeTrue();
+    expect($response->events()->isEmpty())->toBeTrue();
 });