@shipfox/api-workflows-dto 12.3.0 → 12.6.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-workflows-dto",
   "license": "MIT",
-  "version": "12.3.0",
+  "version": "12.6.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",

package/src/events.test.ts

@@ -139,6 +139,45 @@ describe('workflowsJobTerminatedSchema', () => {
     expect(result).toEqual(input);
   });
 
+  it('accepts a string status reason message', () => {
+    const input = {
+      ...validJobTerminated,
+      status: 'failed',
+      statusReason: 'output_too_large',
+      statusReasonMessage: 'Job output exceeded the configured size limit.',
+    };
+
+    const result = workflowsJobTerminatedSchema.parse(input);
+
+    expect(result).toEqual(input);
+  });
+
+  it('accepts a null status reason message', () => {
+    const input = {
+      ...validJobTerminated,
+      status: 'failed',
+      statusReason: 'unknown',
+      statusReasonMessage: null,
+    };
+
+    const result = workflowsJobTerminatedSchema.parse(input);
+
+    expect(result).toEqual(input);
+  });
+
+  it('rejects a non-string status reason message', () => {
+    const input = {
+      ...validJobTerminated,
+      status: 'failed',
+      statusReason: 'output_too_large',
+      statusReasonMessage: 413,
+    };
+
+    const parse = () => workflowsJobTerminatedSchema.parse(input);
+
+    expect(parse).toThrow();
+  });
+
   it('strips unknown keys (tolerant of forward-compatible producer additions)', () => {
     const input = {...validJobTerminated, addedLater: 'ignored'};
 

package/src/events.ts

@@ -147,6 +147,7 @@ export const workflowsJobTerminatedSchema = z.object({
   workflowRunAttemptId: nonEmptyStringSchema,
   status: jobTerminalStatusSchema,
   statusReason: jobStatusReasonSchema.nullable(),
+  statusReasonMessage: z.string().nullable().optional(),
 });
 export type WorkflowsJobTerminatedEventDto = z.infer<typeof workflowsJobTerminatedSchema>;
 

package/src/index.ts

@@ -26,6 +26,7 @@ export {
   type JobStatusDto,
   type JobStatusReasonDto,
   jobDtoSchema,
+  jobExecutionStatusSchema,
   jobListeningBatchSchema,
   jobListeningSchema,
   jobModeSchema,
@@ -95,6 +96,7 @@ export {
   workflowRunDetailResponseSchema,
   workflowRunDtoSchema,
   workflowRunJobDetailDtoSchema,
+  workflowRunJobDisplayStatusCountDtoSchema,
   workflowRunJobExecutionDetailDtoSchema,
   workflowRunJobStatusCountDtoSchema,
   workflowRunJobSummaryDtoSchema,
@@ -109,6 +111,7 @@ export {
 export {type StepSourceLocationDto, stepSourceLocationSchema} from '#schemas/step.js';
 export {
   WORKFLOW_RUN_JOB_PREVIEW_LIMIT,
+  type WorkflowRunJobDisplayStatusCountDto,
   type WorkflowRunJobStatusCountDto,
   type WorkflowRunJobSummaryDto,
   type WorkflowRunListItemDto,

package/src/schemas/index.ts

@@ -81,6 +81,7 @@ export {
   stepStatusReasonSchema,
 } from './step.js';
 export {
+  jobExecutionStatusSchema,
   type RerunWorkflowRunBodyDto,
   rerunWorkflowRunBodySchema,
   WORKFLOW_RUN_JOB_PREVIEW_LIMIT,
@@ -89,6 +90,7 @@ export {
   type WorkflowRunAttemptDto,
   type WorkflowRunAttemptsResponseDto,
   type WorkflowRunDto,
+  type WorkflowRunJobDisplayStatusCountDto,
   type WorkflowRunJobStatusCountDto,
   type WorkflowRunJobSummaryDto,
   type WorkflowRunListItemDto,
@@ -104,6 +106,7 @@ export {
   workflowRunAttemptDtoSchema,
   workflowRunAttemptsResponseSchema,
   workflowRunDtoSchema,
+  workflowRunJobDisplayStatusCountDtoSchema,
   workflowRunJobStatusCountDtoSchema,
   workflowRunJobSummaryDtoSchema,
   workflowRunListItemSchema,
@@ -118,7 +121,6 @@ export {
 export {
   type JobExecutionDto,
   jobExecutionDtoSchema,
-  jobExecutionStatusSchema,
   type StepAttemptDetailResponseDto,
   stepAttemptDetailResponseSchema,
   type WorkflowRunDetailResponseDto,

package/src/schemas/job.test.ts

@@ -42,4 +42,17 @@ describe('job DTO schema', () => {
 
     expect(result.status_reason).toBe(statusReason);
   });
+
+  it.each([
+    'output_too_large',
+    'output_invalid',
+  ] as const)('accepts job failure reason "%s"', (statusReason) => {
+    const result = jobDtoSchema.parse({
+      ...baseJob,
+      status: 'failed',
+      status_reason: statusReason,
+    });
+
+    expect(result.status_reason).toBe(statusReason);
+  });
 });

package/src/schemas/job.ts

@@ -26,8 +26,10 @@ export const jobStatusReasonSchema = z.enum([
   'run_cancelled',
   'timed_out',
   'runner_lost',
+  'output_too_large',
   'step_failed',
   'unknown',
+  'output_invalid',
 ]);
 
 export const jobDtoSchema = z.object({

package/src/schemas/workflow-run-detail.ts

@@ -3,15 +3,11 @@ import {evaluationTraceSchema} from './evaluation-trace.js';
 import {jobDtoSchema} from './job.js';
 import {workflowExecutionEventSchema} from './job-listening.js';
 import {stepAttemptDetailDtoSchema, stepAttemptDtoSchema, stepDtoSchema} from './step.js';
-import {workflowRunAttemptDtoSchema, workflowRunResponseSchema} from './workflow-run.js';
-
-export const jobExecutionStatusSchema = z.enum([
-  'pending',
-  'running',
-  'succeeded',
-  'failed',
-  'cancelled',
-]);
+import {
+  jobExecutionStatusSchema,
+  workflowRunAttemptDtoSchema,
+  workflowRunResponseSchema,
+} from './workflow-run.js';
 
 export const jobExecutionDtoSchema = z.object({
   id: z.string().uuid(),
@@ -20,6 +16,7 @@ export const jobExecutionDtoSchema = z.object({
   name: z.string(),
   status: jobExecutionStatusSchema,
   status_reason: z.string().nullable(),
+  status_reason_message: z.string().nullable().optional(),
   runner: z.array(z.string()).nullable(),
   trigger_events: z.array(workflowExecutionEventSchema).default([]),
   outputs: z.record(z.string(), z.unknown()).nullable(),

package/src/schemas/workflow-run.test.ts

@@ -107,6 +107,9 @@ describe('workflow run list item schema', () => {
       key: `job-${position}`,
       name: null,
       status: 'succeeded' as const,
+      mode: 'one_shot' as const,
+      listener_status: 'inactive' as const,
+      execution_status: null,
       position,
     };
   }
@@ -121,6 +124,55 @@ describe('workflow run list item schema', () => {
 
     expect(result.jobs).toHaveLength(1);
     expect(result.jobs[0]?.status).toBe('succeeded');
+    expect(result.jobs[0]?.execution_status).toBeNull();
+  });
+
+  test('carries execution evidence and listening state for display derivation', () => {
+    const result = workflowRunListItemSchema.parse({
+      ...baseRun,
+      source_snapshot: null,
+      jobs: [
+        {
+          ...jobDto(0),
+          mode: 'listening',
+          listener_status: 'listening',
+          execution_status: 'running',
+        },
+      ],
+      job_status_counts: [{status: 'running', count: 1}],
+      job_display_status_counts: [{status: 'listening', count: 1}],
+    });
+
+    expect(result.jobs[0]).toMatchObject({
+      mode: 'listening',
+      listener_status: 'listening',
+      execution_status: 'running',
+    });
+    expect(result.job_status_counts).toEqual([{status: 'running', count: 1}]);
+    expect(result.job_display_status_counts).toEqual([{status: 'listening', count: 1}]);
+  });
+
+  test('accepts a pre-display-state API response during a mixed-version rollout', () => {
+    const {
+      mode: _mode,
+      listener_status: _listenerStatus,
+      execution_status: _executionStatus,
+      ...legacyJob
+    } = jobDto(0);
+
+    const result = workflowRunListItemSchema.parse({
+      ...baseRun,
+      source_snapshot: null,
+      jobs: [legacyJob],
+      job_status_counts: [{status: 'running', count: 1}],
+    });
+
+    expect(result.jobs[0]).toMatchObject({
+      mode: 'one_shot',
+      listener_status: 'inactive',
+      execution_status: null,
+    });
+    expect(result.job_display_status_counts).toBeUndefined();
   });
 
   // The preview is a bounded slice, so counts describe jobs the payload never carried.

package/src/schemas/workflow-run.ts

@@ -1,5 +1,6 @@
 import {z} from 'zod';
 import {jobStatusSchema} from './job.js';
+import {jobModeSchema, listenerStatusSchema} from './job-listening.js';
 
 export const workflowRunStatusSchema = z.enum([
   'pending',
@@ -11,6 +12,14 @@ export const workflowRunStatusSchema = z.enum([
 
 export type WorkflowRunStatusDto = z.infer<typeof workflowRunStatusSchema>;
 
+export const jobExecutionStatusSchema = z.enum([
+  'pending',
+  'running',
+  'succeeded',
+  'failed',
+  'cancelled',
+]);
+
 export const workflowRunRerunModeSchema = z.enum(['all', 'failed']);
 
 export type WorkflowRunRerunModeDto = z.infer<typeof workflowRunRerunModeSchema>;
@@ -137,16 +146,22 @@ export const workflowRunAttemptsResponseSchema = z.object({
 export type WorkflowRunAttemptsResponseDto = z.infer<typeof workflowRunAttemptsResponseSchema>;
 
 // The run list renders a status glyph per job so a failing run can be read without being
-// opened, which needs the current attempt's jobs in graph order but none of their steps.
+// opened. Runtime state comes from the selected execution rather than the job verdict, while
+// mode and listener status let the client apply the same display rule as run detail. These
+// fields default to the pre-display-state contract so a web client can roll out before or
+// alongside an API deployment without rejecting an older response.
 export const workflowRunJobSummaryDtoSchema = z.object({
   id: z.string().uuid(),
   key: z.string(),
   name: z.string().nullable(),
   status: jobStatusSchema,
+  mode: jobModeSchema.optional().default('one_shot'),
+  listener_status: listenerStatusSchema.optional().default('inactive'),
+  execution_status: jobExecutionStatusSchema.nullable().optional().default(null),
   position: z.number().int().nonnegative(),
 });
 
-export type WorkflowRunJobSummaryDto = z.infer<typeof workflowRunJobSummaryDtoSchema>;
+export type WorkflowRunJobSummaryDto = z.input<typeof workflowRunJobSummaryDtoSchema>;
 
 /**
  * How many jobs a run list row carries in graph order.
@@ -158,7 +173,7 @@ export type WorkflowRunJobSummaryDto = z.infer<typeof workflowRunJobSummaryDtoSc
  */
 export const WORKFLOW_RUN_JOB_PREVIEW_LIMIT = 16;
 
-/** One status and how many of the run's jobs hold it, counted over all of them. */
+/** The persisted job verdict and how many of the run's jobs carry it, counted over all of them. */
 export const workflowRunJobStatusCountDtoSchema = z.object({
   status: jobStatusSchema,
   count: z.number().int().positive(),
@@ -166,14 +181,29 @@ export const workflowRunJobStatusCountDtoSchema = z.object({
 
 export type WorkflowRunJobStatusCountDto = z.infer<typeof workflowRunJobStatusCountDtoSchema>;
 
+/** One display status and how many of the run's jobs render it, counted over all of them. */
+export const workflowRunJobDisplayStatusCountDtoSchema = z.object({
+  status: jobStatusSchema.or(z.literal('listening')),
+  count: z.number().int().positive(),
+});
+
+export type WorkflowRunJobDisplayStatusCountDto = z.infer<
+  typeof workflowRunJobDisplayStatusCountDtoSchema
+>;
+
 export const workflowRunListItemSchema = workflowRunResponseSchema.extend({
   /** Up to `WORKFLOW_RUN_JOB_PREVIEW_LIMIT` jobs in graph order, not the whole set. */
   jobs: z.array(workflowRunJobSummaryDtoSchema).max(WORKFLOW_RUN_JOB_PREVIEW_LIMIT),
-  /** Counted over every job of the attempt, including those past the preview. */
+  /** Persisted verdict counts, kept stable so older web clients can consume new responses. */
   job_status_counts: z.array(workflowRunJobStatusCountDtoSchema),
+  /**
+   * Display-state counts over every job of the attempt, including those past the preview.
+   * Optional so a new web client can consume an older API response during rollout.
+   */
+  job_display_status_counts: z.array(workflowRunJobDisplayStatusCountDtoSchema).optional(),
 });
 
-export type WorkflowRunListItemDto = z.infer<typeof workflowRunListItemSchema>;
+export type WorkflowRunListItemDto = z.input<typeof workflowRunListItemSchema>;
 
 export const workflowRunListResponseSchema = z.object({
   runs: z.array(workflowRunListItemSchema),
@@ -181,7 +211,7 @@ export const workflowRunListResponseSchema = z.object({
   filtered_total_count: z.number().int().nonnegative().nullable(),
 });
 
-export type WorkflowRunListResponseDto = z.infer<typeof workflowRunListResponseSchema>;
+export type WorkflowRunListResponseDto = z.input<typeof workflowRunListResponseSchema>;
 
 const aggregateBucketSchema = z.object({
   value: z.string(),