@shipfox/api-workflows-dto 2.0.0

package/src/index.ts

@@ -0,0 +1,130 @@
+export {
+  type AgentConfigIssueDto,
+  type AgentRuntimeConfigQueryDto,
+  agentConfigIssueSchema,
+  agentRuntimeConfigQuerySchema,
+  type CheckoutIntentDto,
+  type CheckoutTokenAuthDto,
+  type CheckoutTokenResponseDto,
+  checkoutIntentSchema,
+  checkoutTokenAuthSchema,
+  checkoutTokenResponseSchema,
+  type JobDto,
+  type JobExecutionDto,
+  type JobListeningDto,
+  type JobModeDto,
+  type JobStatusDto,
+  type JobStatusReasonDto,
+  jobDtoSchema,
+  jobListeningBatchSchema,
+  jobListeningSchema,
+  jobModeSchema,
+  jobStatusReasonSchema,
+  jobStatusSchema,
+  type ListenerStatusDto,
+  type ListeningTriggerDto,
+  type LogOutcomeDto,
+  listenerStatusSchema,
+  listeningTriggerSchema,
+  logOutcomeSchema,
+  type NextStepResponseDto,
+  nextStepResponseSchema,
+  type ReportStepBodyDto,
+  type ReportStepResponseDto,
+  type RerunWorkflowRunBodyDto,
+  type ResolutionReasonDto,
+  reportStepBodySchema,
+  reportStepResponseSchema,
+  rerunWorkflowRunBodySchema,
+  resolutionReasonSchema,
+  STEP_ERROR_MESSAGE_MAX_LENGTH,
+  STEP_RESPONSE_MAX_LENGTH,
+  type StepAttemptDto,
+  type StepDto,
+  type StepErrorCategoryDto,
+  type StepErrorDto,
+  type StepErrorReasonDto,
+  type StepGateResultDto,
+  stepAttemptDtoSchema,
+  stepDtoSchema,
+  stepErrorCategorySchema,
+  stepErrorDtoSchema,
+  stepErrorReasonSchema,
+  stepGateResultDtoSchema,
+  type TriggerEventsBatchDto,
+  triggerEventsBatchSchema,
+  type WorkflowExecutionContextDto,
+  type WorkflowExecutionEventDto,
+  type WorkflowRunAggregatesQueryDto,
+  type WorkflowRunAggregatesResponseDto,
+  type WorkflowRunAttemptDto,
+  type WorkflowRunAttemptsResponseDto,
+  type WorkflowRunDetailResponseDto,
+  type WorkflowRunDto,
+  type WorkflowRunJobDetailDto,
+  type WorkflowRunJobExecutionDetailDto,
+  type WorkflowRunListQueryDto,
+  type WorkflowRunListResponseDto,
+  type WorkflowRunRerunModeDto,
+  type WorkflowRunResponseDto,
+  type WorkflowRunStatusDto,
+  type WorkflowRunStepDetailDto,
+  workflowExecutionContextSchema,
+  workflowExecutionEventSchema,
+  workflowRunAggregatesQuerySchema,
+  workflowRunAggregatesResponseSchema,
+  workflowRunAttemptDtoSchema,
+  workflowRunAttemptsResponseSchema,
+  workflowRunDetailResponseSchema,
+  workflowRunDtoSchema,
+  workflowRunJobDetailDtoSchema,
+  workflowRunJobExecutionDetailDtoSchema,
+  workflowRunListQuerySchema,
+  workflowRunListResponseSchema,
+  workflowRunRerunModeSchema,
+  workflowRunResponseSchema,
+  workflowRunStatusSchema,
+  workflowRunStepDetailDtoSchema,
+} from '#schemas/index.js';
+export {type StepSourceLocationDto, stepSourceLocationSchema} from '#schemas/step.js';
+export {
+  type WorkflowSourceSnapshotDto,
+  workflowSourceSnapshotSchema,
+} from '#schemas/workflow-run.js';
+export {
+  jobTerminalStatusSchema,
+  terminalStatusSchema,
+  WORKFLOWS_JOB_ACTIVATED,
+  WORKFLOWS_JOB_EVENT_DELIVERED,
+  WORKFLOWS_JOB_EXECUTION_TIMED_OUT,
+  WORKFLOWS_JOB_STEPS_SETTLED,
+  WORKFLOWS_JOB_TERMINATED,
+  WORKFLOWS_STEP_ATTEMPT_TERMINATED,
+  WORKFLOWS_STEP_RESTART_ENQUEUED,
+  WORKFLOWS_WORKFLOW_RUN_ATTEMPT_CREATED,
+  WORKFLOWS_WORKFLOW_RUN_CANCELLED,
+  WORKFLOWS_WORKFLOW_RUN_TERMINATED,
+  type WorkflowsEventMapDto,
+  type WorkflowsJobActivatedEventDto,
+  type WorkflowsJobEventDeliveredEventDto,
+  type WorkflowsJobExecutionTimedOutEventDto,
+  type WorkflowsJobStepsSettledEventDto,
+  type WorkflowsJobTerminatedEventDto,
+  type WorkflowsStepAttemptTerminatedEventDto,
+  type WorkflowsStepRestartEnqueuedEventDto,
+  type WorkflowsWorkflowRunAttemptCreatedEventDto,
+  type WorkflowsWorkflowRunCancelledEventDto,
+  type WorkflowsWorkflowRunTerminatedEventDto,
+  workflowRunTerminalStatusSchema,
+  workflowsEventSchemas,
+  workflowsJobActivatedSchema,
+  workflowsJobEventDeliveredSchema,
+  workflowsJobExecutionTimedOutSchema,
+  workflowsJobStepsSettledSchema,
+  workflowsJobTerminatedSchema,
+  workflowsStepAttemptTerminatedSchema,
+  workflowsStepRestartEnqueuedSchema,
+  workflowsWorkflowRunAttemptCreatedSchema,
+  workflowsWorkflowRunCancelledSchema,
+  workflowsWorkflowRunTerminatedSchema,
+} from './events.js';

