@shipfox/client-workflows 17.0.0 → 18.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/client-workflows",
   "license": "MIT",
-  "version": "17.0.0",
+  "version": "18.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -29,7 +29,7 @@
     "date-fns": "^4.1.0",
     "@shipfox/annotations-dto": "12.3.0",
     "@shipfox/api-definitions-dto": "12.3.0",
-    "@shipfox/api-workflows-dto": "12.3.0",
+    "@shipfox/api-workflows-dto": "12.5.0",
     "@shipfox/client-api": "6.0.1",
     "@shipfox/client-logs": "17.0.0",
     "@shipfox/client-projects": "17.0.0",

package/src/components/job-detail/job-context-panel.tsx

@@ -27,6 +27,7 @@ export function JobContextPanel({job, execution}: {job: Job; execution: JobExecu
       execution.triggerEvents.length ||
       job.success ||
       statusReason ||
+      execution.statusReasonMessage ||
       trace?.length ||
       hasTiming,
   );
@@ -114,6 +115,9 @@ function JobContextSheet({
             {statusReason ? (
               <ContextValue label="Status reason" value={humanize(statusReason)} />
             ) : null}
+            {execution.statusReasonMessage ? (
+              <ContextValue label="Failure details" value={execution.statusReasonMessage} />
+            ) : null}
             {execution.triggerEvents.length ? (
               <JsonCode
                 title={`Trigger events (${execution.triggerEvents.length})`}

package/src/components/job-detail/job-detail-view.tsx

@@ -33,6 +33,7 @@ import {
   emptyStateForJob,
   emptyStateForMissingExecution,
   jobSucceededSummary,
+  MaterializedOutputFailureNotice,
 } from './job-empty-states.js';
 import {
   resolveWorkflowJobSelection,
@@ -258,39 +259,42 @@ export function JobDetailView({
                 Logs
               </Text>
               {selectedJobExecution ? (
-                <StepList
-                  job={job}
-                  jobExecution={selectedJobExecution}
-                  selectedAttemptId={selectedAttemptId}
-                  defaultSelectedAttemptId={landingSelection?.attemptId}
-                  onSelectedAttemptChange={selectAttempt}
-                  inspectorOpenAttemptId={inspectorOpenAttemptId}
-                  onInspectorOpenChange={onInspectorOpenChange}
-                  autoSelectActiveAttempt
-                  emptyState={emptyStateForJob(job, selectedJobExecution)}
-                  showHeader={false}
-                  className="rounded-none border-0 bg-transparent"
-                  renderExpandedStep={(context) => (
-                    <ExpandedStep context={context} pageScrollRef={pageScrollRef} />
-                  )}
-                  renderInspector={(entry) => (
-                    <StepInspectorSheet
-                      entry={entry}
-                      open
-                      onOpenChange={(open) => onInspectorOpenChange(open ? entry.id : null)}
-                      workspaceSlug={workspaceSlug}
-                      projectSlug={projectSlug}
-                      workflowRunId={run.id}
-                      runAttempt={run.runAttempt.attempt}
-                      jobId={job.id}
-                      annotationCount={annotationCountForStep(
-                        annotationSummaryQuery.data,
-                        entry.step.id,
-                        entry.attempt,
-                      )}
-                    />
-                  )}
-                />
+                <>
+                  <MaterializedOutputFailureNotice jobExecution={selectedJobExecution} />
+                  <StepList
+                    job={job}
+                    jobExecution={selectedJobExecution}
+                    selectedAttemptId={selectedAttemptId}
+                    defaultSelectedAttemptId={landingSelection?.attemptId}
+                    onSelectedAttemptChange={selectAttempt}
+                    inspectorOpenAttemptId={inspectorOpenAttemptId}
+                    onInspectorOpenChange={onInspectorOpenChange}
+                    autoSelectActiveAttempt
+                    emptyState={emptyStateForJob(job, selectedJobExecution)}
+                    showHeader={false}
+                    className="rounded-none border-0 bg-transparent"
+                    renderExpandedStep={(context) => (
+                      <ExpandedStep context={context} pageScrollRef={pageScrollRef} />
+                    )}
+                    renderInspector={(entry) => (
+                      <StepInspectorSheet
+                        entry={entry}
+                        open
+                        onOpenChange={(open) => onInspectorOpenChange(open ? entry.id : null)}
+                        workspaceSlug={workspaceSlug}
+                        projectSlug={projectSlug}
+                        workflowRunId={run.id}
+                        runAttempt={run.runAttempt.attempt}
+                        jobId={job.id}
+                        annotationCount={annotationCountForStep(
+                          annotationSummaryQuery.data,
+                          entry.step.id,
+                          entry.attempt,
+                        )}
+                      />
+                    )}
+                  />
+                </>
               ) : (
                 <EmptyStateForMissingExecution job={job} />
               )}

package/src/components/job-detail/job-empty-states.test.ts

@@ -3,7 +3,13 @@ import {
   workflowJobExecutionDto,
   workflowStepDto,
 } from '#test/fixtures/workflow-run.js';
-import {jobSucceededSummary} from './job-empty-states.js';
+import {
+  emptyStateForJob,
+  emptyStateForMissingExecution,
+  jobSucceededSummary,
+  outputFailureDescriptionForExecution,
+  skippedJobDescription,
+} from './job-empty-states.js';
 
 describe('jobSucceededSummary', () => {
   test('counts only succeeded steps when skipped steps are present', () => {
@@ -25,3 +31,101 @@ describe('jobSucceededSummary', () => {
     expect(jobSucceededSummary(job, execution)).toBe('1 step succeeded');
   });
 });
+
+describe('skippedJobDescription', () => {
+  test('explains when materialized output exceeds the configured size limit', () => {
+    expect(skippedJobDescription('output_too_large')).toBe(
+      'The materialized job output exceeded its configured size limit.',
+    );
+  });
+});
+
+describe('materialized output failure descriptions', () => {
+  const fallback =
+    'A materialized job output could not be persisted: it exceeded a size or entry cap, contained a non-JSON-safe value, or referenced an unresolved value. Check the output mapping and values before re-running the workflow.';
+
+  test('uses the server-authored message for an execution with recorded steps', () => {
+    const job = workflowJob({
+      status: 'failed',
+      status_reason: 'output_invalid',
+      job_executions: [
+        workflowJobExecutionDto({
+          status: 'failed',
+          status_reason: 'output_invalid',
+          status_reason_message: 'Job output "payload" cannot be persisted as JSON: undefined.',
+          steps: [workflowStepDto({status: 'succeeded'})],
+        }),
+      ],
+    });
+    const execution = job.jobExecutions[0];
+    if (!execution) throw new Error('Expected a job execution');
+
+    expect(outputFailureDescriptionForExecution(execution)).toBe(
+      'Job output "payload" cannot be persisted as JSON: undefined.',
+    );
+  });
+
+  test('keeps the generic fallback for old output-invalid rows without a message', () => {
+    const job = workflowJob({
+      status: 'failed',
+      status_reason: 'output_invalid',
+      job_executions: [
+        workflowJobExecutionDto({
+          status: 'failed',
+          status_reason: 'output_invalid',
+          steps: [workflowStepDto({status: 'succeeded'})],
+        }),
+      ],
+    });
+    const execution = job.jobExecutions[0];
+    if (!execution) throw new Error('Expected a job execution');
+
+    expect(outputFailureDescriptionForExecution(execution)).toBe(fallback);
+  });
+
+  test('uses the message in the empty state when output materialization failed before steps', () => {
+    const job = workflowJob({
+      status: 'failed',
+      status_reason: 'output_invalid',
+      job_executions: [
+        workflowJobExecutionDto({
+          status: 'failed',
+          status_reason: 'output_invalid',
+          status_reason_message: 'Job outputs cannot define more than 10 entries (found 11)',
+          steps: [],
+        }),
+      ],
+    });
+    const execution = job.jobExecutions[0];
+    if (!execution) throw new Error('Expected a job execution');
+
+    expect(emptyStateForJob(job, execution)).toMatchObject({
+      description: 'Job outputs cannot define more than 10 entries (found 11)',
+    });
+  });
+
+  test('keeps output failures scoped to the selected execution', () => {
+    const job = workflowJob({
+      status: 'failed',
+      status_reason: 'output_invalid',
+      job_executions: [
+        workflowJobExecutionDto({
+          status: 'succeeded',
+          status_reason: null,
+          steps: [workflowStepDto({status: 'succeeded'})],
+        }),
+      ],
+    });
+    const execution = job.jobExecutions[0];
+    if (!execution) throw new Error('Expected a job execution');
+
+    expect(outputFailureDescriptionForExecution(execution)).toBeUndefined();
+    expect(
+      emptyStateForMissingExecution(
+        workflowJob({status: 'failed', status_reason: 'output_invalid'}),
+      ),
+    ).toMatchObject({
+      description: fallback,
+    });
+  });
+});

package/src/components/job-detail/job-empty-states.tsx

@@ -1,3 +1,4 @@
+import {Callout, CalloutContent, CalloutDescription, CalloutTitle} from '@shipfox/react-ui/callout';
 import {EmptyState} from '@shipfox/react-ui/empty-state';
 import type {Job, JobExecution, Step, StepError} from '#core/workflow-run.js';
 import {
@@ -9,6 +10,44 @@ import {
 import type {StepListEmptyState} from '../step-list/index.js';
 import {formatJobExecutionTime} from './job-execution-time-text.js';
 
+const MATERIALIZED_OUTPUT_FAILURE_DESCRIPTION =
+  'A materialized job output could not be persisted: it exceeded a size or entry cap, contained a non-JSON-safe value, or referenced an unresolved value. Check the output mapping and values before re-running the workflow.';
+const OUTPUT_TOO_LARGE_FAILURE_DESCRIPTION =
+  'The materialized job output exceeded its configured size limit. Review the failure details before re-running the workflow.';
+
+export function outputFailureDescriptionForExecution(
+  jobExecution: JobExecution,
+): string | undefined {
+  if (jobExecution.steps.length === 0) return undefined;
+
+  if (jobExecution.statusReason === 'output_invalid') {
+    return jobExecution.statusReasonMessage || MATERIALIZED_OUTPUT_FAILURE_DESCRIPTION;
+  }
+  if (jobExecution.statusReason === 'output_too_large') {
+    return jobExecution.statusReasonMessage || OUTPUT_TOO_LARGE_FAILURE_DESCRIPTION;
+  }
+  return undefined;
+}
+
+export function MaterializedOutputFailureNotice({jobExecution}: {jobExecution: JobExecution}) {
+  const description = outputFailureDescriptionForExecution(jobExecution);
+  if (!description) return null;
+
+  return (
+    <Callout
+      role="alert"
+      type="error"
+      variant="secondary"
+      className="border-b border-border-neutral-base px-row py-row"
+    >
+      <CalloutContent>
+        <CalloutTitle>Job output could not be persisted</CalloutTitle>
+        <CalloutDescription>{description}</CalloutDescription>
+      </CalloutContent>
+    </Callout>
+  );
+}
+
 export function emptyStateForJob(
   job: Job,
   jobExecution: JobExecution,
@@ -64,7 +103,11 @@ export function emptyStateForJob(
   if (displayStatus === 'failed') {
     return {
       title: 'Job failed before its first step started',
-      description: preStepFailureDescription(jobExecution.statusReason ?? job.statusReason, runner),
+      description: preStepFailureDescription(
+        jobExecution.statusReason ?? job.statusReason,
+        runner,
+        jobExecution.statusReasonMessage,
+      ),
       status: displayStatus,
     };
   }
@@ -159,14 +202,21 @@ export function skippedJobDescription(reason: Job['statusReason']): string {
     case 'run_cancelled':
     case 'timed_out':
     case 'runner_lost':
+    case 'output_invalid':
     case 'step_failed':
     case 'unknown':
     case null:
       return 'This job did not start.';
+    case 'output_too_large':
+      return 'The materialized job output exceeded its configured size limit.';
   }
 }
 
-function preStepFailureDescription(reason: string | null, runner: string[] | null = null): string {
+function preStepFailureDescription(
+  reason: string | null,
+  runner: string[] | null = null,
+  statusReasonMessage: string | null = null,
+): string {
   const runnerCopy = runner?.length ? ` Required runner labels: ${runner.join(', ')}.` : '';
 
   switch (reason) {
@@ -179,6 +229,10 @@ function preStepFailureDescription(reason: string | null, runner: string[] | nul
       return 'The execution ended while the run was being cancelled.';
     case 'step_failed':
       return `The execution failed before step details were recorded.${runnerCopy} Review run annotations before re-running the workflow.`;
+    case 'output_too_large':
+      return statusReasonMessage || OUTPUT_TOO_LARGE_FAILURE_DESCRIPTION;
+    case 'output_invalid':
+      return statusReasonMessage || MATERIALIZED_OUTPUT_FAILURE_DESCRIPTION;
     case 'condition_errored':
       return 'The job condition could not be evaluated. Review run annotations before re-running the workflow.';
     case 'dependency_not_completed':

package/src/components/job-detail/step-troubleshooting.tsx

@@ -442,6 +442,8 @@ function failureTitle(reason: string | JobStatusReason): string {
       return 'Agent harness was unavailable';
     case 'runner_lost':
       return 'Runner stopped responding';
+    case 'output_too_large':
+      return 'Job output exceeded its size limit';
     case 'timed_out':
       return 'Step timed out';
     case 'step_failed':
@@ -489,6 +491,8 @@ function failureDescription(reason: string | JobStatusReason): string {
       return 'The runner could not start the agent harness.';
     case 'runner_lost':
       return 'The runner stopped responding before the step completed.';
+    case 'output_too_large':
+      return 'The materialized job output exceeded its configured size limit.';
     case 'timed_out':
       return 'The step exceeded its configured time limit.';
     case 'dependency_not_completed':

package/src/components/step-list/step-list-model.ts

@@ -77,6 +77,7 @@ export function emptyJobExecutionForJob(job: Job): JobExecution {
     name: job.name ?? job.key,
     status: job.status === 'skipped' ? 'cancelled' : job.status,
     statusReason: job.statusReason,
+    statusReasonMessage: null,
     runner: job.runner,
     outputs: job.outputs,
     triggerEvents: [],

package/src/components/workflow-run-view/run-workspace-nav.tsx

@@ -53,8 +53,12 @@ export function RunWorkspaceNav({
 
   return (
     <TimeTickerProvider intervalMs={1000} reducedMotionIntervalMs={10_000}>
-      <aside className="w-full shrink-0 border-b border-border-neutral-base bg-background-neutral-background min-[768px]:w-240 min-[768px]:border-b-0 min-[768px]:border-r">
-        <Collapsible open={mobileOpen} onOpenChange={setMobileOpen}>
+      <aside className="flex min-h-0 w-full shrink-0 flex-col border-b border-border-neutral-base bg-background-neutral-background min-[768px]:w-240 min-[768px]:border-b-0 min-[768px]:border-r">
+        <Collapsible
+          open={mobileOpen}
+          onOpenChange={setMobileOpen}
+          className="flex min-h-0 flex-col min-[768px]:flex-1"
+        >
           <CollapsibleTrigger asChild>
             <button
               type="button"
@@ -82,7 +86,7 @@ export function RunWorkspaceNav({
           </CollapsibleTrigger>
           <div
             className={cn(
-              'max-h-[50vh] overflow-y-auto p-tight min-[768px]:block min-[768px]:max-h-none min-[768px]:p-[12px]',
+              'flex min-h-0 max-h-[50vh] flex-col overflow-y-auto p-tight scrollbar min-[768px]:min-h-0 min-[768px]:max-h-none min-[768px]:flex-1 min-[768px]:flex min-[768px]:overflow-hidden min-[768px]:p-[12px]',
               !mobileOpen && 'hidden',
             )}
           >
@@ -136,7 +140,7 @@ function RunWorkspaceNavContent({
   }, [currentJobId, mobileOpen]);
 
   return (
-    <nav aria-label="Run workspace" className="flex min-w-0 flex-col gap-group">
+    <nav aria-label="Run workspace" className="flex min-h-0 min-w-0 flex-1 flex-col gap-group">
       <ul>
         <li>
           <RunSectionLink
@@ -151,7 +155,10 @@ function RunWorkspaceNavContent({
         </li>
       </ul>
 
-      <section aria-labelledby="run-workspace-jobs-heading" className="min-w-0">
+      <section
+        aria-labelledby="run-workspace-jobs-heading"
+        className="flex min-h-0 min-w-0 flex-1 flex-col"
+      >
         <div className="flex items-center justify-between gap-inline px-tight pb-[6px]">
           <Text
             as="h2"
@@ -166,7 +173,7 @@ function RunWorkspaceNavContent({
             {jobs.length}
           </Text>
         </div>
-        <ol className="max-h-[320px] overflow-y-auto">
+        <ol className="min-h-0 flex-1 overflow-y-auto scrollbar">
           {jobs.map((job) => {
             const current = job.id === currentJobId;
             const execution = defaultJobExecution(job);

package/src/core/entities/job-execution.ts

@@ -29,6 +29,7 @@ interface JobExecutionFields {
   name: string;
   status: JobExecutionStatus;
   statusReason: string | null;
+  statusReasonMessage: string | null;
   runner: string[] | null;
   outputs: Record<string, unknown> | null;
   triggerEvents: WorkflowExecutionEvent[];
@@ -49,6 +50,7 @@ export class JobExecution {
   name!: string;
   status!: JobExecutionStatus;
   statusReason!: string | null;
+  statusReasonMessage!: string | null;
   runner!: string[] | null;
   outputs!: Record<string, unknown> | null;
   triggerEvents!: WorkflowExecutionEvent[];

package/src/core/entities/job.ts

@@ -20,8 +20,10 @@ export type JobStatusReason =
   | 'run_cancelled'
   | 'timed_out'
   | 'runner_lost'
+  | 'output_too_large'
   | 'step_failed'
-  | 'unknown';
+  | 'unknown'
+  | 'output_invalid';
 export interface JobListening {
   on: Array<{
     source: string;

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

@@ -165,6 +165,7 @@ 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),