@shipfox/client-workflows 16.0.0 → 18.0.0

package/src/core/run-annotation.ts

@@ -44,6 +44,12 @@ export interface RunAnnotationSummary {
   success: number;
   /** True when the read hit its page budget, so every count is a lower bound. */
   truncated: boolean;
+  /** Optional per-step counts used by the step inspector without loading annotation bodies. */
+  stepCounts?: readonly {
+    stepId: string;
+    attempt: number;
+    total: number;
+  }[];
 }
 
 /** Everything the annotations list needs to route back to the step that emitted an annotation. */

package/src/core/workflow-run.ts

@@ -46,6 +46,10 @@ export {
   STEP_ERROR_REASONS,
 } from './entities/step.js';
 export type {
+  EvaluationTraceEntry,
+  EvaluationTraceLimitEntry,
+  EvaluationTraceValueEntry,
+  StepAttemptDetail,
   StepAttemptDisplayDuration,
   StepGateResult,
 } from './entities/step-attempt.js';

package/src/hooks/api/annotations.test.ts

@@ -0,0 +1,84 @@
+import {
+  workflowRunAnnotationSummaryQueryOptions,
+  workflowRunAnnotationsQueryOptions,
+} from './annotations.js';
+
+const WORKFLOW_RUN_ID = '11111111-1111-4111-8111-111111111111';
+
+describe('annotation query polling', () => {
+  it('polls enabled list and summary queries by default', () => {
+    const summary = workflowRunAnnotationSummaryQueryOptions(WORKFLOW_RUN_ID, 1);
+    const list = workflowRunAnnotationsQueryOptions(WORKFLOW_RUN_ID, 1);
+
+    expect(summary.refetchInterval).toBe(5_000);
+    expect(refetchIntervalForPages(list, 1)).toBe(5_000);
+  });
+
+  it('polls when enabled explicitly for both query builders', () => {
+    const summary = workflowRunAnnotationSummaryQueryOptions(WORKFLOW_RUN_ID, 1, undefined, {
+      polling: true,
+    });
+    const list = workflowRunAnnotationsQueryOptions(WORKFLOW_RUN_ID, 1, undefined, {
+      polling: true,
+    });
+
+    expect(summary.refetchInterval).toBe(5_000);
+    expect(refetchIntervalForPages(list, 1)).toBe(5_000);
+  });
+
+  it('does not poll disabled query builders', () => {
+    const summary = workflowRunAnnotationSummaryQueryOptions(WORKFLOW_RUN_ID, 1, undefined, {
+      enabled: false,
+    });
+    const list = workflowRunAnnotationsQueryOptions(WORKFLOW_RUN_ID, 1, undefined, {
+      enabled: false,
+    });
+
+    expect(summary.refetchInterval).toBe(false);
+    expect(list.refetchInterval).toBe(false);
+  });
+
+  it('stops summary polling when the owning run is terminal', () => {
+    const options = workflowRunAnnotationSummaryQueryOptions(WORKFLOW_RUN_ID, 1, undefined, {
+      polling: false,
+    });
+
+    expect(options.refetchInterval).toBe(false);
+  });
+
+  it('stops annotation list polling when the owning run is terminal', () => {
+    const options = workflowRunAnnotationsQueryOptions(WORKFLOW_RUN_ID, 1, undefined, {
+      polling: false,
+    });
+
+    expect(options.refetchInterval).toBe(false);
+  });
+
+  it('stops annotation list polling after the first page has been loaded', () => {
+    const options = workflowRunAnnotationsQueryOptions(WORKFLOW_RUN_ID, 1);
+
+    expect(refetchIntervalForPages(options, 2)).toBe(false);
+  });
+
+  it('keeps execution-scoped summaries on a distinct reusable query key', () => {
+    const runSummary = workflowRunAnnotationSummaryQueryOptions(WORKFLOW_RUN_ID, 1);
+    const executionSummary = workflowRunAnnotationSummaryQueryOptions(
+      WORKFLOW_RUN_ID,
+      1,
+      '22222222-2222-4222-8222-222222222222',
+    );
+
+    expect(runSummary.queryKey).not.toEqual(executionSummary.queryKey);
+  });
+});
+
+function refetchIntervalForPages(
+  options: ReturnType<typeof workflowRunAnnotationsQueryOptions>,
+  pageCount: number,
+) {
+  if (typeof options.refetchInterval !== 'function') return options.refetchInterval;
+
+  return options.refetchInterval({
+    state: {data: {pages: Array.from({length: pageCount}, () => ({}))}},
+  } as never);
+}