package/src/schemas/agent-runtime-config.test.ts

@@ -0,0 +1,17 @@
+import {agentRuntimeConfigQuerySchema} from './agent-runtime-config.js';
+
+describe('agentRuntimeConfigQuerySchema', () => {
+  it('coerces the attempt query param', () => {
+    const stepId = crypto.randomUUID();
+
+    const parsed = agentRuntimeConfigQuerySchema.parse({step_id: stepId, attempt: '2'});
+
+    expect(parsed).toEqual({step_id: stepId, attempt: 2});
+  });
+
+  it('rejects malformed query params', () => {
+    const parse = () => agentRuntimeConfigQuerySchema.parse({step_id: 'step-1', attempt: '0'});
+
+    expect(parse).toThrow();
+  });
+});

package/src/schemas/agent-runtime-config.ts

@@ -0,0 +1,8 @@
+import {z} from 'zod';
+
+export const agentRuntimeConfigQuerySchema = z.object({
+  step_id: z.string().uuid(),
+  attempt: z.coerce.number().int().positive(),
+});
+
+export type AgentRuntimeConfigQueryDto = z.infer<typeof agentRuntimeConfigQuerySchema>;

package/src/schemas/checkout-token.test.ts

@@ -0,0 +1,162 @@
+import {checkoutTokenResponseSchema} from './checkout-token.js';
+
+const bearerResponse = {
+  repository_url: 'https://github.com/acme/repo.git',
+  ref: 'main',
+  auth: {
+    kind: 'bearer',
+    token: 'gh-token',
+    expires_at: '2026-06-10T12:00:00.000Z',
+    carry: 'header',
+    host: 'github.com',
+    persist: true,
+  },
+};
+
+const basicResponse = {
+  repository_url: 'https://github.com/acme/repo.git',
+  ref: 'main',
+  auth: {
+    kind: 'basic',
+    username: 'x-access-token',
+    token: 'gh-token',
+    expires_at: '2026-06-10T12:00:00.000Z',
+    carry: 'header',
+    host: 'github.com',
+    persist: false,
+  },
+};
+
+describe('checkoutTokenResponseSchema', () => {
+  it('accepts and round-trips a bearer auth response (no username)', () => {
+    const result = checkoutTokenResponseSchema.parse(bearerResponse);
+
+    expect(result).toEqual(bearerResponse);
+  });
+
+  it('accepts and round-trips a basic auth response with a username', () => {
+    const result = checkoutTokenResponseSchema.parse(basicResponse);
+
+    expect(result).toEqual(basicResponse);
+  });
+
+  it('accepts a Git author identity', () => {
+    const input = {
+      ...basicResponse,
+      git_author: {
+        name: 'shipfox-test[bot]',
+        email: '1+shipfox-test[bot]@users.noreply.github.com',
+      },
+    };
+
+    const result = checkoutTokenResponseSchema.parse(input);
+
+    expect(result.git_author).toEqual(input.git_author);
+  });
+
+  it('accepts a credential-free response with no auth (debug provider)', () => {
+    const input = {repository_url: 'https://github.com/acme/repo.git', ref: 'main'};
+
+    const result = checkoutTokenResponseSchema.parse(input);
+
+    expect(result).toEqual(input);
+    expect(result.auth).toBeUndefined();
+  });
+
+  it('rejects basic auth missing a username', () => {
+    const {username: _username, ...basicAuthWithoutUsername} = basicResponse.auth;
+    const input = {...basicResponse, auth: basicAuthWithoutUsername};
+
+    const parse = () => checkoutTokenResponseSchema.parse(input);
+
+    expect(parse).toThrow();
+  });
+
+  it('rejects an unknown auth kind', () => {
+    const input = {...bearerResponse, auth: {...bearerResponse.auth, kind: 'oauth'}};
+
+    const parse = () => checkoutTokenResponseSchema.parse(input);
+
+    expect(parse).toThrow();
+  });
+
+  it('rejects a malformed (non-ISO) expires_at', () => {
+    const input = {...bearerResponse, auth: {...bearerResponse.auth, expires_at: 'soon'}};
+
+    const parse = () => checkoutTokenResponseSchema.parse(input);
+
+    expect(parse).toThrow();
+  });
+
+  it('accepts the toISOString() Z wire format for expires_at', () => {
+    const input = {
+      ...bearerResponse,
+      auth: {...bearerResponse.auth, expires_at: '2026-06-10T12:00:00.000Z'},
+    };
+
+    const result = checkoutTokenResponseSchema.parse(input);
+
+    expect(result.auth?.expires_at).toBe('2026-06-10T12:00:00.000Z');
+  });
+
+  it('accepts an offset (non-Z) expires_at', () => {
+    const input = {
+      ...bearerResponse,
+      auth: {...bearerResponse.auth, expires_at: '2026-06-10T12:00:00+02:00'},
+    };
+
+    const result = checkoutTokenResponseSchema.parse(input);
+
+    expect(result.auth?.expires_at).toBe('2026-06-10T12:00:00+02:00');
+  });
+
+  it('rejects an empty token', () => {
+    const input = {...bearerResponse, auth: {...bearerResponse.auth, token: ''}};
+
+    const parse = () => checkoutTokenResponseSchema.parse(input);
+
+    expect(parse).toThrow();
+  });
+
+  it('accepts userinfo carry mode', () => {
+    const input = {...bearerResponse, auth: {...bearerResponse.auth, carry: 'userinfo'}};
+
+    const result = checkoutTokenResponseSchema.parse(input);
+
+    expect(result.auth?.carry).toBe('userinfo');
+  });
+
+  it('rejects an unsupported carry mode', () => {
+    const input = {...bearerResponse, auth: {...bearerResponse.auth, carry: 'ssh-agent'}};
+
+    const parse = () => checkoutTokenResponseSchema.parse(input);
+
+    expect(parse).toThrow();
+  });
+
+  it('rejects auth missing host', () => {
+    const {host: _host, ...auth} = bearerResponse.auth;
+    const input = {...bearerResponse, auth};
+
+    const parse = () => checkoutTokenResponseSchema.parse(input);
+
+    expect(parse).toThrow();
+  });
+
+  it('rejects auth missing persist', () => {
+    const {persist: _persist, ...auth} = bearerResponse.auth;
+    const input = {...bearerResponse, auth};
+
+    const parse = () => checkoutTokenResponseSchema.parse(input);
+
+    expect(parse).toThrow();
+  });
+
+  it('rejects an empty repository_url', () => {
+    const input = {...bearerResponse, repository_url: ''};
+
+    const parse = () => checkoutTokenResponseSchema.parse(input);
+
+    expect(parse).toThrow();
+  });
+});

