@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7194.1.ab4fc81f82

package/src/modules/workflows/components/run/RunStatusBadge.tsx

@@ -0,0 +1,112 @@
+'use client'
+
+import * as React from 'react'
+import { Check, Circle, CircleAlert, Pause, Play, SkipForward, Undo2, XCircle } from 'lucide-react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { STATUS_COLORS, type WorkflowStatus, type StepRunStatus } from '../../lib/status-colors'
+
+type BadgeDescriptor = {
+  tone: WorkflowStatus
+  Icon: React.ComponentType<{ className?: string }>
+  fallbackLabel: string
+}
+
+/**
+ * `toWorkflowStatus` is the CANVAS mapping and deliberately collapses anything
+ * it does not know to `not_started`, which would paint a skipped step and a
+ * never-run step identically. A badge carries a label, so it can afford — and
+ * needs — the finer vocabulary.
+ */
+const STEP_STATUS_BADGES: Record<StepRunStatus, BadgeDescriptor> = {
+  completed: { tone: 'completed', Icon: Check, fallbackLabel: 'Completed' },
+  active: { tone: 'in_progress', Icon: Play, fallbackLabel: 'Running' },
+  failed: { tone: 'failed', Icon: XCircle, fallbackLabel: 'Failed' },
+  skipped: { tone: 'pending', Icon: SkipForward, fallbackLabel: 'Skipped' },
+  paused: { tone: 'paused', Icon: Pause, fallbackLabel: 'Waiting' },
+  pending: { tone: 'not_started', Icon: Circle, fallbackLabel: 'Not started' },
+}
+
+const INSTANCE_STATUS_BADGES: Record<string, BadgeDescriptor> = {
+  RUNNING: { tone: 'in_progress', Icon: Play, fallbackLabel: 'Running' },
+  PAUSED: { tone: 'paused', Icon: Pause, fallbackLabel: 'Paused' },
+  WAITING_FOR_ACTIVITIES: { tone: 'paused', Icon: Pause, fallbackLabel: 'Waiting for activities' },
+  FORKED: { tone: 'in_progress', Icon: Play, fallbackLabel: 'Forked' },
+  COMPLETED: { tone: 'completed', Icon: Check, fallbackLabel: 'Completed' },
+  FAILED: { tone: 'failed', Icon: XCircle, fallbackLabel: 'Failed' },
+  CANCELLED: { tone: 'not_started', Icon: SkipForward, fallbackLabel: 'Cancelled' },
+  COMPENSATING: { tone: 'pending', Icon: CircleAlert, fallbackLabel: 'Compensating' },
+  COMPENSATED: { tone: 'pending', Icon: Undo2, fallbackLabel: 'Compensated' },
+}
+
+const UNKNOWN_BADGE: BadgeDescriptor = { tone: 'not_started', Icon: Circle, fallbackLabel: 'Unknown' }
+
+/** The i18n key + English fallback for one step status, shared with the Gantt. */
+export function stepStatusLabelKey(status: StepRunStatus): { key: string; fallback: string } {
+  const descriptor = STEP_STATUS_BADGES[status] ?? UNKNOWN_BADGE
+  return { key: `workflows.instances.run.stepStatus.${status}`, fallback: descriptor.fallbackLabel }
+}
+
+/**
+ * Class-only form, for the mobile overview which takes a class callback rather
+ * than a component. Reads the same descriptor table, so the two surfaces can
+ * never drift apart.
+ */
+export function instanceStatusBadgeClass(status: string): string {
+  const colors = STATUS_COLORS[(INSTANCE_STATUS_BADGES[status] ?? UNKNOWN_BADGE).tone]
+  return `${colors.bg} ${colors.text}`
+}
+
+function Badge({
+  descriptor,
+  label,
+  className,
+}: {
+  descriptor: BadgeDescriptor
+  label: string
+  className: string
+}) {
+  const colors = STATUS_COLORS[descriptor.tone]
+  const { Icon } = descriptor
+  return (
+    <span
+      className={`inline-flex items-center gap-1.5 rounded px-2 py-1 text-xs font-medium ${colors.bg} ${colors.text} ${className}`}
+    >
+      <Icon className={`h-3.5 w-3.5 shrink-0 ${colors.icon}`} aria-hidden="true" />
+      {label}
+    </span>
+  )
+}
+
+/**
+ * Spec §4.6 acceptance criterion — status is never colour-only. Every badge
+ * pairs its DS status token with its own glyph shape AND a text label, so the
+ * same red is never the sole difference between two states.
+ */
+export function RunStatusBadge({ status, className = '' }: { status: StepRunStatus; className?: string }) {
+  const t = useT()
+  const descriptor = STEP_STATUS_BADGES[status] ?? UNKNOWN_BADGE
+  return (
+    <Badge
+      descriptor={descriptor}
+      label={t(`workflows.instances.run.stepStatus.${status}`, descriptor.fallbackLabel)}
+      className={className}
+    />
+  )
+}
+
+/**
+ * Instance-level counterpart. `WorkflowInstance.status` is a wider vocabulary
+ * than the step one (it carries the compensation states), so it gets its own
+ * map rather than being squeezed through the step vocabulary.
+ */
+export function InstanceStatusBadge({ status, className = '' }: { status: string; className?: string }) {
+  const t = useT()
+  const descriptor = INSTANCE_STATUS_BADGES[status] ?? UNKNOWN_BADGE
+  return (
+    <Badge
+      descriptor={descriptor}
+      label={t(`workflows.instances.status.${status}`, descriptor.fallbackLabel)}
+      className={className}
+    />
+  )
+}

