@shipfox/api-workflows-dto 2.0.0

package/src/schemas/job-listening.test.ts

@@ -0,0 +1,64 @@
+import {
+  jobListeningSchema,
+  triggerEventsBatchSchema,
+  workflowExecutionContextSchema,
+} from './job-listening.js';
+
+describe('jobListeningSchema', () => {
+  it('parses listener config payloads unchanged', () => {
+    const displayName = ['Review $', '{{ execution.index }}'].join('');
+    const input = {
+      on: [{source: 'github', event: 'pull_request_review'}],
+      until: [{source: 'github', event: 'pull_request'}],
+      timeout_ms: 1000,
+      max_executions: 3,
+      batch: {debounce_ms: 1000, max_size: 10, max_wait_ms: 5000},
+      on_resolve: 'finish',
+      execution_timeout_ms: null,
+      name: displayName,
+    };
+
+    const result = jobListeningSchema.parse(input);
+
+    expect(result).toEqual(input);
+  });
+});
+
+describe('execution context schemas', () => {
+  it('parses execution namespace payloads with event batches', () => {
+    const event = {
+      source: 'github',
+      event: 'pull_request_review',
+      delivery_id: 'delivery-1',
+      received_at: '2026-06-25T00:00:00.000Z',
+      data: {body: 'LGTM'},
+    };
+
+    const execution = workflowExecutionContextSchema.parse({
+      index: 0,
+      name: 'Review #1',
+      status: 'succeeded',
+      started_at: '2026-06-25T00:00:00.000Z',
+      finished_at: null,
+      events: [event],
+    });
+    const batch = triggerEventsBatchSchema.parse({events: [event]});
+
+    expect(execution.events).toEqual([event]);
+    expect(batch.events).toEqual([event]);
+  });
+
+  it('rejects negative execution indexes', () => {
+    const parse = () =>
+      workflowExecutionContextSchema.parse({
+        index: -1,
+        name: 'Review #-1',
+        status: 'succeeded',
+        started_at: '2026-06-25T00:00:00.000Z',
+        finished_at: null,
+        events: [],
+      });
+
+    expect(parse).toThrow();
+  });
+});

package/src/schemas/job-listening.ts

@@ -0,0 +1,59 @@
+import {z} from 'zod';
+
+export const jobModeSchema = z.enum(['one_shot', 'listening']);
+export const listenerStatusSchema = z.enum(['inactive', 'listening', 'resolved']);
+export const resolutionReasonSchema = z.enum(['until', 'timeout', 'max_executions', 'cancelled']);
+
+export const listeningTriggerSchema = z.object({
+  source: z.string(),
+  event: z.string(),
+  inputs: z.record(z.string(), z.unknown()).optional(),
+  filter: z.string().optional(),
+});
+
+export const jobListeningBatchSchema = z.object({
+  debounce_ms: z.number().int().positive().optional(),
+  max_size: z.number().int().positive().optional(),
+  max_wait_ms: z.number().int().positive().optional(),
+});
+
+export const jobListeningSchema = z.object({
+  on: z.array(listeningTriggerSchema).min(1),
+  until: z.array(listeningTriggerSchema).min(1).nullable(),
+  timeout_ms: z.number().int().positive().nullable(),
+  max_executions: z.number().int().positive().nullable(),
+  batch: jobListeningBatchSchema.nullable(),
+  on_resolve: z.enum(['finish', 'cancel']),
+  execution_timeout_ms: z.number().int().positive().nullable(),
+  name: z.string().nullable(),
+});
+
+export const workflowExecutionEventSchema = z.object({
+  source: z.string(),
+  event: z.string(),
+  delivery_id: z.string(),
+  received_at: z.string(),
+  data: z.unknown(),
+});
+
+export const workflowExecutionContextSchema = z.object({
+  index: z.number().int().nonnegative(),
+  name: z.string(),
+  status: z.string(),
+  started_at: z.string().nullable(),
+  finished_at: z.string().nullable(),
+  events: z.array(workflowExecutionEventSchema),
+});
+
+export const triggerEventsBatchSchema = z.object({
+  events: z.array(workflowExecutionEventSchema),
+});
+
+export type JobModeDto = z.infer<typeof jobModeSchema>;
+export type ListenerStatusDto = z.infer<typeof listenerStatusSchema>;
+export type ResolutionReasonDto = z.infer<typeof resolutionReasonSchema>;
+export type ListeningTriggerDto = z.infer<typeof listeningTriggerSchema>;
+export type JobListeningDto = z.infer<typeof jobListeningSchema>;
+export type WorkflowExecutionEventDto = z.infer<typeof workflowExecutionEventSchema>;
+export type WorkflowExecutionContextDto = z.infer<typeof workflowExecutionContextSchema>;
+export type TriggerEventsBatchDto = z.infer<typeof triggerEventsBatchSchema>;

