@shipfox/api-workflows-dto 12.2.0 → 12.5.0

package/package.json

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

package/src/events.test.ts

@@ -100,6 +100,7 @@ const validStepAttemptTerminated = {
   projectId: 'proj-1',
   stepId: 'step-1',
   attempt: 1,
+  status: 'failed',
   logOutcome: 'drained',
 };
 
@@ -138,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

@@ -139,10 +139,15 @@ export type WorkflowsJobEventDeliveredEventDto = z.infer<typeof workflowsJobEven
 
 export const workflowsJobTerminatedSchema = z.object({
   jobId: nonEmptyStringSchema,
+  // Optional for compatibility with terminal events written before the current execution
+  // identity became part of the event contract. New events always include the value, or null
+  // when the job was terminated before an execution was created.
+  jobExecutionId: nonEmptyStringSchema.nullable().optional(),
   workflowRunId: nonEmptyStringSchema,
   workflowRunAttemptId: nonEmptyStringSchema,
   status: jobTerminalStatusSchema,
   statusReason: jobStatusReasonSchema.nullable(),
+  statusReasonMessage: z.string().nullable().optional(),
 });
 export type WorkflowsJobTerminatedEventDto = z.infer<typeof workflowsJobTerminatedSchema>;
 
@@ -178,6 +183,9 @@ export const workflowsStepAttemptTerminatedSchema = z.object({
   projectId: nonEmptyStringSchema,
   stepId: nonEmptyStringSchema,
   attempt: z.number().int().positive(),
+  // Optional so the subscriber can continue to consume terminal events written
+  // before the status field was added. New outbox events always include it.
+  status: terminalStatusSchema.optional(),
   logOutcome: logOutcomeSchema,
 });
 export type WorkflowsStepAttemptTerminatedEventDto = z.infer<

package/src/index.ts