package/src/hooks/api/annotations.ts

@@ -0,0 +1,240 @@
+import {
+  type AnnotationStyleDto,
+  annotationSummaryResponseSchema,
+  readAnnotationsResponseSchema,
+} from '@shipfox/annotations-dto';
+import {checkedApiRequest} from '@shipfox/client-api';
+import {
+  infiniteQueryOptions,
+  queryOptions,
+  useInfiniteQuery,
+  useQuery,
+} from '@tanstack/react-query';
+import type {RunAnnotationSummary} from '#core/run-annotation.js';
+
+const ANNOTATIONS_PAGE_SIZE = 100;
+const ANNOTATIONS_REFRESH_INTERVAL_MS = 5_000;
+
+export interface WorkflowRunAnnotation {
+  id: string;
+  jobId: string;
+  jobExecutionId: string;
+  originStepId: string;
+  originStepAttempt: number;
+  context: string;
+  style: AnnotationStyleDto;
+  sequence: number;
+  body: string;
+}
+
+export interface WorkflowRunAnnotationsPage {
+  annotations: WorkflowRunAnnotation[];
+  hasMore: boolean;
+  nextCursor: string | null;
+}
+
+export const workflowRunAnnotationsQueryKeys = {
+  all: ['workflow-run-annotations'] as const,
+  list: (workflowRunId: string, attempt: number, jobExecutionId?: string) =>
+    [
+      ...workflowRunAnnotationsQueryKeys.all,
+      'list',
+      workflowRunId,
+      attempt,
+      jobExecutionId ?? null,
+    ] as const,
+  summary: (workflowRunId: string, attempt: number, jobExecutionId?: string) =>
+    [
+      ...workflowRunAnnotationsQueryKeys.all,
+      'summary',
+      workflowRunId,
+      attempt,
+      jobExecutionId ?? null,
+    ] as const,
+};
+
+function annotationParams({
+  workflowRunId,
+  attempt,
+  jobExecutionId,
+  cursor,
+}: {
+  workflowRunId: string;
+  attempt: number;
+  jobExecutionId?: string | undefined;
+  cursor?: string | null | undefined;
+}): URLSearchParams {
+  const params = new URLSearchParams({
+    workflow_run_id: workflowRunId,
+    attempt: String(attempt),
+    limit: String(ANNOTATIONS_PAGE_SIZE),
+  });
+  if (jobExecutionId) params.set('job_execution_id', jobExecutionId);
+  if (cursor) params.set('cursor', cursor);
+  return params;
+}
+
+async function getWorkflowRunAnnotationsPage({
+  workflowRunId,
+  attempt,
+  jobExecutionId,
+  cursor,
+  signal,
+}: {
+  workflowRunId: string;
+  attempt: number;
+  jobExecutionId?: string | undefined;
+  cursor?: string | null | undefined;
+  signal?: AbortSignal;
+}): Promise<WorkflowRunAnnotationsPage> {
+  const response = await checkedApiRequest(
+    readAnnotationsResponseSchema,
+    `/annotations?${annotationParams({workflowRunId, attempt, jobExecutionId, cursor}).toString()}`,
+    {signal},
+  );
+  return {
+    annotations: response.annotations.map(toWorkflowRunAnnotation),
+    hasMore: response.has_more,
+    nextCursor: response.next_cursor,
+  };
+}
+
+async function getWorkflowRunAnnotationSummary({
+  workflowRunId,
+  attempt,
+  jobExecutionId,
+  signal,
+}: {
+  workflowRunId: string;
+  attempt: number;
+  jobExecutionId?: string | undefined;
+  signal?: AbortSignal;
+}): Promise<RunAnnotationSummary> {
+  const params = annotationParams({workflowRunId, attempt, jobExecutionId});
+  params.delete('limit');
+  const response = await checkedApiRequest(
+    annotationSummaryResponseSchema,
+    `/annotations/summary?${params.toString()}`,
+    {signal},
+  );
+  return {
+    total: response.total,
+    error: response.error,
+    warning: response.warning,
+    info: response.info,
+    success: response.success,
+    truncated: false,
+    stepCounts: response.step_counts.map((step) => ({
+      stepId: step.origin_step_id,
+      attempt: step.origin_step_attempt,
+      total: step.total,
+    })),
+  };
+}
+
+export function workflowRunAnnotationsQueryOptions(
+  workflowRunId: string | undefined,
+  attempt: number | undefined,
+  jobExecutionId?: string | undefined,
+  options?: {enabled?: boolean | undefined; polling?: boolean | undefined},
+) {
+  const enabled = Boolean(workflowRunId) && attempt !== undefined && (options?.enabled ?? true);
+  const polling = options?.polling ?? true;
+  return infiniteQueryOptions({
+    queryKey:
+      workflowRunId && attempt !== undefined
+        ? workflowRunAnnotationsQueryKeys.list(workflowRunId, attempt, jobExecutionId)
+        : ([...workflowRunAnnotationsQueryKeys.all, 'list'] as const),
+    enabled,
+    initialPageParam: null as string | null,
+    queryFn: ({pageParam, signal}) =>
+      getWorkflowRunAnnotationsPage({
+        workflowRunId: workflowRunId ?? '',
+        attempt: attempt ?? 0,
+        ...(jobExecutionId ? {jobExecutionId} : {}),
+        cursor: pageParam,
+        signal,
+      }),
+    getNextPageParam: (lastPage) => lastPage.nextCursor,
+    staleTime: 2_000,
+    refetchInterval:
+      enabled && polling
+        ? (query) => {
+            const pages = query.state.data?.pages;
+            return pages && pages.length > 1 ? false : ANNOTATIONS_REFRESH_INTERVAL_MS;
+          }
+        : false,
+  });
+}
+
+export function useWorkflowRunAnnotationsQuery(
+  workflowRunId: string | undefined,
+  attempt: number | undefined,
+  jobExecutionId?: string | undefined,
+  options?: {enabled?: boolean | undefined; polling?: boolean | undefined},
+) {
+  return useInfiniteQuery(
+    workflowRunAnnotationsQueryOptions(workflowRunId, attempt, jobExecutionId, options),
+  );
+}
+
+export function workflowRunAnnotationSummaryQueryOptions(
+  workflowRunId: string | undefined,
+  attempt: number | undefined,
+  jobExecutionId?: string | undefined,
+  options?: {enabled?: boolean | undefined; polling?: boolean | undefined},
+) {
+  const enabled = Boolean(workflowRunId) && attempt !== undefined && (options?.enabled ?? true);
+  const polling = options?.polling ?? true;
+  return queryOptions({
+    queryKey:
+      workflowRunId && attempt !== undefined
+        ? workflowRunAnnotationsQueryKeys.summary(workflowRunId, attempt, jobExecutionId)
+        : ([...workflowRunAnnotationsQueryKeys.all, 'summary'] as const),
+    enabled,
+    queryFn: ({signal}) =>
+      getWorkflowRunAnnotationSummary({
+        workflowRunId: workflowRunId ?? '',
+        attempt: attempt ?? 0,
+        ...(jobExecutionId ? {jobExecutionId} : {}),
+        signal,
+      }),
+    staleTime: 2_000,
+    refetchInterval: enabled && polling ? ANNOTATIONS_REFRESH_INTERVAL_MS : false,
+  });
+}
+
+export function useWorkflowRunAnnotationSummaryQuery(
+  workflowRunId: string | undefined,
+  attempt: number | undefined,
+  jobExecutionId?: string | undefined,
+  options?: {enabled?: boolean | undefined; polling?: boolean | undefined},
+) {
+  return useQuery(
+    workflowRunAnnotationSummaryQueryOptions(workflowRunId, attempt, jobExecutionId, options),
+  );
+}
+
+export function flattenWorkflowRunAnnotations(
+  data: {pages: readonly WorkflowRunAnnotationsPage[]} | undefined,
+): WorkflowRunAnnotation[] {
+  return data?.pages.flatMap((page) => page.annotations) ?? [];
+}
+
+function toWorkflowRunAnnotation(
+  annotation: Awaited<
+    ReturnType<typeof readAnnotationsResponseSchema.parse>
+  >['annotations'][number],
+): WorkflowRunAnnotation {
+  return {
+    id: annotation.id,
+    jobId: annotation.job_id,
+    jobExecutionId: annotation.job_execution_id,
+    originStepId: annotation.origin_step_id,
+    originStepAttempt: annotation.origin_step_attempt,
+    context: annotation.context,
+    style: annotation.style,
+    sequence: annotation.sequence,
+    body: annotation.body,
+  };
+}