package/src/schemas/job.test.ts

@@ -0,0 +1,42 @@
+import {jobDtoSchema} from './job.js';
+
+const baseJob = {
+  id: '11111111-1111-4111-8111-111111111111',
+  run_attempt_id: '22222222-2222-4222-8222-222222222222',
+  key: 'build',
+  name: 'build',
+  mode: 'one_shot',
+  status: 'pending',
+  status_reason: null,
+  carried_over: false,
+  listening: null,
+  listener_status: 'inactive',
+  resolution_reason: null,
+  outputs: null,
+  dependencies: [],
+  position: 0,
+  created_at: '2026-06-21T12:00:00.000Z',
+  updated_at: '2026-06-21T12:01:00.000Z',
+};
+
+describe('job DTO schema', () => {
+  it('accepts a job without execution timing fields', () => {
+    const result = jobDtoSchema.parse(baseJob);
+
+    expect(result).toMatchObject(baseJob);
+  });
+
+  it.each([
+    'default_gate_rejected',
+    'condition_rejected',
+    'condition_errored',
+  ] as const)('accepts job skip reason "%s"', (statusReason) => {
+    const result = jobDtoSchema.parse({
+      ...baseJob,
+      status: 'skipped',
+      status_reason: statusReason,
+    });
+
+    expect(result.status_reason).toBe(statusReason);
+  });
+});

package/src/schemas/job.ts

@@ -0,0 +1,53 @@
+import {z} from 'zod';
+import {
+  jobListeningSchema,
+  jobModeSchema,
+  listenerStatusSchema,
+  resolutionReasonSchema,
+} from './job-listening.js';
+
+export const jobStatusSchema = z.enum([
+  'pending',
+  'running',
+  'succeeded',
+  'failed',
+  'cancelled',
+  'skipped',
+]);
+
+export const jobStatusReasonSchema = z.enum([
+  'dependency_not_completed',
+  'condition_false',
+  'default_gate_rejected',
+  'condition_rejected',
+  'condition_errored',
+  'user_cancelled',
+  'run_cancelled',
+  'timed_out',
+  'runner_lost',
+  'step_failed',
+  'unknown',
+]);
+
+export const jobDtoSchema = z.object({
+  id: z.string().uuid(),
+  run_attempt_id: z.string().uuid(),
+  key: z.string(),
+  name: z.string().nullable(),
+  mode: jobModeSchema,
+  status: jobStatusSchema,
+  status_reason: jobStatusReasonSchema.nullable(),
+  carried_over: z.boolean(),
+  listening: jobListeningSchema.nullable(),
+  listener_status: listenerStatusSchema,
+  resolution_reason: resolutionReasonSchema.nullable(),
+  outputs: z.record(z.string(), z.unknown()).nullable(),
+  dependencies: z.array(z.string()),
+  position: z.number(),
+  created_at: z.string(),
+  updated_at: z.string(),
+});
+
+export type JobDto = z.infer<typeof jobDtoSchema>;
+export type JobStatusDto = z.infer<typeof jobStatusSchema>;
+export type JobStatusReasonDto = z.infer<typeof jobStatusReasonSchema>;

package/src/schemas/log-outcome.ts

@@ -0,0 +1,5 @@
+import {z} from 'zod';
+
+export const logOutcomeSchema = z.enum(['drained', 'abandoned']);
+
+export type LogOutcomeDto = z.infer<typeof logOutcomeSchema>;

package/src/schemas/step-source-location.test.ts