package/src/schemas/checkout-token.ts

@@ -0,0 +1,45 @@
+import {z} from 'zod';
+
+const carryFields = {
+  carry: z.enum(['header', 'userinfo']),
+  host: z.string().min(1),
+  persist: z.boolean(),
+};
+
+const checkoutGitAuthorSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().min(1),
+});
+
+const checkoutTokenBasicAuthSchema = z.object({
+  kind: z.literal('basic'),
+  username: z.string().min(1),
+  token: z.string().min(1),
+  expires_at: z.string().datetime({offset: true}),
+  ...carryFields,
+});
+
+const checkoutTokenBearerAuthSchema = z.object({
+  kind: z.literal('bearer'),
+  token: z.string().min(1),
+  expires_at: z.string().datetime({offset: true}),
+  ...carryFields,
+});
+
+export const checkoutTokenAuthSchema = z.discriminatedUnion('kind', [
+  checkoutTokenBasicAuthSchema,
+  checkoutTokenBearerAuthSchema,
+]);
+
+export type CheckoutTokenAuthDto = z.infer<typeof checkoutTokenAuthSchema>;
+
+export const checkoutTokenResponseSchema = z.object({
+  repository_url: z.string().min(1),
+  ref: z.string().min(1),
+  git_author: checkoutGitAuthorSchema.optional(),
+  // Optional: credential-free providers (e.g. the debug source control) return a
+  // public clone URL with no auth material, so the runner clones without a token.
+  auth: checkoutTokenAuthSchema.optional(),
+});
+
+export type CheckoutTokenResponseDto = z.infer<typeof checkoutTokenResponseSchema>;

