Expose sanitized command principal context for durable operator actions.

Expose command principal context

Author: durable-workflow-ops

src/V2/CommandContext.php

@@ -128,6 +128,17 @@ public function withIntake(string $mode, string $groupId): self
         ]);
     }
 
+    public function withPrincipal(string $type, string $id, ?string $label = null): self
+    {
+        return $this->with([
+            'principal' => array_filter([
+                'type' => $type,
+                'id' => $id,
+                'label' => $label,
+            ], static fn (mixed $value): bool => is_string($value) && trim($value) !== ''),
+        ]);
+    }
+
     /**
      * @return array<string, mixed>
      */

src/V2/Models/WorkflowCommand.php

@@ -210,6 +210,7 @@ public function publicContext(): array
     {
         $workflow = $this->commandContext()['workflow'] ?? null;
         $intake = $this->commandContext()['intake'] ?? null;
+        $principal = $this->commandContext()['principal'] ?? null;
 
         $publicWorkflow = is_array($workflow)
             ? array_filter([
@@ -239,12 +240,54 @@ public function publicContext(): array
             ], static fn (mixed $value): bool => $value !== null && $value !== '')
             : [];
 
+        $publicPrincipal = is_array($principal)
+            ? array_filter([
+                'type' => is_string($principal['type'] ?? null)
+                    ? $principal['type']
+                    : null,
+                'id' => is_string($principal['id'] ?? null)
+                    ? $principal['id']
+                    : null,
+                'label' => is_string($principal['label'] ?? null)
+                    ? $principal['label']
+                    : null,
+            ], static fn (mixed $value): bool => $value !== null && $value !== '')
+            : [];
+
         return array_filter([
             'workflow' => $publicWorkflow === [] ? null : $publicWorkflow,
             'intake' => $publicIntake === [] ? null : $publicIntake,
+            'principal' => $publicPrincipal === [] ? null : $publicPrincipal,
         ], static fn (mixed $value): bool => $value !== null);
     }
 
+    public function principalType(): ?string
+    {
+        $principal = $this->commandContext()['principal'] ?? null;
+
+        return is_array($principal) && is_string($principal['type'] ?? null)
+            ? $principal['type']
+            : null;
+    }
+
+    public function principalId(): ?string
+    {
+        $principal = $this->commandContext()['principal'] ?? null;
+
+        return is_array($principal) && is_string($principal['id'] ?? null)
+            ? $principal['id']
+            : null;
+    }
+
+    public function principalLabel(): ?string
+    {
+        $principal = $this->commandContext()['principal'] ?? null;
+
+        return is_array($principal) && is_string($principal['label'] ?? null)
+            ? $principal['label']
+            : null;
+    }
+
     public function callerLabel(): ?string
     {
         $caller = $this->commandContext()['caller'] ?? null;

src/V2/Models/WorkflowHistoryEvent.php

@@ -148,6 +148,9 @@ private static function commandSnapshot(WorkflowCommand $command): array
             'source' => $command->source,
             'context' => $publicContext === [] ? null : $publicContext,
             'caller_label' => $command->callerLabel(),
+            'principal_type' => $command->principalType(),
+            'principal_id' => $command->principalId(),
+            'principal_label' => $command->principalLabel(),
             'auth_status' => $command->authStatus(),
             'auth_method' => $command->authMethod(),
             'request_method' => $command->requestMethod(),

src/V2/Support/HistoryExport.php

@@ -1020,6 +1020,9 @@ private static function command(WorkflowCommand $command): array
             'source' => $command->source,
             'context' => $command->publicContext(),
             'caller_label' => $command->callerLabel(),
+            'principal_type' => $command->principalType(),
+            'principal_id' => $command->principalId(),
+            'principal_label' => $command->principalLabel(),
             'auth_status' => $command->authStatus(),
             'auth_method' => $command->authMethod(),
             'request_method' => $command->requestMethod(),

src/V2/Support/HistoryTimeline.php

@@ -575,6 +575,9 @@ private static function commandMetadata(
                 $snapshot['context'] ?? null
             ) ?? ($publicContext === [] ? null : $publicContext),
             'caller_label' => self::stringValue($snapshot['caller_label'] ?? null) ?? $command?->callerLabel(),
+            'principal_type' => self::stringValue($snapshot['principal_type'] ?? null) ?? $command?->principalType(),
+            'principal_id' => self::stringValue($snapshot['principal_id'] ?? null) ?? $command?->principalId(),
+            'principal_label' => self::stringValue($snapshot['principal_label'] ?? null) ?? $command?->principalLabel(),
             'auth_status' => self::stringValue($snapshot['auth_status'] ?? null) ?? $command?->authStatus(),
             'auth_method' => self::stringValue($snapshot['auth_method'] ?? null) ?? $command?->authMethod(),
             'request_method' => self::stringValue($snapshot['request_method'] ?? null) ?? $command?->requestMethod(),

src/V2/Support/RunDetailView.php

@@ -299,6 +299,9 @@ public static function forRun(WorkflowRun $run, ?int $timelineLimit = null): arr
                         'source' => $command->source,
                         'context' => $command->publicContext(),
                         'caller_label' => $command->callerLabel(),
+                        'principal_type' => $command->principalType(),
+                        'principal_id' => $command->principalId(),
+                        'principal_label' => $command->principalLabel(),
                         'auth_status' => $command->authStatus(),
                         'auth_method' => $command->authMethod(),
                         'request_method' => $command->requestMethod(),

tests/Feature/V2/V2RunDetailViewTest.php

@@ -2229,6 +2229,11 @@ public function testRunDetailViewOmitsRawRequestContextForWebhookCommands(): voi
                     'status' => 'authorized',
                     'method' => 'token',
                 ],
+                'principal' => [
+                    'type' => 'user',
+                    'id' => '42',
+                    'label' => 'Taylor Otwell',
+                ],
                 'request' => [
                     'method' => 'POST',
                     'path' => '/webhooks/instances/detail-command-context/signals/name-provided',
@@ -2260,8 +2265,17 @@ public function testRunDetailViewOmitsRawRequestContextForWebhookCommands(): voi
         $detail = RunDetailView::forRun($run->fresh(['summary']));
 
         $this->assertCount(1, $detail['commands']);
-        $this->assertSame([], $detail['commands'][0]['context']);
+        $this->assertSame([
+            'principal' => [
+                'type' => 'user',
+                'id' => '42',
+                'label' => 'Taylor Otwell',
+            ],
+        ], $detail['commands'][0]['context']);
         $this->assertSame('Webhook', $detail['commands'][0]['caller_label']);
+        $this->assertSame('user', $detail['commands'][0]['principal_type']);
+        $this->assertSame('42', $detail['commands'][0]['principal_id']);
+        $this->assertSame('Taylor Otwell', $detail['commands'][0]['principal_label']);
         $this->assertSame('authorized', $detail['commands'][0]['auth_status']);
         $this->assertSame('token', $detail['commands'][0]['auth_method']);
         $this->assertSame('POST', $detail['commands'][0]['request_method']);