@@ -0,0 +1,45 @@
+import {stepDtoSchema, stepSourceLocationSchema} from './step.js';
+
+const baseStep = {
+  id: '11111111-1111-4111-8111-111111111111',
+  job_execution_id: '33333333-3333-4333-8333-333333333333',
+  key: null,
+  name: 'echo hello',
+  status: 'pending',
+  type: 'run',
+  config: {run: 'echo hello'},
+  error: null,
+  position: 1,
+  current_attempt: 1,
+  created_at: '2026-06-16T00:00:00.000Z',
+  updated_at: '2026-06-16T00:00:00.000Z',
+};
+
+describe('step source location schemas', () => {
+  test('accepts valid source locations', () => {
+    const result = stepSourceLocationSchema.parse({start_line: 5, end_line: 8});
+
+    expect(result).toEqual({start_line: 5, end_line: 8});
+  });
+
+  test('rejects inverted source locations', () => {
+    const result = stepSourceLocationSchema.safeParse({start_line: 8, end_line: 5});
+
+    expect(result.success).toBe(false);
+  });
+
+  test('accepts step DTOs with source locations', () => {
+    const result = stepDtoSchema.parse({
+      ...baseStep,
+      source_location: {start_line: 5, end_line: 8},
+    });
+
+    expect(result.source_location).toEqual({start_line: 5, end_line: 8});
+  });
+
+  test('accepts step DTOs with null source locations', () => {
+    const result = stepDtoSchema.parse({...baseStep, source_location: null});
+
+    expect(result.source_location).toBeNull();
+  });
+});

package/src/schemas/step.test.ts