package/src/schemas/checkout.test.ts

@@ -0,0 +1,49 @@
+import {checkoutIntentSchema} from './checkout.js';
+
+const validCheckout = {
+  repository_url: 'https://github.com/acme/repo.git',
+  ref: 'main',
+  provider: 'github',
+  source_connection_id: '22222222-2222-4222-8222-222222222222',
+  external_repository_id: 'acme/repo',
+};
+
+describe('checkoutIntentSchema', () => {
+  it('round-trips a valid credential-free intent unchanged', () => {
+    const result = checkoutIntentSchema.parse(validCheckout);
+
+    expect(result).toEqual(validCheckout);
+  });
+
+  it('rejects an intent missing a required field', () => {
+    const {provider: _provider, ...checkoutWithoutProvider} = validCheckout;
+
+    const parse = () => checkoutIntentSchema.parse(checkoutWithoutProvider);
+
+    expect(parse).toThrow();
+  });
+
+  it('rejects a non-UUID source_connection_id', () => {
+    const input = {...validCheckout, source_connection_id: 'not-a-uuid'};
+
+    const parse = () => checkoutIntentSchema.parse(input);
+
+    expect(parse).toThrow();
+  });
+
+  it('rejects an empty repository_url', () => {
+    const input = {...validCheckout, repository_url: ''};
+
+    const parse = () => checkoutIntentSchema.parse(input);
+
+    expect(parse).toThrow();
+  });
+
+  it('rejects an empty provider', () => {
+    const input = {...validCheckout, provider: ''};
+
+    const parse = () => checkoutIntentSchema.parse(input);
+
+    expect(parse).toThrow();
+  });
+});

package/src/schemas/checkout.ts

@@ -0,0 +1,11 @@
+import {z} from 'zod';
+
+export const checkoutIntentSchema = z.object({
+  repository_url: z.string().min(1),
+  ref: z.string().min(1),
+  provider: z.string().min(1),
+  source_connection_id: z.string().uuid(),
+  external_repository_id: z.string().min(1),
+});
+
+export type CheckoutIntentDto = z.infer<typeof checkoutIntentSchema>;