package/src/modules/workflows/components/run/RunStepInspector.tsx

@@ -0,0 +1,176 @@
+'use client'
+
+import * as React from 'react'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { JsonDisplay } from '@open-mercato/ui/backend/JsonDisplay'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { RunStatusBadge } from './RunStatusBadge'
+import { formatRunDuration } from '../../lib/run-duration'
+import type { RunStepInstanceInput } from '../../lib/run-execution'
+import { stepInstanceStatusToRunStatus } from '../../lib/run-execution'
+
+export type RunStepInspectorProps = {
+  /** The node the author selected on the painted canvas, `null` when nothing is selected. */
+  stepId: string | null
+  stepLabel?: string | null
+  /**
+   * Every recorded execution of that step, newest last. A step can run more
+   * than once (a loop, a failure route back, a rerun), and collapsing them
+   * would hide exactly the attempt an operator is looking for.
+   */
+  executions: readonly RunStepInstanceInput[]
+  /** Sub-workflow instances this step spawned, if any. */
+  childInstanceIds?: readonly string[]
+  onOpenChildInstance?: (instanceId: string) => void
+  isLoading?: boolean
+}
+
+function ExecutionRecord({
+  execution,
+  attemptLabel,
+}: {
+  execution: RunStepInstanceInput
+  attemptLabel: string | null
+}) {
+  const t = useT()
+  const duration = formatRunDuration(execution.enteredAt, execution.exitedAt, execution.executionTimeMs)
+  const attempts = typeof execution.retryCount === 'number' ? execution.retryCount + 1 : 1
+
+  return (
+    <div className="rounded-lg border border-border bg-card p-4">
+      <div className="flex flex-wrap items-center gap-2">
+        <RunStatusBadge status={stepInstanceStatusToRunStatus(execution.status)} />
+        {attemptLabel ? <span className="text-xs text-muted-foreground">{attemptLabel}</span> : null}
+        {execution.branchInstanceId ? (
+          <span className="text-xs text-muted-foreground">
+            {t('workflows.instances.run.inspector.branch', 'Parallel branch')}
+          </span>
+        ) : null}
+      </div>
+
+      <dl className="mt-3 grid grid-cols-2 gap-3 text-sm md:grid-cols-4">
+        <div>
+          <dt className="text-xs font-medium text-muted-foreground">
+            {t('workflows.instances.run.inspector.startedAt', 'Started')}
+          </dt>
+          <dd className="mt-0.5 text-foreground">
+            {execution.enteredAt ? new Date(execution.enteredAt).toLocaleString() : '-'}
+          </dd>
+        </div>
+        <div>
+          <dt className="text-xs font-medium text-muted-foreground">
+            {t('workflows.instances.run.inspector.endedAt', 'Ended')}
+          </dt>
+          <dd className="mt-0.5 text-foreground">
+            {execution.exitedAt ? new Date(execution.exitedAt).toLocaleString() : '-'}
+          </dd>
+        </div>
+        <div>
+          <dt className="text-xs font-medium text-muted-foreground">
+            {t('workflows.instances.run.inspector.duration', 'Duration')}
+          </dt>
+          <dd className="mt-0.5 text-foreground">{duration ?? '-'}</dd>
+        </div>
+        <div>
+          <dt className="text-xs font-medium text-muted-foreground">
+            {t('workflows.instances.run.inspector.attempts', 'Attempts')}
+          </dt>
+          <dd className="mt-0.5 text-foreground">{attempts}</dd>
+        </div>
+      </dl>
+
+      <div className="mt-4 space-y-3">
+        <JsonDisplay
+          data={execution.inputData ?? null}
+          title={t('workflows.instances.run.inspector.input', 'Input')}
+          maxInitialDepth={1}
+        />
+        <JsonDisplay
+          data={execution.outputData ?? null}
+          title={t('workflows.instances.run.inspector.output', 'Output')}
+          maxInitialDepth={1}
+        />
+        {execution.errorData ? (
+          <JsonDisplay
+            data={execution.errorData}
+            title={t('workflows.instances.run.inspector.error', 'Error')}
+            className="border-status-error-border bg-status-error-bg"
+            maxInitialDepth={1}
+          />
+        ) : null}
+      </div>
+    </div>
+  )
+}
+
+/**
+ * Per-step I/O inspector (spec §8.3): "clicking a node shows its I/O in the
+ * inspector … input, output, duration, attempts — from `StepInstance`".
+ */
+export function RunStepInspector({
+  stepId,
+  stepLabel,
+  executions,
+  childInstanceIds = [],
+  onOpenChildInstance,
+  isLoading = false,
+}: RunStepInspectorProps) {
+  const t = useT()
+
+  if (!stepId) {
+    return (
+      <div className="rounded-lg border border-dashed border-border p-6 text-sm text-muted-foreground">
+        {t('workflows.instances.run.inspector.empty', 'Select a step on the canvas to inspect its input, output and timing.')}
+      </div>
+    )
+  }
+
+  return (
+    <div className="space-y-3">
+      <div className="flex flex-wrap items-baseline gap-2">
+        <h3 className="text-base font-semibold text-foreground">{stepLabel || stepId}</h3>
+        <span className="font-mono text-xs text-muted-foreground">{stepId}</span>
+      </div>
+
+      {childInstanceIds.length > 0 && onOpenChildInstance ? (
+        <div className="flex flex-wrap gap-2">
+          {childInstanceIds.map((childId) => (
+            <Button
+              key={childId}
+              type="button"
+              variant="outline"
+              size="sm"
+              onClick={() => onOpenChildInstance(childId)}
+            >
+              {t('workflows.instances.run.inspector.openSubWorkflow', 'Open sub-workflow')} #{childId.slice(0, 8)}
+            </Button>
+          ))}
+        </div>
+      ) : null}
+
+      {isLoading ? (
+        <p className="text-sm text-muted-foreground">{t('common.loading')}</p>
+      ) : executions.length === 0 ? (
+        <p className="rounded-lg border border-dashed border-border p-6 text-sm text-muted-foreground">
+          {t('workflows.instances.run.inspector.notExecuted', 'This step has not executed in this run.')}
+        </p>
+      ) : (
+        <div className="space-y-3">
+          {executions.map((execution, index) => (
+            <ExecutionRecord
+              key={execution.id ?? `${execution.stepId}-${index}`}
+              execution={execution}
+              attemptLabel={
+                executions.length > 1
+                  ? t('workflows.instances.run.inspector.execution', 'Execution {n}', { n: String(index + 1) })
+                  : null
+              }
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default RunStepInspector

package/src/modules/workflows/components/run/WouldDoReport.tsx

@@ -0,0 +1,93 @@
+'use client'
+
+/**
+ * The "Would do" report (spec section 8.2) — an ordered list of every side
+ * effect a dry run suppressed.
+ *
+ * Severity pairs its DS token with an icon AND an `sr-only` name, per the
+ * section 4.6 rule that status is never colour-only.
+ */
+
+import * as React from 'react'
+import { AlertTriangle, Ban, Bot, CircleCheck, ShieldAlert, UserCheck } from 'lucide-react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { JsonDisplay } from '@open-mercato/ui/backend/JsonDisplay'
+import { Alert, AlertDescription, AlertTitle } from '@open-mercato/ui/primitives/alert'
+import type { WouldDoEntry, WouldDoEntryKind } from '../../lib/dry-run'
+
+export type WouldDoReportPayload = {
+  isDryRun: boolean
+  entries: WouldDoEntry[]
+  stoppedByRefusal: boolean
+}
+
+const KIND_ICON: Record<WouldDoEntryKind, React.ComponentType<{ className?: string }>> = {
+  activity: CircleCheck,
+  refusal: Ban,
+  userTask: UserCheck,
+  businessRule: ShieldAlert,
+}
+
+const SEVERITY_STYLE: Record<string, { dot: string; text: string }> = {
+  error: { dot: 'bg-status-error-icon', text: 'text-status-error-icon' },
+  warning: { dot: 'bg-status-warning-icon', text: 'text-status-warning-icon' },
+  info: { dot: 'bg-status-info-icon', text: 'text-status-info-icon' },
+}
+
+export function WouldDoReport({ report }: { report: WouldDoReportPayload | null }) {
+  const t = useT()
+
+  if (!report || !report.isDryRun) return null
+
+  return (
+    <div className="space-y-3">
+      <div className="space-y-1">
+        <h2 className="text-sm font-semibold">{t('workflows.dryRun.report.title')}</h2>
+        <p className="text-xs text-muted-foreground">{t('workflows.dryRun.report.description')}</p>
+      </div>
+
+      {report.stoppedByRefusal && (
+        <Alert status="warning" icon={<AlertTriangle aria-hidden="true" />}>
+          <AlertTitle>{t('workflows.dryRun.report.stoppedTitle')}</AlertTitle>
+          <AlertDescription>{t('workflows.dryRun.report.stoppedDescription')}</AlertDescription>
+        </Alert>
+      )}
+
+      {report.entries.length === 0 ? (
+        <p className="rounded-lg border bg-card px-3 py-6 text-center text-sm text-muted-foreground">
+          {t('workflows.dryRun.report.empty')}
+        </p>
+      ) : (
+        <ol className="space-y-2">
+          {report.entries.map((entry) => {
+            const Icon = KIND_ICON[entry.kind] ?? Bot
+            const severity = SEVERITY_STYLE[entry.severity] ?? SEVERITY_STYLE.info
+            return (
+              <li key={entry.id} className="rounded-lg border bg-card p-3">
+                <div className="flex items-start gap-2">
+                  <span className={`mt-1 size-2.5 shrink-0 rounded-full ${severity.dot}`} aria-hidden="true" />
+                  <Icon className={`mt-0.5 size-4 shrink-0 ${severity.text}`} aria-hidden="true" />
+                  <div className="min-w-0 flex-1 space-y-1">
+                    <div className="flex flex-wrap items-baseline gap-2">
+                      <span className="sr-only">
+                        {t(`workflows.dryRun.report.severity.${entry.severity}`)}
+                      </span>
+                      <span className="text-sm font-medium">
+                        {t(`workflows.dryRun.report.kind.${entry.kind}`)}
+                      </span>
+                      <span className="font-mono text-xs text-muted-foreground">{entry.subject}</span>
+                      {entry.stepId ? (
+                        <span className="text-overline text-muted-foreground">{entry.stepId}</span>
+                      ) : null}
+                    </div>
+                    <JsonDisplay data={entry.detail} maxInitialDepth={1} />
+                  </div>
+                </div>
+              </li>
+            )
+          })}
+        </ol>
+      )}
+    </div>
+  )
+}

package/src/modules/workflows/components/run/useAgentLabels.ts

@@ -0,0 +1,42 @@
+'use client'
+
+import { useQuery } from '@tanstack/react-query'
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+
+type AgentsResponse = { items?: Array<{ id?: unknown; label?: unknown }> }
+
+const EMPTY_LABELS: ReadonlyMap<string, string> = new Map()
+
+/**
+ * Agent id → author-facing label, for the run views' reason line.
+ *
+ * "Use the agent's label, never its definition key" is an existing rule in this
+ * module, and the label lives in the OPTIONAL `agent_orchestrator` peer's
+ * registry — the same endpoint `AgentSelector` and `AgentInvokeConfigField`
+ * read. When the peer is not installed the route 404s and this stays empty, so
+ * the caller falls back to the id rather than to an invented name.
+ *
+ * `enabled` is the caller's answer to "does this run contain an agent step at
+ * all"; a run without one must not pay for the request.
+ */
+export function useAgentLabels(enabled: boolean): ReadonlyMap<string, string> {
+  const { data } = useQuery({
+    queryKey: ['workflow-agent-labels'],
+    enabled,
+    staleTime: 5 * 60 * 1000,
+    queryFn: async () => {
+      const result = await apiCall<AgentsResponse>('/api/agent_orchestrator/agents', undefined, {
+        fallback: { items: [] },
+      })
+      const labels = new Map<string, string>()
+      for (const item of result.result?.items ?? []) {
+        if (typeof item?.id !== 'string' || item.id.length === 0) continue
+        if (typeof item.label !== 'string' || item.label.length === 0) continue
+        labels.set(item.id, item.label)
+      }
+      return labels as ReadonlyMap<string, string>
+    },
+  })
+
+  return data ?? EMPTY_LABELS
+}

package/src/modules/workflows/components/run/useLastRunOverlay.ts

@@ -0,0 +1,150 @@
+'use client'
+
+import * as React from 'react'
+import { useQuery } from '@tanstack/react-query'
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { useAgentLabels } from './useAgentLabels'
+import {
+  deriveRunExecution,
+  type RunExecution,
+  type RunEventInput,
+  type RunStepInstanceInput,
+} from '../../lib/run-execution'
+
+type InstanceSummary = {
+  id: string
+  workflowId: string
+  status: string
+  currentStepId: string | null
+  startedAt: string
+  completedAt: string | null
+  /** Engine-owned markers; only `attention` is read here. */
+  metadata?: { attention?: unknown } | null
+}
+
+type InstancesResponse = { data: InstanceSummary[] }
+type StepsResponse = { data: RunStepInstanceInput[] }
+type EventsResponse = { data: RunEventInput[] }
+
+export type LastRunOverlay = {
+  instance: InstanceSummary | null
+  execution: RunExecution | null
+  /**
+   * Agent id → label for the reason line. Travels WITH the overlay so the
+   * Studio canvas names an agent exactly the way the run detail page does.
+   */
+  agentLabels: ReadonlyMap<string, string>
+  isLoading: boolean
+  isUnavailable: boolean
+}
+
+const EMPTY_AGENT_LABELS: ReadonlyMap<string, string> = new Map()
+
+const EMPTY_OVERLAY: LastRunOverlay = {
+  instance: null,
+  execution: null,
+  agentLabels: EMPTY_AGENT_LABELS,
+  isLoading: false,
+  isUnavailable: false,
+}
+
+/**
+ * "Show last run" for the Studio canvas (spec §8.3).
+ *
+ * Reads the most recent instance of the definition being edited and derives the
+ * SAME `RunExecution` the run detail page paints from, so the two surfaces can
+ * never disagree about what a run did.
+ *
+ * Nothing here is fetched unless the toggle is on: an author editing a
+ * definition should not pay for three requests they never asked for.
+ */
+export function useLastRunOverlay(options: {
+  workflowId?: string | null
+  enabled: boolean
+}): LastRunOverlay {
+  const { workflowId, enabled } = options
+  const active = enabled && !!workflowId
+
+  const instanceQuery = useQuery({
+    queryKey: ['workflow-last-run', workflowId],
+    enabled: active,
+    queryFn: async () => {
+      const params = new URLSearchParams({ workflowId: workflowId!, limit: '1' })
+      const result = await apiCall<InstancesResponse>(`/api/workflows/instances?${params.toString()}`)
+      if (!result.ok) throw new Error('[internal] Failed to load the last workflow run')
+      return result.result?.data?.[0] ?? null
+    },
+  })
+
+  const instanceId = instanceQuery.data?.id ?? null
+
+  const stepsQuery = useQuery({
+    queryKey: ['workflow-last-run-steps', instanceId],
+    enabled: active && !!instanceId,
+    queryFn: async () => {
+      const result = await apiCall<StepsResponse>(
+        `/api/workflows/instances/${instanceId}/steps?limit=100`
+      )
+      if (!result.ok) throw new Error('[internal] Failed to load the last run step executions')
+      return result.result?.data ?? []
+    },
+  })
+
+  // Events carry the TAKEN PATH — a transition leaves no row of its own, so the
+  // route overlay has no other source.
+  const eventsQuery = useQuery({
+    queryKey: ['workflow-last-run-events', instanceId],
+    enabled: active && !!instanceId,
+    queryFn: async () => {
+      const result = await apiCall<EventsResponse>(
+        `/api/workflows/instances/${instanceId}/events?eventType=TRANSITION_EXECUTED&limit=100`
+      )
+      if (!result.ok) throw new Error('[internal] Failed to load the last run transitions')
+      return result.result?.data ?? []
+    },
+  })
+
+  // The park events (spec Part 2) come from a SECOND, unfiltered page rather
+  // than by widening the query above: the list route's `eventType` filter is a
+  // single equality, and dropping it would let a long run's transitions fall off
+  // the same 100-row page the taken path depends on. Two cheap reads, both only
+  // once the toggle is on.
+  const parkEventsQuery = useQuery({
+    queryKey: ['workflow-last-run-park-events', instanceId],
+    enabled: active && !!instanceId,
+    queryFn: async () => {
+      const result = await apiCall<EventsResponse>(
+        `/api/workflows/instances/${instanceId}/events?limit=100`
+      )
+      if (!result.ok) throw new Error('[internal] Failed to load the last run events')
+      return result.result?.data ?? []
+    },
+  })
+
+  // Only worth a request once there is a run to overlay at all.
+  const agentLabels = useAgentLabels(active && !!instanceId)
+
+  const execution = React.useMemo(() => {
+    if (!active || !instanceQuery.data) return null
+    return deriveRunExecution({
+      events: [...(eventsQuery.data ?? []), ...(parkEventsQuery.data ?? [])],
+      stepInstances: stepsQuery.data ?? [],
+      currentStepId: instanceQuery.data.currentStepId,
+      instanceStatus: instanceQuery.data.status,
+      attention: instanceQuery.data.metadata?.attention,
+    })
+  }, [active, instanceQuery.data, eventsQuery.data, parkEventsQuery.data, stepsQuery.data])
+
+  if (!active) return EMPTY_OVERLAY
+
+  return {
+    instance: instanceQuery.data ?? null,
+    execution,
+    agentLabels,
+    isLoading:
+      instanceQuery.isLoading || stepsQuery.isLoading || eventsQuery.isLoading || parkEventsQuery.isLoading,
+    // A definition that has never run is not an error — the toggle says so
+    // instead of painting an empty overlay that reads like "nothing executed".
+    isUnavailable: !instanceQuery.isLoading && !instanceQuery.data,
+  }
+}

package/src/modules/workflows/components/run/useLiveAgentActions.ts

@@ -0,0 +1,70 @@
+'use client'
+
+import * as React from 'react'
+import { useAppEvent } from '@open-mercato/ui/backend/injection/useAppEvent'
+
+/**
+ * Live agent-action telemetry for the run view (workflows spec Phase 2).
+ *
+ * Subscribes to the `workflows.agent.action` DOM-bridge event the optional
+ * `agent_orchestrator` peer emits per AI-SDK step while an INVOKE_AGENT step
+ * runs, and ACCUMULATES a bounded, append-only list — unlike `useLiveRunUpdates`
+ * (which refetches run state), these are ephemeral telemetry rendered directly.
+ * Nothing is persisted: a reopened finished run shows no history, and a browser
+ * that connects late simply misses earlier actions. Steps + tool calls only —
+ * no token text.
+ */
+export type LiveAgentAction = {
+  key: string
+  kind: 'tool_call' | 'step_finish' | string
+  name?: string
+  stepIndex: number
+  toolCallCount: number
+}
+
+/** Keep the live log bounded — a long agent run must never grow memory unbounded. */
+export const MAX_LIVE_AGENT_ACTIONS = 50
+
+export type UseLiveAgentActionsOptions = {
+  /** Only actions carrying this instance id are kept. */
+  instanceId?: string | null
+  /** Turn the subscription off (e.g. before the instance has loaded). */
+  enabled?: boolean
+}
+
+export function useLiveAgentActions({
+  instanceId,
+  enabled = true,
+}: UseLiveAgentActionsOptions): LiveAgentAction[] {
+  const [actions, setActions] = React.useState<LiveAgentAction[]>([])
+
+  useAppEvent(
+    'workflows.agent.action',
+    (event) => {
+      if (!enabled) return
+      const payload = event.payload
+      if (!payload || typeof payload !== 'object') return
+      const record = payload as Record<string, unknown>
+      if (instanceId) {
+        const payloadInstanceId = record.id ?? record.instanceId
+        if (typeof payloadInstanceId !== 'string' || payloadInstanceId !== instanceId) return
+      }
+      const stepIndex = typeof record.stepIndex === 'number' ? record.stepIndex : 0
+      const toolCallCount = typeof record.toolCallCount === 'number' ? record.toolCallCount : 0
+      const kind = typeof record.kind === 'string' ? record.kind : 'step_finish'
+      const name = typeof record.name === 'string' ? record.name : undefined
+      setActions((prev) => {
+        const next = [
+          ...prev,
+          { key: `${stepIndex}-${prev.length}`, kind, name, stepIndex, toolCallCount },
+        ]
+        return next.length > MAX_LIVE_AGENT_ACTIONS
+          ? next.slice(next.length - MAX_LIVE_AGENT_ACTIONS)
+          : next
+      })
+    },
+    [enabled, instanceId]
+  )
+
+  return actions
+}