@@ -15,6 +15,10 @@ export {
   checkoutTokenParamsSchema,
   checkoutTokenQuerySchema,
   checkoutTokenResponseSchema,
+  type EvaluationTraceDto,
+  type EvaluationTraceEntryDto,
+  evaluationTraceEntrySchema,
+  evaluationTraceSchema,
   type JobDto,
   type JobExecutionDto,
   type JobListeningDto,
@@ -45,18 +49,25 @@ export {
   resolutionReasonSchema,
   STEP_ERROR_MESSAGE_MAX_LENGTH,
   STEP_RESPONSE_MAX_LENGTH,
+  STEP_STATUS_REASONS,
+  type StepAttemptDetailDto,
+  type StepAttemptDetailResponseDto,
   type StepAttemptDto,
   type StepDto,
   type StepErrorCategoryDto,
   type StepErrorDto,
   type StepErrorReasonDto,
   type StepGateResultDto,
+  type StepStatusReasonDto,
+  stepAttemptDetailDtoSchema,
+  stepAttemptDetailResponseSchema,
   stepAttemptDtoSchema,
   stepDtoSchema,
   stepErrorCategorySchema,
   stepErrorDtoSchema,
   stepErrorReasonSchema,
   stepGateResultDtoSchema,
+  stepStatusReasonSchema,
   type TriggerEventsBatchDto,
   triggerEventsBatchSchema,
   type WorkflowExecutionContextDto,

package/src/schemas/evaluation-trace.test.ts

@@ -0,0 +1,40 @@
+import {evaluationTraceSchema} from './evaluation-trace.js';
+
+describe('evaluation trace schema', () => {
+  it('accepts value entries with resolved and diagnostic metadata', () => {
+    const trace = evaluationTraceSchema.parse([
+      {
+        expression: 'inputs.environment',
+        roots: ['inputs.environment'],
+        fill_target: 'agent.prompt',
+        evaluated_at: '2026-08-05T12:00:00.000Z',
+        field: 'agent.prompt',
+        value: 'production',
+        reference: true,
+        degraded: false,
+        env_key: 'ENVIRONMENT',
+      },
+    ]);
+
+    expect(trace[0]).toMatchObject({
+      field: 'agent.prompt',
+      value: 'production',
+      reference: true,
+      env_key: 'ENVIRONMENT',
+    });
+  });
+
+  it('accepts an explicit trace budget marker', () => {
+    expect(evaluationTraceSchema.parse([{truncated: true, dropped: 3}])).toEqual([
+      {truncated: true, dropped: 3},
+    ]);
+  });
+
+  it('rejects malformed trace entries', () => {
+    const result = evaluationTraceSchema.safeParse([
+      {expression: 'inputs.environment', field: 'agent.prompt'},
+    ]);
+
+    expect(result.success).toBe(false);
+  });
+});

package/src/schemas/evaluation-trace.ts

@@ -0,0 +1,30 @@
+import {z} from 'zod';
+
+const evaluationTraceValueSchema = z.object({
+  expression: z.string(),
+  roots: z.array(z.string()),
+  fill_target: z.string(),
+  evaluated_at: z.string(),
+  field: z.string(),
+  value: z.string().optional(),
+  truncated: z.boolean().optional(),
+  expr_truncated: z.boolean().optional(),
+  reference: z.boolean().optional(),
+  degraded: z.boolean().optional(),
+  env_key: z.string().optional(),
+});
+
+const evaluationTraceLimitSchema = z.object({
+  truncated: z.literal(true),
+  dropped: z.number().int().nonnegative(),
+});
+
+export const evaluationTraceEntrySchema = z.union([
+  evaluationTraceValueSchema,
+  evaluationTraceLimitSchema,
+]);
+
+export const evaluationTraceSchema = z.array(evaluationTraceEntrySchema);
+
+export type EvaluationTraceEntryDto = z.infer<typeof evaluationTraceEntrySchema>;
+export type EvaluationTraceDto = z.infer<typeof evaluationTraceSchema>;

package/src/schemas/index.ts

@@ -13,6 +13,12 @@ export {
   checkoutTokenQuerySchema,
   checkoutTokenResponseSchema,
 } from './checkout-token.js';
+export {
+  type EvaluationTraceDto,
+  type EvaluationTraceEntryDto,
+  evaluationTraceEntrySchema,
+  evaluationTraceSchema,
+} from './evaluation-trace.js';
 export {
   type JobDto,
   type JobStatusDto,
@@ -56,18 +62,23 @@ export {
   type AgentConfigIssueDto,
   agentConfigIssueSchema,
   STEP_ERROR_MESSAGE_MAX_LENGTH,
+  STEP_STATUS_REASONS,
+  type StepAttemptDetailDto,
   type StepAttemptDto,
   type StepDto,
   type StepErrorCategoryDto,
   type StepErrorDto,
   type StepErrorReasonDto,
   type StepGateResultDto,
+  type StepStatusReasonDto,
+  stepAttemptDetailDtoSchema,
   stepAttemptDtoSchema,
   stepDtoSchema,
   stepErrorCategorySchema,
   stepErrorDtoSchema,
   stepErrorReasonSchema,
   stepGateResultDtoSchema,
+  stepStatusReasonSchema,
 } from './step.js';
 export {
   type RerunWorkflowRunBodyDto,
@@ -108,6 +119,8 @@ export {
   type JobExecutionDto,
   jobExecutionDtoSchema,
   jobExecutionStatusSchema,
+  type StepAttemptDetailResponseDto,
+  stepAttemptDetailResponseSchema,
   type WorkflowRunDetailResponseDto,
   type WorkflowRunJobDetailDto,
   type WorkflowRunJobExecutionDetailDto,

package/src/schemas/job.test.ts

@@ -9,6 +9,9 @@ const baseJob = {
   status: 'pending',
   status_reason: null,
   carried_over: false,
+  success: null,
+  runner: null,
+  evaluation_trace: null,
   listening: null,
   listener_status: 'inactive',
   resolution_reason: null,
@@ -39,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

@@ -1,4 +1,5 @@
 import {z} from 'zod';
+import {evaluationTraceSchema} from './evaluation-trace.js';
 import {
   jobListeningSchema,
   jobModeSchema,
@@ -25,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({
@@ -38,6 +41,9 @@ export const jobDtoSchema = z.object({
   status: jobStatusSchema,
   status_reason: jobStatusReasonSchema.nullable(),
   carried_over: z.boolean(),
+  success: z.string().nullable(),
+  runner: z.array(z.string()).nullable(),
+  evaluation_trace: evaluationTraceSchema.nullable(),
   listening: jobListeningSchema.nullable(),
   listener_status: listenerStatusSchema,
   resolution_reason: resolutionReasonSchema.nullable(),

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

@@ -6,8 +6,10 @@ const baseStep = {
   key: null,
   name: 'echo hello',
   status: 'pending',
+  status_reason: null,
   type: 'run',
   config: {run: 'echo hello'},
+  evaluation_trace: null,
   error: null,
   position: 1,
   current_attempt: 1,

package/src/schemas/step.test.ts

@@ -1,4 +1,10 @@
-import {STEP_ERROR_MESSAGE_MAX_LENGTH, stepAttemptDtoSchema, stepErrorDtoSchema} from './step.js';
+import {
+  STEP_ERROR_MESSAGE_MAX_LENGTH,
+  STEP_STATUS_REASONS,
+  stepAttemptDtoSchema,
+  stepErrorDtoSchema,
+  stepStatusReasonSchema,
+} from './step.js';
 
 const baseAttempt = {
   id: '11111111-1111-4111-8111-111111111111',
@@ -111,6 +117,16 @@ describe('stepErrorDtoSchema', () => {
   });
 });
 
+describe('stepStatusReasonSchema', () => {
+  it.each(STEP_STATUS_REASONS)('accepts the domain reason %s', (reason) => {
+    expect(stepStatusReasonSchema.parse(reason)).toBe(reason);
+  });
+
+  it('rejects an unknown step status reason', () => {
+    expect(stepStatusReasonSchema.safeParse('runner_lost').success).toBe(false);
+  });
+});
+
 describe('stepAttemptDtoSchema', () => {
   it('accepts an attempt with no gate or restart feedback', () => {
     const attempt = {...baseAttempt, gate_result: {kind: 'none'}};

package/src/schemas/step.ts

@@ -1,4 +1,15 @@
 import {z} from 'zod';
+import {evaluationTraceSchema} from './evaluation-trace.js';
+
+export const STEP_STATUS_REASONS = [
+  'default_gate_rejected',
+  'condition_rejected',
+  'condition_errored',
+] as const;
+
+export const stepStatusReasonSchema = z.enum(STEP_STATUS_REASONS);
+
+export type StepStatusReasonDto = z.infer<typeof stepStatusReasonSchema>;
 
 // 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`,
@@ -86,8 +97,10 @@ export const stepDtoSchema = z.object({
   name: z.string(),
   source_location: stepSourceLocationSchema.nullable(),
   status: z.string(),
+  status_reason: stepStatusReasonSchema.nullable(),
   type: z.string(),
   config: z.record(z.string(), z.unknown()),
+  evaluation_trace: evaluationTraceSchema.nullable(),
   error: stepErrorDtoSchema,
   position: z.number(),
   // Execution-attempt identity of the current projection (>1 after a restart).
@@ -165,3 +178,10 @@ export const stepAttemptDtoSchema = z.object({
 });
 
 export type StepAttemptDto = z.infer<typeof stepAttemptDtoSchema>;
+
+export const stepAttemptDetailDtoSchema = stepAttemptDtoSchema.extend({
+  config: z.record(z.string(), z.unknown()).nullable(),
+  evaluation_trace: evaluationTraceSchema.nullable(),
+});
+
+export type StepAttemptDetailDto = z.infer<typeof stepAttemptDetailDtoSchema>;

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

@@ -1,7 +1,8 @@
 import {z} from 'zod';
+import {evaluationTraceSchema} from './evaluation-trace.js';
 import {jobDtoSchema} from './job.js';
 import {workflowExecutionEventSchema} from './job-listening.js';
-import {stepAttemptDtoSchema, stepDtoSchema} from './step.js';
+import {stepAttemptDetailDtoSchema, stepAttemptDtoSchema, stepDtoSchema} from './step.js';
 import {workflowRunAttemptDtoSchema, workflowRunResponseSchema} from './workflow-run.js';
 
 export const jobExecutionStatusSchema = z.enum([
@@ -19,8 +20,11 @@ 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(),
+  evaluation_trace: evaluationTraceSchema.nullable(),
   queued_at: z.string().nullable(),
   started_at: z.string().nullable(),
   finished_at: z.string().nullable(),
@@ -43,6 +47,16 @@ export const workflowRunStepDetailDtoSchema = stepDtoSchema.extend({
 
 export type WorkflowRunStepDetailDto = z.infer<typeof workflowRunStepDetailDtoSchema>;
 
+export const stepAttemptDetailResponseSchema = z.object({
+  step_id: z.string().uuid(),
+  attempt: stepAttemptDetailDtoSchema.shape.attempt,
+  authored_config: z.record(z.string(), z.unknown()).nullable(),
+  config: stepAttemptDetailDtoSchema.shape.config,
+  evaluation_trace: stepAttemptDetailDtoSchema.shape.evaluation_trace,
+});
+
+export type StepAttemptDetailResponseDto = z.infer<typeof stepAttemptDetailResponseSchema>;
+
 export const workflowRunJobExecutionDetailDtoSchema = jobExecutionDtoSchema.extend({
   steps: z.array(workflowRunStepDetailDtoSchema),
 });