@@ -0,0 +1,176 @@
+import {STEP_ERROR_MESSAGE_MAX_LENGTH, stepAttemptDtoSchema, stepErrorDtoSchema} from './step.js';
+
+const baseAttempt = {
+  id: '11111111-1111-4111-8111-111111111111',
+  step_id: '22222222-2222-4222-8222-222222222222',
+  attempt: 1,
+  execution_order: 1,
+  status: 'succeeded',
+  exit_code: 0,
+  output: null,
+  outputs: null,
+  response: null,
+  error: null,
+  restart_feedback: null,
+  started_at: '2026-01-01T00:00:00.000Z',
+  finished_at: '2026-01-01T00:01:00.000Z',
+};
+
+describe('stepErrorDtoSchema', () => {
+  it('accepts a message at the maximum length', () => {
+    const result = stepErrorDtoSchema.safeParse({
+      message: 'x'.repeat(STEP_ERROR_MESSAGE_MAX_LENGTH),
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects a message beyond the maximum length', () => {
+    const result = stepErrorDtoSchema.safeParse({
+      message: 'x'.repeat(STEP_ERROR_MESSAGE_MAX_LENGTH + 1),
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it('accepts an agent config issue with an agent config failure reason', () => {
+    const result = stepErrorDtoSchema.parse({
+      message: 'Model provider credentials are not configured',
+      reason: 'agent_config_invalid',
+      agent_config_issue: 'provider_not_configured',
+    });
+
+    expect(result).toEqual({
+      message: 'Model provider credentials are not configured',
+      reason: 'agent_config_invalid',
+      agent_config_issue: 'provider_not_configured',
+    });
+  });
+
+  it('accepts typed output validation failures', () => {
+    const result = stepErrorDtoSchema.parse({
+      message: 'Output "count" must be a finite number or numeric string.',
+      reason: 'output_invalid',
+      field: 'outputs.count',
+    });
+
+    expect(result).toEqual({
+      message: 'Output "count" must be a finite number or numeric string.',
+      reason: 'output_invalid',
+      field: 'outputs.count',
+    });
+  });
+
+  it('rejects unknown agent config issues', () => {
+    const result = stepErrorDtoSchema.safeParse({
+      message: 'Model provider credentials are not configured',
+      reason: 'agent_config_invalid',
+      agent_config_issue: 'unknown',
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it.each([
+    undefined,
+    'workspace_prep_failed',
+    'agent_invocation_failed',
+  ] as const)('rejects an agent config issue when reason is %s', (reason) => {
+    const result = stepErrorDtoSchema.safeParse({
+      message: 'Model provider credentials are not configured',
+      ...(reason === undefined ? {} : {reason}),
+      agent_config_issue: 'provider_not_configured',
+    });
+
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('stepAttemptDtoSchema', () => {
+  it('accepts an attempt with no gate or restart feedback', () => {
+    const attempt = {...baseAttempt, gate_result: {kind: 'none'}};
+
+    const result = stepAttemptDtoSchema.parse(attempt);
+
+    expect(result.gate_result).toEqual({kind: 'none'});
+    expect(result.restart_feedback).toBeNull();
+  });
+
+  it('accepts not-evaluated and evaluation-error gate results', () => {
+    const notEvaluated = stepAttemptDtoSchema.parse({
+      ...baseAttempt,
+      gate_result: {kind: 'not_evaluated'},
+    });
+    const evaluationError = stepAttemptDtoSchema.parse({
+      ...baseAttempt,
+      gate_result: {
+        kind: 'evaluation_error',
+        reason: 'gate expression evaluation failed',
+        exit_code: 1,
+      },
+    });
+
+    expect(notEvaluated.gate_result).toEqual({kind: 'not_evaluated'});
+    expect(evaluationError.gate_result).toEqual({
+      kind: 'evaluation_error',
+      reason: 'gate expression evaluation failed',
+      exit_code: 1,
+    });
+  });
+
+  it('accepts typed gate results and restart feedback', () => {
+    const attempt = {
+      ...baseAttempt,
+      status: 'failed',
+      exit_code: 1,
+      gate_result: {
+        kind: 'failed',
+        passed: false,
+        source: 'exit_code == 0',
+        exit_code: 1,
+      },
+      restart_feedback: 'gate condition not met',
+    };
+
+    const result = stepAttemptDtoSchema.parse(attempt);
+
+    expect(result.gate_result).toEqual({
+      kind: 'failed',
+      passed: false,
+      source: 'exit_code == 0',
+      exit_code: 1,
+    });
+    expect(result.restart_feedback).toBe('gate condition not met');
+  });
+
+  it('accepts an explicit unknown gate result for legacy data', () => {
+    const attempt = {
+      ...baseAttempt,
+      gate_result: {
+        kind: 'unknown',
+        data: {passed: 'yes'},
+      },
+    };
+
+    const result = stepAttemptDtoSchema.parse(attempt);
+
+    expect(result.gate_result).toEqual({
+      kind: 'unknown',
+      data: {passed: 'yes'},
+    });
+  });
+
+  it('rejects inconsistent typed gate results', () => {
+    const result = stepAttemptDtoSchema.safeParse({
+      ...baseAttempt,
+      gate_result: {
+        kind: 'passed',
+        passed: false,
+        source: 'exit_code == 0',
+        exit_code: 1,
+      },
+    });
+
+    expect(result.success).toBe(false);
+  });
+});

package/src/schemas/step.ts

@@ -0,0 +1,163 @@
+import {z} from 'zod';
+
+// Machine-readable cause of a step failure, for DB troubleshooting. The runner
+// reports it and the server stores it as-is. The `checkout_*`, `git_unavailable`,
+// `workspace_prep_failed`, and `setup_aborted` values cover setup-phase failures.
+// For agent steps the cause is split: `agent_config_invalid` is a user-fixable
+// configuration error (unknown provider, missing provider credentials on the runner,
+// wrong provider/model pair, missing model or prompt), while `agent_invocation_failed`
+// covers a genuine provider/API failure once the config is valid (network, 5xx, auth
+// rejected at call time). (Aborts are never reported: the step loop stops before reporting.)
+export const stepErrorReasonSchema = z.enum([
+  'checkout_failed',
+  'checkout_auth_failed',
+  'checkout_unavailable',
+  'git_unavailable',
+  'workspace_prep_failed',
+  'setup_aborted',
+  'config_unresolvable',
+  'output_invalid',
+  'agent_config_invalid',
+  'agent_invocation_failed',
+]);
+
+export type StepErrorReasonDto = z.infer<typeof stepErrorReasonSchema>;
+
+export const agentConfigIssueSchema = z.enum([
+  'step_config_invalid',
+  'provider_not_configured',
+  'provider_unsupported',
+  'model_unavailable',
+  'credentials_invalid',
+]);
+
+export type AgentConfigIssueDto = z.infer<typeof agentConfigIssueSchema>;
+
+// Whether a failure is infrastructure (`setup`) or user-code (`user`). Server-derived
+// from the step's type on the read path; the runner never sends it.
+export const stepErrorCategorySchema = z.enum(['setup', 'user']);
+
+export type StepErrorCategoryDto = z.infer<typeof stepErrorCategorySchema>;
+
+export const STEP_ERROR_MESSAGE_MAX_LENGTH = 2048;
+
+export const stepErrorDtoSchema = z
+  .object({
+    message: z.string().max(STEP_ERROR_MESSAGE_MAX_LENGTH),
+    exit_code: z.number().int().nullable().optional(),
+    signal: z.string().optional(),
+    reason: stepErrorReasonSchema.optional(),
+    field: z.string().optional(),
+    source: z.string().optional(),
+    agent_config_issue: agentConfigIssueSchema.optional(),
+    category: stepErrorCategorySchema.optional(),
+  })
+  .refine(
+    (error) => error.agent_config_issue === undefined || error.reason === 'agent_config_invalid',
+    {
+      message: 'agent_config_issue requires reason to be agent_config_invalid',
+      path: ['agent_config_issue'],
+    },
+  )
+  .nullable();
+
+export type StepErrorDto = z.infer<typeof stepErrorDtoSchema>;
+
+export const stepSourceLocationSchema = z
+  .object({
+    start_line: z.number().int().positive(),
+    end_line: z.number().int().positive(),
+  })
+  .refine((value) => value.end_line >= value.start_line, {
+    message: 'end_line must be greater than or equal to start_line',
+    path: ['end_line'],
+  });
+
+export type StepSourceLocationDto = z.infer<typeof stepSourceLocationSchema>;
+
+export const stepDtoSchema = z.object({
+  id: z.string().uuid(),
+  job_execution_id: z.string().uuid(),
+  key: z.string().nullable(),
+  name: z.string(),
+  source_location: stepSourceLocationSchema.nullable(),
+  status: z.string(),
+  type: z.string(),
+  config: z.record(z.string(), z.unknown()),
+  error: stepErrorDtoSchema,
+  position: z.number(),
+  // Execution-attempt identity of the current projection (>1 after a restart).
+  current_attempt: z.number().int(),
+  created_at: z.string(),
+  updated_at: z.string(),
+});
+
+export type StepDto = z.infer<typeof stepDtoSchema>;
+
+export const stepGateResultDtoSchema = z
+  .discriminatedUnion('kind', [
+    z.object({
+      kind: z.literal('none'),
+    }),
+    z.object({
+      kind: z.literal('not_evaluated'),
+    }),
+    z.object({
+      kind: z.literal('passed'),
+      passed: z.literal(true),
+      source: z.string(),
+      exit_code: z.number().int().nullable(),
+    }),
+    z.object({
+      kind: z.literal('failed'),
+      passed: z.literal(false),
+      source: z.string(),
+      exit_code: z.number().int().nullable(),
+    }),
+    z.object({
+      kind: z.literal('uncheckable'),
+      passed: z.literal(false),
+      uncheckable: z.literal(true),
+      reason: z.string(),
+      exit_code: z.number().int().nullable(),
+    }),
+    z.object({
+      kind: z.literal('evaluation_error'),
+      reason: z.string(),
+      exit_code: z.number().int().nullable(),
+    }),
+    z.object({
+      kind: z.literal('unknown'),
+      data: z.record(z.string(), z.unknown()),
+    }),
+  ])
+  .nullable();
+
+export type StepGateResultDto = z.infer<typeof stepGateResultDtoSchema>;
+
+// One execution attempt of a step (the durable history behind the current
+// projection). Surfaced in run details so a restarted step's attempts are visible.
+export const stepAttemptDtoSchema = z.object({
+  id: z.string().uuid(),
+  step_id: z.string().uuid(),
+  attempt: z.number().int().positive(),
+  execution_order: z.number().int().positive(),
+  status: z.string(),
+  exit_code: z.number().int().nullable(),
+  // `output` and `error` are opaque audit blobs: the raw jsonb persisted for the
+  // attempt, NOT snake_case-normalized (their nested keys may be camelCase, e.g.
+  // `error.exitCode`). Consume the top-level snake_case `exit_code` for the
+  // numeric code; treat these as display/debug payloads.
+  output: z.record(z.string(), z.unknown()).nullable(),
+  outputs: z.record(z.string(), z.unknown()).nullable(),
+  response: z.string().nullable(),
+  error: z.record(z.string(), z.unknown()).nullable(),
+  // `unknown.data` is the raw jsonb gate payload for legacy or unrecognized
+  // rows; nested keys are not snake_case-normalized.
+  gate_result: stepGateResultDtoSchema,
+  restart_feedback: z.string().nullable(),
+  started_at: z.string(),
+  finished_at: z.string().nullable(),
+});
+
+export type StepAttemptDto = z.infer<typeof stepAttemptDtoSchema>;

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

@@ -0,0 +1,67 @@
+import {z} from 'zod';
+import {jobDtoSchema} from './job.js';
+import {workflowExecutionEventSchema} from './job-listening.js';
+import {stepAttemptDtoSchema, stepDtoSchema} from './step.js';
+import {workflowRunAttemptDtoSchema, workflowRunResponseSchema} from './workflow-run.js';
+
+export const jobExecutionStatusSchema = z.enum([
+  'pending',
+  'running',
+  'succeeded',
+  'failed',
+  'cancelled',
+]);
+
+export const jobExecutionDtoSchema = z.object({
+  id: z.string().uuid(),
+  job_id: z.string().uuid(),
+  sequence: z.number().int().positive(),
+  name: z.string(),
+  status: jobExecutionStatusSchema,
+  status_reason: z.string().nullable(),
+  trigger_events: z.array(workflowExecutionEventSchema).default([]),
+  outputs: z.record(z.string(), z.unknown()).nullable(),
+  queued_at: z.string().nullable(),
+  started_at: z.string().nullable(),
+  finished_at: z.string().nullable(),
+  timed_out_at: z.string().nullable(),
+  created_at: z.string(),
+  updated_at: z.string(),
+});
+
+export type JobExecutionDto = z.infer<typeof jobExecutionDtoSchema>;
+
+// A step with its attempt history: one entry per dispatched attempt (a restarted
+// step has more than one). `current_attempt` on the step points at the latest.
+export const workflowRunStepDetailDtoSchema = stepDtoSchema.extend({
+  exit_code: z.number().int().nullable(),
+  outputs: z.record(z.string(), z.unknown()).nullable(),
+  response: z.string().nullable(),
+  gate_result: stepAttemptDtoSchema.shape.gate_result,
+  attempts: z.array(stepAttemptDtoSchema),
+});
+
+export type WorkflowRunStepDetailDto = z.infer<typeof workflowRunStepDetailDtoSchema>;
+
+export const workflowRunJobExecutionDetailDtoSchema = jobExecutionDtoSchema.extend({
+  steps: z.array(workflowRunStepDetailDtoSchema),
+});
+
+export type WorkflowRunJobExecutionDetailDto = z.infer<
+  typeof workflowRunJobExecutionDetailDtoSchema
+>;
+
+export const workflowRunJobDetailDtoSchema = jobDtoSchema.extend({
+  job_executions: z.array(workflowRunJobExecutionDetailDtoSchema),
+});
+
+export type WorkflowRunJobDetailDto = z.infer<typeof workflowRunJobDetailDtoSchema>;
+
+// The run detail read model returned by `GET /workflows/runs/:id`: a run plus its
+// jobs, each job's steps, and each step's attempt history.
+export const workflowRunDetailResponseSchema = workflowRunResponseSchema.extend({
+  run_attempt: workflowRunAttemptDtoSchema,
+  jobs: z.array(workflowRunJobDetailDtoSchema),
+});
+
+export type WorkflowRunDetailResponseDto = z.infer<typeof workflowRunDetailResponseSchema>;