package/src/schemas/index.ts

@@ -0,0 +1,104 @@
+export {
+  type AgentRuntimeConfigQueryDto,
+  agentRuntimeConfigQuerySchema,
+} from './agent-runtime-config.js';
+export {type CheckoutIntentDto, checkoutIntentSchema} from './checkout.js';
+export {
+  type CheckoutTokenAuthDto,
+  type CheckoutTokenResponseDto,
+  checkoutTokenAuthSchema,
+  checkoutTokenResponseSchema,
+} from './checkout-token.js';
+export {
+  type JobDto,
+  type JobStatusDto,
+  type JobStatusReasonDto,
+  jobDtoSchema,
+  jobStatusReasonSchema,
+  jobStatusSchema,
+} from './job.js';
+export {
+  type NextStepResponseDto,
+  nextStepResponseSchema,
+  type ReportStepBodyDto,
+  type ReportStepResponseDto,
+  reportStepBodySchema,
+  reportStepResponseSchema,
+  STEP_RESPONSE_MAX_LENGTH,
+} from './job-execution.js';
+export {
+  type JobListeningDto,
+  type JobModeDto,
+  jobListeningBatchSchema,
+  jobListeningSchema,
+  jobModeSchema,
+  type ListenerStatusDto,
+  type ListeningTriggerDto,
+  listenerStatusSchema,
+  listeningTriggerSchema,
+  type ResolutionReasonDto,
+  resolutionReasonSchema,
+  type TriggerEventsBatchDto,
+  triggerEventsBatchSchema,
+  type WorkflowExecutionContextDto,
+  type WorkflowExecutionEventDto,
+  workflowExecutionContextSchema,
+  workflowExecutionEventSchema,
+} from './job-listening.js';
+export {type LogOutcomeDto, logOutcomeSchema} from './log-outcome.js';
+export {
+  type AgentConfigIssueDto,
+  agentConfigIssueSchema,
+  STEP_ERROR_MESSAGE_MAX_LENGTH,
+  type StepAttemptDto,
+  type StepDto,
+  type StepErrorCategoryDto,
+  type StepErrorDto,
+  type StepErrorReasonDto,
+  type StepGateResultDto,
+  stepAttemptDtoSchema,
+  stepDtoSchema,
+  stepErrorCategorySchema,
+  stepErrorDtoSchema,
+  stepErrorReasonSchema,
+  stepGateResultDtoSchema,
+} from './step.js';
+export {
+  type RerunWorkflowRunBodyDto,
+  rerunWorkflowRunBodySchema,
+  type WorkflowRunAggregatesQueryDto,
+  type WorkflowRunAggregatesResponseDto,
+  type WorkflowRunAttemptDto,
+  type WorkflowRunAttemptsResponseDto,
+  type WorkflowRunDto,
+  type WorkflowRunListQueryDto,
+  type WorkflowRunListResponseDto,
+  type WorkflowRunRerunModeDto,
+  type WorkflowRunResponseDto,
+  type WorkflowRunStatusDto,
+  type WorkflowSourceSnapshotDto,
+  workflowRunAggregatesQuerySchema,
+  workflowRunAggregatesResponseSchema,
+  workflowRunAttemptDtoSchema,
+  workflowRunAttemptsResponseSchema,
+  workflowRunDtoSchema,
+  workflowRunListQuerySchema,
+  workflowRunListResponseSchema,
+  workflowRunRerunModeSchema,
+  workflowRunResponseSchema,
+  workflowRunStatusSchema,
+  workflowSourceSnapshotSchema,
+} from './workflow-run.js';
+export {
+  type JobExecutionDto,
+  jobExecutionDtoSchema,
+  jobExecutionStatusSchema,
+  type WorkflowRunDetailResponseDto,
+  type WorkflowRunJobDetailDto,
+  type WorkflowRunJobExecutionDetailDto,
+  type WorkflowRunStepDetailDto,
+  workflowRunDetailResponseSchema,
+  workflowRunJobDetailDtoSchema,
+  workflowRunJobExecutionDetailDtoSchema,
+  workflowRunStepDetailDtoSchema,
+} from './workflow-run-detail.js';

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