package/src/hooks/api/step-attempt-detail.ts

@@ -0,0 +1,67 @@
+import {stepAttemptDetailResponseSchema} from '@shipfox/api-workflows-dto';
+import {checkedApiRequest} from '@shipfox/client-api';
+import {queryOptions, type UseQueryOptions, useQuery} from '@tanstack/react-query';
+import type {StepAttemptDetail} from '#core/workflow-run.js';
+import {toStepAttemptDetail} from './workflow-run-mapper.js';
+
+export const stepAttemptDetailQueryKeys = {
+  all: ['workflow-step-attempt-details'] as const,
+  detail: (stepId: string, attempt: number) =>
+    [...stepAttemptDetailQueryKeys.all, stepId, attempt] as const,
+};
+
+type StepAttemptDetailQueryKey =
+  | ReturnType<typeof stepAttemptDetailQueryKeys.detail>
+  | readonly ['workflow-step-attempt-details'];
+
+type StepAttemptDetailQueryOptions = UseQueryOptions<
+  StepAttemptDetail,
+  Error,
+  StepAttemptDetail,
+  StepAttemptDetailQueryKey
+>;
+
+async function getStepAttemptDetail({
+  stepId,
+  attempt,
+  signal,
+}: {
+  stepId: string;
+  attempt: number;
+  signal?: AbortSignal;
+}): Promise<StepAttemptDetail> {
+  const response = await checkedApiRequest(
+    stepAttemptDetailResponseSchema,
+    `/workflows/runs/steps/${stepId}/attempts/${attempt}`,
+    {signal},
+  );
+  return toStepAttemptDetail(response);
+}
+
+export function stepAttemptDetailQueryOptions(
+  stepId: string | undefined,
+  attempt: number | undefined,
+): StepAttemptDetailQueryOptions {
+  return queryOptions({
+    queryKey:
+      stepId && attempt !== undefined
+        ? stepAttemptDetailQueryKeys.detail(stepId, attempt)
+        : ([...stepAttemptDetailQueryKeys.all] as const),
+    enabled: Boolean(stepId) && attempt !== undefined,
+    queryFn: ({signal}) =>
+      getStepAttemptDetail({stepId: stepId ?? '', attempt: attempt ?? 0, signal}),
+    staleTime: Infinity,
+  });
+}
+
+export function useStepAttemptDetailQuery(
+  stepId: string | undefined,
+  attempt: number | undefined,
+  options?: {enabled?: boolean | undefined},
+) {
+  return useQuery({
+    ...stepAttemptDetailQueryOptions(stepId, attempt),
+    ...options,
+    enabled: Boolean(stepId) && attempt !== undefined && (options?.enabled ?? true),
+  });
+}