@@ -0,0 +1,27 @@
+import {reportStepBodySchema, STEP_RESPONSE_MAX_LENGTH} from './job-execution.js';
+
+describe('reportStepBodySchema', () => {
+  it('accepts a capped agent response', () => {
+    const parsed = reportStepBodySchema.parse({
+      status: 'succeeded',
+      attempt: 1,
+      exit_code: 0,
+      log_outcome: 'drained',
+      response: 'done',
+    });
+
+    expect(parsed.response).toBe('done');
+  });
+
+  it('rejects responses over the cap', () => {
+    const result = reportStepBodySchema.safeParse({
+      status: 'succeeded',
+      attempt: 1,
+      exit_code: 0,
+      log_outcome: 'drained',
+      response: 'x'.repeat(STEP_RESPONSE_MAX_LENGTH + 1),
+    });
+
+    expect(result.success).toBe(false);
+  });
+});

package/src/schemas/job-execution.ts

@@ -0,0 +1,92 @@
+import {z} from 'zod';
+import {logOutcomeSchema} from './log-outcome.js';
+import {stepDtoSchema, stepErrorDtoSchema} from './step.js';
+
+export const STEP_RESPONSE_MAX_LENGTH = 8 * 1024;
+
+/**
+ * The job to progress is identified by the caller's lease-token claims, never by
+ * the request. An unknown job is a 404, not a `done`.
+ */
+export const nextStepResponseSchema = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('step'),
+    step: stepDtoSchema,
+    attempt: z
+      .number()
+      .int()
+      .positive()
+      .describe(
+        'Attempt number for this step dispatch. Echo it back when reporting the step result so stale reports from older attempts can be ignored.',
+      ),
+    lease_token: z
+      .string()
+      .min(1)
+      .describe(
+        'Job-lease token re-scoped to this dispatched step attempt. The runner presents it as its lease for log-append authorization and carries it on later step requests.',
+      ),
+  }),
+  z.object({
+    kind: z.literal('done'),
+    status: z
+      .enum(['succeeded', 'failed'])
+      .describe('Terminal status of the job when no step remains to run.'),
+  }),
+]);
+
+export type NextStepResponseDto = z.infer<typeof nextStepResponseSchema>;
+
+export const reportStepBodySchema = z
+  .object({
+    status: z.enum(['succeeded', 'failed']).describe('Final status reported for the step attempt.'),
+    error: stepErrorDtoSchema
+      .optional()
+      .describe('Failure details. Required when status is failed.'),
+    attempt: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe(
+        'Attempt number echoed from next-step. Older runners may omit it; when present, it protects the workflow from stale reports.',
+      ),
+    exit_code: z
+      .number()
+      .int()
+      .nullable()
+      .optional()
+      .describe(
+        'Process exit code for the step attempt. Persisted as the canonical attempt exit code and used by gate evaluation.',
+      ),
+    output: z
+      .record(z.string(), z.unknown())
+      .nullable()
+      .optional()
+      .describe(
+        'Structured output captured for attempt history. Large textual logs are stored separately.',
+      ),
+    response: z
+      .string()
+      .max(STEP_RESPONSE_MAX_LENGTH)
+      .optional()
+      .describe('Capped final assistant response for agent step attempts. Omitted for run steps.'),
+    log_outcome: logOutcomeSchema.describe(
+      'Whether the runner drained all locally spooled logs before reporting, or abandoned the log stream for backend closure.',
+    ),
+  })
+  .refine((body) => (body.status === 'succeeded' ? body.error == null : body.error != null), {
+    message: 'succeeded steps must not include an error and failed steps must include one',
+  });
+
+export type ReportStepBodyDto = z.infer<typeof reportStepBodySchema>;
+
+export const reportStepResponseSchema = z.object({
+  ok: z.boolean().describe('Whether the step report was accepted.'),
+  cancel: z
+    .boolean()
+    .describe(
+      'Whether the runner should stop working on the job because it finished without full success.',
+    ),
+});
+
+export type ReportStepResponseDto = z.infer<typeof reportStepResponseSchema>;