package/src/hooks/api/workflow-run-mapper.ts

@@ -1,5 +1,7 @@
 import type {
+  EvaluationTraceDto,
   JobListeningDto,
+  StepAttemptDetailResponseDto,
   StepAttemptDto,
   StepGateResultDto,
   WorkflowExecutionEventDto,
@@ -13,6 +15,7 @@ import type {
   WorkflowRunStepDetailDto,
 } from '@shipfox/api-workflows-dto';
 import {
+  type EvaluationTraceEntry,
   Job,
   JobExecution,
   type JobListening,
@@ -139,6 +142,10 @@ export function toJob(dto: WorkflowRunJobDetailDto): Job {
     status: dto.status,
     statusReason: dto.status_reason,
     carriedOver: dto.carried_over,
+    outputs: dto.outputs ?? null,
+    success: dto.success ?? null,
+    runner: dto.runner ?? null,
+    evaluationTrace: toEvaluationTrace(dto.evaluation_trace),
     listening: dto.listening ? toJobListening(dto.listening) : null,
     listenerStatus: dto.listener_status,
     resolutionReason: dto.resolution_reason,
@@ -158,11 +165,15 @@ export function toJobExecution(dto: WorkflowRunJobExecutionDetailDto): JobExecut
     name: dto.name,
     status: dto.status,
     statusReason: dto.status_reason,
+    statusReasonMessage: dto.status_reason_message ?? null,
+    runner: dto.runner ?? null,
+    outputs: dto.outputs ?? null,
     triggerEvents: (dto.trigger_events ?? []).map(toWorkflowExecutionEvent),
     queuedAt: dto.queued_at ?? null,
     startedAt: dto.started_at ?? null,
     finishedAt: dto.finished_at ?? null,
     timedOutAt: dto.timed_out_at ?? null,
+    evaluationTrace: toEvaluationTrace(dto.evaluation_trace),
     createdAt: dto.created_at,
     updatedAt: dto.updated_at,
     steps: dto.steps.map(toStep),
@@ -179,8 +190,10 @@ export function toStep(dto: WorkflowRunStepDetailDto): Step {
       ? {startLine: dto.source_location.start_line, endLine: dto.source_location.end_line}
       : null,
     status: dto.status,
+    statusReason: dto.status_reason,
     type: dto.type,
     config: dto.config,
+    evaluationTrace: toEvaluationTrace(dto.evaluation_trace),
     agentConfig: toAgentStepConfig(dto),
     error: dto.error
       ? {
@@ -210,6 +223,8 @@ export function toStepAttempt(dto: StepAttemptDto, jobExecutionId: string): Step
     status: dto.status,
     exitCode: dto.exit_code ?? null,
     output: dto.output ?? null,
+    outputs: dto.outputs ?? dto.output ?? null,
+    response: dto.response ?? null,
     error: dto.error ?? null,
     gateResult: toStepGateResult(dto.gate_result),
     restartFeedback: dto.restart_feedback ?? null,
@@ -218,6 +233,16 @@ export function toStepAttempt(dto: StepAttemptDto, jobExecutionId: string): Step
   });
 }
 
+export function toStepAttemptDetail(dto: StepAttemptDetailResponseDto) {
+  return {
+    stepId: dto.step_id,
+    attempt: dto.attempt,
+    authoredConfig: dto.authored_config,
+    config: dto.config,
+    evaluationTrace: toEvaluationTrace(dto.evaluation_trace),
+  };
+}
+
 function toJobListening(dto: JobListeningDto): JobListening {
   return {
     on: dto.on,
@@ -259,6 +284,28 @@ function toStepGateResult(dto: StepGateResultDto): StepGateResult {
   return dto;
 }
 
+function toEvaluationTrace(trace: EvaluationTraceDto | null): EvaluationTraceEntry[] | null {
+  return (
+    trace?.map((entry) =>
+      'dropped' in entry
+        ? entry
+        : {
+            expression: entry.expression,
+            roots: entry.roots,
+            fillTarget: entry.fill_target,
+            evaluatedAt: entry.evaluated_at,
+            field: entry.field,
+            ...(entry.value === undefined ? {} : {value: entry.value}),
+            ...(entry.truncated === undefined ? {} : {truncated: entry.truncated}),
+            ...(entry.expr_truncated === undefined ? {} : {exprTruncated: entry.expr_truncated}),
+            ...(entry.reference === undefined ? {} : {reference: entry.reference}),
+            ...(entry.degraded === undefined ? {} : {degraded: entry.degraded}),
+            ...(entry.env_key === undefined ? {} : {envKey: entry.env_key}),
+          },
+    ) ?? null
+  );
+}
+
 function toAgentStepConfig(dto: WorkflowRunStepDetailDto): Step['agentConfig'] {
   if (dto.type !== 'agent') return null;
   return {

package/src/hooks/api/workflow-runs.test.tsx

@@ -1,3 +1,4 @@
+import type {StepAttemptDetailResponseDto} from '@shipfox/api-workflows-dto';
 import {configureApiClient} from '@shipfox/client-api';
 import {type InfiniteData, QueryClient, QueryClientProvider} from '@tanstack/react-query';
 import {act, cleanup, renderHook, waitFor} from '@testing-library/react';
@@ -11,7 +12,8 @@ import {
   workflowRunDto,
   workflowRunListResponseDto,
 } from '#test/fixtures/workflow-run.js';
-import {toWorkflowRun, toWorkflowRunListPage} from './workflow-run-mapper.js';
+import {useStepAttemptDetailQuery} from './step-attempt-detail.js';
+import {toStepAttemptDetail, toWorkflowRun, toWorkflowRunListPage} from './workflow-run-mapper.js';
 import {
   fireManualWorkflow,
   useCancelWorkflowRunMutation,
@@ -133,6 +135,64 @@ describe('workflow run API hooks', () => {
     expect(cached).toHaveProperty('triggerSource', 'manual');
   });
 
+  test('maps lazy step attempt details to authored and resolved troubleshooting data', () => {
+    const dto: StepAttemptDetailResponseDto = {
+      step_id: '88888888-8888-4888-8888-888888888888',
+      attempt: 2,
+      authored_config: {run: 'echo $' + '{{ inputs.message }}'},
+      config: {run: 'echo hello'},
+      evaluation_trace: [
+        {
+          expression: 'inputs.message',
+          roots: ['inputs.message'],
+          fill_target: 'run',
+          evaluated_at: '2026-08-05T12:00:00.000Z',
+          field: 'run',
+          value: 'hello',
+          degraded: false,
+        },
+      ],
+    };
+
+    expect(toStepAttemptDetail(dto)).toEqual({
+      stepId: dto.step_id,
+      attempt: 2,
+      authoredConfig: dto.authored_config,
+      config: dto.config,
+      evaluationTrace: [
+        {
+          expression: 'inputs.message',
+          roots: ['inputs.message'],
+          fillTarget: 'run',
+          evaluatedAt: '2026-08-05T12:00:00.000Z',
+          field: 'run',
+          value: 'hello',
+          degraded: false,
+        },
+      ],
+    });
+  });
+
+  test('does not fetch step attempt details while the inspector is closed', async () => {
+    const fetchImpl = vi.fn(async () =>
+      jsonResponse({
+        step_id: '88888888-8888-4888-8888-888888888888',
+        attempt: 1,
+        authored_config: null,
+        config: {},
+        evaluation_trace: null,
+      }),
+    );
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+
+    renderWithQueryClient(() =>
+      useStepAttemptDetailQuery('88888888-8888-4888-8888-888888888888', 1, {enabled: false}),
+    );
+
+    await Promise.resolve();
+    expect(fetchImpl).not.toHaveBeenCalled();
+  });
+
   test('rejects malformed detail responses before they reach the query cache', async () => {
     const fetchImpl = vi.fn(async () => jsonResponse({id: RUN_ID, trigger_source: 'manual'}));
     configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});